z/OS DFSMSdfp Advanced Services

z/OS
IBM
DFSMSdfp Advanced Services
Version 2 Release 3
SC23-6861-30
Note
Before using this information and the product it supports, read the information in “Notices” on page 499.
This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications
until otherwise indicated in new editions.
Last updated: July 17, 2017
© Copyright IBM Corporation 1979, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . vii
Tables . . . . . . . . . . . . . . . ix
About This Document . . . . . . . . xi
Required product knowledge . . . . . . . . xi
Referenced documents . . . . . . . . . . . xi
z/OS information . . . . . . . . . . . . xiii
How to Read Syntax Diagrams . . . . . . . xiii
Address and Register Conventions . . . . . . xv
Summary of changes . . . . . . . . xvii
Summary of changes for z/OS Version 2 Release
(V2R3) . . . . . . . . . . . . . .
Summary of changes for z/OS Version 2 Release
(V2R2) . . . . . . . . . . . . . .
z/OS Version 2 Release 1 summary of changes
How to send your comments to IBM
If you have a technical problem .
.
.
.
.
3
. xvii
2
. xvii
xviii
xix
.
. xix
Chapter 1. Using the Volume Table of
Contents . . . . . . . . . . . . . . 1
VTOC Components . . . . . . . . . . . . 1
Data Set Control Block (DSCB) Types . . . . . 2
Allocating and Releasing DASD Space . . . . 16
The VTOC Index . . . . . . . . . . . . 17
VTOC Index Records . . . . . . . . . . 18
Accessing the VTOC with DADSM Macros . . . . 19
Requesting DASD Volume Information Using
LSPACE . . . . . . . . . . . . . . 20
Reading DSCBs from the VTOC Using OBTAIN 37
Releasing Unused Space from a DASD Data Set
Using PARTREL . . . . . . . . . . . . 43
Creating (Allocating) a DASD Data Set Using
REALLOC . . . . . . . . . . . . . . 49
Accessing the VTOC with CVAF Macros. . . . . 57
Serializing and Updating . . . . . . . . . 57
Identifying the Volume . . . . . . . . . 58
Generating a CVPL (CVAF Parameter List) . . . 59
Using Buffer Lists . . . . . . . . . . . 61
Using Macro ICVEDT02 to Map the Extents Area 63
Accessing the DSCB Directly . . . . . . . 64
Accessing DSNs or DSCBs in Sequential Order
66
Reading Sets of DSCBs with CVAF Filter . . . 68
Coding CVAF VTOC Access Macros . . . . . . 75
CVAFDIR Macro Overview and Specification . . 75
CVAFDSM Macro Overview and Specification . . 95
CVAFFILT Macro Overview and Specification
101
CVAFSEQ Macro Overview and Specification
121
CVAFTST Macro Overview and Specification
139
VTOC Index Error Message and Associated
Codes . . . . . . . . . . . . . . . 140
VTOC Error Responses . . . . . . . . . . 141
© Copyright IBM Corp. 1979, 2017
Recovering from System or User Errors
GTF Trace . . . . . . . . . .
VTOC and VTOC Index Listings . . .
.
.
.
.
.
.
. 141
. 142
. 142
Chapter 2. Managing the Volume Table
of Contents . . . . . . . . . . . . 143
Creating the VTOC and VTOC Index . . .
Protecting the VTOC and VTOC Index . . .
RACF . . . . . . . . . . . . .
APF . . . . . . . . . . . . .
Password Protection . . . . . . . .
Copying/Restoring/Initializing the VTOC. .
Volumes Containing a Nonindexed VTOC .
Volumes Containing an Indexed VTOC . .
Deleting a Data Set from the VTOC . . . .
Specifying the Volumes Affected . . . .
Erasing Sensitive Data . . . . . . .
System-Managed-Storage Considerations .
General Considerations and Restrictions .
SCRATCH and CAMLST Macro Specification
Example . . . . . . . . . . . .
SCRATCH Parameter List . . . . . .
Return Codes from SCRATCH. . . . .
Status Codes from SCRATCH . . . . .
Renaming a Data Set in the VTOC . . . .
Specifying the Volumes Affected . . . .
System-Managed-Storage Considerations .
General Considerations and Restrictions .
RENAME and CAMLST Macro Specification .
Example . . . . . . . . . . . .
RENAME Parameter List . . . . . .
Return Codes from RENAME . . . . .
Status Codes from RENAME . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
143
143
143
143
144
144
144
144
145
145
145
146
146
147
147
148
149
150
151
151
151
151
153
153
154
154
155
Chapter 3. Using Catalog Management
Macros . . . . . . . . . . . . . . 157
Application Program Considerations . . . . .
Catalog Search Order . . . . . . . . . . .
Retrieving Information from a Catalog . . . . .
Retrieving Information by Data Set Name
(LOCATE and CAMLST NAME) . . . . . .
Retrieving Information by Generation Data Set
Name (LOCATE and CAMLST NAME) . . .
Retrieving Information by Alias (LOCATE and
CAMLST NAME) . . . . . . . . . . .
Reading a Block by Relative Block Address
(LOCATE and CAMLST BLOCK). . . . . .
Return Codes from LOCATE . . . . . . .
Using Non-VSAM Data Set Catalog Entries . . .
Cataloging a Non-VSAM Data Set (CATALOG
and CAMLST CAT) . . . . . . . . . .
Uncataloging a Non-VSAM Data Set
(CATALOG and CAMLST UNCAT) . . . . .
Recataloging a Non-VSAM Data Set (CATALOG
and CAMLST RECAT) . . . . . . . . .
157
157
157
158
159
161
162
162
163
163
164
166
iii
Return Codes from CATALOG
.
.
.
.
.
. 167
Chapter 4. Executing Your Own
Channel Programs . . . . . . . . . 169
Comparing EXCP and EXCPVR . . . . . . .
Using EXCP and EXCPVR . . . . . . . . .
Allocating the Data Set or Device. . . . . . .
Opening the Data Set. . . . . . . . . . .
Direct Data Set Considerations . . . . . .
VSAM Data Set Considerations . . . . . .
Creating the Channel Program . . . . . . .
CCW Channel Program . . . . . . . . .
zHPF Channel Program . . . . . . . . .
Comparing CCW and zHPF channel programs
EXCP 64-bit Storage Considerations . . . . .
IDAW Requirements for EXCP Requests . . .
IDAW Requirements for EXCPVR Requests . .
MIDAW Requirements . . . . . . . . .
TIDAW requirements for EXCP requests . . .
Determining Whether zHPF is Supported for a
Device. . . . . . . . . . . . . . .
Modifying a Channel Program During
Execution. . . . . . . . . . . . . .
VIO Considerations . . . . . . . . . .
Creating the EXCP-Related Control Blocks. . . .
Input/Output Block (IOB) . . . . . . . .
Input/Output Block Common Extension (IOBE)
Event Control Block (ECB) . . . . . . . .
Input/Output Error Data Block (IEDB) . . . .
Data Control Block (DCB) . . . . . . . .
Data Control Block Extension (DCBE) . . . .
Data Extent Block (DEB). . . . . . . . .
Executing the Channel Program . . . . . . .
Using the EXCP macro instruction . . . . .
Using the EXCPVR macro instruction . . . .
Initiating the Channel Program . . . . . .
Translating the Channel Program . . . . . .
DASD Channel Program Prefix CCW
Commands . . . . . . . . . . . . .
DASD Rotational Positioning Sensing . . . .
Command Retry Considerations . . . . . .
Magnetic Tape Considerations . . . . . . .
Lost Data Condition on IBM 3800 . . . . .
Processing the I/O Completion Status . . . . .
Interruption Handling and Error Recovery
Procedures . . . . . . . . . . . . .
Handling End of Volume and End-Of-Data-Set
Conditions . . . . . . . . . . . . . .
Closing the Data Set . . . . . . . . . . .
Control Block Fields . . . . . . . . . . .
Data Control Block (DCB) Fields . . . . . .
Data Control Block Extension (DCBE) Fields . .
Input/Output Error Data Block (IEDB) Fields
Input/Output Block (IOB) Fields . . . . . .
Input/Output Block Common Extension (IOBE)
Fields . . . . . . . . . . . . . . .
Event Control Block (ECB) Fields . . . . . .
Data Extent Block (DEB) Fields . . . . . .
EXCP and EXCPVR Appendages . . . . . . .
Making Appendages Available to the System
The Authorized Appendage List (IEAAPP00)
iv
z/OS DFSMSdfp Advanced Services
169
170
171
172
172
172
173
173
175
176
177
177
178
180
181
182
183
183
184
184
184
184
184
184
185
185
185
185
186
187
187
187
187
188
189
189
189
189
193
195
196
196
207
209
211
216
220
222
222
224
224
Start-I/O Appendage . . . . . . . . . .
Page Fix and EXCPVR Start I/O Appendage
Program-Controlled Interruption Appendage
End-of-Extent Appendage . . . . . . . .
Abnormal-End Appendage . . . . . . . .
Channel-End Appendage . . . . . . . .
Converting a Relative Track Address to an Actual
Track Address . . . . . . . . . . . . .
Return Codes from the Relative to Actual
Conversion Routine . . . . . . . . . .
Converting an Actual Track Address to a Relative
Track Address . . . . . . . . . . . . .
Return Codes from the Conversion Routine . .
Using the IECTRKAD Callable Service or the
TRKADDR Macro . . . . . . . . . . . .
Obtaining the Sector Number of a Block on an RPS
Device. . . . . . . . . . . . . . . .
225
226
227
228
229
231
232
234
234
235
236
236
Chapter 5. Using XDAP to Read and
Write to Direct Access Devices . . . . 239
Using XDAP . . . . . . . . . .
Macro Instructions Used with XDAP . .
Defining a Data Control Block (DCB) .
Initializing a Data Control Block (OPEN)
End of Volume (EOV) . . . . . .
Restoring a Data Control Block (CLOSE)
Executing Direct Access Programs . . .
Control Blocks Used with XDAP . . . .
Input/Output Block . . . . . . .
Event Control Block . . . . . . .
Direct Access Channel Program . . .
RPS Device Sector Numbers . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
239
240
240
240
241
241
241
244
244
244
244
245
Chapter 6. Using Password Protected
Data Sets . . . . . . . . . . . . . 247
Providing Data Set Security . . . . . .
PASSWORD Data Set Characteristics . .
Creating Protected Data Sets . . . . .
Protection Feature Operating Characteristics
Maintaining the PASSWORD Data Set Using
PROTECT . . . . . . . . . . . .
Record Format . . . . . . . . . .
Protection-Mode Indicator . . . . . .
PROTECT Macro Specification. . . . .
.
.
.
.
.
.
.
.
248
249
250
250
.
.
.
.
.
.
.
.
252
252
252
253
Chapter 7. Using System Macro
Instructions . . . . . . . . . . . . 259
Ensuring Data Security by Validating the Data
Extent Block (DEBCHK macro) . . . . . .
DEBCHK Macro Specification . . . . . .
Obtaining I/O Device Characteristics (DEVTYPE
macro). . . . . . . . . . . . . . .
DEVTYPE Macro Specification. . . . . .
IHADVA Mapping macro . . . . . . .
Reading and Modifying a Job File Control Block
(RDJFCB Macro) . . . . . . . . . . .
RDJFCB Macro Specification . . . . . .
DEQ at Demount Facility for Tape Volumes .
High-Speed Cartridge Tape Positioning. . .
. 259
. 260
. 263
. 264
. 281
.
.
.
.
284
287
299
301
OPEN - Initialize Data Control Block for
Processing the JFCB . . . . . . . . . .
Purging and Restoring I/O Requests (PURGE and
RESTORE macros) . . . . . . . . . . . .
PURGE Macro Specification . . . . . . .
RESTORE Macro Specification . . . . . . .
Performing Track Calculations (TRKCALC macro)
Using TRKCALC . . . . . . . . . . .
Restrictions . . . . . . . . . . . . .
TRKCALC Macro Specification . . . . . .
Perform calculations and conversions with 28-bit
cylinder addresses (TRKADDR macro) . . . . .
Calculate the relative track number on the
volume (TRKADDR ABSTOREL) . . . . . .
Compare two track addresses (TRKADDR
COMPARE) . . . . . . . . . . . . .
Extract 28-bit cylinder number (TRKADDR
EXTRACTCYL) . . . . . . . . . . . .
Extract 4-bit track number (TRKADDR
EXTRACTTRK). . . . . . . . . . . .
Increment track address (TRKADDR
NEXTTRACK) . . . . . . . . . . . .
Normalize cylinder number (TRKADDR
NORMALIZE) . . . . . . . . . . . .
Convert a relative track number to a 28-bit
cylinder address (TRKADDR RELTOABS) . . .
Set cylinder number from register (TRKADDR
SETCYL) . . . . . . . . . . . . . .
Convert normalized track address into an
absolute 28-bit track address (TRKADDR
NORMTOABS) . . . . . . . . . . . .
Determining Level and Name of DFSMS . . . .
Determining Version, Release, and Modification
Level of DFSMS . . . . . . . . . . .
Determining Name of DFSMS . . . . . . .
Determining DFARELS During Assembler
Macro Phase. . . . . . . . . . . . .
302
304
304
307
307
308
309
309
317
317
318
318
319
319
319
.
.
.
.
.
320
321
321
322
323
323
326
328
330
331
334
. 336
. 338
Chapter 9. Using DFSMSdfp Callable
Services . . . . . . . . . . . . . 341
Call for DFSMS Level Determination
Format . . . . . . . . .
Parameters . . . . . . . .
Return Codes . . . . . . .
Example . . . . . . . . .
Call for Data Set Attribute Retrieval .
Format . . . . . . . . .
Parameters . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
347
347
347
347
347
349
349
350
353
353
353
354
Chapter 10. Using the DESERV Exit
363
. 354
355
. 355
. 356
. 357
. 358
. 359
. 359
. 359
. 362
320
Chapter 8. Displaying Messages on
Cartridge Magnetic Tape Subsystems
(MSGDISP macro) . . . . . . . . . 325
MSGDISP—Displaying a Mount Message . . .
MSGDISP—Displaying a Verify Message . . .
MSGDISP—Displaying a Ready Message . . .
MSGDISP—Displaying a Demount Message . .
MSGDISP—Resetting the Message Display . .
MSGDISP—Providing the Full Range of Display
Options . . . . . . . . . . . . . .
Return Codes from MSGDISP . . . . . . .
Return Codes . . . . . . . . . . .
Example . . . . . . . . . . . . .
Call for Data Set Backup-While-Open Support .
Format . . . . . . . . . . . . .
Parameters . . . . . . . . . . . .
Return Codes . . . . . . . . . . .
Example . . . . . . . . . . . . .
Using the Backup-While-Open Facility . . .
Call for DFSMSdfp Share Attributes . . . . .
Format . . . . . . . . . . . . .
Parameters . . . . . . . . . . . .
Return Codes . . . . . . . . . . .
IGWASYS, IGWASMS, IGWABWO, IGWLSHR
Return and Reason Codes . . . . . . .
Call for Record-Level Sharing Query (IGWARLS)
Format . . . . . . . . . . . . .
Parameters . . . . . . . . . . . .
Return Codes . . . . . . . . . . .
Example . . . . . . . . . . . . .
Call for converting and comparing 28-bit cylinder
addresses (IECTRKAD) . . . . . . . . .
Format . . . . . . . . . . . . .
Parameters . . . . . . . . . . . .
Character Data Representation Architecture
(CDRA) APIs . . . . . . . . . . . .
342
342
343
344
344
345
346
346
Task Level Exit . . . . . . . . . . . . .
Global Exit . . . . . . . . . . . . . .
Interactions Between the Task Level and Global
Exits . . . . . . . . . . . . . . . .
Establishing Multiple Task level or Multiple Global
Exits . . . . . . . . . . . . . . . .
Issuing DESERV FUNC=EXIT (invocation
environment) . . . . . . . . . . . . .
Invocation Syntax . . . . . . . . . . .
Installing or Replacing the DESERV Exit . . . .
Deleting the DESERV Exit . . . . . . . . .
Determining If a DESERV Exit Is Active . . . .
Writing the DESERV Exit . . . . . . . . .
Parameters Related to the GET Function . . .
Parameters Related to the PUT Function . . .
PUT Return and Reason Codes . . . . . .
Parameters Related to the DELETE Function
Parameters Related to the RENAME Function
Parameters Related to the UPDATE Function
Entry Environment for Exit Routine . . . . .
Exit Environment for Exit routine . . . . .
Registers on Entry to the DESERV Exit . . . .
Registers on Return from the DESERV Exit . .
DESERV Exit Return and Reason Codes . . .
DESERV FUNC=EXIT Return and Reason Codes
Example of the DESERV Exit . . . . . . . .
364
365
365
366
366
367
369
370
371
371
372
384
386
389
390
392
394
394
395
395
395
395
398
Chapter 11. Managing Hierarchical File
System Data Sets . . . . . . . . . 405
Creating Hierarchical File System Data Sets . .
Defining the Root File System . . . . . .
Creating and Mounting the Root File System
. 405
. 406
406
Contents
v
Creating Additional File Systems and
Directories . . . . . . . . . . . . .
Adding and Mounting File Systems to the Root
File System . . . . . . . . . . . . .
Managing File System Size . . . . . . . . .
Managing File System Activity . . . . . . .
Accessing HFS Data Set Attributes . . . . . .
Transporting a File System . . . . . . . . .
Removing (Deleting) a File System . . . . . .
Migrating a File System . . . . . . . . . .
Backing Up File Systems . . . . . . . . .
Recovering a Backed-Up File System . . . . .
HFS Deferred File System Synchronization . . .
How to specify a SYNC value . . . . . . .
Using pfsctl (BPX1PCT) Physical File System
Control for HFS . . . . . . . . . . . .
DisplayBufferLimits Command . . . . . .
ChangeBufferLimits Command . . . . . .
DisplayGlobalStats Command . . . . . . .
DisplayFSStats Command . . . . . . . .
ExtendFS Command . . . . . . . . . .
BPX1PCT Return and Reason Codes. . . . .
406
407
407
408
408
408
409
409
409
410
410
411
411
412
413
413
414
414
415
Chapter 12. User Access to
Subsystem Statistics, Status, and
Counts Information . . . . . . . . . 421
Register 1 Parameter List . . . .
Passed Argument List -- SSGARGL .
.
.
.
.
.
.
.
.
. 421
. 421
Modifying an FCB Image . . . . .
JES Support for the 3211 Indexing Feature .
.
.
.
.
. 475
. 476
Appendix C. Using the extended
address volume (EAV) migration
assistance tracker . . . . . . . . . 479
Information conventions for the EAV migration
assistance tracker . . . . . . . . . . .
Tracking information . . . . . . . . .
Tracking value . . . . . . . . . . .
DFSMS instances tracked by the EAV migration
assistance tracker . . . . . . . . . . .
LSPACE (SVC 78) . . . . . . . . . .
DEVTYPE (SVC 24) . . . . . . . . .
IDCAMS LISTDATA PINNED . . . . . .
IEHLIST LISTVTOC . . . . . . . . .
IDCAMS DCOLLECT . . . . . . . .
IDCAMS LISTCAT . . . . . . . . .
OBTAIN (SVC 27) . . . . . . . . . .
CVAFDIR . . . . . . . . . . . .
CVAFSEQ . . . . . . . . . . . .
CVAFDSM . . . . . . . . . . . .
CVAFFILT . . . . . . . . . . . .
CVAFVSM . . . . . . . . . . . .
DCB Open of a VTOC . . . . . . . .
DCB Open of EAS eligible data set . . . .
Other Sample exclusion list. . . . . . .
Recommend exclusion list . . . . . . .
Summary of DFSMS instances . . . . . .
. 480
. 480
. 481
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
481
481
482
483
484
485
485
486
487
488
489
490
491
492
492
493
493
494
Appendix A. Control Blocks . . . . . 443
Data Extent Block (DEB) Fields .
Data Facilities Area (DFA) Fields .
.
.
.
.
.
.
.
.
.
.
. 443
. 449
Appendix B. Maintaining the System
Image Library . . . . . . . . . . . 455
UCS Images in SYS1.IMAGELIB . . . . . . .
Examples of UCS Image Coding . . . . . .
UCS Image Alias Names . . . . . . . .
UCS Image Tables in SYS1.IMAGELIB . . . .
Alias Names in UCS Image Tables . . . . .
Adding or Modifying a UCS Image Table Entry
Verifying the UCS Image . . . . . . . .
FCB Images in SYS1.IMAGELIB . . . . . . .
Adding an FCB Image to the Image Library . .
vi
z/OS DFSMSdfp Advanced Services
457
458
462
462
462
466
470
471
473
Appendix D. Accessibility . . . . . . 495
Accessibility features . . . . . . .
Consult assistive technologies . . . .
Keyboard navigation of the user interface
Dotted decimal syntax diagrams . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
495
495
495
495
Notices . . . . . . . . . . . . . . 499
Terms and conditions for product documentation
IBM Online Privacy Statement. . . . . . .
Policy for unsupported hardware. . . . . .
Minimum supported hardware . . . . . .
Trademarks . . . . . . . . . . . . .
.
.
.
.
501
502
502
502
503
Index . . . . . . . . . . . . . . . 505
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.
Locating the volume table of contents . . . . 1
Contents of VTOC - DSCBs Describing Data
Sets on Volume That Has No VTOC Index . . 3
Contents of VTOC on an extended address
volume - DSCBs Describing Data Sets on
Volume That Has No VTOC Index . . . . . 4
Example of the Relationship of a VTOC to Its
Index . . . . . . . . . . . . . . 18
DADSM LSPACE Free Space Information
MF=(D,MSG) . . . . . . . . . . . . 33
DADSM LSPACE Free Space Information
Format, MF=(D,EXPMSG) . . . . . . . . 35
Control Blocks Required for CVAF Filter
Services . . . . . . . . . . . . . . 70
Example of CVAFDIR Macro with VTOC Part
1 of 2 . . . . . . . . . . . . . . 83
Example of CVAFDIR Macro with VTOC Part
2 of 2 . . . . . . . . . . . . . . 84
zHPF channel program . . . . . . . . 175
How EXCP translates an EXCP request with a
single 16K storage area . . . . . . . . 181
How EXCP translates an EXCP request with a
storage areas crossing page boundaries . . . 182
Using IOSPHPF to determine if zHPF is
supported by a processor and device . . . 183
Data Control Block Format for EXCP (After
OPEN) . . . . . . . . . . . . . . 198
Device-dependent portion of the DCB with
DEVD=DA and DSORG=PS (or DSORG=PO) . 204
Device-dependent portion of the DCB with
DEVD=DA and DSORG=DA . . . . . . 205
Device-dependent portion of the DCB with
DEVD=TA and DSORG=PS . . . . . . . 205
Device-dependent portion of the DCB with
DEVD=PR and DSORG=PS . . . . . . . 205
Device-dependent portion of the DCB with
DEVD=PC or RD and DSORG=PS . . . . 206
Format of an IEDB, Mapped by the
IOSDIEDB Macro . . . . . . . . . . 210
Input/Output Block (IOB) Format . . . . 212
IOBFLAG3 and IOBCSW fields for format 0
channel program . . . . . . . . . . 215
IOBFLAG3 and IOBCSW fields for format 1
channel program . . . . . . . . . . 215
IOBFLAG3 and IOBCSW fields for zHPF
channel program . . . . . . . . . . 215
Format of an IOBE, mapped by the
IOSDIOBE macro . . . . . . . . . . 217
Event Control Block after Posting of
Completion Code . . . . . . . . . . 220
© Copyright IBM Corp. 1979, 2017
27.
28.
29.
30.
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.
Parameter List for ADD Function . . . . .
Parameter List for REPLACE Function
Parameter List for DELETE Function
Parameter List for LIST Function . . . . .
Examples of Standard Form of the RDJFCB
macro . . . . . . . . . . . . . .
Example Code Using RDJFCB Macro
Processing a Multivolume Data Set with
EXCP . . . . . . . . . . . . . .
Sample Code Retrieving Allocation
Information Part 1 of 2 . . . . . . . .
Sample Code Retrieving Allocation
Information Part 2 of 2 . . . . . . . .
Examples of Standard Form of the OPEN
TYPE=J Macro . . . . . . . . . . .
The IOB Chain . . . . . . . . . . .
Sample &IHADFARELS Program . . . . .
Example of Determining Symbol Definition
Example of an IGWASYS Call Statement
Example of an IGWASMS Call LINK
Statement . . . . . . . . . . . . .
Example of IGWABWO Using LOAD and
CALL Statements . . . . . . . . . .
Example of the IGWARLS Query Call Using
LOAD and CALL Statements . . . . . .
Exit Routine Call Sequence . . . . . . .
PUT Return and Reason Codes . . . . .
Establishing and Deleting a Task Level
DESERV Exit Part 1 of 2 . . . . . . . .
Establishing and Deleting a Task Level
DESERV Exit Part 2 of 2 . . . . . . . .
Sample DESERV Exit Routine Part 1 of 3
Sample DESERV Exit Routine Part 2 of 3
Sample DESERV Exit Routine Part 3 of 3
Code to Add a 1403 UCS Image to
SYS1.IMAGELIB . . . . . . . . . .
Code to Add a 3203 UCS Image to
SYS1.IMAGELIB . . . . . . . . . .
Sample Code to Add a 3211 UCS Image to
SYS1.IMAGELIB . . . . . . . . . .
UCS Image Table Entry Format . . . . .
Adding a New Band ID to the 4245 UCS
Image Table (UCS5) . . . . . . . . .
Adding a New Default Entry to the 4248 UCS
Image Table (UCS6). . . . . . . . . .
Format of the Standard STD1 FCB Image
Format of the Standard STD2 FCB Image
Sample Code to Assemble and Add an FCB
Load Module to SYS1.IMAGELIB . . . . .
254
255
256
257
288
289
293
298
299
303
307
324
324
345
347
350
358
366
387
399
400
401
402
403
459
460
461
463
469
470
472
473
475
vii
viii
z/OS DFSMSdfp Advanced Services
Tables
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
Referenced Publications . . . . . . . . xi
DSCB Format-1 or Format-8 . . . . . . . 6
DSCB Format-3 . . . . . . . . . . . 11
DSCB Format-4 . . . . . . . . . . . 12
DSCB Format-5 . . . . . . . . . . . 14
Format-9 DSCB . . . . . . . . . . . 15
Format of the LSPACE Parameter List (MF=D) 30
DADSM LSPACE Message Return Area
Contents . . . . . . . . . . . . . 34
LSPACE Data Return Area Format . . . . . 35
DADSM OBTAIN SEARCH Return Codes
40
DADSM OBTAIN SEEK Return Codes . . . 42
DADSM PARTREL Return Codes . . . . . 48
REALLOC Parameter List . . . . . . . . 54
DADSM CREATE Return Codes . . . . . 56
CVAF Parameter List - ICVAFPL . . . . . 59
CVFCTN Field of CVPL—Contents and
Definitions . . . . . . . . . . . . . 61
Format of a Buffer List Header . . . . . . 62
Format of a Buffer List Entry. . . . . . . 63
Format of ICVEDT02 Mapping Macro. . . . 63
Format of a Filter Criteria List Header . . . 70
Format of a Filter Criteria List Entry . . . . 72
SCRATCH Parameter List . . . . . . . 148
SCRATCH Return Codes. . . . . . . . 149
SCRATCH Status Codes . . . . . . . . 150
Secondary Status Codes . . . . . . . . 150
RENAME Parameter List generated by
CAMLST . . . . . . . . . . . . . 154
DADSM RENAME Return Codes . . . . . 155
RENAME Status Codes . . . . . . . . 155
LOCATE Return Codes . . . . . . . . 162
CATALOG Return Codes . . . . . . . 167
Summary of the differences between EXCP,
EXCPVR, and EXCP V=R . . . . . . . 170
Storage area locations for CCW channel
program components . . . . . . . . . 174
Storage area locations for zHPF channel
program components . . . . . . . . . 176
Comparing CCW and zHPF channel
programs . . . . . . . . . . . . . 176
Maximum Number of IDAWs for CCW
byte-counts . . . . . . . . . . . . 180
DCBOFLGS Usage . . . . . . . . . . 194
Bits that EXCP uses in DCBIFLGS after the
DCB is OPEN . . . . . . . . . . . 199
DCB bits to signify presence of DCBE
203
DCB DEVD options . . . . . . . . . 203
IEDB Structure Mapping . . . . . . . . 210
IOBE Structure Mapping . . . . . . . . 217
EXCP Appendages . . . . . . . . . . 222
Entry Points, Returns, and Available Work
Registers for Appendages . . . . . . . 223
Registers and Their Use for Converting
Relative to Actual . . . . . . . . . . 233
© Copyright IBM Corp. 1979, 2017
45. Relative to Actual Conversion Routine Return
Codes . . . . . . . . . . . . . .
46. Registers and Their Use for Converting
Actual to Relative . . . . . . . . . .
47. Actual to Relative Conversion Routine Return
Codes . . . . . . . . . . . . . .
48. Registers and Their Use for A Sector Convert
Routine . . . . . . . . . . . . .
49. Channel Program Command Words Used by
XDAP . . . . . . . . . . . . . .
50. PROTECT Return Codes . . . . . . . .
51. Minimum size of area. . . . . . . . .
52. INFO=AMCAP 32–byte return data . . . .
53. Optimum and Maximum Block Size
Supported When Using EXCP or the Access
Method Large Block Interface . . . . . .
54. Device Characteristics Information . . . .
55. Simulated Device Characteristics Information
56. Output from DEVTYPE Macro . . . . . .
57. Output from DEVTYPE Macro — DASD
Devices . . . . . . . . . . . . .
58. Return Codes from the RDJFCB Macro
59. Type 07 JFCB Exit List Entry . . . . . .
60. Format of the Type 13 JFCB Exit List Entry
61. Format of the Allocation Retrieval List
(mapped by the IHAARL macro) . . . . .
62. Format of the Allocation Retrieval Area
(mapped by the IHAARA macro) . . . . .
63. Backup-While-Open Indicators . . . . . .
64. IGWASYS, IGWASMS, IGWABWO,
IGWLSHR Return and Reason Codes . . .
65. IGWARLS Return and Reason Codes
66. Installing or Replacing the DESERV Exit
67. DESERV Screen Table Structure . . . . .
68. Deleting the DESERV Exit . . . . . . .
69. Determining If a DESERV Exit Is Active
70. DESX Structure Mapping DESERV Exit
Parameter List . . . . . . . . . . .
71. Structure of DESP for DESERV GET
Invocations . . . . . . . . . . . .
72. DESL Structure . . . . . . . . . . .
73. DESN Parameter List . . . . . . . . .
74. DESB Parameter List . . . . . . . . .
75. SMDE Format . . . . . . . . . . .
76. Directory Entry Name Section . . . . . .
77. Directory Entry Notelist Section (PDS Only)
78. Directory Entry Token Section . . . . . .
79. Directory Entry Primary Name Section
80. Directory Entry Name Section . . . . . .
81. LSLoader Attributes Unique to Program
Objects. . . . . . . . . . . . . .
82. Attributes Unique to Load Modules (PDS
only) . . . . . . . . . . . . . .
83. Alias in Unformatted Form . . . . . . .
84. DESERV PUT DESP Fields . . . . . . .
85. DESD Parameter List . . . . . . . . .
234
235
235
237
244
257
265
271
271
274
274
277
277
290
290
294
295
295
353
354
357
369
370
370
371
371
373
375
376
376
377
378
378
378
379
379
381
383
383
384
388
ix
86.
87.
88.
89.
90.
91.
92.
93.
x
DESERV DELETE DESP Fields . . . . .
DESERV RENAME DESP Fields . . . .
DESERV UPDATE DESP Fields . . . .
Return and Reason Codes for the Exit
DESERV Function . . . . . . . . .
BPX1PCT - Return Codes and Reason Codes
Structure for the DisplayBufferLimits and
ChangeBufferLimits Commands
(GFUMPCTL) . . . . . . . . . .
Structure for the DisplayGlobalStats
Command (GFUMPCTL). . . . . . .
Structure for the DisplayFSStats Command
(GFUMPCTL) . . . . . . . . . .
z/OS DFSMSdfp Advanced Services
. 389
. 390
. 392
. 396
415
. 416
. 417
. 418
94. Structure for the ExtendFS Command
(GFUMPCTL) . . . . . . . .
95. Constants for Extend Units Supported
96. Partial Listing of DEB Fields . . .
97. DFA Fields . . . . . . . . .
98. DFA Element Name . . . . . .
99. SYS1.IMAGELIB Contents . . . .
100. UCS5 Image Table Contents. . . .
101. UCS6 Image Table Contents. . . .
102. 3262 Model 5 Print Bands . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 419
419
. 443
. 449
. 453
. 456
. 463
. 464
. 465
About This Document
This document is intended to help system programmers modify and extend the
data management capabilities of the operating system and for programmers to
write advanced application programs.
For information about the accessibility features of z/OS®, for users who have a
physical disability, see Appendix D, “Accessibility,” on page 495.
Required product knowledge
To use this document effectively, you should be familiar with:
v Assembler language
v Standard program linkage conventions
v The utility programs IEHLIST and IEHPROGM
v Data management access methods and macro instructions
v The storage management functions provided by DFSMSdss™ and DFSMShsm™.
DFSMSdss moves data from one device to another, backs up and recovers data
sets, and reduces free-space fragmentation on DASD volumes. DFSMShsm
manages storage by migrating and recalling data sets through a hierarchy of
storage devices.
To learn about physical storage administration, see z/OS DFSMSdfp Storage
Administration.
Referenced documents
The following publications are referenced in this document:
Table 1. Referenced Publications
Publication Title
Order Number
IBM High Level Assembler/MVS & VM & VSE Programmer's Guide
SC26-4941
IBM High Level Assembler/MVS & VM & VSE Language Reference
SC26-4940
z/OS MVS Programming: Assembler Services Guide
SA23-1368
z/OS MVS Programming: Assembler Services Reference ABE-HSP
SA23-1369
z/OS MVS Programming: Authorized Assembler Services Guide
SA23-1371
z/OS MVS Programming: Authorized Assembler Services Reference
ALE-DYN
SA23-1372
z/OS MVS Programming: Authorized Assembler Services Reference
EDT-IXG
SA23-1373
z/OS MVS Programming: Authorized Assembler Services Reference
LLA-SDU
SA23-1374
z/OS MVS Programming: Authorized Assembler Services Reference
SET-WTO
SA23-1375
z/OS MVS Planning: Global Resource Serialization
SA23-1389
z/OS MVS Program Management: User's Guide and Reference
SA23-1393
z/OS MVS Program Management: Advanced Facilities
SA23-1392
z/Architecture Principles of Operation
SA22-7832
© Copyright IBM Corp. 1979, 2017
xi
Table 1. Referenced Publications (continued)
Publication Title
xii
Order Number
IBM 2821 Control Unit Component Description
GA24-3312
IBM 3203 Printer Component Description and Operator's Guide
GA33-1515
IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and 3811 Printer
Control Unit Component Description and Operator's Guide
GA24-3543
IBM 3262 Model 5 Printer Product Description
GA24-3936
IBM 3800 Printing Subsystem Programmer's Guide
GC26-3846
IBM 3800 Printing Subsystem Model 3 Programmer's Guide:
Compatibility
SH35-0051
IBM 3800 Printing Subsystem Models 3 and 8 Programmer's Guide
SH35-0061
3900 Advanced Function Printer Product Description
GA32-0135
IBM 4245 Printer Model 1 Component Description and Operator's Guide
GA33-1541
IBM 4248 Printer Model 1 Description
GA24-3927
IBM 6262 Printer Model 014 Product Description
GA24-4134
IBM 6262 Printer Model 014 User's Guide
GA24-4132
IBM 6262 Printer Print Band Manual
GA24-4131
Device Support Facilities (ICKDSF) User's Guide and Reference
GC35-0033
z/OS MVS JCL Reference
SA23-1385
z/OS MVS JCL User's Guide
SA23-1386
z/OS JES2 Initialization and Tuning Guide
SA32-0991
z/OS JES3 Initialization and Tuning Guide
SA32-1003
z/OS DFSMS Access Method Services Commands
SC23-6846
z/OS DFSMSdfp Diagnosis
SC23-6863
z/OS DFSMS Installation Exits
SC23-6850
z/OS DFSMS Macro Instructions for Data Sets
SC23-6852
z/OS DFSMS Using Data Sets
SC23-6855
z/OS DFSMS Using Magnetic Tapes
SC23-6858
z/OS DFSMSdfp Utilities
SC23-6864
z/OS DFSMS Implementing System-Managed Storage
SC23-6849
z/OS MVS Initialization and Tuning Guide
SA23-1379
z/OS HCD Planning
GA32-0907
z/OS Security Server RACF Security Administrator's Guide
SA23-2289
z/OS MVS System Messages, Vol 1 (ABA-AOM)
SA38-0668
z/OS MVS System Messages, Vol 2 (ARC-ASA)
SA38-0669
z/OS MVS System Messages, Vol 3 (ASB-BPX)
SA38-0670
z/OS MVS System Messages, Vol 4 (CBD-DMO)
SA38-0671
z/OS MVS System Messages, Vol 5 (EDG-GFS)
SA38-0672
z/OS MVS System Messages, Vol 6 (GOS-IEA)
SA38-0673
z/OS MVS System Messages, Vol 7 (IEB-IEE)
SA38-0674
z/OS MVS System Messages, Vol 8 (IEF-IGD)
SA38-0675
z/OS MVS System Messages, Vol 9 (IGF-IWM)
SA38-0676
z/OS DFSMSdfp Advanced Services
Table 1. Referenced Publications (continued)
Publication Title
Order Number
z/OS MVS System Messages, Vol 10 (IXC-IZP)
SA38-0677
z/OS TSO/E Command Reference
SA32-0975
z/OS information
This information explains how z/OS references information in other documents
and on the web.
When possible, this information uses cross document links that go directly to the
topic in reference using shortened versions of the document title. For complete
titles and order numbers of the documents for all products that are part of z/OS,
see z/OS Information Roadmap.
To find the complete z/OS library, go to IBM Knowledge Center
(www.ibm.com/support/knowledgecenter/SSLTBW/welcome).
How to Read Syntax Diagrams
Throughout this library, diagrams are used to illustrate the programming syntax.
Keyword parameters are parameters that follow the positional parameters. Unless
otherwise stated, keyword parameters can be coded in any order. The following
list tells you how to interpret the syntax diagrams:
v Read the diagrams from left-to-right, top-to-bottom, following the main path
line. Each diagram begins on the left with double arrowheads and ends on the
right with two arrowheads facing each other.
►►
Syntax Diagram
►◄
v If a diagram is longer than one line, each line to be continued ends with a single
arrowhead and the next line begins with a single arrowhead.
►►
First Line
►◄
►►
Second Line
►◄
►►
Last Line
►◄
v Required keywords and values appear on the main path line. You must code
required keywords and values.
►►
REQUIRED_KEYWORD
►◄
If several mutually exclusive required keywords or values exist, they are stacked
vertically in alphanumeric order.
►►
REQUIRED_KEYWORD_OR_VALUE_1
REQUIRED_KEYWORD_OR_VALUE_2
►◄
About This Document
xiii
v Optional keywords and values appear below the main path line. You can choose
not to code optional keywords and values.
►►
►◄
KEYWORD
If several mutually exclusive optional keywords or values exist, they are stacked
vertically in alphanumeric order below the main path line.
►►
►◄
KEYWORD_OR_VALUE_1
KEYWORD_OR_VALUE_2
v An arrow returning to the left above a keyword or value on the main path line
means that the keyword or value can be repeated. The comma means that each
keyword or value must be separated from the next by a comma.
,
►►
▼ REPEATABLE_KEYWORD
►◄
v An arrow returning to the left above a group of keywords or values means more
than one can be selected, or a single one can be repeated.
►►
►◄
,
▼
REPEATABLE_KEYWORD_OR_VALUE_1
REPEATABLE_KEYWORD_OR_VALUE_2
v A word in all uppercase is a keyword or value you must spell exactly as shown.
In this example, you must code KEYWORD.
►►
KEYWORD
►◄
If a keyword or value can be abbreviated, the abbreviation is discussed in the
text associated with the syntax diagram.
v If a diagram shows a character that is not alphanumeric (such as parentheses,
periods, commas, and equal signs), you must code the character as part of the
syntax. In this example, you must code KEYWORD=(001,0.001).
►►
KEYWORD=(001,0.001)
►◄
v If a diagram shows a blank space, you must code the blank space as part of the
syntax. In this example, you must code KEYWORD=(001 FIXED).
►►
KEYWORD=(001 FIXED)
v Default keywords and values appear above the main path line. If you omit the
keyword or value entirely, the default is used.
xiv
z/OS DFSMSdfp Advanced Services
►◄
DEFAULT
►►
►◄
KEYWORD
v A word in all lowercase italics is a variable. Where you see a variable in the
syntax, you must replace it with one of its allowable names or values, as defined
in the text.
►►
variable
►◄
v References to syntax notes appear as numbers enclosed in parentheses above the
line. Do not code the parentheses or the number.
(1)
►►
KEYWORD
►◄
Notes:
1
An example of a syntax note.
v Some diagrams contain syntax fragments, which serve to break up diagrams that
are too long, too complex, or too repetitious. Syntax fragment names are in
mixed case and are shown in the diagram and in the heading of the fragment.
The fragment is placed below the main diagram.
►►
Reference to Syntax Fragment
►◄
Syntax Fragment:
1ST_KEYWORD,2ND_KEYWORD,3RD_KEYWORD
Address and Register Conventions
The notation used to code an operand appears in the following format:
symbol
The operand can be any valid assembler-language symbol.
(0)
General register 0 can be used as an operand. When used as an operand in a
macro instruction, the register must be specified as the decimal number 0
enclosed in parentheses as shown.
(1)
General register 1 can be used as an operand. When used as an operand in a
macro instruction, the register must be specified as the decimal number 1
enclosed in parentheses as shown. When you use register 1, the instruction that
loads it is not included in the macro expansion.
(2-12)
The operand specified can be any of the general registers 2 through 12. All
registers as operands must be coded in parentheses; for example, if register 3 is
coded, it is coded as (3). A register from 2 through 12 can be coded as a
decimal number, symbol (equated to a decimal number), or an expression that
results in a value of 2 through 12.
About This Document
xv
RX-Type Address
The operand can be specified as any valid assembler-language RX-type address
as shown in the following examples:
Name
ALPHA1
ALPHA2
BETA1
BETA2
GAMMA1
GAMMA2
GAMMA3
LAMBDA1
Operation
L
L
L
L
L
L
L
L
Operand
1,39(4,10)
REG1,39(4,TEN)
2,ZETA(4)
REG2,ZETA(REG4)
2,ZETA
REG2,ZETA
2,=F'1000'
3,20(,5)
Both ALPHA instructions specify explicit addresses; REG1 and TEN have been
defined as absolute symbols. Both BETA instructions specify implied addresses,
and both use index registers. ZETA is a relocatable symbol. Indexing is omitted
from the GAMMA instructions. GAMMA1 and GAMMA2 specify implied
addresses. The second operand of GAMMA3 is a literal. LAMBDA1 specifies
an explicit address with no indexing.
A-Type Address
The operand can be specified as any address that can be written as a valid
assembler-language A-type address constant. An A-type address constant can
be written as an absolute value, a relocatable symbol, or relocatable expression.
Operands requiring an A-type address are inserted into an A-type address
constant during the macro expansion process. For more details about A-type
address constants, see High Level Assembler/MVS & VM & VSE Language
Reference.
absexp
The operand can be an absolute value or expression. An absolute expression
can be an absolute term or an arithmetic combination of absolute terms. An
absolute term can be a nonrelocatable symbol, a self-defining term, or the
length attribute reference. For more details about absolute expressions, see
High Level Assembler/MVS & VM & VSE Language Reference.
relexp
The operand can be a relocatable symbol or expression. If the program
containing a relocatable symbol or expression is relocated n bytes away from
its originally assigned area of storage, the value of a relocatable symbol or
expression changes by n. For more details about relocatable symbols and
expressions, see High Level Assembler/MVS & VM & VSE Language Reference.
xvi
z/OS DFSMSdfp Advanced Services
Summary of changes
This information includes terminology, maintenance, and editorial changes.
Technical changes or additions to the text and illustrations for the current edition
are indicated by a vertical line to the left of the change.
Summary of changes for z/OS Version 2 Release 3 (V2R3)
The following changes are made for z/OS Version 2 Release 2 (V2R3).
New
v The Data Area Facilities Fields section has been updated. See “Data Facilities
Area (DFA) Fields” on page 449.
v The Data Control Extensions Fields section has been updated. See “Data Control
Block Extension (DCBE) Fields” on page 207.
v In the Volume Table of Contents section, the CVAFDIR macro has a new
parameter. See “VALIDATE: Validate Modified fields in a DSCB” on page 77,
“Generating a CVPL (CVAF Parameter List)” on page 59, and “Buffer List Entry”
on page 62.
v The LSPACE macro has been updated. See “LSPACE—Standard Form” on page
21, “LSPACE-Execute Form” on page 23, “LSPACE—List Form” on page 27, and
“LSPACE–DSECT Form” on page 29.
v “Reading and Modifying a Job File Control Block (RDJFCB Macro)” on page 284
has been updated.
Changed
v
Deleted
No content was removed from this information.
Summary of changes for z/OS Version 2 Release 2 (V2R2)
The following changes are made for z/OS Version 2 Release 2 (V2R2).
New
v The Data Area Facilities Fields has been updated with a new offset for PDSE
Generation support and Maximum Generations supported. See “Data Facilities
Area (DFA) Fields” on page 449.
v The OBTAIN macro now accepts NOQUEUE=OK, which specifies that the I/O
to read DSCBs will not queue on the resource and wait if that resource is not
available. For more information, refer to “Reading a DSCB by Data Set Name”
on page 37 and “Reading a DSCB by Absolute Device Address” on page 40.
v The XDAP macro now accepts IOBE=Y, which indicates that an IOBE is
provided to EXCP. This allows a VTOC writer using the XDAP macro to identify
the application that is updating the VTOC, for the purposes of audit logging of
VTOC I/O. For more information, refer to “Executing Direct Access Programs”
on page 241.
© Copyright IBM Corp. 1979, 2017
xvii
Changed
v Information about the VTOC Index has been updated. See “The VTOC Index”
on page 17 for more information.
v IXRCDS: Retain VIERS in Virtual Storage has been updated. See “IXRCDS:
Retain VIERS in Virtual Storage” on page 79 for more information.
v Information about the LSPACE-DSECT Form has been updated. See
“LSPACE–DSECT Form” on page 29 for more information.
Deleted
No content was removed from this information.
z/OS Version 2 Release 1 summary of changes
See the Version 2 Release 1 (V2R1) versions of the following publications for all
enhancements related to z/OS V2R1:
v z/OS Migration
v z/OS Planning for Installation
v z/OS Summary of Message and Interface Changes
v z/OS Introduction and Release Guide
xviii
z/OS DFSMSdfp Advanced Services
How to send your comments to IBM
We appreciate your input on this documentation. Please provide us with any
feedback that you have, including comments on the clarity, accuracy, or
completeness of the information.
Use one of the following methods to send your comments:
Important: If your comment regards a technical problem, see instead “If you have
a technical problem.”
v Send an email to mhvrcfs@us.ibm.com.
v Send an email from the Contact z/OS web page (www.ibm.com/systems/z/os/
zos/webqs.html).
Include the following information:
v Your name and address
v Your email address
v Your phone or fax number
v The publication title and order number:
z/OS DFSMSdfp Advanced Services
SC23-6861-30
v The topic and page number or URL of the specific information to which your
comment relates
v The text of your comment.
When you send comments to IBM®, you grant IBM a nonexclusive right to use or
distribute the comments in any way appropriate without incurring any obligation
to you.
IBM or any other organizations use the personal information that you supply to
contact you only about the issues that you submit.
If you have a technical problem
Do not use the feedback methods that are listed for sending comments. Instead,
take one or more of the following actions:
v Visit the IBM Support Portal (support.ibm.com).
v Contact your IBM service representative.
v Call IBM technical support.
© Copyright IBM Corp. 1979, 2017
xix
xx
z/OS DFSMSdfp Advanced Services
Chapter 1. Using the Volume Table of Contents
This information is intended to help you to use system macros to access and
modify the volume table of contents (VTOC) and VTOC index. The direct access
device storage management (DADSM) routines control space allocation on direct
access volumes through the VTOC for a volume and through the VTOC index if
one exists. A storage administrator uses the ICKDSF utility to build these
structures. See “Creating the VTOC and VTOC Index” on page 143.
VTOC Components
The VTOC is a data set that describes the contents of the direct access volume on
which it resides. It is a contiguous data set; that is, it resides in a single extent on
the volume and starts after cylinder 0, track 0 and before track 65,535. A VTOC's
address is located in the VOLVTOC field of the standard volume label (see
Figure 1). The volume label is described in z/OS DFSMS Using Data Sets. A VTOC
consists of complete tracks. Some other System z® operating systems support
VTOCs that are compatible with z/OS. Some of them allow the VTOC to begin in
the middle of a track. Normal z/OS operations do not support such a VTOC.
However if you do not create or extend data sets from z/OS in such a VTOC, you
may be able to read data sets on z/OS that were created on the other operating
system.
Standard Volume Label
11(B) VOLVTOC (5 bytes)
CCHHR of first record in VTOC
Cylinder 0
Track 0
Record
Record Record
1
2
3
Record
Record Record
1
2
3
VTOC Data Set
(Can be located
after cylinder 0,
track 0.)
Figure 1. Locating the volume table of contents
© Copyright IBM Corp. 1979, 2017
1
Using the VTOC
The VTOC is composed of 140-byte1 data set control blocks (DSCBs) that
correspond either to a data set currently residing on the volume, or to contiguous,
unassigned tracks on the volume.
A special type of data is in a hierarchical file system (HFS) data set. Each one
contains a UNIX type of file system that is compliant with the IEEE POSIX
standard and OSF XPG/4.2 standard. Certain linear data sets contain z/OS file
system (zFS) file systems. They also meet these standards. Each data set containing
an HFS or zFS file system can contain UNIX files and directories belonging to
multiple users. You can access the files through z/OS UNIX System Services,
BSAM, QSAM, and VSAM. See z/OS DFSMS Using Data Sets. DSCBs for data sets
describe their characteristics and location. DSCBs for contiguous, unassigned tracks
indicate their location.
Data Set Control Block (DSCB) Types
The VTOC contains several kinds of DSCBs. This section describes what the DSCBs
are used for, how many exist on a volume, and how to locate them. The DSCB
layouts are shown in Table 2 on page 6 through Table 5 on page 14.
The first record in every VTOC is the VTOC DSCB (format-4). The record describes
the device the volume resides on, the volume attributes, and the size and contents
of the VTOC data set. The next DSCB in the VTOC data set is a free-space DSCB
(format-5) even if the free space is described by format-7 DSCBs. The third and
subsequent DSCBs in the VTOC can occur in any order.
One or more DSCBs in the VTOC define a data set on each volume on which the
data set resides. The number of DSCBs needed to define a data set is determined
by the number of extents that the data set occupies and by whether it has a format
9 DSCB. One or more format-3 DSCBs are required for data sets with more than
three extents.
Figure 2 on page 3 shows a VTOC and the DSCBs needed to define four data sets.
Data set A (in Figure 2 on page 3) has 29 extents, so it cannot be a basic format,
direct or partitioned (PDS) data set. Because it has so many extents, it requires a
format-1 DSCB and two format-3 DSCBs. Data set B has 16 extents and therefore
requires both a format-1 and a format-3 DSCB. Data sets C and D have three or
fewer extents and need only a format-1 DSCB. Data sets B, C, and D could be any
type of data set.
1. The 140 bytes are divided into a 44-byte key portion followed by a 96-byte data portion. You can refer to the logical 140-byte
DSCB or to either of its parts.
2
z/OS DFSMSdfp Advanced Services
Using the VTOC
0(0)
2(2)
1(1)
IOBFLAG1
IOBFLAG2
3(3)
IOBSENS0
IOBSENS1
4(4)
IOBECBPB
IOBECBCC
8(8)
IOBFLAG3 and IOBCSW - format depends on channel program.
See related figures below.
All
Devices
16(10)
IOBSTRTB
IOBSIOCC
20(14)
IOBDCBPT
IOBFLAG4
24(18)
IOBRESTR+1
IOBRESTR
28(1C)
IOBINCAM
32(20)
IOBSEEK
(first byte, M)
IOBERRCT
Direct Access, Teleprocessing, and Graphic Devices
33(21)
Direct
Access
Storage
Devices
(DASD)
IOBSEEK
(second through eight bytes,
BBCCHHR)
39(27)
Figure 2. Contents of VTOC - DSCBs Describing Data Sets on Volume That Has No VTOC Index
Figure 3 on page 4 shows a VTOC and the DSCBs needed to define four data sets
on an extended address volume. Data set W (in Figure 3 on page 4) has 29 extents,
so it cannot be a basic format, direct or partitioned (PDS) data set. Because it has
so many extents, it requires a format-1 DSCB and two format-3 DSCBs. Data set X
has 16 extents and since it is an EAS eligible data set it requires a format-8 and a
format 9-DSCB, plus an additional format-3 DSCB. Data sets Y and Z have three or
fewer extents and need only a format-1 DSCB. Data sets X, Y, and Z could be any
type of data set.
Chapter 1. Using the Volume Table of Contents
3
Using the VTOC
Standard Volume Label
11(B)
VOLVTOC
field
VTOC Data Set
Data Set W
Format-4 DSCB
Description of
device, volume,
and the VTOC
extent
Format-5 DSCB
Dummy
Format-5
DSCB
Format-7 DSCB
Description
of up to 16
available
extents
Data Set X
Format-8 DSCB
Format-1 DSCB
Description of
data set X and
its first 3
extents
Description of
data set W
and its first
3 extents
Data Set Y
Format-1 DSCB
Format-3 DSCB
Description of
the 4th - 16th
extents of
data set W
Description of
data set Y and
its first 3 extents
Format-3 DSCB
Description of the
17th - 29th extents
of data set W. It may
have less than 29
extents.
Format-3 DSCB
Data Set Z
Format-1 DSCB
Format-9 DSCB
Description of
the 4th - 16th
extents of
data set X
Description of
data set Z
and its first
3 extents
Pointer to
Format-3 DSCB
for data set X
Note: Empty boxes in the VTOC data set represent free VTOC Records (Format-0 DSCBs)
Figure 3. Contents of VTOC on an extended address volume - DSCBs Describing Data Sets on Volume That Has No
VTOC Index
The mapping macro for the format-1, format-2, format-3, format-4, format-5,
format-8, and format-9 DSCBs is IECSDSL1. Code positional parameters to specify
which formats of DSCB to map. For example, the following maps format-1 and
format-3:
IECSDSL1 1,3
The macro does not generate a DSECT statement. This makes it easier to embed it
in your own DSECT or CSECT. You can use a technique such as the following to
get separate DSECT statements:
F1AREA
F3AREA
DSECT
IECSDSL1 1
DSECT
IECSDSL1 3
The first symbol generated for each format is of the form IECSDSLn, where n is
the number of the format.
Format-0 DSCB
Name: Free VTOC Record
Function: Describes an unused record in the VTOC (contains 140 bytes of binary
zeros). To delete a DSCB from the VTOC, a format-0 DSCB is written over it.
4
z/OS DFSMSdfp Advanced Services
Using the VTOC
How Many: One for every unused 140-byte record on the VTOC. The DS4DSREC
field of the format-4 DSCB is a count of the number of format-0 DSCBs on the
VTOC. This field is not maintained for an indexed VTOC.
How Found: Search on key equal to X'00'.
Format-1 and Format-8 DSCBs
Note: The fields in the format 1 DSCB and the format 8 DSCB are almost identical.
The small differences are noted in the field descriptions.
Name: Identifier
Function: Describes the first three extents and other information about a data set.
How Many: One for each data set on the volume, except the VTOC.
How Found: Use the OBTAIN macro or a CVAF macro.
Determining the Type of Data Set: To learn the type of a data set, test the
DS1DSORG field. Except for the DS1DSGU bit, only one bit should be on. If no bit
is on, the data set is not standard and the system generally treats it like
DSORG=PS. The explanation for all DS1DSORG bits being off might be:
v The user did not specify the DSORG option and no program has written data in
the data set.
v The data set was created by a program that used EXCP or EXCPVR.
v The data set was created on another operating system.
All of the above conditions are normal. Normally after a program writes data, the
DS1DSORG field will have a bit on. z/OS currently supports the following types
of data set:
v Physical sequential (DSORG=PS). There are three types:
– Large format if the DS1LARGE bit is on.
– Extended format if the DS1STRP bit is on. An indicator in the catalog entry
specifies whether it is striped.
– Basic format if neither of the above two bits is on.
v Direct (DSORG=DA).
v Partitioned (DSORG=PO). This can signify one of three types of data set:
– PDS (partitioned data set) if the DS1PDSE and DS1PDSEX bits are off.
– PDSE (partitioned data set extended) if the DS1PDSE bit is on and DS1PDSEX
bit is off.
– HFS (hierarchical file system) if the DS1PDSE and DS1PDSEX bits are on.
Other combinations of these three bits are invalid.
v VSAM (AMORG). You can use CSI, catalog search interface, to determine the
type of VSAM data set. If it is a linear data set, it might contain a DB2®
tablespace or a z/OS file system (zFS) or something else.
Table 2 on page 6 shows the contents of a format-1 or format-8 DSCB.
The DS1REFD field:
1. For a VSAM data set, if the date in the FMT-1 DSCB's DS1REFD field is earlier
than the current date, OPEN updates the field with the current date.
Chapter 1. Using the Volume Table of Contents
5
Using the VTOC
2. For a multivolume VSAM data set, OPEN updates the DS1REFD field only for
the first volume of the data component of the base cluster.
3. For a non-VSAM multivolume data set that is not SMS managed, OPEN
updates the DS1REFD field on the first volume OPEN selected to use.
4. For a non-VSAM multivolume SMS-managed data set that is not extended
format, OPEN updates the DS1REFD field on the first volume OPEN selected
to use, as well as the first volume of the data set.
5. For an extended format single-striped non-VSAM data set, OPEN updates the
DS1REFD field on the first volume OPEN selected to use, as well as the first
volume of the data set.
6. For an extended format multi-striped non-VSAM data set, OPEN updates the
DS1REFD fields on all volumes of the data set.
Table 2. DSCB Format-1 or Format-8. DSCB Format-1 or Format-8
Offset Dec
(Hex)
Type or Bit
Mask
Length
0(X'0')
44(X'2C')
Character
Character
44
1
45(X'2D')
Character
6
DS1DSNAM
DS1FMTID
DS1IDC
DS8IDC
DS1DSSN
51(X'33')
53(X'35')
Unsigned
Character
2
3
DS1VOLSQ
DS1CREDT
56(X'38')
Character
3
DS1EXPDT
59(X'3B')
60(X'3C')
61(X'3D')
Unsigned
Unsigned
Bitstring
1.......
.1......
..1.....
1
1
1
DS1NOEPV
DS1NOBDB
DS1FLAG1
DS1COMPR
DS1CPOIT
DS1EXPBY
.
.
.
.
|
.
.
.
.
.
.
.
.
1....
.1...
..1..
. . .11
Name
DS1RECAL
DS1LARGE
DS1ENCRP
DS1EATTR
Description
Data set name.
Format Identifier.
X'F1'. This is a format-1 DSCB.
X'F8'. This is a format-8 DSCB.
Data set serial number (identifies the first or only
volume containing the data set/space).
Volume sequence number.
Creation date ('YDD'), discontinuous binary. Add
1900 and the value in the Y byte to determine the
year. For VSAM data sets that are not
SMS-managed, the expiration date is in the catalog.
Expiration date ('YDD'), discontinuous binary. Add
1900 and the value in the Y byte to determine the
year.
Number of extents on volume.
Number of bytes used in last directory block.
Flags byte
Compressible format data set (DS1STRP is also 1).
Checkpointed data set.
VSE expiration date specified by retention period
(not currently used in z/OS)
Data set recalled.
Large format data set.
Access method encrypted data set.
Extended attribute setting as specified on the
allocation request.(EATTR=)
v If 0, EATTR has not been specified. For VSAM
data sets, the default behavior is equivalent to
EATTR=OPT. For non-VSAM data sets, the
default behavior is equivalent to EATTR=NO.
v If 1, EATTR=NO has been specified. The data set
cannot have extended attributes (format 8 and 9
DSCBs) or optionally reside in EAS.
v If 2, EATTR=OPT has been specified. The data
set can have extended attributes and optionally
reside in EAS. This is the default behavior for
VSAM data sets.
62(X'3E')
6
Character
z/OS DFSMSdfp Advanced Services
13
DS1SYSCD
v If 3, Not Used, EATTR treated as not specified.
System code.
Using the VTOC
Table 2. DSCB Format-1 or Format-8 (continued). DSCB Format-1 or Format-8
Offset Dec
(Hex)
Type or Bit
Mask
Length
75(X'4B')
Character
3
DS1REFD
78(X'4E')
Bitstring
1.......
1
DS1SMSFG
DS1SMSDS
Name
.1......
DS1SMSUC
..1.....
DS1REBLK
...1....
DS1CRSDB
....1...
DS1PDSE
.....1..
DS1STRP
......1.
DS1PDSEX
79(X'4F')
.......1
Character
3
DS1DSAE
DS1SCEXT
79(X'4F')
Bitstring
1
DS1SCXTF
1.......
DS1SCAVB
.
.
.
.
.
.
.
.
DS1SCMB
DS1SCKB
DS1SCUB
DS1SCCP1
.....1..
DS1SCCP2
1...
.1..
..1.
...1
.
.
.
.
.
.
.
.
80(X'50')
Unsigned
2
DS1SCXTV
82(X'52')
Bitstring
2
DS1DSORG
First byte of
DS1DSORG
DS1DSGIS
DS1DSGPS
DS1DSGDA
DS1DSGCX
1000
0100
0010
0001
....
0000
....
000x
000x
000x
000x
xx . .
001x
...1
DS1DSGPO
DS1DSGU
Description
Date last referenced ('YDD' or zero, if not
maintained). Add 1900 and the value in the Y byte
to determine the year.
System managed storage indicators.
System managed data set. IEHLIST displays this bit
as the letter “S”.
Uncataloged system managed data set (the VTOC
index is an uncataloged system managed data set
as are all temporary data sets on system managed
volumes). IEHLIST displays this bit as the letter
“U”.
System determined the block size and data set can
be reblocked (you or the system can reblock the
data set). IEHLIST displays this bit as the letter
“R”.
DADSM created original block size and data set
has not been opened for output. IEHLIST displays
this bit as the letter “B”.
Data set is a PDSE or HFS data set (DS1PDSEX is
also 1 for HFS). IEHLIST displays this bit as the
letter “I” for a PDSE. IEHLIST displays a “?” when
it finds an invalid combination of bits.
Sequential extended-format data set. IEHLIST
displays this bit as the letter “E”. IEHLIST displays
a “?” when it finds an invalid combination of bits.
HFS data set (DS1PDSE must also be 1) IEHLIST
displays this bit as the letter “H”.
Extended attributes exist in the catalog entry.
Secondary space extension. Valid only when
DS1EXT is on (see offset 94(X'5E')).
Secondary space extension flag byte–only one of
the first 4 bits is on.
If 1, DS1SCXTV is the original block length. If 0,
DS1SCXTV is the average record length.
If 1, DS1SCXTV is in megabytes.
If 1, DS1SCXTV is in kilobytes.
If 1, DS1SCXTV is in bytes.
If 1, DS1SCXTV has been compacted by a factor of
256.
If 1, DS1SCXTV has been compacted by a factor of
65,536.
Secondary space extension value for average record
length or average block length.
Data set organization.
Indexed sequential organization.
Physical sequential organization.
Direct organization.
BTAM or QTAM line group.
Reserved.
Partitioned organization.
Unmovable; the data contains location dependent
information.
Chapter 1. Using the Volume Table of Contents
7
Using the VTOC
Table 2. DSCB Format-1 or Format-8 (continued). DSCB Format-1 or Format-8
Offset Dec
(Hex)
84(X'54')
Type or Bit
Mask
100x 00xx
010x 00xx
001x 00xx
000x 10xx
000x 10xx
000x 01xx
. . . x . . xx
Character
10 . . . . . .
01 . . . . . .
11 . . . . . .
..1.....
Length
Second byte of
DS1DSORG
DS1DSGGS
DS1DSGTX
DS1DSGTQ
DS1ACBM
DS1ORGAM
DS1DSGTR
1
...1....
....1...
85(X'55')
. . . . . 00 .
. . . . . 10 .
. . . . . 01 .
. . . . . 11 .
.......x
Character
Name
DS1RECFM
DS1RECFF
DS1RECFV
DS1RECFU
DS1RECFT
DS1RECFB
DS1RECFS
DS1RECFA
DS1RECMC
1
DS1OPTCD
Description
Graphics organization.
TCAM line group (not supported)
TCAM message queue (not supported).
VSAM data set/space.
VSAM data set/space.
TCAM 3705 (not supported).
Reserved.
Record format.
Fixed length.
Variable length.
Undefined length.
Track overflow. No longer supported by current
hardware.
Blocked; cannot occur with undefined.
Fixed length: standard blocks; no truncated blocks
or unfilled tracks except possible the last block and
track. Variable length: spanned records.
No control character.
ISO/ANSI control character.
Machine control character.
Reserved.
Reserved.
Option Code.
BDAM OPTCD field assignments (applies only if DS1DSGDA is on):
1.......
Write validity check.
.1......
Track overflow.
..1.....
Extended search.
...1....
Feedback.
....1...
Actual addressing.
.....1..
Dynamic buffering.
......1.
Read exclusive.
.......1
Relative block addressing.
ISAM OPTCD field assignments (applies only if DS1DSGIS is on):
1.......
Write validity check.
.1......
Accumulate track index entry.
..1.....
Master indices.
...1....
Independent overflow area.
....1...
Cylinder overflow area.
.....1..
Reserved.
......1.
Delete option.
.......1
Reorganization criteria.
BPAM, BSAM, QSAM OPTCD field assignments (applies only if DS1DSGPO or DS1DSGPS is on):
1.......
Write validity check.
.1......
Allow data check (if on printer).
..1.....
Chained scheduling.
...1....
VSE/MVS interchange feature on tape.
....1...
Treat EOF as EOV (tape).
8
z/OS DFSMSdfp Advanced Services
Using the VTOC
Table 2. DSCB Format-1 or Format-8 (continued). DSCB Format-1 or Format-8
Offset Dec
(Hex)
Type or Bit
Mask
85(X'55')
.....1..
......1.
.......1
Bitstring
Length
1
Name
DS1OPTAM
VSAM OPTCD field assignments (applies only if DS1ORGAM
1.......
.1......
DS1OPTBC
. . xx xxxx
86(X'56')
Binary
2
DS1BLKL
88(X'58')
Binary
2
DS1LRECL
90(X'5A')
91(X'5B')
93(X'5D')
Binary
Binary
Character
1.......
.1......
1
2
1
DS1KEYL
DS1RKP
DS1DSIND
DS1IND80
DS1IND40
..1.....
...1....
DS1IND20
DS1IND10
....1...
.....1..
DS1IND08
DS1IND04
......1.
DS1IND02
.......1
94(X'5E')
94(X'5E')
95(X'5F')
Binary
Character
xxxx xxxx
00 . 0 . . . .
00 . 1 . . . .
4
1
DS1DSCHA
DS1IND01
DS1CHKPT
DS1SCALO
DS1SCAL1
DS1DSPAC
DS1DSABS
DS1EXT
11 . . . . . .
10 . . . . . .
01 . . . . . x
01 . . . . . 1
..1.....
DS1CYL
DS1TRK
DS1AVR
DS1AVRND
DS1MSGP
....1...
.....1..
......1.
.......1
Binary
DS1CONTG
DS1MXIG
DS1ALX
DS1SCAL3
3
Description
Search direct.
User label totaling.
Each record contains a table reference character.
VSAM OPTCD settings.
is on):
Reserved.
Data set is an integrated catalog facility catalog.
Reserved.
Block length (Type F unblocked records), or
maximum block size (F blocked, U or V records).
Logical record length: Fixed length-record length,
Undefined length-zero, Variable
unspanned-maximum record length, Variable
spanned and < 32757 bytes-maximum record
length, Variable spanned and > 32756 bytes-X'8000'.
Key length ( 0 to 255).
Relative key position.
Data set indicators.
Last volume containing data in this data set.
Data set is RACF™, a component of the Security
Server for z/OS, defined with a discrete profile.
Block length is a multiple of 8 bytes.
Password is required to read or write, or both; see
DS1IND04.
Data set has been modified since last recall.
If DS1IND10 is 1 and DS1IND04 is 1, password
required to write, but not to read. If DS1IND10 is 1
and DS1IND04 is 0, password required both to
write and to read.
Data set opened for other than input since last
backup copy made.
Same as DS1IND02.
Secure checkpoint data set.
Same as DS1IND01.
Secondary allocation space parameters.
Flag byte.
Space request bits, defined as follows:
Absolute track request.
Extension to secondary space exists (see DS1SCEXT
at offset 79 (X'4F')).
Cylinder request.
Track request.
Average block length request.
Average block and round request.
Mass storage vol group (MSVGP - no longer
supported).
Contiguous request.
MXIG request.
ALX request.
Round request.
Secondary allocation quantity.
Chapter 1. Using the Volume Table of Contents
9
Using the VTOC
Table 2. DSCB Format-1 or Format-8 (continued). DSCB Format-1 or Format-8
Offset Dec
(Hex)
Type or Bit
Mask
Length
98(X'62')
Binary
3
DS1LSTAR
101(X'65')
Binary
2
DS1TRBAL
103(X'67')
104(X'68')
Character
Character
1
1
DS1TTTHI
105(X'69')
105(X'69')
Character
Character
Character
X'81'
X'80'
30
10
1
Name
DS1EXNTS
DS1EXT1
X'40'
X'04'
X'02'
X'01'
X'00'
1
4
Description
Last used track and block on track (TTR). Not
defined for VSAM, PDSE, HFS and direct (BDAM).
See bit DS1LARGE at +61 and byte DS1TTTHI at
+104.
If not extended format, this is the value from
TRKCALC indicating space remaining on last track
used. For extended format data sets this is the high
order two bytes (TT) of the four-byte last used
track number. See DS1LSTAR. Zero for VSAM,
PDSE, and HFS.
Reserved.
High order byte of track number in DS1LSTAR.
Valid if DS1Large is on.
Three extent fields.
First extent description.
Extent type indicator.
Extent on cylinder boundaries.
Extent described is sharing cylinder (no longer
supported).
First extent describes the user labels and is not
counted in DS1NOEPV.
Index area extent (ISAM).
Overflow area extent (ISAM).
User's data block extent, or a prime area extent
(ISAM).
This is not an extent.
Extent sequence number.
Lower limit (CCHH). These are the bit definitions:
0–15
Low order 16 bits of the 28-bit cylinder
number.
16-27
High order 12 bits of the 28-bit cylinder
number. In a format-1 DSCB, these bits
always are zero.
Track number from 0 to 14. Use the
TRKADDR macro or IECTRKAD routine
when performing track address
calculations.
Upper limit (CCHH). Same format as the lower
limit.
Second extent description.
Third extent description.
In a format-1 DSCB this can be a pointer (CCHHR)
to a format-2 or format-3 DSCB or be zero. In a
format-8 DSCB this always is the CCHHR of a
format-9 DSCB.
28-31
4
115(X'73')
125(X'7D')
135(X'87')
Character
Character
Character
140(X'8C')
Character
10
10
5
DS1EXT2
DS1EXT3
DS1PTRDS
DS1END
Format-2 DSCB
This format applied only to ISAM data sets, which can no longer be created or
opened.
10
z/OS DFSMSdfp Advanced Services
Using the VTOC
Format-3 DSCB
Name: Extension
Function: Describes extents after the third extent of a non-VSAM data set or a
VSAM data space.
How Many: One for each data set or VSAM data space on the volume that has
more than three extents. There can be as many as 10 for a PDSE, HFS, extended
format data set, or a VSAM data set cataloged in an integrated catalog facility
catalog. PDSEs, HFS, and extended format data sets can have up to 123 extents.
Each component of a VSAM data set cataloged in an integrated catalog facility
catalog can have up to 123 extents per volume. All other data sets are restricted to
16 extents per volume.
How Found: Chained from a format 1, format 2 or format 9 DSCB that represents
the data set. In the case of a PDSE, HFS data set, sequential extended-format data
set, or VSAM data set, the chain also can be from a preceding format-3 DSCB.
Table 3 shows the contents of a format-3 DSCB.
Table 3. DSCB Format-3
Offset Dec
(Hex)
0(X'00')
4(X'04')
Type
Bitstring
Bitstring
Length
4
40
1
44(X'2C')
Character
1
4
4
1
45(X'2D')
135(X'87')
140(X'8C')
Bitstring
Bitstring
90
5
Name
DS3EXTNT
DS3FMTID
DS3IDC
DS3ADEXT
DS3PTRDS
DS3END
Description
Key identifier (X'03030303').
Four extent descriptions.
Extent type indicator. (See DS1EXT1 in Table 2 on
page 6.)
Extent sequence number.
Lower limit (CCHH).
Upper limit (CCHH).
Format identifier (X'F3').
Constant value of X'F3' in DS3FMTID.
Nine additional extent descriptions.
Pointer (CCHHR) to next format-3 DSCB, or zero.
-
Format-4 DSCB
Name: VTOC
Function: Describes the extent and contents of the VTOC and provides volume
and device characteristics. This DSCB contains a flag indicating whether the
volume is SMS managed.
How Many: One on each volume.
How Found: The VOLVTOC field of the standard volume label contains the
format-4 address. The format-4 DSCB is always the first record in the VTOC.
Table 4 on page 12 shows the contents of a format-4 DSCB.
Exception: The format-4 DSCB has a 44-byte key of X'04' bytes not shown in
Table 4 on page 12.
Chapter 1. Using the Volume Table of Contents
11
Using the VTOC
Table 4. DSCB Format-4
Offset Dec
(Hex)
Type
Length
0(X'00')
Character
1
1(X'01')
6(X'06')
8(X'08')
12(X'0C')
14(X'0E')
Character
Unsigned
Character
Unsigned
Bitstring
1.......
5
2
4
2
1
Name
DS4IDFMT
DS4IDC
DS4HPCHR
DS4DSREC
DS4HCCHH
DS4NOATK
DS4VTOCI
DS4DOSBT
.1......
..1.....
DS4DVTOC
DS4EFVLD
DS4DSTKP
DS4DOCVT
DS4DIRF
DS4DICVT
DS4IVTOC
DS4NOEXT
DS4SMSFG
DS4NTSMS
DS4SMSCV
17(X'11')
...1....
....1...
.....1..
......1.
.......1
Unsigned
Bitstring
00 . . . . . .
01 . . . . . .
10 . . . . . .
11 . . . . . .
11 . . . . . .
. . xx xxxx
Binary
18(X'12')
15(X'0F')
16(X'10')
1
1
DS4SMS
DS4SMSTS
1
DS4DEVAC
Character
14
DS4DEVCT
18(X'12')
18(X'12')
Character
Binary
4
2
DS4DEVSZ
DS4DSCYL
20(X'14')
22(X'16')
24(X'18')
24(X'18')
25(X'19')
26(X'1A')
27(X'1B')
Binary
Unsigned
Binary
Binary
Binary
Binary
Bitstring
...1....
2
2
2
1
1
1
1
DS4DSTRK
DS4DEVTK
DS4DEVOV
DS4DEVI
DS4DEVL
DS4DEVK
DS4DEVFG
DS4DEVAV
12
z/OS DFSMSdfp Advanced Services
Description
Format identifier (X'F4').
Constant value of X'F4' in DS4FMT.
Highest address (CCHHR) of a format-1 DSCB.
Number of available DSCBs.
CCHH of next available alternate track.
Number of remaining alternate tracks.
VTOC indicators.
VSE bit. Either invalid format 5 DSCBs or indexed
VTOC. Previously DOS(VSE) bit. See DS4IVTOC.
Index was disabled.
Extended free-space management flag. When
DS4EFVLD is on, the volume is in OSVTOC format
with valid free space information in the format-7
DSCBs. See also DS4EFLVL and DS4EFPTR.
VSE stacked pack.
VSE converted VTOC.
DIRF bit. A VTOC change is incomplete.
DIRF reclaimed.
Volume uses an indexed VTOC.
Number of extents in the VTOC(X'01').
System managed storage indicators.
Non-system managed volume.
System managed volume in initial status.
Reserved.
System managed volume.
System managed volume.
Reserved.
Number of alternate cylinders when the volume
was formatted. Subtract from first 2 bytes of
DS4DEVSZ to get number of useable cylinders (can
be 0). Valid only if DS4DEVAV is on.
Device constants. For currently supported devices,
these fields do not provide enough information to
calculate the amount of space used on a track. Use
TRKCALC (see “Performing Track Calculations
(TRKCALC macro)” on page 307).
Device size.
Number of logical cylinders including alternates, if
any exist. Unsigned number. Set to X'FFFE' for
devices with more than 65,520 cylinders, indicating
that cylinder-managed space exists (DS4CYLMG is
set on) and extended attribute DSCBs, formats 8
and 9, are allowed.
Number of tracks in a logical cylinder.
Device track length.
Keyed record overhead.
Non-last-keyed record overhead.
Last keyed record overhead.
Non-keyed record overhead differential.
Flag byte 1.
Value in DS4DEVAC, number of alternate cylinders
is valid. Otherwise, the number is not available in
this DSCB.
Using the VTOC
Table 4. DSCB Format-4 (continued)
Offset Dec
(Hex)
Type
Length
Name
....1...
.....1..
......1.
.......1
28(X'1C')
30(X'1E')
31(X'1F')
32(X'20')
40(X'28')
40(X'28')
xxx. . . . .
Binary
Binary
Binary
Binary
Character
Bitstring
1.......
.1......
2
1
1
8
3
1
. .1 . . . . .
. .1 . . . . .
DS4DEVTL
DS4DEVDT
DS4DEVDB
DS4AMTIM
DS4AMCAT
DS4VSIND
DS4VSREF
DS4VSBAD
DS4VVDSA
DS4VVDSR
41(X'29')
43(X'2B')
51(X'33')
56(X'38')
. . .x xxxx
Unsigned
Binary
Character
Character
2
8
5
5
DS4VSCRA
DS4R2TIM
61(X'3D')
71(X'47')
81(X'51')
Character
Character
Character
10
10
1
DS4VTOCE
Reserved.
DS4EFLVL
82(X'52')
Character
5
DS4EFPTR
87(X'57')
Character
1
DS4MCU
88(X'58')
Character
4
DS4DCYL
92(X'5C')
Character
2
DS4LCYL
DS4F6PTR
Description
Keyed record overhead field (DS4DEVOV) is used
as a 2-byte field to specify the overhead required
for a keyed record.
The CCHH of an absolute address is used as a
continuous binary value. Not implemented in the
current IBM product line.
The CCHH of an absolute address is used as four
separate binary values. Not implemented in the
current IBM product line.
A tolerance factor must be applied to all but the
last block of the track. Not implemented in the
current IBM product line.
Reserved.
Device tolerance.
Number of DSCBs per track.
Number of PDS directory blocks per track.
VSAM time stamp.
VSAM catalog indicator.
VSAM indicators.
A VSAM catalog references this volume.
The VSAM data sets on this volume are unusable
because an MSS CONVERTV command has not
completed successfully for the volume. (No longer
set.)
Bit on indicate VVDS does exist
If on, VVDS data set name was scanned. It is
turned on once per volume when the VVDS was
scanned on the volume.
Reserved.
Relative track location of the CRA.
VSAM volume/catalog match time stamp.
Reserved.
Pointer (CCHHR) to first format-6 DSCB, or zero.
(No longer supported as non-zero).
VTOC extent description.
VTOC extent description.
Extended free-space management level. X'00'
indicates extended free-space management is not
used for this volume. X'07' indicates extended
free-space management is in use for this volume
(see also DS4EFVLD).
Pointer to extended free-space information. If
DS4EFLVL=X'00' this is zero. If DS4EFLVL=X'07'
this is the CCHHR of the first FMT-7 DSCB and no
format-5 DSCBs contain free space information.
Minimum allocation size in cylinders for
cylinder-managed space. Each extent in this space
must be a multiple of this value.
Number of logical cylinders. Valid when
DS4DSCYL= X'FFFE'.
First cylinder address/4095 where space is
managed in multicylinder units. Cylinder-managed
space begins at this address. Valid when
DS4CYLMG is set.
Chapter 1. Using the Volume Table of Contents
13
Using the VTOC
Table 4. DSCB Format-4 (continued)
Offset Dec
(Hex)
94(X'5E')
Type
Character
1... ....
Length
1
.1.. ....
Name
DS4DEVF2
DS4CYLMG
DS4EADSCB
..xx
xxxx
1
95(X'5F')
96(X'60')
DS4END
Description
Device Flags Byte 2
Cylinder-managed space exists on this volume and
begins at DS4LCYL in multicylinder units of
DS4MCU. DS4EADSCB is also set when this flag is
on.
Extended attribute DSCBs, Format 8 and 9 DSCBs,
are allowed on this volume.
Reserved
Reserved
-
Format-5 DSCB
Name: Free Space
Function: On a nonindexed VTOC, describes the space on a volume that has not
been allocated to a data set (available space). For an indexed VTOC, a single empty
format-5 DSCB resides in the VTOC; free space is described in the index and
DS4IVTOC is normally on.
How Many: One for every 26 noncontiguous extents of available space on the
volume for a nonindexed VTOC; for an indexed VTOC, there is only one.
How Found: The first format-5 DSCB on the volume is always the second DSCB
of the VTOC. If there is more than one format-5 DSCB, it is chained from the
previous format-5 DSCB using the DS5PTRDS field.
Table 5 shows the contents of a format-5 DSCB.
Table 5. DSCB Format-5
Offset Dec
(Hex)
0(X'00')
4(X'04')
9(X'09')
44(X'2C')
45(X'2D')
135(X'87')
140(X'8C')
Type
Bitstring
Bitstring
Bitstring
Character
Bitstring
Bitstring
Length
4
5
2
2
1
35
1
90
5
Name
DS5KEYID
DS5AVEXT
DS5EXTAV
DS5FMTID
DS5MAVET
DS5PTRDS
DS5END
Description
Key identifier (X'05050505').
Available extent.
Relative track address of the first track in the
extent. Relative to the beginning of the volume.
Number of unused cylinders in the extent.
Number of additional unused tracks.
Seven available extents.
Format identifier (X'F5').
Eighteen available extents.
Pointer (CCHHR) to next format-5 DSCB, or zero.
-
Format-7 DSCB
Name: Free space for certain devices
14
z/OS DFSMSdfp Advanced Services
Using the VTOC
Only one field in the format-7 DSCB is an intended interface. This field indicates
whether the DSCB is a format-7 DSCB. You can reference that field as DS1FMTID
or DS5FMTID. A character 7 indicates that the DSCB is a format-7 DSCB, and your
program should not modify it.
If you are diagnosing a problem, see z/OS DFSMSdfp Diagnosis for the layout of the
Format-7 DSCB.
Format-9 DSCB
Name: Metadata and DSCB pointers.
Function: Contains metadata about the data set and pointers to all format 3
DSCBs for the data set.
How Many: One for each format 8 DSCB.
How Found: Chained from a format-8 DSCB that represents the data set. Data
sets that have a format 1 DSCB do not have a format 9 DSCB.
Table 6 shows the contents of a format-9 DSCB.
Table 6. Format-9 DSCB
|
|
|
|
|
|
|
|
|
|
|
Offset Dec
(Hex)
Type
Length
Name
Description
0 (X'00')
Character
1
1 (X'01')
Binary
1
DS9KEYID
DS9KEY
DS9SUBTY
DS9SUBT1
Key identifier.
Constant value of X'09' in DS9KEYID
Subtype number for format 9.
Constant value of binary 1 to represent subtype 1.
If your program uses the content of a format 9
DSCB, then it should test the subtype field to learn
the format of the DSCB. Currently only one
subtype is defined
Beginning of the fields that are unique to the format 9 subtype 1 DSCB.
2 (X'02')
Binary
1
DS9NUMF9
Number of format 9 DSCB's for this data set. Valid
only in the first format 9 DSCB.
3 (X'03')
Character
1
DS9FLAG1
Format 9 DSCB flag byte 1.
1.......
DS9CREAT
Format 9 DSCB built by create.
4 (X'04')
Character
8
DS9JOBNAME
Job name used to create the data set on the current
volume. Valid only when DS9CREAT is on (see
offset 3 (X'03')).
12 (X'0C')
Character
8
DS9STEPNAME Step name used to create the data set on the
current volume. Valid only when DS9CREAT is on
(see offset 3 (X'03')).
20 (X'14')
Bytes
6
DS9TIME
Number of microseconds since midnight, local
time, that the data set was created. See creation
date field, DS1CREDT (offset 53(X'35')), for the
date. Valid only if DS1VOLSQ is 1 (first volume)
and DS9CREAT is on (see offset 3 (X'03')).
26 (X'20')
Character
18
*
Reserved.
44 (X'2C')
Character
1
DS9FMTID
Format identifier.
DS9IDC
Constant value of X'F9' in DS9FMTID.
45 (X'2D')
Binary
1
DS9NUMF3
Number of format 3 pointers that follow
46 (X'2E')
Binary
50
DS9F3
Pointers to first to tenth format-3 DSCBs
The following five bytes occur ten times.
46 (X'2E')
Binary
5
DS9F3P
First pointer to a format-3 DSCB
Chapter 1. Using the Volume Table of Contents
15
Using the VTOC
Table 6. Format-9 DSCB (continued)
Offset Dec
(Hex)
Type
Length
Name
Description
46
48
50
96
Binary
Binary
Binary
Character
2
2
1
20
DS9F3CC
DS9F3HH
DS9F3R
DS9ATRV1
Cylinder number in pointer to format-3
Track number in pointer to format-3
Record number in pointer to format-3
Attribute bytes available for vendor use. See
Vendor fields in DS9ATRV!.
Attribute fields, for future IBM definition
(X'2E')
(X'30')
(X'32')
(X'60')
116 (X'74')
Character
19
DS9ATRI2
End of the fields that are unique to the format 9 subtype 1 DSCB.
135 (X'87')
Bitstring
5
DS9PTRDS
Pointer (CCHHR) to next format-9 DSCB, the first
format-3 DSCB or zero.
135 (X'87')
Binary
2
DS9CCPTR
Cylinder number in DSCB pointer
138 (X'89')
Binary
2
DS9HHPTR
Track number in DSCB pointer
140 (X'8B')
Binary
1
DS9RPTR
Record number in DSCB pointer
140 (X'8C')
DS9END
Vendor fields in DS9ATRV1 in the format 9 DSCB
z/OS does not enforce any rules on the content of the DS9ATRV1 field. It is available for vendor products to set. IBM
provides the following recommendations:
Each vendor should store subfields in the following format beginning at the leftmost byte:
0 (X'0')
Character
1
xxxx ....
Reserved
.... xxxx
Number of bytes that follow this two-byte header.
Minimum value is 0000.
1 (X'1')
Character
1
One-byte field containing a vendor identification
issued by IBM.
2 (X'2')
Character
Beginning of variable-length field up to 15 bytes.
Allocating and Releasing DASD Space
DADSM allocate and extend routines assign tracks and cylinders on direct access
volumes for data sets. The DADSM extend routine gets additional space for a data
set that has exceeded its primary allocation. The DADSM scratch and partial
release routines release space that is no longer needed on a direct access volume.
The DADSM routines allocate and release space by adding, deleting, and
modifying the DSCBs and updating the VTOC index. When space is released, the
scratch routines free the DSCBs of the deleted data set or data space.
Every data set occupies an integral number of tracks. Unused space on a track
cannot be used for another data set unless the whole track is released. The
minimum amount of space allocated to a data set is zero tracks but a PDS with no
tracks can never contain a member.
After a certain place on the volume, the system rounds up each primary or
secondary space request so it is a multiple of 21 cylinders. Currently that place is
after the first 65520 cylinders. The space within the first 65520 cylinders is called
the track-managed space, even if data sets are allocated in units of cylinders. The
space after the first 65520 cylinders is called the cylinder-managed space. If the
volume capacity is 65520 cylinders or less, then all of the space is track-managed.
16
z/OS DFSMSdfp Advanced Services
Using the VTOC
Note: When a user program needs to determine the characteristics of a given
volume, it must separately check each of the following characteristics and not
assume that the value obtained for one characteristic implies the values for the
other three:
v Whether space beyond a certain place on the volume is managed in
multicylinder units.
v The location on the volume where the multicylinder units begin.
v The number of cylinders in a multicylinder unit.
v Whether the VTOC contains format 8 and 9 DSCBs.
The VTOC Index
The VTOC index enhances the performance of VTOC access. The VTOC index is a
physical-sequential data set on the same volume as the related VTOC. It consists of
an index of data set names in DSCBs contained in the VTOC and volume free
space information. The data set names are in format-1 and format-8 DSCBs. The
free space information describes available tracks on the volume, available DSCBs in
the VTOC and available records in the index.
An SMS-managed volume requires an indexed VTOC; otherwise, the VTOC index is
highly recommended. For additional information about SMS-managed volumes,
see z/OS DFSMS Implementing System-Managed Storage.
Note: You can use the ICKDSF REFORMAT REFVTOC command to rebuild a
VTOC index to reclaim any no longer needed index space and to possibly improve
access times.
z/OS does support sharing a non-SMS-managed volume that contains a VTOC
index with a non-z/OS system. If the other system updates the VTOC and turns
on the DS4DOSBT, then later when z/OS is used to modify the VTOC, DADSM
can detect that the index is no longer valid. The z/VSE® operating system sets this
bit on.
Device Support Facilities (ICKDSF) initializes a VTOC index into 2048-byte
physical blocks, or 8192-byte physical blocks on an extended address volume,
named VTOC index records (VIRs). The DEVTYPE INFO=DASD macro can be
used to return the actual block size or it can be determined from examining the
format-1 DSCB of the index data set. VIRs are used in several ways. A VTOC index
contains the following kinds of VIRs:
VTOC index entry record (VIER) identifies the location of format-1 and
format-8 DSCBs and the format-4 DSCB.
VTOC pack space map (VPSM) identifies the free and allocated space on a
volume.
VTOC index map (VIXM) identifies the VIRs that have been allocated in the
VTOC index.
VTOC map of DSCBs (VMDS) identifies the DSCBs that have been allocated
in the VTOC.
A format-1 DSCB in the VTOC contains the name and extent information of the
VTOC index. The name of the index must be 'SYS1.VTOCIX.volser', where 'volser' is
the serial number of the volume containing the VTOC and its index. The name
must be unique within the system to avoid ENQ contention and must conform to
standard data set naming conventions.
Note:
Chapter 1. Using the Volume Table of Contents
17
Using the VTOC
1. If first character of volser is numeric, you must either precede or replace the
first character with the letter "V" (for example, if volser is 12345, then you
should use either V12345 or V2345).
2. RMF™ statistics on the VTOC index will always show the data set name as
SYS1.VTOCIX.Vvolser regardless of what the actual name is on the volume.
You can only create (allocate) one data set whose name begins with
'SYS1.VTOCIX.' on a volume. To rename a VTOC index data set when the VTOC
index is active, use a name beginning with 'SYS1.VTOCIX.'. If a 'SYS1.VTOCIX.'
data set already exists on a volume, you cannot rename another data set on the
volume to a name with those qualifiers. If the VTOC index is active, you cannot
scratch the VTOC index data set.
The relationship of a VTOC to its index is shown in Figure 4.
VTOC
VTOC Index
┌────────────────────────────┐
┌────→┌─────────────────────────┐
³
Format─4 DSCB
³
³
³
VIXM
³
├────────────────────────────┤
³
├─────────────────────────┤
³
Format─5 DSCB
³
³
³
VPSM
³
├────────────────────────────┤
³
├─────────────────────────┤
³
³
³
³
VMDS
³
³
Other DSCBs
³
³
├─────────────────────────┤
³
³
³
³
VIER
³
³
³
³
├─────────────────────────┤
├────────────────────────────┤
³
³
VIER
³
³ Format─1 DSCB for the VTOC ├─────┘
├─────────────────────────┤
³ Index: SYS1.VTOCIX.nnn
³
³
VIER
³
├────────────────────────────┤
├─────────────────────────┤
³
³
³
.
³
³
Other DSCBs
³
³
.
³
³
³
³
.
³
!────────────────────────────┘
!─────────────────────────┘
Figure 4. Example of the Relationship of a VTOC to Its Index
VTOC Index Records
VTOC index records consist of the following types:
VTOC Index Entry Record
The first level-one VIER is created with the VTOC index. Subsequent VIERs are
created whenever a VIER is too full to allow a data set name to be added to the
VTOC index. VIERs have the following characteristics:
v A VIER uses one VIR and contains variable-length index entries. The number of
VIERs in an index depends upon the number of data sets on the volume.
v All index entries within a VIER are at the same index level. VIERs in a VTOC
index can be on several levels and have a hierarchic relationship. Index entries
in higher-level VIERs point to lower-level VIERs. Index entries in level-one
VIERs (those at the lowest level) point to format-1 or format-8 DSCBs for data
sets on the volume.
v Whenever a fourth VIER is created on the same level, a VIER at a higher level is
created. Once a higher-level VIER is filled with pointers to lower-level VIERs,
another VIER at the same level is created.
18
z/OS DFSMSdfp Advanced Services
Using the VTOC
VTOC Pack Space Map
The VPSM shows the allocated space on a volume and the space that remains free.
The space within the first 65,520 cylinders is called the track-managed space. The
VPSMs for this area contains bit maps of the cylinders and tracks on the volume. A
value of one indicates that the cylinder or track has been allocated; zero, that it is
unallocated. The space after the first 65,520 cylinders is called the
cylinder-managed space. The VPSMs for this area contains bit maps of only
multicylinder units. Individual cylinders and tracks are not mapped in this type of
VPSM. A value of one indicates that the multicylinder unit is allocated; zero, that it
is unallocated.
VTOC Index Map
The VIXM contains a bit map in which each bit represents one VTOC index record.
The status of the bit indicates whether the VIR is allocated (1), or unallocated (0).
On an extended address volume, the VIXM record header is enlarged to
accommodate the volume size, free space statistics for the VTOC and index, free
space statistics for the entire volume and from track-managed space. Fields in this
expanded header define the RBA of the first VPSM record that maps multicylinder
units, along with the minimum allocation unit in cylinders for the VPSMs that map
cylinder-managed space.
An area of the VIXM is reserved for VTOC recording facility (VRF) data. (This
facility allows detection of and recovery from some errors in an indexed VTOC.)
VTOC map of DSCBs
The VMDS shows the DSCBs that have been allocated in the VTOC. The map
contains a bit map of DSCBs corresponding the relative DSCB record in the VTOC.
A value of one indicates that the DSCB has been has been allocated; zero indicates
that it is unallocated.
Structure of an Indexed VTOC
Indexed and nonindexed VTOCs have similar structures with the following
differences for an indexed VTOC:
v Only a single, empty format-5 DSCB exists.
v Some format-4 DSCB data (the number of format-0 DSCBs and the CCHHR of
the highest format-1 DSCB) is not maintained by DADSM. The VSE bit (bit 0 in
field DS4VTOCI), set to 1 in the format-4 DSCB, indicates that the contents of
these fields (and the format-5 DSCB) are not valid. The index bit (bit 7 in field
DS4VTOCI) is set in the format-4 DSCB; it indicates that a VTOC index exists.
Accessing the VTOC with DADSM Macros
You can use either DADSM or common VTOC access facility (CVAF) macros to
access a VTOC and its index. (CVAF access is described in “Accessing the VTOC
with CVAF Macros” on page 57.) The DADSM macros and tasks covered here
include:
v LSPACE provides information on volume size, free space on the volume, free
space on the VTOC and INDEX, volume fragmentation, and VTOC status. Also
provided is information on the size of the track-managed space and its free
space statistics.
v OBTAIN reads one or more DSCBs from the VTOC.
v PARTREL releases unused space from a sequential or partitioned data set or a
PDSE.
v REALLOC allocates DASD space.
Chapter 1. Using the Volume Table of Contents
19
Using the VTOC
To read one or more DSCBs into virtual storage, use the OBTAIN and CAMLST
macro instructions. Identify the DSCB to be read using the name of the data set
associated with the DSCB, or the absolute track address of the DSCB. Provide a
140-byte data area in virtual storage to contain the DSCB. On a request to read
multiple DSCBs specify the NUMBERDSCB= parameter on the OBTAIN or
CAMLST macro and provide consecutive 140-byte return areas in virtual storage to
contain this number of DSCBs. When you specify the name of the data set, an
identifier (format-1, format-4, or format-8) DSCB is read into virtual storage. To
read a DSCB other than a format-1, format-4, or format-8 DSCB, specify an
absolute track address (see the example on page “Example” on page 42). Code the
EADSCB=OK on the OBTAIN or CAMLST macro when your program supports
DSCBs that describe data sets with format-8 and format-9 DSCBs. The extent
descriptors in DSCBs for a data set described with these formats may have 28-bit
cylinder track addresses. Use the TRKADDR macro or IECTRKAD service to
manipulate 16-bit or 28-bit cylinder track addresses.
Restriction: You cannot use the OBTAIN macro instruction with either a SYSIN or
SYSOUT data set.
To release unused space from a sequential, partitioned, or key sequenced data set
or a PDSE, use the PARTREL macro instruction. Your program must be APF
authorized.
Another way is to code the RLSE option on the SPACE keyword on the DD
statement or the dynamic allocation equivalent. This technique does not require
APF authorization. It requires that your program open the data set with the
OUTPUT, EXTEND, OUTIN, OUTINX or INOUT option and the last operation
before closing the data set not be a read or POINT macro."
The following macro instruction descriptions include coding examples,
programming notes, and exception return code descriptions.
Requesting DASD Volume Information Using LSPACE
LSPACE provides information on volume size, free space on the volume, free space
on the VTOC and INDEX, volume fragmentation, and VTOC status. Also provided
is information on the size of the track-managed space and its free space statistics.
The LSPACE macro returns status information (such as LSPACE subfunction,
return code, and reason code) in the parameter list. The LSPACE macro also
returns the return code in register 15. For volumes that are configured with more
than 9999 cylinders, you can use the EXPMSG option to create an expanded
message return area that the LSPACE macro needs. For volumes that are
configured with cylinder-managed space, you can use the XEXPMSG option to
create an extended expanded message return area that the LSPACE macro needs.
The use of XEXPMSG is recommended for all requests to return message data. The
expanded data return area (EXPDATA) will return binary data of free space and
total volume space information for volumes. For volumes with cylinder-managed
space, this will be returned as free space for the entire volume and free space for
the track-managed space. The two sets of free space data will be the same for a
volume that does not have cylinder-managed space. The use of EXPDATA is
recommended for all requests to return binary data. You can have LSPACE return
additional information such as the format 4 DSCB, the total number of free extents
on the volume or the fragmentation index. This information can be returned in the:
v Message return area
v Expanded message return area
v Extended expanded message return area
20
z/OS DFSMSdfp Advanced Services
Using the VTOC
v Data return area
v Expanded data return area
v Format-4 DSCB return area
The calling program must ensure that the volume to be processed remains
mounted during LSPACE processing. The volume need not be allocated.
If the device is not ready when you issue LSPACE and remains not ready, LSPACE
eventually gives return code 4 with a timeout message. (See Table 8 on page 34.) In
the current level of the system, LSPACE defaults to waiting as long as 240 seconds.
You can change this amount of time by setting the byte at offset 7 in the parameter
list. (See Table 7 on page 30.) You must use the list and execute forms of the macro
because the macro has no parameter for this.
For more information about the LSPACE return code, subfunction code, and the
subfunction return and reason codes, see Table 8 on page 34 and z/OS DFSMSdfp
Diagnosis.
LSPACE—Standard Form
The format of the standard form of the LSPACE macro is:
►►
LSPACE
label
UCB=
MF
=
I
addr
(reg)
,MSG=
addr
(reg)
0
,EXPMSG=
addr
(reg)
0
,DATA= addr
(reg)
0
,XEXPMSG= addr
(reg)
0
,EXPDATA= addr
(reg)
0
►
►
►
,SMF=
TEST
NONE
,F4DSCB=
addr
(reg)
0
,DATATYPE=
ALL
FRAGINDEX
INDEX
VOLUME
VTOC
►
►
,ENQHELD=
YES
NO
,PLISTVER=
IMPLIED_VERSION
plistver
MAX
►
►◄
,TIMEOUT=
_value
(reg)
The keywords are the same as described in the execute form of the LSPACE macro.
See the execute form of the LSPACE macro for the descriptions.
MF=I
Specifies the standard form of the LSPACE macro.
Chapter 1. Using the Volume Table of Contents
21
Using the VTOC
I
Specifies the standard form of the macro. This generates a standard
parameter list containing the required variables, loads the address of the
parameter list in register 1, and issues a supervisor call. The standard form
is the default.
Requirement: UCB must be specified when MF=I is used.
PLISTVER=plistver | IMPLIED_VERSION | MAX
This keyword defines the version of the LSPACE parameter list that should be
generated for the MF=I form of the LSPACE macro.
PLISTVER=plistver specifies the version of the LSPACE parameter list that
should be generated, where plistver is either 1 or 2. This PLISTVER= keyword
is required for any macro keys associated with version 2 or larger to be
specified. The macro keys associated with each supported version of the macro
are listed below:
PLISTVER=1
PLISTVER=1 is associated with the following macro keys:
DATA
EXPMSG
F4DSCB
MSG
SMF
PLISTVER=2
PLISTVER=2 is associated with the following macro keys:
XEXPMSG
EXPDATA
DATATYPE
TIMEOUT
ENQHELD
When PLISTVER= IMPLIED_VERSION is specified the generated parameter
list is the lowest version that allows all of the parameters on the invocation to
be processed. When PLISTVER is omitted, the default is the lowest version of
the parameter list, which is version 1.
When PLISTVER= MAX is specified, the generated parameter list is the largest
size currently supported. This size may grow from release to release thus
possibly affecting the amount of storage needed by your program. If your
program can tolerate this, IBM recommends that you always specify MAX
when creating the list form parameter list as that will ensure that the list form
parameter list is always long enough to hold whatever parameters might be
specified on the execute form.
TIMEOUT=__ value |_(reg)
Specifies the elapsed-time value, in units of seconds, that the caller is willing to
wait for the LSPACE function to complete. Note that TIMEOUT is the
elapsed-time value, not the address-of-value. This timeout value includes the
time it takes for LSPACE to obtain the SYSVTOC ENQ resource. The value
must be a positive number between 1 and 86400, inclusive.
value
The value can be an integer number or a symbol.
(reg) (2-12)
Specifies a register containing the elapsed-time value, in units of seconds,
that the caller is willing to wait for the LSPACE function to complete.
22
z/OS DFSMSdfp Advanced Services
Using the VTOC
LSPACE-Execute Form
The format of the execute form of the LSPACE macro is:
►►
LSPACE MF=
label
(E,addr)
(E,(reg))
►
,UCB=
addr
(reg)
►
►
,MSG=
addr
(reg)
0
,EXPMSG=
addr
(reg)
0
,DATA= addr
(reg)
0
,XEXPMSG= addr
(reg)
0
,EXPDATA= addr
(reg)
0
,SMF=
TEST
YES
NONE
,ENQHELD=
YES
NO
►
►◄
,F4DSCB=
addr
(reg)
0
,DATATYPE=
ALL
FRAGINDEX
INDEX
VOLUME
VTOC
,TIMEOUT=
_value
(reg)
MF=(E,addr) or (E,(reg))
Specifies the execute form of the LSPACE macro.
The MF=L form is usually issued before the execute form to create the
parameter list.
(E,addr)
Loads the address of the parameter list specified by addr into register 1 and
then issues a supervisor call.
(E,(reg))
Loads the address of the parameter list specified by (reg) into register 1
and then issues a supervisor call.
UCB=addr or (reg)
Specifies the address of the UCB for the volume whose free space information
you are requesting. The address can be for a captured UCB, or for an actual
UCB above or below the 16MB line. For 31-bit callers, the high-order byte is
part of the UCB address and must be cleared to zeros if a 24-bit UCB address
is being passed.
addr—RX-type address
Specifies the address of a fullword containing the UCB address.
(reg)—(2-12)
Specifies a register containing the UCB address for the device. Note that
this differs from the addr form of the parameter.
Chapter 1. Using the Volume Table of Contents
23
Using the VTOC
When using the standard (MF=I) form of the macro, you must provide a UCB
address.
Restrictions:
1. The LSPACE macro will accept the address of a UCB or UCB copy.
Unauthorized programs can get a copy of the UCB by using the UCBSCAN
macro and specifying the COPY and UCBAREA keywords. The UCB copy
can be above or below the 16MB line and on a word boundary. Refer to
z/OS HCD Planning for details.
2. LSPACE does not support VIO UCBs.
MSG=addr or (reg)or 0 or EXPMSG=addr or (reg) or 0 or DATA= addr or (reg)
or 0
Specifies the way LSPACE is to return free space information. (optional)
Restriction: The MSG, EXPMSG, and DATA parameters are mutually
exclusive.
MSG=addr or (2-12) or 0
Specifies the address of a caller-provided 30-byte message return area into
which LSPACE returns either a free space message or, for unsuccessful
requests, status information. For a description of this area, see “Message
Return Area” on page 33.
addr–RX-type address
Specifies the address of the message return area.
(reg)–(2-12)
Specifies a register containing the address of the message return area.
0
Specifies that you do not want the free space message. This is the default
for all forms of the macro except execute.
EXPMSG=addr or (reg) or 0
Specifies the address of a caller-provided 40-byte expanded message return
area into which LSPACE returns either a free space message or, for
unsuccessful requests, status information. For a description of this area, see
“Expanded Message Return Area” on page 35.
addr–RX-type address
Specifies the address of the message return area.
(reg)–(2-12)
Specifies a register containing the address of the message return area.
0
Specifies that you do not want the free space message. This is the default
for all forms of the macro except execute.
DATA=addr or (reg) or 0
Specifies the address of a caller-provided data return area into which LSPACE
returns free space and volume information. For a description of this area, see
“Data Return Area” on page 35.
addr–RX-type address
Specifies the address of the data return area.
(reg)–(2-12)
Specifies a register containing the address of the data return area.
0
24
Specifies that you do not want the free space and volume information.
z/OS DFSMSdfp Advanced Services
Using the VTOC
SMF=TEST or YES or NONE
Specifies the type of SMF processing.
TEST
Specifies that LSPACE is to test for an active SMF system and whether
SMF volume information is desired. If these conditions are met, an SMF
record is written.Only programs executing in supervisor state, protect key 0-7,
or APF authorized can specify this operand.
YES
Specifies that you want an SMF record containing volume information to
be written. Only programs executing in supervisor state, protect key 0-7, or APF
authorized can specify this operand.
NONE
Specifies that you do not want an SMF record containing volume
information to be written. This is the default for all forms of the macro
except execute.
F4DSCB=addr or (reg) or 0
Specifies the address of a 96-byte DSCB return area provided by the calling
program, into which LSPACE returns the volume's format-4 DSCB. For a
description of the format-4 DSCB fields, see Table 4 on page 12.
addr– RX-type address
Specifies the address of the format-4 DSCB return area.
(reg)– (2-12)
Specifies a register containing the address of the format-4 DSCB return
area.
0
Specifies that you do not want the data portion of the format-4 DSCB for
the volume. This is the default for all forms of the macro except execute.
XEXPMSG=addr or (reg) or 0
Specifies the address of a caller-provided 95-byte extended expanded message
return area into which LSPACE returns either a free space message or, for
unsuccessful requests, status information. Specify this keyword if you wish to
obtain free space information in the message return area for volumes that are
configured with cylinder-managed space. The returned free space will include
space for the total volume and space from the track-managed space on a
volume. The two sets of free space message data will be the same for a volume
that does not have cylinder-managed space. The use of XEXPMSG is
recommended for all requests to return message data. See “LSPACE
Information Return Areas” on page 33 for a description of the message return
area.
addr– RX-type address
Specifies the address of the message return area.
(reg)– (2-12)
Specifies a register containing the address of the message return area.
0
Specifies that you do not want the free space message. This is the default
for all forms of the macro except execute.
EXPDATA=addr or (reg) or 0
Specifies the address of a caller-provided EXPANDED data return area into
which LSPACE returns expanded free space and volume information. Specify
this keyword if you wish to obtain free space information and total volume
space in the LSPACE data return area for volumes. The returned free space will
include space for the total volume and space from the track managed space on
Chapter 1. Using the Volume Table of Contents
25
Using the VTOC
a volume. For volumes with cylinder-managed space this data will be returned
as free space for the entire volume and free space for the track-managed space.
The two sets of free space data will be the same for a volume that does not
have cylinder-managed space. The use of EXPDATA is recommended for all
requests to return binary data. See Table 9 on page 35 for a description of the
expanded data return area.
addr– RX-type address
Specifies the address of the expanded data return area.
(reg)– (2-12)
Specifies a register containing the address of the expanded data return
area.
0
Specifies that you do not want the expanded free space and volume
information.
ENQHELD=YES or NO
Specifies whether the LSPACE address space of the caller has already obtained
the SYSVTOC resource.
YES
Specifies that the LSPACE address space of the caller (which can be the
TCB calling LSPACE, or another task within the address space of the
caller), has issued a RESERVE or ISGENQ
REQUEST=OBTAIN,RESERVEVOLUME=YES for the SYSVTOC resource of
the volume for which LSPACE is being called. When ENQHELD=YES is
specified, the caller must obtain the SYSVTOC resource before invoking
LSPACE (LSPACE verifies that the address space of the caller holds the
SYSVTOC resource). The address space can obtain the SYSVTOC resource
shared or exclusive, but the SYSVTOC must be a SYSTEMS ENQ of the
RESERVE type. Specifying ENQHELD=YES on the execute form will
override the specifications or the defaulting of ENQHELD=NO on the list
form. Note that APF-authorization is required for the caller to obtain the
SYSVTOC resource.
NO Specifies that the LSPACE address space of the caller has not obtained the
SYSVTOC resource before calling LSPACE. This is the default. If the caller
holds SYSVTOC but has specified or defaulted to ENQHELD=NO, the
LSPACE request is failed. Specifying ENQHELD=NO on the execute form
will override the specification of ENQHELD=YES on the list form.
DATATYPE= ALL or FRAGINDEX or INDEX orVOLUME orVTOC
This keyword is allowed only when the DATA or EXPDATA keyword is
specified. Only the information specified will be returned to the caller.
DATATYPE is valid for both non-EAV and EAV. This keyword will eliminate
unnecessary I/O required to retrieve free space information that is not be
required by the caller. DATATYPE=ALL is the default.
ALL
Provide all available LSPACE statistics. This is the default
FRAGINDEX
Provide the fragmentation index
INDEX
Provide free space information related to the VTOC INDEX
VOLUME
Provide free space information for the VOLUME
VTOC Provide free space information related to the VTOC
26
z/OS DFSMSdfp Advanced Services
Using the VTOC
PLISTVER
This keyword, if specified on the MF=E form of the LSPACE macro, will
generate an MNOTE.
TIMEOUT=value or (reg)
Specifies the elapsed-time value, in units of seconds, that the caller is willing to
wait for the LSPACE function to complete. Note that TIMEOUT is the
elapsed-time value, not the address-of-value. This timeout value includes the
time it takes for LSPACE to obtain the SYSVTOC ENQ resource. The value
must be a positive number between 1 and 86400, inclusive.
value
The value can be an integer number or a symbol.
(reg) (2-12)
Specifies a register containing the elapsed-time value, in units of seconds,
that the caller is willing to wait for the LSPACE function to complete.
LSPACE—List Form
The format of the list form of the LSPACE macro is:
►►
LSPACE MF=
label
L
(L,MSG)
(L,EXPMSG)
(L,XEXPMSG)
(L,DATA)
(L,EXPDATA)
►
,MSG=
addr
0
,EXPMSG=
addr
0
,XEXPMSG= addr
0
,EXPDATA= addr
0
,DATA=
addr
0
►
►
,SMF=
TEST
YES
NONE
,F4DSCB=
addr
0
,DATATYPE=
ALL
FRAGINDEX
INDEX
VOLUME
VTOC
►
►◄
,PLISTVER=
IMPLIED_VERSION
plistver
MAX
,TIMEOUT=
value
MF=L or (L,MSG) or (L,EXPMSG) or (L,EXPMSG) or (L,DATA) or (L,EXPDATA)
Specifies the list form of the LSPACE macro.
L
Generates the required constants in the calling program. You can then issue
the execute form of the macro, which uses these constants.
(L,MSG)
Generates the required message return area constants in the calling
program. No other parameters are allowed.
(L,EXPMSG)
Generates the required expanded message return area constants in the
calling program. No other parameters are allowed.
Chapter 1. Using the Volume Table of Contents
27
Using the VTOC
(L,XEXPMSG)
Generates the required extended expanded message return area constants
(95-bytes) in the calling program. No other parameters are allowed. Use
this keyword to obtain the message data area for all volume sizes
including ones with cylinder-managed space.
(L,DATA)
Generates the required data return area constants in the calling program.
No other parameters are allowed.
(L,EXPDATA)
Generates the required expanded data return area constants in the calling
program. No other parameters are allowed. Use the keyword to obtain the
data area for all volume sizes including ones with cylinder-managed space.
DATATYPE=ALL or FRAGINDEX or INDEX orVOLUME orVTOC
This keyword is allowed only when the DATA or EXPDATA keyword is
specified. Only the information specified will be returned to the caller.
DATATYPE is valid for both non-EAV and EAV. This keyword will eliminate
unnecessary I/O required to retrieve free space information that is not be
required by the caller. DATATYPE=ALL is the default.
ALL
Provide all available LSPACE statistics. This is the default
FRAGINDEX
Provide the fragmentation index
INDEX
Provide free space information related to the VTOC INDEX
VOLUME
Provide free space information for the VOLUME
VTOC Provide free space information related to the VTOC
PLISTVER=plistver | IMPLIED_VERSION | MAX
This keyword defines the version of the LSPACE parameter list that should be
generated for the MF=I form of the LSPACE macro.
PLISTVER=plistver specifies the version of the LSPACE parameter list that
should be generated, where plistver is either 1 or 2. This PLISTVER= keyword
is required for any macro keys associated with version 2 or larger to be
specified, The macro keys associated with each supported version of the macro
are listed below:
PLISTVER=1
PLISTVER=1 is associated with the following macro keys:
DATA
EXPMSG
F4DSCB
MSG
SMF
PLISTVER=2
PLISTVER=2 is associated with the following macro keys:
XEXPMSG
EXPDATA
DATATYPE
ENQHELD
TIMEOUT
28
z/OS DFSMSdfp Advanced Services
Using the VTOC
When PLISTVER= IMPLIED_VERSION is specified the generated parameter
list is the lowest version that allows all of the parameters on the invocation to
be processed. When PLISTVER is omitted, the default is the lowest version of
the parameter list, which is version 1.
When PLISTVER= MAX is specified, the generated parameter list is the largest
size currently supported. This size may grow from release to release thus
possibly affecting the amount of storage needed by your program. If your
program can tolerate this, IBM recommends that you always specify MAX
when creating the list form parameter list as that will ensure that the list form
parameter list is always long enough to hold whatever parameters might be
specified on the execute form.
TIMEOUT=value
Specifies the elapsed-time value, in units of seconds, that the caller can wait for
the LSPACE function to complete. Note that this is the elapsed-time value, not
the address-of-value. This timeout value includes the time it takes for LSPACE
to obtain the SYSVTOC ENQ resource. The value must be a positive number
between 1 and 86400, inclusive.
value
The value can be an integer number or a symbol.
LSPACE–DSECT Form
The format of the DSECT form of the LSPACE macro is:
►►
LSPACE test MF=
label
D
(D,MSG)
(D,EXPMSG)
(D,XEXPMSG)
(D,DATA)
(D,EXPDATA)
►◄
,PLISTVER=
plistver
MAX
MF=D or (D,MSG) or (D,EXPMSG) or (D,XEXPMSG) or (D,DATA) or (D,EXPDATA)
Specifies the DSECT form of the LSPACE macro.
D
Generates a DSECT that maps the LSPACE parameter list. No other
parameters are allowed. See Table 7 on page 30 for the format of the
LSPACE parameter list.
(D,MSG)
Generates a DSECT that maps the message return area. No other
parameters are allowed. For the format of the area, see “Message Return
Area” on page 33.
(D,EXPMSG)
Generates a DSECT that maps the expanded message return area. No other
parameters are allowed. For the format of the area, see “Expanded
Message Return Area” on page 35.
(D,XEXPMSG)
Generates a DSECT that maps the extended expanded message return area
(95-bytes). No other parameters are allowed. Use this keyword to obtain
the message data area for all volume sizes including ones with
cylinder-managed space. For the format of the area, see “Expanded
Message Return Area” on page 35.
Chapter 1. Using the Volume Table of Contents
29
Using the VTOC
(D,DATA)
Generates a DSECT that maps the data return area. No other parameters
are allowed. For the format of the area, see “Data Return Area” on page 35.
(D,EXPDATA)
Generates a DSECT that maps the base and expanded data return area. No
other parameters are allowed. Use the keyword to obtain the data area for
all volume sizes including ones with cylinder-managed space. For the
format of the area, see “Data Return Area” on page 35.
PLISTVER=plistver | MAX
This keyword defines the version of the LSPACE parameter list that should
be generated for the MF=D form of the LSPACE macro.
PLISTVER=plistver specifies the version of the LSPACE parameter list that
should be generated, where plistver is either 1 or 2.This PLISTVER=
keyword is required for any macro keys associated with version 2 or larger
to be specified, The macro keys associated with each supported version of
the macro are listed below:
PLISTVER=1
PLISTVER=1 is associated with the following macro keys:
DATA
EXPMSG
F4DSCB
MSG
SMF
PLISTVER=2
PLISTVER=2 is associated with the following macro keys:
XEXPMSG
EXPDATA
DATATYPE
ENQHELD
TIMEOUT
When PLISTVER= MAX is specified, the generated parameter list is the
largest size currently supported. This size may grow from release to release
thus possibly affecting the amount of storage needed by your program. If
your program can tolerate this, IBM recommends that you always specify
MAX when creating the list form parameter list as that will ensure that the
list form parameter list is always long enough to hold whatever
parameters might be specified on the execute form.
When PLISTVER is omitted, the default is the lowest version of the
parameter list mapping.
Table 7. Format of the LSPACE Parameter List (MF=D)
Name
LSPAPL
LSPAPLID
LSPANGTH
LSPAFLAG
LSPASMFY
LSPASMFT
LSPADATA
LSPAMSG
LSPAEMSG
30
Offset
Bytes
Description
0(X'00')
4(X'04')
6(X'06')
4
2
1
10 . . . .
01 . . . .
..100
..010
..001
EBCDIC 'LSPA'.
Length of parameter list.
Parameter flag byte.
SMF=YES.
SMF=TEST.
Free space data request.
Message data returned.
Expanded message data requested.
z/OS DFSMSdfp Advanced Services
.
.
.
.
.
.
.
..
..
..
Using the VTOC
Table 7. Format of the LSPACE Parameter List (MF=D) (continued)
Name
Offset
LSPAEPLP
LSPAXINF
Bytes
Description
..0001..
..00001.
Expanded LSPACE parameter input list provided
Set on when expanded data (EXPDATA) or
extended expanded message (XEXPMSG)
information is returned by LSPACE processing.
Systems prior to z/OS V1R10 do not set this flag.
A program assembled (on a z/OS V1R10 or later
system) with the LSPACE macro using the
extended EXPMSG information respectively when
the program is run on a system prior to z/OS
V1R10.
Reserved.
The maximum amount of time (seconds) LSPACE
is allowed to run. Default is 240 seconds.
LSPACE return code. See Figure 5 on page 33.
LSPACE subfunction code to further describe the
LSPACE result.
Processing complete.
Validate parameters.
Check UCB status.
Read volume label (EXCP).
Read volume label with Timeout.
ISGENQ OBTAIN RESERVEVOLUME on
SYSVTOC
STIMERM SET
ISGENQ RELEASE SYSVTOC.
ISGENQ RELEASE (conditional).
ISGQUERY for ENQHELD=YES
Validate UCB status immediately-prior to
ISGQUERY or ENQ-SYSVTOC.
Examine ISGQUERY results.
Read F4 and maps (CVAFDIR).
Get free extents (CVAFDSM).
Get F0 count (CVAFDSM).
Get VIR count (CVAFDSM).
Check for VRF (CVAFVRF).
ESTAE routine entered. Processing error in
LSPACE.
LSPACE STIMERM timeout
Subfunction return code.
Subfunction reason code.
Invalid parameter list storage key.
Invalid parameter list ID.
Invalid LSPACE flag.
Invalid authorization for System Management
Facility (SMF) flag.
Invalid message or data return area storage key.
Invalid format-4 DSCB return area storage key.
Invalid UCB address.
Invalid virtual UCB address.
Invalid VTOC pointer (UCBVTOC). Either
UCBVTOC is zero, or it does not match the volume
label.
Check for parm list length
ESTAE return code nonzero.
LSPAFRES
LSPAXTIM
7(X'07')
.......x
1
LSPAERCD
LSPASFID
8(X'08')
9(X'09')
1
1
LSPASFPC
LSPASF01
LSPASF02
LSPASF06
LSPASF07
LSPASF08
X'00'
X'01'
X'02'
X'06'
X'07'
X'08'
LSPASF09
LSPASF0A
LSPASF0B
LSPASF0C
LSPASF0D
X'09'
X'0A'
X'0B'
X'0C'
X'0D'
LSPASF0E
LSPASF4X
LSPASFEX
LSPASFF0
LSPASFVR
LSPASFVD
LSPASF85
X'0E'
X'80'
X'81'
X'82'
X'83'
X'84'
X'85'
LSPASF86
LSPASFRT
LSPASFRS
LSPARS01
LSPARS02
LSPARS03
LSPARS04
10(X'0A')
11(X'0B')
X'86'
1
1
X'01'
X'02'
X'03'
X'04'
LSPARS05
LSPARS06
LSPARS07
LSPARS08
LSPARS09
X'05'
X'06'
X'07'
X'08'
X'09'
LSPARS0A
LSPARS0B
X'0A'
X'0B'
Chapter 1. Using the Volume Table of Contents
31
Using the VTOC
Table 7. Format of the LSPACE Parameter List (MF=D) (continued)
Name
Offset
Bytes
Description
LSPARS0C
X'0C'
LSPARS0D
LSPARS0E
X'0D'
X'0E'
Timeout of ISGENQ OBTAIN for the SYSVTOC
resource.
Internal error in ECBs.
UCBVOLI is binary-zeroes (volume has gone
offline)
LSPARS0F
LSPARS10
X'0F'
X'10'
LSPARS11
X'11'
LSPARS12
X'12'
LSPARS13
X'13'
LSPARS14
LSPARS15
LSPAUCB
LSPAFRSP
LSPAFMT4
LSPAEXPL
LSPAFLAG2
LSPAXMSG
X'14'
X'15'
4
4
4
24
1
1... ....
12(X'0C')
16(X'10')
20(X'14')
24 (X'18')
LSPAEDAT
.1.. ....
*
..x. ....
The next five flags pertain to the DATATYPE keyword values.:
LSPAFRSI
...1 ....
LSPAFRVT
.... 1...
LSPAFRVX
.... .1..
LSPAFRFI
.... ..1.
LSPAFALL
.... ...1
LSPAFLAG3
LSPAENQH
LSPATIMS
LSPARSV2
LSPARES2
LSPATIMV
LSPARES3
25 (X'19')
25 (X'19')
26 (X'1A')
28(X'1C')
32(x'20')
1
1... ....
.1.. ....
..xx xxxx
2
4
16
ISGQUERY-results indicates that pointer-to the first
RS (resource) record is zero
ISGQUERY-results indicates that pointer-to the first
RQ (requester) record is zero.
ISGQUERY-results indicates that no RQ (requester)
is the owner of the SYSVTOC resource.
The required RESERVE of SYSVTOC was not
performed by the address space of the caller
The TIMEOUT value is zero or negative
The TIMEOUT value is not within allowable range
UCB address.
Address of message or data return area.
Address of format-4 DSCB.
Expanded parm list area
Parameter flag byte 2
Extended expanded message area requested
(XEXPMSG)
Expanded output data area requested (EXPDATA)
Unused
Volume is specified. the return of volume free
space information is requested
Vtoc is specified. the return of vtoc free space
information is requested
Index is specified. the return of index free space
information is requested
Fragindex is specified. the return of the
fragmentation index is requested
All is specified or defaulted. the return of all free
space information is requested, including the frag
index
Parameter flag byte 3
ENQHELD=YES was specified by the caller
TIMEOUT= was specified by the caller
Reserved (unused) bits in LSPAFLAG3
Reserved
TIMEOUT value in seconds
Reserved
Return Codes from LSPACE
Control returns to the instruction following the instructions generated by the
LSPACE macro.
See Table 8 on page 34 for a description of the LSPACE return codes.
32
z/OS DFSMSdfp Advanced Services
Using the VTOC
LSPACE returns four bytes of diagnostic information in register 0. See the
“DADSM/CVAF Diagnostic Aids” section of z/OS DFSMSdfp Diagnosis for a
description of this information.
LSPACE Information Return Areas
The LSPACE macro returns status information to the parameter list and, optionally,
returns volume information to any of the four following caller requested return
areas.
Requests for the MSG, EXPMSG, XEXPMSG, DATA, and EXPDATA areas are
mutually exclusive. LSPACE checks to ensure that the storage key of each
information return area is equal to the caller's key or that the caller is authorized
prior to its use.
Message Return Area: LSPACE returns information to a 30-byte message return
area ( Figure 5). If you provide a message return area with the MSG option,
LSPACE returns EBCDIC text, qualified by return codes as shown in Table 8 on
page 34.
LSPMSG DSECT
LSPMTEXT DS
CL30
Message Area
Message Text
Figure 5. DADSM LSPACE Free Space Information MF=(D,MSG)
Chapter 1. Using the Volume Table of Contents
33
Using the VTOC
Table 8. DADSM LSPACE Message Return Area Contents
Return Code Description
0(X'00')
For MSG keyword (30 byte area):
Text: SPACE=aaaa,bbbb, cccc/dddd,eeee where:
Free space
aaaa
=
bbbb
=
cccc
=
dddd
=
eeee
=
statistics from the entire volume:
Total number of free cylinders
Total number of additional free tracks
Total number of free extents
Number of cylinders in largest free extent
Number of additional tracks in largest free extent
For aaaa, bbbb, and cccc, the maximum value indicated is 9999 even if the
actual value is greater. Use EXPMSG to avoid use of the maximum 9999.
For EXPMSG keyword (40 byte area):
Text: SPACE=aaaaaa,bbbbbb, cccccc/dddddd,eeeeee where:
Free space
aaaaaa =
bbbbbb =
cccccc
=
dddddd =
eeeeee
=
statistics from the entire volume:
Total number of free cylinders
Total number of additional free tracks
Total number of free extents
Number of cylinders in largest free extent
Number of additional tracks in largest free extent
For aaaaaa, bbbbbb, cccccc, and dddddd, the maximum value indicated is 999999
even if the actual value is greater. Use XEXPMSG to avoid use of the
maximum 999999.
For XEXPMSG keyword (95 byte area):
Text: SPACE=aaaaaaaaa,bbbbbbbbb, ccccccccc/ddddddddd,ee,
fffffffff,gggggggggg,hhhhhhhhhh/iiiiiiiii,jj where:
Free space
aaaaaaaaa
=
bbbbbbbbbb
=
cccccccccc
=
ddddddddd
=
ee
=
statistics from the entire volume:
Total number of free cylinders
Total number of additional free tracks
Total number of free extents
Number of cylinders in largest free extent
Number of additional tracks in largest free extent
Free space statistics from the track-managed space of the volume. For a
volume without cylinder-managed space, these statistics will be equivalent to
the total volume statistics above:
fffffffff = Total number of free cylinders
gggggggggg
= Total number of additional free tracks
hhhhhhhhh
= Total number of free extents
iiiiiiiii = Number of cylinders in largest free extent
jj
= Number of additional tracks in largest free extent
Leading zeroes for each value will be set to ‘blanks’ in the returned message
area.
34
z/OS DFSMSdfp Advanced Services
Using the VTOC
Table 8. DADSM LSPACE Message Return Area Contents (continued)
Return Code Description
4(X'04')
4(X'04')
8(X'08')
12(X'0C')
16(X'10')
20 (X'14')
Text: LSPACE—PERMANENT I/O ERROR
Text: LSPACE—I/O TIMEOUT ERROR
Text: LSPACE—NON-STANDARD OS VOLUME. The volume does not have
a VTOC index and free space information is not available. Either an operating
system other than z/OS has allocated or freed space on the volume or the
volume does not have a format 5 or 7 DSCB chain.
Text: LSPACE—UCB NOT READY
Text: LSPACE—UCBVTOC IS ZERO
Text: LSPACE—INVALID PARAMETER
Text: LSPACE—NOT A DIRECT ACCESS VOL
No text returned (invalid parameter list or SMF indicator) This return code
indicates a parameter list error, which can be a bad parameter list storage key,
parameter list ID is invalid (not set to ‘LSPA’), or the parameter list size is not
sufficient.
No text returned (processing error in LSPACE)
Expanded Message Return Area: LSPACE returns information to a 40-byte
expanded message return area ( Figure 6). By providing an expanded message
return area with the EXPMSG option, LSPACE returns EBCDIC text, qualified by
return codes as shown in Table 8 on page 34.
Even though the expanded message return area displays the same return code
information as the standard message return area, the space information provided
for return code zero consists of six-digit values (aaaaaa instead of aaaa).
LSPMSG DSECT
LSPETEXT DS
CL40
Expanded Message Area
Expanded Message Text
Figure 6. DADSM LSPACE Free Space Information Format, MF=(D,EXPMSG)
Data Return Area: If you provide a data return area with the DATA or EXPDATA
keywords, LSPACE returns the information shown below. The expanded data
return area is provided only when EXPDATA is specified. EXPDATA is the
recommended keyword for returning binary data from LSPACE.
Table 9. LSPACE Data Return Area Format
Name
Offset
Bytes
LSPDRETN
LSPDSPAC
LSPDF0CN
LSPDVRCN
LSPDFRGI
LSPDCYLM
0(X'00')
1
1....
.1...
..1..
...1.
....1
LSPDRRES
LSPDSTAT
LSPDIXDS
LSPDIXAC
LSPDSRES
LSPDRSV1
1(X'01')
2(X'02')
Description
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..... x x x
1
1.......
.1......
..x xx x x x
2
Return area status byte
Returned space information
Returned F0 DSCB count
Returned free VIR count
Returned fragmentation index
Returned data is for a volume with cyl-managed
space
Reserved
Volume status byte
Index exists for VTOC
Index VTOC active
Reserved
Reserved
Chapter 1. Using the Volume Table of Contents
35
Using the VTOC
Table 9. LSPACE Data Return Area Format (continued)
Name
Offset
Bytes
Description
Beginning of the base data return area: For DATA and EXPDATA requests, the following 32 bytes if requested or
defaulted by the DATATYPE keyword will be returned. They represent statistics that describe the entire volume.
LSPDFOS and LSPDVIRS are not applicable to volume statistics.
LSPDEVFS: Free space statistics from the entire volume. For volumes with cylinder-managed space (LSPDCYLM =
'1') these statistics represent space from both the track and cylinder- managed space on the volume. See LSPDTMFS
for statistics from the track-managed space on the volume.
LSPDEVFS
LSPDNEXT
LSPDTCYL
LSPDTTRK
LSPDLCYL
LSPDLTRK
LSPDF0S
LSPDVIRS
LSPDFRAG
4(X'04')
4(X'04')
8(X'08')
12(X'0C')
16(X'10')
20(X'14)'
24(X'18')
28(X'1C')
32(X'20')
20
4
4
4
4
4
4
4
4
Total volume free space
Number of free extents
Total free cylinders
Total addition free tracks
Number of cylinders in largest free extent
Number of additional tracks in largest free extent
Format 0 count
Free VIR count
Fragmentation count
End of the base data return area.
Beginning of the expanded data return area: For EXPDATA requests, the following 32 bytes of statistics if requested
or defaulted by the DATATYPE keyword will be returned.
LSPDTMFS: Free space statistics from track-managed space on a volume for a volume with cylinder-managed space
(LSPDCYLM ='1'). For volumes with no cylinder-managed space (LSPDCYLM ='0') than these statistics are equivalent
to the total volume statistics described above.
LSPDTMFS
LSPDVNXT
LSPDVTCL
LSPDVTTK
LSPDVLCL
LSPDVLTK
36(X'24')
36(X'24')
40(X'28')
44(X'2C'
48(X'30')
52(X'34')
24
4
4
4
4
4
LSPDVFRG
56(X'38')
4
Track-managed free space
Number of free extents
Total free cylinders
Total additional free cylinders
Number of cylinders in the largest free extent
Number of additional free tracks in the largest free
extent
Fragmentation index
Volume size information
LSPDVOLI
LSPDTRKS
LSPDTRKM
LSPDRSV8
60(X'3C')
60(X'3C')
64(X'40'
68(X'44')
8
4
4
60
Volume size information
Total number of tracks on volume
Total number of tracks in track-managed space
when LSPDCYLM='1'. Set to the value of
LSPDTRKS otherwise.
When LSPDCYLM='1', this value is also the first
track address where cylinder managed space
begins.
Reserved
Format-4 DSCB Return Area: If you provide a format-4 DSCB return area with
the F4DSCB option, LSPACE returns information to it as described in Table 4 on
page 12.
36
z/OS DFSMSdfp Advanced Services
Using the VTOC
LSPACE Examples
The following example returns free space information in the message return area.
LSPAMFIM LSPACE MSG=MYMSG,UCB=(R10),MF=I
The following example returns free space information in the data return area.
LSPAMFID LSPACE DATA=MYDATA,UCB=(R10),MF=I
The following example uses the list form of the macro to define the parameter list,
and the execute form to refer to the same parameter list.
LSPALIST LSPACE MSG=MYDATA,MF=L
.
.
.
LSPAEX
LSPACE MF=(E,LSPALIST),UCB=(R10)
Reading DSCBs from the VTOC Using OBTAIN
The following section discusses using the OBTAIN routine to read a DSCB. You
can specify either the data set name or the absolute device address.
OBTAIN does not support z/OS UNIX files. You will receive unpredictable results
if you issue OBTAIN for an z/OS UNIX file.
Reading a DSCB by Data Set Name
If you specify a data set name using OBTAIN and the CAMLST SEARCH option,
the OBTAIN routine reads the 96-byte data portion of the format-1 DSCB and the
absolute track address of the DSCB into virtual storage. The absolute track address
is a 5-byte field in the form CCHHR that contains zeros for VIO data sets.
|
|
|
|
|
|
|
If the data set name is the name of a VSAM cluster that has a different name in the
VTOC, then the system returns an emulated format-1 or 8 DSCB. It does not
describe more than three extents and the system will not return a second DSCB. It
is a format-8 DSCB only if any of the first three extents has a cylinder number
greater than 32752. That is possible only on an EAV (extended addressing volume).
If the emulated DSCB is format-8, then your program must specify EADSCB=OK,
or OBTAIN will give return code 24.
The format of the OBTAIN and CAMLST macros is:
►►
OBTAIN
listname_addrx
label
►
NUMBERDSCB=number_dscbs
►
►◄
EADSCB=
NOTOK
OK
NOQUEUE=OK
Chapter 1. Using the Volume Table of Contents
37
Using the VTOC
►► listname
CAMLST
SEARCH ,dsname_relexp ,vol_relexp
,wkarea_relexp
►
►
►◄
NUMBERDSCB=number_dscbs
EADSCB=
NOTOK
OK
listname_addrx
Points to the parameter list (labeled listname) set up by the CAMLST macro
instruction.
SEARCH
Code this operand as shown.
dsname_relexp
Specifies the virtual storage location of a fully-qualified data set name. The
area that contains the name must be 44 bytes long.
Tip: A DSNAME of 44 bytes of X'04' (X'040404...04') can be used to read a
format-4 DSCB.
vol_relexp
Specifies the virtual storage location of the 6-byte volume serial number on
which the DSCB is located.
wkarea_relexp
Specifies the virtual storage location of a 140-byte work area that you must
define.
NUMBERDSCB
Specifies a value between 0 and 255 that designates the number of consecutive
140-byte return areas that are provided in wkarea_relexp. The system treats a
value of 0 as a 1. Currently the system does not support a chain of more than
12 DSCBs for one data set, but it is valid for you to provide an area that is
longer than currently needed. The system verifies that the provided area is
valid. When you provide an area that is long enough to contain more than one
DSCB, obtain processing will return DSCBs for the requested data set name in
logical VTOC order until all the 140-byte return areas are used. The logical
VTOC order is a format-1 DSCB, followed by zero or more format-3 DSCBs or
a format-8 DSCB, followed by one or more format-9 DSCBs, followed by zero
or more format-3 DSCBs. No absolute maximum number of DSCBs for a data
set should be assumed. The actual number of DSCBs are returned in a field
located in the first 140-byte return area.
On the OBTAIN macro you can code a register number or symbol for a register
number in parentheses. It means that the specified register contains the
number of DSCBs that can fit in the return area. If you code the
NUMBERDSCB parameter on OBTAIN, the macro execution stores the value in
the CAMLST area. You cannot code a register on the CAMLST macro.
Note that for programs run on a pre-z/OS R10 system that do not support this
keyword, the NUMBERDSCB value will be treated as if it were 1.
EADSCB
Specifies whether this program supports data sets with format-8 and format-9
DSCBs. Such data sets can appear on extended address volumes.
EADSCB=OK
Code EADSCB=NOTOK when your program does not support data sets
38
z/OS DFSMSdfp Advanced Services
Using the VTOC
that have format-8 and format-9 DSCBs. The extent descriptors in DSCBs
for a data set described with these formats may have track addresses that
contain cylinder addresses 65,520 or larger. EADSCB=OK is accepted for
data sets described by all DSCB types, including format-1 DSCBs,
regardless of the volume size where the data set resides. Your program can
also run on an older level of the system that does not support this
keyword. In these cases, EADSCB=OK is ignored. EADSCB=OK sets byte
2 bit 4 in the OBTAIN parameter list to on.
EADSCB=NOTOK
Code EADSCB=NOTOK when your program does not support DSCBs
that describe data sets with format-8 and format-9 DSCBs.
EADSCB=NOTOK is the default when the EADSCB keyword is not
specified.
When EADSCB=NOTOK is coded or assumed by default, OBTAIN will
set return code 24 if the target of the OBTAIN request has a format-8
DSCB.
EADSCB=NOTOK sets byte 2 bit 4 in the OBTAIN parameter list to zero.
NOQUEUE=OK
Specifies that the I/O to read DSCBs will not queue on the resource and wait if
that resource is not available.
Example: In the following example, the format-1 DSCB for data set A.B.C is read
into virtual storage using the SEARCH option. The serial number of the volume
containing the DSCB is 770655.
OBTAIN
DSCBABC
CAMLST
DC
DC
DS
SEARCH,DSABC,VOLNUM,WORKAREA
CL44’A.B.C’
DATA SET NAME
CL6’770655’
VOLUME SERIAL NUMBER
140C
140-BYTE WORK AREA
*
*
DSCBABC
DSABC
VOLNUM
WORKAREA
READ DSCB FOR DATA
SET A.B.C INTO DATA
AREA NAMED WORKAREA
Recommendation: Check the return codes.
The OBTAIN macro instruction points to the CAMLST parameter list. SEARCH,
the first operand of CAMLST, specifies that a DSCB be read into virtual storage
using the data set name at the address indicated in the second operand. DSABC
specifies the virtual storage location of a 44-byte area containing the fully-qualified
name of the data set whose format-1 DSCB is to be read. VOLNUM specifies the
virtual storage location of a 6-byte area in which you have placed the serial
number of the volume containing the required DSCB. WORKAREA specifies the
virtual storage location of a 140-byte work area into which the DSCB is to be
returned.
Control is returned to your program at the next executable instruction following
the OBTAIN macro instruction. If the DSCB has been successfully read into your
work area, register 15 contains zeros. Otherwise, register 15 contains one of the
return codes shown in Table 10 on page 40.
Chapter 1. Using the Volume Table of Contents
39
Using the VTOC
Return Codes from OBTAIN (Reading by Data Set Name)
Table 10. DADSM OBTAIN SEARCH Return Codes
Return Code
Description
0(X'00')
4(X'04')
8(X'08')
Successful completion of OBTAIN routine.
The required volume was not mounted.
The format-1 DSCB was not found in the VTOC of the specified
volume.
A permanent I/O error was encountered, or an invalid format-1 DSCB
was found when processing the specified volume, or an unexpected
error return code was received from CVAF (common VTOC access
facility).
Invalid work area pointer.
Data set has a format-8 DSCB and EADSCB=NOTOK is in effect
Internal error with EADSCB=NOTOK in effect.
12(X'0C')
16(X'10')
24(X'18')
28(X'1C')
|
On return from SEARCH requests, the first 103 bytes of the first 140 byte return
area will contain:
v The 96 byte data portion of the format-1, format-4, or format-8 DSCB
v Followed by 5 bytes that contain the absolute track address (CCHHR) of this
DSCB. For VSAM object names that appear in the catalog, but not in the VTOC
or VIO data sets, these 5 bytes contain zeros.
v Followed by a 2 byte count of the total number of DSCBs associated with the
data set DSCB, even if there are insufficient return areas into which to read them
all. This count includes all DSCB types that could describe a data set. Set to zero
for DSCBs constructed from catalog when DSCBs are not present in the VTOC.
Reading a DSCB by Absolute Device Address
You can read a DSCB from a VTOC using OBTAIN and the CAMLST SEEK option.
Specify the SEEK option by coding SEEK as the first operand of the CAMLST
macro and by providing the absolute device address of the DSCB you want to
read, unless the DSCB is for a VIO data set. Only the SEARCH option can be used
to read the DSCB of a VIO data set.
The format of the OBTAIN and CAMLST macros is:
►►
OBTAIN
listname_addrx
label
►
►◄
EADSCB=
40
►
NUMBERDSCB=number_dscbs
z/OS DFSMSdfp Advanced Services
NOTOK
OK
NOQUEUE=OK
Using the VTOC
►► listname
CAMLST
SEEK ,cchhr_relexp ,vol_relexp
,wkarea_relexp
►
►
►◄
NUMBERDSCB=number_dscbs
EADSCB=
NOTOK
OK
listname
Label of the CAMLST macro instruction.
SEEK
Code this operand as shown when calling obtain to read by the passed
CCHHR device address
cchhr_relexp
For SEEK requests, specifies the virtual storage location of the 5-byte absolute
device address (CCHHR) of a DSCB.
vol_relexp
Specifies the virtual storage location of the 6-byte volume serial number on
which the DSCB is located.
wkarea_relexp
For all requests, specifies the virtual storage location of a 140-byte work area,
or larger, that must be defined.
NUMBERDSCB
Specifies a value between 0 and 255 that designates the number of consecutive
140-byte return areas that are provided in wkarea_relexp. The system treats a
value of 0 as a 1. Currently the system does not support a chain of more than
12 DSCBs for one data set, but it is valid for you to provide an area that is
longer than currently needed. The system verifies that the provided area is
valid. When you provide an area that is long enough to contain more than one
DSCB, OBTAIN processing will return DSCBs for the requested data set name
in logical VTOC order until all the 140-byte return areas are used. The logical
VTOC order is a format-1 DSCB, followed by zero or more format-3 DSCBs or
a format-8 DSCB, followed by one or more format-9 DSCBs, followed by zero
or more format-3 DSCBs. No absolute maximum number of DSCBs for a data
set should be assumed. When the target of the seek operation is not a format-1
or format-8 DSCB, the NUMBERDSCB value is treated as if it were 1 and only
that single DSCB will be returned.
On the OBTAIN macro, you can code a register number or symbol for a
register number in parentheses. This means that the specified register contains
the number of DSCBs that can fit in the return area. If you code the
NUMBERDSCB parameter on OBTAIN, the macro execution stores the value in
the CAMLST area. You cannot code a register on the CAMLST macro.
Note that for programs run on a pre-z/OS R10 system that do not support this
keyword, the NUMBERDSCB value will be treated as if it were 1.
EADSCB
Specifies whether this program supports data sets with format-8 and format-9
DSCBs. Such data sets can appear on extended address volumes.
EADSCB=OK
Code EADSCB=NOTOK when your program does not support data sets
that have format-8 and format-9 DSCBs. The extent descriptors in DSCBs
for a data set described with these formats may have track addresses that
Chapter 1. Using the Volume Table of Contents
41
Using the VTOC
contain 28-bit cylinder numbers. EADSCB=OK is accepted for data sets
described by all DSCB types, including format-1 DSCBs, regardless of the
volume size where the data set resides. Your program can also run on an
older level of the system that does not support this keyword. In these
cases, EADSCB=OK is ignored. EADSCB=OK sets byte 2 bit 4 in the
OBTAIN parameter list to on.
EADSCB=NOTOK
Code EADSCB=NOTOK when your program does not support DSCBs
that describe data sets with format-8 and format-9 DSCBs.
EADSCB=NOTOK is the default when the EADSCB keyword is not
specified.
When EADSCB=NOTOK is coded or assumed by default, OBTAIN will
set return code 24 if the target of the OBTAIN request has a format-8 or
format-9 DSCB. OBTAIN will not check format-3 DSCB extent ranges for
track addresses that contain 28-bit cylinder numbers.
EADSCB=NOTOK sets byte 2 bit 4 in the OBTAIN parameter list to zero.
NOQUEUE=OK
Specifies that the I/O to read DSCBs will not queue on the resource and wait if
that resource is not available.
Example: In the following example, the DSCB at actual-device address
X'00 00 00 01 07' is returned in the virtual storage location READAREA, using the
SEEK option. The DSCB resides on the volume with the volume serial number
108745.
OBTAIN
ACTADDR
CAMLST
DC
DC
DS
SEEK,CCHHR,VOLSER,READAREA
XL5’0000000107’ ABSOLUTE TRACK ADDRESS
CL6’108745’
VOLUME SERIAL NUMBER
140C
140-BYTE WORK AREA
*
*
*
ACTADDR
CCHHR
VOLSER
READAREA
READ DSCB FROM
LOCATION SHOWN IN CCHHR
INTO STORAGE AT LOCATION
NAMED READAREA
Recommendation: Check the return codes.
The OBTAIN macro points to the CAMLST parameter list. SEEK, the first operand
of CAMLST, specifies that a DSCB be read into virtual storage. CCHHR specifies
the storage location containing the 5-byte actual-device address of the DSCB.
VOLSER specifies the storage location containing the serial number of the volume
where the DSCB resides. READAREA specifies the storage location to which the
140-byte DSCB is to be returned.
Control is returned to your program at the next executable instruction following
the OBTAIN macro instruction. If the DSCB has been read into your work area,
register 15 contains zeros. Otherwise, register 15 contains one of the return codes
shown in Table 11.
Return Codes from OBTAIN (Reading by Absolute Device
Address)
Table 11. DADSM OBTAIN SEEK Return Codes
42
Return Code
Description
0(X'00')
Successful completion of OBTAIN routine.
z/OS DFSMSdfp Advanced Services
Using the VTOC
Table 11. DADSM OBTAIN SEEK Return Codes (continued)
Return Code
Description
4(X'04')
12(X'0C')
The required volume was not mounted.
A permanent I/O error was encountered or an unexpected error
return code was received from CVAF.
Invalid work area pointer.
The SEEK option was specified and the absolute track address
(CCHHR) is not within the boundaries of the VTOC.
Data set has a format-8 or format-9 DSCB and EADSCB=NOTOK is
in effect
Internal error with EADSCB=NOTOK in effect.
16(X'10')
20(X'14')
24(X'18')
28(X'1C')
On return from SEEK requests with multiple DSCBs requested, the entire 140 bytes
of the first return area will contain the 140 byte key and data portions of the
DSCBs read from the volume. The remaining 140 byte return areas will contain the
entire 140 byte key and data portions of the DSCBs chained from this first DSCB
until the chain of DSCBs has ended or until the 140 byte return areas are
exhausted.
On return from SEEK requests without multiple DSCBs specified, the first return
area will contain the entire 140 byte key and data portions of the DSCB read from
the user’s passed device address.
Releasing Unused Space from a DASD Data Set Using
PARTREL
DADSM supports the release of unused space that is allocated to sequential or
partitioned data sets, PDSEs, sequential extended-format data sets, and VSAM
extended format data sets.The partial release function is called when:
v The data set is closed (if the RLSE subparameter of SPACE was specified on its
DD statement or the storage administrator specified an appropriate value for the
partial release option in the management class definition).
v A restart is processing from a checkpoint taken before the data set was extended.
v DFSMShsm performs a space management cycle and an appropriate value is
specified in the management class definition.
v A PARTREL macro is issued.
For an extended address volume, partial release processing will release space on
multicylinder unit boundaries when the last used track is in an extent in
cylinder-managed space. For VSAM striped data sets where at least one stripe is
on an extended address volume, partial release processing will ensure the stripes
remain the same size. For these reasons, it is possible that the high allocated track
after the release may be larger than the last used track or that no space could be
released.
The PARTREL Macro
The PARTREL macro supports sequential and partitioned data sets on volumes
with or without indexed VTOCs. It supports PDSEs and extended format data sets
on SMS-managed volumes for which indexed VTOCs are required. PARTREL does
not support z/OS UNIX files. You will receive unpredictable results if you issue
PARTREL for z/OS UNIX files.
Chapter 1. Using the Volume Table of Contents
43
Using the VTOC
PARTREL can be coded in the execute, DSECT, and list forms, but not the standard
form. The calling program:
v Must be APF authorized.
v Must have allocated the volume to this task and must ensure it stays mounted
during the PARTREL function.
v Must ensure that the data set is not open.
v Must not hold any locks or an ENQ on the VTOC.
v Must provide the address of an available standard register save area in general
register 13.
v Can provide the associated parameter list and parameters in storage either above
or below 16MB virtual.
v Can be in any storage key.
v Can run in either supervisor or problem program state.
v Can be in either 24 or 31-bit addressing mode.
v Requires the address of a UCB, not a UCB copy.
PARTREL–Execute Form
The format of the execute form of the PARTREL macro is:
►►
PARTREL MF=
label
(E,address)
(E,(reg))
►
,DSN=
addr
(reg)
►
►
,ERASE=
TEST
YES
NO
,MODE=
PGM
SUP
,TIOT=
ENQ
NOENQ
,UCB= (reg)
►
►
,VSAMTYPE=
KSDS
RRDS
LDS
VRRDS
,VSAMSEC=
BYPASS
NOBYPASS
,VSAMFMT=
EXTD
STD
,VSAMCLLR=
VSAMCLSE
NOTVSAM
►
►◄
,VSAMTRKS=
addr
(reg)
Except for MODE, all parameters default to the current contents of the parameter
list. The MODE parameter defaults to PGM.
Descriptions of these parameters include information about DADSM processing.
The descriptions use the term value to designate the parameter value passed to
DADSM. The value can be:
v Specified as a parameter on the PARTREL macro
v Provided as the parameter's associated value in the parameter list
v Defined by DADSM from the information provided in the request.
MF=(E,addr) or (E,(reg))
Specifies the execute form of the macro and the address of an existing
PARTREL parameter list.
addr—RX-type address, (reg)—(0-12)
Specifies the PARTREL parameter list address.
44
z/OS DFSMSdfp Advanced Services
Using the VTOC
DSN=addr or (reg)
Specifies the address of a 44-byte area that contains the data set name. The
name must be left-justified, with any unused bytes defined as blanks. For a
VSAM file, you must specify the component name, not the cluster name.
addr—RX-type address, (reg)—(0), (2-12)
You must provide a value for DSN.
ERASE=YES or NO or TEST
Specifies a residual data erase attribute (see “Deleting a Data Set from the
VTOC” on page 145 for a description of erase attributes). ERASE=YES and
ERASE=NO are mutually exclusive. The default is ERASE=TEST. If you specify
VSAMTYPE, ERASE is ignored.
ERASE=YES
Specifies that the area being released should be erased (overwritten with
zeros) before it is made available for new allocations.
ERASE=NO
Specifies that the area should not be erased. This specification overrides
the RACF® erase attribute.
ERASE=TEST
Specifies that the associated RACF erase attribute is to be used.
MODE=PGM or SUP
Specifies that PARTREL is requested by a caller in problem program state
(MODE=PGM) or in supervisor state (MODE=SUP). MODE=PGM is the
default.
If the calling program is in supervisor state (and wants control returned in
supervisor state), the value of MODE must be SUP. If the calling program is in
problem program state, the value of MODE must be PGM.
TIOT=ENQ or NOENQ
Specifies the desired SYSZTIOT and SYSDSN ENQ processing within partial
release. The default is ENQ. If you specify VSAMTYPE, TIOT is ignored.
TIOT=ENQ
Specifies that partial release is to do its normal, exclusive ENQ on
SYSZTIOT and SYSDSN. If either of these ENQ requests fails, PARTREL
terminates the request with a return code of X'08'.
TIOT=NOENQ
Specifies that the caller has provided the necessary serialization. If partial
release finds that the caller does not have exclusive use of SYSDSN,
PARTREL terminates the request with a return code of X'24'.
When TIOT=NOENQ is specified and flag PRLTIOTX is set on, the ENQ
TEST is not executed. This is a dangerous option and can cause data
corruption. IBM recommends that you not set PRLTIOTX.
UCB=(reg)
Specifies the address of the UCB for the volume on which the subject data set
resides. The UCB address can be for a captured UCB, or for an actual UCB
above or below the 16MB line. For 31-bit callers, the high-order byte is part of
the UCB address and must be cleared to zeros if a 24-bit UCB address is being
passed. The volume must be mounted, and you must ensure that it remains
mounted. Use the address of a UCB, not a UCB copy.
(reg)–(0), (2-12)
specifies a register containing the UCB address for the device.
Chapter 1. Using the Volume Table of Contents
45
Using the VTOC
VSAMTYPE=KSDS or ESDS or RRDS or LDS or VRRDS
Specifies the type of VSAM data set.
Currently, only extended format VSAM data sets are supported.
If you specify VSAMTYPE, you must also specify VSAMFMT, VSAMCLLR,
VSAMSEC, and VSAMTRKS.
If you specify VSAMTYPE, the ERASE= parameter is ignored.
VSAMTYPE=KSDS
Specifies a VSAM key-sequenced data set.
VSAMTYPE=ESDS
Specifies a VSAM entry-sequenced data set.
VSAMTYPE=RRDS
Specifies a VSAM fixed-length relative record data set.
VSAMTYPE=LDS
Specifies a VSAM linear data set.
VSAMTYPE=VRRDS
Specifies a VSAM variable-length relative record data set.
VSAMFMT=EXTD or STD
Specifies the format of the data set.
VSAMFMT=EXTD
Specifies that this is an extended format data set.
VSAMFMT=STD
Specifies that this is not an extended format data set. If you specify STD
catalog services returns an error to partial release.
VSAMCLLR=VSAMCLSE or NOTVSAM
Specifies the caller.
VSAMCLLR=VSAMCLSE
Specifies that the caller is VSAM CLOSE.
VSAMCLLR=NOTVSAM
Specifies that the caller is other than VSAM CLOSE.
VSAMSEC=BYPASS or NOBYPASS
Specifies if security checking is to be performed
VSAMSEC=BYPASS
Specifies that security checking is not to be performed.
VSAMSEC=NOBYPASS
Specifies that security checking is to be performed.
VSAMTRKS=addr or (reg)
Specifies the address of a 4-byte area that is used to contain the number of
tracks released for this data set.
You must provide an address for VSAMTRKS only if you code VSAMTYPE.
addr—RX-type address, (reg)—(0), (2-12)
For a VSAM extended format data set, PARTREL returns a value which is
the sum of all the space released for all the parts of the data set.
PARTREL—List Form
The format of the list form of the PARTREL macro is:
46
z/OS DFSMSdfp Advanced Services
Using the VTOC
►►
PARTREL MF=L
label
►
,DSN=addr
,ERASE=
TEST
YES
NO
,MODE=
PGM
SUP
►
►
,TIOT=
ENQ
NOENQ
,VSAMTYPE=
KSDS
RRDS
LDS
VRRDS
,VSAMFMT=
EXTD
STD
►
►◄
,VSAMCLLR=
VSAMCLSE
NOTVSAM
,VSAMSEC=
BYPASS
NOBYPASS
,VSAMTRKS=addr
Restrictions:
1. The execute form of the UCB parameter cannot be specified on the list form.
2. The list form MODE parameter is for documentation only. The value of MODE
is as specified or defaulted on the execute form.
For an explanation of the parameters, see the execute form.
PARTREL–DSECT Form
The format of the DSECT form of the PARTREL macro is:
►►
PARTREL
MF=D
►◄
label
Description: The following example provides a description of the parameter list:
++PRLPLID
+PRLNGTH
+PRERRCDE
+*
+PRLFLAG
+PRLPGM
+PRLSUP
+PRLTIOT
+PRLNERAS
+PRLERASE
+PRLVCLOS
+PRLVCNV
+PRLBYPS
+PRLNBYPS
+PRLFLAG2
+PRLVKSDS
+PRLVESDS
+PRLVRRDS
+PRLVVRRD
+PRLVLDS
+PRLEXTD
+PRLSTD
+PRLTIOTX
+PRLRSVD
+PRLDSN
+PRLUCB
+PRLTRKS
DS
DS
DS
CL4
AL2
H
DS
XL1
EQU X’00’
EQU X’80’
EQU X’40’
EQU X’20’
EQU X’10’
EQU X’08’
EQU X’04’
EQU X’02’
EQU X’01’
DS XL1
EQU X’80’
EQU X’40’
EQU X’20’
EQU X’10’
EQU X’08’
EQU X’04’
EQU X’02’
EQU X’01’
DS XL2
DS A
DS A
DS A
EBCDIC ’PREL’ FOR PARTREL
LENGTH OF PARAMETER LIST
ERROR CODE RETURNED FROM
PARTIAL RELEASE
PARAMETER FLAG BYTE
MODE=PGM (PROBLEM PROGRAM)
MODE=SUP (SUPERVISOR STATE)
TIOT=NOENQ
ERASE=NO
ERASE=YES
VSAMCLLR=VSAMCLSE
VSAMCLLR=NOTVSAM
VSAMSEC=BYPASS
VSAMSEC=NOBYPASS
VSAMTYPE=KSDS
VSAMTYPE=ESDS
VSAMTYPE=RRDS
VSAMTYPE=VRRDS
VSAMTYPE=LDS
VSAMFMT=EXTD
VSAMFMT=STD
No ENQ TEST when TIOT=NOENQ is specified
RESERVED
DATA SET NAME POINTER
UCB POINTER
ADDRESS OF NUMBER OF TRACKS RETURNED
Chapter 1. Using the Volume Table of Contents
47
Using the VTOC
(ONLY VALID FOR VSAM REQUESTS)
+PRLCTGR DS F
CATALOG REASON CODE
+PRLEND
EQU *
END OF PARAMETER LIST
+PRLENGTH EQU PRLEND-PRELPL
LENGTH OF PARAMETER LIST
Return Codes From PARTREL
Control returns to the instruction following the last instruction generated by the
PARTREL macro. Register 15 contains the applicable PARTREL return code.
If an error occurs, PARTREL issues message IEC614I, consisting of failure-related
status information.
v If an error results from a CVAF function, the subfunction return code field
contains the CVAF return code, and the subfunction reason code field contains
the CVAF status code (CVSTAT).
v If an error results from the execution of an EXCP channel program, the
subfunction return code and reason code fields contain either:
– The ECB completion code and the CSW channel status, if the ECB completion
code is not X'41' and the channel status is not zero.
– The sense bytes (two) from the IOB, if the ECB completion code is X'41' and
there is no channel status.
v If an error results from an RACF invocation, the subfunction return code and
reason code fields contain the RACF return code and reason code.
Table 12 describes the conditions indicated by the PARTREL return code.
Exception: This is a cumulative list of DADSM partial release return codes. Some
of these codes might not apply to the PARTREL macro.
Table 12. DADSM PARTREL Return Codes
Return Code
Description
0(X'00')
2(X'02')
3(X'03')
4(X'04')
8(X'08')
Sucessful
Unable to find extent in format-1 or format-8 DSCB.
Exceeded maximum number of format-3 pointers in format-9 DSCB.
Unable to find extent in format-3 DSCB.
Either the required SYSZTIOT or SYSDSN ENQ failed, or an unrelated
DEB indicates that another DCB is open to the data set.
Invalid parameter list.
One of the following conditions occurred:
12(X'0C')
16(X'10')
v A permanent I/O error occurred.
v CVAF provided an unexpected return code.
v An installation exit rejected the request.
20(X'14')
24(X'18')
28(X'1C')
32(X'20')
36(X'24')
40(X'28')
44(X'2C')
48(X'30')
48
z/OS DFSMSdfp Advanced Services
v An I/O error occurred while the tracks to be released were being
erased (for ERASE-on-SCRATCH).
DSN, or DSN pointer is invalid.
Invalid UCB pointer.
Specified DSORG is not supported.
No room in the VTOC.
Invalid TIOT=NOENQ request; caller does not have exclusive use of
SYSDSN.
An error occurred while SMS was processing the request.
CLOSE is the caller, user rejected the partial release using the
PREEXIT routine.
An error occurred during conversion from CCHH to relative track
address.
Using the VTOC
Table 12. DADSM PARTREL Return Codes (continued)
Return Code
Description
52(X'34')
An error occurred during conversion from relative track address to
CCHH.
An error occurred during conversion from new extent descriptor table
to old extent descriptor table.
An error occurred during sort conversion of the extent descriptor
table.
An error occurred during conversion from format-7 to extent
descriptor table.
An error occurred during conversion from format-5 to extent
descriptor table.
Input DSCB is not a format-5 or a format-7 DSCB.
An error occurred during conversion from extent descriptor table to
format-7.
An error occurred during conversion from extent descriptor table to
format-5.
VSAM standard format data set incorrectly specified. If the data set is
VSAM, it must be extended format.
VSAMTRKS address parameter must be specified when VSAMTYPE is
specified.
The name of the specified VSAM data set is not a VSAM cluster data
component.
Catalog call to partial release failed.
Request was directed to a VSAM data set defined with guaranteed
space.
Unexpected reason code received back from a call to catalog services.
Unable to find enough F0s to complete the PARTREL request.
DAPCCHH passed is in cylinder-managed space, but is not on a
multi-cylinder unit boundary.
56(X'38')
60(X'3C')
64(X'40')
68(X'44')
72(X'48')
76(X'4C')
80(X'50')
84(X'54')
88(X'58')
92(X'5C')
96(X'60')
100(X'64')
104(X'68')
108X'6C')
112(X'70')
Creating (Allocating) a DASD Data Set Using REALLOC
The REALLOC macro builds a parameter list to allocate a new data set. You can
code the macro in the execute, DSECT, and list forms, but not in the standard
form. The calling program includes the following requirements and options:
v Must be APF authorized
v Must allocate the volume to this address space and must ensure it stays
mounted during the REALLOC function
v Must not hold any locks
v Can provide the associated parameter list and parameters in storage either above
or below 16MB
v Can use any storage key
v Can run in either supervisor or problem program state
v Can be in either 24 or 31-bit addressing mode
v Must note that REALLOC does not call RACF or catalog management
v Must note that REALLOC cannot create data sets on SMS-managed volumes
(SMS-managed data sets can be created through JCL or dynamic allocation)
v Must note that REALLOC cannot create PDSEs, HFS data sets, or extended
format data sets
v Requires the address of a UCB, not a UCB copy.
Chapter 1. Using the Volume Table of Contents
49
Using the VTOC
In addition, the calling program must provide the REALLOC macro with one or
more model DSCBs. You can use the OBTAIN macro to get the DSCBs from other
data sets and modify them for the request. DADSM uses these model DSCBs to
validate the allocation request, and to construct the DSCBs written to the VTOC for
the requested allocation.
The ALLOC parameter for the REALLOC macro defines the allocation request as
either absolute (ABS) or movable (MOV).
The requested data set's allocation is not sensitive to its placement on the volume.
This is not a reference to the format-1 DSCB bit DS1DSGU (unmovable bit), that
can be either on or off in an ALLOC=MOV request's partial DSCB. That is, the data
set can subsequently contain location-dependent information.
An absolute request is limited to a single volume with indexed VTOC support. An
absolute request provides a set of allocation parameters, a full format-1 or format-8
DSCB, and an optional format-3 DSCB, that describe the space and attributes of the
desired data set. An optional format-9 DSCBs can also be provided to pass
additional attributes:
v Support is provided for, but not limited to, data sets with a user label extent.
v The number of extents to be allocated, and their absolute placement on the
volume, are defined by the format-1 or format-8 DSCB and one (optional)
format-3 DSCB.
For an absolute request, the following checks are performed prior to writing the
passed DSCBs. The type of checks depend on the volume for which the REALLOC
macro is issued.
v For any volume, a passed DSCB format must not describe a format that is not
supported. The supported formats in REALLOC processing are 1, 3, 8, or 9.
v For an extended address volume, a passed format-1 DSCB must not describe
extents that contain cylinder addresses larger than 65,519.
v A passed format-1, format-3, or format-8 DSCB must not describe extents that
contain cylinder addresses larger than the highest cylinder address of the
volume.
v For an extended address volume, a passed format-8 DSCB must not describe a
data set organization that is not EAS eligible.
v For an extended address volume, a passed format-3 or format-8 DSCB must not
describe an extent that begins on cylinder address 65519 or lower and that ends
on cylinder address 65520 or higher.
v For a volume that is not an extended address volume, a passed format-8 or
format-9 DSCB is not allowed.
The partial DSCB (mapped by the IECPDSCB macro) consists of the first 106 bytes
of a format-1 DSCB followed by 10 bytes in which the primary space request and
number of directory blocks are specified.
A movable request is limited to a single volume with or without indexed VTOC
support. A movable request provides a set of allocation parameters and a partial
DSCB that describe the attributes of the desired data set:
v Absolute track allocated data sets are not supported.
v The maximum number of extents that can be allocated is determined by the data
set organization (PD1DSORG) and the system managed storage indicators
50
z/OS DFSMSdfp Advanced Services
Using the VTOC
(PD1SMSFG) bytes in the partial DSCB.If PD1DSORG indicates a VSAM data set
organization, the maximum number of extents is 7257 across multiple volumes,
123 on a single volume.
REALLOC–Execute Form
The format of the execute form of the REALLOC macro is:
►►
REALLOC MF=
label
(E,addr)
(E,(reg))
►
,ALLOC=
MOV
ABS
NON
►
►
,DSSIZE=
addr
(reg)
,F3DSCB=
addr
(reg)
,F9DSCB=
addr
(reg)
►
►
,MINAU=
addr
(reg)
,NUMF9=
number_dscbs
(reg)
,PDSCB=
addr
(reg)
►
►◄
,PDSDIR=
addr
(reg)
,UCB= (reg)
All parameters except ALLOC default to the current contents of the referenced
parameter list. The ALLOC parameter defaults to MOV.
MF=(E,addr) or (E,(reg))
Specifies the execute form of the macro and the address of a REALLOC
parameter list.
addr–RX-type address, (reg)—(0-12)
Specifies the address of the REALLOC parameter list.
ALLOC=ABS or MOV or NON
Specifies one of the following:
ALLOC=ABS
Specifies that the REALLOC request is for absolute extents.
ALLOC=MOV
Specifies that the REALLOC request is for a movable allocation.
ALLOC=MOV is the default.
ALLOC=NON
Specifies that the REALLOC request is to rebuild the free space chain on
an unindexed VTOC without allocating a data set. Expect a DADSM create
return code X'3D'.
DSSIZE=addr or (reg)
Specifies the size of the data set to be allocated in tracks. The DSSIZE
parameter is invalid for an ALLOC=ABS request.
addr–RX-type address
Specifies the address of a word that contains the data set size.
(reg)–(0), (2-12)
Specifies a register that contains the size of the data set.
Chapter 1. Using the Volume Table of Contents
51
Using the VTOC
Provide a value for DSSIZE for an ALLOC=MOV request.The PDPRIQTY field
of the partial DSCB is ignored.
REALLOC assumes that you have provided the value of DSSIZE in tracks even
if the PD1SCALO flag byte of the partial DSCB indicates a cylinder request
(X'C0'), or an average block request, (X'40').
If the PD1SCALO flag byte of the partial DSCB indicates a cylinder request
(X'C0'), or an average block with round request (X'41'), the value of DSSIZE is
rounded up to the next full cylinder.
F2DSCB
This parameter still is supported for assembly purposes, but the system no
longer supports it when your program executes. This because you can no
longer create indexed sequential data sets
F3DSCB=addr or (reg)
Specifies the in-storage address of a format-3 DSCB. This DSCB is used as a
model to construct the allocated data set's format-3 DSCB.
The F3DSCB parameter is invalid for an ALLOC=MOV request.
addr–RX-type address, (reg)–(0), (2-12)
Provide a value for F3DSCB in an ALLOC=ABS request when the DS1NOEPV
byte of the format-1 DSCB indicates more than three extents (or when the
DS1NOEPV byte indicates more than two extents and the DS1EXT1 extent type
indicator is X'40', a user label extent).
The REALLOC request is limited to a maximum of 16 extents when the
F3DSCB keyword is specified. No more than one format-3 DSCB can be
specified.
Enter a value of zero for the F3DSCB in an ALLOC=ABS request when the
DS1NOEPV byte of the format-1 DSCB indicates that there are less than four
extents (or when the DS1NOEPV byte indicates that there are less than three
extents and the DS1EXT1 extent type indicator is X'40', a user label extent).
F9DSCB=addr or (reg) or 0
Specifies the address of a caller-provided contiguous partial format-9 DSCB
data area where attribute information from it is to be used when creating a
format-9 DSCB. Specify this keyword if you wish to pass format-9 DSCB
attribute information to REALLOC processing. Only attribute information in
the format-9 DSCB will be processed. Format-9 DSCBs with a subtype field
with a value other than 1 will be ignored. See mapping macro, IECSDSL1. The
number of contiguous partial format-9 DSCBs defined in this data area is
defined in the NUMF9=number_dscb keyword or is defaulted to one.
addr-RX-type address
Specifies the address of the partial format-9 DSCB data area.
(reg)-(2-12)
Specifies a register containing the address of the partial format-9 DSCB
data area.
0 Specifies that you do not want to pass a partial format-9 DSCB data area.
MINAU=addr or (reg)
Specifies the size of the minimum allocation unit in tracks. All primary extents
for this data set are in multiples of this minimum allocation unit. This
minimum does not apply to subsequent extensions of the data set.
The MINAU parameter is invalid on an ALLOC=ABS request.
52
z/OS DFSMSdfp Advanced Services
Using the VTOC
addr–RX-type address
Specifies the address of a word containing the minimum allocation unit.
(reg)–(0), (2-12)
Specifies a register containing the minimum allocation unit.
The MINAU parameter has no effect on the requested allocation if:
v You provide a value of zero.
v The PD1SCALO flag byte of the partial DSCB indicates either a cylinder
request (X'C0') or an average block with round request (X'41').
Otherwise, the value of DSSIZE must be a multiple of the value of MINAU.
NUMF9=number_dscbs or (reg)
For REALLOC with F9DSCB requests, number_dscbs is an absolute expression
or (register) with a value between 0 and 255 that designates the number of
consecutive 140-byte partial format-9 DSCB areas that are provided in the
F9DSCB=addr. The system treats a value of 0 as a 1 when F9DSCB=addr is
specified. Format-9 DSCBs with a subtype field with a value other than 1 are
ignored.
PDSCB=addr or (reg)
Specifies the address of a partial DSCB (for ALLOC=MOV) or the in-storage
address of a full format-1 or format-8 DSCB (for ALLOC=ABS). This DSCB is
used as a model to construct the allocated data set's format-1 or format-8
DSCB.
addr–RX-type address, (reg)–(0), (2-12)
Provide a value for the PDSCB parameter and initialize the PD1FMTID field to
X'F1' for a format-1 DSCB or to X'F8' for a format-8 DSCB. However, the
PDSCB attribute information determines EAS eligibility and whether the actual
allocated DSCB allocated is a format-1 or format-8 DSCB.
PDSDIR=addr or (reg)
Specifies the number of 256-byte directory blocks for a partitioned data set
(PDS).
addr–RX-type address
Specifies an in-storage address of a full word containing the number of
256-byte PDS directory blocks.
(reg)–(0), (2-12)
Specifies a register containing the number of 256-byte PDS directory
blocks.
Provide a value for PDSDIR when partitioned organization is indicated:
v The DS1DSORG flag byte of the format-1 DSCB is X'02' (ALLOC=ABS).
v The PD1DSORG flag byte of the partial DSCB is X'02' (ALLOC=MOV).
For an ALLOC=MOV request, you can specify the value of PDSDIR in the
PDDIRQTY field of the partial DSCB. The PDDIRQTY field is used only if the
REALLOC parameter list value of PDSDIR is zero.
Do not specify a value for PDSDIR if a PDS is not indicated.
UCB=(reg)
Specifies the address of the UCB for the volume on which the data set is to be
allocated. The UCB address can be for a captured UCB, or for an actual UCB
above or below the 16MB line. For 31-bit callers, the high-order byte is part of
Chapter 1. Using the Volume Table of Contents
53
Using the VTOC
the UCB address and must be cleared to zeros if a 24-bit UCB address is being
passed. The volume must be mounted, and remain mounted. Use the address
of a UCB, not a UCB copy.
(reg)–(0), (2-12)
Specifies a register containing the UCB address for the device.
REALLOC–List Form
The format of the list form of the REALLOC macro follows. See the execute form
for an explanation of the parameters.
►►
REALLOC MF=L
►
label
,ALLOC=
MOV
ABS
,F3DSCB=addr
►
►◄
,F9DSCB=
addr
(reg)
,NUMF9=
number_dscbs
(reg)
,PDSCB=addr
Restrictions:
1. The execute form parameters DSSIZE, MINAU, PDSDIR, and UCB cannot be
specified on the list form.
2. The list form's ALLOC parameter affects the tests made by the REALLOC
macro during assembly, and the contents of the parameter list.
3. The value of ALLOC is as specified or defaulted on the execute form.
REALLOC–DSECT Form
The format of the DSECT form of the REALLOC macro is:
►►
REALLOC MF=D
►◄
label
REALLOC Parameter List
The parameter list for the DSECT form expansion is:
Table 13. REALLOC Parameter List
Offset
Length or
Bit Pattern
0(X'00')
Description
REALPL
DSECT name.
0(X'00')
4
RALPLID
EBCDIC "REAL" for "REALLOC"
4(X'04')
2
RALNGTH
Length of parameter list
6(X'06')
2
RAERRCDE
Error code from DADSM create
8(X'08')
1
RALFLAG
Flag byte
1... ....
RALABS
0 means ALLOC=MOV. 1 means ALLOC=ABS.
.1.. ....
RALVTOCE
VTOCENQD=YES
1
RALPFLGS
Processing flag byte.
9(X'09')
54
Field Name
z/OS DFSMSdfp Advanced Services
Using the VTOC
Table 13. REALLOC Parameter List (continued)
Offset
Length or
Bit Pattern
Field Name
Description
1... ....
RALDUMMY
Dummy REALLOC parameter list is passed. Only
the processing flag byte (byte 9), minimum
allocation unit (bytes 16-19), and UCB address
(bytes 24-27) are used. Ignore all other bytes and
use the values in the JFCB or Partial DSCB
interface as passed in register 0.
.1.. ....
RALTRKAL
Space must be allocated from track-managed
space.
..1. ....
RALEXREQ
The exact amount of space must be allocated.
Applicable to EAV. The request is to be allocated
using a combination of the track-managed and/or
the cylinder-managed spaces. If the exact space is
not available, then the request is failed.
...1 11..
*
Reserved.
.... ..11
RALEATTR
The extended attribute (EATTR=) value to be
used. Valid when RALDUMMY is set and when
the JFCB is passed in register 0.
v If 0, EATTR has not been specified. For VSAM
data sets, the default behavior is equivalent to
EATTR=OPT. For non-VSAM data sets the
default behavior is equivalent to EATTR=NO.
v If 1, EATTR=NO has been specified. The data
set cannot have extended attributes (format 8
and 9 DSCBs) or optionally reside in EAS.
v If 2, EATTR=OPT has been specified. The data
set can have extended attributes and optionally
reside in EAS. This is the default behavior for
VSAM data sets.
v If 3, Not Used, EATTR treated as not specified.
10(X'0A')
1
RALNUMF9
Number of contiguous partial format 9 DSCBs
that are located at the address in bytes 32-35. The
default is one.
11(X'0B')
1
12(X'0C')
4
RALDSSZ
Data set size
16(X'10')
4
RALMAU
Minimum allocation unit
20(X'14')
4
RALPDSCB
Address of partial DSCB
24(X'18')
4
RALUCB
Address of UCB
28(X'1C')
4
RALDQTY
PDS directory quantity
32(X'20')
4
RAL2DSCB
Address of format 2 DSCB. Mutually exclusive
with RAL9DSCB.
32(X'20')
4
RAL9DSCB
Contiguous partial format 9 DSCBs pointer.
RALNUMF9 defines the number of partial format
9 DSCBs. Format 9 DSCBs with a subtype field
with a value other than 1 are ignored. Only
format 9 DSCB attribute data in this model will
be used. Mutually exclusive with RAL2DSCB.
36(X'24')
4
RAL3DSCB
Address of format 3 DSCB
40(X'28')
0
RALEND
Byte after end of list
40
RALENGTH
Symbolic length of parameter list
Reserved
Return Codes from REALLOC
Control returns to the instruction following the instructions generated by the
REALLOC macro. Register 15 contains the applicable REALLOC return code as
shown in Table 14 on page 56.
Chapter 1. Using the Volume Table of Contents
55
Using the VTOC
REALLOC returns 4 bytes of diagnostic information in register 0. See z/OS
DFSMSdfp Diagnosis.
If an error occurs, REALLOC issues message IEC614I, consisting of failure-related
status information. See Table 14 for descriptions of the conditions indicated by the
REALLOC return code.
Exception: This is a cumulative list of DADSM create return codes. Some of these
codes might not apply to the REALLOC macro.
Table 14. DADSM CREATE Return Codes
Return Code
Description
00(X'00')
If the 4 bytes of diagnostic information returned in register 0 are all
zeros, this indicates successful data set creation. If they are nonzero,
see the DADSM/CVAF Diagnostic Aids section of z/OS DFSMSdfp
Diagnosis to determine the failure-related conditions.
Duplicate data set name.
No room in VTOC or VTOC index.
Permanent I/O error or CVAF error.
Requested absolute track not available.
Requested quantity not available.
Average record length exceeds 65,535 bytes.
ISAM is no longer supported and the request has been failed.
SMS configuration parmlib field USESLV was set to NO. The request
to allocate on a volume with more than 65,520 cylinders is not
allowed.
The create request specified DACEXREQ, but the exact amount of
space could not be returned. Because the exact amount was required,
no space is returned.
Invalid DADSM REALLOC parameter list.
Invalid JFCB, partial DSCB pointer, or ineligible DSORG specified with
F8 ID in the DSCB for an EAS request on EAV.
Not enough space on volume for directory.
REALLOC ALLOC=ABS is not supported on unindexed VTOCs.
REALLOC ALLOC=NON requested the free space chain to be rebuilt.
The data set was not created.
Invalid user label request.
Invalid UCB pointer. Requires the address of a UCB, not a UCB copy.
VSE VTOC cannot be converted to an unindexed VTOC.
No space parameter given for a new data set or zero space requested
at absolute track zero.
Invalid space subparameter.
ABSTR request.
User labels not supported.
Invalid combination of DSSIZE and MINAU in REALLOC parameter.
DSSIZE not a multiple of MINAU.
Directory space requested is larger than primary space.
Invalid FMT3 DSCB pointer.
EAV extent above 65520 cylinders is not an even integral of the
multicylinder unit.
Overlapping extents in the VTOC.
DADSM CREATE terminated because of possible VTOC errors.
Allocation terminated because of VSE stacked pack format.
RACDEF failed, data set already defined.
User not authorized to define data set.
Installation exit rejected this request with return code 8.
04(X'04')
08(X'08')
12(X'0C')
16(X'10')
20(X'14')
24(X'18')
28(X'1C')
32(X'20')
40(X'28')
48(X'30')
52(X'34')
56(X'38')
60(X'3C')
61(X'3D')
64(X'40')
68(X'44')
72(X'48')
76(X'4C')
104(X'68')
108(X'6C')
116(X'74')
120(X'78')
124(X'7C')
128(X'80')
136(X'88')
144(X'90')
148(X'94')
156(X'9C')
164(X'A4')
168(X'A8')
172(X'AC')
176(X'B0')
56
z/OS DFSMSdfp Advanced Services
Using the VTOC
Table 14. DADSM CREATE Return Codes (continued)
Return Code
Description
180(X'B4')
184(X'B8')
188(X'BC')
192(X'C0')
196(X'C4')
Installation exit rejected the request with return code 4.
RACF define with modeling specified and model not found.
Invalid FMT2 DSCB pointer.
Requested data set creation was not allowed by SMS.
Requested data set creation was not possible. Register 0 contains
additional diagnostic information.
The PDSE directory could not be built.
VTOC ENQ related failure.
I/O error occurred during the allocation of a data set. The data set
will be deleted.
Request failed due to a presence of split cylinder data sets on the
volumes.
For this type of data set, the primary quantity requested cannot exceed
65,535 tracks.
Data set could not be created DSNTYPE=LARGE not valid for this
data set.
VTOC conversion failed because the VTOC was full.
200(X'C8')
204(X'CC')
208(X'D0')
212(X'D4')
216(X'D8')
217(X'D9')
220(X'DC')
Accessing the VTOC with CVAF Macros
The common VTOC access facility (CVAF) macros and tasks discussed in this
section consist of the following:
v CVAFDIR directly accesses one or more DSCBs.
v CVAFDSM obtains volume free space information.
v CVAFFILT reads sets of DSCBs for one or more DASD data sets.
v CVAFSEQ retrieves the following:
– Data set names from an active VTOC index
– DSCBs in physical-sequential order
– DSCBs in data set name order (index required).
v CVAFTST determines if a DASD volume has an active VTOC index.
“Coding CVAF VTOC Access Macros” on page 75, contains descriptions of these
macros and examples of their use.
When calling CVAF, your program can be in either 24-bit or 31-bit addressing
mode. If it is in 31-bit mode, the control blocks shown in Figure 7 on page 70
might reside above the 16 MB line. All these areas must be accessible in your
program's storage key.
Note: You must supply a UCB address that matches the caller's AMODE. That is,
AMODE=24 requires a 24 bit UCB address, while AMODE=31 requires a 31 bit
UCB address.
Serializing and Updating
CVAF requires that you provide all necessary system resource serialization for your
request. You can ensure the integrity of multiple data elements (sets of DSCBs or
VIRs) returned by CVAF only if you adequately serialize system resources and
avoid multiple CVAFFILT requests for a set of DSCBs or VIRs. Weigh possible
system performance loss because of serialization against the potential loss of data
integrity.
Chapter 1. Using the Volume Table of Contents
57
Using the VTOC
Updating without adequate serialization might compromise the integrity of the
volume's VTOC, the VTOC index, or any associated data set.
CVAF only complies with requests to modify the volume's VTOC or index from
authorized programs.
CVAF assumes that an authorized program holds an exclusive RESERVE (or ENQ)
on the qname (major name) of SYSVTOC, and the rname (minor name) of the
volume's serial number, with the scope of SYSTEMS. This RESERVE can be made
more efficient if Global Resource Serialization or a functional equivalent is active.
The SYSVTOC qname does not serialize access to the format-1 or the format-8
DSCB for a data set. You can provide serialization by allocating the data set with
disposition OLD, MOD, or NEW (not SHR). This causes the proper ENQ, ensuring
that no other job can update that data set's format-1 or format-8 DSCB.
If your program holds the enqueue for the SYSVTOC resource, then no other
program can later start and complete a DADSM request. This includes extending
or creating a data set on that volume in your own address space. If you try to
extend a data set under the same task that holds SYSVTOC, it will be abnormally
terminated. If a different task requests SYSVTOC, that task will wait. If your
program then requests a resource that is held by that task, the two tasks will be in
a deadlock. To prevent deadlocks between tasks in the same address space when
either of the tasks has previously enqueued on SYSVTOC, the secondary caller of
CVAF must ensure the enqueue bit is on (CV3ENQD) in the CVPL. Other options
to get around this limitation are either:
v Allocating a data set so that it does not require secondary extents.
v Requesting that the output data set be on a volume other than the one where
the application holds enqueue for the SYSVTOC resource.
Identifying the Volume
If authorized, you can identify the volume to the CVAFDIR, CVAFDSM,
CVAFFILT, and CVAFSEQ macros by specifying the address of the UCB. These
macros do not accept the address of a UCB copy. If your program is not
authorized, specify the address of a SAM or EXCP DEB opened to the volume's
VTOC.
The data extent block (DEB) can be obtained by opening a DCB for INPUT, using
the RDJFCB and OPEN TYPE=J macros. (After issuing an OPEN TYPE=J macro,
the DCB's DCBDEBA field contains the DEB's address.) The DCB's DDNAME must
identify a DD statement allocated to the unit whose VTOC is to be accessed. Once
your program issues the RDJFCB macro, it must initialize the JFCBDSNM field
with the data set name of the format-4 DSCB: 44 bytes of X'04'. The RDJFCB macro
is described under “RDJFCB Macro Specification” on page 287; the OPEN macro is
described under “OPEN - Initialize Data Control Block for Processing the JFCB” on
page 302. For an extended address volume the DCB macro must point to a DCBE
where the EADSCB=OK keyword is specified. If you do not code this option, the
OPEN function will issue ABEND 113-48 and message IEC142I.
If a CVAF macro call specifies IOAREA=KEEP, a subsequent CVAF call using a
different CVAF parameter list (CVPL) might omit the UCB and DEB keywords and
supply the IOAREA address from the other CVPL by using the IOAREA keyword.
58
z/OS DFSMSdfp Advanced Services
Using the VTOC
Generating a CVPL (CVAF Parameter List)
The CVAFDIR, CVAFDSM, CVAFFILT, and CVAFSEQ macros use the CVPL to
pass parameters to CVAF. The CVAFTST macro expands to provide its only
parameter (UCB address) in register 1, and calls the applicable CVAF module.
CVAF returns information related to the CVAF request in the CVPL. The CVAFTST
macro will accept the address of a UCB or UCB copy. Unauthorized programs can
get a copy of the UCB by using the UCBSCAN macro and specifying the COPY,
UCBAREA, CMXTAREA, and DCEAREA keywords. The UCB copy, including the
extension, must be below the 16MB line and on a word boundary. Data accessed
with the DCEAREA can be above the 16MB line. Refer to z/OS HCD Planning for
details.
Specifying the CVAFDIR, CVAFDSM, CVAFFILT, or CVAFSEQ macro with MF=L
or MF=I (the default) as a subparameter generates a CVPL. Upon return the
CV1IVT bit in the CVPL indicates whether the accessed VTOC was indexed or
nonindexed. If an error occurs, the CVSTAT field contains feedback data. The
CVAF I/O area address is returned in the CVIOAR field and the CVAF filter save
area address is returned in the CVFSA field. To use the generated CVPL to execute
a different function than was originally specified, use the MF=E keyword.
To specify a CVAF filter request, use a CVPL generated by the CVAFFILT macro.
The CVAFFILT macro generates a CVPL 4 bytes longer (total length = X'44') than
that generated by the other CVAF macros (total length = X'40'). CVAFFILT request
need a longer parm list to accommodate one extra file.
v To get the longer parameter list (X'44' bytes), specify CVPLFSA=YES on the
inclusion of the ICVAFPL mapping macro.
v To get the shorter parameter list (X'40' bytes), specify the CVPLX=YES on the
inclusion of the ICVAFPL mapping macro.
The ICVAFPL macro maps the CVPL. The format of the CVPL is shown in
Table 15.
Note: The area starting at CVCTAR5 is generated only when the CVPLX=YES
macro variable is specified on the invocation of ICVAFPL.
Table 15. CVAF Parameter List - ICVAFPL
Offset
Type
Length
Name
Description
0(X'00')
STRUCTURE
100
CVPL
CVAF parameter list
0(X'00')
CHARACTER
4
CVLBL
EBCDIC 'CVPL'
4(X'04')
SIGNED
2
CVLTH
Length of CVPL
6(X'06')
BIT(8)
1
CVFCTN
Function byte (see values below)
7(X'07')
UNSIGNED
1
CVSTAT
Status information (see values below)
8(X'08')
BIT(8)
1
CVFL1
First flag byte
1... ....
CV1IVT
Indexed VTOC accessed
.1.. ....
CV1IOAR
IOAREA=KEEP
..1. ....
CV1PGM
BRANCH=(YES,PGM)
...1 ....
CV1MRCDS
MAPRCDS=YES
.... 1...
CV1IRCDS
IXRCDS=KEEP
.... .111
CV1MAP
Map bits (see next three bits)
.... .1..
CV1MAPIX
MAP=INDEX
Chapter 1. Using the Volume Table of Contents
59
Using the VTOC
Table 15. CVAF Parameter List - ICVAFPL (continued)
Offset
9(X'09')
10(X'0A')
11(X'0B')
|
|
Type
Name
Description
.... ..1.
CV1MAPVT
MAP=VTOC
.... ...1
CV1MAPVL
MAP=VOLUME
CVFL2
Second flag byte
1... ....
CV2HIVIE
HIVIER=YES
.1.. ....
CV2VRF
VRF data exists
..1. ....
CV2CNT
COUNT=YES
...1 ....
CV2RCVR
RECOVER=YES
.... 1...
CV2SRCH
SEARCH=YES
.... .1..
CV2DSNLY
DSNONLY=YES
.... ..1.
CV2VER
VERIFY=YES
.... ...1
CV2NLEVL
Output - new highest level VIER created
CVFL3
Third flag byte
1... ....
CV3FILT
FLTAREA=KEEP
.1.. ....
CV3IXERR
Index error found
..1. ....
CV3PTR31
Address words in CVPL are valid in AMODE
31
...1 ....
CV3AVT
Support bypass write inhibit error.
.... 1...
CV3ENQD
CVAF caller has serialized with another task
that has reserved the VTOC
.... .1..
CV3NOPIN
Caller requested no UCBPIN
.... ..1.
CV3HLIXP
Higher level IX pruning done
.... ...1
CV3RTA4B
CVAFDSM RTA4BYTE=YES
CVFL4
Fourth flag byte
1... ....
CV4UCBCA
UCB has been captured
.1.. ....
CV4OBTRQ
Request came from OBTAIN
..1. ....
CV4NMHID
Data set name hiding for authorized caller.
...1 ....
CV4EADOK
EADSCB=OK specified
.... 1...
CV4MULTD
Processing of multiple DSCBs on CVAFDIR is
requested (MULTIPLEDSCBS=YES)
.... .1..
CV4NOQUE
Do not queue the OBTAIN I/O
.... ..1.
CV4VALID
Validate fields when CVAFDIR
ACCESS=WRITE
.... ...x
CV4RSVD
Reserved
BIT(8)
BIT(8)
BIT(8)
Length
1
1
1
12(X'0C')
ADDRESS
4
CVUCB
UCB address
16(X'10')
ADDRESS
4
CVDSN
Data set name address
16(X'10')
ADDRESS
4
CVFCL
Filter criteria list address
20(X'14')
ADDRESS
4
CVBUFL
Buffer list address
24(X'18')
ADDRESS
4
CVIRCDS
Index VIR's buffer list pointer
28(X'1C')
ADDRESS
4
CVMRCDS
MAP VIR's buffer list pointer
32(X'20')
ADDRESS
4
CVIOAR
I/O area address
60
z/OS DFSMSdfp Advanced Services
Using the VTOC
Table 15. CVAF Parameter List - ICVAFPL (continued)
Offset
Type
Length
Name
Description
36(X'24')
ADDRESS
4
CVDEB
DEB address
40(X'28')
ADDRESS
4
CVARG
Argument address
44(X'2C')
ADDRESS
4
CVSPACE
Space parameter list address
48(X'30')
ADDRESS
4
CVEXTS
Extent table address
52(X'34')
ADDRESS
4
CVBUFL2
New VRF VIXM Buffer list pointer
56(X'38')
ADDRESS
4
CVVRFDA
VRF data address
60(X'3C')
ADDRESS
4
CVCTAR
Count area address
64(X'40')
ADDRESS
4
CVFSA
Filter save area address
68(X'44')
ADDRESS
4
CVCTAR5
CCHHR AREA RETURN ADDRESS
72(X'48')
UNSIGNED
1
CVNMDSCB
NUM OF DSCBs
73(X'49')
CHARACTER
4
CVCLID
ID of CVAFDIR WRITE caller
76(X'4C')
CHARACTER
23
*
Reserved
The possible contents of the CVFCTN field in the CVPL and their meanings are as
follows:
Table 16. CVFCTN Field of CVPL—Contents and Definitions
Value
Name
Description
X'01'
X'02'
X'03'
X'04'
X'05'
X'06'
X'07'
X'08'
X'09'
X'0A'
X'0E'
X'0F'
X'10'
X'AA'
CVDIRD
CVDIWR
CVDIRLS
CVSEQGT
CVSEQGTE
CVDMIXA
CVDMIXD
CVDMALC
CVDMRLS
CVDMMAP
CVFIRD
CVFIRES
CVFIRLS
CVDMMAPX
CVAFDIR
CVAFDIR
CVAFDIR
CVAFSEQ
CVAFSEQ
CVAFDSM
CVAFDSM
CVAFDSM
CVAFDSM
CVAFDSM
CVAFFILT
CVAFFILT
CVAFFILT
CVAFDSM
ACCESS=READ
ACCESS=WRITE
ACCESS=RLSE
ACCESS=GT
ACCESS=GTEQ
ACCESS=IXADD
ACCESS=IXDLT
ACCESS=ALLOC
ACCESS=RLSE
ACCESS=MAPDATA
ACCESS=READ
ACCESS=RESUME
ACCESS=RLSE
ACCESS=MAPDATA RTA4BYTE=YES
Using Buffer Lists
A buffer list consists of one or more chained control blocks, each with a header
and buffer list entries, obtained and initialized by your program before calling
CVAF. The header indicates whether the buffer list is for DSCBs. The entries point
to and describe the buffers. You can create buffer lists in two ways:
v Directly, when you fill in the arguments and buffer addresses of DSCBs to be
read or written
v Indirectly (by CVAF), when you code the IXRCDS=KEEP and/or
MAPRCDS=YES keywords.
The ICVAFBFL macro maps CVAF buffer lists. Table 17 on page 62 shows the
format of a buffer list header. Table 18 on page 63 shows the format of a buffer list
entry.
Chapter 1. Using the Volume Table of Contents
61
Using the VTOC
Buffer List Header
The buffer list header indicates whether the buffer list describes buffers for DSCBs.
The DSCB bit must be set to 1 and the VIR bit to zero for CVAF to process a
request to read or write a DSCB. Provide buffer lists and buffers in your program's
protect key. CVAF uses the protect key and subpool fields in the buffer list header
only if you code ACCESS=RLSE.
Each buffer list header contains a count of the number of entries in the buffer list
that directly follows the header.
The forward chain address chains buffer lists together. The format of the buffer list
header is shown in Table 17.
Table 17. Format of a Buffer List Header
Length or Bit
Pattern
Name
Description
8
1
1
xxxx . . . .
....1...
.....1..
......1.
BFLHDR
BFLHNOE
BFLHFL
BFLHKEY
BFLHVIR
BFLHDSCB
BFLHWREV
2 (X'02')
. . . . . . .x
1
BFLHNOEN
3 (X'03')
1
BFLHSP
4 (X'04')
4
BFLHFCHN
Buffer list header.
Number of entries.
Key and flag byte.
Protect key of buffer list and buffers.
Reserved.
Buffer list entries describe DSCBs.
Write multiple DSCBs in reverse
order.
Reserved.
Number of entries needed to read all
DSCBs describing the DSN. Set by
CVAFDIR READ when processing a
READ of a format-1 or format-8
DSCB. Applicable to all volume types
and set regardless of the value
provided in BFLHNOE.
Identifies the subpool of buffer list
and buffers.
Forward chain address of next buffer
list.
Offset
0 (X'00')
0 (X'00')
1 (X'01')
Buffer List Entry
A buffer list contains one or more entries in contiguous storage. Each entry
provides the buffer address, the length of the DSCB buffer, the argument, and
indicates whether the argument is an RBA, a TTR, or a CCHHR. The fields and bit
uses are listed below.
v For a DSCB buffer, the RBA bit must be 0, and either the TTR or CCHHR bits
must be set to 1 (they must not both be 1).
v The BFLESKIP bit causes an entry to be ignored.
v The BFLEIOER bit is an output indicator from CVAF that indicates an I/O error
occurred during reading or writing of the DSCB.
v The BFLELTH field is the length of the buffer; for a DSCB buffer, the length
must be 96 or 140.
v The BFLEARG field is the argument (address) of the DSCB. Specify the format of
the 5-byte field by setting the BFLECHR, or BFLETTR bit to 1. The respective
BFLEARG values and formats are as follows:
62
z/OS DFSMSdfp Advanced Services
Using the VTOC
Value
CCHHR
TTR
Format
5-byte CCHHR
0TTR0
The values for BFLEARG depend on the variables associated with a given request.
These are described in the following request-oriented topics.
The format of the buffer list entry is shown in Table 18.
Table 18. Format of a Buffer List Entry
Length or Bit
Pattern
Name
Description
0 (X'00')
0 (X'00')
12
1
100 . . . . .
010 . . . . .
001 . . . . .
...1....
....1...
.....1..
......1.
.......1
BFLE
BFLEFL
BFLERBA
BFLECHR
BFLETTR
BFLEAUPD
BFLEMOD
BFLESKIP
BFLEIOER
BFLENOVR
1 (X'01')
1
1.......
BFLEFLG2
BFLENVER
.1......
BFLEVLER
1
5
3
4
4
BFLELTH
BFLEARG
BFLEATTR
BFLEARBA
BFLEBUF
Buffer list entry.
Flag byte.
Argument is RBA.
Argument is CCHHR.
Argument is TTR.
CVAF updated argument field.
Data in buffer has been modified.
Skip this entry.
I/O error.
If using CVAFDIR to write a 96-byte
DSCB, bypass comparing the DSCB
key to the data set name.
Flag byte 2.
When using CVAFDIR to write
multiple DSCBs and this flag is set,
CVAF will not verify that the existing
DSCB is format 0 prior to writing this
DSCB. This overrides VERIFY=YES on
CVAFDIR (CV2VER) for this buffer list
entry.
This buffer cannot be written due to an
error in validation. (VALIDATE=YES)
on CVAFDIR write.
Reserved.
Length of DSCB buffer.
Argument of DSCB.
TTR of DSCB.
Reserved.
Buffer address.
Offset
|
|
|
|
2
3
4
4
8
(X'02')
(X'03')
(X'04')
(X'04')
(X'08')
Using Macro ICVEDT02 to Map the Extents Area
The ICVEDT02 mapping macro is used to map the extent area when you use the
CVAFDSM macro and specify RTA4BYTE=YES for indexed VTOCs or nonindexed
VTOCs.
The format of the ICVEDT02 mapping macro follows.
Table 19. Format of ICVEDT02 Mapping Macro
Offset
Bytes
Name
Description
0 (X'00')
8
DT2X7EYE
Identifier=“ICVEDT02”
Chapter 1. Using the Volume Table of Contents
63
Using the VTOC
Table 19. Format of ICVEDT02 Mapping Macro (continued)
Offset
Bytes
Name
Description
8 (X'08')
12 (X'0C')
13 (X'0D')
14 (X'0E')
16 (X'10')
4
1
1
2
5
DT2X7LEN
DT2X7LEV
DT2X7FLG
DT2X7NF0
DT2X7CSR
21 (X'15')
24 (X'18')
3
4
DT2X7RES
DT2X7RTA
28 (X'1C')
32 (X'20')
36 (X'24')
-
4
4
8
4
4
DT2X7RE2
DT2X7ENT
DT2ENTRY
DT2RTAST
DT2RTAED
Length of ICVEDT02.
Level number.
Flag byte.
Number of format-0 DSCBs created.
CCHHR cursor field. Used by the system.
Initialized to zero by caller—then do NOT modify.
Reserved.
Relative Track Address (RTA) cursor field. Used by
the system. Initialized to zero by caller—then do
NOT modify.
Reserved.
Number of extent descriptor entries.
Extent descriptor array.
One entry for each extent.
RTA of start of extent
RTA+1 of end of extent
Accessing the DSCB Directly
The CVAFDIR macro can be used to read or write one or more DSCBs and is
described in “CVAFDIR Macro Overview and Specification” on page 75. After a
CVAFDIR call, you can test the CV1IVT bit in the CVPL to determine whether the
VTOC is indexed or nonindexed.
If the first buffer is 96 bytes, CVAF issues a channel program to verify that the key
in the DSCB matches the 44-byte data set name you entered, unless the operation
is a write and the BFLENOVR bit is on.
If the first buffer is for a 96-byte write and the BFLENOVR bit in the BFLEFL is set
to 1, CVAF skips the key verification, improving performance. If you are not
certain that the data set name you provide is correct, set the BFLENOVR bit to 0. If
the BFLENOVR bit is set to 0, CVAF does not execute the write unless the keys
match.
If CVAF is performing key verification, and the DSCB key does not match the data
set name you supply, CVAF ignores any specified BFLEARG and writes the first
DSCB using the rules described in the following section, “Specifying a Data Set
Name to Read or Write a DSCB.”
Specifying a Data Set Name to Read or Write a DSCB
To read or write one or more DSCBs by specifying only the data set name (that is,
BFLEARG is zero), specify either ACCESS=READ or ACCESS=WRITE.
Specify the address of the data set name in the DSN keyword. Specify the address
of the buffer list in the BUFLIST keyword. Each of these areas and the associated
buffers must be in your program's protect key.
The buffer list must contain at least one buffer list entry with the skip bit off and a
pointer to a 96-byte first buffer. Do not use a 140-byte buffer as the first buffer. You
can chain buffer list headers together, but at this time, CVAF only uses the first
buffer list.
64
z/OS DFSMSdfp Advanced Services
Using the VTOC
For an indexed VTOC, CVAF searches the index for the data set name. If the data
set name is found, the DSCB argument is put into the buffer list entry and used to
read or write the DSCB. If the data set name cannot be found in the index, CVAF
performs a key search of the VTOC.
For a nonindexed VTOC, CVAF uses a channel program to perform a key search of
the VTOC to locate the data set name and read or write the DSCBs. If the data set
name is found, CVAF puts the DSCB argument into the buffer list entry.
The DSCB argument returned in the buffer list entry is in the format determined
by the BFLECHR or BFLETTR bits in the buffer list entry.
If CVAF does not find the data set name in the VTOC, a return code of 4 is
indicated in register 15, and an error code of 1 in the CVSTAT field.
For CVAF calls that pass a data set name, a CVAFDIR request will fail if the
EADSCB=OK indicator is not set and the DSCB associated with this data set name
is a format-8 DSCB. CVAF return code of 4 with a CVAF status code (CVSTAT) of
STAT082 will be set.
If you use CVAFDIR MULTIPLEDSCBS=YES ACCESS=READ, all DSCBs associated
with this data set name are read and returned in the buffer list buffer (BFLEBUF)
for entries without the skip bit on in logical VTOC order. The associated address of
each DSCB is put in the corresponding BFLEARG field. The total number of
DSCBs associated with this data set name is also returned in the BFLHNOEN field
of the buffer list header. If there are not enough buffers to house all the DSCBs
associated with this data set name, only those DSCBs that have BFLEs are
processed. The buffer list header field BFLHNOEN will then have a number
greater than the BFLHNOE field.
If you use CVAFDIR MULTIPLEDSCBS=YES ACCESS=WRITE, all BFLEs without
the skip bit are used to write all DSCBs with one call. BFLARG must be correct for
all entries (except the first 96-byte DSCB) and BFLEBUF must point to the correct
corresponding DSCB to be written.
Specifying the DSCB Location
To read or write one or more DSCBs by specifying the DSCB's location (that is,
BFLEARG), specify either ACCESS=READ or ACCESS=WRITE.
Specify the address of the data set name in the DSN keyword and the address of
the buffer list in the BUFLIST keyword. Each of these areas and the associated
buffers must be in your program's protect key.
The buffer list must have at least one buffer list entry with the skip bit off and a
pointer to a 96-byte or 140-byte buffer. You can chain buffer lists together, but at
this time CVAF uses only the first buffer list.
If the first buffer is for a 140-byte read or write, CVAF issues a channel program to
read or write the DSCB at the location specified in the buffer list entry. CVAF
ignores the specified data set name. If you specify VERIFY=YES, CVAF verifies
that the designated DSCB is a format-0 DSCB before issuing the write channel
program.
Chapter 1. Using the Volume Table of Contents
65
Using the VTOC
For CVAF calls that specify the DSCB location, a CVAFDIR request will fail if the
EADSCB=OK indicator is not set and the DSCB associated with this location is a
format-8 DSCB. CVAF return code of 4 with a CVAF status code (CVSTAT) of
STAT082 will be set.
If you use CVAFDIR MULTIPLEDSCBS=YES ACCESS=READ, all DSCBs associated
with the data set whose format-1 or format-8 DSCB is pointed to by the BFLEARG
of the first BFLE entry are read and returned in the buffer list buffer (BFLEBUF)
for entries without the skip bit on in logical VTOC order. The associated address of
each DSCB is put in the corresponding BFLEARG field. The total number of
DSCBs associated with this data set is also returned in the BFLHNOEN field of the
buffer list header. If there are not enough buffers to house all the DSCBs associated
with this data set name, only those DSCBs that have BFLEs are processed. The
buffer list header field BFLHNOEN will then have a number greater than the
BFLHNOE field.
If you use CVAFDIR MULTIPLEDSCBS=YES ACCESS=WRITE, all BFLEs without
the skip bit are used to write all DSCBs with one call. BFLARG must be correct for
all entries and BFLEBUF must point to the correct corresponding DSCB to be
written.
Releasing Buffers and Buffer Lists Obtained by CVAF
You can release buffers and buffer lists acquired by CVAF in the following ways:
v Issue a CVAF call with ACCESS=RLSE, and specify a buffer list address with the
BUFLIST keyword.
v Free a MAP records buffer list by coding MAPRCDS=NO or
MAPRCDS=(NO,addr) and specifying any ACCESS.
v Free an index records buffer list by coding IXRCDS=NOKEEP or
IXRCDS=(NOKEEP,addr) and specifying any ACCESS.
CVAF frees all eligible buffers and any buffer lists that become empty. Eligible
buffers are those pointed to by buffer list entries with the skip bit off. CVAF frees a
buffer list if none of its buffer list entries have the skip bit on. If buffer lists are
chained together, CVAF checks and frees all appropriate buffer lists. Do not request
CVAF to release the same buffer list twice by specifying its address in more than
one place.
Accessing DSNs or DSCBs in Sequential Order
You can use the CVAFSEQ macro to request the return of information about the
data sets:
v DSCBs in indexed (data set name) order (either format-1 and format-8 DSCBs or
a format-4 DSCB)
v One or more DSCBs in physical-sequential order. (If you are unauthorized, you
can request only one DSCB.)
v The next data set name in the index.
CVAF reads the DSCBs into buffers identified by the BUFLIST keyword. See
“CVAFSEQ Macro Overview and Specification” on page 121 for additional
information about the macro.
Use the buffer list to specify the argument of each DSCB to be read. For indexed
access, request 96-byte DSCBs in the buffer list. For physical-sequential access,
request 140-byte DSCBs.
66
z/OS DFSMSdfp Advanced Services
Using the VTOC
If you select indexed order, CVAF returns each format-1, format-4, or format-8
DSCB pointed to by the index. To return only the data set names in the index (not
the DSCBs), specify DSNONLY=YES. CVAF updates the DSN area specified in the
CVAFSEQ macro with the data set name of each DSCB read, every time you issue
CVAFSEQ. CVAF also returns the CCHHR of the DSCB in the argument area
supplied with the ARG keyword.
Note: The returned DSCB from CVAFSEQ always includes the key portion of the
DSCB when the supplied length is 140 bytes for the buffer (field BFLELTH). The
mapping for structure IECSDSF4 in macro IECSDSL1, however, does not include
the key portion of the DSCB. Therefore, if you use the format-4 DSCB fields
defined in this structure (all fields starting with DS4), you must adjust the starting
point of the first field in the IECSDSF4 structure to correspond to 44 bytes into the
returned buffer.
For indexed access, a CVAFSEQ request will fail if the EADSCB=OK indicator is
not set and the DSCB attempted to be read is a format-8 DSCB. CVAF return code
of 4 with a CVAF status code (CVSTAT) of STAT082 will be set.
Initiating Indexed Access (DSN Order)
To initiate indexed access (DSN order), either supply 44 bytes of binary zeros in
the DSN area (to indicate the first data set name in the index) or specify the data
set name that is the starting point for the index search.
The name returned in the DSN area is equal to or greater than the DSN supplied,
depending on the ACCESS keyword selection.
If you specify DSNONLY=NO, CVAF returns the DSCB and argument using the
buffer list provided with the BUFLIST keyword. CVAF uses the first entry in the
buffer list with the skip bit set to 0 and a nonzero buffer address. You can specify
the argument format by setting either the TTR or CCHHR bit in the buffer list
entry to 1. If neither bit is set, CVAF returns a CCHHR argument. For indexed
access, the DSCB size in the buffer list entry must be 96 bytes.
If you specify DSNONLY=YES, specify the CCHHR argument in the ARG area.
The data set name of the format-4 DSCB is in the index and CVAF might return its
name (44 bytes of X'04'). The format-4 DSCB's name is likely to be the first data set
name in the VTOC index.
Initiating Physical-Sequential Access
To initiate physical-sequential access, either specify DSN=0, or do not specify the
DSN parameter at all. To begin the read, initialize the argument field in the first
buffer list entry to zero or to the argument of the DSCB. If the argument is zero,
CVAF uses the argument of the start of the VTOC.
The ACCESS keyword determines whether CVAF reads the DSCB whose argument
is supplied or the DSCB following it. For example, to read the first DSCB (the
format-4 DSCB) in the VTOC, you can set the BFLEARG in the first buffer list
entry to zero and specify ACCESS=GTEQ in the CVAFSEQ macro. If you
subsequently specify ACCESS=GT, CVAF reads the second DSCB (the first format-5
DSCB). Set the DSCB size to 140 in buffer list entries.
If your program is authorized, CVAF reads as many DSCBs as there are entries in
the buffer list for a single CVAF call; if it is not authorized, CVAF reads only one
DSCB.
Chapter 1. Using the Volume Table of Contents
67
Using the VTOC
CVAF uses one buffer list and does not inspect a second buffer list chained from
the first. If your program is authorized, CVAF uses all entries in the buffer list; if it
is not authorized, CVAF uses only the first entry. CVAF does not inspect the skip
bit. Each entry must contain a buffer address and have the length field set to 140.
CVAF updates the argument field of each buffer list entry with the argument of the
DSCB. You can specify the argument format by setting either the TTR or CCHHR
bit in the buffer list entry to 1. If neither bit is set, CVAF returns a CCHHR
argument.
CVAF uses only the argument in the first entry to begin the search and does not
inspect arguments in subsequent entries. If you specify a nonzero argument value
in the first entry, there must be a DSCB with that argument.
CVAF indicates an end-of-data condition by providing return code 4 in register 15,
and a value of X'20' in the CVSTAT field. CVAF sets the argument fields of all
buffer list entries following the last DSCB read, to zero (the first entry is zero if
CVAF does not read any DSCBs).
CVAF reads all DSCBs, including format-0 DSCBs. You cannot be certain that you
have read all DSCBs until CVAF has read the entire VTOC. For a nonindexed
VTOC, the DS4HPCHR field of the format-4 DSCB contains the CCHHR of the last
format-1 DSCB. DSCBs other than format-1 can reside beyond that location. For an
indexed VTOC, the VMDS contains information about which DSCBs are format-0
DSCBs.
For physical-sequential access, a CVAFSEQ request to an extended address volume
will fail if the EADSCB=OK indicator is not set. CVAF return code of 4 with a
CVAF status code (CVSTAT) of STAT082 will be set.
Reading Sets of DSCBs with CVAF Filter
You can use the CVAFFILT macro to retrieve sets of DSCBs into buffers provided
by the calling program. CVAF filter service supports both indexed and nonindexed
VTOCs. “CVAFFILT Macro Overview and Specification” on page 101 describes the
macro's format and parameters. The following section summarizes this service and
its requirements.
v Request DSCBs by specifying either one or more fully-qualified data set names,
or one partially-qualified name. See “Filter Criteria List (FCL)” on page 70 and
“Partially-Qualified Names for CVAFFILT” on page 107 for further information.
v Identify a single DASD volume in the CVPL.
v For each data set that has a format-1 DSCB, the VTOC order returned by
CVAFFILT is the format-1 DSCB, followed by any format 3 DSCBs.
For each data set that has a format-8 DSCB, the VTOC order returned by
CVAFFILT is the format-8 DSCB, one or more format-9 DSCBs, followed by any
format-3 DSCBs. Currently, the minimum buffer list entry size needed to read all
DSCBs associated with a data set is 12. This is one format-8 DSCB, one format-9
DSCB, and 10 format-3 DSCBs to reach the 123-extent limit.
v CVAF filter service returns DSCB information for one or more qualifying data
sets into caller-provided buffers. See “Example of CVAFFILT Macro Sequences”
on page 73 and “Example of Using the CVAFFILT Macro” on page 107 for
further information. CVAF filter service does not return a partial DSCB chain in
the following cases:
– If you do not provide enough buffers to hold the requested DSCBs, CVAF
filter service returns one or more complete DSCB chains and/or a status code
68
z/OS DFSMSdfp Advanced Services
Using the VTOC
(CVSTAT in the CVPL). The status code indicates if a RESUME CVAF call can
be used to retrieve the rest (or more) of the DSCBs. See “RESUME Capability”
for specific information.
– If the total number of buffers is insufficient to contain a data set's complete
DSCB chain, CVAF filter service sets the FCLDSNST byte in the FCL, ignores
the data set, and processes the next qualifying data set. To avoid this
situation, provide a minimum of eleven DSCB buffers (enough for a data set
at the 123 extent limit).
v For fully qualified data set names in the Filter Criteria List, a CVAFFILT request
issued to an extended address volume will fail if the EADSCB=OK indicator is
not set and the DSCB associated with the fully qualified data set name is
described by a format-8 DSCB. For partially qualified data set names in the
Filter Criteria List, a CVAFFILT request issued to an extended address volume
will fail if the EADSCB=OK indicator is not set and a DSCB associated with a
data set that matches the Filter Criteria List is described by a format- 8 DSCB. In
both these cases, the data set name status in the FCL (FCLDSNST) will be set to
a status value of (x'06'). This status code indicates that a data set name is
described by a format-8 DSCB and the caller did not specify support for it with
the EADSCB=OK keyword. It will be set only when other data set name status
codes are not applicable. CVAF status code (CVSTAT) of STAT086 (x'56') will be
set with these errors. This status code indicates all of the user FCL entries were
processed, a resume is not required, one or more errors were found.
RESUME Capability
If CVAF filter service terminates because you failed to provide sufficient buffers,
the information necessary for a RESUME function is saved in the filter save area.
(Specifying FLTAREA=KEEP on the initial CVAFFILT allocates the filter save area.)
To allow RESUME processing to execute correctly, you must maintain the
relationship between the requested volume (identified by CVDEB, CVUCB, or a
kept IOAREA), your FCL, and CVAF's FSA. If you observe this requirement, you
can initiate and resume multiple CVAF filter service operations asynchronously on
one or more DASD volumes. You can ensure this relationship by providing a
unique CVPL and FCL for the duration of the READ/RESUME/RELEASE
sequence associated with each logical request.
Issuing an ACCESS=RESUME without having previously specified
FLTAREA=KEEP causes CVAF filter service to produce return code 4 in register 15
and 66 (decimal) in the CVSTAT field.
If you specify FLTAREA=KEEP, issue a subsequent CVAFFILT call with the
ACCESS=RLSE keyword to release filter save area storage.
Chapter 1. Using the Volume Table of Contents
69
Using the VTOC
Reg 1 ───→ CVPL──────┐
³ CVFCL ─┼──────────────────────────→
³
³
³ CVBUFL─┼──→ BFL───────┐
³
³
³ BFLH
³
³
³
³
³
└─────────┘
³ BFLE────┴┐
³ ³
³
³ ³BFLEBUF─┼─→ DSCB
³ └───────┬┘
Buffer
³ BFLE────┴┐
³ ³
³
³ ³BFLEBUF─┼─→ DSCB
³ └───────┬┘
Buffer
³
³
³ ... ³
³
³
³ BFLE────┴┐
³ ³
³
³ ³BFLEBUF─┼─→ DSCB
³ └───────┬┘
Buffer
└─────────┘
FCL───────┐
³ FLCH
³
³
³
³ FCLDSN──┴┐
³ ³
³
³ ³FCLDSNA─┼─→ DSN
³ └───────┬┘
³ FCLDSN──┴┐
³ ³
³
³ ³FCLDSNA─┼─→ DSN
³ └───────┬┘
³
³
³ ... ³
³
³
³ FCLDSN──┴┐
³ ³
³
³ ³FCLDSNA─┼─→ DSN
³ └───────┬┘
└─────────┘
Figure 7. Control Blocks Required for CVAF Filter Services
Filter Criteria List (FCL)
The filter criteria list (FCL) consists of a list header and a variable number of list
entries. The list entries follow the header, and each entry represents a data set
name to be processed by CVAF filter. The header and entries, shown in Table 20
and Table 21 on page 72, are mapped by the ICVFCL macro. The format of the FCL
header is shown in Table 20.
Table 20. Format of a Filter Criteria List Header
Offset
Bytes
Name
Description
0 (X'00')
4 (X'04')
4
2
FCLID
FCLCOUNT
6 (X'06')
8 (X'08')
2
1
1...
.1..
..1.
...1
FCLDSCBR
FCL1FLAG
FCL1LIST
FCL1ORDR
FCL1EQF1
FCL1EQF9
EBCDIC 'FCLbb' (bb here represents a blank.)
Number of data set name entries provided in
the list.
Number of DSCBs returned.
Request flag byte.
List contains fully-qualified data set names.
FCL data set name order requested.
Return only format-1 or format-8 DSCBs.
Return only format-1 or format-8 and format-9
DSCBs.
Reserved.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . xxxx
9 (X'09')
1
1.......
.1......
FCL2FLAG
FCL2SEQ
FCL2SDIR
Status flag byte.
CVAFFILT executed sequential VTOC access.
CVAFFILT executed sequential VTOC access,
but did at least one direct DSCB read.
Reserved.
FCLDRSV
Reserved.
. . xx xxxx
10 (X'0A')
6
FCLID
Must be a 4-character EBCDIC constant of 'FCLbb'. (bb here represents a blank.)
70
z/OS DFSMSdfp Advanced Services
Using the VTOC
FCLCOUNT
Specifies the number of data set name entries (FCLDSN) supplied in the list.
Do not change this parameter between the initial CVAFFILT call and any
subsequent RESUME operations.
v If you specify a partially-qualified data set name, specify FCLCOUNT = 1.
See “Partially-Qualified Names for CVAFFILT” on page 107 for the format of
partially-qualified data set names.
v If you specify a list of fully-qualified names, CVAFFILT processes only the
number of names specified in FCLCOUNT.
FCLDSCBR
Indicates the total number of DSCB entries (including format-1, format-2, and
format-3) returned to the caller's buffers by a single CVAFFILT call.
If CVAF encounters an error after successfully processing a data set, you can:
1. Initialize FCLDSCBR to 0 before each READ and RESUME call.
2. Upon return from CVAF filter service, process the number of DSCBs
indicated by FCLDSCBR.
3. Then, interpret the CVAF return code and CVSTAT.
FCL1FLAG
Define your request for ACCESS=READ with this flag byte. Any subsequent
RESUME requests refer to a copy of these bits in the filter save area (FSA).
FCL1LIST
If you specify a list of fully-qualified data set names, set this bit to 1. If
you specify a single partially-qualified data set name, set this bit to 0.
FCL1ORDR
If you specify that CVAF is to return DSCB chains in the data set name
sequence implied by the placement of the FCLDSN elements, set this bit to
1.
Note:
1. It can improve performance to allow CVAF to determine the sequence
of return for format-1 DSCBs.
2. CVAF returns DSCBs for a given data set in format-1, format-3 order.
For an extended address volume, the data set order for EAS eligible
data sets is a format-1, one or more format-9, and any format-3 DSCBs.
3. If you specify a single partially-qualified data set name, this field is not
used.
FCL1EQF1
To have CVAF return only the format-1 or format-8 DSCBs for the data set
names, set this bit to 1.
FCL1EQF9
To have CVAF return only the format-1 or format-8 and format-9 DSCBs
for the data set names, set this bit to 1.
FCL2FLAG
CVAF filter indicates the following status conditions in this byte.
FCL2SEQ
This bit is set to 1 if a sequential VTOC access path is most efficient. If
CVAF filter selects the direct VTOC access path, it sets this field to 0.
FCL2SDIR
This bit is set to 1 if storage limitations within the sequential VTOC access
Chapter 1. Using the Volume Table of Contents
71
Using the VTOC
path require direct DSCB reads. CVAF initializes this bit to 0 on each
ACCESS=READ and ACCESS=RESUME request. Testing this bit when
CVAF filter returns control can indicate if you need to change the storage
limitation.
The format of the FCL entry is shown in Table 21.
Table 21. Format of a Filter Criteria List Entry
Offset
0 (X'00')
Bytes
Name
Description
8
1
X'00'
X'01'
X'02'
X'03'
FCLDSN
FCLDSNST
Data set name information entry.
Data set name status.
Data set name not yet processed.
DSCBs returned successfully.
Data set name not found.
Error in DSCB chain. RESUME function
recommended.
Error in CVAFFILT processing.
RESUME not recommended.
Insufficient user buffer list elements.
RESUME function recommended.
Request issued to an EAV without
EADSCB=OK specified and a format-8
DSCB was found.
Request issued to any volume without
EADSCB=OK specified where an EAS
eligible data set was found.
Data set name length.
Flag byte.
This data set name processed during
this invocation.
Reserved.
Reserved.
Data set name address.
X'04'
X'05'
X'06'
X'07'
1 (X'01')
2 (X'02')
3 (X'03')
4 (X'04')
1
1
1.......
FCLDSNLG
FCL3FLAG
FCL3UPDT
. xxx xxxx
1
4
FCLDSNRV
FCLDSNA
FCLDSN
Contains data set name information. This and the following fields are repeated
in the FCL as a set as many times as indicated by the value in FCLCOUNT.
FCLDSNST
Indicates DSCB retrieval status.
v CVAF filter initializes this byte to 0 for ACCESS=READ requests.
v After processing the data set name for either ACCESS=READ or
ACCESS=RESUME, CVAF filter updates this byte.
v ACCESS=RESUME requests do not process data set names whose
FCLDSNST field is nonzero; therefore, results can be unpredictable if
you alter this field.
v For partially-qualified data set name requests, CVAF filter does not post
the FCLDSNST field until it has returned all DSCB chains for all
qualifying data sets. CVAF filter posts the highest numeric value that
applied during its processing.
v For fully-qualified data set name requests, CVAF filter returns a
FCLDSNST byte for each data set name. If the value is greater than 1,
CVAF filter has not returned any DSCBs for the associated data set
name.
72
z/OS DFSMSdfp Advanced Services
Using the VTOC
See Table 21 on page 72 for an explanation of the values in this field.
FCLDSNLG
Indicates the length of the data set name. This value is required.
FCL3FLAG
The status flag byte associated with the data set name pointed to by
FCLDSNA.
FCL3UPDT
This bit indicates that CVAF filter processed the associated data set
name during the current invocation of CVAFFILT.
v When initializing for either a READ or RESUME request, CVAF filter
sets this bit to 0.
v When CVAF filter has completed processing for the associated data
set name, it sets this bit to 1.
FCL3DSNRV
Reserved, unused.
FCLDSNA
Specifies the address of a fully-qualified data set name, or, if this is the
only data set name and FCL1LIST is 0, a partially-qualified data set name.
You must provide both this address and the storage area to which it
points.
Example of CVAFFILT Macro Sequences
The example below demonstrates the order that you might issue CVAFFILT macro
calls to complete the following tasks:
v Request the DSCBs for a list of data sets.
v Resume CVAFFILT processing interrupted because of insufficient user buffers.
v Release the kept filter save area.
The example assumes the following conditions:
v You are an authorized caller (that is, you are specifying a UCB address and
IOAREA=KEEP).
v You have initialized a CVAF buffer list with the following characteristics:
– Four buffers
– The buffer list address in your program has the label BUFADDR
– The same buffer list is used for ACCESS=READ and ACCESS=RESUME
processing.
v You have initialized a filter criteria list as follows:
– FCLCOUNT = 6 (You are requesting DSCB chains for six data set names.)
– FCL1LIST = '1'B (The data set names are fully qualified.)
– FCL1ORDR = '1'B (You want the DSCB chains returned in the order implied
by data set name elements in the FCL.)
– The six data set name elements are initialized so that they form a list
requesting SYS1.A, SYS2.B, SYS3.C, SYS4.D, SYS5.E, and SYS6.F.
v The first five data sets have DSCB chain lengths or 1, 5, 2, 3, and 1, respectively,
on the volume.
v The sixth data set (SYS6.F) is not defined on the volume.
Chapter 1. Using the Volume Table of Contents
73
Using the VTOC
To obtain an initialized CVPL, you could issue the following CVAFFILT macro (list
form—does not call CVAF). This example requests the branch entry to CVAF and
specifies that the caller is in supervisor state.
CVPLIST
CVAFFILT BRANCH=(YES,SUP),MF=L
To obtain the first set of DSCB chains, you could issue the following CVAFFILT
macro (execute form—calls CVAF). This example specifies that the filter save area
is to be kept to allow for ACCESS=RESUME calls. The IOAREA is to be kept for
improved efficiency.
CVAFFILT ACCESS=READ,BUFLIST=bufaddr,FCL=fcladdr,
UCB=ucbaddr,FLTAREA=KEEP,IOAREA=KEEP,
MF=(E,CVPLIST)
This CVAFFILT call returns the following DSCBs:
Buffer
1
2
3
4
Contents of Buffer
Format-1 DSCB, SYS1.A
Format-1 DSCB, SYS3.C
Format-3 DSCB, SYS3.C
Undefined (unused)
CVAF filter produces return code = 4, CVSTAT = X'40' (RESUME recommended),
and FCLDSCBR = 3. (CVAF returns a total of three DSCBs for the two data sets.)
CVAF would not return DSCBs for data set SYS2.B because its chain contains more
DSCBs than the total number of buffers provided. To retrieve the DSCBs for
SYS2.B, you need to specify at least five buffers and execute another
ACCESS=READ. (Even though CVAF allows you to specify a different buffer list
for each READ or RESUME, or to modify the existing list between READ and
RESUME calls, modifying the FCL would cause unpredictable results.) Buffer entry
4 does not have any DSCBs returned, because SYS4.D's DSCB chain size is larger
than the number of remaining buffers. The FCL status information would be as
follows:
DSN
SYS1.A
SYS2.B
SYS3.C
SYS4.D
SYS5.E
SYS6.F
FCLDSNST
1
5
1
0
0
0
FCL3UPDT
1
1
1
0
0
0
Comments
DSCBs returned from this
DSCB chain exceeds total
DSCBs returned from this
DSCBs can be returned by
DSCBs can be returned by
DSCBs can be returned by
call
buffers
call
RESUME
RESUME
RESUME
Because this CVAFFILT invocation recommends RESUME, and you specified
FLTAREA=KEEP, you could use the following execute form of CVAFFILT to obtain
more DSCB chains:
CVAFFILT ACCESS=RESUME,MF=(E,CVPLIST)
This CVAFFILT call returns DSCBs as follows:
Buffer
1
2
3
4
Contents
Format-1
Format-2
Format-3
Format-1
of Buffer
DSCB, SYS4.D
DSCB, SYS4.D
DSCB, SYS4.D
DSCB, SYS5.E
CVAF filter produces return code = 0, CVSTAT = 0 (request completed), and
updates the FCL status as follows:
DSN
SYS1.A
SYS2.B
SYS3.C
74
FCLDSNST
1
5
1
z/OS DFSMSdfp Advanced Services
FCL3UPDT
0
0
0
Comments
DSCBs returned from prior call
DSCB chain exceeds total buffers
DSCBs returned from prior call
Using the VTOC
SYS4.D
SYS5.E
SYS6.F
1
1
2
1
1
1
DSCBs returned from this call
DSCBs returned from this call
Data set name not found
FCLDSCBR would contain 4. (This CVAFFILT call returns a total of four DSCBs.)
CVAF filter does not return any DSCBs for SYS6.F, because its format-1 DSCB
cannot be found on the volume (FCLDSNST = '2').
Because this status indicates that CVAF filter has returned all requested DSCBs,
and you requested FLTAREA=KEEP and IOAREA=KEEP on the previous call,
request the RLSE function as follows:
CVAFFILT ACCESS=RLSE,FLTAREA=NOKEEP,IOAREA=NOKEEP,
MF=(E,CVPLIST)
Coding CVAF VTOC Access Macros
This section includes VTOC index information that depends on internal system
logic. It is intended to help you to use CVAF macro instructions to modify the
VTOC
v “CVAFDIR Macro Overview and Specification”
v “CVAFDSM Macro Overview and Specification” on page 95
v “CVAFFILT Macro Overview and Specification” on page 101
v “CVAFSEQ Macro Overview and Specification” on page 121
v “CVAFTST Macro Overview and Specification” on page 139
v “VTOC Index Error Message and Associated Codes” on page 140
CVAFDIR Macro Overview and Specification
For an indexed or nonindexed VTOC, you can use the CVAFDIR macro to perform
the following functions:
v Read or write one or more DSCBs by specifying the name of the data set they
represent.
v Read or write one or more DSCBs by specifying their addresses.
In addition, for an indexed VTOC, you can use the CVAFDIR macro to perform the
following functions:
v Read or write VTOC index records. (This allows calling programs to modify the
VTOC index.)
v Read and retain in virtual storage the first high-level VIER, and VIERs used
during an index search.
v Read and retain in virtual storage the space map VIRs.
v Free VIRs retained in virtual storage.
See “Accessing the DSCB Directly” on page 64 for additional information.
The format of the CVAFDIR macro is:
Chapter 1. Using the Volume Table of Contents
75
CVAF Macros
►►
CVAFDIR ACCESS=
label
READ
WRITE
RLSE
►
,DSN=addr
,BUFLIST=addr
►
►
,VERIFY=
NO
YES
,UCB= (ucbaddr)
,DEB=addr
,IOAREA=
NOKEEP
KEEP
(KEEP,addr)
(NOKEEP,addr)
►
►
,MAPRCDS=
NO
YES
(YES,addr)
(NO,addr)
,IXRCDS=
NOKEEP
KEEP
(KEEP,addr)
(NOKEEP,addr)
►
►
NO
,BRANCH=
(1)
YES
(YES,SUP)
(YES,PGM)
,EADSCB=
NOTOK
OK
,MULTIPLEDSCBS=
NO
YES
►
►◄
,MF=
I
L
(E,addr)
Notes:
1
If YES is coded, the default is SUP.
ACCESS: Read or Write a DSCB or VIRs, or Release Buffer Lists
When ACCESS is READ or WRITE, a single DSCB is accessed for an indexed or
nonindexed VTOC, or one or more VIRs are accessed for an indexed VTOC.
ACCESS=READ
Specifies that a single DSCB or one or more VIRs are to be read into a buffer
whose address is in a buffer list.
If the buffer list is for a DSCB, only one entry is used in the buffer list. The
first entry with the skip bit set to zero and a nonzero buffer address is used.
All VIRs whose buffer list entry has the skip bit off are read into a buffer.
DSN and BUFLIST are required if ACCESS=READ for a DSCB buffer list.
ACCESS=WRITE
Specifies that a single DSCB or one or more VIRs are to be written from buffers
whose address is in a buffer list.
ACCESS=WRITE is permitted with BRANCH=NO only if the caller is
authorized by APF.
DSN and BUFLIST are required if ACCESS=WRITE for a DSCB buffer list.
If any buffer list entry has its modified bit set, only those entries with the
modified bit set are written. If no modify bits are on, all VIRs are written.
ACCESS=RLSE
Applies only to VIR buffer lists. It requests the release of one or more buffers
in the VIR buffer list chain identified in the BUFLIST keyword, and the release
of each buffer list for which all buffers are released.
76
z/OS DFSMSdfp Advanced Services
CVAF Macros
DSN and BUFLIST are not required if ACCESS=RLSE.
Only buffers in the buffer list with the skip bit set to zero and with a nonzero
buffer address are released. The buffer list is not released if any entry has the
skip bit set to one.
For an indexed VTOC, if ACCESS=RLSE is coded, buffer lists and buffers
pointed to by the BUFLIST keyword are released, along with buffer lists
supplied in the CVAF parameter list CVMRCDS and CVIRCDS fields. If the
CVMRCDS or the CVIRCDS buffers are supplied in the BUFLIST field, either
directly or indirectly through chaining, the keyword MAPRCDS=YES,
IXRCDS=KEEP, or MAPRCDS=(NO,0), IXRCDS=(NOKEEP,0) must be coded to
prevent CVAF from freeing the buffers more than once. If buffers are released,
the CVAF parameter list field pointing to the buffer list is updated.
DSN: Specify the Name of the DSCB
DSN=addr
Supplies the address of a 44-byte data set name of the DSCB to be accessed.
DSN is required if ACCESS=READ or WRITE and the request is to read or
write a DSCB. If a 140-byte DSCB is specified:
v CVAF validity checks the storage location, but ignores the contents of the
location.
v Specify an argument that points to an extent within the VTOC.
BUFLIST: Specify One or More Buffer Lists
BUFLIST=addr
Supplies the address of a buffer list used to read or write a DSCB or VIRs.
|
VALIDATE: Validate Modified fields in a DSCB
|
|
|
VALIDATE=YES
CVAF verifies that the DSCBs being written do not modify essential fields that
should not be modified.
|
|
This parameter applies only to CVAFDIR ACCESS=WRITE.
VALIDATE=NO
|
CVAF does not do any checking. This is the default.
|
|
Restriction: VALIDATE applies only when writing a DSCB, and is ignored
when a VIR is written.
VERIFY: Verify that a DSCB is a Format-0 DSCB
VERIFY=YES
CVAF verifies that the DSCB is a format-0 DSCB before writing the DSCB. The
first four bytes of the key are compared with binary zeros. If the key does not
start with 4 bytes of zeros, the DSCB is not written and an error code is
returned.
VERIFY=NO
CVAF does not test the key of the DSCB. This is the default.
Restriction: VERIFY applies only when writing a 140-byte DSCB. VERIFY is
ignored when a VIR is written.
Chapter 1. Using the Volume Table of Contents
77
CVAF Macros
UCB or DEB: Specify the VTOC to Be Accessed
UCB= rs-type or (2-12) standard form UCB= rx-type or (2-12) execute form
Specifies the address of the UCB for the VTOC to be accessed. The UCB
address can be for a captured UCB, or for an actual UCB above or below the
16MB line. Use the address of a UCB, not a UCB copy. An unauthorized caller
must not use this parameter. If your program is in 31-bit mode, this address
must be in 31-bit address; the high order byte is part of the address. You
should not code the UCB parameter with MF=L.
Recommendation: Code the address of the UCB parameter as register (2-12).
Coding an RX-Type address gives unpredictable results.
Note: You must supply a UCB address that matches the caller's AMODE. That
is, AMODE=24 requires a 24 bit UCB address, while AMODE=31 requires a 31
bit UCB address.
DEB=addr
Supplies the address of a DEB opened to the volume table of contents (VTOC)
you want to access. CVAF does not allow output requests to the VTOC or
VTOC index if you specify the DEB subparameter. If you are not authorized
(neither APF nor in a system key), you cannot perform any asynchronous
activity (such as EXCP, CLOSE, EOV) against the data set represented by the
DEB because CVAF removes the DEB from the DEB table for the duration of
the CVAF call. If you are not authorized, (neither APF authorized nor in a
system key), specify a DEB address, not a UCB, to CVAFDIR. See “Identifying
the Volume” on page 58 for further details.
If you supply a previously obtained I/O area through the IOAREA keyword,
neither UCB nor DEB need be supplied. Otherwise, supply either a UCB or DEB. If
you supply a UCB address, it is overlaid in the CVPL by the UCB address in the
I/O area. If you supply both the DEB and UCB addresses in the CVPL, the DEB
address is used and the UCB address in the CVPL is overlaid by the UCB address
in the DEB.
IOAREA: Keep or Free the I/O Work Area
IOAREA=KEEP
Specifies that, upon completion of the CVAF request, the program should keep
the CVAF I/O area associated with the CVAF parameter list. You can code
IOAREA=KEEP with BRANCH=NO only if the caller is authorized (APF or
system key).
If IOAREA=KEEP is coded, the caller must call CVAF with IOAREA=NOKEEP
specified at some future time, whether or not any further VTOC access is
required. An example of such a caller is the recovery routine of the routine that
calls CVAF.
When you code IOAREA=KEEP, it allows subsequent CVAF requests to be
more efficient, because the program can bypass certain initialization functions.
You do not need to specify either DEB or UCB when a previously obtained
CVAF I/O area is supplied; you also cannot change those values.
When IOAREA=KEEP is first issued, CVAF returns the CVAF I/O area in the
CVAF parameter list (CVIOAR). Subsequent calls of CVAF can use that same
parameter list, and CVAF obtains its I/O area from the CVIOAR.
When processing on the current volume is finished, release all areas that were
kept.
78
z/OS DFSMSdfp Advanced Services
CVAF Macros
IOAREA=(KEEP,addr)
Supplies the address of a previously obtained I/O area. If a different CVAF
parameter list is used, the previously obtained I/O area can be passed to
CVAF by coding its address as the second parameter of the IOAREA keyword.
IOAREA=NOKEEP
Causes the work area to be freed upon completion of the CVAF request.
IOAREA=(NOKEEP,addr)
Causes a previously obtained work area to be freed upon completion of the
CVAF request.
MAPRCDS: Keep or Free MAPRCDS Buffer List and Buffers
This keyword applies to an indexed VTOC only and specifies the disposition of the
MAPRCDS buffer list and buffers.
MAPRCDS=YES
Specifies that the buffer list and buffers are to be retained at the end of
processing.
If no buffer list address is in the CVAF parameter list, CVAF reads the MAP
VIRs into buffers it obtains. The buffer list that contains the address and RBAs
of the VIRs can be accessed after processing from the CVAF parameter list
field, CVMRCDS. The buffer list and VIR buffers are in your protect key:
subpool 0 if you are not authorized; subpool 229 if you are.
When processing on the current volume is finished, release all areas that were
kept.
MAPRCDS=(YES,addr)
If MAPRCDS=YES is coded and the buffer list address (CVMRCDS in CVAF
parameter list) is supplied, VIRs are not read.
The CVMRCDS buffer list used in CVAFDIR macro can be passed to another
CVAF macro call through the MAPRCDS keyword.
If MAPRCDS=YES is coded for a nonindexed VTOC, the function is
performed, but an error code is returned.
MAPRCDS=NO
If MAPRCDS=NO is coded, all the buffers without the skip bit on in the buffer
list whose address is in the CVMRCDS field of the CVPL are freed. If all the
buffers are freed, the buffer list is also freed.
MAPRCDS=(NO,addr)
Frees buffer lists and buffers previously obtained by CVAF.
You must free buffer lists and buffers obtained by CVAF. This can be done in one
of three ways:
v By coding MAPRCDS=NO on the CVAFDIR macro that obtained the buffers
v By coding MAPRCDS=NO on a subsequent CVAF macro
v By coding CVAFDIR ACCESS=RLSE and providing the address of the buffer list
in the BUFLIST keyword.
Requirement: You must enqueue the VTOC and reserve the unit to maintain the
integrity of MAP records read.
IXRCDS: Retain VIERS in Virtual Storage
This keyword applies to indexed VTOCs only.
Chapter 1. Using the Volume Table of Contents
79
CVAF Macros
IXRCDS=KEEP
Specifies that VIERs read into storage are to be kept in virtual storage. The
VIERs are retained even if processing cannot complete successfully. The CVAF
parameter list in field CVIRCDS contains the address of a buffer list with the
VIR buffer addresses and RBAs of the VIERs read.
The index search function dynamically updates the buffer list and, when
necessary, obtains additional buffer lists and chains them together.
If IXRCDS=KEEP is specified and no buffer list is supplied to CVAF in the
CVPL, CVAF obtains a buffer list and buffers and reads the first high-level
VIER. The address of the buffer list is placed in the CVIRCDS field of the
CVPL.
The buffer list and VIR buffers are in your protect key. The subpool is 0 if you
are not authorized; it is subpool 229 if you are.
If IXRCDS=KEEP is coded for a nonindexed VTOC, a request to read or write
a DSCB is performed, but an error code is returned.
When processing on the current volume is finished, release all areas that were
kept.
IXRCDS=(KEEP,addr)
The index records buffer list address from one CVAF request is being passed to
this CVAF parameter list by specifying its address as the second parameter in
the IXRCDS keyword.
IXRCDS=NOKEEP
If IXRCDS=NOKEEP is coded, the VIERs that are accessed (if any) are not
retained. Furthermore, the buffer list supplied in the CVIRCDS field in the
CVAF parameter list is released, as are all buffers found in the buffer list. If the
skip bit is set in any entry in the buffer list, the buffer and buffer list are not
freed. This is the default.
IXRCDS=(NOKEEP,addr)
Specifies that previously accessed VIERs are not to be retained.
You must free buffer lists and buffers obtained by CVAF. This can be done in one
of three ways:
v By coding IXRCDS=NOKEEP on the CVAFDIR macro that obtained the buffers
v By coding IXRCDS=NOKEEP on a subsequent CVAF macro
v By coding CVAFDIR ACCESS=RLSE and providing the address of the buffer list
in the BUFLIST keyword.
Requirement: You must enqueue the VTOC and reserve the unit to maintain the
integrity of the VIERs read.
BRANCH: Specify the Entry to the Macro
BRANCH=(YES,SUP)
Requests the branch entry. Your program be in supervisor state. Protect key
checking is bypassed.
If BRANCH=YES is coded, an 18-word save area must be supplied. No lock
can be held on entry to CVAF. SRB mode is not allowed.
BRANCH=YES
Equivalent to BRANCH=(YES,SUP), because SUP is the default when YES is
coded. Protect key checking is bypassed.
80
z/OS DFSMSdfp Advanced Services
CVAF Macros
BRANCH=(YES,PGM)
Requests the branch entry. Your program be authorized by APF and be in
problem state. Protect key checking is bypassed.
BRANCH=NO
Requests the SVC entry. If any output operations are requested, your program
must be authorized by APF. Protect key checking is performed. This is the
default.
EADSCB: Specify the support level for extended attribute DSCBs
EADSCB=OK
This specification indicates that the calling program supports extended
attribute DSCBs. An extended address volume may have these DSCBs
allocated to it. The returned DSCBs (format-3, format-8) may contain extent
descriptors described by 28-bit cylinder addresses or DSCBs (format-9) that
contain additional attribute information.
For search calls where the data set name is passed (CVAFDIR
ACCESS=READ,BFLEARG=0), a CVAFDIR request will fail if the EADSCB=OK
indicator is not set and the DSCB associated with this data set name is a
format-8 DSCB.
For seek calls where the record address is passed (CVAFDIR
ACCESS=READ,BFLEARG=cchhr), a CVAFDIR request issued to an EAV
volume will be failed if the EADSCB=OK indicator is not set and the DSCB
associated with this address is a format-8 or format-9 DSCB.
For seek calls where the record address is passed (CVAFDIR
ACCESS=READ,BFLEARG=cchhr), and MULTIPLEDSCBS=NO is specified or
defaulted to NO, a CVAFDIR request will faileif the EADSCB=OK indicator is
not set and the DSCB associated with this address is a format-3 DSCB that
contain track addresses above 65,520 cylinders.
The failing error code for these cases will be reflected as follows:
v CVAF status code (CVSTAT) set to STAT082.
v Return code 4.
EADSCB=OK will set the CV4EADOK indicator in the CVPL.
For all other calls, the EADSCB=OK keyword is ignored.
EADSCB=NOTOK
Indicates a calling program does not support extended attribute DSCBs. The
specification of this will resolve to the CV4EADOK indicator in the CVPL to be
set off. This is the default.
MULTIPLEDSCBS: Specify whether multiple DSCBs should be
processed
MULTIPLEDSCBS=NO
This specification indicates that the calling program requests that only one
DSCB should be processed. This is the default for MF=L and MF=I forms of
the CVAFDIR macro. When the MULTIPLEDSCBS keyword is not specified on
the MF=E form, the existing setting of CV4MULTD is left unchanged. When
MULTIPLEDSCBS=NO is specified or defaulted, only the first available buffer
list entry is processed.
MULTIPLEDSCBS=YES
This specification indicates that the calling program requests to read/write
multiple DSCBs to/from a buffer list that contains more than one buffer list
Chapter 1. Using the Volume Table of Contents
81
CVAF Macros
entry. This parameter causes an indicator in the CVPL, CV4MULTD, to be set
on. Multiple DSCB processing for reads and writes is requested by specifying
the MULTIPLEDSCBS=YES keyword and providing a buffer list that contains
more than one buffer list entry (BFLHNOE>1).
MF: Specify the Form of the Macro
This keyword specifies whether the list, execute, or normal form of the macro is
requested.
MF=I
If I is coded or if neither L nor E is coded, the CVAF parameter list is
generated and CVAF is called. This is the normal form of the macro.
MF=L
Indicates the list form of the macro. A parameter list is generated, but CVAF is
not called.
MF=(E,addr)
Indicates the execute form of the macro. The CVAF parameter list whose
address is in addr can be modified by this form of the macro.
Return Codes from CVAFDIR
On return from CVAF, register 1 contains the address of the CVPL (CVAF
parameter list), and register 15 contains one of the following return codes:
Return Code
Meaning
0 (X'00')
The request was successful. However, if the CVAFDIR request is to
read or write a DSCB and a VTOC index structure error is
encountered, the CVSTAT field indicates the structure error that
was encountered. (CVSTAT code descriptions are in z/OS
DFSMSdfp Diagnosis.)
An error occurred. The CVSTAT field in the CVPL contains an
indication of the cause of the error. (CVSTAT code descriptions are
in z/OS DFSMSdfp Diagnosis.)
Invalid VTOC index structure while processing a request to read
or write a VTOC index record. The CVSTAT field in the CVPL
contains an indication of the cause of the error. (CVSTAT code
descriptions are in z/OS DFSMSdfp Diagnosis.)
The CVAF parameter list is not in your protect key or is not valid
(the ID is not valid, or the length field is incorrect, or the CVFCTN
(function code) field is not valid or is not supported in this
release). The CVPL has not been modified.
An I/O error was encountered.
4 (X'04')
8 (X'08')
12 (X'0C')
16 (X'10')
Example of Using the CVAFDIR Macro with a VTOC
This example uses the CVAFDIR macro to read a DSCB of a given data set name
and determines whether the DSCB is for a partitioned data set. The address of the
44-byte data set name is supplied to the program in register 5 (labeled RDSN in
the example). The address of a DEB open to the VTOC is supplied to the program
in register 4 (labeled RDEB in the example).
The buffer list is in the program and is generated by the ICVAFBFL macro. The
DSCB buffer is in the program and is generated by the IECSDSL1 macro.
82
z/OS DFSMSdfp Advanced Services
CVAF Macros
DIRXMP1 CSECT
STM
14,12,12(RSAVE)
BALR 12,0
USING *,12
ST
RSAVE,SAVEAREA+4
LA
RWORK,SAVEAREA
ST
RWORK,8(,RSAVE)
LR
RSAVE,RWORK
************************************************************
*
*
REGISTERS
*
************************************************************
REG1
EQU
1
REGISTER 1
RWORK
EQU
3
WORK REGISTER
RDEB
EQU
4
DEB ADDRESS
RDSN
EQU
5
ADDRESS OF DATA SET NAME
RSAVE
EQU
13
SAVE AREA ADDRESS
REG15
EQU
15
RETURN CODE REGISTER 15
************************************************************
*
*
RETURN CODES
*
************************************************************
PDSRTN EQU
0
DATA SET A PDS RETURN CODE
NOTFND EQU
4
DATA SET NOT FOUND RETURN CODE
NOTPDS EQU
8
DATA SET NOT A PDS RETURN CODE
UNEXPECD EQU
12
UNEXPECTED ERROR RETURN CODE
************************************************************
*
*
READ DSCB INTO DS1FMTID.
*
DATA SET NAME ADDRESS SUPPLIED IN RDSN.
*
ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB.
*
DETERMINE IF DATA SET IS A PARTITIONED DATA SET.
*
THIS PROGRAM IS NEITHER REENTRANT NOR REUSABLE.
*
************************************************************
XC BUFLIST(BFLHLN+BFLELN),BUFLIST ZERO BUFFER LIST
OI BFLHFL,BFLHDSCB
DSCBS TO BE READ WITH BUFFER LIST
MVI BFLHNOE,1
ONE BUFFER LIST ENTRY
LA RWORK,DS1FMTID
ADDRESS OF DSCB BUFFER
ST RWORK,BFLEBUF
PLACE IN BUFFER LIST
OI BFLEFL,BFLECHR
CCHHR OF DSCB RETURNED BY CVAF
MVI BFLELTH,DSCBLTH
DATA PORTION OF DSCB READ - DSN
SUPPLIED IN CVPL
MVC DS1DSNAM,0(RDSN)
MOVE IN DATA SET NAME TO WORKAREA
CVAFDIR ACCESS=READ,DSN=DS1DSNAM,BUFLIST=BUFLIST,DEB=(RDEB)
USING CVPL,REG1
ADDRESSABILITY TO CVPL
LTR REG15,REG15
ANY ERROR
BZ NOERROR
BRANCH IF NOT
*
Figure 8. Example of CVAFDIR Macro with VTOC Part 1 of 2
Chapter 1. Using the Volume Table of Contents
83
CVAF Macros
************************************************************
*
*
DETERMINE WHAT ERROR IS
*
************************************************************
C
REG15,ERROR4
IS RETURN CODE 4
BNE OTHERERR
BRANCH IF NOT 4
CLI CVSTAT,STAT001
IS IT DATA SET NAME NOT FOUND?
BNE OTHERERR
BRANCH IF NOT
DROP REG1
ADDRESSABILITY TO CVPL NOT NEEDED
************************************************************
*
*
DATA SET NAME NOT FOUND
*
************************************************************
L
RSAVE,4(,RSAVE)
RETURN (14,12),RC=NOTFND SET UP DATA SET NOT FOUND ERROR
NOERROR EQU *
DSCB READ
MVC F1CCHHR,BFLEARG
MOVE CCHHR OF FORMAT 1/4 DSCB TO
WORKAREA
CLI DS1FMTID,C’4’
IS DSCB A FORMAT 4 DSCB
BE NOTF1
BRANCH IF YES. NOT A FORMAT 1
TM DS1DSORG,DS1DSGPO
IS FORMAT 1 DSCB FOR PARTITIONED
DATA SET
BO PDS
BRANCH IF PDS
NOTF1
EQU *
DSCB IS NOT A PDS
L
RSAVE,4(,RSAVE)
RETURN (14,12),RC=NOTPDS SET UP NOT PDS RETURN CODE
PDS
EQU *
DATA SET IS PARTITIONED
L
RSAVE,4(,RSAVE)
RETURN (14,12),RC=PDSRTN SET UP PDS RETURN CODE
OTHERERR EQU *
UNEXPECTED ERROR
L
RSAVE,4(,RSAVE)
RETURN (14,12),RC=UNEXPECD
ERROR4 DC F’4’
BUFLIST ICVAFBFL DSECT=NO
IECSDSL1 (1)
ERROR RETURN CODE 4
BUFFER LIST
FORMAT 1 DSCB DATA SET NAME AND
BUFFER
DSCBLTH EQU *-IECSDSL1-L’DS1DSNAM LENGTH OF DATA PORTION OF DSCB
F1CCHHR DS XL5
CCHHR OF DSCB
SAVEAREA DS 18F
SAVE AREA
CVPL
ICVAFPL ,
CVPL MAPPING MACRO
*
*
*
END
Figure 9. Example of CVAFDIR Macro with VTOC Part 2 of 2
Example of Using the CVAFDIR Macro with an Indexed VTOC
This example uses the CVAFDIR macro to read one or more DSCBs from a VTOC.
The UCB is supplied to the program in register 4 (labeled RUCB). The TTR of each
DSCB read is to be returned to the caller as well as the return code received back
from CVAFDIR. This program must be APF authorized.
The address of a parameter list is supplied to the program in register 5 (labeled
RLIST). The parameter list contains one or more 4-word entries. The format of each
4-word entry is mapped by the LISTMAP DSECT. The first word contains the
address of the data set name of the DSCB to be read. The second word contains
the address of the 96-byte buffer into which the DSCB is to be read. The third
word contains the address of the 3-byte TTR of the DSCB read. The fourth word
contains the return code received back from CVAFDIR for the DSCB read.
84
z/OS DFSMSdfp Advanced Services
CVAF Macros
The CVPL is generated by a list form of the CVAFDIR macro at label CVPL. The
BUFLIST, IXRCDS, IOAREA, and BRANCH keywords are coded on the list form of
the macro. IXRCDS=KEEP and IOAREA=KEEP are coded to avoid overhead if two
or more DSCBs are to be read. BRANCH=(YES,PGM) is coded in the list form of
the CVAFDIR macro to cause the CVPL to have the CV1PGM bit set to one; this
indicates to CVAF that the caller is authorized by APF and not in supervisor state.
The execute forms of the CVAFDIR macro then specify BRANCH=YES, and not
BRANCH=(YES,PGM), because the CV1PGM bit is set in the list form of the
macro.
The CVAFDIR macro with ACCESS=RLSE is coded before the program exits to
release the CVAF I/O area and the index records buffer list. BUFLIST=0 is coded
because no user-supplied buffer list is to be released; BUFLIST was coded on the
list form of the CVAFDIR macro and, therefore, is in the CVBUFL field of the
CVPL. This field must be set to zero for the release function.
DIRXMP2
CSECT
STM
BALR
USING
ST
LA
ST
LR
14,12,12(13)
12,0
*,12
13,SAVEAREA+4
RWORK,SAVEAREA
RWORK,8(,13)
13,RWORK
*
************************************************************
*
* REGISTERS
*
************************************************************
*
RWORK
EQU 3
WORK REGISTER
RUCB
EQU 4
UCB ADDRESS SUPPLIED BY CALLER
RLIST
EQU 5
ADDRESS OF PARAMETER LIST (SUPPLIED)
RDSN
EQU 6
ADDRESS OF DATA SET NAME
RTTR
EQU 7
ADDRESS OF TTR
REG15
EQU 15
RETURN CODE REGISTER 15
*
************************************************************
*
* UCB ADDRESS SUPPLIED IN RUCB.
* READ DSCB OF DATA SET NAME SUPPLIED.
* RETURN TTR OF DSCB.
* RETURN RETURN CODE FOR CVAFDIR REQUEST FOR DSCB.
* ADDRESS OF PARAMETER LIST IN RLIST.
* WORD 1 OF PARAMETER LIST = ADDRESS OF DATA SET NAME
* WORD 2 OF PARAMETER LIST = ADDRESS OF DSCB TO BE RETURNED
* WORD 3 OF PARAMETER LIST = ADDRESS OF TTR TO BE RETURNED
* WORD 4 OF PARAMETER LIST = RETURN CODE RETURNED FROM CVAFDIR FOR DSCB
* WORDS 1-4 CAN BE DUPLICATED FOR MULTIPLE REQUESTS
* THE HIGH ORDER BIT OF WORD 3 SET TO X’80’ FOR THE LAST ENTRY ONLY.
*
************************************************************
*
USING LISTMAP,RLIST
ADDRESSABILITY TO PARMLIST
TOPLOOP EQU *
LOOP FOR EACH DSCB
XC
BUFLIST(BFLHLN+BFLELN),BUFLIST ZERO BUFFER LIST
OI
BFLHFL,BFLHDSCB
DSCBS TO BE READ WITH BUFFER LIST
MVI BFLHNOE,1
ONE BUFFER LIST ENTRY
L
RWORK,LISTDSCB
ADDRESS OF DSCB BUFFER
ST
RWORK,BFLEBUF
PLACE IN BUFFER LIST
OI
BFLEFL,BFLETTR
TTR OF DSCB RETURNED BY CVAF
MVI BFLELTH,DSCBLTH
DATA PORTION OF DSCB READ - DSN
*
SUPPLIED IN CVPL
L
RDSN,LISTDSN
ADDRESS OF DATA SET NAME
Chapter 1. Using the Volume Table of Contents
85
CVAF Macros
NOERROR
RELOOP
CVAFDIR DSN=(RDSN),UCB=(RUCB),MF=(E,CVPL),BRANCH=YES
LA
RTTR,LISTARG
ADDRESS OF TTR TO BE RETURNED
USING TTRMAP,RTTR
MAP OF TTR
LTR REG15,REG15
ANY ERROR
BZ
NOERROR
BRANCH IF NOT
XC
TTR,TTR
ZERO TTR INDICATING NO DSCB
ST
REG15,LISTRC
STORE RC FROM CVAFDIR INTO LISTRC
B
RELOOP
GET NEXT ENTRY
EQU *
DSCB READ
MVC TTR(3),BFLEATTR
RETURN TTR OF DSCB
ST
REG15,LISTRC
STORE RC FROM CVAFDIR INTO LISTRC
EQU *
GET NEXT ENTRY
TM
LASTLIST,LASTBIT
IS IT LAST ENTRY IN LIST?
LA
RLIST,NEXTLIST
GET NEXT ENTRY
BZ
TOPLOOP
PROCESS NEXT LIST
CVAFDIR ACCESS=RLSE,
RELEASE CVAF OBTAINED AREAS
IOAREA=NOKEEP,
RELEASE IOAREA
IXRCDS=NOKEEP,
RELEASE VIER BUFFER LIST
BUFLIST=0,
NO USER BUFFER LIST SUPPLIED TO RLSE
BRANCH=YES,
BRANCH ENTER CVAF
MF=(E,CVPL)
L
13,SAVEAREA+4
RETURN (14,12)
BUFLIST
ICVAFBFL DSECT=NO
BUFFER LIST
SAVEAREA
LISTMAP
LISTDSN
LISTDSCB
*
LISTARG
*
LASTLIST
LASTBIT
LISTTTR
LISTRC
NEXTLIST
DSCB
DS
18F
DSECT
DS
F
DS
F
REGISTER SAVE AREA
DS
0F
*
*
*
*
*
ADDRESS OF DATA SET NAME
ADDRESS OF BUFFER FOR DSCB TO BE
RETURNED
ADDRESS OF FLAG AND TTR
RETURNED
FIRST BYTE
LAST ENTRY IN LIST
REMAINDER OF TTR ADDRESS
RETURN CODE FROM CVAFDIR FOR THIS DSN
NEXT LIST
DS
X
EQU X’80’
DS
XL3
DS
F
EQU *
DSECT
IECSDSL1 (1)
DSCBLTH EQU *-DSCB-L’DS1DSNAM LENGTH OF DATA PORTION OF DSCB
TTRMAP
DSECT
TTRFLG
DS
XL1
FLAG VALUE
TTR
DS
XL3
TTR VALUE
DIRXMP2 CSECT
CVPL
CVAFDIR ACCESS=READ,BUFLIST=BUFLIST,MF=L,
*
IOAREA=KEEP,
KEEP IOAREA TO AVOID OVERHEAD
*
IXRCDS=KEEP,
KEEP VIERS FOR 2ND / SUBSEQUENT CALLS*
BRANCH=(YES,PGM)
CALLED IN PROGRAM STATE BUT APF
*
AUTHORIZED SO UCB IS SUPPLIED
ORG
CVPL
OVERLAY CVPL WITH EXPANSION OF MAP
CVPLMAP ICVAFPL DSECT=NO
END
Example of Using the CVAFDIR macro to read multiple DSCBs
This example uses the CVAFDIR macro to read multiple DSCBs for a VSAM data
set that has 123 extents using the MULTIPLEDSCBS=YES parameter. Refer to the
documentation within the sample source for program logic and expected output.
The following is the sample JCL used to execute the sample source module below.
//*
//**********************************
//* JCL TO EXECUTE CVDIR027 MODULE *
//**********************************
86
z/OS DFSMSdfp Advanced Services
CVAF Macros
//*
//STEP001 EXEC
//STEPLIB
DD
//SYSPRINT DD
//CVAFDD
DD
//OUTDD
DD
//*
PGM=CVDIR027
DISP=SHR,DSN=YOUR.TEST.LOAD
SYSOUT=*
DISP=SHR,UNIT=3390,VOL=SER=1P9503
SYSOUT=*
/* VSAM01 VOLSER */
/* OUTPUT DATASET */
The following is the CVAFDIR sample source to read multiple DSCBs.
CVDIR027 CSECT
CVDIR027 AMODE 31
CVDIR027 RMODE 24
*
***********************************************************************
*
*
*
CVDIR027 - MODULE THAT ISSUES THE CVAFDIR MACRO WHICH RETURNS
*
*
THE DSCBS FOR A GIVEN DATASET USING THE KEYWORDS
*
*
MULTIPLEDSCBS=YES AND EADSCB=OK.
*
*
*
*
THIS MODULE USES A PASSED DSN (SEARCH) AND ISSUES THE *
*
CVAFDIR MACRO TO PERFORM A READ OF ALL DSCBS FOR THE *
*
DATASET. THE DATASET PROCESSED IS VSAM AND HAS 123
*
*
EXTENTS. THE DSN IS CVAFDIR1.VSAM01.DATA.
*
*
*
*
THE CVAFDIR MACRO CALL WILL USE THE FOLLOWING:
*
*
EADSCB=OK CODED
*
*
MULTIPLEDSCBS=YES CODED
*
*
*
*
*
*
THIS MODULE HAS BEEN WRITTEN TO RUN AT THE Z/OS 1.10 *
*
LEVEL AND WILL CREATE A SLIGHTLY DIFFERENT OUTPUT
*
*
REPORT DEPENDENT UPON DEVICE TYPE (EAV OR NON EAV).
*
*
THE NUMBER OF BUFFER LIST ENTRIES NEEDED WILL BE 11
*
*
FOR A NON EAV DEVICE AND THE NUMBER OF BUFFER LIST
*
*
ENTRIES NEEDED WILL BE 12 FOR AN EAV DEVICE TO
*
*
ACCOUNT FOR THE FORMAT 9 DSCB.
*
*
*
*
*
*
THIS MODULE WILL CREATE AN OUTPUT REPORT DIRECTED TO *
*
THE OUTDD DD THAT SHOULD LOOK LIKE THE FOLLOWING:
*
*
*
*---------------------------------------------------------------------*
*
*
*
NON EAV VOLUME
*
*
-------------*
*
*
*
CVDIR027 START OF OUTPUT MESSAGES
*
*
*
*
PROCESSING DSN: CVAFDIR1.VSAM01.DATA
*
*
CVAFDIR CALL: EADSCB=OK AND MULTIPLEDSCBS=YES CODED
*
*
CV4EADOK BIT SET / EADSCB=OK
*
*
CV4MULTD BIT SET / MULTIPLEDSCBS=YES
*
*
RC00 VERIFIED - THE REQUEST WAS SUCCESSFUL
*
*
X"00"
DEC"000"
00 - CVSTAT CODE VERIFIED
*
*
BUFFER LIST ENTRIES PROVIDED: 12
*
*
BUFFER LIST ENTRIES NEEDED : 11
*
*
*
*
CVDIR027 END OF OUTPUT MESSAGES
*
*
*
*
*
*
*
*
EAV VOLUME
*
*
---------*
*
*
*
CVDIR027 START OF OUTPUT MESSAGES
*
*
*
Chapter 1. Using the Volume Table of Contents
87
CVAF Macros
*
PROCESSING DSN: CVAFDIR1.VSAM01.DATA
*
*
CVAFDIR CALL: EADSCB=OK AND MULTIPLEDSCBS=YES CODED
*
*
CV4EADOK BIT SET / EADSCB=OK
*
*
CV4MULTD BIT SET / MULTIPLEDSCBS=YES
*
*
RC00 VERIFIED - THE REQUEST WAS SUCCESSFUL
*
*
X"00"
DEC"000"
00 - CVSTAT CODE VERIFIED
*
*
BUFFER LIST ENTRIES PROVIDED: 12
*
*
BUFFER LIST ENTRIES NEEDED : 12
*
*
*
*
CVDIR027 END OF OUTPUT MESSAGES
*
*
*
*
*
*
*
***********************************************************************
*
*
*
CVDIR027 - LOGIC NOTES
*
*
*
*
THIS MODULE WILL PERFORM THE FOLLOWING:
*
*
*
*
INITIALIZATION
*
*
- OBTAIN THE NECESSARY INFORMATION FROM THE DASD VOLUME
*
*
- OPEN AN OUTPUT FILE AND WRITE THE NECESSARY OUTPUT MESSAGES
*
*
*
*
MAINLINE
*
*
- INVOKE SETU1RTN TO SETUP BUFFER LIST FOR 12 ENTRIES
*
*
- INVOKE VSAM1RTN TO PROCESS VSAM01 DSN
*
*
- INVOKE READRTN - EADSCB=OK AND MULTIPLEDSCBS=YES CODED
*
*
- CHECK CV4FL BIT SETTINGS AFTER CVAFDIR CALL
*
*
- CHECK RC AND CVSTAT CODES RETURNED
*
*
- CHECK BUFFERS PROVIDED AND BUFFERS NEEDED FROM BUFFER LIST
*
*
- WRITE OUTPUT RECS
*
*
- ISSUE CVAFDIR TO RELEASE WORK AREAS
*
*
- WRITE OUTPUT RECS
*
*
*
*
*
*
FINALIZATION
*
*
- CLOSE THE OUTPUT FILE
*
*
- EXIT
*
*
*
*
*
*
CVDIR027 - JOB INFORMATION
*
*
*
*
NORMAL END OF JOB:
*
*
- RC=00 AND OUTDD OUTPUT AS DETAILED ABOVE
*
*
*
*
*
*
ABNORMAL END OF JOB:
*
*
- ABEND 100 - ERROR OPENING VTOC ON THE DASD VOLUME THAT IS
*
*
ASSOCIATED WITH THE CVAFDD DD STATEMENT
*
*
- ABEND 101 - ERROR OPENING THE OUTDD DATASET
*
*
- ABEND 102 - ERROR CLOSING THE OUTDD DATASET
*
*
*
*
*
*
*
*
*
***********************************************************************
*
***********************************************************************
*
*
* HOUSEKEEPING
*
* - SAVE CALLER’S REGISTERS AND ESTABLISH A NEW REGISTER SAVE AREA
*
*
*
***********************************************************************
*
STM R14,R12,12(R13)
STANDARD LINKAGE CONVENTION
BALR R11,0
DCL R11 AS IMPLIED BASE REG
USING BASE,R11,R12
R12 IS ALSO BASE REG
88
z/OS DFSMSdfp Advanced Services
CVAF Macros
BASE
L
R12,BASEADDR
SET UP ADDRESSING FOR R12
B
CV000000
BRANCH AROUND DECLARES
BASEADDR DC
A(BASE+4096)
ADDRESSING FOR R12
CV000000 DS
0H
CONTINUE...
ST
R13,SAVE+4
SAVE PTR TO CALLER’S SAVE AREA
LA
R14,SAVE
GET ADDRESS OF THE NEW SAVE AREA
ST
R14,8(,R13)
CHAIN CALLER’S AREA TO OURS
LR
R13,R14
ESTABLISH THE NEW SAVE AREA
*
***********************************************************************
*
*
* INITIALIZATION
*
*
*
***********************************************************************
*
INITIAL DS
0H
INITIALIZATION SECTION
BAL R14,IDVOLRTN
INVOKE RTN TO IDENTIFY THE VOLUME
OPEN (OUTFILE,(OUTPUT)) OPEN THE OUTDD OUTPUT FILE
TM
OUTFILE+48,X’10’
TEST IF FILE IS OPEN (OUTFILE)
BO
INIT0010
IF OPEN OK - BRANCH AROUND ABEND
ABEND 101
ELSE ISSUE USER ABEND 101
INIT0010 DS
0H
FILE IS OPEN WRITE START MESSAGE
PUT OUTFILE,STRTMSG
WRITE A RECORD TO THE OUTPUT FILE
PUT OUTFILE,BLNKLINE
WRITE A RECORD TO THE OUTPUT FILE
*
***********************************************************************
*
*
* MAINLINE
*
*
*
***********************************************************************
*
MAINLINE DS
0H
MAINLINE SECTION
*
MAIN0010 DS
0H
PROCESS CVAFDIR1.VSAM01.DATA DATASET
*
BAL R14,SETU1RTN
SETUP FOR CVAFDIR - 12 ENTRIES
BAL R14,VSAM1RTN
PROCESS VSAM01 DATASET ROUTINE
PUT OUTFILE,BLNKLINE
WRITE A RECORD TO THE OUTPUT FILE
*
*
***********************************************************************
*
*
* FINALIZATION
*
*
*
***********************************************************************
*
FINAL
DS
0H
FINALIZATION SECTION
PUT OUTFILE,ENDMSG
WRITE A RECORD TO THE OUTPUT FILE
CLOSE (OUTFILE)
CLOSE OUTPUT FILE
C
R15,RCODE00
IF FILE CLOSE IS OK
BE
FINL0010
BRANCH AROUND ABEND
ABEND 102
ELSE ISSUE USER ABEND 102
FINL0010 DS
0H
EXIT MODULE
L
R13,4(R13)
RESTORE REGISTER
LM
R14,R12,12(R13)
RESTORE CALLERS REGISTERS
LA
R15,0
SET RC TO 0
BR
R14
RETURN TO CALLER
*
***********************************************************************
*
IDVOLRTN
*
*
- OBTAIN THE NECESSARY INFORMATION FROM THE DASD VOLUME
*
***********************************************************************
*
IDVOLRTN DS
0H
IDENTIFY VOLUME ROUTINE
ST
R14,IDVLSAVE
STORE C(R14) INTO SAVE AREA
RDJFCB (VTOCDCB,(INPUT)) READ JFCB / OPEN VTOC
MVI JFCB1,X’04’
PUT IN ID FOR FORMAT 4
Chapter 1. Using the Volume Table of Contents
89
CVAF Macros
MVC JFCB1+1(43),JFCB1 SETUP FOR VTOC OPEN
OPEN (VTOCDCB,(INPUT)),TYPE=J OPEN VTOC (OPEN TYPE=J)
TM
VTOCDCB+48,X’10’
IF OPEN OF VTOC IS OK
BO
IDVL0010
BRANCH AROUND ABEND
ABEND 100
ELSE ISSUE USER ABEND 100
IDVL0010 DS
0H
SLR R4,R4
INIT REG4 FOR DEB PTR
SLR R5,R5
INIT REG5 FOR UCB PTR
ICM R4,B’0111’,VTOCDCB+45 GET DEB ADDRESS
ST
R4,DEBADD
STORE C(R4) INTO DEBADD
ICM R5,B’0111’,33(R4) GET UCB ADDRESS
ST
R5,UCBADD
STORE UCB ADDRESS
IDVLEXIT DS
0H
EXIT FROM IDVOLRTN
L
R14,IDVLSAVE
LOAD C(IDVLSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
SETU1RTN
*
*
- SETUP FOR CVAFDIR - BFLHNOE = 12
*
*
- WILL SETUP 12 ENTRIES FOR CVAFDIR CALL
*
*
- CVAFDIR READ CALL (SEARCH) PASSED DSN
*
*
- 96 BYTE BUFFER - 1ST BUFFER
*
*
- 140 BYTE BUFFERS - REMAINING BUFFERS
*
*
- DSNAME=DSN WILL BE USED FOR SEARCH
*
*
- CCHHR = ZERO
*
***********************************************************************
*
SETU1RTN DS
0H
SETUP FOR CVAFDIR CALL
ST
R14,SET1SAVE
STORE C(R14) INTO SAVE AREA
LA
R4,BUFLHDR
GET ADDR OF BUF LIST HEADER
L
R5,NBRENT
LOAD R5 WITH NBR OF ENTRIES (12)
USING BFLHDR,R4
GET ADDRESSABILITY TO HEADER
MVI BFLHNOE,TWELVE
INDICATE 12 ENTRIES
MVI BFLHKEY,BFLHDSCB
INDICATE READ DSCB
LA
R6,DSCBBUF
LOAD R6 WITH ADDR OF 1ST DSCB BUFFER
LA
R7,BUFLIST1
LOAD R7 WITH ADDR OF BUFLIST1
USING BFLE,R7
GET ADDRESSABILITY TO ENTRY
*
* INITIALIZE 1ST ENTRY
*
OI
BFLEFL,BFLECHR
INDICATE CCHHR TO BE READ
MVC BFLEARG(5),CCHHR0 SET ZEROES FOR ARGUMENT
MVI BFLELTH,DSCBL96
GET LENGTH OF BUFFER
ST
R6,BFLEBUF
PUT DSCB BUF ADDR IN ENTRY
LA
R7,ENTLENG(,R7)
INCREMENT ADDR TO NEXT ENTRY
LA
R6,DSCBL96(,R6)
INCREMENT ADDR TO NEXT DSCB BUFFER
S
R5,ONE
C(R5) = C(R5) - 1
*
* INITIALIZE REMAINING ENTRIES
*
SETU0010 DS
0H
INIT REMAINING 140 BYTE BUFFERS
OI
BFLEFL,BFLECHR
INDICATE CCHHR TO BE READ
MVI BFLELTH,DSCBL140
GET LENGTH OF BUFFER
ST
R6,BFLEBUF
PUT DSCB BUF ADDR IN ENTRY
LA
R7,ENTLENG(,R7)
INCREMENT ADDR TO NEXT ENTRY
LA
R6,DSCBL140(,R6)
INCREMENT ADDR TO NEXT DSCB BUFFER
BCT R5,SETU0010
BRANCH TO SETU0010 IF MORE ENTRIES
SET1EXIT DS
0H
EXIT FROM SETU1RTN
L
R14,SET1SAVE
LOAD C(SAVE AREA) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
VSAM1RTN
*
*
- PROCESS VSAM01 DATASET ROUTINE
*
*
- CVAFDIR READ: EADSCB=OK AND MULTIPLEDSCBS=YES CODED *
*
- CHECK RC / CVSTAT CODES
*
*
- ISSUE CVAFDIR RELEASE
*
90
z/OS DFSMSdfp Advanced Services
CVAF Macros
***********************************************************************
*
VSAM1RTN DS
0H
PROCESS VSAM01 DATASET ROUTINE
ST
R14,VSAMSAVE
STORE C(R14) INTO SAVE AREA
MVC DSNAME(44),VSAM01 DSNAME=CVAFDIR1.VSAM01.DATA
PUT OUTFILE,VSAM1MSG
WRITE A RECORD TO THE OUTPUT FILE
PUT OUTFILE,CALLMR11
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,READRTN
READRTN - EADSCB=OK/MULTIPLEDSCBS=YES
L
R15,RETCODE
LOAD R15 WITH SAVED RETURN CODE
C
R15,RCODE00
IF RC FROM READ IS EQUAL TO ZERO
BE
VSAM0010
BRANCH TO VSAM0010
PUT OUTFILE,UNEXPMS2
ELSE WRITE RC ERROR MESSAGE
B
VSAM0020
BRANCH TO VSAM0020
VSAM0010 DS
0H
PUT OUTFILE,RC00MSG
WRITE RC00 MESSAGE
VSAM0020 DS
0H
LA
R9,CVAFDIR
GET ADDRESS OF CVAF PARM LIST
USING CVPL,R9
GET ADDRESSABILITY TO CVPL
CLI CVSTAT,STAT000
IF CVSTAT FROM READ IS EQUAL TO ZERO
BE
VSAM0030
BRANCH TO VSAM0030
PUT OUTFILE,UNEXPMS3
ELSE WRITE CVSTAT ERROR MESSAGE
B
VSAM0040
BRANCH TO VSAM0040
VSAM0030 DS
0H
PUT OUTFILE,CV00MSG
WRITE CV00 MESSAGE
VSAM0040 DS
0H
CLI BFLHNOE,X’0C’
IF NUMBER OF BUFFERS PROVIDED = 12
BE
VSAM0050
BRANCH TO VSAM0050
PUT OUTFILE,UNEXPMS4
ELSE WRITE BUFFER ERROR MESSAGE
B
VSAM0060
BRANCH TO VSAM0060
VSAM0050 DS
0H
PUT OUTFILE,BUFSMSG1
WRITE BUFFER MESSAGE
VSAM0060 DS
0H
CLI BFLHNOEN,X’0B’
IF NUMBER OF BUFFERS NEEDED = 11
BE
VSAM0070
BRANCH TO VSAM0070
CLI BFLHNOEN,X’0C’
IF NUMBER OF BUFFERS NEEDED = 12
BE
VSAM0080
BRANCH TO VSAM0080
PUT OUTFILE,UNEXPMS5
ELSE WRITE BUFFER ERROR MESSAGE
B
VSAM0090
BRANCH TO VSAM0090
VSAM0070 DS
0H
PUT OUTFILE,BUFNMSG1
WRITE BUFFER MESSAGE
B
VSAM0090
BRANCH TO VSAM0090
VSAM0080 DS
0H
PUT OUTFILE,BUFNMSG2
WRITE BUFFER MESSAGE
VSAM0090 DS
0H
*
CVAFDIR ACCESS=RLSE,IXRCDS=NOKEEP,BUFLIST=0,
X
MF=(E,CVAFDIR)
*
C
R15,RCODE00
IF RC FROM RLSE IS EQUAL TO ZERO
BE
VSAMEXIT
BRANCH TO VSAMEXIT
PUT OUTFILE,UNEXPMS6
ELSE WRITE RLSE ERROR MESSAGE
*
VSAMEXIT DS
0H
EXIT FROM ROUTINE
DROP R9
DROP R9
L
R14,VSAMSAVE
LOAD C(SAVE AREA) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
READRTN
*
*
- CVAFDIR READ ROUTINE
*
*
MULTIPLEDSCBS=YES IS CODED
*
*
EADSCB=OK IS CODED
*
*
- CHECK CV4FL BIT SETTINGS AFTER READ
*
*
- REPORT ON CV4FL BIT SETTINGS FOR CV4EADOK AND CVMULTD *
***********************************************************************
*
READRTN DS
0H
CVAFDIR READ ROUTINE
Chapter 1. Using the Volume Table of Contents
91
CVAF Macros
ST
L
R14,READSAVE
R2,DEBADD
STORE C(R14) INTO SAVE AREA
LOAD R2 WITH DEB ADDRESS
*
CVAFDIR ACCESS=READ,DEB=(R2),BUFLIST=BUFLHDR,MAPRCDS=YES,
DSN=DSNAME,MULTIPLEDSCBS=YES,EADSCB=OK,
MF=(E,CVAFDIR)
X
X
*
ST
R15,RETCODE
STORE RC INTO RETCODE
LA
USING
CLI
BE
CLI
BE
CLI
BE
PUT
B
DS
PUT
PUT
B
DS
PUT
PUT
B
DS
PUT
PUT
DS
DROP
L
BR
R9,CVAFDIR
CVPL,R9
CVFL4,CV4EADOK
READ0010
CVFL4,CV4MULTD
READ0020
CVFL4,BOTH
READ0030
OUTFILE,UNEXPMS1
READEXIT
0H
OUTFILE,OKMSG
OUTFILE,NOMULTMS
READEXIT
0H
OUTFILE,NOTOKMSG
OUTFILE,MULTMSG
READEXIT
0H
OUTFILE,OKMSG
OUTFILE,MULTMSG
0H
R9
R14,READSAVE
R14
GET ADDRESS OF CVAF PARM LIST
GET ADDRESSABILITY TO CVPL
IF CVFL4 = X’10’ CV4EADOK ONLY
BRANCH TO READ0010
IF CVFL4 = X’08’ CV4MULTD ONLY
BRANCH TO READ0020
IF CVFL4 = X’18’ CV4MULTD/CV4EADOK
BRANCH TO READ0030
ELSE WRITE ERROR RECORD PL
BRANCH TO EXIT ROUTINE
WRITE MESSAGES X’10’
WRITE OK MSG RECORD
WRITE NO MULTI MSG RECORD
BRANCH TO EXIT ROUTINE
WRITE MESSAGES X’08’
WRITE NOTOK MSG RECORD
WRITE MULTI MSG RECORD
BRANCH TO EXIT ROUTINE
WRITE MESSAGES X’18’
WRITE OK MSG RECORD
WRITE MULTI MSG RECORD
EXIT FROM READRTN
DROP R9
LOAD C(SAVE AREA) INTO R14
EXIT
*
READ0010
READ0020
READ0030
READEXIT
*
***********************************************************************
*
WORKING STORAGE
*
***********************************************************************
*
DS
0D
DC
CL36’CVDIR027-WORKING STORAGE BEGINS HERE’
*
***********************************************************************
*
EQUATES
*
***********************************************************************
*
R0
EQU
0
R1
EQU
1
R2
EQU
2
R3
EQU
3
R4
EQU
4
R5
EQU
5
R6
EQU
6
R7
EQU
7
R8
EQU
8
R9
EQU
9
R10
EQU 10
R11
EQU 11
R12
EQU 12
R13
EQU 13
R14
EQU 14
R15
EQU 15
BOTH
EQU X’18’
TWELVE
EQU X’0C’
*
***********************************************************************
*
SAVE AREAS
*
92
z/OS DFSMSdfp Advanced Services
CVAF Macros
***********************************************************************
*
SAVE
DC
18F’0’
MAIN PROGRAM SAVE AREA
IDVLSAVE DC
F’0’
IDENTIFY VOLUME ROUTINE SAVE AREA
READSAVE DC
F’0’
CVAFDIR READ ROUTINE SAVE AREA
SET1SAVE DC
F’0’
SETUP ROUTINE SAVE AREA
VSAMSAVE DC
F’0’
VSAM01 ROUTINE SAVE AREA
*
***********************************************************************
*
CONSTANTS
*
***********************************************************************
*
CCHHR0
DS
XL5’00’
CCHHR ARGUMENT - ZERO
NBRENT
DC
F’12’
CONSTANT-12 NUMBER OF BUFFER ENTRIES
RCODE00 DC
F’0’
RETURN CODE 0
ONE
DC
F’1’
CONSTANT - ONE
VSAM01
DC
CL44’CVAFDIR1.VSAM01.DATA’
*
***********************************************************************
*
PROGRAM BUFFERS
*
***********************************************************************
*
BUFLIST DS
0F
BUFFER LIST DECLARATIONS
BUFLHDR DC
2F’0’
BUFFER LIST HEADER
BUFLIST1 DC
3F’0’
BUFFER LIST ENTRY 1
ENTLENG EQU *-BUFLIST1
ENTRY LENGTH - 12
BUFLIST2 DC
3F’0’
BUFFER LIST ENTRY 2
BUFLIST3 DC
3F’0’
BUFFER LIST ENTRY 3
BUFLIST4 DC
3F’0’
BUFFER LIST ENTRY 4
BUFLIST5 DC
3F’0’
BUFFER LIST ENTRY 5
BUFLIST6 DC
3F’0’
BUFFER LIST ENTRY 6
BUFLIST7 DC
3F’0’
BUFFER LIST ENTRY 7
BUFLIST8 DC
3F’0’
BUFFER LIST ENTRY 8
BUFLIST9 DC
3F’0’
BUFFER LIST ENTRY 9
BUFLISTA DC
3F’0’
BUFFER LIST ENTRY 10
BUFLISTB DC
3F’0’
BUFFER LIST ENTRY 11
BUFLISTC DC
3F’0’
BUFFER LIST ENTRY 12
*
DSCBBUF DS
XL96
DSCB BUFFER DECLARATION 1 - 96 BYTE
DSCBL96 EQU *-DSCBBUF
LENGTH - 96
DSCBBUF2 DS
XL140
DSCB BUFFER DECLARATION 2 - 140 BYTE
DSCBL140 EQU *-DSCBBUF2
LENGTH - 140
DSCBBUF3 DS
XL140
DSCB BUFFER DECLARATION 3 - 140 BYTE
DSCBBUF4 DS
XL140
DSCB BUFFER DECLARATION 4 - 140 BYTE
DSCBBUF5 DS
XL140
DSCB BUFFER DECLARATION 5 - 140 BYTE
DSCBBUF6 DS
XL140
DSCB BUFFER DECLARATION 6 - 140 BYTE
DSCBBUF7 DS
XL140
DSCB BUFFER DECLARATION 7 - 140 BYTE
DSCBBUF8 DS
XL140
DSCB BUFFER DECLARATION 8 - 140 BYTE
DSCBBUF9 DS
XL140
DSCB BUFFER DECLARATION 9 - 140 BYTE
DSCBBUFA DS
XL140
DSCB BUFFER DECLARATION 10- 140 BYTE
DSCBBUFB DS
XL140
DSCB BUFFER DECLARATION 11- 140 BYTE
DSCBBUFC DS
XL140
DSCB BUFFER DECLARATION 12- 140 BYTE
*
***********************************************************************
*
PROGRAM MESSAGES
*
***********************************************************************
*
BLNKLINE DC
CL80’ ’
STRTMSG DC
CL80’CVDIR027 START OF OUTPUT MESSAGES
’
ENDMSG
DC
CL80’CVDIR027 END OF OUTPUT MESSAGES
’
VSAM1MSG DC
CL80’ PROCESSING DSN: CVAFDIR1.VSAM01.DATA
’
CALLMR11 DC CL80’ CVAFDIR CALL: EADSCB=OK AND MULTIPLEDSCBS=YES CODED’
OKMSG
DC
CL80’ CV4EADOK BIT SET / EADSCB=OK
’
NOTOKMSG DC
CL80’ CV4EADOK BIT NOT SET / EADSCB=NOTOK
’
MULTMSG DC
CL80’ CV4MULTD BIT SET / MULTIPLEDSCBS=YES
’
NOMULTMS DC
CL80’ CV4MULTD BIT NOT SET / MULTIPLEDSCBS=NO
’
RC00MSG DC
CL80’ RC00 VERIFIED - THE REQUEST WAS SUCCESSFUL
’
Chapter 1. Using the Volume Table of Contents
93
CVAF Macros
CV00MSG DC
CL80’ X"00"
DEC"000"
00 - CVSTAT CODE VERIFIED ’
BUFSMSG1 DC
CL80’ BUFFER LIST ENTRIES PROVIDED: 12
’
BUFNMSG1 DC
CL80’ BUFFER LIST ENTRIES NEEDED : 11
’
BUFNMSG2 DC
CL80’ BUFFER LIST ENTRIES NEEDED : 12
’
UNEXPMS1 DC
CL80’ ERROR: UNEXPECTED BIT SETTING FOR CVFL4
’
UNEXPMS2 DC
CL80’ ERROR: UNEXPECTED RETURN CODE FROM CVAFDIR READ ’
UNEXPMS3 DC
CL80’ ERROR: UNEXPECTED CVSTAT CODE FROM CVAFDIR READ ’
UNEXPMS4 DC
CL80’ ERROR: UNEXPECTED NUMBER OF BUFFERS PROVIDED
’
UNEXPMS5 DC
CL80’ ERROR: UNEXPECTED NUMBER OF BUFFERS NEEDED
’
UNEXPMS6 DC
CL80’ ERROR: UNEXPECTED RETURN CODE FROM CVAFDIR RLSE ’
*
***********************************************************************
*
WORK AREAS
*
***********************************************************************
*
DEBADD
DC
F’0’
DEB ADDRESS SAVE AREA
UCBADD
DC
F’0’
UCB ADDRESS SAVE AREA
RETCODE DC
F’999’
RETURN CODE SAVE AREA
DSNAME
DS
CL44
DSNAME
*
***********************************************************************
*
DCB - OUTPUT FILE (OUTFILE)
*
***********************************************************************
*
OUTFILE DCB DDNAME=OUTDD,
X
DSORG=PS,
X
RECFM=FB,
X
LRECL=80,
X
MACRF=PM
*
***********************************************************************
*
VTOC DCB AREA
*
***********************************************************************
*
VTOCDCB DCB DDNAME=CVAFDD,MACRF=E,EXLST=XLST1,DSORG=PS,DCBE=VTOCDCBE
XLST1
DC
X’87’
DC
AL3(JFCB1)
JFCB1
DS
0CL176
TESTNAME DS
CL44
DS
CL8
DS
BL1
DS
CL123
*
VTOCDCBE DCBE EADSCB=OK
*
***********************************************************************
*
CVAF DECLARATIONS
*
***********************************************************************
*
CVAFDIR CVAFDIR MF=L
*
***********************************************************************
*
MAPPING MACROS
*
***********************************************************************
*
ICVAFPL
ICVAFBFL
DSECT
IECSDSL1 (1,3,8,9)
*
*
END CVDIR027
END OF CVDIR027
/*
94
z/OS DFSMSdfp Advanced Services
CVAF Macros
CVAFDSM Macro Overview and Specification
The CVAFDSM macro is used to obtain volume information for an indexed or
nonindexed VTOC.
The CVAFDSM macro can be used for an indexed VTOC to obtain:
v One or more extents that describe unallocated space on the volume
v A count of free DSCBs on the VTOC
v A count of free VTOC index records in the VTOC index.
v A value that represents the highest allocated DSCB as determined by the VTOC
INDEX.
The CVAFDSM macro can be used for an nonindexed VTOC to obtain:
v One or more extents that describe unallocated space on the volume
The format of the CVAFDSM macro is:
►►
CVAFDSM ACCESS=MAPDATA
,MAP=
INDEX
VOLUME
VTOC
label
►
,EXTENTS=addr
►
►
NO
YES
,RTA4BYTE=
(1)
,MAPRCDS=
YES
(YES,addr)
(2)
NO
(NO,addr)
,UCB= (ucbaddr)
,DEB=addr
►
►
,COUNT=
NO
YES
,CTAREA=addr
,HADSCB=addr
►
►
,IOAREA=
NOKEEP
KEEP
(KEEP,addr)
(NOKEEP,addr)
NO
(3)
YES
(YES,SUP)
(YES,PGM)
,BRANCH,
,EADSCB=
NOTOK
OK
►
►◄
,MF=
I
L
(E,addr)
Notes:
1
Default if MF=I.
2
Default if MF=L or MF=(E, addr).
3
If YES is coded, the default is SUP.
ACCESS: Request Information from Index Space Maps or the
VTOC
ACCESS=MAPDATA
Obtains data from index space maps or free space DSCBs.
The following data is available from the index space maps:
Chapter 1. Using the Volume Table of Contents
95
CVAF Macros
v The number of format-0 DSCBs (the data is obtained from the VTOC map of
DSCBs)
v The number of unallocated VIRs in the index (the data is obtained from the
VTOC index map)
v The number (and location) of extents of unallocated pack space (the data is
obtained from the VTOC pack space map).
The following data is available from nonindexed VTOCs:
v The number (and location) of extents of unallocated pack space.
MAP: Identify the Map to Be Accessed
MAP=INDEX
Specifies that the VTOC index map (VIXM) is to be accessed and a count of
unallocated VIRs returned. COUNT=YES must also be coded.
MAP=VOLUME
For indexed VTOCs, specifies that the VTOC pack space map (VPSM) is to be
accessed and information on unallocated extents of pack space returned.
For nonindexed VTOCs, specifies that the information from the free space
DSCBs on unallocated extents is to be returned.
For indexed and nonindexed VTOCs, EXTENTS=addr and COUNT=NO must
also be coded.
MAP=VTOC
Specifies that the VTOC map of DSCBs (VMDS) is to be accessed and a count
of format-0 DSCBs returned. COUNT=YES must also be coded.
EXTENTS: Storage Area Where Extents Are Returned
EXTENTS=addr
Specifies the address where extent information is to be returned. You specify
this parameter only when you also specify MAP=VOLUME to request that
unallocated space information from the volume is to be returned.
When RTA4BYTE=YES is specified the following occurs:
v Information about free extents uses mapping macro ICVEDT02 (see “Using
Macro ICVEDT02 to Map the Extents Area” on page 63 for ICVEDT02
format).
v EXTENTS= specifies the address of a control block (ICVEDT02) used to pass
4 byte relative track addresses of the unallocated space. You provide this
storage, and you must use this mapping macro to initialize it.
Prior to calling CVAF, initialize the ICVEDT02 control block as follows:
– Place “ICVEDT02” in the first 8 bytes (DT2X7EYE).
– Place the total area length, in bytes, in DT2X7LEN. This value is 36 + (8 *
the value in DT2X7ENT).
– Set the control block level number to “1” (DT2X7LEV). (Note that this
value can be different in a possible future release, if IBM makes changes
that effect the control block.)
– Set the remaining fields in the control block static area DT2X7FLG
through DT2X7RE2 to zero prior to calling CVAF for the first time. Leave
these fields unchanged from the way the previous call returned them,
when calling for additional extents.
– Set DT2X7ENT to the total number of extent descriptor entries that will fit
in the storage you provide.
96
z/OS DFSMSdfp Advanced Services
CVAF Macros
– Place the relative track address (RTA) at which CVAF should start the
search into the first four bytes of the first extent area DT2RTAST(1).
CVAF updates the first extent entry with information about the next free
extent found that has a higher starting RTA than that provided. Each
subsequent extent entry is filled in with information about additional free
space extents (in ascending RTA order).
For all calls, if all the unallocated extents from the volume are returned
before the provided storage area is filled, the remaining entries are set to
zero. CVAF will now set return code 4 in register 15, and will set the
CVSTAT field to X'20' to indicate end of data.
If End Of Data is reached before the provided storage area is filled with
unallocated extents, CVAF will set return code 4 in register 15. If return
code 0 is set in register 15, you can call CVAF again to get the remaining
unallocated space information if there is any. Do NOT modify ANY
header information in ICVEDT02, as CVAF can have saved internal use
restart information there. Instead, copy the last ending RTA+1
(DT2RTAED) returned from the previous CVAF search into DT2RTAST.
When RTA4BYTE=NO is specified or defaulted the following occurs:
v Information about free extents has the format of XXYYZ (see “RTA4BYTE:
Specify the Type of Extent Area Used” for XXYYZ format).
v EXTENTS= is the address of a 1-byte count field containing the number of
5-byte entries that follow. You provide this storage area. The length of the
area, in bytes, is 1 + ( count * 5), where count is the value of the first byte of
the area. The first two bytes (“XX”) of the first 5-byte extent area entry, is the
relative track address (RTA) at which CVAF will start the search. CVAF
updates the first entry with information about the next free extent found
that has a higher starting RTA than that supplied. Each subsequent entry is
filled in with information about additional free extents (in ascending track
address order).
v CVAF can be called multiple times, as needed, to retrieve more extents than
the area can hold in a single call. The first extent returned is the first free
extent after the relative track address (“XX”) recorded in the first extent
(XXYYZ) in the area.
v To retrieve the first free extent on the volume, set “XX” in the first entry to
zero. When calling additional times, set “XX” in the first entry to the LAST
relative track address returned by the previous call.
Recommendation: If you use larger volumes, specify RTA4BYTE=YES when
you request extent information. If an extent is beyond the 64x1024 tracks
boundary when the program specifies RTA4BYTE=NO or allows the default,
the CVAF request fails with a CVSTAT of STAT075.
RTA4BYTE: Specify the Type of Extent Area Used
RTA4BYTE=YES
Specifies that the extents area contains pairs of addresses in the format RTA
RTA+1, where RTA is the four byte relative address of the first track of the
extent, and RTA+1 is the four byte relative address of the last track of the
extent plus 1.
You must use the macro ICVEDT02 to map the extent area if you specify
RTA4BYTE=YES. See Table 19 on page 63 for a description.
RTA4BYTE=YES is a required parameter for an nonindexed VTOC, and
optional for an indexed VTOC.
Chapter 1. Using the Volume Table of Contents
97
CVAF Macros
RTA4BYTE=NO
Specifies that the extents area is in the format XXYYZ where:
XX
YY
Z
The relative track address of the first track of the extent
The number of whole cylinders in the extent
The number of additional tracks in the extent.
If you do not specify the RTA4BYTE parameter, the default is RTA4BYTE=NO.
MAPRCDS: Keep or Free MAPRCDS Buffer List and Buffers
MAPRCDS=YES
Specifies that the buffer list and buffers are to be retained at the end of the
function.
If MAPRCDS=YES is specified and no buffer list is supplied through the CVAF
parameter list, CVAF reads the VIRs into buffers obtained by CVAF. The buffer
list that contains the address and RBAs of the VIRs can be accessed after the
CVAF call from the CVAF parameter list field, CVMRCDS. The buffer list and
VIR buffers are in the caller's protect key: subpool 0 if the caller is not
authorized; subpool 229 if the caller is authorized.
MAPRCDS=YES is the default if MF=I is specified or defaulted.
When processing on the current volume is finished, release all areas that were
kept.
MAPRCDS=(YES,addr)
If MAPRCDS=YES is coded, but the buffer list address (CVMRCDS in CVAF
parameter list) is supplied, the VIRs are not read.
The CVMRCDS buffer list from one CVAF call can be passed to another CVAF
macro call through the MAPRCDS keyword.
MAPRCDS=NO
Specifies that the MAP records buffers and buffer list are freed upon
completion of the CVAFDSM function.
NO is the default if MF=L is specified.
MAPRCDS=(NO,addr)
Frees buffer lists and buffers previously obtained by CVAF.
Buffer lists and buffers obtained by CVAF must be freed by the caller. This can be
done in one of the following ways:
v By coding MAPRCDS=NO on the call that obtained the buffers
v By coding MAPRCDS=NO on a subsequent CVAF call
v By coding CVAFDIR ACCESS=RLSE and providing the buffer list in the
BUFLIST keyword.
If MF=(E,addr) is coded and MAPRCDS is not coded, the parameter list value of
MAPRCDS is not changed.
Requirement: You must enqueue the VTOC and reserve the unit to maintain the
integrity of the MAP records read.
UCB or DEB: Specify the VTOC to Be Accessed
UCB= rs-type or (2-12) standard form UCB= rx-type or (2-12) execute form
Specifies the address of the UCB for the VTOC to be accessed. The UCB
address can be for a captured UCB, or for an actual UCB above or below the
98
z/OS DFSMSdfp Advanced Services
CVAF Macros
16MB line. Use the address of a UCB, not a UCB copy. An unauthorized caller
can not use this parameter. If your program is in 31-bit mode, this address
must be in 31-bit address; the high order byte is part of the address. You
should not code the UCB parameter with MF=L.
DEB=addr
Supplies the address of a DEB opened to the VTOC you want to access. CVAF
does not allow output requests to the VTOC or VTOC index if you specify the
DEB subparameter. Without authorization, you cannot perform any
asynchronous activity (such as EXCP, CLOSE, EOV) against the data set
represented by the DEB because CVAF removes the DEB from the DEB table
for the duration of the CVAF call. If you are not authorized (neither APF
authorized nor in a system key), specify a DEB address, not a UCB, to
CVAFDSM. See “Identifying the Volume” on page 58 for further details.
If you supply a previously obtained I/O area through the IOAREA keyword,
neither UCB nor DEB need be supplied. Otherwise, supply either a UCB or DEB. If
you supply a UCB address, it is overlaid in the CVPL by the UCB address in the
I/O area. If you supply both the UCB and the DEB addresses in the CVPL, the
DEB address is used and the UCB address in the CVPL is overlaid by the UCB
address in the DEB.
COUNT: Obtain a Count of Unallocated DSCBs or VIRs
COUNT=YES
Indicates that a count of unallocated DSCBs or VIRs in the designated space
map is requested. MAP=VTOC or MAP=INDEX must be specified if
COUNT=YES is coded.
COUNT=NO
Indicates that a count of unallocated DSCBs or VIRs is not desired but, rather,
information on free space on the pack is desired. MAP=VOLUME must be
coded if COUNT=NO is coded or the default.
CTAREA: Supply a Field to Contain the Number of Format-0
DSCBs
CTAREA=addr
Supplies the address of a 4-byte field to contain the number of format-0 DSCBs
when COUNT=YES, MAP=VTOC is specified; or the number of unallocated
VIRs in the VTOC index when COUNT=YES, MAP=INDEX is specified.
HADSCB: Supply a Field to Contain the CCHHR of the Highest
Allocated DSCB
HADSCB=addr
Supplies the address of a 5–byte field to contain the CCHHR of the highest
allocated DSCB in the VTOC when COUNT=YES and MAP=VTOC are
specified.
IOAREA: Keep or Free the I/O Work Area
IOAREA=KEEP
Specifies that the CVAF I/O area associated with the CVAF parameter list is to
be kept upon completion of the CVAF request. IOAREA=KEEP can be coded
with BRANCH=NO only if the caller is authorized (APF or system key).
Chapter 1. Using the Volume Table of Contents
99
CVAF Macros
If IOAREA=KEEP is coded, the caller must call CVAF with IOAREA=NOKEEP
specified at some future time, whether or not any further VTOC access is
required. An example of such a caller is the recovery routine of the caller of
CVAF.
Coding IOAREA=KEEP allows subsequent CVAF requests to be more efficient,
as certain initialization functions can be bypassed. Neither DEB nor UCB need
be specified when a previously obtained CVAF I/O area is supplied; neither
can they be changed.
When IOAREA=KEEP is first issued, CVAF returns the CVAF I/O area in the
CVAF parameter list (CVIOAR). Subsequent calls of CVAF can use that same
parameter list, and CVAF obtains its I/O area from the CVIOAR.
When processing on the current volume is finished, release all areas that were
kept.
IOAREA=(KEEP,addr)
Supplies the address of a previously obtained I/O area. If a different CVAF
parameter list is used, the previously obtained CVAF I/O area can be passed
to CVAF by coding its address as the second parameter of the IOAREA
keyword.
IOAREA=NOKEEP
Causes the work area to be freed upon completion of the CVAF request. This is
the default.
IOAREA=(NOKEEP,addr)
Causes a previously obtained work area to be freed upon completion of the
CVAF request.
BRANCH: Specify the Entry to the Macro
BRANCH=(YES,SUP)
Requests the branch entry. The caller must be in supervisor state. Protect key
checking is bypassed.
If BRANCH=YES is coded, an 18-word save area must be supplied. No lock
can be held on entry to CVAF. SRB mode is not allowed.
BRANCH=YES
Equivalent to BRANCH=(YES,SUP), because SUP is the default when YES is
coded. Protect key checking is bypassed.
BRANCH=(YES,PGM)
Requests the branch entry. The caller must be APF authorized and in problem
state. Protect key checking is bypassed.
BRANCH=NO
Requests the SVC entry. The caller must be APF authorized if any output
operations are requested. Protect key checking is performed. This is the
default.
EADSCB: Specify the support level for extended attribute DSCBs
EADSCB=OK
This specification indicates that the calling program supports RTAs that could
contain tracks an extended address volume.
For calls that request unallocated space (ACCESS=MAPDATA,
MAP=VOLUME, RTA4BYTE=YES and EXTENTS=address), a CVAFDSM
request issued to an EAV volume will be failed if the EADSCB=OK indicator is
not set.
100
z/OS DFSMSdfp Advanced Services
CVAF Macros
The failing error code for these cases will be reflected as follows:
v CVAF status code (CVSTAT) set to STAT082.
v Return code 4.
EADSCB=OK will set the CV4EADOK indicator in the CVPL. All other calls to
CVAFDSM are allowed and EADSCB=OK will be ignored.
EADSCB=NOTOK
Indicates a calling program does not support extended attribute DSCBs.
EADSCB=NOTOK will set the CV4EADOK indicator in the CVPL to off. This
is the default.
MF: Specify the Form of the Macro
This keyword specifies whether the list, execute, or normal form of the macro is
requested.
MF=I
If I is coded or if neither L nor E is coded, the CVAF parameter list is
generated, as is code, to call CVAF. This is the default.
MF=L
Indicates the list form of the macro. A parameter list is generated, but code to
call CVAF is not generated.
MF=(E,addr)
Indicates the execute form of the macro. The remote CVAF parameter list
supplied as addr is used in, and can be modified by, the execute form of the
macro.
Return Codes from CVAFDSM
On return from CVAF, register 1 contains the address of the CVPL (CVAF
parameter list), and register 15 contains one of the following return codes:
Return Code
Meaning
0 (X'00')
4 (X'04')
The request was successful.
End of data (CVSTAT is set to decimal 32), or an error was
encountered. The CVSTAT field in the CVPL contains an
indication of the cause of the error. (CVSTAT code descriptions
are in z/OS DFSMSdfp Diagnosis.)
Invalid VTOC index structure. CVSTAT contains an indication of
the cause of the error. (CVSTAT code descriptions are in z/OS
DFSMSdfp Diagnosis.)
One of the following
v The CVAF parameter list is not in your protect key.
v The CVAF parameter list protect key is invalid.
v The CVAF parameter list ID is invalid.
v The CVAF parameter list length is incorrect.
v The CVAF parameter list has not been modified.
v The function code (CVFCTN) field is not valid.
v The function code (CVFCTN) field is not supported by this
release.
An I/O error was encountered.
8 (X'08')
12 (X'0C')
16 (X'10')
CVAFFILT Macro Overview and Specification
You can use the CVAFFILT macro to invoke the CVAF filter service. You can also
use it to map or initialize the CVAF parameter list (CVPL). CVAF filter retrieves
data set DSCB chains from an indexed or nonindexed VTOC and places them in
Chapter 1. Using the Volume Table of Contents
101
CVAF Macros
buffers you provide. You can request the DSCBs for a single partially-qualified
data set name or for a list of fully-qualified data set names.
Identify a specific DASD device and provide both a filter criteria list (FCL)
defining the request, and a CVAF buffer list (with buffers) for DSCB return. The
format of the two elements of the FCL is shown in Table 20 on page 70 and
Table 21 on page 72. The format of the buffer list is shown in “Using Buffer Lists”
on page 61. CVAFFILT returns a complete set of DSCBs in the order that they are
chained in the VTOC (format-1, format-2, then format-3).
Keywords coded on the list form of the macro need not be coded on the execute
form. Keywords coded on one CVAFFILT call remain in effect for subsequent calls
unless overridden, if you use the same CVAFFILT parameter list.
See “Reading Sets of DSCBs with CVAF Filter” on page 68 for additional
information.
The format of the CVAFFILT macro is:
►►
CVAFFILT
►
label
,ACCESS=
READ
RESUME
RLSE
,BUFLIST=
addr
(reg)
►
►
,UCB= (ucbaddr)
,DEB=addr
,FCL=
addr
(reg)
,FLTAREA=
NOKEEP
KEEP
(KEEP,
addr
)
(reg)
(NOKEEP,
addr
)
(reg)
►
►
,IOAREA=
NOKEEP
KEEP
(KEEP,
,BRANCH=
addr
)
(reg)
(NOKEEP, addr
)
(reg)
NO
YES
(YES,
SUP
PGM
)
►
►◄
,EADSCB=
NOTOK
OK
,MF=
I
D
L
(E,
addr
(reg)
)
Restriction: For the first operand following CVAFFILT, do not code the leading
comma.
Control Block Address Resolution: Keyword=addr or (reg)
You, as the caller, either define or reference the control blocks needed by CVAF
filter. Caller-defined control blocks are: BUFLIST, CVPL, and FCL. Caller-referenced
control blocks are: DEB, FLTAREA, IOAREA, and UCB. The CVAFFILT macro
generates different instructions for keyword=addr and keyword=(reg) depending
upon whether you are specifying a defined or referenced control block.
102
z/OS DFSMSdfp Advanced Services
CVAF Macros
v When you specify any control block's address as (reg), the CVAFFILT macro
assumes that the register specified contains that address.
v When you specify a “defined” control block's address as addr, the CVAFFILT
macro assumes that the specified location is that of the control block itself. The
macro generates a load address instruction (LA) to obtain the control block's
address.
v When you specify a “referenced” control block's address as addr, the CVAFFILT
macro assumes that the specified location is that of a word containing the
address of the control block. The macro generates a load instruction (L) to obtain
the control block's address.
ACCESS: Retrieve a DSCB, or Release FLTAREA and/or IOAREA
ACCESS=READ
Retrieves all DSCBs associated with the data set names specified in the filter
criteria list (FCL), placing them in your buffers. You can select (filter) the
retrieved DSCBs by providing either a list of one or more fully-qualified
names, or a single partially-qualified name, using single or double asterisk
notation. (See the example of partially-qualified names in “Partially-Qualified
Names for CVAFFILT” on page 107.)
If the number of buffers is not large enough to hold all the requested DSCBs,
CVAFFILT indicates this in the CVSTAT status byte of the CVAF parameter list
(CVPL). You can resume the READ function by issuing a call with
ACCESS=RESUME. See “Codes Put in the CVSTAT Field” on page 141.
When selecting DSCBs by partially-qualified name, CVAFFILT uses only the
first data set name in the FCL list. Set the FCLCOUNT count field in the FCL
to 1 or CVAFFILT returns error code 63 in the CVSTAT status byte of the
CVPL. The DSCBs returned by CVAFFILT might not be in sequence by data set
name; however, the DSCBs for each data set are always in order (format-1,
format-2, format-3).
When selecting DSCBs by fully-qualified names, you can request that CVAF
filter return the DSCBs for the selected data set names in the data set name
order implied by the FCL. See the FCL1ORDR flag in Table 20 on page 70.
Always test the status byte of each data set name in the FCL list to ensure
successful completion. (Some error conditions result in failure to return a data
set's DSCBs.) See the FCLDSNST byte in Table 21 on page 72.
ACCESS=RESUME
Resumes a previously initiated READ or RESUME function that was
terminated because you did not provide enough buffers to contain all the
requested DSCBs. For the RESUME function to execute correctly, the keyword
FLTAREA=KEEP must be coded in each of the previous READ and RESUME
function calls.
ACCESS=RLSE
Releases the previously kept filter save area (FLTAREA) and/or CVAF I/O
work area (IOAREA).
BUFLIST: Specify a Buffer List
BUFLIST=addr or (reg)
Supplies the address of a buffer list used to read DSCBs. When you specify
ACCESS=RLSE, the BUFLIST keyword is required for the standard form of the
macro. See the format of the buffer list header and buffer list entry in Table 17
on page 62 and Table 18 on page 63, respectively.
Chapter 1. Using the Volume Table of Contents
103
CVAF Macros
UCB or DEB: Specify the VTOC to Be Accessed
UCB= rs-type or (2-12) standard form UCB= rx-type or (2-12) execute form
Specifies the address of the UCB for the VTOC to be accessed. The UCB
address might be for a captured UCB, or for an actual UCB above or below the
16 MB line. Use the address of a UCB, not a UCB copy. An unauthorized caller
must not use this parameter. If your program is in 31-bit mode, this address
must be in 31-bit address; the high order byte is part of the address. You
should not code the UCB parameter with MF=L.
DEB=addr or (reg)
Supplies the address of a DEB opened to the VTOC you want to access. If you
are not authorized, specify a DEB address, not a UCB, to CVAFFILT; also,
without authorization, you cannot perform any asynchronous activity against
the data set represented by the DEB (such as EXCP, CLOSE, EOV), because
CVAF removes the DEB from the DEB table for the duration of the CVAF call.
See “Identifying the Volume” on page 58 for further details.
If you supply a previously obtained I/O area through the IOAREA keyword,
neither UCB nor DEB is needed. Otherwise, supply either a UCB or DEB. If you
supply a UCB address, it is overlaid in the CVPL by the UCB address in the I/O
area. If you supply both the UCB and the DEB addresses in the CVPL, the DEB
address is used and the UCB address in the CVPL is overlaid by the UCB address
in the DEB.
FCL: Specify a Filter Criteria List
FCL=addr or (reg)
Supplies the address of a filter criteria list. It is required when ACCESS=READ
is specified on the standard form of the macro. The format of the two elements
of the filter criteria list is shown in Table 20 on page 70 and Table 21 on page
72.
FLTAREA: Keep or Free the Filter Save Area
FLTAREA=KEEP
Specifies keeping the filter save area. Code this operand if the RESUME
function might be called later (to resume processing prematurely terminated
because the number of caller-supplied buffers is not enough to contain all the
returned DSCBs).
CVAFFILT returns the address of the kept filter save area in the CVAFFILT
parameter list (CVFSA field). If you specify the same parameter list in
subsequent RESUME calls, CVAFFILT reuses the same filter save area.
Tip: If you code this operand, you must subsequently issue CVAFFILT with
ACCESS=RLSE to release the filter save area.
FLTAREA=(KEEP,addr or (reg))
Supplies the address of a previously obtained filter save area. See the
description of FLTAREA=KEEP operand for additional concerns.
FLTAREA=NOKEEP
Frees the filter save area upon completion of the CVAF request.
FLTAREA=(NOKEEP,addr or (reg))
Frees a previously obtained filter save area upon completion of the CVAF
request.
104
z/OS DFSMSdfp Advanced Services
CVAF Macros
IOAREA: Keep or Free the I/O Work Area
IOAREA=KEEP
Specifies keeping the CVAF I/O work area. For authorized callers, CVAFFILT
returns the address of the kept I/O work area in the CVAFFILT parameter list
(CVIOAR). If you specify the same parameter list in subsequent calls,
CVAFFILT reuses the same I/O work area.
Tip: If you code this operand, you must subsequently issue CVAFFILT with
ACCESS=RLSE to release the I/O work area.
IOAREA=(KEEP,addr or (reg))
Supplies the address of a previously obtained filter save area. See the
description of IOAREA=KEEP operand for additional concerns.
IOAREA=NOKEEP
Frees the filter save area upon completion of the CVAF request.
IOAREA=(NOKEEP,addr or (reg))
Frees a previously obtained CVAF I/O work area upon completion of the
CVAF request.
BRANCH: Specify the Entry to the Macro
BRANCH=NO
Requests the SVC (default) entry. Protect key checking is performed.
BRANCH=YES
Equivalent to BRANCH=(YES,SUP), because SUP is the default when you code
YES. You must be in supervisor state. Protect key checking is bypassed.
BRANCH=(YES,SUP)
Requests the branch entry. You must be in supervisor state. Protect key
checking is bypassed. If you specify BRANCH=YES, supply an 18-word save
area. You cannot hold a lock at entry to CVAF. You cannot be in SRB mode.
BRANCH=(YES,PGM)
Requests the branch entry. You must be APF authorized and be in problem
state. Protect key checking is bypassed.
EADSCB=value: Specify the support level for extended attribute
DSCBs.
EADSCB=OK
This specification indicates that the calling program supports extended
attribute DSCBs. An extended address volume may have these DSCBs
allocated to it. The returned DSCBs (format-3, format-8) may contain extent
descriptors described by 28-bit cylinder addresses or DSCBs (format-9) that
contain additional attribute information.
For fully qualified data set names in the Filter Criteria List, a CVAFFILT
request fails if the EADSCB=OK, indicator is not set and the DSCB associated
with the fully qualified data set name is a format-8 DSCB.
For partially qualified data set names in the Filter Criteria List, a CVAFFILT
request fails if the EADSCB=OK, indicator is not set and a DSCB associated
with a data set that matches the Filter Criteria List is a format-8 DSCB.
The failing error code for these cases will be reflected as follows:
Chapter 1. Using the Volume Table of Contents
105
CVAF Macros
v Data set name status in the FCL (FCLDSNST) is set to a status value of
(X'06'). This status code indicates that a data set name is described by a
format-8 DSCB and the caller did not specify support for an EAV with the
EADSCB=OK keyword.
v Set the no resume CVAF status code (CVSTAT) of STAT072
v Return code 4.
EADSCB=OK will set the CV4EADOK indicator in the CVPL.
EADSCB=NOTOK
Indicates a calling program does not support extended attribute DSCBs.
EADSCB=NOTOK will set the CV4EADOK indicator in the CVPL to off. This
is the default.
MF: Specify the Form of the Macro
Specifies whether the DSECT, list, execute, or normal form of the macro is
requested. You can be in either 24-bit or 31-bit addressing mode. If you are not
authorized, you must pass the address of a DEB built by OPEN. If you are
authorized, you can pass either the DEB address or the UCB address. You must
ensure that the volume is allocated and will remain mounted (for example, by
dynamic allocation).
MF=I
Specifies the standard form of the macro. The CVAF parameter list is generated
and CVAF is called. The default is MF=I.
MF=D
Specifies the DSECT form of the macro. The macro generates a request for the
ICVAFPL macro to map the unique CVAF filter CVPL (4-bytes longer than
standard CVPL).
MF=L
Specifies the list form of the macro. The CVAF parameter list is generated, but
CVAF is not called.
MF=(E,addr or (reg))
Specifies the execute form of the macro. The CVAF parameter list whose
address is in addr or reg is used. You can modify the parameter list with this
form of the macro.
Return Codes from CVAFFILT
CVAF filter service does not issue any messages. Upon return from CVAF, register
1 contains the address of the CVAF parameter list and register 15 contains one of
the following return codes:
Return Code
Meaning
0 (X'00')
4 (X'04')
8 (X'08')
12 (X'0C')
16 (X'10')
The request was successful.
Logical error; status information in CVSTAT.
Invalid VTOC structure.
CVAFFILT parameter list in wrong key, or not valid.
I/O error.
CVSTAT in the CVAF parameter list contains the status code. See “Codes Put in
the CVSTAT Field” on page 141 for a list of the status codes.
106
z/OS DFSMSdfp Advanced Services
CVAF Macros
Partially-Qualified Names for CVAFFILT
CVAFFILT supports partially-qualified data set names using single or double
asterisk notation and the percent sign as shown in the following text:
v You can use a single asterisk to represent a single qualifier. For example,
SYS1.*.LOAD designates any data set with three qualifiers, the first being SYS1,
the second being any qualifier, and the third being LOAD.
v You can also use a single asterisk to represent zero or more unspecified
characters. For example, LOAD.*LIB designates any data set having only two
qualifiers, with LOAD being the first, and the second qualifier ending with the
character string LIB (for example, LINKLIB). The asterisk can appear anywhere
within the qualifier. You can use two single asterisks in the following way:
LOAD.A*B*.LIB. CVAFFILT does not support the use of two or more single
asterisks with any other character within a single qualifier (for example,
LOAD.B**.LIB is not valid).
v A double asterisk represents a place holder for zero or more qualifiers. For
example, SYS1.** designates any data set having SYS1 as its first or only
qualifier.
v You can specify a percent sign (%) as part of a partially-qualified name. The
percent sign designates any data set whose name matches the partially-qualified
name, except for the single character in the position indicated by the percent
sign. For example, SYS%.*.LOAD% designates any data set with three qualifiers,
the first being any 4-character qualifier beginning with SYS, the second being
any qualifier, and the third being any five character qualifier beginning with
LOAD.
Example of Using the CVAFFILT Macro
This example uses the CVAFFILT macro to read all format-1 and format-3 DSCBs
for specific data sets within a given VTOC as well as for all data sets within a
given VTOC. It will also calculate the number of DSCBs and print the totals and
appropriate messages to an output file. Refer to the documentation within the
sample source in “CVAFFILT Macro Overview and Specification” on page 101 for
setup requirements, program logic, and expected output.
The CVAF parameter list, buffer list, and filter criteria list are defined in the
sample source. The ICVAFPL macro generates the CVAF parameter list, the
ICVAFBFL macro generates the buffer list, and the ICVFCL macro generates the
filter criteria list.
Sample JCL for the CVAFFILT macro: The following is the sample JCL used to
Assemble, Link, and Execute the example source. Changes will have to be made to
this JCL as appropriate for each customer environment.
//CVAFFEXP JOB ,MSGCLASS=X,TIME=(,10),
//
NOTIFY=&SYSUID
//*
//STEP01 EXEC PROC=ASMACLG
//SYSIN
DD *
(INCLUDE EXAMPLE SOURCE HERE)
/*
//*
//L.SYSLMOD DD DSN=YOUR.AUTH.LINKLIB(CVAFFEXP),DISP=SHR
//L.SYSIN
DD *
SETCODE AC(1)
ENTRY
CVAFFEXP
/*
//*
//G.SYSABEND DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
Chapter 1. Using the Volume Table of Contents
107
CVAF Macros
//*
//G.CVAFDD
//G.OUTDD
//
//
//
//
//*
//
DD DISP=SHR,UNIT=3390,VOL=SER=339L62
DD DSN=CVAFFLT1.OUTPUT,
DISP=(NEW,CATLG),
UNIT=3390,VOL=SER=339L61,
SPACE=(TRK,(2,2)),
DCB=(RECFM=FBA,LRECL=133,BLKSIZE=1330)
Code example of the CVAFFILT Macro:
CVAFFEXP TITLE ’CVAF CVAFFILT EXAMPLE’
CVAFFEXP CSECT
CVAFFEXP AMODE 24
CVAFFEXP RMODE 24
*
***********************************************************************
*
*
*
CVAFFEXP - CVAFFILT EXAMPLE
*
*
*
*
*
*
CVAFFILT EXAMPLE TO BE USED IN DFSMS ADVANCED SERVICES MANUAL
*
*
*
*
CVAFFILT MACRO RUN IN AMODE24/RMODE24
*
*
*
*
CVAFFILT TEST DSN’S / PROCESSING USED:
*
*
*
*
1) 2 SEQUENTIAL DATASETS WITH 5 EXTENTS. (1 FMT1/1 FMT3 EACH)
*
*
DSCBS RETURNED WILL BE COMBINED TO TOTAL 2 FMT1 / 2 FMT3’S
*
*
DSN: CVAFFLT1.DATA01
*
*
DSN: CVAFFLT1.DATA02
*
*
CREATE ON THE VOLUME ASSOCIATED WITH THE CVAFDD DD
*
*
*
*
2) PDSE DATASET WITH 122 EXTENTS. (1 FMT1/10 FMT3’S)
*
*
DSN: CVAFFLT1.PDSE01
*
*
CREATE ON THE VOLUME ASSOCIATED WITH THE CVAFDD DD
*
*
*
*
3) 1 SEQUENTIAL DATASET WITH 5 EXTENTS (1 FMT1/1 FMT3)
*
*
DSN: CVAFFLT1.DATA01
*
*
CREATE ON THE VOLUME ASSOCIATED WITH THE CVAFDD DD
*
*
*
*
4) RETURN DSCB COUNT FOR ENTIRE VOLUME USING CVAFFILT RESUME
*
*
PROCESING.
*
*
DSN’S ON THE VOLUME: (IN SEQUENCE ORDER)
*
*
SYS1.VTOCIX.V39L62 (VTOC INDEX - 1 FMT1)
*
*
CVAFFLT1.DATA01
(5 EXTENTS - 1 FMT1/1 FMT3)
*
*
CVAFFLT1.DATA02
(5 EXTENTS - 1 FMT1/1 FMT3)
*
*
CVAFFLT1.PDSE01
(122 EXTENTS - 1 FMT1/10 FMT3’S)
*
*
DSN’S CREATED ON THE VOLUME ASSOCIATED WITH THE CVAFDD DD
*
*
*
*
*
*
OUTPUT IN OUTDD DATASET SHOULD BE THE FOLLOWING:
*
*---------------------------------------------------------------------*
*
*
*
*
* CVAFFEXP START OF OUTPUT MESSAGES
*
*
*
* RC00 VERIFIED - THE REQUEST WAS SUCCESSFUL
*
* CVAFFILT RETURNED THE FOLLOWING DSCBS FOR DSN: CVAFFLT1.DATA01
*
*
AND FOR DSN: CVAFFLT1.DATA02
*
*
NUMBER OF FORMAT 1 DSCBS - 0000002
*
*
NUMBER OF FORMAT 3 DSCBS - 0000002
*
*
*
* RC00 VERIFIED - THE REQUEST WAS SUCCESSFUL
*
* CVAFFILT RETURNED THE FOLLOWING DSCBS FOR DSN: CVAFFLT1.PDSE01
*
*
NUMBER OF FORMAT 1 DSCBS - 0000001
*
108
z/OS DFSMSdfp Advanced Services
CVAF Macros
*
NUMBER OF FORMAT 3 DSCBS - 0000010
*
*
*
* RC00 VERIFIED - THE REQUEST WAS SUCCESSFUL
*
* CVAFFILT RETURNED THE FOLLOWING DSCBS FOR DSN: CVAFFLT1.DATA01
*
*
NUMBER OF FORMAT 1 DSCBS - 0000001
*
*
NUMBER OF FORMAT 3 DSCBS - 0000001
*
*
*
* RC04 VERIFIED - CVSTAT 064 RESUME IS NECESSARY
*
* CVAFFILT (INITIAL) RETURNED THE FOLLOWING DSCBS FOR THE VOLUME:
*
*
NUMBER OF FORMAT 1 DSCBS - 0000003
*
*
NUMBER OF FORMAT 3 DSCBS - 0000002
*
* CVAFFILT (RESUME) RETURNED THE FOLLOWING DSCBS FOR THE VOLUME:
*
*
NUMBER OF FORMAT 1 DSCBS - 0000001
*
*
NUMBER OF FORMAT 3 DSCBS - 0000010
*
* CVAFFILT RESUME OPERATION COMPLETE - ALL DSCBS RETURNED
*
*
*
* CVAFFEXP END OF OUTPUT MESSAGES
*
*
*
*
*
*---------------------------------------------------------------------*
*
*
* NOTE: THE NUMBER OF DSCBS RETURNED WILL VARY IF THE DATASET DOES
*
*
NOT EXIST ON THE VOLUME OF IF THE DATASET EXTENT IS NOT AS
*
*
LISTED ABOVE OR IF THERE IS NO VTOC INDEX ON THE VOLUME.
*
*
*
* NOTE: WHEN CREATING A PDSE ON A SMS MANAGED VOLUME A VVDS
*
*
WILL ALSO BE CREATED AND THE FMT1 COUNT WILL BE
*
*
INCREASED BY ONE.
*
*
*
*
*
***********************************************************************
*
***********************************************************************
*
*
*
CVAFFEXP - LOGIC NOTES
*
*
*
*
THIS EXAMPLE WILL PERFORM THE FOLLOWING:
*
*
*
*
INITIALIZATION
*
*
- OBTAIN THE NECESSARY INFORMATION FROM THE DASD VOLUME
*
*
- OPEN AN OUTPUT FILE AND WRITE THE NECESSARY OUTPUT MESSAGES
*
*
- INITIALIZE THE NECESSARY BUFFER LIST FOR CVAFFILT
*
*
*
*
MAINLINE
*
*
- INITIALIZE A FCL TO READ FOR TWO SPECIFIC SEQ DATASETS
*
*
- ISSUE CVAFFILT READ TO READ THE DSCBS FOR THE TWO DATASETS
*
*
- CHECK THE RETURN CODE AND CVSTAT CODE FROM CVAFFILT
*
*
- COUNT THE NUMBER OF FMT1 AND FMT3 DSCBS FOR THE REQUEST
*
*
- FORMAT THE DSCB COUNTS AND WRITE TO THE OUTPUT DATASET
*
*
- ISSUE CVAFFILT RLSE TO RELEASE THE WORK AREAS USED
*
*
*
*
- INITIALIZE A FCL TO READ FOR ONE SPECIFIC PDSE DATASET
*
*
- ISSUE CVAFFILT READ TO READ THE DSCBS FOR THE PDSE DATASET
*
*
- CHECK THE RETURN CODE AND CVSTAT CODE FROM CVAFFILT
*
*
- COUNT THE NUMBER OF FMT1 AND FMT3 DSCBS FOR THE REQUEST
*
*
- FORMAT THE DSCB COUNTS AND WRITE TO THE OUTPUT DATASET
*
*
- ISSUE CVAFFILT RLSE TO RELEASE THE WORK AREAS USED
*
*
*
*
- INITIALIZE A FCL TO READ FOR ONE SPECIFIC SEQ DATASET
*
*
- ISSUE CVAFFILT READ TO READ THE DSCBS FOR THE ONE DATASET
*
*
- CHECK THE RETURN CODE AND CVSTAT CODE FROM CVAFFILT
*
*
- COUNT THE NUMBER OF FMT1 AND FMT3 DSCBS FOR THE REQUEST
*
*
- FORMAT THE DSCB COUNTS AND WRITE TO THE OUTPUT DATASET
*
*
- ISSUE CVAFFILT RLSE TO RELEASE THE WORK AREAS USED
*
*
*
*
- INITIALIZE A FCL TO READ THE DSCBS ON THE ENTIRE VOLUME
*
*
- ISSUE CVAFFILT READ TO READ THE DSCBS FOR THE VOLUME
*
Chapter 1. Using the Volume Table of Contents
109
CVAF Macros
*
- CHECK THE RETURN CODE AND CVSTAT CODE FROM CVAFFILT
*
*
- PROCESS ALL DSCBS USING CVAFFILT RESUME AS NECESSARY
*
*
- COUNT THE NUMBER OF FMT1 AND FMT3 DSCBS FOR THE REQUEST
*
*
- FORMAT THE DSCB COUNTS AND WRITE TO THE OUTPUT DATASET
*
*
- ISSUE CVAFFILT RLSE TO RELEASE THE WORK AREAS USED
*
*
*
*
FINALIZATION
*
*
- CLOSE THE OUTPUT FILE
*
*
- EXIT
*
*
*
*
*
*
CVAFFEXP - JOB INFORMATION
*
*
*
*
NORMAL END OF JOB:
*
*
- RC=00 AND OUTDD OUTPUT AS DETAILED ABOVE
*
*
*
*
*
*
ABNORMAL END OF JOB:
*
*
- ABEND 100 - ERROR OPENING VTOC ON THE DASD VOLUME THAT IS
*
*
ASSOCIATED WITH THE CVAFDD DD STATEMENT
*
*
- ABEND 101 - ERROR OPENING THE OUTDD DATASET
*
*
- ABEND 102 - ERROR CLOSING THE OUTDD DATASET
*
*
*
*
*
*
DASD VOLUMES USED IN THIS EXAMPLE:
*
*
- 339L61 - 3390 WHERE OUTDD DATASET IS DEFINED
*
*
- 339L62 - 3390 WHERE TEST DATASETS DETAILED ABOVE ARE DEFINED
*
*
*
*
*
***********************************************************************
*
***********************************************************************
*
*
* HOUSEKEEPING
*
* - SAVE CALLER’S REGISTERS AND ESTABLISH A NEW REGISTER SAVE AREA
*
*
*
***********************************************************************
*
STM R14,R12,12(R13)
STANDARD LINKAGE CONVENTION
BALR R11,0
DCL R11 AS IMPLIED BASE REG
USING BASE,R11,R12
R12 IS ALSO BASE REG
BASE
L
R12,BASEADDR
SET UP ADDRESSING FOR R12
B
CVAFFL00
BRANCH AROUND DECLARES
BASEADDR DC
A(BASE+4096)
ADDRESSING FOR R12
CVAFFL00 DS
0H
CONTINUE...
ST
R13,SAVE+4
SAVE PTR TO CALLER’S SAVE AREA
LA
R14,SAVE
GET ADDRESS OF THE NEW SAVE AREA
ST
R14,8(,R13)
CHAIN CALLER’S AREA TO OURS
LR
R13,R14
ESTABLISH THE NEW SAVE AREA
*
***********************************************************************
*
*
* INITIALIZATION
*
*
*
***********************************************************************
*
INITIAL DS
0H
INITIALIZATION SECTION
BAL R14,IDVOLRTN
INVOKE RTN TO IDENTIFY THE VOLUME(S)
BAL R14,OPENRTN
INVOKE OPEN OUTPUT DATASET RTN
MVC PDETLINE(133),STRTMSG MOVE START MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MVC PDETLINE(133),BLNKLNE MOVE BLANK LINE TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,BUFLRTN
INVOKE RTN TO INIT BUFFER LIST (H/E)
*
***********************************************************************
*
*
110
z/OS DFSMSdfp Advanced Services
CVAF Macros
* MAINLINE
*
*
*
***********************************************************************
*
MAINLINE DS
0H
MAINLINE SECTION
MVI DSNNBR,X’02’
SET DSNNBR FLAG TO TWO
BAL R14,FCL1RTN
INVOKE RTN TO INIT FCL (DS01/DS02)
BAL R14,CVAFRD2
INVOKE CVAFFILT READ RTN 2
BAL R14,TSTRCRTN
INVOKE TEST RC RTN
L
R15,RETCODE
LOAD R15 WITH RETURN CODE
CH
R15,RCODE00
IS RC = 0
BNE MAIN0010
NO - DO NOT FORMAT/PRINT LINES
MVC DS(44),DS01
ELSE MOVE DSN FOR DS01 TO MSG LINE
MVC PDETLINE(133),DSCBMSGA MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MVC DS2(44),DS02
MOVE DSN FOR DS02 TO MSG LINE
MVC PDETLINE(133),DSCBMSGB MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,FMTOPRTN
INVOKE FORMAT OUTPUT MSG RTN
B
MAIN0020
BRANCH TO MAIN0020
MAIN0010 DS
0H
CVAFFILT - CVSTAT LOGICAL ERROR
MVC DS3(44),DS01
MOVE DSN FOR DS01 TO MSG LINE
MVC PDETLINE(133),DSCBMSGC MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MVC DS3(44),DS02
MOVE DSN FOR DS02 TO MSG LINE
MVC PDETLINE(133),DSCBMSGC MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MAIN0020 DS
0H
MVC PDETLINE(133),BLNKLNE MOVE BLANK LINE TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,CVAFRL
INVOKE CVAFFILT RELEASE RTN
MVI DSNNBR,X’01’
SET DSNNBR FLAG TO ONE
BAL R14,FCL2RTN
INVOKE RTN TO INIT FCL (DS03)
BAL R14,CVAFRD1
INVOKE CVAFFILT READ RTN 1
BAL R14,TSTRCRTN
INVOKE TEST RC RTN
L
R15,RETCODE
LOAD R15 WITH RETURN CODE
CH
R15,RCODE00
IS RC = 0
BNE MAIN0030
NO - DO NOT FORMAT/PRINT LINES
MVC DS(44),DS03
ELSE MOVE DSN FOR DS03 TO MSG LINE
MVC PDETLINE(133),DSCBMSGA MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,FMTOPRTN
INVOKE FORMAT OUTPUT MSG RTN
B
MAIN0040
BRANCH TO MAIN0040
MAIN0030 DS
0H
CVAFFILT - CVSTAT LOGICAL ERROR
MVC DS3(44),DS03
MOVE DSN FOR DS03 TO MSG LINE
MVC PDETLINE(133),DSCBMSGC MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MAIN0040 DS
0H
MVC PDETLINE(133),BLNKLNE MOVE BLANK LINE TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,CVAFRL
INVOKE CVAFFILT RELEASE RTN
BAL R14,FCL3RTN
INVOKE RTN TO INIT FCL (DS01)
BAL R14,CVAFRD1
INVOKE CVAFFILT READ RTN
BAL R14,TSTRCRTN
INVOKE TEST RC RTN
L
R15,RETCODE
LOAD R15 WITH RETURN CODE
CH
R15,RCODE00
IS RC = 0
BNE MAIN0050
NO - DO NOT FORMAT/PRINT LINES
MVC DS(44),DS01
ELSE MOVE DSN FOR DS01 TO MSG LINE
MVC PDETLINE(133),DSCBMSGA MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,FMTOPRTN
INVOKE FORMAT OUTPUT MSG RTN
B
MAIN0060
BRANCH TO MAIN0060
MAIN0050 DS
0H
CVAFFILT - CVSTAT LOGICAL ERROR
MVC DS3(44),DS01
MOVE DSN FOR DS01 TO MSG LINE
MVC PDETLINE(133),DSCBMSGC MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MAIN0060 DS
0H
Chapter 1. Using the Volume Table of Contents
111
CVAF Macros
MVC
PUT
BAL
BAL
BAL
LA
USING
BAL
PDETLINE(133),BLNKLNE MOVE BLANK LINE TO LINE
OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
R14,CVAFRL
INVOKE CVAFFILT RELEASE RTN
R14,FCL4RTN
INVOKE RTN TO INIT FCL (ENTIRE VOL)
R14,CVAFRDA
INVOKE CVAFFILT READ RTN (FOR RESUME)
R9,CVPLDEFA
ESTABLISH ADDRESSABILITY
CVPLMAP,R9
TO THE CVPL (FOR CVSTAT)
R14,TSTRCRTN
INVOKE TEST RC RTN
*
***********************************************************************
*
*
* FINALIZATION
*
*
*
***********************************************************************
*
FINAL
DS
0H
FINALIZATION SECTION
MVC PDETLINE(133),BLNKLNE MOVE BLANK LINE TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MVC PDETLINE(133),ENDMSG MOVE END MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,CLOSERTN
INVOKE CLOSE OUTPUT DATASET RTN
L
R13,4(R13)
RESTORE REGISTER
LM
R14,R12,12(R13)
RESTORE CALLERS REGISTERS
LA
R15,0
SET RC TO 0
BR
R14
RETURN TO CALLER
*
***********************************************************************
*
OPENRTN
*
*
- ROUTINE TO OPEN OUTPUT FILE USED BY THIS MODULE
*
***********************************************************************
*
OPENRTN DS
0H
OPEN FILES ROUTINE
ST
R14,OPENSAVE
STORE C(R14) INTO SAVE AREA
OPEN (OUTFILE,(OUTPUT)) OPEN THE OUTDD OUTPUT FILE FOR MSGS
TM
OUTFILE+(DCBOFLGS-IHADCB),DCBOFOPN IS FILE OPEN?
BO
OPENEXIT
FILE OPEN OK - EXIT OPEN RTN
LA
R1,EABN101
OUTPUT FILE NOT OPEN-USER ABEND 101
BAL R14,ABENDRTN
INVOKE ABEND ROUTINE
OPENEXIT DS
0H
EXIT FROM OPEN ROUTINE
L
R14,OPENSAVE
LOAD C(OPENSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
CLOSERTN
*
*
- ROUTINE TO CLOSE OUTPUT FILE USED BY THIS MODULE
*
***********************************************************************
*
CLOSERTN DS
0H
CLOSE FILES ROUTINE
ST
R14,CLOSSAVE
STORE C(R14) INTO SAVE AREA
CLOSE (OUTFILE)
CLOSE OUTPUT FILE
LTR R15,R15
CHECK IF CLOSED OK
BZ
CLOSEXIT
IF OK BRANCH TO CLOSEXIT
LA
R1,EABN102
ELSE SETUP FOR USER ABEND 102
BAL R14,ABENDRTN
INVOKE ABEND ROUTINE
CLOSEXIT DS
0H
EXIT FROM CLOSE ROUTINE
L
R14,CLOSSAVE
LOAD C(CLOSSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
ABENDRTN
*
*
- FORCE AN ABEND ROUTINE
*
***********************************************************************
*
ABENDRTN DS
0H
ABEND ROUTINE
ST
R14,ABENSAVE
STORE C(R14) INTO SAVE AREA
ABEND (R1),DUMP
ISSUE USER ABEND WITH DUMP
ABENEXIT DS
0H
EXIT FROM ABEND ROUTINE
112
z/OS DFSMSdfp Advanced Services
CVAF Macros
L
BR
R14,ABENSAVE
R14
LOAD C(ABENSAVE) INTO R14
EXIT
*
***********************************************************************
*
IDVOLRTN
*
*
- OBTAIN THE NECESSARY INFORMATION FROM THE DASD VOLUME
*
***********************************************************************
*
IDVOLRTN DS
0H
IDENTIFY VOLUME ROUTINE
ST
R14,IDVLSAVE
STORE C(R14) INTO SAVE AREA
RDJFCB (VTOCDCB,(INPUT)) READ JFCB / OPEN VTOC
MVI JFCB1,X’04’
PUT IN ID FOR FORMAT 4
MVC JFCB1+1(43),JFCB1 SETUP FOR VTOC OPEN
OPEN (VTOCDCB,(INPUT)),TYPE=J OPEN VTOC (OPEN TYPE=J)
TM
VTOCDCB+(DCBOFLGS-IHADCB),DCBOFOPN
BO
IDVOL010
BRANCH TO IDVOL010 - GOOD OPEN
LA
R1,EABN100
ELSE SETUP FOR USER ABEND 100
BAL R14,ABENDRTN
INVOKE ABEND ROUTINE
IDVOL010 DS
0H
GOOD OPEN - OBTAIN VOLUME INFORMATION
SLR RDEB,RDEB
INIT REG1 FOR DEB PTR
SLR RUCB,RUCB
INIT REG2 FOR UCB PTR
ICM RDEB,B’0111’,VTOCDCB+(DCBDEBA-IHADCB) GET DEB ADDRESS
ST
RDEB,DEBADD
SAVE DEB ADDRESS INTO R1
ICM RUCB,B’0111’,(DEBBASND-DEBBASIC)+(DEBUCBA-DEBDASD)(RDEB)
ST
RUCB,UCBADD
SAVE UCB ADDRESS INTO R2
IDVLEXIT DS
0H
EXIT FROM IDVOLRTN
L
R14,IDVLSAVE
LOAD C(IDVLSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
TSTRCRTN
*
*
- TEST RETURN CODE FROM CVAFFILT
*
*
- FORMAT AND PRINT MESSAGES AS NEEDED
*
***********************************************************************
*
TSTRCRTN DS
0H
CHECK RETURN CODE ROUTINE
ST
R14,TSTRSAVE
STORE C(R14) INTO SAVE AREA
L
R15,RETCODE
LOAD R15 WITH RC SAVED FROM LAST CALL
CH
R15,RCODE00
IF RETURN CODE = 00
BE
TSTRC00
BRANCH TO PROCESS RC00
CH
R15,RCODE04
IF RETURN CODE = 04
BE
TSTRC04
BRANCH TO PROCESS RC04
TSTRCER DS
0H
ELSE PRINT GENERAL ERROR MESSAGE
MVC PDETLINE(133),RCERMSG MOVE ERROR MSG TO PRINT LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
B
TSTREXIT
BRANCH TO EXIT RTN
TSTRC00 DS
0H
PROCESS RETURN CODE = 00
MVC PDETLINE(133),RC00MSG MOVE RC00 MSG TO PRINT LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,FMTCTRTN
BRANCH TO FMT COUNT RTN
BAL R14,FMTOPRTN
INVOKE FORMAT OUTPUT MSG ROUTINE
B
TSTREXIT
BRANCH TO EXIT RTN
TSTRC04 DS
0H
PROCESS RETURN CODE = 04
CLI CVSTAT,STAT064
DO WE NEED RESUME?
BNE TSTR0010
NO - PRINT LOGICAL ERROR MSG
BAL R14,CVAFRS
INVOKE CVAFRS RESUME ROUTINE
B
TSTREXIT
BRANCH TO EXIT RTN
TSTR0010 DS
0H
PRINT RC04-OTHER LOGICAL ERROR/CVSTAT
MVC PDETLINE(133),RC04MSG MOVE RC04 MSG TO PRINT LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
TSTREXIT DS
0H
EXIT FROM TSTRCRTN
L
R14,TSTRSAVE
LOAD C(TSTRSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
FMTCTRTN
*
*
- COUNT THE NUMBER OF FMT1 AND FMT3 DSCBS FOR THE REQUEST
*
Chapter 1. Using the Volume Table of Contents
113
CVAF Macros
***********************************************************************
*
FMTCTRTN DS
0H
COUNT DSCBS RETURNED ROUTINE
ST
R14,FMTCSAVE
STORE C(R14) INTO SAVE AREA
SLR R6,R6
ZERO OUT R6
SLR R7,R7
ZERO OUT R7
CLI DSNNBR,X’01’
IF DSNNBR FLAG = 1
BE
FMTC0010
BRANCH TO LOAD ADDR OF FCL
LA
R4,FCLDEF2
ELSE LOAD R4 WITH ADDR OF FCL2
B
FMTC0020
BRANCH TO SET USING
FMTC0010 DS
0H
LA
R4,FCLDEF
LOAD R4 WITH ADDR OF FCL
FMTC0020 DS
0H
CONTINUE - SET USING
USING FCLMAP,R4
ESTABLISH ADDRESSABILITY TO FCL
SLR R5,R5
ZERO OUT R5
ICM R5,B’0011’,FCLDSCBR DETERMINE IF ANY DSCBS RETURNED
BZ
FMTC0060
NO - GO AND PRINT APPROPRIATE MSG
LA
R4,DSCBDEF
LOAD R4 WITH ADDR OF DSCB MAP
USING DSCBMAP,R4
ESTABLISH ADDRESSABILITY TO DSCB
FMTC0030 DS
0H
COUNT DSCBS BY TYPE RETURNED
CLI DS1FMTID,X’F1’
IF FORMAT1
BE
FMTC0040
BRANCH TO FMTC0040
CLI DS1FMTID,X’F3’
ELSE IF NOT FORMAT3
BNE FMTC0050
BRANCH TO FMTC0050
LA
R7,1(R7)
ADD 1 TO FORMAT3 COUNT
B
FMTC0050
BRANCH TO FMTC0050
FMTC0040 DS
0H
FMTC0040 - FORMAT1 INCREMENT
LA
R6,1(R6)
ADD 1 TO FORMAT1 COUNT
FMTC0050 DS
0H
FMTC0050 - PROCESS THROUGH DSCBS
LA
R4,DSCBSIZ(R4)
ADD DSCBSIZ TO R4
BCT R5,FMTC0030
SUBTRACT 1 FROM DSCB COUNT AND CONT
ST
R6,RETF1
STORE #FMT1’S INTO RETF1
ST
R7,RETF3
STORE #FMT3’S INTO RETF3
DROP R4
DROP R4 USING
B
FMTCEXIT
BRANCH AROUND FMTC0060
FMTC0060 DS
0H
PRINT MSG - NO DSCB’S RETURNED
MVC PDETLINE(133),NODSCBM
MOVE MSG TO PRINT LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
SLR R6,R6
ZERO OUT R6
ST
R6,RETF1
STORE ZERO INTO RETF1
SLR R7,R7
ZERO OUT R7
ST
R7,RETF3
STORE ZERO INTO RETF3
FMTCEXIT DS
0H
EXIT FROM FMTCTRTN
L
R14,FMTCSAVE
LOAD C(FMTCSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
FMTOPRTN
*
*
- FORMAT THE DSCB COUNTS AND WRITE TO THE OUTPUT DATASET
*
***********************************************************************
*
FMTOPRTN DS
0H
FORMAT OUTPUT ROUTINE
ST
R14,FMTOSAVE
STORE C(R14) INTO SAVE AREA
MVC MSG(29),DSCBMSG1
MOVE MSG TO FORMAT LINE
L
R6,RETF1
LOAD R6 WITH NBR OF FMT1’S RETURNED
CVD R6,WF1
CONVERT TO DEC FOR PRINTING
UNPK WFMTREC+29(7),WF1 UNPACK TO FORMAT LINE
OI
WFMTREC+35,X’F0’
SET APPROPRIATE BITS
MVC PDETLINE(133),WFMTREC
MOVE RECORD TO OUTPUT LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MVC MSG(29),DSCBMSG2
MOVE MSG TO FORMAT LINE
L
R7,RETF3
LOAD R7 WITH NBR OF FMT3’S RETURNED
CVD R7,WF3
CONVERT TO DEC FOR PRINTING
UNPK WFMTREC+29(7),WF3 UNPACK TO FORMAT LINE
OI
WFMTREC+35,X’F0’
SET APPROPRIATE BITS
MVC PDETLINE(133),WFMTREC
MOVE RECORD TO OUTPUT LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
114
z/OS DFSMSdfp Advanced Services
CVAF Macros
FMTOEXIT DS
0H
EXIT FROM FMTOPRTN
L
R14,FMTOSAVE
LOAD C(FMTOSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
BUFLRTN
*
*
- INITIALIZE BUFFER LIST HEADER (BFLH)
*
*
- INITIALIZE BUFFER LIST ELEMENTS (BFLE)
*
***********************************************************************
*
BUFLRTN DS
0H
BUFFER LIST INITIALIZATION ROUTINE
ST
R14,BUFLSAVE
STORE C(R14) INTO SAVE AREA
XC
BFLHDEF(BFLSIZE),BFLHDEF CLEAR BUFR LIST AREA
LA
R1,BFLHDEF
R1 - BUFFER LIST HEADER
USING BFLMAP,R1
ESTABLISH ADDRESSABILITY
MVI BFLHNOE,BUFNBR
SET NUMBER OF BUFFER ELEMENTS
OI
BFLHFL,BFLHDSCB
IDENTIFY AS DSCB BUFR ELEMENT LIST
LA
R2,BFLHDEF+BFLHLN R2 - FIRST BUFFER LIST ELEMENT
USING BFLE,R2
ESTABLISH ADDRESSABILITY
LA
R3,DSCBDEF
R3 - FIRST DSCB BUFFER
LA
R4,BUFNBR
R4 = NUMBER OF ELEMENTS AND BUFRS
BFL0010 OI
BFLEFL,BFLECHR
REQUEST CCHHR ON RETURN
MVI BFLELTH,DSCBSIZ
SET BUFR LNGTH TO FULL DSCB SIZE
ST
R3,BFLEBUF
SET ADDR(DSCB BUFFER)
LA
R2,BFLELN(R2)
R2 - NEXT BUFFER LIST ELEMENT
LA
R3,DSCBSIZ(R3)
R3 - NEXT DSCB BUFFER
BCT R4,BFL0010
LOOP THROUGH ALL ELEMENTS
DROP R1,R2
DROP TEMP USINGS
BUFLEXIT DS
0H
EXIT FROM BUFLRTN
L
R14,BUFLSAVE
LOAD C(BUFLSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
FCL1RTN
*
*
- INITIALIZE FILTER CRITERIA LIST (FCL) HEADER AND ELEMENT
*
*
- INITIALIZE A FCL TO READ FOR TWO SPECIFIC SEQ DATASETS
*
***********************************************************************
*
FCL1RTN DS
0H
FCL INITIALIZATION ROUTINE
ST
R14,FCL1SAVE
STORE C(R14) INTO SAVE AREA
XC
FCLDEF2(FCLSIZE2),FCLDEF2 CLEAR FCL AREA
LA
R1,FCLDEF2
R1 - FCL HEADER
USING FCLMAP,R1
ESTABLISH ADDRESSABILITY
LA
R2,FCLHDEND
R2 - FIRST FCL ELEMENT
USING FCLDSN,R2
ESTABLISH ADDRESSABILITY
MVC FCLID,CFCLID
SET THE EYECATCHER ’FCL ’
MVC FCLCOUNT,=H’2’
SET NUMBER OF FCL ELEMENTS
MVI FCL1FLAG,X’80’
SET FLAG FOR FULLY QUAL DSN
MVI FCLDSNLG,X’0F’
SET LENGTH FOR DSN1 (15)
LA
R3,DS01
DSN=CVAFFLT1.DATA01
*
SEQ DS - 5 EXTENTS
*
1 FORMAT1 AND 1 FORMAT3
ST
R3,FCLDSNA
SET ADDR OF DSN
LA
R2,FCLDSNEL(R2)
LOAD R2 WITH ADDR OF 2ND FCL ELEMENT
MVI FCLDSNLG,X’0F’
SET LENGTH FOR DSN2 (15)
LA
R3,DS02
DSN=CVAFFLT1.DATA02
*
SEQ DS - 5 EXTENTS
*
1 FORMAT1 AND 1 FORMAT3
ST
R3,FCLDSNA
SET ADDR OF DSN
DROP R1,R2
DROP TEMP USING
FC1EXIT DS
0H
EXIT FROM FCLRTN
L
R14,FCL1SAVE
LOAD C(FCL1SAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
FCL2RTN
*
*
- INITIALIZE FILTER CRITERIA LIST (FCL) HEADER AND ELEMENT
*
Chapter 1. Using the Volume Table of Contents
115
CVAF Macros
*
- INITIALIZE A FCL TO READ FOR ONE SPECIFIC PDSE DATASET
*
***********************************************************************
*
FCL2RTN DS
0H
FCL INITIALIZATION ROUTINE
ST
R14,FCL2SAVE
STORE C(R14) INTO SAVE AREA
XC
FCLDEF(FCLSIZE),FCLDEF CLEAR FCL AREA
LA
R1,FCLDEF
R1 - FCL HEADER
USING FCLMAP,R1
ESTABLISH ADDRESSABILITY
LA
R2,FCLHDEND
R2 - FIRST (ONLY) FCL ELEMENT
USING FCLDSN,R2
ESTABLISH ADDRESSABILITY
MVC FCLID,CFCLID
SET THE EYECATCHER ’FCL ’
MVC FCLCOUNT,=H’1’
SET NUMBER OF FCL ELEMENTS
MVI FCL1FLAG,X’80’
SET FLAG FOR FULLY QUAL DSN
MVI FCLDSNLG,X’0F’
SET LENGTH FOR DSN (15)
LA
R3,DS03
DSN=CVAFFLT1.PDSE01
*
PDSE DS - 122 EXTENTS
*
1 FORMAT1 AND 10 FORMAT3’S
ST
R3,FCLDSNA
SET ADDR OF DSN
DROP R1,R2
DROP TEMP USING
FC2EXIT DS
0H
EXIT FROM FCLRTN
L
R14,FCL2SAVE
LOAD C(FCL2SAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
FCL3RTN
*
*
- INITIALIZE FILTER CRITERIA LIST (FCL) HEADER AND ELEMENT
*
*
- INITIALIZE A FCL TO READ FOR ONE SPECIFIC SEQ DATASET
*
***********************************************************************
*
FCL3RTN DS
0H
FCL INITIALIZATION ROUTINE
ST
R14,FCL3SAVE
STORE C(R14) INTO SAVE AREA
XC
FCLDEF(FCLSIZE),FCLDEF CLEAR FCL AREA
LA
R1,FCLDEF
R1 - FCL HEADER
USING FCLMAP,R1
ESTABLISH ADDRESSABILITY
LA
R2,FCLHDEND
R2 - FIRST (ONLY) FCL ELEMENT
USING FCLDSN,R2
ESTABLISH ADDRESSABILITY
MVC FCLID,CFCLID
SET THE EYECATCHER ’FCL ’
MVC FCLCOUNT,=H’1’
SET NUMBER OF FCL ELEMENTS
MVI FCL1FLAG,X’80’
SET FLAG FOR FULLY QUAL DSN
MVI FCLDSNLG,X’0F’
SET LENGTH FOR DSN (15)
LA
R3,DS01
DSN=CVAFFLT1.DATA01
*
SEQ DS - 5 EXTENTS
*
1 FORMAT1 AND 1 FORMAT3
ST
R3,FCLDSNA
SET ADDR OF DSN
DROP R1,R2
DROP TEMP USING
FC3EXIT DS
0H
EXIT FROM FCLRTN
L
R14,FCL3SAVE
LOAD C(FCL3SAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
FCL4RTN
*
*
- INITIALIZE FILTER CRITERIA LIST (FCL) HEADER AND ELEMENT
*
*
- INITIALIZE A FCL TO READ THE DSCBS ON THE ENTIRE VOLUME
*
***********************************************************************
*
FCL4RTN DS
0H
FCL INITIALIZATION ROUTINE
ST
R14,FCL4SAVE
STORE C(R14) INTO SAVE AREA
XC
FCLDEF(FCLSIZE),FCLDEF CLEAR FCL AREA
LA
R1,FCLDEF
R1 - FCL HEADER
USING FCLMAP,R1
ESTABLISH ADDRESSABILITY
LA
R2,FCLHDEND
R2 - FIRST (ONLY) FCL ELEMENT
USING FCLDSN,R2
ESTABLISH ADDRESSABILITY
MVC FCLID,CFCLID
SET THE EYECATCHER ’FCL ’
MVC FCLCOUNT,=H’1’
SET NUMBER OF FCL ELEMENTS
MVI FCL1FLAG,X’00’
SET FLAG FOR GENERIC DSN
MVI FCLDSNLG,X’02’
SET LENGTH FOR DSN - ** (02)
LA
R3,=C’**’
ALL DATASETS ON THE VOLUME
116
z/OS DFSMSdfp Advanced Services
CVAF Macros
FC4EXIT
ST
DROP
DS
L
BR
R3,FCLDSNA
R1,R2
0H
R14,FCL4SAVE
R14
SET ADDR OF DSN
DROP TEMP USING
EXIT FROM FCLRTN
LOAD C(FCL4SAVE) INTO R14
EXIT
*
***********************************************************************
*
CVAFRD1
*
*
- INVOKE THE CFAFFILT MACRO AND READ THE DSCBS (1 DSN)
*
***********************************************************************
*
CVAFRD1 DS
0H
CVAFFILT - READ ROUTINE (2 DSN)
ST
R14,CVR1SAVE
STORE C(R14) INTO SAVE AREA
SLR R2,R2
ZERO OUT R2
LA
R2,CVPLDEF
LOAD R2 WITH ADDR OF CVPL
L
R3,UCBADD
LOAD R3 WITH UCB ADDRESS
CVAFFILT ACCESS=READ,UCB=(R3),FCL=FCLDEF,BUFLIST=BFLHDEF,
X
MF=(E,(R2))
ST
R15,RETCODE
STORE RC FOR LATER INTERROGATION
CVR1EXIT DS
0H
EXIT FROM CVAFRD1
L
R14,CVR1SAVE
LOAD C(CVR1SAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
CVAFRD2
*
*
- INVOKE THE CFAFFILT MACRO AND READ THE DSCBS (2 DSN’S)
*
***********************************************************************
*
CVAFRD2 DS
0H
CVAFFILT - READ ROUTINE (2 DSN’S)
ST
R14,CVR2SAVE
STORE C(R14) INTO SAVE AREA
SLR R2,R2
ZERO OUT R2
LA
R2,CVPLDEF
LOAD R2 WITH ADDR OF CVPL
L
R3,UCBADD
LOAD R3 WITH UCB ADDRESS
LA
R4,FCLDEF2
LOAD R4 WITH ADDR OF FCLDEF2
LA
R5,BFLHDEF
LOAD R5 WITH ADDR OF FCLDEF2
CVAFFILT ACCESS=READ,UCB=(R3),FCL=(R4),BUFLIST=(R5),
X
MF=(E,(R2))
ST
R15,RETCODE
STORE RC FOR LATER INTERROGATION
CVR2EXIT DS
0H
EXIT FROM CVAFRD2
L
R14,CVR2SAVE
LOAD C(CVR2SAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
CVAFRDA
*
*
- INVOKE THE CFAFFILT MACRO AND READ ALL THE DSCBS
*
***********************************************************************
*
CVAFRDA DS
0H
CVAFFILT - READ ALL DSCBS ROUTINE
ST
R14,CVRASAVE
STORE C(R14) INTO SAVE AREA
CVAFFILT ACCESS=READ,UCB=UCBADD,FCL=FCLDEF,BUFLIST=BFLHDEF, X
FLTAREA=KEEP,IOAREA=KEEP,
X
MF=(E,CVPLDEFA)
ST
R15,RETCODE
STORE RC FOR LATER INTERROGATION
CVRAEXIT DS
0H
EXIT FROM CVAFRDA
L
R14,CVRASAVE
LOAD C(CVRASAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
CVAFRS
*
*
- INVOKE THE CFAFFILT MACRO USING RESUME
*
***********************************************************************
*
CVAFRS
DS
0H
CVAFFILT - RESUME ROUTINE
ST
R14,CVRSSAVE
STORE C(R14) INTO SAVE AREA
CVRS0000 DS
0H
NOW CHECK RC AND STAT CODES
CH
R15,RCODE00
IS THE RC FROM RESUME 0?
BE
CVRS0050
YES BRANCH TO CVRS0050
Chapter 1. Using the Volume Table of Contents
117
CVAF Macros
CVRS0010
CVRS0020
CVRS0030
CVRS0040
CVRS0050
CH
R15,RCODE04
IS THE RC FROM RESUME 4?
BE
CVRS0020
YES BRANCH TO CVRS0020
DS
0H
ELSE PRINT MSG (RC IS 8,12,OR 16)
MVC PDETLINE(133),RCERMSG MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
B
CVRSEXIT
BRANCH TO EXIT ROUTINE
DS
0H
PROCESS FOR RC04 - CHECK FOR STAT064
CLI CVSTAT,STAT064
IS THE CVSTAT CODE 064(RESUME NEEDED)
BNE CVRS0060
NO - BRANCH TO CVRS0060
CLI RESFLG,X’01’
IS RESUME FLAG ON
BE
CVRS0030
YES - BRANCH TO CVRS0030
MVC PDETLINE(133),ST64MSG1 MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MVC PDETLINE(133),ST64MSG2 MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,FMTCTRTN
INVOKE FORMAT COUNT ROUTINE
BAL R14,FMTOPRTN
INVOKE FORMAT OUTPUT MSG ROUTINE
MVI RESFLG,X’01’
RESUME NEEDED - SET FLAG ON
B
CVRS0040
BRANCH TO CVRS0040
DS
0H
RESUME PROCESSING
MVC PDETLINE(133),ST64MSG3 MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,FMTCTRTN
INVOKE FORMAT COUNT ROUTINE
BAL R14,FMTOPRTN
INVOKE FORMAT OUTPUT MSG ROUTINE
DS
0H
RESUME PROCESSING
CVAFFILT ACCESS=RESUME,MF=(E,CVPLDEFA)
B
CVRS0000
BRANCH TO CHECK RETURN CODE AGAIN
DS
0H
RC IS 0 NO LONGER NEED RESUME
MVC PDETLINE(133),ST64MSG3 MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,FMTCTRTN
INVOKE FORMAT COUNT ROUTINE
BAL R14,FMTOPRTN
INVOKE FORMAT OUTPUT MSG ROUTINE
MVC PDETLINE(133),ST64MSG4 MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
*
*
*
RELEASE WORK AREAS
CVAFFILT ACCESS=RLSE,FLTAREA=NOKEEP,IOAREA=NOKEEP,
X
MF=(E,CVPLDEFA)
B
CVRSEXIT
BRANCH TO EXIT ROUTINE
CVRS0060 DS
0H
RC IS 4 BUT CVSTAT IS NOT 064
MVC PDETLINE(133),RC04MSG MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
CVRSEXIT DS
0H
EXIT FROM CVAFRS
L
R14,CVRSSAVE
LOAD C(CVRSSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
CVAFRL
*
*
- INVOKE THE CFAFFILT MACRO AND RELEASE WORK AREAS
*
***********************************************************************
*
CVAFRL
DS 0H
CVAFFILT - RLSE ROUTINE
ST R14,CVRLSAVE
STORE C(R14) INTO SAVE AREA
CVAFFILT ACCESS=RLSE,FCL=0,BUFLIST=0,FLTAREA=NOKEEP,
X
MF=(E,CVPLDEF)
CH
R15,RCODE00
IF RC = 0 THEN
BE
CVRLEXIT
BRANCH TO EXIT
MVC PDETLINE(133),RLSEMSG ELSE MOVE MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
CVRLEXIT DS
0H
EXIT FROM CVAFRL
L
R14,CVRLSAVE
LOAD C(CVRLSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
WORKING STORAGE
*
***********************************************************************
118
z/OS DFSMSdfp Advanced Services
CVAF Macros
*
DS
DC
0D
CL36’CVAFFEXP-WORKING STORAGE BEGINS HERE’
*
***********************************************************************
*
EQUATES
*
***********************************************************************
*
EABN100 EQU
100
USER ABEND CODE 100 - VTOC OPEN ERROR
EABN101 EQU
101
USER ABEND CODE 101 - OUTDD OPEN ERROR
EABN102 EQU
102
USER ABEND CODE 102 - OUTDD CLOSE ERROR
BUFNBR
EQU
11
11 BUFFERS TO BE USED
R0
EQU
0
R1
EQU
1
RDEB
EQU
1
REG1 FOR DEB ADDRESS
R2
EQU
2
RUCB
EQU
2
REG2 FOR UCB ADDRESS
R3
EQU
3
R4
EQU
4
R5
EQU
5
R6
EQU
6
R7
EQU
7
R8
EQU
8
R9
EQU
9
R11
EQU 11
R12
EQU 12
R13
EQU 13
R14
EQU 14
R15
EQU 15
*
***********************************************************************
*
SAVE AREAS
*
***********************************************************************
*
SAVE
DC
18F’0’
MAIN PROGRAM SAVE AREA
OPENSAVE DC
F’0’
OPEN FILES ROUTINE SAVE AREA
CLOSSAVE DC
F’0’
CLOSE FILES ROUTINE SAVE AREA
ABENSAVE DC
F’0’
ABEND ROUTINE SAVE AREA
IDVLSAVE DC
F’0’
IDNETIFY VOLUME ROUTINE SAVE AREA
BUFLSAVE DC
F’0’
INITIALIZE BUFFER ROUTINE SAVE AREA
FCL1SAVE DC
F’0’
INITIALIZE FCL1 ROUTINE SAVE AREA
FCL2SAVE DC
F’0’
INITIALIZE FCL2 ROUTINE SAVE AREA
FCL3SAVE DC
F’0’
INITIALIZE FCL3 ROUTINE SAVE AREA
FCL4SAVE DC
F’0’
INITIALIZE FCL4 ROUTINE SAVE AREA
TSTRSAVE DC
F’0’
TEST RETURN CODE ROUTINE SAVE AREA
CVR1SAVE DC
F’0’
CVAFFILT READ 1 DSN ROUTINE SAVE AREA
CVR2SAVE DC
F’0’
CVAFFILT READ 2 DSN ROUTINE SAVE AREA
CVRASAVE DC
F’0’
CVAFFILT READ ALL ROUTINE SAVE AREA
CVRLSAVE DC
F’0’
CVAFFILT RLSE ROUTINE SAVE AREA
CVRSSAVE DC
F’0’
CVAFFILT RESUME ROUTINE SAVE AREA
FMTCSAVE DC
F’0’
FORMAT DSCB COUNT ROUTINE SAVE AREA
FMTOSAVE DC
F’0’
FORMAT OUTPUT ROUTINE SAVE AREA
*
***********************************************************************
*
CONSTANTS
*
***********************************************************************
*
RETCODE DC
F’999’
RCODE00 DC
H’0’
RETURN CODE 0 - HALFWORD
RCODE04 DC
H’4’
RETURN CODE 4 - HALFWORD
DSNNBR
DC
X’FF’
INDICATE NBR OF DSNS TO PROCESS
RESFLG
DC
X’00’
RESUME FLAG - OFF
BLNKLNE DC
CL133’ ’
STRTMSG DC
CL133’ CVAFFEXP START OF OUTPUT MESSAGES
’
ENDMSG
DC
CL133’ CVAFFEXP END OF OUTPUT MESSAGES
’
ST64MSG1 DC
CL133’ RC04 VERIFIED - CVSTAT 064 RESUME IS NECESSARY ’
ST64MSG2 DS
0CL133
Chapter 1. Using the Volume Table of Contents
119
CVAF Macros
DC
CL49’ CVAFFILT (INITIAL) RETURNED THE FOLLOWING DSCBS ’
DC
CL84’FOR THE VOLUME:
’
ST64MSG3 DS
0CL133
DC
CL49’ CVAFFILT (RESUME) RETURNED THE FOLLOWING DSCBS ’
DC
CL84’FOR THE VOLUME:
’
ST64MSG4 DS
0CL133
DC
CL48’ CVAFFILT RESUME OPERATION COMPLETE - ALL DSCBS ’
DC
CL85’RETURNED’
DSCBMSGA DS
0CL133
DC
CL48’ CVAFFILT RETURNED THE FOLLOWING DSCBS FOR DSN:’
DS
DC
CL44’ ’
DC
CL41’ ’
DSCBMSGB DS
0CL133
DC
CL48’
AND FOR DSN:’
DS2
DC
CL44’ ’
DC
CL41’ ’
DSCBMSGC DS
0CL133
DC
CL48’ CVAFFILT LOGICAL ERROR STATUS RETURNED - DSN:’
DS3
DC
CL44’ ’
DC
CL41’ ’
NODSCBM DC
CL133’ NO DSCBS RETURNED FROM CVAFFILT
’
RC00MSG DC
CL133’ RC00 VERIFIED - THE REQUEST WAS SUCCESSFUL
’
RC04MSG DC
CL133’ RC04 VERIFIED - LOGICAL ERROR STATUS IN CVSTAT ’
RCERMSG DC
CL133’ RC08, RC12, OR RC16 RETURNED FROM CVAFFILT
’
RLSEMSG DC
CL133’ NON ZERO RETURN CODE BACK FROM RLSE
’
DSCBMSG1 DC
CL29’ NUMBER OF FORMAT 1 DSCBS - ’
DSCBMSG2 DC
CL29’ NUMBER OF FORMAT 3 DSCBS - ’
DS01
DC
CL44’CVAFFLT1.DATA01’
DS02
DC
CL44’CVAFFLT1.DATA02’
DS03
DC
CL44’CVAFFLT1.PDSE01’
CFCLID
DC
CL4’FCL ’
***********************************************************************
*
WORK AREAS
*
***********************************************************************
*
WF1
DS
D
DOUBLE WORD - FORMAT 1 WORK AREA
WF3
DS
D
DOUBLE WORD - FORMAT 3 WORK AREA
DEBADD
DC
F’0’
DEB ADDRESS SAVE AREA
UCBADD
DC
F’0’
UCB ADDRESS SAVE AREA
RETF1
DC
F’0’
COUNT OF FMT 1 DSCBS RET BY CVAFFILT
RETF3
DC
F’0’
COUNT OF FMT 3 DSCBS RET BY CVAFFILT
WFMTREC DS
0CL133
WORK FORMAT RECORD FOR OUTPUT
MSG
DC
CL29’ ’
GENERAL MESSAGE
FMTCNT
DC
CL08’ ’
FORMAT COUNT
TOEOL
DC
CL96’ ’
SPACES TO END OF LINE
*
***********************************************************************
*
PRINT LINES
*
***********************************************************************
*
DS
0D
TAKE CARE OF SLACK BYTES
PDETLINE DS
0CL133
DETAIL LINE
DC
CL133’ ’
EPDETLEN EQU *-PDETLINE
LENGTH OF DETAIL LINE
*
***********************************************************************
*
DCB - OUTPUT FILE (OUTFILE)
*
***********************************************************************
*
OUTFILE DCB DDNAME=OUTDD,
X
DSORG=PS,
X
RECFM=FBA,
X
LRECL=133,
X
MACRF=PM
*
***********************************************************************
*
VTOC DCB AREA
*
120
z/OS DFSMSdfp Advanced Services
CVAF Macros
***********************************************************************
*
VTOCDCB DCB DDNAME=CVAFDD,MACRF=E,EXLST=XLST1,DSORG=PS
XLST1
DC
X’87’
DC
AL3(JFCB1)
JFCB1
DS
0CL176
TESTNAME DS
CL44
DS
CL8
DS
BL1
DS
CL123
*
***********************************************************************
*
MAPPPING MACROS
*
***********************************************************************
*
CVPLMAP ICVAFPL CVPLFSA=YES
CVAF PARMLIST
FCLMAP
ICVFCL
FILTER CRITERIA LIST
BFLMAP
ICVAFBFL
BUFFER LIST
PUSH PRINT
PRINT NOGEN
DSCBMAP DSECT
DSCB DSECT
IECSDSL1 (1)
USE FMT 1 DSCB MAPPING TO GET BUFFER
DSCBSIZ EQU *-IECSDSL1
LENGTH OF FULL DSCB
DCBD DSORG=XE,DEVD=DA
MAP OF DCB
IEZDEB
MAP OF DEB
POP PRINT
*
*
CVAFFEXP CSECT ,
CONT OF CSECT AFTER MAPPING MACROS
*
*
***********************************************************************
*
CVAF PARAMETER LISTS
*
***********************************************************************
*
CVPLDEF CVAFFILT MF=L,BRANCH=NO,FLTAREA=KEEP
CVPLDEFA CVAFFILT BRANCH=(YES,SUP),MF=L
*
***********************************************************************
*
SPACE ALLOCATION FOR CVPL, FCL, BFL, AND DSCB BUFFERS
*
***********************************************************************
*
FCLDEF
DS
(FCLHDLEN+FCLDSNEL)X FCL HEADER AND ONE FCL ELEMENT
FCLSIZE EQU *-FCLDEF
*
DEFINE A CVAF BUFFER LIST WITH
FCLDEF2 DS
(FCLHDLEN+2*FCLDSNEL)X FCL HEADER AND TWO FCL ELEMENTS
FCLSIZE2 EQU *-FCLDEF2
*
DEFINE A CVAF BUFFER LIST WITH
*
N BUFFER LIST ELEMENTS
BFLHDEF DS
(BFLHLN)X
BUFFER LIST HEADER
BFLEDEF DS
(BUFNBR*BFLELN)X
N BUFFER LIST ELEMENTS
BFLSIZE EQU *-BFLHDEF
*
DEFINE N FULL DSCB BUFFERS
DSCBDEF DS
(BUFNBR*DSCBSIZ)X
*
END CVAFFEXP
END OF CVAFFEXP
CVAFSEQ Macro Overview and Specification
The CVAFSEQ macro can be used to:
v Read an indexed VTOC sequentially in data-set-name (DSN) order
v Read an indexed VTOC or a nonindexed VTOC in physical-sequential order.
See “Accessing DSNs or DSCBs in Sequential Order” on page 66 for additional
information.
Chapter 1. Using the Volume Table of Contents
121
CVAF Macros
The format of the CVAFSEQ macro is:
►►
CVAFSEQ ACCESS=
GT
GTEQ
label
►
,BUFLIST=addr
,DSN=addr
►
►
,UCB= (ucbaddr)
,DEB=addr
,DSNONLY=
NO
YES
,ARG=addr
►
►
,IOAREA=
NOKEEP
KEEP
(KEEP,addr)
(NOKEEP,addr)
,IXRCDS=
NOKEEP
KEEP
(KEEP,addr)
(NOKEEP,addr)
►
►◄
(1)
,BRANCH=
NO
YES
(YES,SUP)
(YES,PGM)
,EADSCB=
NOTOK
OK
,MF=
I
L
(E,addr)
Notes:
1
If YES is coded, the default is SUP.
ACCESS: Specify Relationship between Supplied and Returned
DSN
ACCESS=GT
Specifies that the DSN or argument value is to be used to return a DSCB
whose DSN or argument is greater than that supplied.
ACCESS=GTEQ
Specifies that the DSN or argument value is to be used to return a DSCB
whose DSN or argument is greater than or equal to that supplied.
Recommendation: A CVAF call specifying ACCESS=GTEQ should be followed
by an ACCESS=GT request, or the same DSCB or name is returned.
BUFLIST: Specify One or More Buffer Lists
BUFLIST=addr
Supplies the address of a buffer list used to read or write DSCBs and VIRs.
DSN: Specify Access by DSN Order or by Physical-Sequential
Order
DSN=addr
Supplies the address of a 44-byte area containing either zeros or a data set
name. Specifying the DSN keyword causes access of an indexed VTOC by DSN
order. BUFLIST is required if DSNONLY=NO is coded or the default.
DSN omitted
If you omit the DSN keyword, access of an indexed or nonindexed VTOC is by
physical-sequential order. BUFLIST is required.
If the order is physical-sequential, initialize the argument field in the first buffer
list entry to zero or to the argument of the DSCB. If the argument is zero
122
z/OS DFSMSdfp Advanced Services
CVAF Macros
(BFLEARG=00), the read begins at the start of the VTOC. You must be authorized
(APF or system key) to read multiple DSCBs with a single invocation of the
CVAFSEQ macro. See “Initiating Physical-Sequential Access” on page 67 for more
information.
UCB or DEB: Specify the VTOC to Be Accessed
UCB= rs-type or (2-12) standard form UCB= rx-type or (2-12) execute form
Specifies the address of the UCB for the VTOC to be accessed. The UCB
address can be for a captured UCB, or for an actual UCB above or below the
16MB line. Use the address of a UCB, not a UCB copy. An unauthorized caller
must not use this parameter. If your program is in 31-bit mode, this address
must be in 31-bit address; the high order byte is part of the address. You
should not code the UCB parameter with MF=L.
Recommendations::
v Code the address of the UCB parameter only as register (2-12). Coding an
RX-type address gives you unpredictable results.
v Do not use the UCB address passed back in the CVPL from a previous
CVAFSEQ request, particularly in AMODE=24, as it may be invalid (because
it is a captured and then uncaptured address). The recommendation is to use
IOAREA=KEEP.
DEB=addr
Supplies the address of a DEB opened to the VTOC you want to access. CVAF
does not allow output requests to the VTOC or VTOC index if you specify the
DEB subparameter. If you are not authorized, you cannot perform any
asynchronous activity (such as EXCP, CLOSE, EOV), against the data set
represented by the DEB because CVAF removes the DEB from the DEB table
for the duration of the CVAF call. If you are not authorized (neither APF
authorized nor in a system key), specify a DEB address, not a UCB, to
CVAFSEQ. See “Identifying the Volume” on page 58 for further details.
If you supply a previously obtained I/O area through the IOAREA keyword,
neither UCB nor DEB need be supplied. Otherwise, supply either a UCB or DEB. If
you supply a UCB address, it is overlaid in the CVPL by the UCB address in the
I/O area. If you supply both the UCB and the DEB addresses in the CVPL, the
DEB address is used and the UCB address in the CVPL is overlaid by the UCB
address in the DEB.
DSNONLY: Specify That Only the Data Set Name Is Read
This keyword is applicable only to accessing an indexed VTOC in DSN order.
DSNONLY=NO
Requests that the data set name be obtained from the VTOC index and the
DSCB be read into a buffer supplied through the BUFLIST keyword. BUFLIST
is required.
DSNONLY=YES
Requests that only the data set name be obtained from the VTOC index. If the
ARG keyword is coded, the argument of the DSCB is returned.
ARG: Specify Where the Argument of the DSCB Is to Be
Returned
This keyword is applicable only to accessing an indexed VTOC in DSN order with
DSNONLY=YES coded.
Chapter 1. Using the Volume Table of Contents
123
CVAF Macros
ARG=addr
Supplies the address of the 5-byte area where the CCHHR of each data set
name in the VTOC index is returned when DSNONLY=YES is coded.
IOAREA: Keep or Free the I/O Work Area
IOAREA=KEEP
Specifies that the CVAF I/O area associated with the CVAF parameter list is to
be kept upon completion of the CVAF request. IOAREA=KEEP can be coded
with BRANCH=NO only if the caller is authorized (APF, or system key).
If IOAREA=KEEP is coded, the caller must call CVAF with IOAREA=NOKEEP
specified at some future time, whether or not any further VTOC access is
required: for example, the recovery routine of the caller of CVAF.
Coding IOAREA=KEEP allows subsequent CVAF requests to be more efficient,
because certain initialization functions can be bypassed. Neither DEB nor UCB
need be specified when a previously obtained CVAF I/O area is supplied; nor
can they be changed.
When IOAREA=KEEP is first issued, CVAF returns the CVAF I/O area in the
CVAF parameter list (CVIOAR). Subsequent calls of CVAF can use that same
parameter list, and CVAF obtains its I/O area from the CVIOAR.
When processing on the current volume is finished, release all areas that were
kept.
Note: Do not switch back and forth between AMODE=24 and AMODE=31
during a succession of CVAFSEQ requests while IOAREA=KEEP is active. This
can cause problems such as ABENDS in CVAF.
IOAREA=(KEEP,addr)
Supplies the address of a previously obtained I/O area. If a different CVAF
parameter list is used, the previously obtained CVAF I/O area can be passed
to CVAF by coding its address as the second parameter of the IOAREA
keyword.
IOAREA=NOKEEP
Causes the work area to be freed upon completion of the CVAF request.
IOAREA=(NOKEEP,addr)
Causes a previously obtained work area to be freed upon completion of the
CVAF request.
IXRCDS: Retain VIERs in Virtual Storage
This keyword applies to an indexed VTOC only.
IXRCDS=KEEP
Specifies that the VIERs read into storage during the CVAF function are to be
kept in virtual storage. The VIERs are retained even if the index function is
unsuccessful. The VIERs are accessed from the CVAF parameter list
(CVIRCDS). CVIRCDS is the address of a buffer list containing the VIR buffer
addresses and RBAs of the VIERs read.
Index search function dynamically updates the buffer list and, when necessary,
obtains additional buffer lists and chains them together.
If IXRCDS=KEEP is specified and no buffer list is supplied to CVAF in the
CVPL, CVAF obtains a buffer list and buffers and reads the first high-level
VIER. The address of the buffer list is placed in the CVIRCDS field of the
CVPL.
124
z/OS DFSMSdfp Advanced Services
CVAF Macros
The buffer list and VIR buffers are in the caller's protect key. The subpool is 0
if the caller is not authorized; subpool 229 if the caller is authorized.
If IXRCDS=KEEP for an nonindexed VTOC, a request to read a DSCB can be
performed, but an error code is returned.
When processing on the current volume is finished, release all areas that were
kept.
IXRCDS=(KEEP,addr)
The CVIRCDS from one CVAF call can be passed to another CVAF parameter
list by specifying the address as the second parameter in the IXRCDS keyword.
IXRCDS=NOKEEP
If IXRCDS=NOKEEP is coded, the VIERs that are accessed (if any) are not
retained. Furthermore, the buffer list supplied in the CVIRCDS field in the
CVAF parameter list is released, as are all buffers found in the buffer list. If the
skip bit is set in any entry in the buffer list, the buffer and buffer list are not
freed.
IXRCDS=(NOKEEP,addr)
specifies that previously accessed VIERs are not to be retained.
You must free buffer lists and buffers obtained by CVAF. This can be done in one
of three ways:
v By coding IXRCDS=NOKEEP on the CVAFSEQ macro that obtained the buffers
v By coding IXRCDS=NOKEEP on a subsequent CVAF macro
v By coding CVAFDIR ACCESS=RLSE and providing the address of the buffer list
in the BUFLIST keyword.
Requirement: You must enqueue the VTOC and reserve the unit to maintain the
integrity of the VIERs read.
BRANCH: Specify the Entry to the Macro
BRANCH=(YES,SUP)
Requests the branch entry. The caller must be in supervisor state. Protect key
checking is bypassed.
If BRANCH=YES is coded, an 18-word save area must be supplied. No lock
can be held on entry to CVAF. SRB mode is not allowed.
BRANCH=YES
Equivalent to BRANCH=(YES,SUP), because SUP is the default when YES is
coded. Protect key checking is bypassed.
BRANCH=(YES,PGM)
Requests the branch entry. The caller must be APF authorized and in problem
state. Protect key checking is bypassed.
BRANCH=NO
requests the SVC entry. The caller must be APF authorized if any output
operations are requested. Protect key checking is performed. This is the
default.
EADSCB=value: Specify the support level for extended attribute
DSCBs.
EADSCB=OK
This specification indicates that the calling program supports extended
attribute DSCBs. An extended address volume may have these DSCBs
Chapter 1. Using the Volume Table of Contents
125
CVAF Macros
allocated to it. The returned DSCBs (format-3, format-8) may contain extent
descriptors described by 28-bit cylinder addresses or DSCBs (format-9) that
contain additional attribute information.
For calls that initiate physical sequential access (DSN=0 or omitted), a
CVAFSEQ request issued to an EAV volume will be failed if this new,
EADSCB=OK, indicator is not set.
For calls that initiate index order (DSN=address) where the BUFLIST=address
keyword is specified, a CVAFSEQ request issued to an EAV volume will be
failed if the EADSCB=OK indicator is not set and the DSCB associated with
this address is a format-8 DSCB.
The failing error code for these cases will be reflected as follows:
v CVAF status code (CVSTAT) set to STAT082.
v Return code 4
EADSCB=OK will set the CV4EADOK indicator in the CVPL. All other calls to
CVAFSEQ are allowed and EADSCB=OK will be ignored. That is CVAFSEQ
calls with DSNONLY=YES and ARG=address specified.
EADSCB=NOTOK
Indicates a calling program does not support extended attribute DSCBs.
EADSCB=NOTOK will turn off the CV4EADOK indicator in the CVPL. This is
the default.
MF: Specify the Form of the Macro
This keyword specifies whether the list, execute, or normal form of the macro is
requested.
MF=I
If I is coded, or neither L nor E is coded, the CVAF parameter list is generated,
as is code, to call CVAF. This is the normal form of the macro.
MF=L
Indicates the list form of the macro. A parameter list is generated, but code to
call CVAF is not generated.
MF=(E,addr)
Indicates the execute form of the macro. The remote CVAF parameter list
supplied as addr is used in and can be modified by the execute form of the
macro.
Return Codes from CVAFSEQ
On return from CVAF, register 1 contains the address of the CVPL (CVAF
parameter list), and register 15 contains one of the following return codes:
Return Code
Meaning
0 (X'00')
4 (X'04')
The request was successful.
End of data (CVSTAT is set to decimal 32), or an error was
encountered. The CVSTAT field in the CVPL contains an
indication of the cause of the error. Error descriptions are in
“VTOC Index Error Message and Associated Codes” on
page 140.
Invalid VTOC index structure. CVSTAT contains an
indication of the cause of the error. Error descriptions are in
“VTOC Index Error Message and Associated Codes” on
page 140.
8 (X'08')
126
z/OS DFSMSdfp Advanced Services
CVAF Macros
Return Code
Meaning
12 (X'0C')
The CVPL (CVAF parameter list) is not in your protect key,
or is not valid (the ID is not valid, or the length field is
incorrect, or the CVFCTN field is not valid). The CVPL has
not been modified.
An I/O error was encountered.
16 (X'10')
Example of using the CVAFSEQ macro with an indexed VTOC
This example uses the CVAFSEQ macro to count the number of VSAM data sets
whose data set names are within the range defined by two supplied data set
names. The addresses of the two data set names are supplied to the program in
registers 6 and 7, labeled RDSN1 and RDSN2, respectively. The address of a DEB
open to the VTOC is supplied in register 4, labeled RDEB.
The CVAF parameter list is expanded by a list form of the CVAFSEQ macro.
ACCESS=GTEQ is specified on the list form of macro and is, therefore, not coded
in the first execution of the CVPL. Subsequent executions of the CVPL (at label
RELOOP) specify ACCESS=GT.
End of data is tested by comparing the CVSTAT field to the value of STAT032,
which is an equate in the ICVAFPL mapping macro.
The count of VSAM DSCBs matching the data set name criterion is returned in
register 15, unless an error is encountered, in which case a negative 1 is returned in
register 15.
SEQXMP1
CSECT
STM 14,12,12(13)
BALR 12,0
USING *,12
ST
13,SAVEAREA+4
LA
RWORK,SAVEAREA
ST
RWORK,8(,13)
LR
13,RWORK
************************************************************
*
*
REGISTERS
*
************************************************************
REG1
EQU 1
REGISTER 1
RWORK
EQU 3
WORK REGISTER
RDEB
EQU 4
DEB ADDRESS
RDSN1
EQU 6
ADDRESS OF DATA SET NAME 1
RDSN2
EQU 7
ADDRESS OF DATA SET NAME 2
REG15
EQU 15
RETURN CODE REGISTER 15
************************************************************
*
*
COUNT THE NUMBER OF VSAM DATA SETS WHOSE DATA SET NAMES ARE
*
BETWEEN DSN1 AND DSN2 INCLUSIVELY.
*
RDSN1 CONTAINS ADDRESS OF DSN1.
*
RDSN2 CONTAINS ADDRESS OF DSN2.
*
ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB.
*
************************************************************
XC
BUFLIST(BFLHLN+BFLELN),BUFLIST ZERO BUFFER LIST
OI
BFLHFL,BFLHDSCB
DSCBS TO BE READ WITH BUFFER LIST
MVI BFLHNOE,1
ONE BUFFER LIST ENTRY
LA
RWORK,DS1FMTID
ADDRESS OF DSCB BUFFER
ST
RWORK,BFLEBUF
PLACE IN BUFFER LIST
MVI BFLELTH,DSCBLTH
DATA PORTION OF DSCB READ - DSN
*
SUPPLIED IN CVPL
Chapter 1. Using the Volume Table of Contents
127
CVAF Macros
MVC
LOOP
DS1DSNAM,0(RDSN1)
XR
RWORK,RWORK
CVAFSEQ DEB=(RDEB),
BUFLIST=BUFLIST,
EADSCB=OK,
MF=(E,CVPL)
EQU *
MOVE IN STARTING DATA SET NAME TO *
WORKAREA
ZERO COUNT
FIND FIRST DATA SET WHOSE DATA SET*
NAME IS GREATER THAN OR EQUAL TO *
THAT OF DSN1
*
LOOP UNTIL END OF DATA OR DATA SET
NAME GREATER THAN DSN2
LTR REG15,REG15
ANY ERROR
BZ
TESTDSN
BRANCH IF NOT-CHECK DSN LIMIT
************************************************************
*
*
DETERMINE WHAT ERROR IS
*
************************************************************
C
REG15,ERROR4
IS RETURN CODE 4
BNE OTHERERR
BRANCH IF NOT 4
CLI CVSTAT,STAT032
IS IT END OF DATA?
BNE OTHERERR
BRANCH IF NOT
************************************************************
*
*
END OF DATA
*
************************************************************
B
RELEASE
RELEASE CVAF RESOURCES AND RETURN
TESTDSN EQU *
IS DATA SET NAME GREATER THAN DSN2
CLI DS1FMTID,DS1IDC
IS THIS A FORMAT 1 DSCB?
BE
CKVSAM
BRANCH IF FORMAT 1
CLI DS1FMTID,DS8IDC
IS THIS A FORMAT 8 DSCB?
BNE CKLAST
BRANCH IF NO. CAN NOT BE VSAM.
CKVSAM
EQU *
CHECK VSAM
CLC DS1DSNAM,0(RDSN2) HAS LIMIT BEEN REACHED?
BH
RELEASE
BRANCH IF HIGH TO RELEASE RESOURCES
TM
DS1DSORG+1,DS1ORGAM IS DATA SET VSAM
BZ
CKLAST
BRANCH IF NO-DO NOT COUNT IT
LA
RWORK,1(,RWORK)
INCREMENT COUNT BY ONE
CKLAST
EQU *
CHECK IF LAST DATA SET NAME (DSN2)
CLC DS1DSNAM,0(RDSN2) HAS LIMIT BEEN REACHED?
BNH RELOOP
BRANCH IF NO-READ NEXT ONE
B
RELEASE
RELEASE CVAF RESOURCES AND RETURN
RELOOP
EQU *
READ NEXT DSCB
CVAFSEQ ACCESS=GT,
GET DSCB WITH DATA SET NAME
EADSCB=OK,
GREATER THAN THE ONE LAST READ
MF=(E,CVPL)
B
LOOP
CHECK RESULTS OF CVAFSEQ
OTHERERR EQU *
UNEXPECTED ERROR
************************************************************
*
*
UNEXPECTED ERROR PROCESSING
*
************************************************************
LA
RWORK,1(0,0)
ONE IN RWORK
LNR RWORK,RWORK
SET NEGATIVE COUNT INDICATING ERROR
RELEASE CVAFDIR ACCESS=RLSE,
RELEASE CVAF BUFFERS/IOAREA
BUFLIST=0,
DO NOT RELEASE USER BUFFER LIST
IXRCDS=NOKEEP,
RELEASE CVAF VIER BUFFERS
MF=(E,CVPL)
RELEASE CVAF I/O AREA
LR
REG15,RWORK
CURRENT COUNT IS RETURN CODE
L
13,SAVEAREA+4
RETURN (14,12),RC=(15)
RETURN CURRENT COUNT
ERROR4
DC
F’4’
ERROR RETURN CODE 4
BUFLIST ICVAFBFL DSECT=NO
BUFFER LIST
IECSDSL1 (1)
FORMAT 1 DSCB DATASET NAME AND
BUFFER
DSCBLTH EQU *-IECSDSL1-L’DS1DSNAM LENGTH OF DATA PORTION OF DSCB
SAVEAREA DS
18F
SAVE AREA
128
z/OS DFSMSdfp Advanced Services
*
*
*
*
*
*
*
CVAF Macros
CVPL
CVPLMAP
CVAFSEQ ACCESS=GTEQ,
IXRCDS=KEEP,
DSN=DS1DSNAM,
BUFLIST=BUFLIST,
EADSCB=OK,
MF=L
ORG CVPL
ICVAFPL DSECT=NO
READ DSCB WITH DSN GTEQ SUPPLIED DSN *
KEEP VIERS IN STORAGE DURING CALLS
*
SUPPLIED DATA SET NAME
*
*
*
EXPAND MAP OVER LIST
CVPL MAP
END
Example of using the CVAFSEQ macro to process a volume in
physical sequential order
This example will use the CVAFSEQ macro to read through the DSCBs in physical
sequential order. Although CVAFSEQ can be used to process both an indexed and
non indexed volume in physical sequential order this example uses a non indexed
volume. The CVAFSEQ call will return DSCBs where BFLEARG is set to a starting
CCHHR. This value is initially set to zero and the CVAFSEQ call uses
ACCESS=GT. A buffer list with five buffer list entries is contained within the
program and is used to read up to five DSCBs at a time.
Output from this program will be to OUTDD. It will be a list of all the datasets on
the volume and their corresponding CCHHRs. The output from this program is
based on the volume and dataset information detailed within the source code
example. If the output received is different it can be verified using the IEHLIST
utility.
This program must be APF authorized because it uses the UCB= and
BRANCH=(YES,PGM) parameters. It is bad programming practice to give a
program APF authorization unnecessarily. In this case these two options just give a
slight performance improvement. To remove APF authorization from this example,
perform these steps:
v Remove the SETCODE and ENTRY statements for the binder.
v Replace the UCB parameter with DEB=(reg). Precede the CVAFSEQ macro with
an instruction to load the specified register from DEBADD.
v Remove the BRANCH parameter on CVAFSEQ.
Sample JCL for CVAFSEQ macro to process a volume in sequential order: The
following is the sample JCL used to Assemble, Link, and Execute the example
source. Changes will have to be made to this JCL, as appropriate, for each
customer environment.
//SEQXMP2 JOB ,MSGCLASS=X,TIME=(,10),
//
NOTIFY=&SYSUID
//*
//STEP01 EXEC PROC=ASMACLG
//SYSIN
DD *
(INCLUDE EXAMPLE SOURCE HERE)
/*
//*
//L.SYSLMOD DD DSN=YOUR.AUTH.LINKLIB(SEQXMP2),DISP=SHR
//L.SYSIN
DD *
SETCODE AC(1)
ENTRY
SEQXMP2
/*
//*
//G.SYSABEND DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//*
//G.CVAFDD DD DISP=SHR,UNIT=3390,VOL=SER=339003
//G.OUTDD
DD DSN=CVAFSEQ1.OUTPUT,
Chapter 1. Using the Volume Table of Contents
129
CVAF Macros
//
//
//
//
//*
//
DISP=(NEW,CATLG),
UNIT=3390,VOL=SER=339001,
SPACE=(TRK,(2,2)),
DCB=(RECFM=FBA,LRECL=133,BLKSIZE=1330)
Code example of the CVAFSEQ macro to process a volume in sequential order:
SEQXMP2 TITLE ’CVAF CVAFSEQ - SEQXMP2 EXAMPLE’
SEQXMP2 CSECT
SEQXMP2 AMODE 24
SEQXMP2 RMODE 24
*
***********************************************************************
*
*
*
SEQXMP2 - THIS MODULE WILL READ THROUGH THE DSCBS ON A
*
*
NONINDEXED VOLUME. IT WILL USE THE CVAFSEQ MACRO
*
*
TO READ UP TO 5 DSCBS AT A TIME IN PHYSICAL
*
*
SEQUENTIAL ORDER.
*
*
OUTPUT FROM THIS MODULE WILL BE TO OUTDD. IT WILL
*
*
LIST ALL OF THE DATASETS ON THE VOLUME AND THEIR
*
*
CORRESPONDING CCHHR’S. THE FMT4, FMT5, AND FMT7 DSCBS *
*
AND THEIR CORRESPONDING CCHHRS WILL NOT BE LISTED.
*
*
*
*
THE FOLLOWING DATASETS WERE ALLOCATED IN THE FOLLOWING *
*
ORDER ON A NONINDEXED VOLUME.
*
*
10 SEQUENTIAL DATASETS: CVAFSEQ1.SEQ01-CVAFSEQ1.SEQ10 *
*
5 PDS DATASETS: CVAFSEQ1.PDS01-CVAFSEQ1.PDS05
*
*
5 PDSE DATASETS: CVAFSEQ1.PDSE01-CVAFSEQ1.PDSE05
*
*
2 VSAM DATASETS: CVAFSEQ1.VSAM01-CVAFSEQ1.VSAM02
*
*
*
*
NOTE: THE OUTPUT FROM THIS EXAMPLE IS BASED ON USING A NON SMS
*
*
MANAGED NON INDEXED VOLUME FOR ALLOCATING THE TEST
*
*
DATASETS (CVAFDD DD).
*
*
IF A SMS MANAGED NON INDEXED VOLUME IS USED THE POSITION
*
*
OF THE VVDS DATASET WILL BE THE SECOND ENTRY IN THE LIST. *
*
*
*
DASD VOLUMES USED IN THIS EXAMPLE:
*
*
- 1 3390-3 WHERE THE OUTDD DATASET IS DEFINED
*
*
- 1 3390-3 WHERE THE TEST DATASETS DETAILED ABOVE ARE DEFINED
*
*
THIS VOLUME INITIALIZED USING: VTOC(3326,0,195) NOINDEX
*
*
*
*
*
*
*
*
OUTPUT IN OUTDD DATASET SHOULD BE THE FOLLOWING:
*
*---------------------------------------------------------------------*
*
*
*
*
* SEQXMP2 START OF OUTPUT MESSAGES
*
*
*
* DSN: CVAFSEQ1.SEQ01
CCHHR: 0CFE000003 *
* DSN: CVAFSEQ1.SEQ02
CCHHR: 0CFE000004 *
* DSN: CVAFSEQ1.SEQ03
CCHHR: 0CFE000005 *
* DSN: CVAFSEQ1.SEQ04
CCHHR: 0CFE000006 *
* DSN: CVAFSEQ1.SEQ05
CCHHR: 0CFE000007 *
* DSN: CVAFSEQ1.SEQ06
CCHHR: 0CFE000008 *
* DSN: CVAFSEQ1.SEQ07
CCHHR: 0CFE000009 *
* DSN: CVAFSEQ1.SEQ08
CCHHR: 0CFE00000A *
* DSN: CVAFSEQ1.SEQ09
CCHHR: 0CFE00000B *
* DSN: CVAFSEQ1.SEQ10
CCHHR: 0CFE00000C *
* DSN: CVAFSEQ1.PDS01
CCHHR: 0CFE00000D *
* DSN: CVAFSEQ1.PDS02
CCHHR: 0CFE00000E *
* DSN: CVAFSEQ1.PDS03
CCHHR: 0CFE00000F *
* DSN: CVAFSEQ1.PSD04
CCHHR: 0CFE000010 *
* DSN: CVAFSEQ1.PDS05
CCHHR: 0CFE000011 *
* DSN: CVAFSEQ1.PDSE01
CCHHR: 0CFE000012 *
130
z/OS DFSMSdfp Advanced Services
CVAF Macros
* DSN: CVAFSEQ1.PDSE02
CCHHR: 0CFE000013 *
* DSN: CVAFSEQ1.PDSE03
CCHHR: 0CFE000014 *
* DSN: CVAFSEQ1.PDSE04
CCHHR: 0CFE000015 *
* DSN: CVAFSEQ1.PDSE05
CCHHR: 0CFE000016 *
* DSN: CVAFSEQ1.VSAM01.DATA
CCHHR: 0CFE000017 *
* DSN: SYS1.VVDS.V339003
CCHHR: 0CFE000018 *
* DSN: CVAFSEQ1.VSAM02.DATA
CCHHR: 0CFE000019 *
*
*
* END OF DATA REACHED - ALL DATA SETS PROCESSED
*
*
*
* SEQXMP2 END OF OUTPUT MESSAGES
*
*
*
*
*
*---------------------------------------------------------------------*
*
*
***********************************************************************
*
*
*
SEQXMP2 - LOGIC NOTES
*
*
*
*
THIS MODULE WILL PERFORM THE FOLLOWING:
*
*
*
*
INITIALIZATION
*
*
- INITIALIZE STARTING CCHHR VALUE TO 0 (GT ZERO USED IN CVAFSEQ) *
*
- OBTAIN THE NECESSARY INFORMATION FROM THE DASD VOLUME
*
*
- OPEN AN OUTPUT FILE
*
*
- WRITE NECESSARY MESSAGES TO THE OUTPUT FILE
*
*
*
*
MAINLINE
*
*
DO WHILE MORE DATASETS ON VOLUME TO PROCESS
*
*
- LOAD 5 ENTRY TABLE WITH DSCB ADDRESS
*
*
- INIT BUFFER LIST HDR TO READ DSCBS AND STARTING CCHHR
*
*
- INIT BUFFER LIST ENTRY WITH DSCB ADDRESS AND LENGTH
*
*
- ISSUE CVAFSEQ MACRO TO READ 5 ENTRIES
*
*
- LOAD CCHHR RETURNED FROM CVAFSEQ INTO TABLE
*
*
- PROCESS TABLE ENTRIES AND PRODUCE OUTPUT: DSN/CCHHR LIST
*
*
*
*
FINALIZATION
*
*
- WRITE NECESSARY MESSAGES TO THE OUTPUT FILE
*
*
- CLOSE THE OUTPUT FILE
*
*
- EXIT
*
*
*
*
*
*
SEQXMP2 - JOB INFORMATION
*
*
*
*
NORMAL END OF JOB:
*
*
- RC=00 AND OUTDD OUTPUT AS DETAILED ABOVE
*
*
*
*
*
*
ABNORMAL END OF JOB:
*
*
- ABEND 100 - ERROR OPENING VTOC ON THE DASD VOLUME THAT IS
*
*
ASSOCIATED WITH THE CVAFDD DD STATEMENT
*
*
- ABEND 101 - ERROR OPENING THE OUTDD DATASET
*
*
- ABEND 102 - ERROR CLOSING THE OUTDD DATASET
*
*
*
*
*
*
*
***********************************************************************
*
***********************************************************************
*
*
* HOUSEKEEPING
*
* - SAVE CALLER’S REGISTERS AND ESTABLISH A NEW REGISTER SAVE AREA
*
*
*
***********************************************************************
*
STM R14,R12,12(R13)
STANDARD LINKAGE CONVENTION
BALR R11,0
DCL R11 AS IMPLIED BASE REG
Chapter 1. Using the Volume Table of Contents
131
CVAF Macros
USING BASE,R11,R12
R12 IS ALSO BASE REG
L
R12,BASEADDR
SET UP ADDRESSING FOR R12
B
CVAFSQ00
BRANCH AROUND DECLARES
BASEADDR DC
A(BASE+4096)
ADDRESSING FOR R12
CVAFSQ00 DS
0H
CONTINUE...
ST
R13,SAVE+4
SAVE PTR TO CALLER’S SAVE AREA
LA
R14,SAVE
GET ADDRESS OF THE NEW SAVE AREA
ST
R14,8(,R13)
CHAIN CALLER’S AREA TO OURS
LR
R13,R14
ESTABLISH THE NEW SAVE AREA
*
***********************************************************************
*
*
* INITIALIZATION
*
*
*
***********************************************************************
*
INITIAL DS
0H
INITIALIZATION SECTION
MVC CCHHRS,CCHHR0
INIT CCHHR START TO ZERO
BAL R14,IDVOLRTN
INVOKE RTN TO IDENTIFY THE VOLUME(S)
BAL R14,OPENRTN
INVOKE OPEN OUTPUT DATASET RTN
MVC PDETLINE(133),STRTMSG MOVE START MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MVC PDETLINE(133),BLNKLNE MOVE BLANK LINE TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
*
***********************************************************************
*
*
* MAINLINE
*
*
*
***********************************************************************
*
MAINLINE DS
0H
MAINLINE SECTION
MVI SWEOD,NOEOD
SET SWITCH TO NO EOD INITIALLY
BAL R14,LDTABRTN
INVOKE LDTABRTN TO LOAD TABLE
BAL R14,INITBRTN
INVOKE INITBRTN TO INIT BUFFER LIST
BAL R14,CVAFSRTN
INVOKE CVAFSRTN TO ISSUE CVAFSEQ CALL
BAL R14,LODCRTN
INVOKE LODCRTN TO LOAD CCHHR IN TBL
BAL R14,PRTBRTN
INVOKE PRTBRTN TO PROCESS TBL ENTRIES
CLI SWEOD,EOD
DID WE REACH THE END OF DATA?
BNE MAINLINE
NO, PROCESS MORE DATA
L
R15,RETCODE
LOAD R15 WITH RETURN CODE
CH
R15,RCODE00
IF RC WAS 00?
BNE FINAL
NO - DO NOT PRINT EOD MESSAGE
MVC PDETLINE(133),BLNKLNE YES- MOVE BLANK LINE TO LINE
PUT OUTFILE,PDETLINE
WRITE THE REC TO OUTPUT FILE
MVC PDETLINE(133),EODMSG
MOVE EOD MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE THE REC TO OUTPUT FILE
*
***********************************************************************
*
*
* FINALIZATION
*
*
*
***********************************************************************
*
FINAL
DS
0H
FINALIZATION SECTION
MVC PDETLINE(133),BLNKLNE MOVE BLANK LINE TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
MVC PDETLINE(133),ENDMSG MOVE END MSG TO LINE
PUT OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
BAL R14,CLOSERTN
INVOKE CLOSE OUTPUT DATASET RTN
L
R13,4(R13)
RESTORE REGISTER
LM
R14,R12,12(R13)
RESTORE CALLERS REGISTERS
LA
R15,0
SET RC TO 0
BR
R14
RETURN TO CALLER
*
***********************************************************************
*
OPENRTN
*
BASE
132
z/OS DFSMSdfp Advanced Services
CVAF Macros
*
- ROUTINE TO OPEN OUTPUT FILE USED BY THIS MODULE
*
***********************************************************************
*
OPENRTN DS
0H
OPEN FILES ROUTINE
ST
R14,OPENSAVE
STORE C(R14) INTO SAVE AREA
OPEN (OUTFILE,(OUTPUT)) OPEN THE OUTDD OUTPUT FILE FOR MSGS
TM
OUTFILE+(DCBOFLGS-IHADCB),DCBOFOPN
IS FILE OPEN
BO
OPENEXIT
FILE OPEN OK - EXIT OPEN RTN
LA
R1,EABN101
OUTPUT FILE NOT OPEN-USER ABEND 101
BAL R14,ABENDRTN
INVOKE ABEND ROUTINE
OPENEXIT DS
0H
EXIT FROM OPEN ROUTINE
L
R14,OPENSAVE
LOAD C(OPENSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
CLOSERTN
*
*
- ROUTINE TO CLOSE OUTPUT FILE USED BY THIS MODULE
*
***********************************************************************
*
CLOSERTN DS
0H
CLOSE FILES ROUTINE
ST
R14,CLOSSAVE
STORE C(R14) INTO SAVE AREA
CLOSE (OUTFILE)
CLOSE OUTPUT FILE
LTR R15,R15
CHECK IF CLOSED OK
BZ
CLOSEXIT
IF OK BRANCH TO CLOSEXIT
LA
R1,EABN102
ELSE SETUP FOR USER ABEND 102
BAL R14,ABENDRTN
INVOKE ABEND ROUTINE
CLOSEXIT DS
0H
EXIT FROM CLOSE ROUTINE
L
R14,CLOSSAVE
LOAD C(CLOSSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
ABENDRTN
*
*
- FORCE AN ABEND ROUTINE
*
***********************************************************************
*
ABENDRTN DS
0H
ABEND ROUTINE
ST
R14,ABENSAVE
STORE C(R14) INTO SAVE AREA
ABEND (R1),DUMP
ISSUE USER ABEND WITH DUMP
ABENEXIT DS
0H
EXIT FROM ABEND ROUTINE
L
R14,ABENSAVE
LOAD C(ABENSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
IDVOLRTN
*
*
- OBTAIN THE NECESSARY INFORMATION FROM THE DASD VOLUME
*
***********************************************************************
*
IDVOLRTN DS
0H
IDENTIFY VOLUME ROUTINE
ST
R14,IDVLSAVE
STORE C(R14) INTO SAVE AREA
RDJFCB (VTOCDCB,(INPUT)) READ JFCB / OPEN VTOC
MVI JFCB1,X’04’
PUT IN ID FOR FORMAT 4
MVC JFCB1+1(43),JFCB1 SETUP FOR VTOC OPEN
OPEN (VTOCDCB,(INPUT)),TYPE=J OPEN VTOC (OPEN TYPE=J)
TM
VTOCDCB+(DCBOFLGS-IHADCB),DCBOFOPN TEST FOR GOOD OPEN
BO
IDVOL010
BRANCH TO IDVOL010 - GOOD OPEN
LA
R1,EABN100
ELSE SETUP FOR USER ABEND 100
BAL R14,ABENDRTN
INVOKE ABEND ROUTINE
IDVOL010 DS
0H
GOOD OPEN - OBTAIN VOLUME INFORMATION
SLR RDEB,RDEB
INIT REG1 FOR DEB PTR
SLR RUCB,RUCB
INIT REG4 FOR UCB PTR
ICM RDEB,B’0111’,VTOCDCB+(DCBDEBA-IHADCB) GET DEB ADDRESS
ST
RDEB,DEBADD
SAVE DEB ADDRESS INTO R1
ICM RUCB,B’0111’,(DEBBASND-DEBBASIC)+(DEBUCBA-DEBDASD)(RDEB)
ST
RUCB,UCBADD
SAVE UCB ADDRESS INTO R4
IDVLEXIT DS
0H
EXIT FROM IDVOLRTN
L
R14,IDVLSAVE
LOAD C(IDVLSAVE) INTO R14
BR
R14
EXIT
Chapter 1. Using the Volume Table of Contents
133
CVAF Macros
*
***********************************************************************
*
LDTABRTN
*
* - LOAD 5 ENTRY TABLE WITH DSCB ADDRESS TO USE
*
***********************************************************************
*
LDTABRTN DS
0H
LOAD TABLE ROUTINE
ST
R14,LDTBSAVE
STORE C(R14) INTO SAVE AREA
LA
R6,DSCB01
LOAD R6 WITH ADDRESS OF DSCB01
ST
R6,TDSCB01
STORE ADDRESS OF DSCB01 INTO TABLE
LA
R6,DSCB02
LOAD R6 WITH ADDRESS OF DSCB02
ST
R6,TDSCB02
STORE ADDRESS OF DSCB02 INTO TABLE
LA
R6,DSCB03
LOAD R6 WITH ADDRESS OF DSCB03
ST
R6,TDSCB03
STORE ADDRESS OF DSCB03 INTO TABLE
LA
R6,DSCB04
LOAD R6 WITH ADDRESS OF DSCB04
ST
R6,TDSCB04
STORE ADDRESS OF DSCB04 INTO TABLE
LA
R6,DSCB05
LOAD R6 WITH ADDRESS OF DSCB05
ST
R6,TDSCB05
STORE ADDRESS OF DSCB05 INTO TABLE
LDTBEXIT DS
0H
EXIT FROM LDTABRTN
L
R14,LDTBSAVE
LOAD C(LDTBSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
INITBRTN
*
* - INITIALIZE THE BUFFER LIST
*
***********************************************************************
*
INITBRTN DS
0H
INITIALIZE BUFFER LIST ROUTINE
ST
R14,INITSAVE
STORE C(R14) INTO SAVE AREA
LA
R7,BUFLISTE
LOAD R7 WITH ADDRESS OF BUFLIST ENTRY
USING BFLE,R7
ESTABLISH ADDRESSABILITY TO BFLE
LA
R8,BUFLISTH
LOAD R8 WITH ADDRESS OF BUFLIST HDR
USING BFLHDR,R8
ESTABLISH ADDRESSABILITY TO BFLHDR
LA
R2,TABLE
LOAD R2 WITH ADDRESS OF TABLE
USING TBLMAP,R2
ESTABLISH ADDRESSABILITY USING TBLMAP
XC
BFLHDR(BFLHLN+TBLNBR*BFLELN),BFLHDR CLEAR BUFLIST
OI
BFLHFL,BFLHDSCB
DSCBS TO BE READ WITH BUFFER LIST
MVC BFLEARG,CCHHRS
MOVE STARTING CCHHR TO ARG
MVI BFLHNOE,TBLNBR
MOVE NBR OF TBL ENTRIES TO BUFE NBR
SLR R10,R10
INIT R10 WITH ZERO
IC
R10,BFLHNOE
NBR OF BUFFER ENTRIES IN R10
ST
R10,COUNT
NBR OF BUFFER ENTRIES IN COUNT
*
INIT0010 DS
0H
INIT BUFFER LIST WITH DSCB ADDR/LENG
L
R6,DSCBA
LOAD R6 WITH DSCB ADDRESS FROM TABLE
ST
R6,BFLEBUF-BFLE(,R7)
PLACE IN BUFFER LIST
MVI BFLELTH-BFLE(R7),DSCBLTH FULL DSCB READ
OI
BFLEFL,BFLECHR
CCHHR TO BE RETURNED
LA
R2,TBLLNG(,R2)
POINT TO NEXT TABLE ENTRY
LA
R7,BFLELN(,R7)
POINT TO NEXT BUFFER LIST ENTRY
BCT R10,INIT0010
BRANCH TO INIT0010 IF C(R10) GT ZERO
DROP R2
DROP R2
INITEXIT DS
0H
EXIT FROM INITBRTN
L
R14,INITSAVE
LOAD C(INITSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
CVAFSRTN
*
* - CVAFSEQ REQUEST TO READ UP TO 5 ENTRIES AND PLACE DATA FOR EACH *
*
ENTRY STARTING AT THE CORRESPONDING DSCB ADDRESS IN THE BUFFER
*
*
LIST ENTRY.
*
***********************************************************************
*
CVAFSRTN DS
0H
CVAFSEQ REQUEST ROUTINE
ST
R14,CVAFSAVE
STORE C(R14) INTO SAVE AREA
L
RUCB,UCBADD
LOAD R4 WITH UCB ADDRESS
CVAFSEQ UCB=(RUCB),
CVAFSEQ MACRO INVOCATION
X
134
z/OS DFSMSdfp Advanced Services
CVAF Macros
CVAFSR04
CVAFSS32
CVAFSR08
CVAFSR12
CVAFSR16
CVAFEXIT
ST
LTR
CH
BZ
CH
BE
CH
BE
CH
BE
CH
BE
MVC
PUT
B
DS
MVC
PUT
CLI
BE
MVC
PUT
B
DS
MVC
PUT
B
DS
MVC
PUT
B
DS
MVC
PUT
B
DS
MVC
PUT
DS
L
BR
EADSCB=OK,
BRANCH=(YES,PGM),
MF=(E,CVPL)
R15,RETCODE
STORE RC INTO RETCODE
R15,R15
TEST RC RETURNED FROM CVAFSEQ
R15,RCODE00
IS IT A RC00?
CVAFEXIT
YES - BRANCH TO EXIT ROUTINE
R15,RCODE04
IS IT A RC04?
CVAFSR04
YES - BRANCH TO PROCESS RC04
R15,RCODE08
IS IT A RC08?
CVAFSR08
YES - BRANCH TO PROCESS RC08
R15,RCODE12
IS IT A RC12?
CVAFSR12
YES - BRANCH TO PROCESS RC12
R15,RCODE16
IS IT A RC16?
CVAFSR16
YES - BRANCH TO PROCESS RC16
PDETLINE(133),RCERMSG ELSE FORMAT UNEXPECTED RC
OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
CVAFEXIT
EXIT ROUTINE
0H
RETURN CODE 04
PDETLINE(133),RC04MSG FORMAT RC04 MESSAGE
OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
CVSTAT,STAT032
IS CVSTAT CODE STAT032?
CVAFSS32
YES - BRANCH TO PROCESS STAT032
PDETLINE(133),STAT2MSG NO - FORMAT STAT2MSG
OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
CVAFEXIT
BRANCH TO EXIT ROUTINE
0H
CVSTAT CODE = STAT032
PDETLINE(133),STAT1MSG FORMAT STAT1MSG
OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
CVAFEXIT
BRANCH TO EXIT ROUTINE
0H
RETURN CODE 08
PDETLINE(133),RC08MSG FORMAT RC08 MESSAGE
OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
CVAFEXIT
BRANCH TO EXIT ROUTINE
0H
RETURN CODE 12
PDETLINE(133),RC12MSG FORMAT RC12 MESSAGE
OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
CVAFEXIT
BRANCH TO EXIT ROUTINE
0H
RETURN CODE 16
PDETLINE(133),RC16MSG FORMAT RC16 MESSAGE
OUTFILE,PDETLINE
WRITE A RECORD TO THE OUTPUT FILE
0H
EXIT FROM CVAFSRTN
R14,CVAFSAVE
LOAD C(CVAFSAVE) INTO R14
R14
EXIT
X
X
*
***********************************************************************
*
LODCRTN
*
* - LOAD CCHHR FROM BUFFER LIST ENTRY INTO PROCESSING TABLE. THIS
*
*
VALUE RETURNED FROM CVAFSEQ CALL.
*
***********************************************************************
*
LODCRTN DS
0H
LOAD CCHHR INTO PROCESSING TABLE
ST
R14,LODCSAVE
STORE C(R14) INTO SAVE AREA
DROP R7,R8
DROP R7 AND R8
LA
R7,BUFLISTE
LOAD R7 WITH ADDRESS OF BUFLIST ENTRY
USING BFLE,R7
ESTABLISH ADDRESSABILITY TO BFLE
LA
R2,TABLE
LOAD R2 WITH ADDRESS OF TABLE
USING TBLMAP,R2
ESTABLISH ADDRESSABILITY USING TBLMAP
L
R10,COUNT
LOAD R10 WITH TABLE ENTRY COUNT
*
LODC0010 DS
0H
PROCESS CCHHR VALUE RETURNED
LA
R8,BFLEARG
LOAD R8 WITH ADDRESS OF BFLEARG
ST
R8,CCHHRA
STORE CCHHR VALUE INTO TABLE
LA
R2,TBLLNG(,R2)
POINT TO NEXT TABLE ENTRY
LA
R7,BFLELN(,R7)
POINT TO NEXT BUFFER LIST ENTRY
BCT R10,LODC0010
BRANCH TO LODC0010 IF C(R10) GT ZERO
DROP R2,R7
DROP R2 AND R7
Chapter 1. Using the Volume Table of Contents
135
CVAF Macros
LODCEXIT DS
0H
EXIT FROM LODCRTN
L
R14,LODCSAVE
LOAD C(LODCSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
PRTBRTN
*
* - PROCESS TABLE WHICH CONTAINS ADDRESS OF DSCB AND ADDRESS OF
*
*
CCHHR FOR EACH ENTRY RETURNED FROM CVAFSEQ CALL. TABLE IS
*
*
CURRENTLY 5 ENTRIES.
*
***********************************************************************
*
PRTBRTN DS
0H
PROCESS TABLE ENTRIES (DSCBA/CCHHRA)
ST
R14,PRTBSAVE
STORE C(R14) INTO SAVE AREA
L
R10,COUNT
LOAD COUNT IN R10
LA
R2,TABLE
LOAD ADDRESS OF TABLE INTO R2
USING TBLMAP,R2
ESTABLISH ADDRESSABILITY TO TABLE
PRTB0000 DS
0H
PROCESS ENTRIES
L
R3,DSCBA
ADDRESSABILITY TO DSCBA
L
R4,CCHHRA
ADDRESSABILITY TO CCHHRA
CLC 0(1,R3),FMT4
IS IT A FMT4?
BE
PRTB0020
YES, BRANCH TO POINT TO NEXT ENTRY
CLC 0(1,R3),FMT5
IS IT A FMT5?
BE
PRTB0020
YES, BRANCH TO POINT TO NEXT ENTRY
CLC 0(1,R3),FMT7
IS IT A FMT7?
BE
PRTB0020
YES, BRANCH TO POINT TO NEXT ENTRY
CLC 0(1,R3),FMT9
IS IT A FMT9?
BE
PRTB0020
YES, BRANCH TO POINT TO NEXT ENTRY
* DETERMINE IF END OF DATA WAS REACHED
CLC 0(1,R3),NODSN
IS THERE ’00’ IN FIRST BYTE
BNE PRTB0010
NO, THEN CONTINUE TO PROCESS DSN
MVI SWEOD,EOD
YES, SET SWITCH TO END OF DATA
B
PRTBEXIT
EXIT OUT OF ROUTINE
PRTB0010 DS
0H
PROCESS DSN - FORMAT
MVC DSNMSG(44),0(R3)
MOVE DSN TO PRINT LINE
* PROCESS / FORMAT CCHHR
MVC CCHHRS(5),0(R4)
MOVE CCHHR TO CCHHRS START VARIABLE
UNPK CCHHRM(L’CCHHRM+1),CCHHRS(6) UNPACK CCHHR
TR
CCHHRM,TCHAR1
CONVERT TO PRINTABLE HEX
PUT OUTFILE,MSG1 PRINT THE DSN LINE
PRTB0020 DS
0H
INCREMENT COUNTER FILEEDIT
LA
R2,TBLLNG(R2)
POINT TO NEXT TABLE ENTRY
BCT R10,PRTB0000
BRANCH TO PRTB0000 IF C(R10) GT ZERO
PRTBEXIT DS
0H
EXIT FROM PRTBRTN
L
R14,PRTBSAVE
LOAD C(PRTBSAVE) INTO R14
BR
R14
EXIT
*
***********************************************************************
*
WORKING STORAGE
*
***********************************************************************
*
DS
0D
DC
CL36’SEQXMP2-WORKING STORAGE BEGINS HERE’
*
***********************************************************************
*
EQUATES
*
***********************************************************************
*
EABN100 EQU 100
USER ABEND CODE 100-VTOC OPEN ERROR
EABN101 EQU 101
USER ABEND CODE 101-OUTDD OPEN ERROR
EABN102 EQU 102
USER ABEND CODE 102-OUTDD CLOSE ERROR
R0
EQU 0
R1
EQU 1
RDEB
EQU 1
REG1 FOR DEB ADDRESS
R2
EQU 2
R3
EQU 3
R4
EQU 4
RUCB
EQU 4
REG4 FOR UCB ADDRESS
136
z/OS DFSMSdfp Advanced Services
CVAF Macros
R5
EQU 5
R6
EQU 6
R7
EQU 7
R8
EQU 8
R9
EQU 9
R10
EQU 10
R11
EQU 11
R12
EQU 12
R13
EQU 13
R14
EQU 14
R15
EQU 15
*
***********************************************************************
*
SAVE AREAS
*
***********************************************************************
*
SAVE
DC
18F’0’
MAIN PROGRAM SAVE AREA
OPENSAVE DC
F’0’
OPEN FILES ROUTINE SAVE AREA
CLOSSAVE DC
F’0’
CLOSE FILES ROUTINE SAVE AREA
ABENSAVE DC
F’0’
ABEND ROUTINE SAVE AREA
IDVLSAVE DC
F’0’
IDENTIFY VOLUME ROUTINE SAVE AREA
LDTBSAVE DC
F’0’
LOAD TABLE ROUTINE SAVE AREA
INITSAVE DC
F’0’
INIT BUFFER ROUTINE SAVE AREA
PRTBSAVE DC
F’0’
PROCESS TABLE ROUTINE SAVE AREA
CVAFSAVE DC
F’0’
CVAFSEQ REQUEST ROUTINE SAVE AREA
LODCSAVE DC
F’0’
LOAD CCHHR ROUTINE SAVE AREA
*
***********************************************************************
*
CONSTANTS
*
***********************************************************************
*
RETCODE DC
F’0’
RETURN CODE SAVE FIELD
RCODE00 DC
H’0’
RETURN CODE 0 - HALFWORD
RCODE04 DC
H’4’
RETURN CODE 4 - HALFWORD
RCODE08 DC
H’8’
RETURN CODE 8 - HALFWORD
RCODE12 DC
H’12’
RETURN CODE 12 - HALFWORD
RCODE16 DC
H’16’
RETURN CODE 16 - HALFWORD
CCHHR0
DC
XL5’0000000000’
INIT WITH ZERO
FMT4
DC
XL1’04’
FMT4?
FMT5
DC
XL1’05’
FMT5?
FMT7
DC
XL1’07’
FMT7? (ONLY CERTAIN DEVICE TYPES)
FMT9
DC
XL1’09’
FMT9? (ONLY CERTAIN DEVICE TYPES)
NODSN
DC
XL1’00’
END OF DATA?
BLNKLNE DC
CL133’ ’
STRTMSG DC
CL133’ SEQXMP2 START OF OUTPUT MESSAGES
’
ENDMSG
DC
CL133’ SEQXMP2 END OF OUTPUT MESSAGES
’
RC00MSG DC
CL133’ RC00 RETURNED FROM SEQXMP2
’
RC04MSG DC
CL133’ RC04 RETURNED FROM SEQXMP2
’
RC08MSG DC
CL133’ RC08 RETURNED FROM SEQXMP2
’
RC12MSG DC
CL133’ RC12 RETURNED FROM SEQXMP2
’
RC16MSG DC
CL133’ RC16 RETURNED FROM SEQXMP2
’
RCERMSG DC
CL133’ UNEXPECTED RC (??) RETURNED FROM SEQXMP2
’
STAT1MSG DC
CL133’ CVSTAT CODE STAT032 ENCOUNTERED
’
STAT2MSG DC
CL133’ UNEXPECTED CVSTAT CODE RETURNED FROM SEQXMP2
’
EODMSG
DC
CL133’ END OF DATA REACHED - ALL DATA SETS PROCESSED
’
MSG1
DS
0CL133
DC
CL6’ DSN: ’
DSNMSG
DS
CL44’ ’
DC
CL7’CCHHR: ’
CCHHRM
DS
CL10’ ’
DC
CL66’ ’
***********************************************************************
*
WORK AREAS
*
***********************************************************************
*
BUFLST
DS
0F
BUFFER LIST WORK AREA
BUFLISTH DC
2F’0’
BUFFER LIST HEADER
Chapter 1. Using the Volume Table of Contents
137
CVAF Macros
BUFLISTE
*
UCBADD
DEBADD
COUNT
DC
15F’0’
5 BUFFER LIST ENTRIES
DC
DC
DC
DS
DS
DS
DS
DS
DS
F’0’
F’0’
F’0’
D
XL140
XL140
XL140
XL140
XL140
UCB ADDRESS SAVE AREA
DEB ADDRESS SAVE AREA
TABLE COUNTER
DSCB01
DSCB01 BUFFER AREA
DSCB02
DSCB02 BUFFER AREA
DSCB03
DSCB03 BUFFER AREA
DSCB04
DSCB04 BUFFER AREA
DSCB05
DSCB05 BUFFER AREA
*
CCHHRS
DC
XL5’0000000000’
STARTING CCHHR
*
***********************************************************************
*
PRINT LINES
*
***********************************************************************
*
DS
0D
PDETLINE DS
0CL133
DETAIL LINE
DC
CL133’ ’
EPDETLEN EQU *-PDETLINE
LENGTH OF DETAIL LINE
*
***********************************************************************
*
DCB - OUTPUT FILE (OUTFILE)
*
***********************************************************************
*
OUTFILE DCB DDNAME=OUTDD,
X
DSORG=PS,
X
RECFM=FBA,
X
LRECL=133,
X
MACRF=PM
*
***********************************************************************
*
VTOC DCB AREA
*
***********************************************************************
*
VTOCDCB DCB DDNAME=CVAFDD,MACRF=E,EXLST=XLST1,DSORG=PS,DCBE=VTOCDCBE
XLST1
DC
X’87’
DC
AL3(JFCB1)
JFCB1
DS
0CL176
TESTNAME DS
CL44
DS
CL8
DS
BL1
DS
CL123
VTOCDCBE DCBE EADSCB=OK
*
***********************************************************************
*
TABLES
*
***********************************************************************
*
TABLE
DC
0H
START OF TABLE DSCB ADDR / CCHHR ADDR
*
TDSCB01 DS
F’0’
DSCB01 ADDRESS (140 BYTE DSCB)
TCHR01
DS
F’0’
CCHHR ADDRESS FOR DSCB01 - RETURNED
*
TBLLNG
EQU *-TABLE
LENGTH OF TABLE ENTRY
*
TDSCB02 DS
F’0’
DSCB02 ADDRESS (140 BYTE DSCB)
TCHR02
DS
F’0’
CCHHR ADDRESS FOR DSCB02 - RETURNED
*
TDSCB03 DS
F’0’
DSCB03 ADDRESS (140 BYTE DSCB)
TCHR03
DS
F’0’
CCHHR ADDRESS FOR DSCB03 - RETURNED
*
TDSCB04 DS
F’0’
DSCB04 ADDRESS (140 BYTE DSCB)
TCHR04
DS
F’0’
CCHHR ADDRESS FOR DSCB04 - RETURNED
*
138
z/OS DFSMSdfp Advanced Services
CVAF Macros
TDSCB05 DS
F’0’
DSCB05 ADDRESS (140 BYTE DSCB)
TCHR05
DS
F’0’
CCHHR ADDRESS FOR DSCB05 - RETURNED
*
TBLNBR
EQU (*-TABLE)/TBLLNG
NBR OF TABLE ENTRIES
*
**********************************************************************
*
TABLES (CONT)
*
**********************************************************************
*
TCHAR1
EQU *-C’0’
TABLE TO TRANSLATE TO PRINTABLE HEX
DC
C’0123456789ABCDEF’
*
**********************************************************************
*
SWITCHES
*
**********************************************************************
SWEOD
DC
XL1’00’
SWITCH - END OF DATA ?
EOD
EQU X’FF’
END OF DATA DETECTED
NOEOD
EQU X’00’
END OF DATA NOT DETECTED
*
**********************************************************************
*
DSECTS
*
**********************************************************************
TBLMAP
DSECT
DUMMY CONTROL SECTION FOR TABLE MAP
DSCBA
DS
F
DSCB ADDRESS ENTRY
CCHHRA
DS
F
CCHHR ADDRESS ENTRY
*
**********************************************************************
*
MACROS / INCLUDES
*
**********************************************************************
DCBD DSORG=XE,DEVD=DA
MAP OF DCB
IEZDEB
MAP OF DEB
ICVAFBFL
BUFFER LIST WITH ONE ENTRY
DSCB
DSECT
IECSDSL1 (1)
FORMAT 1 DSCB
DSCBLTH EQU *-IECSDSL1
LENGTH OF DSCB
*
**********************************************************************
*
CVAF PARAMETER LISTS
*
**********************************************************************
*
SEQXMP2 CSECT
CVPL
CVAFSEQ ACCESS=GT,
CVAFSEQ MACRO REQUEST
X
BUFLIST=BUFLISTH, ADDRESS OF BUFFER LIST
X
MF=L
ORG CVPL
CVPLMAP ICVAFPL DSECT=NO
CVAF PARM LIST MAP
*
*
END SEQXMP2
END OF SEQXMP2
CVAFTST Macro Overview and Specification
The CVAFTST macro determines whether the system supports an indexed VTOC,
and, if it does, whether the VTOC on the unit whose UCB is supplied is indexed
or nonindexed.
When you issue CVAFTST, register 13 must contain the address of a standard 18
word save area.
You will get a return code of 12 if CVAFTST cannot determine whether an indexed
or nonindexed VTOC is on the unit's volume. You should not receive a return code
of 12 from CVAFTST if you have opened a data set (including the VTOC) on the
volume.
You need no authorization to issue the CVAFTST macro.
Chapter 1. Using the Volume Table of Contents
139
CVAF Macros
See “CVAFDSM Macro Overview and Specification” on page 95 for an example of
using the CVAFTST macro with the CVAFDSM macro.
The format of the CVAFTST macro is:
►►
CVAFTST UCB=(reg)
►◄
label
UCB: Specify the VTOC to Be Tested
UCB=(reg)
Supplies the address of the UCB for the volume whose VTOC is to be tested.
The UCB address can be for a captured UCB, or for an actual UCB above or
below the 16 MB line. If your program is in 31-bit mode, this address must be
in 31-bit address; the high order byte is part of the address.
Recommendation: Code the address of the UCB parameter as register (2-12).
Coding an RX-type address gives unpredictable results.
The CVAFTST macro accepts the address of a UCB or UCB copy. Unauthorized
programs can get a copy of the UCB by using the UCBSCAN macro and
specifying the COPY, UCBAREA, CMXTAREA, and DCEAREA keywords. The
UCB copy and common extension copy must be below the 16 MB line and on
a word boundary. Data accessed with DCEAREA can be above the 16 MB line.
Refer to z/OS HCD Planning for details.
Return Codes from CVAFTST
On return from CVAF, register 15 contains one of the following return codes:
Return Code
Meaning
0 (X'00')
The system does not support an indexed VTOC. The volume
should be considered to have a nonindexed VTOC. The UCB
was not inspected to determine its validity or status.
The system supports an indexed VTOC, but the volume has
a nonindexed VTOC.
The system supports an indexed VTOC and the volume has
an indexed VTOC.
The system supports an indexed VTOC, but the volume is
not mounted or the VIB is not initialized for it; thus, the
status (indexed or nonindexed) of the VTOC cannot be
determined.
The system supports an indexed VTOC, but the unit is not a
DASD or has a VIO UCB, or the UCB address is not valid.
The address of a UCB copy is not valid without a
CMXTAREA and a DCEAREA.
4 (X'04')
8 (X'08')
12 (X'0C')
16 (X'10')
VTOC Index Error Message and Associated Codes
Error Message
When CVAF finds an error in a VTOC index, it issues the following message:
IEC606I VTOC INDEX DISABLED ON dev,volser,code,[rba[,secno,offset]]
140
z/OS DFSMSdfp Advanced Services
CVAF Macros
In addition, CVAF puts a return code in the CVSTAT field of the CVPL.
Explanation: The Common VTOC Access Facility (CVAF) detected a VTOC index
error on the device dev with volume serial number volser. A number that represents
the kind of VTOC index error is provided in the code field. The RBA of the VIR in
the VTOC index that contains the structure error indicated by code is provided in
the rba field. If the VIR is a VIER, the section number in the VIER containing the
VTOC index entry is supplied in the secno field, and the offset into the section of
that VTOC index entry is supplied in the offset field.
System Action: The VTOC index is disabled. The VTOC will be converted to
nonindexed format when DADSM next allocates space on the volume. A system
dump is written to the SYS1.DUMP data set, and an entry is made in the
SYS1.LOGREC data set. The message IEC604I (which indicates that the VTOC
convert routines have been used) will be issued later.
Programmer Response: Examine the system dump and a print of the VTOC
index, and use the information in message IEC606I to determine the cause of the
VTOC index structure error.
Routing and Descriptor Codes: The routing codes are 4 (direct access pool) and
10 (system/error maintenance), and the descriptor code is 4 (system status).
Codes Put in the CVSTAT Field
If you are diagnosing an error and require a description of the CVSTAT field codes,
see z/OS DFSMSdfp Diagnosis.
VTOC Error Responses
The following actions are taken if an error occurs in the VTOC:
v If an index structure error is detected and if the address space is enqueued on
the VTOC, then DADSM or CVAF disables the VTOC index. The indexed VTOC
bit is zeroed in the format-4 DSCB, a software error record is written to
SYS1.LOGREC, and a system dump is taken at the next call to DADSM create or
extend. The VTOC is converted to a nonindexed format at the next DADSM
create or extend call.
v If a program check, machine check, or other error occurs while using a VTOC
access macro, a SYS1.LOGREC record is written, and a system dump is taken.
v An error code is put in the CVSTAT field of the CVPL. The values and
explanations of these error codes are listed in “VTOC Index Error Message and
Associated Codes” on page 140.
Recovering from System or User Errors
Because an unauthorized user cannot modify a VTOC, neither the VTOC nor the
VTOC index need be recovered from an error caused by an unauthorized user.
A system error can affect a VTOC and VTOC index by interrupting DADSM while
it is updating, leaving the VTOC or the VTOC index (or both) in a
partially-updated state. Both the VTOC and the VTOC index allow DADSM to
recover from such an interruption.
For a nonindexed VTOC (or a VTOC with an index that has been disabled), a
subsequent call to DADSM create or extend, causes VTOC convert routines to
reestablish the free space DSCB chain.
Chapter 1. Using the Volume Table of Contents
141
CVAF Macros
For an indexed VTOC, a subsequent call to any DADSM function causes the
recovery of the previous interrupt (either by backing out or completing the
interrupted function).
GTF Trace
A trace function exists to trace all CVAF calls for VTOC index output I/O, all
VTOC output I/O, and all VTOC index and space map modifications. For
information on this function, see z/OS DFSMSdfp Diagnosis.
VTOC and VTOC Index Listings
You can obtain dump, formatted, or abridged listings of the VTOC and the VTOC
index by using the LISTVTOC command of the IEHLIST utility program. The
DFSMSdss print command also provides VTOC and index listing options. The
ISMF data set application displays information about the data sets represented in a
VTOC.
142
z/OS DFSMSdfp Advanced Services
Chapter 2. Managing the Volume Table of Contents
This information covers the programs and procedures used to create and manage a
volume table of contents (VTOC).
Creating the VTOC and VTOC Index
To prepare a volume for activity by initializing it, use the Device Support Facilities
(ICKDSF) utility to build the VTOC. You can create a VTOC index when
initializing a volume by using the ICKDSF INIT command and specifying the
INDEX keyword.
To convert a non-indexed VTOC to an indexed VTOC, use the BUILDIX command
with the IXVTOC keyword. The reverse operation can be performed by using the
BUILDIX command and specifying the OSVTOC keyword.
To refresh a volume VTOC and INDEX in its current format, use the ICKDSF
command REFORMAT with the RVTOC keyword. To optionally extend the VTOC
and INDEX, use the ICKDSF command REFORMAT with the EXTVTOC and
EXTINDEX keywords.
See Device Support Facilities (ICKDSF) User's Guide and Reference for details.
Protecting the VTOC and VTOC Index
Use the following methods in order to protect the VTOC and VTOC index:
RACF®
You can protect the VTOC and VTOC index using the Resource Access Control
Facility (RACF), a component of the Security Server for z/OS, by defining the
volume serial entity under the RACF DASDVOL class. For you to modify a
protected VTOC and VTOC index, programs must be authorized at the following
levels:
v UPDATE level to open for output processing a VTOC or any data set with a
name beginning with SYS1.VTOCIX.
v ALTER level to allocate, rename, or scratch any data set with a name beginning
with SYS1.VTOCIX or to rename a data set to a name beginning with
SYS1.VTOCIX.
Neither the VTOC nor the VTOC index is protected from being opened for input
processing by the DASDVOL/volume serial entity. Neither the VTOC nor the
VTOC index can be protected through the RACF DATASET class. For additional
information on using RACF, see z/OS Security Server RACF Security Administrator's
Guide.
APF
The authorized program facility (APF) must authorize a program in order for you
to:
v Open a VTOC for output processing
v Open for output processing, allocate, rename, or scratch any data set whose
name begins with SYS1.VTOCIX
© Copyright IBM Corp. 1979, 2017
143
Managing the VTOC
v Rename a data set to a name that begins with SYS1.VTOCIX.
For additional information on using APF, see z/OS MVS Programming: Authorized
Assembler Services Guide.
Password Protection
The VTOC index data set can be password protected. Protection is the same as for
a password-protected data set. Password checking is bypassed if the volume
containing the VTOC index is protected by RACF with the DASDVOL class. For
additional information, see Chapter 6, “Using Password Protected Data Sets,” on
page 247.
Copying/Restoring/Initializing the VTOC
The following topics discuss VTOC considerations when updating volumes:
v “Volumes Containing a Nonindexed VTOC”
v “Volumes Containing an Indexed VTOC”
Volumes Containing a Nonindexed VTOC
When updating volumes containing a non-indexed VTOC keep the following
considerations in mind:
v Restoring a Volume from a Dump Tape: There are no operational requirements if
you change the volume serial number or do a partial restore that does not
modify the VTOC. If you do a restore and change the VTOC size without
changing the volume serial number, the system can automatically update the
UCB with the new VTOC location and new volume serial number following a
Restore or Copy Volume operation if you have the REFUCB function enabled. To
enable this function, do one of the following:
– Specifiy ENABLE(REFUCB) in the DEVSUPxx parmlib member
– Issue the MODIFY command as follows:
F DEVMAN,ENABLE(REFUCB)
If you do not enable REFUCB, you cannot restore on a volume with an indexed
VTOC. In that case, you must vary the volume offline after it is restored.
v Copying a Volume: There are no operational requirements if you change the
volume serial number or do not modify the VTOC of the receiving volume. If
you do a copy and change the VTOC size without changing the volume serial
number, you must vary the volume offline after it is copied. Do not attempt to
copy from a volume with an indexed VTOC.
v Shared DASD Considerations:In shared DASD environments, if the VTOC index is
relocated or the volume is changed from indexed VTOC to nonindexed VTOC or
from nonindexed VTOC to indexed VTOC, it generally is advisable to vary the
device offline to the sharing system or systems before beginning the operation.
However it is not necessary to vary the volume offline on other systems in the
same sysplex z/OS Version 1 Release 5 or higher using ICKDSF release 17.
Volumes Containing an Indexed VTOC
Use Device Support Facilities (ICKDSF) to convert a VTOC to a non-indexed
format to update the volume. If you do not, keep the following considerations in
mind:
Initializing a Volume: If you do not change the volume serial number, you must
vary the volume offline before starting the job.
144
z/OS DFSMSdfp Advanced Services
Managing the VTOC
Restoring a Volume from a Dump Tape: There are no operational requirements if
you change the volume serial number or do a partial restore that does not
modify the VTOC or VTOC index. If you do a restore, and modify the VTOC or
VTOC index without changing the volume serial number, you must vary the
volume offline after it is restored.
Copying a Volume: There are no operational requirements if you change the
volume serial number of the receiving volume or do a partial dump without
modifying the VTOC or VTOC index. If you modify the VTOC or VTOC index
without changing the volume serial number, you must vary the receiving
volume offline after it is copied.
Deleting a Data Set from the VTOC
You can use the SCRATCH and CAMLST macro to delete a non-VSAM data set or
a temporary VSAM data set. SCRATCH processing makes the space occupied by
the data set available for reallocation. This process does not automatically erase
data from the disk. See “Erasing Sensitive Data” for further information.
Specifying the Volumes Affected
When deleting a data set, build a volume list in virtual storage. The volume list
consists of an entry for each volume on which the data set resides. If you are
deleting an SMS-managed data set, specify at least one SMS-managed volume in
the list. The first two bytes of the list indicate the number of entries in the list.
Each 12-byte entry consists of a 4-byte device code (the UCBTYP field from the
volume's UCB), a 6-byte volume serial number, and 2 bytes of scratch status
information consisting of a secondary status code and a status code, both of which
must be initialized to zero.
Volumes are processed according to their order in the volume list. If a volume is
not mounted, a message is issued to the operator requesting that the volume be
mounted. This only occurs when you indicate the direct access device on which
unmounted volumes are to be mounted by loading register 0 with the address of
the UCB of the device. (The device must be allocated to your job.) If you do not
load register 0 with a UCB address, its contents must be zero, and at least one of
the volumes in the volume list must be mounted before the SCRATCH macro
instruction is issued. Use the address of a UCB, not a UCB copy, in register 0 with
this macro. 31-bit programs must pass a clean UCB addr on RENAME, when
applicable.
If the requested volume cannot be mounted, the operator replies by indicating that
the request cannot be fulfilled. A status code is then set in the last byte of the
volume list entry (the second byte of the scratch status code) for the unavailable
volume, and the next volume in the volume list is processed.
Erasing Sensitive Data
You should erase data sets that contain sensitive data by overwriting them with
zeros before their space is made available. This can either be done before issuing
the SCRATCH macro, or be requested in scratch processing by performing one of
the following:
v Providing an associated RACF profile ERASE attribute
v Activating bit 21 (X'00 00 04 00') of the SCRATCH parameter list. See Table 22 on
page 148.
Authorized callers of SCRATCH can prevent erasure of the data by setting bit 22 to
1, which overrides the RACF profile ERASE attribute.
Chapter 2. Managing the Volume Table of Contents
145
Managing the VTOC
System-Managed-Storage Considerations
SMS screens all data set SCRATCH requests. If the volumes in your volume list are
SMS managed, SMS does a catalog LOCATE to determine the actual volume serial
numbers, and deletes the data set from all volumes on which it resides. SMS
coordinates the required changes to the VTOC, the VTOC index, and the catalog.
If DADSM encounters a processing error when SMS is active and all the volumes
in your list are SMS managed, SMS determines the volume on which the failure
occurred. The first entry in your list will be overlaid with the entry for the volume
on which the request failed.
You might find that a volume indicated as being in error was not specified in the
volume list your program provided. This occurs if the volumes in your list are
different from the volumes in the data set's catalog entry.
If SMS is not active, you cannot delete SMS-managed data sets.
You can delete SMS-managed VSAM data sets using the access method services
DELETE command. See z/OS DFSMS Access Method Services Commands for further
information.
General Considerations and Restrictions
A data set cannot be deleted if the expiration date in the format-1 DSCB has not
passed unless you override the expiration date. You can request SCRATCH to
ignore the expiration date by specifying the OVRD option in the CAMLST macro
instruction. SCRATCH processing supports three never-scratch dates. To prevent a
data set from being scratched, specify one of the following expiration dates:
1999.365
1999.366
1999.999
To delete a virtual input/output (VIO) data set, the data set must be allocated for
use by your job step.
You cannot use the SCRATCH macro with either a SYSIN or SYSOUT data set or
an z/OS UNIX file. You will receive unpredictable results if you use SCRATCH for
z/OS UNIX files.
If you attempt to delete a password-protected data set that is not also RACF
protected, the operating system issues message IEC301A to the operator at the
console, or the terminal operator of a TSO console, to enter the password. The data
set will be scratched if the password supplied is associated with a WRITE
protection mode indicator. The protection mode indicator is described in Chapter 6,
“Using Password Protected Data Sets,” on page 247.
If a data set is RACF-defined (indicated in its format-1 DSCB or described by a
RACF profile) or the volume upon which it resides is RACF-defined, you can
scratch the data set only if you have ALTER access authority to either the data
set/volume serial in the DATASET class or to the volume serial in the DASDVOL
class.
Requirement: For an SMS-managed non-VSAM data set, you need RACF
authority to the data set or to the catalog to delete it.
146
z/OS DFSMSdfp Advanced Services
Managing the VTOC
For a non-VSAM data set that is not SMS-managed, DADSM invokes RACF to
verify authorization. If you have ALTER access authority to the data set/volume
serial in the DATASET class, DADSM deletes the data set from the volume. If you
have ALTER authority to the data set/volume serial in the DATASET class, or
UPDATE access authority to the catalog/volume serial in the DATASET class, you
can delete the catalog entry.
Use the STOW macro to delete or rename a member of a PDS or PDSE. STOW is
described in z/OS DFSMS Macro Instructions for Data Sets and z/OS DFSMS Using
Data Sets. You can also use the IEHPROGM utility to delete a member (see z/OS
DFSMSdfp Utilities).
SCRATCH and CAMLST Macro Specification
The format of the SCRATCH and CAMLST macros is:
►►
SCRATCH
listname_addrx
►◄
label
►► listname
CAMLST
SCRATCH ,dsname_relexp ,,vol_list_relexp
►
►
►◄
,,OVRD
listname_addrx
Points to the parameter list (labeled listname) set up by the CAMLST macro
instruction.
SCRATCH
Code this operand as shown.
dsname_relexp
Specifies the virtual storage location of a fully-qualified data set name. The
area that contains the name must be 44 bytes long.
vol list_relexp
Specifies the virtual storage location of an area that contains a volume list. The
area must begin on a halfword boundary.
OVRD
When coded as shown, specifies that the expiration date in the DSCB should
be ignored.
Example
In the following example, data set A.B.C is deleted from two volumes. The
expiration date in the identifier (format-1) DSCB is ignored.
SR
SCRATCH
*
*
*
0,0
DELABC
SHOW NO UCB IS SUPPLIED
DELETE DATA SET A.B.C
FROM TWO VOLUMES,
IGNORING EXPIRATION
DATE IN THE DSCB
Chapter 2. Managing the Volume Table of Contents
147
Managing the VTOC
DELABC
DSABC
VOLIST
CAMLST
DC
DC
DC
DC
DC
DC
DC
DC
SCRATCH,DSABC,,VOLIST,,OVRD
CL44’A.B.C’
DATA SET NAME
H’2’
NUMBER OF VOLUMES
X’3030200E’
3380 DISK DEVICE CODE
CL6’000017’
VOLUME SERIAL NO.
H’0’
SCRATCH STATUS CODE
X’3030200E’
3380 DISK DEVICE CODE
CL6’000018’
VOLUME SERIAL NO.
H’0’
SCRATCH STATUS CODE
Recommendation: Check the return codes and SCRATCH status codes.
The SCRATCH macro instruction points to the CAMLST macro instruction. The
SCRATCH operand specifies that a data set be deleted. DSABC specifies the virtual
storage location of a 44-byte area containing the fully-qualified name of the data
set to be deleted. VOLIST specifies the virtual storage location of the volume list
you have built. OVRD specifies that the expiration date in the DSCB of the data set
to be deleted should be ignored.
SCRATCH Parameter List
The CAMLST macro generates the SCRATCH parameter list, but your code can set
several options that CAMLST does not support. See Table 22.
Table 22. SCRATCH Parameter List
Offset
Length or Bit Pattern
Description
0(0)
1
Flags. Always X'41'.
1(1)
1
Flags.
.1.. ....
Do not delete the Resource Access
Control Facility (RACF) profile. Has an
effect only if JSCBPASS is on.
JSCBPASS is on if the program
properties table gives authority to
bypass security. See the NOPASS
option on the primary POI task (PPT)
statement in the SCHEDxx member of
SYS1.PARMLIB as described in z/OS
MVS Initialization and Tuning Reference.
x.xx xxxx
Reserved.
1
Flags.
1... ....
SYSZTIOT already is enqueued.
SCRATCH bypasses enqueueing on
SYSZTIOT if this bit is on and the
caller is APF-authorized or is running
in a system key or supervisor state. If
SYSZTIOT is not already enqueued,
system damage might result.
.10. ...0
Always set for SCRATCH.
...1 ....
OVRD coded on CAMLST.
.... 1...
Bypass RACF profile checking.
SCRATCH bypasses RACF profile
checking if this bit is on and the caller
is APF-authorized or is running in a
system key or supervisor state.
2(2)
148
z/OS DFSMSdfp Advanced Services
Managing the VTOC
Table 22. SCRATCH Parameter List (continued)
Offset
Length or Bit Pattern
Description
.... .1..
Erase all allocated space for the data
set.
.... ..1.
Do not erase allocated space.
SCRATCH bypasses space erasure if
this bit is on and the caller is
APF-authorized or is running in a
system key or supervisor state.
3(3)
1
Reserved.
4(4)
4
Address of 44-byte data set name.
8(8)
4
Reserved.
12(C)
4
Address of volume list.
Return Codes from SCRATCH
Control returns to the instruction following the instructions generated by the
SCRATCH macro. Register 15 contains the SCRATCH return code as shown in
Table 23.
SCRATCH returns 4 bytes of diagnostic information in register 0. If an error
occurs, DADSM issues message IEC614I, consisting of failure-related information
including the return code and the 4 bytes of diagnostic information. See z/OS
DFSMSdfp Diagnosis for a description of this information.
The last two bytes of a volume list entry contain the secondary status code and the
scratch status code. The secondary status codes are shown in Table 25 on page 150
and the scratch status codes are shown in Table 24 on page 150. To determine if the
data set has been deleted from each volume, check the scratch status code. (Even if
the scratch status code is zero, the secondary status code might be nonzero for the
first entry in the volume list.)
Table 23 describes the conditions indicated by the SCRATCH return code.
Table 23. SCRATCH Return Codes
Return Code
Description
000 (X'00')
If the 4 bytes of diagnostic information returned in register 0 are all
zeros, the data set was successfully deleted. If they are nonzero, use
the SCRATCH diagnostic information tables in z/OS DFSMSdfp
Diagnosis to determine the failure-related conditions.
No volume containing any part of the data set was mounted. The
data set might be a VIO data set that was not allocated to your
jobstep.
An unusual condition was encountered on one or more volumes.
One of the following conditions occurred:
004 (X'04')
008 (X'08')
012 (X'0C')
v The SCRATCH parameter list is not valid.
v The volume list is not valid.
v At entry to SCRATCH, register 0 was not zero and did not point
to a valid UCB. The address must be that of a UCB, not a UCB
copy.
The SCRATCH status code will not have been set.
Chapter 2. Managing the Volume Table of Contents
149
Managing the VTOC
Status Codes from SCRATCH
After the SCRATCH macro instruction is executed (for SCRATCH return codes 0, 4,
and 8 only), the last byte of each 12-byte entry in the volume list indicates one of
the following conditions:
Table 24. SCRATCH Status Codes
Status Code
Meaning
0 (X'00')
1 (X'01')
The data set has been deleted from this volume.
The VTOC of this volume does not contain the format-1 or format-8
DSCB to be deleted.
One of the following conditions occurred:
v The data set could not be scratched because the correct password
was not specified in the two attempts allowed.
v The user tried to scratch a VSAM data space or an integrated
catalog facility VSAM data set.
v The user tried to scratch the VTOC index data set.
v An SMS-validation failure occurred.
v The verify of the last referenced date failed.
The data set was not deleted because either the OVRD option was
not specified or the retention cycle had not expired.
One of the following conditions occurred:
v An invalid format-1 or format-8 DSCB was encountered when
processing this volume.
v An unexpected CVAF error return code was encountered.
v An installation exit rejected the request.
v An I/O error occurred while the DASD tracks occupied by the
data set were being erased. Either the ERASE option was
specified in the scratch parameter list or the ERASE attribute was
specified for an RACF-defined data set.
It could not be verified that this volume was mounted, nor was
there a unit available for mounting the volume.
The operator was unable to mount this volume.
The data set was not deleted because it was open.
The format-1 or format-8 DSCB indicates the data set is defined to
RACF, but either you are not authorized to the data set or volume,
or the data set is a VSAM data space.
The data set is on a read-only volume and cannot be deleted on this
volume.
2 (X'02')
3 (X'03')
4 (X'04')
5 (X'05')
6 (X'06')
7 (X'07')
8 (X'08')
|
|
9 (X'09')
After the SCRATCH macro instruction is executed, the next to last byte of the first
entry in the volume list indicates one of the following conditions:
Table 25. Secondary Status Codes
150
Status Code
Meaning
0 (X'00')
128 (X'80')
No secondary status for this volume.
The data set was RACF protected and the calling program was
authorized by the RACF DATASET class to scratch the data set.
This means that at least one volume entry was protected.
z/OS DFSMSdfp Advanced Services
Managing the VTOC
Renaming a Data Set in the VTOC
You can use the RENAME and CAMLST macro to rename a non-VSAM data set.
Rename processing causes the data set name in all format-1 or format-8 DSCBs to
be replaced with the new name you supply. The new data set name must conform
to standard data set naming conventions.
Specifying the Volumes Affected
When renaming a data set, build a volume list in virtual storage. The volume list
consists of an entry for each volume on which the data set resides. If you are
renaming an SMS-managed data set, specify at least one SMS-managed volume in
the list. The first two bytes of the list indicate the number of entries in the list.
Each 12-byte entry consists of a 4-byte device code (the UCBTYP field from the
volume's UCB), a 6-byte volume serial number, and a 2-byte rename status code
that should be initialized to zero.
Volumes are processed according to their order in the volume list. If a volume is
not mounted, a message is issued to the operator requesting that the volume be
mounted. This only occurs when you indicate the direct access device on which
unmounted volumes are to be mounted by loading register 0 with the address of
the UCB of the device. (The device must be allocated to your job.) If you do not
load register 0 with a UCB address, its contents must be zero, and at least one of
the volumes in the volume list must be mounted before the RENAME macro
instruction is issued. Use the address of a UCB, not a UCB copy, in register 0 with
this macro. 31-bit programs must pass a clean UCB addr on RENAME, when
applicable.
If the requested volume cannot be mounted, the operator replies by indicating that
the request cannot be fulfilled. A status code is then set in the last byte of the
volume list entry (the second byte of the rename status code) for the unavailable
volume, and the next volume indicated in the volume list is processed.
System-Managed-Storage Considerations
SMS screens all data set RENAME requests. If the volumes specified in your
volume list are SMS managed, SMS does a catalog LOCATE to determine the
actual volume serial numbers, and coordinates the required changes to the VTOC,
the VTOC index, and the catalog.
If DADSM encounters a processing error while SMS is active and all the volumes
in your list are SMS managed, SMS determines the volume on which the failure
occurred. The first entry in your list will be overlaid with the entry for the volume
on which the request failed.
You might find that a volume indicated as being in error was not specified in the
volume list your program provided. This occurs if the volumes in your list are
different from the volumes in the data set's catalog entry.
If SMS is not active, you cannot rename SMS-managed data sets.
General Considerations and Restrictions
Multivolume Considerations
To rename a data set that is stored on more than one volume, all volumes must be
mounted.
Chapter 2. Managing the Volume Table of Contents
151
Managing the VTOC
Unrenamable Data Sets and UNIX Files
You cannot use the RENAME macro with either a SYSIN or SYSOUT data set or
UNIX file (such as an z/OS UNIX file). You will receive unpredictable results if
you use RENAME for UNIX files.
You cannot rename VIO data sets.
Data Set Security
You can rename a RACF-defined data set only if you have ALTER access authority
to the data set in the DATASET class.
If you attempt to rename a password-protected data set, the operating system
issues message IEC301A asking the operator or TSO operator to verify the
password. The data set will be renamed if the password supplied is associated
with a WRITE protection mode indicator. The protection mode indicator is
described in Chapter 6, “Using Password Protected Data Sets,” on page 247.
Renaming a Data Set That Might be in Use
You can rename a data set that is allocated to the current address space but it
cannot be open.
In general, you cannot rename a data set whose name is the same as any data set
that is allocated to another address space in the same system or in the scope of the
SYSDSN enqueue. The system bypasses this restriction if all of the following are
true:
v Your program sets on a certain bit in the CAMLST macro expansion. You can
code this instruction: OI listname+2,X'10'.
v You have at least read authority to the RACF facility class named
STGADMIN.DPDSRN.olddsname, where olddsname is up to 23 characters of the
existing data set name. You can use a generic class name such as
STGADMIN.DPDSRN.SYS2.*. IBM recommends that no one have authority to
STGADMIN.DPDSRN.* because it is too broad.
v The data set is not SMS-managed.
Alternatively, you can use the data set rename option of PDF. If you attempt to
rename a non-SMS-managed, non-VSAM data set, the data set name is in use and
you have the appropriate RACF facility class authority, then PDF asks whether you
wish to proceed because you know that the data set is not actually open. Let the
rename proceed only if you know the data set being renamed is not open on any
system.
Attention: This option should be used with extreme caution. Very few people
should have RACF authority to STGADMIN.DPDSRN.olddsname. Do not use this
option unless you know the data set is not open on any system. After the data set
is renamed, someone could delete it in a different address space. If someone has it
open by the old name, new data sets will appear at those places on the disk. This
would be a security violation that the system does not detect.
The data set rename function writes a type 18 SMF record to provide information
to storage administrators, system programmers, and auditors. The record contains
an indicator of whether it was successful due to the use of this duplicate name
override function. If you request the option in the CAMLST macro expansion but
the data set name is not in use, then the SMF indicator will not be on.
152
z/OS DFSMSdfp Advanced Services
Managing the VTOC
RENAME and CAMLST Macro Specification
The format of the RENAME and CAMLST macros is:
►►
RENAME
listname_addrx
►◄
label
►► listname
CAMLST
RENAME ,dsname_relexp ,new name_relexp
►
► ,vol list_relexp
►◄
listname_addrx
Points to the parameter list (labeled listname) set up by the CAMLST macro
instruction.
RENAME
Code this operand as shown.
dsname_relexp
Specifies the virtual storage location of a fully-qualified data set name to be
replaced. The area containing the name must be 44 bytes long.
new name_relexp
Specifies the virtual storage location of a fully-qualified data set name that is to
be used as the new name. The area containing the name must be 44 bytes long.
vol list_relexp
Specifies the virtual storage location of an area that contains a volume list. The
area must begin on a halfword boundary.
Example
In the following example, data set A.B.C is renamed D.E.F. The data set resides on
two volumes.
SR
0,0
RENAME DSABC
DSABC
OLDNAME
NEWNAME
VOLIST
CAMLST
DC
DC
DC
DC
DC
DC
DC
DC
DC
SET REG 0 TO ZERO
CHANGE DATA SET
NAME A.B.C TO D.E.F
RENAME,OLDNAME,NEWNAME,VOLIST
CL44’A.B.C’
OLD DATA SET NAME
CL44’D.E.F’
NEW DATA SET NAME
H’2’
TWO VOLUMES
X’3030200E’
3380 DISK DEVICE CODE
CL6’000017’
VOLUME SERIAL NO.
H’0’
RENAME STATUS CODE
X’3030200E’
3380 DISK DEVICE CODE
CL6’000018’
VOLUME SERIAL NO.
H’0’
RENAME STATUS CODE
Recommendation: Check the return codes and RENAME status codes.
The RENAME macro instruction points to the CAMLST macro instruction. The
RENAME operand specifies that a data set be renamed. OLDNAME specifies the
Chapter 2. Managing the Volume Table of Contents
153
Managing the VTOC
virtual storage location of a 44-byte area where you have placed the fully-qualified
name of the data set to be renamed. NEWNAME specifies the virtual storage
location of a 44-byte area where you have placed the new name of the data set.
VOLIST specifies the virtual storage location of the volume list you have built.
RENAME Parameter List
The CAMLST macro generates the RENAME parameter list but your code can set
several options that CAMLST does not support. See Table 26.
Table 26. RENAME Parameter List generated by CAMLST
Offset
Length or Bit Pattern
Description
0(0)
1
Flags. Always X'C1'
1(1)
1
Flags.
.1.. ....
Do not define RACF profile.
..1. ....
Do not update the changed bit
(DS1DSCHA) in the format 1 DSCB.
x..x xxxx
Reserved.
1
Flags.
..1. ....
Always set for RENAME.
...1 ....
See “Renaming a Data Set That Might be in
Use” on page 152.
xx.. xxxx
Reserved.
3(3)
1
Reserved.
4(4)
4
Address of 44-byte existing data set name.
8(8)
4
Address of 44-byte new data set name.
12(C)
4
Address of volume list.
2(2)
Return Codes from RENAME
Control returns to the instruction following the instructions generated by the
RENAME macro. Register 15 contains the DADSM return code as shown in
Table 27 on page 155.
DADSM RENAME returns 4 bytes of diagnostic information in register 0. If an
error occurs, DADSM issues message IEC614I, consisting of failure-related
information including the return code and the 4 bytes of diagnostic information.
See z/OS DFSMSdfp Diagnosis for a description of this information.
Each volume's volume list entry contains the rename status code as shown in
Table 28 on page 155. To determine whether the data set has been successfully
renamed on each volume, check the rename status code, contained in the last byte
of each entry in the volume list.
Table 27 on page 155 describes the conditions indicated by the DADSM return
code.
154
z/OS DFSMSdfp Advanced Services
Managing the VTOC
Table 27. DADSM RENAME Return Codes
Return Code
Description
000 (X'00')
If the 4 bytes of diagnostic information returned in register 0 are all
zeros, the data set has been successfully renamed. If they are
nonzero, use the DADSM RENAME diagnostic information tables in
z/OS DFSMSdfp Diagnosis to determine the failure-related
conditions.
No volume containing any part of the data set was mounted. The
data set can be a VIO data set but cannot be renamed.
An unusual condition was encountered on one or more volumes.
The diagnostic information is in register 0. Use the DADSM
RENAME diagnostic information tables in z/OS DFSMSdfp Diagnosis
to determine the failure-related conditions.
One of the following conditions occurred:
004 (X'04')
008 (X'08')
012 (X'0C')
v The DADSM RENAME parameter list is not valid.
v The volume list is not valid.
v At entry to RENAME, register 0 was not zero and did not point
to a valid UCB. The address must be that of a UCB, not a UCB
copy.
The RENAME status code will not have been set.
Status Codes from RENAME
After the RENAME macro instruction is executed (for RENAME return codes 0, 4,
and 8 only), the last byte of each 12-byte entry in the volume list indicates one of
the following conditions described in Table 28.
Table 28. RENAME Status Codes
Status Code
Meaning
0 (X'00')
The format-1 DSCB for the data set has been renamed in the VTOC
on this volume.
The VTOC of this volume does not contain the format-1 or format-8
DSCB of the data set to be renamed.
One of the following conditions occurred:
1 (X'01')
2 (X'02')
v The data set could not be renamed because the data set was
password protected and the password was not supplied in the
two attempts allowed.
v An attempt was made to rename a VSAM data space or an
integrated catalog facility VSAM data set.
v An attempt was made to rename a VTOC index data set.
3 (X'03')
4 (X'04')
v An SMS-validation failure occurred.
A format-1 or format-8 DSCB containing the new data set name
already exists in the VTOC of this volume, or an attempt was made
to rename a data set to a name starting with SYS1.VTOCIX.
One of the following conditions occurred:
v A permanent I/O error occurred while trying to rename the data
set on this volume.
v An invalid format-1 or format-8 DSCB was encountered while
processing this volume.
5 (X'05')
v No space is available in the index VIER for the new name, and
no additional VIERs are available.
It could not be verified that this volume was mounted nor was a
unit available for mounting the volume.
Chapter 2. Managing the Volume Table of Contents
155
Managing the VTOC
Table 28. RENAME Status Codes (continued)
Status Code
Meaning
6 (X'06')
7 (X'07')
The operator was unable to mount this volume.
The data set was not renamed, because it was currently open for
processing.
The data set is defined to RACF, but either you are not authorized
to the data set or the data set is defined to RACF on multiple
volumes.
The data set is on a read-only volume and cannot be renamed on
this volume.
8 (X'08')
|
|
9 (X'09')
156
z/OS DFSMSdfp Advanced Services
Chapter 3. Using Catalog Management Macros
This information covers catalog management macro instructions for compatibility
purposes only. Catalog management macro instructions can be used to perform the
following functions:
v Retrieve information from an integrated catalog facility catalog.
v Catalog, uncatalog, or re-catalog in an integrated catalog facility catalog the
following types of data sets:
– DASD data sets that are not VSAM or SMS-managed
– Tape data sets.
Application Program Considerations
A catalog management request can be satisfied in an integrated catalog facility
catalog. Consider the following restrictions and limitations in relation to your
application programs:
v A catalog management request is expressed in a parameter list pointed to by
register 1. Generate the parameter list with a CAMLST macro. The CAMLST and
its associated fields must not be located in read-only storage.
v Register 15 contains the return code. These return codes are explained in the
sections below.
Catalog Search Order
Catalogs are searched for entries using the following methods:
1. If a catalog is specified in a macro, only that catalog is searched.
2. If the entry is identified with a qualified entry name and its first qualifier is the
same as the name or alias of a user catalog, the user catalog is searched. When
the entry is found, no other catalog is searched.
3. The master catalog is searched.
See z/OS DFSMS Access Method Services Commands for more detailed information.
Retrieving Information from a Catalog
To read an entry from a catalog, use the LOCATE and CAMLST macro
instructions. You can specify the entry to be read into your output area using the
following information:
v The fully- or partially-qualified name of a data set
v The relative block address of the block containing the entry.
If you specify a fully-qualified data set name, a list of volumes on which the data
set resides is read into your output area. This volume list always begins with a
2-byte entry indicating the number of volumes in the list.
Restriction: When CAMLST is used to locate a data set that is over 20 volumes in
length, only information from the first 20 volumes is returned. If you need to
retrieve data from more than 20 volumes, use IGGCSI (Catalog Search Interface).
See (link to pertinent section in Man Cat).
© Copyright IBM Corp. 1979, 2017
157
CATALOG Macros
For the Catalog interface, a fully-qualified name is one which represents a single
data set. A partially-qualified name is one which may contain multiple qualifiers,
but does not specify a full data set name.
For example, if LEVEL1.LEVEL2.LEVEL3.LEVEL4 is a data set, then
LEVEL1.LEVEL2.LEVEL3.LEVEL4 is a fully-qualified name. The following data set
would be considered partially-qualified names:
LEVEL1.LEVEL2.LEVEL3
LEVEL1.LEVEL2
LEVEL1
Restriction: For the catalog interface, you cannot specify an asterisk (*) or an
ampersand (&) to specify a partially-qualified data set name.
See z/OS DFSMSdfp Diagnosis for descriptions of the contents of the volume control
block and the other catalog data areas.
See “Return Codes from LOCATE” on page 162 for a description of the LOCATE
return codes.
Retrieving Information by Data Set Name (LOCATE and
CAMLST NAME)
Specifying a data set name returns a volume list in your output area. A volume list
consists of an entry for each volume on which part of the data set resides. For each
volume, the list contains the volume serial number, device type, and file sequence
number. Volumes are divided by whether they fall within the minimum unit count,
or outside of it. Volumes within and without are in descending binary order by
device type, except for reusable KSDS. For a reusable KSDS, the volume serial
numbers are returned in the order: first index, first data, remaining index,
remaining data.
A volume list begins with a 2-byte field containing the number of volumes in the
list. The count field is followed by a variable number of 12-byte entries. Each
12-byte entry consists of a 4-byte device code, a 6-byte volume serial number, and
a 2-byte volume sequence number. As many as 20 of these 12-byte entries can be
built in your output area. LOCATE can return bytes 252 - 254 of your area
containing the relative track address of the DSCB on the first or only volume for
that data set. Otherwise, these bytes are zero. Bytes 242 to 251 are reserved, byte
255 contains zeros, and bytes 256 to 264 are also reserved and not intended as a
programming interface.
A CAMLST LOCATE on a VSAM cluster returns the volumes for all components.
The format of this volume list is as described previously. The output is translated
into the format described in the preceding two paragraphs before returning to the
caller. The original VSAM or integrated catalog facility return code is saved in
register 0.
The macro format for the LOCATE and CAMLST NAME is:
►►
LOCATE listname_addrx
label
158
z/OS DFSMSdfp Advanced Services
►◄
CATALOG Macros
►►
listname CAMLST NAME
,dsname_relexp ,area_relexp
►◄
listname_addrx
Points to the parameter list (labeled listname) set up by the CAMLST macro
instruction.
NAME
To retrieve information from a catalog by name, code this operand as shown.
dsname_relexp
Specifies the virtual storage location of a fully-qualified data set name. The
area that contains the name must be 44 bytes long. The name can be defined
by a C-type define constant (DC) instruction.
area_relexp
Specifies the virtual storage location of your 265-byte output area, that you
must define. The output area must begin on a doubleword boundary.
Example
In the following example, the catalog entry containing a list of the volumes on
which data set A.B resides, is read into virtual storage.
LOCATE
INDAB
*
*
*
READ CATALOG ENTRY FOR DATA SET A.B
INTO VIRTUAL STORAGE AREA NAMED LOCAREA.
LOCAREA MAY ALSO CONTAIN A 3-BYTE
TTR OR A 6-BYTE SERIAL NUMBER
Check Return Codes
INDAB
AB
LOCAREA
CAMLST
DC
DS
DS
NAME,AB,,LOCAREA
CL44’A.B’
0D
265C
The LOCATE macro instruction points to the CAMLST macro instruction. NAME,
the first operand of CAMLST, specifies that the system is to search for a catalog
entry using the name of a data set. AB, the second operand, specifies the virtual
storage location of the fully-qualified data set name LOCAREA, the fourth
operand, specifies a 265-byte area you have reserved in virtual storage.
After these macro instructions execute, the 265-byte area contains a volume list or a
volume control block for the data set A.B. If the entry has been located and read
successfully, register 15 contains zeros. Otherwise, register 15 contains a return
code (see “Return Codes from LOCATE” on page 162).
Retrieving Information by Generation Data Set Name (LOCATE
and CAMLST NAME)
Specify the name of a generation data set using the fully-qualified generation index
name and the relative generation number of the data set. The value of a relative
generation number reflects the position of a data set in a generation data group.
The following values can be used to identify a data set in a generation data group:
v Zero—specifies the latest data set (highest generation number) cataloged in a
generation data group.
v Negative number—specifies a data set cataloged before the latest data set.
Chapter 3. Using Catalog Management Macros
159
CATALOG Macros
Rule: If DISP (disposition) is DELETE to make room for other data sets and no
generation data group exists, the job will complete indicating a deleted
generation name (G0000V00). If a generation data group exists but is not in the
range specified for deletion, the step will fail.
v Positive number—specifies a data set not yet cataloged in the generation data
group.
Using zero or a negative number as the relative generation number places a
volume list (or a volume control block) in your output area and replaces the
relative generation number with the absolute generation name.
Using a positive number as the relative generation number creates an absolute
generation name and replaces the relative generation number. Because there are no
entries in the catalog, zeros are read into the first 256 bytes of your output area.
The format for the LOCATE and CAMLST NAME macros is:
►►
LOCATE list_addrx
►◄
label
►►
listname CAMLST NAME
,dsname_relexp ,area_relexp
►◄
list_addrx
Points to the parameter list (labeled listname) set up by the CAMLST macro
instruction.
NAME
To read a block from the catalog by generation data set name, code this
operand as shown.
dsname_relexp
Specifies the virtual storage location of the name of the generation index and
the relative generation number. The area that contains these must be 44 bytes
long.
area_relexp
Specifies the virtual storage location of your 265-byte output area, which you
must define. The output area must begin on a doubleword boundary. The
output area will contain a volume list that is built from the catalog. If the data
set resides on one volume, bytes 252 - 254 can contain the relative track
address of the DSCB. This address is relative to the beginning of the volume.
Example
In the following example, the list of volumes containing generation data set
A.PAY(-3) is read into virtual storage.
160
z/OS DFSMSdfp Advanced Services
CATALOG Macros
LOCATE
INDGX
READ CATALOG ENTRY
FOR DATA SET A.PAY(-3)
INTO YOUR STORAGE
AREA NAMED LOCAREA
*
*
*
Check Return Codes
INDGX
APAY
LOCAREA
CAMLST
DC
DS
DS
NAME,APAY,,LOCAREA
CL44’A.PAY(-3)’
0D
265C
The LOCATE macro instruction points to the CAMLST macro instruction. NAME,
the first operand of CAMLST, initiates a search for a catalog entry using the name
of a data set. APAY, the second operand, specifies the virtual storage location of the
name of the generation index and the relative generation number of a data set in
the generation data group. LOCAREA, the fourth operand, specifies a 265-byte
area you have reserved to receive the catalog information.
After executing this macro instruction, the system replaces the relative generation
number that you specified with the data set's absolute generation name. Control is
returned to your program at the next executable instruction following the LOCATE
macro instruction. If the entry has been located and read successfully, register 15
contains zeros. Otherwise, register 15 contains a return code (see “Return Codes
from LOCATE” on page 162). See “Retrieving Information by Data Set Name
(LOCATE and CAMLST NAME)” on page 158 for a description of the contents of
the output area.
Retrieving Information by Alias (LOCATE and CAMLST NAME)
For each of the preceding functions, you can specify an alias as the name of a data
set. Functions proceed as previously described with one exception: the true name
replaces the specified alias name.
The format for the LOCATE and CAMLST NAME macros is:
►►
LOCATE list_addrx
►◄
label
►►
listname CAMLST NAME
,dsname_relexp ,area_relexp
►◄
list_addrx
Points to the parameter list (labeled listname) set up by the CAMLST macro
instruction.
NAME
To retrieve information from a catalog, code this operand as shown.
dsname_relexp
Specifies the virtual storage location of a fully-qualified data set name, the first
or only name of which is the alias. The area containing the name must be 44
bytes long. The name can be defined by a C-type DC instruction.
area_relexp
Specifies the virtual storage location of your 265-byte output area, that you
Chapter 3. Using Catalog Management Macros
161
CATALOG Macros
must define. The output area must begin on a doubleword boundary. The first
256 bytes of the output area will contain a volume list that is read from a
catalog. If the data set resides on one volume, bytes 252 - 254 can contain the
relative track address of the DSCB. This address is relative to the beginning of
the volume.
Example
In the following example, the catalog entry containing a list of the volumes on
which data set A.B.C resides is read into virtual storage (data set A.B.C, however,
is addressed by an alias name, X.B.C).
LOCATE
INDAB
*
*
*
READ CATALOG ENTRY
FOR DATA SET X.B.C
INTO VIRTUAL STORAGE
AREA NAMED LOCAREA.
Check Return Codes
INDAB
ABC
LOCAREA
CAMLST
DC
DS
DS
NAME,ABC,,LOCAREA
CL44’X.B.C’
0D
265C
The LOCATE macro instruction points to the CAMLST macro instruction. NAME,
the first operand of CAMLST, initiates a search of the catalog for an entry using
the name of a data set. ABC, the second operand, specifies the virtual storage
location of the fully-qualified name of a data set (in this case, data set A.B.C is
addressed by its alias X.B.C). LOCAREA, the fourth operand, specifies a 265-byte
area you have reserved in virtual storage.
See “Return Codes from LOCATE” for a description of the LOCATE return codes.
Reading a Block by Relative Block Address (LOCATE and
CAMLST BLOCK)
This format is no longer supported and will result in an error.
Return Codes from LOCATE
Control is returned to your program at the next executable instruction following
the LOCATE macro instruction. Register 15 contains one of the following return
codes. If register 15 is non-zero, then register 0 contains an ICF catalog return code,
described under message IDC3009I in z/OS MVS System Messages, Vol 6 (GOS-IEA).
Table 29. LOCATE Return Codes
Code
Meaning
0 (X'00')
4 (X'04')
8 (X'08')
Operation successful.
Either the required catalog does not exist or it cannot be opened.
The user is not authorized to perform this operation. Register 0
contains hexadecimal 38.
An invalid low-level GDG name was found.
A data set exists at other than the lowest index level specified.
Register 0 contains the number of the index level where the data set
was encountered.
An invalid name has been provided
12 (X'0C')
16 (X'10')
20 (X'14')
162
z/OS DFSMSdfp Advanced Services
CATALOG Macros
Table 29. LOCATE Return Codes (continued)
Code
Meaning
24 (X'18')
One of the following happened:
v A permanent I/O or unrecoverable error was encountered.
v An error was found in a parameter list. R1 is set to X'08000000'.
v There was a nonzero return code from ESTAE or GETMAIN. R1
is set to X'08000000'.
38 (X'26')
DFSMShsm LOCATE preprocessor has experienced an error.
Note: See z/OS MVS System Messages, Vol 7 (IEB-IEE) and z/OS MVS System Messages, Vol 8
(IEF-IGD), message IDC3009I, for documentation of integrated catalog facility catalog and
VSAM catalog return codes.
Using Non-VSAM Data Set Catalog Entries
You can catalog, uncatalog, and recatalog non-VSAM data sets using the
CATALOG and CAMLST macro instructions. CATALOG macro instructions are
used to point to CAMLST macro instructions and to specify cataloging options.
For a description of the search algorithms used for cataloging, uncataloging, and
recataloging non-VSAM data sets, see the DEFINE and the DELETE commands in
z/OS DFSMS Access Method Services Commands.
Cataloging a Non-VSAM Data Set (CATALOG and CAMLST
CAT)
The format of the CATALOG and CAMLST macros is:
►►
CATALOG
list_addrx
►◄
label
►►
listname CAMLST
CAT
,name_relexp ,vol_list_relexp
►
CATBX
►
►◄
,DSCBTTR=dscb_ttr_relexp
list_addrx
Points to the parameter list (labeled listname) set up by the CAMLST macro
instruction.
CAT or CATBX
Code this operand as shown. Either CAT or CATBX can be coded.
name_relexp
Specifies the virtual storage location of the fully-qualified name of a data set.
The name cannot exceed 44 characters. If the name is less than 44 characters, it
must be followed by at least one blank. In a DFSMShsm environment, if the
data set name is less than 44 characters, it must be padded with blanks until
the 44-character length is reached.
Chapter 3. Using Catalog Management Macros
163
CATALOG Macros
vol list_relexp
Specifies the virtual storage location of an area that contains a volume list. The
list must begin on a halfword boundary and consist of an entry for each
volume on which the data set is stored. The first two bytes of the list indicate
the number of entries in the volume list; the number cannot be zero. Each
12-byte volume list entry consists of a 4-byte device code, a 6-byte volume
serial number, and a 2-byte data set sequence number. The sequence number is
always zero for direct access volumes.
DSCBTTR=dscb ttr_relexp
Specifies the virtual storage location of the 3-byte relative track address (TTR)
of the data set control block (DSCB). This DSCB is on the first or only volume
of the data set. The address is relative to the beginning of the volume.
Programming Considerations for Multiple-Step Jobs
When executing multiple-step jobs, it is preferable to catalog or uncatalog data sets
using JCL, instead of using IDCAMS, IEHPROGM, or a user program. Because
step allocation and unallocation monitors data sets during job execution and is
unaware of functions performed by user programs, conflicting functions can be
performed or GDG orientation can be lost.
Unallocation can recatalog existing cataloged data sets at job termination. This
action occurs when the data set is opened during the job and the DSCB TTR could
not be found in the catalog entry. If you are using the CAMLST macro to uncatalog
and then catalog data sets with new volume information, be sure to include the
DSCB TTR.
Example
In the following example, the non-VSAM data set named A.B.C is cataloged. The
data set is stored on two volumes.
CATALOG ADDABC
CATALOG DATA SET A.B.C.
Check Return Codes
ADDABC
DSNAME
VOLUMES
CAMLST
DC
DC
DC
DC
DC
DC
DC
DC
CAT,DSNAME,,VOLUMES
CL6’A.B.C’
ONE BLANK FOR DELIMITER
H’2’
DATA SET ON TWO VOLUMES
X’3010200E’
3380 DISK DEVICE CODE
CL6’000014’
VOLUME SERIAL NUMBER
H’0’
DATA SET SEQUENCE NUMBER
X’3010200E’
3380 DISK DEVICE CODE
CL6’000015’
VOLUME SERIAL NUMBER
H’0’
SEQUENCE NUMBER
The CATALOG macro instruction points to the CAMLST macro instruction. CAT,
the first operand of CAMLST, specifies that a data set is to be cataloged. DSNAME,
the second operand, specifies the virtual storage location of the data set name
A.B.C. VOLUMES, the fourth operand, specifies the virtual storage location of the
volume list.
Control is returned to your program at the instruction following the CATALOG
macro instruction. Register 15 contains one of the return codes described under
“Return Codes from CATALOG” on page 167.
Uncataloging a Non-VSAM Data Set (CATALOG and CAMLST
UNCAT)
Use this macro to remove a data set reference and unneeded indexes.
164
z/OS DFSMSdfp Advanced Services
CATALOG Macros
The format of the CATALOG and CAMLST macros is:
►►
CATALOG
list_addrx
►◄
UNCAT
UCATDX
►◄
label
►►
listname CAMLST
,name_relexp
list_addrx
Points to the parameter list (labeled listname) set up by the CAMLST macro
instruction.
UNCAT or UCATDX
Code this operand as shown. Either UNCAT or UCATDX can be coded but, in
either case, unneeded indexes, with the exception of the highest-level index,
are removed along with the data set reference.
name_relexp
Specifies the virtual storage location of the fully-qualified name of a data set or
index level. The name cannot exceed 44 characters. If the name is less than 44
characters, it must be followed by at least one blank. In a DFSMShsm
environment, if the data set name is less than 44 characters, it must be padded
with blanks until the 44-character length is reached.
Example
In the following example, the catalog entry for data set A.B.C is removed from a
catalog.
CATALOG REMOVE
*
REMOVE REFERENCES TO DATA SET A.B.C
FROM CATALOG
Check Return Codes
REMOVE
DSNAME
CAMLST
DC
UNCAT,DSNAME
CL6’A.B.C’
ONE BLANK FOR DELIMITER
The CATALOG macro instruction points to the CAMLST macro instruction.
UNCAT, the first operand of CAMLST, specifies that references to a data set are to
be removed from the catalog. DSNAME, the second operand, specifies the virtual
storage location of the fully-qualified name of the data set whose references are to
be removed.
Control is returned to your program at the instruction following the CATALOG
macro instruction. Register 15 contains one of the return codes described under
“Return Codes from CATALOG” on page 167.
Restriction: The CAMLST UNCAT or UCATDX function is not supported for
system-managed data sets. These are ignored. The function is not performed and
the return code is 0.
Chapter 3. Using Catalog Management Macros
165
CATALOG Macros
Recataloging a Non-VSAM Data Set (CATALOG and CAMLST
RECAT)
You can recatalog a non-VSAM data set using the CATALOG and CAMLST macro
instructions. Recataloging is usually necessary if a data set is extended to a new
volume.
Build a complete volume list in virtual storage consisting of an entry for each
volume on which the data set resides. The first 2 bytes of the list indicate the
number of entries in the list; the number must not be zero. Each 12-byte volume
pointer consists of a 4-byte device code, a 6-byte volume serial number, and a
2-byte data set sequence number. The sequence number is always zero for direct
access volumes.
The format of the CATALOG and CAMLST macros is:
►►
CATALOG
list_addrx
►◄
label
►►
listname CAMLST RECAT
,name_relexp ,vol_list_relexp
►
►
►◄
,DSCBTTR=dscb_ttr_relexp
list_addrx
Points to the parameter list (labeled listname) set up by the CAMLST macro
instruction.
RECAT
Code this operand as shown.
name_relexp
Specifies the virtual storage location of the fully-qualified name of a data set.
The name cannot exceed 44 characters. If the name is less then 44 characters, it
must be followed by at least one blank. In a DFSMShsm environment, if the
data set name is less than 44 characters, it must be padded with blanks until
the 44-character length is reached. A C-type DC instruction can define the
name.
vol list_relexp
Specifies the virtual storage location of an area that contains a volume list. The
area must begin on a halfword boundary.
DSCBTTR=dscb ttr_relexp
Specifies the virtual storage location of the 3-byte relative track address (TTR)
of the identifier DSCB. This DSCB is on the first or only volume of the data
set. The address is relative to the beginning of the volume.
Example
In the following example, the two-volume data set named A.B.C is recataloged to
add a third volume. An entry is added to the volume list, that previously
contained only two entries.
166
z/OS DFSMSdfp Advanced Services
CATALOG Macros
CATALOG RECATLG
*
*
RECATALOG DATA SET
A.B.C ADDING A NEW
VOLUME
Check Return Codes
RECATLG
DSNAME
VOLUMES
CAMLST
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
RECAT,DSNAME,,VOLUMES
CL6’A.B.C ’
FOR DELIMITER ONE BLANK
H’3’
THREE VOLUMES
X’3010200E’
3380 DISK DEVICE CODE
CL6’000014’
VOLUME SERIAL NUMBER
H’0’
SEQUENCE NUMBER
X’3010200E’
3380 DISK DEVICE CODE
CL6’000015’
VOLUME SERIAL NUMBER
H’0’
SEQUENCE NUMBER
X’3010200E’
3380 DISK DEVICE CODE
CL6’000016’
VOLUME SERIAL NUMBER
H’0’
SEQUENCE NUMBER
The CATALOG macro instruction points to the CAMLST macro instruction.
RECAT, the first operand of CAMLST, specifies that a data set is to be recataloged.
DSNAME, the second operand, specifies the virtual storage location of the
fully-qualified name of the data set to be recataloged. VOLUMES, the fourth
operand, specifies the virtual storage location of the volume list you have built.
Control is returned to your program at the instruction following the CATALOG
macro instruction. If the data set has been successfully recataloged, register 15
contains zeros. Otherwise, register 15 contains one of the return codes described
under “Return Codes from CATALOG.”
Return Codes from CATALOG
Control is returned at the instruction following the CATALOG macro instruction.
Register 15 might contain one of the following return codes. Register 15 contains
one of the following return codes. If register 15 is non-zero, then register 0 contains
an ICF catalog return code, described under message IDC3009I in z/OS MVS
System Messages, Vol 6 (GOS-IEA)
Table 30. CATALOG Return Codes
Code
Meaning
0 (X'00')
4 (X'04')
8 (X'08')
Operation successful.
Either the required catalog does not exist or it is not open.
One of the following happened:
v The existing catalog structure is inconsistent with the operation
requested.
20 (X'14')
28 (X'1C')
v The user is not authorized to perform the operation.
There is insufficient space in the catalog data set. If R1 =
X'08000000', then an invalid name has been provided
One of the following happened:
v A permanent I/O or unrecoverable error was encountered.
v An error was found in a parameter list. R1 is set to X'08000000'.
v There was a nonzero return code from ESTAE or GETMAIN. R1
is set to X'08000000'.
Chapter 3. Using Catalog Management Macros
167
CATALOG Macros
168
z/OS DFSMSdfp Advanced Services
Chapter 4. Executing Your Own Channel Programs
This information describes the execute-channel-program (EXCP) and
execute-channel-program-virtual-real (EXCPVR) macro instructions and is provided
for compatibility with other IBM operating systems. References to EXCP apply
equally to EXCPVR unless otherwise stated. IBM recommends using an access
method such as VSAM in place of EXCP or EXCPVR.
The EXCP and EXCPVR macro instructions allow you to control the data
organization based on device characteristics. The exceptions to this capability are
partitioned data sets extended (PDSEs), extended format data sets, spooled and
dummy data sets, TSO terminals, and z/OS UNIX files and file systems. They are
not supported for user-written applications using EXCP. This information covers
EXCP macro instruction application and function and includes descriptions of
specific control blocks and macro instructions. Factors that affect the operation of
EXCP, such as device variations and program modification, are also discussed.
Before reading this information, you should be familiar with the operational
characteristics of the I/O devices required by your channel programs. Operational
characteristics are described in IBM publications for each I/O device. You also
need to understand the information in the following publications:
v HLASM Programmer's Guide, which is available at High Level Assembler and
Toolkit Feature in IBM Knowledge Center (www.ibm.com/support/
knowledgecenter/SSENW6), contains information about coding programs in the
assembler language.
v z/Architecture Principles of Operation, SA22-7832, describes channel command
words (CCWs) and channel programs.
v z/OS DFSMS Using Data Sets contains the standard procedures for I/O
processing under the operating system.
v z/OS DFSMS Macro Instructions for Data Sets describes the system macro
instructions that can be used in programs coded in the assembler language.
EXCP is primarily for I/O programming situations that cannot be dealt with using
standard access methods. When writing your own access method, include EXCP
for I/O operations. You must also use EXCP for processing nonstandard magnetic
tape labels, including reading and writing labels and positioning volumes.
To issue EXCP, provide a channel program and control blocks in your program
area. The I/O process then schedules I/O requests for the specified device,
executes commands, handles interruptions, directs error recovery procedures, and
posts the results of I/O requests.
Comparing EXCP and EXCPVR
EXCP and EXCPVR are two macros you can use to initiate channel program I/O
operations, or as it is often put, execute a channel program. Both provide the same
function - a device dependent way to perform I/O operations. However, there are
a number of differences:
v In order to issue an EXCPVR request, your program must run in a protection
key between zero and seven, run in supervisor state, or be APF authorized. An
© Copyright IBM Corp. 1979, 2017
169
EXCP request, on the other hand, can be issued by programs running in any key,
including user key (key 8) or problem state.
v If you issue an EXCPVR request, your program is responsible for translating its
own virtual channel program into a real channel program. This includes page
fixing your channel program and I/O buffers either before issuing the EXCPVR
request, or by using the page fix appendage and updating your channel
program with real addresses, building indirect address lists when needed, and
updating the address fields within your channel program with real addresses.
This allows your program to improve the efficiency of I/O operations in a
paging environment, but does add some complexity to your program.
If you issue an EXCP request, you supply a virtual channel program. In other
words, the channel program contains the virtual addresses of storage areas that
may be in pageable storage, and the system is responsible for translating your
virtual channel program into a real channel program.
Note that EXCP requests issued in an APF-authorized program in a V=R address
space (EXCP V=R requests, in other words) are not translated. A V=R address
space is one defined with ADDRSPC=REAL in the JCL EXEC statement. Because
the address space is V=R, any CCWs created by the user already have correct
real data addresses. (Translation would only re-create the user's channel
program, so the CCWs are used directly.)
For information on using APF, see z/OS MVS Programming: Authorized Assembler
Services Guide.
Table 31. Summary of the differences between EXCP, EXCPVR, and EXCP V=R
EXCP
Characteristics
EXCPVR
Characteristics
EXCP V=R
Characteristics
Program state and key
Any protection key,
supervisor or
problem state.
Protection keys 0-7,
supervisor state, or
APF authorized.
Protection keys 0-7,
supervisor state, or
APF authorized.
User responsible for translating their channel
program
No
Yes
No translation
required.
CCW formats supported
0 and 1
0 and 1
0 and 1
Virtual IDAW supported
Yes
No
No
No
Yes
No
High Performance FICON for System z
(zHPF) channel programs supported
Yes
Yes
No
User can modify channel program during
execution
No
Yes, non-zHPF only
Yes
Self modifying channel programs supported
No
Yes, non-zHPF only
Yes
Function
MIDAWs supported
®
Using EXCP and EXCPVR
This information briefly explains the procedures required when issuing the EXCP
and EXCPVR macro instruction. To issue the EXCP or EXCPVR macro instruction
directly, perform the following tasks.
1. Allocate the data set or device to be used for the EXCP request. See “Allocating
the Data Set or Device” on page 171.
2. Construct and open a data control block (DCB) with the DCB and OPEN macro
instructions. Optionally create a data control block extension (DCBE) before
issuing the OPEN macro. See “Initializing a Data Control Block (OPEN)” on
page 240and “Opening the Data Set” on page 172.
170
z/OS DFSMSdfp Advanced Services
3. Create a channel program containing the commands necessary to perform the
I/O operations on the appropriate device. See “Creating the Channel Program”
on page 173.
4. Create the control blocks needed to initiate the EXCP request. This includes the
input/output block (IOB) and event control block (ECB), and optionally the
input/output block extension (IOBE), and input/output error data block
(IEDB). See “Creating the EXCP-Related Control Blocks” on page 184.
For more information on specific control blocks, see “Control Block Fields” on
page 196.
5. Issue an EXCP or EXCPVR macro instruction to pass the address of the IOB,
and optionally the IOBE, to the routines that initiate and supervise I/O
operations.
After issuing EXCP or EXCPVR, issue a WAIT or EVENTS macro instruction
specifying the address of the ECB, to wait for the channel program to complete.
See “Executing the Channel Program” on page 185.
6. Once the I/O request has completed, examine the completion status of your
EXCP or EXCPVR request and process any error conditions that may have
occurred. See “Processing the I/O Completion Status” on page 189.
7. If volume switching is necessary (because of a unit exception or end of DASD
extent), issue the EOV macro. See “Handling End of Volume and
End-Of-Data-Set Conditions” on page 193.
8. When data set processing is complete, close the data set to restore the DCB. See
“Closing the Data Set” on page 195.
9. If your program called dynamic allocation, it can optionally call dynamic
unallocation.
Allocating the Data Set or Device
You allocate the data set or device in one of the following ways:
v Using job step allocation, see z/OS MVS JCL Reference
v Using dynamic allocation, see one of the following:
– z/OS MVS Programming: Authorized Assembler Services Guide
– z/OS TSO/E Command Reference
When your program calls dynamic allocation using SYC 99 or the DYNALLOC
macro, you can use the XTIOT option, which is bit S99TIOEX. It causes creation of
an XTIOT entry instead of an entry in the TIOT. The XTIOT resides above the 16
MB line. This option requires your program to be APF authorized, in supervisor
state, or in a system key (0–7).
With dynamic allocation, you can use the NOCAPTURE option, which is bit
S99ACUCB. If the actual UCB address is above the 16 MB line and you do not
code LOC=ANY option on the DCBE macro, then, OPEN and EOV will capture it
and EOV and CLOSE will uncapture it. (Capturing means to create a 24–bit address
for a UCB that has an actual address above the 16 MB line. This NOCAPTURE
option also causes creation of an XTIOT instead of a TIOT entry, but it does not
require your program to have authorization). If you code the LOC=ANY option on
the DCBE, then OPEN will not capture the UCB and its address will be in a
four-byte field in the DEB.
With dynamic allocation, you can use the S99DSABA bit, which allows the DSAB
control block to reside above the 16 MB line. If you turn S99DSABA on, then you
must also turn on S99TIOEX and your program must be authorized.
Chapter 4. Executing Your Own Channel Programs
171
The purpose of these three dynamic allocation options (XTIOT, NOCAPTURE, and
LOC=ANY) is to reduce use of storage below 16MB. BSAM, BPAM, and QSAM
also support these three options.
To learn whether the allocation has any of these three options, issue the DEVTYPE
macro with the INFO=AMCAP option. On a system before z/OS V1R11, bits
S99DSABA and S99TIOEX will be off. On a release V1R12 or later system, these
options should only be used when NON_VSAM_XTIOT=YES is specified in the
DEVSUPxx parmlib member. This is represented by the DFAXTBAM bit in the
DFA as mapped by IHADFA.
Opening the Data Set
You must supply a DCB for each data set or device to open. The OPEN macro
instruction finishes initializing one or more DCBs so that their associated data sets
can be processed. Issue OPEN for all DCBs used by your channel programs. (A
dummy data set cannot be opened for EXCP.) Some of the procedures performed
by OPEN are:
v Checking data set access authorization
v Constructing the data extent block (DEB)
v Completing the fields in the DCB and DCBE
v Verifying or creating standard labels
v Positioning tape
v Loading your appendage routines.
v Capturing the UCB if the DCBE option "LOC" was set or defaulted to "BELOW",
that is LOC=BELOW or not coded, or the "NON_VSAM_XTIOT" option of the
DEVSUPxx member of PARMLIB was set or defaulted to "NO", that is
NON_VSAM_XTIOT=NO or not coded. In other words, OPEN does not capture
the UCB if LOC and NON_VSAM_XTIOT were specified as follows: LOC=ANY
and NON_VSAM_XTIOT=YES.
The parameters and different forms of the OPEN macro instruction are described
in “OPEN - Initialize Data Control Block for Processing the JFCB” on page 302 and
z/OS DFSMS Macro Instructions for Data Sets.
Direct Data Set Considerations
To process a multivolume direct data set (BDAM) with EXCP, use the open
routines to build a data extent block for each volume. Your program can do this by
reading in the JFCB with a RDJFCB macro instruction and opening each volume of
the data set with a separate DCB. See “Using BSAM or EXCP for Random I/O to a
Multivolume Data Set” on page 292 for an example of how to code a routine to do
this, and “Reading and Modifying a Job File Control Block (RDJFCB Macro)” on
page 284 for further uses of the RDJFCB macro.
VSAM Data Set Considerations
With a DCB used to open a component of a VSAM data set you can perform the
following tasks:
v Verify that an application has master password or RACF alter authority for the
data set.
v Read from or write to a data set to repair data set or catalog damage if normal
VSAM processing cannot. Because of the potential for damaging a valid data set
or catalog, exercise extreme caution when writing an application using this
interface.
172
z/OS DFSMSdfp Advanced Services
You can specify a DCB when opening a component (data or index) of a VSAM
data set if the following conditions are met:
v The application has master password or RACF alter authority for the data set.
v The component must not reside on multiple volumes.
v The component must not be a member of a concatenation.
v The DCB must specify the EXCP access method.
v The data set disposition must be either (OLD,KEEP,KEEP) or (SHR,KEEP,KEEP)
v The DCB must specify either the INPUT or UPDAT option.
v Your program must be either APF authorized or in supervisor state.
When opening a VSAM component on a volume that supports extended attribute
DSCBs, the specified DCB must point to a DCBE with the EADSCB=OK keyword.
When EADSCB=OK is specified, your program must support extended attribute
DSCBs. These are format-8 and format-9 DSCBs, where the extent descriptors may
contain 28-bit cylinder numbers.
Creating the Channel Program
The channel program contains the instructions used by the channel subsystem and
the device to execute an I/O operation. This section describes what you need to
consider when you create a channel program for an EXCP request.
There are two types of channel programs, which are described in the following
sections:
v “CCW Channel Program”
v “zHPF Channel Program” on page 175
CCW Channel Program
The CCW channel program you supply is composed of CCWs on doubleword
boundaries. Each channel command word specifies a command to be executed
and, for data transfer commands, the source or destination area. CCW operation
codes are described in the IBM publications for each I/O device.
You can specify both data chaining and command chaining by setting applicable
chaining bits in the channel command word and indicating the type of chaining in
the IOB. If an I/O error occurs while your channel program executes, the
corresponding chaining bits in the IOB need to be set. Otherwise, error recovery
could be impossible. The integrity of your data could be compromised. (See
“Input/Output Block (IOB) Fields” on page 211 for additional information.) If you
specify both data and command chaining in the same channel command word,
data chaining takes precedence.
The location of the CCWs, IDALs, MIDALs and I/O buffers in virtual and central
storage depend on whether you are using EXCP or EXCPVR, whether you are
using format 0 or 1 CCWs, and whether the device supports 64-bit IDALs or
MIDALs. In particular:
v When you use format-0 CCWs, the CCWs and the storage areas pointed to by
the CCWs (IDALs, MIDALs, or I/O buffers) must be in 24-bit storage.
Otherwise, you can use 31-bit storage.
v When the CCW points to an indirect address list (IDAL), each indirect address
list word (IDAW) in the list points to a 31-bit or 64-bit I/O buffer, depending on
whether 31-bit or 64-bit IDAWs are used and whether the device supports 64-bit
IDAWs. 64-bit IDAWs are only supported for disk and tape devices.
Chapter 4. Executing Your Own Channel Programs
173
v When the CCW points to a modified indirect address list (MIDAL), each
modified indirect address word (MIDAW) in the list points to a 64-bit I/O
buffer. MIDAWs are only supported for EXCPVR requests for disk devices and
only when running on an IBM System z9® or higher processor.
v For EXCP requests, the system translates your virtual channel program into a
real channel program. During the translation process, the CCWs are copied to
fixed storage, IDALs are created, and the I/O buffers are page fixed. Therefore,
the storage restrictions mentioned above apply only to the virtual storage
locations of the CCWs and IDALs; the CCWs and IDALs may reside anywhere
in central storage. However, if the I/O buffer resides in 64-bit central storage,
the device must support 64-bit IDAWs or else the system fails the EXCP request.
v Because the system does translate your channel program for an EXCPVR
request, the storage restrictions mentioned above apply to both virtual and
central storage. For example, if format-0 CCWs are used, the CCWs and the
storage areas pointed to by the CCWs (IDALs, MIDALs, or I/O buffers) must be
in 24-bit virtual and central storage. However, the IDALS and MIDALS can still
point above the 16MB line.
The following table summarizes the channel program storage requirements for
different types of CCW channel programs:
Table 32. Storage area locations for CCW channel program components
Request and format
Channel Program
Component
Virtual storage location
Central storage location
EXCP format 0
CCW
24-bit
Any
IDAL
24-bit
Any
I/O Buffer
v 24-bit if pointed to by
CCW
v 31 or 64-bit if pointed to
by an IDAW
Any
CCW
31-bit
Any
IDAL
31-bit
Any
I/O Buffer
v 31-bit if pointed to by
CCW
v 31 or 64-bit if pointed to
by an IDAW or MIDAW
Any
CCW
24-bit
24-bit
IDAL
24-bit
24-bit
MIDAL
24-bit
24-bit
I/O Buffer
v 24-bit if pointed to by
CCW
v 31 or 64-bit if pointed to
by an IDAW or MIDAW
v 24-bit if pointed to by
CCW
v 31 or 64-bit if pointed to
by an IDAW or MIDAW
CCW
31-bit
31-bit
IDAL
31-bit
31-bit
MIDAL
31-bit
31-bit
I/O Buffer
v 31-bit if pointed to by
CCW
v 31 or 64-bit if pointed to
by an IDAW or MIDAW
v 31-bit if pointed to by
CCW
v 31 or 64-bit if pointed to
by an IDAW or MIDAW
EXCP format 1
EXCPVR format 0
EXCPVR format 1
174
z/OS DFSMSdfp Advanced Services
zHPF Channel Program
zHPF channel programs are supported for EXCP and EXCPVR requests for DASD
devices. The following diagram shows the different parts of a zHPF channel
program.
TCCB
TCA header
TCW
TCA (DCWs and control data)
TCA trailer
Commands and control data/parameters
TSB
I/O completion info,
sense data, measurement
statistics
Data
TIDAL
Indirect address list
Read and write
data buffers
Figure 10. zHPF channel program
The parts of a zHPF channel program include:
v A transport control word (TCW) that contains pointers to all of the other areas
of the channel program and the number of bytes to be read or written. The
channel uses the TCW to transport the commands and data to the device and
locate the status block used to store ending status information; it is not sent to
the device. You can use the IOSDTCW macro to map the TCW.
For an EXCPVR request, the TCW must reside in 24 or 31-bit central and virtual
storage
For EXCP, the TCW must be in 24 or 31-bit virtual storage or anywhere in
central storage.
For both EXCP or EXCPVR, the TCW must start on a 64-byte boundary. If the
TCW does not start on a 64-byte boundary, EXCP fails the request with abend
code 800, reason code X'OA'.
v A transport status block (TSB) that contains I/O completion information, sense
data and measurement statistics. The TSB is assigned by z/OS, not the EXCP
user. If you provide a TCW with a non-zero TSB address, EXCP fails the request
with abend code 800. The system copies all relevant status information from the
TSB into the IOBE.
v A transport command control block (TCCB) containing the commands and
control data parameters to be passed to the device. The TCCB should start on a
double word boundary, must reside within a 4 KB page, and may reside in
64-bit virtual and central storage. You can use the IOSDTCCB macro to map the
TCCB, including device command words (DCWs). The TCCB consists of three
parts:
– Transport control area header (TCAH) containing information about the
transport control area (TCA) and the commands contained within.
– Transport control area (TCA) containing the commands and control
parameters. Each command is represented by a DCW that consists of a
Chapter 4. Executing Your Own Channel Programs
175
command code, flags to indicate chaining and other toptions, a control data
count, and a data byte count, if the command is used to transfer data. If the
command transfers control data (command parameters) to the device, the
control data follows the DCW in the TCA.
Unlike CCWs, DCWs do not point to their corresponding I/O buffers. The
I/O buffers for all DCWs are pointed to by the TCW, and the I/O buffers
associated with a particular DCW are based on the amount of data
transferred by the previous DCWs.
The maximum size of the TCA is 240 bytes.
– Transport control area trailer (TCAT) containing the number of bytes
transferred.
The System z I/O architecture allows the TCCB to be pointed to either directly
by the TCW or indirectly via a transport indirect address list (TIDAL). However,
TCCB TIDALs are not supported for EXCP or EXCPVR requests. If a TCCB
TIDAL is specified, EXCP fails the request with abend code 800.
v One or more I/O buffers. The TCW may point to a single read and/or write
buffer.
For EXCPVR requests, the I/O buffesr can be up to 4 KB in size. If more than 4
KB of data needs to be transferred or the data is non-contiguous or spans a
page, a data TIDAL must be created. The I/O buffers and the TIDAWs may
reside in 64-bit virtual and central storage. A TIDAL can also be chained to
another TIDAL by setting the TIDAL transfer-in-channel (TTIC) bit in the last
TIDAW in the list. In this case, the TIDAW address field does not point to an
I/O buffer, but instead points to another TIDAL.
For EXCP requests, the I/O buffers can be greater than 4KB - see “TIDAW
requirements for EXCP requests” on page 181.
The following table summarizes the channel program storage requirements for
zHPF channel programs:
Table 33. Storage area locations for zHPF channel program components
Request and format
Channel Program
Component
Virtual storage location
Central storage location
EXCP
TCW
31-bit
Any
TCCB
Any
Any
TIDAL
Any
Any
I/O Buffer
Any
Any
TCW
31-bit
31-bit
TCCB
Any
Any
TIDAL
Any
Any
I/O Buffer
Any
Any
EXCPVR
Comparing CCW and zHPF channel programs
Table 34. Comparing CCW and zHPF channel programs
176
Function
CCW channel programs
zHPF channel programs
Devices supported
All
DASD only
z/OS DFSMSdfp Advanced Services
Table 34. Comparing CCW and zHPF channel programs (continued)
Function
CCW channel programs
zHPF channel programs
Processors supported
All
EXCP and EXCPVR are only
supported on a zEnterprise®
196 (z196) zEnterprise 114
(z114) or higher processor
Command set
All commands for all
currently supported devices
Subset of DASD commands
Maximum channel program
size
No limit
240 bytes because of the TCA
size limit
Maximum data transferred
per CCW or TCW
64 KB-1
64 KB, 2 MB, or 4 GB,
depending on the processor
Read and write commands in Yes
the same channel program
No
Skip on read
CCW or MIDAW skip bit
TIDAW skip bit
Indirect addressing
IDAL, MIDAL
TIDAL
Data Chaining
Yes
No, but TIDAL is equivalent
to data chaining.
Status modifier/search
commands
Yes
No
Program controlled interrupt
(PCI)
Yes
No
Append to running channel
program
Yes
No
Self-modifying channel
programs
Yes
No
VIO data sets
Yes
No
EXCP 64-bit Storage Considerations
For EXCP virtual requests, the system page fixes the I/O buffers associated with
your channel program. These I/O buffers may reside in 31-bit or 64-bit virtual
storage.
If the I/O buffers reside in 64-bit virtual storage (referred to as a memory object),
you must follow the following requirement:
v The I/O buffers must not reside within a memory object backed by 1 MB fixed
real page frames. For example, you cannot specify PAGEFRAMESIZE=1MEG or
PAGEFRAMESIZE=MAX on the IARV64 GETSTOR request that creates the
memory object. If you do, EXCP fails when it attempts to page fix the storage.
IDAW Requirements for EXCP Requests
For EXCP requests, the virtual channel program provided by the caller can have
one or more CCWs with the indirect address (IDA) flag set and the address
portion of these CCWs pointing to a single 31-bit or 64-bit IDAW. This EXCP
function is referred to as virtual IDAWs.
The 31-bit IDAW can contain a valid virtual address up to the maximum 31-bit
address. Virtual IDAWs are supported on all virtual CCWs except:
v Transfer in channel (TIC) commands
v Read, read backward, and sense commands, with the skip flag set.
Chapter 4. Executing Your Own Channel Programs
177
v All nondata-transfer type commands: for example, recalibrate, rewind, forward
space, fold, block data check, no operation, control commands
A virtual IDAW points to a single, contiguous 31-bit or 64-bit virtual storage area.
The virtual storage area can be backed by central storage above or below 2 GB.
Either type of virtual IDAW can point to storage that is backed above 2 GB. When
EXCP translates the channel program, the virtual IDAW is translated into one or
more real IDAWs in 31-bit central storage.
Note: 64-bit IDAWs are supported only for direct access storage devices (DASD)
and on all IBM-supplied cartridge tape devices. You should examine bit
UCBEIDAW in the UCB to determine whether 64-bit IDAWs are supported by the
device.
IDAW Requirements for EXCPVR Requests
For EXCPVR requests, the caller is responsible for creating IDAWs when the data
areas associated with the CCWs in your channel program cross certain boundaries.
This can be done before issuing the EXCPVR macro or by the SIO appendage after
the EXCPVR macro is issued. See “SIO Appendage” on page 227 for more
information.
For format-0 channel programs, the CCWs and IDAWs must be below 16 MB in
central storage. For format-1 channel programs, the CCWs and IDAWs must be
below 2 GB in central storage. Regardless of the channel program format, you can
use 31-bit or 64-bit IDAWs to point to storage areas above or below 2 GB in central
storage.
Note: 64-bit IDAWs are supported only for direct access storage devices (DASD)
and on all IBM-supplied cartridge tape devices. You should examine bit
UCBEIDAW in the UCB to determine whether 64-bit IDAWs are supported by the
device. If you use 64-bit IDAWs, an IOBE must be specified for the EXCPVR
request and flag IOBEEIDA in the IOBE must be set.
If data areas do cross boundaries, provide an additional IDAW in the IDAL for
each crossed boundary.
v If you use 31-bit IDAWs , you must use 2 KB boundaries.
v If you use 64-bit IDAWs, you must use 4 KB boundaries.
The channel subsystem uses the IDAL to identify the address where it will
continue reading or writing when a boundary is crossed during a read or write
operation. The IDAL must contain central storage addresses when it is processed
by the channel subsystem.
Before you convert the virtual addresses in the channel program to real addresses,
you must first page fix the data areas in central storage. This can be done before
issuing the EXCPVR macro or by the page fix appendage after the EXCPVR macro
is issued. After the data areas have been page fixed, you can use the LRA
instruction to convert the virtual addresses in the channel program to central
storage addresses, as long as the central storage addresses are below 2 GB. The
LRA instruction returns a 31-bit central storage address regardless of whether you
are in 24-bit or 31-bit addressing mode, but fails in those addressing modes if the
central storage address is above 2 GB. If the central storage address is above 2 GB,
you must either use the LRAG or STRAG instruction to convert the virtual address
to a real address or else use the LRA instruction after first switching to 64-bit
addressing mode.
178
z/OS DFSMSdfp Advanced Services
If all of the central storage addresses associated with the data buffers are below 2
GB, then you can use 2 KB (31-bit) IDAWs to address the data. Otherwise, you
must use 4 KB (64-bit) IDAWs to address the data. For the most efficient use of
system resources, code LOC=(ANY,64) or LOC=(BELOW,64) when you obtain
storage with the GETMAIN or STORAGE macro. See z/OS MVS Programming:
Assembler Services Reference ABE-HSP.
The following illustration shows the relationship between the CCW and the
IDAWs.
Format 0 CCW
Command
Code
0
Address of the IDAL
X4
7 8
Byte Count
31 32
39 40
47 48
63
IDAL
0
First indirect data
address word
4
Second indirect data
address word
8
Subsequent indirect
data address word
Format 1 CCW
Command
Code
0
Byte Count
X4
7 8
15 16
Address of the IDAL
31 32
63
IDAL
0
First indirect data
address word
4
Second indirect data
address word
8
Subsequent indirect
data address word
Note the following information about the IDAL:
v If you are using 31-bit IDAWs, then after the first entry, put one entry in the
IDAL for each 2 KB page boundary that your data area crosses.
v If you are using 64-bit IDAWs, put one entry in the IDAL for each 4 KB page
boundary that your data area crosses and set flag IOBEEIDA in the IOBE..
v If the format 0 CCW has an IDAL address rather than a data address, you must
set the indirect address flag (bit 37) on to signal this to the channel. The
equivalent format 1 CCW bit is bit 13.
v You can determine the maximum number of entries needed in the IDAL from
the count in the CCW as follows:
Number of IDAWSs = (CCW-byte-count + P + P - 2 ) / P
– Substitute 2048 for P in this formula for 31-bit IDAWs.
– Substitute 4096 for P in this formula for 64-bit IDAWs.
For example, the following shows the maximum number of IDAWs for a
particular CCW byte-count and a page boundary of 4 KB:
Chapter 4. Executing Your Own Channel Programs
179
Table 35. Maximum Number of IDAWs for CCW byte-counts
CCW byte-count
Maximum number of IDAWs
1
1
2
2
4095
2
4096
2
4097
2
4098
3
The number of 31-bit IDAWs that are required depends on the number of 2 KB
boundaries that are crossed by the data. For example, if your data is 800 bytes long
and does not cross a 2 KB boundary, no IDAWs are required. If your data crosses a
4 KB boundary, then two IDAWs are required. If your data is 5000 KB long, at least
two IDAWs are required. If your data crosses two 4 KB boundaries, four IDAWs
are required.
The first indirect address is the central storage address of the first byte of the data
area. The second and subsequent indirect addresses are the central storage
addresses of the second and subsequent 2 KB or 4 KB boundaries of the data area.
For example, if the data area central storage address is X'707FF' and the byte count
is X'1802', the 4-byte IDAL contains the following central storage addresses
(assuming the central storage addresses are contiguous):
707FF
70800
71000
If the data area central storage address is X'707FF' and the byte count is X'800', the
IDAL contains the following addresses:
707FF
70800
MIDAW Requirements
For EXCPVR requests, the channel program provided by the caller can have one or
more CCWs with the modified indirect address (MIDA) flag set. When this flag is
set, the CCW points to a list of one or more modified indirect address words
(MIDAWs). MIDAWs are similar to IDAWs except that the boundary and length
requirements are relaxed. For example, each IDAW in a list, except the first, must
point to a storage area on either a 2 KB or 4 KB boundary depending on the type
of IDAW, and the length includes storage up to the next 2 KB or 4 KB boundary or
until the CCW count is exhausted. On the other hand, MIDAWs can point
anywhere on a page and contain any length as long as a page boundary is not
crossed. MIDAWs can reduce the number of CCWs in your channel program by
eliminating the need for data chaining, thereby improving the performance of your
channel program.
MIDAWs are supported only for direct access storage devices (DASD) and only
when running on an IBM System z9 or higher processor. Examine bit UCBMIDAW
in the UCB to determine whether MIDAWs are supported by the device
If you use MIDAWs, you must specify an IOBE for the EXCPVR request and set
flag IOBEMIDA in the IOBE.
180
z/OS DFSMSdfp Advanced Services
TIDAW requirements for EXCP requests
The input and output data pointers in the TCW may point to a single, contiguous
area of storage, or may point to a virtual TIDAL that consists of one or more
virtual TIDAWs, each of which may points to a contiguous area of storage. Unlike
the zHPF channel programs created by EXCPVR, these storage areas may be larger
than 4K and may span page boundaries.
During channel program translation EXCP creates a real TIDAL when any of the
following is true:
v
The TCW input or output data pointer points to a virtual storage area that
spans pages. For example, the TCW input address points to a 16K byte virtual
storage area or points to a 2K byte area that crosses a page boundary.
v The TCW points to a virtual TIDAL. Unlike CCW channel programs, the TIDAL
may consist of multiple TIDAWs, each of which can point to a virtual storage
area that spans pages. Supporting multiple TIDAWs is necessary for zHPF
because there is only a single input and output area pointer (rather than one per
CCW), so the storage areas are more likely to be scattered throughout virtual
storage.
An EXCP Request with a Single 16K Storage Area
In Figure 11, the TCW points to a single 16K area of storage. When EXCP translates
the channel program, it creates four TIDAWs, one for each page.
TCW
1000x
TCW
1000x
2000x
2000x
3000x
TIDAW (4K)
3000x
TIDAW (4K)
TIDAW (4K)
4000x
4000x
TIDAW (4K)
Translated channel program
User channel program
Figure 11. How EXCP translates an EXCP request with a single 16K storage area
Note that if the TCW points to an area that is less than or equal to 4K but spanned
pages, EXCP will create two TIDAWs.
An EXCP Request with a virtual TIDAL
In Figure 12 on page 182, the TCW points to the virtual address of a TIDAL. The
TIDAWs within the TIDAL point either to storage areas that larger than 4K or to
storage areas that cross page boundaries. The TIDAL itself also crosses a page
boundary. Note that for EXCPVR requests, this would not be allowed because it
violates I/O architecture rules. However, for EXCP requests, the virtual TIDAL
may have any alignment and may cross page boundaries - EXCP will translate the
virtual TIDAL to a real TIDAL and ensure proper alignment and ensure that page
boundaries are not crossed.
Chapter 4. Executing Your Own Channel Programs
181
TCW
TCW
input count=24K
TIDAL@=nnnnnnn4x
input count=24K
1000x
2000x
3000x
TIDAW (12K)
TIDAW (8K)
TIDAW (4K)
TIDAL@=nnnnnnn4x
TIDAW (4K)
7400x
8400x
F800x
User channel program
TIDAW (4K)
TIDAW (4K)
TIDAW (4K)
TIDAW (4K)
TIDAW (4K)
TIDAW (4K)
TIDAW (4K)
1000x
2000x
3000x
7400x
8000x
9000x
F800x
10000x
Translated channel program
Figure 12. How EXCP translates an EXCP request with a storage areas crossing page
boundaries
Determining Whether zHPF is Supported for a Device
Before you create and use a zHPF channel program, you must make sure that
zHPF and the zHPF incorrect length facility are supported for both the device and
the processor involved. An EXCP or EXCPVR request is only supported on z196 or
z114 processors that support the zHPF incorrect length facility. To determine
whether the processor supports zHPF, the zHPF incorrect length facility and
EXCP/EXCPVR, issue the IOSZHPF macro with the DEVINFO=YES parameter.
DEVINFO returns 8 bytes of information about zHPF functions supported for the
device, including:
v Processor and z/OS capabilities
– Functions supported by the channel subsystem and online channels for a
device
– Maximum data transfer size
– EXCPVR/EXCP virtual supported
– Incorrect length support
v Device capabilities - You must specify DEVINFO(YES) to get device related
information. Refer to the device specific architecture to interpret the device
related DEVINFO=YES information.
v For those capabilities that have both a processor and device component, you
must check both bits IOSDZHPF and IECDZHPF to determine if the capability is
supported.
182
z/OS DFSMSdfp Advanced Services
IOSZHPF UCBPTR=(Rx),
INFOAREA=MyInfoArea,
DEVINFO=YES
.
.
.
MyInfoArea DS XL(ZHPF_Info_Len)
IOSDZHPF
IECDZHPF
Version
EXCPVR supported
Incorrect length supported
Other processor & z/OS flags
Max transfer size
Device capabilities
Capability bit 0
Capability bit 1
Capability bit 2
Capability bit 3
Capability bit 4
Capability bit 5
.
.
.
Capability bit 64
Figure 13. Using IOSPHPF to determine if zHPF is supported by a processor and device
As Figure 13 shows, you must check the following in order to check to see whether
the processor and device supports zHPF:
v If the processor supports zHPF
v If the processor supports incorrect length
v If the device supports incorrect length
Modifying a Channel Program During Execution
For EXCP requests that run in a V=V address space, the system builds a translated
copy of your channel program in real storage. Channel program changes made by
your page-fix or start-I/O appendage, which run before the channel program is
translated, will affect the real channel program. Later changes to your copy of your
channel program with processor instructions or with data read in by an I/O
operation will not affect the real translated channel program. Thus, in a V=V
address space any attempt to modify an active channel program affects only the
virtual image of the channel program, not the real channel program being executed
by the channel subsystem. If you wish your changed channel program to be
executed, your program can issue another EXCP macro or your channel-end
appendage can return at offset 8.
Modifying a channel program during execution is supported for EXCPVR and
EXCP requests that run in a V=R address space, since the system does not build a
translated copy of your channel program. Modifying a channel program during
execution is only supported for CCW channel programs, not zHPF channel
programs.
VIO Considerations
VIO data sets are supported for EXCP and EXCPVR requests. When an EXCP or
EXCPVR request is issued for a VIO data set, the system simulates all of the
common channel commands. Both format-0 and format-1 CCW channel programs
are supported for VIO data sets, but note that 64-bit IDAWs, MIDAWs, and zHPF
channel programs are not supported for a VIO data set.
Chapter 4. Executing Your Own Channel Programs
183
For EXCPVR requests, the addresses in the CCWs and IDAWs must be virtual
addresses - they must not be converted to real addresses.
Creating the EXCP-Related Control Blocks
Using EXCP requires familiarity with the function and structure of the IOB, ECB,
DCB, DEB, and optionally IOBE, DCBE,UCB and IEDB. DCB, IOB, IOBE, IEDB,
and ECB fields are illustrated in the “Control Block Fields” on page 196 section.
The DEB fields used for EXCP and EXCPVR are illustrated in Appendix A,
“Control Blocks,” on page 443 (all the DEB fields are illustrated in z/OS DFSMSdfp
Diagnosis).
The IOB, ECB, DCB, and DEB must be in 24-bit virtual storage. The IOBE, IEDB,
and DCBE may reside in 31-bit virtual storage, even if your program runs in 24-bit
mode.
All EXCP control blocks that you provide must be located in storage that your
program's protection key allows the program to modify. Descriptions of these
control blocks follow.
Input/Output Block (IOB)
The input/output block (IOB) is used for communication between the problem
program and the system. It provides the addresses of other control blocks, and
maintains information about the channel program, such as the type of chaining
and the progress of I/O operations. You must define the IOB and specify its
address as the only parameter of the EXCP or EXCPVR macro instruction. See
“Input/Output Block (IOB) Fields” on page 211.
Input/Output Block Common Extension (IOBE)
The input/output block common extension (IOBE) specifies the type of channel
program and its format, options that control the execution of the channel program
and the level of ERP processing, and provides the anchor to the IEDB. The IOBE is
an extension to the IOB and, like the IOB, provides for communication between the
user of EXCP and the system. This control block is required for format-1 CCW
channel programs and zHPF channel programs, but is optional for format-0 CCW
channel programs. See “Input/Output Block Common Extension (IOBE) Fields” on
page 216.
Event Control Block (ECB)
The event control block (ECB) provides you with a completion code that describes
whether the channel program was completed with or without error. A WAIT or
EVENTS macro instruction, which can be used to synchronize I/O operations with
the problem program, must identify the ECB. You must define the ECB and specify
its address in the IOB. See “Event Control Block (ECB) Fields” on page 220.
Input/Output Error Data Block (IEDB)
The system uses the input/output error data block IEDB to provide extended error
information. This control block is optional. See “Input/Output Error Data Block
(IEDB) Fields” on page 209.
Data Control Block (DCB)
The data control block (DCB) provides the system with information about the
characteristics and processing requirements of a data set to be read or written by
184
z/OS DFSMSdfp Advanced Services
the channel program. A DCB must be generated by a DCB macro instruction that
includes parameters for EXCP. If you are not using appendages, a short DCB is
constructed. Such a DCB does not support reduced error recovery. You specify the
address of the DCB in the IOB. See “Data Control Block (DCB) Fields” on page
196.
Data Control Block Extension (DCBE)
The data control block extension (DCBE) provides further processing options. The
DCBE options currently supported by EXCP are the following:
v BLKSIZE
v BLOCKTOKENSIZE
v CAPACITYMODE
v EADSCB
v EODAD
v LOC
v SYNC
See “Data Control Block Extension (DCBE) Fields” on page 207.
Data Extent Block (DEB)
The data extent block (DEB) contains one or more extent entries for the associated
data set and other control information. An extent defines all or part of the physical
boundaries on an I/O device occupied by, or reserved for, a particular data set.
Each extent entry contains the address of a unit control block (UCB) that provides
information about the type and location of an I/O device. More than one extent
entry can contain the same UCB address. For all I/O devices supported by the
operating system, the DEB is produced during execution of the OPEN macro
instruction for the DCB. The system places the address of the DEB into the DCB.
See “Data Extent Block (DEB) Fields” on page 222.
Executing the Channel Program
This information explains how to pass the channel program to the system for
execution and how the system uses your channel program and control blocks after
you issue EXCP or EXCPVR request.
Using the EXCP macro instruction
The EXCP macro instruction initiates channel program I/O operations. Whenever
you want to execute one of your channel programs, issue EXCP.
The format of the EXCP macro is:
►►
EXCP iob_addr
►◄
label
iob_addr—RX-type address, (2-12), or (1)
The address of the IOB of the channel program to be executed.
If your program is also supplying an IOBE, then set register 0 to the address of
the IOBE, and set flag IOBCEF on in the IOB to indicate that the IOB extension
is present. An IOBE is required for format-1 CCW channel programs.
Chapter 4. Executing Your Own Channel Programs
185
Using the EXCPVR macro instruction
The EXCPVR macro instruction provides you with the same functions as the EXCP
macro instruction and allows your program to improve the efficiency of the I/O
operations in a paging environment by translating its own virtual channel
programs to real channel programs. In order to issue EXCPVR, your program must
be executing in protection key eight, executing in supervisor state, or be APF
authorized.
The program issuing the EXCPVR must remain in authorized state until
completion of the channel programs. For a description of how to authorize a
program, see z/OS MVS Programming: Authorized Assembler Services Guide.
The format of the EXCPVR macro is:
►►
EXCPVR iob_addr
►◄
label
iob_addr—RX-type address, (2-12), or (1)
the address of the input/output block of the channel program to be executed.
If your program is also supplying an IOBE, then set register 0 to the address of
the IOBE, and set flag IOBCEF on in the IOB to indicate that the IOB extension
is present. An IOBE is required for format-1 CCW and zHPF channel
programs.
To use EXCPVR, follow the procedures needed to execute an EXCP request and
also follow the procedures listed below. If you have already page fixed your
channel program and data areas prior to issuing the EXCPVR macro, or you are in
a V=R address space, steps 1 and 2 are not necessary.
1. Code PGFX=YES in the DCB associated with the EXCPVR requests and provide
a page-fix (PGFX) appendage by specifying SIOA=symbol in the DCB.
2. Fix the data area containing your channel program, the data areas referred to
by your channel program, the PCI appendage (if your program can generate
program-controlled interrupts), and any area referred to by the PCI appendage
including the DEB, IOB, etc. To fix these areas, build a list in your PGFX
appendage containing the addresses of these virtual areas. Any area that you
know already is in fixed storage for the duration of the I/O can be omitted
from the page fix list.
3. If you have not already built indirect address lists or if your channel program
still contains virtual addresses prior to issuing the EXCPVR macro, you must
do the following two items in your start I/O (SIO) appendage. The SIO
appendage is described in “Start-I/O Appendage” on page 225.
v Determine whether the data areas in virtual storage specified in the address
fields of your channel program cross page boundaries. If they do, build an
indirect data address list and update your channel program with the address
of the indirect address list. For CCW channel programs, build an IDAL or
MIDAL.
If you build an IDAL, put the address of the IDAL in the affected CCW and
turn on the IDA bit in the CCW.
If you build a MIDAL, put the address of the MIDAL in the affected CCW
and turn on the MIDA bit in the CCW. For zHPF channel programs, build a
186
z/OS DFSMSdfp Advanced Services
TIDAL, put the address of the TIDAL in the input or output address field in
the TCW, and turn on the input or output TIDAL bit in the TCW.
v Translate the addresses in your channel programs from virtual to central
storage addresses.
Initiating the Channel Program
Issuing EXCP or EXCPVR macro requests execution of the channel program
specified in the IOB. The system validates the request by checking fields of the
control blocks associated with this request. If the system detects invalid
information in a control block, it initiates abnormal termination procedures. The
system gets the address of the:
v DCB from the IOB
v DEB from the DCB
v UCB from the DEB.
If this is an EXCPVR request and you have provided a page-fix appendage, the
system passes control to it to allow you to either page fix your channel program
and data areas, or to provide EXCP with a page fix list so that EXCP will do the
page fixing. For a description of the page-fix appendage and its linkage to the
system, see “Page Fix and EXCPVR Start I/O Appendage” on page 226.
If you have provided a start I/O (SIO) appendage, the system passes control to it.
The system does not examine the channel program until the return from the SIO
appendage.The return address from the SIO appendage determines whether the
system executes or skips the I/O operation. For a description of the SIO
appendage and its linkage to the system, see “Start-I/O Appendage” on page 225.
Translating the Channel Program
For EXCP requests that do not run in a V=R address space, the system performs
the following tasks:
v Copies your virtual channel program and translates the copy into one that uses
only central storage addresses
v Fixes in real storage the pages used as I/O areas for the data transfer operations
specified in your channel program.
DASD Channel Program Prefix CCW Commands
For direct access devices, specify the seek address in the IOB. The system
constructs a CCW chain that begins with a Define Extent or Prefix command and
passes control to the real version of your channel program. The system uses the
contents of DEBXDEF, as described in Appendix A, “Control Blocks,” on page 443
Appendix A, on page 443, when building the Define Extent or Prefix command.
You can issue a define extent command at the beginning of the channel program.
The system copies the data area and replaces the beginning and ending extent
addresses and the file mask byte. If file mask byte in your Define Extent is set to
inhibit writes, the system will use this value when it builds the Define Extent or
Prefix command. The file mask is set to prohibit seek-cylinder CCWs, or, if space is
not allocated in full cylinders, seek-head commands. If the data set is open for
INPUT, write CCWs are also prohibited. Your channel program can contain Locate
Record CCWs.
DASD Rotational Positioning Sensing
On newer storage subsystems, such as IBM D58000, the sector value has no effect.
On other subsystems, your channel program can be more efficient for device and
Chapter 4. Executing Your Own Channel Programs
187
channel usage if it supplies sector numbers. Your program can read sector numbers
with the read sector command or calculate them with the sector conversion
routine. That routine is described in “Obtaining the Sector Number of a Block on
an RPS Device” on page 236.
Command Retry Considerations
Command retry is a function of many IBM 3990 and newer storage controllers.
When the channel subsystem receives a retry request, it repeats the execution of
the CCW, without requiring any additional input/output interrupts. For example, a
storage control might initiate a retry procedure to recover from a transient error.
A command retry during the execution of a channel program can cause the
following conditions to be detected by the initiating program:
v Modifying CCWs: For EXCPVR and EXCP V=R requests, a CCW used in a
channel program must not be modified before the CCW operation has been
successfully completed. Without the command retry function, a command is
fetched only once from storage by a channel. This allowed a program to
determine through condition codes or program controlled interruptions (PCI)
that a CCW had been fetched and accepted by the channel. The CCW could be
modified before execution. With the command retry function, this procedure
cannot be repeated because the channel fetches the CCW from storage again on
a command retry sequence. In the case of data chaining, the channel retries
commands starting with the first CCW in the data chain.
v Program Controlled Interrupts (PCI): A CCW containing a PCI flag can cause
multiple program-controlled interrupts. This will happen if the PCI-flagged
CCW was retried during a command retry procedure and a PCI could be
generated each time the CCW is executed.
v Residual Count: If a channel program is prematurely terminated during the retry
of a command, the residual count in the channel status word (CSW) will not
necessarily indicate how much storage was used. For example, if the storage
control detects a wrong-length record error condition, an erroneous residual
count is stored in the CSW until the command retry is successful. When the
retry is successful, the residual in the CSW reflects the correct length of the data
transfer.
v Command Address: When data chaining with command retry, the CSW might
not indicate how many CCWs have been executed at the time of a PCI. For
example:
CCW#
1
2
3
4
Channel Program
Read, data chain
Read, data chain
Read, data chain, PCI
Read, command chain
In this example, assume that the storage control signals command retry on Read
#3 and the processor accepts the PCI after the channel resets the command
address to Read #1 because of command retry. The CSW stored for the PCI will
contain the command address of Read #1 when the channel has actually
progressed to Read #3.
v Testing Buffer Contents on Data Read: Any program that tests a buffer to
determine when a CCW has been executed and continues to execute based on
this data can get incorrect results if an error is detected and the CCW is retried.
188
z/OS DFSMSdfp Advanced Services
Magnetic Tape Considerations
For a magnetic tape device, the system constructs a CCW chain to set the mode
specified in the DEB and pass control to the real version of your channel program.
(You cannot set the mode yourself.) For cartridge tape devices, the mode byte also
prohibits supervisor channel command words such as the mode set command. If
your program opens a tape for input or read backwards and you do not have
RACF authority to write on the volume, the system normally prevents writes. With
a reel tape the system does this by requiring the operator to remove the write ring.
With a cartridge tape, the system does this using the Mode Set command. See z/OS
DFSMS Using Magnetic Tapes for more information on tape handling.
Lost Data Condition on IBM 3800
With the IBM 3800 Printing Subsystem, a cancel key or a system-restart-required
paper jam causes both a lost data indicator to be set in DCBIFLGS and a lost page
count and channel page identifier to be stored in the UCB extension. Reset the lost
data indicator bit (DCBIFLDT) and the first two bits in the DCBIFLGS field to zero
before reissuing requests to the printer. For additional information see IBM 3800
Printing Subsystem Programmer's Guide and IBM 3800 Printing Subsystem Models 3
and 8 Programmer's Guide.
Processing the I/O Completion Status
For direct access and tape devices, the system considers the channel program
completed when it has received both a channel-end and device-end. The
channel-end and device end can be presented by the device separately or
simultaneously. But for other devices, the system considers the channel program
completed when it receives a channel-end condition in the subchannel status word
(SCSW). Unless a channel-end (CHE) or abnormal-end (ABE) appendage directs
otherwise, the system places a completion code in the IOB and IEDB and then in
the ECB (after appendages have been called). The completion code refers to errors
associated with channel end. If device and channel end occur simultaneously,
errors associated with device end (that is, unit exception or unit check) are also
accounted for.
If device end follows channel end and an error is associated with device end, the
completion code in the ECB will not indicate the error. However, the status of the
device and channel is saved by the system for the device. The next I/O request
directed to the I/O device from any address space is marked as intercepted. The
error is assumed to be permanent, and the completion code in the ECB for the
intercepted request indicates interception. The DCBIFLGS field of the DCB will
also indicate a permanent error. Note that, if a write-tape-mark or erase-long-gap
CCWis the last or only CCW in your channel program, the I/O process does not
attempt recovery procedures for device end errors. In these circumstances,
command chaining a NOP CCW to your write-tape-mark or erase-long-gap CCW
ensures initiation of device-end error recovery procedures.
To be prepared for device-end errors, you should be familiar with device
characteristics that can cause such errors. After one of your channel programs has
terminated, do not release buffer space until determining that your next request for
the device has not been intercepted. You can reissue an intercepted request.
Interruption Handling and Error Recovery Procedures
An I/O interruption allows the processor to respond to signals from an I/O device
that indicate either termination of a phase of I/O operations or external action on
Chapter 4. Executing Your Own Channel Programs
189
the device. A complete explanation of I/O interruptions is contained in the
publication z/Architecture Principles of Operation. For descriptions of interruption by
specific devices, see the IBM publications for each device.
If error conditions are associated with an interruption, the system schedules the
appropriate device-dependent error routine. The operating system might then start
another request that is not related to the channel program in error. If the error
recovery procedures (ERPs) fail to correct the error, the system places an error code
in the IOB, IEDB, and then in the ECB, after appendages have been called.
A channel program might depend upon the successful completion of a previous
channel program (as when one channel program retrieves data to be used in
building another). The previous channel program is called a related request and
must be identified to the system. For a description of this procedure, see
IOBFLAGS in “Input/Output Block (IOB) Fields” on page 211 and “Purging and
Restoring I/O Requests (PURGE and RESTORE macros)” on page 304.
If a permanent error occurs in the channel program of a related request, the system
removes the request queue elements for all dependent channel programs and
returns them to the caller without executing the request. For all requests dependent
on the channel program in error, the system places completion codes in the ECBs.
The system also places ones in the first two bit positions of the DCBIFLGS field of
the DCB. Any new requests for a DCB with error flags are posted complete
without execution. To reissue requests that depend on the channel program in
error, reset the first two bits of the DCBIFLGS field of the DCB to zero. Then
reissue EXCP for each desired channel program.
Reexecuting Channel Programs by Error Recovery Procedures
Under some circumstances the ERP might reexecute a channel program from the
beginning. For example, DASD channel programs are almost always retried from
the beginning. You will want to build channel programs that the ERP can restart
after any CCW or DCW has failed.
For CCW channel programs, if a CCW modifies a data area used by an earlier
CCW, the channel program might not reexecute properly.
The following are some situations where a channel program might not give correct
results when reexecuted by the ERP (see “Modifying a Channel Program During
Execution” on page 183):
v The channel program modifies itself.
v The application program or the PCI appendage modifies the channel program or
a data area before receiving notification that the channel program has completed.
Generally you can attempt to add CCWs to the end of the channel program.
Example
The following is an example of a DASD channel program that will not always
execute correctly. Using this channel program is inadvisable.
LRArea
Seek
Search
Sector
Data
190
CCW
CCW
CCW
CCW
DC
DC
DC
DC
DC
DC
z/OS DFSMSdfp Advanced Services
X’47’,LRArea,X’60’,L’LRArea
Locate Record
X’86’,Data,X’60’,L’Data
Read Data
X’92’,Search,X’60’,L’Search
Read Count
X’22’,Sector,X’20’,1
Read Sector for this count
0XL16
Area for Locate Record command
X’06010002’
Operation, auxiliary, block count (2)
X’xxxxxxxx’
CCHH for seek
X’xxxxxxxxxx’
Search argument
X’FF0000’
Sector and transfer length factor
----
The application program would have to store appropriate values at labels "Seek"
and "Search" before issuing EXCP. (On an IBM 3990 storage subsystem, it will
execute more efficiently if an appropriate value is stored at "Sector" also. On newer
storage subsystems, such as the IBM 2107, the sector value has no effect.)
If all or part of the third CCW executes (Read Count), then reexecution of the
channel program by the ERP will give different results.
Requesting Extended Error Information
You can request that EXCP and EXCPVR processing return extended error
information. This extended error information consists of sense information, a
completion code, and other information you can use to help more accurately
diagnose I/O errors later encountered. Extended error information is available for
all devices.
To request extended error information, you must perform the following steps:
v Follow the EXCP/EXCPVR initialization procedures described in “Input/Output
Block (IOB) Fields” on page 211, including building and initializing the DCB,
IOB and ECB.
v Define an input/output block common extension (IOBE) and an input/output
error data block (IEDB) using the IOSDIOBE and IOSDIEDB mapping macros,
respectively. Each must be defined on word boundaries. You must supply both
an IOBE and an IEDB to receive extended error information. Initialize the fields
as described in “Input/Output Block Common Extension (IOBE) Fields” on page
216 and “Input/Output Error Data Block (IEDB) Fields” on page 209.
v Set register 0 to the address of the IOBE.
v Set register 1 to the address of the IOB.
v Set flag IOBCEF on in the IOB to indicate that the IOB extension is present.
v Issue the EXCP or EXCPVR macro (see “Using the EXCP macro instruction” on
page 185 and “Using the EXCPVR macro instruction” on page 186 respectively).
There are two versions of the IEDB. The version number within the IEDB defines
how long the IEDB is - the version 1 IEDB is 48 bytes long, and the version 2 IEDB
is 96 bytes long.
v The version 1 IEDB contains the following information:
– The completion code from I/O processing that gives the status. The
completion codes and their meanings are shown in Figure 26 on page 220.
The completion code is contained in the IEDBCOD, which is updated with
the results of the I/O requests. The system sets the IEDBCOD field prior to
calling the abnormal-end, normal-end, PCI, and end-of-extent appendages.
The system also sets this field when the ECB is posted, whether or not you
have set any appendages. The system can set the IEDBCOD multiple times as
events occur.
– The sense information, set only after a unit check. Once set, the sense
information remains until overlaid by the next unit check. Since the system
never clears this area, you might want to clear it before issuing EXCP. See the
appropriate device publication for an explanation of the sense information.
v The version 2 IEDB is recommended for zHPF channel programs, and contains
all of the information in the version 1 IEDB plus the failing storage address
when a channel control check or channel data check occurs as a result as a
storage or storage key error error, or if a program check or protection check
occurs for a zHPF channel program due to a bad storage address.
Chapter 4. Executing Your Own Channel Programs
191
Requesting Different Levels of ERP Processing
You can request the system to limit error recovery procedure (ERP) processing to
selected functions, typically when EXCP or EXCPVR processing has encountered
an I/O error. The processing selections available depend upon the device type.
For all devices, except magnetic tape subsystems that use cartridges, the following
processing levels are available:
v No ERP processing. ERP processing does not attempt error recovery or issue
messages. However, ERP processing can perform recovery for non-error unit
checks for logging, forced logging mode and buffered log overflow. To request
no ERP processing, set at least one of the DCBIFIOE bits on in the DCBIFLGS
field in the DCB.
v Full ERP processing. ERP processing performs such functions as logging the
errors, logging data collected by a control unit for a device, retrying errors,
issuing error messages and processing requests from the device. You do not have
to request full ERP processing; it is the system default.
For magnetic tape subsystems that use cartridges, such as the 3490 or 3590-1, the
following processing levels are available:
v Basic ERP processing. ERP processing logs the errors, logs data collected by a
control unit for a device and processes requests from a device. In this case, the
system does not issue messages or retry errors. To request basic ERP processing,
set one of the DCBIFIOE bits on in the DCBIFLGS field in the DCB.
v Intermediate ERP processing. ERP processing performs the functions provided
by basic processing and also issues any permanent error messages. To request
intermediate ERP processing, define an IOBE and set IOBEPMSG on in
IOBEERPM. In addition, set at least one of the DCBIFIOE bits on in the
DCBIFLGS field in the DCB.
v Full ERP processing. ERP processing performs such functions as logging the
errors, logging data collected by a control unit for a device, retrying errors,
issuing error messages and processing requests from the device. You do not have
to request full ERP processing; it is the system default. Bits in DCBIFIOE must
be 0. The DCB macro assembles them as zeros.
VIO considerations
When you issue EXCP or EXCPVR against a VIO data set, the system simulates all
the common channel commands. When working with VIO data sets, if you supply
an IEDB the system verifies its validity, but will not set any fields in it in the
current level of the operating system. VIO is not supported for zHPF channel
programs.
Invalid ending status
Normally when a channel program ends, the ending CCW or TCW address is
stored in field IOBCMD31 or IOBCMDA depending on the type of channel
program. However, for certain types of errors, the ending status of the channel
program is unpredictable and the ending address will be set to zero. Therefore,
your program should never assume that a valid ending address is always provided
in the IOB.
For CCW channel programs, the ending CCW address will be set to zero when any
of the following conditions occur:
v An interface control check, channel control check, or channel data check has
occurred and the ending address in the subchannel status word (SCSW) is not
valid
192
z/OS DFSMSdfp Advanced Services
v A program check, protection check, or chaining check has occurred
v The ending CCW address was in a part of the channel program that was
modified by device dependent system code. If device dependent system code
needs to modify your channel program, it does so in system related storage that
is not available to your program.
For zHPF channel programs:
v The ending TCW address will be set to zero when an interface control check,
channel control check, or channel data check has occurred and the ending
address in the SCSW is not valid.
v The ending DCW offset in the IOBE is more useful for determining where the
channel program ended than the TCW, since the DCW is analogous to the CCW
in zHPF channel programs. The ending DCW offset will not be stored if the
device did not send ending status containing a valid DCW offset or the channel
was unable to store the ending status. In this case, the flag indicating that the
DCW offset is valid will be off.
Device No Longer Supports zHPF or Required zHPF functions
As mentioned in “Determining Whether zHPF is Supported for a Device” on page
182, you must make sure that a device supports zHPF as well as all the zHPF
functions your channel program requires before issuing an EXCP or EXCPVR
request for a zHPF channel program. In addition, even if the processor and device
support zHPF and all the zHPF functions required, these might be disabled when
you actually submit your channel programs:
v zHPF itself might be disabled on a processor and device that supports it when
you submit your channel program for any of the following reasons:
– The operator issued a command to disable zHPF for the system
– The zHPF feature is no longer enabled for the control unit associated with the
device
– Internal errors have occurred that caused zHPF to be disabled for the device
– The device used in the EXCP or EXCPVR request has been swapped to a
device that does not support zHPF.
When the device no longer supports zHPF, the IOB completion code
(IOBECBCC) is set to X'41' and the reason code (IOBERCOD) is set to X'0E'. You
can retry the EXCP or EXCPVR request by creating a CCW channel program and
either reissuing the EXCP or EXCPVR request, or returning at offset +8 in your
abnormal end appendage to execute a new channel program.
v Some required zHPF functions might be disabled on a supporting processor and
device if you swap to a device that does not support all required zHPF
functions. In that case, you must evaluate the zHPF functions that are supported
on that device to determine whether you still can use a zHPF channel program
or whether you must substitute a CCW channel program instead.
Handling End of Volume and End-Of-Data-Set Conditions
The EOV macro instruction identifies end-of-volume and end-of-data-set
conditions. For an end-of-volume condition, EOV causes switching volumes and
verifying or creating standard labels. For an end-of-data-set condition (except when
another data set is concatenated), EOV causes your end-of-data set routine to be
entered. Before processing trailer labels on a tape input data set, decrement the
DCBBLKCT field. Your program issues EOV for any of the following reasons:
v Switching magnetic tape or direct access volumes is necessary
Chapter 4. Executing Your Own Channel Programs
193
v Performing a secondary allocation on the same or another volume for a direct
access data set opened for output
v Switching to the next concatenated data set is necessary.
To determine how the system disposes of a tape volume when a program issues an
EOV macro, see the description of the DISP parameter of the OPEN macro in z/OS
DFSMS Macro Instructions for Data Sets.
For magnetic tape, issue EOV when either a tapemark is read or a write command
received a unit exception condition. You can also issue EOV to go to the next
volume or data set even though neither a tapemark was read nor end-of-tape
reached. Bit settings in the 1-byte DCBOFLGS field ofthe DCB determine the action
taken when EOV is executed. Before issuing EOV for magnetic tape or DASD
make sure that appropriate bits are set in DCBOFLGS. Bit positions 2, 3, 6, and 7 of
DCBOFLGS are used only by the system; you are concerned with bit positions 0, 1,
4, and 5. The use of these DCBOFLGS bit positions is as follows:
Table 36. DCBOFLGS Usage
Position
Bit name
Meaning
0
DCBOFLWR
1
DCBOFLRB
4
DCBOFPPC
5
DCBOFTM
set to 1 indicates that a write command was executed
and that a tapemark or DASD file mark is to be
written. OPEN sets this bit to 1 if the OPEN option is
OUTPUT, OUTIN, OUTINX, or EXTEND. OPEN sets
it to 0 for any other OPEN option. For DASD, a 1
also indicates that ECBFDAD and DCBTRBAL
contain valid information. See “Device-Dependent
Parameters” on page 203 for more information.
indicates that a backward read was the last I/O
operation
indicates that concatenated data sets are to be treated
as unlike. For further information, refer to z/OS
DFSMS Using Data Sets.
indicates that a tapemark has been read (tape only).
If bits 0 and 5 of DCBOFLGS are both off when EOV is executed, EOV spaces the
tape past a tapemark, and standard labels, if present, are verified on both the old
and new volumes. The direction of spacing depends on bit 1. If bit 1 is off, the
tape is spaced forward; if bit 1 is on, the tape is backspaced.
For tape, if bit 0 is on, but bit 5 is off, EOV writes a tapemark at the current
position, which is assumed to be following the last data record of the data set on
the current volume. EOV also writes labels on both the old and new tapes if they
are labeled. See z/OS DFSMS Using Magnetic Tapes for information on label
processing. For DASD, if bit 0 is on, EOV attempts to write a file mark. See the
DCBFDAD description in “Device-Dependent Parameters” on page 203 for more
information.
When you issue EOV, the system might rebuild the DEB at another location. After
each EOV, obtain the rebuilt DEB address from the DCB. If the data set was
allocated without the nocapture option of dynamic allocation, then EOV might
have uncaptured the UCB for the previous volume. If so, that captured UCB
address might become invalid. Note that the 24-bit address of the new UCB might
be the same as the previous UCB.
194
z/OS DFSMSdfp Advanced Services
After issuing EOV for sequentially organized output data sets on direct access
volumes, you can determine whether additional space was obtained on the same
or a different volume. Do this by examining the DEB and the UCB. If the volume
serial number in the UCB has not changed, additional space was obtained on the
same volume. Otherwise, space was obtained on a different volume.
The format of the EOV macro is:
►►
EOV dcb_addr
►◄
label
,MODE=
24
31
dcb_addr—RX-type address, (2-12), or (1)
The address of the DCB that is opened for the data set. If this parameter is
specified as (1), register 1 must contain this address.
MODE=24 or 31
Indicates how the registers are set. With either value, your program can be in
24-bit or 31-bit mode. The modes are:
24 If you do not specify the MODE operand, this mode is assumed. The
expansion of the EOV macro stores the DCB address into register 1. The
high-order byte of register 1 is ignored during EOV processing. The DCB
must be below 16MB, but the calling program can be above the line.
31 The EOV macro expansion code puts the DCB address into register 15 and
sets register 1 to zeros. The DCB address must be below 16 MB, because
providing a DCB above 16 MB causes an ABEND50D. The high-order byte
of the address specified in the EOV macro must be zero.
Closing the Data Set
The CLOSE macro instruction restores one or more DCBs so that processing of
their associated data sets can be terminated. Issue CLOSE for all DCBs that were
used by your channel programs. Some of the procedures performed when CLOSE
is executed are:
v Releasing data extent block
v Removing information transferred to DCB fields when OPEN was executed
v Verifying or creating standard labels
v Volume disposition
v Releasing programmer-written appendage routines
v Uncapture UCB if the actual UCB is above the line and the allocation was done
without the nocapture option and LOC=ANY in the DCBE macro was not
specified.
When CLOSE is issued for a data set on a magnetic tape volume, the system
processes labels according to bit settings in the DCBOFLGS field of the DCB.
Before issuing CLOSE for magnetic tape, set the appropriate bits in DCBOFLGS.
The significant DCBOFLGS bit positions are listed in the EOV macro instruction
description.
Chapter 4. Executing Your Own Channel Programs
195
When CLOSE is issued for a data set open for output on a direct access device, the
system will try to write a file mark if fields are as described in “Device-Dependent
Parameters” on page 203.
The parameters and different forms of the CLOSE macro instruction are described
in z/OS DFSMS Macro Instructions for Data Sets.
Control Block Fields
Control block field information covered here includes fields of the DCB, DCBE,
input/output block, IOBE, IEDB, event control block, and data extent block.
To use the DCBD macro to map the DCB, see “Mapping the DCB” on page 207.
Data Control Block (DCB) Fields
The EXCP form of the DCB macro instruction produces a DCB that can be used
with the EXCP macro instruction. Code a DCB macro instruction for each data set
to be processed by your channel programs. (Notation conventions and format
illustrations of the DCB macro instruction are given in z/OS DFSMS Macro
Instructions for Data Sets.) DCB parameters that apply to EXCP depend on the
following elements of the DCB that are generated:
v Foundation block: This portion is required and is always 12 bytes in length. If
the DCBMACRF field indicates that a DCB portion before this is missing or
short, the system ignores values in those fields.
v EXCP interface: This portion is optional. If you specify any parameter in this
category, 20 bytes are generated.
v Foundation block extension and common interface: This portion is optional and
is always 20 bytes in length. If this portion is generated, the device-dependent
portion is also generated.
v Device dependent: This portion is optional and is generated only if the
foundation block extension and common interface portion is generated. Its size
ranges from 4 to 20 bytes, depending on specifications in the DEVD parameter.
If you do not specify the DEVD parameter and the foundation extension and
common interface portions are generated, 16 bytes for this portion are generated.
Some of the procedures performed by the system when the DCB is opened and
closed (such as writing file marks for output data sets on direct access volumes)
require information from optional DCB fields. Make sure that the DCB is large
enough to provide information for the procedures you want the system to handle.
Figure 14 on page 198 shows the relative position of each portion of an opened
DCB. The fields, corresponding to the DCB macro instruction parameters, are also
identified, except for DDNAME. (DDNAME is not included in a DCB that has
been opened.) The fields in parentheses represent system information that is not
associated with parameters of the DCB macro instruction.
Sources of information for DCB fields other than the DCB macro instruction are
data definition (DD) statements or dynamic allocation parameters, data set labels,
and DCB modification routines. You can use any of these sources to specify DCB
parameters. However, if a particular portion of the DCB is not generated by the
DCB macro instruction, the system will not accept information intended for that
portion from any alternative source.
196
z/OS DFSMSdfp Advanced Services
You can provide symbolic names for the fields in one or more EXCP DCBs by
coding a DCBD macro to generate a dummy control section (DSECT). For further
information, see “Mapping the DCB” on page 207.
The EXCP DCB does not have a field to contain the current or maximum block size
but the DCBE does have such a field.
Chapter 4. Executing Your Own Channel Programs
197
The device-dependent portion of the data
control block varies in length and format
according to specifications in the DSORG
and DEVD parameters. Illustrations of this
portion for each device type are included in the
description of the DEVD parameter.
Device
Dependant
20
BUFNO
BUFCB
24
DSORG
BUFL
Common
Interface
28
IOBAD
32
BFTEK,
BFALN
EODAD
RECFM
EXLST
Foundation
Block
Extension
36
40
(TIOT)
MACRF
44
(IFLGS)
(DEB Address)
(OFLGS)
Reserved
Foundation
Block
48
52
OPTCD
Reserved
56
Reserved
60
EOEA
PCIA
SIOA
CENDA
XENDA
Reserved
EXCP
Interface
64
68
Figure 14. Data Control Block Format for EXCP (After OPEN)
The fields in parentheses represent system information that is not associated with
parameters of the DCB macro instruction.
198
z/OS DFSMSdfp Advanced Services
DCB Fields that do not have Macro Parameters
DCBOFLGS: See “Handling End of Volume and End-Of-Data-Set Conditions” on
page 193.
DCBIFLGS: See “Processing the I/O Completion Status” on page 189 and
“Interruption Handling and Error Recovery Procedures” on page 189.
These are the bits that EXCP uses in DCBIFLGS after the DCB is OPEN:
Table 37. Bits that EXCP uses in DCBIFLGS after the DCB is OPEN
Bits that EXCP uses in DCBIFLGS after the DCB is OPEN
11.. ....
DCBIFPEC
An IOB without the unrelated bit on got a permanent I/O
error. EXCP posts subsequent related requests with X'48' in the
ECB until the user clears DCBIFPEC. Corresponds to DCBIBEC
in DCBIFLG before OPEN.
..11 ....
DCBIFPCT
Channel 9 or 12 code detected on printer. Corresponds to
DCBIFC9 and DCBIFC12 in DCBMACR before OPEN.
.... 11..
DCBIFIOE
Request less than full system ERP (error recovery procedure)
processing. Your program can set these bits directly, or you can
code the IMSK parameter (see “EXCP Interface Parameters” on
page 200). See “Requesting Different Levels of ERP Processing”
on page 192.
DCBTIOT: If the data set allocation was dynamic and had the XTIOT (S99TIOEX)
or nocapture (S99ACUCB) option, then this field contains zeroes. You can use
DEBXTNP, DEBXDSAB and DSABTIOT to get the TIOT or XTIOT entry address. If
the allocation was not dynamic or did not have the XTIOT or nocapture option,
this field is unsigned (16-bit) offset in the TIOT to the entry.
An entry in the TIOT or XTIOT is mapped by the IEFTIOT1 macro.
Foundation Block Parameters
DDNAME=symbol
The name of the data definition (DD) statement that describes the data set to
be processed. This parameter is required and must be supplied before your
program issues the OPEN macro. You can code a dummy value and change it
before issuing OPEN.
MACRF=E
The EXCP or EXCPVR macro instruction is to be used in processing the data
set. This operand must be coded and must be supplied before your program
issues the OPEN macro.
REPOS=Y or N
Magnetic tape volumes: This parameter indicates to the system whether the
user is keeping an accurate block count. (Maintain the block count in the
DCBBLKCT field.) The system ignores this parameter when the program is
executing and the device is not magnetic tape.
The EOV and CLOSE functions can record the block count in the IBM standard
or ISO/ANSI standard trailer labels.
On input, the EOV and CLOSE functions can compare the DCB block count
with the block count in the standard trailer labels to detect missing or
duplicate blocks. This is supported on reel and cartridge tapes.
Chapter 4. Executing Your Own Channel Programs
199
On input or output, the EOV and CLOSE functions can compare the DCB
block count with the block count calculated from tape cartridge subsystems to
detect missing or duplicate blocks. The system does this for any label type and
for unlabeled tapes. Refer to z/OS DFSMS Using Magnetic Tapes.
For magnetic tape devices with reels (not cartridges), coding REPOS=Y allows
the dynamic device reconfiguration (DDR) function to move the volume to
another tape drive if the drive has a failure. With a cartridge, DDR can do this
without your program maintaining block count.
For magnetic tape devices with reels (not cartridges), restart requires the block
count in order to restore the tape to its position at the time of the checkpoint.
With a cartridge, restart can do this without requiring that you maintain a
block count.
The system performs the following tasks:
v Y-The count is accurate.
v N-The block count is inaccurate.
If the operand is omitted, N is assumed.
EXCP Interface Parameters
If you do not code any of the parameters described here, the DCB macro does not
create this portion of the block and OPEN will ignore any value that your program
sets. You can code values to affect the macro expansion and change any of these
fields before the end of the DCB OPEN exit routine. For more information on
EXCP appendages, see “Making Appendages Available to the System” on page 224.
EOEA=symbol
Last two characters of an EOE appendage name that you have entered into
SYS1.LPALIB or SYS1.SVCLIB.
PCIA=symbol
Last two characters of a PCI appendage name that you have entered into
SYS1.LPALIB or SYS1.SVCLIB.
SIOA=symbol
Last two characters of a SIO appendage name that you have entered into
SYS1.LPALIB or SYS1.SVCLIB.
PGFIX=YES
The SIO appendage includes a page-fix entry point. Refer to “Using the
EXCPVR macro instruction” on page 186 and “Page Fix and EXCPVR Start I/O
Appendage” on page 226.
CENDA=symbol
Last two characters of a CHE appendage name that you have entered into
SYS1.LPALIB or SYS1.SVCLIB.
XENDA=symbol
Last two characters of an ABE appendage name that you have entered into
SYS1.LPALIB or SYS1.SVCLIB.
OPTCD=Z
Indicates that, for devices that have a magnetic tape reel (input only), a
reduced error recovery procedure (four reads only) will occur when a data
check is encountered. Only specify this operand when the tape is known to
contain errors and the application does not require that all records be
processed. Its proper use would include error frequency analysis in the
SYNAD routine. Specification of this parameter will also cause generation of a
200
z/OS DFSMSdfp Advanced Services
foundation block extension. This parameter does not apply to magnetic tape
subsystems that use cartridges. Your program can change this parameter value
at any time.
IMSK=value
The IMSK parameter lets you specify whether or not you want to ignore
system error routines:
v Code X'FFFFFFFF' to specify that you want the system to use the error
routines.
v If you code any value other than X'FFFFFFFF', the system will not use the
system's error routines. This causes one of the DCBIFOIOE bits to be set on.
See “DCBIFLGS” on page 199.
Foundation Block Extension and Common Interface Parameters
EXLST=address
The address of an exit list that you have written for exception conditions. The
format and purpose of the exit list are provided in z/OS DFSMS Using Data
Sets.
EODAD=address
The address of your end-of-data-set routine for input data sets. If this routine
is not available when it is required, the task is abnormally terminated.
It is required when you issue an EOV macro for the last volume containing
data and bit 0 of DCBOFLGS indicates that the last operation was a read. (See
“Handling End of Volume and End-Of-Data-Set Conditions” on page 193 for
more information concerning EOV.) An exception to this is when another data
set is concatenated after the current data set.
The EODAD address used here is a 24-bit address in the DCB. If you use the
DCB extension (DCBE), and its 31-bit EODAD field is non-zero, the system
uses that address instead.
DSORG=PS or PO or DA
The data set organization (one of the following codes). Each code indicates that
the format of the device-dependent portion of the DCB is to be similar to that
generated for a particular access method:
Code
DCB Format:
PS
PO
DA
QSAM or BSAM
BPAM
BDAM
When writing in a partitioned or sequential DASD data set, you can cause
EOV or CLOSE to write a file mark. Refer to “Device-Dependent Parameters”
on page 203 for further information.
Do not issue the STOW macro against an EXCP DCB; it can corrupt the
directory contents.
IOBAD=address
The address of an input/output block. You can use this field for any purpose.
RECFM=code
The record format of the data set. (Record format codes are given in z/OS
DFSMS Macro Instructions for Data Sets.) When writing a data set to be read
later, RECFM, LRECL, and BLKSIZE should be specified to identify the data
Chapter 4. Executing Your Own Channel Programs
201
set attributes. LRECL and BLKSIZE can only be specified in a DD statement, in
an SVC 99 call, or in the JFCB, because these fields do not exist in a DCB used
by EXCP.
IBM recommends that when you are creating a data set you issue a RDJFCB
macro and set JFCLRECL and JFCBLKSI before issuing OPEN TYPE=J. This
will allow LRECL and BLKSIZE to be in the data set label. An alternate way to
set or learn the block size is to use the BLKSIZE field in the DCBE.
The RECFM parameter is not used by the EXCP routines. It provides
information stored for subsequent use by access methods that read or update
the data set.
The following parameters are optional. The system does not manage the buffers
described.
BFALN=F or D
The word boundary alignment of each buffer, either word or doubleword.
BUFL=length
The length in bytes of each buffer; the maximum length is 32760.
BUFCB=address
The address of a buffer pool control block, that is, the 8-byte field preceding
the buffers in a buffer pool. If the low order bit is on, the address is invalid
and if you issue the FREEPOOL macro, it has no effect. The FREEPOOL macro
sets the low order bit on. The DCB macro sets the low order bit on if the
common interface portion is valid.
BUFNO=number
The number of buffers assigned to the associated data set; the maximum
number is 255. For an EXCP DCB, OPEN ignores this parameter and the
BFALN, BUFL, and BUFCB parameters. They have an effect only if your
program uses those fields or if your program issues a GETPOOL or GETBUF
macro.
Buffer number and block size affect the data transfer rate and the operating
system overhead per block. Using more buffers reduces (per block transferred)
the system overhead. If you allocate more buffers than your program can
process effectively, the virtual pages containing those buffers might be paged
out, adding to the system overhead for the job. A large number of buffers also
causes a large amount of real storage to be allocated to the job while the data
is being transferred.
A job in a low-performance group can get swapped out more frequently than a
higher-priority job. The number of buffers allocated for the job effect the
number of pages that have to be swapped out.
Programs that access data sets with a small block size (for example, 80) can
easily make effective use of 30 buffers, which fit in, at most, two 4096-byte
pages. The use of 30 buffers in this case is more efficient than 5, resulting in
only 1 channel program rather than 6 channel programs to transfer 30 blocks.
Using data sets with large blocking factors such as half-track blocking on
DASD can be effective if only three or four buffers are specified, rather than
five or more. The slightly lower DASD performance and small increase in
system instruction costs should be more than offset by a reduction in paging or
swapping in a constrained environment.
202
z/OS DFSMSdfp Advanced Services
The DCB OPEN installation exit can use installation criteria for a default buffer
number for EXCP DCBs (for a description of the OPEN installation exit, see
z/OS DFSMS Installation Exits). Your program can use the BUFNO value that
the OPEN installation exit might set.
Device-Dependent Parameters
DCBE=
the DCBE= parameter is a device independent parameter but is included here
because if DCBE= is specified the entire device-dependent section of the DCB
is generated. You specify DCBE= when the DCB extension (DCBE) is required.
The first word of the DCB (at offset +0) points to the DCBE when 2 bits at
offset 32 (X'20') are on as follows:
Table 38. DCB bits to signify presence of DCBE
Name
Bit
DCBH1
X'80'
DCBH0
X'04'
Coding DCBE= in the DCB macro sets these 2 bits on. For further DCBE
information see “Data Control Block Extension (DCBE) Fields” on page 207.
See z/OS DFSMS Macro Instructions for Data Sets for more information on the
DCBE= parameter of the DCB macro.
DEVD=code
The device in which the data set might reside. The codes are listed in order of
descending space requirements for the DCB:
Table 39. DCB DEVD options
Code
DA
TA
PR
PC
RD
Device
Direct access
Magnetic tape
Printer
Card punch
Card reader
If you do not want to select a specific device until job setup time, specify the
device type requiring the largest area; that is, DEVD=DA.
The following diagrams illustrate the device-dependent portion of the DCB for
each combination of device type specified in the DEVD parameter and data set
organization specified in the DSORG parameter. Fields that correspond to
device-dependent parameters in addition to DEVD are indicated by the parameter
name.
When processing concatenated data sets, the system changes the value in
DCBDEVT as appropriate as it reaches each new data set. These values are
described in z/OS DFSMS Macro Instructions for Data Sets.
Chapter 4. Executing Your Own Channel Programs
203
┌───────────────────────────────────────────────────┐
³ 0
³
³
DCBDCBE
³
├────────────┬──────────────────────────────────────┤
³ 4
³ 5
³
³ Reserved ³ (DCBFDAD)
³
├────────────┘
³
³ 8
³
³
³
³
┌──────────────────────────────────────┤
³
³ 13
³
³
³ (DCBDVTBA)
³
├────────────┼────────────┬─────────────────────────┤
³ 16
³ 17
³ 18
³
³ DCBKEYLE ³ (DCBDEVT)³
(DCBTRBAL)
³
└────────────┴────────────┴─────────────────────────┘
Figure 15. Device-dependent portion of the DCB with DEVD=DA and DSORG=PS (or
DSORG=PO)
The fields in parentheses represent information not associated with parameters of
the DCB macro instruction. EOV sets all of these fields. OPEN sets DCBDVTBA
and DCBDEVT, but not DCBFDAD. Your program can modify DCBFDAD,
DCBKEYLE, or DCBTRBAL as described in the text.
When writing on DASD, maintain certain fields of the device-dependent portion of
the DCB. The system uses the information in the following instances:
v To write a file mark for output data sets
v When releasing unused space at the end of the allocated area
You can request partial space release using the management class, RLSE on the
DD SPACE parameter, TSO/E ALLOCATE command RELEASE parameter or
PARTREL macro.
v When adding to the data set with DISP=MOD or the EXTEND or OUTINX
options of OPEN
v When DFSMSdss copies the data set.
Maintain the following fields of the device dependent portion of the DCB when
writing on DASD:
v The track balance (DCBTRBAL) field that contains a 2-byte unsigned binary
number that indicates the remaining number of bytes on the current track. It is
recommended that your program not directly calculate this number but use the
TRKCALC macro (see “Performing Track Calculations (TRKCALC macro)” on
page 307). Both the calculation values and the algorithm differ among device
types.
v The full disk address (DCBFDAD) field that indicates the location of the current
record. The address is in the form MBBCCHHR. For the actual form of
MBBCCHHR, see Table 44 on page 233.
If space is available for output data sets, the system uses the contents of the full
disk address (DCBFDAD) field, plus one block, to write a file mark when the DCB
is closed or EOV is issued. If the track balance field (DCBTRBAL) is less than
eight, the file mark is written on the next sequential track.
Note that the track containing your last data block, as identified by DCBFDAD,
might not be the best place for a file mark. Consider the following:
204
z/OS DFSMSdfp Advanced Services
v If the file mark is near the end of the track and a future user extends the data
set using DISP=MOD on the DD statement or using the OPEN EXTEND or
OUTINX option, then the first new block might be on the next track. This leaves
a file mark inside the data.
v For compatibility with BSAM and QSAM when you are writing fixed-standard
records, you should cause the file mark to be written wherever the next block
would have been written, as if all blocks were full size. The file mark should not
be “squeezed” on to the current track.
If the system is to write a file mark, you must maintain the contents of these two
fields and set on bit 0 of DCBOFLGS. For further information on DCBOFLGS, see
“Handling End of Volume and End-Of-Data-Set Conditions” on page 193. Use the
OPEN macro instruction to initialize DCBDVTBA and DCBDEVT. You can use
DCBDVTBA or DCBDVTBL with the DEVTAB parameter of the TRKCALC macro
(see “Performing Track Calculations (TRKCALC macro)” on page 307 for the
TRKCALC description).
┌────────────┬─────────────────────────────────────┐
³ 16
³ 17
³
³ DCBKEYLE ³ Reserved
³
└────────────┴─────────────────────────────────────┘
Figure 16. Device-dependent portion of the DCB with DEVD=DA and DSORG=DA
┌───────────────────────────────────────────────────┐
³ 12
³
³
(DCBBLKCT)
³
├────────────┬────────────┬────────────┬────────────┤
³ 16
³ 17
³ 18
³ 19
³
³ DCBTRTCH ³ (DCBDEVT) ³ DCBDEN
³ Reserved ³
└────────────┴────────────┴────────────┴────────────┘
The fields in parentheses represent information not associated with parameters of the DCB
macro instruction. They are set by OPEN and EOV. Your program can modify DCBBLKCT
as described for the REPOS parameter above.
Figure 17. Device-dependent portion of the DCB with DEVD=TA and DSORG=PS
The system uses the contents of the block count (DCBBLKCT) field to write the
block count in trailer labels when the DCB is closed or when the EOV macro
instruction is issued. For tape cartridges, the system also compares this count with
a count calculated from hardware information. OPEN and EOV set this DCB field
to zero except when reading standard labeled tape backward. In that case OPEN or
EOV set DCBBLKCT to the block count in the trailer label.
The I/O process increments this field by the contents of the IOBINCAM field of
the IOB upon completion of each I/O request.
To indicate to the system that your program is maintaining DCBBLKCT, code
foundation block parameter REPOS=Y. See “Foundation Block Parameters” on page
199.
┌────────────┬────────────────────────────────────┐
³ 16
³ 17
³
³ DCBPRTSP ³
Reserved
³
└────────────┴────────────────────────────────────┘
Figure 18. Device-dependent portion of the DCB with DEVD=PR and DSORG=PS
Chapter 4. Executing Your Own Channel Programs
205
┌────────────┬──────────────────────────────────────┐
³ 16
³ 17
³
³ DCBMODE ³
Reserved
³
³ DCBSTACK ³
³
└────────────┴──────────────────────────────────────┘
Figure 19. Device-dependent portion of the DCB with DEVD=PC or RD and DSORG=PS
The following DCB operands pertain to specific devices and can be specified only
when the DEVD parameter is specified.
KEYLEN=length
For direct access devices, the length in bytes of the key of a physical record,
with a maximum value of 255. When a block is read or written, the number of
bytes transmitted is the key length plus the record length. This parameter does
not directly affect EXCP processing, but is stored in the data set label.
DEN=value
For magnetic tape reels, the tape recording density in bits per inch is shown in
the following table:
Value
2
3
4
Density
800 (NRZI)
1600 (PE)
6250 (GCR)
NRZI—Non return-to-zero change to ones recording
recording GCR—group coded recording
PE—phase encoded
If this parameter is omitted, the highest density available on the device is
assumed. Refer to z/OS DFSMS Macro Instructions for Data Sets for further
information on DEN.
TRTCH=value
For magnetic tape subsystems with Improved Data Recording Capability, the
tape recording techniques consist of the following values:
Value
Tape recording technique
COMP
Record data in compacted format.
NOCOMP
Record data in standard uncompacted format.
For 7-track magnetic tape, the tape recording technique:
Value
Tape recording technique
COMP
Record data in compacted format.
C
Data conversion feature is available.
E
Even parity is used. (If omitted, odd parity is
assumed.)
T
BCDIC to EBCDIC translation is required.
MODE=value
For a card reader or punch, the mode of operation. Either C (column binary
mode) or E (EBCDIC code) can be specified. This field and parameter do not
directly affect EXCP processing but your program can use the field. This is
useful to allow you to specify the value on the DD statement.
STACK=value
For a card punch or card reader, the stacker bin to receive cards, either 1 or 2.
206
z/OS DFSMSdfp Advanced Services
This field and parameter do not directly affect EXCP processing but your
program can use the field. This is useful to allow you to specify the value on
the DD statement.
PRTSP=value
For a printer, the line spacing is 0 — 3. This field and parameter do not
directly affect EXCP processing but your program can use the field. This is
useful to allow you to specify the value on the DD statement.
Mapping the DCB
In addition to the operands described in z/OS DFSMS Macro Instructions for Data
Sets for the DSORG parameter of the DCBD macro, you can specify the following
operand:
DSORG=XA or XE
Specify the section of the DCB to be mapped.
XA Specifies a DCB with the foundation block and EXCP interface.
XE Specifies a DCB with the common interface, foundation block extension,
and foundation block.
Code DSORG=(XA,XE) to map all four sections of the DCB.
Data Control Block Extension (DCBE) Fields
The data control block extension (DCBE) provides further processing options.
EXCP supports these options:
v The BLKSIZE parameter when you issue the OPEN and EOV macros.
v The BLOCKTOKENSIZE parameter to signify that your program is able to
handle a DASD data set that has the large format attribute. The data set is not
necessarily large. If you code BLOCKTOKENSIZE=LARGE, then it means that
your program can handle a data set that exceeds 65535 tracks or might grow
above that size. Look for these differences:
– If the data set is a large format data set, the DSCB the DS1LARGE bit will be
on and the two bytes in DS1LSTAR that contain a relative track number are
logically extended with the DS1TTTHI byte. See the format 1 DSCB
description in “Format-1 and Format-8 DSCBs” on page 5.
– The two bytes in each DEBNMTRK field are logically extended by the
DEBNMTRKHI byte. See Appendix A, “Control Blocks,” on page 443.
– If your program calls either of the track conversion routines that CVTPRLTV
or CVTPCNVT point to, then your program should use the +12 entry points
instead of the +0 entry points.
If you do not code BLOCKTOKENSIZE=LARGE on the DCBE macro, then:
– If the OPEN macro option is not INPUT and the data set is large format, then
OPEN will issue a 213-14 ABEND.
– If the OPEN macro option is INPUT and the data set has more than 65535
tracks on the volume, then OPEN will issue a 213-16 ABEND.
v The CAPACITYMODE parameter to write more data on an IBM 3590 Magnetic
Tape Subsystem that emulates an IBM 3490 when you issue the OPEN macro.
v The EADSCB=OK parameter to specify that your application program supports
one of the following, as appropriate:
– VTOC that describes a volume supporting extended attribute DSCBs.
(“Reading and Modifying a Job File Control Block (RDJFCB Macro)” on page
284 describes how to open a VTOC.) An extended address volume may have
extended attribute DSCBs. They are format-8 and format-9 DSCBs. If you do
Chapter 4. Executing Your Own Channel Programs
207
not code this option, the OPEN function will issue ABEND 113-48 and
message IEC142I. Code this option when your application program supports
format-8 and format-9 DSCBs.
– A data set that has extended attribute DSCBs, Track addresses in DSCBs
pointed to by a format-8 DSCB may contain cylinder addresses above 65,520.
If you do not code this option, then OPEN issues a 113-44 ABEND and
message IEC142I. Code this option when your application program supports
MACRF=E (EXCP) and the data set has format 8 and 9 DSCBs.
v The EODAD parameter when you issue an EOV macro. If the DCBEEODAD
field has a non-zero value when the system needs to use it, this value takes
precendence over an EODAD specification in the DCB. See “Foundation Block
Extension and Common Interface Parameters” on page 201.
v The LOC parameter when you issue an OPEN macro. To successfully open a
data set that has been allocated with the XTIOT, UCB NOCAPTURE, or DSAB
above the line dynamic allocation options, you must specify both:
– DCBE option LOC=ANY. The LOC=ANY option is represented by the
DCBELOCANY bit in the DCBE.
– DEVSUPxx parmlib parameter NON_VSAM_XTIOT=YES. The DEVSUPxx
parameter NON_VSAM_XTIOT is represented by DFAXTBAM bit in the DFA
as mapped by IHADFA.
v The CONCURRENTRW=YES,TRKLOCK parameter means that your application
program can tolerate serialization on a track basis. Another system can modify
one or more tracks while your program is reading another track in the data set
extent. Your program cannot read multiple blocks spread across multiple tracks
with consistency. For BSAM, QSAM, and EXCP only specify TRKLOCK if your
program can tolerate this level of serialization. For EXCP channel programs that
do not cross a track boundary, the blocks are consistent. This applies to any type
of data set access using EXCP.
|
|
|
|
|
|
|
|
v The SYNC parameter to control buffered tape marks on an IBM 3590 when you
issue the OPEN, EOV, or CLOSE macros.
Note that the DCBE can be above the 16 MB line even though your user program
is running in 24-bit mode. See z/OS DFSMS Macro Instructions for Data Sets for
more information concerning the DCBE.
Set and Retrieve Data Set Block Size
The DCBE has a field to contain the current or maximum block size for the data
set.
In order to use this field, your program must code a value for the BLKSIZE
keyword on the DCBE macro or turn on the DCBEULBI bit. The keyword value
can be numeric or a non-relocatable symbolic expression. The value can be 0.
If you code a zero value or turn on DCBEULBI, then OPEN stores into
DCBEBLKSI the block size value from the data set label if opening for input or
output with DISP=MOD, which can be disk or tape. If your program issues the
OPEN macro with the OUTPUT or OUTIN option, then OPEN tries to calculate an
optimal value for BLKSIZE as it does for BSAM and QSAM. The
system-determined block size function is described in z/OS DFSMS Using Data Sets.
The basic principle is that your program supplies the LRECL value and RECFM
value (not U) and OPEN calculates an optimal BLKSIZE value for the device and
stores it into DCBEBLKSI.
Attention: OPEN might calculate a BLKSIZE value in the DCBE that exceeds the
maximum that is supported by the regular access methods or other programs that
208
z/OS DFSMSdfp Advanced Services
read your program's data sets. For example, on magnetic tape the value probably
will exceed 32760. If this is a problem, you can do the following:
Supply a DCB OPEN exit routine as described in z/OS DFSMS Using Data Sets. If
your exit routine finds that the DCBEBLKSI field is still 0, it means that the data
set label and the DD statement do not have a value for BLKSIZE. If your program
is opening for output, it can leave the DCBE alone and let OPEN calculate an
optimal BLKSIZE value or it can calculate one. This is your program's last chance
to set it before the system stores the BLKSIZE value in various system control
blocks and the data set label. Your DCB OPEN exit routine can issue the DEVTYPE
macro with the INFO=AMCAP parameter to learn the optimal and maximum
BLKSIZE values for the device. If it is too large, your program can calculate a
smaller valid value. Store a value into DCBEBLKSI before OPEN can set it. The
INFO=AMCAP parameter of DEVTYPE is described on “DEVTYPE—Info Form”
on page 270.
OPEN builds the DEB after calling the DCB OPEN exit routine. If your program
calculates a maximum block size, it can take into consideration a value for
BLKSZLIM coded on the DD statement. To find this value, issue the RDJFCB
macro with an X'13 ' code. See “Reading and Modifying a Job File Control Block
(RDJFCB Macro)” on page 284.
Why should your program do this?
v To decrease your program's dependence on the device type
v The system stores this value in the data set label for use by z/OS and on other
systems
v The system stores this value in various SMF records to improve monitoring of
system resources
v DFSMSrmm™ retains this information for its tape reports.
Unlike the regular access methods, EXCP processing does not do complete
checking of the BLKSIZE value in an EXCP DCBE.
Input/Output Error Data Block (IEDB) Fields
The system uses the IEDB to provide extended error information, and for zHPF the
failing storage address. The IEDB has two versions:
v The version 1 IEDB is 48 bytes.
v The version 2 IEDB is 96 bytes. This is the recommended version for zHPF
channel programs.
You provide an IEDB by setting its address in an IOBE. Set reserved fields to X'00'.
The system moves the sense bytes to IEDBSNS. If fewer than 32 sense bytes are
available, there might be residual data. Refer to “Requesting Extended Error
Information” on page 191 for more information on using the IEDB.
Chapter 4. Executing Your Own Channel Programs
209
0
IEDBID
5
4
IEDBVERS
7
6
IEDBFLG1
IEDBCOD
RESERVED
8-39
IEDBSNS
40-43
RESERVED
44-47
IEDB2CSW
48-55
IEDBFSA
48-55
Reserved
Figure 20. Format of an IEDB, Mapped by the IOSDIEDB Macro
Table 40. IEDB Structure Mapping
Offset
Length or
Bit Pattern
Name
Description
0 (X'0')
4
IEDBID
Eye catcher. Must be "IEDB"
4 (X'4')
1
IEDBVERS
Version.
v The version 1 IEDB is 48 bytes.
v The version 2 IEDB is 96 bytes. This is the
recommended version for zHPF channel programs.
For version 1, the macro defines IEDBVRSC as the version
constant. For version 2, the macro defines IEDBVRS2 as
the version constant.
5 (X'5')
1
IEDBFLG1
Flags field.
1... ....
IEDBBDSN
The sense data is invalid and begins with X'10FE'.
.1.. ....
IEDBFSAV
The failing storage address (IEDBFSA) is valid.
..xx xxxx
210
z/OS DFSMSdfp Advanced Services
Reserved.
Table 40. IEDB Structure Mapping (continued)
Offset
Length or
Bit Pattern
Name
Description
6 (X'6')
1
IEDBCOD
Original I/O completion code prior to EXCP or EXCPVR
changing it. This is the same format as the ECB
completion code byte.
7 (X'7')
1
8 (X'8')
32
IEDBSNS
Sense bytes.
1
IEDBSNS00
Sense byte 0.
1
IEDBSNS01
Sense byte 1.
9 (X'9')
Reserved.
(Fields IEDBSNS02 to IEDBSNS31 define sense bytes 2 to 31.)
40(X'28')
4
Reserved.
44(X'2C')
4
IEDB2CSW
Virtual CCW address pointing after the last CCW
executed by the control unit. The system sets this only if
all of the following are true: (1) EXCP or the user set
IOBEP on to allow prefetching of CCWs and data, (2) the
user set IOB2CSWS on (two channel status words), (3) the
control unit was executing ahead of the channel, (4) the
control unit detected an error and (5) the control unit
reported the failing CCW. The system never clears this
field.
48(X'30')
8
IEDBFSA
The failing storage address for channel control checks and
channel data checks. For zHPF channel programs, a
failing storage address may also be provided for program
checks and protection checks. This field is valid only if
IEDBFSAV is on.
56(X'38')
40
Reserved.
Input/Output Block (IOB) Fields
The input/output block (IOB) is not automatically constructed by a macro
instruction; it must be defined as a series of constants and be on a word boundary.
For unit-record and tape devices, the IOB is 32 bytes long. For direct access,
teleprocessing, and graphic devices, 8 additional bytes must be provided. Use the
system mapping macro IEZIOB, which expands into a DSECT, to help in
constructing an IOB. IEZIOB fields that are not described here are not part of the
programming interface.
In Figure 21 on page 212 the shaded areas indicate fields in which you must
specify information. The other fields are used by the system and must be defined
as all zeros. You cannot place information into these fields, but you can examine
them.
You do not have to set the following IOB fields to any particular value before
issuing EXCP because the system itself sets them:
v IOBSENS0
v IOBSENS1
v IOBECBCC
v IOBCSW
v IOBSIOCC
v IOBCMD31
Chapter 4. Executing Your Own Channel Programs
211
0(0)
2(2)
1(1)
IOBFLAG1
3(3)
IOBSENS0
IOBFLAG2
IOBSENS1
4(4)
IOBECBPB
IOBECBCC
8(8)
IOBFLAG3 and IOBCSW - format depends on channel program.
See related figures below.
All
Devices
16(10)
IOBSTRTB
IOBSIOCC
20(14)
IOBDCBPT
IOBFLAG4
24(18)
IOBRESTR+1
IOBRESTR
28(1C)
IOBINCAM
32(20)
IOBSEEK
(first byte, M)
IOBERRCT
Direct Access, Teleprocessing, and Graphic Devices
33(21)
Direct
Access
Storage
Devices
(DASD)
IOBSEEK
(second through eight bytes,
BBCCHHR)
39(27)
Figure 21. Input/Output Block (IOB) Format
IOBFLAG1 (1 byte)
Set bit positions 0, 1, 6, and 7. One-bits in positions 0 and 1 (IOBDATCH and
IOBCMDCH) indicate data chaining and command chaining, respectively. (If
you specify both data chaining and command chaining, the system does not
use error recovery routines except for the direct access and tape devices.) If an
I/O error occurs while your channel program executes, a failure to set the
chaining bits in the IOB that correspond to those in the CCW might make
successful error recovery impossible. The integrity of your data could be
compromised.
A one-bit in position 6 (IOBUNREL) indicates that the channel program is not
a related request; that is, the channel program is not related to any other
channel program. See bits 2 and 3 of IOBFLAG2 below.
If you intend to issue an EXCP or XDAP macro with a BSAM, QSAM, or
BPAM DCB, you should turn on bit 7 (IOBSPSVC) to prevent access-method
appendages from processing the I/O request.
212
z/OS DFSMSdfp Advanced Services
IOBFLAG2 (1 byte)
If you set bit 6 in the IOBFLAG1 field to zero, bits 2 and 3 (IOBRRT3 and
IOBRRT2) in this field must then be set to one of the following:
v 00, if any channel program or appendage associated with a related request
might modify this IOB or channel program.
v 01, if the conditions requiring a 00 setting do not apply, but the CHE or ABE
appendage might retry this channel program if it completes normally or
with the unit-exception or wrong-length-record bits on in the CSW.
v 10 in all other cases.
The combinations of bits 2 and 3 represent related requests,known as type 1
(00), type 2 (01), and type 3 (10). The type you use determines how much the
system can overlap the processing of related requests. Type 3 allows the
greatest overlap, normally making it possible to quickly reuse a device after a
channel-end interruption. (Related requests that were executed on a pre-MVS
system are executed as type-1 requests if not modified.)
IOBSENS0 and IOBSENS1 (2 bytes)
are set by the system when a unit check occurs. These are the first two sense
bytes. Occasionally, the system is unable to obtain any sense bytes because of
unit checks when sense commands are issued. In this case, the system
simulates sense bytes by moving X'10FE' to IOBSENS0 and IOBSENS1.
The first six of these 16 bits have these device-independent meanings:
1...
.1..
..1.
...1
....
....
....
....
....
....
1...
.1..
Command reject
Intervention required
Bus out check
Equipment check
Data check
Overrun
The last ten of these 16 bits have device-dependent meanings. See appropriate
hardware documentation.
If you wish to retrieve more than two sense bytes, supply an IOBE and IEDB
as described in “Interruption Handling and Error Recovery Procedures” on
page 189.
IOBECBCC (1 byte)
The first byte of the completion code for the channel program. The system
places this code in the high-order byte of the event control block when the
channel program is posted complete. The completion codes and their meanings
are listed under “Event Control Block (ECB) Fields” on page 220.
IOBECBPT (3 bytes)
The address of the 4-byte event control block (ECB) you have provided.
IOBFLAG3 (1 byte) and IOBCSW (7 bytes)
The system stores status information in these eight bytes. See “IOBFLAG3 and
IOBCSW Format for Different Channel Program Types” on page 214.
IOBSIOCC (1 byte)
If the channel program uses format 0 CCWs, bits 2 and 3 contain the start
subchannel (SSCH) condition code for the instruction the system issues to start
the channel program.
If this is a format 1 CCW channel program or is a zHPF channel program, then
field IOBSIOCC is redefined as field IOBSTART, which contains the four byte
starting address of the channel program to be executed. (The IOBE field
IOBESIOC is used instead of IOBSIOCC.)
Chapter 4. Executing Your Own Channel Programs
213
IOBSTRTB (3 bytes)
If the channel program uses format 0 CCWs, the three byte starting address of
the channel program to be executed.
IOBFLAG4 (1 byte)
Set bit 3 (IOBCEF) to indicate whether you are supplying an IOB common
extension (IOBE). If this bit is 1, then register 0 contains the IOBE address
when you issue EXCP or EXCPVR. Refer to “Requesting Extended Error
Information” on page 191 and “Requesting Different Levels of ERP Processing”
on page 192.
You must set IOBCEF on if you want to use format 1 CCWs, 64 bit IDAWS,
MIDAWS, or a zHPF channel program.
IOBDCBPT (3 bytes)
The address of the DCB of the data set to be read or written by the channel
program.
Reserved (1 byte)
Used by the system.
IOBRESTR+1 (3 bytes)
If a related channel program is permanently in error, this field is used to chain
together IOBs that represent dependent channel programs. To learn more about
the conditions under which the chain is built, see “Purging and Restoring I/O
Requests (PURGE and RESTORE macros)” on page 304.
IOBINCAM (2 bytes)
For magnetic tape, the amount by which the system increments the block count
(DCBBLKCT) field in the device-dependent portion of the DCB. You can alter
these bytes at any time. For forward operations, these bytes should contain a
binary positive integer (usually +1); for backward operations, they should
contain a binary negative integer. When these bytes are not used, all zeros
must be specified. See Figure 17 on page 205.
IOBERRCT (2 bytes)
Used by the system.
IOBSEEK (first byte, M)
For direct access devices, the extent entry in the data extent block that is
associated with the channel program (0 indicates the first entry; 1 indicates the
second, and so forth). For teleprocessing and graphic devices, it contains the
UCB index.
IOBSEEK (last 7 bytes, BBCCHHR)
For direct access devices, the seek address for your channel program.
IOBFLAG3 and IOBCSW Format for Different Channel Program
Types
The fields IOBFLAG3 and IOBCSW have different meanings depending on the
type of channel program and its format.
For format 0 CCW channel programs, these fields have the following format:
214
z/OS DFSMSdfp Advanced Services
8(8)
IOBCMDA
IOBFLAG3
12(C)
IOBUSTAT
IOBCSTAT
IOBRESCT
Figure 22. IOBFLAG3 and IOBCSW fields for format 0 channel program
For format 1 CCW channel programs, these fields have the following format:
8(8)
IOBCMD31
12(C)
IOBUSTAT
IOBCSTAT
IOBRESCT
Figure 23. IOBFLAG3 and IOBCSW fields for format 1 channel program
For zHPF channel programs, these fields have the following format:
8(8)
IOBCMD31
12(C)
IOBUSTAT
IOBCSTAT
IOBFCXST
IOBSESTA
Figure 24. IOBFLAG3 and IOBCSW fields for zHPF channel program
IOBFLAG3
This field is used by the system for format-0 CCW channel programs only.
IOBCMDA
The 24-bit ending CCW virtual address or zero for format-0 CCW channel
programs. The ending CCW address points after the last executed CCW in
your channel program. The ending address may be zero if either the system
determined that the address was invalid or the last executed CCW was a CCW
that was added by the system.
IOBCMD31
The 31-bit ending virtual address or zero for format-1 CCW channel programs
and zHPF channel programs. For format-1 channel programs, the ending
address points after the last executed CCW in your channel program. For
Chapter 4. Executing Your Own Channel Programs
215
zHPF channel programs, the ending address points to the TCW. The ending
address may be zero if either the system determined that the address was
invalid, or for CCW channel programs, the last executed CCW was a CCW
that was added by the system.
IOBUSTAT
The device status (previously called unit status).
IOBCSTAT
The subchannel status (previously called channel status). If the ending address
is zero or the subchannel status byte in the IOB (IOBCSTAT) shows any of the
following errors: program check, protection check, channel data check, channel
control check, interface control check, or chaining check, and your appendage
determines that the ERP has not yet run, then let the ERP try to recover and do
not modify IOBSTART. If the ERP has completed and one or more of these six
bits is on or the address is zero, then the status of the channel program is not
known.
IOBRESCT
The residual count for format-0 and format-1 CCW channel programs, which is
the number of bytes not transferred in the last CCW. For zHPF channel
programs, the residual count is four bytes and contained in the IOBE.
IOBFCXST
Used by the system.
IOBSESTA
The subchannel extended status for zHPF channel programs. The subchannel
extended status further qualifies subchannel related errors defined in
IOBCSTAT. Macro IHASESQ defines the different subchannel extended status
values.
Input/Output Block Common Extension (IOBE) Fields
You can construct an IOB common extension (IOBE) block to receive extended
error information or to control the level of error recovery procedure (ERP)
processing. To provide an IOBE, set IOBCEF in IOBFLAG4 on and set the IOBE
address in register 0 when you issue EXCP or EXCPVR. (The IOBE is mapped by
the IOSDIOBE macro).
Set reserved bytes to X'00'. The IOBE can reside above or below 16MB virtual.
The constant IOBELNTH is set to the length of the IOBE and should be used when
obtaining and clearing storage. In addition, the constant IOBEEND represents the
end of the IOBE.
216
z/OS DFSMSdfp Advanced Services
0
IOBEID
5
4
IEDBVERS
7
6
IOBEFLG1
IOBEFLG2
IOBEERPM
8-11
IOBEUSER,IOBEUPTR
12-15
IOBEIEDB
16
17-47
IOBEFLG3
RESERVED
Figure 25. Format of an IOBE, mapped by the IOSDIOBE macro
Table 41. IOBE Structure Mapping
Offset
Length or
Bit Pattern Name
Description
0 (X'0')
4
IOBEID
Eye catcher ("IOBE")
4 (X'4')
1
IOBEVERS
Version number (X'01')
5 (X'5')
1
IOBEFLG1
Reserved.
Chapter 4. Executing Your Own Channel Programs
217
Table 41. IOBE Structure Mapping (continued)
Offset
Length or
Bit Pattern Name
Description
6 (X'6')
1
IOBEFLG2
Flag field 2. Set by issuer of EXCP or EXCPVR.
1... ....
IOBEMIDA
The channel program might have one or more CCWs that has the MIDA
(modified indirect data addressing) bit on and point to a MIDAL (modified
indirect addressing list). Supported only for EXCPVR requests.
This bit must set to zero if you are using a zHPF channel program.
.1.. ....
IOBEP
The user allows unlimited prefetching of CCWs. (Unlimited prefetching of
the IDAWs, MIDAWs, and data associated with the currrent or prefetched
CCW is always allowed.) If zero, no prefetching is allowed, except in the case
of data chaining on output, where prefetching of one CCW describing a data
area is allowed. Prefetching of CCWs applies only for FICON channels. It has
no effect on Enterprise Systems Connection (ESCON) or parallel channels.
This bit applies to EXCPVR; EXCP always uses unlimited prefetching.
This bit must set to zero if you are using a zHPF channel program.
..1. ....
IOBECPNM
...1 ....
IOBEEIDA
The user guarantees that the channel program will not be modified during
execution other than to add CCWs at the end. This bit is supported only for
EXCPVR requests. EXCP requests that do not run in an authorized V=R
address space cannot be modified during execution.
This bit must set to zero if you are using a zHPF channel program.
Any IDAWs are eight bytes each and point to 4096-byte boundaries with the
possible exception of the first IDAW in each list. Currently supported only on
direct access storage device (DASD) and on IBM-supplied cartridge tape
devices. Bit UCBEIDAW in the UCB tells you whether the device supports
64-bit IDAWs. Supported for EXCP and EXCPVR and for format-0 and
format-1 channel programs. Not currently supported in VIO.
This bit must set to zero if you are using a zHPF channel program.
.... 1...
IOBEPCIS
PCI synchronization. Channel must synchronize after the next CCW
following a PCI (at CCW+8). Supported for EXCPVR only if IOBEP is on.
Not supported in VIO. EXCP requests never require PCI synchronization.
This bit must set to zero if you are using a zHPF channel program.
.... .1..
IOBNORWS
.... ..1.
IOB2CSWS
No read/write synchronization. The channel should not synchronize on
read/write transitions. User guarantees that the reads and writes are from
different areas. Always supported for EXCP. Supported for EXCPVR only if
IOBEP is on.
This bit must set to zero if you are using a zHPF channel program.
Two channel status words. If an error occurs where the control unit is
executing ahead of the channel, the system returns two ending CCW
addresses. The second ending CCW address is in the IEDB. Always allowed
for EXCP. Supported for EXCPVR only if IOBEP is on. If this bit is off when
the control unit has an error when executing ahead of the channel, the
system simulates an invalid ending CCW address.
This bit must set to zero if you are using a zHPF channel program.
.... ...1
IOBEFMT1
Channel program is format-1 CCWs and IOBSTART contains a 31-bit address.
This bit also causes the system to use IOBESIOC instead of IOBSIOCC and
for the ending CCW address to be in IOBCMD31 instead of the three bytes in
IOBCMDA. Supported for both EXCP and EXCPVR requests.
1
IOBEERPM
Mask indicating the functions the ERP is allowed to perform.
1.......
IOBEPMSG
User allows basic error recovery procedures (ERP) recovery and permanent
error messages that do not require interaction with the system or an operator.
See "Requesting Different Levels of ERP Processing" on page 87.
This bit must set to zero if you are using a zHPF channel program.
7 (X'7')
.xxx xxxx
218
z/OS DFSMSdfp Advanced Services
Reserved.
Table 41. IOBE Structure Mapping (continued)
Offset
Length or
Bit Pattern Name
Description
8 (X'8')
4
IOBEUSER
Address field for user use.
4
IOBEUPTR
Character field for user use.
12 (X'C')
4
IOBEIEDB
Zero or address of IEDB if you want extended error information. For more
information see, “Requesting Extended Error Information” on page 191.
16 (X'10')
1
IOBEFLG3
Flag byte 3.
1... ....
IOBENSER
Set by user to allow the device to bypass the channel program extent
collision checking. Extent range enforcement remains active. Meaningful only
if the DASD supports it; has no effect otherwise. Can improve performance
on IBM 2105 Enterprise Storage Server™ and newer DASD control units when
using multisystem access or multiple parallel access volumes (PAV).
.1.. ....
IOBENVAL
Set by user to allow the device to bypass the validation checking of the
parameters on define extent and locate record commands. Extent enforcement
remains active; meaningful only if the DASD device supports it, has no effect
otherwise. Can improve performance on IBM 2015 Enterprise Storage Server®
and newer DASD control unitswhen using multisystem access or multiple
parallel access volumes (PAV).
..1. ....
IOBEDSMC
Set by user to disable streaming mode control. This bit must set to zero if
you are using a zHPF channel program.
...1 ....
IOBEIOT
If the user sets this to 0, IOBETIME applies to the request only while the
request is active. If this is 1, IOBETIME applies while the request is queued
or active.
.... 1...
IOBEDCWOffsetValid
For zHPF channel programs, the DCW offset in IOBEDCWOffset is valid.
.... .1..
IOBEResCountValid
For zHPF channel programs, the residual count in IOBEResCount is valid.
.... ..xx
Reserved.
17 (X'11')
1
IOBESIOC
Same format as IOBSIOCC. Valid only if IOBEFMT1 is on.
18 (X'12')
1
IOBETIME
Time limit. If this value is non-zero, it is the number of seconds the user
allows the request to take. Has an effect if the DEBACCS field shows the
DCB is open for input. There will be no message or error recording due to
reaching the limit. Bit IOBEIOT specifies what time is measured.
19(X'13')
1
IOBEFLG4
Flag byte 4.
1... ....
IOBEZHPF
The zHPF channel program. This field is set by the user for EXCPVR and
EXCP virtual requests.
This bit must be set to zero for CCW channel programs.
.1.. ....
.xxx xxxx
IOBECacheMiss
Specifies one or more I/O device cache misses occurred. This bit must be set
to zero if you are using a zHPF channel program.
Reserved.
20(X'14')
4
IOBEResCount
For zHPF channel programs, this field contains the residual count. This field
is valid only if IOBEResCountValid is on.
24(X'18')
2
IOBEDCWOffset
For zHPF channel programs, this field contains the offset within the TCA of
the DCW that was partially or completely executed. If the channel program
could not be completed, this offset identifies the DCW for which processing
could not be completed. This field is valid only if IOBEDCWOffsetValid is
on.
26(X'1A')
1
IOBEDDPC_RC
For zHPF channel programs, this field contains the device detected program
check reason code. This field is valid only when the subchannel status
indicates a program check and the subchannel extended status indicates a
device dependent program check. The reason codes are documented in
z/Architecture® Principles of Operation.
27(X'1B')
1
IOBEDDPC_RCQ
For zHPF channel programs, this field contains the first byte of the device
detected program check reason code qualifier. This field is valid only when
the subchannel status indicates a program check and the subchannel
extended status indicates a device dependent program check. The reason
code qualifiers are documented in z/Architecture Principles of Operation.
Chapter 4. Executing Your Own Channel Programs
219
Table 41. IOBE Structure Mapping (continued)
Offset
Length or
Bit Pattern Name
28(X'1C')
1
29(X'1D')
19
Description
IOBERCOD
The I/O completion reason code. This is the second byte of the completion
code for the channel program. The system also places this code in the second
byte of the event control block when the channel program is posted
complete. The reason codes applicable to EXCP or EXCPVR and their
meanings are listed in “Event Control Block (ECB) Fields.”
Reserved.
Event Control Block (ECB) Fields
Define an event control block (ECB) as a 4-byte area on a word boundary. When
the channel program has been completed, the system places a completion code
containing status information into the ECB (Figure 26). Before examining this
information, test for the setting of the complete bit. If the complete bit is not on,
and your problem program cannot perform other useful operations, issue a WAIT
or EVENTS macro instruction that specifies the ECB. Do not construct a program
loop to test for the complete bit.
The ECB is mapped by the IHAECB macro.
You do not have to set any particular values in the ECB before issuing EXCP or
EXCPVR because the system clears it.
Byte 0
Byte 1
Bytes 2 and 3
Completion code byte
Bit 0 Bit 1
Wait
Reason code
Complete
Undefined
Rest of completion code bits
Figure 26. Event Control Block after Posting of Completion Code
Wait bit
One in this position indicates that the WAIT or EVENTS macro instruction has
been issued, but the channel program has not been completed.
Complete bit
A one in this position indicates that the channel program has been completed.
If it has not been completed, a zero bit is in this position.
Completion code
This code, which includes the wait and complete bits, might be one of the
following hexadecimal expressions. If an appendage posts the ECB, it might
use other 4-byte codes in which the first two bits are 01. Refer to “Start-I/O
Appendage” on page 225 and “Channel-End Appendage” on page 231.
The system sets these codes in IOBECBCC and IEDBCOD before posting the
ECB.
220
Code
Meaning
41
Permanent I/O error
42
Extent error (DASD only). Either IOBSEEK lies outside the extents
described by the DEB or the channel program attempted execution
outside the current extent.
z/OS DFSMSdfp Advanced Services
44
An error occurred after the previous I/O request to the device was
posted complete. The appendages and (if allowed to execute) the ERP
have determined that this is a permanent error. The I/O request is
terminated with the permanent error. The CSW contents and sense
data in the IOB do not apply to the attempted operation. They apply to
the previous operation attempted for any data set on the device. You
can reissue the EXCP macro instruction to restart the channel program.
45
A program check or machine check occurred in IOS while processing
the I/O request.
48
The channel program was purged.
4B
An error occurred during tape repositioning that was requested by the
tape ERP.
4F
Error recovery routines were entered following a direct access error but
are unable to read the home address or record 0.
51
Simulated error status. The appendages and, if allowed to execute, the
ERP have determined that this is a permanent error. The I/O request is
terminated with the permanent error. This code indicates that the
device is in a permanent error state, boxed, or not connected. The code
can indicate also that a missing interrupt was detected and that the
I/O operation was terminated as a result of recovery operations by the
missing interrupt handler.
This completion code appears only in the IEDB, if one was provided. It
is translated to a 41 completion code prior to updating the ECB and
IOBECBCC.
74
Simulated error status. This code is set as a result of attempting to start
an I/O operation to a device that is in a permanent error state, boxed,
or not connected. This code is also set if a missing interrupt was
detected and the I/O operation was terminated as a result of recovery
operations by the missing interrupt handler. The system has set this
code temporarily in IOBECBCC and IEDB to invoke the ERP, if
allowed to execute, and the appendages to determine if the error is
permanent or correctable. If the error is determined to be permanent
the system will change the value to 51. The system does not set the 74
code in the ECB.
7F
Normal I/O completion, but does not appear in the ECB.
Reason code byte
Reason code for the completion code.
Code
Meaning
0E
A zHPF channel program was specified but the device does not
support zHPF. This reason code appears with completion code 41.
10
A zHPF channel program was specified, but the I/O request was
terminated because a capability needed by the I/O request is not
supported by the processor, device, or software. This reason code is
presented if an EXCPVR request is issued when the processor and
device do not support the zHPF incorrect length facility. This reason
code appears with completion code 41.
Chapter 4. Executing Your Own Channel Programs
221
Data Extent Block (DEB) Fields
The data extent block is constructed by the system when an OPEN macro
instruction is issued for the DCB. You cannot modify the fields of the DEB, but you
can examine them. The DEB is mapped by the IEZDEB macro. The DEB fields
used for EXCP and EXCPVR are illustrated in Appendix A, “Control Blocks,” on
page 443. You can find a complete view of DEB fields “Data Extent Block (DEB)
Fields” on page 443.
EXCP and EXCPVR Appendages
An appendage is a routine that provides additional control over I/O operations.
Using appendages, you can examine the status of I/O operations and determine
the actions to be taken for various conditions. An appendage can receive control as
shown in Table 42.
Table 42. EXCP Appendages
Appendage
Description
When Called
ABE
CHE
EOE
PCI
Abnormal-end
Channel-end
End-of-extent
Program-controlled
interruption
Page-fix
Start-I/O
Abnormal conditions
Channel-end, unit exception, wrong-length record
DASD track address in I/O block outside allocated extent limits
When one or more PCI bits are on in a channel program
PGFX
SIO
Prior to SIO for EXCPVR requests
Just prior to translating channel program
Appendages get control in supervisor state, protection key 0, receiving the pointers
from the system described in the following table. The appendages receive control
in 24-bit addressing mode and must return in the same mode.
This information is not part of the intended interface.
Register
Content
0
Points to the user's IOBE if one was provided as input to EXCP or
EXCPVR. Otherwise 0 is passed to the appendage routine.
1
Points to the request queue element.
2
Points to the input/output block.
3
Points to the data extent block.
4
Points to the data control block.
6
Points to the seek address (MBBCCHHR) if control is given to an
end-of-extent appendage.
The track address of the block reference (CCHH) may contain 28-bit
cylinder numbers for devices with more than 65,520 cylinders. Showing
nibbles it is in the form of CCCCcccH, where ccc represent bits 0-11 of the
28-bit cylinder number and CCCC represents bits 12-27 the 28-bit cylinder
number. Use the TRKADDR macro to manipulate 16-bit and 28-bit cylinder
numbers correctly.
7
222
Points to the unit control block (UCB) and always contains a clean 31–bit
UCB address. If the DEB flag "DEB31UCB" is off, then the UCB address is
captured below the 16 MB line. Whereas if DEB31UCB is on, then the
address might point above the 16 MB line even though the appendages
z/OS DFSMSdfp Advanced Services
always are entered in 24–bit mode. The UCB address is captured by OPEN
or EOV until EOV or CLOSE uncaptures it. If the DCBE option "LOC" was
not set or defaulted to "BELOW", that is LOC=BELOW or not coded, or the
"NON_VSAM_XTIOT" option of the DEVSUPxx member of PARMLIB was
set or defaulted to "NO", that is NON_VSAM_XTIOT=NO or not coded. In
other words, OPEN does not capture the UCB if LOC and
NON_VSAM_XTIOT were specified as follows: LOC=ANY and
NON_VSAM_XTIOT=YES.
13
Points to a 16-word area you can use to save input registers or data.
14
Points to the location in the system where control is to be returned
following execution of an appendage. When returning control to the
system, you can use displacements from the return address in register 14.
Allowable displacements are summarized and described later for each
appendage in Table 43.
15
Points to the entry point of the appendage. When the PGFX appendage is
entered, points to the SIO entry point.
The processing done by appendages is subject to the following requirements and
restrictions:
v Register 9, if used, must be set to binary zeros before control is returned to the
system. All other registers, except those indicated in the descriptions of the
appendage, must be saved and restored if you use them. Table 43 summarizes
register conventions. Note that the need to save and restore registers applies to
all eight byes in each register.
v No SVC instructions or instructions that change the status of the system (for
example, WTO, LPSW, or similar privileged instructions) can be issued.
v Loops testing for the completion of I/O operations cannot be used.
The information here describes appendage types, with explanations of when they
are entered, how they return control to the system, and which registers they can
use without saving and restoring their contents. If you do not supply a particular
appendage, or supply no appendage, the system acts as though that appendage
had returned at offset 0 from register 14.
Table 43. Entry Points, Returns, and Available Work Registers for Appendages
Appendage Entry Point
EOE
SIO
Reg 15
Reg 15
Returns
Available Work Registers
v
Reg 14 + 0 - Call ABE
v
Reg 14 + 4 - Skip
v
Reg 14 + 8 - Try again
v
Reg 14 + 0 - Normal
v
Reg 14 + 4 - Skip
Reg. 10, 11, 12, and 13
Reg. 10, 11, and 13
PCI
Reg 15
v
Reg 14 + 0 - Normal
Reg. 10, 11, 12, and 13
PGFIX
Reg 15+4
v
Reg 14 + 0 - Normal
Reg. 10, 11, and 13
CHE
Reg 15
v
Reg 14 + 0 - Normal
Reg. 10, 11, 12, and 13
v
Reg 14 + 4 - Skip
v
Reg 14 + 8 - Re-EXCP
v Reg 14 + 12 - By pass
Chapter 4. Executing Your Own Channel Programs
223
Table 43. Entry Points, Returns, and Available Work Registers for Appendages (continued)
Appendage Entry Point
ABE
Reg 15
Returns
v
Reg 14 + 0 - Normal
v
Reg 14 + 4 - Skip
v
Reg 14 + 8 - Re-EXCP
Available Work Registers
Reg. 10, 11, 12, and 13
v Reg 14 + 12 - By pass
Note: The register conventions for passing parameters from appendages to the system are described in
the individual appendage descriptions.
Making Appendages Available to the System
Prior to execution, appendages must be members of either the SYS1.LPALIB or
SYS1.SVCLIB data set. To put appendages into SYS1.LPALIB or SYS1.SVCLIB,
link-edit them into these data sets after the system has been built. Each appendage
must have an 8-character member name, the first six characters being IGG019 and
the last two being anything in the range from WA to Z9. If your program runs in a
V=R address space and uses a PCI appendage, the appendage and any routine that
the PCI appendage refers to must be placed in either SYS1.SVCLIB or the fixed
link pack area (LPA). For information on providing a list of programs to be fixed
in storage, see z/OS MVS Initialization and Tuning Guide.
The Authorized Appendage List (IEAAPP00)
If an unauthorized program opens a DCB to be used with an EXCP macro
instruction, the names of any appendages associated with the DCB must be listed
in the IEAAPP00 member of SYS1.PARMLIB. (An unauthorized program is one
that runs in a protection key greater than 7 and has not been marked as authorized
by the Authorized Program Facility.) Once you have added your appendages to
SYS1.LPALIB or SYS1.SVCLIB after the system was built, you can add IEAAPP00
to SYS1.PARMLIB and put the names of the appendages in it with the IEBUPDTE
utility or with another program that updates partitioned data sets. See the
description of the IEAAPP00 parmlib member in z/OS MVS Initialization and Tuning
Reference.
The following example shows JCL statements and IEBUPDTE input that add
IEAAPP00 to SYS1.PARMLIB and put the names of one EOE appendage, two SIO
appendages, two CHE appendages, and one ABE appendage in IEAAPP00:
//
JOB
//
EXEC
//SYSPRINT
DD
//SYSUT2
DD
//SYSIN
DD
./ ADD NAME=IEAAPP00
EOEAPP WA,
SIOAPP X1,X2,
CHEAPP Z3,Z4,
ABEAPP Z2
./ ENDUP
/*
...
PGM=IEBUPDTE,PARM=’NEW’
SYSOUT=A
DSN=SYS1.PARMLIB,DISP=SHR
*
Note the following about the IEBUPDTE input:
v The type of appendage is identified by six characters that begin in column 1.
EOEAPP identifies an EOE appendage, SIOAPP an SIO appendage, CHEAPP a
224
z/OS DFSMSdfp Advanced Services
CHE appendage, and ABEAPP an ABE appendage. (The PCI appendage
identifier, PCIAPP, is not shown, because the example does not add a PCI
appendage name to IEAAPP00.)
v Only the last two characters in an appendage's name are specified, beginning in
column 8.
v Each statement that identifies one or more appendage names ends in a comma,
except the last statement.
You can also use IEBUPDTE to add appendage names later or to delete appendage
names. The following example shows JCL statements and IEBUPDTE input that
adds the names of a PCI and an ABE appendage to the IEAAPP00 appendage list
created in the preceding example, and deletes the name of an SIO appendage from
that list:
//
JOB. . .
//
EXEC
PGM=IEBUPDTE,PARM=’NEW’
//SYSPRINT
DD
SYSOUT=A
//SYSUT2
DD
DSN=SYS1.PARMLIB,DISP=SHR
//SYSIN
DD
*
./ ADD NAME=IEAPP00
PCIAPP Y1,
EOEAPP WA,
SIOAPP X1,
CHEAPP Z3,Z4,
ABEAPP Z2,Z4
./ ENDUP
/*
Note the following about the IEBUPDTE input:
v The command to IEBUPDTE is ADD but a replace occurs because PARM='NEW'
is specified.
v All the appendage names that are to remain in IEAAPP00 are repeated.
v IGG019Z4 is both a CHE and an ABE appendage.
Start-I/O Appendage
Unless an ERP is in control, the system passes control to the SIO appendage just
before the system translates and starts your channel program. It is called even if
the channel program is not later translated. Your SIO appendages can build the
channel program. The system does not test IOBSTART until after the SIO
appendage returns. IOBSTART contains the virtual address of the start of the
channel program.
The start I/O appendage may build a zHPF channel program or a CCW channel
program. The caller does not have to set the IOBEZHPF bit prior to issuing the
EXCPVR request. If the start I/O appendage builds a zHPF channel program, it
should set the IOBEZHPF bit if it is not already set, and reset the IOBEFMT1 bit.
Otherwise, it should reset the IOBEZHPF bit.
If the device is not enabled for zHPF or does not have the necessary capabilities,
the start I/O appendage should either build a CCW channel program, or post the
request in error and return to EXCP indicating that the I/O operation should be
skipped (return +4).
Optional return vectors give the I/O requester the following choices:
v Reg. 14 + 0 — Normal return. The system should translate the channel program,
if required, and initiate the I/O.
Chapter 4. Executing Your Own Channel Programs
225
v Reg. 14 + 4 — Skip the I/O operation. The channel program is not initiated. The
channel program is not posted complete. You can post the channel program
complete by using the POST macro, as follows.
– Set the completion code in register 10. This register is used to post the ECB.
– Set register 11 to the ECB address in the IOB.
– Issue the POST macro as shown in the example below:
POST (11),(10),LINKAGE=BRANCH
For more information on the POST macro, see z/OS MVS Programming:
Authorized Assembler Services Guide and z/OS MVS Programming: Authorized
Assembler Services Reference LLA-SDU
Page Fix and EXCPVR Start I/O Appendage
This appendage is a combination of two independent appendages. The complete
appendage is a reenterable subroutine with two entry points, one for the SIO
appendage and one for the PGFX appendage.
The SIO entry point is located at offset +0 in the SIO subroutine; from this entry
point you might have an instruction to branch to any other location in the
appendage. The entry point of the PGFX appendage is at offset +4 in the SIO
subroutine. The address of offset +0, the SIO appendage entry address, is set in
register 15 as the entry point of the PGFX appendage, allowing you to use the
same entry linkage code for both entry points.
Note that you cannot fix pages that were allocated with CONTROL=UNAUTH on
the IARV64 macro. Unauthorized programs cannot override this setting, but they
can allocate 64-bit storage with the IARST64 macro.
PGFX Appendage
This appendage creates a list of the addresses of the areas that must be fixed to
prevent paging exceptions during the execution of the current input/output (I/O)
request. While this appendage can be entered more than once for one I/O request,
each time it is entered it must create the same list of areas to be fixed. The
appendage can use the 16-word save area pointed to by register 13. Registers 10,
11, and 13 can be used as work registers.
Each page-fix entry placed in the list by the appendage must have the following
doubleword format:
³0³1
31³32³33
63³
³─³──────────────────────────────³──³───────────────────────────────³
³0³
Starting virtual
³ 0³
Ending virtual
³
³ ³
address of area
³ ³
address of area
³
³ ³
to be fixed
³ ³
to be fixed + 1
³
³─³──────────────────────────────³──³───────────────────────────────³
³ ³
³ ³
³
On return from the PGFX appendage to the system (via the return address
provided in register 14), register 10 must point to the first page-fix entry and
register 11 must contain the number of page-fix entries in the work area. The
system then fixes the pages corresponding to the areas listed by the PGFX
appendage. The pages remain fixed until the associated EXCPVR request
terminates.
If either the channel end appendage or the abnormal end appendage returns via
the return address in register 14 plus 8, the PGFX appendage is not normally
226
z/OS DFSMSdfp Advanced Services
reentered. Instead, the SIO appendage is entered, and the page-fix list built by the
PGFX appendage is still active. When a PURGE macro has been issued (for
instance, when a storage swap has occurred), the PGFX appendage is entered after
either the channel end appendage or the abnormal end appendage returns via the
return address in register 14 plus 8. When I/O is restored, the PGFX appendage is
entered. The page-fix list must be in page-fixed storage.
SIO Appendage
If you are using EXCPVR to execute a channel program and your channel program
does not already contain real addresses, translate the virtual addresses in the
operands of your channel program to central storage addresses. This should be
done in the SIO appendage. If indirect data addressing is required, use the SIO
appendage to build the indirect address lists (IDALs, MIDALs, or TIDALs) and
turn on the appropriate indirect address list flag for the channel program.
You can use EXCPVR for VIO data sets with the following considerations for the
SIO appendage:
v The use of IDAWs and an IDAL is not required.
v MIDALs and zHPF channel programs are not supported for VIO.
v Addresses in the CSWs and IDAWs must be virtual. They must not be converted
to central storage addresses.
The UCBVRDEB bit in the UCBJBNR byte can be checked to determine if the data
set is being processed with VIO.
When building an IDAL for CCW channel programs consider the following:
v Bit IOBEEIDA, described in “Input/Output Block Common Extension (IOBE)
Fields” on page 216, specifies whether you are using 31-bit or 64-bit IDAWs.
With 31-bit IDAWs, use 2 KB boundaries when determining whether a storage
boundary is crossed for a CCW. With 64-bit IDAWs, use 4 KB boundaries.
v The LRA instruction returns a 31-bit central storage address regardless of
whether you are in 24-bit or 31-bit addressing mode, but fails in those
addressing modes if the central storage address is above 2 GB. If the central
storage address is above 2 GB, you must either use the LRAG or STRAG
instruction to convert the virtual address to a real address or use the LRA
instruction (after first switching to 64-bit addressing mode). If your program
switches to 64-bit addressing mode, you must ensure that you save and restore
the high 32 bits of any register that you modify. If you fail to do this,
unpredictable results can occur for other 64-bit programs in your address space.
See “IDAW Requirements for EXCP Requests” on page 177 for more information
on creating IDAWs for EXCPVR requests.
Program-Controlled Interruption Appendage
This appendage is entered if the channel finds one or more program-controlledinterruption (PCI) bits on in a channel program. It can be entered as many times as
the channel finds PCI bits on, or more often. Before the appendage is entered, the
contents of the subchannel status word are placed in the channel status word field
of the input/output block.
Note that PCI and PCI appendages are not supported for zHPF channel programs.
A PCI appendage is reentered if an ERP is retrying a channel program in which a
PCI bit is on. The IOB error flag is set when the ERP is in control (IOBFLAG1 =
Chapter 4. Executing Your Own Channel Programs
227
X'20'). (For special PCI conditions encountered with command retry, see
“Command Retry Considerations” on page 188.)
To post the channel program from a PCI appendage to an EXCP request (EXCP
V=V), use the procedure described in “SIO Appendage” on page 227.
If the step is running ADDRSPC=REAL (V=R) and an authorized program issued
the EXCP request or if an EXCPVR request was issued, the PCI appendage uses
central storage addresses. Use the following procedure to post the channel
program from the PCI appendage. For more information on the POST macro, see
z/OS MVS Programming: Authorized Assembler Services Guide and z/OS MVS
Programming: Authorized Assembler Services Reference LLA-SDU.
The POST macro is coded as follows:
POST
ecbaddr,compcode,ASCB=addr,ERRET=addr,ECBKEY=key,
LINKAGE=BRANCH,MEMREL=NO
The ERRET routine address must point to a BR 14 instruction. This instruction
must be in storage addressable from any address space (for example, CVTBRET)
and addressable by 24 bits.
Note: If you specify the ASCB parameter with MEMREL=NO, only registers 9 and
14 are restored when returning from the POST macro.
The following procedure posts the channel program from the PCI appendage.
1. Save necessary registers, because only registers 9 and 14 are restored on the
return from the POST macro.
2. Set the ECB key in register 0.
3. Set the 4-byte completion code in register 10.
4. Set the ECB address in register 11.
5. Set the error routine address in register 12, by setting it to address of CVTBRET
and turn on the high-order bit (X'80') of the high-order byte.
6. Set the ASCB address in register 13. If you do not have the ASCB address, you
can use the following procedure to obtain the ASCB address:
a. Issue the EPAR instruction to obtain the ASID. For information on the EPAR
instruction, see z/Architecture Principles of Operation.
b. Issue the LOCASCB macro to obtain the ASCB address. The LOCASCB
macro is documented in z/OS MVS Programming: Authorized Assembler
Services Reference LLA-SDU.
7. Issue the POST macro, as shown in the following example:
POST (11),(10),ASCB=(13),ERRET=(12),ECBKEY=(0),LINKAGE=BRANCH
8. On return, reestablish necessary registers.
To return control to the system for normal operation, use the return address in
register 14.
End-of-Extent Appendage
If an end-of-cylinder or file-protect condition occurs, the system updates the seek
address to the next higher cylinder or track address and retries the request. If the
new seek address is within the current extent for the data set, the request is
executed; if the new seek address is not within the current extent for the data set,
the EOE appendage is entered. To try the request in the next extent, move the new
seek address to the location pointed to by register 6.
228
z/OS DFSMSdfp Advanced Services
If a file protect is caused by a full seek (command code=07) embedded within a
channel program, the request is flagged as a permanent error, and the ABE
appendage is entered.
The end-of-extent (EOE) appendage is entered when the seek address specified in
the input/output block is outside the allocated extent limits indicated in the data
extent block.
The simplest way to compare two track or block addresses to see their relative
positions on the volume is to use the CLC instruction; however that technique
works only if both addresses (CCHH or CCHHR) contain cylinder numbers of less
than 65536. To handle any addresses that are more or less than cylinder 65536, use
the TRKADDR macro with the COMPARE option. See “Compare two track
addresses (TRKADDR COMPARE)” on page 318.
You can use the following optional return addresses:
v Contents of register 14 to return control to the system, causes the ABE
appendage to be entered. The system places an end-of-extent error code (X'42')
in the ECB code field of the input/output block for subsequent posting in the
ECB.
v Contents of register 14 plus 4: The channel program is posted complete with
X'42'. The ABE appendage is not reentered for this request.
v Contents of register 14 plus 8: The request is tried again.
Registers 10 through 13 in an EOE appendage can be used without saving and
restoring their contents.
Abnormal-End Appendage
To determine the method the system uses to handle an abnormal condition use the
abnormal-end (ABE) appendage. The following information explains how to use
the ABE appendage.
This appendage can be entered on abnormal conditions, such as unit exception,
wrong-length indication, out-of-extent error, intercept condition (that is, device end
error), unit check, program check, protection check, channel data check, channel
control check, interface control check, and chaining check. It can also be entered
when an EXCP is issued for a DCB that has already been purged. The following
apply:
v If IOBECBCC is set to X'41', this appendage was entered because of a unit
exception or wrong-length record indication or both. The system previously
called the channel-end appendage, if present. For further information on these
conditions, see “Channel-End Appendage” on page 231.
v If the IOBECBCC is set to X'42', this appendage was entered because of an
out-of-extent error. The system previously called the end-of-extent appendage, if
present.
v If this appendage is entered with IOBECBCC set to X'4B', the tape error recovery
procedure (ERP) either encountered an unexpected load point, or found zeros in
the command address field of the CSW.
v If the IOBECBCC is set to X'7E', the appendage was first entered because of an
intercept condition. If it is then determined that the error condition is
permanent, the appendage will be reentered with the IOBECBCC set to X'44'.
The intercept condition signals that an error was detected at device end after
channel end on the previous request.
Chapter 4. Executing Your Own Channel Programs
229
v If the IOBECBCC was set to X'48', the appendage was entered because of an
EXCP being issued to an already purged DCB. This applies only to related
requests.
v If the appendage is entered with IOBECBCC set to X'7F', it might be because of
a unit check, program check, protection check, channel data check, channel
control check, interface control check, or chaining check. If the IOBECBCC is
X'7F', it is the first detection of an error in the associated channel program. If the
IOBIOERR flag (bit 5 of the IOBFLAG1) is on, the IOBECBCC field will contain
X'41', X'42', X'48', X'4B', or X'4F', indicating a permanent I/O error.
v If the ending address is zero or the subchannel status byte in the IOB
(IOBCSTAT) shows any of the following errors: program check, protection check,
channel data check, channel control check, interface control check, or chaining
check, and your abnormal end appendage determines that the ERP has not yet
run, then do not modify IOBSTART. This lets the ERP try to recover. If the ERP
has completed and one or more of these six bits is on or the address is zero,
then the status of the channel program is not known.
To determine if an error is permanent, check the IOBECBCC field of the IOB for a
X'4x' completion code.
To determine the type of error, check the subchannel status word field and the
sense information in the IOB. However, when the IOBECBCC is X'42', X'48', or
X'4F', these fields are not applicable. For X'44', the CSW is applicable, but the sense
is valid only if the unit check bit is set.
By using the return address in register 14 to return control to the system, the
channel program is posted complete, and its request element is made available.
You can use the following optional return addresses:
v Contents of register 14 plus 4: The channel program is not posted complete, but
its request element is made available. You can post the channel program by
using the calling sequence described under the SIO appendage.
v Contents of register 14 plus 8: The channel program is not posted complete, and
its request element is placed back on the request queue to be retried. Reinitialize
the IOBFLAG1, IOBFLAG2, and IOBFLAG3 fields of the input/output block and
set the IOBERRCT field to zero. As an added precaution, clear the IOBSENS0,
IOBSENS1, and IOBCSW fields.
The appendage can request that a different type of channel program be started.
For example:
– The original request was for a zHPF channel program but the device is no
longer enabled for zHPF or does not support the zHPF capabilities required
by the new channel program.
– The original request was for a non-zHPF channel program but the new I/O
request allows a zHPF channel program to be used.
The channel program type may be changed from non-zHPF to zHPF only if the
caller passed an IOBE to EXCP. If the channel program type is changed, the
appendage must set or reset the IOBEFMT1 and IOBEZHPF bits correctly to
reflect the type of channel program. For example, if the original channel
program was a format-1 CCW channel program and the new channel program is
a zHPF channel program, then the IOBEFMT1 bit must be reset and the
IOBEZHPF bit must be set.The system will call appendages, beginning with the
SIO appendage, as if this were a new EXCP or EXCPVR request. Note that the
EXCPVR page fix appendage will not be called again.
230
z/OS DFSMSdfp Advanced Services
v Contents of register 14 plus 12: The channel program is not posted complete,
and its request element is not made available. (Use this return only if the
appendage has passed the request queue element to the exit effector for use in
scheduling an asynchronous routine.)
Registers 10 through 13 in an ABE appendage can be used without saving and
restoring their contents.
Channel-End Appendage
This appendage is entered when a channel end (CHE), unit exception (UE) with or
without channel end or when channel end with wrong-length record (WLR) occurs
without any other abnormal-end conditions.
By using the return address in register 14 to return control to the system, the
channel program is posted complete, and its request element is made available. In
the case of unit exception or wrong-length record, the ERP is performed before the
channel program is posted complete, and the IOBIOERR flag (X'04') in IOBFLAG1
is set on. The CSW status can be obtained from the IOBCSW field.
If the appendage takes care of the wrong-length record or unit exception or both, it
can turn off the IOBIOERR (X'04') flag in IOBFLAG1 and return normally. The
event will then be posted complete (completion code X'7F' under normal
conditions, taken from the high-order byte of the IOBECBCC field). If the
appendage returns normally without resetting the IOBIOERR flag to zero, the
request will be routed to the associated device ERP. If the ERP could not correct
the error, the ABE appendage will be entered with the completion code in
IOBECBCC set to X'41'. (See the first bullet in “Abnormal-End Appendage” on
page 229.)
You can use the following optional return addresses:
v Contents of register 14 plus 4: The channel program is not posted complete, but
its request element is made available. You can post the channel program by
using the calling sequence described under the SIO appendage. This is especially
useful to post an ECB other than the ECB in the input/output block.
v Contents of register 14 plus 8: The channel program is not posted complete, and
its request element is placed back on the request queue so that a channel
program at the same or different address can be executed. For correct execution
of the channel program, reinitialize the IOBFLAG1, IOBFLAG2, and IOBFLAG3
fields of the input/output block and set the error counts field to zero. As an
added precaution, clear the IOBSENS0, IOBSENS1, and IOBCSW fields. You can
change IOBSTART before returning. If the device is DASD, you can change the
IOBSEEK field but the first byte must refer to an extent with the same UCB
address. The system will call appendages, beginning with the SIO appendage, as
if this were a new EXCP or EXCPVR request. Note that the EXCPVR page fix
appendage will not be called again.
The appendage can request that a different type of channel program be started.
For example:
– The original request was for a zHPF channel program but the device is no
longer enabled for zHPF or does not support the zHPF capabilities required
by the new channel program.
– The original request was for a non-zHPF channel program but the new I/O
request allows a zHPF channel program to be used.
The channel program type may be changed from non-zHPF to zHPF only if the
caller passed an IOBE to EXCP. If the channel program type is changed, the
Chapter 4. Executing Your Own Channel Programs
231
appendage must set or reset the IOBEFMT1 and IOBEZHPF bits correctly to
reflect the type of channel program. For example, if the original channel
program was a format-1 CCW channel program and the new channel program is
a zHPF channel program, then the IOBEFMT1 bit must be reset and the
IOBEZHPF bit must be set.
v Contents of register 14 plus 12: The channel program is not posted complete,
and its request element is not made available. (Use this return only if the
appendage has passed the request queue element to the exit effector for use in
scheduling an asynchronous routine. For information on asynchronous exit
routines, see z/OS MVS Programming: Authorized Assembler Services Guide.)
Registers 10 through 13 in a CHE appendage can be used without saving and
restoring their contents.
Converting a Relative Track Address to an Actual Track Address
Convert a relative track address to the actual address by using a resident system
conversion routine that can be called in 24 or 31 bit mode.
The conversion routine has two entry points. One, at the address in the
CVTPCNVT field of the communication vector table (CVT), is intended for data
sets with up to 65535 tracks. The other, at offset +12 from the address in
CVTPCNVT, is intended for any data set. Call the conversion routine with one of
the following instructions:
BALR 14,15 Call +0 entry point for track conversion
BASR 14,15 Call +0 entry point for track conversion
BAL 14,12(,15) Call +12 entry point for track conversion
BAS 14,12(,15) Call +12 entry point for track conversion
IBM does not provide a macro for this conversion routine's invocations.
The address of the CVT is in storage location 16 (field FLCCVT of the PSA data
area, mapped by macro IHAPSA).
The conversion routine does all its work in general registers. Load registers 0, 1, 2,
14, and 15 with input to the routine. Register usage is as follows:
232
z/OS DFSMSdfp Advanced Services
Table 44. Registers and Their Use for Converting Relative to Actual
Register
Use
0
Must be loaded with a 4-byte value of the relative track number.
If entered at CVTPCNVT+0, this value must be in the form TTRn,
where:
TT
The track number relative to the beginning of the data set
R
The block identification on that track
n
If the DEB is for a partitioned concatenation, (the DSORG
field in the DCB indicates PO), then supply the
concatenation number for the data set. A value of 0
indicates the first data set, 1 indicates the second data set
and so forth. If your partitioned concatenation includes
PDSEs or z/OS UNIX directories, each of them is
represented by a dummy extent in the DEB. EXCP and
EXCPVR are not valid for those extents. If the data set is
not concatenated or the concatenation is not partitioned, set
to 0.
If entered at CVTPCNVT+12, this value must be in the form TTTR,
where:
TTT
1
2
3–8
9–12
The track number relative to the beginning of the data set
R
The block identification on that track
This entry point is intended for any type of data set.
Must be loaded with the address of the data extent block (DEB) of
the data set. Each DEB resides below 16 MB. When you call the +0
entry point, the called routine clears the high order byte of this
register. When you call the +12 entry point, this byte must contain
X'00'. Note that if the DEB31UCB bit is zero, the UCB address field
is three bytes in DEBUCBA. If the DEB31UCB bit is one, the UCB
address field is four bytes in DEBUCBAD.
Must be loaded with the address of an 8-byte area that is to receive
the actual address of the block to be processed. The converted
address is of the form MBBCCHHR, where:
M
Indicates which extent entry in the data extent block is
associated with the direct access program. (0 indicates the
first extent, 1 indicates the second, and so forth)
BB
Two bytes of zeros
CC
Low order 16 bits of the cylinder number. The cylinder
number is 28 bits on all currently supported DASD.
HH
The actual track number in the low order four bits and the
high order twelve bits of the cylinder number in the high
order twelve bits.
R
The block number.
Not used by the conversion routine.
Used by the conversion routine and not restored.
Chapter 4. Executing Your Own Channel Programs
233
Table 44. Registers and Their Use for Converting Relative to Actual (continued)
Register
Use
13
Used by the conversion routine and not restored. If you call the +12
entry point, the high order three bytes must contain zero and the
low order byte must be as set as follows:
v If the DEB is for a partitioned concatenation, (the DSORG field in
the DCB indicates PO), then supply the concatenation number for
the data set. A value of 0 indicates the first data set, 1 indicates
the second data set and so forth.
14
15
v If the data set is not concatenated or the concatenation is not
partitioned, set to 0.
Must be loaded with the address to which control is to be returned
after execution of the conversion routine.
Used by the conversion routine as a base register and must be
loaded with the address where the conversion routine is to receive
control (from field CVTPCNVT of the CVT).
Return Codes from the Relative to Actual Conversion Routine
When control is returned to your program, register 15 contains one of the
following return codes:
Table 45. Relative to Actual Conversion Routine Return Codes
Return Code
Description
0 (X'00')
4 (X'04')
Successful conversion.
The relative track address converts to an actual track address
outside the extents defined in the DEB.
Internal access method control blocks are invalid. Call IBM service if
the control blocks should be valid.
Internal access method control blocks are invalid. Call IBM service if
the control blocks should be valid.
Passed concatenation number is too big for the data set.
The combination of the DEBNMTRK and DEBNMTRKHI fields in
the last extent shows that the input track number points into this
extent, but the calculated CCHH does not lie within this extent.
8 (X'08')
12(X'0C')
16 (X'10')
20 (X'14')
Converting an Actual Track Address to a Relative Track Address
Convert an actual track address to a relative track address by using a resident
system conversion routine that can be called in 24 or 31 bit mode.
The conversion routine has two entry points. One, at the address in the
CVTPRLTV field of the communication vector table (CVT), is intended for data sets
with up to 65535 tracks. The other, at offset +12 from the address in CVTPRLTV, is
intended for any data set. Call the conversion routine with one of the following
instructions:
BALR 14,15 Call +0 entry point for track conversion
BASR 14,15 Call +0 entry point for track conversion
BAL 14,12(,15) Call +12 entry point for track conversion
BAS 14,12(,15) Call +12 entry point for track conversion
IBM does not provide a macro for this conversion routine's invocations.
234
z/OS DFSMSdfp Advanced Services
The conversion routine will return either TTR0 (if entered at CVTPRLTV+0) or
TTTR (if entered at CVTPRLTV+12), where TTR0 and TTTR are as described in
Table 44 on page 233.
The address of the CVT is in storage location 16 (field FLCCVT of the PSA data
area, mapped by macro IHAPSA).
The conversion routine does all its work in general registers. Load registers 1, 2,
14, and 15 with input to the routine. Register usage is as follows:
Table 46. Registers and Their Use for Converting Actual to Relative
Register
Use
0
Loaded with the resulting TTR0 or TTTR to be passed back to the
caller. These two formats are as described for register 0 in Table 44
on page 233.
Must be loaded with the address of the data extent block of the
data set. Each DEB resides below 16 MB. When you call the +0
entry point, the called routine clears the high order byte of this
register. When you call the +12 entry point, this byte must contain
X'00'.
Must be loaded with the address of an 8-byte area containing the
actual address to be converted to a TTR0 or TTTR. The actual
address is of the form MBBCCHHR.
Not used by the conversion routine.
Used by the conversion routine and not restored.
Must be loaded with the address to which control is to be returned
after execution of the conversion routine.
Used by the conversion routine as a base register and must be
loaded with the content of field CVTPRLTV of the CVT.
1
2
3–8
9–13
14
15
Return Codes from the Conversion Routine
When control is returned to your program, register 15 contains one of the
following return codes:
Table 47. Actual to Relative Conversion Routine Return Codes
Return Code
Description
0 (X'00')
4 (X'04')
Successful conversion.
CCHH is outside of extent M. Returned relative track number is
invalid. If you called the +12 entry point, then it has set the output
R byte to X'FE'.
Internal access method control blocks are invalid. Call IBM service if
the control blocks should be valid.
Internal access method control blocks are invalid. Call IBM service if
the control blocks should be valid.
Passed extent number M is too big for the data set. If you called the
+12 entry point, then it has set the output R byte to X'FE'.
The calculated relative track number is too large to be returned. If
you called the +0 entry, then the track number exceeds X'FFFF', so
the routine returned X'FFFFFE00'. If you called the +12 entry point,
then the track number exceeds X'FFFFFF', so the routine returned
X'FFFFFFFE'. The likely causes of this are that the DEB is not valid
or (for entry +0) the data set is a large format data set, but the track
location is more than X'FFFF' tracks into the data set.
8 (X'08')
12(X'0C')
16 (X'10')
20 (X'14')
Chapter 4. Executing Your Own Channel Programs
235
Note: For return codes 4, 16 and 20 with the +12 entry point, this routine returns a
different value for the R byte (X'FE') than was passed to it.
Using the IECTRKAD Callable Service or the TRKADDR Macro
The IECTRKAD callable service or the TRKADDR macro can be used to perform
the following operations on both 16-bit and 28-bit cylinder addresses:
v Calculate the relative track number on the volume
v Compare two track addresses
v Extract the 28-bit cylinder number
v Extract the 4-bit track number
v Increment the track address by one track and increment the cylinder number if
necessary.
v Normalize cylinder number to permit comparing one cchh against another
v Convert a relative track number to a 28-bit cylinder address
v Set the cylinder number in a 28-bit track address
v Convert a normalized track address into an absolute 28-bit track address.
See “Call for converting and comparing 28-bit cylinder addresses (IECTRKAD)” on
page 359 and “Perform calculations and conversions with 28-bit cylinder addresses
(TRKADDR macro)” on page 317 for more information.
Obtaining the Sector Number of a Block on an RPS Device
For programs that can be used with both RPS and non-RPS devices, test the
UCBRPS bit (bit 3 at offset 17 of the UCB) to determine whether the device has
rotational position sensing. If the UCBRPS bit is off, do not issue a channel
program with a Set Sector command to the device. The address of the sector
conversion routine's entry point is in the CVT0SCR1 field of the CVT.The IBM
DS8000® and newer storage subsystems accept the Set Sector command, but the
command has no effect.
Your program can call the conversion routine by issuing a BASR 14,15 or BAS
14,16(,15) instruction. If you are passing the track balance to the routine, invoke the
routine using a BAS 14,8(15) or BAS 14,20(,15). If you are computing the sector
value on modulo devices with variable length records, pass the track balance to the
sector convert routine.
The sector convert routine can be called in 24-bit or 31-bit mode at any of its entry
points. When calling in 24-bit mode all addresses must point below the 16MB line.
Note:
1. The sector convert routine does not support PDSEs or extended format data
sets. Using the sector convert routine against a PDSE or extended format data
set returns results that are inconsistent with the physical record format.
2. The sector convert routine does not support data sets that are not DASD or do
not have a UCB. Examples include tape, dummy data sets (DD DUMMY),
spooled data sets (*, DATA or SYSOUT), TSO terminals and z/OS UNIX files
such as zFS and HFS files. You will receive unpredictable results if you use the
conversion routine with a data set or file that is not on DASD or does not have
a UCB.
For RPS devices, the conversion routine does all its work in general registers. Load
registers 0, 2, 14, and 15 with input to the routine. Register usage is as follows:
236
z/OS DFSMSdfp Advanced Services
Table 48. Registers and Their Use for A Sector Convert Routine
Register
Use
0
For fixed, standard blocks or fixed, unblocked records not in a
partitioned data set: Register 0 must contain a 4-byte value in the
form XXKR, where:
XX
A 2-byte field containing the physical block size
K
A 1-byte field containing the key length
R
A 1-byte field containing the number of the record for
which a sector value is desired.
To indicate fixed-length records, turn off (set to 0) the high-order bit
of register 0.
Passing the track balance: Register 0 must contain a 4-byte value of
the track balance of the record preceding the required record.
For all other cases: Register 0 must contain a 4-byte value in the
form BBIR, where:
BB
The total number of key and data bytes on the track up to,
but not including, the target record. To indicate
variable-length records, turn on (set to 1) the high-order bit
of register 0.
I
A 1-byte key indicator (1 for keyed records, 0 for records
without keys)
A 1-byte field containing the number of the record for
which a sector value is desired.
Not used by the sector-convert routine.
When called at offset 0 or 8, must contain a 4-byte field where:
R
1
2
The first byte is the UCB device type code for the device
(obtainable from UCB+19)
The remaining 3 bytes are the address of a 1-byte area that
is to receive the sector value.
3-8
9-10
11
12,13
14
15
If called at offset 16 or 20, must contain the address of a 1-byte area
that is to receive the sector value.
Not used.
Used by the convert routine and not saved or restored.
If called at offset 0 or 8, not used.
If called at offset 16 or 20, contains 1-byte UCBTBYT4 code in the
low-order byte. The remaining three bytes must contain zero.
Not used.
Must be loaded with the address in which control is to be returned
after execution of the sector conversion routine.
Used by the conversion routine as a base register and must be
loaded with the address of the entry point to the conversion routine
(from field CVT0SCR1 of the CVT).
Chapter 4. Executing Your Own Channel Programs
237
238
z/OS DFSMSdfp Advanced Services
Chapter 5. Using XDAP to Read and Write to Direct Access
Devices
The execute direct access program (XDAP) is a macro instruction used to read,
verify, or update a block on a direct access volume. This information covers the
XDAP macro instruction, including information for compatibility with other IBM
operating systems, what the XDAP macro does, and how to use it. It also discusses
the macro instructions used with XDAP and the control blocks that are generated.
However, IBM suggests using an access method such as VSAM in place of XDAP.
Because most of the specifications for XDAP are similar to those for the execute
channel program (EXCP) macro instruction, you should be familiar with the
information in “IDAW Requirements for EXCP Requests” on page 177 of this
publication. You should also be familiar with the information in z/OS DFSMS
Using Data Sets that provides how-to information for using the access method
routines of the system control program.
If you are not using the standard IBM data access methods, by issuing XDAP you
can generate the control information and channel program necessary for reading or
updating the records of a data set.
Restriction: XDAP does not support partitioned data set extended (PDSEs) ,
extended-format data sets, UNIX files, UNIX system services data sets, or SYSIN
and SYSOUT data sets.
While XDAP cannot be used to add blocks to a data set, it can be used to change
the keys of existing blocks. Any block configuration and any data set organization
can be read or updated.
XDAP requires less storage than do the standard access methods. However, XDAP
does not provide many of the control program services that are included in the
access methods. For example, when XDAP is issued, the system does not block or
unblock records and does not verify block length.
All virtual addresses that you use with XDAP except the OPEN and CLOSE
parameter lists, DCBE, and IOBE must be 24–bit.
Using XDAP
To issue XDAP, provide the actual track address of the track containing the block
to be processed. Also provide either the block identification or the key of the block,
and specify which you should use to locate the block. If a block is located by
identification, both the key and data portions of the block can be read or updated.
If a block is located by key, only the data portion can be processed.
For additional control over I/O operations, you can write appendages that must be
entered into the LPA library. Descriptions of these routines and their coding
specifications are included under “IDAW Requirements for EXCP Requests” on
page 177.
When using the XDAP macro instruction, code a DCB macro instruction in your
program to generate a data control block (DCB) for the data set to be read or
© Copyright IBM Corp. 1979, 2017
239
Using XDAP
updated. Also code an OPEN macro instruction that initializes the data control
block and produces a data extent block (DEB). The OPEN macro instruction must
be executed before any XDAP macro instructions are executed.
When the XDAP macro instruction is assembled, a control block and the following
executable code are generated. This control block can be logically divided into
three sections:
v An event control block (ECB) that is supplied with a completion code each time
the direct access channel program is terminated.
v An input/output block (IOB) that contains information about the direct access
channel program.
v A direct access channel program consisting of three or four channel command
words (CCWs). The type of channel program generated depends on the
parameters of the XDAP macro instruction. When executed, it locates a block by
either its actual address or its key and reads, updates, or verifies the block.
When the channel program has terminated, a completion code is placed into the
event control block. After issuing XDAP and the direct access program has
terminated, regain control by using a WAIT macro instruction to specify the
address of the event control block. If volume switching is necessary, issue an EOV
macro instruction. Once processing of the data set is completed, issue a CLOSE
macro instruction to restore the data control block.
The parameters of the XDAP macro instruction are described in “Executing Direct
Access Programs” on page 241.
Macro Instructions Used with XDAP
When using the XDAP macro instruction, you must also code DCB, OPEN, CLOSE
and, in some cases, the EOV macro instructions. Special requirements or options
for the other required macro instructions are explained in the following:
v “Defining a Data Control Block (DCB)”
v “Initializing a Data Control Block (OPEN)”
v “End of Volume (EOV)” on page 241
v “Restoring a Data Control Block (CLOSE)” on page 241
See “Data Control Block (DCB) Fields” on page 196 for listings of the parameters
for DCB, OPEN, CLOSE and EOV.
Defining a Data Control Block (DCB)
Issue a DCB macro instruction for each data set to be read, updated, or verified by
the direct access channel program. To learn which macro instruction parameters to
code, see “Data Control Block (DCB) Fields” on page 196.
Initializing a Data Control Block (OPEN)
The OPEN macro instruction initializes one or more data control blocks so that
their associated data sets can be processed. Issue OPEN for all data control blocks
used by the direct access program. Some of the procedures performed when OPEN
is executed include the following actions:
v Constructing a data extent block
v Transferring information from DD statements and data set labels to the DCB
v Verifying or creating standard labels
v Loading programmer-written appendage routines.
240
z/OS DFSMSdfp Advanced Services
Using XDAP
The two parameters of the OPEN macro instruction are the address or addresses of
the data control blocks to be initialized and the method of I/O processing of the
data set. The processing method can be specified as INPUT, OUTPUT, UPDAT, or
EXTEND; however, if nothing is specified, INPUT is assumed. The parameters and
different forms of the OPEN macro instruction are described in z/OS DFSMS Macro
Instructions for Data Sets.
End of Volume (EOV)
The EOV macro instruction identifies end-of-volume (EOV) and end-of-data-set
conditions. For an end-of-volume condition, EOV causes switching of volumes and
verification or creation of standard labels. For an end-of-data-set condition (except
when another data set is concatenated), EOV causes your end-of-data-set routine to
be entered. When using XDAP, issue EOV if switching of direct access volumes is
necessary or if secondary allocation is to be performed for a direct access data set
opened for output. For details about the parameters of the EOV macro instruction,
see “Handling End of Volume and End-Of-Data-Set Conditions” on page 193.
Note: Should EOV call DADSM EXTEND to extend on the same volume or a new
volume (which implies DASD output), EXTEND will issue an enqueue on
SYSVTOC. If the EOV request is issued for a data set on a volume where the
application already holds the SYSVTOC enqueue, this will cause abnormal
termination. For this case, a circumvention would be to allocate the output data set
large enough to not require a secondary extent or request the output data set be on
a volume that is different than the one for which it holds the SYSVTOC enqueue.
Restoring a Data Control Block (CLOSE)
The CLOSE macro instruction restores one or more data control blocks so that
processing of their associated data sets can be terminated. Issue CLOSE for all data
sets used by the direct access channel program. When CLOSE is executed, some of
the following procedures are performed:
v Releasing the data extent block
v Removing information that was transferred to data-control block fields when
OPEN was executed
v Verifying or creating standard labels
v Releasing programmer-written appendage routines.
The CLOSE macro instruction must identify the address of at least one data control
block to be restored, and can specify other parameters. The parameters and
different forms of the CLOSE macro instruction are described in z/OS DFSMS
Macro Instructions for Data Sets.
Executing Direct Access Programs
The XDAP macro instruction produces the XDAP control block (that is, the ECB,
IOB, and channel program) and executes the direct access channel program.
The format of the XDAP macro instruction is:
Chapter 5. Using XDAP to Read and Write to Direct Access Devices
241
Using XDAP
►►
XDAP ecb_symbol
,type
,dcb_addr
,area_addr
►
,blkref_addr
►
label
► ,length_value ,
(key_addr,keylength_value)
►
►◄
,sector_addr
,IOBE=
N
Y
,MF=
E
L
ecb_symbol—symbol or (2-12)
The symbolic name to be assigned to the XDAP event control block. Registers
can be used only with MF=E.
type— RI or RK or WI or WK or VI or VK
The type of I/O operation intended for the data set and the method by which
blocks of the data set are to be located. One of the combinations shown must
be coded in this field. The codes and their meanings are:
R
Read a block.
W
Update a block.
V
Verify that the device is able to read the contents of a block, but do not
transfer data.
I
Locate a block by identification. (The key portion, if present, and the data
portion of the block are read, updated, or verified.)
K
Locate a block by key. (Only the data portion of the block is read, updated,
or verified.) If you code this value, code the key_addr,keylength-value
operands.
dcb_addr—A-type address or (2-12)
The address of the data control block for the data set.
area_addr—A-type address or (2-12)
The address of an input or output area for a block of the data set.
length_value—absexp or (2-12)
The number of bytes to be transferred to or from the input or output area. If
blocks are to be located by identification and the data set contains keys, the
value must include the length of the key. The maximum number of bytes
transferred is 32 767.
key_addr—RX-type address or (2-12)
When blocks are to be located by key, the address of a virtual storage field that
contains the key of the block to be read, updated, or verified.
keylength_value—absexp or (2-12)
When blocks are to be located by key, the length of the key. The maximum
length is 255 bytes.
blkref_addr—RX-type address or (2-12)
The address of a field in virtual storage that contains the actual track address
of the track containing the block to be located. The actual address of a block is
in the form MBBCCHHR, where:
M
242
Indicates which extent entry in the data extent block is associated with the
direct access program
z/OS DFSMSdfp Advanced Services
Using XDAP
BB Must be zero
CC The cylinder address
HH The actual track address
R
The block identification. R is not used if blocks are to be located by key.
The track address of the block reference (CCHH) may contain 28-bit cylinder
numbers for devices with more than 65,520 cylinders. Showing nibbles it is in
the form of CCCCcccH, where ccc represent bits 0-11 of the 28-bit cylinder
number and CCCC represents bits 12-27 the 28-bit cylinder number. Use the
TRKADDR macro to manipulate 16-bit and 28-bit cylinder numbers correctly.
(For more detailed information, see “Converting a Relative Track Address to an
Actual Track Address” on page 232.)
sector_addr—RX-type address or (2-12)
The address of a 1-byte field containing a sector value. The sector_addr
parameter is used for rotational position sensing (RPS) devices. The parameter
is optional, but its use will improve channel performance. When the parameter
is coded, a set-sector CCW (using the sector value indicated by the data
address field) precedes the search-ID-equal command in the channel program.
The sector_addr parameter is ignored if the type parameter is coded as RK, WK,
or VK. If a sector address is specified in the execute form of the macro, then a
sector address, not necessarily the same, must be specified in the list form. The
sector address in the executable form will be used.
Exception: No validity check is made on either the address or the sector value
when the XDAP macro is issued. However, a unit check/command reject
interruption will occur during channel-program execution if the sector value is
not valid for the device or if the sector_addr operand is used when accessing a
device without RPS.
|
IOBE=N
Indicates that an I/O Block Extension control block (IOBE) is not provided to
EXCP.
|
IOBE=Y
Indicates that an IOBE is provided to EXCP; the address of the IOBE is in
register 0. Use this to identify the application that is updating the VTOC, for
the purposes of audit logging of VTOC I/O. The name of the application is in
field IOBEUSER.
|
MF=
You can use the L-form of the XDAP macro instruction for a macro expansion
consisting of a parameter list, or the E-form for a macro expansion consisting
of executable instructions.
MF=E
The first operand (ecb_symbol) is required and can be coded as a symbol or
supplied in registers 2 through 12. The type, dcb_addr, area_addr, and
length_value operands can be supplied in either the L- or E-form. The
blkref_addr operand can be supplied in the E-form or moved into the IOBSEEK
field of the IOB by your program. The sector_addr is optional; it can be coded
either in both the L- and E-form or in neither.
MF=L
The first two operands (ecb_symbol and type) are required and must be coded
Chapter 5. Using XDAP to Read and Write to Direct Access Devices
243
Using XDAP
as symbols. If you choose to code length_value or keylength_value, they must be
absolute expressions. Other operands, if coded, must be A-type addresses.
(blkref_addr is ignored if coded.)
The XDAP macro builds a channel program containing A-type addresses. These
addresses refer to storage within the L-form of the macro. If you copy the L-form
of the macro to a work area so that the program can be reentrant, the E-form of the
XDAP macro does not update the A-type addresses. This results in an invalid
channel program.
The dcb_addr, area_addr, blkref_addr, and sector_value operands can be coded as
RX-type addresses or supplied in registers 2 through 12. The length_value and
keylength_value operands can be specified as absolute expressions or decimal
integers or supplied in registers 2 through 12.
Control Blocks Used with XDAP
The control blocks generated during execution of the XDAP macro instruction
consist of the following:
Input/Output Block
The input/output block is 40 bytes in length and immediately follows the event
control block. “Control Block Fields” on page 196 contains a diagram of the IOB
(Figure 21 on page 212). You might want to examine the IOBSENS0, IOBSENS1,
and IOBCSW fields if the ECB is posted with X'41'.
Event Control Block
Refer to “Event Control Block (ECB) Fields” on page 220 for information on event
control block fields.
Direct Access Channel Program
The direct access channel program is 24 bytes in length (except when set sector is
used for RPS devices) and immediately follows the input/output block. Depending
on the type of I/O operation that is specified in the XDAP macro instruction, one
of four channel programs can be generated. The three channel command words for
each of the four possible channel programs are shown in Table 49.
Table 49. Channel Program Command Words Used by XDAP
Type of I/O Operation
Read by identification
CCW
Command Code
1
Search ID Equal
2
Transfer in Channel
Verify by identification
3
Read Key and Data
Read by key
1
Search Key Equal
2
Transfer in Channel
Verify by key
3
Read Data
Write by identification
1
Search ID Equal
2
Transfer in Channel
3
Write Key and Data
Write by key
1
Search Key Equal
2
Transfer in Channel
3
Write Data
Note: For verifying operations, the third CCW is flagged to suppress the transfer of
information to virtual storage.
244
z/OS DFSMSdfp Advanced Services
Using XDAP
When a sector address is specified with an RI, VI, or WI operation, the channel
program is 32 bytes in length. Each of the channel programs in Table 49 on page
244 would be preceded by a set sector command.
RPS Device Sector Numbers
To obtain the performance improvement given by rotational position sensing,
specify the sector_addr parameter in the XDAP macro. For programs that can be
used with both RPS and non-RPS devices, test the UCBRPS bit to determine
whether the device has rotational position sensing. If the UCBRPS bit is off, do not
issue a channel program with a set sector command to the device.
The sector_addr parameter on the XDAP macro specifies the address of a 1-byte
field in virtual storage. Store the sector number of the block to be located in this
field. You can obtain the sector number of the block by using a resident system
conversion routine. See “Obtaining the Sector Number of a Block on an RPS
Device” on page 236
Chapter 5. Using XDAP to Read and Write to Direct Access Devices
245
246
z/OS DFSMSdfp Advanced Services
Chapter 6. Using Password Protected Data Sets
This information covers password protection for data sets. The use of password
protection is not recommended, but is provided for compatibility with other IBM
operating systems. You should use RACF protection (using SAF) instead.
The password protection described does not apply to data sets and catalogs
managed by the Storage Management Subsystem (SMS) or to VSAM data sets.
SMS ignores passwords. In addition, the PROTECT macro and SVC does not
support a volume on a unit defined as dynamic.
If a SAF (system authorization facility)-compliant security product is active and
provides protection for the data set, then the system bypasses password protection
for that data set. Additionally, the system always bypasses password protection for
VSAM and for SMS-managed data sets. The system provides SMS-managed data
set and catalog protection through the SAF interface. For more SAF information,
see “System Authorization Facility” in z/OS MVS Programming: Assembler Services
Guide, and z/OS MVS Programming: Assembler Services Reference ABE-HSP.
For information about VSAM data set protection, see z/OS DFSMS Using Data Sets
and z/OS DFSMS Access Method Services Commands.
The following are some reasons to use SAF instead of password protection:
v If you give a password to someone, you have no control over to whom they
choose to give it.
v Data sets tend to have various passwords, making you write them down. This is
less secure than if you can memorize one SAF password.
v Batch job access or interactive non-TSO access requires that a system operator
supply a password. Your communication to the operator is likely to be insecure.
That operator might not be present when your job runs. The operator might
have to give each data set's password to other operators.
v The program is halted while each password is supplied. This is contrary to the
increased automation of modern systems.
v There is no way to know who has used a particular password.
v It is human nature not to change passwords, especially if there are many. As
time passes, there is a greater danger of them being exposed.
v If more than a small number of data sets have passwords, then the time for the
system to find the PASSWORD data set entry increases greatly. With RACF, the
increase is much less. With a RACF generic profile there is no increase in search
time when a new data set uses the same profile.
v With DASD shared between systems, the password definitions on each system
are independent. They can get out of synchronization.
v The PASSWORD data set entry contains the data set name but not the volume
serial number. If you create a data set before defining a password, you could
find that someone has already defined a password for that data set name. Your
data set will require the existing password just to scratch or rename it.
v Password protection is not supported on system-managed volumes or on
dynamic devices.
© Copyright IBM Corp. 1979, 2017
247
Password Protection
To use the data set protection feature of the operating system, create and maintain
a PASSWORD data set consisting of records that associate the names of the
protected data sets with the passwords assigned to each data set. The ways to
maintain the PASSWORD data set consist of:
v Writing your own routines
v Using the PROTECT macro instruction
v Using the utility control statements of the IEHPROGM utility program
v If you have TSO, using the TSO PROTECT command.
This information discusses only the first two methods. The last two methods are
discussed in the publications shown in the following list.
Before using this information, you should be familiar with the contents of the
following publications:
v z/OS DFSMS Using Data Sets describes the data set protection feature.
v The following publications describe the operator messages and replies associated
with the data set protection feature:
– z/OS MVS System Messages, Vol 1 (ABA-AOM)
– z/OS MVS System Messages, Vol 2 (ARC-ASA)
– z/OS MVS System Messages, Vol 3 (ASB-BPX)
– z/OS MVS System Messages, Vol 4 (CBD-DMO)
– z/OS MVS System Messages, Vol 5 (EDG-GFS)
– z/OS MVS System Messages, Vol 6 (GOS-IEA)
– z/OS MVS System Messages, Vol 7 (IEB-IEE)
– z/OS MVS System Messages, Vol 8 (IEF-IGD)
– z/OS MVS System Messages, Vol 9 (IGF-IWM)
– z/OS MVS System Messages, Vol 10 (IXC-IZP)
v z/OS MVS JCL Reference describes the data definition (DD) statement parameter
used to indicate that a data set is to be password protected. It is a subparameter
of the LABEL parameter.
v z/OS DFSMSdfp Utilities describes how to maintain the PASSWORD data set
using the utility control statements of the IEHPROGM utility program.
v z/OS TSO/E Command Reference describes how to use the TSO PROTECT
command.
Providing Data Set Security
In addition to the usual label protection that prevents the opening of a data set
without the correct data set name, the operating system provides data set security
options that prevent unauthorized access to confidential data. Password protection
prevents access to data sets until a correct password is entered by the system
operator, or, for TSO, by a remote terminal operator.
The following types of access are allowed to password-protected data sets:
v PWREAD/PWWRITE—A password is required for read or write access.
v PWREAD/NOWRITE—A password is required for read access. Writing is not
allowed.
v NOPWREAD/PWWRITE—Reading is allowed without a password. A password
is required to write.
248
z/OS DFSMSdfp Advanced Services
Password Protection
To prepare for use of the data set protection feature, place a sequential data set
named PASSWORD on the system residence volume. This data set must contain at
least one record for each data set placed under protection. Each record consists of a
data set name, a password for that data set, a counter field, a protection-mode
indicator, and a field for recording any information you wish to log. On the system
residence volume, these records are formatted as a key area (data set name and
password) and a data area (counter field, protection-mode indicator, and logging
field). The data set is searched on the key area.
v The area allocated to the data set should not have been previously used for a
PASSWORD data set, as this might cause unpredictable results when adding
records to the data set.
v If the system residence volume does not contain a PASSWORD data set, the
system allows no access to password protected data sets. Do not rely on this for
protection because anyone who creates a data set named PASSWORD on the
system residence volume can define a password for any data set.
v Data sets on magnetic tape are protected only when standard labels are used.
You can write routines to create and maintain the PASSWORD data set. For
information on using the PROTECT macro instruction to maintain the PASSWORD
data set, see “Maintaining the PASSWORD Data Set Using PROTECT” on page
252. Using the IEHPROGM utility program to maintain the PASSWORD data set is
described in z/OS DFSMSdfp Utilities. These routines can be placed in your own
library or in the system's library (SYS1.LINKLIB). You can use a data management
access method to read from and write to the PASSWORD data set.
Password-protected data sets can only be accessed by programs supplying the
correct password. Upon receiving a request to open a protected data set, the
operating system checks whether the data set has already been opened for this job
step and if the access mode is compatible with the previously used protection
mode. If neither condition is satisfied, a message requesting the password is sent to
the operator console. If the program attempting to open the data is running under
TSO in the foreground, the message is sent to the TSO terminal operator.
PASSWORD Data Set Characteristics
The PASSWORD data set and your operating system must reside on the same
volume. That volume is the IPL volume. It is called the system residence volume.
The space allocated to the PASSWORD data set must be contiguous. The amount
of space allocated depends on the number of data sets you want to protect. Each
entry in the PASSWORD data set requires 132 bytes of space. The organization of
the PASSWORD data set is physical-sequential; the record format is unblocked,
fixed-length records (RECFM=F). Each record that forms the data area is 80 bytes
long (LRECL=80,BLKSIZE=80) and is preceded by a 52-byte key (KEYLEN=52).
The key area contains the fully-qualified data set name (up to 44 bytes long) and a
password, one to eight alphanumeric characters in length, left justified with blanks
added to fill the areas.
Restriction: The PASSWORD data set cannot be large format or extended format.
Attention: Data sets on magnetic tape complying with the specifications of the
International Organization for Standardization (ISO) 1001-1979 or the American
National Standards Institute (ANSI) X3.27-1978 do not include generation and
version numbers as part of generation data set names. If included in the
PASSWORD data set, generation and version numbers for these data sets are
ignored.
Chapter 6. Using Password Protected Data Sets
249
Password Protection
You should protect the PASSWORD data set by creating a password record for it
when your program initially builds the data set or you should use RACF to control
access. Thereafter, the PASSWORD data set cannot be opened (except by the
operating system routines that scan the data set) without entering the password. If
a problem occurs on a password-protected system data set, maintenance personnel
require the password to access the data set and resolve the problem.
Creating Protected Data Sets
The data definition (DD) statement parameter LABEL= can be used to indicate that
a data set is to be password protected. For data sets on DASD, an alternative
method for a previously allocated data set is to use the PROTECT macro
instruction, the IEHPROGM utility, or the TSO PROTECT command. You can
create a data set and set the protection indicator in its label without entering a
password record for it in the PASSWORD data set. In this case the system allows
no access to the data set.
Operating procedures at your installation must ensure that password records for
all data sets currently password-protected are entered in the PASSWORD data set.
For installations where independent computing systems share common DASD
resources, PASSWORD data sets on all systems must contain the appropriate
password records for any protected data set on shared DASD.
Under certain circumstances, the order in which data sets are allocated and
deallocated from multiple systems on shared DASD could result in loss of
protection or corruption of data. For example, if a set is allocated and opened by a
user on system A and then scratched by a different user on system B, the first user
has a window to the unallocated (free) area. If any data set, protected or
unprotected, is allocated in that space by a user on either system while the
window is open, the new data set has no protection from the user with the
window. The most common solution to this problem is to use GRS (see z/OS MVS
Planning: Global Resource Serialization).
While the allocation disposition is still NEW, a password-protected data set can be
used without supplying a password. Once the data set is deallocated, a subsequent
attempt to open it results in termination of the program unless the password
record is available and the correct password is supplied. If the protection mode is
NOPWREAD and the request is to open the data set for input or read backward,
no password is required.
Tape Volumes Containing Multiple Password-protected Data Sets
To password protect a data set on a tape volume containing other data sets,
password protect all the data sets on the volume. (Standard labels—SL, SUL, AL,
or AUL—are required. For definitions of these label types and the protection-mode
indicators that can be used, see z/OS DFSMS Using Magnetic Tapes.)
If you issue an OPEN macro instruction to create a data set following an existing
password-protected data set, the password of the existing data set will be verified
during open processing for the new data set. The password supplied must be
associated with a PWWRITE protection-mode indicator.
Protection Feature Operating Characteristics
The topics that follow discuss the protection feature operating characteristics:
v “Terminating the Protection Feature Process” on page 251
v “Password Protection When Switching Volumes” on page 251
250
z/OS DFSMSdfp Advanced Services
Password Protection
v “Password Protection When Concatenating Data Sets”
v “Maintaining the Counter for Password Protection”
Terminating the Protection Feature Process
Processing is terminated if:
v The operator cannot supply the correct password for the protected data set
within two attempts.
v A password record does not exist in the PASSWORD data set for the protected
data set being opened.
v The protection-mode indicator in the password record and the method of I/O
processing specified in the open routine do not agree; for example, OUTPUT
specified against a read-only protection-mode indicator.
v There is a mismatch in data set names for a data set involved in a volume
switching operation. This is discussed in the next paragraph.
Password Protection When Switching Volumes
Password protection is retained when volumes of a multivolume data set are
switched. If the following conditions are met, the system accepts a newly-mounted
tape volume to be used for input or a newly-mounted direct access volume:
v The data set names are the same in the password record for the data set and the
job file control block (JFCB). (This ensures that the problem program has not
changed the data set name in the JFCB since the data set was opened.)
v The protection-mode indicator in the password record is compatible with the
processing mode, and a valid password has been supplied.
The system accepts a newly-mounted tape volume for output under any of the
following conditions:
v The security indicator in the HDR1 label indicates password protection; the data
set name in the password record is the same as the data set name in the JFCB;
and the protection-mode indicator is compatible with the processing mode. (If
the data set name in the JFCB has been changed, a new password is requested
from the operator.)
v The security indicator in the HDR1 label does not indicate password protection.
(A new label is written with the security indicator indicating password
protection.)
v Only a volume label exists. (An HDR1 label is written with the security indicator
indicating password protection.)
Password Protection When Concatenating Data Sets
A password is requested for every protected data set that is involved in a
concatenation of data sets.
Password Protection SCRATCH and RENAME Functions
To delete or rename a protected data set, the job step making the request must be
able to supply the password. The system checks to see if the job step is currently
authorized to write to the data set. If the job step is not, a password must be
provided that is associated with a WRITE protection-mode indicator.
Maintaining the Counter for Password Protection
The operating system increments the counter in the password record on each
usage, but no overflow indication will be given (overflow after 65535 openings).
Provide a counter maintenance routine to check and, if necessary, reset this
counter.
Chapter 6. Using Password Protected Data Sets
251
Password Protection
Maintaining the PASSWORD Data Set Using PROTECT
To use the PROTECT macro instruction, your PASSWORD data set must be on the
system residence volume. The PROTECT macro can be used to:
v
v
v
v
Add an entry to the PASSWORD data set
Replace an entry in the PASSWORD data set
Delete an entry from the PASSWORD data set
Obtain a list of information about an entry in the PASSWORD data set; this list
contains the security counter, access type, and the 77 bytes of security
information in the data area of the entry.
The PROTECT macro also updates the DSCB of a protected direct access data set
to reflect its protection status; this feature eliminates the need for job control
language when you protect a data set.
PROTECT does not support data sets on dynamic devices.
Record Format
When using the PROTECT macro, the PASSWORD data set must contain at least
one record for each protected data set. The password (the last eight bytes of the
key area), that you assign when you protect the data set for the first time, is called
the control password.
You can create as many secondary records for the same protected data set as
needed. Passwords assigned to these additional records are called secondary
passwords. This feature allows several users to access the same protected data set
while you control the way it is used. For example, one user could be given
read/write authorization while another user is assigned a password that allows
only read access.
Protection-Mode Indicator
You can set the protection-mode indicator (third data byte) in the password record
to one of the following values:
v X'00' to indicate that the password is a secondary password and the protected
data set is to be read only (PWREAD).
v X'80' to indicate that the password is the control password and the protected
data set is to be read only (PWREAD).
v X'01' to indicate that the password is a secondary password and the protected
data set is to be read and written (PWREAD/PWWRITE).
v X'81' to indicate that the password is the control password and the protected
data set is to be read and written (PWREAD/PWWRITE).
The checking sequence for the protection status of a data set produces the
following defaults:
If control password is:
252
1.
PWREAD/PWWRITE or
PWREAD/NOWRITE
2.
NOPWREAD/PWWRITE
z/OS DFSMSdfp Advanced Services
Secondary password must be:
PWREAD/PWWRITE or
PWREAD/NOWRITE
NOPWREAD/PWWRITE
Password Protection
If the control password is set to either of the settings in item 1 and you try to set
the secondary password to NOPWREAD/PWWRITE, the secondary password
reverts to PWREAD/PWWRITE.
If the control password is changed from either of the settings in item 1 to the
setting in item 2, the secondary password is reset to NOPWREAD/PWWRITE.
If the control password is changed from the setting in item 2 to a setting in item 1,
the secondary password is set to PWREAD/PWWRITE.
Because the DSCB of the protected data set is updated only when the control
password is changed, protection attributes for secondary passwords might conflict
with the protection attributes of the control password.
PROTECT Macro Specification
The format of the PROTECT macro is:
►►
PROTECT
parameter_list_address
►◄
label
parameter list address—A-type address, (2-12), or (1)
Indicates the location of the parameter list. The parameter list must be created
before the PROTECT macro is issued. The address of the parameter list can be
passed in register 1, in any of registers 2 through 12, or as an A-type address.
The first byte of the parameter list must be used to identify the function (add,
replace, delete, or list). See Figure 27 on page 254 through Figure 30 on page
257 for the parameter lists and codes used to identify the functions.
Requirement: The parameter lists and the areas addressed by the list must reside
below 16 MB virtual. PROTECT will fail the request if the actual UCB of the
system residence volume is above 16 MB or if PROTECT tries to update the data
set's DSCB and one of its UCBs is above the 16 MB line.
Chapter 6. Using Password Protected Data Sets
253
Password Protection
PROTECT Macro Parameter Lists
ADD Function:
┌─────────────────────────────┬────────────────────────────────────────¿
³ 0
X’01’
³ 13 Control password pointer
³
├─────────────────────────────┼────────────────────────────────────────u
³ 1
00 00 00
³ 16 Number of volumes
³
├─────────────────────────────┼────────────────────────────────────────u
³ 4
Data set name length
³ 17 Volume list pointer
³
├─────────────────────────────┼────────────────────────────────────────u
³ 5
Data set name pointer ³ 20 Protection code
³
├─────────────────────────────┼────────────────────────────────────────u
³ 8
00
³ 21 New password pointer
³
├─────────────────────────────┼────────────────────────────────────────u
³ 9
00 00 00
³ 24 String length
³
├─────────────────────────────┼────────────────────────────────────────u
³ 10 00
³ 25 String pointer
³
└─────────────────────────────┴────────────────────────────────────────Ù
Figure 27. Parameter List for ADD Function
0 X'01'
Entry code indicating ADD function.
4 Data set name length.
5 Data set name pointer.
13 Control password pointer.
The control password is assigned when the data set is placed under protection
for the first time. The pointer can be 3 bytes of binary zeros if the new
password is the control password.
16 Number of volumes.
If the data set is not cataloged, to have it flagged as protected, specify the
number of volumes in this field. A zero requests that the catalog information
be used.
17 Volume list pointer.
If the data set is not cataloged, to have it flagged as protected, provide the
address of a list of volume serial numbers in this field. Zeros request that the
catalog information be used.
20 Protection code.
A 1-byte number indicating the type of protection: X'00' indicates default
protection (for the ADD function; the default protection is the type of
protection specified in the control password record of the data set); X'01'
indicates that the data set is to be read and written; X'02' indicates that the
data set is read only; and X'03' indicates that the data set can be read without a
password, but a password is needed for write access. The PROTECT macro
uses the protection code value, specified in the parameter list, to set the
protection-mode indicator in the password record.
21 New password pointer.
If the data set is being placed under protection for the first time, the new
password becomes the control password. If you are adding a secondary entry,
the new password is different from the control password.
254
z/OS DFSMSdfp Advanced Services
Password Protection
24 String length.
The length of the character string (maximum 77 bytes) to be placed in the
optional information field of the password record. If you do not want to add
information, set this field to zero.
25 String pointer.
The address of the character string placed in the optional information field. If
you do not want to add information, set this field to zero.
REPLACE Function:
┌─────────────────────────────┬────────────────────────────────────────¿
³ 0
X’02’
³ 13 Control password pointer
³
├─────────────────────────────┼────────────────────────────────────────u
³ 1
00 00 00
³ 16 Number of volumes
³
├─────────────────────────────┼────────────────────────────────────────u
³ 4
Data set name length
³ 17 Volume list pointer
³
├─────────────────────────────┼────────────────────────────────────────u
³ 5
Data set name pointer ³ 20 Protection code
³
├─────────────────────────────┼────────────────────────────────────────u
³ 8
00
³ 21 New password pointer
³
├─────────────────────────────┼────────────────────────────────────────u
³ 9
Current password pointer³ 24 String length
³
├─────────────────────────────┼────────────────────────────────────────u
³ 12 00
³ 25 String pointer
³
└─────────────────────────────┴────────────────────────────────────────Ù
Figure 28. Parameter List for REPLACE Function
0 X'02'.
Entry code indicating REPLACE function.
4 Data set name length.
5 Data set name pointer.
9 Pointer to current password.
The address of the password that is going to be replaced.
13 Control password pointer.
The address of the password assigned to the data set when it was first placed
under protection. The pointer can be set to 3 bytes of binary zeros if the
current password is the control password.
16 Number of volumes.
If the data set is not cataloged, to have it flagged as protected, specify the
number of volumes in this field. A zero requests that the catalog information
be used.
17 Volume list pointer.
If the data set is not cataloged, to have it flagged as protected, provide the
address of a list of volume serial numbers in this field. If this field is zero, the
catalog information is used.
20 Protection code.
A 1-byte number indicating the type of protection: X'00' indicates default
protection (for the REPLACE function the default is the type of protection
specified in the control password record of the data set); X'01' indicates that the
Chapter 6. Using Password Protected Data Sets
255
Password Protection
data set is to be read and written; X'02' indicates that the data set is to be read
only; and X'03' indicates that the data set can be read without a password, but
a password is needed for write access.
21 New password pointer.
The address of the password to be used to replace the current password.
24 String length.
The length of the character string (maximum 77 bytes) to be placed in the
optional information field of the password record. If you do not want to add
information, set this field to zero.
25 String pointer.
The address of the character string to be placed in the optional information
field. If you do not want to add information, set this field to zero.
DELETE Function:
┌─────────────────────────────┬────────────────────────────────────────¿
³ 0
X’03’
³ 9 Current password pointer
³
├─────────────────────────────┼────────────────────────────────────────u
³ 1
00 00 00
³ 12 00
³
├─────────────────────────────┼────────────────────────────────────────u
³ 4
Data set name length
³ 13 Control password pointer
³
├─────────────────────────────┼────────────────────────────────────────u
³ 5
Data set name pointer ³ 16 Number of volumes
³
├─────────────────────────────┼────────────────────────────────────────u
³ 8
00
³ 17 Volume list pointer
³
└─────────────────────────────┴────────────────────────────────────────Ù
Figure 29. Parameter List for DELETE Function
0 X'03'.
Entry code indicating DELETE function.
4 Data set name length.
5 Data set name pointer.
9 Current password pointer.
The address of the password to be deleted. You can delete either a control or
secondary entry.
13 Control password pointer.
The address of the password assigned to the data set when it was placed
under protection for the first time. The pointer can be 2 bytes of binary zeros if
the current password is also the control password.
16 Number of volumes.
If the data set is not cataloged, to have it flagged as protected, specify the
number of volumes in this field. A zero requests that the catalog information
be used.
17 Volume list pointer.
If the data set is not cataloged, to have it flagged as protected, provide the
address of a list of volume serial numbers in this field. Zeros request that the
catalog information will be used.
256
z/OS DFSMSdfp Advanced Services
Password Protection
LIST Function:
┌─────────────────────────────┬────────────────────────────────────────¿
³ 0
X’04’
³ 5 Data set name pointer
³
├─────────────────────────────┼────────────────────────────────────────u
³ 1
80─byte buffer pointer ³ 8 00
³
├─────────────────────────────┼────────────────────────────────────────u
³ 4
Data set name length
³ 9 Current password pointer
³
└─────────────────────────────┴────────────────────────────────────────Ù
Figure 30. Parameter List for LIST Function
0 X'04'.
Entry code indicating LIST function.
1 80-byte buffer pointer.
The address of a buffer to receive the information returned to your program by
the macro instruction.
4 Data set name length.
5 Data set name pointer.
9 Current password pointer.
The address of the password of the record to be listed.
Return Codes from the PROTECT Macro
When the PROTECT macro finishes processing, register 15 contains one of the
following return codes:
Table 50. PROTECT Return Codes
Return Code
Description
0 (X'00')
4 (X'04')
Updating of the PASSWORD data set completed successfully.
The password of the data set name was already in the PASSWORD
data set.
The password of the data set name was not in the PASSWORD data
set.
A control password is required or the one supplied is incorrect.
The supplied parameter list was incomplete or incorrect.
There was an I/O error in the PASSWORD data set or the system
residence volume (which contains the PASSWORD data set), has an
actual UCB that resides above the 16 MB line.
The PASSWORD data set was full.
The validity check of the buffer address failed.
The LOCATE macro failed. LOCATE's return code is in register 1,
and the number of indexes searched is in register 0.
The OBTAIN macro for the user data set failed. OBTAIN's return
code is in register 1. The user data set resides on a volume that has
an actual UCB that resides above the 16 MB line. Register 1 contains
a 4, which simulates an OBTAIN return code.
The DSCB could not be updated.
The PASSWORD data set does not exist.
Tape data set cannot be protected.
Data set in use.
The data set uses the virtual storage access method (VSAM).
8 (X'08')
12 (X'0C')
16 (X'10')
20 (X'14')
24 (X'18') 1
28 (X'1C')
32 (X'20') 2
36 (X'24')
40
44
48
52
56
2
(X'28') 2
(X'2C')
(X'30') 2
(X'32') 2
(X'38') 2
Chapter 6. Using Password Protected Data Sets
257
Password Protection
Table 50. PROTECT Return Codes (continued)
Return Code
Description
60 (X'3C')
The data set is cataloged as being on more than 20 volumes. The
DSCBs on the first 20 volumes have been updated. PROTECT does
not support updating the rest.
Note:
1. A message is written to the console indicating that the PASSWORD data set is
full.
2. The PASSWORD data set has been updated, but the DSCB has not been flagged
to indicate the protected status of the data set.
258
z/OS DFSMSdfp Advanced Services
Chapter 7. Using System Macro Instructions
This information covers system macro instructions. The macros are grouped
functionally where appropriate and perform the stated functions.
v Ensure data security (DEBCHK macro)
v Obtain device characteristics from control blocks and system tables (DEVTYPE
macro)
v Modify the JFCB (RDJFCB and OPEN TYPE=J macros)
v Manipulate I/O activity queues (PURGE and RESTORE macros)
v Perform track capacity calculations (TRKCALC macro).
v Perform calculations and conversions with 28-bit cylinder addresses (TRKADDR
macro).
Some functions of these macros tend to depend on the internal logic of the system.
Before reading this information, you should be familiar with the publications High
Level Assembler/MVS & VM & VSE Language Reference They contain the information
necessary to code programs in the assembler language.
Ensuring Data Security by Validating the Data Extent Block (DEBCHK
macro)
Protecting one user's data from inadvertent or malicious access by an unauthorized
user depends on protection of the data extent block (DEB). The DEB is a critical
control block because it contains information about the device a data set is
mounted on, and describes the location of data sets on direct access device storage
volumes.
To ensure that only a valid system-provided DEB (normally built by open) is
passed to data management functions, the DEBCHK verify function is used. OPEN
places the address of DEBs it creates to a DEB table, which is used by the verify
function. If you code a routine that builds a DEB, add the address of the DEB you
built to the DEB table. If you code a routine that depends on the validity of a DEB
that is passed to your routine, verify that the DEB passed to your routine has a
valid entry in the DEB table and points to your DCB or access method control
block (ACB). Use the TYPE=ADD and the TYPE=VERIFY operands of the macro,
respectively.
To prevent an asynchronous routine from changing or deleting, or assigning a new
DEB to a DCB, hold the local lock. In this case, use the branch entry to the
DEBCHK verify routine and use the DEB address returned in register 1, not the
DEB address in the DCB. The DCB will remain valid as long as your program
holds the local lock or prevents untrustworthy programs from running.
Your program must be executing in 24-bit or 31-bit addressing mode when you call
the DEBCHK macro.
The DEB fields used for EXCP and EXCPVR are illustrated in Appendix A,
“Control Blocks,” on page 443 (all the DEB fields are illustrated in z/OS DFSMSdfp
Diagnosis).
© Copyright IBM Corp. 1979, 2017
259
System Macros
DEBCHK Macro Specification
The format of the DEBCHK macro is:
►►
DEBCHK cbaddr
►
label
,TYPE=
VERIFY
ADD
DELETE
PURGE
PURGE,PURGE=FORCE
►
►
,AM=
amtype
(amaddr)
((amreg))
,BRANCH=
NO
YES
,TCBADDR=address
►
►◄
,KEYADDR=address
,KEYREG=reg
,SAVREG=reg
,MF=L
cbaddr
Control block address.
for BRANCH=NO
RX-type address, (2-12), or (1)
A control block address passed to the DEBCHK routine. This operand is
ignored if MF=L is coded. For verify, add, and delete requests, cbaddr is the
address of a DCB or ACB that points to the DEB whose address is either
verified to be in the DEB table, added to the DEB table, or deleted from the
DEB table. For the purge function, cbaddr is the address of the DEB whose
pointer is to be purged from the table: No reference is made to the DCB or
ACB.
Recommendation: A spooled DCB's DEB does not point back to the DCB, but
to the spooled ACB; in this case, the DEBCHK should be issued against the
ACB.
for BRANCH=YES
The A-type address of a 4-byte field, or a register (3-9) or (12), that points
to the DCB or ACB containing the DEB to be verified.
TYPE=VERIFY or ADD or DELETE or PURGE or PURGE,PURGE=FORCE
Indicates the function to be performed. If MF=L is coded, TYPE is ignored. The
functions are:
VERIFY
This function is assumed if the TYPE operand is not coded. The control
program checks the DEB table to determine whether the DEB pointer is in
the table at the location indicated by the DEBTBLOF field of the DEB. The
DEB is also checked to verify that DEBDCBAD points to the DCB (or ACB)
passed to DEBCHK. The DEBAMTYP field in the DEB is compared to the
AM operand value, if given. The two must be equal. TYPE=VERIFY can be
issued in either supervisor or problem state.
ADD
The DEB and the DCB (or ACB) must point to each other before the DEB
address can be added to the DEB table. Before the DEB pointer can be
260
z/OS DFSMSdfp Advanced Services
System Macros
added to the table, the DEB itself must be queued on the current TCB DEB
chain (the TCBDEB field contains the address of the first DEB in the chain).
DEBCHK adds the DEB address to the DEB table at some offset into the
table. DEBCHK places a value in the DEBTBLOF field of the DEB and
inserts the access method type into the DEBAMTYP field of the DEB.
DEBCHK places a zero in the DEBAMTYP field if the AM operand is not
coded. TYPE=ADD can be issued only in supervisor state.
DELETE
The DEB and the DCB (or ACB) must point to each other before the DEB
address can be deleted from the DEB table. TYPE=DELETE can be issued
only in supervisor state.
PURGE
DEBCHK removes the DEB pointer from the DEB table without checking
the DCB (or ACB). TYPE=PURGE can be issued only in supervisor state.
PURGE,PURGE=FORCE
DEBCHK removes the DEB pointer from the DEB table without checking
the DCB (or ACB). The caller must be in system key, supervisor state, hold
the local lock, and the passed DEB pointer must exist in the DEB table but
not represent a valid DEB.
AM Specifies an access method value. Each value corresponds to a particular access
method type (note that BPAM and SAM have the same values):
Value
(X'00')
(X'01')
(X'02')
(X'04')
(X'08')
(X'10')
(X'20')
(X'20')
(X'40')
(X'81')
(X'84')
Type
NONE
VSAM
EXCP
Not supported
GAM
TAM
BPAM
SAM
BDAM
SUBSYS
Not supported
The operand can be coded in one of the following three ways, only the first of
which is valid for the list form (MF=L) of the instruction.
amtype
Refers to the access method: BDAM, SAM, BPAM, TAM (which refers to
BTAM only), GAM, EXCP, or VSAM. SUBSYS identifies a subsystem of the
operating system, such as a job entry subsystem. NONE indicates that no
access method or subsystem is specified.
(amaddr)
The RS-type address of the access method value. This format cannot be
coded when MF=L is used.
((amreg))
One of the general registers 1 through 14 that contains the access method
value in its low-order byte (bit positions 24 through 31). The high-order
bytes are not inspected. This form cannot be used when MF=L is coded.
Chapter 7. Using System Macro Instructions
261
System Macros
The use of amaddr and amreg should be restricted to those cases where the
access method value has been generated previously by the MF=L form of
DEBCHK. If MF=L is not coded, the significance of the AM operand depends
upon the TYPE.
If TYPE is ADD and AM is specified, the access method value is inserted in the
DEBAMTYP field of the DEB, and all subsequent DEBCHK macros referring to
this DEB must either specify the same AM or omit the operand. When the AM
operand is omitted for TYPE=ADD, a null value (0) is placed in the DEB and
all subsequent DEBCHK macros must omit the AM operand.
If AM is specified when the TYPE is PURGE, DELETE, or VERIFY, the access
method value is compared to the value in the DEBAMTYP field of the DEB. If
AM is omitted, no comparison is made.
BRANCH=NO or YES
Specifies whether you want to use the branch entry to the DEBCHK verify
routines.
NO
SAVREG
TCBADDR
KEYADDR
KEYREG
Specifies branch entry is not to be used. The program ignores operands
SAVREG, TCBADDR, KEYADDR, and KEYREG. Your program must be
running in TCB mode.
YES
Specifies the branch entry is to be used. TYPE=VERIFY must be implicitly
or explicitly specified. The operands TCBADDR and KEYADDR/KEYREG
are required. AM and MF are ignored. Notes for BRANCH=YES:
v Your program can run in TCB or SRB mode.
v Registers 1, 2, 10, 11, 14, and 15 must not be used for SAVREG=.
v Registers 1, 2, 10, 11, 14, 15, and the register specified for SAVREG=
must not be used for cbaddr, TCBADDR=, or KEYADDR=/KEYREG=.
v The contents of registers 10, 11, and 14 are unpredictable on completion.
Also, if you do not specify SAVREG=, the contents of register 2 are
unpredictable.
v At completion, register 1 contains the address of the DEB, and register
15 contains either 0, 4, or 16 (see “Return Codes from DEBCHK” on
page 263 for codes and their meanings).
v Can be specified when operating in 24-bit or 31-bit addressing mode.
TCBADDR=address—RX-type address, (3-9), or (12)
Specifies the word or register containing the address of the TCB to be used by
the DEBCHK verify routine. Use this operand only with BRANCH=YES.
KEYADDR=address—RX-type address
Specifies the location, or a register that points to the location, of a byte
containing the key to be used when accessing the DCB (or ACB). The
protection key is in bits 0 to 3. Use this operand only with BRANCH=YES.
KEYREG=reg
Specifies the register containing the key value in bit positions 24-27 to be used
when accessing the DCB(or ACB). Use this operand only with BRANCH=YES.
262
z/OS DFSMSdfp Advanced Services
System Macros
SAVREG=reg
Specifies the register in which register 2 is to be saved. Use this operand only
with BRANCH=YES.
MF=L
Indicates the list form of the DEBCHK macro instruction. When MF=L is
coded, a parameter list is built, consisting of the access method value that
corresponds to the AM keyword. This value can be referred to by name in
another DEBCHK macro by coding AM=(amaddr), or it can be inserted into the
low-order byte of a register before issuing another DEBCHK macro by coding
AM=((amreg)).
Return Codes from DEBCHK
Register 15 contains one of the following codes:
Return Code
Meaning
0 (X'00')
The requested function completed successfully and register 1
contains the address of the DEB.
Either (a) the DEB table associated with the job step does not
exist; or (b) the DEB field that is an index into the DEB table
contains an invalid value; or (c) the control block address is not
the same as the content of the DEB table entry.
An invalid TYPE was specified. (The DEBCHK routine was
entered by a branch, not by the macro.)
Your program was not authorized and TYPE was not VERIFY.
DEBDCBAD did not contain the address of the DCB (or ACB) that
was passed to the DEBCHK routine.
The AM value does not equal the value in the DEBAMTYP field.
The DEB is not on the DEB chain and TYPE=ADD was specified.
TYPE=ADD was specified for a DEB that was already entered in
the DEB table.
The DEB table exceeded the maximum size and TYPE=ADD.
TYPE=PURGE,PURGE=FORCE was specified but one or more of
the required conditions was not satisfied. The caller must be in
system key, supervisor state, hold the local lock, and the passed
DEB pointer must exist in the DEB table but not represent a valid
DEB.
4 (X'04')
8 (X'08')
12 (X'0C')
16 (X'10')
20 (X'14')
24 (X'18')
28 (X'1C')
32 (X'20')
36 (X'24')
Obtaining I/O Device Characteristics (DEVTYPE macro)
Use the DEVTYPE macro instruction to request information relating to the
characteristics of an I/O device and to cause this information to be placed into a
specified area. (The results of a DEVTYPE macro instruction executed before a
checkpoint is taken should not be considered valid after a checkpoint/restart
occurs.) The IHADVA macro maps the data returned by the DEVTYPE macro - see
“IHADVA Mapping macro” on page 281.
The topics that follow discuss the DEVTYPE macro, device characteristics, and the
output for specific devices.
Your program can issue the DEVTYPE macro while executing in 24- or 31-bit
mode. If your program is executing in 31-bit mode, the parameter list, information
list, and the UCB address list can reside above the 16 MB line.
Table 57 on page 277 shows the output for each device type that results from
issuing the DEVTYPE macro without the INFOLIST parameter.
Chapter 7. Using System Macro Instructions
263
System Macros
For all currently supported devices, DEVTYPE does not return enough information
to perform space calculations. TRKCALC should be used to perform space
calculations. For information on using the TRKCALC macro, see “Performing Track
Calculations (TRKCALC macro)” on page 307.
DEVTYPE Macro Specification
There are four forms of DEVTYPE macro invocation covered here. They are the
standard form, execute form, list form, and INFO form.
Restrictions:
v If you do not code the BELOW or ANY value for the UCBLIST parameter, then
you can assemble and run DEVTYPE as described in this document on any
release of DFSMS.
v If you code the BELOW or ANY value for the UCBLIST parameter, then the
program cannot be assembled on MVS/DFP™ Version 3 but the system will
ignore the BELOW or ANY value if you assemble it on DFSMS.
v If you code the INFOLIST or INFO parameter, then the macro cannot be
assembled or run on MVS/DFP Version 3.
v If you omit INFOLIST, INFO, BELOW and ANY and the PLISTVER parameter,
then you can assemble the program on DFSMS but it will not run on MVS/DFP
Version 3. If you code PLISTVER=0, then you can assemble the program on
DFSMS but not on MVS/DFP and you can run the program on either level of
the system. During assembly your program can choose which parameters to
code by using the technique described in “Determining DFARELS During
Assembler Macro Phase” on page 323.
There are two types of call to the standard form of the DEVTYPE macro.
v The minimum type call refers to the DD statement for the device. It has no list
or execute forms.
v The UCBLIST/INFOLIST type call requires you to specify either the UCBLIST or
INFOLIST parameter or both.
The format of the different types of call to the standard form of DEVTYPE macro
follow. The parameter descriptions follow the formats.
Minimum Type Call
The minimum type of call refers to the DD statement for the device. For this type
call, as the parameters are passed in general registers no list or execute form exists.
It returns the device information to the area you specify.
The format of the minimum type call of the DEVTYPE macro is:
►►
DEVTYPE ddloc ,area_addrx
label
►◄
,DEVTAB
,RPS
UCBLIST or INFOLIST Type of Call
The UCBLIST or INFOLIST type call requires you to specify either the UCBLIST or
INFOLIST parameter or both.
264
z/OS DFSMSdfp Advanced Services
System Macros
The format of the UCBLIST or INFOLIST type call is:
►►
DEVTYPE
ddloc
►
label
,BELOW
UCBLIST=(ucbl_addr,ucbl_num
)
,ANY
► ,(area_addr,area_size)
►◄
INFOLIST=codel_addr
,PLISTVER=
MAX
0
1
ddloc—A-type address or (1-12)
The name of an 8-byte field that contains the symbolic name of the DD
statement to which the device is assigned. The name must be left justified in
the 8-byte field, and must be followed by blanks if the name is fewer than
eight characters. Each DEVTYPE macro executable invocation must have either
ddloc to identify an allocated data set or UCBLIST= to identify one or more
devices.
You can specify ddloc as (1) only if you omit all keywords.
area_addrx—Rx-type address or (0, 2-12)
area_addr—A-type address or (2-12)
The name of an area into which the device information is to be placed. If your
program does not specify the UCBLIST or INFOLIST function, the area is two,
five, or six words long, depending on whether you specify the DEVTAB and
RPS operands. If your program specifies the UCBLIST parameter without
INFOLIST the area must be 6 words long for each UCB. The area must be on a
word boundary.
If your program specifies the INFOLIST parameter, then the length of the area
depends on what you coded for INFO on the referenced DEVTYPE macro. The
INFO description states how many bytes are returned for each value you
specify in the INFO list. To calculate the area size needed, multiply the sum of
those values by ucbl_num in UCBLIST. If you omit UCBLIST (and specify
ddloc), do not multiply.
Note that if you specify UCBLIST (and not ddloc) then (area_addr,area_size) must
still be the second positional parameter. If you code (area_addr,area_size) before
all the keywords, then code it after one comma. If you code (area_addr,area_size)
after a keyword, then code (area_addr,area_size) after two commas.
area_size—absolute expression or (2-12)
The size (in bytes) of the area into which the device information is to be
placed. See Table 51.
Table 51. Minimum size of area
ddloc specified
UCBLIST specified
INFOLIST specified
Minimum size of
area
Yes
No
Omitted or 0
8, 20, or 24 bytes
depending on
whether DEVTAB
and RPS are coded.
Chapter 7. Using System Macro Instructions
265
System Macros
Table 51. Minimum size of area (continued)
ddloc specified
UCBLIST specified
INFOLIST specified
Minimum size of
area
Yes
No
Yes
Sum of the number of
bytes returned for
each code specified
with INFO. See also
the INFO keyword.
No
Yes
Omitted or 0
24 bytes per UCB
No
Yes
Yes
The product of the
number of UCBs
specified with
UCBLIST and the
sum of the number of
bytes returned for
each code specified
with INFO. See also
the INFO keyword.
DEVTAB[,RPS]
DEVTAB is only meaningful for direct access devices. If DEVTAB is specified,
the following number of words of information is placed in your area:
v For direct access devices: 5 words
v For non-direct access devices: 2 words.
If you do not specify DEVTAB, INFOLIST, or UCBLIST, one word of
information is placed in your area if the reference is to a graphics or
teleprocessing device; for any other type of device, two words of information
are placed in your area.
RPS
If RPS is specified, DEVTAB must also be specified. The RPS parameter
causes one additional word of rotational position sensing information to be
included with the DEVTAB information.
UCBLIST=(ucbl_addr,ucbl_num [,BELOW or ANY])
UCBLIST provides a list service in which the caller passes a list of 4-byte UCB
addresses and specifies the number of UCB address entries that are in the list.
You must specify the UCBLIST parameter or ddloc. The BELOW or ANY are
optional keywords that indicate whether the address passed by the UCB
parameter contains a 3-byte or 4-byte UCB address. This keyword only applies
to callers running in AMODE 31. If the caller is running in AMODE 24, the
keyword ANY is ignored and the high-order byte is treated as X'00'.
If you do not specify INFOLIST, then the information returned is always
returned in 6-word entries (one entry per UCB address) regardless of the
device type. The words that would contain information not applicable to the
device for that entry are not altered.
The DEVTYPE macro will accept a captured UCB or an actual UCB address
above or below the 16 MB line, via the UCBLIST = parameter. It will also
accept 24- or 31-bit addresses of UCB copies. The UCB copy must be on a
word boundary, but can be above or below the 16 MB line. Unauthorized
programs can get a copy of the UCB by using the UCBSCAN macro and
specifying the COPY and UCBAREA keywords. Refer to z/OS HCD Planning
for details.
266
z/OS DFSMSdfp Advanced Services
System Macros
ucbl_addr—A-type address or (2-12)
Name of an area containing a list of 4-byte UCB addresses.
ucbl_num—absolute expression or (2-12)
Number of 4-byte UCB address entries in the list.
BELOW
The UCB parameter contains addresses of UCBs that reside in storage
below 16 MB, or a captured UCB. This is the default. If BELOW is
specified, the high-order byte of the UCB address is treated as X'00'.
ANY
The UCB parameter contains a 4-byte UCB address. If ANY is specified
when invoking in 31-bit mode, DEVTYPE treats each word in the UCB
address list as a 31-bit address.
INFOLIST=codel_addr
The name of an area that specifies the types of information DEVTYPE is to
return. Coding INFOLIST=0 has the same effect as omitting it. If you specify
INFOLIST, then you must also specify ddloc or UCBLIST and you must specify
(area_addr,area_size). The format of the returned words is described under
DEVTYPE, DASD, and SUFFIX (see page “DEVTYPE” on page 272).
codel_addr—A-type address or (2-12)
Specifies an area which contains an instance of the DEVTYPE macro where
you coded only the INFO keyword.
PLISTVER=0 or 1 or MAX
Specifies the version of the parameter list for the macro to generate.
0
The program cannot be assembled on a level of the system earlier than
DFSMS/MVS Release 3, which was released in 1996. It can run on any
system level that supports the coded parameters. You cannot code this
with the INFOLIST or INFO parameter. The parameter list will be 20 bytes
long.
1
The program can be assembled and run only on DFSMS/MVS Release 3 or
later. The parameter list will not be acceptable for systems prior to
DFSMS/MVS. This specification generates a 24-byte parameter list.
MAX
In the current release, this has the same effect as coding 1. In a future
release, this value might allow a parameter list that is incompatible with an
earlier release. This is the default and generates a 24-byte parameter list.
DEVTYPE—Execute Form
The execute form of the DEVTYPE macro is:
Chapter 7. Using System Macro Instructions
267
System Macros
►►
DEVTYPE
label
►
ddloc
,BELOW
UCBLIST=( ucbl_addr,ucbl_num
)
,ANY
►
►
,(area_addrx,area_size)
INFOLIST=codel_addrx
,PLISTVER=
MAX
0
1
► MF=(E,name)
►◄
ddloc—RX-type address or (1-12)
Has the same meaning as the standard form of the macro (see also the
UCBLIST parameter below for execute form requirements of the ddloc
parameter).
area_addrx—RX-type address or (2-12)
Has the same meaning as the standard form of the macro. This parameter must
be coded on the list and/or the execute form.
This must be coded on the execute form.
area_size—RX-type address or (2-12)
This form has the same meaning as the standard form of the macro. This
parameter must be coded on the list and/or on the execute form.
This must be coded on the execute form.
UCBLIST=(ucbl_addrx,ucbl_num ,BELOW or ANY)
This format has the same meaning as the standard form of the macro. You
must specify either the UCBLIST or the ddloc parameter on either the execute
or list form. You can code them on both forms. Either parameter on the execute
form overrides the same parameter on the list form.
ucbl_addrx—RX-type address or (2-12)
This format has the same meaning as the standard form of the macro.
ucbl_num—absolute expression or (2-12)
This format has the same meaning as the standard form of the macro
except that in the execute form, the maximum value of an absolute
expression is 4095. You can supply a larger value in a register.
BELOW
This format has the same meaning as the standard form of the macro. If
you write two or three values for UCBLIST on the execute form, it replaces
and overrides all three values in the list form. If you omit UCBLIST on the
execute form, DEVTYPE will use the values in the list form. This is the
default.
ANY
This format has the same meaning as the standard form of the macro. If
you write two or three values for UCBLIST on the execute form, it replaces
and overrides all three values in the list form. If you omit UCBLIST on the
execute form, DEVTYPE will use the values in the list form.
INFOLIST=codel_addrx
This format has the same meaning as the standard form of the macro. You can
code INFOLIST=0 to remove a previous INFOLIST value that is in the list
form.
268
z/OS DFSMSdfp Advanced Services
System Macros
codel_addrx—RX-type address or (2-12)
This format has the same meaning as the standard form of the macro.
PLISTVER=0 or 1 or MAX
This format has the same meaning as on the standard form of the macro. If
you code a non-default value for PLISTVER on the list form, then code the
same value on the execute form.
MF=(E,name)
Specifies the execute form of DEVTYPE. The execute form of the DEVTYPE
macro is valid only with the UCBLIST or INFOLIST function.
Specifies the execute form of the macro. Use the execute form to modify a
parameter list and call the DEVTYPE function.
E
name—RX-type address or (1-12)
Label of the parameter list constructed by the corresponding MF=L form.
DEVTYPE—List Form
The list form of the DEVTYPE macro follows:
►►
DEVTYPE
label
►
ddloc
UCBLIST=
YES
,BELOW
(ucbl_addr,ucbl_num
)
,ANY
►
MF=L
,(area_addr,area_size)
INFOLIST=codel_addr
,PLISTVER=
►◄
MAX
0
1
label
Label of the parameter list to be used. When you specify label with MF=L, label
must be the same as name on MF=(E,name).
ddloc—A-type address
This format has the same meaning as the standard form of the macro.
UCBLIST=YES or (ucbl_addr,ucbl_num,BELOW or ANY)
This format has the same meaning as the standard form of the macro. This is
the default.
YES
DEVTYPE allows UCBLIST=YES as a place holder when MF=L is coded. It
has no effect on the macro expansion.
ucbl_addr—A-type address
This format has the same meaning as the standard form of the macro.
ucbl_num—absolute expression.
This format has the same meaning as the standard form of the macro.
BELOW
This format has the same meaning as the standard form of the macro. This
is the default.
ANY
This format has the same meaning as the standard form of the macro.
Chapter 7. Using System Macro Instructions
269
System Macros
Coding UCBLIST=YES has no effect on the macro expansion. Do not code
UCBLIST=YES with a DD name parameter on the same macro.
area_addr—A-type address
This format has the same meaning as the standard form of the macro. This
parameter must be coded on the list and/or the execute form.
area_size—absolute expression
This format has the same meaning as the standard form of the macro. This
parameter must be coded on the list and/or the execute form.
INFOLIST=codel_addr
This format has the same meaning as the standard form of the macro.
codel_addr—A-type address or (2-12)
This format has the same meaning as the standard form of the macro.
PLISTVER=0 or 1 or MAX
This format has the same meaning as on the standard form of the macro. If
you code a non-default value for PLISTVER on the list form, then code the
same value on the execute form.
MF=L
Specifies the list form of DEVTYPE. The list form of the DEVTYPE macro is
valid only with the UCBLIST or INFOLIST function. By specifying MF=L you
construct a parameter list, and you can subsequently supply the values by
specifying the execute form of the macro.
DEVTYPE—Info Form
The INFO form of the DEVTYPE macro is used to generate a code list for the
INFOLIST parameter. The INFO form is not executable. It has no list or execute
form. When you specify the INFOLIST parameter of DEVTYPE, it refers to an
expansion of DEVTYPE with only the INFO parameter.
The INFO form of the DEVTYPE macro is:
,
DEVTYPE INFO=( ▼
►►
label
)
►◄
AMCAP
DEVTYPE
DASD
SUFFIX
INFO=(AMCAP or DEVTYPE or DASD or SUFFIX)
Specifies the types of information that you wish to retrieve. Specify any
combination of the indicated values in any order. You can specify the same
value more than once in the list. The parentheses around the INFO value can
be omitted if there is only one value.
Specifying the INFO keyword causes the macro expansion to be a list, and it
will not be executable. If you specify the INFO keyword, then omit the MF
keyword or specify MF=L. Note that the E-form does not provide for updating
any of these values. This means that you can specify INFOLIST to refer to a
DEVTYPE expansion that is assembled in a reentrant CSECT.
270
z/OS DFSMSdfp Advanced Services
System Macros
DEVTYPE will return information in the area that you supply in the area_addrx
parameter. Each type of information that you request is of a fixed length, as
stated below. At execution time, the DEVTYPE macro will check whether the
area is long enough. The information will be returned in the order in which
you specify the values with the INFO= keyword. If the requested information
has no meaning for the device or data set, then DEVTYPE clears the
appropriate storage. This means that each piece of information will be returned
at a predictable offset in your area.
IBM can add support to DEVTYPE for new INFO= codes in a future level of
the system. DEVTYPE in the current level is expected to tolerate object code
assembled on such a future level. DEVTYPE in the current level is expected to
return the appropriate number of bytes. They should be binary zeroes or
partial information padded on the right with binary zeroes. In either case
DEVTYPE will also set a return code=0 with a reason code=4 to indicate this
condition. If the information returned by the future code cannot validly be
zero, then you can test for zeroes to determine which field or fields are not
supported. You can also test the DFA to determine the level of the system.
DEVTYPE is not designed to support downward compatibility of source code;
that is, you will not be able to assemble source code containing future INFO
values on the current level.
AMCAP
Returns 32 bytes for the access method capacity as follows:
Table 52. INFO=AMCAP 32–byte return data
Offset
Bytes
Description
0(0)
0(0)
1
1... ....
1(1)
8(8)
7
8
16(10)
8
24(18)
8
Flags.
BSAM, QSAM, and (if DASD) BPAM support the large block interface
and the block size limit is in the next doubleword.
Reserved, currently set to zeros.
Maximum block size supported. If you specify a DD name to DEVTYPE
for a data set concatenation, this value is the largest for any of the DDs.
This value might exceed 32760 for a magnetic tape or dummy data set
and therefore require EXCP or the access method large block interface.
On output, OPEN does not allow a block size that exceeds this value
except with EXCP. On certain cartridge tape drives, exceeding this limit
can cause bypassing of hardware buffering. In the future, IBM might
support values that exceed 32760 for other device types.
Recommended maximum block size. This is less than or equal to the
maximum block size supported. Above this length the device might be
less efficient or less reliable. If you specify a DD name to DEVTYPE for
a data set concatenation, this value is the largest for any of the DDs
(refer to Table 53). Consult hardware documentation for further
information.
Maximum unspanned logical record length supported by BSAM,
QSAM, or BPAM. Various types of data sets on the device might have
various maximum record lengths. Therefore, if UCBLIST was coded on
DEVTYPE and not a DD name, this value is the smallest for the
possible data set types for BSAM, QSAM, and BPAM.
Table 53. Optimum and Maximum Block Size Supported When Using EXCP or the Access Method Large Block
Interface
Device Type
Optimum
Maximum
DASD
Half track
32 760
Chapter 7. Using System Macro Instructions
271
System Macros
Table 53. Optimum and Maximum Block Size Supported When Using EXCP or the Access Method Large Block
Interface (continued)
Device Type
Optimum
Maximum
Reel tape
32 760
32 760
3480, 3490
65 535
65 535
3490 Emulation (VTS)
262 144 (256 KB)
262 144 (256 KB)
3590
262 144 (256 KB) except on some older 262 144 (256 KB)
models on which it is 229 376 (224
KB)
DUMMY
16
5 000 000
DEVTYPE
Returns a copy of the four-byte UCBTYP field of the UCB. See the description
of word 0 in “Device Characteristics Information” on page 273.
DASD
Returns 16 bytes as follows:
Bytes 0-3
Number of cylinders on the device, excluding alternates. For a VIO
data set, this number is the number of simulated cylinders needed to
contain the data set.
Bytes 4-7
Number of tracks per cylinder.
Bytes 8-9
Flags (two bytes)
1... ....
ECKD™ supported. This means that the following commands
are supported:
v Define Extent (X'63') at the beginning of the channel
program, except with VIO.
v Locate Record (X'47')
v Read Multiple Count, Key and Data (X'5E')
v Write Count, Key and Data Next Track (X'9D')
For VIO data sets, this bit is on because these commands are
always supported. For a non-VIO DASD, this bit also means
that the device supports the Define Extent command, but
EXCP allows it only at the beginning of your channel program.
See “DASD Channel Program Prefix CCW Commands” on
page 187.
272
.1.. ....
Locate Record Extended CCW is supported. For VIO data sets,
this bit is on because those commands are always supported.
..1. ....
Controller cache supported.
...1 ....
Flag DVAIXVLD. Flags DVACYLMG (byte 8 bit 4) and
DVAEADSCB (byte 8 bit 5), along with field DVAVIRSZ (bytes
14-15) valid and possibly zero.
.... 1...
Flag DVACYLMG. Cylinder-managed space exists on this
volume and begins at DVALCYL (bytes 10-11) in multicylinder
units of DVAMCU (byte 9). DVAEADSCB (byte 8 bit 5) is also
set with this flag on. Valid when DVAIXVLD (byte 8 bit 3) is
set.
z/OS DFSMSdfp Advanced Services
System Macros
.... .1..
Flag DVAEADSCB. Extended attribute DSCBs, Format 8 and 9
DSCBs, are allowed on this volume. Valid when DVAIXVLD
(byte 8 bit 3) is set.
.... ..1.
Flag DVASSDEV. The device is solid state.
.... ...1
Flag DVACRYPT. Data encrypted device.
Byte 9 Field DVAMCU. Minimum allocation size in cylinders for
cylinder-managed space. Each extent in this space must be a multiple
of this value. Also referred to as the multicylinder unit (MCU). This is
the smallest unit of disk space in cylinders that can be allocated in
cylinder managed space. Valid when DVACYLMG (byte 8 bit 4) is set.
This field is zero on releases before z/OS 1.10 or if the status is not yet
known. In these two cases DVAIXVLD (byte 8 bit 3) is not set.
Bytes 10-11
Field DVALCYL. First cylinder address divided by 4095 where space is
managed in multicylinder units. Valid when DVACYLMG (byte 8 bit 4)
is set. When valid and zero the volume has no cylinder-managed
space. This field is zero on releases before z/OS 1.10 or if the status is
not yet known. In these two cases DVAIXVLD (byte 8 bit 3) is not set.
Byte 12
Track set size. Zero if device does not support read-any or write-any.
See 3990 Reference for more information.
Bytes 13
Reserved. DEVTYPE currently returns zeroes but could return
something different in a future release.
Bytes 14-15
Block size of the index data set. Valid when byte 8 bit 3 is on. When
valid and zero the volume has no working VTOC index. This field is
zero on releases before z/OS 1.10 or if the status is not yet known. In
these cases byte 8 bit 3 is not set.
SUFFIX
Returns in two bytes the length of the suffix that the system adds to each block
in an extended format data set that can be stored on the device. Use this
information for space calculations such as with the TRKCALC macro and for
determining optimal block size. For device types that support extended format
data sets, DEVTYPE returns 32. A non-zero value does not mean that the data
set actually is extended format or that the device supports extended format
data sets. Not all storage controllers can support extended format data sets. In
a future release this value might change.
Device Characteristics Information
|
|
|
|
|
|
|
The following information is placed into your area as a result of issuing a
DEVTYPE macro if you do not code the INFOLIST parameter or if you code
INFO=DEVTYPE.
Word 0: Describes the device as defined in the UCBTYP field of the UCB. See the
definition of UCBTYP in an expansion of the IEFUCBOB mapping macro. It calls
an inner macro, IECDUCBD, that defines additional bits for UCBTYP that are
unique for DASD. See the comment that refers to UCBTBYT2. These bit definitions
include the read-only device attributes.The IHADVA macro maps these four bytes
this way:
Chapter 7. Using System Macro Instructions
273
System Macros
Table 54. Device Characteristics Information
Offset
Length
Symbol
Description
0
2
DVAOPTS
Model and option bits that depend on the device
2
1
DVACLASS
Device class. Exactly one bit is on except that X'41' means a channel-to-channel adapter.
X'80'=magnetic tape, X'40'=unit record, X'20'=DASD, X'10'=display and X'08'=character reader.
A value of X'01' indicates a simulated device that does not have a UCB. These meanings are
described in Table 55.
3
1
DVAUNIT
Device type. Depends on the device class.
Simulated Device Characteristics:
Some types of data set reside on simulated devices and do not have a UCB. If you
do not code UCBLIST or INFOLIST, DEVTYPE will return data as described by
Table 2 in the first two words. The UCB type codes in this table can be returned
only if you identify the device by DD name and not if you code UCBLIST.
DEVTYPE also can return the word 0 described in Table 55 if you code
INFO=DEVTYPE.
Table 55. Simulated Device Characteristics Information
Data Set Type
Word 0 in
Hexadecimal
Word 1 in
Hexadecimal
DUMMY application process queue
0000 0000
0000 0000
TSO terminal
0000 0101
0000 7FF8
SYSIN, SYSOUT, or subsystem (SUBSYS=)
0000 0102
0000 7FF8
UNIX system services (possibly HFS) file
0000 0103
0000 7FF8
The system also uses a copy of the UCBTYP word in these places:
v In catalog entries for DASD and tape data sets. Some of the model and option
bits are zero. See output of the IDCAMS LISTCAT command.
v As the device code returned by the LOCATE macro in the volume list. See
“Retrieving Information from a Catalog” on page 157. Some of the model and
option bits are zero.
v Input to the SCRATCH macro. See “Deleting a Data Set from the VTOC” on
page 145 and “SCRATCH and CAMLST Macro Specification” on page 147.
v Input to the RENAME macro. See “Renaming a Data Set in the VTOC” on page
151 and “RENAME and CAMLST Macro Specification” on page 153.
Word 1
Maximum block size without using the large block interface of the access
method. The maximum value is 32760 bytes. For direct access devices, this
value is the smaller of either the maximum size of a nonkeyed block or the
maximum block size allowed by the operating system; for magnetic tape
devices, this value is the maximum block size allowed by the access
methods. For these and other device types, see Table 56 on page 277.
If your program specifies either DEVTAB or UCBLIST without INFOLIST,
the next three words contain the following information about direct access
devices:
Word 2
274
z/OS DFSMSdfp Advanced Services
System Macros
Bytes 0-1
The number of physical cylinders on the device, including
alternates. Treat this as an unassigned 16-bit number.
Recommendation: Before you use bytes 0 and 1, read the
description of word 4, byte 1, bit 0. For a VIO data set, that bit is
zero, and the number of cylinders is as many as are needed to
contain the simulated data set. This can differ from the number for
the real device being simulated.
Bytes 2-3
The number of tracks per cylinder.
Word 3
Bytes 0-1
Maximum track length. Note that this value is not equal to the
value in word 1 (maximum block size).
Byte 2 Block overhead, keyed block—the number of bytes required for
gaps and check bits for each keyed block other than the last block
on a track.
Recommendation: Before using bytes 2 and 3, read the description
of word 4.
Byte 3 Block overhead—the number of bytes required for gaps and check
bits for a keyed block that is the last block on a track.
Bytes 2-3
Block overhead—the number of bytes required for gaps and check
bits for any keyed block on a track including the last block. Use of
this form is indicated by a 1 in bit 4, byte 1 of word 4.
Basic overhead—the number of bytes required for the count field.
Use of this form is indicated by a 1 in bit 3, byte 1 of word 4.
Word 4
Byte 0 Block overhead, block without key—the number of bytes to be
subtracted from word 3, bytes 2 or 3 or bytes 2 and 3, if a block is
not keyed.
If bit 3, byte 1 of word 4 is 1, this byte contains the modulo factor
for a modulo device.
Byte 1
Bit 0
If on, the number of cylinders, as indicated in word 2,
bytes 0 and 1 is not valid. If the number of cylinders on
the volume exceeds 65520, then this bit is on. To retrieve
the number of cylinders for any DASD, you can use the
INFO=DASD operand of the DEVTYPE macro.
Bit 1
If on, ECKD supported. This means that the following
commands are supported:
v Define Extent (X'63') at the beginning of the channel
program, except with VIO.
v Locate Record (X'47')
v Read Multiple Count, Key and Data (X'5E')
v Write Count, Key and Data Next Track (X'9D')
Chapter 7. Using System Macro Instructions
275
System Macros
For VIO data sets, this bit is on because these commands
are always supported. For a non-VIO DASD, this bit also
means that the device supports the Define Extent
command, but EXCP allows it only at the beginning of
your channel program. See “DASD Channel Program
Prefix CCW Commands” on page 187.
Bits 2-3
If both on, indicates the drive is attached to a cache storage
control.
Bit 3
If on, indicates a modulo device (such as 3380, 3390).
Bit 4
If on, bytes 2 and 3 of word 3 contain a halfword giving
the block overhead for any block on a track, including the
last block.
Bit 5
If on, the device supports paging CCWs.
Bit 6
If on, the device has no alternate cylinders.
Bit 7
If on, a tolerance factor must be applied to all blocks
except the last block on the track.
Bytes 2-3
Tolerance factor—this factor is used to calculate the effective length
of a block. The calculation should be performed in the following
order:
Step 1 Add the block's key length to the block's data length.
Step 2 Test bit 7 of byte 1 of word 4. If bit 7 is 0, perform step 3.
If bit 7 is 1, multiply the sum computed in step 1 by the
tolerance factor. Shift the result of the multiplication 9 bits
to the right.
Step 3 Add the appropriate block overhead to the value obtained
above.
If bit 3, byte 1 of word 4 is 1, bytes 2 and 3 contain the
overhead for the data or key field.
If your program specifies DEVTAB and RPS, or specifies UCBLIST without
INFOLIST, the next word contains the following information:
|
|
Word 5
Bytes 0-1
R0 overhead for sector calculations
Byte 2 Number of sectors for each track
Byte 3 Number of data sectors for each track
Table 56 on page 277 and Table 57 on page 277 show the output for each device
type that results from issuing the DEVTYPE macro.
If your program specifies UCBLIST and not INFOLIST, the output consists of one
6-word entry for every UCB address contained in the UCB list.
276
z/OS DFSMSdfp Advanced Services
System Macros
Table 56. Output from DEVTYPE Macro.
Maximum Access Method Record Size
When Not Using Large Block Interface
IBM Device1
2540 Reader
2540 Punch
2501 Reader
3890 Document Processor
3505 Reader
3525 Punch
1403 Printer
3203 Model 5 Printer
3211 Printer
3262 Model 5 Printer
4245 Printer
4248 Printer
3800 or 3900 Printing Subsystem
3410, 3420, 3422, 3424 4 3430, 3480, 3490, 3590
Tape Units
Note:
80
80
80
80
80
80
120 1
132
132 1
132
132
132 2
136 3
32760
1. Although certain models can have a larger line size, the minimum line size is assumed.
2. The IBM 4248 Printer returns 132 characters even if the 168 Print Position Feature is
installed on the device.
3. The IBM 3800 Printing Subsystem can print 136 characters per line at 10-pitch, 163
characters per line at 12-pitch, and 204 characters per line at 15-pitch. The machine
default is 136 characters per line at 10-pitch.
4. The 3424 Magnetic Tape Unit is available only in Brazil, S.A.
Table 57. Output from DEVTYPE Macro — DASD Devices
IBM Device
Maximum
Record Size
(Word 1,
Decimal)
DEVTAB (Words 2, 3, and 4, in Hexadecimal)
RPS (Word 5,
in
Hexadecimal)
3380 Models AD4, AJ4, BD4, BJ4, and CJ2 Disk
Storage
32 760
0376 000F BB60 0100 2010 010B
04E0 DED6
3380 Models AD4, AJ4, BD4, BJ4, Disk Storage
(attached to a cache storage control)
32 760
0376 000F BB60 0100 2030 010B
04E0 DED6
3380 Models AE4 and BE4 Disk Storage
32 760
06EB 000F BB60 0100 2010 010B
04E0 DED6
3380 Models AE4 and BE4 Disk Storage
(attached to a cache storage control)
32 760
06EB 000F BB60 0100 2030 010B
04E0 DED6
3380 Models AK4 and BK4 Disk Storage
32 760
0A60 000F BB60 0100 2010 010B
04E0 DED6
3380 Models AK4 and BK4 Disk Storage
(attached to a cache storage control)
32 760
0A60 000F BB60 0100 2030 010B
04E0 DED6
3390 Model 1 (attached to a 3990 Model 2)
32 760
0459 000F E5A2 0000 0052 0000
0594 E000
3390 Model 1 (attached to a 3990 Model 3)
32 760
0459 000F E5A2 0000 0072 0000
0594 E000
3390 Model 2 (attached to a 3990 Model 2)
32 760
08B2 000F E5A2 0000 0052 0000
0594 E000
3390 Model 2 (attached to 3990 Model 3)
32 760
08B2 000F E5A2 0000 0072 0000
0594 E000
3390 Model 3 (attached to a 3990 Model 2)
32 760
0D0B 000F E5A2 0000 0052 0000
0594 E000
3390 Model 3 (attached to a 3990 Model 3)
32 760
0D0B 000F E5A2 0000 0072 0000
0594 E000
3390 Model 3 (attached to a 3990 Model 6)
32 760
0D0B 000F E5A2 0000 0072 0000
0594 E000
3390 Model 9 (attached to a 3990 Model 2)
32 760
2721 000F E5A2 0000 0052 0000
0594 E000
3390 Model 9 (attached to a 3990 Model 3)
32 760
2721 000F E5A2 0000 0052 0000
0594 E000
3390 Model 9 (attached to a 3990 Model 6)
32 760
2721 000F E5A2 0000 0052 0000
0594 E000
Chapter 7. Using System Macro Instructions
277
System Macros
Table 57. Output from DEVTYPE Macro — DASD Devices (continued)
IBM Device
Maximum
Record Size
(Word 1,
Decimal)
DEVTAB (Words 2, 3, and 4, in Hexadecimal)
RPS (Word 5,
in
Hexadecimal)
9345 Model 1
32 760
05A0 000F BC98 0000 0052 0000
04A0 D500
Recommendation: For all currently supported devices, DEVTYPE does not return
enough information to perform space calculations. Use the TRKCALC macro and
the sector conversion routine to perform space calculations. For information on
using the TRKCALC macro, see “Performing Track Calculations (TRKCALC
macro)” on page 307. For information on the sector conversion routine, see
“Obtaining the Sector Number of a Block on an RPS Device” on page 236.
DEVTYPE—Return Codes and Reason Codes
Control is returned to your program at the next executable instruction following
the DEVTYPE macro instruction. Register 15 contains a return code from the
DEVTYPE macro, and register 0 contains the reason code. Registers 2 to 14
contents are unchanged. Register 1 contents are unpredictable. The return codes
and their meanings are as follows:
Return Code
Meaning
0 (X'00')
Information has been successfully stored in your work area.
Reason Code
Meaning
0 (X'00')
All the information is available.
4 (X'04')
4 (X'04')
DEVTYPE did not recognize one or more INFO parameter
codes. DEVTYPE cleared the appropriate amount of the
return area and processed the rest of the INFO codes.
Invocation error.
Reason Code
Meaning
4 (X'04')
DD name not defined.
8 (X'08')
8 (X'08')
Parameter list not valid. The error might be version code,
length, zero field, or return area is not large enough.
DEVTYPE does not do a complete UCB check in the
current release. The UCB address might not be valid
because the correct value was not coded for the third value
of the UCBLIST parameter.
Unsupported device class.
Reason Code
Meaning
12 (X'0C')
DEVTYPE does not support the device class. It must be
DASD, tape, subsystem (including spooled), unit record,
TSO terminal, dummy, communications, graphics or
channel-to-channel adapter. If UCBLIST was coded, then
DEVTYPE has ignored the rest of the list.
278
z/OS DFSMSdfp Advanced Services
System Macros
DEVTYPE—Example 1—Referring to a DD Statement
MYDD
DEVINFO
DEVTYPE MYDD,DEVINFO,DEVTAB
•
•
•
DC
CL8’DATATAB’
DC
5F’0’
Example 1 of DEVTYPE returns 20 bytes of device information if DATATAB is a
DASD data set or 8 bytes otherwise.
DEVTYPE—Example 2—Includes Building a Parameter List
MVC
DTLIST,KDTLIST
BUILD PARAMETER LIST IN DYNAMIC STORAGE
*************************************************************************
* RETRIEVE FOUR BYTE UCBTYP FOR SYSUT1 DEVICE
*************************************************************************
DEVTYPE MF=(E,DTLIST),,(AREA,L’AREA)
•
•
•
*************************************************************************
* RETRIEVE 20 BYTES (DASD INFO AND UCBTYP) FOR THE UNIT DESCRIBED BY THE
* UCB THAT UCBAD POINTS TO. THE AREA ADDRESS AND LENGTH ARE STILL
* IN THE PARAMETER LIST FROM THE DEVTYPE EXECUTION PERFORMED ABOVE
*************************************************************************
DEVTYPE UCBLIST=(UCBAD,1),INFOLIST=ILIST2,MF=(E,DTLIST)
•
•
•
KDTLIST DEVTYPE FIRSTDD,MF=L,INFOLIST=ILIST1 NON-MODIFIABLE PARAMETER
*
LIST
LDTLIST EQU
*-KDTLIST
FIRSTDD DC
CL8’SYSUT1’
ILIST1 DEVTYPE INFO=DEVTYPE
ILIST2 DEVTYPE INFO=(DASD,DEVTYPE) REQUEST DATA AT AREA
DYNAMIC DSECT
UCBAD
DS
A
ADDRESS OF UCB
DTLIST DS
CL(LDTLIST)
DEVTYPE PARAMETER LIST(MODIFIABLE)
DS
0F
ALIGNMENT FOR TRKCYL
AREA
DS
0CL20
INFORMATION FROM
*
DEVTYPE INFO=(DASD,DEVTYPE)
TYP1
DS
0CL4
INFORMATION FROM
*
DEVTYPE INFO=DEVTYPE (UCBTYP)
*
FOR FIRSTDD
NUMCYL DS
F
NUMBER OF CYLINDERS ON VOLUME
TRKCYL DS
F
NUMBER OF TRACKS PER CYLINDER
DS
CL8
MISCELLANEOUS
TYP2
DS
CL4
UCBTYP FROM UCB POINTED TO
*
FROM UCBAD
Example 2 of DEVTYPE builds a parameter list in dynamically-acquired storage so
the program can be reentrant. It then supplies additional parameters in the first
execute form and overrides some of them in the second execute form. In effect, the
first specification of DEVTYPE is:
DEVTYPE FIRSTDD,(AREA,L’AREA),INFOLIST=ILIST1
ILIST1 describes four bytes to be returned. They are at the beginning of a 20-byte
area - DEVTYPE clears the extra 16 bytes. The list form at KDTLIST specifies
parameters that will not be overridden by the first execute form. The execute form
specifies parameters that are determined during execution. In effect, the second
specification of DEVTYPE is:
DEVTYPE ,(AREA,L’AREA),INFOLIST=ILIST2,UCBLIST=(UCBAD,1)
Chapter 7. Using System Macro Instructions
279
System Macros
The INFOLIST describes 20 bytes to be returned.
The first execute form illustrates an unusual technique of coding a keyword
parameter (MF) before two positional parameters. The first positional value is null,
and the second position is (AREA,L'AREA). This generally is not a good technique
because it is confusing. It is used here only to show the flexibility that Assembler
H and High Level Assembler allow.
For another example of DEVTYPE, see Figure 38 on page 324.
DEVTYPE—Example 3—Building a Parameter List and Using
IHADVA
This example is the same as the previous one, but it uses the IHADVA macro to
map the DEVTYPE output and several unusual techniques to demonstration the
possibilities.
MVC DTLIST,KDTLIST
Build parameter list in dynamic storage
***********************************************************************
* Retrieve four-byte UCBTYP for SYSUT1 device in 20-byte area.
***********************************************************************
DEVTYPE ,(DVAIDASD,L’DVAIDASD+LenDEVTYPE),MF=(E,DTLIST)
DTUsing USING DVAUCBTY,DVAIDASD
Map DSECT on CSECT
*
*
***********************************************************************
* Retrieve 20 bytes (DASD INFO and UCBTYP) for the unit described by
* the UCB that UCBAD points to. The area address and length are still
* in the parameter list from the DEVTYPE execution performed above.
***********************************************************************
DEVTYPE UCBLIST=(UCBAD,1),INFOLIST=ILIST2,MF=(E,DTLIST)
DTUsing USING DVAUCBTY,DVAIDASD+L’DVAIDASD
Map DSECT on CSECT
*
*
KDTLIST DEVTYPE FIRSTDD,MF=L,INFOLIST=ILIST1 Read-only parameter list
LDTLIST EQU
*-KDTLIST
Length of parameter list
FIRSTDD DC
CL8’SYSUT1’
DD name
ILIST1 DEVTYPE INFO=DEVTYPE
DEVTYPE INFO list
ILIST2 DEVTYPE INFO=(DASD,DEVTYPE) Another INFO list
* End of CSECT.
DYNAMIC DSECT
**** Dynamic storage for reentrancy
UCBAD
DS
A
Address of UCB
DTLIST DS
CL(LDTLIST)
DEVTYPE parameter list (modifiable)
DS
0F
Alignment for efficiency
* Output from INFO=(DASD,DEVTYPE) begins here.
* Next line defines symbols for DVAIDASD, which is 16 bytes.
IHADVA DSECT=NO,INFO=DASD Info from DEVTYPE INFO=DASD
DS
CL(LenDEVTYPE) Info from DEVTYPE INFO=DEVTYPE
* Next line defines the DVAUCBTY DSECT, which is 4 bytes.
IHADVA DSECT=YES,INFO=DEVTYPE Info from DEVTYPE INFO=DEVTYPE
LenDEVTYPE EQU *-DVAUCBTY
Length of DSECT (4 b
Example 3 of DEVTYPE builds a parameter list in dynamically-acquired storage so
the program can be reentrant. It then supplies additional parameters in the first
execute form and overrides some of them in the second execute form. In effect, the
first specification of DEVTYPE is:
DEVTYPE FIRSTDD,(DVAIDASD,L’DVAIDASD+LenDEVTYPE),INFOLIST=ILIST1
ILIST1 describes four bytes to be returned at the beginning of a 20-byte area. The
length attribute of the INFO=DASD area is L'DVAIDASD, which is 16. The
constant LenDEVTYPE is the length of the INFO=DEVTYPE area, which is four
bytes. DEVTYPE clears the extra 16 bytes. The list form at KDTLIST specifies
parameters that will not be overridden by the first execute form. The execute form
specifies parameters that are determined during execution.
280
z/OS DFSMSdfp Advanced Services
System Macros
The DTUsing USING DVAUCBTY,DVAIDASD line is a labeled dependent USING
statement. It applies the 4-byte DVAUCBTY DSECT on top of the storage at
DVAIDASD. One purpose of the symbol DTUsing could be to allow a later DROP
statement to end the addressability but that is not the purpose of the label here.
The purpose here is to avoid an assembler warning message ASMA303W. Multiple
address resolutions may result from this USING and the USING on statement
number nn". It would be on the second labeled USING if it did not have the same
label.
In effect, the second specification of DEVTYPE is:
DEVTYPE ,(L’DVAIDASD+LenDEVTYPE),INFOLIST=ILIST2,UCBLIST=(UCBAD,1)
The INFOLIST describes 20 bytes to be returned. The second USING with the label
DTUsing defines addressability to the last four of the 20 bytes. The first 16 bytes
have no USING because they are a part of the DYNAMIC DSECT and already
have addressability that is not shown. This technique of using one DSECT (defined
by IHADVA DSECT=YES,INFO=DEVTYPE) apply to two places in different areas of the
program is allowed by named USINGs without loading another base register.
The IHADVA DSECT=NO,INFO=DASD line defines 16 bytes of variables that DEVTYPE
sets. The first symbol is DVAIDASD and its length attribute is 16.
The DS CL(LenDEVTYPE) line defines variables that are described by the DSECT
generated by the IHADVA DSECT=YES,INFO=DEVTYPE line.
IHADVA Mapping macro
The IHADVA macro supports two parameters:
DSECT={YES|NO}
If you code DSECT=YES, you get a single area with a DSECT. This is the
default. Its name depends on whether you code INFO= and what you code for
it. The DSECT name depends on the first value that you code for INFO=.
The following applies if you code DSECT=NO:
v If you omit INFO= or you code INFO=NONE, then the area begins with the
symbol DVAREA and it is not a DSECT.
v
If you code any combination of INFO values other than NONE, then
DVAREA is not defined and there is no DSECT.
INFO={NONE|DEVTYPE|DASD|SUFFIX|AMCAP}
If you omit the INFO keyword, then the mapping is for all of the following at
the same origin:
v
- the minimum type of call
v UCBLIST= without INFO=
v INFO=DASD
v INFO=DEVTYPE
v
INFO=SUFFIX
INFO=NONE.
This generates the mapping for the minimum type of call or when you
code UCBLIST= without INFO=. You cannot code NONE in combination
with any other value.
INFO=DASD
Generate the mapping for the area returned by coding INFO=DASD. The
DSECT name or first symbol is DVAIDASD.
Chapter 7. Using System Macro Instructions
281
System Macros
INFO=DEVTYPE
Generate the mapping for the area returned by coding INFO=DEVTYPE.
The DSECT name or first symbol is DVAUCBTY.
INFO=SUFFIX
Generate the mapping for the area returned by coding INFO=SUFFIX. The
DSECT name or first symbol is DVASUFFX.
INFO=AMCAP
Generate the mapping for the area returned by coding INFO=AMCAP. The
DSECT name or first symbol is DVAAMCAP.
=======================================================================
DEVTYPE return area (mapping macro IHADVA)
THIS MACRO MAPS THE AREA RETURNED TO THE CALLER BY THE DEVTYPE SVC
=======================================================================
OFFSET
DEC(HEX) TYPE
LEN NAME
======== ======== ===== =========
0 (0) STRUCTURE
24 DVAREA
0 (0) CHARACTER
8 DVAPREFX
0
0
2
3
4
8
8
10
12
14
(0)
(0)
(2)
(3)
(4)
(8)
(8)
(A)
(C)
(E)
14
15
16
17
(E)
(F)
(10)
(11)
18 (12)
282
DESCRIPTION
===========================
Area if no INFOLIST=, DEVTAB
or RPS
Following four bytes are also returned for INFO=DEVTYPE
CHARACTER
4
DVAUCBTY
UCB TYPE FIELD
BITSTRING
2
DVAOPTS
UCB OPTIONS
BITSTRING
1
DVACLASS
DEVICE CLASS
BITSTRING
1
DVAUNIT
UNIT TYPE
SIGNED
4
DVAMAXRC
MAXIMUM RECORD SIZE
CHARACTER
12
DVATAB
SECTION INCLUDED BY DEVTAB
UNSIGNED
2
DVACYL
PHYS NUMBER CYL PER VOLUME
SIGNED
2
DVATRK
NR OF TRACKS PER CYL
SIGNED
2
DVATRKLN
TRACK LENGTH ( BYTES)
SIGNED
2
DVAOVHD
BLOCK OVERHEAD IF DVA2BOV IS
ON
IF DVA2BOV IS OFF USE INSTEAD THE FOLLOWING TWO VALUES
ADDRESS
1
DVAOVNLB
OVERHEAD NOT LAST BLOCK
ADDRESS
1
DVAOVLB
OVERHEAD LAST BLOCK
ADDRESS
1
DVAOVNK
OVERHEAD DECR IF NOT KEYED
BITSTRING
1
DVAFLAGS
FLAG BYTE
1... ....
DVABDCYL
IF 1, DVACYL IS INVALID
YL02130
.1.. ....
DVADEFLR
DEFINE EXTENT/LOCATE RECORD
AND RELATED TRANSFER COMMANDS
ARE IMPLEMENTED
..1. ....
DVADEFEX
DEFINE EXTENT IMPLEMENTED
...1 ....
DVAMODL
IF ON, USE MODULO TRACK
ALGORTIHM
.... 1...
DVA2BOV
IF ON, USE DVAOVHD ELSE USE
DVAOVNLB & DVAOVLB
.... .1..
DVAPAGES
IF ON DEVICE SUPPORTS PAGING
CCWS
.... ..1.
DVANOALT
NO ALT TRKS AVAILABLE
.... ...1
DVAFTOL
IF ON, APPLY TOLERANCE FACTOR
SIGNED
2
DVATOL
TOLERANCE FACTOR
(BLKSI+KEYLE) DVATOL/DVADVSR GIVES THE ADJUSTED BLOCK SIZE
TO WHICH APPROPRIATE OVERHEADS ARE THEN ADDED.
20 (14)
20 (14)
22 (16)
CHARACTER
SIGNED
ADDRESS
4
2
1
23 (17)
ADDRESS
1
z/OS DFSMSdfp Advanced Services
DVARPS
DVAOVR0
DVASECT
DVASECTD
RPS SECTION
OVERHEAD BYTES FOR RECORD 0
NUMBER OF SECTORS IN FULL
TRACK
NUMBER OF DATA SECTORS
System Macros
====================================================================
THE FOLLOWING SECTION IS RETURNED BY DEVTYPE FOR INFO=DASD.
====================================================================
0
0
4
8
(0)
(0)
(4)
(8)
STRUCTURE
UNSIGNED
UNSIGNED
UNSIGNED
1... ....
16 DVAIDASD
4 DVAICYL
4 DVAITRK
1 DVAIFLAG
DVAECKD1
.1.. ....
DVALRE1
..1. ....
...1 ....
DVACACHE1
DVAIXVLD
.... 1...
DVACYLMG
.... .1..
DVAEADSCB
9 (9)
.... ..1.
.... ...1
UNSIGNED
1
DVASSDEV
DVACRYPT
DVAMCU
10 (A)
UNSIGNED
2
DVALCYL
12 (C)
13 (D)
UNSIGNED
UNSIGNED
1
1
DVAITSET
*
14 (E)
UNSIGNED
2
DVAVIRSZ
NUMBER OF CYLINDERS
TRACKS PER CYLINDER
FLAGS
ECKD SUPPORTED, ALSO ON FOR
VIO DATA SETS
LOCATE RECORD EXTENDED
SUPPORTED
DEVICE IS CACHED
DVACYLMG, DVAEADSCB, DVAVIRSZ
valid.
Cylinder-managed space exists
on this volume and begins at
DVALCYL in multicylinder units
of DVAMCU. DVAEADSCB is also
set with this flag on. Valid
when DVAIXVLD is set.
Extended attribute DSCBs,
Format 8 and 9 DSCBs, are
allowed on this volume. Valid
when DVAIXVLD is set.
The device is solid state
Data encrypted device.
Minimum allocation size in
cylinders for cylinder-managed
space. Each extent in this
space must be a multiple of
this value. space. Also
referred to as the
multicylinder unit (MCU). This
is the smallest unit of disk
space in cylinders that can be
allocated in cylinder-managed
space. Valid when DVACYLMG is
set. This field is zero on
releases before z/OS 1.10 or
if the status is not yet
known. In these two cases
DVAIXVLD is not set.
First cylinder address divided
by 4095 where space is managed
in multicylinder units.
Cyl-managed space begins at
this address. Valid when
DVACYLMG is set. This field is
zero on releases before z/OS
1.10 or if the status is not
yet known. In these two cases
DVAIXVLD is not set.
TRACK SET SIZE
Reserved. DEVTYPE currently
returns zeroes but could
return something different in
a future release.
Block size of the index data
set. Valid when DAVIXVLD is
set on. When valid and zero
the volume has no working VTOC
index. This field is zero on
releases before z/OS 1.10 or
if the status is not yet
known. In these cases DVAIXVLD
is not set.
Chapter 7. Using System Macro Instructions
283
System Macros
====================================================================
THE FOLLOWING SECTION IS RETURNED BY DEVTYPE FOR INFO=AMCAP.
====================================================================
0 (0) STRUCTURE
32 DVAAMCAP
ACCMETH
CAPABILITY
0 (0) BITSTRING
1 DVAAMFLG
FLAGS
1... ....
DVAAMLBI
BSAM, QSAM AND (IF DASD) BPAM
SUPPORT THE LARGE BLOCK
INTERFACE & THE LIMIT IS IN
THE NEXT DOUBLEWORD.
.1.. ....
DVAAM_XTIOT
This data set allocation has an
XTIOT. Either all or none of the
entries for a concatenation are
XTIOT.
..1. ....
DVAAM_XTIOTAM BSAM, QSAM and BPAM (if DASD)
support XTIOT for this device,
and the NON_VSAM_XTIOT option in
PARMLIB allows it. DEVTYPE will
turn this on if the UCB is DASD
or tape or the DD is dummy and
the PARMLIB option allows it.
...1 ....
DVAAM_31UCB
One or more UCB addresses for
this data set allocation (or
concatenation) point above the 16
MB and have not been captured for
the allocation. If this bit is
off, the data set still might be
extended to another volume and
gain a 31-bit address UCB.
.... 1...
DVAAM_31UCBAM BSAM, QSAM and BPAM (if DASD)
support 31-bit UCB addresses in
the DEB and the NON_VSAM_XTIOT
option in PARMLIB allows it.
.... .1..
.... ..1.
1
8
16
24
0
DVAAM_DSAB
DVAAM_DSABAM
DSAB is above the line.
BSAM, QSAM and BPAM (if DASD)
support DSAB above the line and
the NON_VSAM_XTIOT option in
PARMLIB allows it.
(1) CHARACTER
7 *
RESERVED
(8) BITSTRING
8 DVAMAXBLK
MAXIMUM BLOCK SIZE SUPPORTED
WITH
SAM LBI
(10) BITSTRING
8 DVAOPTBLK
RECOMMENDED MAXIMUM BLOCK SIZE
LONGER BLOCKS MIGHT BE LESS
EFFICIENT OR LESS RELIABLE.
LESS THAN OR EQUAL TO PREVIOUS
FIELD.
(18) BITSTRING
8 DVAMAXLR
MAXIMUM UNSPANNED LOGICAL
RECORD
LENGTH SUPPORTED BY BSAM, QSAM
AND BPAM
====================================================================
THE FOLLOWING SECTION IS RETURNED BY DEVTYPE FOR INFO=SUFFIX.
====================================================================
(0)
SIGNED
2 DVASUFFX
SUFFIX LENGTH
Reading and Modifying a Job File Control Block (RDJFCB Macro)
To accomplish the functions that are performed as a result of an OPEN macro
instruction, the open routine requires access to information that you have supplied
in a data definition (DD) statement. This information is stored by the system in a
job file control block (JFCB). Some information is placed into the JFCB when the
data set is allocated, while other information is placed there only when the data set
284
z/OS DFSMSdfp Advanced Services
System Macros
is opened. Which fields are updated and when they are updated will vary
depending upon factors such as what is specified in the JCL DD statement, what
the application does, whether the data set is SMS managed or not, and so on.
Fields that have not been updated yet will contain binary zeroes.
In certain applications, you might find it necessary to modify the contents of a
JFCB (previously specified in the allocation parameters) before issuing an OPEN
macro instruction against a data set. For example, lets suppose that you are adding
records to the end of a sequential data set. You might want to add a secondary
allocation quantity to allow the existing data set to be extended when the space
currently allocated is exhausted. To assist you, the system provides the RDJFCB
macro instruction. This macro instruction causes a JFCB to be moved to an area
specified in an exit list. Use of the RDJFCB macro instruction with an exit list is
shown under “Example” on page 289. When you subsequently issue the OPEN
macro instruction, you can specify the TYPE=J operand to open the data set using
the JFCB in the area you specified.
You can use RDJFCB and a DCB to learn the data set name, AMP parameters and
volume serials of a VSAM data set. You can use any valid combination of MACRF
and DSORG in the DCB. The simplest would be DSORG=PS,MACRF=R. You
cannot use the JFCB with OPEN TYPE=J to open a VSAM data set.
If you specify the XTIOT, UCB NOCAPTURE or DSAB-above-the-line options of
dynamic allocation, then the system creates an XTIOT. With these options, if the
access method is not EXCP and the data set is not VSAM, then RDJFCB requires
that you code the LOC=ANY option on the DCBE macro, and the
NON_VSAM_XTIOT=YES option in the DEVSUPxx member of SYS1.PARMLIB is
in effect.
The RDJFCB macro also allows you to retrieve allocation information for the data
sets in a concatenation. You can either select data sets or, by default, retrieve the
information for all data sets in the concatenation.
You can retrieve the following items:
v All JFCBs
v All volume serial numbers
v Block size limit
v The path name (PATH=) associated with any DD. In these cases the data set
name in the JFCB is a dummy value.
“Type 07 JFCB Exit List Entry” on page 290 describes how you can use RDJFCB to
retrieve this information.
Tip: If you set the bit JFCNWRIT in the JFCBTSDM field to 1 before you issue the
OPEN macro instruction, the JFCB is not written back at the conclusion of open
processing. OPEN TYPE=J normally moves your program's modified copy of the
JFCB, to replace the system copy. To ensure that this move is done, your program
must set bit zero of the JFCBMASK+4 field to 1. IBM recommends not setting on
JFCNWRIT. If the user JFCB (which the system used to open the data set) is not
written back, errors can occur during termination processing for EOV, CLOSE, or
the job/step because OPEN might have updated information in the user JFCB
which will not be reflected in the system copy of the JFCB. For example, when a
nonspecific tape data set is opened, OPEN will update the user supplied JFCB with
the volume serial number of the tape selected. However, the system copy of the
JFCB will not reflect this volume serial number. This could cause errors during
Chapter 7. Using System Macro Instructions
285
System Macros
termination processing for EOV, CLOSE, or the job/step (for example, the data set
might not be cataloged even though the job requested it).
Tip: If your program has a DCBE, which has a value for BLKSIZE, which is too
large for the two bytes in the JFCB, the OPEN TYPE=J normally copies it to
another system control block. If your program sets JFCNWRIT on, that setting may
prevent OPEN from storing the DCBE BLKSIZE value into the system control
block. This may lead to further system errors during data set processing.
|
|
|
|
|
Your program can also use the SWAREQ macro to access JFCBs and JFCBXs. It
requires your program to access the DSAB or DSABs and the TIOT or XTIOTs. You
can use the GETDSAB macro for this and you will need several mapping macros.
SWAREQ and GETDSAB are documented in z/OS MVS Programming: Authorized
Assembler Services Guide. The RDJFCB macro is designed to be simpler to use and
does not require examining system control blocks.
Some of the modifications that can be made to the JFCB include:
v Moving the creation and expiration date fields of the DSCB into the JFCB
v Modifying the number-of-volumes field in the JFCB
The number-of-volumes field can be modified only to be a value not greater
than the total number of volume serial numbers available in the JFCB and any
JFCBXs (extensions). The JFCB can have five volume serial numbers. Each JFCBX
can have 15 volume serial numbers. Whether or not a JFCBX is required and
how many JFCBXs are required is determined during data set allocation. A
JFCBX cannot be dynamically created after allocation except when a tape data
set is extended to a new volume. Therefore, the maximum value of the
number-of- volumes field is based on the JFCB and how many JFCBXs exist.
Setting the number-of-volumes field to a value greater than that maximum will
not cause a JFCBX to be dynamically created.
v Moving the DCB fields from the DSCB into the JFCB
v Adding volume serial numbers to the JFCB (see “RDJFCB Security” on page 291)
Volume serial numbers in excess of five are written to the JFCBX (extension).
The JFCBX cannot be modified by user programs.
v Modifying the sequence number field of the volume in the JFCB. For
DISP=NEW the modified volume sequence will be honored during OPEN
TYPE=J only for tape and only when the file sequence number in the JFCB is
also modified.
v Modifying the sequence number field of the data set in the JFCB. This specifies
the file for a subsequent OPEN TYPE=J to process. You can use this technique to
write many data sets on a tape volume or set of volumes. Use RDJFCB and
increase the sequence number of the data set by 1 before each OPEN TYPE=J. If
the device supports buffered tape marks, you can obtain significantly better
performance by requesting the SYNC=NONE option on the DCBE macro. It
allows the device to enter "streaming mode" and to write tape marks much
faster. A side effect is that any I/O error can be reflected at an unpredictable
time. This can result in an ABEND in OPEN or CLOSE for a user data block. It
also means that if a device malfunction occurs, it might result in the loss of more
than one data set that the application had closed previously. To position rapidly
to a tape data set other than the next data set, you can use the technique
described in “High-Speed Cartridge Tape Positioning” on page 301.
v Changing the data set name field or member field in the JFCB. See “RDJFCB
Security” on page 291 and “RDJFCB Use by Authorized Programs” on page 291.
You can open a VTOC by reading the JFCB, changing the data set name to 44
bytes of X'04' and then issuing the OPEN macro with TYPE=J. Use BSAM or
286
z/OS DFSMSdfp Advanced Services
System Macros
EXCP. If you use BSAM, also code RECFM=F, KEYLEN=44 and BLKSIZE=96 on
the DCB macro. For an extended address volume the DCB macro must point to
a DCBE where the EADSCB=OK keyword is specified. You'll find examples of
opening an EXCP DCB for a VTOC in “Example of Using the CVAFFILT Macro”
on page 107 and “Example of using the CVAFSEQ macro to process a volume in
physical sequential order” on page 129.
v Setting bit JFCDQDSP in field JFCBFLG3 to invoke the tape volume DEQ at
demount facility (see “DEQ at Demount Facility for Tape Volumes” on page 299)
v Modifying the JFCRBIDO field in the JFCB to cause high-speed positioning to a
specific data block on a tape volume on a device that supports cartridge tapes
(see “High-Speed Cartridge Tape Positioning” on page 301)
v Setting bit JFCNDSCB to prevent OPEN from merging fields from the data set
label to the JFCB. This means that you must supply the information from other
sources, such as the JFCB or the DCB. A data set label is a DSCB or standard
tape label. This bit does not control all fields. For example it does not control the
creation and expiration dates. Note that if you set this bit on, it can cause
incorrect positioning in the data set after an automatic step restart when using
DISP=MOD or the OPEN macro with the EXTEND option. Setting this bit on
can interfere with the system correcting JFCBDSCB (TTR of DSCB on first
volume). Setting this bit on is not a good programming practice because it
depends on internal system logic.
v Setting bit JFCNDCB to prevent OPEN from merging fields from the DCB to the
JFCB. This interferes with correct information being set in the data set label and
it interferes with OPEN doing certain checks. Setting this bit on is not a good
programming practice because it depends on internal system logic.
v Setting bit JFCBLKSZ to indicate that the JFCB block size field has been set to
zero by the application and that OPEN needs to set the block size value in the
SIOT extension, if applicable, to zero as well. OPEN will also reset JFCBLKSZ
off.
The secondary allocation quantity will be moved from the DSCB into the JFCB
unless prevented by the setting of JFCNWRIT or JFCNDSCB.
RDJFCB Macro Specification
The RDJFCB macro instruction moves a job file control block (JFCB) into an area of
your choice as identified by the EXLST parameter of the DCB macro for each data
control block specified.
The format of the RDJFCB macro is:
Chapter 7. Using System Macro Instructions
287
System Macros
►►
RDJFCB
label
(dcb_addr)
,
( ▼ dcb_addr
►◄
,
,
option1
,(
option1
,(
option2
,(, option2
)
)
)
)
option1:
INPUT
EXTEND
OUTPUT
INOUT
OUTIN
OUTINX
RDBACK
UPDAT
option2:
,DISP
,LEAVE
,REREAD
,REWIND
Tip: If you wish to have multiple DCBs with or without options, code each DCB
(and options) as shown in the diagram and precede each additional DCB with a
comma. Examples of the standard form of the RDJFCB macro are:
RDJFCB
RDJFCB
RDJFCB
RDJFCB
RDJFCB
RDJFCB
(DCB1)
(DCB1,INPUT)
(DCB1,(INPUT))
(DCB1,(INPUT,REREAD))
(DCB1,,DCB2)
(DCB1,,DCB2,(INPUT,REREAD),DCB3,INPUT)
Figure 31. Examples of Standard Form of the RDJFCB macro
dcb_address, or (options)
(Same as the dcb_address, option1, and option2 operands of the OPEN macro
instruction, as shown in z/OS DFSMS Macro Instructions for Data Sets), except
for the MODE operand, which is not valid with the RDJFCB macro.
The option operands do not affect RDJFCB processing. You can, however,
specify them in the list form of the RDJFCB macro instruction and refer to the
generated parameter list with the execute form of the macro.
v You can also use the MF parameter on an RDJFCB macro. Its syntax, use, and
effect are the same as is documented for the OPEN macro in z/OS DFSMS Macro
Instructions for Data Sets. In addition, you can code an execute-form RDJFCB
macro that refers to a list-form OPEN macro that does not have MODE=31.
288
z/OS DFSMSdfp Advanced Services
System Macros
v The RDJFCB parameter list, the DCB, and the JFCB area specified in the exit list
as well as the exit list itself must reside below 16 MB, although the calling
program can be above 16M.
Example
In Figure 32, the macro instruction at EX1 creates a parameter list for two data
control blocks: INVEN and MASTER. In creating the list, both data control blocks
are assumed to be opened for input; option2 for both blocks is assumed to be DISP.
The macro instruction at EX2 moves the system-created JFCBs for INVEN and
MASTER into the area you specified, thus making the JFCBs available to your
problem program for modification. The macro instruction at EX3 modifies the
parameter list entry for the data control block named INVEN and indicates,
through the TYPE=J operand, that the problem program is supplying the JFCBs for
system use.
EX1
RDJFCB (INVEN,,MASTER),MF=L
.
.
.
EX2
RDJFCB MF=(E,EX1)
.
.
.
EX3
OPEN (,(RDBACK,LEAVE)),TYPE=J,MF=(E,EX1)
.
.
.
INVEN
DCB
EXLST=LSTA,...
MASTER
DCB
EXLST=LSTB,...
LSTA
DS
0F
DC
AL1(EXLLASTE+EXLRJFCB)
DC
AL3(JFCBAREA)
.
.
.
JFCBAREA DS
0F,176C
.
.
.
LSTB
DS
0F
.
.
.
IHAEXLST ,
DCB exit list mapping
Figure 32. Example Code Using RDJFCB Macro
Multiple data control block addresses and associated options can be specified in
the RDJFCB macro instruction. This facility makes it possible to read several job
file control blocks in parallel.
An exit list address must be provided in each DCB specified by an RDJFCB macro
instruction. Each exit list must contain an active entry of either or both types
supported by RDJFCB.
RDJFCB processes the first of each of the two types of its entries in the exit list. For
example, in a three-entry list containing types 07, 07 and 13, RDJFCB will process
the first and third entries and ignore the second entry. An ignored entry has no
effect on the RDJFCB return code.
Chapter 7. Using System Macro Instructions
289
System Macros
Each of the entries is briefly explained in the following text. A full discussion of
the exit list and its use is contained in z/OS DFSMS Using Data Sets.
After RDJFCB is performed, register 15 contains one of the following codes:
Table 58. Return Codes from the RDJFCB Macro
Return Code
Meaning
0 (X'00')
4 (X'04')
RDJFCB function completed successfully.
One or more DCBs encountered one of the following
conditions and were skipped. DCBs that were not skipped
were processed successfully.
v The DCB was being processed by Open/Close/EOV or a
similar function.
v No data set with the DDNAME that is in the DCB is
allocated.
8 (X'08')
v The DCB is not open and its DDNAME is blank.
One or more DCBs had an ARL that could not be processed.
Each ARL contains a reason code describing its status.
One or more DCBs might have encountered a condition
described under return code 4. This type of ARL does not
contain a reason code.
Type 07 JFCB Exit List Entry
The type 07 JFCB exit list entry allows you to perform a variety of tasks, as
described in the following text.
The format of the type 07 JFCB exit list entry is:
Table 59. Type 07 JFCB Exit List Entry
Hexadecimal Code (High-Order Byte)
07
Contents of Exit List Entry (Three
Low-Order Bytes)
Address of a 176-byte area required if the
RDJFCB or OPEN (TYPE=J) macro
instruction is used.
The virtual storage area into which the JFCB is read must be:
v Located within the user's region
v On a word boundary
v At least 176 bytes long.
Requirement: Users running in 31-bit addressing mode must ensure that this area
is located below 16 MB virtual. Each exit list entry must be 4 bytes long. The
system recognizes only the first occurrence of an exit list entry code. Indicate the
end of the exit list by setting the high-order bit in the entry code byte to 1.
The DCB can be either open or closed when this macro instruction is executed. If
accessing concatenated sequential data sets and the DCB is open, the RDJFCB
routine reads the JFCB for the current data set. In all other cases, the RDJFCB
routine reads the JFCB for the first or only data set.
If the RDJFCB routine fails while processing a DCB associated with your RDJFCB
request, or you do not provide a virtual storage address in the three low-order
bytes of the exit list entry, your task is abnormally terminated. None of the options
290
z/OS DFSMSdfp Advanced Services
System Macros
available through the DCB ABEND exit, as described in z/OS DFSMS Using Data
Sets, are available when a RDJFCB macro instruction is issued.
RDJFCB Security: OPEN TYPE=J compares the volume serial numbers specified
in the user-supplied JFCB with the volume serial numbers in the system's copy of
the JFCB. Each different volume serial number will be enqueued exclusively. The
volumes stay enqueued until the job step terminates, because the CLOSE routines
will not dequeue the volumes. If the job step already has the volume open, OPEN
TYPE=J continues. If the volume is enqueued by another job step, an ABEND 413
occurs with a return code of X'04'.
Some JFCB modifications can compromise the security of existing
password-protected or RACF-protected data sets. The following modifications are
specifically not allowed, unless the program making the modifications is
authorized (an authorized program is one that is either in supervisor state,
executing in one of the system protection keys (keys 0 through 7), or authorized
under the authorized program facility) or can supply the password:
v Changing the disposition of a password-protected data set from OLD or MOD to
NEW.
v Changing the data set name or one or more of the volume serial numbers when
the disposition is NEW.
v Changing the label processing specifications to bypass label processing.
Changing the data set name in the JFCB has no effect on the name of the data set.
You are just referring to a different data set. If the DISP setting is NEW, it does not
cause the changed data set name to be created. If OPEN allocates the changed data
set name, it is as if the DD had DISP=OLD. To create a data set on DASD, your
program should call dynamic allocation by issuing SVC 99 (Requesting dynamic
allocation functions in z/OS MVS Programming: Authorized Assembler Services Guide).
Alternately your program might be able to use the REALLOC macro, but note that
it requires authorization and carries restrictions. See “Creating (Allocating) a DASD
Data Set Using REALLOC” on page 49.
RDJFCB Use by Authorized Programs: Except when opening a VTOC, if you
change the data set name in the JFCB and your job step is APF-authorized, you
should do a system enqueue on the major name of “SYSDSN” for the substituted
data set name. Issuing an ENQ macro for a major name of SYSDSN requires
authorization.
If your program changes the data set name or the volume serial number and is not
authorized, OPEN TYPE=J calls dynamic allocation for the new name. CLOSE will
automatically unallocate the data set.
To use the correct interface with other system functions (for example, partial
release), the ENQ macro should include the TCB of the initiator and the length of
the data set name (with no trailing blanks). When you complete processing of the
data set, you should use the DEQ macro to release the resources. If your program
is not authorized and issues an OPEN TYPE=J macro, and the substituted data set
name is already enqueued by another job step, an ABEND 913 occurs with a return
code of X'1C'.
To open a VTOC data set to change its contents (that is, open it for OUTPUT,
OUTIN, INOUT, UPDAT, OUTINX, or EXTEND), your program must be
authorized under the Authorized Program Facility (APF). APF provides security
and integrity for your data sets and programs. Details on how to authorize your
Chapter 7. Using System Macro Instructions
291
System Macros
program are provided in z/OS MVS Programming: Assembler Services Guide, z/OS
MVS Programming: Authorized Assembler Services Guide, and z/OS MVS Programming:
Assembler Services Reference ABE-HSP.
You cannot extend a VTOC by this means.
Restriction: Do not change the data set name to NULLFILE (signifying a dummy
data set). Changing the name to NULLFILE can prevent the device allocated for
the data set specified on the DD statement from being deallocated at job/step
termination.
Using BSAM or EXCP for Random I/O to a Multivolume Data Set: If you open
a BDAM DCB for a multivolume data set, OPEN links your program to all
volumes simultaneously so that your program can ignore volume boundaries and
treat all volumes of the data set as one entity. If you open a BSAM or EXCP DCB
for a multivolume data set, OPEN gives your program access to only one volume
at a time. This is true for both disk and tape. To switch to another volume, your
program issues a CHECK or FEOV macro for BSAM or EOV macro for EXCP. To
return to a previous volume, you must close and reopen the data set, which would
be slow.
Your program can use RDJFCB and OPEN TYPE=J with one DCB per volume to
process all the volumes in parallel. Your program must keep track of which DCB is
for each volume. Your program uses the RDJFCB macro to read in the JFCB, and
uses OPEN with TYPE=J to open each volume of the data set. The coding example
in Figure 33 on page 293 illustrates the procedure with EXCP DCBs.
This technique does not work for a JFCB disposition of NEW because OPEN
TYPE=J honors modifications to the JFCB volume sequence number JFCBVLSQ
only for tape and only if the JFCB file sequence is also modified.
This technique does not work with a striped data set because OPEN always opens
all volumes of a striped data set in parallel as for BDAM.
If you are using BSAM to read non-striped volumes in parallel, you should avoid
using the CHECK macro because it can automatically move to the next volume
when you reach the end of the current volume. Use WAIT or EVENTS instead of
CHECK. Refer to z/OS DFSMS Using Data Sets and z/OS DFSMS Macro Instructions
for Data Sets for information about WAIT or EVENTS. If you optimize I/O with the
MULTACC parameter of the DCBE macro, you also must issue TRUNC macros.
With tape, you cannot open more than one DCB per allocated drive. You can
calculate the number of allocated drives from the TIOT entry length or by issuing
the IEFDDSRV macro. IEFDDSRV returns the number of devices in
DVAR_NUM_DVENT. Refer to z/OS MVS Programming: Assembler Services Reference
IAR-XCT.
If your program does any of the following it will damage the data set:
v If you use BSAM and the OPEN option is not UPDAT and you issue WRITE
macros, you might cause the data set to be extended to new tracks or to the next
volume. In the latter case you have two DCBs open to one volume and they can
interfere with each other.
v If you use BSAM and the OPEN option is not UPDAT and the last operation
before CLOSE is WRITE (and CHECK, WAIT or EVENTS), then CLOSE marks
that volume as being the last volume of the data set. The result might be every
volume marked as being the last one. This is true also if you use EXCP and
292
z/OS DFSMSdfp Advanced Services
System Macros
CLOSE finds that bit 0 of DCBOFLGS is on. For EXCP, see Table 36 on page 194
and “Device-Dependent Parameters” on page 203. If a program later tries to
read the volumes of the data set sequentially, such as a program backing it up,
that program will not read past the end of this volume. In addition, a later
program trying to add records to the end of a volume by opening with the
EXTEND or OUTINX option or with the OUTPUT or OUTIN option with
DISP=MOD, can add them to the wrong volume.
If the data set is newly allocated on DASD, space has been allocated only on the
first volume unless you used the guaranteed space option of SMS. For both DASD
and tape, if the data set has not yet been written on the volume, the OPEN fails.
ALLVOLS RMODE 24
Because of DCB exit list & JFCB
RDJFCB DCB1
Read in the JFCB
LTR
R15,R15
Branch if the DD name
BNZ
NODD
is not defined
* Calculate amount of storage for one DCB per volume and get storage.
SR
R0,R0
Prepare for IC
IC
R0,JFCBNVOL
Get number of volumes
LR
R3,R0
Save number of volumes
MH
R0,=Y(DCBLNGXE) Mult by EXCP DCB length without append.
STORAGE OBTAIN,LENGTH=(0),LOC=(BELOW,ANY),ADDR=DCBAddrL
LR
R4,R1
Point to area for first DCB
LA
R5,1
Set first volume sequence number
OpenLoop STH
R5,JFCBVLSQ
Tell OPEN which volume to open
MVC
0(DCBLNGXE,R4),DCB1 Build a DCB
OPEN ((R4),UPDAT),TYPE=J Use TYPE=J for one volume
LTR
R15,R15
Branch in the unlikely event
BNZ
OpenFail
that OPEN failed
LA
R4,DCBLNGXE(,R4) Point to place for next DCB
LA
R5,1(R5)
Increment the volume counter
BCT
R3,OpenLoop
Loop until all volumes are open
.
.
.
DCB1
DCB
DDNAME=SYSUT1,MACRF=(E),EXLST=ExitL,DSORG=PS
* The following is a DCB exit list.
ExitL
DC
0F’0’,AL1(EXLLASTE+EXLRJFCB)
Last entry, for JFCB
DC
AL3(JFCB)
Address of JFCB area
DCBAddrL DS
A
Address of DCB list
JFCB
DS
CL176
JFCB READ IN HERE
ORG
JFCB+70
Go back to remap
JFCBVLSQ DS
H
Volume sequence number
ORG
JFCB+117
JFCBNVOL DS
FL1
Number of volumes allocated
ORG
,
* Mapping macro IEFJFCBN might be used instead.
DCBD DSORG=XE,DEVD=(DA,TA) Map an EXCP DCB
IHAEXLST ,
DCB exit list mapping
Figure 33. Processing a Multivolume Data Set with EXCP
Type 13 JFCB Exit List Entry
The type 13 JFCB exit list entry allows you to retrieve selected allocation
information, as described in the following text. The system will accept both a type
X'07' and a X'13' exit list entry. RDJFCB uses the first of each of them.
The format of the type 13 JFCB exit list entry is:
Chapter 7. Using System Macro Instructions
293
System Macros
Table 60. Format of the Type 13 JFCB Exit List Entry
Hexadecimal Code (High-Order Byte)
Contents of Exit List Entry (Three
Low-Order Bytes)
13
Address of an allocation retrieval list.
Using RDJFCB to Retrieve Allocation Information: RDJFCB uses DCB exit list
entry type 13 to retrieve allocation information (JFCBs and volume serial numbers)
for data sets that might be concatenated. The exit list entry code is X'13', and is
defined as “retrieve allocation information.” The second through fourth bytes of
this entry must point to an allocation retrieval list (ARL), as described in Table 61
on page 295. If you issue RDJFCB, this DCB exit list entry retrieves all JFCBs for
the specified concatenated data sets, and lists of all volume serial numbers for
these data sets. The block size, as specified on the DD statement of each data set, is
put into the extended information segment following the volume serial numbers. If
this block size field is 0, the block size of the data set is in the JFCB. You can either
select JFCBs in the concatenation or, by default, retrieve all of them. RDJFCB uses
the parameter list to receive and return information about the request. See
Figure 34 on page 298 for an example of usage.
OPEN TYPE=J does not recognize this exit list entry.
You can use the IHAARL macro (shown here) to generate and map the ARL. Your
program might issue a GETMAIN or STORAGE macro for the ARL, or, if you
specify DSECT=NO, the ARL is generated within your program's storage. The ARL
must be below 16 MB. The allocation retrieval area (ARA), acquired by RDJFCB
through a GETMAIN macro, can be above or below 16 MB.
The format of the IHAARL macro is:
►►
IHAARL
►◄
label
DSECT=
YES
NO
,PREFIX=prefix
,DESCR=
NO
YES
DSECT=YES or NO
Specifies whether the symbol at the beginning of the generated area appears
on a DSECT instruction or a DC instruction. For DSECT=NO, the symbol
appears on a DC instruction. The default is DSECT=YES.
PREFIX=prefix
Allows you to invoke the macro more than once per assembly. Specifies a
character string with which all generated symbols are to be prefixed. Do not
specify delimiters, such as quotation marks. If you omit this operand or specify
a null value, the prefix defaults to the characters ARL.
DESCR=YES or NO
Specifies whether the macro expansion includes the macro description (prolog).
The default is DESCR=NO.
Table 61 on page 295 and Table 62 on page 295 describe the formats of the
allocation retrieval list and allocation retrieval area, respectively.
294
z/OS DFSMSdfp Advanced Services
System Macros
Table 61. Format of the Allocation Retrieval List (mapped by the IHAARL macro)
Offset
Bytes
Name
Description
The following fields are set by the caller of RDJFCB.
0 (X'00')
2 (X'02')
4 (X'04')
2
2
1
0.......
1... ....
.1.. ....
ARLLEN
ARLIDENT
ARLOPT1
ARLLANY
ARLUSS
. .xx xxxx
5 (X'05')
12 (X'0C')
7
2
ARLRSVD1
ARLRETRV
14 (X'0E')
2
ARLFIRST
Length of this area. Value should be 36.
EBCDIC 'AR'
Option byte.
ARA must be below 16 MB.
ARA can be above 16 MB.
Request ARA have a path name for each
entry for which PATH was coded.
Reserved. Must be zero.
Reserved. Must be zero.
Number of data sets for which to retrieve
information. If 0, retrieve all in the
concatenation.
Number of first data set in concatenation
for which to retrieve information. 0 or 1
specifies retrieval of information
beginning with first data set in the
concatenation.
The following fields are set by RDJFCB
16
20
21
24
(X'10')
(X'14')
(X'15')
(X'18')
4
1
3
2
ARLAREA
ARLPOOL
ARLRLEN
ARLRTRVD
26 (X'1A')
2
ARLCONC
28 (X'1C')
1
ARLRCODE
29 (X'1D')
7
ARLRSVD2
Address of ARA. See Table 62.
Storage subpool containing ARA.
Length of ARA.
Number of concatenated data sets for
which JFCBs were retrieved.
Number of concatenated data sets. If no
concatenation, this value is 1.
Reason Code:
0 = Requested information was read.
The following reason codes are related to
return code 8:
4 = ARLFIRST is greater than
ARLCONC.
8 = Insufficient storage to read
information. ARLPOOL and ARLRLEN
describe what RDJFCB needs.
Reserved. Used by RDJFCB.
Table 62. Format of the Allocation Retrieval Area (mapped by the IHAARA macro)
Offset
Bytes
Name
Description
0 (X'00')
2
ARALEN
2 (X'02')
1
ARAFLG
Length of the information for this data set
(including this field). The starting address of
the ARA plus the value in the length field
designates the address of the ARA for the next
data set in the concatenation, if requested. Do
not use the length field to calculate the
number of volumes.
Flags.
Chapter 7. Using System Macro Instructions
295
System Macros
Table 62. Format of the Allocation Retrieval Area (mapped by the IHAARA macro) (continued)
Offset
Bytes
Name
Description
ARAXINF
3 (X'03')
1... ....
.xxx xxxx
1
4 (X'04')
180 (X'B4')
176(Dec)
variable
ARAJFCB
*
Extended information segment is present.
Reserved. Must be zero.
Offset in doublewords from the beginning of
the allocation retrieval area for the current data
set to the extended information segment.
JFCB
Sixth and subsequent volume serial numbers.
Determined by the value in JFCBNVOL. If the
number of volume serial numbers is fewer
than the specified volume count, entries at the
end of the list might contain all blanks. If the
first byte of an entry is X'FF', the JCL-specified
VOL=REF and the volume could not be
determined.
ARAXINOF
Extended Information Segment. The DSECT name is ARAXINFO.
0 (X'00')
2
ARAXINLN
2 (X'02')
2
ARAPATHO
4 (X'04')
8 (X'08')
4
8
ARAXLBKS
16 (X'10')
8
ARABKSLM
Length of the extended information segment
(including this field).
If other than zero, ARAPATHO is the offset
from beginning of extended information
segment to the path name (ARAPATHNAME);
in this case, the data set name in the JFCB is
meaningless. If zero, then this entry does not
contain a path name.
Reserved. Must be 0.
Block size for this data set or 0. If 0 then block
size can be found in the JFCB in ARAJFCB. If
JFCBLKSZ is set, this field will be returned
with a value of 0.
The maximum allowed value for system
determined block size (BLKSZLIM or
DFABLKSZ value in DFA). This integer value
is meaningful only if block size (BLKSIZE) is
omitted from all sources and the application
program opens for output. It is the first value
available from these sources:
1. BLKSZLIM keyword on the DD statement
or dynamic allocation.
2. Block size limit in data class. Set by storage
administrator. Available even if the data set
is not SMS-managed.
3. System default set in TAPEBLKSZLIM
keyword in DEVSUPxx member in
SYS1.PARMLIB by system programmer.
Also available in DFA.
4. 32760
24 (X'16')
16
*
The following fields are present only if ARAPATHO is non-zero:
ARAPATHNAME
296
z/OS DFSMSdfp Advanced Services
The minimum value in the current level of the
operating system is 32760.
Reserved.
DSECT
System Macros
Table 62. Format of the Allocation Retrieval Area (mapped by the IHAARA macro) (continued)
Offset
Bytes
Name
Description
x
2
ARAPATHLEN
x+2
255
257
ARAPATHNAM
ARAPNAMLEN
Length of path name, excluding any trailing
blanks. Calculate the value of x by adding the
value in the two bytes in ARAPATHO to the
address of ARAXINLN.
Path name.
Symbolic length of maximum path name
section.
When you have finished using information from the retrieval areas, you should
issue FREEMAIN or STORAGE macro to free any areas that were acquired through
GETMAIN (including the ARA, acquired by RDJFCB). When coding the
FREEMAIN or STORAGE macro, specify the length, subpool, and address values
from the ARLRLEN, ARLPOOL, and ARLAREA fields, respectively. The DSECT
name is ARAXINFO.
Code the FREEMAIN macro as shown:
FREEMAIN RU,LV=length,SP=subpool,A=address
If RDJFCB successfully fills in the ARL field, register 15 is set to zero. Otherwise
see Table 58 on page 290.
Example: In Figure 34 on page 298, the macro instruction at ALLOCINF creates a
parameter list for one DCB (INDCB), assumed to be open for input. The JFCBs and
volume serial numbers are retrieved for all data sets allocated to DDNAME
SYSLIB.
Chapter 7. Using System Macro Instructions
297
System Macros
***JCL FOR FOLLOWING INVOCATION OF RDJFCB:
//SYSLIB DD
DISP=SHR,DSN=DEPT61.MACLIB
//
DD
DISP=SHR,DSN=CORPORAT.MACLIB
//
DD
PATH=’/projects/sasp/maclib’,PATHOPTS=ORDONLY
//
DD
DISP=SHR,DSN=SYS1.MACLIB
***EXAMPLE CODE TO INVOKE RDJFCB ALLOCATION INFORMATION RETRIEVAL:
* GET A COPY OF THE JFCB FOR THE FIRST OR ONLY DATA SET ALLOCATED
* TO SYSLIB AND TRY TO READ THE JFCBS VOLUME SERIAL NUMBERS
* AND PATH NAMES FOR ALL DATA SETS ALLOCATED TO SYSLIB.
*
ALLOCINF RDJFCB (INDCB)
LTR
R15,R15
TEST RDJFCB RETURN CODE
BNZ
NOJFCB
BRANCH IF INFORMATION NOT AVAILABLE
ICM
R1,X’F’,SLBAREA GET AND TEST ADDRESS OF ARL
BZ
OLDSYSTM
GO IF SYSTEM DOES NOT SUPPORT ARL
CLI
SLBRCODE,0
TEST RDJFCB REASON CODE
BNE
NOJFCB
BRANCH IF INFORMATION NOT AVAILABLE
*
* LOOP THROUGH THE JFCBS IN THE AREA TO WHICH SLBAREA POINTS.
* CODE CAN BE INSERTED HERE TO PRINT THE DATA SET NAMES, VOLUME SERIAL NUMBERS
* AND PATH NAMES.
L
R9,SLBRTRVD
GET NUMBER OF JFCB’S RETRIEVED
L
R2,SLBAREA
POINT TO ARA
USING ARA,R2
LOOPARA TM
ARAFLG,ARAXINF
BRANCH IF NO EXTENDED
BZ
USEJFCB
INFORMATION SEGMENT
SR
R3,3
PREPARE FOR IC
IC
R3,ARAXINOF
GET DOUBLEWORD OFFSET
SLL
R3,3
GET BYTE OFFSET
AR
R3,R2
POINT TO EXTENDED INFO SEGMENT
USING ARAXINLN,R3
EXTENDED INFORMATION SEGMENT
SR
R4,R4
PREPARE FOR ICM
ICM
R4,B’0011’,ARAPATHO BRANCH IF NO PATH
BZ
USEJFCB
NAME
USING ARAPATHNAME,R4
* PRINT PATH NAME
.
.
B
NEXTARA
* PRINT DATA SET NAME IN JFCB.
USEJFCB ...
.
.
NEXTARA AH
R2,ARALEN
POINT TO NEXT ARA ENTRY
BCT
R9,LOOPARA
DECREMENT JFCB COUNTER, LOOP IF MORE
.
.
SR
R2,R2
IC
R2,SLBPOOL
SR
R0,R0
ICM
R0,B’0111’,SLBRLEN
FREEMAIN RU,LV=(0),SP=(R2),A=SLBAREA
.
.
Figure 34. Sample Code Retrieving Allocation Information Part 1 of 2
298
z/OS DFSMSdfp Advanced Services
System Macros
OLDSYSTM DS
.
.
*
NOJFCB DS
*
.
.
*
0H
ROUTINE TO HANDLE JUST LIBJFCB
0H
ROUTINE TO HANDLE INABILITY TO GET THE
JFCB. THE DATA SET MAY NOT BE ALLOCATED.
SLBOPNX DS
*
.
.
INDCB
DCB
0H
DCB OPEN EXIT ROUTINE FOR SYSLIB.
HANDLES RECFM, LRECL, AND BLKSIZE.
DSORG=PO,DDNAME=SYSLIB,MACRF=R,SYNAD=INERROR,
X
EXLST=INEXLST
0F’0’,AL1(EXLDCBEX)
ENTRY CODE FOR OPEN EXIT ROUTINE
AL3(SLBOPNX)
ADDR OF DCB OPEN EXIT ROUTINE
AL1(EXLARL)
ENTRY CODE TO RETRIEVE
ALLOCATION INFORMATION
AL3(SLBSTRT)
ADDR OF ALLOCATION RETRIEVAL LIST
AL1(EXLLASTE+EXLRJFCB) ENTRY CODE TO RETRIEVE FIRST JFCB
AND INDICATE LAST ENTRY IN LIST
AL3(LIBJFCB)
ADDR OF JFCB FOR FIRST DATA SET
INEXLST DC
DC
DC
*
DC
DC
*
DC
*
* AN ALLOCATION RETRIEVAL LIST FOLLOWS, POINTED TO BY DCB EXIT LIST.
*
SLBSTRT IHAARL DSECT=NO,PREFIX=SLB
DC
0F’0’
LIBJFCB DC
CL176’ ’
FIRST JFCB
.
IHAARA ,
IHAEXLST ,
DCB exit list mapping
Figure 35. Sample Code Retrieving Allocation Information Part 2 of 2
DEQ at Demount Facility for Tape Volumes
This facility is intended to be used by long-running programs that create an
indefinitely long tape data set (such as a log tape). Use of this facility by such a
program permits the processed volumes to be allocated to another job for
processing (such as data reduction). This processing is otherwise prohibited unless
the indefinitely long data set is closed and dynamically deallocated.
You can invoke this facility only through the RDJFCB/OPEN TYPE=J interface by
setting bit JFCDQDSP (bit 0) in field JFCBFLG3 at offset 163 (X'A3') to 1. The
volume serial of the tape is dequeued when the volume is demounted by OPEN or
EOV with message IEC502E when all the following conditions are present:
v The tape volume is verified (where a tape is considered verified after file protect,
label type, and density conflicts have been resolved) for use by OPEN or EOV
(see page “DEQ at Demount Facility for Tape Volumes” for more information
concerning verified).
v JFCDQDSP is set to 1.
v The program is APF authorized (protect key and supervisor/problem state are
not relevant).
v The tape volume is to be immediately processed for output. That is, either
OPEN verifies the volume and the OPEN option is OUTPUT, OUTIN, or
Chapter 7. Using System Macro Instructions
299
System Macros
OUTINX; or EOV verifies the volume and the DCB is opened for OUTPUT,
OUTIN, INOUT, or EXTEND, and the last operation against the data set was an
output operation (DCBOFLWR is set to 1).
For EOV to find JFCDQDSP set to 1, the program must not inhibit the rewrite of
the JFCB by setting bit 4 of JFCBTSDM to 1.
The tape volume is considered verified after file protect, label type, and density
conflicts have been resolved. The volume is dequeued when demounted after this
verification, even if further into OPEN or EOV processing the volume is rejected
because of expiration date, security protection, checkpoint data set protection, or
an I/O error.
When the volume serial is dequeued, the volume becomes available for allocation
to another job. However, because the volume DEQ is performed without
deallocating the volume, care must be exercised both by the authorized program
and the installation to prevent misuse of the DEQ at demount facility. A discussion
of such misuse follows:
v The authorized program must not close and reopen the data set using the tape
volume DEQ at demount facility, if it does, one of the following can occur:
– The dequeued volume can be mounted and in use by another job. When the
volume is requested for mounting, for the authorized program, the operator is
unable to satisfy the mount. Therefore, the operator must either cancel the
requesting job, cancel the job using the volume, wait for the requesting job to
time out, or wait for the job using the volume to terminate.
– The dequeued volume can be allocated to another job, but not yet in use. The
operator mounts the volume to satisfy the mount request of the authorized
job. When the volume is requested for mounting by the other job, the
operator is unable to satisfy the mount request, and is faced with the same
choices as in the previous item.
– The dequeued volume can not yet be allocated to another job and the volume
is mounted to satisfy the mount request of the authorized job. Another job
can allocate the volume and, when the volume is requested for mounting, the
situation is the same as in the previous item.
It is the responsibility of the installation that permits a program to run with APF
authorization to ensure that it does not close and reopen a data set using the
DEQ at demount facility.
v Care should be exercised when an authorized program uses the DEQ at
demount facility (data set 1), but processes another tape data set (data set 2).
Assume the same volume serial numbers have been coded in the DD statements
for data set 1 and data set 2. As the volumes of data set 1 are demounted, they
are dequeued even though those volumes still might be requested for data set 2.
All the problems explained in the preceding list can occur as data set 2 and
another job contend for a dequeued volume.
This problem should not occur, given the intended use of the DEQ at demount
facility; that is, a long-running application creating an indefinitely long tape data
set. This type of application is not normally invoked through batch execution
with user-written DD statements.
v After a volume has been demounted and dequeued because of the DEQ at
demount facility, the volume is not automatically rejected by the control
program when mounted in response to a specific or nonspecific mount request.
Without the use of the facility, the control program can recognize (by the ENQ)
that the volume is in use, and reject the volume. Therefore, operations
procedures, in effect to prevent incorrect volumes from being mounted, should
300
z/OS DFSMSdfp Advanced Services
System Macros
be reviewed in the light of reduced control program protection from such errors
when the DEQ at demount facility is used. Specifically, if a volume is remounted
for an authorized program and the volume had been used previously by that
authorized program, duplicate volume serial numbers will exist in the JFCB, and
the control program will be unable to release the volume during EOV
processing.
v Checkpoint/restart considerations are discussed in z/OS DFSMSdfp
Checkpoint/Restart.
High-Speed Cartridge Tape Positioning
High-speed positioning for cartridge tape is available when opening a tape data set
on an IBM standard-labeled tape for either EXTEND (OUTINX, EXTEND, or
DISP=MOD). High-speed positioning is also available when opening to the
beginning of such a data set. To invoke high-speed positioning, your program
must modify certain fields in the JFCB and use OPEN TYPE=J to open the data set.
When you write or read on an IBM 3590 Model A60 at the right hardware level it
is not important to use the procedure described here. The magnetic tape subsystem
gives these performance benefits automatically. This procedure will not degrade
performance.
Tip: On an IBM 3480, IBM 3490, or older models of IBM 3590, this technique offers
significantly better performance than the technique for setting the data set
sequence number. In addition, systems with DFSMSrmm use this faster technique
automatically for all cartridge tapes. For the IBM 3590 Model A60, both techniques
give high performance.
Use the following procedure to modify the JFCB:
1. Issue the RDJFCB macro to have the system move the JFCB into your work
area.
2. Set the JFCPOSID flag in the JFCBFLG3 flag byte to indicate that you are
providing a block ID for a high-speed search.
3. Move the block ID into the JFCRBIDO field of the JFCB. If you are opening to
the beginning of a data set, use the block ID of the first header label record of
that data set. If you are opening to the end of a data set (for example, to extend
it), use the block ID of the tape mark immediately following the last block of
user data in that data set.
4. Issue the OPEN TYPE=J macro to have the system use your modified JFCB.
After the tape is positioned, OPEN processes the trailer labels for the data set
being extended.
If you set the JFCPOSID flag off, OPEN positions the volume normally, as though
the high-speed positioning feature were not active.
If you set the JFCPOSID flag on, but do not provide a block ID in the JFCRBIDO
field, OPEN positions the volume normally and does one of the following:
v If you are opening to the beginning of a data set, OPEN inserts the block ID of
the first header label record of that data set into the JFCRBIDO field.
v If you are opening to the end of the data set, OPEN inserts the block ID of the
tape mark immediately following the last block of user data for that data set into
the JFCRBIDO field.
OPEN does not update your copy of the JFCB. To retrieve the new value in the
system's copy of the JFCB, issue RDJFCB after OPEN.
Chapter 7. Using System Macro Instructions
301
System Macros
If the JFCPOSID flag is on during CLOSE processing, (because you set it on before
OPEN), CLOSE inserts the block ID for the first header label record of the next
data set (which might not exist) into the JFCRBIDC field. Therefore, if you
unallocate the cartridge tape device and want to use the current block ID for
subsequent processing, save the block ID before you close the data set.
OPEN resets the JFCPOSID flag if any one of the following conditions exists:
v Your program issues an OPEN which is not TYPE=J
v The requested tape volume is not an IBM standard-labeled volume
v The requested unit is not a buffered tape device.
Exceptions:
1. If you specify dynamic deallocation (with SVC99, FREE=CLOSE on the DD
statement, or the FREE option on the CLOSE macro), the block ID for the next
data set will not be available to your program.
2. When using high-speed positioning, specify the data set sequence number
normally, either explicitly by LABEL=(seqno,SL) on the DD statement, or by
default.
After the system routines have used the JFCRBIDO field for high-speed
positioning, they clear JFCRBIDO in the system's copy of the JFCB to prevent
misinterpretation during a subsequent OPEN.
OPEN - Initialize Data Control Block for Processing the JFCB
The OPEN macro instruction initializes one or more data control blocks (DCBs) so
that their associated data sets can be processed.
A full explanation of the operands of the OPEN macro instruction is contained in
the publication z/OS DFSMS Macro Instructions for Data Sets. The TYPE=J option,
because it is used in conjunction with modifying a JFCB, should be used only by
the system programmer or under the system programmer's supervision.
The format of the OPEN TYPE=J macro is:
302
z/OS DFSMSdfp Advanced Services
System Macros
►►
OPEN
label
(dcb_addr)
,
( ▼ dcb_addr
►◄
,
, option1
,(
option1 )
,(, option2
)
)
,TYPE=J
option1:
INPUT
EXTEND
OUTPUT
INOUT
OUTIN
OUTINX
RDBACK
UPDAT
option2:
DISP
LEAVE
REREAD
REWIND
Tip: If you wish to have multiple DCBs with or without options, code each DCB
(and options) as shown in the diagram and precede each additional DCB with a
comma.
OPEN
OPEN
OPEN
OPEN
OPEN
OPEN
(DCB1),TYPE=J
(DCB1,INPUT),TYPE=J
(DCB1,(INPUT)),TYPE=J
(DCB1,(INPUT,REREAD)),TYPE=J
(DCB1,,DCB2),TYPE=J
(DCB1,,DCB2,(INPUT,REREAD),DCB3,INPUT),TYPE=J
Figure 36. Examples of Standard Form of the OPEN TYPE=J Macro
TYPE=J
Specifies that, for each DCB referred to, you have supplied a job file control
block (JFCB) to be used during initialization. A JFCB is an internal
representation of information in a DD statement.
During initialization of a data control block, its associated JFCB can be
modified with information from the DCB or an existing data set label or with
system control information.
When the TYPE=J operand is specified, also supply a DD statement. However,
the amount of information that is given in the DD statement is at your
discretion, because you can modify many fields of the system-created JFCB. If
you specify DUMMY on your DD statement, the open routine ignores the JFCB
DSNAME and opens the data set as dummy. (See Figure 32 on page 289 for an
example of coding that modifies a system-created JFCB.) The DD statement
Chapter 7. Using System Macro Instructions
303
System Macros
must specify at least the device allocation (see z/OS MVS JCL User's Guide for
methods of preventing share status) and a ddname corresponding to the
associated DCB DCBDDNAM field.
The MODE operand is not shown here because it is not allowed with the TYPE=J
operand of the OPEN macro instruction.
Since OPEN with TYPE=J does not accept a JFCBX from the caller, you cannot
change volume serials after the first five volumes.
OPEN TYPE=J will not change the volume attributes (PRIVATE, PUBLIC, or
STORAGE) which are assigned to the volume during allocation. For example, if a
volume status of PRIVATE is needed but allocation is going to assign a status of
PUBLIC, then VOL=PRIVATE should be specified on the DD statement.
Purging and Restoring I/O Requests (PURGE and RESTORE macros)
The system's purge routines perform either a halt or a quiesce operation. In a halt
operation, the purge routines stop the processing of specified I/O requests initiated
with an EXCP or EXCPVR macro instruction. In a quiesce operation, the purge
routines includes the following procedures:
v Allow the completion of I/O requests (initiated with an EXCP or EXCPVR
macro instruction) that were passed to the system for execution and are
executing
v Stop the processing of requests that have not yet been initiated or passed to the
system, but save the IOBs of the requests so they can be reprocessed (restored)
later.
The system's restore routines make it possible to reprocess I/O requests that are
quiesced.
Restriction: Purge and restore processing performed for I/O requests that are not
initiated by an EXCP or EXCPVR macro is not covered here. User applications that
use the PURGE and RESTORE macros with the sequential access method (SAM)
against partitioned data sets (PDSs) (for example, to synchronize the I/O) cannot
do so against PDSEs, sequential extended format data sets, or z/OS UNIX files,
because SAM does not use EXCP or EXCPVR to access these types of data.
To pass control to the purge and restore routines, build a parameter list and place
its address in register 1, then issue the macro instruction.
24-bit or 31-bit addressing mode can be used for the PURGE or RESTORE macro
(and the parameter list).
PURGE Macro Specification
The PURGE macro is used to halt or finish I/O requests.
Refer to “General-Use Mapping Macros” in z/OS MVS Programming: Authorized
Assembler Services Reference ALE-DYN for information about using the 31-bit
interface provided by the PURGE function.
The format of the PURGE macro is:
304
z/OS DFSMSdfp Advanced Services
System Macros
►►
PURGE parameter_list_address
►◄
label
parameter_list_address—RX-type address, (2-12) or (1)
Address of a parameter list, 12 or 16 bytes long, that you have built on a word
boundary in storage. The parameter list address can be specified as an RX-type
address or in registers 2 through 12, or 1. The name of the mapping macro is
IECDPPL.
The format and contents of the parameter list are as follows:
Byte
Contents
0
A byte that specifies the actions of the purge routines. The bit settings and
their meanings are:
1... .... Purge I/O requests to a single data set. The setting of this bit only
takes effect if bit 2 of byte 12 is 0 and bit 6 of byte 0 is 0.
0... .... Either purge I/O requests associated with a TCB or address space,
or purge I/O requests to more than one data set. If bit 2 of byte 12
is 1, then the request is to purge I/O associated with an address
space. If bit 2 of byte 12 is 0 and bit 6 of byte 0 is 1, then the
request is to purge I/O associated with a TCB. If bit 2 of byte 12 is
0 and bit 6 of byte 0 is 0, then the request is to purge I/O to more
than one data set.
.1.. .... Post ECBs associated with purged I/O requests.
..1. .... Halt I/O-request processing. (Quiesce I/O-request processing, if 0.)
...1 .... Purge related requests. (Only valid if a data-set purge is
requested.)
.... 0... Reserved—must be zero.
.... .1.. Do not purge the TCB request-block chain of asynchronously
scheduled processing.
.... ..1. Purge I/O requests associated with a TCB. The setting of this bit
will only take affect if bit 2 of byte 12 is 0.
.... ...1 This is a 16-byte parameter list. Additional purge options are
specified in bytes 12 to 15. (If this bit is off, the list is 12 bytes long,
and the purge routines do not put a return code in byte 4 of this
list or in register 15.)
1,2,3
The address of a DEB when purging I/O requests to a single data set. The
address of the first DEB in a chain of DEBs when purging I/O requests to
more than one data set. (The next-to-the-last word of each DEB must point
to the next DEB in the chain; the second word of the last DEB must
contain zeros.)
4
A byte of zeros. (If bit 7 of byte 0 is on, the purge routines will put a code
in byte: X'7F' when the purge operation is successful; X'40' when it is not
successful. If bit 7 of byte 0 is off, then X'7F' appears in this byte.)
5,6,7
If you turned on bit 6 of byte 0, the address of the TCB associated with the
I/O requests you want purged. Will be zeros if the TCB is the one you are
running under.
8
Value of X'00' or X'02' means that EXCP is the owner.
9,10,11 The address of a word in storage or the address of the DEBUSPRG field
(that is X'11' bytes more than the DEB address in this parameter list). At
the address you specify, the purge routines store a pointer to the purged
Chapter 7. Using System Macro Instructions
305
System Macros
I/O restore list, that in turn contains a pointer to the first IOB in the chain
of IOBs. The location of the pointer and format of the chain are shown in
Figure 37 on page 307.
Note: This field is only relevant for quiesce options.
12
A byte that allows you to specify additional purge options. The bit settings
and their meanings are:
Note: The following applies only if bit 7 of byte 0 is set to 1.
..1. .... Purge I/O requests associated with an address space. (Your
program must be in supervisor state.) The setting of this bit will
take affect regardless of the setting of bit 6 of byte 0 and bit 0 of
byte 0.
...1 .... If this is a data-set purge, check the validity of all the DEBs
associated with the purge operation. Validate this parameter list,
whatever the type of purge operation, by ensuring that there are
no inconsistencies in the selection of purge options. (If your
program is in problem state, these actions are taken regardless of
the bit setting.)
.... 1... Ensure that I/O requests will be reprocessed (restored) under their
original TCB. (If zero, and bit 7 of byte 0 is on, the I/O requests
are reprocessed under the TCB of the program making the restore
request.)
.... .0.. Must be zero.
13
A byte of zeros.
14,15
If bit 2 of byte 12 is on, the 2-byte ID of the address space associated with
the I/O requests you want purged.
Control is returned to your program at the instruction following the PURGE macro
instruction.
Return Codes from PURGE
If the purge operation was successful, register 15 contains zeros. Otherwise,
register 15 contains one of the following return codes:
Return Code
Meaning
4 (X'04')
Your request to purge I/O requests associated with a given
TCB was not honored because that TCB did not point to the
job step TCB, while the requester is in problem state.
Either you requested an address-space purge operation, but
were not in supervisor state, or you requested a data set
purge operation, but failed to supply a DEB address in bytes
1, 2, and 3 of the purge parameter list.
Another purge request has preempted your request. You
might want to reissue your purge request in a
time-controlled loop.
8 (X'08')
20 (X'14')
Exception: If you set bit 7 in byte 0 of the parameter list to zero, register 15 will
contain zeros, regardless of the outcome of the purge operation.
Modifying the IOB Chain
This procedure is not recommended. However, to change the order in which
purged I/O requests are restored or prevent a purged request from being restored,
you can change the sequence of IOBs in the IOB chain or remove an IOB from the
306
z/OS DFSMSdfp Advanced Services
System Macros
chain. The address of the IOB chain can be obtained from the purge I/O restore list
(see Figure 37).(The address of the purge I/O restore list is shown at bytes 9
through 11 of the purge parameter list.) Note that some IOBs could be in a
different protection key.
Purge I/O Restore List
┌──────────────────────────────────────────────┐
³
³
³
20(X’14’)
³
³
┌───────────────────────────────────┐
³
┌────┼─────┤ Pointer to the first IOB. If 1s, ³
³
³
³
³ no I/O request was quiesced.
³
³
³
³
└───────────────────────────────────┘
³
³
³
³
³
└──────────────────────────────────────────────┘
³
└───→IOB(1) (where 1 is first IOB in chain)
┌──────────────────────────────────────────────┐
³
³
³
IOBRESTR 25(19)
³
³
┌───────────────────────────────────┐
³
┌────┼─────┤ Pointer to the next IOB in the
³
³
³
³
³ chain.
³
³
┴
³
└───────────────────────────────────┘
³
┬
³
³
³
└──────────────────────────────────────────────┘
³
└───→IOB(n) (where n is last IOB in chain)
┌──────────────────────────────────────────────┐
³
³
³
IOBRESTR 25(19)
³
³
┌───────────────────────────────────┐
³
³
³ Contains binary 1s.
³
³
³
³
³
³
³
└───────────────────────────────────┘
³
³
³
└──────────────────────────────────────────────┘
Figure 37. The IOB Chain
RESTORE Macro Specification
The RESTORE macro is used to reprocess I/O requests.
The format of the RESTORE macro is:
►►
RESTORE
restore_address
►◄
label
restore_address—RX-type address, (2-12) or (1)
Address that you specified at byte 9 of the purge parameter list. See “PURGE
Macro Specification” on page 304 for information about byte 9.
Performing Track Calculations (TRKCALC macro)
The TRKCALC macro performs DASD track capacity calculations. This macro is
intended for EXCP applications and other advanced applications. You can use
TRKCALC to determine:
v The number of equal-length records that can be written on a track
Chapter 7. Using System Macro Instructions
307
System Macros
v The total track capacity
v Whether a record can be written in the space remaining on a track and return
the new track balance
v What the track balance would be if the last record were removed from a track
v The length of the longest possible record that can be written to a track.
The TRKCALC routine issues no SVC instructions or I/O. TRKCALC can be called
in an SRB routine or in TCB mode. It can be called in 24-bit or 31-bit addressing
mode and in supervisor or problem state.
TRKCALC works equally well for any track. It does not use the address of the
track.
Using TRKCALC
This information provides an overview of how to use TRKCALC to accomplish
various tasks. See “TRKCALC Macro Specification” on page 309 for details on how
to code the TRKCALC parameters and on how output is returned.
Determining the number of equal-length records that can be
written on a track
To determine the number of equal-length records that can be written on a track,
code TRKCALC with FUNCTN=TRKCAP. You must specify the number of existing
records on the track and the key and data length of the new records (using either
the R, K, and DD keywords or the R, K, and DD bytes in the RKDD parameter).
If you wish to regard the track as being empty, specify an R value of 1. Otherwise,
specify an R value that is one greater than the number of existing records on the
track.
If the length of any existing record differs from the length of the new records (as
specified in the DD value), then code the BALANCE parameter. Otherwise, omit
the BALANCE parameter.
Determining the total track capacity
To determine the total track capacity, code
FUNCTN=TRKBAL,REMOVE=YES
and either R=1 or the R byte in RKDD set to 1.
Note: This value is useful only as input for the BALANCE parameter on later calls
to TRKCALC to represent an empty track. You cannot write a record of this size.
Determine whether a record can be written in the space
remaining on a track and return the new track balance
To determine whether a record can be written in the space remaining on the track
and return the new track balance, code
FUNCTN=TRKBAL,REMOVE=NO
and the BALANCE parameter. You can supply this new track balance with the
BALANCE parameter on a later call to TRKCALC.
308
z/OS DFSMSdfp Advanced Services
System Macros
Determine the track balance if the last record were removed from
a track
To determine what the track balance would be if the last record were removed
from the track, code FUNCTN=TRKBAL and REMOVE=YES. Use the R, K and DD
parameters or the RKDD parameter to identify the record to be removed. It must
be the last record on the track.
Determine the length of the longest possible record that can be
written on a track
To determine the length of the longest possible record that can be written on a
track, code FUNCTN=TRKBAL, REMOVE=NO, MAXSIZE=YES. You must specify
the number of existing records on the track (using either the R keyword or the
RKDD parameter) and a data length of X'FFFF' (using either the DD keyword or
the RKDD parameter). The DD value of X'FFFF' is greater than is supported on
any disk. Expect a return code 8, which means that the record does not fit and
TRKCALC returned the size of the largest possible record.
If you wish to regard the track as being empty, specify an R value of 1.
If the track is not empty, specify an R value that is one greater than the number of
existing records on the track and code the BALANCE parameter. In this case,
TRKCALC will give return code 8 and the length of the longest possible record
that will fit on the rest of the track.
Note: The value returned might be larger than what is supported by any access
method other than EXCP.
Restrictions
Non-EXCP user applications cannot expect consistent information from TRKCALC
for PDSEs, because of the unique structure and format of PDSEs. However,
processing will complete without error indications.
TRKCALC does not support z/OS UNIX files. You will receive unpredictable
results if you use TRKCALC for z/OS UNIX files.
TRKCALC Macro Specification
The standard, list, execute, and DSECT forms of the macro are described. Examples
of the TRKCALC macro follow the macro descriptions.
TRKCALC—Standard Form
The format of the TRKCALC macro is:
Chapter 7. Using System Macro Instructions
309
System Macros
►► listname
TRKCALC
FUNCTN=
TRKBAL
TRKCAP
,DEVTAB=addr
,UCB=addr
,TYPE=addr
►
►
►
,BALANCE=addr
,LOC=
►
,MAXSIZE=
NO
YES
,REGSAVE=
NO
YES
BELOW
ANY
,REMOVE=
NO
YES
,RKDD=addr
,R=addr ,K=addr ,DD=addr
►
►
►◄
I
,MF=
FUNCTN=TRKBAL or TRKCAP
Specifies the function to be performed. Specify one of the three keywords,
DEVTAB, UCB, or TYPE, to provide the information source for the macro.
TRKBAL
If REMOVE=NO is specified, TRKBAL calculates whether an additional
record fits on the track and what the new track balance would be if the
record were added. If REMOVE=YES is specified, TRKBAL calculates what
the track balance would be if a record were removed from the track. The
record to be added or removed from the track is defined by the RKDD
parameter, or by the R, K, and DD parameters.
If R is equal to 1 (or the R value in the RKDD parameter is 1) and
REMOVE=NO is specified, TRKCALC will treat record 1 as if it were being
added to an empty track; if R is equal to 1 and REMOVE=YES is specified,
TRKCAL will treat record 1 as if it were being deleted from the track,
leaving an empty track.
If R is not equal to 1, the specified record is added to or removed from the
track. If the input track balance is not supplied through the BALANCE
parameter, it is assumed that the track contains equal-sized records as
specified in the RKDD parameter (or in the R, K, and DD parameters).
When REMOVE=NO is specified, one of the following occurs:
v If the record fits on the track, register 0 contains the new track balance.
v If the record does not fit on the track and MAXSIZE=NO is specified, a
record does not fit return code is placed in register 15.
v If the record does not fit and MAXSIZE=YES is specified, one of the
following happens:
– The data length of the largest record that fits in the remaining space
is returned in register 0.
– A code is returned that indicates no record fits in the remaining
space.
When REMOVE=YES is specified, one of the following occurs:
v If R is equal to 1, register 0 contains the track capacity.
v If R is not equal to 1, registers 0 contains the input track balance
(supplied through the BALANCE parameter) incremented by the track
310
z/OS DFSMSdfp Advanced Services
System Macros
balance used by the input record. If the input balance is not supplied,
register 0 contains the track capacity left after R–1 records are written on
the track.
TRKCAP
Calculates, and returns in register 0, the number of fixed-length records
that can be written on a whole track (R is equal to 1) or on a
partially-filled track (R is not equal to 1). The records are defined by the K
and DD values of the RKDD parameter, or by the K and DD parameters.
Depending on the value for R, one of the following occurs:
v If R is equal to 1, TRKCALC ignores the BALANCE parameter and
makes the calculation as if the track were empty.
v If R is not equal to 1 and the BALANCE parameter is omitted, the
calculation is made for a track that already contains R–1 records of the
length defined by the K and DD values.
v If R is not equal to 1 and the BALANCE parameter is supplied, the
calculation is made for a track whose remaining track balance is the
value of the BALANCE parameter.
DEVTAB=addr—RX-type address, (2-12), (0), (14)
addr specifies a word that contains the address of the device characteristics
table entry (DCTE). If you specify a register, it contains the actual address of
the DCTE. The address of the DCTE can be found in the word beginning at the
DCBDVTBL field of an opened DCB.
UCB=addr—RX-type address, (2-12), (0), (14)
addr specifies the address of a word that contains the address of the UCB. If
you specify a register, it contains the actual address of the UCB.
The TRKCALC macro accepts the address of a UCB or UCB copy.
Unauthorized programs can get a copy of the UCB by using the UCBSCAN
macro and specifying the COPY and UCBAREA keywords. See z/OS HCD
Planning for more information.
TYPE=addr—RX-type address, (2-12), (0), (14)
You can specify the address of the UCB device type (UCBTBYT4), or you can
specify the 1-byte UCB device type in the low-order byte of a register.
LOC=BELOW or ANY
Optional parameter indicating whether the value passed by the UCB parameter
is a 4-byte or a 3-byte address. This parameter only applies to callers running
in AMODE 31. If the caller is running in AMODE 24, this parameter is ignored
and the high-order byte is treated as X'00'.
BELOW
The UCB parameter contains a UCB address for a UCB which resides in
storage below 16 megabytes, or a captured UCB. This is the default.
If LOC=BELOW is specified, the high-order byte of the UCB address will
be treated as X'00'.
ANY
The address passed in the UCB parameter contains a 3-byte or 4-byte UCB
address.
If LOC=ANY is specified when invoking in 31-bit mode, TRKCALC will
treat the UCB address as a 31-bit address.
BALANCE=addr—RX-type address, (2-12), (0), (14)
You can specify either the address of a halfword containing the current track
Chapter 7. Using System Macro Instructions
311
System Macros
balance, or you can specify the balance in the low-order two bytes of a register.
The value supplied could be the value returned when you last issued
TRKCALC. If R is equal to 1, the balance is reset to track capacity by
TRKCALC, and your supplied value is ignored. This is an input value and is
not modified by the TRKCALC macro. The resulting track balance is returned
in register 0 and in the TRKCALC parameter list field STARBAL. The value
you supply for this parameter must be a valid value for the device type in use.
REMOVE=YES or NO
Indicates if a record is to be deleted from the track.
YES
Specifies that the record identified by the record number (specified in the R
keyword) is being deleted from the track. The track balance is incremented
instead of decremented.
YES is valid only on a FUNCTN=TRKBAL call.
NO Specifies that a record is not to be deleted from the track. NO is the
default.
MAXSIZE=YES or NO
YES
If the specified record does not fit, the largest length of a record with the
specified key length that fits is returned (register 0).
YES is valid only on a FUNCTN=TRKBAL call.
NO Maximum size is not returned. NO is the default.
RKDD=addr—RX-type address, (2-12), (0), (14)
addr specifies a word containing a record number (1 byte), key length (1 byte),
and data length (2 bytes) (bytes 0, 1, and 2 and 3, respectively) or a register
containing the record number, key length, and data length. R, K, and DD can
be specified by this keyword, or you can use the following three keywords
instead.
R=addr—RX-type address, (2-12), (0), (14), or n
You can specify either the address of the record number, or you can specify
the record number using the low-order byte of a register or immediate
data (n). Specify a decimal digit for n (immediate data).
K=addr—RX-type address, (2-12), (0), (14), or n
You can specify either the address of a field containing the hexadecimal
value of the record's key length, or you can specify the record's key length
using the low-order byte of a register or immediate data (n). Specify a
decimal digit for n (immediate data).
DD=addr—RX-type address, (2-12), (0), (14), or n
You can specify either the address of a field containing the hexadecimal
value of the record's data length, or you can specify the record's data
length using the low-order two bytes of a register or immediate data (n).
Specify a decimal digit for n (immediate data).
REGSAVE=YES or NO
Specifies whether registers are to be saved.
YES
Specifies registers 1 through 14 are saved and restored in the
caller-provided save area (pointed to by register 13) across the TRKCALC
call. Otherwise, registers 1, 9, 10, 11, and 14 are modified. Registers 0 and
15 are always modified by a TRKCALC call.
312
z/OS DFSMSdfp Advanced Services
System Macros
NO Specifies registers are not saved across a TRKCALC call. NO is the default.
MF=I
Specifies storage definition for the TRKCALC parameter list and parameter list
initialization, using the given keywords, then calling the TRKCALC function.
MF=I is the default.
TRKCALC—Execute Form
A remote parameter list is referred to and can be modified by the execute form of
the TRKCALC macro. The TRKCALC routine is called. The function of the
operands is the same as for the standard form.
The format of the execute form of the TRKCALC macro is:
►►
TRKCALC
label
►
FUNCTN=
TRKBAL
TRKCAP
,DEVTAB=
,UCB=
,TYPE=
addr
*
addr
*
addr
*
►
►
,LOC=
BELOW
ANY
,BALANCE=
addr
*
,REMOVE=
NO
YES
►
►
,MAXSIZE=
NO
YES
,REGSAVE=
NO
YES
►
,RKDD=addr
,R=addr ,K=addr ,DD=addr
,MF= (E,addr)
►◄
FUNCTN=TRKBAL or TRKCAP
Is coded as shown in the standard form. If this keyword is omitted, any
specification of REMOVE, MAXSIZE, LAST, and the RX form of BALANCE is
ignored. In addition, DEVTAB is assumed if UCB is coded and a failure occurs,
or if TYPE is specified. When you use FUNCTN, one of the keywords
(DEVTAB, UCB, or TYPE) must be specified to provide an information source.
DEVTAB=addr or *—RX-type address, (2-12), (0), (14)
Is coded as shown in the standard form except for the * subparameter. Specify
an * when you have inserted the address of the device characteristics table
entry (DCTE) in the parameter list.
UCB=addr or *.—RX-type address, (2-12), (0), (14)
Is coded as shown in the standard form except for the * subparameter. Specify
an * when you have inserted the address of the UCB in the parameter list.
The TRKCALC macro accepts the address of a UCB or UCB copy.
Unauthorized programs can get a copy of the UCB by using the UCBSCAN
macro and specifying the COPY and UCBAREA keywords. See z/OS HCD
Planning for more information.
Chapter 7. Using System Macro Instructions
313
System Macros
TYPE=addr or *—RX-type address, (2-12), (0), (14)
Is coded as shown in the standard form except for the * subparameter. Specify
an * when you have inserted the address of the UCB type (UCBTYP) in the
parameter list.
LOC=BELOW or ANY
Is coded as shown in the standard form.
BALANCE=addr or *—RX-type address, (2-12), (0), (14)
Is coded as shown in the standard form except for the * subparameter. Specify
an * when you have inserted the balance in the parameter list.
REMOVE=YES or NO
Is coded as shown in the standard form.
MAXSIZE=YES or NO
Is coded as shown in the standard form.
RKDD=addr—RX-type address, (2-12), (0), (14)
Is coded as shown in the standard form.
R=addr—RX-type address, (2-12), (0), (14) or n
Is coded as shown in the standard form.
K=addr—RX-type address, (2-12), (0), (14), or n
Is coded as shown in the standard form.
DD=addr—RX-type address, (2-12), (0), (14), or n
Is coded as shown in the standard form.
REGSAVE=YES or NO
Is coded as shown in the standard form.
MF=(E,addr)
This operand specifies that the execute form of the TRKCALC macro
instruction and an existing data management parameter list are used.
E
Coded as shown.
addr—RX-type address, (0), (1), (2-12), or (14)
Specifies the address of the parameter list.
TRKCALC—List Form
The list form of the TRKCALC macro constructs an empty, in-line parameter list.
By coding only MF=L, you construct a parameter list, and the actual values can be
supplied by the execute form of the TRKCALC macro. Any parameters other than
MF=L are ignored.
The format of the list form of the TRKCALC macro is:
►►
TRKCALC
MF=L
►◄
label
TRKCALC—DSECT Only
This call gives a symbolic expansion of the parameter list for the TRKCALC macro.
No DSECT statement is generated. If a name is specified on the macro call, it
applies, after any necessary boundary alignment, to the beginning of the list. The
macro-generated symbols all begin with the characters STAR.
314
z/OS DFSMSdfp Advanced Services
System Macros
The format of the DSECT form of the TRKCALC macro is:
►►
TRKCALC
MF=D
►◄
label
Input Register Usage for All Forms of MF
Register
Use
0, 2-12, 14
Available to provide input for keywords.
1
Only to provide the address of the parameter list for an MF=E call.
13
Input for keywords if REGSAVE=YES is not specified.
15
Work register to build the TRKCALC parameter list for the MF=E call; it is
not available as an input register.
Output from TRKCALC
FUNCTN=TRKBAL:
Output
Meaning
R15=X'00'
The record fits on the track. Register 0 and STARBAL contain the new
track balance.
R15=X'04'
Record does not fit on the track. If MAXSIZE=YES is specified, a partial
record does not fit either. Register 0 and STARBAL are set to zero.
R15=X'08'
Record does not fit on the track. MAXSIZE=YES is specified, and a partial
record does fit. Register 0 and STARBAL are set to the maximum number
of data bytes that fit on the remainder of the track with the specified key
length.
The key length is excluded from the count of maximum data bytes.
R15=X'0C'
The user supplied a device type, but the device characteristics table
indicated that no device of that type was generated on the system. Register
0 is set to zero.
STARBAL
This is the track balance field of the TRKCALC parameter list. This field is
first set to the track capacity if R is equal to 1, or to the supplied
BALANCE value if R is not equal to 1, or to the calculated balance if R is
not equal to 1 and BALANCE are omitted. STARBAL is updated to the
new track balance if the record fits; otherwise, STARBAL is left with the
input track balance value.
FUNCTN=TRKCAP :
Output
Meaning
Chapter 7. Using System Macro Instructions
315
System Macros
R15=X'00'
Register 0 contains the number of records that fit on the track if R is equal
to 1, or the number of records that fit on the remainder of the track if R is
not equal to 1.
R15=X'04'
No records of the length specified fit on a full track (R is equal to 1) or a
partial track (R is not equal to 1). Register 0 is set to zero.
R15=X'0C'
The user supplied a device type, but the device characteristics table
indicated that no device of that type was generated on the system. Register
0 is set to zero.
STARBAL
This is the track balance field of the TRKCALC parameter list. This field is
first set to the track capacity if R is equal to 1, or to the supplied
BALANCE value if R is not equal to 1, or to the calculated balance if R is
not equal to 1 and BALANCE is omitted. STARBAL is updated to the new
track balance if the record fits; otherwise, STARBAL is left with the input
track balance value when the request specified MAXSIZE=NO or was
defaulted to MAXSIZE=NO. If the record does not fit on the track with
MAXSIZE=YES specified, STARBAL is set to the maximum number of data
bytes of a partial record that can fit on the remainder of the track with the
specified key length (Register 15 set to 8) or STARBAL is set to zero when
a partial record could not fit on the remainder of the track (Register 15 set
to 4).
Return Codes from TRKCALC
The TRKCALC macro passes a return code in register 15. The return codes and
their meanings are as follows:
Return Code
Meaning
0 (X'00')
4 (X'04')
8 (X'08')
Indicates that register 0 contains the new track balance.
Indicates that the record did not fit (register 0 = 0).
Indicates that the record did not fit. (Register 0 contains the
maximum data length that does fit.)
The system could not find an entry in the device
characteristics table whose attributes match those of the
user-specified device type. Register 0 is set to zero.
12 (X'0C')
TRKCALC Macro Examples
In this example, TRKCALC is coded to determine how many records of a given
size with 10-byte keys fit on an IBM 3380 track. After issuing the macro, the
number of records is saved in NUMREC:
DL
UTYPE
NUMREC
TRKCALC FUNCTN=TRKCAP,TYPE=UTYPE,R=1,K=10,DD=DL,
MF=(E,(1))
.
.
ST 0,NUMREC
SAVE NUMBER OF RECORDS
.
.
DC H’xxxx’
DATA LENGTH
DC X’0E’
DS F
MAX # OF RECORDS
X
In this example, TRKCALC is coded to determine whether another record can fit
on a track of a 3380, given a track balance.
316
z/OS DFSMSdfp Advanced Services
System Macros
UTYPE
REC
KL
DD
BAL
TRKCALC FUNCTN=TRKBAL,TYPE=UTYPE,R=REC,K=KL,DD=DD,
BALANCE=BAL,MAXSIZE=YES,MF=(E,(1))
.
.
DC X’0E’
DC X’xx’
DC X’xx’
DC H’xxxx’
DC H’xxxx’
X
Perform calculations and conversions with 28-bit cylinder addresses
(TRKADDR macro)
TRKADDR is an assembler macro that performs conversion and compare
operations on DASD track addresses in the form CCCCcccH, where CCCC is the 16
low order bits of the cylinder number and ccc is the 12 high order bits of the
cylinder number. This is referred to as a 28-bit cylinder address. TRKADDR works
equally well with track addresses that contain a cylinder number less than or
greater than 16 bits. It works with all DASD types that are supported by z/OS. Its
functions include:
v Calculate the relative track number on the volume
v Compare two track addresses
v Extract the 28-bit cylinder number
v Extract the 4-bit track number
v Increment the track address by one track and increments the cylinder number if
necessary.
v Normalize cylinder number to permit comparing one cchh against another
v Convert a relative track number to a 28-bit cylinder address
v Set the cylinder number in a 28-bit track address
v Convert a normalized track address into an absolute 28-bit track address.
Unless otherwise stated, you can specify any registers from 0 to 15 except that
register 0 cannot be used to address storage. TRKADDR does not use any other
registers, even register 13. You can invoke TRKADDR in 24-bit, 31-bit or 64-bit
mode. If you use the SYSSTATE macro with AMODE64=YES in an earlier source
code statement, then TRKADDR might generate more efficient code.
Calculate the relative track number on the volume (TRKADDR
ABSTOREL)
The format of the execute form of the TRKADDR ABSTOREL macro is:
►►
TRKADDR
label
ABSTOREL
,cchh
,(reg)
,REG=(rega,regb)
►◄
Converts absolute track address (CCCCcccH) to a relative track number. Calculates
the relative track number on the volume and stores the result in the first register.
The second register is used as a work register.
Parameters
cchh
Input: Track address in absolute format
Chapter 7. Using System Macro Instructions
317
System Macros
(reg)
This is a register from 1 to 15 containing the address of the cchh.
rega
Output: Relative track number
regb
Work register
Compare two track addresses (TRKADDR COMPARE)
The format of the execute form of the TRKADDR COMPARE macro is:
►►
TRKADDR
COMPARE
label
,cchh1
,(reg1)
,cchh2
,(reg2)
,REG=(rega,regb)
►◄
Compares two track addresses in storage using the two registers as work registers.
Sets condition code as for CLC machine instruction. Normalizes the two input
values (CCCCcccH to cccCCCCH) and then compares the two normalized values.
The input values are returned unchanged.
Parameters
cchh1 and cchh2
Input: Track addresses in absolute format to be compared. These value are
returned unchanged.
(reg1) and (reg2)
This is a register from 1 to 15 containing the address of the cchh.
rega, regb
Work registers
Extract 28-bit cylinder number (TRKADDR EXTRACTCYL)
The format of the execute form of the TRKADDR EXTRACTCYL macro is:
►►
TRKADDR
label
EXTRACTCYL
,cchh
,(reg)
,REG=(rega)
Extracts the 28-bit cylinder number to a register (CCCCcccH to 0cccCCCC). The
input field is returned unchanged.
Parameters
cchh
Input: Track address in absolute format
(reg)
This is a register from 1 to 15 containing the address of the cchh.
rega
Output: Cylinder number from the input track address
318
z/OS DFSMSdfp Advanced Services
►◄
System Macros
Extract 4-bit track number (TRKADDR EXTRACTTRK)
The format of the execute form of the TRKADDR EXTRACTTRK macro is:
►►
TRKADDR
EXTRACTTRK
label
,cchh
,(reg)
,REG=(rega)
►◄
Extracts the 4-bit track number to a register (CCCCcccH to 0000000H). The input
field is returned unchanged.
Parameters
cchh
Input: Track address in absolute format
(reg)
This is a register from 1 to 15 containing the address of the cchh.
rega
Output: Track number from the input track address
Increment track address (TRKADDR NEXTTRACK)
The format of the execute form of the TRKADDR NEXTTRACK macro is:
►►
TRKADDR
label
NEXTTRACK
,cchh
,(reg)
,REG=(rega)
►◄
Increments the track address by one track and increments the cylinder number if
necessary. The modified value is returned in the input cchh field. The register is
used as a work register.
Parameters
cchh
Input/Output: Track address in absolute format (CCCCcccH). Upon completion
of the operation, this parameter contains the incremented track address in
absolute format.
(reg)
This is a register from 1 to 15 containing the address of the cchh.
rega
Work register
Normalize cylinder number (TRKADDR NORMALIZE)
The format of the execute form of the TRKADDR NORMALIZE macro is:
Chapter 7. Using System Macro Instructions
319
System Macros
►►
TRKADDR
NORMALIZE
,cchh
,(reg)
label
,REG=(rega)
►◄
Reverses the 16-bit and 12-bit portions of the cylinder number and stores the result
in the 32-bit register with the H digit so you can use a simple unsigned
comparison. The CCCCcccH becomes cccCCCCH. Use this when comparing one
cchh against another. Normalize each and do an unsigned comparison.
Parameters
cchh
Input: Track address in absolute format.
(reg)
This is a register from 1 to 15 containing the address of the cchh.
rega
Output: Normalized track address
Convert a relative track number to a 28-bit cylinder address
(TRKADDR RELTOABS)
The format of the execute form of the TRKADDR RELTOABS macro is:
►►
TRKADDR
label
RELTOABS
,cchh
,(reg)
,REG=(reg_pair)
►◄
Converts relative track number to absolute format (CCCCcccH). RELTOABS
converts a relative track number to a 28-bit cylinder address form in the passed
cchh field. The register must be the first in an even/odd pair. The odd register
must contain the relative track number on the volume. The macro modifies both
registers. In 24-bit and 31-bit addressing modes these are four-byte registers. In
64-bit mode, they are eight-byte registers.
Parameters
cchh
Output: Converted track address in absolute format.
(reg)
This is a register from 1 to 15 containing the address of the cchh.
reg_pair
Input: The first register of an even/odd pair where the odd register contains
the track address to be converted.
Set cylinder number from register (TRKADDR SETCYL)
The format of the execute form of the TRKADDR SETCYL macro is:
320
z/OS DFSMSdfp Advanced Services
System Macros
►►
TRKADDR
SETCYL
label
,cchh
,(reg)
,REG=(rega)
►◄
Stores the cylinder number from the register to the 28-bits in the cchh and sets H to
0 (0cccCCCC to CCCCccc0). Destroys the register.
Parameters
cchh
Output: Contains the cylinder number
(reg)
This is a register from 1 to 15 containing the address of the cchh.
rega
Input: Contains the cylinder number to be converted
Convert normalized track address into an absolute 28-bit track
address (TRKADDR NORMTOABS)
The format of the execute form of the TRKADDR NORMTOABS macro is:
►►
TRKADDR
NORMTOABS
label
,cchh
,(reg)
,REG=(rega,regb)
►◄
Reverses the 12-bit and 16-bit portions of the cylinder number and stores the result
in the 32-bit register with the H digit. The cccCCCCH becomes CCCCcccH. Use this
to convert a normalized track address to an absolute 28-bit track address.
Parameters
cchh
Input: Cylinder address to be converted
(reg)
This is a register from 1 to 15 containing the address of the cchh.
rega
Output: Contains the converted value
regb
Work register
Determining Level and Name of DFSMS
You can use the IHADFA mapping macro to determine the level and name of
DFSMS. It maps the data facilities area. Use the CVT mapping macro to define
symbol CVTDFA, which points to the DFA. The DFARELS field in the DFA is four
bytes that designate the product level.
Chapter 7. Using System Macro Instructions
321
System Macros
Determining Version, Release, and Modification Level of
DFSMS
The first byte of DFARELS contains a binary value that indicates the level of
DFSMS on which your program is running:
Value Meaning
0
Your program is not executing on DFSMS; it is executing on MVS/XA DFP
Version 2 or MVS/DFP Version 3 and the following three bytes also
contain zeroes. On those two products you can determine the release level
by examining the two-byte field DFAREL. DFAREL is described in the
comments in IHADFA.
1
Your program is running on DFSMS/MVS and the following three bytes
designate the version, release and modification level of DFSMS/MVS. A
value of X'01010200' in DFARELS designates DFSMS/MVS Version 1,
Release 2, Modification level 0.
2
Your program is running on the level of DFSMS that is exclusive to
OS/390® or one of the first two releases of z/OS. A value of X'02020A00' in
DFARELS designates DFSMS for OS/390 Version 2 Release 10,
Modification level 0. DFSMS was not modified in the first two releases of
z/OS, so these releases also have a value of X'02020A00'.
>3
Your program is running on a level of DFSMS that is part of a hypothetical
replacement product after all versions and releases of z/OS. The system
never returns this value. This represents IBM's intent in case there is such a
product. The following three bytes designate the version, release, and
modification level of that product. The value in the other three bytes is
X'010100' or higher. It may differ from the level of installed z/OS.
3
Your program is running on a level of DFSMS that is exclusive to z/OS
Version 1 Release 3 or higher. The following three bytes designate the
version, release, and modification level of z/OS for which that DFSMS was
designed. The value in the other three bytes is X'010300' or higher. It may
differ from the level of installed z/OS.
IBM intends that for any future level of the DFA, the 4-byte DFARELS will not
contain a value smaller than any previous value. If your purpose in testing
DFARELS is to determine whether a particular feature of DFSMS is available, then
we suggest that your program test all four bytes of DFARELS. IBM intends that if
one of the low-order three bytes of DFARELS contains a value that is smaller than
the corresponding byte in the prior release, then a higher order byte will contain a
larger value.
For compatibility with programs that were designed to run on MVS/XA DFP
Version 2 or MVS/DFP Version 3, DFSMS sets DFAREL to the value X'3321', which
designates MVS/DFP Version 3, Release 3, modification level 2. The last digit
indicates that the system actually is at a higher level than DFP 3.3.2.
See also “Call for DFSMS Level Determination” on page 342 for an alternative
method of determining the level of DFSMS.
See “Data Facilities Area (DFA) Fields” on page 449 for a layout of the fields of the
Data Facilities Area (DFA) control block.
322
z/OS DFSMSdfp Advanced Services
System Macros
Determining Name of DFSMS
If the value of DFARELS is '03010300' or greater, it means the system is z/OS
Version 1 Release 3.0 or later. This means that field DFAELNMP points to a
structure that contains the name of DFSMS. See DFAELNM in “Data Facilities Area
(DFA) Fields” on page 449.
Determining DFARELS During Assembler Macro Phase
Your program can test the DFARELS field during execution as described earlier.
This does not allow you to assemble a program that optionally uses a new macro
parameter that is available only on a certain level of the system. Your program
receives syntax error messages if assembled on an older level of the system.
A solution is to test a macro variable symbol set by the IHADFA macro. The name
of the symbol is &IHADFARELS and it is a character type of global variable
symbol. Your program's test of its value must follow the IHADFA invocation.
The other system facilities determine whether your program can run on a different
release than the one on which it was assembled. For some new functions the older
release will ignore the new function. Other new functions will fail on an older
release.
The IHADFA macro sets the variable symbol &IHADFARELS to an eight-character
value. Each pair of characters in the value represents the decimal value of one byte
in DFARELS. They are not hexadecimal digits because the EBCDIC values of “A”
to “F” are not in proper collating sequence with the numeric digits. For example
the value for z/OS Version 1 Release 10 is ' 03011000', '03' represent the name
z/OS, ' 01' represents Version 1, ' 10' represents release 10, ' 00' represents
modification level 0.
This is an example of a program using &IHADFARELS:
Chapter 7. Using System Macro Instructions
323
System Macros
xxxx
CSECT
.
.
.
GBLC &IHADFARELS
Set by IHADFA macro to be system level
IHADFA ,
Set &IHADFARELS and define DFARELS
xxxx
CSECT
Reset CSECT
.
.
.
* Expand one of two macro invocations. Either works on any DFSMS
* release. If in 31-bit mode on 1.3 or later, then ANY means a UCB
* may be above the line. Neither works on DFP Version 3 when assembled
* on DFSMS.
AIF
(’&IHADFARELS’ LT ’01010300’).OLD
* If executing in 31-bit mode on 1.3 or later, this requires that each
* UCB address be 31-bit. They may point below the line. On an older
* level of DFSMS, the ANY has no effect. DFP 3.x will reject it.
DEVTYPE UCBLIST=(MYLIST,1,ANY),MF=(E,DEVTLIST)
AGO
.CONT
.OLD
DEVTYPE UCBLIST=(MYLIST,1),MF=(E,DEVTLIST)
.CONT
ANOP
.
MYLIST DC
A(0)
DEVTLIST DEVTYPE ,(DEVINFO,24),MF=L
Figure 38. Sample &IHADFARELS Program
The IHADFA macro as shipped prior to DFSMS/MVS V1R3 did not set
&IHADFARELS. You can use the technique in the example even if IHADFA does
not set &IHADFARELS.
This technique of using IHADFA to decide on another macro invocation assumes
that IHADFA resides in a complete macro library for the same release as the other
macro. It might not work properly with a macro from a different release or
product.
Following is an example of determining whether a mapping macro has defined a
symbol that is needed during the assembly. During execution, the program tests
DFARELS to determine how to execute.
GBLC &IHADFARELS Set by IHADFA macro to be system level
IHADFA ,
Learn release of assembly & execution
TRKLIST DSECT
TRKCALC MF=D
DSECT for TRKCALC parameter list
SPACE 2
* If global symbol &IHADFARELS has a null value or is less than
* 01010300, then TRKCALC did not define a certain symbol. Since
* other parts of this program use it, it must be defined.
AIF
(’&IHADFARELS’ GE ’01010300’).GOTBIT
Go if newer
STARLOC EQU
X’01’
LOC=ANY. DEVTAB or UCB may be above line
.GOTBIT ANOP
Figure 39. Example of Determining Symbol Definition
324
z/OS DFSMSdfp Advanced Services
Chapter 8. Displaying Messages on Cartridge Magnetic Tape
Subsystems (MSGDISP macro)
This information covers using the MSGDISP macro to display messages on
magnetic tape devices that have displays. With MSGDISP, you can specify the
message to be displayed and how to display it (for example, steady or flashing).
The standard, executes, and list forms of the macro are described here. The six
main parameters of the macro and their functions are:
Value
Meaning
MOUNT
Displays an 'M' in position 1 of the display area during a mount request
until a volume is loaded and made ready. The 'M' is followed by the
volume serial number and label type.
Shows that a volume has been accepted by displaying its serial number
and label type in positions 2 through 8.
Displays text in positions 2 through 7 while a data set is open.
Places a volume disposition indicator in position 1 of the display until a
volume is demounted.
Clears the display area.
Provides the full range of display options, including the option to
alternate two messages.
VERIFY
RDY
DEMOUNT
RESET
GEN
All except the RDY parameter require that the caller be in supervisor state, have a
storage protect key of 0 through 7, or be authorized by the authorized program
facility.
You can issue the MSGDISP macro in 24- or 31-bit addressing mode. When you
use 31-bit addressing mode, all addresses must be valid 31-bit addresses.
The MSGDISP macro generates a parameter list as input to the message display
service routine. You can code an installation exit routine named IGXMSGEX,which
gains control when MSGDISP is processing MOUNT, DEMOUNT, VERIFY, or GEN
requests. The exit can change the message text displayed (two 8-byte strings) and 1
bit of the format control byte. See z/OS DFSMS Installation Exits for details.
© Copyright IBM Corp. 1979, 2017
325
Cartridge Messages
MSGDISP—Displaying a Mount Message
The format of the MSGDISP macro with the MOUNT parameter is:
►►
MSGDISP
MOUNT ,UCB=(reg)
►
label
,LABEL=
'S'
'A'
'N'
'X'
addr
►
►
,MF=
L
(E,addr)
,SER=
'volser'
addr
,MEDIATYPE=n
►
►◄
,INDEX=
YES
NO
,TEST=
NO
YES
,WAIT=
YES
NO
MOUNT
Displays an 'M' in position 1 of the display area during a mount request. The
'M' is followed by a volume serial number and label type. The display flashes
on and off until a volume is loaded and ready. If the device is ready at the
time a mount request is issued, the 'M' is not displayed.
UCB=(reg)—(2-12)
Specifies a register containing the UCB address for the device. Use the address
of a UCB, not a UCB copy.
LABEL='A' or 'N' or 'S' or 'X' or addr
Displays the label type of the mounted volume in position 8. If you specify an
unknown label type other than a blank, a “?” is displayed.
'A'
Specifies ISO/ANSI (AL) or ISO/ANSI with user labels (AUL).
Apostrophes are required.
'N'
Specifies no labels (NL), LTM (VSE), or bypass label processing (BLP)
Apostrophes are required.
'S'
Specifies IBM Standard (SL) or IBM Standard with user labels (SUL).
Apostrophes are required.
'X'
Specifies nonstandard labels (NSL). Apostrophes are required.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of an area containing an “A”, “N”, “S”, or “X”. (See
the following explanations of these characters.) For MF=L, you can only
specify an A-type address.
MF=L or (E,addr)
Specifies either the execute or the list form of MSGDISP. If you do not specify
this parameter, the standard form of the macro is used.
326
z/OS DFSMSdfp Advanced Services
Cartridge Messages
L
Specifies the list form of MSGDISP. This generates a parameter list that can
be used as input to the execute form. The execute form can modify the
parameter list.
(E,addr)
Specifies that the execute form of the macro and an existing parameter list
are used.
addr—RX-type address, (1), or (2-12)
Specifies the address of the parameter list.
SER='volser' or addr
Specifies the serial number of the volume to be mounted. The serial number is
displayed in positions 2 through 7. If you do not specify SER, the system
supplies the volume serial number. If the serial number is not available, a
scratch volume is used, unless the volume use attribute indicates a default of
“PRIVAT”.
'volser'
Specifies the volume serial number as a literal. Specify in apostrophes.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of the volume serial number. For MF=L, you can only
specify an A-type address.
MEDIATYPE=n
Specifies what media type to mount for SCRTCH or PRIVAT mounts. The
MEDIATYPE keyword applies only when volumes are to be mounted on
devices that reside in a Manual Tape Library (MTL). If MEDIATYPE is
specified for devices outside of a Manual Tape Library, it is ignored. The value
n can be specified as a literal, the address of a 1 byte field containing the
value, or the name of the addressable field containing the value. Valid values
for MEDIATYPE are the numbers 1 through 8.
TEST=NO or YES
Specifies whether the macro expansion is to include code that tests the UCB to
determine whether message display is supported. If the result of the test is that
the message display is not supported, an SVC is not invoked.
NO Specifies that the macro expansion is not to include code that tests the
UCB to determine whether the device supports message display.
YES
Specifies testing the UCB by the MSGDISP macro before attempting to
invoke the message display service routine.
Requirement: TEST=YES requires you to include the UCB mapping macro
(IEFUCBOB) in the source code.
Restriction: There is a restriction when using TEST=YES. Programs
running in AMODE 24 and invoking the MSGDISP macro with the
TEST=YES parameter cannot pass the actual address of a UCB that resides
above the 16 MB line. These programs must pass the captured UCB
address or, if an actual address is passed, the UCB must reside below the
16 MB line.
INDEX=NO or YES
Specifies whether the automatic cartridge loader (ACL) should be indexed to
satisfy a scratch mount request.
Chapter 8. Displaying Messages on Cartridge Magnetic Tape Subsystems (MSGDISP macro)
327
Cartridge Messages
NO Specifies that indexing should not be done regardless of the state of the
ACL.
YES
Specifies that indexing should be done if:
v The ACL is present and loaded, and
v The request is for SCRTCH or PRIVAT.
WAIT=NO or YES
Specifies when control is returned to you.
NO Specifies that the MSGDISP function is not to wait for completion of I/O
initiated on the caller's behalf. When MSGDISP returns, the I/O request
might still be running. I/O return codes are not returned, and I/O errors
are recorded in the same manner as any permanent error by the error
recovery procedure.
YES
Specifies that control is to be returned after I/O is complete.
MSGDISP—Displaying a Verify Message
The format of the MSGDISP macro with the VERIFY parameter is:
►►
MSGDISP
VERIFY ,UCB= (reg)
label
,LABEL=
'S'
'A'
'N'
'X'
addr
►
►
►
,MF=
L
(E,addr)
,SER=
'volser'
addr
,TEST=
NO
YES
►
►◄
,WAIT=
YES
NO
VERIFY
Displays the serial number and label type of a volume that has been accepted
for processing. The serial number is displayed on the pod in positions 2
through 7, and the 1 character label type in position 8. Position 1 remains
blank. The display lasts until the next display request is executed.
UCB=(reg)—(2-12)
Specifies a register containing the UCB address for the device. Use the address
of a UCB, not a UCB copy.
LABEL='A' or 'N' or 'S' or 'X' or addr
Specifies label type of the mounted volume in position 8 of the display. If an
unknown label type other than a blank is specified, a “?” is displayed.
'A'
Specifies ISO/ANSI (AL) or ISO/ANSI with user (AUL) labels.
Apostrophes are required.
328
z/OS DFSMSdfp Advanced Services
Cartridge Messages
'N'
Specifies no labels (NL), LTM (VSE), or bypass label processing (BLP).
Apostrophes are required.
'S'
Specifies IBM Standard (SL) or IBM Standard with user (SUL) labels.
Apostrophes are required.
'X'
Specifies nonstandard (NSL) labels. Apostrophes are required.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of an area containing an “A”, “N”, “S”, or “X” (see
explanations below for these characters). For MF=L, you can only specify
an A-type address.
MF=L or (E,addr)
Specifies either the execute or list form of MSGDISP. If you do not specify this
parameter, the standard form of the macro is used.
L
Specifies the list form of MSGDISP. This generates a parameter list that can
be used as input to the execute form. The execute form can modify the
parameter list.
(E,addr)
Specifies that the execute form of the macro and an existing parameter list
is to be used.
addr—RX-type address, (1), or (2-12)
Specifies the address of the parameter list.
SER='volser' or addr
Specifies the serial number of the volume that has been verified. The serial
number displays in positions 2 through 7. If you do not specify SER, the
system supplies the volume serial number. If the serial number is not available,
a scratch volume is used, unless the volume use attribute indicates a default of
“PRIVAT”.
'volser'
Specifies the volume serial number as a literal. Express® in apostrophes.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of the volume serial number. For MF=L, you can only
specify an A-type address.
TEST=NO or YES
Specifies whether the macro expansion is to include code that will test the UCB
to determine whether message display is supported. If the result of the test is
that the message display is not supported, an SVC is not invoked.
NO Specifies that the macro expansion is not to include code that tests the
UCB to determine whether the device supports message display.
YES
Specifies testing the UCB by the MSGDISP macro before attempting to
invoke the message display service routine.
Requirement: TEST=YES requires you to include the UCB mapping macro
(IEFUCBOB) in the source code. If this provision is not followed, a
program check in expansion code might result. Programs running in
AMODE 24 and invoking the MSGDISP macro with the TEST=YES
parameter cannot pass the actual address of a UCB that resides above the
Chapter 8. Displaying Messages on Cartridge Magnetic Tape Subsystems (MSGDISP macro)
329
Cartridge Messages
16 MB line. These programs must pass the captured UCB address or, if an
actual address is passed, the UCB must reside below the 16 MB line.
WAIT=NO or YES
Specifies when control is to be returned to you and that the MSGDISP function
is not to wait for completion of I/O initiated on the caller's behalf. When
MSGDISP returns, the I/O request might still be running.
NO Specifies that the MSGDISP function is not to wait for completion of I/O
that is initiated on the caller's behalf. When MSGDISP returns, the I/O
request might still be running. I/O return codes are not returned, and I/O
errors are recorded in the same manner as any permanent error by the
error recovery procedure.
YES
Specifies that control is to be returned after I/O is complete.
MSGDISP—Displaying a Ready Message
The format of the MSGDISP macro with the RDY parameter is:
►►
MSGDISP
label
RDY ,DCB=addr
►
,MF=
L
(E,addr)
►
►◄
,TXT=
'msgtxt'
addr
RDY
Displays the text supplied in the TXT parameter in positions 2 through 7 while
the data set is open. The display is steady (not flashing) and is enclosed in
parentheses. The display is also written to the tape pool console (routing code
3, descriptor code 7).
DCB=addr
Specifies the address of a DCB opened to a data set on the mounted volume. If
multiple devices are allocated, the message display is directed to the one
containing the volume currently in use.
Tip: If multiple devices or multiple volumes are allocated, you can update a
message display after an end-of-volume condition by using the EOV user exit
specified in a DCB exit list. In the case of a concatenated data set with unlike
characteristics, the DCB OPEN exit can also be used to update the display.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of the opened DCB. For MF=L, you can only specify
an A-type address.
MF=L or (E,addr)
Specifies either the execute or list form of MSGDISP. If this parameter is not
specified, the standard form of the macro is used.
L
330
Specifies the list form of MSGDISP. This generates a parameter list that can
be used as input to the execute form. The execute form can modify the
parameter list.
z/OS DFSMSdfp Advanced Services
Cartridge Messages
(E,addr)
Specifies that the execute form of the macro and an existing parameter list
is to be used.
addr—RX-type address, (1), or (2-12)
Specifies the address of the parameter list.
TXT='msgtxt' or addr
Specifies up to six characters to display in positions 2 through 7 of the display.
If you do not specify TXT, blanks are displayed.
'msgtxt'
Specifies the text as a literal. Express in apostrophes.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of an area containing the text to be displayed. For
MF=L, you can only specify an A-type address.
MSGDISP—Displaying a Demount Message
The format of the MSGDISP macro with the DEMOUNT parameter is:
►►
MSGDISP
DEMOUNT ,UCB= (reg)
►
label
,DISP=
'D'
'K'
'R'
addr
►
►
,MF=
L
(E,addr)
,MLABEL=
'S'
'A'
'N'
'X'
addr
►
►
,MSER=
'volser_to_mount'
addr
,SER=
'volser'
addr
►
►
,MEDIATYPE=n
,INDEX=
YES
NO
,TEST=
NO
YES
►
►◄
,WAIT=
YES
NO
DEMOUNT
Displays a volume disposition indicator in position 1 until the volume is
demounted. Optionally, you can display the serial number of the volume to be
demounted at the same time. The display flashes on and off. If a volume is not
mounted on the device when the display request is executed, blanks are
displayed.
The demount message can be displayed alternately (flashing) with a mount
message for the next volume by specifying the MSER parameter.
Chapter 8. Displaying Messages on Cartridge Magnetic Tape Subsystems (MSGDISP macro)
331
Cartridge Messages
UCB=(reg)—(2-12)
Specifies a register containing the UCB address for the device. Use the address
of a UCB, not a UCB copy.
DISP='D' or 'K' or 'R' or addr
Specifies the character to display in position 1 of the pod, representing the
volume disposition.
'D'
Specifies demount a public volume. Apostrophes are required. “D” also
displays when you specify an invalid character or when the volume use
attribute is unknown (as in an automatic volume recognition (AVR) error
when reading a label).
'K'
Specifies keep a private volume and return it to the library. Apostrophes
are required.
'R'
Specifies retain a private volume near the device for further use.
Apostrophes are required.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of an area containing a “D”, “K”, or “R”. For MF=L,
you can only specify an A-type address.
MF=L or (E,addr)
Specifies either the execute or list form of MSGDISP. If you do not specify this
parameter, the standard form of the macro is used.
L
Specifies the list form of MSGDISP. This generates a parameter list that can
be used as input to the execute form. The execute form can modify the
parameter list.
(E,addr)
Specifies that the execute form of the macro and an existing parameter list
is to be used.
addr—RX-type address, (1), or (2-12)
Specifies the address of the parameter list.
MLABEL='A' or 'N' or 'S' or 'X' or addr
Displays the label type of the volume to be loaded and made ready following
a demount, in position 8. If you specify an unknown label type other than a
blank, a “?” is displayed. You can only specify this parameter if you also
specify the MSER parameter.
'A'
Specifies ISO/ANSI (AL) or ISO/ANSI with user (AUL) labels.
Apostrophes are required.
'N'
Specifies no labels (NL), LTM (leading tape mark, created by VSE), or
bypass label processing (BLP). Apostrophes are required.
'S'
Specifies IBM Standard (SL) or IBM Standard with user (SUL) labels.
Apostrophes are required.
'X'
Specifies nonstandard (NSL) labels. Apostrophes are required.
332
z/OS DFSMSdfp Advanced Services
Cartridge Messages
addr—RX-type address, A-type address, or (2-12)
Specifies the address of an area containing an “A”, “N”, “S”, or “X” (see
the following explanations of these characters). For MF=L, you can only
specify an A-type address.
MSER='volser-to-mount' or addr
Displays the mount message for the next volume alternately (flashing) with the
demount message. The display continues until you demount the current
volume. At that time, the mount message will display (flashing) until you load
the volume and make the device ready. If no volume is mounted at the time
the demount and mount messages are executed, only the mount message will
display (flashing) until the volume is loaded and ready.
'volser-to-mount'
Specifies the volume serial number of the volume to be mounted, as a
literal. Apostrophes are required.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of the volume serial number of the volume to be
mounted. For MF=L, you can only specify an A-type address.
SER='volser' or addr
Specifies the serial number of the volume to be demounted. The serial number
is displayed in positions 2 through 7. If you do not specify SER, the system
supplies the volume serial number. If the serial number is not available, a
scratch volume is used, unless the volume use attribute indicates a default of
“PRIVAT”.
'volser'
Specifies the volume serial number as a literal. Specify with apostrophes.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of the volume serial number. This parameter is not
valid for the MF=L form. For MF=L, you can only specify an A-type
address.
MEDIATYPE=n
Specifies what media type to demount for SCRTCH or PRIVAT demounts. The
MEDIATYPE keyword applies only when volumes are to be demounted on
devices that reside in a Manual Tape Library (MTL). If MEDIATYPE is
specified for devices outside of a Manual Tape Library, it is ignored. The value
n can be specified as a literal, the address of a 1 byte field containing the
value, or the name of the addressable field containing the value. Valid values
for MEDIATYPE are the numbers 1 through 8.
INDEX=NO or YES
Specifies whether the ACL should be indexed to satisfy a scratch mount
request.
NO Specifies that indexing should not be done regardless of the state of the
ACL.
YES
Specifies that indexing should be done if:
v The ACL is present and loaded, and
v The request is for SCRTCH or PRIVAT.
TEST=NO or YES
Specifies whether the macro expansion is to include code that tests the UCB to
determine whether message display is supported. If the result of the test is that
the message display is not supported, an SVC is not invoked.
Chapter 8. Displaying Messages on Cartridge Magnetic Tape Subsystems (MSGDISP macro)
333
Cartridge Messages
NO Specifies that the macro expansion is not to include code that tests the
UCB to determine whether the device supports message display.
YES
Specifies testing the UCB by the MSGDISP macro before attempting to
invoke the message display service routine.
Requirement: TEST=YES requires you to include the UCB mapping macro
(IEFUCBOB) in the source code. If this provision is not followed, a
program check in expansion code might result. Programs running in
AMODE 24 and invoking the MSGDISP macro with the TEST=YES
parameter cannot pass the actual address of a UCB that resides above the
16 MB line. These programs must pass the captured UCB address or, if an
actual address is passed, the UCB must reside below the 16 MB line.
WAIT=NO or YES
Specifies when control is to be returned to you.
NO Specifies that the MSGDISP function is not to wait for completion of I/O
initiated on the caller's behalf. When MSGDISP returns, the I/O request
might still be running. I/O return codes are not returned, and I/O errors
are recorded in the same manner as any permanent error by the error
recovery procedure.
YES
Specifies that control is to be returned after I/O is complete.
MSGDISP—Resetting the Message Display
The format of the MSGDISP macro with the RESET parameter is:
►►
MSGDISP
RESET
label
,UCB= (reg)
,UCBL=addr
►
,MF=
L
(E,addr)
►
►◄
,TEST=
NO
YES
,WAIT=
YES
NO
RESET
Clears all existing data on the display. If you specify WAIT=NO and the last
service requested was a demount, the display is not cleared.
After being cleared, the display shows the internal status of the device (for
example, a message indicating that the device is ready).
UCB=(reg)—(2-12)
Specifies a register containing the UCB address for the device. Use the address
of a UCB, not a UCB copy.
UCBL=addr—RX-type address, A-type address, (0), or (2-12)
Specifies the address of a list containing a maximum of 64 words. Each word
in the list contains the address of a UCB representing a device whose display
is to be reset. The end of the list is indicated by a '1' in the high-order bit of
the last address in the list. If an error is encountered while processing the list,
register 1 points to the associated UCB when you regain control.
334
z/OS DFSMSdfp Advanced Services
Cartridge Messages
You cannot specify UCBL with TEST=YES and WAIT=NO.
MF=L or (E,addr)
Specifies either the execute or the list form of MSGDISP. If you do not specify
this parameter, the standard form of the macro is used.
L
Specifies the list form of MSGDISP. This generates a parameter list that can
be used as input to the execute form. The execute form can modify the
parameter list.
(E,addr)
Specifies that the execute form of the macro and an existing parameter list
is to be used.
addr—RX-type address, (1), or (2-12)
Specifies the address of the parameter list.
TEST=NO or YES
Specifies whether the macro expansion is to include code that tests the UCB to
determine whether message display is supported. If the result of the test is that
the message display is not supported, an SVC is not invoked.
NO Specifies that the macro expansion is not to include code that tests the
UCB to determine whether the device supports message display. NO is the
default?
YES
Specifies testing the UCB by the MSGDISP macro before attempting to
invoke the message display service routine. You cannot specify TEST=YES
if you also specify the UCBL parameter.
Requirement: TEST=YES requires you to include the UCB mapping macro
(IEFUCBOB) in the source code. If this provision is not followed, a
program check in expansion code might result. Programs running in
AMODE 24 and invoking the MSGDISP macro with the TEST=YES
parameter cannot pass the actual address of a UCB that resides above the
16 MB line. These programs must pass the captured UCB address or, if an
actual address is passed, the UCB must reside below the 16 MB line.
WAIT=NO or YES
Specifies when control is to be returned to you.
NO Specifies that the MSGDISP function is not to wait for completion of I/O
initiated on the caller's behalf. When MSGDISP returns, the I/O request
might still be running. I/O return codes are not returned, and I/O errors
are recorded in the same manner as any permanent error by the error
recovery procedure.
You cannot specify WAIT=NO if you also specify the UCBL parameter.
YES
Specifies that control is to be returned after I/O is complete.
Demount messages can be reset only if WAIT=YES is specified.
Chapter 8. Displaying Messages on Cartridge Magnetic Tape Subsystems (MSGDISP macro)
335
Cartridge Messages
MSGDISP—Providing the Full Range of Display Options
The format of the MSGDISP macro with the GEN parameter is:
►►
MSGDISP
GEN ,UCB= (reg)
►
label
,FLASH=
BLINK
STEADY
STEADY2
BLINK2
ALT
►
►
,MF=
L
E,addr
,INDEX=
YES
NO
,TEST=
NO
YES
►
►
,TXT=
'msgtxt'
addr
,TXT2=
'altmsgtxt'
addr
,VOL=
STATIC
REMOVE
INSERT
SWAP
►
►◄
,WAIT=
YES
NO
GEN
Specifies the full range of display options.
UCB=(reg)—(2-12)
Specifies a register containing the UCB address for the device. Use the address
of a UCB, not a UCB copy.
FLASH=STEADY or STEADY2 or BLINK or BLINK2 or ALT
Specifies message display mode.
Hint: If you specify VOL=SWAP, messages will always be displayed as if you
had specified FLASH=ALT.
STEADY
Specifies that the primary message (TXT) is to be displayed without
flashing.
STEADY2
Specifies that the alternate message (TXT2) is to be displayed without
flashing.
BLINK
Specifies that the primary message (TXT) flash on and off at a rate of
approximately two seconds on and one-half second off.
BLINK2
Specifies that the alternate message (TXT2) flash on and off at a rate of
approximately two seconds on and one-half second off.
ALT
Specifies that the primary and alternate messages (TXT and TXT2) flash on
and off alternately, at a rate of approximately two seconds on and one-half
second off.
336
z/OS DFSMSdfp Advanced Services
Cartridge Messages
MF=L or (E,addr)
Specifies either the execute or the list form of MSGDISP. If you do not specify
this parameter, the standard form of the macro is used.
L
Specifies the list form of MSGDISP. This generates a parameter list that can
be used as input to the execute form. The execute form can modify the
parameter list.
(E,addr)
Specifies that the execute form of the macro and an existing parameter list
is to be used.
addr
Specifies the address of the parameter list. Specify either an RX-type
address or a register in the range of 2 through 12.
INDEX=NO or YES
Specifies whether the ACL should be indexed to satisfy a scratch mount
request.
NO Specifies that indexing should not be done regardless of the state of the
ACL.
YES
Specifies that indexing should be done if:
v The ACL is present and loaded, and
v The request is for SCRTCH or PRIVAT.
TEST=NO or YES
Specifies whether to test the UCB to determine if the device is capable of
displaying messages.
NO Specifies that the macro expansion is not to include code that tests the
UCB to determine whether the device supports message display.
YES
Specifies testing the UCB by the MSGDISP macro before attempting to
invoke the message display service routine.
Requirement: TEST=YES requires you to include the UCB mapping macro
(IEFUCBOB) in the source code. If this provision is not followed, a
program check in expansion code might result. Programs running in
AMODE 24 and invoking the MSGDISP macro with the TEST=YES
parameter cannot pass the actual address of a UCB that resides above the
16 MB line. These programs must pass the captured UCB address or, if an
actual address is passed, the UCB must reside below the 16 MB line.
TXT='msgtxt' or addr
Specifies 8 characters to be shown in positions 1 through 8 of the display. If
you do not specify TXT, blanks are displayed.
'msgtxt'
Specifies the 8 characters as literals. Apostrophes are required.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of an area containing the 8 characters. For MF=L, you
can only specify an A-type address.
TXT2='altmsgtxt' or addr
Specifies 8 alternate characters to display in positions 1 through 8 of the
display. If you do not specify TXT2, blanks are displayed.
Chapter 8. Displaying Messages on Cartridge Magnetic Tape Subsystems (MSGDISP macro)
337
Cartridge Messages
'altmsgtxt'
Specifies the 8 characters as literals. Apostrophes are required.
addr—RX-type address, A-type address, or (2-12)
Specifies the address of an area containing the 8 characters. For MF=L, you
can only specify an A-type address.
VOL=STATIC or REMOVE or INSERT or SWAP
Specifies message display mode, based on volume status.
STATIC
Specifies that messages display without regard to volume status until the
next message request is executed, or until the next command initiates
volume movement.
REMOVE
Specifies that messages display until the current volume is demounted.
This parameter is ignored if a volume is not mounted when the request is
executed.
INSERT
Specifies that messages display until a volume is present, the tape is
threaded, and the active/inactive switch is in the active position. This
parameter is ignored if a volume is loaded and ready when the request is
executed.
SWAP
Specifies that messages always display as if FLASH=ALT were specified.
The data from TXT and TXT2 displays alternately (flashing) until the
current volume has been demounted. Then only TXT2 displays (flashing)
until a new volume is loaded and ready. If no volume is mounted when
this parameter is specified, only TXT2 data displays (flashing) until a new
volume is loaded and ready.
WAIT=NO or YES
Specifies when control is to be returned to you.
NO Specifies that the MSGDISP function is not to wait for completion of I/O
initiated on the caller's behalf. When MSGDISP returns, the I/O request
might still be running. I/O return codes are not returned, and I/O errors
are recorded in the same manner as any permanent error by the error
recovery procedure.
YES
Specifies that control is to be returned after I/O is complete. This is the
default.
Return Codes from MSGDISP
When the system returns control to the problem program, the low-order byte of
register 15 contains a return code. The low-order byte of register 0 can contain a
reason code. These codes are described in the following table:
Return Code
0 (X'00')
4 (X'04')
8 (X'08')
338
z/OS DFSMSdfp Advanced Services
Reason Code
Meaning
1 (X'01')
2 (X'02')
3 (X'03'
Successful completion.
Device does not support MSGDISP.
Invalid input parameter.
Invalid DCB or DEBCHK error.
Environmental error.
Cartridge Messages
Return Code
Reason Code
Meaning
4 (X'04')
5 (X'05')
Authorization (TESTAUTH) violation.
Invalid UCB. Requires the address of a UCB, not a
UCB copy.
Invalid request.
Unsuccessful ESTAE macro call.
Unsuccessful GETMAIN request.
I/O error (The system posted the request for an
error).
6 (X'06')
11 (X'0B')
12 (X'0C')
12 (X'0C')
An I/O error occurs for load display if the drive display has a hardware failure.
If you get return code X'04' or X'0C' on a RESET UCBL operation, when you regain
control, register 1 points to the UCB associated with the error.
Chapter 8. Displaying Messages on Cartridge Magnetic Tape Subsystems (MSGDISP macro)
339
340
z/OS DFSMSdfp Advanced Services
Chapter 9. Using DFSMSdfp Callable Services
This information describes the DFSMSdfp-related callable services. Callable
services reside in SYS1.CSSLIB, the callable system service library. They are
invoked from a user program by issuing a CALL statement, accompanied by a
parameter identifying the desired service and a list of service-specific arguments
and storage areas. The intent is that if you link edit any of the routines described
here with your program, the routine continues to execute correctly on future levels
of the operating system.
The DFSMSdfp callable services provide 15 callable system services. They can be
invoked by the high-level languages supported by z/OS Language Environment®
and by assembler language callers.
Note: Nine of these callable services are related to using the character data
representation architecture (CDRA) identifiers.They are application program
interfaces (APIs) that are needed to consistently and correctly process graphic
character data. We have listed them here (see “Character Data Representation
Architecture (CDRA) APIs” on page 362), but for detailed information on their use,
refer to Character Data Representation Architecture Reference and Registry.
These services enable programs written in assembler language or high-level
languages to use:
v IECTRKAD to perform conversions and compares of DASD track addresses that
contain 16-bit or 28-bit cylinder numbers.
v IGWARLS to query the information in the catalog for record-level sharing (RLS),
including the values of the LOG, BWO, and LOGSTREAMID parameters, the
VSAM_QUIESCED indicator, the RLS_RECOVERY_TIMESTAMP fields, and
whether the sphere requires forward recovery.
v IGWABWO to communicate with DFSMSdfp to retrieve or set various data
set–related indicators. Through the use of these indicators, your program can
determine if a data set is eligible for backup while it is open for update and, if
eligible, what action can or should be taken. See Table 63 on page 353 for an
explanation of the indicators.
v IGWASMS to return certain data set attributes for SMS managed data sets. These
data set attributes are:
– SMSDATA—SMS class names, that is, storage class, management class, and
data class.
– DSTYPE—Currently indicates whether the data set is a PDSE-type data set,
HFS, or neither.
Note: If IGWASMS is called for a non-SMS managed data set, zeros are
returned for the DSTYPE attribute.
v IGWASYS to determine the version, release, and modification level of DFSMSdfp
on your system, and the status of the SMS subsystem.
v IGWLSHR to determine the DFSMSdfp share attributes in use on the current
system.
This information describes calling the service from a nonreentrant program written
in assembler language. See z/OS MVS Programming: Assembler Services Reference
© Copyright IBM Corp. 1979, 2017
341
Callable Services
ABE-HSP for information on using CALL in a reentrant program. For information
on using CALL in programs written in high-level languages, see the applicable
language documentation.
Your program can call the DFSMSdfp callable services in either 24- or 31-bit
AMODE. The program can be executed in any protection key and in either
supervisor or problem state. When you invoke any of the callable services, your
program must provide the address of a standard 18 word save area in register 13.
The syntax diagrams here show a CALL statement in assembler language. These
callable services can be invoked in the following two ways:
v A CALL statement is coded in the invoking application. The callable services
IGWASYS, IGWASMS, IGWABWO, IGWLSHR or IGWARLS, among others, are
in SYS1.CSSLIB. When link-editing the invoking application, specify
SYS1.CSSLIB in the library concatenation.
v The invoking application can issue a LINK or LOAD/CALL to the desired
service, IGWASYS, IGWASMS, IGWABWO, IGWLSHR, or IGWARLS. For an
example of using a LINK macro, see “Example” on page 347. For an example of
using CALL and LOAD/CALL macros, see “Example” on page 344 and
“Example” on page 349.
To invoke the callable services write a set of arguments in a specific order on the
invocation. The number of arguments associated with each callable service is
fixed, and the types of arguments are restricted to 32-bit binary integers
(hereafter referred to as integers) and fixed-length EBCDIC character strings. The
CALL statement format is described in the following information:
– “Call for DFSMS Level Determination”
– “Call for Data Set Attribute Retrieval” on page 345
– “Call for Data Set Backup-While-Open Support” on page 347
– “Call for DFSMSdfp Share Attributes” on page 353
– “Call for Record-Level Sharing Query (IGWARLS)” on page 355
– “Call for converting and comparing 28-bit cylinder addresses (IECTRKAD)”
on page 359
Call for DFSMS Level Determination
The DFSMS level determination call (IGWASYS) returns the version, release and
modification levels of DFSMS. It also returns a code number to represent the name
of the product that contains DFSMS. These four numbers represent the
environment that DFSMS was designed to run in. That level might be earlier than
the release for the rest of the operating system.
An alternative technique to determine the level of the system is described in
“Determining Level and Name of DFSMS” on page 321.
Format
The format of the system attribute IGWASYS call statement is:
342
z/OS DFSMSdfp Advanced Services
Callable Services
►►
CALL IGWASYS
, return_code ,
( reason_code ,
►
label
► level_indicator ,
system_level , system_attr )
►◄
Parameters
return_code
Return code from IGWASYS. The return code is also returned in register 15.
For an explanation, see “IGWASYS, IGWASMS, IGWABWO, IGWLSHR Return
and Reason Codes” on page 354. This is an output argument that must be
defined as an integer.
reason_code
Reason code from the IGWASYS service. The reason code is also returned in
register 0. For an explanation, see “IGWASYS, IGWASMS, IGWABWO,
IGWLSHR Return and Reason Codes” on page 354. This is an output argument
that must be defined as an integer.
level_indicator
The product whose level information is requested. This is an input argument.
Define level_indicator as an integer. Code a value of 1 to request the level of
MVS/XA DFP Version 2 or MVS/DFP Version 3 or code a 2 to request the
level of DFSMS/MVS or later. This value affects what the system returns in
system_level, which is described below.
system_level
The product level that is installed on the system invoking the service. This is
an output argument and is a four-element array of integers. The array elements
consist of the following integers:
v Version number
v Release number
v Modification level
v Special indicator
If you pass a value of 1 for level_indicator, DFSMS returns the system_level
values as 3, 3, 2 and 1. The first three values reflect the fact that DFSMS
contains the functions of MVS/DFP Version 3 Release 3 modification level 2.
The system sets the fourth value to 1 to indicate that the system is actually at a
level higher than 3.3.2. If your program were executing on MVS/DFP 3.3.2,
then these four values would have been returned as 3, 3, 2 and 0.
If you pass a value of 2 for level_indicator, IGWASYS sets the fourth system_level
word to a code that represents the product name that IGWASYS is part of. On
no level of the system will this word contain a value that is smaller than on a
prior release. One of the following values is returned:
1
“DFSMS/MVS”. With MVS/ESA SP Version 5, it constituted an
MVS/ESA system. With OS/390 MVS™, it was part of OS/390 Version
1 or Version 2. The first three system_level words represent
DFSMS/MVS.
2
DFSMS is part of OS/390 and not a separate product. The first three
system_level words show OS/390 Version 2, Release 10, Modification
Level 0, or later. Those words represent the OS/390 level that DFSMS
Chapter 9. Using DFSMSdfp Callable Services
343
Callable Services
3
>3
was designed to support. You will see these values also on z/OS
DFSMS Version 1 Release 1 and 2 because DFSMS was not changed
from OS/390 2.10.
DFSMS is part of z/OS and not a separate product. The first three
system-level words show z/OS Version 1, Release 3, Modification Level
0, or later. Those words represent the z/OS level that the DFSMS was
designed to support.
DFSMS is part of hypothetical replacement product after all versions
and releases of z/OS. The system never returns this value. It represents
IBM's intent in case there is such a product. The other words represent
the operating system level that the DFSMS was designed to support.
If the next release of the system does not contain a new level of DFSMS,
IGWASYS will continue to return the original DFSMS release. This is to help
with diagnosis of configuration problems and service.
The intent is that in any future level of the system, your program can
determine whether it is running on a particular level or it is running on some
later level. If that is what you wish your program to do, then it is suggested
that your program test all four words of system level. First test the fourth
word to ensure that it has a value of 1 or greater. Then test the other three
words to see whether they designate the appropriate version, release and
modification level. It is IBM's intent that if one of the values in the first column
of the figure below is smaller than was returned for the corresponding value in
the prior release, then one of the values in the second column contains a larger
value than was returned in the prior release:
Third word (modification level)
Second word (release)
First word (version)
Fourth, first or second word
Fourth or first word
Fourth word
system_attr
System attributes are returned in the system_attr array. This is an output
argument. The array elements are defined as follows:
1
Status of the Storage Management Subsystem. A value of 0 indicates
inactive; 1 indicates active.
2–4
Reserved elements; 0 is returned.
Define as a four-element array of integers.
Return Codes
See Table 64 on page 354 for the IGWASYS return and reason codes.
Example
The following example shows a system attribute call using a CALL statement.
344
z/OS DFSMSdfp Advanced Services
Callable Services
.
.
CALL IGWASYS,(RC1,RS1,CODE1,LEVEL,ATTR) Test pre-DFSMS/MVS
LTR
R15,R15
Test return code
BNZ
BADSYS
CLC
LEVEL,=F’2’
Test for MVS/XA DFP Version 2
BE
OLDSYS
MVC
SYSNAME,UNKNAME Assume name is unknown
BL
BADSYS
Branch if unknown system
MVC
SYSNAME,=CL12’MVS/DFP’ Show we are on MVS/DFP
CLC
LEVEL+12(4),=F’1’
See if after MVS/DFP
BL
SHOWSYS
Branch if before DFSMS/MVS
CALL IGWASYS,(RC1,RS1,CODE2,LEVEL,ATTR)
LTR
R15,R15
Branch if environment or
BNZ
BADSYS
system error
MVC
SYSNAME,UNKNAME
Assume unknown product name
CLC
LEVEL+12(4),=F’1’
Test for DFSMS/MVS code
BL
OLDSYS
Branch if unexpected code
MVC
SYSNAME,=CL12’DFSMS/MVS’ Show product name
BE
SHOWSYS
Branch if DFSMS/MVS
MVC
SysName,=CL12’OS/390 DFSMS’ Set assumed new name
CLC
LEVEL+12(4),=F’3’
Branch if
BL
SHOWSYS
OS/390
BH
COPYSYS
Branch if after z/OS name
MVC
SysName,=CL12’z/OS DFSMS’ Assume early z/OS
* On z/OS. Test for early releases.
CLC
Level(8),=F’1,3’
Branch if
BL
ShowSys
before z/OS 1.3
* On z/OS 1.3 or later. Use the name provided by the system.
CopySys L
R14,16
Point to CVT
L
R15,CVTDFA-CVT(,R14) Point to DFA
L
R14,DFAELNMP-DFA(,R15) Point to element name
USING DFAELNM,R14
MVI
SysName,C’ ’
Blank out name
MVC
SysName+1(L’SysName-1),SysName
LH
R15,DFAELNML
Get name length
CH
R15,MaxLen
Skip one instruction if
BNH
*+8
name not too long
LH
R15,MaxLen
Truncate to our field length
BCTR R15,0
Decrement for EX instruction
EX
R15,MVCName
Copy name from DFA
DROP R14
ShowSys EQU
*
Handle version, release and modification level
.
.
RC1
DC
F’0’
Return code
RS1
DC
F’0’
Reason code
CODE1
DC
F’1’
Ask for pre-DFSMS DFP level
CODE2
DC
F’2’
Ask for level of DFSMS, or later
LEVEL
DC
4F’0’
Version, release, Modification Level and code
ATTR
DC
4F’0’
SMS attributes
SYSNAME DC
CL12’MVS/XA DFP’ Name of product
UNKNAME DC
(L’SYSNAME)C’?’
Constant for unknown name
MaxLen DC
Y(L’SysName)
Our maximum allowed length of name
MVCName MVC
SysName(0),DFAELTXT-DFAELNM(R14)
Figure 40. Example of an IGWASYS Call Statement
Call for Data Set Attribute Retrieval
The data set attribute retrieval call (IGWASMS), returns the names of the data set's
related SMS classes and whether it is a PDSE, or an HFS data set, or neither.
Chapter 9. Using DFSMSdfp Callable Services
345
Callable Services
Format
The format of the data set attribute IGWASMS call statement is:
►►
CALL IGWASMS
, (
return_code , reason_code ,
►
label
► prob_det
, dsname_length , dsname
, sms_data
, ds_type
)
►◄
Parameters
return_code
Return code from IGWASMS. The return code is also returned in register 15.
Return codes are explained in “IGWASYS, IGWASMS, IGWABWO, IGWLSHR
Return and Reason Codes” on page 354. This is an output argument that must
be defined as an integer.
reason_code
Reason code from IGWASMS. The reason code is also returned in register 0.
Reason codes are explained in “IGWASYS, IGWASMS, IGWABWO, IGWLSHR
Return and Reason Codes” on page 354. This is an output argument that must
be defined as an integer.
prob_det
Problem determination data. See “IGWASYS, IGWASMS, IGWABWO,
IGWLSHR Return and Reason Codes” on page 354 for more information about
problem determination data. This is an output argument that must be defined
as a two-element array of integers.
dsname_length
Length, in bytes, of the data set name provided by the caller in dsname. The
value can be a number from 1 to 44. This is a required input argument that
must be defined as an integer.
dsname
Name of the data set on which the IGWASMS service. For VSAM data sets, the
cluster name must be specified. This is a required input argument that must be
defined as EBCDIC character data of length dsname_length.
sms_data
The SMS class names associated with the specified data set returned,
left-justified with blanks padded on the right. The array elements are returned
in the following circumstances:
v Storage class name, or blanks if the data set is not an SMS data set.
v Management class name, or blanks if the data set has no associated
management class.
v Data class name, or blanks if the data set has no associated data class.
This is an output argument that must be defined as a three-element array,
where each entry is a 30 (byte) character EBCDIC string.
ds_type
The type of data set, dsname, is returned. A value of 1 indicates the data set is a
PDSE-type data set. A value of 2 indicates the data set is an HFS-type data set.
An HFS data set defines a file system and is not a file within the file system.A
346
z/OS DFSMSdfp Advanced Services
Callable Services
value of 0 indicates that it is neither. No other values are currently defined.
This is an output argument that must be defined as an integer.
Return Codes
See Table 64 on page 354 for the IGWASMS return and reason codes.
Example
The following example shows sample coding for a data set attribute call using a
LINK statement.
.
.
LINK EP=IGWASMS,MF=(E,ASMSLIST)
.
.
RC2
RS2
PROB1
DSNLEN1
DSN1
SMSDATA
DSTYPE
ASMSLIST
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
F’0’
F’0’
2F’0’
A(L’DSN1)
CL12’THIS.DATASET’
3CL30’ ’
F’0’
A(RC2)
A(RS2)
A(PROB1)
A(DSNLEN1)
A(DSN1)
A(SMSDATA)
A(DSTYPE)
Figure 41. Example of an IGWASMS Call LINK Statement
Call for Data Set Backup-While-Open Support
The data set backup-while-open support call (IGWABWO) communicates with
DFSMSdfp to retrieve or set indicators related to taking data set backups while
they are open for update.
Format
The format of the IGWABWO callable service is:
►►
CALL IGWABWO
, (
return_code , reason_code ,
►
label
► prob_det
, read_write
► bwo_flags
, bwo_recov
, dsname_length ,
, bwo_resrv
dsname , select
,
, )
►
►◄
Parameters
return_code
Return code from IGWABWO. The return code is also returned in register 15.
Chapter 9. Using DFSMSdfp Callable Services
347
Callable Services
Return codes are explained in “IGWASYS, IGWASMS, IGWABWO, IGWLSHR
Return and Reason Codes” on page 354. This is an output argument that must
be defined as an integer.
reason_code
Reason code from IGWABWO. The reason code is also returned in register 0.
Reason codes are explained in “IGWASYS, IGWASMS, IGWABWO, IGWLSHR
Return and Reason Codes” on page 354. This is an output argument that must
be defined as an integer.
prob_det
Problem determination data. See “IGWASYS, IGWASMS, IGWABWO,
IGWLSHR Return and Reason Codes” on page 354 for more information about
problem determination data. This is an output argument that must be defined
as a two-element array of integers.
read_write
Function indicator for this service. A caller-supplied value of 0 indicates that
this is a READ-type request for the backup-while-open (BWO) data of the
specified data set. A value of 1 indicates a WRITE-type request, that is, an
initialization or update of the specified data set's BWO data with the supplied
arguments bwo_flags, bwo_recov, and bwo_resrv. The select argument indicates
which arguments are to be processed. This is a required input argument that
must be defined as an integer.
dsname_length
Length, in bytes, of the data set name provided by the caller in dsname. The
value can be a number from 1 to 44. This is a required input argument that
must be defined as an integer.
dsname
Name of the data set that the IGWABWO service operates on. Only
system-managed VSAM-type data sets are eligible to be backed up while they
are open for update. The dsname specified must be the base cluster name of a
VSAM data set. This is a required input argument that must be defined as
EBCDIC character data of length dsname_length.
select
Indicates which of the following arguments will be processed. Arguments are
specified by selecting the appropriate value. This is a required input argument.
1 to process bwo_flags
2 to process bwo_recov
3 to process bwo_flags and bwo_recov
Regardless of how many arguments are to be processed, all three fields
(bwo_flags, bwo_recov, and the reserved bwo_resrv field) must be defined in your
program and included in the invocation. Those not selected will receive no
value in a READ-type request. The values of those not selected will be ignored
in a WRITE-type request.
bwo_flags
This argument is a three-element array, whose elements correspond to the three
BWO flags associated with an SMS data set. bwo_flags is an output argument
for read_write=0 type requests, and a required input argument for read_write=1
type requests.
1. The first element is associated with flag, BWO1. 1 is on, 0 is off.
2. This element corresponds to flag, BWO2. 1 is on, 0 is off.
3. This element corresponds to flag, BWO3. 1 is on, 0 is off.
Define as a three-element array of integers.
348
z/OS DFSMSdfp Advanced Services
Callable Services
bwo_recov
This argument is an 8-byte storage area containing the recovery timestamp
associated with a data set that is eligible for BWO. bwo_recov is an output
argument for read_write=0 type requests, and a required input argument for
read_write=1 type requests. The format of the timestamp for CICS® VSAM
data sets is as follows:
v The first word contains the date in packed decimal format, 0CYYDDDF,
where:
0C
is the century - 00 represents 19YY, 01 represents 20YY
YY
is the last two digits of the year
DDD is the day of the year (Julian date)
F
is the sign (F for positive number)
v The second word contains the time in packed decimal format, HHMMSSTF,
where:
HH
Hours, based on a 24-hour clock
MM
Minutes
SS
Seconds
T
Tenths of a second
F
is the sign (F for positive number)
bwo_resrv
This argument is reserved for future use. While the bwo_resrv argument cannot
be written or read, it must be defined in your program and included in the
invocation. Define as EBCDIC character data of length 16 bytes.
Return Codes
See Table 64 on page 354 for the IGWABWO return and reason codes.
Example
The following example shows sample coding for WRITE and READ-type
backup-while-open calls using LOAD and CALL statements.
Chapter 9. Using DFSMSdfp Callable Services
349
Callable Services
.
.
LOAD
LR
CALL
CALL
EP=IGWABWO
R2,R0
(R2),(RC1,RS1,PROB1,RW1,DSNLEN1,DSN1,SEL1,BWOF1,BWOR1,BWRE)
(R2),(RC2,RS2,PROB2,RW2,DSNLEN2,DSN2,SEL2,BWOF2,BWOR2,BWRE)
.
.
* ARGUMENTS FOR WRITING
RC1
DC F’0’
RS1
DC F’0’
PROB1
DC 2F’0’
RW1
DC F’1’
WRITE
DSNLEN1 DC F’11’
DSN1
DC CL44’THAT.VSAM01’
SEL1
DC F’3’
WRITE BWO_FLAGS AND BWO_RECOV
BWOF1
DC F’0’
DC F’1’
DC F’0’
BWOR1
DS 0F
DC X’0096137F’
INPUT DATE IN 0CYYDDDF FORMAT
DC X’1045301F’
INPUT TIME IN HHMMSSTF FORMAT
BWRE1
DC CL16’ ’
* ARGUMENTS FOR READING
RC2
DC F’0’
RS2
DC F’0’
PROB2
DC 2F’0’
RW2
DC F’0’
READ
DSNLEN2 DC F’11’
DSN2
DC CL44’THAT.VSAM01’
SEL2
DC F’3’
READ BWO_FLAGS AND BWO_RECOV
BWOF2
DC 3F’0’
BWOR2
DC CL8’ ’
BWRE2
DC CL16’ ’
*
Figure 42. Example of IGWABWO Using LOAD and CALL Statements
Using the Backup-While-Open Facility
The following information describes the usage of the backup-while-open (BWO)
facility. BWO flags and the BWO recovery field can be retrieved or updated using
the IGWABWO service described in “Call for Data Set Backup-While-Open
Support” on page 347. The BWO indicators are described in Table 63 on page 353.
For environments that require high-availability, it might not be possible or
desirable to stop or quiesce an application to produce consistent backup copies of
the application's data sets.
For these environments DFSMSdfp provides support to allow SMS-managed
VSAM data sets that are open for output to be backed up. The support is only
useful for applications (such as database systems) that can recover a restored
database to a point of consistency. This is typically done from a log (forward
recovery log) maintained by the application that contains record images of all
changed (added, deleted, or updated) records. These images can then be reapplied
to a backup copy of the database, logically recreating the status of the database at
a particular point in time.
350
z/OS DFSMSdfp Advanced Services
Callable Services
The support provided by BWO might not be necessary for online applications that
can quiesce the database data sets to ensure no output or update activity against
the data set while the backup is in progress. Quiescing a data set in this context
means the data set is closed and unallocated.
The following discussion of the operation of this support uses these terms:
v Database manager-the application that controls access to the data sets to be
processed. In order for BWO support to be effective, the database manager must
have some logging facility to allow point-in-time reconstruction of a database.
v Backup manager-the applications or products that perform the backup and
restore functions, such as DFSMShsm and DFSMSdss.
v Recovery manager-the component that manages the inventory of recovery logs
and applies the changes from the appropriate log(s) to the restored data set.
The following paragraphs describe the relationships between the BWO support
and a user of BWO. Refer to Table 63 on page 353 for the various states of the
BWO flags in the following discussion. The BWO indicators are retained in the
catalog. The BWO flag states are set or reset using the DFSMSdfp callable system
service IGWABWO.
v At initial allocation (IDCAMS DEFINE, IDCAMS or TSO ALLOCATE, JCL and
dynamic allocation), the data set is not enabled for BWO (default, BWO flag
state is 000).
v The database manager should check the BWO flags prior to opening the data set
to ensure it is not downlevel (BWO flag state is 101 or 001). If the data set is
downlevel, the recovery manager must be used to apply log changes to the data
set.
v The database manager must set flag BWO1 (BWO flag state 100) on for each
data set that is allowed to be backed up while open for output. This authorizes
the backup manager to initiate backups without serializing the data set, whether
or not it is being accessed by the application.
v The backup manager must retrieve the BWO flags prior to the start of the
backup. If BWO1 is on, then a backup can be taken without any serialization;
otherwise, normal data set serialization must be performed by the backup
manager.
When the backup completes, the backup manager must retrieve the BWO flags
again. If the BWO flag state has changed, then at some point during the backup
an action occurred that prevented creation of a valid backup. The backup
manager should discard the backup just created.
v When the data set needs to be recovered, it is first restored using the backup
manager. Data sets are serialized during restore to prevent applications from
accessing them. The backup manager must set the BWO flags at the completion
of the restore to indicate whether the restore was done using a backup copy that
was created with or without serialization.
– If the backup was taken without serialization, the BWO flags must be set to
101.
– If the backup was taken with serialization, the BWO flags must be set to 000.
In either case, the application administrator should decide whether or not to
apply recovery logs.
The database manager should not allow access to the data set until the recovery
manager has completed processing.
v The recovery manager should change the BWO flags to 001 before opening the
data set, apply the logs, and then set the flags to 000 to indicate that the data set
Chapter 9. Using DFSMSdfp Callable Services
351
Callable Services
has been processed and is consistent. The database manager can then reestablish
normal access to the data set (thus opening the data set for use).
v For a data set that is enabled for BWO, in certain instances the system prevents
starting a backup copy without serialization (for example, during a CI/CA split)
by setting the BWO flags to 010. This indicates a backup should not be started
without serialization (BWO1 off), and that a backup that is currently in process
should be considered invalid. When the condition that prevented the starting of
a backup is ended, the system resets the BWO flags to 110. This indicates that a
backup can now be started without serialization, and that any backup in
progress should be discarded.
v If the database data sets are accessed by batch programs (when the database
manager is not accessing the data sets) that do not create forward recovery logs,
the database manager should clear the BWO1 flag and set the BWO3 flag at
close (that is, OX1). The setting of the BWO2 flag should not be changed. If the
backup manager discovers this BWO state at the end of backup without
serialization, the backup is not valid and should be discarded. The backup
manager can start a backup with serialization if the BWO flag state is 011, but
the flags should be reset to 000.
Note:
1. Since backups can result in heavy I/O activity, you might want to take backups
during the time of least activity against the data set to avoid affecting the
application response time.
2. The BWO flags are not locked between reading and setting them with
IGWABWO. The application is responsible for providing serialization when the
settings of the flags are changed.
3. KSDS data sets require special consideration. Inserts and updates can result in
control interval (CI) and control area (CA) splits. Backups taken without
serialization during CI and CA splits are discarded by the IBM products to
prevent missing or duplicate records in the backup copies.
The frequency of CI and CA splits depends on the insert activity, the update
activity that increases the lengths of records, and the amount of free space in CI
and CA. For KSDS data sets that are BWO enabled, run backups during
periods of low inserts and updates or ensure adequate free space in control
intervals and control areas.
4. Backups without serialization can be taken (on data sets defined with share
option 1 or 2) when:
v The database contains alternate indices in the upgrade set.
v The database is accessed by pathnames, or with ddname or dsname sharing.
5. Data sets can be opened regardless of the setting of the BWO flags. It is the
database manager's responsibility to determine whether the contents of the data
set are consistent.
6. The database manager can use the BWO recovery field to store information
(such as the log RBA or log timestamp) for the recovery manager to use in
locating the appropriate recovery logs.
7. BWO concept only applies to logical data set backup/restore. It does not apply
to physical data set backup/restore or full volume dump/restore.
Table 63 on page 353 describes the meaning of each of the BWO (BWO1, BWO2,
and BWO3) indicators.
352
z/OS DFSMSdfp Advanced Services
Callable Services
Table 63. Backup-While-Open Indicators
BWO Setting
Description
000
001
010
Data set does not support backup without serialization.
Forward recovery in progress. Reset to 000 after recovery.
A CI/CA split for a BWO data set is in progress. Do not start backup. If
backup in progress, discard at end. This state can exist at open if the
database manager abended during split. Database action depends on
database manager. The data set might need restore and forward recovery
or backout of changes if AIXs are present.
The database manager closed a BWO data set and a CI/CA split had
occurred when it was previously open. Backup manager should reset it
to 000 and serialize to back up, not a BWO candidate. The database
manager should change this state to 110 at open.
A BWO data set has been opened by the database manager. Back up
without serialization.
Data set has been restored and requires forward recovery before it can
be used. Reset it to 001 before forward recovery.
A CI/CA split has occurred and completed on a BWO data set. This
state can exist at open if the database manager abended. Back up
without serialization. Reset it to 100 before backup.
An invalid state.
011
100
101
110
111
Call for DFSMSdfp Share Attributes
The DFSMSdfp share attributes call (IGWLSHR) returns the DFSMSdfp share
attributes currently in use.
Format
The format of the IGWLSHR callable service is:
►►
CALL IGWLSHR
, (
return_code , reason_code ,
►
, share_attr_array_length
►
label
► prob_det
, share_attr_selector
,
► share_attr_array )
►◄
Parameters
return_code
Return code from IGWLSHR. The return code is also returned in register 15.
Return codes are explained in “IGWASYS, IGWASMS, IGWABWO, IGWLSHR
Return and Reason Codes” on page 354. This is an output argument that must
be defined as an integer.
reason_code
Reason code from IGWLSHR. The reason code is also returned in register 0.
Reason codes are explained in “IGWASYS, IGWASMS, IGWABWO, IGWLSHR
Return and Reason Codes” on page 354. This is an output argument that must
be defined as an integer.
Chapter 9. Using DFSMSdfp Callable Services
353
Callable Services
prob_det
Problem determination data. See “IGWASYS, IGWASMS, IGWABWO,
IGWLSHR Return and Reason Codes” for more information about problem
determination data. This is an output argument that must be defined as a
two-element array of integers.
share_attr_selector
Use to specify which DFSMSdfp share attributes are requested. Code a value of
1 to request the PDSE sharing protocol attributes. This is a required input
argument that must be defined as an integer.
share_attr_array_length
Use to specify the size of the share attributes array. This length represents the
number of array elements in the share_attr_array. Code the value required for
the chosen share_attr_selector value. The share_attr_array_length must minimally
be 1 when the share_attr_selector is 1. This is a required input argument that
must be defined as an integer.
share_attr_array
Returns DFSMSdfp share attributes. This is an output argument. Define as an
array of integers of length share_attr_array_length, where share_attr_array_length
is the length required for the chosen share_attr_selector value. The array
elements for the share_attr_selector value are returned as follows:
1
Status of PDSE sharing protocol. A value of 0 indicates PDSE support is
unavailable; that is, the system supports the call, but SMS PDSE support is
not active. If the system does not support this call (as with a previous
release), then a return code of 36 is returned.
A value of 1 indicates normal PDSE sharing protocol in use. A value of 2
indicates extended PDSE sharing protocol in use.
2–4
Reserved elements; 0 is returned.
Return Codes
See Table 64 for the IGWLSHR return and reason codes.
IGWASYS, IGWASMS, IGWABWO, IGWLSHR Return and
Reason Codes
When IGWASYS, IGWASMS, IGWABWO, or IGWLSHR returns control to the
calling program, it provides both a return code and a reason code. IGWASMS and
IGWABWO can return additional data useful for problem determination in the
prob_det array. IGWLSHR can return additional data regarding share_attr_selector
and share_attr_array_length arguments. The following table identifies return code
and reason code combinations, tells what each means, explains what and when
additional problem determination data is returned, and recommends what action
should be taken.
Table 64. IGWASYS, IGWASMS, IGWABWO, IGWLSHR Return and Reason Codes
Return Code Dec
(Hex)
Reason Code
Dec (Hex)
0 (0)
4 (4)
0 (0)
4 (4)
354
z/OS DFSMSdfp Advanced Services
Description
The operation was successful.
The operation was successful, but the bwo_recov argument has no valid
value for the data set specified in dsname. This is because it was created
under DFP 3.1.0, and no bwo_recov has been added to the data set. Add
bwo_recov to the data set as appropriate.
Callable Services
Table 64. IGWASYS, IGWASMS, IGWABWO, IGWLSHR Return and Reason Codes (continued)
Return Code Dec
(Hex)
Reason Code
Dec (Hex)
8 (8)
4 (4)
8 (8)
8 (8)
8 (8)
12 (C)
8 (8)
16 (10)
8 (8)
20 (14)
8 (8)
24 (18)
8 (8)
28 (1C)
8 (8)
32 (20)
12 (C)
8 (8)
12 (C)
12 (C)
12 (C)
16 (10)
16 (10)
4 (4)
20 (14)
4 (4)
36 (24)
4 (4)
Description
An invalid dsname_length or share_attr_selector was specified. Correct the
argument and retry the request.
An invalid dsname of blanks or invalid share_attr_array_length was specified.
Correct the argument and retry the request.
An invalid read_write was specified. A value of 0 or 1 must be supplied.
Correct the read_write argument and retry the request.
The values supplied for bwo_flags are not valid. BWO1, BWO2, and BWO3
must have a value of either 0 or 1. Correct the bwo_flags argument and retry
the request.
BWO is only supported for VSAM-type data sets. The name specified was
not a VSAM cluster name. Specify the name of a VSAM cluster in the
dsname argument and retry the request.
An invalid level_indicator was specified. Correct the level_indicator argument
and retry the request.
An invalid select argument was specified. A value between 1 and 3 must be
specified. Correct the select argument and retry the request.
The data set specified in dsname is not an SMS-managed data set. Correct
the dsname argument and retry the request.
There is insufficient virtual storage to process the request. Free some virtual
storage and retry the request. If the condition persists, contact IBM for
programming assistance.
The data set specified in dsname could not be found. Verify that the data set
exists and has been correctly specified in dsname.
The data set specified in dsname is currently in MIGRATE status.
An error occurred on a call to catalog management. The catalog return code
is in the first element of prob_det and the catalog reason code is in the
second element of prob_det. See message IDC3009I for an explanation of the
catalog return code and reason code. A catalog management return code of
8 indicates that the specified data set was not found. If you get this return
code, correct dsname and retry the request.
A system error occurred during IGWASYS/SMS/BWO or IGWLSHR
processing. The elements of prob_det contain additional diagnostic data.
Contact IBM for programming assistance and provide them with the
IGWASYS/SMS/BWO return_code, reason_code, and prob_det values.
Linkage cannot be established to the IGWLSHR service module or to
IGWASYS/SMS/BWO service modules, IGWAMCS1 and IGWAMCS2.
Either the wrong level of the operating system is being used, or the callable
system service library, SYS1.CSSLIB, is missing the required services.
Contact your installation system programmer for assistance.
Call for Record-Level Sharing Query (IGWARLS)
IGWARLS is used to query the information in the catalog for record-level sharing.
Format
The format of the IGWARLS call statement is:
Chapter 9. Using DFSMSdfp Callable Services
355
Callable Services
►►
CALL IGWARLS
, (
return_code , reason_code ,
►
label
► prob_det
, dsname_length , dsname
► logstreamid_length
, recovery_status
, log_type
,
, logstreamid , rls_recovery_timestamp_utc ,
► rls_recovery_timestamp_local ,
vsam_quiesced , bwo )
►
►
►◄
Parameters
return_code
Return code from IGWARLS. The return code is also returned in register 15.
Return codes are explained in “Return Codes” on page 357. This is an output
argument. Define return_code as an integer.
reason_code
Reason code from IGWARLS. The reason code is also returned in register 0.
Reason codes are explained in “Return Codes” on page 357. This is an output
argument. Define reason_code as an integer.
prob_det
Problem determination data. See “Return Codes” on page 357 for more
information about problem determination data. This is an output argument.
Define prob_det as a two element array of integers.
dsname_length
Length, in bytes, of the data set name provided by the caller in dsname. The
value can be a number from 1 to 44. This is a required input argument. Define
dsname_length as an integer.
dsname
Name of the base cluster that the IGWARLS service will operate on. This is a
required input argument. Define dsname as EBCDIC character data of length
dsname_length.
recovery_status
Returns an indication as to whether the sphere is marked as requiring forward
recovery.
v 0 - RLS recovery required is not pending for the VSAM sphere.
v 1 - RLS recovery required is pending.
recovery_status is an output argument that is defined as an integer.
log_type
The specification of the LOG= parameter on DEFINE CLUSTER is returned.
v 1 - LOG parameter undefined
v 2 - LOG=NONE
v 3 - LOG=UNDO
v 4 - LOG=ALL
log_type is an output argument that is defined as an integer.
logstreamid_length
Length, in bytes, of the LOGSTREAMID field. This is a required input
parameter. Define logstreamid_length as an integer. The value of
logstreamid_length should be at least 26 bytes.
356
z/OS DFSMSdfp Advanced Services
Callable Services
logstreamid
The specification of the LOGSTREAMID on DEFINE CLUSTER is returned. If
the parameter is undefined, blanks are returned. The caller can determine the
size of the returned LOGSTREAMID field by scanning from right to left
looking for a non blank character or until the entire field has been scanned.
logstreamid is an output argument that is defined as an EBCDIC character data
field of length logstreamid_length.
rls_recovery_timestamp_utc
An output argument which represents the UTC time (formally known as GMT)
of the dump/copy in STCK format. The field is defined as an eight-byte
unsigned integer. Your program might regard this field as either an integer or a
character string.
rls_recovery_timestamp_local
An output argument which represents the local time of the dump/copy in
STCK format. The field is defined as an eight-byte unsigned integer. Your
program might regard this field as either an integer or a character string.
vsam_quiesced
An output argument which indicates whether the sphere is marked as
VSAM_QUIESCED.
v 0 - The sphere is not marked VSAM_QUIESCED.
v 1 - The sphere is marked VSAM_QUIESCED.
vsam_quiesced is an output argument, defined as an integer.
bwo
An output argument which indicates whether the value of the BWO parameter
on define cluster.
v 1 - BWO parameter is undefined.
v 2 - BWO = TYPECICS processing allowed.
v 3 - BWO = NO. BWO processing is not allowed.
v 4 - BWO = TYPEIMS processing allowed.
v 5 - BWO = TYPEOTHER processing allowed.
Return Codes
When IGWARLS returns control to the calling program, it provides both a return
code and a reason code. IGWARLS can return additional data useful for problem
determination in the prob_det array. Table 65 identifies return code and reason code
combinations, tells what each means, explains what and when additional problem
determination data is returned, and recommends what action should be taken.
Table 65. IGWARLS Return and Reason Codes
Return Code Dec
(Hex)
Reason Code Dec
(Hex)
0 (0)
8 (8)
0 (0)
4 (4)
8 (8)
8 (8)
8 (8)
20 (14)
8 (8)
32 (20)
Description
The operation was successful.
An invalid dsname_length was specified. Correct the dsname_length argument
and retry the request.
An invalid dsname of blanks was specified. Correct the dsname argument and
retry the request.
IGWARLS is only supported for VSAM data sets. The name specified was
not the name of the base cluster. Specify the name of the base cluster in the
dsname argument and retry the request.
The data set specified in dsname is not an SMS managed data set. Correct
the dsname argument and retry the request.
Chapter 9. Using DFSMSdfp Callable Services
357
Callable Services
Table 65. IGWARLS Return and Reason Codes (continued)
Return Code Dec
(Hex)
Reason Code Dec
(Hex)
8 (8)
40 (28)
12 (C)
8 (8)
12 (C)
12 (C)
12 (C)
14 (E)
12 (C)
16 (10)
16 (10)
4 (4)
20 (14)
4 (4)
36 (24)
4 (4)
Description
For IGWARLS, the logstreamid_length specified was invalid (<=0) or was
not large enough to return the requested logstreamid. Correct the
logstreamid_length argument and retry the request.
There is insufficient virtual storage to process the request. Retry the request.
If the condition persists, contact IBM for programming assistance.
The data set specified in dsname could not be found. Verify that the data set
exists and has been correctly specified in dsname.
The data set specified in dsname was found in the catalog but its attributes
were not available. Verify that the data set has been correctly specified in
dsname.
Cannot access the data set that is specified in dsname. The data set has been
HSM migrated. HRECALL the data set and retry the request.
An error occurred on a call to catalog management. The catalog return code
is in the first element of prob_det and the catalog reason code is in the
second element of prob_det. See message IDC3009I for an explanation of the
catalog return code and reason code. A catalog management return code of
8 indicates that the specified data set was not found. If you get this return
code, correct dsname and retry the request.
A system error occurred during IGWARLS processing. The elements of
prob_det contain additional diagnostic data. Contact IBM for programming
assistance and provide them with the IGWARLS return_code, reason_code,
and prob_det values.
Linkage cannot be established to the IGWRLS service module, IGWAMCS4.
Either the wrong level of the operating system is being used, or the callable
system service library, SYS1.CSSLIB, is missing the required services.
Contact your installation system programmer for assistance.
Example
The following example shows the RLS query call using LOAD and CALL
statements:
.
.
RC1
RS1
PROB1
DSNLEN1
DSN1
RECSTAT
LOGTYPE
LOGSTRML
LOGSTRM
RCVTMG
RCVTML
VSAMQUIS
BWO
LOAD
LR
CALL
EP=IGWARLS
R9,R0
(R9),(RC1,RS1,PROB1,DSNLEN1,DSN1,RECSTAT,LOGTYPE,
LOGSTRML,LOGSTRM,RCVTMG,RCVTML,VSAMQUIS,BWO)
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
F’0’
F’0’
2F’0’
A(L’DSN1)
CL12’BASE.CLUSTER’
F’0’
F’0’
A(L’LOGSTRM)
CL26’ ’
XL8’00’
XL8’00’
F’0’
F’0’
Figure 43. Example of the IGWARLS Query Call Using LOAD and CALL Statements
358
z/OS DFSMSdfp Advanced Services
X
Callable Services
Call for converting and comparing 28-bit cylinder addresses
(IECTRKAD)
IECTRKAD is a callable service to perform conversions and compares of 28-bit
cylinder addresses. The track addresses are in the form CCCCcccH, where CCCC is
the 16 low order bits of the cylinder number and ccc is the 12 high order bits of it.
Cobol, PL/I, and C programs can call IECTRKAD without having to write
assembler routines to invoke TRKADDR.
The caller requirements of IECTRKAD are:
v Register 1 contains an address to a parameter list. Register 0 is not used.
Register 13 points to a standard register 18-word save area and registers 14 and
15 have their standard usage.
v Calling program can be in either 24-or 32-bit addressing mode
v Calling program can be executing in any protection key and in either supervisor
or problem state
The called routine, IECTRKAD, has the following characteristics:
v No executable macro other than CALL and LINK is provided to call IECTRKAD.
v The called routine resides in SYS1.CSSLIB and is shipped in distribution library
ACSSLIB.
v User program can link edit with the called routine to invoke IECTRKAD.
v User program can use the LINK macro or the LOAD and CALL macros to
invoke IECTRKAD.
v IECTRKAD processing will use the equivalent TRKADDR function and pass the
result back accordingly.
v IECTRKAD is release independent; if you link or bind IECTRKAD with your
program, it will run on earlier or later releases of z/OS. This includes releases
before the first availability of IECTRKAD.
Format
You can adapt the assembler language syntax shown here to your computer
language such as C, COBOL or PL/I:
►►
CALL IECTRKAD
, (
operation
label
►
, cchh1
►
, cchh2
, returncode
,
reasoncode )
►◄
, number
Parameters
Where the parameters are:
operation
Specifies the operation to perform. This parameter is the name of a field that
contains character data of length 10. The allowable values are:
Chapter 9. Using DFSMSdfp Callable Services
359
Callable Services
ABSTOREL
calculates the relative track number on the volume from the passed cchh1
track address.
COMPARE
compares the two track addresses passed in cchh1 and cchh2.
EXTRACTCYL
extracts the 28-bit cylinder number from the passed cchh1 track address.
EXTRACTTRK
extracts the 4-bit track number from the passed cchh1 track address.
NEXTTRACK
increments the track address by one track and increments the cylinder
number if necessary from the passed cchh1 track address.
NORMALIZE
reverses the 16-bit and 12-bit portions of the cylinder number from the
passed cchh1 track address. The CCCCcccH becomes cccCCCCH. This could
be used to subsequently perform unsigned comparisons of track addresses.
NORMTOABS
reverses the 12-bit and 16-bit portions of the cylinder from the track
address passed in number. The cccCCCCH becomes CCCCcccH. Use this to
convert a normalized track address to an absolute 28-bit cylinder address.
RELTOABS
converts a relative track number, passed in number, to a 28-bit cylinder
address.
SETCYL
converts a relative cylinder number, passed in number, to a 28-bit cylinder
address and sets the head portion to zero.
If you request an operation that is less than 10 characters, it must be padded
on the right with blanks.
cchh1
Required parameter, cchh1, is a four-byte area containing a track address that
nominally is in the form of CCHH. For all functions except RELTOABS and
SETCYL this is input to the called routine. For RELTOABS, SETCYL, and
NORMTOABS this is output from the called routine.
cchh2
Optional positional parameter, cchh2, is a four-byte area whose meaning
depends on the operation specified by the first parameter. For all functions
except COMPARE and NEXTTRACK this parameter is ignored.
For COMPARE processing, cchh2 contains the track address that is to be
compared to the first cchh1 parameter.
For NEXTTRACK processing, cchh2, is the four-byte output area to contain the
track address (CCHH) of the next logical track on the volume. If the input
track number is 0 to 13, the output cylinder number will be the same and the
output track number will be one greater than the input track number. If the
input track number is 14, the output cylinder will be one higher than the
cylinder number in cchh1 and the output track number will be 0. The called
routine does not check for numeric overflow.
360
z/OS DFSMSdfp Advanced Services
Callable Services
number
Optional positional parameter, number, is a four-byte integer whose meaning
depends on the operation specified by the first parameter.
For ABSTOREL processing, number is the output area that will contain the
relative track number on the volume.
For COMPARE processing, number is the output area that will contain the
result of the comparison. Zero means the inputs are equal. Negative one means
the first one is lower. Positive one means the first one is higher.
For EXTRACTCYL processing, number is the output area that will contain the
28-bit cylinder number with the four high order bits set to zero.
For EXTRACTTRK processing, number is the output area that will contain the
four-bit track number with the 28 high order bits set to zero.
For NEXTTRACK processing, number is an ignored parameter. It can be 0 or
any valid virtual address. Not checked by the called routine.
For NORMALIZE processing, number is the output area that will contain the
normalized version of the input CCHH. The CCCCcccH becomes cccCCCCH.
The high order 28-bits are the cylinder number and the low order four bits are
the track number. This allows your code to do a more efficient comparison of
one track address with many track addresses. Normalize each and do unsigned
comparisons.
For NORMTOABS processing, number is the input area that contains the
normalized track address to be converted. The cccCCCCH becomes CCCCcccH.
Use this to convert a normalized track address to an absolute 28-bit cylinder
address.
For RELTOABS processing, number is the input area that contains the relative
track number on the volume. For example the first two tracks on the second
cylinder (cylinder 1) have relative track numbers of 15 and 16. The called
routine converts the relative track number to a 28-bit nonlinear cylinder
address with a 4-bit head value in the low order four bits in the cchh1 output
area.
For SETCYL processing, number is the input area that contains the cylinder
number on the volume in the low order 28-bits with the four high order bits
set to zero. The called routine splits the 28-bits into the high order 12-bits and
low order 16-bits, reverses them in the output field, cchh1, with the cylinder
address in the high order 28-bits and the low order four bits to zero
returncode
returncode is a 4-byte integer that contains the return code from IECTRKAD
processing. returncode is also returned in register 15. The return codes that
could be set include the following:
0
Successful.
4
Successful, but with exceptions
8
Request was unsuccessful because of invalid or incorrect input. Refer
to thereasoncode for more detailed information
reasoncode
reasoncode is a 4-byte integer associated with a specific return code. reasoncode is
returned in Register 0.
No reason codes are supplied for return code 4:
The following reason codes are supplied for return code 8:
Chapter 9. Using DFSMSdfp Callable Services
361
Callable Services
4
The H portion of a track address is not valid on a NEXTTRACK
operation
8
The caller specified an invalid operation (the first parameter is not one
of the supported operations)
12
The address of a required parameter is zero.
Character Data Representation Architecture (CDRA) APIs
The following CDRA APIs are included in the DFSMS product library. For more
detailed description of both the APIs and their use, see Character Data
Representation Architecture Reference and Registry.
API
Description
CDRGESP
Get Encoding Scheme, Character Set, and Code Page Elements
CDRSCSP
Get Short Form (CCSID) from Specified ES (CS, CP)
CDRGESE
Get Encoding Scheme Element and its Subelements
CDRGCTL
Get Control Function Definition
CDRSMXC
Get Short Form (CCSID) with maximal CS for Specified ES, CP
CDRMSCI
Multiple-Step Convert Initialize
CDRMSCP
Multiple-Step Convert Perform
CDRMSCC
Multiple-Step Convert Clean Up
CDRXSRF
Extract Status and Reason Codes from Feedback Code
362
z/OS DFSMSdfp Advanced Services
Chapter 10. Using the DESERV Exit
The DESERV exit was designed to support those programs which, before the
binder, used SVC screening or replacement of the SVC table to trap SVC 21
(STOW) in order to monitor STOWs. DESERV provides an equivalent function to
that obtained by SVC Screening or replacing the SVC table entry for SVC 21 (or
SVC 12, BLDL). The DESERV exit can be used along with the SVC screening and
SVCUPDTE facilities to monitor accesses and updates to PDS and PDSE
directories.
The system calls the DESERV GET function when the following occurs:
v The binder is used to bind a program object or a load module and it is searching
for member names to be included. (Note the linkage editor does not use
DESERV).
v The system is searching for modules to load into storage while processing the
ATTACH, LINK, LOAD or XCTL functions.
In these situations the system uses DESERV GET rather than issuing BLDL.
However, in some situations DESERV GET issues BLDL to perform the directory
search (the BLDL function does not issue DESERV calls). The system calls the
DESERV PUT function when the following occurs:
v The binder is creating a program object in a PDSE (note the linkage editor does
not use DESERV, nor does the binder use DESERV PUT when creating a load
module in a PDS).
v An IEBCOPY job is loading a program object from an IEBCOPY unloaded data
set.
v An IEBCOPY job is copying a member to a PDSE where one of the member‘s
names is greater than 63 bytes long.
In these situations the system uses DESERV PUT rather than issuing STOW. The
DESERV PUT and STOW code do not interact. STOW does not issue DESERV PUT
nor does DESERV PUT issue STOW.
Currently the system does not use the RENAME or UPDATE functions. SMP/E is
the only known user of the DELETE function. The rename, update and delete
functions and the STOW code do not interact.
With SVC screening, an SVC screen table is associated with a task control block
(TCB). The table marks specific SVC numbers as not valid. The table also defines
the address of a routine that gets control when an SVC that is not valid is issued.
Then it's possible for the screen routine to inhibit the function, perform the
function itself, or temporarily disable the SVC screening and re-issue the SVC. This
technique provides a front and back end mechanism for SVC routines.
With SVCUPDTE, an application can dynamically replace or delete SVC table
entries for the system or obtain the SVC number of a routine at a specified entry
point. One specific use of the replace function of SVCUPDTE would use a scenario
like the following to replace an IBM supplied SVC routine.
1. Extract the SVC entry for SVC 18 (BLDL) from the SVC table.
2. Issue SVCUPDTE to install the vendor's version of the BLDL function.
3. When an SVC 18 is issued, the vendor's BLDL module gets control.
© Copyright IBM Corp. 1979, 2017
363
DESERV Exit
4. The vendor's BLDL either performs the function and returns to the caller, or
branch enters the IBM supplied BLDL code whose address was obtained earlier
from the SVC table.
For more detail and explanation of the DESERV functions, see z/OS DFSMS Using
Data Sets; for their macros, see z/OS DFSMS Macro Instructions for Data Sets.
DESERV provides a task level exit for an interface that is similar to SVC screening
for the SVC routines BLDL and STOW. DESERV also provides a global exit for an
interface that is similar to the SVCUPDTE replace option. For more information on
using SVC Screening and SVCUPDTE, refer to z/OS MVS Programming: Authorized
Assembler Services Reference SET-WTO and z/OS MVS Programming: Authorized
Assembler Services Guide.
Task Level Exit
The task level DESERV exit can be established for any TCB following the LPA's
initialization. Once established for a task, the DESERV exit is given control for the
DESERV functions that are issued under the TCB. The exit entry point is given
control twice for each GET, PUT, RENAME, DELETE, or UPDATE invocation; once
before DESERV executes and once immediately before the return from the DESERV
function. The parameters passed to the exit indicate whether this call happens
before or after the DESERV function executes.
If a DESERV FUNC=GET call is made for which there are no PDSEs in the
concatenation, the DESERV code issues BLDL to search for the requested names.
The task level exit is called in this case. However, if SVC screening is also active,
the exit might perform one of the following tasks:
v Not process this DESERV call (that is, lets the SVC screen routine process the
BLDL request) or
v Process this DESERV call with the pre- and post-processing exits, but also
disable the SVC screening for BLDL in the pre-processing exit and enable the
BLDL screening in the post-processing exit. A parameter passed to the exit
indicates whether a BLDL will be or has been issued.
Just as with the SVC screening facility, the DESERV task level exit function enables
the user to indicate that the exit should be propagated to subsequently attached
tasks.
The first DESERV call for a task searches the TCB chain for a DESERV task level
exit routine with propagate specified. DESERV searches the TCB chain following
the originating TCB pointer (TCBOTC). If none exists, the task is marked to
indicate that no DESERV task level exit exists. Therefore, for the propagate option
to work, the exit routine must be established before issuing the ATTACH macro.
This is roughly consistent with implementing SVC screening. The difference is that
the SVC screening table is propagated at the time of the ATTACH, while the
DESERV exit might not be propagated at ATTACH (for example, if the attached
program is found in the job pack queue, no directory search (that is, DESERV GET)
is done to find the module).
364
z/OS DFSMSdfp Advanced Services
DESERV Exit
Global Exit
The global DESERV exit can be established for the system following the
initialization of LPA. When establishing a global exit, obtain the DST (DESERV
Screen Table) storage in common storage. The DST is used to identify a DESERV
exit. Once established, the DESERV exit gets control anytime DESERV GET, PUT,
RENAME, DELETE, or UPDATE functions are called. The exit entry point is given
control twice for each invocation, once before DESERV is executed, and once
immediately after the return from the DESERV function. The call to the exit
indicates whether this call is before or after DESERV executes. The global exit
routine must reside in commonly addressable storage.
If a DESERV FUNC=GET call is made for which there are no PDSEs in the
concatenation, the DESERV code issues BLDL to search for the requested names.
The global exit is called in this case. If both the SVCUPDTE facility and the
DESERV global exit are used, before implementing the global DESERV exit
consider the interactions of the DESERV global exit and the routine that is given
control when the SVC is issued.
Interactions Between the Task Level and Global Exits
If both task level and global DESERV exits have been defined, there is a prescribed
calling sequence. The task level exit is called first. If the task level exit indicates
that the DESERV function should be terminated (via a return code 4 from the exit),
DESERV returns immediately to its caller. However, the global exit is given control
when the task level exit returned with return code 0. The global exit can indicate
(via return code 4) that control should pass back immediately to the DESERV
caller. In this case before returning to the DESERV caller, the task level exit is given
control indicating that the DESERV function is complete. After returning from the
task level exit, DESERV returns to the caller.
If the global exit returns with return code 0, the DESERV function executes,
making the post-processing exit calls. The post processing exit calls are made first
to the global exit and second to the task level processing exit. This sequence (the
reverse of the pre-processing exit sequence) is chosen to simulate the return
sequence that would have been seen if both SVC screen routine and updated SVC
routine were in place. The following diagram illustrates the exit routine call
sequence:
Chapter 10. Using the DESERV Exit
365
DESERV Exit
DESERV GET, PUT, RENAME, DELETE or UPDATE is issued
enter DESERV GET, PUT, RENAME, DELETE, or UPDATE
call task exit for pre-processing
if return_code = 0 then
call global exit for preprocessing
if return_code = 0 then
process GET, PUT, RENAME, DELETE, or UPDATE
GOTO post_process_global
else if return_code = 4 then
GOTO post_process_task
else if return_code = 4 then
return to DESERV caller
Post_process_global:
call global exit for post-processing
Post_process_task:
call task exit for post-processing
return to DESERV caller
Figure 44. Exit Routine Call Sequence
Establishing Multiple Task level or Multiple Global Exits
The system identifies a DESERV exit by a DST (DESERV Screen Table). The system
maintains at most one task level DST for each task, and at most one DST for the
system (which represents the global exit). However, multiple DESERV exits can be
established. To support multiple exits of a given type (task or global), when a
DESERV FUNC=EXIT is issued with EXIT_OPTION=REPLACE, DESERV returns
the address of the DST that was replaced (or zero if no DST was replaced). Then it
is the responsibility of the newly defined exit to pass control to the previously
defined exit.
Issuing DESERV FUNC=EXIT (invocation environment)
INTERRUPTS:
Enabled
STATE and KEY:
Supervisor state, or system key (0-7)
ASC Mode:
P=H=S
AMODE, RMODE:
No restrictions
LOCKS:
None held
REGISTERS:
v All register contents except registers 15 and 0 are restored on return.
v Register 15 contains the return code and register 0 contains the reason
code.
v No save area is required.
SERIALIZATION REQUIREMENTS:
None. DESERV maintains serialization. Therefore the caller does not need
to provide any ENQ-like serialization.
366
z/OS DFSMSdfp Advanced Services
DESERV Exit
Invocation Syntax
The following figure illustrates the syntax for the DESERV EXIT function:
►►
DESERV FUNC=EXIT
►
label
,EXIT_SCOPE=
TASK
GLOBAL
►
►
,EXIT_OPTION=
NOREPLACE
REPLACE
DELETE
QUERY
► ,EXIT_PREV_DSTPTR=
,EXIT_DST=
dst_address
(2-12)
dstPTR_address
(2-12)
►
►
►
,MF=
S
L
,RETCODE=retcode
(E,
(1-12)
label
,COMPLETE
,NOCHECK
)
►
►◄
,RSNCODE=rsncode
FUNC=EXIT
Requests the DESERV function which operates on a DESERV exit. This
keyword is always required except when MF=E is coded with "NOCHECK"
and no other keywords are coded or MF=L is coded with no other keywords.
For the MF=E case, the FUNC keyword and other keywords specified on the
MF=L DESERV macro invocation are assumed to have been coded completely.
EXIT_SCOPE=GLOBAL or TASK
Specifies whether the exit specified will be of a TASK level or of a GLOBAL
level.
EXIT_OPTION=REPLACE or NOREPLACE or DELETE or QUERY
If EXIT_OPTION=REPLACE or NOREPLACE is coded, this specifies whether
this invocation of the DESERV FUNC=EXIT should replace an existing
DESERV EXIT (TASK or GLOBAL as specified by the EXIT_SCOPE parameter).
EXIT_PREV_DST will return the existing exit or be set to zero if one does not
exist.
If EXIT_OPTION=DELETE is coded, this indicates that the current exit is to be
deleted (EXIT_OPTION=DELETE). In this case the EXIT_DST parameter
specifies the address of the DST which is to be deleted. This address will be
used as the compare value in a compare and swap operation, and only the
currently active exit can be deleted. The DST address specified with the
EXIT_PREV_DSTPTR parameter will be used as the swap value.
If EXIT_OPTION=QUERY is coded, this indicates that the current exit DST
address is to be returned via the EXIT_PREV_DSTPTR parameter.
EXIT_DST=deserv_exit_screen_table RX-Type Address or (2-12)
Specifies the address of the DESERV Screen Table (DST). The screen table is
mapped by DST DSECT of the IGWDES mapping macro. For an
Chapter 10. Using the DESERV Exit
367
DESERV Exit
EXIT_OPTION of either NOREPLACE or REPLACE, this parameter defines the
DST and defines the exit routine address which becomes the currently active
exit if the operation is successful. For an EXIT_OPTION of DELETE, this
parameter defines the DST whose address is used as a compare value in a
compare and swap operation when deleting the current DST (the address of
the input DST is used as the compare value). If the compare fails, DESERV
returns an error return and reason code. If EXIT_OPTION=QUERY is coded,
this parameter is not required.
EXIT_PREV_DSTPTR=addr_of_deserv_exit_screen_table RX-Type Address or
(2-12)
The EXIT_PREV_DSTPTR is an output parameter when an EXIT_OPTION of
NOREPLACE, REPLACE or QUERY is specified, and an input parameter if an
EXIT_OPTION of DELETE is specified.
For EXIT_OPTION=NOREPLACE or QUERY this parameter specifies a four
byte field into which DESERV will return the address of the current DST (or
zero if no DST exists).
For EXIT_OPTION=REPLACE, this parameter specifies a four byte field into
which DESERV will return the address of the DST which was successfully
replaced (or zero if no previous DST existed).
For EXIT_OPTION=DELETE, this parameter specifies a four byte field that
points to the DST that DESERV restore as the current DST. This address is the
swap value for the compare and swap operation.
MF=S or L or {(E,{(1-12) or label}{,COMPLETE or NOCHECK})} RX-Type Address
or (1-12) - for MF=E second argument Default=S - if the MF keyword is not
specified Default=COMPLETE - if MF=E is specified without the third
argument (COMPLETE or NOCHECK).
Specifies the format of the macro expansion.
The Standard form, S, checks all required keywords and keywords that are not
valid. This form generates a complete inline expansion of the parameter list
and code to call the Directory Entry Services routine. The standard form is for
programs that are not reenterable, or for programs that do not change values
in the parameter list.
L specifies the List form of the macro. This form generates a remote parameter
list. Only keywords of argument type KEY or SYM can be coded. Registers are
not valid because code generation does not occur, adcons are generated.
Invalid keyword checking is done.
Keywords with defaults that are set by MF=L invocation are not reset to their
default during MF=E invocation.
E specifies the Execute form of the macro. This form updates the remote
parameter list (MF=L) and transfers control to the DESERV routine.
The second parameter for MF=E format is the address of the parameter list
created by the MF=L DESERV invocation. This parameter must be specified as
either an RX type of address (possibly the label from MF=L macro invocation)
or a register enclosed in parentheses.
The third parameter, COMPLETE or NOCHECK, is optional. Default is
COMPLETE. This argument specifies whether required keyword checking will
be done. If MF=E is coded with the NOCHECK argument then no, some, or all
allowed keywords can be specified, assuming that any missing keywords were
coded on the MF=L macro invocation. If MF=E is coded with the COMPLETE
argument or allowed to default, the parameter list will be zeroed out (except
368
z/OS DFSMSdfp Advanced Services
DESERV Exit
for the parameter list header) This sets all defaults because the defaults for the
DESERV macro are 0. All required keywords must be specified.
RETCODE=retcode RX-Type Address or (2-12)
Specifies the address where the return code returned by DESERV will be
stored. Can not be specified on MF=L macro format. The default is not to store
the return code in virtual storage. The return code is always returned in
register 15 without regard to whether RETCODE is coded.
RSNCODE=rsncode RX-Type Address or (2-12)
Specifies the address where the reason code returned by DESERV will be
stored. Can not be specified on MF=L macro format. The default is not to store
the return code in virtual storage. The return code is always returned in
register 0 without regard to whether RETCODE is coded.
DESERV code is available and used by the system starting with DFSMSdfp Version
1.1. However, invoking the EXIT function requires that the appropriate PTF be
applied to the system to enable the support. Your program can test to determine if
the appropriate level of DFSMS™ or PTF is installed.
If the DESERV FUNC=EXIT interface is called on DFSMS without the support code
being available, DESERV returns an error return and reason code.
Installing or Replacing the DESERV Exit
Your program, while operating in task mode, can establish DESERV exits by
issuing the DESERV macro with FUNC=EXIT and appropriate parameters.
Table 66. Installing or Replacing the DESERV Exit
If EXIT_OPTION =
then:
and these parameters...
REPLACE
The new exit definition
EXIT_DST and
replaces the most recently
EXIT_PREV_DSTPTR must
defined exit. The DST
be specified.
(DESERV Screen Table)
address of the previously
defined exit's DST is returned
to the caller.
NOREPLACE (with no exit
currently existing)
The exit definition is
See REPLACE.
activated. A value of zero is
returned as the previous DST
address.
NOREPLACE (with an exit
currently existing)
The currently defined exit
remains the active exit. The
address of the currently
defined DST is returned as
the previous DST address.
See REPLACE.
Note: If EXIT_OPTION=REPLACE is specified the caller must expect that a previous DST
address is returned. It is the responsibility of the caller to replace the old DST address when
eventually disabling the new exit. Also the exit routine might need to be aware that there
was a previous exit defined, and might choose to invoke the previously defined exit.
EXIT_DST defines the DST address. The DESERV FUNC=EXIT caller owns and
manages storage for the DST. The DST can be encapsulated inside other
application managed control blocks. This can help the exit routine determine the
context of the application in which it was called. When the DST is used with a task
level exit, the DST_FLAGS_PROP bit can be set on to indicate that this DST should
Chapter 10. Using the DESERV Exit
369
DESERV Exit
be propagated to tasks that are attached by this task. The propagate function is not
supported for the global exit. The format of the DST is shown in Table 67.
Table 67. DESERV Screen Table Structure
Offset
Length or Bit
Pattern
Name
Description
0 (X'0')
20
DST
(structure)
0 (X'0')
16
DST_HEADER
(character)
0 (X'0')
8
DST_ID
Eyecatcher 'IGWDST' (character)
08 (X'08')
4
DST_LEN
Length of DST
X'14'
DST_LEN_IV
Constant to be used with
DST_LEN
1
DST_LEV
Control block level (unsigned)
X'01'
DST_LEV_IV
Constant to be used with
DST_LEV
1
DST_FLAGS
DST flags (unsigned)
xxxx xxx.
-
Reserved
.... ...1
DST_FLAGS_PROP
Propagate this DST to lower level
tasks
14 (X'0E')
2
DST_RES
Reserved
16 (X'10')
4
DST_EXIT
Address of exit routine screen
table (address)
12 (X'0C')
13 (X'0D')
EXIT_PREV_DSTPTR returns the address of the DST that was defined prior to this
DESERV FUNC=EXIT call.
Deleting the DESERV Exit
An application that has established a DESERV exit can delete the currently active
exit by issuing the DESERV macro with FUNC=EXIT. You can specify the
following:
Table 68. Deleting the DESERV Exit
For this parameter
specify this:
EXIT_SCOPE
(application dependent)
EXIT_OPTION
DELETE
EXIT_DST
Currently active DST to be deleted
EXIT_PREV_DSTPTR
The DST to become active
Note: The address of the DST must match that of the currently defined DST. If the
addresses do not match, DESERV returns error return and reason codes to indicate the
DELETE operation has failed and the active DST remains unaffected.
For a task related exit, the DESERV exit is implicitly deleted when the task ends. A
global exit can only be explicitly deleted by issuing a DESERV FUNC=EXIT call.
The system does not serialize the deletion of a DESERV exit with the use of that
exit by any other task or application. It is up to the application that establishes and
deletes the exit to ensure that the storage occupied by the DST and exit code is not
freed until all other users of the exit are no longer using the exit. For a task related
370
z/OS DFSMSdfp Advanced Services
DESERV Exit
exit, you can accomplish this by putting the DST and exit into task-related storage
and not explicitly freeing the storage. For a global exit, you can accomplish this by
putting the DST and exit into system related common storage and never freeing
the storage. For practical purposes, waiting for several minutes after the exit is
deleted before freeing the storage should be safe as no new invocations of DESERV
will use the exit once it is deleted.
Determining If a DESERV Exit Is Active
To determine if a DESERV exit is active issue the DESERV macro with FUNC=EXIT
and choose the following options:
Table 69. Determining If a DESERV Exit Is Active
For this parameter
choose this:
EXIT_OPTION
QUERY
EXIT_SCOPE
(application dependant)
EXIT_PREV_DSTPTR
The address of a 4 byte area into which the
currently active DST address is returned (or
zero if there is no currently defined DST
address.)
Writing the DESERV Exit
A DESERV exit gets control once prior to any DESERV GET, PUT, RENAME,
UPDATE or DELETE function processing, and once immediately prior to DESERV's
return to the caller. A DESERV exit receives control in key 0 and supervisor state.
Register 13 points to an 18-word key 0 register save area.
The DESX DSECT maps the input to the exit routines and is defined in the
IGWDES macro. Register 1 points to the DESX on entry to the exit routine. The
DESX structure is shown in Table 70.
Table 70. DESX Structure Mapping DESERV Exit Parameter List
Offset
Length or Bit
Pattern
Name
Description
0 (X'0')
36
DESX
(structure)
0 (X'0')
16
DESX_HEADER
(character)
0 (X'0')
8
DESX_ID
Eyecatcher - IGWDESX (character)
08 (X'08')
4
DESX_LEN
Length of DESX (signed)
X'24'
DESX_LEN_IV
Constant to be used with DESX_LEN
1
DESX_LEV
Control block level (character)
X'01'
DESX_LEV_IV
Constant to be used with DESX_LEV
13 (X'0D')
3
-
Reserved
16 (X'10')
4
DESX_DESP_PTR
Address of caller's DESP (address)
20 (X'14')
4
DESX_DST
Address of DESERV screen table (address)
24 (X'18')
1
DESX_CALLER_KEY
Key of DESERV caller in bits 0-3 (unsigned)
12 (X'0C')
Chapter 10. Using the DESERV Exit
371
DESERV Exit
Table 70. DESX Structure Mapping DESERV Exit Parameter List (continued)
Offset
Length or Bit
Pattern
Name
Description
25 (X'19')
1
DESX_FLAGS
(bitstring)
1... ....
DESX_BLDL_BIT
DESERV issues BLDL to process this GET request
.1.. ....
DESX_PREV_BIT
EXIT called before DESERV PUT or GET function
..1. ....
DESX_POST_BIT
EXIT called after DESERV PUT or GET function
26 (X'1A')
2
-
Reserved
28 (X'1C')
4
DESX_RETURN_CODE
Return code to be returned to DESERV caller (unsigned)
32 (X'20')
4
DESX_REASON_CODE
Reason code to be returned to DESERV caller (unsigned)
Note that the DESERV return and reason codes, with the exception of the PUT
codes, can be found in z/OS DFSMS Using Data Sets. See Figure 45 on page 387 for
the PUT return and reason codes.
Parameters Related to the GET Function
If the DESERV exit gets control for a DESERV GET function invocation,
DESX_DESP_PTR points to the DESERV parameter list. If the DESP field
DESP_FUNC=X'01' (DESP_FUNC_GET), this indicates a GET function parameter
list. See Table 71 on page 373 for the DESP structure for fields pertaining to a
DESERV GET invocation.
DESERV GET will return information on selected members. This information is
returned in a DESB structure. The DESB is mapped by the DESB DSECT in the
IGWDES macro. If the storage for the DESB is provided by the DESERV GET, the
DESP_AREA_PTR field contains the address of this storage. Alternatively the caller
may request that DESERV GET not obtain the storage for the DESB. In this case
the DESP_AREAPTR_PTR field contains the address of a 4 byte area into which
DESERV GET will return the address of a DESB. The DESB will be obtained in the
subpool identified by DESP_SUBPOOL (or default to subpool zero). The flag
DESP_SUBPOOL_FLG indicates whether the subpool was specified explicitly by
the DESERV GET caller.
A DESERV GET invocation identifies the members to be searched for by a name
list, a PDS format directory entry, or an SMDE. The DESP field DESP_GETTYPE
defines the get type. If the get type is a PDSDE (the member to be searched for is
defined by a PDS format directory entry), the DESP_PDSDE_PTR points to a
directory entry as returned by the BLDL macro. The PDS2 DSECT in the IHAPDS
macro maps this structure. The function of DESERV GET for a PDSDE get type
depends on the type of library identified by the concatenation number in the PDS
style directory entry. If the concatenation number identifies a PDS, the GET
function is simply to convert the PDS style directory entry into a SMDE. If the
concatenation number identifies a PDSE, the GET function is to connect to the
member identified by the PDS2TTRP field, and to return the appropriate SMDE. In
either case the SMDE is retuned (if in the PDSE case the member actually exists) in
the data portion of the output buffer (DESB, mapped below).
If the get type is name list, the DESL area points to the names to be searched for.
The DESP_NAME_LIST_PTR points to the DESL and the DESL DSECT in the
IGWDES macro maps it. A DESL is an array consisting of the number of entries
the DESP field DESP_NAME_LIST2 defines. The DESL parameter list is shown in
Table 72 on page 375.
372
z/OS DFSMSdfp Advanced Services
DESERV Exit
If the get type is SMDE, the DESP_SMDE_PTR points to a system-managed
directory entry (SMDE) as returned by DESERV GET. DESERV GET will cause a
connection to the member identified by the SMDE. DESERV GET will return a
copy of the SMDE in the output DESB. The SMDE returned will of course have
updated connect token and connect id fields.
There are two input flags which control DESERV GET's view of the PDS or PDSE
to be searched. If the DESP_C370LIB flag is on, a PDS may be viewed as a
C370LIB. This means that if the PDS has a special member named @@DC370$, this
member is treated as the "real" directory for the PDS. If the DESP_SYSTEM_DCB is
on, this indicates that the caller (who must be authorized) has indicated that this
DCB is "owned by the system" and is not on any DEB chain, therefore DEBCHK
should not be done.
Hint: The name of the special member @@DC370$ might not display correctly on
your screen or printer. The first two characters are X'7C' and the last character is
X'5B'.
Table 71. Structure of DESP for DESERV GET Invocations
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
104
DESP
DE Services parameter list (structure)
00 (X'00')
16
DESP_HEADER
(character) 'IGWDESP'
00 (X'00')
8
DESP_ID
Eyecatcher IGWDESP (character)
08 (X'08')
24
DESP_LEN
Length of DESP (signed)
X'04'
DESP_LEN_IV
Constant to be used with DESP_LEN
1
DESP_LEV
Control block level (character)
X'01'
DESP_LEV_IV
Constant to be used with DESP_LEV
13 (X'0D')
3
-
Reserved
16 (X'10')
1
DESP_FUNC
Function type (unsigned)
X'07'
DESP_FUNC_DELETE
Function is DELETE
X'08'
DESP_FUNC_RENAME
Function is RENAME
X'09'
DESP_FUNC_UPDATE
Function is UPDATE
X'04'
DESP_FUNC_PUT
Function is PUT
X'01'
DESP_FUNC_GET
Function is GET
X'00'
DESP_FUNC_OMITTED
Function is omitted
17 (X'11')
3
-
Reserved
20 (X'14')
4
-
Reserved
24 (X'18')
12
DESP_DATA
Function data (character)
24 (X'18')
2
DESP_FLAGS
Flags (bitstring)
1... ....
DESP_BYPASS_LLA
0=USE LLA, 1=BYPASS LLA
.x.. ....
-
Reserved
..1. ....
DESP_SUBPOOL_FLG
0=SUBPOOL not specified, 1=SUBPOOL specified
...1 ....
DESP_C370LIB
1=treat PDSs as C370LIB if @@DC370$ member
exists
.... xx..
-
Reserved
.... ..1.
DESP_SYSTEM_DCB
1=treat DCB as a system DCB
12 (X'0C')
Chapter 10. Using the DESERV Exit
373
DESERV Exit
Table 71. Structure of DESP for DESERV GET Invocations (continued)
Offset
Length or Bit
Pattern
Name
Description
26 (X'1A')
1
-
Reserved
27 (X'1B')
1
-
Reserved
28 (X'1C')
1
DESP_LIBTYPE
Indicates whether a DCB or DEB is input =X'02',
DEB input=X'01') (unsigned)
X'02'
DESP_LIBTYPE_DCB
Constant to be used with DESP_LIBTYPE
X'01'
DESP_LIBTYPE_DEB
Constant to be used with DESP_LIBTYPE
X'00'
DESP_LIBTYPE_OMITTED
Constant to be used with DESP_LIBTYPE
1
DESP_GETTYPE
Indicates whether Name List or PDSDE is input.
(NAME_LIST input=(X'01', PDSDE input=X'02')
(unsigned)
X'03'
DESP_GETTYPE_SMDE
Constant to be used with DESP_GETTYPE
X'02'
DESP_GETTYPE_PDSDE
Constant to be used with DESP_GETTYPE
X'01'
DESP_GETTYPE_NAME_LIST
Constant to be used with DESP_GETTYPE
X'00'
DESP_GETTYPE_OMITTED
Constant to be used with DESP_GETTYPE
30 (X'1E')
1
-
Reserved
31 (X'1F')
1
-
Reserved
32 (X'20')
1
-
Reserved
33 (X'21')
1
DESP_SUBPOOL
Subpool number for getting DESB.
34 (X'22')
1
DESP_CONN_INTENT
Connect intent (unsigned)
X'03'
DESP_CONN_INTENT_INPUT
INPUT
X'02'
DESP_CONN_INTENT_EXEC
EXEC
X'01'
DESP_CONN_INTENT_HOLD
HOLD
X'00'
DESP_CONN_INTENT_NONE
None
35 (X'23')
1
-
Reserved
36 (X'24')
4
DESP_DCB_PTR
DCB address, valid if DESP_LIBTYPE=X'02'
(address)
40 (X'28')
4
DESP_DEB_PTR
DEB address, valid if DESP_LIBTYPE=X'01'
(address)
44 (X'2C')
4
DESP_CONN_ID_PTR
Connect identifier address
48 (X'30')
4
DESP_AREAPTR_PTR
Address of output field for buffer address
52 (X'34')
4
DESP_AREA_PTR
Buffer address
56 (X'38')
4
DESP_AREA2
Buffer length (unsigned)
60 (X'3C')
4
-
Reserved
64 (X'40')
4
-
Reserved
68 (X'44')
4
DESP_ENTRY_GAP
Entry gap size (signed)
72 (X'48')
4
-
Reserved
76 (X'4C')
4
-
Reserved
80 (X'50')
4
DESP_NAME_LIST_PTR
Name list address, valid if DESP_GETTYPE=X'01'
(address)
84 (X'54')
4
DESP_NAME_LIST2
Input list number of entries, valid if
DESP_GETTYPE=X'01' (unsigned)
29 (X'1D')
374
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 71. Structure of DESP for DESERV GET Invocations (continued)
Offset
Length or Bit
Pattern
Name
Description
88 (X'58')
4
-
Reserved
92 (X'5C')
4
DESP_PDSDE_PTR
BLDL directory entry address, valid if
DESP_GETTYPE=X'02' (address)
92 (X'5C')
4
DESP_SMDE_PTR
SMDE directory entry address, valid if
DESP_GETTYPE=X'03' (address)
96 (X'60')
4
-
Reserved
100 (X'64')
4
-
Reserved
Table 72. DESL Structure
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
16
DESL
Name list (structure)
00 (X'00')
16
DESL_ENTRY
Name list entry (character)
00 (X'00')
1
DESL_FLAGS
Flags (unsigned)
1... ....
DESL_MODULE_BUFFERED_
LLA
Module is staged by LLA
1
DESL_CODE
Result code (New name exists=X'03', Error=X'02',
Not found or not processed=X'01', Found=X'00')
(unsigned)
X'03'
DESL_CODE_NEWNAME_
EXISTS
For func=rename, indicates a new name already
existed in the PDSE.
X'02'
DESL_CODE_ERROR
An unexpected error has occurred. The
DESL_ERRCODE field is set to a DESRF value
X'01'
DESL_CODE_NOTFOUND
Entry not found or entry not processed. If
func=rename, old name was not found.
X'00'
DESL_CODE_SUCC
Entry successfully processed
2 (X'2')
2
DESL_ERRCODE
Error reason code (low order halfword of DESERV
reason code if error) (unsigned)
4 (X'4')
4
-
Reserved
08 (X'08')
4
DESL_SMDE_PTR
Pointer to SMDE within DESB. Output for GET
function, input for UPDATE function (address)
08 (X'08')
4
DESL_NEW_NAME_PTR
Pointer to new name (DESN) descriptor for
RENAME function (address)
12 (X'0C')
4
DESL_NAME_PTR
Pointer to name (DESN) descriptor for GET and
DELETE functions (address)
12 (X'0C')
4
DESL_OLD_NAME_PTR
Pointer to old name (DESN) descriptor for
RENAME function (address)
1 (X'1')
The DESERV GET caller will have built the DESL to point to variable length
names. The DESN DSECT maps these names in the IGWDES macro. See Table 73
on page 376 for the DESN parameter list.
Chapter 10. Using the DESERV Exit
375
DESERV Exit
Table 73. DESN Parameter List
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
variable
DESN
Name record (structure)
00 (X'00')
2
DESN_LEN
Length of name that follows (unsigned)
2 (X'02')
variable
DESN_VAL
Name data (character)
The DESP_CONN_INTENT field of the DESP indicates the connection intent
requested by the caller. The connection intent only has an effect if the name is
found in a PDSE. If the connection intent is DESP_CONN_INTENT_HOLD (X'01'),
the effect is similar to a BLDL invocation (because the member is connected for
HOLD which is not sufficient to read the member). If the connection intent is
DESP_CONN_EXEC (X'02') or DESP_CONN_INTENT_INPUT (X'03'), the effect is
similar to a FIND invocation (because the member is connected and sufficient
control blocks are built so that the member can be read). The GET function does
not currently support a connect intent of NONE.
The output from DESERV GET consists of flags and error codes in the DESL (if the
get type is name list) as well as an SMDE (system managed directory entry)
pointer. For a gettype of name list, the SMDE is pointed to by the
DESL_SMDE_PTR field. For a gettype of PDSDE, the SMDE is in the DESB at the
label DESB_DATA. The SMDE is mapped by the SMDE DSECT in the IGWSMDE
macro and the PMAR DSECT in the IEWPMAR macro. The SMDE resides in the
output buffer as provided by the caller of DESERV GET. The output buffer is
mapped by the DESP DSECT of the IGWDES macro. The DESB structure is shown
in Table 74.
The basic SMDE format is shown in Table 75 on page 377.
Table 74. DESB Parameter List
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
variable
DESB
DEServ buffer header (structure)
00 (X'00')
40
DESB_FIXED
(character)
00 (X'00')
16
DESB_HEADER
(character)
00 (X'00')
8
DESB_ID
Eyecatcher - IGWDESB (character)
08 (X'08')
4
DESB_LEN
Length of buffer (signed)
12 (X'0C')
1
DESB_LEV
Control block level (character)
X'01'
DESB_LEV_IV
Constant to be used with DESB_LEV
13 (X'0D')
3
-
Reserved
16 (X'10')
4
DESB_NEXT
Next buffer pointer (address)
20 (X'14')
4
-
Reserved
24 (X'18')
4
DESB_COUNT
Count of entries in this buffer (unsigned)
28 (X'1C')
4
DESB_AVAIL
Start of free space in buffer (address)
32 (X'20')
1
-
Reserved
33 (X'21')
1
DESB_SUBPOOL
Subpool number (unsigned)
34 (X'22')
2
DESB_GAP_LEN
Length of user-requested gap (unsigned)
36 (X'24')
4
-
Reserved
376
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 74. DESB Parameter List (continued)
Offset
Length or Bit
Pattern
Name
Description
40 (X'28')
variable
Start of data area (character)
DESB_DATA
Table 75. SMDE Format
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
variable
SMDE
Member directory entry (structure)
00 (X'00')
44
SMDE_BASIC
Start of basic section (character)
00 (X'00')
16
SMDE_HDR
Header (character)
00 (X'00')
8
SMDE_ID
Eyecatcher (character)
08 (X'08')
4
SMDE_LEN
Length of control block. This is the sum of the
sizes of the SMDE sections and the size of the
user data. (unsigned)
12 (X'0C')
1
SMDE_LVL
SMDE version number (unsigned)
X'01'
SMDE_LVL_VAL
Constant to be used with SMDE_LVL
13 (X'0D')
3
-
Reserved
16 (X'10')
1
SMDE_LIBTYPE
Source library type. Possible values are declared
below with names like SMDE_LIBTYPE_XXX.
(unsigned)
X'03'
SMDE_C370LIB
Constant to be used with SMDE_LIBTYPE
X'02'
SMDE_LIBTYPE_HFS
Constant to be used with SMDE_LIBTYPE
X'01'
SMDE_LIBTYPE_PDSE
Constant to be used with SMDE_LIBTYPE
X'00'
SMDE_LIBTYPE_PDS
Constant to be used with SMDE_LIBTYPE
1
SMDE_FLAG
Flag byte (bitstring)
1... ....
SMDE_FLAG_ALIAS
Entry is an alias
.1.. ....
SMDE_FLAG LMOD
Member is a program
..xx xxxx
*
Reserved
18 (X'12')
2
-
Reserved, must be zero
20 (X'14')
5
-
Extended MLTK (character)
20 (X'14')
1
-
Reserved, must be zero
21 (X'15')
4
SMDE_MLTK
MLT and concatenation number (character)
21 (X'15')
3
SMDE_MLT
MLT of member - zero if HFS (character)
24 (X'18')
1
SMDE_CNCT
Concatenation number (unsigned)
25 (X'19')
1
SMDE_LIBF
Library flag - Z-byte (unsigned)
X'02'
SMDE_LIBF_TASKLIB
Constant to be used with SMDE_LIBF
X'01'
SMDE_LIBF_LINKLIB
Constant to be used with SMDE_LIBF
X'00'
SMDE_LIBF_PRIVATE
Constant to be used with SMDE_LIBF
26 (X'1A')
2
SMDE_NAME_OFF
Name offset (signed)
28 (X'1C')
2
SMDE_USRD_LEN
User data length (signed)
28 (X'1C')
2
SMDE_PMAR_LEN
Sum of lengths of program management attribute
record sections (PMAR, PMARR, PMARL)
(signed)
17 (X'11')
Chapter 10. Using the DESERV Exit
377
DESERV Exit
Table 75. SMDE Format (continued)
Offset
Length or Bit
Pattern
Name
Description
30 (X'1E')
2
SMDE_USERD_OFF
User data offset (signed)
30 (X'1E')
2
SMDE_PMAR_OFF
Program management attribute record offset
(signed)
32 (X'20')
2
SMDE_TOKEN_LEN
Token length (signed)
34 (X'22')
2
SMDE_TOKEN_OFF
Token data offset (signed)
36 (X'24')
2
SMDE_PNAME_OFF
Primary name offset, zero for non-alias SMDES or
if library type is a PDS and this is not a program.
(signed)
38 (X'26')
2
SMDE_NLST_CNT
Number of note list entries that exist at beginning
of user data field. Always zero for non-PDS
members. (signed)
40 (X'28')
4
-
Reserved
44 (X'2C')
variable
SMDE_SECTIONS
Start of entry sections (character)
Table 76 through Table 79 on page 379 shows the optional SMDE_SECTIONS, or
extensions to the SMDE.
Table 76. Directory Entry Name Section
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
variable
SMDE_NAME
Name descriptor (structure)
00 (X'00')
2
SMDE_NAME_LEN
Length of entry name (signed)
2 (X'02')
variable
SMDE_NAME_VAL
Entry name (character)
Table 77. Directory Entry Notelist Section (PDS Only)
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
variable
SMDE_NLST
Note list extension (structure)
00 (X'00')
4
SMDE_NLST_ENTRY
Note list entries (character)
00 (X'00')
3
SMDE_NLST_RLT
Note list record location token (character)
3 (X'03')
1
SMDE_NLST_NUM
Number of RLT described by this note list block.
If 0 this is not a notelist but a data block.
(unsigned)
Table 78. Directory Entry Token Section
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
32
SMDE_TOKEN
(structure)
00 (X'00')
4
SMDE_TOKEN_CONNID
CONNECT_IDENTIFIER (unsigned)
4 (X'04')
4
SMDE_TOKEN_ITEMNO
Item number (unsigned)
08 (X'08')
24
SMDE_TOKEN_FT
File token (character)
378
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 79. Directory Entry Primary Name Section
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
variable
SMDE_PNAME
Primary name descriptor (structure)
00 (X'00')
2
SMDE_PNAME_LEN
Length of primary name (signed)
2 (X'02')
variable
SMDE_PNAME_VAL
Primary name (character)
If the SMDE represents a directory entry for a program (either a load module or a
program object) the program's attributes are defined by the PMAR structure. The
PMAR is a subfield of the SMDE and its offset is defined by the field
SMDE_PMAR_OFF. Table 80 shows the basic PMAR definition. Table 81 on page
381 and Table 82 on page 383 show the PMAR extensions for program objects
(PMARL) and load modules (PMARR), respectively.
If the SMDE represents a data member of a PDS or a PDSE, the SMDE_USRD_OFF
field indicates the offset into the SMDE for the user data of the directory entry.
Table 80. Directory Entry Name Section. Data is always present at offset SMDE_PMAR_OFF in an SMDE.
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
30
PMAR
Basic section of program user data (structure)
00 (X'00')
30
PMAR_ENTRY
Alternative name for the PMAR section (character)
00 (X'00')
2
PMAR_SLEN
Section length (unsigned)
2 (X'02')
1
PMAR_LVL
PMAR format level (unsigned)
X'02'
PMAR_LVL_VAL
Constant to be used with PMAR
X'01'
PMAR_PM1_VAL
Constant to be used with PMAR
X'02'
PMAR_PM2_VAL
Constant to be used with PMAR
1
PMAR_PLVL
Bind processor creating object 1 - E-level linkage
editor 2 - F-level linkage editor 3 - (VS1/VS2)
linkage editor 4 - XA linkage editor 5 - binder
version 1. (unsigned)
X'01'
PMAR_PLVL_E_VAL
Constant to be used with PMAR_PLVL
X'02'
PMAR_PLVL_F_VAL
Constant to be used with PMAR_PLVL
X'03'
PMAR_PLVL_AOS_VAL
Constant to be used with PMAR_PLVL
X'04'
PMAR_PLVL_XA_VAL
Constant to be used with PMAR_PLVL
X'05'
PMAR_PLVL_B1_VAL
Constant to be used with PMAR_PLVL
X'06'
PMAR_PLVL_B2_VAL
Constant to be used with PMAR_PLVL
4
PMAR_ATR
Attribute bytes (character)
3 (X'03')
4 (X'04')
Chapter 10. Using the DESERV Exit
379
DESERV Exit
Table 80. Directory Entry Name Section (continued). Data is always present at offset SMDE_PMAR_OFF in an
SMDE.
Offset
Length or Bit
Pattern
Name
4 (X'04')
1
PMAR_ATR1
First attribute byte. These flags must be at the
same offsets as the corresponding flags in
PDS2ATR1 declared by macro IHAPDS. (bitstring)
1... ....
PMAR_RENT
Reenterable
.1.. ....
PMAR_REUS
Reusable
..1. ....
PMAR_OVLY
Overlay structure
...1 ....
PMAR_TEST
Module to be tested - TSO/E TEST
.... 1...
PMAR LOAD
Only loadable
.... .1..
PMAR_SCTR
Scatter format
.... ..1.
PMAR_EXEC
Executable
.... ...1
PMAR_1BLK
Load module contains only one block of text data
and has no RLD data.
1
PMAR_ATR2
Second attribute byte. These flags must be at the
same offsets as the corresponding flags in
PDS2ATR2 declared by macro IHAPDS. (bitstring)
1... ....
PMAR_FLVL
If on, the program cannot be processed by the E
level linkage editor. If off, the program can be
processed by any level of the linkage editor or the
binder.
.1.. ....
PMAR_ORGO
Linkage editor assigned origin of first block of
text is zero.
..x. ....
-
Reserved
...1 ....
PMAR_NRLD
Program contains no RLD items
.... 1...
PMAR_NREP
Module cannot be reprocessed by the linkage
editor
.... .1..
PMAR_TSTN
Module contains TSO/E TEST symbol records
.... ..x.
-
Reserved
.... ...1
PMAR REFR
Refreshable program
6 (X'06')
1
PMAR_ATR3
Third attribute byte. (bitstring)
6 (X'06')
1
PMAR_FTB1
Alternative name for flags byte. These flags must
be at the same offsets as the corresponding flags
in PDS2FTB1 declared by macro IHAPDS.
(bitstring)
x... ....
-
Reserved
.1.. ....
PMAR_BIG
This program requires 16MB or more of virtual
storage.
..1. ....
PMAR_PAGA
Page alignment is required
...1 ....
PMAR_XSSI
SSI information present
.... 1...
PMAR_XAPF
APF information present
.... .1..
PMAR_LFMT
PMARL follows PMAR.
.... ..xx
-
Reserved
1
PMAR_ATR4
Fourth attribute byte (bitstring)
5 (X'05')
7 (X'07')
380
z/OS DFSMSdfp Advanced Services
Description
DESERV Exit
Table 80. Directory Entry Name Section (continued). Data is always present at offset SMDE_PMAR_OFF in an
SMDE.
Offset
Length or Bit
Pattern
Name
7 (X'07')
1
PMAR_FTB2
Alternative name for flags byte. These flags must
be at the same offsets as the corresponding flags
in PDS2FTB2 declared by macro IHAPDS.
(bitstring)
1... ....
PMAR_ALTP
Alternate primary flag. If on for a primary name,
indicates primary name was generated by the
binder. If on for an alias, indicates the long alias
name was specified as the primary name on the
bind.
.xx. ....
-
Reserved
...1 ....
PMAR_RMOD
RMODE is ANY.
.... xx..
PMAR_AAMD
Alias entry point addressing mode. If B'00',
AMODE is 24. If B'10', AMODE is 31. If B'11',
AMODE is ANY.
.... ..xx
PMAR_MAMD
Main entry point addressing mode. If B'00'
AMODE is 24. If B'10', AMODE is 31. If B'11',
AMODE is ANY.
08 (X'08')
1
-
Reserved
9 (X'09')
1
PMAR_AC
APF authorization code (unsigned)
10 (X'0A')
4
PMAR_STOR
Virtual storage required (unsigned)
14 (X'0E')
4
PMAR_EPM
Main entry point offset (unsigned)
18 (X'12')
4
PMAR_EPA
This entry point offset (unsigned)
22 (X'16')
4
PMAR_SSI
SSI information (bitstring)
22 (X'16')
1
PMAR_CHLV
Change level of member (unsigned)
23 (X'17')
1
PMAR_SSFB
SSI flag byte (bitstring)
24 (X'18')
2
PMAR_MSER
Member serial number (Reserved)
26 (X'1A')
4
-
Reserved
30 (X'1E')
variable
PMAR_END
End of basic section (character)
Description
Table 81. LSLoader Attributes Unique to Program Objects. If PMAR_LFMT=ON this section follows the PMAR basic
section.
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
50
PMARL
LSLoader section for program objects (structure)
00 (X'00')
2
PMARL_SLEN
Section length (unsigned)
2 (X'02')
48
PMARL_DATA
Section data (character)
2 (X'02')
4
PMARL_ATR
Attribute bytes (character)
2 (X'02')
1
PMARL_ATR1
Fifth attribute byte (bitstring)
1... ....
PMARL_NMIG
This program object cannot be converted directly
to PDS load module format.
.1.. ....
PMARL_PRIM
FETCHOPT PRIME option
..1. ....
PMARL_PACK
FETCHOPT PACK option
...x xxxx
-
Reserved
Chapter 10. Using the DESERV Exit
381
DESERV Exit
Table 81. LSLoader Attributes Unique to Program Objects (continued). If PMAR_LFMT=ON this section follows the
PMAR basic section.
Offset
Length or Bit
Pattern
Name
Description
3 (X'03')
1
PMARL_ATR2
Sixth attribute byte (bitstring)
1... ....
PMARL_CMPR
Compressed format module
.1.. ....
PMARL_1RMOD
1st segment is RMODE Any, set for PM2-level PO
only
..1. ....
PMARL_2RMOD
2nd segment is RMODE Any, set for PM2-level
PO if there are at least two segments.
...1 ....
PMARL_SEGM
Loader data includes a Segment Table with >1
loadable entry or a Gas Table, set for PM2-level
PO only.
.... 1...
PMARL_1ALIN
1st segment is page-aligned, set for PM2-level PO
only
.... .1..
PMARL_2ALIN
2nd segment is page-aligned, set for PM2-level PO
if there are at least 2 segments.
.... ..1.
PMARL_FILL
FILL option specified set for PM2-level PO only
.... ...x
-
Reserved
4 (X'04')
1
PMARL_FILLVAL
FILL character value set for PM2-level PO only
5 (X'05')
1
-
Reserved
THE FOLLOWING NOTED FIELDS ARE NOT INTENDED FOR USE. INCLUDED HERE FOR INFORMATION
PURPOSES ONLY.
6 (X'06')
4
PMARL_MPGS
Total length of program on DASD in pages
(unsigned)
10 (X'0A')
40
PMARL_MDAT
DASD program descriptors (character)
10 (X'0A')
4
PMARL_TXTL
Length of text (unsigned)
14 (X'0E')
4
PMARL_TXTO
Offset to text (address)
18 (X'12')
4
PMARL_BDRL
Length of binder index (unsigned)
22 (X'16')
4
PMARL_BDRO
Offset to binder index (address)
26 (X'1A')
4
PMARL_RDTL
Length of PRDT (unsigned)
30 (X'1E')
4
PMARL_RDTO
Offset to PRDT (address)
34 (X'22')
4
PMARL_RATL
Length of PRAT (unsigned)
38 (X'26')
4
PMARL_RATO
Offset to PRAT (address)
42 (X'2A')
4
PMARL_NVSPGS
Number of virtual storage pages to contain
program object, for PM2-level PO
42 (X'2A')
4
PMARL_LMDL
Length of LSLoader data (unsigned) for PM1-level
PO
46 (X'2E')
4
PMARL_LMDO
Offset to LSLoader data (address)
50 (X'32')
2
PMARL_NSEG
Number of loadable segments
52 (X'34')
2
PMARL_NGAS
Count of entries in Gas Table
54 (X'36')
4
PMARL_1STOR
Virtual storage required for first loadable segment,
valid when PMARL_NSEG > 1.
58 (X'3A')
4
PMARL_2STOR
Virtual storage required for second loadable
segment, valid when PMARL_NSEG > 1.
382
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 81. LSLoader Attributes Unique to Program Objects (continued). If PMAR_LFMT=ON this section follows the
PMAR basic section.
Offset
Length or Bit
Pattern
Name
62 (X'3E')
4
PMARL_2TXTO
Description
Offset to second txt segment including gas, valid
when PMARL_NSEG > 1.
END INFORMATION ONLY FIELDS.
66 (X'42')
16
PMARL_TRACE
AUDIT trace data
66 (X'42')
4
PMARL_DATE
Date saved
70 (X'46')
4
PMARL_TIME
Time saved
74 (X'4A')
8
PMARL_USER
User or job identification
82 (X'52')
variable
PMARL_END
End of LSLoader section (character)
Table 82. Attributes Unique to Load Modules (PDS only). If PMAR_LFMT=OFF then this section follows the PMAR
basic section.
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
23
PMARR
Load module (PDS) attributes section (structure)
00 (X'00')
2
PMARR_SLEN
Section length (unsigned)
2 (X'02')
21
PMARR_DATA
Section data (character)
2 (X'02')
8
PMARR_TTRS
TTR fields (character)
2 (X'02')
3
PMARR_TTRT
TTR of first block of text (character)
5 (X'05')
1
PMARR_ZERO
Zero (character)
6 (X'06')
3
PMARR_TTRN
TTR of note list or scatter translation table. Used
for modules in scatter load format or overlay
structure only. (character)
9 (X'09')
1
PMARR_NL
Number of entries in note list for scatter format
modules and modules in overlay structure,
otherwise zero. (address)
10 (X'0A')
2
PMARR_FTBL
Length of first block of text (signed)
12 (X'0C')
3
PMARR_ORG
Load module origin if 0 (unsigned)
12 (X'0C')
2
-
Reserved
14 (X'0E')
1
PMARR_RLDS
Number of RLD/CTL records that follow the first
text record
15 (X'F')
8
PMARR_SCAT
Scatter load information (character)
15 (X'F')
2
PMARR_SLSZ
Scatter list length (unsigned)
17 (X'11')
2
PMARR_TTSZ
Translation table length (unsigned)
19 (X'13')
2
PMARR_ESDT
ESDID of first text block (character)
21 (X'15')
2
PMARR_ESDC
ESDID of EP control section (character)
23 (X'17')
variable
PMARR_END
End of load module attributes (character)
Table 83. Alias in Unformatted Form. Used only as input to the PUT function.
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
7
PMAR alias entry section (structure)
PMARA
Chapter 10. Using the DESERV Exit
383
DESERV Exit
Table 83. Alias in Unformatted Form (continued). Used only as input to the PUT function.
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
2
PMARA_LEN
Section length (unsigned)
2 (X'02')
5
PMARA_DATA
Section data (character)
2 (X'02')
4
PMARA_EPA
Entry point offset (unsigned)
6 (X'06')
1
PMARA_ATR
Attribute bytes (character)
6 (X'06')
1
PMARA_ATR1
First attribute byte (bitstring)
6 (X'06')
1
PMARA_FTB2
Alternative name for flags byte. These flags must
be at the same offsets as the corresponding flags
in PDS2FTB2 declared by macro IHAPDS.
(bitstring)
xxxx ....
-
Reserved
.... 11..
PMARA_AMD
Alias entry addressing mode. If B'00', AMODE is
24. If B'10', AMODE is 31. If B'11', AMODE is
ANY.
.... ..xx
-
Reserved
variable
PMARA_END
End of alias entry section (character)
7 (X'07')
Parameters Related to the PUT Function
If the DESERV exit gets control for a DESERV put function invocation,
DESX_DESP_PTR points to the DESERV parameter list. If the DESP field
DESP_FUNC=X'04' (DESP_FUNC_PUT), this indicates a PUT function parameter
list. Table 84 shows the fields of the DESP that pertain to the DESERV PUT
invocation.
Table 84. DESERV PUT DESP Fields
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
104
DESP
DE Services parameter list (structure)
00 (X'00')
16
DESP_HEADER
Standard header (character)
00 (X'00')
8
DESP_ID
Eyecatcher 'IGWDESP' (character)
08 (X'08')
4
DESP_LEN
Length of DESP (signed)
4
DESP_LEN_IV
Constant to be used for DESP_LEN
1
DESP_LEV
Control block level (character)
4
DESP_LEV_IV
Constant to be used for DESP_LEV
13 (X'0D')
3
-
Reserved
16 (X'10')
1
DESP_FUNC
Function type (GET=X'01', PUT=X'04',
DELETE=X'07', RENAME=X'08',
UPDATE=X'09') (unsigned)
X'07'
DESP_FUNC_DELETE
Constant to be used for DESP_FUNC
X'08'
DESP_FUNC_RENAME
Constant to be used for DESP_FUNC
X'09'
DESP_FUNC_UPDATE
Constant to be used for DESP_FUNC
X'04'
DESP_FUNC_PUT
Constant to be used for DESP_FUNC
X'01'
DESP_FUNC_GET
Constant to be used for DESP_FUNC
X'00'
DESP_FUNC_OMITTED
Constant to be used for DESP_FUNC
12 (X'0C')
384
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 84. DESERV PUT DESP Fields (continued)
Offset
Length or Bit
Pattern
Name
Description
17 (X'11')
3
-
Reserved
20 (X'14')
4
-
Reserved
24 (X'18')
12
DESP_DATA
Function data (character)
24 (X'18')
2
-
Reserved
26 (X'1A')
1
-
Reserved
27 (X'1B')
1
-
Reserved
28 (X'1C')
1
DESP_LIBTYPE
Indicates whether a DCB or a DEB is
input. (unsigned)
X'02'
DESP_LIBTYPE_DCB
DCB input
X'01'
DESP_LIBTYPE_DEB
DEB input
X'00'
DESP_LIBTYPE_OMITTED
Omitted
29 (X'1D')
1
-
Reserved
30 (X'1E')
1
-
Reserved
31 (X'1F')
1
-
Reserved
32 (X'20')
1
DESP_OPTION
REPLACE option (REPLACE=X'01',
NOREPLACE=X'00') (unsigned)
X'02'
DESP_OPTION_REPLACE_ALIAS
Constant to be used with
DESP_OPTION
X'01'
DESP_OPTION_REPLACE
Constant to be used with
DESP_OPTION
X'00'
DESP_OPTION_NOREPLACE
Constant to be used with
DESP_OPTION
33 (X'21')
1
-
Reserved
34 (X'22')
1
-
Reserved
35 (X'23')
1
-
Reserved
36 (X'24')
4
DESP_DCB_PTR
DCB address
40 (X'28')
4
DESP_DEB_PTR
DEB address
44 (X'2C')
4
-
Reserved
48 (X'30')
4
-
Reserved
52 (X'34')
4
-
Reserved
56 (X'38')
4
-
Reserved
60 (X'3C')
4
-
Reserved
64 (X'40')
4
-
Reserved
68 (X'44')
4
-
Reserved
72 (X'48')
4
DESP_MEM_DATA_PTR
MEM_DATA_ADDRESS
76 (X'4C')
4
DESP_MEM_DATA2
MEM_DATA entry count (unsigned)
80 (X'50')
4
-
Reserved
84 (X'54')
4
-
Reserved
88 (X'58')
4
-
Reserved
92 (X'5C')
4
-
Reserved
96 (X'60')
4
-
Reserved
Chapter 10. Using the DESERV Exit
385
DESERV Exit
Table 84. DESERV PUT DESP Fields (continued)
Offset
Length or Bit
Pattern
Name
Description
100 (X'64')
4
Reserved
-
PUT Return and Reason Codes
Figure 45 on page 387 describes the return and reason codes for the PUT function.
386
z/OS DFSMSdfp Advanced Services
DESERV Exit
Return Code
Description
DESRC_SUCC
X'00' Successful processing
Reason Code
DESRS_SUCC
DESRC_INFO 4
DESRC_WARN 8
Description
Not completely successful
Results questionable
Reason Code
DESRS_DST_ALREADY_EXISTS
DESRS_DST_COMP_SWAP_FAILED
DESRC_PARM 12
Description
X'00' Successful processing
Description
X'44B' An EXIT exists and DESERV FUNC EXIT with NOREPLACE
specified was issued. The current exit is not replaced
X'451' An EXIT_OPTION=DELETE specified a DST address that
was not current. The compare and swap failed.
Missing/invalid parameters
Reason Code
DESRS_EXIT_OPTION_INVALID
Description
X'44F' The EXIT_OPTION specified is not supported
DESRS_EXIT_SCOPT_INVALID
X'45'
DESRS_EXIT_DST_PTR_ZERO
X'44C' The caller of DESERV FUNC=EXIT supplied a DST address
of zero via the EXIT_DST parameter
The EXIT_SCOPE specified is not supported
DESRS_INVAL_DST_HEADER
X'44D' The DST header is not correct
DESRS_INVAL_PREVDST_HEADER
X'453' The DST header is not valid for the DST pointed to by
DESP_PREV_DSTPTR_PTR. This is checked for
EXIT_OPTION=DELETE
DESRS_PREV_DSTPTR_PTR_ZERO
X'452' The pointer to the previous DST is zero.
for EXIT_OPTION=DELETE
This is checked
DESRS_INVALID_PARM_LIST_HEADER X'411' The id, length, or level of the DESP is not valid
DESRC_CALR 16
DESRS_UNSUPPORTED_FUNC
X'424' The FUNC value is incorrect
DESRS_DEB_REQUIRES_AUTH
DESRS_INVALID_DCB_PTR
X'423' To pass the DEB the caller must be in supervisor state or a
privileged key
X'422' The address of the DCB is 0
DESRS_DCB_NOT_OPEN
X'421' The passed DCB is not opened
DESRS_INVALID_DEB_PTR
X'41E' Address of the DEB is 0 or DEB was input but the DCB
pointed to by the DEB did not point back to the DEB
Caller has a problem
Reason Code
DESRS_DEBCHK_FAILED
DESRS_AUTH_ERROR
DESRC_ENVR 20
Resources unavailable
DESRC_IOER 24
DESRC_MEDE 28
DESRC_DSLE 32
I/O error
Media error
Data set logical error
DESRC_SEVE 36
Severe error
Description
X'41D' The DEBCHK macro failed. The DCB or DEB was not valid
X'449' Caller not supervisor state or system key
Reason Code
Description
DESRS_UNKNOWN
X'447' Issued by the DESERV recovery routine when entered for an
unknown reason (ie. prog chk).
X'437' Non-zero return code from an IGWFESTK request
DESRS_ADD_STACK_FAILED
DESRS_SETLOOK_ERR
X'407' Bad return code from SETLOCK
DESRS_EXTRACT_ERROR
X'406' IGWFTOKM EXTRACT failed
DESRS_SET_ERROR
X'405' IGWFTOKM SET failed
DA6S3027
Figure 45. PUT Return and Reason Codes
The DESD (DESERV member data descriptor) is the input to the DESERV PUT
function. The DESD is an array consisting of the number of entries defined by the
Chapter 10. Using the DESERV Exit
387
DESERV Exit
DESP field DESP_MEM_DATA2. The DESP_MEM_DATA_PTR points to the DESD
and the DESD CSECT of the IGWDES macro maps it. The DESD structure is
shown in Table 85.
Table 85. DESD Parameter List
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
16
DESD
Member data descriptor (structure)
00 (X'00')
16
DESD_ENTRY
Entry descriptor (character)
00 (X'00')
1
DESD_FLAG
Flags (bitstring)
1... ....
DESD_FLAG_ALIAS
Alias entry
1
DESD_CODE
Processing code (error=X'02', not processed =X'01',
successful =X'00')(unsigned)
X'02'
DESD_CODE_ERROR
Constant to be used with DESD_CODE
X'01'
DESD_CODE_NOGO
Constant to be used with DESD_CODE
X'00'
DESD_CODE_SUCC
Constant to be used with DESD_CODE
2 (X'02')
2
DESD_ERRCODE
Error code (low order halfword of DESERV reason
code if error) (unsigned)
4 (X'04')
2
-
Reserved
6 (X'06')
2
DESD_DATA_LEN
Length of data area (unsigned)
08 (X'08')
4
DESD_DATA_PTR
Address of data (address)
12 (X'0C')
4
DESD_NAME_PTR
Address of varying length name (address)
1 (X'01')
The DESD_NAME_PTR points to the DESN structure. The DESD_DATA_PTR
points to the directory entry for the program object being saved in the PDSE
directory. The format of the directory entry is different depending on whether the
DESD entry represents the primary name or an alias name. For the primary name,
the DESD_DATA_PTR points to the CSECT PMAR mapped by IEWPMAR. For an
alias name, the DESD_DATA_PTR points to the CSECT PMARA mapped by the
macro IEWPMAR. Table 83 on page 383 shows the PMARA structure. The
DESD_FLAG_ALIAS identifies the entry in the DESD as a primary or an alias.
The DESERV exit is passed to the current return and reason code that is to be
passed back to the DESERV caller. The exit (either the pre-processing or the
post-processing) can cause DESERV to return a different return and reason code to
the DESERV caller by returning with a return code of 4 in register 15. If the exit
returns control to DESERV with a return code of 4 in register 15, the (possibly
modified) values of DESX_RETURN_CODE and DESX_REASON_CODE are
returned to the caller of DESERV. If the pre-processing exit returns a return code of
0 in register 15, processing continues. Whereas if the post-processing exit returns
with a return code of 0 in register 15, the original values of DESX_RETURN_CODE
and DESX_REASON_CODE (those that were passed as input to the exit) are
returned to the DESERV caller.
The exit processing can include interrogation of the DESERV parameter list (DESP)
or interrogation or modification of the other interface structures and buffers. The
DESP will not be modified by the DESERV exit. The exit is passed the caller key
DESP, but DESERV has already made a key 5 copy of the DESP that is used for
DESERV processing. Therefore modifications to the caller key DESP would not
388
z/OS DFSMSdfp Advanced Services
DESERV Exit
influence the DESERV processing. The DESERV interface structures are defined in
the macro IGWDES. The macros IGWSMDE and IEWPMAR define the directory
entry format.
Parameters Related to the DELETE Function
If the DESERV exit gets control for a DESERV DELETE function invocation,
DESX_DESP_PTR points to the DESERV parameter list. If the DESP field
DESP_FUNC=X'07' (DESP_FUNC_DELETE), this indicates a DELETE function
parameter list. Table 86 shows the fields of the DESP that pertain to the DESERV
DELETE invocation.
Table 86. DESERV DELETE DESP Fields
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
104
DESP
DE Services parameter list (structure)
00 (X'00')
16
DESP_HEADER
Standard header (character)
00 (X'00')
8
DESP_ID
Eyecatcher IGWDESP (character)
08 (X'08')
4
DESP_LEN
Length of DESP (signed)
X'04'
DESP_LEN_IV
Constant to be used with DESP_LEN
1
DESP_LEV
Control block level (character)
X'04'
DESP_LEV_IV
Constant to be used with DESP_LEV
13 (X'0D')
3
-
Reserved
16 (X'10')
1
DESP_FUNC
Function type (GET=X'01', PUT=X'04',
DELETE=X'07', RENAME=X'08', UPDATE=X'09')
X'09'
DESP_FUNC_UPDATE
Constant to be used with DESP_FUNC
X'08'
DESP_FUNC_RENAME
Constant to be used with DESP_FUNC
X'07'
DESP_FUNC_DELETE
Constant to be used with DESP_FUNC
X'04'
DESP_FUNC_PUT
Constant to be used with DESP_FUNC
X'01'
DESP_FUNC_GET
Constant to be used with DESP_FUNC
X'00'
DESP_FUNC_OMITTED
Constant to be used with DESP_FUNC
17 (X'11')
3
-
Reserved
20 (X'14')
4
-
Reserved
24 (X'18')
12
DESP_DATA
Function data (character)
24 (X'18')
2
-
Reserved
26 (X'1A')
1
-
Reserved
27 (X'1B')
1
-
Reserved
28 (X'1C')
1
DESP_LIBTYPE
Indicates whether a DCB or a DEB in input. (DCB
input X'02', DEB input X'01') (unsigned)
X'02'
DESP_LIBTYPE_DCB
Constant to be used with DESP_LIBTYPE
X'01'
DESP_LIBTYPE_DEB
Constant to be used with DESP_LIBTYPE
X'00'
DESP_LIBTYPE_OMITTED
Constant to be used with DESP_LIBTYPE
29 (X'1D')
1
-
Reserved
30 (X'1E')
1
-
Reserved
31 (X'1F')
1
-
Reserved
32 (X'20')
1
-
Reserved
12 (X'0C')
Chapter 10. Using the DESERV Exit
389
DESERV Exit
Table 86. DESERV DELETE DESP Fields (continued)
Offset
Length or Bit
Pattern
Name
Description
33 (X'21')
1
-
Reserved
34 (X'22')
1
-
Reserved
35 (X'23')
1
-
Reserved
36 (X'24')
4
DESP_DCB_PTR
DCB address
40 (X'28')
4
DESP_DEB_PTR
DEB address
44 (X'2C')
4
-
Reserved
48 (X'30')
4
-
Reserved
52 (X'34')
4
-
Reserved
56 (X'38')
4
-
Reserved
60 (X'3C')
4
-
Reserved
64 (X'40')
4
-
Reserved
68 (X'44')
4
-
Reserved
72 (X'48')
4
-
Reserved
76 (X'4C')
4
-
Reserved
80 (X'50')
4
DESP_NAME_LIST
List of names to be deleted (DESL) (address)
84 (X'54')
4
DESP_NAME_LIST2
Number of entries in DESL name list (unsigned)
88 (X'58')
4
-
Reserved
92 (X'5C')
4
-
Reserved
96 (X'60')
4
-
Reserved
100 (X'64')
4
-
Reserved
The DESL points to the names to be deleted. The DESP_NAME_LIST_PTR points
to the DESL and the DESL DSECT in the IGWDES macro maps it. A DESL is an
array consisting of the number of entries the DESP field DESP_NAME_LIST2
defines. The DESL structure is shown in Table 72 on page 375.
Parameters Related to the RENAME Function
If the DESERV exit gets control for a DESERV RENAME function invocation,
DESX_DESP_PTR points to the DESERV parameter list. If the DESP field
DESP_FUNC=X'08' (DESP_FUNC_RENAME), this indicates a RENAME function
parameter list. Table 87 shows the fields of the DESP that pertain to the DESERV
RENAME invocation.
Table 87. DESERV RENAME DESP Fields
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
104
DESP
DE Services parameter list (structure)
00 (X'00')
16
DESP_HEADER
Standard header (character)
00 (X'00')
8
DESP_ID
Eyecatcher IGWDESP (character)
08 (X'08')
4
DESP_LEN
Length of DESP (signed)
X'04'
DESP_LEN_IV
Constant to be used with DESP_LEN
390
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 87. DESERV RENAME DESP Fields (continued)
Offset
Length or Bit
Pattern
Name
Description
12 (X'0C')
1
DESP_LEV
Control block level (character)
X'04'
DESP_LEV_IV
Constant to be used with DESP_LEV
13 (X'0D')
3
-
Reserved
16 (X'10')
1
DESP_FUNC
Function type (GET=X'01', PUT=X'04',
DELETE=X'07', RENAME=X'08', UPDATE=X'09')
X'09'
DESP_FUNC_UPDATE
Constant to be used with DESP_FUNC
X'08'
DESP_FUNC_RENAME
Constant to be used with DESP_FUNC
X'07'
DESP_FUNC_DELETE
Constant to be used with DESP_FUNC
X'04'
DESP_FUNC_PUT
Constant to be used with DESP_FUNC
X'01'
DESP_FUNC_GET
Constant to be used with DESP_FUNC
X'00'
DESP_FUNC_OMITTED
Constant to be used with DESP_FUNC
17 (X'11')
3
-
Reserved
20 (X'14')
4
-
Reserved
24 (X'18')
12
DESP_DATA
Function data (character)
24 (X'18')
2
-
Reserved
26 (X'1A')
1
-
Reserved
27 (X'1B')
1
-
Reserved
28 (X'1C')
1
DESP_LIBTYPE
Indicates whether a DCB or a DEB is input.
(DCB,DEB) (DCB input X'02', DEB input X'01')
(unsigned)
X'02'
DESP_LIBTYPE_DCB
Constant to be used with DESP_LIBTYPE
X'01'
DESP_LIBTYPE_DEB
Constant to be used with DESP_LIBTYPE
X'00'
DESP_LIBTYPE_OMITTED
Constant to be used with DESP_LIBTYPE
29 (X'1D')
1
-
Reserved
30 (X'1E')
1
-
Reserved
31 (X'1F')
1
-
Reserved
32 (X'20')
1
-
Reserved
33 (X'21')
1
-
Reserved
34 (X'22')
1
-
Reserved
35 (X'23')
1
-
Reserved
36 (X'24')
4
DESP_DCB_PTR
DCB address
40 (X'28')
4
DESP_DEB_PTR
DEB address
44 (X'2C')
4
-
Reserved
48 (X'30')
4
-
Reserved
52 (X'34')
4
-
Reserved
56 (X'38')
4
-
Reserved
60 (X'3C')
4
-
Reserved
64 (X'40')
4
-
Reserved
68 (X'44')
4
-
Reserved
72 (X'48')
4
-
Reserved
Chapter 10. Using the DESERV Exit
391
DESERV Exit
Table 87. DESERV RENAME DESP Fields (continued)
Offset
Length or Bit
Pattern
Name
Description
76 (X'4C')
4
-
Reserved
80 (X'50')
4
DESP_NAME_LIST
List of pairs of names for rename operations
(DESL) (address)
84 (X'54')
4
DESP_NAME_LIST2
Number of entries in DESL name list (unsigned)
88 (X'58')
4
-
Reserved
92 (X'5C')
4
-
Reserved
96 (X'60')
4
-
Reserved
100 (X'64')
4
-
Reserved
The DESL points to the names that are to be renamed and to the new names. The
DESP_NAME_LIST_PTR points to the DESL and the DESL DSECT in the IGWDES
macro maps it. A DESL is an array consisting of the number of entries the DESP
field DESP_NAME_LIST2 defines. The DESL structure is shown in Table 72 on
page 375.
Parameters Related to the UPDATE Function
If the DESERV exit gets control for a DESERV UPDATE function invocation,
DESX_DESP_PTR points to the DESERV parameter list. If the DESP field
DESP_FUNC=X'09' (DESP_FUNC_UPDATE), this indicates an UPDATE function
parameter list. Table 88 shows the fields of the DESP that pertain to the DESERV
UPDATE invocation.
Table 88. DESERV UPDATE DESP Fields
Offset
Length or Bit
Pattern
Name
Description
00 (X'00')
104
DESP
DE Services parameter list (structure)
00 (X'00')
16
DESP_HEADER
Standard header (character)
00 (X'00')
8
DESP_ID
Eyecatcher 'IGWDESP' (character)
08 (X'08')
4
DESP_LEN
Length of DESP (signed)
X'04'
DESP_LEN_IV
Constant to be used with DESP_LEN
1
DESP_LEV
Control block level (character)
X'04'
DESP_LEV_IV
Constant to be used with DESP_LEV
13 (X'0D')
3
-
Reserved
16 (X'10')
1
DESP_FUNC
Function type (GET=X'01', PUT=X'04',
DELETE=X'07', RENAME=X'08', UPDATE=X'09')
X'09'
DESP_FUNC_UPDATE
Constant to be used with DESP_FUNC
X'08'
DESP_FUNC_RENAME
Constant to be used with DESP_FUNC
X'07'
DESP_FUNC_DELETE
Constant to be used with DESP_FUNC
X'04'
DESP_FUNC_PUT
Constant to be used with DESP_FUNC
X'01'
DESP_FUNC_GET
Constant to be used with DESP_FUNC
X'00'
DESP_FUNC_OMITTED
Constant to be used with DESP_FUNC
17 (X'11')
3
-
Reserved
20 (X'14')
4
-
Reserved
12 (X'0C')
392
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 88. DESERV UPDATE DESP Fields (continued)
Offset
Length or Bit
Pattern
Name
Description
24 (X'18')
12
DESP_DATA
Function data (character)
24 (X'18')
2
-
Reserved
26 (X'1A')
1
-
Reserved
27 (X'1B')
1
-
Reserved
28 (X'1C')
1
DESP_LIBTYPE
Function subtype (DCB,DEB) (DCB input X'02',
DEB input X'01') (unsigned)
X'02'
DESP_LIBTYPE_DCB
Constant to be used with DESP_LIBTYPE
X'01'
DESP_LIBTYPE_DEB
Constant to be used with DESP_LIBTYPE
X'00'
DESP_LIBTYPE_OMITTED
Constant to be used with DESP_LIBTYPE
29 (X'1D')
1
-
Reserved
30 (X'1E')
1
-
Reserved
31 (X'1F')
1
-
Reserved
32 (X'20')
1
-
Reserved
33 (X'21')
1
-
Reserved
34 (X'22')
1
-
Reserved
35 (X'23')
1
-
Reserved
36 (X'24')
4
DESP_DCB_PTR
DCB address
40 (X'28')
4
DESP_DEB_PTR
DEB address
44 (X'2C')
4
-
Reserved
48 (X'30')
4
-
Reserved
52 (X'34')
4
-
Reserved
56 (X'38')
4
-
Reserved
60 (X'3C')
4
-
Reserved
64 (X'40')
4
-
Reserved
68 (X'44')
4
-
Reserved
72 (X'48')
4
-
Reserved
76 (X'4C')
4
-
Reserved
80 (X'50')
4
DESP_NAME_LIST
List of SMDEs with imbedded PMAR (and
PMARL) to update the directory information
(DESL) (address)
84 (X'54')
4
DESP_NAME_LIST2
Number of entries in DESL name list (unsigned)
88 (X'58')
4
-
Reserved
92 (X'5C')
4
-
Reserved
96 (X'60')
4
-
Reserved
100 (X'64')
4
-
Reserved
The DESL points to the SMDEs which are to be updated. The
DESP_NAME_LIST_PTR points to the DESL and the DESL DSECT in the IGWDES
macro maps it. A DESL is an array consisting of the number of entries the DESP
field DESP_NAME_LIST2 defines. The DESL structure is shown in Table 72 on
page 375.
Chapter 10. Using the DESERV Exit
393
DESERV Exit
Entry Environment for Exit Routine
Interrupts:
Enabled
State and Key:
Supervisor state and key 0
ASC Mode:
P=H=S
AMODE, RMODE:
AMODE=31, RMODE=ANY
LOCKS:
No locks held
Registers:
0
1
2-12
13
14
15
unpredictable
address of DESERV EXIT parameter list mapped by DSECT DESX
in IGWDES.
unpredictable
eighteen word save area (key 0).
return address
entry point address of exit routine
The exit is entered in TASK mode and the DESERV recovery environment is an
ESTAE; therefore, the exit routine can issue SVCs, if required.
Exit Environment for Exit routine
Interrupts:
Enabled
State and Key:
Supervisor state and key 0
ASC Mode:
P=H=S
AMODE, RMODE:
AMODE=31, RMODE=ANY
LOCKS:
No locks held
Registers:
Unless otherwise specified, all registers must be restored to their contents
on entry.
15
Return code
v For pre-processing exit:
R15 = 0
Continue processing of this DESERV call.
R15 = 4
Discontinue processing of this DESERV call. Control is
immediately returned to the caller of DESERV with the return
and reason codes as set by the exit in the DESX fields
DESX_RETURN_CODE and DESX_REASON_CODE.
v For post-processing exit:
394
z/OS DFSMSdfp Advanced Services
DESERV Exit
R15 = 0
Continue processing of this DESERV call (that is, return to the
caller of DESERV).
R15 = 4
Control is returned to the caller of DESERV with the return and
reason codes as set by the exit in the DESX fields
DESX_RETURN_CODE and DESX_REASON_CODE. Values for
DESX_RETURN_CODE and DESX_REASON_CODE are
described in the macro IGWDES. The reason code structure is
such that the first two bytes are system component id and
module id (that is, system diagnostic information). The low
order two bytes contain the real reason code as indicated in the
macro IGWDES. For additional return and reason codes for the
GET, RENAME, DELETE, and UPDATE return and reason codes,
refer to z/OS DFSMS Macro Instructions for Data Sets.
v Restriction: Any other return code from the exits causes DESERV code
to take an SVC dump.
Registers on Entry to the DESERV Exit
When your DESERV exit gets control, the general-purpose registers have the
following content:
Register
Contents
0
not applicable
1
address of DESX
2-12
not applicable
13
address of register save area
14
return address
15
address of DESERV exit entry point
Registers on Return from the DESERV Exit
When you return control to DESERV, the register contents must be set up as
follows:
Register
Contents
0-14
restored to contents at entry
15
return code
DESERV Exit Return and Reason Codes
Return Code
Description
00 (X'00')
Continue with DESERV function
04 (X'04')
Return immediately to the DESERV caller and return the return and reason
codes as defined by DESX_RETURN_CODE and DESX_REASON_CODE
respectively.
DESERV FUNC=EXIT Return and Reason Codes
The formats of the return and reason codes are:
Chapter 10. Using the DESERV Exit
395
DESERV Exit
Offset/length
Description
00 (X'00') 1 byte
SMS Component code (X'27') indicates Common Adaptor (of which
DESERV is a part)
01 (X'01') 1 byte
Module ID - used for problem diagnosis
02 (X'02') 2 bytes
Reason code - identifies the error. A program testing the DESERV reason
code should only look at these last two bytes. The component id and
module id should not be tested. They are reported for diagnostic purposes
only.
The following are the two low order byte values for the reason codes that DESERV
FUNC=EXIT might return (sorted by return code).
Table 89. Return and Reason Codes for the Exit DESERV Function
Return Code
Reason Code
Symbolic name
Description
DESRC_SUCC
Successful
DESRS_SUCC
Successful
DESRC_INFO
Not completely successful.
DESRS_NAME_
NOT_DEFINED
Name to be replaced did not
previously exist
X'8'
DESRC_WARN
Results questionable
X'12'
DESRC_PARM
Missing or invalid
parameters
X'411'
DESRS_INVALID_
PARM_LIST_HEADER
The id, length, or level of
the DESP is not valid
X'415'
DESRS_PDS_
NOT_SUPPORTED
This function requires a
PDSE data set
X'41E'
DESRS_INVALID_ DEB_PTR Address of the DEB is 0 or
DEB was input but the DCB
pointed to by the DEB did
not point back to the DEB
X'41F'
DESRS_DCB_NOT_
OPEN_OUTPUT
With function PUT the DCB
must have been opened for
output
X'421'
DESRS_DCB_ NOT_OPEN
The passed DCB is not
opened
X'422'
DESRS_INVALID_
DCB_PTR
The address of the DCB is 0
X'423'
DESRS_DEB_
REQUIRES_AUTH
To pass the DEB, the caller
must be in supervisor state
or a privileged key
X'424'
DESRS_
UNSUPPORTED_FUNC
The FUNC value is incorrect
X'427'
DESRS_INVALID_
MEM_DATA_CNT
The count of entries in the
MEM_DATA block is 0
X'428'
DESRS_INVALID_
MEM_DATA_PTR
The address of the
MEM_DATA block is 0
X'0'
X'00'
X'4'
X'400'
396
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 89. Return and Reason Codes for the Exit DESERV Function (continued)
Return Code
Reason Code
Symbolic name
Description
X'429'
DESRS_INVALID_
PUT_OPTION
The PUT function requires
that the OPTION field be
specified
DESRC_CALR
Caller has a problem
X'3FD'
DESRS_PRI_
NM_THIS_FILE
Alias name is same name as
primary name for this
member
X'400'
DESRS_NAME_
ALREADY_EXISTS
Name to be replaced did not
previously exist
X'40E'
DESRS_NAME_
ALREADY_EXISTS
The PUT failed because of a
name conflict
X'40F'
DESRS_NP_
PRIMARY_NAME
The MEM_DATA must have
one member designated as
primary
X'410'
DESRS_INVALID_
NAME_PREFIX
The first 8 bytes of a name
were all X'FF'
X'412'
DESRS_MORE_
THAN_!_PRIMARY
The MEM_DATA must have
only one member designated
as primary
X'413'
DESRS_ INVALID_MLT
MLT is not valid
X'414'
DESRS_ INVALID_CT
Connect token is not valid
X'41D'
DESRS_DEBCHK_ FAILED
The DEBCHK macro failed,
the DCB or DEB was not
valid
X'425'
DESRS_INVALID_
NAME_LENGTH
The length of an alias name
was either 0 or greater than
8
X'43A'
DESRS_DATA_
LENGTH_ERROR
The DESD data length is not
valid, data length must be
greater than 0 and less than
108 bytes
X'43C'
DESRS_NAME_
IS_PRIMARY_NAME
The alias name specified is a
primary name and the
options did not allow for
deleting primary name
X'20'
DESRC_ENVR
Resources unavailable
X'24'
DESRC_IOER
I/O error
X'28'
DESRC_MEDE
Media Error
X'32'
DESRC_DSLE
Data Set logical error
X'36'
DESRC_SEVE
Severe error
X'407'
DESRS_ SETLOOK_ERR
Bad return code from
SETLOCK
X'437'
DESRS_ADD_
STACK_FAILED
Non-zero return code from
an IGWFESTK request
X'16'
Chapter 10. Using the DESERV Exit
397
DESERV Exit
Table 89. Return and Reason Codes for the Exit DESERV Function (continued)
Return Code
X'0C'
Reason Code
Symbolic name
Description
X'447'
DESRS_UNKNOWN
Issued by the DESERV
recovery routine when
entered for an unknown
reason (for example, a
program check) while the
exit routine was in control.
Most likely an exit error.
X'469'
DESRS_DST_EXIT_PTR_
NOT_COMMON
Global exit address is not in
common storage.
Additional Return and Reason Codes: For the GET, RENAME, DELETE, and
UPDATE return and reason codes, refer to z/OS DFSMS Macro Instructions for Data
Sets.
Example of the DESERV Exit
The following program segment establishes and deletes the task mode DESERV
exit and thereby restores the previous task. The sample is generic enough to apply
to either the global or the task level exit but shows here the task level support.
When establishing a global exit, obtain the DST storage in common storage.
398
z/OS DFSMSdfp Advanced Services
DESERV Exit
SAMPLE
CSECT
USING *,12
STM
14,12,12(13)
LR
12,15
LA
2,SAVE
ST
2,8(13)
ST
13,SAVE+4
LR
13,2
.
.
.
SAVE REGISTERS
ESTABLISH BASE REGISTER
ADDRESS REGISTER SAVE AREA
FORWARD CHAIN SAVE AREA
BACKWARD CHAIN SAVE AREA
ESTABLISH SAVE AREA
*
*
* ESTABLISH THE TASK LEVEL EXIT
*
*
BUILD THE DST TO REPRESENT MY TASK LEVEL EXIT
*
LA
3,MY_DST
ADDRESSABILITY TO MY DST
USING DST,3
MAP DST
XC
DST,DST
CLEAR MY DST STORAGE
MVC
DST_ID,DST_ID_CONST SET EYECATCHER IN DST
LA
15,DST_LEN_IV(,0)
GET LENGTH OF DST
ST
15,DST_LEN
SET LENGTH OF DST
MVI
DST_LEV,DST_LEV_IV
SET LEVEL OF DST USED
OI
DST_FLAGS,DST_FLAGS_PROP SET FLAG TO PROPAGATE THIS
EXIT
*
TO ATTACHED TASKS.
MVC
DST_EXIT_PTR,ADDR_DESEXIT SET ADDRESS OF TASK EXIT
*
*
CALL DESERV TO ENABLE MY TASK LEVEL EXIT
*
THIS MODULE ASSUMES THAT IT IS RUNNING EITHER SUPERVISOR STATE
*
OR SYSTEM KEY.
*
DESERV FUNC=EXIT,
*
EXIT_SCOPE=TASK,
*
EXIT_OPTION=REPLACE,
*
EXIT_DST=MY_DST,
*
EXIT_PREV_DSTPTR=MY_PREV_DSTPTR,
*
MF=S
.
.
.
*
* QUERY THE CURRENT DST ADDRESS, RETURNED IN CURRENT_DSTPTR.
* THERE IS NO NEED TO QUERY PRIOR TO DOING THE DELETE, THIS IS
* HERE JUST TO SHOW THE INVOCATION SYNTAX.
*
DESERV FUNC=EXIT,
*
EXIT_SCOPE=TASK,
*
EXIT_OPTION=QUERY,
*
EXIT_PREV_DSTPTR=CURRENT_DSTPTR,
*
MF=S
Figure 46. Establishing and Deleting a Task Level DESERV Exit Part 1 of 2
Chapter 10. Using the DESERV Exit
399
DESERV Exit
*
*
*
*
*
*
HERE THE APPLICATION WOULD DO SOMETHING TO
CAUSE A DESERV CALL TO BE DONE. AN EXAMPLE OF THIS TYPE OF THING
WOULD BE ATTACHING THE BINDER AS A SUBTASK (THE BINDER USES
DESERV.)
.
.
.
*
* DELETE THE TASK LEVEL EXIT
*
DESERV FUNC=EXIT,
EXIT_SCOPE=TASK,
EXIT_OPTION=DELETE,
EXIT_DST=MY_DST,
EXIT_PREV_DSTPTR=MY_PREV_DSTPTR,
MF=S
.
.
.
*
* RESTORE REGISTERS AND RETURN
L
13,SAVE+4
LM
14,12,12(13)
SR
15,15
SET RETURN CODE
BR
14
RETURN TO CALLER
* THE FOLLOWING IS A BLOCK USED BY THIS APPLICATION. THIS BLOCK CAN
* BE USED BY THE EXIT. THE EXIT ALSO (SMARTLY) FINDS THE
* PREV_DST_PTR FIELD IN MY_BLOCK WHEN IT GIVES CONTROL TO THE
* PREVIOUSLY ESTABLISHED TASK LEVEL EXIT.
MY_BLOCK
DS 0D
MY APPLICATION BLOCK
MY_APPLICATION_STUFF DS CL8
MY APPLICATION STUFF
MY_DST
DS CL(DST_LEN_IV) MY DST IMBEDDED IN MY BLOCK
MY_PREV_DSTPTR DS F
ADDRESS OF PREVIOUS TASK LEVEL
EXTRN
DESEXIT
ADDR_DESEXIT
DC A(DESEXIT)
ADDRESS OF MY TASK LEVEL EXIT
DST_ID_CONST
DC CL8’IGWDST ’ DST EYECATCHER
*
DST
CURRENT_DSTPTR DS F
ADDRESS OF CURRENT TASK LEVEL
*
DST
SAVE
DS 18F
REGISTER SAVE AREA
END
*
*
*
*
*
Figure 47. Establishing and Deleting a Task Level DESERV Exit Part 2 of 2
The following program segment shows a sample DESERV exit. This is the exit
established by the previous segment of code. This sample shows how to pass
control to a previous exit. Note that this sample exit is not reentrant, so it assumes
there is only one subtask.
400
z/OS DFSMSdfp Advanced Services
DESERV Exit
DESEXIT CSECT
DESEXIT AMODE 31
Must be AMODE 31
DESEXIT RMODE ANY
Could be RMODE 24 if required
*
* entry code to save registers and establish base register.
USING *,12
STM
14,12,12(13)
SAVE REGISTERS
LR
12,15
ESTABLISH BASE REGISTER
LA
2,SAVE
ADDRESS REGISTER SAVE AREA
ST
2,8(13)
FORWARD CHAIN SAVE AREA
ST
13,SAVE+4
BACKWARD CHAIN SAVE AREA
LR
13,2
ESTABLISH SAVE AREA
*
* Assume this exit is only interested in the output from GET functions.
* Therefore ignore entry for all other functions and only
* process the get function invocations where get processing is complete
*
SLR
2,2
clear reg
ST
2,EXIT_RC
initialize return code
LR
2,1
get the DESX address in reg 2
USING DESX,2
map the DESX
L
3,DESX_DST_PTR
get address of DST
LR
4,3
get address of DST
LA
5,MY_DST-MY_BLOCK(,0) get offset to DST within MY_BLOCK
SR
4,5
get the address of MY_BLOCK
USING MY_BLOCK,4
map MY_BLOCK
*
* First give control to any previously established DESERV
* exits. If the value in PREV_DST_PTR is zero, then there was no
* previous DST (that is, no previous DESERV exit). PREV_DST_PTR was
* saved in MY_BLOCK by the SAMPLE CSECT that enabled this
* exit.
SR
15,15
simulate previous exit’s return code
ICM
5,15,PREV_DST_PTR get previous DST address
BZ
NOPREVDST
branch if zero, no previous DST
* There was a previous exit, to which you transfer control.
* First build a DESX then branch to the previous exit.
*
*
* Getmain dynamic storage for interfacing with the other exit
*
*
GETMAIN RU,LV=DESX_LEN_IV,SP=230,KEY=0,LOC=(ANY)
ST
1,MY_DESX_STG_PTR
MVC
0(L’DESX,1),DESX copy the DESX that was input to this
*
routine.
ST
5,DESX_DST_PTR-DESX(,1) Set previous DST address in DESX
L
15,DST_EXIT_PTR-DST(,5) get address of previous exit
BALR
14,15
call the previous exit in 31 bit amode
Figure 48. Sample DESERV Exit Routine Part 1 of 3
Chapter 10. Using the DESERV Exit
401
DESERV Exit
NOPREVDST EQU *
ST
15,EXIT_RC
save previous exit’s return code
* If this invocation of the exit was the pre-processing exit and the
* exit we called just returned with a return code of 4 then they
* might have returned the data in question.
TM
DESX_FLAGS,DESX_POST_BIT is this post-processing call
BO
POST
yes, branch
* this is a pre-processing call, did the exit just called request an
* immediate return, and therefore maybe fill in the output fields
* if the return code was zero, the called routine wants deserv to
* perform the function.
CLC
EXIT_RC,ZERO
was return code zero
BE
RETURN
yes, branch to return to deserv
POST
EQU
*
either called exit performed the
*
deserv function, or this is a post
*
processing exit call.
L
6,DESX_DESP_PTR
get the DESERV parameter list (DESP)
USING DESP,6
map DESP
CLI
DESP_FUNC,DESP_FUNC_GET is this a function GET call
BNE
RETURN
no, branch
CLC
DESX_REASON_CODE+2(2),=AL2(DESRS_SUCC) check low order
*
halfword of reason code for success
BE
GOODDATA
branch if DESERV GET was successful
CLC
DESX_REASON_CODE+2(2),=AL2(DESRS_NOTFOUND) check for
*
some members not found
BNE
BADDATA
branch if some other error
GOODDATA EQU
*
*
* Process the entries in the names list that were found
*
.
.
.
B
RETURN
return to the caller (DESERV)
BADDATA EQU
*
.
.
.
*
RETURN EQU
*
Return to caller (DESERV)
*
* restore registers, FREEMAIN storage, etc.
*
L
15,EXIT_RC
set return code
L
13,SAVE+4
L
14,12(13)
restore return address
LM
0,12,20(13)
restore callers other registers
BR
14
return to deserv
Figure 49. Sample DESERV Exit Routine Part 2 of 3
402
z/OS DFSMSdfp Advanced Services
*
* CONTROL INFORMATION
*
SAVE
DS 18F
ZERO
DC F’0’
EXIT_RC
DC F’0’
DESX_ID_CONST DC CL8’IGWDESX ’
MY_DESX_STG_PTR DC F’0’
*
MY_BLOCK
DSECT
MY_APPLICATION_STUFF DS CL8
MY_DST
DS CL(DST_LEN_IV)
PREV_DST_PTR
DS F
IGWDES
IGWSMDE
IEWPMAR
*
END
REGISTER SAVE AREA
constant of zero
Return code to pass back to DESERV
EYECATCHER FOR DESX
ADDRESS OF GETMAINED STORAGE FOR
DESX TO PASS TO PREVIOUS EXIT.
MY APPLICATION BLOCK
MY APPLICATION STUFF
MY DST IMBEDED IN MY BLOCK
ADDRESS OF PREVIOUS TASK LEVEL EXIT
DESERV MAPPINGS
DIRECTORY ENTRY
PROGRAM MANAGEMENT ATTRIBUTE RECORD
THE PMAR IS A SUB RECORD OF THE SMDE
Figure 50. Sample DESERV Exit Routine Part 3 of 3
Chapter 10. Using the DESERV Exit
403
404
z/OS DFSMSdfp Advanced Services
Chapter 11. Managing Hierarchical File System Data Sets
A hierarchical file system (HFS) data set is a data set that contains a
POSIX-compliant hierarchical file system, which is a collection of files and
directories organized in a hierarchical structure that can be accessed using z/OS
UNIX system services. You can use many of the standard BSAM, QSAM, BPAM,
and VSAM interfaces to access data in z/OS UNIX HFS files. Most applications
that use these access methods can access HFS files without reassembly or
recompliation.
The contents of HFS data sets are structured like a tree, based on a root directory
with various subdirectories. The files within an HFS data set are identified by their
path and file names.
DFSMShsm can automatically back up HFS data sets if it is using DFSMSdss as its
data mover, but it cannot back up individual files within an HFS data set.
Once you evaluate z/OS UNIX and decide to install it in your enterprise, you may
proceed with the following planning tasks:
v Deciding which DASD devices will contain the HFS data sets
v Deciding how to control access to them
v Structuring the file systems
v Determining backup, restore, and expiration date policies
v Determining HFS naming policies (file names can be up to 255 characters long
and path names can be up to 1023 characters)
v Defining data classes, management classes, and coding ACS routines and JCL
statements for HFS data sets
Creating Hierarchical File System Data Sets
You specify HFS in the DSNTYPE parameter to allocate an HFS data set. You can
also define a data class for HFS data sets. Both cataloged and uncataloged HFS
data sets can reside on a single non-SMS-managed volume. A cataloged HFS data
set can also be a multivolume if it resides on Storage Management Subsystem
managed volumes. This type of data set can expand to as many as 255 extents of
direct access storage device (DASD) space on multiple volumes (59 volumes
maximum with 123 extents per volume).
RACF or an equivalent security product must be installed and active on your
system to use z/OS UNIX or HFS data sets. z/OS UNIX maintains system security
by verifying user identities and file access control information.
This information covers the following:
v “Defining the Root File System” on page 406
v “Creating and Mounting the Root File System” on page 406
v “Creating Additional File Systems and Directories” on page 406
v “Adding and Mounting File Systems to the Root File System” on page 407
© Copyright IBM Corp. 1979, 2017
405
Planning for HFS
Defining the Root File System
During installation of z/OS UNIX, a system programmer or storage administrator
codes the ROOT statement in the BPXPRMxx member of SYS1.PARMLIB. This
identifies the HFS data set containing the root file system for the system to
logically mount when it starts z/OS UNIX system services.
ROOT
FILESYSTEM(’OMVS.ROOT’)
TYPE(HFS)
MODE(RDWR)
The root file system is the starting point of the overall file structure. It consists of
the root directory and any related HFS files or subdirectories. After installation is
complete and the MVS system is running, you can create (allocate) an HFS data
set, which contains the root file system.
See z/OS MVS Initialization and Tuning Reference for information about member
BPXPRMxx.
Creating and Mounting the Root File System
Create an HFS data set to contain the root file system by running a job to allocate
the data set. During allocation, z/OS UNIX builds a basic root directory, which
you can alter to meet your specific needs. You specify DSNTYPE=HFS to designate
an HFS data set.
//STEP1
//MKFS
//
EXEC PGM=IEFBR14
DD DSNAME=OMVS.ROOT,DISP=(NEW,CATLG),
DSNTYPE=HFS,SPACE=(CYL,(1,1,1))
Tip: To make the HFS data set SMS-managed, use the ACS routines or specify the
STORCLAS parameter in the JCL. HFS data sets do not have to be SMS-managed.
Write operations present the greatest exposure to file system damage. For this
reason the root file system should be small, minimizing the amount of write
activity to it, thus offering the least exposure to damage.
Additionally, if all users' files are in file systems that are mounted on the root file
system, rather than defined as part of the root itself, and users are denied write
access to the root, the root is further protected from inadvertent damage. Damaged
user directories or files can be unmounted and replaced without causing z/OS
UNIX system services to fail.
Creating Additional File Systems and Directories
After allocating an HFS data set for the root file system and logging on as a
TSO/E user, you can define additional directories in the root file system using the
MKDIR command. For example, to create the /u/joe directory, issue:
MKDIR '/u'
MKDIR '/u/joe'
These directories can be used as mount points for additional mountable file
systems. You can use an IBM-supplied program that creates directories,
pseudo-TTY pairs, and device files. Interactive users and application programs can
then add files to those additional file systems.
The MKDIR command requires written permission on the parent directory of the
directory to be created.
406
z/OS DFSMSdfp Advanced Services
Planning for HFS
Adding and Mounting File Systems to the Root File System
If you have appropriate authority, you can create other mountable file systems
with their own directory and data file structures, and mount them on a directory
in the root file system or in another file system. Each file system can be logically
mounted to a directory (mount point) in another file system by using the TSO/E
MOUNT command. Use the UNMOUNT command to unmount a file system. To
create and mount additional file systems:
1. Allocate an additional HFS data set by using either the TSO/E ALLOCATE
command as shown in the following example or a JCL DD statement similar to
that shown in “Creating and Mounting the Root File System” on page 406.
ALLOCATE DSNAME(’OMVS.USER.JOE’) NEW DSNTYPE(HFS) BLKSIZE(0)
LRECL(0) RECFM(U) DSORG(PO) SPACE(1,1) CYLINDERS
The new data set is allocated with an empty root directory.
2. Have an authorized user enter a TSO/E MOUNT command to logically mount
the new file system in the directory of an existing file system.
MOUNT FILESYSTEM(’OMVS.USER.JOE’) TYPE(HFS) MOUNTPOINT(’/u/joe’)
You can specify additional file systems to be logically mounted automatically every
time z/OS UNIX is started by adding MOUNT commands to the BPXPRMxx
member of SYS1.PARMLIB. The following restrictions apply to mounting file
systems:
v The mount point must be a directory.
v Any files in the directory are not accessible while the file system is mounted.
v Only one mount can be active at any time for a mount point.
v A file system can be mounted on only one directory at a time.
You can also create special HFS files to perform the following tasks:
v Represent hardware devices (character special files).
v Allow the use of alias names for HFS files (symbolic links).
v Send data from one process to another so that the receiving process reads the
data first-in-first-out (FIFO special files, also called named pipes). The term
process as used here is defined as either a program that is created by the fork
function, or a program that requests z/OS UNIX system services.
Managing File System Size
File system size increases as users add files and extend existing files. Eventually, a
file system can outgrow the space on its volume. In this case, the storage
administrator or system programmer responsible for HFS data sets can either make
more space available on the volume by moving individual HFS files to other file
systems that have space available, or do one of the following:
v Move the entire file system to another set of volumes as follows:
1. Have an authorized user enter a TSO/E UNMOUNT command to logically
unmount the file system.
2. Allocate an HFS data set with a different data set name on a volume, or set
of volumes, that has adequate space available.
3. Use the DFSMSdss DUMP function to logically dump the old file system.
4. Use the DFSMSdss RESTORE function to restore the dumped file system
with a new name to a volume, or set of volumes, that has sufficient space. If
you want to maintai