IBM DFSMSdfp Advanced Services User manual
বিজ্ঞাপন
বিজ্ঞাপন
z/OS
DFSMSdfp Advanced Services
Version 2 Release 3
IBM
SC23-6861-30
Note
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
Address and Register Conventions .
Summary of changes . . . . . . . . xvii
Summary of changes for z/OS Version 2 Release 3
Summary of changes for z/OS Version 2 Release 2
z/OS Version 2 Release 1 summary of changes xviii
How to send your comments to IBM xix
If you have a technical problem .
Chapter 1. Using the Volume Table of
Contents . . . . . . . . . . . . . . 1
Data Set Control Block (DSCB) Types .
Allocating and Releasing DASD Space .
Accessing the VTOC with DADSM Macros .
Requesting DASD Volume Information Using
Reading DSCBs from the VTOC Using OBTAIN 37
Releasing Unused Space from a DASD Data Set
Creating (Allocating) a DASD Data Set Using
Accessing the VTOC with CVAF Macros.
Generating a CVPL (CVAF Parameter List) .
Using Macro ICVEDT02 to Map the Extents Area 63
Accessing DSNs or DSCBs in Sequential Order 66
Reading Sets of DSCBs with CVAF Filter .
Coding CVAF VTOC Access Macros .
CVAFDIR Macro Overview and Specification .
CVAFDSM Macro Overview and Specification .
CVAFFILT Macro Overview and Specification
CVAFSEQ Macro Overview and Specification
CVAFTST Macro Overview and Specification
VTOC Index Error Message and Associated
© Copyright IBM Corp. 1979, 2017
Recovering from System or User Errors .
VTOC and VTOC Index Listings .
Chapter 2. Managing the Volume Table of Contents . . . . . . . . . . . . 143
Creating the VTOC and VTOC Index .
Protecting the VTOC and VTOC Index .
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 .
System-Managed-Storage Considerations .
General Considerations and Restrictions .
SCRATCH and CAMLST Macro Specification .
Renaming a Data Set in the VTOC .
Specifying the Volumes Affected .
System-Managed-Storage Considerations .
General Considerations and Restrictions .
RENAME and CAMLST Macro Specification .
Chapter 3. Using Catalog Management
Macros . . . . . . . . . . . . . . 157
Application Program Considerations .
Retrieving Information from a Catalog .
Retrieving Information by Data Set Name
Retrieving Information by Generation Data Set
Name (LOCATE and CAMLST NAME) .
Retrieving Information by Alias (LOCATE and
Reading a Block by Relative Block Address
Using Non-VSAM Data Set Catalog Entries .
Cataloging a Non-VSAM Data Set (CATALOG and CAMLST CAT) .
Uncataloging a Non-VSAM Data Set
Recataloging a Non-VSAM Data Set (CATALOG and CAMLST RECAT) .
iii
Channel Programs . . . . . . . . . 169
Allocating the Data Set or Device.
Direct Data Set Considerations .
VSAM Data Set Considerations .
Creating the Channel Program .
Comparing CCW and zHPF channel programs 176
EXCP 64-bit Storage Considerations .
IDAW Requirements for EXCP Requests .
IDAW Requirements for EXCPVR Requests .
TIDAW requirements for EXCP requests .
Determining Whether zHPF is Supported for a
Modifying a Channel Program During
Creating the EXCP-Related Control Blocks.
Input/Output Block Common Extension (IOBE) 184
Input/Output Error Data Block (IEDB) .
Data Control Block Extension (DCBE) .
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
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
Handling End of Volume and End-Of-Data-Set
Data Control Block (DCB) Fields .
Data Control Block Extension (DCBE) Fields .
Input/Output Error Data Block (IEDB) Fields 209
Input/Output Block (IOB) Fields .
Input/Output Block Common Extension (IOBE)
Event Control Block (ECB) Fields .
Data Extent Block (DEB) Fields .
Making Appendages Available to the System 224
The Authorized Appendage List (IEAAPP00) 224
iv
z/OS DFSMSdfp Advanced Services
Page Fix and EXCPVR Start I/O Appendage 226
Program-Controlled Interruption Appendage 227
Converting a Relative Track Address to an Actual
Return Codes from the Relative to Actual
Converting an Actual Track Address to a Relative
Return Codes from the Conversion Routine .
Using the IECTRKAD Callable Service or the
Obtaining the Sector Number of a Block on an RPS
Chapter 5. Using XDAP to Read and
Write to Direct Access Devices . . . . 239
Macro Instructions Used with XDAP .
Defining a Data Control Block (DCB) .
Initializing a Data Control Block (OPEN) .
Restoring a Data Control Block (CLOSE) .
Executing Direct Access Programs .
Control Blocks Used with XDAP .
Direct Access Channel Program .
Chapter 6. Using Password Protected
Data Sets . . . . . . . . . . . . . 247
PASSWORD Data Set Characteristics .
Creating Protected Data Sets .
Protection Feature Operating Characteristics .
Maintaining the PASSWORD Data Set Using
Instructions . . . . . . . . . . . . 259
Ensuring Data Security by Validating the Data
Obtaining I/O Device Characteristics (DEVTYPE macro).
Reading and Modifying a Job File Control Block
DEQ at Demount Facility for Tape Volumes .
High-Speed Cartridge Tape Positioning.
OPEN - Initialize Data Control Block for
Purging and Restoring I/O Requests (PURGE and
Performing Track Calculations (TRKCALC macro) 307
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
Extract 28-bit cylinder number (TRKADDR
Extract 4-bit track number (TRKADDR
Increment track address (TRKADDR
Normalize cylinder number (TRKADDR
Convert a relative track number to a 28-bit cylinder address (TRKADDR RELTOABS) .
Set cylinder number from register (TRKADDR
Convert normalized track address into an absolute 28-bit track address (TRKADDR
Determining Level and Name of DFSMS .
Determining Version, Release, and Modification
Determining DFARELS During Assembler
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
Chapter 9. Using DFSMSdfp Callable
Services . . . . . . . . . . . . . 341
Call for DFSMS Level Determination .
Call for Data Set Attribute Retrieval .
Call for Data Set Backup-While-Open Support .
Using the Backup-While-Open Facility .
Call for DFSMSdfp Share Attributes .
IGWASYS, IGWASMS, IGWABWO, IGWLSHR
Call for Record-Level Sharing Query (IGWARLS) 355
Call for converting and comparing 28-bit cylinder addresses (IECTRKAD) .
Character Data Representation Architecture
Chapter 10. Using the DESERV Exit 363
Interactions Between the Task Level and Global
Establishing Multiple Task level or Multiple Global
Issuing DESERV FUNC=EXIT (invocation environment) .
Installing or Replacing the DESERV Exit .
Determining If a DESERV Exit Is Active .
Parameters Related to the GET Function .
Parameters Related to the PUT Function .
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 395
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 406
Contents
v
Creating Additional File Systems and
Adding and Mounting File Systems to the Root
Managing File System Activity .
Accessing HFS Data Set Attributes .
Removing (Deleting) a File System .
Recovering a Backed-Up File System .
HFS Deferred File System Synchronization .
Using pfsctl (BPX1PCT) Physical File System
BPX1PCT Return and Reason Codes.
Subsystem Statistics, Status, and
Counts Information . . . . . . . . . 421
Passed Argument List -- SSGARGL .
Appendix A. Control Blocks . . . . . 443
Data Extent Block (DEB) Fields .
Data Facilities Area (DFA) Fields .
Appendix B. Maintaining the System
Image Library . . . . . . . . . . . 455
Examples of UCS Image Coding .
UCS Image Tables in SYS1.IMAGELIB .
Alias Names in UCS Image Tables .
Adding or Modifying a UCS Image Table Entry 466
Adding an FCB Image to the Image Library .
JES Support for the 3211 Indexing Feature .
Information conventions for the EAV migration assistance tracker .
DFSMS instances tracked by the EAV migration assistance tracker .
DCB Open of EAS eligible data set .
Appendix D. Accessibility . . . . . . 495
Consult assistive technologies .
Keyboard navigation of the user interface .
Dotted decimal syntax diagrams .
Notices . . . . . . . . . . . . . . 499
Terms and conditions for product documentation 501
Policy for unsupported hardware.
Index . . . . . . . . . . . . . . . 505
vi
z/OS DFSMSdfp Advanced Services
Figures
Locating the volume table of contents .
Contents of VTOC - DSCBs Describing Data
Sets on Volume That Has No VTOC Index .
Contents of VTOC on an extended address volume - DSCBs Describing Data Sets on
Volume That Has No VTOC Index .
Example of the Relationship of a VTOC to Its
DADSM LSPACE Free Space Information
DADSM LSPACE Free Space Information
Control Blocks Required for CVAF Filter
Example of CVAFDIR Macro with VTOC Part
Example of CVAFDIR Macro with VTOC Part
How EXCP translates an EXCP request with a single 16K storage area .
How EXCP translates an EXCP request with a storage areas crossing page boundaries .
Using IOSPHPF to determine if zHPF is supported by a processor and device .
Data Control Block Format for EXCP (After
Device-dependent portion of the DCB with
DEVD=DA and DSORG=PS (or DSORG=PO) . 204
Device-dependent portion of the DCB with
Device-dependent portion of the DCB with
Device-dependent portion of the DCB with
Device-dependent portion of the DCB with
Format of an IEDB, Mapped by the
Input/Output Block (IOB) Format .
IOBFLAG3 and IOBCSW fields for format 0 channel program .
IOBFLAG3 and IOBCSW fields for format 1 channel program .
IOBFLAG3 and IOBCSW fields for zHPF channel program .
Format of an IOBE, mapped by the
Event Control Block after Posting of
Parameter List for ADD Function .
Parameter List for REPLACE Function 255
Parameter List for DELETE Function 256
Parameter List for LIST Function .
Examples of Standard Form of the RDJFCB macro .
Example Code Using RDJFCB Macro
Processing a Multivolume Data Set with
Sample Code Retrieving Allocation
Sample Code Retrieving Allocation
Examples of Standard Form of the OPEN
Example of Determining Symbol Definition 324
Example of an IGWASYS Call Statement 345
Example of an IGWASMS Call LINK
Example of IGWABWO Using LOAD and
Example of the IGWARLS Query Call Using
Establishing and Deleting a Task Level
Establishing and Deleting a Task Level
Sample DESERV Exit Routine Part 1 of 3 401
Sample DESERV Exit Routine Part 2 of 3
Sample DESERV Exit Routine Part 3 of 3
Code to Add a 1403 UCS Image to
Code to Add a 3203 UCS Image to
Sample Code to Add a 3211 UCS Image to
UCS Image Table Entry Format .
Adding a New Band ID to the 4245 UCS
Adding a New Default Entry to the 4248 UCS
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 .
© Copyright IBM Corp. 1979, 2017
vii
viii
z/OS DFSMSdfp Advanced Services
Tables
2. DSCB Format-1 or Format-8 .
7. Format of the LSPACE Parameter List (MF=D) 30
8. DADSM LSPACE Message Return Area
9. LSPACE Data Return Area Format .
10. DADSM OBTAIN SEARCH Return Codes 40
11. DADSM OBTAIN SEEK Return Codes .
12. DADSM PARTREL Return Codes .
14. DADSM CREATE Return Codes .
15. CVAF Parameter List - ICVAFPL .
16. CVFCTN Field of CVPL—Contents and
17. Format of a Buffer List Header .
18. Format of a Buffer List Entry.
19. Format of ICVEDT02 Mapping Macro.
20. Format of a Filter Criteria List Header .
21. Format of a Filter Criteria List Entry .
26. RENAME Parameter List generated by
27. DADSM RENAME Return Codes .
31. Summary of the differences between EXCP,
32. Storage area locations for CCW channel program components .
33. Storage area locations for zHPF channel program components .
34. Comparing CCW and zHPF channel programs .
35. Maximum Number of IDAWs for CCW byte-counts .
37. Bits that EXCP uses in DCBIFLGS after the
38. DCB bits to signify presence of DCBE 203
43. Entry Points, Returns, and Available Work
44. Registers and Their Use for Converting
© Copyright IBM Corp. 1979, 2017
45. Relative to Actual Conversion Routine Return
46. Registers and Their Use for Converting
47. Actual to Relative Conversion Routine Return
48. Registers and Their Use for A Sector Convert
49. Channel Program Command Words Used by
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 274
56. Output from DEVTYPE Macro .
57. Output from DEVTYPE Macro — DASD
58. Return Codes from the RDJFCB Macro 290
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 357
66. Installing or Replacing the DESERV Exit 369
67. DESERV Screen Table Structure .
68. Deleting the DESERV Exit .
69. Determining If a DESERV Exit Is Active 371
70. DESX Structure Mapping DESERV Exit
71. Structure of DESP for DESERV GET
76. Directory Entry Name Section .
77. Directory Entry Notelist Section (PDS Only) 378
78. Directory Entry Token Section .
79. Directory Entry Primary Name Section 379
80. Directory Entry Name Section .
81. LSLoader Attributes Unique to Program
82. Attributes Unique to Load Modules (PDS only) .
83. Alias in Unformatted Form .
ix
86. DESERV DELETE DESP Fields .
87. DESERV RENAME DESP Fields .
88. DESERV UPDATE DESP Fields .
89. Return and Reason Codes for the Exit
90. BPX1PCT - Return Codes and Reason Codes 415
91. Structure for the DisplayBufferLimits and
92. Structure for the DisplayGlobalStats
93. Structure for the DisplayFSStats Command
94. Structure for the ExtendFS Command
95. Constants for Extend Units Supported 419
96. Partial Listing of DEB Fields .
100. UCS5 Image Table Contents.
101. UCS6 Image Table Contents.
102. 3262 Model 5 Print Bands .
x
z/OS DFSMSdfp Advanced Services
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
IBM High Level Assembler/MVS & VM & VSE Programmer's Guide
IBM High Level Assembler/MVS & VM & VSE Language Reference z/OS MVS Programming: Assembler Services Guide z/OS MVS Programming: Assembler Services Reference ABE-HSP z/OS MVS Programming: Authorized Assembler Services Guide z/OS MVS Programming: Authorized Assembler Services Reference
ALE-DYN z/OS MVS Programming: Authorized Assembler Services Reference
EDT-IXG z/OS MVS Programming: Authorized Assembler Services Reference
LLA-SDU z/OS MVS Programming: Authorized Assembler Services Reference
SET-WTO z/OS MVS Planning: Global Resource Serialization z/OS MVS Program Management: User's Guide and Reference z/OS MVS Program Management: Advanced Facilities z/Architecture Principles of Operation
© Copyright IBM Corp. 1979, 2017
Order Number
SC26-4941
SC26-4940
SA23-1368
SA23-1369
SA23-1371
SA23-1372
SA23-1373
SA23-1374
SA23-1375
SA23-1389
SA23-1393
SA23-1392
SA22-7832
xi
Table 1. Referenced Publications (continued)
Publication Title
IBM 2821 Control Unit Component Description
IBM 3203 Printer Component Description and Operator's Guide
IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and 3811 Printer
Control Unit Component Description and Operator's Guide
IBM 3262 Model 5 Printer Product Description
IBM 3800 Printing Subsystem Programmer's Guide
IBM 3800 Printing Subsystem Model 3 Programmer's Guide:
Compatibility
IBM 3800 Printing Subsystem Models 3 and 8 Programmer's Guide
3900 Advanced Function Printer Product Description
IBM 4245 Printer Model 1 Component Description and Operator's Guide
IBM 4248 Printer Model 1 Description
IBM 6262 Printer Model 014 Product Description
IBM 6262 Printer Model 014 User's Guide
IBM 6262 Printer Print Band Manual
Device Support Facilities (ICKDSF) User's Guide and Reference z/OS MVS JCL Reference z/OS MVS JCL User's Guide z/OS JES2 Initialization and Tuning Guide z/OS JES3 Initialization and Tuning Guide z/OS DFSMS Access Method Services Commands z/OS DFSMSdfp Diagnosis z/OS DFSMS Installation Exits z/OS DFSMS Macro Instructions for Data Sets z/OS DFSMS Using Data Sets z/OS DFSMS Using Magnetic Tapes z/OS DFSMSdfp Utilities z/OS DFSMS Implementing System-Managed Storage z/OS MVS Initialization and Tuning Guide z/OS HCD Planning z/OS Security Server RACF Security Administrator's Guide 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)
xii
z/OS DFSMSdfp Advanced Services
Order Number
GA24-3312
GA33-1515
GA24-3543
GA24-3936
GC26-3846
SH35-0051
SC23-6864
SC23-6849
SA23-1379
GA32-0907
SA23-2289
SA38-0668
SA38-0669
SA38-0670
SA38-0671
SA38-0672
SA38-0673
SA38-0674
SA38-0675
SA38-0676
SH35-0061
GA32-0135
GA33-1541
GA24-3927
GA24-4134
GA24-4132
GA24-4131
GC35-0033
SA23-1385
SA23-1386
SA32-0991
SA32-1003
SC23-6846
SC23-6863
SC23-6850
SC23-6852
SC23-6855
SC23-6858
Table 1. Referenced Publications (continued)
Publication Title
z/OS MVS System Messages, Vol 10 (IXC-IZP) z/OS TSO/E Command Reference
Order Number
SA38-0677
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.
►► KEYWORD
(1)
►◄
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.
v
Changed
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
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 [email protected].
v
Send an email from the Contact z/OS web page (www.ibm.com/systems/z/os/ zos/webqs.html).
Include the following information: v Your name and address v Your email address v Your phone or fax number v The publication title and order number: z/OS 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
1
Record
2
Record
3
Record
1
Record
2
Record
3
Figure 1. Locating the volume table of contents
VTOC Data Set
(Can be located after cylinder 0, track 0.)
© Copyright IBM Corp. 1979, 2017
1
Using the VTOC
The VTOC is composed of 140-byte
1 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)
IOBFLAG1
4(4)
IOBECBCC
8(8)
1(1)
IOBFLAG2
2(2)
IOBSENS0
IOBECBPB
3(3)
IOBSENS1
IOBFLAG3 and IOBCSW - format depends on channel program.
See related figures below.
All
Devices
16(10)
IOBSIOCC
20(14)
IOBFLAG4
24(18)
IOBRESTR
28(1C)
IOBINCAM
IOBSTRTB
IOBDCBPT
IOBRESTR+1
IOBERRCT
32(20)
IOBSEEK
(first byte, M)
Direct Access, Teleprocessing, and Graphic Devices
33(21)
IOBSEEK
(second through eight bytes,
BBCCHHR)
Direct
Access
Storage
Devices
(DASD)
39(27)
Figure 2. Contents of VTOC - DSCBs Describing Data Sets on Volume That Has No VTOC Index
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
Format-4 DSCB Format-5 DSCB
Description of device, volume, and the VTOC extent
Dummy
Format-5
DSCB
Format-7 DSCB
Description of up to 16 available extents
Data Set W
Format-1 DSCB
Description of data set W and its first
3 extents
Format-3 DSCB
Description of the 4th - 16th extents of data set W
Format-3 DSCB
Description of the
17th - 29th extents of data set W. It may have less than 29 extents.
Data Set Y
Format-1 DSCB
Description of data set Y and its first 3 extents
Format-3 DSCB
Description of the 4th - 16th extents of data set X
Data Set Z
Format-1 DSCB
Description of data set Z and its first
3 extents
Format-9 DSCB
Pointer to
Format-3 DSCB for data set X
Data Set X
Format-8 DSCB
Description of data set X and its first 3 extents
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 DSECT
IECSDSL1 1
F3AREA 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 Name Description
0(X'0')
44(X'2C')
45(X'2D')
51(X'33')
53(X'35')
56(X'38')
59(X'3B')
60(X'3C')
61(X'3D')
Character
Character
Character
Unsigned
Character
Character
Unsigned
Unsigned
Bitstring
1 . . . . . . .
. 1 . . . . . .
. . 1 . . . . .
. . . 1 . . . .
. . . . 1 . . .
. . . . . 1 . .
. . . . . .11
6
2
3
44
1
3
1
1
1
DS1DSNAM
DS1FMTID
DS1IDC
DS8IDC
DS1DSSN
DS1VOLSQ
DS1CREDT
DS1EXPDT
DS1NOEPV
DS1NOBDB
DS1FLAG1
DS1COMPR
DS1CPOIT
DS1EXPBY
DS1RECAL
DS1LARGE
DS1ENCRP
DS1EATTR
DS1SYSCD
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.
v If 3, Not Used, EATTR treated as not specified.
System code.
62(X'3E') Character
6
z/OS DFSMSdfp Advanced Services
13
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 Name Description
75(X'4B')
78(X'4E')
79(X'4F')
79(X'4F')
80(X'50')
82(X'52')
Character
Bitstring
1 . . . . . . .
. 1 . . . . . .
. . 1 . . . . .
. . . 1 . . . .
. . . . 1 . . .
. . . . . 1 . .
. . . . . . 1 .
. . . . . . . 1
Character
Bitstring
1 . . . . . . .
. 1 . . . . . .
. . 1 . . . . .
. . . 1 . . . .
. . . . 1 . . .
. . . . . 1 . .
Unsigned
Bitstring
1000 000x
0100 000x
0010 000x
0001 000x
. . . . xx . .
0000 001x
. . . . . . . 1
3
1
3
1
2
2
DS1REFD
DS1SMSFG
DS1SMSDS
DS1SMSUC
DS1REBLK
DS1CRSDB
DS1PDSE
DS1STRP
DS1PDSEX
DS1DSAE
DS1SCEXT
DS1SCXTF
DS1SCAVB
DS1SCMB
DS1SCKB
DS1SCUB
DS1SCCP1
DS1SCCP2
DS1SCXTV
DS1DSORG
First byte of
DS1DSORG
DS1DSGIS
DS1DSGPS
DS1DSGDA
DS1DSGCX
DS1DSGPO
DS1DSGU
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)
Type or Bit
Mask Length Name Description
84(X'54')
85(X'55')
100x 00xx
010x 00xx
001x 00xx
000x 10xx
000x 10xx
000x 01xx
. . . x . . xx
Character
10 . . . . . .
01 . . . . . .
11 . . . . . .
. . 1 . . . . .
. . . 1 . . . .
. . . . 1 . . .
. . . . . 00 .
. . . . . 10 .
. . . . . 01 .
. . . . . 11 .
. . . . . . . x
Character
1
1
Second byte of
DS1DSORG
DS1DSGGS
DS1DSGTX
DS1DSGTQ
DS1ACBM
DS1ORGAM
DS1DSGTR
DS1RECFM
DS1RECFF
DS1RECFV
DS1RECFU
DS1RECFT
DS1RECFB
DS1RECFS
DS1RECFA
DS1RECMC
DS1OPTCD
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 . . . . . .
. . 1 . . . . .
Track overflow.
Extended search.
. . . 1 . . . .
. . . . 1 . . .
. . . . . 1 . .
. . . . . . 1 .
. . . . . . . 1
Feedback.
Actual addressing.
Dynamic buffering.
Read exclusive.
Relative block addressing.
ISAM OPTCD field assignments (applies only if DS1DSGIS is on):
1 . . . . . . .
Write validity check.
. 1 . . . . . .
. . 1 . . . . .
Accumulate track index entry.
Master indices.
. . . 1 . . . .
. . . . 1 . . .
. . . . . 1 . .
. . . . . . 1 .
. . . . . . . 1
Independent overflow area.
Cylinder overflow area.
Reserved.
Delete option.
Reorganization criteria.
BPAM, BSAM, QSAM OPTCD field assignments (applies only if DS1DSGPO or DS1DSGPS is on):
1 . . . . . . .
Write validity check.
. 1 . . . . . .
. . 1 . . . . .
Allow data check (if on printer).
Chained scheduling.
. . . 1 . . . .
. . . . 1 . . .
VSE/MVS interchange feature on tape.
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 Length Name Description
85(X'55')
. . . . . 1 . .
. . . . . . 1 .
. . . . . . . 1
Bitstring 1 DS1OPTAM
Search direct.
User label totaling.
Each record contains a table reference character.
VSAM OPTCD settings.
VSAM OPTCD field assignments (applies only if DS1ORGAM is on):
1 . . . . . . .
Reserved.
. 1 . . . . . .
. . xx xxxx
DS1OPTBC Data set is an integrated catalog facility catalog.
Reserved.
86(X'56')
88(X'58')
Binary
Binary
2
2
DS1BLKL
DS1LRECL
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'.
90(X'5A')
91(X'5B')
93(X'5D')
Binary
Binary
Character
1 . . . . . . .
. 1 . . . . . .
. . 1 . . . . .
. . . 1 . . . .
. . . . 1 . . .
. . . . . 1 . .
. . . . . . 1 .
1
2
1
DS1KEYL
DS1RKP
DS1DSIND
DS1IND80
DS1IND40
DS1IND20
DS1IND10
DS1IND08
DS1IND04
DS1IND02
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.
94(X'5E')
94(X'5E')
95(X'5F')
. . . . . . . 1
Binary
Character xxxx xxxx
00 . 0 . . . .
00 . 1 . . . .
11 . . . . . .
10 . . . . . .
01 . . . . . x
01 . . . . . 1
. . 1 . . . . .
. . . . 1 . . .
. . . . . 1 . .
. . . . . . 1 .
. . . . . . . 1
Binary
4
1
3
-
DS1DSCHA
DS1IND01
DS1CHKPT
DS1SCALO
DS1SCAL1
DS1DSPAC
DS1DSABS
DS1EXT
DS1CYL
DS1TRK
DS1AVR
DS1AVRND
DS1MSGP
DS1CONTG
DS1MXIG
DS1ALX
DS1SCAL3
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 Name Description
98(X'62') Binary 3 DS1LSTAR
101(X'65')
103(X'67')
104(X'68')
105(X'69')
105(X'69')
115(X'73')
125(X'7D')
135(X'87')
140(X'8C')
Binary
Character
Character
Character
Character
Character
X'81'
X'80'
X'40'
X'04'
X'02'
X'01'
X'00'
Character
Character
Character
Character
2
1
1
30
10
1
1
4
4
10
10
5
DS1TRBAL
DS1TTTHI
DS1EXNTS
DS1EXT1
DS1EXT2
DS1EXT3
DS1PTRDS
DS1END
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.
28-31
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.
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) Type Length Name Description
0(X'00')
4(X'04')
44(X'2C')
45(X'2D')
135(X'87')
140(X'8C')
Bitstring
Bitstring
Character
Bitstring
Bitstring
4
1
1
4
4
40
1
90
5
-
DS3EXTNT
DS3FMTID
DS3IDC
DS3ADEXT
DS3PTRDS
DS3END
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
Chapter 1. Using the Volume Table of Contents
11
Using the VTOC
Table 4. DSCB Format-4
Offset Dec
(Hex) Type
0(X'00')
1(X'01')
6(X'06')
8(X'08')
12(X'0C')
14(X'0E')
Character
Character
Unsigned
Character
Unsigned
Bitstring
1 . . . . . . .
. 1 . . . . . .
. . 1 . . . . .
15(X'0F')
16(X'10')
17(X'11')
18(X'12')
18(X'12')
18(X'12')
20(X'14')
22(X'16')
24(X'18')
24(X'18')
25(X'19')
26(X'1A')
27(X'1B')
. . . 1 . . . .
. . . . 1 . . .
. . . . . 1 . .
. . . . . . 1 .
. . . . . . . 1
Unsigned
Bitstring
00 . . . . . .
01 . . . . . .
10 . . . . . .
11 . . . . . .
11 . . . . . .
. . xx xxxx
Binary
Character
Character
Binary
Binary
Unsigned
Binary
Binary
Binary
Binary
Bitstring
. . . 1 . . . .
12
z/OS DFSMSdfp Advanced Services
1
1
1
2
1
2
2
1
1
4
2
4
2
5
2
1
Length Name
1 DS4IDFMT
DS4IDC
DS4HPCHR
DS4DSREC
DS4HCCHH
DS4NOATK
DS4VTOCI
DS4DOSBT
DS4DVTOC
DS4EFVLD
1
14
DS4DSTKP
DS4DOCVT
DS4DIRF
DS4DICVT
DS4IVTOC
DS4NOEXT
DS4SMSFG
DS4NTSMS
DS4SMSCV
DS4SMS
DS4SMSTS
DS4DEVAC
DS4DEVCT
DS4DEVSZ
DS4DSCYL
DS4DSTRK
DS4DEVTK
DS4DEVOV
DS4DEVI
DS4DEVL
DS4DEVK
DS4DEVFG
DS4DEVAV
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 . .
28(X'1C')
30(X'1E')
31(X'1F')
32(X'20')
40(X'28')
40(X'28')
. . . . . . 1 .
. . . . . . . 1 xxx. . . . .
Binary
Binary
Binary
Binary
Character
Bitstring
1 . . . . . . .
. 1 . . . . . .
2
1
1
8
3
1
DS4DEVTL
DS4DEVDT
DS4DEVDB
DS4AMTIM
DS4AMCAT
DS4VSIND
DS4VSREF
DS4VSBAD
41(X'29')
43(X'2B')
51(X'33')
56(X'38')
61(X'3D')
71(X'47')
81(X'51')
82(X'52')
87(X'57')
88(X'58')
92(X'5C')
. .1 . . . . .
. .1 . . . . .
. . .x xxxx
Unsigned
Binary
Character
Character
Character
Character
Character
Character
Character
Character
Character
5
1
4
2
10
10
1
5
5
2
8
DS4VVDSA
DS4VVDSR
DS4VSCRA
DS4R2TIM
DS4F6PTR
DS4VTOCE
Reserved.
DS4EFLVL
DS4EFPTR
DS4MCU
DS4DCYL
DS4LCYL
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) Type Length Name
94(X'5E') Character
1... ....
1 DS4DEVF2
DS4CYLMG
95(X'5F')
96(X'60')
.1.. ....
..xx
xxxx
1
DS4EADSCB
DS4END
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) Type Length Name Description
0(X'00')
4(X'04')
9(X'09')
44(X'2C')
45(X'2D')
135(X'87')
140(X'8C')
Bitstring
Bitstring
Bitstring
Character
Bitstring
Bitstring
2
1
35
1
90
5
4
5
2
DS5KEYID
DS5AVEXT
DS5EXTAV
DS5FMTID
DS5MAVET
DS5PTRDS
DS5END
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
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
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)
0 (X'00')
Type
Character
Length Name
1
Description
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 . . . . . . .
1 DS9FLAG1
DS9CREAT
Format 9 DSCB flag byte 1.
Format 9 DSCB built by create.
4 (X'04')
12 (X'0C')
20 (X'14')
Character
Character
Bytes
8
8
6
DS9JOBNAME Job name used to create the data set on the current volume. Valid only when DS9CREAT is on (see offset 3 (X'03')).
DS9STEPNAME Step name used to create the data set on the current volume. Valid only when DS9CREAT is on
(see offset 3 (X'03')).
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')
44 (X'2C')
45 (X'2D')
46 (X'2E')
Character
Character
Binary
Binary
18
1
1
50
The following five bytes occur ten times.
46 (X'2E') Binary 5
*
DS9FMTID
DS9IDC
DS9NUMF3
DS9F3
DS9F3P
Reserved.
Format identifier.
Constant value of X'F9' in DS9FMTID.
Number of format 3 pointers that follow
Pointers to first to tenth format-3 DSCBs
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 (X'2E')
48 (X'30')
50 (X'32')
96 (X'60')
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
116 (X'74') Character 19 DS9ATRI2
End of the fields that are unique to the format 9 subtype 1 DSCB.
Attribute fields, for future IBM definition
135 (X'87')
135 (X'87')
138 (X'89')
140 (X'8B')
140 (X'8C')
Bitstring
Binary
Binary
Binary
5
2
2
1
DS9PTRDS
DS9CCPTR
DS9HHPTR
DS9RPTR
DS9END
Pointer (CCHHR) to next format-9 DSCB, the first format-3 DSCB or zero.
Cylinder number in DSCB pointer
Track number in DSCB pointer
Record number in DSCB pointer
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 ....
.... xxxx
Reserved
Number of bytes that follow this two-byte header.
Minimum value is 0000.
1 (X'1')
2 (X'2')
Character
Character
1 One-byte field containing a vendor identification issued by IBM.
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.V
volser 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
┌────────────────────────────┐
³ Format─4 DSCB ³
├────────────────────────────┤
³
³
³
³
³ Format─5 DSCB ³
├────────────────────────────┤
Other DSCBs
³
³
³
³
├────────────────────────────┤ ³
³ Format─1 DSCB for the VTOC ├─────┘
³ Index: SYS1.VTOCIX.nnn
³
├────────────────────────────┤
³
³ Other DSCBs
³
³
³ ³
!────────────────────────────┘
³
³
³
³
³
³
³
³
VTOC Index
┌────→┌─────────────────────────┐
³ VIXM ³
├─────────────────────────┤
³ VPSM ³
├─────────────────────────┤
³ VMDS ³
├─────────────────────────┤
³ VIER ³
├─────────────────────────┤
³
³
³
³
VIER
VIER
.
.
³
├─────────────────────────┤
³
├─────────────────────────┤
³
³
³ .
³
!─────────────────────────┘
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
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:
► ►►
label
LSPACE
MF = I
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
NONE
►
,ENQHELD= YES
NO
,F4DSCB=
addr
(reg)
0
ALL
,DATATYPE= FRAGINDEX
INDEX
VOLUME
VTOC
IMPLIED_VERSION
,PLISTVER=
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:
►►
►
label
LSPACE
,MSG=
addr
(reg)
0
,EXPMSG=
addr
(reg)
0
,DATA=
addr
(reg)
0
,XEXPMSG=
addr
(reg)
0
,EXPDATA=
addr
(reg)
0
►
,F4DSCB=
addr
(reg)
0
MF= (E,addr)
(E,(reg))
,SMF= TEST
YES
NONE
,DATATYPE=
ALL
,UCB=
addr
(reg)
,ENQHELD= YES
NO
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
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
Specifies that you do not want the free space and volume information.
24
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:
► ►►
label
LSPACE MF= 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
ALL
,DATATYPE= FRAGINDEX
INDEX
VOLUME
VTOC
,TIMEOUT=
value
IMPLIED_VERSION
,PLISTVER=
plistver
MAX
►
►◄
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:
►◄ ►►
label
LSPACE test MF= 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
(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 Offset Bytes Description
LSPAPL
LSPAPLID
LSPANGTH
LSPAFLAG
LSPASMFY
LSPASMFT
LSPADATA
LSPAMSG
LSPAEMSG
0(X'00')
4(X'04')
6(X'06')
4
2
1
10 . . . . . .
01 . . . . . .
. . 1 0 0 . . .
. . 0 1 0 . . .
. . 0 0 1 . . .
EBCDIC 'LSPA'.
Length of parameter list.
Parameter flag byte.
SMF=YES.
SMF=TEST.
Free space data request.
Message data returned.
Expanded message data requested.
30
z/OS DFSMSdfp Advanced Services
Using the VTOC
Table 7. Format of the LSPACE Parameter List (MF=D) (continued)
Name Offset Bytes Description
LSPAEPLP
LSPAXINF
LSPAFRES
LSPAXTIM
LSPAERCD
LSPASFID
LSPASFPC
LSPASF01
LSPASF02
LSPASF06
LSPASF07
LSPASF08
LSPASF86
LSPASFRT
LSPASFRS
LSPARS01
LSPARS02
LSPARS03
LSPARS04
LSPARS05
LSPARS06
LSPARS07
LSPARS08
LSPARS09
LSPASF09
LSPASF0A
LSPASF0B
LSPASF0C
LSPASF0D
LSPASF0E
LSPASF4X
LSPASFEX
LSPASFF0
LSPASFVR
LSPASFVD
LSPASF85
LSPARS0A
LSPARS0B
7(X'07')
8(X'08')
9(X'09')
10(X'0A')
11(X'0B')
. . 0 0 0 1 . .
. . 0 0 0 0 1 .
. . . . . . . x
1
1
1
X'00'
X'01'
X'02'
X'06'
X'07'
X'08'
X'09'
X'0A'
X'0B'
X'0C'
X'0D'
X'0E'
X'80'
X'81'
X'82'
X'83'
X'84'
X'85'
X'86'
1
1
X'01'
X'02'
X'03'
X'04'
X'05'
X'06'
X'07'
X'08'
X'09'
X'0A'
X'0B'
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.
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
LSPARS0D
LSPARS0E
X'0C'
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
LSPARS11
X'0F'
X'10'
X'11'
LSPARS12
LSPARS13
LSPARS14
LSPARS15
LSPAUCB
LSPAFRSP
LSPAFMT4
LSPAEXPL
LSPAFLAG2
LSPAXMSG
LSPAEDAT
*
X'12'
X'13'
The next five flags pertain to the DATATYPE keyword values.:
LSPAFRSI ...1 ....
LSPAFRVT
LSPAFRVX
LSPAFRFI
LSPAFALL
LSPAFLAG3
LSPAENQH
LSPATIMS
LSPARSV2
LSPARES2
LSPATIMV
LSPARES3
12(X'0C')
16(X'10')
20(X'14')
24 (X'18')
25 (X'19')
25 (X'19')
26 (X'1A')
28(X'1C')
32(x'20')
X'14'
X'15'
4
4
4
24
1
1... ....
.1.. ....
..x. ....
.... 1...
.... .1..
.... ..1.
.... ...1
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 statistics from the entire volume:
aaaa bbbb
= Total number of free cylinders
= Total number of additional free tracks
cccc dddd eeee
= 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 statistics from the entire volume:
aaaaaa
= Total number of free cylinders
bbbbbb
= Total number of additional free tracks
cccccc
= Total number of free extents
dddddd = Number of cylinders in largest free extent
eeeeee
= 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 statistics from the entire volume:
aaaaaaaaa
= Total number of free cylinders
bbbbbbbbbb
= Total number of additional free tracks
cccccccccc
= Total number of free extents
ddddddddd
= Number of cylinders in largest free extent
ee
= 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 Description
LSPDRETN
LSPDSPAC
LSPDF0CN
LSPDVRCN
LSPDFRGI
LSPDCYLM
LSPDRRES
LSPDSTAT
LSPDIXDS
LSPDIXAC
LSPDSRES
LSPDRSV1
0(X'00')
1(X'01')
2(X'02')
1
1 . . . . . . .
. 1 . . . . . .
. . 1 . . . . .
. . . 1 . . . .
. . . . 1 . . .
. . . . . x x x
1
1 . . . . . . .
. 1 . . . . . .
. . x x x 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
LSPDVFRG
36(X'24')
36(X'24')
40(X'28')
44(X'2C'
48(X'30')
52(X'34')
56(X'38')
4
4
4
24
4
4
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
60(X'3C')
60(X'3C')
64(X'40'
LSPDRSV8 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
►
NOTOK
EADSCB= OK
NOQUEUE=OK
NUMBERDSCB=number_dscbs
►
►◄
Chapter 1. Using the Volume Table of Contents
37
Using the VTOC
►►
listname
CAMLST SEARCH ,dsname_relexp ,vol_relexp ,wkarea_relexp
►
NUMBERDSCB=number_dscbs NOTOK
EADSCB= 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 READ DSCB FOR DATA
SET A.B.C INTO DATA
AREA NAMED WORKAREA
DSCBABC CAMLST
DSABC DC
VOLNUM DC
WORKAREA DS
SEARCH,DSABC,VOLNUM,WORKAREA
CL44’A.B.C’ DATA SET NAME
CL6’770655’
140C
VOLUME SERIAL NUMBER
140-BYTE WORK AREA
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')
12(X'0C')
16(X'10')
24(X'18')
28(X'1C')
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.
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
►
NOTOK
EADSCB= OK
NOQUEUE=OK
NUMBERDSCB=number_dscbs
►
►◄
40
z/OS DFSMSdfp Advanced Services
Using the VTOC
►►
listname
CAMLST SEEK ,cchhr_relexp ,vol_relexp ,wkarea_relexp
►
NUMBERDSCB=number_dscbs NOTOK
EADSCB= 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 READ DSCB FROM
LOCATION SHOWN IN CCHHR
INTO STORAGE AT LOCATION
NAMED READAREA
ACTADDR CAMLST SEEK,CCHHR,VOLSER,READAREA
CCHHR DC XL5’0000000107’ ABSOLUTE TRACK ADDRESS
VOLSER DC
READAREA DS
CL6’108745’
140C
VOLUME SERIAL NUMBER
140-BYTE WORK AREA
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
Return Codes from OBTAIN (Reading by Absolute Device
Address)
Table 11. DADSM OBTAIN SEEK Return Codes
Return Code Description
0(X'00') Successful completion of OBTAIN routine.
42
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')
16(X'10')
20(X'14')
24(X'18')
28(X'1C')
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.
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:
►►
label
PARTREL MF= (E,address)
(E,(reg)) ,DSN=
addr
(reg)
►
TEST
,ERASE= YES
NO
►
,VSAMTYPE= KSDS
RRDS
LDS
VRRDS
►
,VSAMSEC= BYPASS
NOBYPASS
PGM
,MODE= SUP
,VSAMFMT=
,VSAMTRKS=
EXTD
STD
ENQ
,TIOT= NOENQ
addr
(reg)
,VSAMCLLR=
,UCB= (reg)
VSAMCLSE
NOTVSAM
►
►◄
►
►
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 TEST
,ERASE= YES
NO
►
,TIOT=
ENQ
NOENQ
►
,VSAMCLLR= VSAMCLSE
NOTVSAM
,VSAMTYPE= KSDS
RRDS
LDS
VRRDS
,VSAMSEC= BYPASS
,VSAMFMT= EXTD
STD
NOBYPASS
,VSAMTRKS=addr
PGM
,MODE= SUP
►
►◄
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:
►►
label
PARTREL MF=D ►◄
Description:
The following example provides a description of the parameter list:
++PRLPLID DS
+PRLNGTH DS
+PRERRCDE DS
+*
CL4
AL2
H
EBCDIC ’PREL’ FOR PARTREL
LENGTH OF PARAMETER LIST
ERROR CODE RETURNED FROM
PARTIAL RELEASE
+PRLFLAG DS XL1 PARAMETER FLAG BYTE
+PRLPGM EQU X’00’ MODE=PGM (PROBLEM PROGRAM)
+PRLSUP EQU X’80’ MODE=SUP (SUPERVISOR STATE)
+PRLTIOT EQU X’40’ TIOT=NOENQ
+PRLNERAS EQU X’20’ ERASE=NO
+PRLERASE EQU X’10’ ERASE=YES
+PRLVCLOS EQU X’08’
+PRLVCNV EQU X’04’
VSAMCLLR=VSAMCLSE
VSAMCLLR=NOTVSAM
+PRLBYPS EQU X’02’
+PRLNBYPS EQU X’01’
+PRLFLAG2 DS XL1
+PRLVKSDS EQU X’80’
VSAMSEC=BYPASS
VSAMSEC=NOBYPASS
+PRLVESDS EQU X’40’
+PRLVRRDS EQU X’20’
+PRLVVRRD EQU X’10’
+PRLVLDS EQU X’08’
VSAMTYPE=KSDS
VSAMTYPE=ESDS
VSAMTYPE=RRDS
VSAMTYPE=VRRDS
+PRLEXTD
+PRLSTD
EQU X’04’
EQU X’02’
+PRLTIOTX EQU X’01’
+PRLRSVD DS XL2
VSAMTYPE=LDS
VSAMFMT=EXTD
VSAMFMT=STD
No ENQ TEST when TIOT=NOENQ is specified
+PRLDSN
+PRLUCB
+PRLTRKS
DS A
DS A
DS A
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
+PRLCTGR DS F
+PRLEND EQU *
(ONLY VALID FOR VSAM REQUESTS)
CATALOG REASON CODE
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')
12(X'0C')
16(X'10')
20(X'14')
24(X'18')
28(X'1C')
32(X'20')
36(X'24')
40(X'28')
44(X'2C')
48(X'30')
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: v A permanent I/O error occurred.
v CVAF provided an unexpected return code.
v An installation exit rejected the request.
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.
48
z/OS DFSMSdfp Advanced Services
Using the VTOC
Table 12. DADSM PARTREL Return Codes (continued)
Return Code Description
52(X'34')
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')
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.
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:
► ►►
label
REALLOC
►
,DSSIZE=
addr
(reg)
►
►
,MINAU=
addr
,PDSDIR=
(reg)
addr
(reg)
MF= (E,addr)
(E,(reg)) MOV
,ALLOC= ABS
NON
,F3DSCB=
addr
(reg)
,NUMF9=
number_dscbs
(reg)
,UCB= (reg)
,F9DSCB=
addr
(reg)
,PDSCB=
addr
(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.
►►
label
REALLOC MF=L
MOV
,ALLOC= ABS
►
,F9DSCB=
addr
(reg)
,NUMF9=
number_dscbs
(reg)
,F3DSCB=addr
,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:
►►
label
REALLOC MF=D ►◄
REALLOC Parameter List
The parameter list for the DSECT form expansion is:
Table 13. REALLOC Parameter List
Offset Length or
Bit Pattern
Field Name
0(X'00')
0(X'00')
4(X'04')
6(X'06')
8(X'08')
9(X'09')
4
2
2
1
1... ....
.1.. ....
1
REALPL
RALPLID
RALNGTH
RAERRCDE
RALFLAG
RALABS
RALVTOCE
RALPFLGS
Description
DSECT name.
EBCDIC "REAL" for "REALLOC"
Length of parameter list
Error code from DADSM create
Flag byte
0 means ALLOC=MOV. 1 means ALLOC=ABS.
VTOCENQD=YES
Processing flag byte.
54
z/OS DFSMSdfp Advanced Services
Using the VTOC
Table 13. REALLOC Parameter List (continued)
Offset Length or
Bit Pattern
1... ....
Field Name
RALDUMMY
Description
10(X'0A')
11(X'0B')
12(X'0C')
16(X'10')
20(X'14')
24(X'18')
28(X'1C')
32(X'20')
32(X'20')
36(X'24')
40(X'28')
.1.. ....
..1. ....
1
4
4
4
1
4
4
4
...1 11..
.... ..11
4
4
0
40
RALTRKAL
RALEXREQ
*
RALEATTR
RALNUMF9
RALDSSZ
RALMAU
RALPDSCB
RALUCB
RALDQTY
RAL2DSCB
RAL9DSCB
RAL3DSCB
RALEND
RALENGTH
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.
Space must be allocated from track-managed space.
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.
Reserved.
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.
Number of contiguous partial format 9 DSCBs that are located at the address in bytes 32-35. The default is one.
Reserved
Data set size
Minimum allocation unit
Address of partial DSCB
Address of UCB
PDS directory quantity
Address of format 2 DSCB. Mutually exclusive with 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.
Address of format 3 DSCB
Byte after end of list
Symbolic length of parameter list
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
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.
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')
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')
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')
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.
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')
200(X'C8')
204(X'CC')
208(X'D0')
212(X'D4')
216(X'D8')
217(X'D9')
220(X'DC')
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.
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
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
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
0(X'00')
0(X'00')
4(X'04')
6(X'06')
7(X'07')
8(X'08')
Type Length
STRUCTURE 100
CHARACTER 4
SIGNED
BIT(8)
2
1
1
1
UNSIGNED
BIT(8)
1... ....
.1.. ....
..1. ....
...1 ....
.... 1...
.... .111
.... .1..
Name
CVPL
CVLBL
CVLTH
CVFCTN
CVSTAT
CVFL1
CV1IVT
CV1IOAR
CV1PGM
CV1MRCDS
CV1IRCDS
CV1MAP
CV1MAPIX
Description
CVAF parameter list
EBCDIC 'CVPL'
Length of CVPL
Function byte (see values below)
Status information (see values below)
First flag byte
Indexed VTOC accessed
IOAREA=KEEP
BRANCH=(YES,PGM)
MAPRCDS=YES
IXRCDS=KEEP
Map bits (see next three bits)
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')
Type
.... ..1.
.... ...1
BIT(8)
1... ....
.1.. ....
..1. ....
...1 ....
.... 1...
.... .1..
.... ..1.
.... ...1
Length
1
Name
CV1MAPVT
CV1MAPVL
CVFL2
CV2HIVIE
CV2VRF
CV2CNT
CV2RCVR
CV2SRCH
CV2DSNLY
CV2VER
CV2NLEVL
Description
MAP=VTOC
MAP=VOLUME
Second flag byte
HIVIER=YES
VRF data exists
COUNT=YES
RECOVER=YES
SEARCH=YES
DSNONLY=YES
VERIFY=YES
Output - new highest level VIER created
|
||
10(X'0A')
11(X'0B')
12(X'0C')
16(X'10')
16(X'10')
20(X'14')
24(X'18')
28(X'1C')
32(X'20')
.... .1..
.... ..1.
.... ...1
BIT(8)
1... ....
.1.. ....
..1. ....
...1 ....
.... 1...
.... .1..
.... ..1.
BIT(8)
1... ....
.1.. ....
..1. ....
...1 ....
.... 1...
.... ...x
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
1
1
4
4
4
4
4
4
4
60
z/OS DFSMSdfp Advanced Services
CVFL3
CV3FILT
CV3IXERR
CV3PTR31
CV3AVT
CV3ENQD
CV3NOPIN
CV3HLIXP
CV3RTA4B
CVFL4
CV4UCBCA
CV4OBTRQ
CV4NMHID
CV4EADOK
CV4MULTD
CV4NOQUE
CV4VALID
CV4RSVD
CVUCB
CVDSN
CVFCL
CVBUFL
CVIRCDS
CVMRCDS
CVIOAR
Third flag byte
FLTAREA=KEEP
Index error found
Address words in CVPL are valid in AMODE
31
Support bypass write inhibit error.
CVAF caller has serialized with another task that has reserved the VTOC
Caller requested no UCBPIN
Higher level IX pruning done
CVAFDSM RTA4BYTE=YES
Fourth flag byte
UCB has been captured
Request came from OBTAIN
Data set name hiding for authorized caller.
EADSCB=OK specified
Processing of multiple DSCBs on CVAFDIR is requested (MULTIPLEDSCBS=YES)
Do not queue the OBTAIN I/O
Validate fields when CVAFDIR
ACCESS=WRITE
Reserved
UCB address
Data set name address
Filter criteria list address
Buffer list address
Index VIR's buffer list pointer
MAP VIR's buffer list pointer
I/O area address
Using the VTOC
Table 15. CVAF Parameter List - ICVAFPL (continued)
Offset
36(X'24')
40(X'28')
44(X'2C')
48(X'30')
52(X'34')
56(X'38')
60(X'3C')
64(X'40')
68(X'44')
72(X'48')
73(X'49')
76(X'4C')
Type
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
UNSIGNED
CHARACTER
CHARACTER
Length
4
4
4
4
4
4
4
4
4
1
4
23
Name
CVDEB
CVARG
CVSPACE
CVEXTS
CVBUFL2
CVVRFDA
CVCTAR
CVFSA
CVCTAR5
CVNMDSCB
CVCLID
*
Description
DEB address
Argument address
Space parameter list address
Extent table address
New VRF VIXM Buffer list pointer
VRF data address
Count area address
Filter save area address
CCHHR AREA RETURN ADDRESS
NUM OF DSCBs
ID of CVAFDIR WRITE caller
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
Table 17. Format of a Buffer List Header
Offset
Length or Bit
Pattern Name Description
0 (X'00')
0 (X'00')
1 (X'01')
2 (X'02')
3 (X'03')
4 (X'04')
1
4
8
1
1 xxxx . . . .
. . . . 1 . . .
. . . . . 1 . .
. . . . . . 1 .
. . . . . . .x
1
BFLHDR
BFLHNOE
BFLHFL
BFLHKEY
BFLHVIR
BFLHDSCB
BFLHWREV
BFLHNOEN
BFLHSP
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.
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
Offset
Length or Bit
Pattern Name Description
0 (X'00')
0 (X'00')
1 (X'01')
2 (X'02')
3 (X'03')
4 (X'04')
4 (X'04')
8 (X'08')
. 1 . . . . . .
3
4
1
5
4
12
1
100 . . . . .
010 . . . . .
001 . . . . .
. . . 1 . . . .
. . . . 1 . . .
. . . . . 1 . .
. . . . . . 1 .
. . . . . . . 1
1
1 . . . . . . .
BFLE
BFLEFL
BFLERBA
BFLECHR
BFLETTR
BFLEAUPD
BFLEMOD
BFLESKIP
BFLEIOER
BFLENOVR
BFLEFLG2
BFLENVER
BFLEVLER
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.
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')
21 (X'15')
24 (X'18')
28 (X'1C')
32 (X'20')
36 (X'24')
-
4
1
1
2
5
3
4
4
4
8
4
4
DT2X7LEN
DT2X7LEV
DT2X7FLG
DT2X7NF0
DT2X7CSR
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.
DT2X7RES
DT2X7RTA
DT2X7RE2
DT2X7ENT
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.
DT2ENTRY One entry for each extent.
DT2RTAST RTA of start of extent
DT2RTAED 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 ─┼──────────────────────────→ FCL───────┐
³ ³
³ CVBUFL─┼──→ BFL───────┐
³ FLCH
³
³
³
³
³
└─────────┘
³
³
³ BFLH
³
³
³
³ BFLE────┴┐
³ ³ ³
³ FCLDSN──┴┐
³ ³ ³
³ ³FCLDSNA─┼─→ DSN
³ └───────┬┘
³ ³BFLEBUF─┼─→ DSCB
³ └───────┬┘ Buffer
³ FCLDSN──┴┐
³ ³ ³
³ BFLE────┴┐
³ ³ ³
³ ³FCLDSNA─┼─→ DSN
³ └───────┬┘
³ ³BFLEBUF─┼─→ DSCB
³ └───────┬┘ Buffer
³
³ ...
³
³
³ ³
³ ...
³
³ ³
³
³ ³
³
³ FCLDSN──┴┐
³
³ BFLE────┴┐
³ ³ ³
³ ³BFLEBUF─┼─→ DSCB
³ └───────┬┘ Buffer
└─────────┘
³ ³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
Table 20. Format of a Filter Criteria List Header
Offset Bytes Name Description
0 (X'00')
4 (X'04')
6 (X'06')
8 (X'08')
9 (X'09')
4
2
FCLID EBCDIC 'FCLbb' (bb here represents a blank.)
FCLCOUNT Number of data set name entries provided in the list.
2
1
FCLDSCBR Number of DSCBs returned.
FCL1FLAG Request flag byte.
1 . . . . . . .
FCL1LIST List contains fully-qualified data set names.
. 1 . . . . . .
FCL1ORDR FCL data set name order requested.
. . 1 . . . . .
FCL1EQF1 Return only format-1 or format-8 DSCBs.
. . . 1 . . . .
FCL1EQF9 Return only format-1 or format-8 and format-9
DSCBs.
. . . . xxxx Reserved.
1 FCL2FLAG Status flag byte.
1 . . . . . . .
FCL2SEQ CVAFFILT executed sequential VTOC access.
. 1 . . . . . .
FCL2SDIR
. . xx xxxx
CVAFFILT executed sequential VTOC access, but did at least one direct DSCB read.
Reserved.
10 (X'0A') 6 FCLDRSV Reserved.
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 Bytes Name Description
0 (X'00')
1 (X'01')
2 (X'02')
3 (X'03')
4 (X'04')
8
1
X'00'
X'01'
X'02'
X'03'
X'04'
X'05'
X'06'
X'07'
1
1
1 . . . . . . .
. xxx xxxx
1
4
FCLDSN
FCLDSNST
FCLDSNLG
FCL3FLAG
FCL3UPDT
FCLDSNRV
FCLDSNA
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.
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 Contents of Buffer
3
4
1
2
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 FCL3UPDT Comments
1 1 DSCBs returned from this call
5
1
1
1
DSCB chain exceeds total buffers
DSCBs returned from this call
0
0
0
0
0
0
DSCBs can be returned by RESUME
DSCBs can be returned by RESUME
DSCBs can be returned by 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 Contents of Buffer
1 Format-1 DSCB, SYS4.D
2
3
4
Format-2 DSCB, SYS4.D
Format-3 DSCB, SYS4.D
Format-1 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
FCLDSNST FCL3UPDT Comments
1 0 DSCBs returned from prior call
5
1
0
0
DSCB chain exceeds total buffers
DSCBs returned from prior call
74
z/OS DFSMSdfp Advanced Services
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
►►
label
CVAFDIR ACCESS= READ
WRITE
RLSE
►
NO
,VERIFY= YES
,UCB= (ucbaddr)
,DEB=addr
,DSN=addr
,IOAREA=
,BUFLIST=addr
NOKEEP
KEEP
(KEEP,addr)
(NOKEEP,addr)
►
NO
,MAPRCDS= YES
(YES,addr)
(NO,addr)
►
NO
(1)
,BRANCH= YES
(YES,SUP)
(YES,PGM)
►
I
,MF= L
(E,addr)
,IXRCDS=
,EADSCB= OK
NOKEEP
KEEP
(KEEP,addr)
(NOKEEP,addr)
NOTOK NO
,MULTIPLEDSCBS= YES
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
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')
4 (X'04')
8 (X'08')
12 (X'0C')
16 (X'10')
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.
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
LA
ST
LR
RSAVE,SAVEAREA+4
RWORK,SAVEAREA
RWORK,8(,RSAVE)
RSAVE,RWORK
*
*
************************************************************
*
REGISTERS
************************************************************
REG1 EQU 1 REGISTER 1
RWORK
RDEB
EQU
EQU
3
4
WORK REGISTER
DEB ADDRESS
RDSN
RSAVE
EQU 5
EQU 13
ADDRESS OF DATA SET NAME
SAVE AREA ADDRESS
REG15 EQU 15 RETURN CODE REGISTER 15
************************************************************
*
* RETURN CODES
*
************************************************************
PDSRTN EQU 0
NOTFND EQU 4
NOTPDS EQU 8
DATA SET A PDS RETURN CODE
DATA SET NOT FOUND RETURN CODE
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
LA RWORK,DS1FMTID
ST RWORK,BFLEBUF
OI BFLEFL,BFLECHR
MVI BFLELTH,DSCBLTH
ONE BUFFER LIST ENTRY
ADDRESS OF DSCB BUFFER
PLACE IN BUFFER LIST
CCHHR OF DSCB RETURNED BY CVAF
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
LTR REG15,REG15
BZ NOERROR
ADDRESSABILITY TO CVPL
ANY ERROR
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
CLI CVSTAT,STAT001
BRANCH IF NOT 4
IS IT DATA SET NAME NOT FOUND?
*
*
BNE OTHERERR
DROP REG1
************************************************************
*
DATA SET NAME NOT FOUND
BRANCH IF NOT
ADDRESSABILITY TO CVPL NOT NEEDED
************************************************************
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
NOTF1
CLI
BE
TM
DS1FMTID,C’4’
NOTF1
DS1DSORG,DS1DSGPO
BO PDS
EQU *
L RSAVE,4(,RSAVE)
IS DSCB A FORMAT 4 DSCB
BRANCH IF YES. NOT A FORMAT 1
IS FORMAT 1 DSCB FOR PARTITIONED
DATA SET
BRANCH IF PDS
DSCB IS NOT A PDS
PDS
RETURN (14,12),RC=NOTPDS SET UP NOT PDS RETURN CODE
EQU * DATA SET IS PARTITIONED
L RSAVE,4(,RSAVE)
RETURN (14,12),RC=PDSRTN SET UP PDS RETURN CODE
OTHERERR EQU
L
*
RSAVE,4(,RSAVE)
UNEXPECTED ERROR
RETURN (14,12),RC=UNEXPECD
ERROR4
BUFLIST
DC F’4’
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
CVPL ICVAFPL ,
SAVE AREA
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 14,12,12(13)
BALR 12,0
USING *,12
ST
LA
ST
LR
13,SAVEAREA+4
RWORK,SAVEAREA
RWORK,8(,13)
13,RWORK
*
************************************************************
*
* REGISTERS
*
************************************************************
*
RWORK
RUCB
RLIST
RDSN
RTTR
REG15
*
EQU 3
EQU 4
EQU 5
EQU 6
EQU 7
EQU 15
WORK REGISTER
UCB ADDRESS SUPPLIED BY CALLER
ADDRESS OF PARAMETER LIST (SUPPLIED)
ADDRESS OF DATA SET NAME
ADDRESS OF TTR
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
TOPLOOP EQU *
XC
OI
ADDRESSABILITY TO PARMLIST
LOOP FOR EACH DSCB
BUFLIST(BFLHLN+BFLELN),BUFLIST ZERO BUFFER LIST
BFLHFL,BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST
MVI BFLHNOE,1
L RWORK,LISTDSCB
ST
OI
RWORK,BFLEBUF
BFLEFL,BFLETTR
MVI BFLELTH,DSCBLTH
ONE BUFFER LIST ENTRY
ADDRESS OF DSCB BUFFER
PLACE IN BUFFER LIST
TTR OF DSCB RETURNED BY CVAF
L RDSN,LISTDSN
DATA PORTION OF DSCB READ - DSN
SUPPLIED IN CVPL
ADDRESS OF DATA SET NAME
*
Chapter 1. Using the Volume Table of Contents
85
CVAF Macros
BZ
XC
ST
B
CVAFDIR DSN=(RDSN),UCB=(RUCB),MF=(E,CVPL),BRANCH=YES
LA RTTR,LISTARG ADDRESS OF TTR TO BE RETURNED
USING TTRMAP,RTTR
LTR REG15,REG15
MAP OF TTR
ANY ERROR
NOERROR
TTR,TTR
REG15,LISTRC
RELOOP
BRANCH IF NOT
ZERO TTR INDICATING NO DSCB
STORE RC FROM CVAFDIR INTO LISTRC
GET NEXT ENTRY
NOERROR EQU *
MVC TTR(3),BFLEATTR
ST REG15,LISTRC
RELOOP EQU *
TM
LA
LASTLIST,LASTBIT IS IT LAST ENTRY IN LIST?
RLIST,NEXTLIST GET NEXT ENTRY
BZ TOPLOOP
CVAFDIR ACCESS=RLSE,
IOAREA=NOKEEP,
IXRCDS=NOKEEP,
BUFLIST=0,
BRANCH=YES,
PROCESS NEXT LIST
RELEASE CVAF OBTAINED AREAS
RELEASE IOAREA
RELEASE VIER BUFFER LIST *
NO USER BUFFER LIST SUPPLIED TO RLSE *
BRANCH ENTER CVAF
*
*
*
L
MF=(E,CVPL)
13,SAVEAREA+4
RETURN (14,12)
DSCB READ
RETURN TTR OF DSCB
STORE RC FROM CVAFDIR INTO LISTRC
GET NEXT ENTRY
BUFLIST ICVAFBFL DSECT=NO BUFFER LIST
SAVEAREA DS
LISTMAP DSECT
LISTDSN DS
LISTDSCB DS
*
LISTARG DS
*
LASTLIST DS
18F
F
F
0F
X
LASTBIT EQU X’80’
REGISTER SAVE AREA
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
LISTTTR DS
LISTRC DS
NEXTLIST EQU *
DSCB DSECT
XL3
F
IECSDSL1 (1)
DSCBLTH EQU *-DSCB-L’DS1DSNAM LENGTH OF DATA PORTION OF DSCB
TTRMAP DSECT
TTRFLG DS
TTR DS
DIRXMP2 CSECT
XL1
XL3
FLAG VALUE
TTR VALUE
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 *
*
*
ORG CVPL
CVPLMAP ICVAFPL DSECT=NO
AUTHORIZED SO UCB IS SUPPLIED
OVERLAY CVPL WITH EXPANSION OF MAP
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 PGM=CVDIR027
//STEPLIB DD DISP=SHR,DSN=YOUR.TEST.LOAD
//SYSPRINT DD SYSOUT=*
//CVAFDD
//OUTDD
//*
DD DISP=SHR,UNIT=3390,VOL=SER=1P9503 /* VSAM01 VOLSER */
DD SYSOUT=* /* 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.
EXTENTS.
THE DATASET PROCESSED IS VSAM AND HAS 123
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)
BALR R11,0
USING BASE,R11,R12
STANDARD LINKAGE CONVENTION
DCL R11 AS IMPLIED BASE REG
R12 IS ALSO BASE REG
88
z/OS DFSMSdfp Advanced Services
CVAF Macros
BASE L
B
BASEADDR DC
CV000000 DS
ST
LA
ST
LR
R12,BASEADDR
CV000000
A(BASE+4096)
0H
R13,SAVE+4
R14,SAVE
R14,8(,R13)
R13,R14
SET UP ADDRESSING FOR R12
BRANCH AROUND DECLARES
ADDRESSING FOR R12
CONTINUE...
SAVE PTR TO CALLER’S SAVE AREA
GET ADDRESS OF THE NEW SAVE AREA
CHAIN CALLER’S AREA TO OURS
ESTABLISH THE NEW SAVE AREA
*
***********************************************************************
*
* INITIALIZATION
*
*
* *
***********************************************************************
*
INITIAL DS 0H
BAL R14,IDVOLRTN
INITIALIZATION SECTION
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
ABEND 101
IF OPEN OK - BRANCH AROUND ABEND
ELSE ISSUE USER ABEND 101
INIT0010 DS 0H
PUT OUTFILE,STRTMSG
FILE IS OPEN WRITE START MESSAGE
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
BAL R14,SETU1RTN
BAL R14,VSAM1RTN
PROCESS CVAFDIR1.VSAM01.DATA DATASET
SETUP FOR CVAFDIR - 12 ENTRIES
PROCESS VSAM01 DATASET ROUTINE
PUT OUTFILE,BLNKLINE WRITE A RECORD TO THE OUTPUT FILE
*
*
***********************************************************************
* *
* FINALIZATION
*
***********************************************************************
*
FINAL DS 0H
PUT OUTFILE,ENDMSG
FINALIZATION SECTION
WRITE A RECORD TO THE OUTPUT FILE
*
*
FINL0010 DS
L
LM
LA
BR
CLOSE (OUTFILE)
C R15,RCODE00
BE FINL0010
ABEND 102
0H
R13,4(R13)
R14,R12,12(R13)
R15,0
R14
CLOSE OUTPUT FILE
IF FILE CLOSE IS OK
BRANCH AROUND ABEND
ELSE ISSUE USER ABEND 102
EXIT MODULE
RESTORE REGISTER
RESTORE CALLERS REGISTERS
SET RC TO 0
RETURN TO CALLER
*
*
*
***********************************************************************
IDVOLRTN
- OBTAIN THE NECESSARY INFORMATION FROM THE DASD VOLUME
*
*
***********************************************************************
*
IDVOLRTN DS
ST
0H
R14,IDVLSAVE
IDENTIFY VOLUME ROUTINE
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
BO
VTOCDCB+48,X’10’
IDVL0010
IF OPEN OF VTOC IS OK
BRANCH AROUND ABEND
ABEND 100
IDVL0010 DS 0H
SLR
SLR
R4,R4
R5,R5
ELSE ISSUE USER ABEND 100
INIT REG4 FOR DEB PTR
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
L
BR
0H
R14,IDVLSAVE
R14
EXIT FROM IDVOLRTN
LOAD C(IDVLSAVE) INTO 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
ST
LA
L
0H
R14,SET1SAVE
R4,BUFLHDR
R5,NBRENT
SETUP FOR CVAFDIR CALL
STORE C(R14) INTO SAVE AREA
GET ADDR OF BUF LIST HEADER
LOAD R5 WITH NBR OF ENTRIES (12)
USING BFLHDR,R4
MVI BFLHNOE,TWELVE
GET ADDRESSABILITY TO HEADER
INDICATE 12 ENTRIES
MVI BFLHKEY,BFLHDSCB INDICATE READ DSCB
LA R6,DSCBBUF LOAD R6 WITH ADDR OF 1ST DSCB BUFFER
LOAD R7 WITH ADDR OF BUFLIST1
GET ADDRESSABILITY TO ENTRY
*
* INITIALIZE 1ST ENTRY
*
LA R7,BUFLIST1
USING BFLE,R7
OI BFLEFL,BFLECHR INDICATE CCHHR TO BE READ
MVC BFLEARG(5),CCHHR0 SET ZEROES FOR ARGUMENT
MVI BFLELTH,DSCBL96
ST R6,BFLEBUF
GET LENGTH OF BUFFER
PUT DSCB BUF ADDR IN ENTRY
LA
LA
S
R7,ENTLENG(,R7)
R6,DSCBL96(,R6)
R5,ONE
INCREMENT ADDR TO NEXT ENTRY
INCREMENT ADDR TO NEXT DSCB BUFFER
C(R5) = C(R5) - 1
*
* INITIALIZE REMAINING ENTRIES
*
SETU0010 DS
OI
0H
BFLEFL,BFLECHR
INIT REMAINING 140 BYTE BUFFERS
INDICATE CCHHR TO BE READ
MVI BFLELTH,DSCBL140 GET LENGTH OF BUFFER
ST
LA
R6,BFLEBUF
R7,ENTLENG(,R7)
PUT DSCB BUF ADDR IN ENTRY
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
L
BR
0H
R14,SET1SAVE
R14
EXIT FROM SETU1RTN
LOAD C(SAVE AREA) INTO 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
ST
0H
R14,VSAMSAVE
PROCESS VSAM01 DATASET ROUTINE
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
C
B
VSAM0010 DS
R15,RETCODE
R15,RCODE00
VSAM0020
0H
LOAD R15 WITH SAVED RETURN CODE
IF RC FROM READ IS EQUAL TO ZERO
BE VSAM0010 BRANCH TO VSAM0010
PUT OUTFILE,UNEXPMS2 ELSE WRITE RC ERROR MESSAGE
BRANCH TO VSAM0020
PUT OUTFILE,RC00MSG
VSAM0020 DS 0H
LA R9,CVAFDIR
USING CVPL,R9
CLI CVSTAT,STAT000
BE VSAM0030
WRITE RC00 MESSAGE
GET ADDRESS OF CVAF PARM LIST
GET ADDRESSABILITY TO CVPL
IF CVSTAT FROM READ IS EQUAL TO ZERO
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
CLI
BE
0H
BFLHNOE,X’0C’
VSAM0050
IF NUMBER OF BUFFERS PROVIDED = 12
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
CLI
BE
CLI
BE
0H
BFLHNOEN,X’0B’
VSAM0070
BFLHNOEN,X’0C’
VSAM0080
IF NUMBER OF BUFFERS NEEDED = 11
BRANCH TO VSAM0070
IF NUMBER OF BUFFERS NEEDED = 12
BRANCH TO VSAM0080
PUT OUTFILE,UNEXPMS5 ELSE WRITE BUFFER ERROR MESSAGE
B
VSAM0070 DS
VSAM0090
0H
BRANCH TO VSAM0090
VSAM0090 DS
*
PUT OUTFILE,BUFNMSG1 WRITE BUFFER MESSAGE
B VSAM0090 BRANCH TO VSAM0090
VSAM0080 DS 0H
PUT OUTFILE,BUFNMSG2 WRITE BUFFER MESSAGE
0H
CVAFDIR ACCESS=RLSE,IXRCDS=NOKEEP,BUFLIST=0,
MF=(E,CVAFDIR)
*
X
C
BE
R15,RCODE00
VSAMEXIT
IF RC FROM RLSE IS EQUAL TO ZERO
BRANCH TO VSAMEXIT
PUT OUTFILE,UNEXPMS6 ELSE WRITE RLSE ERROR MESSAGE
*
VSAMEXIT DS 0H
DROP R9
EXIT FROM ROUTINE
DROP R9
L
BR
R14,VSAMSAVE
R14
LOAD C(SAVE AREA) INTO 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)
*
ST R15,RETCODE STORE RC INTO RETCODE
*
LA R9,CVAFDIR
USING CVPL,R9
CLI CVFL4,CV4EADOK
BE READ0010
CLI CVFL4,CV4MULTD
BE READ0020
CLI CVFL4,BOTH
BE READ0030
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
PUT OUTFILE,UNEXPMS1 ELSE WRITE ERROR RECORD PL
B READEXIT BRANCH TO EXIT ROUTINE
READ0010 DS 0H
PUT OUTFILE,OKMSG
WRITE MESSAGES X’10’
WRITE OK MSG RECORD
PUT OUTFILE,NOMULTMS WRITE NO MULTI MSG RECORD
B READEXIT BRANCH TO EXIT ROUTINE
READ0020 DS 0H WRITE MESSAGES X’08’
PUT OUTFILE,NOTOKMSG WRITE NOTOK MSG RECORD
PUT OUTFILE,MULTMSG
B READEXIT
WRITE MULTI MSG RECORD
BRANCH TO EXIT ROUTINE
READ0030 DS 0H
PUT OUTFILE,OKMSG
PUT OUTFILE,MULTMSG
READEXIT DS 0H
DROP R9
L R14,READSAVE
BR R14
WRITE MESSAGES X’18’
WRITE OK MSG RECORD
WRITE MULTI MSG RECORD
EXIT FROM READRTN
DROP R9
LOAD C(SAVE AREA) INTO R14
EXIT
*
***********************************************************************
* WORKING STORAGE *
***********************************************************************
*
DS
DC
0D
CL36’CVDIR027-WORKING STORAGE BEGINS HERE’
*
***********************************************************************
* EQUATES *
***********************************************************************
*
R0
R1
R2
R3
R4
R5
R6
R7
R8
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
0
1
2
3
4
5
6
7
R9
R10
EQU 8
EQU 9
EQU 10
R11
R12
R13
R14
EQU
EQU
EQU
EQU
11
12
13
14
R15
BOTH
EQU 15
EQU X’18’
TWELVE EQU X’0C’
*
***********************************************************************
* SAVE AREAS *
X
X
92
z/OS DFSMSdfp Advanced Services
CVAF Macros
***********************************************************************
*
SAVE DC
IDVLSAVE DC
18F’0’
F’0’
MAIN PROGRAM SAVE AREA
IDENTIFY VOLUME ROUTINE SAVE AREA
READSAVE DC
SET1SAVE DC
VSAMSAVE DC
*
F’0’
F’0’
F’0’
CVAFDIR READ ROUTINE SAVE AREA
SETUP ROUTINE SAVE AREA
VSAM01 ROUTINE SAVE AREA
***********************************************************************
* CONSTANTS *
***********************************************************************
*
CCHHR0
NBRENT
RCODE00
ONE
DS
DC
DC
DC
XL5’00’
F’12’
F’0’
F’1’
CCHHR ARGUMENT - ZERO
CONSTANT-12 NUMBER OF BUFFER ENTRIES
RETURN CODE 0
CONSTANT - ONE
CL44’CVAFDIR1.VSAM01.DATA’ VSAM01 DC
*
***********************************************************************
* PROGRAM BUFFERS *
***********************************************************************
*
BUFLIST DS
BUFLHDR DC
0F
2F’0’
BUFFER LIST DECLARATIONS
BUFFER LIST HEADER
BUFLIST1 DC 3F’0’
ENTLENG EQU *-BUFLIST1
BUFLIST2 DC 3F’0’
BUFFER LIST ENTRY 1
ENTRY LENGTH - 12
BUFFER LIST ENTRY 2
BUFLIST3 DC
BUFLIST4 DC
BUFLIST5 DC
BUFLIST6 DC
BUFLIST7 DC
BUFLIST8 DC
BUFLIST9 DC
BUFLISTA DC
3F’0’
3F’0’
3F’0’
3F’0’
3F’0’
3F’0’
3F’0’
3F’0’
BUFFER LIST ENTRY 3
BUFFER LIST ENTRY 4
BUFFER LIST ENTRY 5
BUFFER LIST ENTRY 6
BUFFER LIST ENTRY 7
BUFFER LIST ENTRY 8
BUFFER LIST ENTRY 9
BUFFER LIST ENTRY 10
BUFLISTB DC
BUFLISTC DC
*
DSCBBUF
DSCBL96
DS
EQU
3F’0’
3F’0’
XL96
*-DSCBBUF
DSCBBUF2 DS XL140
DSCBL140 EQU *-DSCBBUF2
DSCBBUF3 DS
DSCBBUF4 DS
DSCBBUF5 DS
DSCBBUF6 DS
DSCBBUF7 DS
DSCBBUF8 DS
DSCBBUF9 DS
DSCBBUFA DS
DSCBBUFB DS
DSCBBUFC DS
XL140
XL140
XL140
XL140
XL140
XL140
XL140
XL140
XL140
XL140
BUFFER LIST ENTRY 11
BUFFER LIST ENTRY 12
DSCB BUFFER DECLARATION 1 - 96 BYTE
LENGTH - 96
DSCB BUFFER DECLARATION 2 - 140 BYTE
LENGTH - 140
DSCB BUFFER DECLARATION 3 - 140 BYTE
DSCB BUFFER DECLARATION 4 - 140 BYTE
DSCB BUFFER DECLARATION 5 - 140 BYTE
DSCB BUFFER DECLARATION 6 - 140 BYTE
DSCB BUFFER DECLARATION 7 - 140 BYTE
DSCB BUFFER DECLARATION 8 - 140 BYTE
DSCB BUFFER DECLARATION 9 - 140 BYTE
DSCB BUFFER DECLARATION 10- 140 BYTE
DSCB BUFFER DECLARATION 11- 140 BYTE
DSCB BUFFER DECLARATION 12- 140 BYTE
*
***********************************************************************
* PROGRAM MESSAGES *
***********************************************************************
*
BLNKLINE DC
STRTMSG DC
ENDMSG DC
VSAM1MSG DC
CL80’ ’
CL80’CVDIR027 START OF OUTPUT MESSAGES
CL80’CVDIR027 END OF OUTPUT MESSAGES
CL80’ PROCESSING DSN: CVAFDIR1.VSAM01.DATA
’
’
’
CALLMR11 DC CL80’ CVAFDIR CALL: EADSCB=OK AND MULTIPLEDSCBS=YES CODED’
OKMSG DC
NOTOKMSG DC
CL80’ CV4EADOK BIT SET / EADSCB=OK
CL80’ CV4EADOK BIT NOT SET / EADSCB=NOTOK
’
’
MULTMSG DC
NOMULTMS DC
RC00MSG DC
CL80’ CV4MULTD BIT SET / MULTIPLEDSCBS=YES
CL80’ CV4MULTD BIT NOT SET / MULTIPLEDSCBS=NO
CL80’ RC00 VERIFIED - THE REQUEST WAS SUCCESSFUL
’
’
’
Chapter 1. Using the Volume Table of Contents
93
CVAF Macros
CV00MSG DC
BUFSMSG1 DC
BUFNMSG1 DC
BUFNMSG2 DC
UNEXPMS1 DC
UNEXPMS2 DC
UNEXPMS3 DC
UNEXPMS4 DC
CL80’ X"00" DEC"000" 00 - CVSTAT CODE VERIFIED ’
CL80’ BUFFER LIST ENTRIES PROVIDED: 12 ’
CL80’ BUFFER LIST ENTRIES NEEDED : 11
CL80’ BUFFER LIST ENTRIES NEEDED : 12
’
’
CL80’ ERROR: UNEXPECTED BIT SETTING FOR CVFL4 ’
CL80’ ERROR: UNEXPECTED RETURN CODE FROM CVAFDIR READ ’
CL80’ ERROR: UNEXPECTED CVSTAT CODE FROM CVAFDIR READ ’
CL80’ ERROR: UNEXPECTED NUMBER OF BUFFERS PROVIDED ’
UNEXPMS5 DC
UNEXPMS6 DC
CL80’ ERROR: UNEXPECTED NUMBER OF BUFFERS NEEDED ’
CL80’ ERROR: UNEXPECTED RETURN CODE FROM CVAFDIR RLSE ’
*
***********************************************************************
* WORK AREAS *
***********************************************************************
*
DEBADD DC
UCBADD
RETCODE DC
DSNAME
*
DC
DS
F’0’
F’0’
F’999’
CL44
DEB ADDRESS SAVE AREA
UCB ADDRESS SAVE AREA
RETURN CODE SAVE AREA
DSNAME
***********************************************************************
* DCB - OUTPUT FILE (OUTFILE) *
***********************************************************************
*
OUTFILE DCB DDNAME=OUTDD,
DSORG=PS,
RECFM=FB,
LRECL=80,
MACRF=PM
*
***********************************************************************
X
X
X
X
* VTOC DCB AREA *
***********************************************************************
*
VTOCDCB DCB DDNAME=CVAFDD,MACRF=E,EXLST=XLST1,DSORG=PS,DCBE=VTOCDCBE
XLST1 DC
DC
X’87’
AL3(JFCB1)
JFCB1 DS
TESTNAME DS
DS
DS
DS
0CL176
CL44
CL8
BL1
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:
►►
label
CVAFDSM ACCESS=MAPDATA ,MAP= INDEX
VOLUME
VTOC
►
NO
,RTA4BYTE= YES ,MAPRCDS= YES
(1)
(YES,addr)
(2)
NO
(NO,addr)
►
NO
,COUNT= YES
,CTAREA=addr ,HADSCB=addr
,EXTENTS=addr
,UCB= (ucbaddr)
,DEB=addr
►
NOKEEP
,IOAREA= KEEP
(KEEP,addr)
(NOKEEP,addr)
NO
(3)
,BRANCH, YES
(YES,SUP)
(YES,PGM)
NOTOK
,EADSCB= OK
►
I
,MF= L
(E,addr)
2
3
Notes:
1 Default if MF=I.
Default if MF=L or MF=(E, addr).
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')
8 (X'08')
12 (X'0C')
16 (X'10')
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.
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
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
READ
,ACCESS= RESUME
RLSE
,BUFLIST=
addr
(reg)
►
,UCB= (ucbaddr)
,DEB=addr
,FCL=
addr
(reg)
NOKEEP
,FLTAREA= KEEP
(KEEP,
addr
(reg)
(NOKEEP,
addr
(reg)
)
)
►
NOKEEP
,IOAREA= KEEP
(KEEP,
addr
(reg)
(NOKEEP,
addr
(reg)
)
)
►
NOTOK
,EADSCB= OK ,MF=
I
D
,BRANCH=
L
(E,
addr
(reg)
)
NO
YES
(YES, SUP )
PGM
►
►
►◄
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
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.
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
DD DISP=SHR,UNIT=3390,VOL=SER=339L62
//G.OUTDD
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
CVAFFLT1.DATA02
CVAFFLT1.PDSE01
(5 EXTENTS - 1 FMT1/1 FMT3)
(5 EXTENTS - 1 FMT1/1 FMT3)
(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
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
* *
***********************************************************************
*
BASE
STM
BALR
R14,R12,12(R13)
R11,0
USING BASE,R11,R12
L
B
BASEADDR DC
CVAFFL00 DS
ST
LA
ST
LR
R12,BASEADDR
CVAFFL00
A(BASE+4096)
0H
R13,SAVE+4
R14,SAVE
R14,8(,R13)
R13,R14
STANDARD LINKAGE CONVENTION
DCL R11 AS IMPLIED BASE REG
R12 IS ALSO BASE REG
SET UP ADDRESSING FOR R12
BRANCH AROUND DECLARES
ADDRESSING FOR R12
CONTINUE...
SAVE PTR TO CALLER’S SAVE AREA
GET ADDRESS OF THE NEW SAVE AREA
CHAIN CALLER’S AREA TO OURS
ESTABLISH THE NEW SAVE AREA
*
***********************************************************************
*
* INITIALIZATION
*
*
* *
***********************************************************************
*
INITIAL DS 0H
BAL R14,IDVOLRTN
INITIALIZATION SECTION
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
MVI DSNNBR,X’02’
BAL R14,FCL1RTN
BAL R14,CVAFRD2
MAINLINE SECTION
SET DSNNBR FLAG TO TWO
INVOKE RTN TO INIT FCL (DS01/DS02)
INVOKE CVAFFILT READ RTN 2
BAL R14,TSTRCRTN
L R15,RETCODE
CH R15,RCODE00
BNE MAIN0010
INVOKE TEST RC RTN
LOAD R15 WITH RETURN CODE
IS RC = 0
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
MVC DS2(44),DS02
WRITE A RECORD TO THE OUTPUT FILE
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
B MAIN0020
INVOKE FORMAT OUTPUT MSG RTN
BRANCH TO MAIN0020
MAIN0010 DS 0H
MVC DS3(44),DS01
CVAFFILT - CVSTAT LOGICAL ERROR
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’
BAL R14,FCL2RTN
BAL R14,CVAFRD1
BAL R14,TSTRCRTN
SET DSNNBR FLAG TO ONE
INVOKE RTN TO INIT FCL (DS03)
INVOKE CVAFFILT READ RTN 1
INVOKE TEST RC RTN
L
CH
R15,RETCODE
R15,RCODE00
BNE MAIN0030
MVC DS(44),DS03
LOAD R15 WITH RETURN CODE
IS RC = 0
NO - DO NOT FORMAT/PRINT LINES
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
B MAIN0040
INVOKE FORMAT OUTPUT MSG RTN
BRANCH TO MAIN0040
MAIN0030 DS 0H
MVC DS3(44),DS03
CVAFFILT - CVSTAT LOGICAL ERROR
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
BAL R14,CVAFRD1
BAL R14,TSTRCRTN
L R15,RETCODE
CH R15,RCODE00
BNE MAIN0050
INVOKE RTN TO INIT FCL (DS01)
INVOKE CVAFFILT READ RTN
INVOKE TEST RC RTN
LOAD R15 WITH RETURN CODE
IS RC = 0
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
BAL R14,FMTOPRTN
WRITE A RECORD TO THE OUTPUT FILE
INVOKE FORMAT OUTPUT MSG RTN
B
MAIN0050 DS
MAIN0060
0H
BRANCH TO MAIN0060
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 PDETLINE(133),BLNKLNE MOVE BLANK LINE TO LINE
PUT OUTFILE,PDETLINE WRITE A RECORD TO THE OUTPUT FILE
BAL R14,CVAFRL
BAL R14,FCL4RTN
INVOKE CVAFFILT RELEASE RTN
INVOKE RTN TO INIT FCL (ENTIRE VOL)
BAL R14,CVAFRDA
LA R9,CVPLDEFA
USING CVPLMAP,R9
BAL R14,TSTRCRTN
INVOKE CVAFFILT READ RTN (FOR RESUME)
ESTABLISH ADDRESSABILITY
TO THE CVPL (FOR CVSTAT)
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
LM
LA
BR
R13,4(R13)
R14,R12,12(R13)
R15,0
R14
RESTORE REGISTER
RESTORE CALLERS REGISTERS
SET RC TO 0
RETURN TO CALLER
*
***********************************************************************
*
*
OPENRTN
- ROUTINE TO OPEN OUTPUT FILE USED BY THIS MODULE
***********************************************************************
*
*
*
OPENRTN DS
ST
0H
R14,OPENSAVE
OPEN FILES ROUTINE
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
LA
OPENEXIT
R1,EABN101
BAL R14,ABENDRTN
OPENEXIT DS 0H
FILE OPEN OK - EXIT OPEN RTN
OUTPUT FILE NOT OPEN-USER ABEND 101
INVOKE ABEND ROUTINE
EXIT FROM OPEN ROUTINE
L
BR
R14,OPENSAVE
R14
LOAD C(OPENSAVE) INTO R14
EXIT
*
***********************************************************************
*
*
CLOSERTN
- ROUTINE TO CLOSE OUTPUT FILE USED BY THIS MODULE
***********************************************************************
*
*
*
CLOSERTN DS
ST
0H
R14,CLOSSAVE
CLOSE (OUTFILE)
LTR R15,R15
CLOSE FILES ROUTINE
STORE C(R14) INTO SAVE AREA
CLOSE OUTPUT FILE
CHECK IF CLOSED OK
BZ
LA
CLOSEXIT
R1,EABN102
BAL R14,ABENDRTN
CLOSEXIT DS 0H
L
BR
R14,CLOSSAVE
R14
IF OK BRANCH TO CLOSEXIT
ELSE SETUP FOR USER ABEND 102
INVOKE ABEND ROUTINE
EXIT FROM CLOSE ROUTINE
LOAD C(CLOSSAVE) INTO R14
EXIT
*
*
*
***********************************************************************
ABENDRTN
- FORCE AN ABEND ROUTINE
*
*
***********************************************************************
*
ABENDRTN DS
ST
0H
R14,ABENSAVE
ABEND ROUTINE
STORE C(R14) INTO SAVE AREA
ABEND (R1),DUMP
ABENEXIT DS 0H
ISSUE USER ABEND WITH DUMP
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
ST
0H
R14,IDVLSAVE
IDENTIFY VOLUME ROUTINE
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
BO
VTOCDCB+(DCBOFLGS-IHADCB),DCBOFOPN
IDVOL010 BRANCH TO IDVOL010 - GOOD OPEN
LA R1,EABN100
BAL R14,ABENDRTN
IDVOL010 DS 0H
SLR RDEB,RDEB
ST
IDVLEXIT DS
L
BR
ELSE SETUP FOR USER ABEND 100
INVOKE ABEND ROUTINE
GOOD OPEN - OBTAIN VOLUME INFORMATION
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)
RUCB,UCBADD
0H
R14,IDVLSAVE
R14
SAVE UCB ADDRESS INTO R2
EXIT FROM IDVOLRTN
LOAD C(IDVLSAVE) INTO R14
EXIT
*
*
*
***********************************************************************
TSTRCRTN
- TEST RETURN CODE FROM CVAFFILT
*
*
* - FORMAT AND PRINT MESSAGES AS NEEDED *
***********************************************************************
*
TSTRCRTN DS
ST
L
CH
BE
CH
BE
TSTRCER DS
0H
R14,TSTRSAVE
R15,RETCODE
R15,RCODE00
TSTRC00
R15,RCODE04
TSTRC04
0H
CHECK RETURN CODE ROUTINE
STORE C(R14) INTO SAVE AREA
LOAD R15 WITH RC SAVED FROM LAST CALL
IF RETURN CODE = 00
BRANCH TO PROCESS RC00
IF RETURN CODE = 04
BRANCH TO PROCESS RC04
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
B TSTREXIT
INVOKE FORMAT OUTPUT MSG ROUTINE
BRANCH TO EXIT RTN
TSTRC04 DS 0H
CLI CVSTAT,STAT064
BNE TSTR0010
BAL R14,CVAFRS
B TSTREXIT
PROCESS RETURN CODE = 04
DO WE NEED RESUME?
NO - PRINT LOGICAL ERROR MSG
INVOKE CVAFRS RESUME ROUTINE
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
BR
R14,TSTRSAVE
R14
LOAD C(TSTRSAVE) INTO 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
ST
0H
R14,FMTCSAVE
COUNT DSCBS RETURNED ROUTINE
STORE C(R14) INTO SAVE AREA
SLR R6,R6
SLR R7,R7
CLI DSNNBR,X’01’
BE FMTC0010
ZERO OUT R6
ZERO OUT R7
IF DSNNBR FLAG = 1
BRANCH TO LOAD ADDR OF FCL
LA
B
R4,FCLDEF2
FMTC0020
ELSE LOAD R4 WITH ADDR OF FCL2
BRANCH TO SET USING
FMTC0010 DS
LA
FMTC0020 DS
0H
R4,FCLDEF
0H
USING FCLMAP,R4
SLR R5,R5
LOAD R4 WITH ADDR OF FCL
CONTINUE - SET USING
ESTABLISH ADDRESSABILITY TO FCL
ZERO OUT R5
ICM R5,B’0011’,FCLDSCBR DETERMINE IF ANY DSCBS RETURNED
BZ
LA
FMTC0060
R4,DSCBDEF
USING DSCBMAP,R4
FMTC0030 DS 0H
NO - GO AND PRINT APPROPRIATE MSG
LOAD R4 WITH ADDR OF DSCB MAP
ESTABLISH ADDRESSABILITY TO DSCB
COUNT DSCBS BY TYPE RETURNED
CLI DS1FMTID,X’F1’
BE FMTC0040
CLI DS1FMTID,X’F3’
BNE FMTC0050
LA
B
FMTC0040 DS
R7,1(R7)
FMTC0050
0H
LA
FMTC0050 DS
R6,1(R6)
0H
LA R4,DSCBSIZ(R4)
BCT R5,FMTC0030
ST
ST
R6,RETF1
R7,RETF3
DROP R4
B FMTCEXIT
IF FORMAT1
BRANCH TO FMTC0040
ELSE IF NOT FORMAT3
BRANCH TO FMTC0050
ADD 1 TO FORMAT3 COUNT
BRANCH TO FMTC0050
FMTC0040 - FORMAT1 INCREMENT
ADD 1 TO FORMAT1 COUNT
FMTC0050 - PROCESS THROUGH DSCBS
ADD DSCBSIZ TO R4
SUBTRACT 1 FROM DSCB COUNT AND CONT
STORE #FMT1’S INTO RETF1
STORE #FMT3’S INTO RETF3
DROP R4 USING
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
SLR R7,R7
ST
FMTCEXIT DS
R7,RETF3
0H
STORE ZERO INTO RETF1
ZERO OUT R7
STORE ZERO INTO RETF3
EXIT FROM FMTCTRTN
L
BR
R14,FMTCSAVE
R14
LOAD C(FMTCSAVE) INTO R14
EXIT
*
***********************************************************************
*
*
FMTOPRTN
- FORMAT THE DSCB COUNTS AND WRITE TO THE OUTPUT DATASET
***********************************************************************
*
*
*
FMTOPRTN DS
ST
0H
R14,FMTOSAVE
FORMAT OUTPUT ROUTINE
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
CVD R7,WF3
LOAD R7 WITH NBR OF FMT3’S RETURNED
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
L
BR
0H
R14,FMTOSAVE
R14
EXIT FROM FMTOPRTN
LOAD C(FMTOSAVE) INTO R14
EXIT
*
*
*
***********************************************************************
BUFLRTN
- INITIALIZE BUFFER LIST HEADER (BFLH)
*
*
* - INITIALIZE BUFFER LIST ELEMENTS (BFLE) *
***********************************************************************
*
BUFLRTN DS
ST
XC
LA
0H
R14,BUFLSAVE
BUFFER LIST INITIALIZATION ROUTINE
STORE C(R14) INTO SAVE AREA
BFLHDEF(BFLSIZE),BFLHDEF CLEAR BUFR LIST AREA
R1,BFLHDEF
USING BFLMAP,R1
R1 - BUFFER LIST HEADER
ESTABLISH ADDRESSABILITY
MVI BFLHNOE,BUFNBR
OI BFLHFL,BFLHDSCB
SET NUMBER OF BUFFER ELEMENTS
IDENTIFY AS DSCB BUFR ELEMENT LIST
LA R2,BFLHDEF+BFLHLN R2 - FIRST BUFFER LIST ELEMENT
USING BFLE,R2 ESTABLISH ADDRESSABILITY
LA
LA
R3,DSCBDEF
R4,BUFNBR
BFL0010 OI BFLEFL,BFLECHR
MVI BFLELTH,DSCBSIZ
ST
LA
R3,BFLEBUF
R2,BFLELN(R2)
LA R3,DSCBSIZ(R3)
BCT R4,BFL0010
R3 - FIRST DSCB BUFFER
R4 = NUMBER OF ELEMENTS AND BUFRS
REQUEST CCHHR ON RETURN
SET BUFR LNGTH TO FULL DSCB SIZE
SET ADDR(DSCB BUFFER)
R2 - NEXT BUFFER LIST ELEMENT
R3 - NEXT DSCB BUFFER
LOOP THROUGH ALL ELEMENTS
DROP R1,R2
BUFLEXIT DS 0H
L
BR
R14,BUFLSAVE
R14
DROP TEMP USINGS
EXIT FROM BUFLRTN
LOAD C(BUFLSAVE) INTO R14
EXIT
*
*
*
***********************************************************************
FCL1RTN
- INITIALIZE FILTER CRITERIA LIST (FCL) HEADER AND ELEMENT
*
*
* - INITIALIZE A FCL TO READ FOR TWO SPECIFIC SEQ DATASETS *
***********************************************************************
*
FCL1RTN DS
ST
XC
LA
0H
R14,FCL1SAVE
FCL INITIALIZATION ROUTINE
STORE C(R14) INTO SAVE AREA
FCLDEF2(FCLSIZE2),FCLDEF2 CLEAR FCL AREA
R1,FCLDEF2
USING FCLMAP,R1
R1 - FCL HEADER
ESTABLISH ADDRESSABILITY
LA R2,FCLHDEND
USING FCLDSN,R2
MVC FCLID,CFCLID
MVC FCLCOUNT,=H’2’
R2 - FIRST FCL ELEMENT
ESTABLISH ADDRESSABILITY
SET THE EYECATCHER ’FCL ’
SET NUMBER OF FCL ELEMENTS
*
*
MVI
MVI
LA
FCL1FLAG,X’80’
FCLDSNLG,X’0F’
R3,DS01
SET FLAG FOR FULLY QUAL DSN
SET LENGTH FOR DSN1 (15)
DSN=CVAFFLT1.DATA01
SEQ DS - 5 EXTENTS *
*
ST
LA
MVI
LA
R3,FCLDSNA
R2,FCLDSNEL(R2)
FCLDSNLG,X’0F’
R3,DS02
1 FORMAT1 AND 1 FORMAT3
SET ADDR OF DSN
LOAD R2 WITH ADDR OF 2ND FCL ELEMENT
SET LENGTH FOR DSN2 (15)
DSN=CVAFFLT1.DATA02
SEQ DS - 5 EXTENTS *
*
ST R3,FCLDSNA
DROP R1,R2
FC1EXIT DS
L
BR
0H
R14,FCL1SAVE
R14
1 FORMAT1 AND 1 FORMAT3
SET ADDR OF DSN
DROP TEMP USING
EXIT FROM FCLRTN
LOAD C(FCL1SAVE) INTO 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
ST
XC
LA
0H
R14,FCL2SAVE
FCL INITIALIZATION ROUTINE
STORE C(R14) INTO SAVE AREA
FCLDEF(FCLSIZE),FCLDEF CLEAR FCL AREA
R1,FCLDEF
USING FCLMAP,R1
R1 - FCL HEADER
ESTABLISH ADDRESSABILITY
LA R2,FCLHDEND
USING FCLDSN,R2
MVC FCLID,CFCLID
MVC FCLCOUNT,=H’1’
R2 - FIRST (ONLY) FCL ELEMENT
ESTABLISH ADDRESSABILITY
SET THE EYECATCHER ’FCL ’
SET NUMBER OF FCL ELEMENTS
*
*
*
MVI
MVI
LA
FCL1FLAG,X’80’
FCLDSNLG,X’0F’
R3,DS03
SET FLAG FOR FULLY QUAL DSN
SET LENGTH FOR DSN (15)
DSN=CVAFFLT1.PDSE01
PDSE DS - 122 EXTENTS *
*
ST R3,FCLDSNA
DROP R1,R2
FC2EXIT DS
L
BR
0H
R14,FCL2SAVE
R14
1 FORMAT1 AND 10 FORMAT3’S
SET ADDR OF DSN
DROP TEMP USING
EXIT FROM FCLRTN
LOAD C(FCL2SAVE) INTO R14
EXIT
*
***********************************************************************
FCL3RTN
- INITIALIZE FILTER CRITERIA LIST (FCL) HEADER AND ELEMENT
- INITIALIZE A FCL TO READ FOR ONE SPECIFIC SEQ DATASET
*
*
*
***********************************************************************
*
FCL3RTN DS
ST
0H
R14,FCL3SAVE
FCL INITIALIZATION ROUTINE
STORE C(R14) INTO SAVE AREA
XC
LA
FCLDEF(FCLSIZE),FCLDEF CLEAR FCL AREA
R1,FCLDEF R1 - FCL HEADER
USING FCLMAP,R1
LA R2,FCLHDEND
ESTABLISH ADDRESSABILITY
R2 - FIRST (ONLY) FCL ELEMENT
USING FCLDSN,R2
MVC FCLID,CFCLID
MVC FCLCOUNT,=H’1’
MVI FCL1FLAG,X’80’
MVI
LA
FCLDSNLG,X’0F’
R3,DS01
ESTABLISH ADDRESSABILITY
SET THE EYECATCHER ’FCL ’
SET NUMBER OF FCL ELEMENTS
SET FLAG FOR FULLY QUAL DSN
SET LENGTH FOR DSN (15)
DSN=CVAFFLT1.DATA01
SEQ DS - 5 EXTENTS
1 FORMAT1 AND 1 FORMAT3
*
*
ST
FC3EXIT DS
L
BR
R3,FCLDSNA
DROP R1,R2
0H
R14,FCL3SAVE
R14
SET ADDR OF DSN
DROP TEMP USING
EXIT FROM FCLRTN
LOAD C(FCL3SAVE) INTO R14
EXIT
*
*
*
***********************************************************************
FCL4RTN
- INITIALIZE FILTER CRITERIA LIST (FCL) HEADER AND ELEMENT
*
*
* - INITIALIZE A FCL TO READ THE DSCBS ON THE ENTIRE VOLUME *
***********************************************************************
*
FCL4RTN DS
ST
XC
LA
0H
R14,FCL4SAVE
FCLDEF(FCLSIZE),FCLDEF
R1,FCLDEF
USING FCLMAP,R1
LA R2,FCLHDEND
FCL INITIALIZATION ROUTINE
STORE C(R14) INTO SAVE AREA
CLEAR FCL AREA
R1 - FCL HEADER
ESTABLISH ADDRESSABILITY
R2 - FIRST (ONLY) FCL ELEMENT
USING FCLDSN,R2
MVC FCLID,CFCLID
MVC FCLCOUNT,=H’1’
MVI FCL1FLAG,X’00’
MVI FCLDSNLG,X’02’
LA R3,=C’**’
ESTABLISH ADDRESSABILITY
SET THE EYECATCHER ’FCL ’
SET NUMBER OF FCL ELEMENTS
SET FLAG FOR GENERIC DSN
SET LENGTH FOR DSN - ** (02)
ALL DATASETS ON THE VOLUME
116
z/OS DFSMSdfp Advanced Services
CVAF Macros
ST R3,FCLDSNA
DROP R1,R2
FC4EXIT DS
L
BR
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
ST
0H
R14,CVR1SAVE
CVAFFILT - READ ROUTINE (2 DSN)
STORE C(R14) INTO SAVE AREA
SLR R2,R2
LA R2,CVPLDEF
ZERO OUT R2
LOAD R2 WITH ADDR OF CVPL
L R3,UCBADD LOAD R3 WITH UCB ADDRESS
CVAFFILT ACCESS=READ,UCB=(R3),FCL=FCLDEF,BUFLIST=BFLHDEF, X
ST
CVR1EXIT DS
L
BR
MF=(E,(R2))
R15,RETCODE
0H
R14,CVR1SAVE
R14
STORE RC FOR LATER INTERROGATION
EXIT FROM CVAFRD1
LOAD C(CVR1SAVE) INTO R14
EXIT
*
***********************************************************************
* CVAFRD2 *
* - INVOKE THE CFAFFILT MACRO AND READ THE DSCBS (2 DSN’S) *
***********************************************************************
*
CVAFRD2 DS
ST
0H
R14,CVR2SAVE
SLR R2,R2
LA
L
LA
LA
R2,CVPLDEF
R3,UCBADD
R4,FCLDEF2
R5,BFLHDEF
CVAFFILT - READ ROUTINE (2 DSN’S)
STORE C(R14) INTO SAVE AREA
ZERO OUT R2
LOAD R2 WITH ADDR OF CVPL
LOAD R3 WITH UCB ADDRESS
LOAD R4 WITH ADDR OF FCLDEF2
LOAD R5 WITH ADDR OF FCLDEF2
CVAFFILT ACCESS=READ,UCB=(R3),FCL=(R4),BUFLIST=(R5),
ST
CVR2EXIT DS
L
BR
MF=(E,(R2))
R15,RETCODE
0H
R14,CVR2SAVE
R14
STORE RC FOR LATER INTERROGATION
EXIT FROM CVAFRD2
LOAD C(CVR2SAVE) INTO R14
EXIT
*
*
*
***********************************************************************
CVAFRDA
- INVOKE THE CFAFFILT MACRO AND READ ALL THE DSCBS
*
*
X
***********************************************************************
*
CVAFRDA DS
ST
0H
R14,CVRASAVE
CVAFFILT - READ ALL DSCBS ROUTINE
STORE C(R14) INTO SAVE AREA
CVAFFILT ACCESS=READ,UCB=UCBADD,FCL=FCLDEF,BUFLIST=BFLHDEF, X
FLTAREA=KEEP,IOAREA=KEEP, X
ST
CVRAEXIT DS
L
BR
MF=(E,CVPLDEFA)
R15,RETCODE
0H
R14,CVRASAVE
R14
STORE RC FOR LATER INTERROGATION
EXIT FROM CVAFRDA
LOAD C(CVRASAVE) INTO R14
EXIT
*
***********************************************************************
*
*
CVAFRS
- INVOKE THE CFAFFILT MACRO USING RESUME
***********************************************************************
*
*
*
CVAFRS DS
ST
CVRS0000 DS
CH
BE
0H
R14,CVRSSAVE
0H
R15,RCODE00
CVRS0050
CVAFFILT - RESUME ROUTINE
STORE C(R14) INTO SAVE AREA
NOW CHECK RC AND STAT CODES
IS THE RC FROM RESUME 0?
YES BRANCH TO CVRS0050
Chapter 1. Using the Volume Table of Contents
117
CVAF Macros
CH
BE
R15,RCODE04
CVRS0020
IS THE RC FROM RESUME 4?
YES BRANCH TO CVRS0020
CVRS0010 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
CVRS0020 DS 0H
CLI CVSTAT,STAT064
PROCESS FOR RC04 - CHECK FOR STAT064
IS THE CVSTAT CODE 064(RESUME NEEDED)
BNE CVRS0060
CLI RESFLG,X’01’
NO - BRANCH TO CVRS0060
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
MVI RESFLG,X’01’
B
CVRS0030 DS
CVRS0040
0H
INVOKE FORMAT OUTPUT MSG ROUTINE
RESUME NEEDED - SET FLAG ON
BRANCH TO CVRS0040
RESUME PROCESSING
MVC PDETLINE(133),ST64MSG3 MOVE MSG TO LINE
PUT OUTFILE,PDETLINE WRITE A RECORD TO THE OUTPUT FILE
BAL R14,FMTCTRTN
BAL R14,FMTOPRTN
INVOKE FORMAT COUNT ROUTINE
INVOKE FORMAT OUTPUT MSG ROUTINE
CVRS0040 DS 0H RESUME PROCESSING
CVAFFILT ACCESS=RESUME,MF=(E,CVPLDEFA)
B CVRS0000 BRANCH TO CHECK RETURN CODE AGAIN
CVRS0050 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,
MF=(E,CVPLDEFA)
B
CVRS0060 DS
CVRSEXIT
0H
BRANCH TO EXIT ROUTINE
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
L
BR
0H
R14,CVRSSAVE
R14
EXIT FROM CVAFRS
LOAD C(CVRSSAVE) INTO R14
EXIT
*
*
*
***********************************************************************
CVAFRL
- INVOKE THE CFAFFILT MACRO AND RELEASE WORK AREAS
*
*
X
***********************************************************************
*
CVAFRL DS 0H
ST R14,CVRLSAVE
CVAFFILT - RLSE ROUTINE
STORE C(R14) INTO SAVE AREA
CVAFFILT ACCESS=RLSE,FCL=0,BUFLIST=0,FLTAREA=NOKEEP, X
CH
BE
MF=(E,CVPLDEF)
R15,RCODE00
CVRLEXIT
IF RC = 0 THEN
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
BR
R14,CVRLSAVE
R14
LOAD C(CVRLSAVE) INTO R14
EXIT
*
***********************************************************************
* WORKING STORAGE *
***********************************************************************
118
z/OS DFSMSdfp Advanced Services
CVAF Macros
*
DS
DC
0D
CL36’CVAFFEXP-WORKING STORAGE BEGINS HERE’
*
***********************************************************************
* EQUATES *
***********************************************************************
*
EABN100
R2
RUCB
R3
R4
R5
R6
R7
R8
R9
R11
EQU
EABN101 EQU
EABN102
R0
R1
RDEB
EQU
BUFNBR EQU
EQU
100
101
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU 11
8
9
6
7
4
5
2
3
1
2
0
1
102
11
R12
R13
EQU 12
EQU 13
USER ABEND CODE 100 - VTOC OPEN ERROR
USER ABEND CODE 101 - OUTDD OPEN ERROR
USER ABEND CODE 102 - OUTDD CLOSE ERROR
11 BUFFERS TO BE USED
REG1 FOR DEB ADDRESS
REG2 FOR UCB ADDRESS
R14
R15
EQU 14
EQU 15
*
***********************************************************************
* SAVE AREAS *
***********************************************************************
*
SAVE DC
OPENSAVE DC
18F’0’
F’0’
MAIN PROGRAM SAVE AREA
OPEN FILES ROUTINE SAVE AREA
CLOSSAVE DC
ABENSAVE DC
IDVLSAVE DC
BUFLSAVE DC
F’0’
F’0’
F’0’
F’0’
CLOSE FILES ROUTINE SAVE AREA
ABEND ROUTINE SAVE AREA
IDNETIFY VOLUME ROUTINE SAVE AREA
INITIALIZE BUFFER ROUTINE SAVE AREA
FCL1SAVE DC
FCL2SAVE DC
FCL3SAVE DC
FCL4SAVE DC
TSTRSAVE DC
CVR1SAVE DC
CVR2SAVE DC
CVRASAVE DC
F’0’
F’0’
F’0’
F’0’
F’0’
F’0’
F’0’
F’0’
INITIALIZE FCL1 ROUTINE SAVE AREA
INITIALIZE FCL2 ROUTINE SAVE AREA
INITIALIZE FCL3 ROUTINE SAVE AREA
INITIALIZE FCL4 ROUTINE SAVE AREA
TEST RETURN CODE ROUTINE SAVE AREA
CVAFFILT READ 1 DSN ROUTINE SAVE AREA
CVAFFILT READ 2 DSN ROUTINE SAVE AREA
CVAFFILT READ ALL ROUTINE SAVE AREA
CVRLSAVE DC
CVRSSAVE DC
FMTCSAVE DC
FMTOSAVE DC
RETCODE
RCODE00
RCODE04
DSNNBR
RESFLG
BLNKLNE
STRTMSG
ENDMSG
DC
DC
DC
DC
DC
DC
DC
DC
ST64MSG1 DC
ST64MSG2 DS
F’0’
F’0’
F’0’
F’0’
CVAFFILT RLSE ROUTINE SAVE AREA
CVAFFILT RESUME ROUTINE SAVE AREA
FORMAT DSCB COUNT ROUTINE SAVE AREA
FORMAT OUTPUT ROUTINE SAVE AREA
*
***********************************************************************
* CONSTANTS *
***********************************************************************
*
F’999’
H’0’
H’4’
X’FF’
X’00’
CL133’ ’
RETURN CODE 0 - HALFWORD
RETURN CODE 4 - HALFWORD
INDICATE NBR OF DSNS TO PROCESS
RESUME FLAG - OFF
CL133’ CVAFFEXP START OF OUTPUT MESSAGES
CL133’ CVAFFEXP END OF OUTPUT MESSAGES
CL133’ RC04 VERIFIED - CVSTAT 064 RESUME IS NECESSARY ’
0CL133
’
’
Chapter 1. Using the Volume Table of Contents
119
CVAF Macros
DC
DC
ST64MSG3 DS
DC
DC
ST64MSG4 DS
DC
DC
CL49’ CVAFFILT (INITIAL) RETURNED THE FOLLOWING DSCBS ’
CL84’FOR THE VOLUME: ’
0CL133
CL49’ CVAFFILT (RESUME) RETURNED THE FOLLOWING DSCBS ’
CL84’FOR THE VOLUME:
0CL133
’
CL48’ CVAFFILT RESUME OPERATION COMPLETE - ALL DSCBS ’
CL85’RETURNED’
0CL133
CL48’ CVAFFILT RETURNED THE FOLLOWING DSCBS FOR DSN:’
DSCBMSGA DS
DC
DS DC
DC
DSCBMSGB DS
DC
DS2 DC
DC
CL44’ ’
CL41’ ’
0CL133
CL48’ AND FOR DSN:’
CL44’ ’
CL41’ ’
0CL133
CL48’ CVAFFILT LOGICAL ERROR STATUS RETURNED - DSN:’
DSCBMSGC DS
DC
DS3 DC
DC
NODSCBM DC
RC00MSG DC
RC04MSG DC
RCERMSG DC
RLSEMSG DC
DSCBMSG1 DC
DSCBMSG2 DC
DS01
DS02
DC
DC
DS03 DC
CFCLID DC
CL44’ ’
CL41’ ’
CL133’ NO DSCBS RETURNED FROM CVAFFILT
CL133’ RC00 VERIFIED - THE REQUEST WAS SUCCESSFUL
CL133’ RC04 VERIFIED - LOGICAL ERROR STATUS IN CVSTAT ’
CL133’ RC08, RC12, OR RC16 RETURNED FROM CVAFFILT ’
CL133’ NON ZERO RETURN CODE BACK FROM RLSE
CL29’ NUMBER OF FORMAT 1 DSCBS - ’
CL29’ NUMBER OF FORMAT 3 DSCBS - ’
’
’
’
CL44’CVAFFLT1.DATA01’
CL44’CVAFFLT1.DATA02’
CL44’CVAFFLT1.PDSE01’
CL4’FCL ’
***********************************************************************
* WORK AREAS *
***********************************************************************
*
WF1
WF3
DS
DS
DEBADD DC
UCBADD DC
RETF1
RETF3
DC
DC
WFMTREC DS
MSG DC
D
D
F’0’
F’0’
F’0’
F’0’
0CL133
CL29’ ’
DOUBLE WORD - FORMAT 1 WORK AREA
DOUBLE WORD - FORMAT 3 WORK AREA
DEB ADDRESS SAVE AREA
UCB ADDRESS SAVE AREA
COUNT OF FMT 1 DSCBS RET BY CVAFFILT
COUNT OF FMT 3 DSCBS RET BY CVAFFILT
WORK FORMAT RECORD FOR OUTPUT
GENERAL MESSAGE
FMTCNT DC
TOEOL DC
CL08’ ’
CL96’ ’
FORMAT COUNT
SPACES TO END OF LINE
*
***********************************************************************
* PRINT LINES *
***********************************************************************
*
DS
PDETLINE DS
0D
0CL133
DC CL133’ ’
EPDETLEN EQU *-PDETLINE
TAKE CARE OF SLACK BYTES
DETAIL LINE
LENGTH OF DETAIL LINE
*
***********************************************************************
* DCB - OUTPUT FILE (OUTFILE) *
***********************************************************************
*
OUTFILE DCB DDNAME=OUTDD,
DSORG=PS,
X
X
RECFM=FBA,
LRECL=133,
MACRF=PM
X
X
*
***********************************************************************
* 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’
JFCB1
DC
DS
TESTNAME DS
DS
DS
DS
AL3(JFCB1)
0CL176
CL44
CL8
BL1
CL123
*
***********************************************************************
* MAPPPING MACROS *
***********************************************************************
*
CVPLMAP ICVAFPL CVPLFSA=YES
FCLMAP ICVFCL
BFLMAP ICVAFBFL
CVAF PARMLIST
FILTER CRITERIA LIST
BUFFER LIST
PUSH PRINT
PRINT NOGEN
DSCBMAP DSECT
IECSDSL1 (1)
DSCBSIZ EQU *-IECSDSL1
*
*
DCBD DSORG=XE,DEVD=DA
IEZDEB
POP PRINT
DSCB DSECT
USE FMT 1 DSCB MAPPING TO GET BUFFER
LENGTH OF FULL DSCB
MAP OF DCB
MAP OF DEB
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
*
FCLDEF2 DS
FCLSIZE2 EQU *-FCLDEF2
*
*
BFLHDEF DS (BFLHLN)X
BFLEDEF DS
BFLSIZE EQU *-BFLHDEF
DEFINE A CVAF BUFFER LIST WITH
N BUFFER LIST ELEMENTS
BUFFER LIST HEADER
(BUFNBR*BFLELN)X N BUFFER LIST ELEMENTS
*
DSCBDEF DS
DEFINE A CVAF BUFFER LIST WITH
(FCLHDLEN+2*FCLDSNEL)X FCL HEADER AND TWO FCL ELEMENTS
(BUFNBR*DSCBSIZ)X
DEFINE N FULL DSCB BUFFERS
*
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:
►►
label
CVAFSEQ ACCESS= GT
GTEQ ,BUFLIST=addr ,DSN=addr
►
►
,UCB= (ucbaddr)
,DEB=addr
NO
,DSNONLY= YES
►
NOKEEP
,IOAREA= KEEP
(KEEP,addr)
(NOKEEP,addr)
,IXRCDS=
,ARG=addr
NOKEEP
KEEP
(KEEP,addr)
(NOKEEP,addr)
NO
,BRANCH= YES
(1)
(YES,SUP)
(YES,PGM)
NOTOK
,EADSCB= OK
I
,MF= 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')
8 (X'08')
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.
126
z/OS DFSMSdfp Advanced Services
CVAF Macros
Return Code
12 (X'0C')
16 (X'10')
Meaning
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.
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
LA
ST
LR
13,SAVEAREA+4
RWORK,SAVEAREA
RWORK,8(,13)
13,RWORK
*
*
************************************************************
*
REGISTERS
************************************************************
REG1 EQU 1 REGISTER 1
RWORK
RDEB
EQU
EQU
3
4
WORK REGISTER
DEB ADDRESS
RDSN1
RDSN2
EQU 6
EQU 7
ADDRESS OF DATA SET NAME 1
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
OI
BUFLIST(BFLHLN+BFLELN),BUFLIST ZERO BUFFER LIST
BFLHFL,BFLHDSCB
MVI BFLHNOE,1
LA RWORK,DS1FMTID
DSCBS TO BE READ WITH BUFFER LIST
ONE BUFFER LIST ENTRY
ADDRESS OF DSCB BUFFER
ST RWORK,BFLEBUF
MVI BFLELTH,DSCBLTH
PLACE IN BUFFER LIST
DATA PORTION OF DSCB READ - DSN
SUPPLIED IN CVPL
*
Chapter 1. Using the Volume Table of Contents
127
CVAF Macros
MVC DS1DSNAM,0(RDSN1)
XR RWORK,RWORK
CVAFSEQ DEB=(RDEB),
BUFLIST=BUFLIST,
EADSCB=OK,
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
*
*
EQU
MF=(E,CVPL)
*
LTR REG15,REG15
BZ TESTDSN
LOOP UNTIL END OF DATA OR DATA SET *
NAME GREATER THAN DSN2
ANY ERROR
BRANCH IF NOT-CHECK DSN LIMIT
************************************************************
*
DETERMINE WHAT ERROR IS
************************************************************
C REG15,ERROR4 IS RETURN CODE 4
BNE OTHERERR
CLI CVSTAT,STAT032
BRANCH IF NOT 4
IS IT END OF DATA?
*
*
BNE OTHERERR BRANCH IF NOT
************************************************************
END OF DATA
*
************************************************************
B RELEASE
TESTDSN EQU *
RELEASE CVAF RESOURCES AND RETURN
IS DATA SET NAME GREATER THAN DSN2
CLI DS1FMTID,DS1IDC
BE CKVSAM
CLI DS1FMTID,DS8IDC
BNE CKLAST
IS THIS A FORMAT 1 DSCB?
BRANCH IF FORMAT 1
IS THIS A FORMAT 8 DSCB?
BRANCH IF NO. CAN NOT BE VSAM.
CKVSAM EQU * CHECK VSAM
CLC DS1DSNAM,0(RDSN2) HAS LIMIT BEEN REACHED?
BH
TM
RELEASE BRANCH IF HIGH TO RELEASE RESOURCES
DS1DSORG+1,DS1ORGAM IS DATA SET VSAM
BZ
LA
CKLAST
RWORK,1(,RWORK)
BRANCH IF NO-DO NOT COUNT IT
INCREMENT COUNT BY ONE
CKLAST EQU * CHECK IF LAST DATA SET NAME (DSN2)
CLC DS1DSNAM,0(RDSN2) HAS LIMIT BEEN REACHED?
BNH
B
RELOOP
RELEASE
RELOOP EQU *
CVAFSEQ ACCESS=GT,
BRANCH IF NO-READ NEXT ONE
RELEASE CVAF RESOURCES AND RETURN
READ NEXT DSCB
GET DSCB WITH DATA SET NAME *
GREATER THAN THE ONE LAST READ *
LOOP
OTHERERR EQU *
*
*
B
EADSCB=OK,
MF=(E,CVPL)
CHECK RESULTS OF CVAFSEQ
UNEXPECTED ERROR
************************************************************
*
UNEXPECTED ERROR PROCESSING
************************************************************
LA RWORK,1(0,0) ONE IN RWORK
LNR RWORK,RWORK
RELEASE CVAFDIR ACCESS=RLSE,
BUFLIST=0,
IXRCDS=NOKEEP,
SET NEGATIVE COUNT INDICATING ERROR
RELEASE CVAF BUFFERS/IOAREA
DO NOT RELEASE USER BUFFER LIST
RELEASE CVAF VIER BUFFERS
*
*
*
LR
L
MF=(E,CVPL)
REG15,RWORK
13,SAVEAREA+4
RELEASE CVAF I/O AREA
CURRENT COUNT IS RETURN CODE
RETURN (14,12),RC=(15) RETURN CURRENT COUNT
ERROR4 DC F’4’
BUFLIST ICVAFBFL DSECT=NO
IECSDSL1 (1)
ERROR RETURN CODE 4
BUFFER LIST
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 CVAFSEQ ACCESS=GTEQ,
IXRCDS=KEEP,
DSN=DS1DSNAM,
BUFLIST=BUFLIST,
EADSCB=OK,
MF=L
ORG CVPL
CVPLMAP 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.
SEQUENTIAL ORDER.
IT WILL USE THE CVAFSEQ MACRO
TO READ UP TO 5 DSCBS AT A TIME IN PHYSICAL
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).
*
*
*
*
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
*
*
*
*
*
IF A SMS MANAGED NON INDEXED VOLUME IS USED THE POSITION *
*
*
*
*
*
*
*
* OUTPUT IN OUTDD DATASET SHOULD BE THE FOLLOWING:
*---------------------------------------------------------------------*
*
*
*
*
*
*
* SEQXMP2 START OF OUTPUT MESSAGES
*
*
*
*
*
* DSN: CVAFSEQ1.SEQ01
* DSN: CVAFSEQ1.SEQ02
* DSN: CVAFSEQ1.SEQ03
* DSN: CVAFSEQ1.SEQ04
* DSN: CVAFSEQ1.SEQ05
* DSN: CVAFSEQ1.SEQ06
* DSN: CVAFSEQ1.SEQ07
* DSN: CVAFSEQ1.SEQ08
CCHHR: 0CFE000003
CCHHR: 0CFE000004
CCHHR: 0CFE000005
CCHHR: 0CFE000006
CCHHR: 0CFE000007
CCHHR: 0CFE000008
CCHHR: 0CFE000009
CCHHR: 0CFE00000A
*
*
*
*
*
*
*
*
* DSN: CVAFSEQ1.SEQ09
* DSN: CVAFSEQ1.SEQ10
* DSN: CVAFSEQ1.PDS01
* DSN: CVAFSEQ1.PDS02
* DSN: CVAFSEQ1.PDS03
* DSN: CVAFSEQ1.PSD04
* DSN: CVAFSEQ1.PDS05
* DSN: CVAFSEQ1.PDSE01
CCHHR: 0CFE00000B *
CCHHR: 0CFE00000C *
CCHHR: 0CFE00000D *
CCHHR: 0CFE00000E *
CCHHR: 0CFE00000F *
CCHHR: 0CFE000010 *
CCHHR: 0CFE000011 *
CCHHR: 0CFE000012 *
130
z/OS DFSMSdfp Advanced Services
CVAF Macros
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
* DSN: CVAFSEQ1.PDSE02
* DSN: CVAFSEQ1.PDSE03
* DSN: CVAFSEQ1.PDSE04
* DSN: CVAFSEQ1.PDSE05
* DSN: CVAFSEQ1.VSAM01.DATA
* DSN: SYS1.VVDS.V339003
* DSN: CVAFSEQ1.VSAM02.DATA
*
CCHHR: 0CFE000013 *
CCHHR: 0CFE000014 *
CCHHR: 0CFE000015 *
CCHHR: 0CFE000016 *
CCHHR: 0CFE000017 *
CCHHR: 0CFE000018 *
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)
BALR R11,0
STANDARD LINKAGE CONVENTION
DCL R11 AS IMPLIED BASE REG
Chapter 1. Using the Volume Table of Contents
131
CVAF Macros
BASE
USING BASE,R11,R12
L R12,BASEADDR
B
BASEADDR DC
CVAFSQ00
A(BASE+4096)
CVAFSQ00 DS
ST
LA
ST
LR
0H
R13,SAVE+4
R14,SAVE
R14,8(,R13)
R13,R14
R12 IS ALSO BASE REG
SET UP ADDRESSING FOR R12
BRANCH AROUND DECLARES
ADDRESSING FOR R12
CONTINUE...
SAVE PTR TO CALLER’S SAVE AREA
GET ADDRESS OF THE NEW SAVE AREA
CHAIN CALLER’S AREA TO OURS
ESTABLISH THE NEW SAVE AREA
*
***********************************************************************
*
* INITIALIZATION
*
*
* *
***********************************************************************
*
INITIAL DS 0H
MVC CCHHRS,CCHHR0
INITIALIZATION SECTION
INIT CCHHR START TO ZERO
BAL R14,IDVOLRTN
BAL R14,OPENRTN
INVOKE RTN TO IDENTIFY THE VOLUME(S)
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
MVI SWEOD,NOEOD
BAL R14,LDTABRTN
BAL R14,INITBRTN
MAINLINE SECTION
SET SWITCH TO NO EOD INITIALLY
INVOKE LDTABRTN TO LOAD TABLE
INVOKE INITBRTN TO INIT BUFFER LIST
BAL R14,CVAFSRTN
BAL R14,LODCRTN
BAL R14,PRTBRTN
CLI SWEOD,EOD
BNE MAINLINE
L R15,RETCODE
CH R15,RCODE00
BNE FINAL
INVOKE CVAFSRTN TO ISSUE CVAFSEQ CALL
INVOKE LODCRTN TO LOAD CCHHR IN TBL
INVOKE PRTBRTN TO PROCESS TBL ENTRIES
DID WE REACH THE END OF DATA?
NO, PROCESS MORE DATA
LOAD R15 WITH RETURN CODE
IF RC WAS 00?
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
PUT OUTFILE,PDETLINE
MOVE EOD MSG TO LINE
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
L R13,4(R13)
INVOKE CLOSE OUTPUT DATASET RTN
RESTORE REGISTER
LM
LA
BR
R14,R12,12(R13)
R15,0
R14
RESTORE CALLERS REGISTERS
SET RC TO 0
RETURN TO CALLER
*
***********************************************************************
* OPENRTN *
132
z/OS DFSMSdfp Advanced Services
CVAF Macros
* - ROUTINE TO OPEN OUTPUT FILE USED BY THIS MODULE *
***********************************************************************
*
OPENRTN DS
ST
0H
R14,OPENSAVE
OPEN FILES ROUTINE
STORE C(R14) INTO SAVE AREA
OPEN (OUTFILE,(OUTPUT)) OPEN THE OUTDD OUTPUT FILE FOR MSGS
TM
BO
OUTFILE+(DCBOFLGS-IHADCB),DCBOFOPN IS FILE OPEN
OPENEXIT FILE OPEN OK - EXIT OPEN RTN
LA R1,EABN101
BAL R14,ABENDRTN
OUTPUT FILE NOT OPEN-USER ABEND 101
INVOKE ABEND ROUTINE
OPENEXIT DS
L
BR
0H
R14,OPENSAVE
R14
EXIT FROM OPEN ROUTINE
LOAD C(OPENSAVE) INTO R14
EXIT
*
*
*
***********************************************************************
CLOSERTN
- ROUTINE TO CLOSE OUTPUT FILE USED BY THIS MODULE
*
*
***********************************************************************
*
CLOSERTN DS
ST
0H
R14,CLOSSAVE
CLOSE FILES ROUTINE
STORE C(R14) INTO SAVE AREA
CLOSE (OUTFILE)
LTR R15,R15
BZ
LA
CLOSEXIT
R1,EABN102
BAL R14,ABENDRTN
CLOSEXIT DS 0H
CLOSE OUTPUT FILE
CHECK IF CLOSED OK
IF OK BRANCH TO CLOSEXIT
ELSE SETUP FOR USER ABEND 102
INVOKE ABEND ROUTINE
EXIT FROM CLOSE ROUTINE
L
BR
R14,CLOSSAVE
R14
LOAD C(CLOSSAVE) INTO R14
EXIT
*
***********************************************************************
*
*
ABENDRTN
- FORCE AN ABEND ROUTINE
***********************************************************************
*
*
*
ABENDRTN DS
ST
0H
R14,ABENSAVE
ABEND (R1),DUMP
ABENEXIT DS 0H
ABEND ROUTINE
STORE C(R14) INTO SAVE AREA
ISSUE USER ABEND WITH DUMP
EXIT FROM ABEND ROUTINE
L
BR
R14,ABENSAVE
R14
LOAD C(ABENSAVE) INTO R14
EXIT
*
***********************************************************************
*
*
IDVOLRTN
- OBTAIN THE NECESSARY INFORMATION FROM THE DASD VOLUME
***********************************************************************
*
*
*
IDVOLRTN DS
ST
0H
R14,IDVLSAVE
IDENTIFY VOLUME ROUTINE
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
BO
VTOCDCB+(DCBOFLGS-IHADCB),DCBOFOPN
IDVOL010
LA R1,EABN100
BAL R14,ABENDRTN
TEST FOR GOOD OPEN
BRANCH TO IDVOL010 - GOOD OPEN
ELSE SETUP FOR USER ABEND 100
INVOKE ABEND ROUTINE
IDVOL010 DS 0H
SLR RDEB,RDEB
GOOD OPEN - OBTAIN VOLUME INFORMATION
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
IDVLEXIT DS
RUCB,UCBADD
0H
SAVE UCB ADDRESS INTO R4
EXIT FROM IDVOLRTN
L
BR
R14,IDVLSAVE
R14
LOAD C(IDVLSAVE) INTO 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
ST
0H
R14,LDTBSAVE
LOAD TABLE ROUTINE
STORE C(R14) INTO SAVE AREA
LA
ST
LA
ST
LA
ST
LA
ST
R6,DSCB01
R6,TDSCB01
R6,DSCB02
R6,TDSCB02
R6,DSCB03
R6,TDSCB03
R6,DSCB04
R6,TDSCB04
LOAD R6 WITH ADDRESS OF DSCB01
STORE ADDRESS OF DSCB01 INTO TABLE
LOAD R6 WITH ADDRESS OF DSCB02
STORE ADDRESS OF DSCB02 INTO TABLE
LOAD R6 WITH ADDRESS OF DSCB03
STORE ADDRESS OF DSCB03 INTO TABLE
LOAD R6 WITH ADDRESS OF DSCB04
STORE ADDRESS OF DSCB04 INTO TABLE
LA
ST
LDTBEXIT DS
L
BR
R6,DSCB05
R6,TDSCB05
0H
R14,LDTBSAVE
R14
LOAD R6 WITH ADDRESS OF DSCB05
STORE ADDRESS OF DSCB05 INTO TABLE
EXIT FROM LDTABRTN
LOAD C(LDTBSAVE) INTO R14
EXIT
*
***********************************************************************
* INITBRTN
* - INITIALIZE THE BUFFER LIST
***********************************************************************
*
*
*
INITBRTN DS
ST
0H
R14,INITSAVE
LA R7,BUFLISTE
USING BFLE,R7
LA R8,BUFLISTH
USING BFLHDR,R8
LA R2,TABLE
USING TBLMAP,R2
INITIALIZE BUFFER LIST ROUTINE
STORE C(R14) INTO SAVE AREA
LOAD R7 WITH ADDRESS OF BUFLIST ENTRY
ESTABLISH ADDRESSABILITY TO BFLE
LOAD R8 WITH ADDRESS OF BUFLIST HDR
ESTABLISH ADDRESSABILITY TO BFLHDR
LOAD R2 WITH ADDRESS OF TABLE
ESTABLISH ADDRESSABILITY USING TBLMAP
XC
OI
BFLHDR(BFLHLN+TBLNBR*BFLELN),BFLHDR CLEAR BUFLIST
BFLHFL,BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST
MVC BFLEARG,CCHHRS
MVI BFLHNOE,TBLNBR
MOVE STARTING CCHHR TO ARG
MOVE NBR OF TBL ENTRIES TO BUFE NBR
SLR R10,R10
IC R10,BFLHNOE
ST R10,COUNT
INIT R10 WITH ZERO
NBR OF BUFFER ENTRIES IN R10
NBR OF BUFFER ENTRIES IN COUNT
*
INIT0010 DS
L
ST
0H
R6,DSCBA
INIT BUFFER LIST WITH DSCB ADDR/LENG
LOAD R6 WITH DSCB ADDRESS FROM TABLE
R6,BFLEBUF-BFLE(,R7) PLACE IN BUFFER LIST
MVI BFLELTH-BFLE(R7),DSCBLTH FULL DSCB READ
OI
LA
BFLEFL,BFLECHR
R2,TBLLNG(,R2)
CCHHR TO BE RETURNED
POINT TO NEXT TABLE ENTRY
LA R7,BFLELN(,R7)
BCT R10,INIT0010
DROP R2
INITEXIT DS 0H
POINT TO NEXT BUFFER LIST ENTRY
BRANCH TO INIT0010 IF C(R10) GT ZERO
DROP R2
EXIT FROM INITBRTN
L
BR
R14,INITSAVE
R14
LOAD C(INITSAVE) INTO 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
ST
0H
R14,CVAFSAVE
CVAFSEQ REQUEST ROUTINE
STORE C(R14) INTO SAVE AREA
L RUCB,UCBADD
CVAFSEQ UCB=(RUCB),
LOAD R4 WITH UCB ADDRESS
CVAFSEQ MACRO INVOCATION X
134
z/OS DFSMSdfp Advanced Services
CVAF Macros
ST
EADSCB=OK,
BRANCH=(YES,PGM),
MF=(E,CVPL)
R15,RETCODE
LTR R15,R15
CH
BZ
CH
BE
CH
BE
CH
BE
CH
BE
R15,RCODE00
CVAFEXIT
R15,RCODE04
CVAFSR04
R15,RCODE08
CVAFSR08
R15,RCODE12
CVAFSR12
R15,RCODE16
CVAFSR16
STORE RC INTO RETCODE
TEST RC RETURNED FROM CVAFSEQ
IS IT A RC00?
YES - BRANCH TO EXIT ROUTINE
IS IT A RC04?
YES - BRANCH TO PROCESS RC04
IS IT A RC08?
YES - BRANCH TO PROCESS RC08
IS IT A RC12?
YES - BRANCH TO PROCESS RC12
IS IT A RC16?
YES - BRANCH TO PROCESS RC16
MVC PDETLINE(133),RCERMSG ELSE FORMAT UNEXPECTED RC
PUT OUTFILE,PDETLINE WRITE A RECORD TO THE OUTPUT FILE
B
CVAFSR04 DS
CVAFEXIT
0H
EXIT ROUTINE
RETURN CODE 04
MVC PDETLINE(133),RC04MSG FORMAT RC04 MESSAGE
PUT OUTFILE,PDETLINE WRITE A RECORD TO THE OUTPUT FILE
CLI CVSTAT,STAT032
BE CVAFSS32
IS CVSTAT CODE STAT032?
YES - BRANCH TO PROCESS STAT032
MVC PDETLINE(133),STAT2MSG NO FORMAT STAT2MSG
PUT OUTFILE,PDETLINE WRITE A RECORD TO THE OUTPUT FILE
B
CVAFSS32 DS
CVAFEXIT
0H
BRANCH TO EXIT ROUTINE
CVSTAT CODE = STAT032
MVC PDETLINE(133),STAT1MSG FORMAT STAT1MSG
PUT OUTFILE,PDETLINE WRITE A RECORD TO THE OUTPUT FILE
B
CVAFSR08 DS
CVAFEXIT
0H
BRANCH TO EXIT ROUTINE
RETURN CODE 08
MVC PDETLINE(133),RC08MSG FORMAT RC08 MESSAGE
PUT OUTFILE,PDETLINE WRITE A RECORD TO THE OUTPUT FILE
B
CVAFSR12 DS
CVAFEXIT
0H
BRANCH TO EXIT ROUTINE
RETURN CODE 12
MVC PDETLINE(133),RC12MSG FORMAT RC12 MESSAGE
PUT OUTFILE,PDETLINE WRITE A RECORD TO THE OUTPUT FILE
B
CVAFSR16 DS
CVAFEXIT
0H
BRANCH TO EXIT ROUTINE
RETURN CODE 16
MVC PDETLINE(133),RC16MSG FORMAT RC16 MESSAGE
PUT OUTFILE,PDETLINE WRITE A RECORD TO THE OUTPUT FILE
CVAFEXIT DS
L
BR
0H
R14,CVAFSAVE
R14
EXIT FROM CVAFSRTN
LOAD C(CVAFSAVE) INTO R14
EXIT
*
***********************************************************************
* LODCRTN *
* - LOAD CCHHR FROM BUFFER LIST ENTRY INTO PROCESSING TABLE.
THIS *
* VALUE RETURNED FROM CVAFSEQ CALL.
*
***********************************************************************
*
LODCRTN DS
ST
0H
R14,LODCSAVE
DROP R7,R8
LOAD CCHHR INTO PROCESSING TABLE
STORE C(R14) INTO SAVE AREA
DROP R7 AND R8
LOAD R7 WITH ADDRESS OF BUFLIST ENTRY LA R7,BUFLISTE
USING BFLE,R7
LA R2,TABLE
ESTABLISH ADDRESSABILITY TO BFLE
LOAD R2 WITH ADDRESS OF TABLE
ESTABLISH ADDRESSABILITY USING TBLMAP
LOAD R10 WITH TABLE ENTRY COUNT
USING TBLMAP,R2
L R10,COUNT
*
LODC0010 DS
LA
ST
LA
LA
0H
R8,BFLEARG
R8,CCHHRA
R2,TBLLNG(,R2)
R7,BFLELN(,R7)
BCT R10,LODC0010
DROP R2,R7
PROCESS CCHHR VALUE RETURNED
LOAD R8 WITH ADDRESS OF BFLEARG
STORE CCHHR VALUE INTO TABLE
POINT TO NEXT TABLE ENTRY
POINT TO NEXT BUFFER LIST ENTRY
BRANCH TO LODC0010 IF C(R10) GT ZERO
DROP R2 AND R7
X
X
Chapter 1. Using the Volume Table of Contents
135
CVAF Macros
LODCEXIT DS
L
BR
0H
R14,LODCSAVE
R14
EXIT FROM LODCRTN
LOAD C(LODCSAVE) INTO 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
ST
L
LA
0H
R14,PRTBSAVE
R10,COUNT
R2,TABLE
PROCESS TABLE ENTRIES (DSCBA/CCHHRA)
STORE C(R14) INTO SAVE AREA
LOAD COUNT IN R10
LOAD ADDRESS OF TABLE INTO R2
USING TBLMAP,R2
PRTB0000 DS 0H
L
L
R3,DSCBA
R4,CCHHRA
CLC 0(1,R3),FMT4
BE PRTB0020
CLC 0(1,R3),FMT5
BE PRTB0020
ESTABLISH ADDRESSABILITY TO TABLE
PROCESS ENTRIES
ADDRESSABILITY TO DSCBA
ADDRESSABILITY TO CCHHRA
IS IT A FMT4?
YES, BRANCH TO POINT TO NEXT ENTRY
IS IT A FMT5?
YES, BRANCH TO POINT TO NEXT ENTRY
CLC 0(1,R3),FMT7
BE PRTB0020
CLC 0(1,R3),FMT9
BE PRTB0020
IS IT A FMT7?
YES, BRANCH TO POINT TO NEXT ENTRY
IS IT A FMT9?
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
MVI SWEOD,EOD
NO, THEN CONTINUE TO PROCESS DSN
YES, SET SWITCH TO END OF DATA
B
PRTB0010 DS
PRTBEXIT
0H
EXIT OUT OF ROUTINE
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
LA
0H
R2,TBLLNG(R2)
BCT R10,PRTB0000
PRTBEXIT DS 0H
INCREMENT COUNTER FILEEDIT
POINT TO NEXT TABLE ENTRY
BRANCH TO PRTB0000 IF C(R10) GT ZERO
EXIT FROM PRTBRTN
L
BR
R14,PRTBSAVE
R14
LOAD C(PRTBSAVE) INTO R14
EXIT
*
***********************************************************************
* WORKING STORAGE *
***********************************************************************
*
DS
DC
0D
CL36’SEQXMP2-WORKING STORAGE BEGINS HERE’
*
***********************************************************************
* EQUATES *
***********************************************************************
*
USER ABEND CODE 100-VTOC OPEN ERROR
USER ABEND CODE 101-OUTDD OPEN ERROR
USER ABEND CODE 102-OUTDD CLOSE ERROR
EABN100 EQU 100
EABN101 EQU 101
EABN102 EQU 102
R0 EQU 0
R1
RDEB
R2
R3
R4
RUCB
EQU
EQU
EQU
EQU
EQU
EQU
1
1
2
3
4
4
REG1 FOR DEB ADDRESS
REG4 FOR UCB ADDRESS
136
z/OS DFSMSdfp Advanced Services
CVAF Macros
R5
R6
R7
R8
R9
R10
R11
R12
EQU 5
EQU 6
EQU 7
EQU 8
EQU 9
EQU 10
EQU 11
EQU 12
R13
R14
R15
*
EQU
EQU
EQU
13
14
15
***********************************************************************
* SAVE AREAS *
***********************************************************************
*
SAVE DC
OPENSAVE DC
CLOSSAVE DC
ABENSAVE DC
IDVLSAVE DC
LDTBSAVE DC
INITSAVE DC
PRTBSAVE DC
CVAFSAVE DC
LODCSAVE DC
*
18F’0’
F’0’
F’0’
F’0’
F’0’
F’0’
F’0’
F’0’
F’0’
F’0’
MAIN PROGRAM SAVE AREA
OPEN FILES ROUTINE SAVE AREA
CLOSE FILES ROUTINE SAVE AREA
ABEND ROUTINE SAVE AREA
IDENTIFY VOLUME ROUTINE SAVE AREA
LOAD TABLE ROUTINE SAVE AREA
INIT BUFFER ROUTINE SAVE AREA
PROCESS TABLE ROUTINE SAVE AREA
CVAFSEQ REQUEST ROUTINE SAVE AREA
LOAD CCHHR ROUTINE SAVE AREA
***********************************************************************
* CONSTANTS *
***********************************************************************
*
RETCODE DC
RCODE00 DC
RCODE04 DC
RCODE08 DC
F’0’
H’0’
H’4’
H’8’
RETURN CODE SAVE FIELD
RETURN CODE 0 - HALFWORD
RETURN CODE 4 - HALFWORD
RETURN CODE 8 - HALFWORD
RCODE12
RCODE16
CCHHR0
FMT4
FMT5
FMT7
FMT9
NODSN
BLNKLNE
STRTMSG
ENDMSG
RC00MSG
RC04MSG
RC08MSG
RC12MSG
RC16MSG
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
H’12’
H’16’
XL5’0000000000’
XL1’04’
XL1’05’
XL1’07’
XL1’09’
XL1’00’
CL133’ ’
CL133’ SEQXMP2 START OF OUTPUT MESSAGES
CL133’ SEQXMP2 END OF OUTPUT MESSAGES
CL133’ RC00 RETURNED FROM SEQXMP2
’
’
CL133’ RC04 RETURNED FROM SEQXMP2
CL133’ RC08 RETURNED FROM SEQXMP2
CL133’ RC12 RETURNED FROM SEQXMP2
CL133’ RC16 RETURNED FROM SEQXMP2
CL133’ UNEXPECTED RC (??) RETURNED FROM SEQXMP2
CL133’ CVSTAT CODE STAT032 ENCOUNTERED
CL133’ UNEXPECTED CVSTAT CODE RETURNED FROM SEQXMP2
CL133’ END OF DATA REACHED - ALL DATA SETS PROCESSED ’
’
’
’
’
’
’
’
’
0CL133
CL6’ DSN: ’
CL44’ ’
CL7’CCHHR: ’
CL10’ ’
CL66’ ’
RETURN CODE 12 - HALFWORD
RETURN CODE 16 - HALFWORD
INIT WITH ZERO
FMT4?
FMT5?
FMT7? (ONLY CERTAIN DEVICE TYPES)
FMT9? (ONLY CERTAIN DEVICE TYPES)
END OF DATA?
RCERMSG DC
STAT1MSG DC
STAT2MSG DC
EODMSG DC
MSG1 DS
DC
DSNMSG DS
DC
CCHHRM DS
DC
***********************************************************************
* WORK AREAS *
***********************************************************************
*
BUFLST DS
BUFLISTH DC
0F
2F’0’
BUFFER LIST WORK AREA
BUFFER LIST HEADER
Chapter 1. Using the Volume Table of Contents
137
CVAF Macros
BUFLISTE DC
*
UCBADD DC
DEBADD DC
COUNT DC
DS
DSCB01 DS
DSCB02 DS
DSCB03 DS
DSCB04 DS
15F’0’
F’0’
F’0’
F’0’
D
XL140
XL140
XL140
XL140
XL140
5 BUFFER LIST ENTRIES
UCB ADDRESS SAVE AREA
DEB ADDRESS SAVE AREA
TABLE COUNTER
DSCB01 BUFFER AREA
DSCB02 BUFFER AREA
DSCB03 BUFFER AREA
DSCB04 BUFFER AREA
DSCB05 BUFFER AREA DSCB05 DS
*
CCHHRS DC
*
XL5’0000000000’ STARTING CCHHR
***********************************************************************
* PRINT LINES *
***********************************************************************
*
DS
PDETLINE DS
0D
0CL133
DC CL133’ ’
EPDETLEN EQU *-PDETLINE
DETAIL LINE
LENGTH OF DETAIL LINE
*
***********************************************************************
* DCB - OUTPUT FILE (OUTFILE) *
***********************************************************************
*
OUTFILE DCB DDNAME=OUTDD,
DSORG=PS,
RECFM=FBA,
LRECL=133,
MACRF=PM
*
***********************************************************************
* VTOC DCB AREA *
***********************************************************************
X
X
X
X
*
VTOCDCB DCB DDNAME=CVAFDD,MACRF=E,EXLST=XLST1,DSORG=PS,DCBE=VTOCDCBE
XLST1 DC
DC
X’87’
AL3(JFCB1)
JFCB1 DS
TESTNAME DS
DS
DS
0CL176
CL44
CL8
BL1
DS CL123
VTOCDCBE DCBE EADSCB=OK
*
***********************************************************************
* TABLES *
***********************************************************************
*
TABLE DC 0H START OF TABLE DSCB ADDR / CCHHR ADDR
*
TDSCB01 DS
TCHR01 DS
F’0’
F’0’
*
TBLLNG EQU *-TABLE
DSCB01 ADDRESS (140 BYTE DSCB)
CCHHR ADDRESS FOR DSCB01 - RETURNED
LENGTH OF TABLE ENTRY
*
TDSCB02 DS
TCHR02 DS
*
TDSCB03 DS
TCHR03 DS
*
TDSCB04 DS
TCHR04 DS
*
F’0’
F’0’
F’0’
F’0’
F’0’
F’0’
DSCB02 ADDRESS (140 BYTE DSCB)
CCHHR ADDRESS FOR DSCB02 - RETURNED
DSCB03 ADDRESS (140 BYTE DSCB)
CCHHR ADDRESS FOR DSCB03 - RETURNED
DSCB04 ADDRESS (140 BYTE DSCB)
CCHHR ADDRESS FOR DSCB04 - RETURNED
138
z/OS DFSMSdfp Advanced Services
CVAF Macros
TDSCB05 DS
TCHR05 DS
F’0’
F’0’
DSCB05 ADDRESS (140 BYTE DSCB)
CCHHR ADDRESS FOR DSCB05 - RETURNED
*
TBLNBR EQU (*-TABLE)/TBLLNG NBR OF TABLE ENTRIES
*
**********************************************************************
* TABLES (CONT) *
**********************************************************************
*
TCHAR1 EQU
DC
*-C’0’
C’0123456789ABCDEF’
TABLE TO TRANSLATE TO PRINTABLE HEX
*
**********************************************************************
* SWITCHES *
**********************************************************************
SWEOD
EOD
DC
EQU
XL1’00’
X’FF’
SWITCH - END OF DATA ?
END OF DATA DETECTED
NOEOD
*
EQU X’00’ END OF DATA NOT DETECTED
**********************************************************************
* DSECTS *
**********************************************************************
TBLMAP DSECT DUMMY CONTROL SECTION FOR TABLE MAP
DSCBA DS
CCHHRA DS
F
F
DSCB ADDRESS ENTRY
CCHHR ADDRESS ENTRY
*
**********************************************************************
* MACROS / INCLUDES *
**********************************************************************
DCBD DSORG=XE,DEVD=DA
IEZDEB
MAP OF DCB
MAP OF DEB
DSCB
DSCBLTH
ICVAFBFL
DSECT
IECSDSL1 (1)
EQU *-IECSDSL1
BUFFER LIST WITH ONE ENTRY
FORMAT 1 DSCB
LENGTH OF DSCB
*
**********************************************************************
* CVAF PARAMETER LISTS *
**********************************************************************
*
SEQXMP2 CSECT
CVPL CVAFSEQ ACCESS=GT, CVAFSEQ MACRO REQUEST
BUFLIST=BUFLISTH, ADDRESS OF BUFFER LIST
CVPLMAP ICVAFPL DSECT=NO
*
*
MF=L
ORG CVPL
END SEQXMP2
CVAF PARM LIST MAP
END OF SEQXMP2
X
X
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:
►►
label
CVAFTST UCB=(reg) ►◄
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')
4 (X'04')
8 (X'08')
12 (X'0C')
16 (X'10')
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.
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:
►►
label
SCRATCH
listname_addrx
►◄
►►
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 0,0
SCRATCH 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
DC
DC
DC
DC
DC
CAMLST SCRATCH,DSABC,,VOLIST,,OVRD
DC CL44’A.B.C’ DATA SET NAME
DC
DC
H’2’
X’3030200E’
NUMBER OF VOLUMES
3380 DISK DEVICE CODE
CL6’000017’
H’0’
X’3030200E’
CL6’000018’
H’0’
VOLUME SERIAL NO.
SCRATCH STATUS CODE
3380 DISK DEVICE CODE
VOLUME SERIAL NO.
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
0(0)
1(1)
Length or Bit Pattern
1
1
.1.. ....
2(2) x.xx xxxx
1
1... ....
.10. ...0
...1 ....
.... 1...
Description
Flags. Always X'41'.
Flags.
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.
Reserved.
Flags.
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.
Always set for SCRATCH.
OVRD coded on CAMLST.
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.
148
z/OS DFSMSdfp Advanced Services
Managing the VTOC
Table 22. SCRATCH Parameter List (continued)
Offset Length or Bit Pattern
.... .1..
3(3)
4(4)
8(8)
12(C)
.... ..1.
1
4
4
4
Description
Erase all allocated space for the data set.
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.
Reserved.
Address of 44-byte data set name.
Reserved.
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
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
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')
004 (X'04')
008 (X'08')
012 (X'0C')
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: 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')
2 (X'02')
3 (X'03')
4 (X'04')
5 (X'05')
6 (X'06')
7 (X'07')
8 (X'08')
9 (X'09')
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.
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
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.
150
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
RENAME and CAMLST Macro Specification
The format of the RENAME and CAMLST macros is:
►►
label
RENAME
listname_addrx
Managing the VTOC
►◄
►►
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
SET REG 0 TO ZERO
CHANGE DATA SET
NAME A.B.C TO D.E.F
DSABC CAMLST RENAME,OLDNAME,NEWNAME,VOLIST
OLDNAME DC CL44’A.B.C’ OLD DATA SET NAME
NEWNAME DC
VOLIST DC
CL44’D.E.F’
H’2’
NEW DATA SET NAME
TWO VOLUMES
DC
DC
DC
DC
DC
DC
X’3030200E’
CL6’000017’
H’0’
X’3030200E’
CL6’000018’
H’0’
3380 DISK DEVICE CODE
VOLUME SERIAL NO.
RENAME STATUS CODE
3380 DISK DEVICE CODE
VOLUME SERIAL NO.
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
0(0)
1(1)
2(2)
3(3)
4(4)
8(8)
12(C)
Length or Bit Pattern
1
1
.1.. ....
..1. ....
x..x xxxx
1
..1. ....
...1 ....
xx.. xxxx
1
4
4
4
Description
Flags. Always X'C1'
Flags.
Do not define RACF profile.
Do not update the changed bit
(DS1DSCHA) in the format 1 DSCB.
Reserved.
Flags.
Always set for RENAME.
See “Renaming a Data Set That Might be in
Reserved.
Reserved.
Address of 44-byte existing data set name.
Address of 44-byte new data set name.
Address of volume list.
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
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')
004 (X'04')
008 (X'08')
012 (X'0C')
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: 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')
1 (X'01')
2 (X'02')
3 (X'03')
4 (X'04')
5 (X'05')
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: 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.
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.
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')
8 (X'08')
9 (X'09')
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.
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:
►►
label
LOCATE
listname_addrx
►◄
158
z/OS DFSMSdfp Advanced Services
►►
listname
CAMLST NAME ,dsname_relexp ,area_relexp
CATALOG Macros
►◄
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
*
*
*
Check Return Codes
INDAB
AB
CAMLST
DC
LOCAREA DS
DS
NAME,AB,,LOCAREA
CL44’A.B’
0D
265C
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
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:
►►
label
LOCATE
list_addrx
►◄
►►
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
*
*
*
Check Return Codes
INDGX
APAY
CAMLST
DC
LOCAREA DS
DS
NAME,APAY,,LOCAREA
CL44’A.PAY(-3)’
0D
265C
READ CATALOG ENTRY
FOR DATA SET A.PAY(-3)
INTO YOUR STORAGE
AREA NAMED LOCAREA
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:
►►
label
LOCATE
list_addrx
►◄
►►
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.
INDAB
ABC
LOCAREA
Check Return Codes
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')
12 (X'0C')
16 (X'10')
20 (X'14')
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
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:
►►
label
CATALOG
list_addrx
►◄
►►
listname
CAMLST CAT
CATBX
►
,DSCBTTR=dscb_ttr_relexp
,name_relexp ,vol_list_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
Check Return Codes
ADDABC
DSNAME
CAMLST
DC
VOLUMES DC
DC
DC
DC
DC
DC
DC
CATALOG DATA SET A.B.C.
CAT,DSNAME,,VOLUMES
CL6’A.B.C’ ONE BLANK FOR DELIMITER
H’2’
X’3010200E’
CL6’000014’
H’0’
DATA SET ON TWO VOLUMES
3380 DISK DEVICE CODE
VOLUME SERIAL NUMBER
DATA SET SEQUENCE NUMBER
X’3010200E’
CL6’000015’
H’0’
3380 DISK DEVICE CODE
VOLUME SERIAL NUMBER
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:
►►
label
CATALOG
list_addrx
►◄
►►
listname
CAMLST UNCAT
UCATDX
,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
*
Check Return Codes
REMOVE CAMLST
DSNAME DC
UNCAT,DSNAME
CL6’A.B.C’
REMOVE REFERENCES TO DATA SET A.B.C
FROM CATALOG
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:
►►
label
CATALOG
list_addrx
►◄
►►
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 CAMLST
DSNAME DC
VOLUMES DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
RECAT,DSNAME,,VOLUMES
CL6’A.B.C ’ FOR DELIMITER ONE BLANK
H’3’
X’3010200E’
THREE VOLUMES
3380 DISK DEVICE CODE
CL6’000014’
H’0’
X’3010200E’
CL6’000015’
VOLUME SERIAL NUMBER
SEQUENCE NUMBER
3380 DISK DEVICE CODE
VOLUME SERIAL NUMBER
H’0’
X’3010200E’
CL6’000016’
H’0’
SEQUENCE NUMBER
3380 DISK DEVICE CODE
VOLUME SERIAL NUMBER
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')
20 (X'14')
28 (X'1C')
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.
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
Function
Program state and key
EXCP
Characteristics
Any protection key, supervisor or problem state.
No
EXCPVR
Characteristics
Protection keys 0-7, supervisor state, or
APF authorized.
Yes User responsible for translating their channel program
CCW formats supported
Virtual IDAW supported
MIDAWs supported
High Performance FICON
® for System z
(zHPF) channel programs supported
User can modify channel program during execution
Self modifying channel programs supported
0 and 1
Yes
No
Yes
No
No
0 and 1
No
Yes
Yes
Yes, non-zHPF only
Yes, non-zHPF only
Yes
Yes
EXCP V=R
Characteristics
Protection keys 0-7, supervisor state, or
APF authorized.
No translation required.
0 and 1
No
No
No
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.
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
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
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
EXCP format 0
EXCP format 1
EXCPVR format 0
EXCPVR format 1
Channel Program
Component
CCW
IDAL
I/O Buffer
CCW
IDAL
I/O Buffer
CCW
IDAL
MIDAL
I/O Buffer
CCW
IDAL
MIDAL
I/O Buffer
Virtual storage location
24-bit
24-bit v 24-bit if pointed to by
CCW v 31 or 64-bit if pointed to by an IDAW
31-bit
31-bit v 31-bit if pointed to by
CCW v 31 or 64-bit if pointed to by an IDAW or MIDAW
24-bit
24-bit
24-bit v 24-bit if pointed to by
CCW v 31 or 64-bit if pointed to by an IDAW or MIDAW
31-bit
31-bit
31-bit v
31-bit if pointed to by
CCW v 31 or 64-bit if pointed to by an IDAW or MIDAW
Central storage location
Any
Any
Any
Any
Any
Any
24-bit
24-bit
24-bit v 24-bit if pointed to by
CCW v 31 or 64-bit if pointed to by an IDAW or MIDAW
31-bit
31-bit
31-bit v
31-bit if pointed to by
CCW v 31 or 64-bit if pointed to by an IDAW or MIDAW
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.
TCW
TCCB
TCA header
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.
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
EXCP
EXCPVR
Channel Program
Component
TCW
TCCB
TIDAL
I/O Buffer
TCW
TCCB
TIDAL
I/O Buffer
Virtual storage location
31-bit
Any
Any
Any
31-bit
Any
Any
Any
Central storage location
Any
Any
Any
Any
31-bit
Any
Any
Any
Comparing CCW and zHPF channel programs
Table 34. Comparing CCW and zHPF channel programs
Function
Devices supported
CCW channel programs
All
zHPF channel programs
DASD only
176
z/OS DFSMSdfp Advanced Services
Table 34. Comparing CCW and zHPF channel programs (continued)
Function
Processors supported
CCW channel programs
All
zHPF channel programs
EXCP and EXCPVR are only supported on a zEnterprise
®
196 (z196) zEnterprise 114
(z114) or higher processor
Subset of DASD commands Command set All commands for all currently supported devices
No limit Maximum channel program size
Maximum data transferred per CCW or TCW
64 KB-1
Read and write commands in the same channel program
Yes
Skip on read
Indirect addressing
Data Chaining
CCW or MIDAW skip bit
IDAL, MIDAL
Yes
Yes
240 bytes because of the TCA size limit
64 KB, 2 MB, or 4 GB, depending on the processor
No
TIDAW skip bit
TIDAL
No, but TIDAL is equivalent to data chaining.
No Status modifier/search commands
Program controlled interrupt
(PCI)
Append to running channel program
Self-modifying channel programs
VIO data sets
Yes
Yes
Yes
Yes
No
No
No
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
0
Command
Code
7 8
Address of the IDAL
X4
Byte Count
31 32 39 40 47 48
IDAL
0
4
8
First indirect data address word
Second indirect data address word
Subsequent indirect data address word
63
Format 1 CCW
0
Command
Code
7 8
X4
15 16
Byte Count
31 32
Address of the IDAL
IDAL
0
4
8
First indirect data address word
Second indirect data address word
Subsequent indirect data address word
63
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
1
2
4095
4096
4097
4098
Maximum number of IDAWs
1
2
2
2
2
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.
1000x 1000x
TCW TCW
2000x 2000x
3000x
4000x
TIDAW (4K)
TIDAW (4K)
TIDAW (4K)
TIDAW (4K)
3000x
4000x
User channel program
Translated 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
input count=24K
TCW
input count=24K
TIDAL@=nnnnnnn4x
TIDAW (12K)
TIDAW (8K)
TIDAW (4K)
1000x
2000x
3000x
7400x
8400x
F800x
TIDAL@=nnnnnnn4x
TIDAW (4K)
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
User 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
Version
EXCPVR supported
Incorrect length supported
Other processor & z/OS flags
Max transfer size
Device capabilities
IECDZHPF
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
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
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:
►►
label
EXCP
iob_addr
►◄
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:
►►
label
EXCPVR
iob_addr
►◄
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
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#
3
4
1
2
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
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 DC
DC
Seek DC
Search DC
CCW X’47’,LRArea,X’60’,L’LRArea Locate Record
CCW X’86’,Data,X’60’,L’Data Read Data
CCW X’92’,Search,X’60’,L’Search Read Count
CCW X’22’,Sector,X’20’,1 Read Sector for this count
Sector DC
Data DC
0XL16
X’06010002’
X’xxxxxxxx’
X’xxxxxxxxxx’
X’FF0000’
----
Area for Locate Record command
Operation, auxiliary, block count (2)
CCHH for seek
Search argument
Sector and transfer length factor
190
z/OS DFSMSdfp Advanced Services
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.
0
1
4
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
5
DCBOFLWR
DCBOFLRB
DCBOFPPC
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:
►◄ ►►
label
EOV
dcb_addr
24
,MODE= 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
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
40
(TIOT)
44
(IFLGS)
48
(OFLGS)
52
OPTCD
56
Reserved
60
EOEA
64
SIOA
68
XENDA
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.
20
BUFNO
BUFCB
24
BUFL
28
IOBAD
32
BFTEK,
BFALN
36
RECFM
EODAD
EXLST
DSORG
Device
Dependant
Common
Interface
Foundation
Block
Extension
MACRF
(DEB Address)
Reserved
Reserved
PCIA
CENDA
Reserved
Foundation
Block
EXCP
Interface
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.. ....
..11 ....
.... 11..
DCBIFPEC
DCBIFPCT
DCBIFIOE
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.
Channel 9 or 12 code detected on printer. Corresponds to
DCBIFC9 and DCBIFC12 in DCBMACR before OPEN.
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
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.
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
PS
PO
DA
DCB Format:
QSAM or BSAM
BPAM
BDAM
When writing in a partitioned or sequential DASD data set, you can cause
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
DCBH1
DCBH0
Bit
X'80'
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
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
³ DCBTRTCH ³ (DCBDEVT) ³ DCBDEN
³ 19
³
³
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
┌────────────┬────────────────────────────────────┐
³ 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 ³
³ DCBSTACK ³
Reserved ³
³
└────────────┴──────────────────────────────────────┘
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 PE—phase encoded recording GCR—group coded recording
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
COMP
NOCOMP
Tape recording technique
Record data in compacted format.
Record data in standard uncompacted format.
T
For 7-track magnetic tape, the tape recording technique:
C
E
Value
COMP
Tape recording technique
Record data in compacted format.
Data conversion feature is available.
Even parity is used. (If omitted, odd parity is assumed.)
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
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
4
IEDBVERS
5
IEDBFLG1
6
IEDBCOD
7
RESERVED
8-39
IEDBSNS
40-43
RESERVED
44-47
IEDB2CSW
48-55
IEDBFSA
48-55
Reserved
Table 40. IEDB Structure Mapping
Offset
0 (X'0')
4 (X'4')
4
1
Length or
Bit Pattern Name
IEDBID
IEDBVERS
5 (X'5') 1
1... ....
.1.. ....
..xx xxxx
Figure 20. Format of an IEDB, Mapped by the IOSDIEDB Macro
IEDBFLG1
IEDBBDSN
IEDBFSAV
Description
Eye catcher. Must be "IEDB"
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.
Flags field.
The sense data is invalid and begins with X'10FE'.
The failing storage address (IEDBFSA) is valid.
Reserved.
210
z/OS DFSMSdfp Advanced Services
Table 40. IEDB Structure Mapping (continued)
Offset
Length or
Bit Pattern Name Description
6 (X'6') 1 IEDBCOD
IEDB2CSW
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')
8 (X'8')
1
32
1
IEDBSNS
IEDBSNS00
Reserved.
Sense bytes.
Sense byte 0.
9 (X'9') 1 IEDBSNS01 Sense byte 1.
(Fields IEDBSNS02 to IEDBSNS31 define sense bytes 2 to 31.)
40(X'28')
44(X'2C')
4
4
48(X'30')
56(X'38')
8
40
IEDBFSA
Reserved.
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.
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.
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)
IOBFLAG1
4(4)
IOBECBCC
8(8)
1(1)
IOBFLAG2
2(2)
IOBSENS0
IOBECBPB
3(3)
IOBSENS1
IOBFLAG3 and IOBCSW - format depends on channel program.
See related figures below.
All
Devices
16(10)
IOBSIOCC
20(14)
IOBFLAG4
IOBSTRTB
IOBDCBPT
24(18)
IOBRESTR
IOBRESTR+1
28(1C)
IOBINCAM
IOBERRCT
32(20)
IOBSEEK
(first byte, M)
Direct Access, Teleprocessing, and Graphic Devices
33(21)
IOBSEEK
(second through eight bytes,
BBCCHHR)
Direct
Access
Storage
Devices
(DASD)
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)
IOBFLAG3
12(C)
IOBUSTAT IOBCSTAT
IOBCMDA
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
4
IEDBVERS
5
IOBEFLG1
6
IOBEFLG2
7
IOBEERPM
8-11
IOBEUSER,IOBEUPTR
12-15
IOBEIEDB
16
IOBEFLG3
17-47
RESERVED
Figure 25. Format of an IOBE, mapped by the IOSDIOBE macro
Table 41. IOBE Structure Mapping
Offset
0 (X'0')
4 (X'4')
5 (X'5')
1
1
Length or
Bit Pattern Name
4 IOBEID
IOBEVERS
IOBEFLG1
Description
Eye catcher ("IOBE")
Version number (X'01')
Reserved.
Chapter 4. Executing Your Own Channel Programs
217
Table 41. IOBE Structure Mapping (continued)
Offset
6 (X'6')
Length or
Bit Pattern Name
1
1... ....
IOBEFLG2
IOBEMIDA
Description
Flag field 2. Set by issuer of EXCP or EXCPVR.
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.
7 (X'7')
.1.. ....
..1. ....
...1 ....
.... 1...
.... .1..
.... ..1.
.... ...1
1
1.......
.xxx xxxx
IOBEP
IOBECPNM
IOBEEIDA
IOBEPCIS
IOBNORWS
IOB2CSWS
IOBEFMT1
IOBEERPM
IOBEPMSG
This bit must set to zero if you are using a zHPF channel program.
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.
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.
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.
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.
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.
This bit must set to zero if you are using a zHPF channel program.
Mask indicating the functions the ERP is allowed to perform.
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.
Reserved.
218
z/OS DFSMSdfp Advanced Services
Table 41. IOBE Structure Mapping (continued)
Offset
8 (X'8')
12 (X'C')
16 (X'10')
17 (X'11')
18 (X'12')
19(X'13')
.xxx xxxx
20(X'14')
24(X'18')
26(X'1A')
27(X'1B')
4
2
.1.. ....
1
1
IOBECacheMiss
Reserved.
IOBEResCount
IOBEDCWOffset
IOBEDDPC_RC
IOBEDDPC_RCQ
This bit must be set to zero for CCW channel programs.
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.
For zHPF channel programs, this field contains the residual count. This field is valid only if IOBEResCountValid is on.
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.
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.
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
28(X'1C')
Length or
Bit Pattern Name
1 IOBERCOD
29(X'1D') 19
Description
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
Completion code byte
Bit 0
Bit 1
Byte 1 Bytes 2 and 3
Reason code Undefined
Wait
Complete
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.
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.
220
z/OS DFSMSdfp Advanced Services
44
45
48
4B
4F
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.
A program check or machine check occurred in IOS while processing the I/O request.
The channel program was purged.
An error occurred during tape repositioning that was requested by the tape ERP.
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.
Normal I/O completion, but does not appear in the ECB.
7F
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
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
Table 42. EXCP Appendages
Appendage Description When Called
ABE
CHE
EOE
PCI
PGFX
SIO
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
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.
3
4
1
2
6
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.
Points to the request queue element.
Points to the input/output block.
Points to the data extent block.
Points to the data control block.
7
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.
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
222
z/OS DFSMSdfp Advanced Services
13
14
15
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.
Points to a 16-word area you can use to save input registers or data.
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
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 Reg 15
Available Work Registers
Reg. 10, 11, 12, and 13
SIO
PCI
PGFIX
CHE
Reg 15
Reg 15
Reg 15+4
Reg 15
Returns
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 v Reg 14 + 0 - Normal v Reg 14 + 0 - Normal v Reg 14 + 0 - Normal v Reg 14 + 4 - Skip v Reg 14 + 8 - Re-EXCP v Reg 14 + 12 - By pass
Reg. 10, 11, and 13
Reg. 10, 11, 12, and 13
Reg. 10, 11, and 13
Reg. 10, 11, 12, and 13
Chapter 4. Executing Your Own Channel Programs
223
Table 43. Entry Points, Returns, and Available Work Registers for Appendages (continued)
Appendage Entry Point Returns Available Work Registers
ABE Reg 15 v Reg 14 + 0 - Normal v Reg 14 + 4 - Skip v Reg 14 + 8 - Re-EXCP v
Reg 14 + 12 - By pass
Reg. 10, 11, 12, and 13
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:
//
//
//SYSPRINT
//SYSUT2
JOB
EXEC
DD
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:
//
//
//SYSPRINT
//SYSUT2
JOB. . .
EXEC
DD
DD
//SYSIN DD
./ ADD NAME=IEAPP00
PCIAPP Y1,
EOEAPP WA,
SIOAPP X1,
CHEAPP Z3,Z4,
ABEAPP Z2,Z4
./ ENDUP
/*
PGM=IEBUPDTE,PARM=’NEW’
SYSOUT=A
DSN=SYS1.PARMLIB,DISP=SHR
*
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 address of area
³ 0³
³ ³
Ending virtual 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
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
1
2
3–8
9–12
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
R
n
The track number relative to the beginning of the data set
The block identification on that track
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
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
BB
CC
HH
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)
Two bytes of zeros
Low order 16 bits of the cylinder number. The cylinder number is 28 bits on all currently supported DASD.
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
14
15
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.
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')
8 (X'08')
12(X'0C')
16 (X'10')
20 (X'14')
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.
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
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
1
2
3–8
9–13
14
15
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.
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')
8 (X'08')
12(X'0C')
16 (X'10')
20 (X'14')
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.
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
1
2
Table 48. Registers and Their Use for A Sector Convert Routine
Register Use
0
3-8
9-10
11
12,13
14
15
K
R
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
A 1-byte field containing the key length
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
I
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.
A 1-byte key indicator (1 for keyed records, 0 for records without keys)
R
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:
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.
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
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
label
► ,length_value , ,blkref_addr
(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
Indicates which extent entry in the data extent block is associated with the direct access program
242
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 CCW Command Code
Read by identification
Verify by identification
Read by key
Verify by key
Write by identification 1
2
2
3
3
1
1
2
Search ID Equal
Transfer in Channel
Read Key and Data
Search Key Equal
Transfer in Channel
Read Data
Search ID Equal
Transfer in Channel
Write by key
2
3
3
1
Write Key and Data
Search Key Equal
Transfer in Channel
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
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 Add an entry to the PASSWORD data set v Replace an entry in the PASSWORD data set v Delete an entry from the PASSWORD data set v 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:
1. PWREAD/PWWRITE or
PWREAD/NOWRITE
2. NOPWREAD/PWWRITE
Secondary password must be:
PWREAD/PWWRITE or
PWREAD/NOWRITE
NOPWREAD/PWWRITE
252
z/OS DFSMSdfp Advanced Services
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:
►►
label
PROTECT
parameter_list_address
►◄
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')
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')
2
40 (X'28')
2
44 (X'2C')
48 (X'30')
2
52 (X'32')
2
56 (X'38')
2
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).
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:
►►
label
DEBCHK
cbaddr
VERIFY
,TYPE= ADD
DELETE
PURGE
PURGE,PURGE=FORCE
►
,AM=
amtype
(amaddr)
((amreg))
►
,KEYADDR=address
,KEYREG=reg
,BRANCH=
,SAVREG=reg
NO
YES
,MF=L
,TCBADDR=address
►
►
►◄
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
Value
(X'00')
(X'01')
(X'02')
(X'04')
(X'08')
(X'10')
(X'20')
(X'20')
(X'40')
(X'81')
(X'84') 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):
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
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')
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')
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.
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:
►►
label
DEVTYPE ddloc ,area_addrx
,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
The format of the UCBLIST or INFOLIST type call is:
►►
label
DEVTYPE
ddloc
UCBLIST=(ucbl_addr,ucbl_num
,BELOW
,ANY
)
► ,(area_addr,area_size)
INFOLIST=codel_addr MAX
,PLISTVER= 0
1
System Macros
►
►◄
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
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
Yes
No
No
UCBLIST specified
No
Yes
Yes
INFOLIST specified
Yes
Omitted or 0
Yes
Minimum size of area
Sum of the number of bytes returned for each code specified with INFO. See also the INFO keyword.
24 bytes per UCB
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
►
,(area_addrx,area_size)
ddloc
UCBLIST=( ucbl_addr,ucbl_num
,BELOW
,ANY
)
INFOLIST=codel_addrx MAX
,PLISTVER= 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.
E
Specifies the execute form of the macro. Use the execute form to modify a parameter list and call the DEVTYPE function.
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:
►►
label
DEVTYPE
►
,(area_addr,area_size)
ddloc
UCBLIST= YES
(ucbl_addr,ucbl_num
,BELOW
,ANY
)
INFOLIST=codel_addr MAX
,PLISTVER= 0
1
MF=L
►
►◄
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:
►►
label
DEVTYPE INFO=(
▼
,
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)
8(8)
16(10)
24(18)
7
8
1
1... ....
8
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
DASD
Optimum
Half track
Maximum
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
3480, 3490
3490 Emulation (VTS)
3590
DUMMY
32 760
65 535
262 144 (256 KB)
262 144 (256 KB) except on some older models on which it is 229 376 (224
KB)
16
32 760
65 535
262 144 (256 KB)
262 144 (256 KB)
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.
.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.
272
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
0 2 DVAOPTS
2 1
Description
Model and option bits that depend on the device
DVACLASS Device class. Exactly one bit is on except that X'41' means a channel-to-channel adapter.
3 1 DVAUNIT
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
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
DUMMY application process queue
TSO terminal
SYSIN, SYSOUT, or subsystem (SUBSYS=)
UNIX system services (possibly HFS) file
Word 0 in
Hexadecimal
0000 0000
0000 0101
0000 0102
0000 0103
Word 1 in
Hexadecimal
0000 0000
0000 7FF8
0000 7FF8
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.
Word 3
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.
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.
Word 4
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.
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.
IBM Device
1
Maximum Access Method Record Size
When Not Using Large Block Interface
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)
32 760 3380 Models AD4, AJ4, BD4, BJ4, and CJ2 Disk
Storage
3380 Models AD4, AJ4, BD4, BJ4, Disk Storage
(attached to a cache storage control)
3380 Models AE4 and BE4 Disk Storage
3380 Models AE4 and BE4 Disk Storage
(attached to a cache storage control)
3380 Models AK4 and BK4 Disk Storage
3380 Models AK4 and BK4 Disk Storage
(attached to a cache storage control)
3390 Model 1 (attached to a 3990 Model 2)
3390 Model 1 (attached to a 3990 Model 3)
3390 Model 2 (attached to a 3990 Model 2)
3390 Model 2 (attached to 3990 Model 3)
3390 Model 3 (attached to a 3990 Model 2)
3390 Model 3 (attached to a 3990 Model 3)
3390 Model 3 (attached to a 3990 Model 6)
3390 Model 9 (attached to a 3990 Model 2)
3390 Model 9 (attached to a 3990 Model 3)
3390 Model 9 (attached to a 3990 Model 6)
32 760
32 760
32 760
32 760
32 760
32 760
32 760
32 760
32 760
32 760
32 760
32 760
32 760
32 760
32 760
DEVTAB (Words 2, 3, and 4, in Hexadecimal) RPS (Word 5, in
Hexadecimal)
0376 000F BB60 0100 2010 010B
0376 000F BB60 0100 2030 010B
06EB 000F BB60 0100 2010 010B
06EB 000F BB60 0100 2030 010B
0A60 000F BB60 0100 2010 010B
0A60 000F BB60 0100 2030 010B
0459 000F E5A2 0000 0052 0000
0459 000F E5A2 0000 0072 0000
08B2 000F E5A2 0000 0052 0000
08B2 000F E5A2 0000 0072 0000
0D0B 000F E5A2 0000 0052 0000
0D0B 000F E5A2 0000 0072 0000
0D0B 000F E5A2 0000 0072 0000
2721 000F E5A2 0000 0052 0000
2721 000F E5A2 0000 0052 0000
2721 000F E5A2 0000 0052 0000
04E0 DED6
04E0 DED6
04E0 DED6
04E0 DED6
04E0 DED6
04E0 DED6
0594 E000
0594 E000
0594 E000
0594 E000
0594 E000
0594 E000
0594 E000
0594 E000
0594 E000
0594 E000
Chapter 7. Using System Macro Instructions
277
System Macros
Table 57. Output from DEVTYPE Macro — DASD Devices (continued)
IBM Device
9345 Model 1
Maximum
Record Size
(Word 1,
Decimal)
32 760
DEVTAB (Words 2, 3, and 4, in Hexadecimal) RPS (Word 5, in
Hexadecimal)
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
“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')
4 (X'04')
8 (X'08')
Information has been successfully stored in your work area.
Reason Code
Meaning
0 (X'00')
All the information is available.
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')
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
•
•
DEVTYPE MYDD,DEVINFO,DEVTAB
•
MYDD DC
DEVINFO DC
CL8’DATATAB’
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
AREA
*
DS
DS
TYP1
*
DS
*
NUMCYL DS
CL(LDTLIST)
0F
0CL20
0CL4
DEVTYPE PARAMETER LIST(MODIFIABLE)
ALIGNMENT FOR TRKCYL
INFORMATION FROM
DEVTYPE INFO=(DASD,DEVTYPE)
INFORMATION FROM
DEVTYPE INFO=DEVTYPE (UCBTYP)
FOR FIRSTDD
NUMBER OF CYLINDERS ON VOLUME
TRKCYL DS
TYP2
*
DS
DS
F
F
CL8
CL4
NUMBER OF TRACKS PER CYLINDER
MISCELLANEOUS
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’
ILIST1 DEVTYPE INFO=DEVTYPE
DD name
DEVTYPE INFO list
ILIST2 DEVTYPE INFO=(DASD,DEVTYPE) Another INFO list
* End of CSECT.
DYNAMIC
UCBAD
DSECT
DS
**** Dynamic storage for reentrancy
A
CL(LDTLIST)
Address of UCB
DEVTYPE parameter list (modifiable) DTLIST DS
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
DESCRIPTION
===========================
Area if no INFOLIST=, DEVTAB or RPS
Following four bytes are also returned for INFO=DEVTYPE
0 (0) CHARACTER 4 DVAUCBTY UCB TYPE FIELD
0 (0) BITSTRING
2 (2) BITSTRING
2
1
DVAOPTS
DVACLASS
UCB OPTIONS
DEVICE CLASS
3 (3) BITSTRING
4 (4) SIGNED
8 (8) CHARACTER 12
8 (8) UNSIGNED 2
1
4
DVAUNIT
DVAMAXRC
DVATAB
DVACYL
UNIT TYPE
MAXIMUM RECORD SIZE
SECTION INCLUDED BY DEVTAB
PHYS NUMBER CYL PER VOLUME
10 (A) SIGNED
12 (C) SIGNED
14 (E) SIGNED
2
2
2
DVATRK
DVATRKLN
DVAOVHD
NR OF TRACKS PER CYL
TRACK LENGTH ( BYTES)
BLOCK OVERHEAD IF DVA2BOV IS
ON
IF DVA2BOV IS OFF USE INSTEAD THE FOLLOWING TWO VALUES
14 (E) ADDRESS 1 DVAOVNLB OVERHEAD NOT LAST BLOCK
15 (F) ADDRESS
16 (10) ADDRESS
17 (11) BITSTRING
1... ....
1
1
1
DVAOVLB
DVAOVNK
DVAFLAGS
DVABDCYL
OVERHEAD LAST BLOCK
OVERHEAD DECR IF NOT KEYED
FLAG BYTE
IF 1, DVACYL IS INVALID
.1.. ....
DVADEFLR
YL02130
DEFINE EXTENT/LOCATE RECORD
AND RELATED TRANSFER COMMANDS
ARE IMPLEMENTED
..1. ....
...1 ....
.... 1...
DVADEFEX
DVAMODL
DVA2BOV
DEFINE EXTENT IMPLEMENTED
IF ON, USE MODULO TRACK
ALGORTIHM
IF ON, USE DVAOVHD ELSE USE
.... .1..
DVAPAGES
DVAOVNLB & DVAOVLB
IF ON DEVICE SUPPORTS PAGING
.... ..1.
.... ...1
18 (12) SIGNED 2
DVANOALT
DVAFTOL
DVATOL
CCWS
NO ALT TRKS AVAILABLE
IF ON, APPLY TOLERANCE FACTOR
TOLERANCE FACTOR
(BLKSI+KEYLE) DVATOL/DVADVSR GIVES THE ADJUSTED BLOCK SIZE
TO WHICH APPROPRIATE OVERHEADS ARE THEN ADDED.
20 (14) CHARACTER
20 (14) SIGNED
22 (16)
23 (17)
ADDRESS
ADDRESS
4 DVARPS
2
1
1
DVAOVR0
DVASECT
DVASECTD
RPS SECTION
OVERHEAD BYTES FOR RECORD 0
NUMBER OF SECTORS IN FULL
TRACK
NUMBER OF DATA SECTORS
282
z/OS DFSMSdfp Advanced Services
System Macros
0 (0) STRUCTURE 16 DVAIDASD
0 (0) UNSIGNED 4 DVAICYL
4 (4) UNSIGNED
8 (8) UNSIGNED
1... ....
4
1
DVAITRK
DVAIFLAG
DVAECKD1
9
10
12
13
14
====================================================================
THE FOLLOWING SECTION IS RETURNED BY DEVTYPE FOR INFO=DASD.
====================================================================
(9)
(A)
(C)
(D)
(E)
.1.. ....
..1. ....
...1 ....
.... 1...
.... .1..
.... ..1.
.... ...1
UNSIGNED
UNSIGNED
UNSIGNED
UNSIGNED
UNSIGNED
1
2
1
1
2
DVALRE1
DVACACHE1
DVAIXVLD
DVACYLMG
DVASSDEV
DVACRYPT
DVAMCU
DVAITSET
*
DVAEADSCB
DVALCYL
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
0 (0) BITSTRING
1... ....
1 DVAAMFLG
DVAAMLBI
CAPABILITY
FLAGS
BSAM, QSAM AND (IF DASD) BPAM
SUPPORT THE LARGE BLOCK
.1.. ....
..1. ....
DVAAM_XTIOT
INTERFACE & THE LIMIT IS IN
THE NEXT DOUBLEWORD.
This data set allocation has an
XTIOT. Either all or none of the entries for a concatenation are
XTIOT.
DVAAM_XTIOTAM BSAM, QSAM and BPAM (if DASD) support XTIOT for this device,
...1 ....
.... 1...
DVAAM_31UCB 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.
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.
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
8
(1)
(8)
16 (10)
24 (18)
.... .1..
.... ..1.
CHARACTER
BITSTRING
BITSTRING
BITSTRING
7 *
8
DVAAM_DSAB DSAB is above the line.
DVAAM_DSABAM BSAM, QSAM and BPAM (if DASD) support DSAB above the line and the NON_VSAM_XTIOT option in
DVAMAXBLK
PARMLIB allows it.
RESERVED
MAXIMUM BLOCK SIZE SUPPORTED
WITH
8
8
DVAOPTBLK
DVAMAXLR
SAM LBI
RECOMMENDED MAXIMUM BLOCK SIZE
LONGER BLOCKS MIGHT BE LESS
EFFICIENT OR LESS RELIABLE.
LESS THAN OR EQUAL TO PREVIOUS
FIELD.
MAXIMUM UNSPANNED LOGICAL
RECORD
LENGTH SUPPORTED BY BSAM, QSAM
AND BPAM
====================================================================
THE FOLLOWING SECTION IS RETURNED BY DEVTYPE FOR INFO=SUFFIX.
====================================================================
0 (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”
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
►►
label
RDJFCB (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 (DCB1)
RDJFCB (DCB1,INPUT)
RDJFCB (DCB1,(INPUT))
RDJFCB (DCB1,(INPUT,REREAD))
RDJFCB (DCB1,,DCB2)
RDJFCB (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
EX2
EX3
INVEN
MASTER
LSTA
.
.
RDJFCB (INVEN,,MASTER),MF=L
.
.
.
RDJFCB MF=(E,EX1)
.
.
.
DC
.
.
.
OPEN (,(RDBACK,LEAVE)),TYPE=J,MF=(E,EX1)
.
DCB
DCB
DS
DC
EXLST=LSTA,...
EXLST=LSTB,...
0F
AL1(EXLLASTE+EXLRJFCB)
AL3(JFCBAREA)
JFCBAREA DS
.
.
.
LSTB
0F,176C
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')
8 (X'08')
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.
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
RDJFCB DCB1
LTR R15,R15
BNZ NODD
Because of DCB exit list & JFCB
Read in the JFCB
Branch if the DD name is not defined
* Calculate amount of storage for one DCB per volume and get storage.
SR R0,R0 Prepare for IC
IC
LR
R0,JFCBNVOL
R3,R0
Get number of volumes
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
LA
R4,R1
R5,1
Point to area for first DCB
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
BNZ OpenFail
LA
LA R5,1(R5)
Branch in the unlikely event
R4,DCBLNGXE(,R4) that OPEN failed
Point to place for next DCB
Increment the volume counter
Loop until all volumes are open
.
.
BCT R3,OpenLoop
.
DCB1 DCB DDNAME=SYSUT1,MACRF=(E),EXLST=ExitL,DSORG=PS
* The following is a DCB exit list.
ExitL DC
DC
0F’0’,AL1(EXLLASTE+EXLRJFCB)
AL3(JFCB)
Last entry, for JFCB
Address of JFCB area
DCBAddrL DS
JFCB DS
A
CL176
ORG JFCB+70
JFCBVLSQ DS H
Address of DCB list
JFCB READ IN HERE
Go back to remap
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)
13
Contents of Exit List Entry (Three
Low-Order Bytes)
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
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:
►◄ ►►
label
IHAARL
YES
DSECT= NO
,PREFIX=prefix NO
,DESCR= 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')
5 (X'05')
12 (X'0C')
14 (X'0E')
2
2
1
0 . . . . . . .
1... ....
.1.. ....
. .xx xxxx
7
2
2
ARLLEN
ARLIDENT
ARLOPT1
ARLLANY
ARLUSS
ARLRSVD1
ARLRETRV
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 (X'10')
20 (X'14')
21 (X'15')
24 (X'18')
26 (X'1A')
28 (X'1C')
29 (X'1D')
4
1
3
2
2
1
7
ARLAREA
ARLPOOL
ARLRLEN
ARLRTRVD
ARLCONC
ARLRCODE
ARLRSVD2
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 (X'02')
2
1
ARALEN
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
3 (X'03')
4 (X'04')
180 (X'B4')
1... ....
.xxx xxxx
1
176(Dec) variable
ARAXINF
ARAXINOF
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.
Extended Information Segment. The DSECT name is ARAXINFO.
0 (X'00') 2 ARAXINLN
2 (X'02')
4 (X'04')
8 (X'08')
16 (X'10')
2
4
8
8
ARAPATHO
ARAXLBKS
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
The minimum value in the current level of the operating system is 32760.
Reserved.
24 (X'16') 16 *
The following fields are present only if ARAPATHO is non-zero:
ARAPATHNAME DSECT
296
z/OS DFSMSdfp Advanced Services
System Macros
Table 62. Format of the Allocation Retrieval Area (mapped by the IHAARA macro) (continued)
Offset Bytes Name Description
x x+2
2
255
257
ARAPATHLEN
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
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
DD
DISP=SHR,DSN=CORPORAT.MACLIB
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
BNZ NOJFCB
TEST RDJFCB RETURN CODE
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
BNE NOJFCB
TEST RDJFCB REASON CODE
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
L
R9,SLBRTRVD
R2,SLBAREA
GET NUMBER OF JFCB’S RETRIEVED
POINT TO ARA
USING ARA,R2
LOOPARA TM ARAFLG,ARAXINF BRANCH IF NO EXTENDED
BZ
SR
USEJFCB
R3,3
INFORMATION SEGMENT
PREPARE FOR IC
IC R3,ARAXINOF
SLL R3,3
AR R3,R2
USING ARAXINLN,R3
GET DOUBLEWORD OFFSET
GET BYTE OFFSET
POINT TO EXTENDED INFO SEGMENT
EXTENDED INFORMATION SEGMENT
SR R4,R4 PREPARE FOR ICM
ICM R4,B’0011’,ARAPATHO BRANCH IF NO PATH
BZ USEJFCB
USING ARAPATHNAME,R4
NAME
* PRINT PATH NAME
.
B
.
NEXTARA
* PRINT DATA SET NAME IN JFCB.
USEJFCB ...
.
.
NEXTARA AH R2,ARALEN
BCT R9,LOOPARA
SR
IC
.
.
R2,R2
R2,SLBPOOL
SR R0,R0
ICM R0,B’0111’,SLBRLEN
POINT TO NEXT ARA ENTRY
DECREMENT JFCB COUNTER, LOOP IF MORE
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
0H
ROUTINE TO HANDLE JUST LIBJFCB
ROUTINE TO HANDLE INABILITY TO GET THE
JFCB. THE DATA SET MAY NOT BE ALLOCATED.
SLBOPNX DS
*
.
.
0H DCB OPEN EXIT ROUTINE FOR SYSLIB.
HANDLES RECFM, LRECL, AND BLKSIZE.
INDCB
*
DCB DSORG=PO,DDNAME=SYSLIB,MACRF=R,SYNAD=INERROR,
EXLST=INEXLST
INEXLST DC
DC
DC
0F’0’,AL1(EXLDCBEX)
AL3(SLBOPNX)
AL1(EXLARL)
ENTRY CODE FOR OPEN EXIT ROUTINE
ADDR OF DCB OPEN EXIT ROUTINE
ENTRY CODE TO RETRIEVE
ALLOCATION INFORMATION
*
DC
DC
AL3(SLBSTRT) ADDR OF ALLOCATION RETRIEVAL LIST
AL1(EXLLASTE+EXLRJFCB) ENTRY CODE TO RETRIEVE FIRST JFCB
AL3(LIBJFCB)
AND INDICATE LAST ENTRY IN LIST
ADDR OF JFCB FOR FIRST DATA SET DC
*
* AN ALLOCATION RETRIEVAL LIST FOLLOWS, POINTED TO BY DCB EXIT LIST.
*
SLBSTRT IHAARL DSECT=NO,PREFIX=SLB
DC
LIBJFCB DC
.
0F’0’
CL176’ ’ FIRST JFCB
IHAARA ,
IHAEXLST , DCB exit list mapping
X
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
►◄ ►►
label
OPEN (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 (DCB1),TYPE=J
OPEN (DCB1,INPUT),TYPE=J
OPEN (DCB1,(INPUT)),TYPE=J
OPEN (DCB1,(INPUT,REREAD)),TYPE=J
OPEN (DCB1,,DCB2),TYPE=J
OPEN (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
►◄ ►►
label
PURGE
parameter_list_address
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
12
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
Note:
This field is only relevant for quiesce options.
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')
8 (X'08')
20 (X'14')
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.
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)
┌──────────────────────────────────────────────┐
³ ³
³
³
┴
┬
³
³
┌────┼─────┤ Pointer to the next IOB in the
³ ³ ³ chain.
³
³
IOBRESTR 25(19)
┌───────────────────────────────────┐
³
³
└───────────────────────────────────┘ ³
³
└──────────────────────────────────────────────┘
³
³
³
³
└───→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:
►►
label
RESTORE
restore_address
►◄
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
►
NO
,MAXSIZE= YES
►
NO
,REGSAVE= YES
BELOW
,LOC= ANY
NO
,REMOVE= YES
,RKDD=addr
,R=addr ,K=addr ,DD=addr
,MF=
I
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:
► ►►
►
label
TRKCALC
BELOW
,LOC= ANY
►
NO
,MAXSIZE= YES
►
NO
,REGSAVE= YES
FUNCTN= TRKBAL
TRKCAP
,BALANCE=
addr
*
,RKDD=addr
,R=addr ,K=addr ,DD=addr
,MF= (E,addr)
,DEVTAB=
addr
*
,UCB=
addr
*
,TYPE=
addr
*
NO
,REMOVE= YES
►
►
►◄
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:
►►
label
TRKCALC MF=L ►◄
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:
►►
label
TRKCALC MF=D ►◄
Input Register Usage for All Forms of MF
Register
Use
0, 2-12, 14
Available to provide input for keywords.
1
13
15
Only to provide the address of the parameter list for an MF=E call.
Input for keywords if REGSAVE=YES is not specified.
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')
12 (X'0C')
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.
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:
.
.
TRKCALC FUNCTN=TRKCAP,TYPE=UTYPE,R=1,K=10,DD=DL,
MF=(E,(1))
ST 0,NUMREC SAVE NUMBER OF RECORDS
.
DL
UTYPE
.
DC H’xxxx’
DC X’0E’
NUMREC DS F
DATA LENGTH
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:
►►
label
TRKADDR 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:
►►
label
TRKADDR COMPARE ,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:
►►
label
TRKADDR 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:
►►
label
TRKADDR EXTRACTTRK ,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:
►►
label
TRKADDR 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
►►
label
TRKADDR NORMALIZE ,cchh
,(reg)
,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:
►►
label
TRKADDR 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
►►
label
TRKADDR SETCYL ,cchh
,(reg)
,REG=(rega)
System Macros
►◄
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:
►►
label
TRKADDR NORMTOABS ,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
2
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.
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
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.
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
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 xxxx
CSECT
.
.
.
GBLC &IHADFARELS
IHADFA ,
CSECT
.
Set by IHADFA macro to be system level
Set &IHADFARELS and define DFARELS
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)
.OLD
.CONT
AGO .CONT
DEVTYPE UCBLIST=(MYLIST,1),MF=(E,DEVTLIST)
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
MOUNT
VERIFY
RDY
DEMOUNT
RESET
GEN
Meaning
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.
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:
►►
label
MSGDISP MOUNT ,UCB=(reg)
'S'
,LABEL= 'A'
'N'
'X'
addr
►
,MF= L
(E,addr)
►
YES
,INDEX= NO
,SER=
,TEST=
'volser'
addr
NO
YES ,WAIT=
,MEDIATYPE=n
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:
►►
►
label
MSGDISP VERIFY ,UCB= (reg)
,MF= L
(E,addr)
,SER= 'volser'
addr
,LABEL=
'S'
'A'
'N'
'X'
addr
NO
,TEST= YES
►
YES
,WAIT= 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:
►►
label
MSGDISP 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
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.
330
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
'D'
,DISP= 'K'
'R'
addr
►
,MF= L
(E,addr)
'S'
,MLABEL= 'A'
'N'
'X'
addr
►
,MSER= 'volser_to_mount'
addr
►
,MEDIATYPE=n YES
,INDEX= NO
►
,SER= 'volser'
addr
,TEST=
NO
YES
YES
,WAIT= 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:
► ►►
label
MSGDISP RESET ,UCB= (reg)
,UCBL=addr
►
NO
,TEST= YES ,WAIT=
YES
NO
,MF= L
(E,addr)
►◄
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:
►►
label
MSGDISP GEN ,UCB= (reg)
BLINK
,FLASH= STEADY
STEADY2
BLINK2
ALT
►
,MF= L
E,addr
►
,TXT=
'msgtxt' addr
,INDEX=
,TXT2=
YES
NO
'altmsgtxt' addr
,TEST=
NO
YES
,VOL=
STATIC
REMOVE
INSERT
SWAP
►
YES
,WAIT= 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 Reason Code Meaning
0 (X'00')
4 (X'04')
8 (X'08') 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.
338
z/OS DFSMSdfp Advanced Services
Return Code
12 (X'0C')
Reason Code
4 (X'04')
5 (X'05')
6 (X'06')
11 (X'0B')
12 (X'0C')
Cartridge Messages
Meaning
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).
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
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.
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
2
1 or Version 2. The first three system_level words represent
DFSMS/MVS.
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) Fourth, first or second word
Second word (release) Fourth or first word
First word (version) 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
2–4
Status of the Storage Management Subsystem. A value of 0 indicates inactive; 1 indicates active.
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’
BL SHOWSYS
See if after MVS/DFP
Branch if before DFSMS/MVS
CALL IGWASYS,(RC1,RS1,CODE2,LEVEL,ATTR)
LTR R15,R15 Branch if environment or
BNZ BADSYS
MVC SYSNAME,UNKNAME system error
Assume unknown product name
CLC LEVEL+12(4),=F’1’
BL OLDSYS
Test for DFSMS/MVS code
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
BH
SHOWSYS
COPYSYS
OS/390
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
L
R14,16 Point to CVT
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
CH
R15,DFAELNML
R15,MaxLen
BNH *+8
LH R15,MaxLen
Get name length
Skip one instruction if name not too long
Truncate to our field length
BCTR R15,0
EX R15,MVCName
DROP R14
ShowSys EQU *
Decrement for EX instruction
Copy name from DFA
Handle version, release and modification level
RC1
RS1
CODE1
CODE2
LEVEL
ATTR
SYSNAME DC
UNKNAME DC
DC
DC
DC
DC
.
.
DC
DC
F’0’
F’0’
F’1’
F’2’
4F’0’
4F’0’
Return code
Reason code
Ask for pre-DFSMS DFP level
Ask for level of DFSMS, or later
Version, release, Modification Level and code
SMS attributes
CL12’MVS/XA DFP’
(L’SYSNAME)C’?’
Name of product
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
DC F’0’
DC F’0’
PROB1 DC 2F’0’
DSNLEN1 DC A(L’DSN1)
DSN1 DC CL12’THIS.DATASET’
SMSDATA DC 3CL30’ ’
DSTYPE DC F’0’
ASMSLIST DC A(RC2)
DC A(RS2)
DC A(PROB1)
DC A(DSNLEN1)
DC A(DSN1)
DC A(SMSDATA)
DC 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
,
dsname_length
,
dsname
,
select
,
► bwo_flags ,
bwo_recov
,
bwo_resrv
, )
►
►
►◄
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
YY
is the century - 00 represents 19YY, 01 represents 20YY 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
T
F
Seconds
Tenths of a second 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 EP=IGWABWO
LR R2,R0
CALL (R2),(RC1,RS1,PROB1,RW1,DSNLEN1,DSN1,SEL1,BWOF1,BWOR1,BWRE)
CALL (R2),(RC2,RS2,PROB2,RW2,DSNLEN2,DSN2,SEL2,BWOF2,BWOR2,BWRE)
.
.
* ARGUMENTS FOR WRITING
RC1 DC F’0’
RS1
PROB1
DC
DC
F’0’
2F’0’
RW1 DC F’1’
DSNLEN1 DC F’11’
DSN1
SEL1
BWOF1
DC
DC
DC F’0’
DC F’1’
WRITE
CL44’THAT.VSAM01’
F’3’ WRITE BWO_FLAGS AND BWO_RECOV
BWOR1
DC F’0’
DS 0F
DC X’0096137F’
DC X’1045301F’
BWRE1 DC CL16’ ’
* ARGUMENTS FOR READING
RC2 DC F’0’
INPUT DATE IN 0CYYDDDF FORMAT
INPUT TIME IN HHMMSSTF FORMAT
RS2
PROB2
DC F’0’
DC 2F’0’
RW2 DC F’0’
DSNLEN2 DC F’11’
DSN2
SEL2
BWOF2
BWOR2
BWRE2
*
DC
DC
DC
DC
DC
READ
CL44’THAT.VSAM01’
F’3’
3F’0’
CL8’ ’
CL16’ ’
READ BWO_FLAGS AND BWO_RECOV
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
000
001
010
011
100
101
110
111
Description
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.
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
,
label
► prob_det ,
share_attr_selector
,
share_attr_array_length
,
► 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.
2–4
A value of 1 indicates normal PDSE sharing protocol in use. A value of 2 indicates extended PDSE sharing protocol in use.
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) Description
0 (0)
4 (4)
0 (0)
4 (4)
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.
354
z/OS DFSMSdfp Advanced Services
Callable Services
Table 64. IGWASYS, IGWASMS, IGWABWO, IGWLSHR Return and Reason Codes (continued)
Return Code Dec
(Hex)
Reason Code
Dec (Hex) Description
8 (8)
8 (8)
8 (8)
8 (8)
8 (8)
8 (8)
8 (8)
8 (8)
12 (C)
12 (C)
12 (C)
16 (10)
20 (14)
36 (24)
4 (4)
8 (8)
12 (C)
16 (10)
20 (14)
24 (18)
28 (1C)
32 (20)
8 (8)
12 (C)
16 (10)
4 (4)
4 (4)
4 (4)
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
,
recovery_status
,
log_type
,
► logstreamid_length ,
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
0 (0)
8 (8)
8 (8)
8 (8)
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) Description
8 (8)
0 (0)
4 (4)
8 (8)
20 (14)
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.
32 (20)
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) Description
8 (8)
12 (C)
12 (C)
12 (C)
12 (C)
16 (10)
20 (14)
36 (24)
40 (28)
8 (8)
12 (C)
14 (E)
16 (10)
4 (4)
4 (4)
4 (4)
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:
.
.
LOAD EP=IGWARLS
LR R9,R0
CALL (R9),(RC1,RS1,PROB1,DSNLEN1,DSN1,RECSTAT,LOGTYPE,
LOGSTRML,LOGSTRM,RCVTMG,RCVTML,VSAMQUIS,BWO)
RC1
RS1
DC
DC
PROB1 DC
DSNLEN1 DC
DSN1 DC
RECSTAT DC
LOGTYPE DC
LOGSTRML DC
LOGSTRM DC
RCVTMG DC
RCVTML DC
VSAMQUIS DC
BWO 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
X
358
z/OS DFSMSdfp Advanced Services
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:
►►
label
►
,
number
CALL IECTRKAD , (
operation
,
cchh1
,
returncode
,
reasoncode
)
,
cchh2
►
►◄
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
4
Successful.
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
8
12
The H portion of a track address is not valid on a NEXTTRACK operation
The caller specified an invalid operation (the first parameter is not one of the supported operations)
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
TASK
,EXIT_SCOPE= GLOBAL
►
► ,EXIT_PREV_DSTPTR=
dstPTR_address
(2-12)
►
S
,MF= L
(E, (1-12) label
,COMPLETE
,NOCHECK )
►
NOREPLACE
,EXIT_OPTION= REPLACE
DELETE
QUERY
,EXIT_DST=
dst_address
(2-12)
,RETCODE=retcode
,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
NOREPLACE (with no exit currently existing)
The new exit definition replaces the most recently defined exit. The DST
(DESERV Screen Table) address of the previously defined exit's DST is returned to the caller.
The exit definition is activated. A value of zero is returned as the previous DST address.
EXIT_DST and
EXIT_PREV_DSTPTR must be specified.
See REPLACE.
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
12 (X'0C')
13 (X'0D')
14 (X'0E')
16 (X'10')
2
4 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
0 (X'0')
0 (X'0')
0 (X'0')
08 (X'08')
Length or Bit
Pattern
8
4
20
16
X'14'
1
X'01'
1 xxxx xxx.
.... ...1
Name
DST
DST_HEADER
DST_ID
DST_LEN
DST_LEN_IV
DST_LEV
DST_LEV_IV
-
DST_FLAGS
DST_FLAGS_PROP
DST_RES
DST_EXIT
Description
(structure)
(character)
Eyecatcher 'IGWDST' (character)
Length of DST
Constant to be used with
DST_LEN
Control block level (unsigned)
Constant to be used with
DST_LEV
DST flags (unsigned)
Reserved
Propagate this DST to lower level tasks
Reserved
Address of exit routine screen table (address)
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
EXIT_OPTION
EXIT_DST
EXIT_PREV_DSTPTR
(application dependent)
DELETE
Currently active DST to be deleted
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
EXIT_OPTION
EXIT_SCOPE
EXIT_PREV_DSTPTR
choose this:
QUERY
(application dependant)
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
0 (X'0')
0 (X'0')
0 (X'0')
08 (X'08')
12 (X'0C')
13 (X'0D')
16 (X'10')
20 (X'14')
24 (X'18')
Length or Bit
Pattern
4
4
1
8
4
36
16
X'24'
1
X'01'
3
Name
DESX
DESX_HEADER
DESX_ID
DESX_LEN
DESX_LEN_IV
DESX_LEV
-
DESX_LEV_IV
DESX_DESP_PTR
DESX_DST
DESX_CALLER_KEY
Description
(structure)
(character)
Eyecatcher - IGWDESX (character)
Length of DESX (signed)
Constant to be used with DESX_LEN
Control block level (character)
Constant to be used with DESX_LEV
Reserved
Address of caller's DESP (address)
Address of DESERV screen table (address)
Key of DESERV caller in bits 0-3 (unsigned)
Chapter 10. Using the DESERV Exit
371
DESERV Exit
Table 70. DESX Structure Mapping DESERV Exit Parameter List (continued)
Offset
25 (X'19')
26 (X'1A')
28 (X'1C')
32 (X'20')
Length or Bit
Pattern
2
4
4
1
1... ....
.1.. ....
..1. ....
Name
DESX_FLAGS
DESX_BLDL_BIT
DESX_PREV_BIT
DESX_POST_BIT
-
DESX_RETURN_CODE
DESX_REASON_CODE
Description
(bitstring)
DESERV issues BLDL to process this GET request
EXIT called before DESERV PUT or GET function
EXIT called after DESERV PUT or GET function
Reserved
Return code to be returned to DESERV caller (unsigned)
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
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.
Table 71. Structure of DESP for DESERV GET Invocations
Offset
00 (X'00')
00 (X'00')
00 (X'00')
08 (X'08')
12 (X'0C')
13 (X'0D')
16 (X'10')
17 (X'11')
20 (X'14')
24 (X'18')
24 (X'18')
Length or Bit
Pattern Name
1
X'07'
X'08'
X'09'
X'04'
X'01'
X'00'
3
4
12
104
16
8
24
X'04'
1
X'01'
3
2
1... ....
.x.. ....
..1. ....
...1 ....
DESP
DESP_HEADER
DESP_ID
DESP_LEN
DESP_LEN_IV
DESP_LEV
-
DESP_LEV_IV
DESP_FUNC
DESP_FUNC_DELETE
DESP_FUNC_RENAME
DESP_FUNC_UPDATE
DESP_FUNC_PUT
DESP_FUNC_GET
-
DESP_FUNC_OMITTED
-
DESP_DATA
DESP_FLAGS
DESP_BYPASS_LLA
-
DESP_SUBPOOL_FLG
DESP_C370LIB
.... xx..
.... ..1.
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'.
-
DESP_SYSTEM_DCB
Description
DE Services parameter list (structure)
(character) 'IGWDESP'
Eyecatcher IGWDESP (character)
Length of DESP (signed)
Constant to be used with DESP_LEN
Control block level (character)
Constant to be used with DESP_LEV
Reserved
Function type (unsigned)
Function is DELETE
Function is RENAME
Function is UPDATE
Function is PUT
Function is GET
Function is omitted
Reserved
Reserved
Function data (character)
Flags (bitstring)
0=USE LLA, 1=BYPASS LLA
Reserved
0=SUBPOOL not specified, 1=SUBPOOL specified
1=treat PDSs as C370LIB if @@DC370$ member exists
Reserved
1=treat DCB as a system DCB
Chapter 10. Using the DESERV Exit
373
DESERV Exit
Offset
26 (X'1A')
27 (X'1B')
28 (X'1C')
44 (X'2C')
48 (X'30')
52 (X'34')
56 (X'38')
60 (X'3C')
64 (X'40')
68 (X'44')
72 (X'48')
76 (X'4C')
80 (X'50')
Table 71. Structure of DESP for DESERV GET Invocations (continued)
29 (X'1D')
30 (X'1E')
31 (X'1F')
32 (X'20')
33 (X'21')
34 (X'22')
35 (X'23')
36 (X'24')
40 (X'28')
84 (X'54')
4
4
4
4
4
4
4
4
4
4
1
X'03'
X'02'
X'01'
X'00'
1
4
1
1
1
1
X'03'
X'02'
X'01'
X'00'
1
1
1
Length or Bit
Pattern Name
X'02'
X'01'
X'00'
1
4
4
-
-
DESP_LIBTYPE
DESP_LIBTYPE_DCB
DESP_LIBTYPE_DEB
DESP_LIBTYPE_OMITTED
DESP_GETTYPE
DESP_NAME_LIST2
Description
Reserved
Reserved
Indicates whether a DCB or DEB is input =X'02',
DEB input=X'01') (unsigned)
Constant to be used with DESP_LIBTYPE
Constant to be used with DESP_LIBTYPE
Constant to be used with DESP_LIBTYPE
Indicates whether Name List or PDSDE is input.
(NAME_LIST input=(X'01', PDSDE input=X'02')
(unsigned)
DESP_GETTYPE_SMDE
DESP_GETTYPE_PDSDE
Constant to be used with DESP_GETTYPE
Constant to be used with DESP_GETTYPE
DESP_GETTYPE_NAME_LIST Constant to be used with DESP_GETTYPE
DESP_GETTYPE_OMITTED Constant to be used with DESP_GETTYPE
-
-
-
DESP_SUBPOOL
Reserved
Reserved
Reserved
Subpool number for getting DESB.
DESP_CONN_INTENT Connect intent (unsigned)
DESP_CONN_INTENT_INPUT INPUT
DESP_CONN_INTENT_EXEC EXEC
DESP_CONN_INTENT_HOLD HOLD
-
DESP_CONN_INTENT_NONE None
Reserved
DESP_DCB_PTR
DESP_DEB_PTR
DCB address, valid if DESP_LIBTYPE=X'02'
(address)
DEB address, valid if DESP_LIBTYPE=X'01'
(address)
DESP_CONN_ID_PTR
DESP_AREAPTR_PTR
DESP_AREA_PTR
DESP_AREA2
-
-
-
-
DESP_ENTRY_GAP
DESP_NAME_LIST_PTR
Connect identifier address
Address of output field for buffer address
Buffer address
Buffer length (unsigned)
Reserved
Reserved
Entry gap size (signed)
Reserved
Reserved
Name list address, valid if DESP_GETTYPE=X'01'
(address)
Input list number of entries, valid if
DESP_GETTYPE=X'01' (unsigned)
374
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 71. Structure of DESP for DESERV GET Invocations (continued)
Offset
88 (X'58')
92 (X'5C')
4
4
Length or Bit
Pattern Name
-
DESP_PDSDE_PTR
92 (X'5C')
96 (X'60')
100 (X'64')
4
4
4
-
-
DESP_SMDE_PTR
Description
Reserved
BLDL directory entry address, valid if
DESP_GETTYPE=X'02' (address)
SMDE directory entry address, valid if
DESP_GETTYPE=X'03' (address)
Reserved
Reserved
Table 72. DESL Structure
Offset
00 (X'00')
00 (X'00')
00 (X'00')
1 (X'1')
Length or Bit
Pattern Name
16
16
1
1... ....
1
DESL
DESL_ENTRY
DESL_FLAGS
DESL_MODULE_BUFFERED_
LLA
DESL_CODE
2 (X'2')
4 (X'4')
08 (X'08')
08 (X'08')
12 (X'0C')
12 (X'0C')
X'03'
X'02'
X'01'
X'00'
2
4
4
4
4
4
-
DESL_CODE_NEWNAME_
EXISTS
DESL_CODE_ERROR
DESL_CODE_NOTFOUND
DESL_CODE_SUCC
DESL_ERRCODE
DESL_SMDE_PTR
DESL_NEW_NAME_PTR
DESL_NAME_PTR
DESL_OLD_NAME_PTR
Description
Name list (structure)
Name list entry (character)
Flags (unsigned)
Module is staged by LLA
Result code (New name exists=X'03', Error=X'02',
Not found or not processed=X'01', Found=X'00')
(unsigned)
For func=rename, indicates a new name already existed in the PDSE.
An unexpected error has occurred. The
DESL_ERRCODE field is set to a DESRF value
Entry not found or entry not processed. If func=rename, old name was not found.
Entry successfully processed
Error reason code (low order halfword of DESERV reason code if error) (unsigned)
Reserved
Pointer to SMDE within DESB. Output for GET function, input for UPDATE function (address)
Pointer to new name (DESN) descriptor for
RENAME function (address)
Pointer to name (DESN) descriptor for GET and
DELETE functions (address)
Pointer to old name (DESN) descriptor for
RENAME function (address)
The DESERV GET caller will have built the DESL to point to variable length
Chapter 10. Using the DESERV Exit
375
DESERV Exit
Table 73. DESN Parameter List
Offset
00 (X'00')
00 (X'00')
2 (X'02')
Length or Bit
Pattern Name
variable
2 variable
DESN
DESN_LEN
DESN_VAL
Description
Name record (structure)
Length of name that follows (unsigned)
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
The basic SMDE format is shown in Table 75 on page 377.
Offset
00 (X'00')
00 (X'00')
00 (X'00')
00 (X'00')
08 (X'08')
12 (X'0C')
13 (X'0D')
16 (X'10')
20 (X'14')
24 (X'18')
28 (X'1C')
32 (X'20')
33 (X'21')
34 (X'22')
36 (X'24')
Table 74. DESB Parameter List
Length or Bit
Pattern Name
2
4
1
1
4
4
4
4 variable
40
16
8
4
1
X'01'
3
DESB
DESB_FIXED
DESB_HEADER
DESB_ID
DESB_LEN
DESB_LEV
-
DESB_LEV_IV
-
DESB_NEXT
DESB_COUNT
DESB_AVAIL
-
DESB_SUBPOOL
-
DESB_GAP_LEN
Description
DEServ buffer header (structure)
(character)
(character)
Eyecatcher - IGWDESB (character)
Length of buffer (signed)
Control block level (character)
Constant to be used with DESB_LEV
Reserved
Next buffer pointer (address)
Reserved
Count of entries in this buffer (unsigned)
Start of free space in buffer (address)
Reserved
Subpool number (unsigned)
Length of user-requested gap (unsigned)
Reserved
376
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 74. DESB Parameter List (continued)
Offset
40 (X'28')
Length or Bit
Pattern Name
variable DESB_DATA
Table 75. SMDE Format
Offset
00 (X'00')
00 (X'00')
00 (X'00')
00 (X'00')
08 (X'08')
Length or Bit
Pattern Name
variable
44
16
8
4
SMDE
SMDE_BASIC
SMDE_HDR
SMDE_ID
SMDE_LEN
12 (X'0C')
13 (X'0D')
16 (X'10')
3
1
1
X'01'
SMDE_LVL
SMDE_LVL_VAL
-
SMDE_LIBTYPE
17 (X'11')
18 (X'12')
20 (X'14')
20 (X'14')
21 (X'15')
21 (X'15')
24 (X'18')
25 (X'19')
26 (X'1A')
28 (X'1C')
28 (X'1C')
X'03'
X'02'
X'01'
X'00'
1
4
3
5
1
1... ....
.1.. ....
..xx xxxx
2
1
1
X'02'
X'01'
2
2
X'00'
2
SMDE_C370LIB
SMDE_LIBTYPE_HFS
SMDE_LIBTYPE_PDSE
SMDE_LIBTYPE_PDS
SMDE_FLAG
-
*
SMDE_FLAG_ALIAS
SMDE_FLAG LMOD
-
-
SMDE_MLTK
SMDE_MLT
SMDE_CNCT
SMDE_LIBF
SMDE_LIBF_TASKLIB
SMDE_LIBF_LINKLIB
SMDE_LIBF_PRIVATE
SMDE_NAME_OFF
SMDE_USRD_LEN
SMDE_PMAR_LEN
Description
Start of data area (character)
Description
Member directory entry (structure)
Start of basic section (character)
Header (character)
Eyecatcher (character)
Length of control block. This is the sum of the sizes of the SMDE sections and the size of the user data. (unsigned)
SMDE version number (unsigned)
Constant to be used with SMDE_LVL
Reserved
Source library type. Possible values are declared below with names like SMDE_LIBTYPE_XXX.
(unsigned)
Constant to be used with SMDE_LIBTYPE
Constant to be used with SMDE_LIBTYPE
Constant to be used with SMDE_LIBTYPE
Constant to be used with SMDE_LIBTYPE
Flag byte (bitstring)
Entry is an alias
Member is a program
Reserved
Reserved, must be zero
Extended MLTK (character)
Reserved, must be zero
MLT and concatenation number (character)
MLT of member - zero if HFS (character)
Concatenation number (unsigned)
Library flag - Z-byte (unsigned)
Constant to be used with SMDE_LIBF
Constant to be used with SMDE_LIBF
Constant to be used with SMDE_LIBF
Name offset (signed)
User data length (signed)
Sum of lengths of program management attribute record sections (PMAR, PMARR, PMARL)
(signed)
Chapter 10. Using the DESERV Exit
377
DESERV Exit
Table 75. SMDE Format (continued)
Offset
30 (X'1E')
30 (X'1E')
2
2
Length or Bit
Pattern Name
SMDE_USERD_OFF
SMDE_PMAR_OFF
32 (X'20')
34 (X'22')
36 (X'24')
2
2
2
SMDE_TOKEN_LEN
SMDE_TOKEN_OFF
SMDE_PNAME_OFF
38 (X'26')
40 (X'28')
44 (X'2C')
2
4 variable
SMDE_NLST_CNT
-
SMDE_SECTIONS
Description
User data offset (signed)
Program management attribute record offset
(signed)
Token length (signed)
Token data offset (signed)
Primary name offset, zero for non-alias SMDES or if library type is a PDS and this is not a program.
(signed)
Number of note list entries that exist at beginning of user data field. Always zero for non-PDS members. (signed)
Reserved
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
00 (X'00')
00 (X'00')
2 (X'02')
Length or Bit
Pattern Name
variable
2 variable
SMDE_NAME
SMDE_NAME_LEN
SMDE_NAME_VAL
Description
Name descriptor (structure)
Length of entry name (signed)
Entry name (character)
Table 77. Directory Entry Notelist Section (PDS Only)
Offset
00 (X'00')
00 (X'00')
00 (X'00')
3 (X'03')
Length or Bit
Pattern Name
3
1 variable
4
SMDE_NLST
SMDE_NLST_ENTRY
SMDE_NLST_RLT
SMDE_NLST_NUM
Description
Note list extension (structure)
Note list entries (character)
Note list record location token (character)
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
00 (X'00')
00 (X'00')
4 (X'04')
08 (X'08')
32
4
4
24
SMDE_TOKEN
SMDE_TOKEN_CONNID
SMDE_TOKEN_ITEMNO
SMDE_TOKEN_FT
Description
(structure)
CONNECT_IDENTIFIER (unsigned)
Item number (unsigned)
File token (character)
378
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 79. Directory Entry Primary Name Section
Offset
00 (X'00')
00 (X'00')
2 (X'02')
Length or Bit
Pattern Name
variable
2 variable
SMDE_PNAME
SMDE_PNAME_LEN
SMDE_PNAME_VAL
Description
Primary name descriptor (structure)
Length of primary name (signed)
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
00 (X'00')
00 (X'00')
00 (X'00')
2 (X'02')
3 (X'03')
4 (X'04')
Length or Bit
Pattern Name
2
1
30
30
X'02'
X'01'
X'02'
1
PMAR
PMAR_ENTRY
PMAR_SLEN
PMAR_LVL
PMAR_LVL_VAL
PMAR_PM1_VAL
PMAR_PM2_VAL
PMAR_PLVL
X'01'
X'02'
X'03'
X'04'
X'05'
X'06'
4
PMAR_PLVL_E_VAL
PMAR_PLVL_F_VAL
PMAR_PLVL_AOS_VAL
PMAR_PLVL_XA_VAL
PMAR_PLVL_B1_VAL
PMAR_PLVL_B2_VAL
PMAR_ATR
Description
Basic section of program user data (structure)
Alternative name for the PMAR section (character)
Section length (unsigned)
PMAR format level (unsigned)
Constant to be used with PMAR
Constant to be used with PMAR
Constant to be used with PMAR
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)
Constant to be used with PMAR_PLVL
Constant to be used with PMAR_PLVL
Constant to be used with PMAR_PLVL
Constant to be used with PMAR_PLVL
Constant to be used with PMAR_PLVL
Constant to be used with PMAR_PLVL
Attribute bytes (character)
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
4 (X'04')
5 (X'05')
6 (X'06')
6 (X'06')
7 (X'07')
Length or Bit
Pattern Name
1
1... ....
.1.. ....
..1. ....
...1 ....
.... 1...
.... .1..
.... ..1.
.... ...1
1
1... ....
.1.. ....
..x. ....
...1 ....
.... 1...
.... .1..
.... ..x.
.... ...1
1
1 x... ....
.1.. ....
..1. ....
...1 ....
.... 1...
.... .1..
.... ..xx
1
-
-
-
-
PMAR_ATR1
PMAR_RENT
PMAR_REUS
PMAR_OVLY
PMAR_TEST
PMAR LOAD
PMAR_SCTR
PMAR_EXEC
PMAR_1BLK
PMAR_ATR2
PMAR_FLVL
PMAR_ORGO
PMAR_NRLD
PMAR_NREP
PMAR_TSTN
PMAR REFR
PMAR_ATR3
PMAR_FTB1
PMAR_BIG
PMAR_PAGA
PMAR_XSSI
PMAR_XAPF
PMAR_LFMT
PMAR_ATR4
Description
First attribute byte. These flags must be at the same offsets as the corresponding flags in
PDS2ATR1 declared by macro IHAPDS. (bitstring)
Reenterable
Reusable
Overlay structure
Module to be tested - TSO/E TEST
Only loadable
Scatter format
Executable
Load module contains only one block of text data and has no RLD data.
Second attribute byte. These flags must be at the same offsets as the corresponding flags in
PDS2ATR2 declared by macro IHAPDS. (bitstring)
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.
Linkage editor assigned origin of first block of text is zero.
Reserved
Program contains no RLD items
Module cannot be reprocessed by the linkage editor
Module contains TSO/E TEST symbol records
Reserved
Refreshable program
Third attribute byte. (bitstring)
Alternative name for flags byte. These flags must be at the same offsets as the corresponding flags in PDS2FTB1 declared by macro IHAPDS.
(bitstring)
Reserved
This program requires 16MB or more of virtual storage.
Page alignment is required
SSI information present
APF information present
PMARL follows PMAR.
Reserved
Fourth attribute byte (bitstring)
380
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 80. Directory Entry Name Section (continued). Data is always present at offset SMDE_PMAR_OFF in an
SMDE.
Offset
7 (X'07')
08 (X'08')
9 (X'09')
10 (X'0A')
14 (X'0E')
18 (X'12')
22 (X'16')
22 (X'16')
23 (X'17')
24 (X'18')
26 (X'1A')
30 (X'1E')
Length or Bit
Pattern Name
1
1... ....
.xx. ....
...1 ....
.... xx..
.... ..xx
1
1
4
4
4
4
1
1
2
4 variable
-
-
-
PMAR_FTB2
PMAR_ALTP
PMAR_RMOD
PMAR_AAMD
PMAR_MAMD
PMAR_AC
PMAR_STOR
PMAR_EPM
PMAR_EPA
PMAR_SSI
PMAR_CHLV
PMAR_SSFB
PMAR_MSER
PMAR_END
Description
Alternative name for flags byte. These flags must be at the same offsets as the corresponding flags in PDS2FTB2 declared by macro IHAPDS.
(bitstring)
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.
Reserved
RMODE is ANY.
Alias entry point addressing mode. If B'00',
AMODE is 24. If B'10', AMODE is 31. If B'11',
AMODE is ANY.
Main entry point addressing mode. If B'00'
AMODE is 24. If B'10', AMODE is 31. If B'11',
AMODE is ANY.
Reserved
APF authorization code (unsigned)
Virtual storage required (unsigned)
Main entry point offset (unsigned)
This entry point offset (unsigned)
SSI information (bitstring)
Change level of member (unsigned)
SSI flag byte (bitstring)
Member serial number (Reserved)
Reserved
End of basic section (character)
Table 81. LSLoader Attributes Unique to Program Objects. If PMAR_LFMT=ON this section follows the PMAR basic section.
Offset
00 (X'00')
00 (X'00')
2 (X'02')
2 (X'02')
2 (X'02')
Length or Bit
Pattern
50
2
48
4
1
1... ....
Name
PMARL
PMARL_SLEN
PMARL_DATA
PMARL_ATR
PMARL_ATR1
PMARL_NMIG
.1.. ....
..1. ....
...x xxxx -
PMARL_PRIM
PMARL_PACK
Description
LSLoader section for program objects (structure)
Section length (unsigned)
Section data (character)
Attribute bytes (character)
Fifth attribute byte (bitstring)
This program object cannot be converted directly to PDS load module format.
FETCHOPT PRIME option
FETCHOPT PACK option
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
10 (X'0A')
10 (X'0A')
14 (X'0E')
18 (X'12')
22 (X'16')
26 (X'1A')
30 (X'1E')
34 (X'22')
38 (X'26')
42 (X'2A')
3 (X'03') 1
1... ....
.1.. ....
..1. ....
...1 ....
.... 1...
.... .1..
PMARL_ATR2
PMARL_CMPR
PMARL_1RMOD
PMARL_2RMOD
PMARL_SEGM
PMARL_1ALIN
PMARL_2ALIN
Sixth attribute byte (bitstring)
Compressed format module
1st segment is RMODE Any, set for PM2-level PO only
2nd segment is RMODE Any, set for PM2-level
PO if there are at least two segments.
Loader data includes a Segment Table with >1 loadable entry or a Gas Table, set for PM2-level
PO only.
1st segment is page-aligned, set for PM2-level PO only
2nd segment is page-aligned, set for PM2-level PO if there are at least 2 segments.
4 (X'04')
5 (X'05')
.... ..1.
.... ...x
1
1 -
-
PMARL_FILL
PMARL_FILLVAL
FILL option specified set for PM2-level PO only
Reserved
FILL character value set for PM2-level PO only
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)
42 (X'2A')
46 (X'2E')
50 (X'32')
52 (X'34')
54 (X'36')
58 (X'3A')
40
4
4
4
4
4
4
4
4
4
4
4
2
2
4
4
PMARL_MDAT
PMARL_TXTL
PMARL_TXTO
PMARL_BDRL
PMARL_BDRO
PMARL_RDTL
PMARL_RDTO
PMARL_RATL
PMARL_RATO
PMARL_NVSPGS
PMARL_LMDL
PMARL_LMDO
PMARL_NSEG
PMARL_NGAS
PMARL_1STOR
PMARL_2STOR
DASD program descriptors (character)
Length of text (unsigned)
Offset to text (address)
Length of binder index (unsigned)
Offset to binder index (address)
Length of PRDT (unsigned)
Offset to PRDT (address)
Length of PRAT (unsigned)
Offset to PRAT (address)
Number of virtual storage pages to contain program object, for PM2-level PO
Length of LSLoader data (unsigned) for PM1-level
PO
Offset to LSLoader data (address)
Number of loadable segments
Count of entries in Gas Table
Virtual storage required for first loadable segment, valid when PMARL_NSEG > 1.
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
62 (X'3E')
Length or Bit
Pattern Name
4 PMARL_2TXTO
Description
Offset to second txt segment including gas, valid when PMARL_NSEG > 1.
END INFORMATION ONLY FIELDS.
66 (X'42')
66 (X'42')
70 (X'46')
74 (X'4A')
82 (X'52')
4
8
16
4 variable
PMARL_TRACE
PMARL_DATE
PMARL_TIME
PMARL_USER
PMARL_END
AUDIT trace data
Date saved
Time saved
User or job identification
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
00 (X'00')
00 (X'00')
2 (X'02')
2 (X'02')
2 (X'02')
5 (X'05')
6 (X'06')
9 (X'09')
10 (X'0A')
12 (X'0C')
12 (X'0C')
14 (X'0E')
15 (X'F')
15 (X'F')
17 (X'11')
19 (X'13')
21 (X'15')
23 (X'17')
3
1
Length or Bit
Pattern
23
2
21
8
Name
PMARR
PMARR_SLEN
PMARR_DATA
PMARR_TTRS
PMARR_TTRT
3
PMARR_ZERO
PMARR_TTRN
1
2
3
2
1
8
2
2
2
2 variable
-
PMARR_NL
PMARR_FTBL
PMARR_ORG
PMARR_RLDS
PMARR_SCAT
PMARR_SLSZ
PMARR_TTSZ
PMARR_ESDT
PMARR_ESDC
PMARR_END
Description
Load module (PDS) attributes section (structure)
Section length (unsigned)
Section data (character)
TTR fields (character)
TTR of first block of text (character)
Zero (character)
TTR of note list or scatter translation table. Used for modules in scatter load format or overlay structure only. (character)
Number of entries in note list for scatter format modules and modules in overlay structure, otherwise zero. (address)
Length of first block of text (signed)
Load module origin if 0 (unsigned)
Reserved
Number of RLD/CTL records that follow the first text record
Scatter load information (character)
Scatter list length (unsigned)
Translation table length (unsigned)
ESDID of first text block (character)
ESDID of EP control section (character)
End of load module attributes (character)
Table 83. Alias in Unformatted Form. Used only as input to the PUT function.
Offset
00 (X'00')
Length or Bit
Pattern Name
7 PMARA
Description
PMAR alias entry section (structure)
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
00 (X'00')
2 (X'02')
2 (X'02')
6 (X'06')
6 (X'06')
6 (X'06')
7 (X'07')
4
1
2
5
1
1
Length or Bit
Pattern Name
PMARA_LEN
PMARA_DATA
PMARA_EPA
PMARA_ATR
PMARA_ATR1
PMARA_FTB2 xxxx ....
.... 11..
.... ..xx
variable
-
-
PMARA_AMD
PMARA_END
Description
Section length (unsigned)
Section data (character)
Entry point offset (unsigned)
Attribute bytes (character)
First attribute byte (bitstring)
Alternative name for flags byte. These flags must be at the same offsets as the corresponding flags in PDS2FTB2 declared by macro IHAPDS.
(bitstring)
Reserved
Alias entry addressing mode. If B'00', AMODE is
24. If B'10', AMODE is 31. If B'11', AMODE is
ANY.
Reserved
End of alias entry section (character)
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
00 (X'00')
00 (X'00')
00 (X'00')
08 (X'08')
12 (X'0C')
13 (X'0D')
16 (X'10')
Length or Bit
Pattern Name
4
3
1
4
1
8
4
104
16
DESP
DESP_HEADER
DESP_ID
DESP_LEN
DESP_LEN_IV
DESP_LEV
-
DESP_LEV_IV
DESP_FUNC
X'07'
X'08'
X'09'
X'04'
X'01'
X'00'
DESP_FUNC_DELETE
DESP_FUNC_RENAME
DESP_FUNC_UPDATE
DESP_FUNC_PUT
DESP_FUNC_GET
DESP_FUNC_OMITTED
Description
DE Services parameter list (structure)
Standard header (character)
Eyecatcher 'IGWDESP' (character)
Length of DESP (signed)
Constant to be used for DESP_LEN
Control block level (character)
Constant to be used for DESP_LEV
Reserved
Function type (GET=X'01', PUT=X'04',
DELETE=X'07', RENAME=X'08',
UPDATE=X'09') (unsigned)
Constant to be used for DESP_FUNC
Constant to be used for DESP_FUNC
Constant to be used for DESP_FUNC
Constant to be used for DESP_FUNC
Constant to be used for DESP_FUNC
Constant to be used for DESP_FUNC
384
z/OS DFSMSdfp Advanced Services
DESERV Exit
33 (X'21')
34 (X'22')
35 (X'23')
36 (X'24')
40 (X'28')
44 (X'2C')
48 (X'30')
52 (X'34')
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')
X'00'
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
1
4
1
1
Table 84. DESERV PUT DESP Fields (continued)
Offset
17 (X'11')
20 (X'14')
24 (X'18')
24 (X'18')
26 (X'1A')
27 (X'1B')
28 (X'1C')
Length or Bit
Pattern Name
1
1
1
3
4
12
2
-
-
-
DESP_DATA
-
-
DESP_LIBTYPE
29 (X'1D')
30 (X'1E')
31 (X'1F')
32 (X'20')
1
1
1
X'02'
X'01'
X'00'
1
DESP_LIBTYPE_DCB
DESP_LIBTYPE_DEB
-
DESP_LIBTYPE_OMITTED
-
-
DESP_OPTION
X'02'
X'01'
DESP_OPTION_REPLACE_ALIAS
DESP_OPTION_REPLACE
DESP_OPTION_NOREPLACE
-
-
-
-
-
-
-
DESP_DCB_PTR
-
-
-
DESP_DEB_PTR
-
-
-
-
DESP_MEM_DATA_PTR
-
DESP_MEM_DATA2
Description
Reserved
Reserved
Function data (character)
Reserved
Reserved
Reserved
Indicates whether a DCB or a DEB is input. (unsigned)
DCB input
DEB input
Omitted
Reserved
Reserved
Reserved
REPLACE option (REPLACE=X'01',
NOREPLACE=X'00') (unsigned)
Constant to be used with
DESP_OPTION
Constant to be used with
DESP_OPTION
Constant to be used with
DESP_OPTION
Reserved
Reserved
Reserved
DCB address
DEB address
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
MEM_DATA_ADDRESS
MEM_DATA entry count (unsigned)
Reserved
Reserved
Reserved
Reserved
Reserved
Chapter 10. Using the DESERV Exit
385
DESERV Exit
Table 84. DESERV PUT DESP Fields (continued)
Offset
100 (X'64')
Length or Bit
Pattern Name
4 -
Description
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
DESRC_SUCC
DESRC_INFO 4
DESRC_WARN 8
DESRC_PARM 12
Description
X'00' Successful processing
Reason Code
DESRS_SUCC
Description
Not completely successful
Results questionable
Reason Code
DESRS_DST_ALREADY_EXISTS
Description
X'00' Successful processing
DESRS_DST_COMP_SWAP_FAILED
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
DESRS_EXIT_SCOPT_INVALID
DESRS_EXIT_DST_PTR_ZERO
DESRS_INVAL_DST_HEADER
DESRS_INVAL_PREVDST_HEADER
DESRS_PREV_DSTPTR_PTR_ZERO
Description
X'44F' The EXIT_OPTION specified is not supported
X'45' The EXIT_SCOPE specified is not supported
X'44C' The caller of DESERV FUNC=EXIT supplied a DST address of zero via the EXIT_DST parameter
X'44D' The DST header is not correct
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
X'452' The pointer to the previous DST is zero.
This is checked for EXIT_OPTION=DELETE
DESRS_INVALID_PARM_LIST_HEADER X'411' The id, length, or level of the DESP is not valid
DESRS_UNSUPPORTED_FUNC
DESRS_DEB_REQUIRES_AUTH
DESRS_INVALID_DCB_PTR
DESRS_DCB_NOT_OPEN
DESRS_INVALID_DEB_PTR
X'424' The FUNC value is incorrect
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
X'421' The passed DCB is not opened
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
DESRC_CALR 16
DESRC_ENVR 20
DESRC_IOER 24
DESRC_MEDE 28
DESRC_DSLE 32
DESRC_SEVE 36
Caller has a problem
Reason Code
DESRS_DEBCHK_FAILED
DESRS_AUTH_ERROR
Resources unavailable
I/O error
Media error
Data set logical error
Severe error
Reason Code
DESRS_UNKNOWN
DESRS_ADD_STACK_FAILED
DESRS_SETLOOK_ERR
DESRS_EXTRACT_ERROR
DESRS_SET_ERROR
Description
X'41D' The DEBCHK macro failed. The DCB or DEB was not valid
X'449' Caller not supervisor state or system key
Description
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
X'407' Bad return code from SETLOCK
X'406' IGWFTOKM EXTRACT failed
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
Table 85. DESD Parameter List
Offset
00 (X'00')
00 (X'00')
00 (X'00')
1 (X'01')
Length or Bit
Pattern Name
16
16
1
1... ....
1
DESD
DESD_ENTRY
DESD_FLAG
DESD_FLAG_ALIAS
DESD_CODE
2 (X'02')
4 (X'04')
6 (X'06')
08 (X'08')
12 (X'0C')
4
4
2
2
X'02'
X'01'
X'00'
2
DESD_CODE_ERROR
DESD_CODE_NOGO
DESD_CODE_SUCC
DESD_ERRCODE
-
DESD_DATA_LEN
DESD_DATA_PTR
DESD_NAME_PTR
Description
Member data descriptor (structure)
Entry descriptor (character)
Flags (bitstring)
Alias entry
Processing code (error=X'02', not processed =X'01', successful =X'00')(unsigned)
Constant to be used with DESD_CODE
Constant to be used with DESD_CODE
Constant to be used with DESD_CODE
Error code (low order halfword of DESERV reason code if error) (unsigned)
Reserved
Length of data area (unsigned)
Address of data (address)
Address of varying length name (address)
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.
Table 86. DESERV DELETE DESP Fields
Offset
00 (X'00')
00 (X'00')
00 (X'00')
08 (X'08')
12 (X'0C')
13 (X'0D')
16 (X'10')
8
4
Length or Bit
Pattern
104
16
Name
DESP
DESP_HEADER
DESP_ID
X'04'
1
X'04'
3
1
-
DESP_LEN
DESP_LEN_IV
DESP_LEV
DESP_LEV_IV
DESP_FUNC
17 (X'11')
20 (X'14')
24 (X'18')
24 (X'18')
26 (X'1A')
27 (X'1B')
28 (X'1C')
29 (X'1D')
30 (X'1E')
31 (X'1F')
32 (X'20')
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.
X'09'
X'08'
X'07'
X'04'
3
4
X'01'
X'00'
1
1
12
2
1
1
1
1
X'02'
X'01'
X'00'
1
DESP_FUNC_UPDATE
DESP_FUNC_RENAME
DESP_FUNC_DELETE
DESP_FUNC_PUT
-
-
DESP_FUNC_GET
DESP_FUNC_OMITTED
-
-
-
DESP_DATA
DESP_LIBTYPE
-
-
-
DESP_LIBTYPE_DCB
DESP_LIBTYPE_DEB
-
DESP_LIBTYPE_OMITTED
Description
DE Services parameter list (structure)
Standard header (character)
Eyecatcher IGWDESP (character)
Length of DESP (signed)
Constant to be used with DESP_LEN
Control block level (character)
Constant to be used with DESP_LEV
Reserved
Function type (GET=X'01', PUT=X'04',
DELETE=X'07', RENAME=X'08', UPDATE=X'09')
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Reserved
Reserved
Function data (character)
Reserved
Reserved
Reserved
Indicates whether a DCB or a DEB in input. (DCB input X'02', DEB input X'01') (unsigned)
Constant to be used with DESP_LIBTYPE
Constant to be used with DESP_LIBTYPE
Constant to be used with DESP_LIBTYPE
Reserved
Reserved
Reserved
Reserved
Chapter 10. Using the DESERV Exit
389
DESERV Exit
Offset
33 (X'21')
34 (X'22')
35 (X'23')
36 (X'24')
40 (X'28')
44 (X'2C')
48 (X'30')
52 (X'34')
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')
Table 86. DESERV DELETE DESP Fields (continued)
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
1
4
1
1
Length or Bit
Pattern Name
-
-
-
-
-
-
-
DESP_DCB_PTR
-
-
-
DESP_DEB_PTR
-
-
-
-
-
-
DESP_NAME_LIST
DESP_NAME_LIST2
Description
Reserved
Reserved
Reserved
DCB address
DEB address
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
List of names to be deleted (DESL) (address)
Number of entries in DESL name list (unsigned)
Reserved
Reserved
Reserved
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
00 (X'00')
00 (X'00')
00 (X'00')
08 (X'08')
Length or Bit
Pattern Name
8
4
104
16
X'04'
DESP
DESP_HEADER
DESP_ID
DESP_LEN
DESP_LEN_IV
Description
DE Services parameter list (structure)
Standard header (character)
Eyecatcher IGWDESP (character)
Length of DESP (signed)
Constant to be used with DESP_LEN
390
z/OS DFSMSdfp Advanced Services
DESERV Exit
29 (X'1D')
30 (X'1E')
31 (X'1F')
32 (X'20')
33 (X'21')
34 (X'22')
35 (X'23')
36 (X'24')
40 (X'28')
44 (X'2C')
48 (X'30')
52 (X'34')
56 (X'38')
60 (X'3C')
64 (X'40')
68 (X'44')
72 (X'48')
4
4
4
4
4
4
4
1
1
4
4
4
1
1
1
1
X'02'
X'01'
X'00'
1
Table 87. DESERV RENAME DESP Fields (continued)
Offset
12 (X'0C')
13 (X'0D')
16 (X'10')
Length or Bit
Pattern Name
3
1
1
X'04'
-
DESP_LEV
DESP_LEV_IV
DESP_FUNC
17 (X'11')
20 (X'14')
24 (X'18')
24 (X'18')
26 (X'1A')
27 (X'1B')
28 (X'1C')
X'09'
X'08'
X'07'
X'04'
3
4
X'01'
X'00'
1
1
1
12
2
DESP_FUNC_UPDATE
DESP_FUNC_RENAME
DESP_FUNC_DELETE
DESP_FUNC_PUT
-
-
DESP_FUNC_GET
DESP_FUNC_OMITTED
-
DESP_DATA
-
-
DESP_LIBTYPE
-
-
-
-
DESP_LIBTYPE_DCB
DESP_LIBTYPE_DEB
-
DESP_LIBTYPE_OMITTED
-
-
-
-
-
-
-
-
-
-
DESP_DCB_PTR
DESP_DEB_PTR
Description
Control block level (character)
Constant to be used with DESP_LEV
Reserved
Function type (GET=X'01', PUT=X'04',
DELETE=X'07', RENAME=X'08', UPDATE=X'09')
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Reserved
Reserved
Function data (character)
Reserved
Reserved
Reserved
Indicates whether a DCB or a DEB is input.
(DCB,DEB) (DCB input X'02', DEB input X'01')
(unsigned)
Constant to be used with DESP_LIBTYPE
Constant to be used with DESP_LIBTYPE
Constant to be used with DESP_LIBTYPE
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
DCB address
DEB address
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Chapter 10. Using the DESERV Exit
391
DESERV Exit
Table 87. DESERV RENAME DESP Fields (continued)
Offset
76 (X'4C')
80 (X'50')
4
4
Length or Bit
Pattern Name
-
DESP_NAME_LIST
84 (X'54')
88 (X'58')
92 (X'5C')
96 (X'60')
100 (X'64')
4
4
4
4
4
-
-
-
-
DESP_NAME_LIST2
Description
Reserved
List of pairs of names for rename operations
(DESL) (address)
Number of entries in DESL name list (unsigned)
Reserved
Reserved
Reserved
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
00 (X'00')
00 (X'00')
00 (X'00')
08 (X'08')
12 (X'0C')
13 (X'0D')
16 (X'10')
Length or Bit
Pattern Name
8
4
104
16
X'04'
1
X'04'
3
1
DESP
DESP_HEADER
DESP_ID
DESP_LEN
DESP_LEN_IV
DESP_LEV
-
DESP_LEV_IV
DESP_FUNC
17 (X'11')
20 (X'14')
X'09'
X'08'
X'07'
X'04'
3
4
X'01'
X'00'
DESP_FUNC_UPDATE
DESP_FUNC_RENAME
DESP_FUNC_DELETE
DESP_FUNC_PUT
-
-
DESP_FUNC_GET
DESP_FUNC_OMITTED
Description
DE Services parameter list (structure)
Standard header (character)
Eyecatcher 'IGWDESP' (character)
Length of DESP (signed)
Constant to be used with DESP_LEN
Control block level (character)
Constant to be used with DESP_LEV
Reserved
Function type (GET=X'01', PUT=X'04',
DELETE=X'07', RENAME=X'08', UPDATE=X'09')
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Constant to be used with DESP_FUNC
Reserved
Reserved
392
z/OS DFSMSdfp Advanced Services
DESERV Exit
29 (X'1D')
30 (X'1E')
31 (X'1F')
32 (X'20')
33 (X'21')
34 (X'22')
35 (X'23')
36 (X'24')
40 (X'28')
44 (X'2C')
48 (X'30')
52 (X'34')
56 (X'38')
60 (X'3C')
64 (X'40')
68 (X'44')
72 (X'48')
76 (X'4C')
80 (X'50')
Table 88. DESERV UPDATE DESP Fields (continued)
Offset
24 (X'18')
24 (X'18')
26 (X'1A')
27 (X'1B')
28 (X'1C')
Length or Bit
Pattern Name
1
1
12
2
1
-
-
-
DESP_DATA
DESP_LIBTYPE
4
4
4
4
4
4
4
4
4
4
4
1
1
1
1
1
1
4
X'02'
X'01'
X'00'
1
-
-
-
-
DESP_LIBTYPE_DCB
DESP_LIBTYPE_DEB
-
DESP_LIBTYPE_OMITTED
-
-
DESP_DCB_PTR
-
-
-
-
-
-
-
DESP_DEB_PTR
-
-
DESP_NAME_LIST
84 (X'54')
88 (X'58')
92 (X'5C')
96 (X'60')
100 (X'64')
4
4
4
4
4
-
-
-
-
DESP_NAME_LIST2
Description
Function data (character)
Reserved
Reserved
Reserved
Function subtype (DCB,DEB) (DCB input X'02',
DEB input X'01') (unsigned)
Constant to be used with DESP_LIBTYPE
Constant to be used with DESP_LIBTYPE
Constant to be used with DESP_LIBTYPE
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
DCB address
DEB address
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
List of SMDEs with imbedded PMAR (and
PMARL) to update the directory information
(DESL) (address)
Number of entries in DESL name list (unsigned)
Reserved
Reserved
Reserved
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:
0
1
Register
Contents
not applicable address of DESX
2-12
13
14
15
not applicable address of register save area return address 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
15
restored to contents at entry 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
X'0'
X'4'
X'8'
X'12'
X'00'
X'400'
X'411'
X'415'
X'41E'
X'41F'
X'421'
X'422'
X'423'
X'424'
X'427'
X'428'
DESRC_SUCC
DESRS_SUCC
DESRC_INFO
DESRS_NAME_
NOT_DEFINED
DESRC_WARN
DESRC_PARM
Description
Successful
Successful
Not completely successful.
Name to be replaced did not previously exist
Results questionable
DESRS_INVALID_
PARM_LIST_HEADER
DESRS_PDS_
NOT_SUPPORTED
Missing or invalid parameters
The id, length, or level of the DESP is not valid
This function requires a
PDSE data set
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
DESRS_DCB_NOT_
OPEN_OUTPUT
With function PUT the DCB must have been opened for output
DESRS_DCB_ NOT_OPEN The passed DCB is not opened
DESRS_INVALID_
DCB_PTR
The address of the DCB is 0
DESRS_DEB_
REQUIRES_AUTH
To pass the DEB, the caller must be in supervisor state or a privileged key
The FUNC value is incorrect DESRS_
UNSUPPORTED_FUNC
DESRS_INVALID_
MEM_DATA_CNT
DESRS_INVALID_
MEM_DATA_PTR
The count of entries in the
MEM_DATA block is 0
The address of the
MEM_DATA block is 0
396
z/OS DFSMSdfp Advanced Services
DESERV Exit
Table 89. Return and Reason Codes for the Exit DESERV Function (continued)
X'20'
X'24'
X'28'
X'32'
X'36'
Return Code
X'16'
Reason Code
X'429'
X'3FD'
X'400'
X'40E'
X'40F'
X'410'
X'412'
X'413'
X'414'
X'41D'
X'425'
X'43A'
X'43C'
Symbolic name
DESRS_INVALID_
PUT_OPTION
Description
The PUT function requires that the OPTION field be specified
Caller has a problem DESRC_CALR
DESRS_PRI_
NM_THIS_FILE
DESRS_NAME_
ALREADY_EXISTS
DESRS_NAME_
ALREADY_EXISTS
DESRS_NP_
PRIMARY_NAME
Alias name is same name as primary name for this member
Name to be replaced did not previously exist
The PUT failed because of a name conflict
DESRS_INVALID_
NAME_PREFIX
DESRS_MORE_
THAN_!_PRIMARY
DESRS_ INVALID_MLT
DESRS_ INVALID_CT
DESRS_DATA_
LENGTH_ERROR
DESRS_NAME_
IS_PRIMARY_NAME
The MEM_DATA must have one member designated as primary
The first 8 bytes of a name were all X'FF'
The MEM_DATA must have only one member designated as primary
MLT is not valid
Connect token is not valid
DESRS_DEBCHK_ FAILED The DEBCHK macro failed, the DCB or DEB was not valid
DESRS_INVALID_
NAME_LENGTH
The length of an alias name was either 0 or greater than
8
The DESD data length is not valid, data length must be greater than 0 and less than
108 bytes
The alias name specified is a primary name and the options did not allow for deleting primary name
X'407'
X'437'
DESRC_ENVR
DESRC_IOER
DESRC_MEDE
DESRC_DSLE
DESRC_SEVE
DESRS_ SETLOOK_ERR
DESRS_ADD_
STACK_FAILED
Resources unavailable
I/O error
Media Error
Data Set logical error
Severe error
Bad return code from
SETLOCK
Non-zero return code from an IGWFESTK request
Chapter 10. Using the DESERV Exit
397
DESERV Exit
Table 89. Return and Reason Codes for the Exit DESERV Function (continued)
Return Code Reason Code Symbolic name
X'447' DESRS_UNKNOWN
X'0C' X'469' DESRS_DST_EXIT_PTR_
NOT_COMMON
Description
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.
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
LR
14,12,12(13)
12,15
.
.
.
LA
ST
ST
LR
2,SAVE
2,8(13)
13,SAVE+4
13,2
*
*
*
*
* ESTABLISH THE TASK LEVEL EXIT
*
BUILD THE DST TO REPRESENT MY TASK LEVEL EXIT
LA 3,MY_DST
USING DST,3
XC
MVC
DST,DST
ADDRESSABILITY TO MY DST
MAP DST
CLEAR MY DST STORAGE
DST_ID,DST_ID_CONST SET EYECATCHER IN DST
*
LA
ST
MVI
OI
MVC
15,DST_LEN_IV(,0)
15,DST_LEN
DST_LEV,DST_LEV_IV
SAVE REGISTERS
ESTABLISH BASE REGISTER
ADDRESS REGISTER SAVE AREA
FORWARD CHAIN SAVE AREA
BACKWARD CHAIN SAVE AREA
ESTABLISH SAVE AREA
GET LENGTH OF DST
SET LENGTH OF DST
SET LEVEL OF DST USED
DST_FLAGS,DST_FLAGS_PROP SET FLAG TO PROPAGATE THIS
TO ATTACHED TASKS.
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
EXIT
*
*
*
*
*
*
*
*
*
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
LM
13,SAVE+4
14,12,12(13)
SR
BR
15,15
14
SET RETURN CODE
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_STUFF DS CL8
MY APPLICATION BLOCK
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
ADDR_DESEXIT
DST_ID_CONST
EXTRN DESEXIT
DC A(DESEXIT) ADDRESS OF MY TASK LEVEL EXIT
DC CL8’IGWDST ’ DST EYECATCHER
*
CURRENT_DSTPTR DS F
*
SAVE DS
END
18F
DST
ADDRESS OF CURRENT TASK LEVEL
DST
REGISTER SAVE AREA
*
*
*
*
*
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
DESEXIT RMODE ANY
*
Must be AMODE 31
Could be RMODE 24 if required
* entry code to save registers and establish base register.
USING *,12
STM
LR
14,12,12(13)
12,15
SAVE REGISTERS
ESTABLISH BASE REGISTER
LA
ST
ST
LR
2,SAVE
2,8(13)
13,SAVE+4
13,2
ADDRESS REGISTER SAVE AREA
FORWARD CHAIN SAVE AREA
BACKWARD CHAIN SAVE AREA
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
ST
2,2
2,EXIT_RC
LR 2,1
USING DESX,2 clear reg initialize return code get the DESX address in reg 2 map the DESX
L
LR
LA
SR
3,DESX_DST_PTR
4,3 get address of DST get address of DST
5,MY_DST-MY_BLOCK(,0) get offset to DST within MY_BLOCK
4,5
USING MY_BLOCK,4 get the address of MY_BLOCK 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
ICM
15,15 simulate previous exit’s return code
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
L
5,DESX_DST_PTR-DESX(,1) Set previous DST address in DESX
15,DST_EXIT_PTR-DST(,5)
BALR 14,15 get address of previous exit 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
BO
DESX_FLAGS,DESX_POST_BIT is this post-processing call
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.
POST
*
*
CLC
BE
EQU
EXIT_RC,ZERO
RETURN
* was return code zero yes, branch to return to deserv either called exit performed the deserv function, or this is a post
L
USING
CLI
6,DESX_DESP_PTR
DESP,6 processing exit call.
get the DESERV parameter list (DESP) map DESP
DESP_FUNC,DESP_FUNC_GET is this a function GET call
BNE
CLC
RETURN no, branch
DESX_REASON_CODE+2(2),=AL2(DESRS_SUCC) check low order
*
*
BE
CLC
BNE
GOODDATA halfword of reason code for success branch if DESERV GET was successful
DESX_REASON_CODE+2(2),=AL2(DESRS_NOTFOUND) check for
BADDATA
GOODDATA EQU * some members not found branch if some other error
*
* Process the entries in the names list that were found
*
.
B
.
.
BADDATA EQU
.
.
.
*
RETURN EQU
*
RETURN
*
* return to the caller (DESERV)
Return to caller (DESERV)
* restore registers, FREEMAIN storage, etc.
*
L
L
15,EXIT_RC
13,SAVE+4 set return code
L
LM
BR
14,12(13)
0,12,20(13)
14 restore return address restore callers other registers return to deserv
Figure 49. Sample DESERV Exit Routine Part 2 of 3
402
z/OS DFSMSdfp Advanced Services
*
* CONTROL INFORMATION
*
SAVE
ZERO
EXIT_RC
DS 18F
DC F’0’
DC F’0’
REGISTER SAVE AREA constant of zero
Return code to pass back to DESERV
DESX_ID_CONST DC CL8’IGWDESX ’ EYECATCHER FOR DESX
MY_DESX_STG_PTR DC F’0’
*
MY_BLOCK DSECT
MY_APPLICATION_STUFF DS CL8
MY_DST
PREV_DST_PTR
*
DS
DS
ADDRESS OF GETMAINED STORAGE FOR
DESX TO PASS TO PREVIOUS EXIT.
MY APPLICATION BLOCK
MY APPLICATION STUFF
CL(DST_LEN_IV) MY DST IMBEDED IN MY BLOCK
F
IGWDES
IGWSMDE
IEWPMAR
ADDRESS OF PREVIOUS TASK LEVEL EXIT
DESERV MAPPINGS
DIRECTORY ENTRY
PROGRAM MANAGEMENT ATTRIBUTE RECORD
THE PMAR IS A SUB RECORD OF THE SMDE
END
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 EXEC PGM=IEFBR14
//MKFS 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 maintain the original file system name, delete the existing file system first, and then restore it using DFSMSdss without renaming it.
Chapter 11. Managing Hierarchical File System Data Sets
407
Planning for HFS
v Remove files from the file system by either deleting them or by moving them to another file system. If it is impossible to remove the chosen files from a particular directory in the file system, it may be possible to remove other files from a different directory in the same file system. The objective is to reduce the size of the file system.
v Create a new file system on another volume, or set of volumes, and move some files from the full file system to the new file system. To avoid problems that can result from this approach, define symbolic links using the original names.
v Add another volume to the file system candidate volume list with the IDCAMS
ALTER ADDVOLUMES command. The file system must be unmounted and remounted for the additional volumes to be usable by the HFS.
v The storage administrator or system programmer can monitor the space in a file system by mounting an HFS with parm FSFULL. For example, mount parm('FSFULL(70,10)') will cause HFS to issue message IGW023A when the file system is 70 percent full and then issues an additional IGW023I messages when the file system is 80 and 90 percent full.
Managing File System Activity
If activity for a file system becomes so extensive that accesses are slow, you can do one of the following tasks: v Move the file system to a volume that processes I/O more quickly, for example, a volume that has a faster channel or a cached storage control.
v Move a subtree from the full file system into a new file system on a different volume. Mount the new file system on the now-empty directory, which was the head of the subtree. This divides I/O activity between two volumes. To avoid failures from this action, define symbolic links using the original names.
Accessing HFS Data Set Attributes
Any application (for example, Interactive System Productivity Facility (ISPF) option
3.4I or DCOLLECT) that requests size information about HFS file system requires
OMVS to service that request. This means that the user ID must be defined to
OMVS and have Resource Access Control Facility (RACF) authority to access the data set. The HFS file system must be either mounted on this file system or mountable (that is, not already mounted READ/WRITE on another system).
Transporting a File System
You might also want to copy a data set to a storage medium that can be physically transported to another location. In order to do that, perform one of the following tasks: v Use either the PAX, CPIO, or TAR shell commands to copy the file system in tape archive (TAR) format.
v Have an authorized user logically unmount the file system, allocate an HFS data set with a different data set name, and use the DFSMSdss dump utility to copy the old file system to the new data set.
408
z/OS DFSMSdfp Advanced Services
Planning for HFS
Removing (Deleting) a File System
If you mount the file system (HFS data set) to a different file system or you want to delete it, first logically unmount it using the TSO/E UNMOUNT command against the HFS data set containing it. Then you can use either or both of the
MOUNT commands (see “Adding and Mounting File Systems to the Root File
You can eliminate the file system by using any of the following techniques: v Use the DELETE command (IDCAMS or TSO).
v Execute an IEFBR14 job with DISP=(OLD,DELETE) specified for the HFS data set.
v ISPF option 3.x.
v Use the SCRATCH and UNCATLG commands of IEHPROGM.
Migrating a File System
If a file system is unmounted and remains so for a predetermined time, the system can migrate it to a lower priority storage medium. The system automatically recalls a migrated file system from migration storage if a mount command is issued for the file system.
If you plan to migrate HFS data sets, consider migrating them only to level 1
(DASD) storage. Recalling a data set that was migrated to tape could adversely affect performance because of the time required to physically mount the tape volume.
If the tape is in an automated library, then recalling it should be much faster than if the system has to request an operator to mount it.
Backing Up File Systems
DFSMShsm provides automatic backup facilities for HFS data sets. You can back up mountable file systems by periodically backing up the HFS data sets that contain them; the data sets can be restored if necessary. DFSMShsm is also used for migrating and restoring unmounted file systems.
You can manually back up a mountable file system, including the root file system, periodically with DFSMSdss data set dumps. To do this, issue the DFSMSdss
DUMP command. This quiesces activity against the specified HFS data set, then invokes backup processing. When the backup is complete, the file system is unquiesced and user activity can resume.
Retain periodic DFSMSdss data set dumps of file systems in case a program fails and damages files and directories. Keep this backup in another area or different building in case the computer site experiences physical damage.
There is no facility for automatically backing up individual files within an HFS data set. You can manually back up files with the PAX, CPIO, and TAR commands.
For more information on using DFSMSdss, refer to the DFSMSdss section of z/OS
DFSMSdfp Storage Administration.
Chapter 11. Managing Hierarchical File System Data Sets
409
Planning for HFS
Recovering a Backed-Up File System
If a file system is damaged, you can recover by replacing it with a saved version that was created from an earlier backup. To recover a backed up file system, you must perform the following tasks:
1.
Notify all users to stop all activity on the damaged file system.
2.
Have an authorized user enter the TSO/E UNMOUNT command with the
IMMEDIATE option to logically unmount the damaged file system. If the unmount fails, reenter the UNMOUNT command with the FORCE option.
3.
Use the DFSMSdss dump utility to restore the backed up file system to a replacement file system (HFS data set). You can do this simultaneously with the previous steps.
4.
Have an authorized user enter a TSO/E MOUNT command to logically mount the replacement file system. Ensure that the MOUNT commands in the
BPXPRMxx member in SYS1.PARMLIB are consistent with this MOUNT command.
5.
Issue a broadcast message to all users or a message to all z/OS UNIX users when they invoke the shell, telling them that you have mounted a back-level file system and informing them of the mount point. Users must recreate and add any files added since the file system was backed up.
You might choose a more disruptive method to recover a backed up file system for the root file system. Refer to z/OS UNIX System Services Planning, “Shutting Down z/OS Unix“, for more information on how to perform a shutdown.
HFS Deferred File System Synchronization
Normal HFS disk hardening executes under a sync daemon that runs periodically to write out all file and metadata changes that have occurred since the last time the sync daemon ran. If a large number of files are created, modified, or deleted within the time span that is between the file system sync intervals, then with the next file system sync, these file changes are collected and the disk version of the file system is sync'ed with a greatly reduced number of media manager calls. This reduces the actual I/O activity.
The reduced I/O can have a dramatic effect on performance, because the default sync daemon interval is one minute. The sync daemon runs in the OMVS address space and is independent of any user request to the file system.
When the sync daemon runs, all the HFS changes are batched into one large I/O request that gets passed to the media manager. The intent is to perform one long
I/O operation to the HFS on disk. However, even with optimal conditions, where the HFS resides on one volume and is contained within a single extent, it is necessary to have a few media manager calls during the disk hardening I/O operation. If the HFS has multiple extents or resides on multiple volumes, multiple channel programs must be built, because a single I/O operation cannot span multiple extents.
In addition to the sync daemon interval, HFS also supports the individual file sync
(fsync). The fsync can be performed at any time by the application program.
However, be aware that an fsync will result in the entire file system being sync'ed.
It is very important to note that during the HFS file system sync operation, the sync task runs independently of the users that are currently accessing the HFS.
When the sync task runs, it obtains an exclusive latch for the file system being sync'ed. This latch is held for the duration of the file system sync operation. While
410
z/OS DFSMSdfp Advanced Services
Planning for HFS
this latch is held UNIX system services users of the HFS file system will not be able to access the HFS. When the sync task runs, the HFS must:
1.
Update all of the new or changed files' metadata
2.
Delete structures for any removed files
3.
Update the internal HFS storage maps within the HFS attributes directory
4.
Call the media manager to perform the I/O operation that makes the changes to the disk version of the HFS data set.
The I/O operation is synchronous, which means that HFS sync task will be suspended for the duration of the media manager call. Normally, this file system sync lockout condition is brief, lasting for a few seconds, and is rarely noticed by the end user. However, in some situations the file system sync lockout could last much longer. The duration of the lockout depends on the sync interval, the amount of work that must be performed by the SYNC task, and the performance of the
I/O subsystem.
To minimize the effect on applications from the file system sync operations that take a long time to complete, you can do one or more of the following:
1.
Mount the affected HFS with a shorter sync interval. This will reduce overall
HFS performance, but the sync lockout will not be as long.
2.
Split the HFS into two or more smaller HFS data sets.
3.
Avoid high impact commands such as "rm -R" on large directories.
How to specify a SYNC value
The default HFS SYNC daemon interval value is 60 seconds. You may override this default by changing the SYNCDEFAULT option of the FILESYSTYPE parameter in the BPXPRMxx member of SYS1.PARMLIB. Individual HFS data sets can have an overriding SYNC value. This can be accomplished by specifying a SYNC value on the ROOT parameter, or a SYNC value on the MOUNT parameter in the
BPXPRMxx member of SYS1.PARMLIB.
Refer to z/OS MVS Initialization and Tuning Reference for details on how to specify
FILESYSTYPE, ROOT, and MOUNT parameters. Additionally, individual HFS data sets can be mounted by the user with the MOUNT command that specifies a
SYNC value.
Using pfsctl (BPX1PCT) Physical File System Control for HFS
The following information describes the use of pfsctl, BPX1PCT callable service, for
HFS.
The pfsctl callable service, BPX1PCT, conveys a command and an argument to a physical file system. The meaning of the command and argument are specific to the physical file system and are defined by the physical file system.
Format
:
CALL BPX1PCT,(File_System_type,
Command,
Argument_length,
Argument,
Return_value,
Return_code,
Reason_code)
File_System_type:
Chapter 11. Managing Hierarchical File System Data Sets
411
Planning for HFS
Type:
Length:
Character string
8 bytes
Character string: HFS
Command:
Type:
Length:
Integer
Fullword
If the physical file system is an HFS data set, you can code one of these values:
X’40000001’
X’00000002’
X’40000003’
X’40000004’
X’00000005’
DisplayBufferLimits
ChangeBufferLimits
DisplayGlobalStats
DisplayFSStats
ExtendFS
These HFS-defined commands and the data areas for each are defined in
GFUMPCTL, located in SYS1.MODGEN.
Argument_Length:
A 4-byte integer. See below for the valid values.
Argument:
Structure as described below and in Table 91 on page 416, Table 92 on
page 417, Table 93 on page 418, or Table 94 on page 419.
Return Value:
Fullword
Return_Code:
A 4-byte integer that BPX1PCT sets to one of the values described in
Reason_Code:
A 4-byte integer that BPX1PCT sets to one of the values described
If the physical file system is an HFS data set, then the following apply: v
v
“Output from TRKCALC” on page 315
v
“ChangeBufferLimits Command” on page 413
v
“DisplayGlobalStats Command” on page 413
v
“DisplayFSStats Command” on page 414
v
“BPX1PCT Return and Reason Codes” on page 415
DisplayBufferLimits Command
Function:
The DisplayBufferLimits command returns the storage limits in the data area, specifically the VMAX and FMIN values for the HFS buffers currently in effect.
Command:
X'40000001'
Argument_Length:
The argument length is the length of the data area. The data area must be
at least the length of PCTL_BFRLIMITS_TYPE. See Table 91 on page 416.
Argument:
PCTL_BFRLIMITS_TYPE
412
z/OS DFSMSdfp Advanced Services
Planning for HFS
Usage Notes
1.
The caller does not have to be authorized.
2.
VMAX and FMIN values are both in megabytes (MB).
3.
This command is equivalent to the confighfs shell command: confighfs -l
ChangeBufferLimits Command
Function:
The ChangeBufferLimits command modifies the storage limits, specifically the VMAX and FMIN values, for HFS buffers as requested in the data area.
Command:
X'00000002'
Argument_length:
The argument length is the length of the data area. The data area must be
at least the length of PCTL_BFRLIMITS_TYPE. See Table 91 on page 416.
Argument:
PCTL_BFRLIMITS_TYPE
Usage Notes
1.
The following fields must be set within this structure: v The PCTL_BL_ACTION flag must be set.
v Modify VMAX by setting the PCTL_BL_VMAX flag and specifying the new
VMAX value in the field PCTL_BL_VMAX_VAL.
v Modify FMIN by setting the PCTL_BL_FMIN flag and specifying the new
FMIN value in the field PCTL_BL_FMIN_VAL.
2.
The caller must be a superuser.
3.
A request to modify both VMAX and FMIN can be made in one call.
4.
The VMAX and FMIN values are in megabytes (MB).
5.
This command is equivalent to the confighfs shell commands. The following confighfs command sets virtual storage maximum (VMAX) to n, where n is in
MB.: confighfs -v n
The following confighfs command sets virtual storage minimum (FMIN) to n, where n is in MB.
confighfs -f n
DisplayGlobalStats Command
Function:
The DisplayGlobalStats command returns HFS global system level statistics in the data area.
Command:
X'40000003'
Argument_Length:
The argument length is the length of the data area. The data area must be
at least the length of PCTL_GLOBALSTATS_TYPE. See Table 92 on page
Chapter 11. Managing Hierarchical File System Data Sets
413
Planning for HFS
Argument:
PCTL_GLOBALSTATS_TYPE
Usage Notes
1.
The caller does not have to be authorized.
2.
This command is equivalent to the command: confighfs -q
DisplayFSStats Command
Function:
The DisplayFSStats command returns HFS file system level statistics in the data area. The values returned for file system statistics are associated with the current mount of the specified file system.
Command:
X'40000004'
Argument_Length:
The argument length is the length of the data area. The data area must be
the length of PCTL_FSSTATS_TYPE. See Table 93 on page 418.
Argument:
PCTL_FSSTATS_TYPE
Usage Notes
1.
The file system name must be supplied as input in the field PCTL_FS_NAME within the PCTL_FSSTATS_TYPE structure.
2.
The caller does not have to be authorized.
3.
This command is equivalent to the confighfs shell command: confighfs pathname where the pathname is an absolute or relative pathname that identifies the HFS.
ExtendFS Command
Function:
The ExtendFS command attempts to extend (allocate additional disk space for) the specified file system by the requested amount as specified in the data area.
Command:
X'00000005'
Argument_Length:
The argument length is the length of the data area. The length of the data
area must be at least the length of PCTL_EXTENDFS_TYPE. See Table 94 on page 419.
Argument:
PCTL_EXTENDFS_TYPE
Usage Notes
v The following fields must be set within this structure:
– Set PCTL_EXT_FSNAME to the name of the file system to be extended.
– If your request is to allocate space on a new volume, set the
PCTL_EXT_NEW_VOL flag on.
– Set PCTL_EXT_UNIT to one of the following units to extend:
414
z/OS DFSMSdfp Advanced Services
Planning for HFS
1.
ExtendFS_UNIT_MB to indicate that the amount to extend is in megabytes
(MB).
2.
ExtendFS_UNIT_TRK to indicate that the amount to extend is in tracks.
3.
ExtendFS_UNIT_CYL to indicate that the amount to extend is in cylinders.
– Set PCTL_EXT_AMT to the amount to be extended.
– The caller must be a superuser.
– If the flag PCTL_EXT_NEW_VOL = off, an attempt to obtain additional space is only made on the last volume of the HFS. The HFS will not be extended to a new volume.
– If the flag PCTL_EXT_NEW_VOL = on, an attempt to obtain additional space is only made on a new volume. In this case, candidate volumes must exist for the HFS, and the candidate volumes must have existed at the time of the current mount of the HFS.
– If a secondary space amount exists for the HFS, it is ignored.
– If the entire amount requested cannot be obtained, the operation fails.
v This command is equivalent to the confighfs shell command: confighfs -x size pathname To extend on the same volume confighfs -xn size pathname To extend to a new volume where size is the amount to be extended suffixed by the extend unit of M
(megabytes), T (tracks), or C (cylinders) and pathname is an absolute or relative pathname that identifies the HFS.
BPX1PCT Return and Reason Codes
Using BPX1PCT for HFS returns a non-zero return code and reason code only if
the return value is -1. Table 90 contains a list of return and reason codes returned
by BPX1PCT for the HFS DisplayBufferLimits, ChangeBufferLimits,
DisplayGlobalStats, DisplayFSStats, and ExtendFS commands.
Table 90. BPX1PCT - Return Codes and Reason Codes
Return Code
0
EINVAL
Reason Code
0
5B360106
Description
Successful completion
The HFS pfsctl service
ExtendFS function was called with an invalid
PCTL_EXT_UNIT parameter.
Command
ExtendFS only
EFAULT
5B360108
5B360102
5B360103
The HFS pfsctl ExtendFS function was called with an extend value of zero.
The HFS pfsctl service was called with an unsupported command code.
The data area address provided for the HFS pfsctl command is zero.
ExtendFS only
5B360107 The HFS pfsctl service
ChangeBufferLimits or
ExtendFS function was called by an unauthorized caller.
Chapter 11. Managing Hierarchical File System Data Sets
415
Planning for HFS
Table 90. BPX1PCT - Return Codes and Reason Codes (continued)
Return Code
EMVSERR
ENOBUFS
ENOENT
ENOSPC
Reason Code
5B360101
5B360104
5B360105
5B27C005
Description
An error occurred during the add local recovery routine function.
The data area length provided for the HFS pfsctl command was less than the minimum size required to complete the request.
An HFS pfsctl service was called with an unmounted
HFS.unted
DADSM error occurred; no space available to extend the
HFS data set
Command
DisplayFSStats and
ExtendFS only.
ExtendFS only
>80000000
EIO
EMVSPFSPERM
EMVSPARM
5B27C00A
5B27xxxx
5BB3xxxx
5B36000E
File system was in an HFS Out of Space error state and the extend amount was insufficient to meet the requirement to complete the sync shadow write. The reason code contains the 2's complement of the additional number of tracks required.
ExtendFS only
DADSM error occurred; I/O error VTOC
ExtendFS only
Unexpected error encountered ExtendFS only
Unexpected error encountered ChangeBufferLimits only
VMAX below minimum
(VMAX set to minimum)
ChangeBufferLimits only
5B36000F
5B360010
5B360014
FMIN exceeded VMAX (FMIN set to VMAX)
ChangeBufferLimits only
FMIN at maximum available
(FMIN set to maximum)
VMAX below FMIN (VMAX set to FMIN)
ChangeBufferLimits only
ChangeBufferLimits only
Table 91 shows the GFUMPCTL structure for the DisplayBufferLimits and the
ChangeBufferLimits commands:
Table 91. Structure for the DisplayBufferLimits and ChangeBufferLimits Commands (GFUMPCTL)
Offsets
0 (0)
0 (0)
Type
STRUCTURE
CHARACTER
Length
28
1
Name
PCTL_BFRLIMITS_TYPE
PCTL_BL_FLGS
Description
Flags
416
z/OS DFSMSdfp Advanced Services
Planning for HFS
Table 91. Structure for the DisplayBufferLimits and ChangeBufferLimits Commands (GFUMPCTL) (continued)
Offsets Type
1... ....
Length
1
Name
PCTL_BL_ACTION
Description
off
: display buffer limits
1 (1) CHARACTER
1... ....
2 (2)
4 (4)
8 (8)
12 (C)
.1.. ....
CHARACTER
SIGNED
SIGNED
CHARACTER
28 (1C) CHARACTER
1
1
4
4
16
PCTL_BL_LIMIT
PCTL_BL_VMAX
PCTL_BL_FMIN
*
PCTL_BL_VMAX_VAL
PCTL_BL_FMIN_VAL
*
PCTL_BL_END on : change buffer limits
Limits to be modified
Modify VMAX request
Modify FMIN request
Reserved
Modify VMAX value
Modify FMIN value
Reserved
Table 92 shows the GFUMPCTL structure for the DisplayGlobalStats command:
Table 92. Structure for the DisplayGlobalStats Command (GFUMPCTL)
Offsets Type
0 (0)
0 (0)
(0) STRUCTURE
CHARACTER
8 (8) CHARACTER
16 (10) SIGNED
Length
8
4
200
8
Name
PCTL_GLOBALSTATS_TYPE
PCTL_GS_CURR_TIME
*
PCTL_GS_TOTVIRT
20 (14)
24 (18)
24 (18)
26 (1A)
28 (1C)
32 (20)
36 (24)
44 (2C)
52 (34)
52 (34)
54 (36)
56 (38)
60 (3C)
64 (40)
72 (48)
80 (50)
80 (50)
82 (52)
84 (54)
88 (58)
92 (5C)
100 (64)
108 (6C) CHARACTER
108 (6C) UNSIGNED
110 (6E)
112 (70)
SIGNED
CHARACTER
UNSIGNED
UNSIGNED
SIGNED
SIGNED
UNSIGNED
UNSIGNED
CHARACTER
UNSIGNED
UNSIGNED
SIGNED
SIGNED
UNSIGNED
UNSIGNED
CHARACTER
UNSIGNED
UNSIGNED
SIGNED
SIGNED
UNSIGNED
UNSIGNED
UNSIGNED
SIGNED
4
28
2
2
4
4
8
8
28
2
2
4
4
8
8
28
2
2
4
4
8
8
28
2
2
4
PCTL_GS_TOTFIX
PCTL_GS_BP1
PCTL_GS_BP1_BFRSIZE
PCTL_GS_BP1_DSCNT
PCTL_GS_BP1_TOTVIRT
PCTL_GS_BP1_TOTFIX
PCTL_GS_BP1_FIXD_Y
PCTL_GS_BP1_FIXD_N
PCTL_GS_BP2
PCTL_GS_BP2_BPRSIZE
PCTL_GS_BP2_DSCNT
PCTL_GS_BP2_TOTVIRT
PCTL_GS_BP2_TOTFIX
PCTL_GS_BP2_FIXD_Y
PCTL_GS_BP2_FIXD_N
PCTL_GS_BP3
PCTL_GS_BP3_BFRSIZE
PCTL_GS_BP3_DSCNT
PCTL_GS_BP3_TOTVIRT
PCTL_GS_BP3_TOTFIX
PCTL_GS_BP3_FIXD_Y
PCTL_GS_BP3_FIXD_N
PCTL_GS_BP4
PCTL_GS_BP4_BFRSIZE
PCTL_GS_BP4_DSCNT
PCTL_GS_BP4_TOTVIRT
Description
Current timestamp
Reserved
Combined total virtual (in pages) in use by all buffer pools
Combined total fixed (in pages) in use by all buffer pools
Stats for buffer pool 1
Size of each buffer (in pages)
Number of data spaces in pool
Total virtual used by this pool
Total fixed used by this pool
Times a buffer was already fixed prior to an I/O request
Times a buffer was not already fixed prior to an I/O request
Stats for buffer pool 2
Size of each buffer (in pages)
Number of data spaces in pool
Total virtual used by this pool
Total fixed used by this pool
Times a buffer was already fixed prior to an I/O request
Times a buffer was not already fixed prior to an I/O request
Stats for buffer pool 3
Size of each buffer (in pages)
Number of data spaces in pool
Total virtual used by this pool
Total fixed used by this pool
Times a buffer was already fixed prior to an I/O request
Times a buffer was not already fixed prior to an I/O request
Stats for buffer pool 4
Size of each buffer (in pages)
Number of data spaces in pool
Total virtual used by this pool
Chapter 11. Managing Hierarchical File System Data Sets
417
Planning for HFS
Table 92. Structure for the DisplayGlobalStats Command (GFUMPCTL) (continued)
Offsets Type
116 (74) SIGNED
120 (78) CHARACTER
128 (80)
136 (88)
144 (90)
152 (98)
CHARACTER
CHARACTER
CHARACTER
CHARACTER
160 (A0) CHARACTER
168 (A8) CHARACTER
200 (C8) CHARACTER
Length
4
8
8
8
8
8
8
32
Name
PCTL_GS_BP4_TOTFIX
PCTL-GS_BP4_FIXD_Y
PCTL_GS_BP4_FIXD_N
PCTL_GS_META_Y
PCTL_GS_META_N
PCTL_GS_RPN0_Y
PCTL_GS_RPN0_N
*
PCTL_GS_END
Description
Total fixed used by this pool
Times a buffer was already fixed prior to an I/O request
Times a buffer was not already fixed prior to an I/O request
Times metadata in cache on a lookup
Times metadata not in cache on a lookup
Times RPN0 in cache on read/write
Times RPN0 not in cache on read/write
Reserved
Table 93 contains the GFUMPCTL structure DisplayFSStats command:
Table 93. Structure for the DisplayFSStats Command (GFUMPCTL)
Offsets Type
0 (0)
0 (0)
STRUCTURE
CHARACTER
44 (2C) BITSTRING
Length
228
44
4
Name
PCTL_FSSTATS_TYPE
PCTL_FS_NAME
PCTL_FS_FLAGS
Description
44 (2C) BITSTRING
45 (2D) BITSTRING
46 (2E) BITSTRING
47 (2F) BITSTRING
48 (30) CHARACTER
56 (38) CHARACTER
64 (40) UNSIGNED
66 (42) CHARACTER
68 (44) SIGNED
72 (48) SIGNED
76 (4C) SIGNED
80 (50) UNSIGNED
88 (58) UNSIGNED
96 (60) UNSIGNED
104 (68) UNSIGNED
112 (70) UNSIGNED
120 (78) UNSIGNED
128 (80) UNSIGNED
136 (88) UNSIGNED
144 (90) UNSIGNED
152 (98) UNSIGNED
160 (A0) UNSIGNED
168 (A8) UNSIGNED
176 (B0) UNSIGNED
184 (B8) UNSIGNED
188 (BC) CHARACTER
2
2
8
8
1
1
1
1
4
4
4
8
8
8
4
8
8
8
8
8
8
8
8
8
8
4
PCTL_FS_RFS_MTAB_FLAGS
PCTL_FS_RFS_FLAGS
PCTL_FS_RFS_SYNC_ERR
*
PCTL_FS_CURR_TIME
PCTL_FS_MOUNT_TIME
PCTL_FS_SYNC
*
PCTL_FS_SIZE
PCTL_FS_USED
PCTL_FS_AD_ALLOC
PCTL_FS_SEQ_IO
PCTL_FS_RANDOM_IO
PCTL_FS_META_Y
PCTL_FS_META_N
PCTL_FS_RPN0_Y
PCTL_FS_RPN0_N
PCTL_FS_IX_TOPS
PCTL_FS_IX_SPLITS
PCTL_FS_IX_JOINS
PCTL_FS_IX_RDHIT
PCTL_FS_IX_RDMISS
PCTL_FS_IX_WRHIT
PCTL_FS_IX_WRMISS
PCTL_FS_PGS_CACHED
PCTL_FS_HFRFN
File system name
Flags from RFS (an internal HFS control block)
MTAB flags
RFS flags
RFS error flags
Reserved
Current timestamp
Mount timestamp
SYNC interval (in seconds)
Reserved
File system size (in pages)
Number of pages used in FS
Number of pages allocated to AD in
FS
Number of sequential I/O requests for data
Number of random I/O requests for data
Times metadata in cache on a lookup
Times metadata not in cache on a lookup
Times RPN0 in cache on read/write
Times RPN0 NOT in cache on read/write
Number of index new tops
Number of index splits
Number of index joins
Number of index page read hits
Number of index page read misses
Number of index page write hits
Number of index page write misses
Number of data buffer pages cached by this file system
HFRFN from DMIB
418
z/OS DFSMSdfp Advanced Services
Planning for HFS
Table 93. Structure for the DisplayFSStats Command (GFUMPCTL) (continued)
Offsets Type
192 (C0) UNSIGNED
196 (C4) UNSIGNED
200 (C8) CHARACTER
228 (E4) CHARACTER
Length
4
4
28
Name
PCTL_FS_MEM_CNT
PCTL_FS_APM_CNT
*
PCTL_FS_END
Description
Member count from RFS
Number of available page maps
Reserved
Table 94. Structure for the ExtendFS Command (GFUMPCTL)
Offsets
0 (0)
0 (0)
Type
STRUCTURE
CHARACTER
44 (2C) CHARACTER
1... ....
45 (2D) CHARACTER
Length
68
44
1
1
Name
PCTL_EXTENDFS_TYPE
PCTL_EXT_FSNAME
PCTL_EXT_FLGS
PCTL_EXT_NEW_VOL
PCTL_EXT_UNIT
46 (2E) CHARACTER
48 (30) SIGNED
52 (34) CHARACTER
68 (44) CHARACTER
Table 94 contains the GFUMPCTL structure ExtendFS command:
2
4
16
*
PCTL_EXT_AMT
*
PCTL_EXT_END
Description
File system name
Flags
Extend to new volume
Unit of amount to extend (‘M’, ‘T’ or
‘C’)
Reserved
Amount to be extended
Reserved
Table 95. Constants for Extend Units Supported
Type Value Name
CHARACTER
CHARACTER
CHARACTER
1
1
1
EXTENDFS_UNIT_MB
EXTENDFS_UNIT_TRK
EXTENDFS_UNIT_CYL
Description
Constant (‘M’, Megabytes (MB) for pctl_ext_unit
Constant (‘T’, Tracks) for pctl_ext_unit
Constant (‘C’, Cylinders) for pctl_ext_unit
Chapter 11. Managing Hierarchical File System Data Sets
419
Planning for HFS
420
z/OS DFSMSdfp Advanced Services
Chapter 12. User Access to Subsystem Statistics, Status, and
Counts Information
This information documents programming interfaces provided by IDCAMS.
Your program can call a system service that returns the information that the access method services LISTDATA command returns. This information is subsystem statistics, status and count information. To obtain this information, your program must be APF-authorized. Your program will call IDCSS01 with the LINK macro.
You pass to IDCSS01 a three-word parameter list pointed to by register 1. If your program is not authorized and attempts to link to IDCSS01, the system issues
ABEND with system code 047. The following shows an example of the IDCSS01 call:
ST R5,AddrSGARGL Set address of SSGARGL
LINK EP=IDCSS01,PARAM=(,MyArgL,MyRetCode) Call LISTDATA
SR R15,R15 Prepare for ICM
ICM R15,B’0011’,MyRetCode Obtain and test return code
BNZ
. . .
ListDataFail Branch if call failed
MyArgL DC A(AddrSSGARGL)
AddrSGARGL DC A(0)
MyRetcode DC H’0’
IDCDF70 ,
Address of SSGARGL address
Address of SSGARGL
Return code from service
Map the parameter list
Your program must point register 13 to a standard 18-word save area when calling
IDCSS01.
Register 1 Parameter List
Word 1
must be zero.
Word 2
contains an address of a pointer to the argument list SSGARGL (detailed below), which IDCSS01 requires. Within this argument list is a field named
SSGOADR, which points to the buffer area in which IDCSS01 returns subsystem statistics, status, or counts information. The buffer area may be obtained by the caller or may be left for IDCSS01 to obtain.
Word 3
points to an area to receive a 2-byte binary return code. Possible return codes are listed at the end of SSGARGL. IDCSS01 also returns this return code in the low order bytes of register 15.
Passed Argument List -- SSGARGL
The following describes SSGARGL. SSGARGL is the area pointed to by the word that Word 2 points to. Word 2 is part of the parameter list passed to IDCSS01. The caller must establish some fields; IDCSS01 establishes other fields. The caller must set an option flag to indicate whether information requested is status information
(SSGRSS), counts information (SSGRPD), Space Efficient Volume status (SSGSEV), or Extent Pool Configuration status (SSGEPC). If the caller passes SSGADDN,
IDCSS01 establishes SSGAVOL and SSGUNIT. .
© Copyright IBM Corp. 1979, 2017
421
If counts information is requested, the caller must indicate whether it applies to all subsystems (SSGALL), a specific subsystem (SSG1SS), or a specific device
(SSGDEV). In addition, the caller must either pass the ddname (through
SSGADDN) of a DD statement that allocates a caching subsystem volume, or the caller must identify the volume and unit (through SSGAVOL and SSGUNIT) of a caching subsystem volume for which information is being requested.
If Space Efficient Volume status, or Extent Pool Configuration status is requested, the caller must follow the instruction described in the mapping for the space efficient volume status output buffer, or mapping for the extent pool configuration status output buffer described in later of this section.
Note:
The SSGOLN may be larger than the data returned in the SSGBUFR buffer.
To detect end of data, the following should be considered: v If “current index into the SSGBUFR buffer” is within SSGOLN-4 bytes, then the full six bytes of SSGDAVOL being zero is the way to determine the premature
“end of data”.
v If “current index into the SSGBUFR buffer” is beyond SSGOLN-4 bytes of the data, then they are at “end of data”.
The following list contains other fields that IDCSS01 establishes:
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 96 SSGARGL
16
17
18
19
12
16
0
8
20
24
28
(0) CHARACTER
(8) ADDRESS
(C) ADDRESS
(10) BITSTRING
(10) BITSTRING
(11) BITSTRING
(12) BITSTRING
(13) BITSTRING
(14) SIGNED
(18) ADDRESS
(1C) BITSTRING
1... ....
.1.. ....
1
1
1
1
8 SSGHEAD
4 SSGADDN
4 SSGAVOL
4 SSGUNIT
4
4
2
SSGUNIT1
SSGUNIT2
SSGUNIT3
SSGUNIT4
SSGOLN
SSGOADR
SSGOPT
SSGRPD
SSGRSS
SSGARGL IDENTIFIER
DDNAME ADDRESS
VOLUME ADDRESS
DEVICE TYPE
GENERAL FLAGS
GENERAL FLAGS
DEVICE CLASS
DEVICE TYPE WITHIN THE CLASS
LENGTH OF OUTPUT BUFFER
ADDRESS OF OUTPUT BUFFER
OPTIONS BYTE
SENSE SUBSYSTEM COUNTS
SENSE SUBSYSTEM STATUS
29
..1. ....
...1 ....
.... 1...
.... .1..
.... ..1.
.... ...1
(1D) 1... ....
.1.. ....
..1. ....
...1 ....
SSGCACHE
SSGSDS
SSGALL
SSG1SS
SSGDEV
SSGAMD
SSG2SD
SSGACD
SSGOFFL
SSGARGL2
ON=CACHING,OFF=PAGING
ON=1 SD, OFF= 2 SD’S
SENSE FOR ALL SUBSYSTEMS
SENSE FOR SPECIFIED SUBSYSTEM
SENSE FOR SPECIFIED DEVICE
PTR TO 3880 MODEL PASSED
INSTEAD OF PTR TO VOLUME
PRINT 2 SD
ACCESSCODE
SSGAVOL POINTS TO DEVICE ID OF
AN OFFLINE DEVICE this flag indicates that the parameter list is extended by
.... 1...
SSGLINKP the 16 bytes defined as
SSGARGLX
Link performance statistics supported by caller and request return of statistics when request for Subsystem counts are made (SSGRPD = ON) for one or more Subsystems
(SSG1SS=ON or SSGALL = ON).
Results passed back in area pointed to by SSGLPOAR
Extended size statistics are provided if SSGEXRQ is specified.
The returned field,
SSGLLSET, will be set to the size for each set of link statistics.
422
z/OS DFSMSdfp Advanced Services
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
30
31
.... .1..
(1E) BITSTRING
(1F) CHARACTER
SSGARGL3
1 SSGMDLID
1 SSGRCIOS this flag indicates that the paramter list is extended with area defined as SSGARLGY
CU MODEL IDENTIFIER
’old’ parameter list end
Parameter List Extension.
Note: IDCSS01 will not reference fields contained in SSGARGLX
32 unless the bit defined as SSGARGL2 is set to ’1’.
====================================================================================
32 (20) CHARACTER 16 SSGARGLX parm list extension
(20) UNSIGNED 1 SSGATIME I/O timeout value in seconds.When SSGATIME is not zero, it will be stored into IOSXTIME in the IOSB. If the I/O is active or queued longer that SSGATIME, the I/O will be terminated and IDCSS01 will return a return code of
33
35
36
40
41
(21) CHARACTER
(23) UNSIGNED
(24) ADDRESS
(28) CHARACTER
(29) CHARACTER
2
1
4
1
7
SSGADEVN
SSGLPRET
SSGLPOAR
SSGSCHST
*
60. Hex values for SSGATIME support seconds from 1 to 255.
Binary device number that received an IO (RC8) or timeout (RC60) from IDCSS01
Reason code from link performance statistics processing
Address of link performance
Statistics output buffer queue. When zero on return statistics not available for devices found on counts request or statistics not not requested by the caller
SUBCHANNEL SET ID
RESERVED
Parameter List Extension number 3
Note: IDCSS01 will not reference fields contained in SSGARGLY unless the bit defined as SSGARGL3 is set to ’1’.
Entire section added
====================================================================================
48 (30) CHARACTER 48 SSGARGLY Parm list extension 3
48 (30) BITSTRING
1... ....
4 SSGOPTY
SSGRANKP
Extended options
RANK performance statistics are supported by caller and request return of statistics when request for Subsystem counts are made (SSGRPD = ON) for one or more Subsystems
.... ...1
SSGVOL
(SSG1SS=ON or SSGALL = ON).
Results passed back in area pointed to by SSGRSOAR.
Volume status is supported by caller and request return of status in
SSGSEBUF pointed by
SSGSEOAR when request for volume status are made
(SSGVOL=ON) for the scope of single device (SSGDEV=ON), online devices in the subsystem
(SSG1SS=ON), or all online devices
(SSGALL=ON). For single offline volume status, caller sets address of the MVS addr character in
SSGAVOL and set offline
(SSGOFFL=ON).
Volume status is not supported when
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
423
|
|
|
.1.. ....
..1. ....
...1 ....
SSGSEGMP
SSGSEV
SSGEPC other statistics or status is requested by caller.
Segment pool statistics are supported by caller and request return of statistics when request for Subsystem counts are made (SSGRPD = ON) for one or more Subsystems
(SSG1SS=ON or SSGALL = ON).
Results passed back in area pointed to by SSGSPOAR
Space Efficient Volume
(SEVOL) status is supported by caller and request return of status in SSGSEBUF pointed by
SSGSEOAR when request for
SEVOL are made (SSGSEV
=ON) for the scope of single device
(SSGDEV=ON), online SEVOL devices in the subsystem
(SSG1SS=ON), or all online SEVOL devices
(SSGALL=ON). For single offline SEVOL status, caller set address of the MVS addr character in SSGAVOL and set offline (SSGOFFL=ON).
The Fixed Block (FB)
SEVOL device status is returned when the reporting scope is single
(SSGDEV=ON), the FB user request is active
(SSGURFBD=ON), FB LSS number is in SSGFBLSS, and FB device number is in SSGFBDEV. FB SEVOL status is available through CKD I/O device that resides in the same
Storage Facility Image as
FB SEVOL and resides in the same Even or Odd number LSS as even or odd
FB LSS.
SEVOL status is not supported when other statistics or status is requested by caller.
Extent Pool Config (EPC) status is supported by caller and request return of status in SSGEPBUF pointed by SSGEPOAR when request for EPC of
Storage Facility Image oriented by I/O device in
SSGADDN or SSGAVOL are made (SSGEPC=ON).
When
Extent Pool ID (SSGEPID) is set as ’FFFF’X by caller, EPC summary status is returned.
When even numbered Extent Pool
ID is specified in
SSGEPID with the I/O device in the even LSS, detail status of EPC for the specified Extent Pool is returned.
When odd numbered Extent Pool ID is specified with the I/O device in the odd LSS, detail status of EPC for the specified Extent Pool is returned. SSGURBMP is
424
z/OS DFSMSdfp Advanced Services
.... 1...
.... .1..
.... ..1.
52
52
53
(34) CHARACTER
(34) UNSIGNED
(35) UNSIGNED
60 (3C) ADDRESS
64 (40) ADDRESS
68 (44) ADDRESS
72 (48) ADDRESS
8
1
1
4
4
4
4
SSGURFBD
SSGURBMP
SSGEXRQ
SSGRETY
SSGRSRET
SSGSGRET
SSGRSOAR
SSGSPOAR
SSGSEOAR
SSGEPOAR internal use only. When
Extent Pool ID (SSGEPID) is set as ’FFFF’X with
SSGURBMP is ON, branch entry caller receives error. Whether ON or OFF of SSGURBMP does not make difference in EPC detail status for branch entry caller. EPC status report is not supported when other statistics or status is requested by caller.
Request Fixed Block SEVOL status by turning
SSGURFBD flag ON.
IDCAMS internal use.
Refer SSGEPC bit description.
By setting this attribute bit along with other request(s), caller supports and requests the return of extended length statistics.
The extended length is any set of statistics that is larger than the standard length of statistics. The extended length statistics will be returned if target storage facility supports it, otherwise the standard size statistics will be returned. Ignored this attribute bit for requests where the statistics do not support the extended length and where caller does not make any request.
Current request that supports the extended length is:
- Link performance statistics
Extended return codes
Reason code from Rank
Performance Statistics processing
Reason code from Segm
Performance Statistics processing
Address of Rank performance
Statistics output buffer queue. When zero on return statistics not available for devices found on counts request or statistics not not requested by the caller
Address of segment pool performance Statistics output buffer queue. When zero on return statistics not available for devices found on counts request or statistics not not requested by the caller
Address of SE Volume status output buffer queue.
When zero on return status not available for devices found on SEVOL status request or status not requested.
Address of Extent Pool
Config (EPC) status output buffer. When zero on return status not available for Storage
Facility Image found on
EPC status request or status not requested
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
425
76 (4C) UNSIGNED 2 SSGEPID by the caller.
Extent Pool ID.
’FFFF’X indicates no
Ext Pool ID is
78
80
82
(4E) UNSIGNED
(50) UNSIGNED
2
2
SSGFBLSS
SSGFBDEV
(52) CHARACTER 14 *
MAPPING FOR THE SUBSYSTEM GET OUTPUT BUFFER provided by caller.
Fix Block device number
Fix Block LSS number reserved for future use
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0
0
6
(0) STRUCTURE
(0) CHARACTER
(6) BITSTRING
1... ....
* SSGBUFR
6 SSGDAVOL
1 SSGDAFLG
SSG_UA_FLAG
VOLUME SERIAL
"ONE" UNIT ADDR FORMAT
.1.. ....
7
..11 1111
(7) CHARACTER
SSG_FND_STG2 2ND STG DIR PATH FND SS01 TO
LA01 IDCSS01 PASSED TO IDCLA01
* RESERVED
1 SSGDCUID Real CUID for data in
SSGDADA
8
12
14
16
16
16
16
16
16
16
16
16
(8) CHARACTER
(C) CHARACTER
(E) SIGNED
(10) CHARACTER
(10) CHARACTER
(10) CHARACTER
(10) CHARACTER
(10) CHARACTER
(10) CHARACTER
(10) CHARACTER
(10) CHARACTER
(10) CHARACTER
4
2
2
192
192
160
80
80
44
40
24
12
SSGDAUA1
SSGDAUB1
SSGDALN
SSGDADA
SSGDAXPF
FIRST UNIT ADDRESS
FIRST UNIT ADDRESS (BINARY)
DATA LENGTH
DATA AREA
CACHING SUBSYSTEM PERFORMANCE
STATISTICS
SSGDASPF CACHING SUBSYSTEM COUNTS
SSGDA2SD STATUS FOR 2 SD
SSGDAIPF PAGING SUBSYSTEM COUNTS
SSGDASS SUBSYSTEM STATUS (LNGTHND)
SSGDASS_40
STATUS FOR 3380
SSGDAACD
ACCESSCODES
SSGDAAC0
28 (1C) CHARACTER 12
STORAGE CLUSTER 0 WORD
SSGDAAC1
STORAGE CLUSTER 1 WORD
MAPPING FOR THE SUBSYSTEM GET OUTPUT BUFFER
FOR LINK PERFORMANCE STATISTICS
Output buffer is a chain, anchored by SSGLPOAR, of link performance statistics tables. Each table entry represents data read from a single storage subsystem box. The statistics from a single box may be described with more than table entry. The chain is a single threaded queue. Each chain element needs to be freed by the caller of this interface. Output buffer is built for storage boxes that support link performance statistics and are returned only if requested by caller (SSGLINKP) on a request for performance data (SSGRPD) for requests with scope of of subsystem (SSG1SS) or all subsystems (SSGALL).
The parameter list extension must also be passed as indicated with SSGARLG2.
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0
0
0
4
(0) STRUCTURE
(0) CHARACTER
(0) UNSIGNED
(4) UNSIGNED
*
56
4
4
SSGLBUFR
SSGLHDR
SSGLQDAL
SSGLQDAO
Queue element header
Length of this queue element, header plus data
Offset to the start of the
8 (8) ADDRESS 4 SSGLFWDP statistics sets
Pointer to next queue element, when zero end of queue
Orientation to subsystem that stats pertain
====================================================================================
12 (C) CHARACTER 6 SSGLVOL Volume serial of device that stats where read from
18 (12) CHARACTER 2 SSGLDEVN
20
28
28
30
(14) CHARACTER
(1C) CHARACTER
(1C) UNSIGNED
(1E) UNSIGNED
8
28
2
2
*
SSGLLHDR
SSGLNSET
SSGLLSET
Device number of device that
Stats where read from
Reserved
Link stats info
Num of link stats sets read
Size of each set
426
z/OS DFSMSdfp Advanced Services
32
38
41
51
52
56
(20) CHARACTER
(26) CHARACTER
(29) CHARACTER
(33) CHARACTER
(34) CHARACTER
(38) CHARACTER
6
3
10
1
4
*
SSGLCUT
SSGLCUM
SSGLSEQ
SSGLVER
*
SSGLDADA
The extended size would be set if the target storage facility supports it and SSGEXRQ is set, otherwise the standard 96-bytes entry size for each interface
ID will be set.
Control unit type
Control unit model
Control unit sequence number
Version of link statistics.
When value of version is X’00’, it indicates that the link statistics are defined in the
96 byte format. When value of version is X’01’, it indicates that the link statistics are defined in the 156 byte format.
Not used
Link performance stats read
56
56
SSGLDADA consists of link statistics sets with Interface ID containing one or more table information entries.
Each entry can be 96 bytes defined in SSGLLSTA or 156 bytes defined in SSGLXSTA depending on version number in SSGLVER.
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
(38) CHARACTER
(38) UNSIGNED
96
1
SSGLLSTA(*)
SSGLLTYP
Stats entry
Link type
01 - ESCON
02 - Fibre Channel 1 Gb/s
03 - Fibre Channel 2 Gb/s
57
58
59
60
62
64
64
68
72
(39) UNSIGNED
(3A) UNSIGNED
(3B) UNSIGNED
(3C) CHARACTER
(3E) CHARACTER
(40) CHARACTER
(40) UNSIGNED
(44) UNSIGNED
(48) UNSIGNED
1
1
1
2
2
88
4
4
4
*
SSGLLBYI
SSGLLTMI
*
04 - Fibre Channel 4 Gb/s
05 - Fibre Channel 8 Gb/s
06 - Fibre Channel 16 Gb/s
Unused
Byte increment 01 - 128K bytes
Time increment 01 - 16 MS
Unused
SSGLLIID
SSGLLSAT
Interface id
Link statistics
SSGLERDB Eckd read bytes in byte increment
SSGLEWRB Eckd write bytes in byte increment
SSGLERDO Eckd read operations. for escon ports, one count per chain which transfers data to
76
80
84
88
92
96
100
(4C) UNSIGNED
(50) UNSIGNED
(54) UNSIGNED
(58) UNSIGNED
(5C) UNSIGNED
(60) UNSIGNED
(64) UNSIGNED
4
4
4
4
4
4
4 the host. for ficon ports, one count per command which transfer data to the host
SSGLEWRO Eckd write operations. for escon ports, one count per chain which transfers data to the host. for ficon ports, one count per command which transfer data to the host
SSGLERDT Eckd read accumulated time on channel. the active processing time for each command is accumulated based on increment value.
SSGLEWRT Eckd write accumulated time on channel. the active processing time for each command is accumulated based on increment value.
SSGLPRDB Pprc send bytes in byte increment
SSGLPWRB Pprc received bytes in byte increment
SSGLPRDO Pprc send operations. each pprc write command sent by the pprc primary
SSGLPWRO Pprc received operations. each pprc write command received by the pprc secondary.
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
427
104
108
112
116
120
124
128
132
136
(68) UNSIGNED
(6C) UNSIGNED
(70) UNSIGNED
(74) UNSIGNED
(78) UNSIGNED
(7C) UNSIGNED
(80) UNSIGNED
(84) UNSIGNED
(88) CHARACTER
4
4
4
4
4
4
4
4
16
SSGLPRDT Pprc send accumulated time based on incremant value
SSGLPWRT Pprc received accumulated time based on increment value
SSGLSRDB Scsi read bytes in byte increment
SSGLSWRB Scsi write bytes in byte increment
SSGLSRDO Scsi read operations. each scsi read is counted
SSGLSWRO Scsi write operations. each scsi write is counted
SSGLSRDT Scsi read accumulated time based on increment value
SSGLSWRT Scsi write accumulated time
* based on increment value
Reserved
SSGLDADA consists of table entris defined by SSGLXSTA shown below when SSGLVER is decimal value of 1.
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ================================
56
56
152
(38) CHARACTER
(38) UNSIGNED
(98) UNSIGNED
156
96
4
SSGLXSTA(*)
*
SSGLFLKF
Stats entry
Mapped in SSGLLSTA
Fibre Channel Link Failure
Error Count.
156 (9C) UNSIGNED 4 SSGLFLSY
This count is the number of miscellaneous fibre channel link errors, such as unexpected NOS received or a link state machine failure detected.
Fibre Channel Loss of
Synchronization Error Count.
This count is the number of loss of synchronization errors where
160
164
(A0) UNSIGNED
(A4) UNSIGNED
4
4
SSGLFLSG
SSGLFPSQ it is a confirmed and a persistent synchronization loss on the fibre channel link.
Fibre Channel Loss of Signal
Error Count.
This count is the number of times that a loss of signal was detected on the fibre channel link when a signal was previously detected.
Fibre Channel Primitive Sequence
Error Count.
This count is the number of
168
172
176
180
184
(A8) UNSIGNED
(AC) UNSIGNED
(B0) UNSIGNED
(B4) UNSIGNED
(B8) UNSIGNED
4
4
4
4
4
SSGLFITW
SSGLFCRC
SSGLFLR1
SSGLFLR2
SSGLFILF primitive sequence protocol error counts where an unexpected primitive sequence was received.
Fibre Channel Invalid
Transmission Word Error Count.
This count is the number of times a "bit" error was detected.
Examples of a "bit" errors are a code violation, invalid special code alignment, or disparity errors.
Fibre Channel CRC Error Count.
This count is the number of times a received frame’s CRC is in error.
Fibre Channel Link Recovery
(LR) Sent Count Count.
This count is the number of times the port has transitioned from an active (AC) state to a Link
Recovery (LR1) state.
Fibre Channel Link Recovery
(LR) Received Count Recovery
Count.
This count is the number of times the port has transitioned from an active (AC) state to a Link
Recovery (LR2) state.
Fibre Channel Illegal Frame
428
z/OS DFSMSdfp Advanced Services
188
192
196
200
204
208
(BC) UNSIGNED
(C0) UNSIGNED
(C4) UNSIGNED
(C8) UNSIGNED
(CC) UNSIGNED
(D0) UNSIGNED
4
4
4
4
4
4
SSGLFOOD
SSGLFOOA
SSGLFDPF
SSGLFIRO
SSGLFSQT
SSGLFBER
Count. This count is the number of frames that violated Fibre
Channel protocol. One example is an invalid frame header. One common reason is when the first frame of data sequence is missing and a subsequent data frame is detected as illegal.
Fibre Channel Out of Order
Data Count.
This count is the number of times that a out of order frame is detected. The frame is either missing from a data sequence or it is received beyond the port’s sequence reassembly threshold.
Fibre Channel Out of Order
ACK Count.
This count is the number of times that a out of order ACK frame is detected. The frame is either missing from a data sequence or it is received beyond the port’s sequence reassembly threshold.
Fibre Channel Duplicate
Frame Count.
This count is the number of times a frame was received that has been detected as previously processed.
Fibre Channel Invalid
Relative Offset Count.
This count is the number of times that a frame was received with bad relative offset in the frame header.
Fibre Channel Sequence
Timeout Count.
This count is the number of times the port has detected a timeout condition on receiving sequence initiative for a fibre channel exchange.
Fibre Channel Bit Error
Rate Count.
This count is the number of the bit error (invalid transmission word) bursts for the previous 5 minute counting window.
MAPPING FOR THE SUBSYSTEM GET OUTPUT BUFFER
FOR RANK PERFORMANCE STATISTICS
Output buffer is a queue, anchored by SSGRSOAR, of rank performance statistics. Each queue element represents data read from a single storage subsystem box that describes sets of statistics. The queue is a single threaded queue. Each queue element needs to be freed by the caller of this interface. Output buffer built for storage subsystem boxes that support rank performance statistics and are returned only if requested by caller (SSGRANKP) on a request for performance data (SSGRPD) for requests with scope of of subsystem (SSG1SS) or all subsystems (SSGALL).
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0
0
0
4
8
(0) STRUCTURE
(0) CHARACTER
(0) UNSIGNED
(4) UNSIGNED
(8) ADDRESS
*
56 SSGRHDR
4
4
4
SSGRBUFR
SSGRQDAL
SSGRQDAO
SSGRFWDP
Queue element header
Length of this queue element, header plus data
Offset to the start of the statistics sets
Pointer to next queue element, when zero end of queue
Orientation to subsystem that stats pertain
====================================================================================
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
429
12
18
20
28
28
30
54
56
56
56
32
38
41
51
52
(C) CHARACTER
(12) CHARACTER
(14) CHARACTER
(1C) CHARACTER
(1C) UNSIGNED
(1E) UNSIGNED
(20) CHARACTER
(26) CHARACTER
(29) CHARACTER
(33) CHARACTER
(34) UNSIGNED
(36) UNSIGNED
(38) CHARACTER
(38) CHARACTER
(38) UNSIGNED
6
2
8
28
2
SSGRVOL
SSGRDEVN
*
SSGRRHDR
SSGRNSET
Volume serial of device that stats where read from
Device number of device that
Stats where read from
Reserved
Rank stats info
Num of rank stat sets available to be returned on the ESS starting from first rank ID SSGRRID. Can be used to determine buffer
2
10
1
2
6
3
SSGRLSET
SSGRCUT
SSGRCUM
SSGRSEQ
SSGRVER
SSGRARNM requirements
Size of each rank stats set excluding size of array info
SSGRRAR
Control unit type
Control unit model
Control unit sequence number
Version of rank statistics
2 SSGRARSZ
Num of array info sets avail to be returned on the ESS starting from first rank id
SSGRRID. Can be used to determine buffer requirements
Size of each array information set SSGRRAR
* SSGRDADA
56 SSGRRSTA(*)
Rank performance stats read
Rank statistics entry
2 SSGRRKID Rank Identifier
|
|
|
The returned data consists of rank sets with each rank set containing one or more array information entries.
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE * SSGRRSTT Rank stats entry mapping
0
2
4
5
6
(0) UNSIGNED
(2) UNSIGNED
(4) UNSIGNED
(5) BITSTRING
1... ....
2
2
1
1
SSGRRID
SSGRRPNM
SSGRRCNT
SSGRRRTQ
SSGRRDER includes one or more entries for array information
Rank identifier
Segment pool number
Count of arrays in rank
Rank Type Qualifier
Data Encrypted Rank. When ’1’, the data stored on the physical
.... ...1
SSGRRAPV media (i.e disk) is encrypted.
Adapter Pair ID Valid. When ’1’, the Adapter Pair ID in Bytes 6-7
(6) CHARACTER 2 * is valid.
Not used
In the statistics below bytes are accumulated in units of
128 KB, and time is accumulated in units of 16 milliseconds
====================================================================================
8
12
16
20
(8) UNSIGNED
(C) UNSIGNED
(10) UNSIGNED
(14) UNSIGNED
4
4
4
4
SSGRRBYR
SSGRRBYW
SSGRRROP
SSGRRWOP
Rank bytes read
Rank bytes written
Rank read operations
Rank write operations
24
28
32
32
34
50
(18) UNSIGNED
(1C) UNSIGNED
(20) CHARACTER
4
4
24
SSGRRKRT
SSGRRKWT
SSGRRAR(*)
Rank read repsonse time
Rank wrirte response time
Array information mapping
The format of the next 24 bytes is repeated the number times as indicated by SSGRRCNT.
(20) UNSIGNED
(22) CHARACTER
(32) UNSIGNED
2
16
1
SSGRRAID
SSGRREBC
SSGRRTYP
Rank array id
Array type in ebcdic
Array type
51
52
53
(33) UNSIGNED
(34) UNSIGNED
(35) BITSTRING
11.. ....
1
1
1
SSGRRAWD
SSGRRASP
SSGRRACS
SSGRRADC
01 = RAID-5
02 = RAID-10
03 = RAID-6
04-FF NOT USED
Array width
Array speed (1000 RPM)
Array Device Class and Array
Status
Mask bits for Array Device Class
Device Class
’00’b Enterprise
’01’b Near-line (An Advanced
430
z/OS DFSMSdfp Advanced Services
54
..1. ....
...1 ....
.... 1...
(36) CHARACTER
SSGRRAS1
SSGRRAS2
SSGRRAS3
2 SSGRRACP
Technology Attachment
(ATA) Drive)
’10’b SATA (Serial Advanced
Technology Attachment
(ATA) Drive)
’11’b Solid State Drive (SSD)
Raid Degraded.
One or more array members need rebuilding
DDM Throttling.
A Near-line DDM in the array is throttling performance due to temperature or workload.
RPM Exception.
A DDM with an slower RPM than the normal array DDMs is a member of the array as a result of a sparing action.
Array capacity (GB)
MAPPING FOR THE SUBSYSTEM GET OUTPUT BUFFER
FOR SEGMENT POOL PERFORMANCE STATISTICS
Output buffer is a queue, anchored by SSGSPOAR, of segment pool perf statistics. Each queue element represents data read from a single storage subsystem box that describes sets of statistics. The queue is a single threaded queue. Each queue element needs to be freed by the caller of this interface. Output buffer built for storage subsystem boxes that support rank performance statistics and are returned only if requested by caller (SSGSEGMP) on a request for performance data (SSGRPD) for requests with scope of of subsystem (SSG1SS) or all subsystems (SSGALL).
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0
0
0
(0) STRUCTURE
(0) CHARACTER
(0) UNSIGNED
*
56
4
SSGSBUFR
SSGSHDR
SSGSQDAL
Queue element header
Length of this queue element,
4
8
(4) UNSIGNED
(8) ADDRESS
4
4
SSGSQDAO
SSGSFWDP header plus data
Offset to the start of the statistics sets
Pointer to next queue element, when zero end of queue
Orientation to subsystem that stats pertain
====================================================================================
12 (C) CHARACTER 6 SSGSVOL Volume serial of device that stats where read from
18 (12) CHARACTER 2 SSGSDEVN
20
28
28
30
(14) CHARACTER
(1C) CHARACTER
(1C) UNSIGNED
(1E) UNSIGNED
8
28
2
2
*
SSGSSHDR
SSGSNSET
SSGSLSET
Device number of device that
Stats where read from
Reserved
Segment pool stats info
Num of pool stats sets read
Size of each set
32
38
41
51
52
(20) CHARACTER
(26) CHARACTER
(29) CHARACTER
(33) CHARACTER
(34) BITSTRING
1... ....
10
1
1
6
3
SSGSCUT
SSGSCUM
SSGSSEQ
SSGSVER
SSGSFLG
SSGSVLD
Control unit type
Control unit model
Control unit sequence number
Version of pool statistics
Flags
Extent pool statistics valid
Bytes 44-67 starting at
SSGSSRSC
53
56
56
56
(35) CHARACTER
(38) CHARACTER
(38) CHARACTER
(38) UNSIGNED
52
2
3 *
* SSGSDADA
SSGSSSTA(*)
SSGSSGID
Not used
Segment pool perf stats read
Segment pool stats entry
Segment pool identifier
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 52 SSGSSSTT seg pool statistics entry includes one or more entry
0
2
(0) UNSIGNED
(2) UNSIGNED
2 SSGSSPID
1 SSGSSPLT
Seg pool identifier
Segment pool type
00-03 = reserved
04 = FB 1GB
05-131 = reserved
132 = CKD 1GB
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
431
3
4
(3) BITSTRING
1... ....
(4) UNSIGNED
1
4
SSGSSPTQ
SSGSSDEP
SSGSSCAP
133-255 = reserved
Extent Pool Type Qualifier
Data Encrypted Extent Pool.
When ’1’, the data stored on the physical media (i.e disk) is encrypted.
Real seg pool capacity (GB)
00-03 = reserved
04 = FB 1GB
05-131 = reserved
132 = CKD 1GB
133-255 = reserved
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
8
12
3
4
16
20
24
28
32
36
40
(3) CHARACTER
(4) UNSIGNED
(8) UNSIGNED
(C) UNSIGNED
(10) UNSIGNED
(14) UNSIGNED
(18) UNSIGNED
(1C) UNSIGNED
(20) UNSIGNED
(24) UNSIGNED
(28) CHARACTER
1
4
4
4
4
4
4
4
4
4
12
*
SSGSSCAP
SSGSSNMS
SSGSSNMA
SSGSSRSC
SSGSSVCP
SSGSSNMV
SSGSSVSC
SSGSSSDY
SSGSSTDY
*
Not used
Real seg pool capacity (GB)
Num real segments in seg pool
Num real allocated segments in in segment pool
Real segment conversions
Virtual seg pool capacity(GB)
Number of virtual segments in segment pool
Virtual segment conversions
Number of segments that were sources of dynamic segment relocations
Number of segments that were targets of cynamic segment relocations
Not used
MAPPING FOR THE SPACE EFFICIENT VOLUME STATUS
OUTPUT BUFFER
Output buffer is a queue, anchored by SSGSEOAR, of Space
Efficient Volume (SEVOL) status. Each queue element represents status of the space efficient volume specified in the header.
The queue is a single threaded queue.
Each queue element needs to be freed by the caller of this interface.
Output buffer is built for SEVOL(s) when SEVOL status is requested (SSGSEV=ON).
Caller sets the scope of SEVOL(s) by turning one of flag bit that is the single device (SSGDEV), subsystem (SSG1SS), or all subsystems (SSGALL).
For a single SEVOL status request, the SEVOL status can be obtain when the path of SEVOL is available.
For a subsystem (SSG1SS) and all systems (SSGALL) scope, the SEVOL status is available when SEVOL is ONLINE.
When the scope is the single device (SSGDEV=ON) and the Fix Block SEVOL is requested (SSGURFBD=ON), the status of FB SEVOL oriented by LSS (SSGFBLSS) and Device
(SSGFBDEV) is reported.
FB SEVOL status is not available with the scope of the subsystem (SSG1SS=ON) or the all subsystems (SSGALL=ON).
FB SEVOL status is available when LSS number of both the I/O device (SSGAVOL or SSGDDN) and
FB SEVOL are numbered in the same even or odd number.
Flag and variable combinations of SEVOL status request are shown as below in the railroad chart format.
>>_SSGSEV_ _SSGALL________ ________________> (A)
|_SSG1SS________|
|
|_SSGDEV_ ____________________ __> (B)
|_SSGFBLSS__SSGFBDEV_|
(A)>__ _SSGAVOL__SSGUNIT__ __ __________________><
|_SSGADDN___________| |
|
|
(B)> __ _SSGAVOL__SSGUNIT__ _|
|_SSGADDN___________|
|_SSGAVOL__SSGOFFL__|
432
z/OS DFSMSdfp Advanced Services
|
|
|
|
|
|
|
|
MAPPING FOR THE SPACE EFFICIENT VOLUME STATUS OUTPUT
BUFFER
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0
0
0
(0) STRUCTURE
(0) CHARACTER
(0) UNSIGNED
84
56
4
SSGSEBUF
SSGSEHDR
SSGSEQAL
Queue element header
Length of this queue element, header plus data
4
8
(4) UNSIGNED
(4) ADDRESS
4
4
SSGSEQAO
SSGSEFWP
Offset to the start of the statistics sets
Pointer to next queue element, when zero end of queue
Orientation to device that status pertain
==============================================================
0 (0) STRUCTURE 96 SSGSEBUF
0 (0) CHARACTER 68 SSGSEHDR Queue element header
12 (C) CHARACTER
18 (12) CHARACTER
20 (14) CHARACTER
22 (16) CHARACTER
24 (18) UNSIGNED
28 (1C) CHARACTER
28 (1C) UNSIGNED
6 SSGSEVOL
2 SSGSEDEV
2 SSGSESCX
2 *
4 SSGSETTL
28 SSGSVHDR
2 SSGSESZ
Volume serial of device that stat where read from
Device number of device that Status where read from
Subsystem ID not used
Total SE VOL Count, only valid for head of bufferchain
SE VOL header
Size of data
30
36
39
42
44
56
(1E) CHARACTER
(24) CHARACTER
(27) CHARACTER
(2A) CHARACTER
(2C) CHARACTER
(38) CHARACTER
56 (38) BITSTRING
1... ....
.1.. ....
6
3
3
2
12
28
SSGSECUT
SSGSECUM
SSGSECUC
SSGSECUP
SSGSESEQ
SSGSEDAD
1 SSGSEFLG
SSGSEVF
SSGSEAN
Control unit type
Control unit model
Control unit maker / company
Control unit plant
Control unit sequence number
SE Vol statistics
Flag byte 1
ON=SE Vol
Space currently allocated is not available not used
Extent Pool ID
57 (39) CHARACTER
58 (3A) UNSIGNED
1 *
2 SSGSEEP
The following two fields are a remaining percentage of usable space that will initiate a notification to the host
==============================================================
60 (3C) UNSIGNED 1 SSGSECWW Capacity warning watermark
61 (3D) UNSIGNED 1 SSGSEGWW
62 (3E) CHARACTER 2 *
Guarantee warning watermark not used
The following fields are expressed in number of cylinders for CKD device.
The following fields are expressed in TENTH of binary Gigabytes for Fix Block device.
==============================================================
64 (40) UNSIGNED 4 SSGSEC SE Volume capacity limit. This field is
68 (44) UNSIGNED 4 SSGSEG always zero.
SE Volume guarantee capacity. This field is always zero.
72 (48) UNSIGNED
73 (49) UNSIGNED
74 (4A) CHARACTER
76 (4C) UNSIGNED
4
2*
4 SSGSEC
SSGSESCA not used
Space currently consumed
1 SSGSECWW Guarantee warning watermark
SE Volume capacity limit. This field is
72 (48) UNSIGNED 1 SSGSECWW Capacity warning watermark
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
433
|
|
|
|
|
|
|
|
|
|
|
|
|
|
76 (4C) UNSIGNED
80 (50) UNSIGNED
80 (50) UNSIGNED
84 (54) UNSIGNED
88 (58) UNSIGNED
92 (5C) UNSIGNED always zero.
4 SSGSEEPR Size of Repository volume in Extent Pool
4 SSGSECAP
4 SSGSEG
SE Volume capacity
SE Volume guarantee capacity. This field is always zero.
4 SSGSESCA Space currently consumed
4 SSGSEEPR Size of Repository volume in Extent
Pool
4 SSGSECAP SE Volume capacity
MAPPING FOR THE EXTENT POOL CONFIGURATION STATUS
OUTPUT BUFFER
Output buffer is a queue, anchored by SSGEPOAR, of Extent
Pool Configuration status.
Each queue element represents the status of the Extent Pools defined in Storage Facility image. If the caller provide a Extent Pool ID ( SSGEPID has value between ’0’X and ’FFFE’X ), then in addition to the summary status of Extent Pool, the detail status of that Extent Pool identified by Extent Pool ID is reported.
Caller is responsible for freeing the output buffer.
The flag and variable combinations for EPC status is shown as below railroad chart.
Below variable defines scope
>>__SSGEPC__ _SSGEPID=(’FFFF’X)________________________>(A)
|_SSGEPID=(’0’X to ’FFFE’X of even number)_>(B)
|_SSGEPID=(’1’X to ’FFFD’X of odd number)__>(C)
(A)>______________________________ ______________________>
(B)>_(Even LSS I/O dev follows)_ _|
(C)>_(Odd LSS I/O dev follows)__|
Following variable and flag represent I/O device
>______ _SSGAVOL__SSGUNIT__ ______________________________><
|_SSGADDN___________|
|_SSGAVOL__SSGOFFL__|
MAPPING FOR THE EXTENT POOL CONFIGURATION STATUS OUTPUT BUFFER
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0
0
0
4
(0) STRUCTURE
(0) CHARACTER
(0) UNSIGNED
(4) UNSIGNED
* SSGEPBUF
36 SSGEHDR
4 SSGEPQAL
4 SSGEPQAO
Queue element header
Length of this queue element, header plus data
Offset to the start of the statistics sets
8 (8) UNSIGNED 4 SSGEPFWD Pointer to next queue element, when zero end of queue
Orientation to device that stats pertain
==============================================================
12 (C) CHARACTER 6 SSGEPVOL Volume serial of device that status where read from
18 (12) CHARACTER 2 SSGEPDEV
20 (14) UNSIGNED 2 SSGEPIDC
Device number of device that tats where read from
Ext Pool ID provided by caller
22
28
(16) CHARACTER
(1C) ADDRESS
6
4
*
SSGEPSIP
Reserved
Internal code use only.
Branch Entry caller shall set zero.
434
z/OS DFSMSdfp Advanced Services
32
34
36
36
36
38
40
42
48
51
54
56
(20) UNSIGNED
(22) UNSIGNED
(24) CHARACTER
(24) CHARACTER
(24) UNSIGNED
(26) UNSIGNED
(28) BITSTRING
1... ....
.1.. ....
..1. ....
(2A) CHARACTER
(30) CHARACTER
(33) CHARACTER
(36) CHARACTER
(38) CHARACTER
2
2
*
32
6
3
3
SSGEPSDO
SSGEPDDO
SSGEPDAD
SSGEPDHL
2 SSGEPLEN
2 SSGEPCNT
2 SSGEPFL1
SSGEPIDV
SSGEPLSS
SSGEPCC
SSGEPCUT
SSGEPCUM
SSGEPCUC
2 SSGEPCUP
12 SSGEPSEQ
Offset to 1st Summary data
(SSGEPSUM) array
Offset to Detail data
(SSGEPDAT)
Ext Pool Config status
Fixed length of epc data header
Length of data returned
Count of Extent Pools
Extent Pool Flags
Ext Pool detailed data valid
0 = odd LSS 1 = even LSS
No EPC status data is available.
Following
2 cases cause no EPC data.
When Ext Pool ID specified in even number, EPC status request was sent to the device in the odd numbered LSS.
When Ext Pool ID specified in odd number, EPC status request was sent to the device in the even numbered LSS.
Control unit type
Control unit model
Control unit maker/company
Control unit plant
Control unit sequence number
68
68
The format of the next eight bytes is repeated the number times as indicated by SSGEPCNT.
==============================================================
(44) CHARACTER
(44) CHARACTER
8 SSGEPSUM
2 SSGEPIDS
Ext Pool summary data
Extent Pool ID
71
The following two fields are a remaining percentage of usable space that will initiate a notification to the host
70
==============================================================
(46) UNSIGNED 1 SSGEPRWP Ext Pool Repository full warning percentage
(47) UNSIGNED 1 SSGEPFWP Ext Pool Full warning percentage
72 (48) BITSTRING
1... ....
2 SSGEPFLG
SSGEPFB
Ext Pool flags
0=CKD Ext Pool,
1=FB Ext Pool
.1.. ....
SSGEPRC
74
..1. ....
...1 ....
.... 1...
.... .1..
.... ..1.
(4A) CHARACTER 2 *
SSGEOPV
*
*
SSGEPWP
SSGEPF
Ext Pool repository configured
Over Provisioned volumes in Ext pool not used not used
Ext Pool at warning percentage
Ext Pool full not used
The following fields contain detailed Extent Pool configuration information for Extent Pool identified by Ext Pool ID specified by caller.
The address of SSGEPDAT is the sum of SSGEPOAR and SSGEPDDO.
===================================================================================
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
OFFSET OFFSET
======== ======== ========= ======== ============== ===============================
0
0
(0) CHARACTER 12316
(0) CHARACTER 2
SSGEPDAT
SSGEPIDD Ext Pool ID for detailed data
2 (2) BITSTRING
1... ....
1 SSGEPDFG Extent Pool Detailed Flags
SSGEPARN Allocated Space in
Repository is not
.1.. ....
..1. ....
available
SSGEPRAW Repository at warning
SSGEPRF percent
Repository full
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
435
3 (3) CHARACTER 1 * not used
4
8
12
The following fields are expressed in number of cylinders for CKD device.
The following fields are expressed in TENTH of binary Gigabytes for Fix Block device.
==============================================================
(4) UNSIGNED
(8) UNSIGNED
(C) UNSIGNED
4 SSGEPSZ
4 SSGEALOC
4 SSGEPRSZ
Ext Pool size
Space currently allocated in Ext Pool
Size of Ext Pool
Repository, this set
16
20
24
(10) UNSIGNED
(14) UNSIGNED
(18) CHARACTER
4 SSGEPRAL
4 SSGEPGSZ
4 * to 0 when SSGEPRC=0
Space currently allocated in Ext Pool Repository, set to 0 when SSGEPRC=0
Amount of guaranteed space in Repository.
Set to 0 when SSGEPRC=0 not used
28
The next three fields are 32k bitmaps
==============================================================
(1C) BITSTRING 4096 SSGENORM Normally provisioned volumes
4124 (101C) BITSTRING
8220 (201C) BITSTRING
4096 SSGEPOPV
4096 SSGEPSEV
Over provisioned volumes
Space Efficient volumes
MAPPING FOR THE DEVICE PERFORMANCE STATISTICS
OUTPUT BUFFER
Output buffer is anchored by SSGOADR, of a device performance statistics output table.
Output buffer needs to be freed by the caller of this interface. Output buffer is built for a device that supports device performance statistics and returned only if requested by caller for performance data
(SSGRPD) for a request with scope of of device (SSGDEV).
The parameter list extension must also be passed as indicated with SSGARGL2.
====================================================================================
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 256 SSGDPBUF
0
6
(0) CHARACTER
(6) BITSTRING
6
1
SSGDPVOL
SSGDPFLG
DEVICE PERFORMANCE
STATISTICS OUTPUT BUFFER
VOLUME SERIAL
1... ....
.1.. ....
GDPCUI
7
8
12
14
16
16
17
..11 1111
(7) CHARACTER
Real CUID for data
(8) CHARACTER
(C) CHARACTER
(E) SIGNED
(10) CHARACTER
(10) BITSTRING
1... ....
.111 ....
.... 1111
(11) CHARACTER
*
1 SS
SSGDP_UA_FLAG ’ONE’ UNIT ADDR FORMAT
SSGDP_FND_STG2 2ND STG DIR PATH FND
SS01 TO LA01 IDCSS01
PASSED TO IDCLA01
RESERVED
4
2
2
192
1
SSGDPUA1
SSGDPUB1
SSGDPLN
SSGDPDA
SSGDPFTF
SSGDPNAV in ssgdada
FIRST UNIT ADDRESS
FIRST UNIT ADDRESS
(BINARY)
DATA LENGTH
DEVICE PERFORMANCE
STATISTICS DATA AREA
1
SSGDPPDR
SSGDPFDR
SSGDPDUA
Bit =1 : Cache Storage unavailable (Set to zero for 2107/1750)
Mask bits for Format of
Perf Data Returned
Value after masking
( SSGDPFTF & SSGDPPDR )
’000’b 3990 Format
’001’b 2107/1750 Format
Mask bits for Format of data returned.
The same definition and values of bit 4-7 of byte 0 from Sense
Subsystem status.
Device Unit Address of the device to which the
436
z/OS DFSMSdfp Advanced Services
18 (12) CHARACTER
20 (14) UNSIGNED
24 (18) UNSIGNED
28 (1C) UNSIGNED
32 (20) UNSIGNED
36 (24) UNSIGNED
40 (28) UNSIGNED
2 SSGDPDST
4 SSGDPRNI
4 SSGDPRNH
4 SSGDPWNI
4 SSGDPFWH
4 SSGDPRSI
4 SSGDPRSH statistics pertain
Device Status. The same as Sense Subsystem
Status in bytes 26-27
Search/Read Normal I/O
Requests.
The number of command chains which meet the following requirements.
- The chain is not part of a sequential operation.
- The chain did not include a Define Extent command which specified Cache
Fast Write Data.
- The chain contained at least one search or read command but no write commands.
Search/Read Normal I/O
Request Hits.
The number of command chains which meet the following requirements.
- The chain is not part of a sequential operation.
- The chain did not include a Define Extent command which specified Cache Fast
Write Data.
- The chain contained at least one search or read command but no write commands.
- The chain was completed without requiring access to any DDM.
Write Normal I/O Requests.
The number of command chains which meet the following requirements.
- The chain is not part of a sequential operation.
- The chain did not include a Define Extent command which specified Cache
Fast Write Data.
- The chain contained at least one write command.
DASD Fast Write I/O Request
Hits.
The number of command chains which meet the following requirements.
- The chain is not part of a sequential operation.
- The chain did not include a Define Extent command which specified Cache Fast
Write Data.
- The chain contained at least one write command.
- The chain was completed without requiring access to any DDM.
Search/Read Sequential I/O
Requests.
The number of sequential mode command chains which meet the following requirements.
- The chain contained at least one search or read command but no write commands.
Search/Read Sequential I/O
Request Hits.
The number of sequential mode command chains which meet the following requirements.
- The chain contained at least one search or read command but no write
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
437
44 (2C) UNSIGNED
48 (30) UNSIGNED
52 (34) UNSIGNED
56 (38) UNSIGNED
60 (3C) UNSIGNED
64 (40) UNSIGNED
4 SSGDPWSI
4 SSGDPWSH
4 SSGDPRCF
4 SSGDPRCH
4 SSGDPCFW
4 SSGDPCFH commands.
- The chain was completed without requiring access to any DDM.
Write Sequential I/O
Requests.
The number of sequential mode command chains which meet the following requirements.
- The chain contained at least one write command.
Fast Write Sequential I/O
Request Hits.
The number sequential write operations that did not require movement of data to or from a storage device before completion of the I/O operation.
Search/Read Cache Fast Write
I/O Requests.
The number of command chains which meet the following requirements.
- The chain included a Define
Extent command which specified the Cache Fast
Write Data attribute.
- The chain contained at least one search or read command but no write commands.
- Cache Fast Write Data must be activated for the subsystem.
Search/Read Cache Fast Write
I/O Request Hits.
The number of command chains which meet the following requirements.
- The chain included a
Define Extent command which specified the Cache
Fast Write Data attribute.
- The chain contained at least one search or read command but no write commands.
- Cache Fast Write Data must be actuated for the subsystem.
- The chain was completed without requiring access to any DDM.
Cache Fast Write I/O
Requests.
The number of command chains which meet the following requirements.
- The chain included a Define
Extent command which specified the Cache Fast
Write Data attribute.
- The chain contained at least one write command.
- Cache Fast Write Data must be actuated for the subsystem.
Cache Fast Write I/O Request
Hits.
The number of command chains which meet the following requirements.
- The chain included a Define
Extent command which specified the Cache Fast
Write Data attribute.
- The chain contained at least one write command.
- Cache Fast Write Data must be actuated for the subsystem.
- The chain was completed without requiring access
438
z/OS DFSMSdfp Advanced Services
68 (44) UNSIGNED
72 (48) UNSIGNED
76
80
84
88
(4C) UNSIGNED
(50) UNSIGNED
(54) UNSIGNED
(58) UNSIGNED
92 (5C) UNSIGNED
96
100
104
(60) UNSIGNED
(64) UNSIGNED
(68) CHARACTER
105
109
(69) UNSIGNED
(6D) BITSTRING
1111 ....
.... 1...
......11.
110
112
116
.... ...1
(6E) CHARACTER
(70) UNSIGNED
(74) UNSIGNED
4
4
4
4
4
4
4
4
4
1
2
4
4
4
1
SSGDPICL
SSGDPBCI
SSGDPSDC
SSGDPDCC
SSGDPCDC
SSGDPFWD
SSGDPNFW
SSGDPSFW
SSGDPNRM
SSGDPDS2
SSGDPQWP
SSGDPDVD
SSGDPRVA
SSGDPZHV
SSGDPUNI
SSGDPBYV
SSGDPSID
SSGDPITA
SSGDPITH to any DDM.
Inhibit Cache Loading I/O
Request that operate with
DASD (Set to zeros for
2107/1750)
Bypass Cache I/O Requests
(Set to zeros for
2107/1750)
Seq DASD to Cache
Transfer Operations
DASD to Cache Transfer
Operation Count
Cache to DASD Transfer
Operation Count
DASD Fast Write Operation
Delayed Due to non-volatile storage
Space constraints
Normal ’DASD Fast Write’
Write Operation Counts.
The number of command chains which meet the following requirements.
- The chain is not part of a sequential operation.
- The chain did not include a Define Extent command which specified Cache Fast
Write Data.
- The chain contained at least one write command.
- The chain was completed without requiring access to any DDM.
Sequential Access ’DASD
Fast Write’ Write
Operation Counts
Number of record cache
Read misses
Device Status - Group 2
The device status,
SSGDPDS2, is identical to the data returned by the Sense Subsystem
Status in Byte 36.
Note: The format of the data in SSGDPDS2 is determined by the value in SSGDPFDR.
Quick Write Promotes
Flag byte
SSGDPDVD describes the validity of data returned and the increment values used for certain counters
Mask for reserved bits
When set on, SSGDPZHR and
SSGDPZHW are valid.
Mask bits for Units
Value after masking
( SSGDPDVD & SSGDPUNI )
’00’b Unit of SSGDPRRT,
SSGDPWRT,SSGDPBRD,
SSGDPBWR,SSGDPRAT, and SSGDPWAT is
16 milliseconds.
Unit of SSGDPPBR
SSGDPPBW is
128 KB.
’01’b Reserved
’10’b Reserved
’11’b Reserved
1 indicates SSGDPBRD,
SSGDPBWR, SSGDPRAT, and
SSGDPWAT are valid
SSID
Irregular Track Accesses
Irregular Track Access
Hits
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
439
120
124
128
129
130
132
133
134
136
140
144
148
152
156
160
164
168
172
176
180
184
188
(78) UNSIGNED
(7C) UNSIGNED
(80) BITSTRING
(81) CHARACTER
(82) CHARACTER
(84) CHARACTER
(85) BITSTRING
1... ....
.1.. ....
..1. ....
(86) CHARACTER
(88) UNSIGNED
(8C) UNSIGNED
(90) UNSIGNED
(94) UNSIGNED
(98) UNSIGNED
(9C) UNSIGNED
(A0) UNSIGNED
(A4) UNSIGNED
(A8) UNSIGNED
(AC) UNSIGNED
(B0) UNSIGNED
(B4) UNSIGNED
(B8) UNSIGNED
(BC) UNSIGNED
4
4
2
4
1
1
2
1
1
4
4
4
4
4
4
4
4
4
4
4
4
4
SSGDPODC
SSGDPMSL
SSGDPNVI
SSGDPRVB
SSGDPSPI
SSGDPSTY
SSGDPSFL
SSGDPSF0
SSGDPSF1
SSGDPSF2
*
SSGDPPRO
SSGDPPWO
SSGDPPBR
SSGDPPBW
SSGDPRMR
SSGDPNTR
SSGDPNCW
SSGDPTTS
SSGDPNSA
SSGDPRRT
SSGDPWRT
SSGDPBRD
SSGDPBWR
SSGDPRAT
Operation Delayed Due To
Cache Space Constraints
Milliseconds of lower interface I/O activity for the indicated device
(Set to zeros for
2107/1750)
Non-volume information contain in the record
Value Definition
0 No Additional Information
1 RAID Rank Information
2 Segment Pool and Physical
Storage Counter information
3-255 Not Defined
Not used
Segment Pool ID
Non-volume information contained in the record
Segment Type
00-03 Reserved
04 FB 1GB
05-131 Reserved
132 CKD 1GB
133-255 Reserved
Segment Flags
Dynamic Segment
Allocation
Data Sharing
Migrating/Migration Error
State
Not used
Physical Storage Read
Operations
Physical Storage Write
Operations
Physical Storage Bytes
Read. See Increment Value in SSGDPDVD
Physical Storage Bytes
Written. See Increment
Value in SSGDPDVD
Record Mode Read
Operations
Number of tracks read from the concurrent Copy or XRC Sidefile
Number of contaminating writes for a Concurrent Copy or XRC volume as a result of:
- Update to a Concurrent Copy protected track.
- Update to an XRC monitored track.
Number of tracks or portion of tracks that were transferred to the secondary device of a PPRC pair
NVS Space Allocations
Physical Storage Read
Response Time. See
Increment Value in
SSGDPDVD
Physical Storage Write
Response Time. See
Increment Value in
SSGDPDVD
Bytes Read. See Increment
Value in SSGDPDVD
Bytes Written. See
Increment Value in
SSGDPDVD
Read Accumulated Time.
The accumulated response time for all read operations.
See Increment Value in
SSGDPDVD
440
z/OS DFSMSdfp Advanced Services
192
196
200
204
208
212
216
(C0) UNSIGNED
(C4) UNSIGNED
(C8) UNSIGNED
(CC) CHARACTER
(D0) UNSIGNED
(D4) UNSIGNED
(D8) UNSIGNED
4
4
4
4
4
4
4
SSGDPWAT
SSGDPZHR
SSGDPZHW
Write Accumulated Time.
The accumulated response time for all write operations. See Increment
Value in SSGDPDVD zHPF Read I/O Requests. This count is the number of Transport
Mode read command chains. The
Read I/O Request will also be counted in one of the following counters:
- SSGDPRNI, Search/Read Normal
I/O Requests
- SSGDPRSI, Search/Read
Sequential I/O Requests
- SSGDPRCF, Search/Read Cache
Fast Write I/O Requests zHPF Write I/O Requests.
This count is the number of Transport
Mode write command chains. The
Write I/O Request will also be counted in one of the following counters:
- SSGDPWNI, Write Normal I/O
Requests
- SSGDPWSI, Write Sequential I/O
Requests
- SSGDPCFW, Cache Fast Write I/O
Requests
SSGDPRVX Not used - zeros
SSGDPZHL zHPF List Pre-fetch I/O
Requests. This count is the number of command chains which meet the following requirements:
- The Transport Mode operation specified a non-zero Imbedded
Locate Record Count.
SSGDPZHH zHPF List Pre-fetch I/O Requests
Hits. This count is the number of common chains which meet the following requirements:
- The Transport Mode operation specified a non-zero Imbedded
Locate Record Count.
- The chain was completed without requiring access to any DDM.
SSGDPGSF Global Mirror Collisions
Sidefile Count. A GM collision occurs when, during the sending
220 (DC) UNSIGNED 4 of data to the secondary to create a consistency group, a subsequent host update is attempted before the modified track has been transmitted to the secondary volume. The modified track will be moved to the sidefile before allowing a new host write. This counter will be incremented by one when a track is added to the sidefile.
SSGDPGSS Global Mirror Collisions Send
Synchronous Count. When a write collision occurs, the modified track data which belongs to the current consistency group may be sent to the remote control unit before allowing the write. The data may come from the sidefile if it is full or from cache if the collision sidefile is not being utilized.
SSGDPRVY Not used - zeros 224 (E0) CHARACTER
RETURN CODES FROM IDCSS01
32
====================================================================================
Chapter 12. User Access to Subsystem Statistics, Status, and Counts Information
441
LEN TYPE VALUE NAME DESCRIPTION
===== ========= ================= =============== ===============================
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
0000
0004
0008
000C
SS01CC00
SS01CC04
SS01CC08
SS01CC12
SUCCESSFUL COMPLETION
GETMAIN FAILED
I/O ERROR OCCURRED
VOLUME NOT FOUND
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
0010
0014
0018
001C
0020
SS01CC16
SS01CC20
SS01CC24
SS01CC28
SS01CC32
ESTAE FAILED
LRA INSTRUCTION FAILED
BUFFER NOT LARGE ENOUGH
FILE NOT IN TIOT
VOLUME NOT FOUND ALL
2
2
2
2
2
2
2
2
NUMB HEX
NUMB HEX
NUMB HEX
NUMB HEX
NUMB HEX
NUMB HEX
NUMB HEX
NUMB HEX
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
2 NUMB HEX
0024
0028
002C
0030
0034
0038
003C
0040
0044
0046
0047
0048
0049
004A
0063
SS01CC36
SS01CC40
SS01CC44
SS01CC48
SS01CC52
SS01CC56
SS01CC60
SS01CC64
SS01CC68
SS01CC70
SS01CC71
SS01CC72
SS01CC73
SS01CC74
SS01CC99
NO PATH(S) TO SD(S)
NO ONLINE PATH FROM IOS
REQUEST NOT SUPPORTED
WARNING MSG ISSUED
ERROR MSG ISSUED
SERIOUS ERROR MSG
I/O timeout occured
Reserved
RESERVED
IOSCDR ERROR
UCBINFO ERROR
RESERVED
MISSING CDR INFOR
ERR DURING CDR INFOR
GATHERING.
RESERVED
REASON CODES FROM ESS (BOX) PERFORMANCE STATISTICS
(SSGLPRET, SSGRSRET, SSGSGRET).
====================================================================================
LEN TYPE VALUE NAME DESCRIPTION
===== ========= ================= =============== ===============================
1 NUMB HEX 01 SS01LP01 Stats requested, all stats
1 NUMB HEX 02 SS01LP02 returned on supporting subsystem boxes
Stats not requested by the
1
1
NUMB HEX
NUMB HEX
03
04
SS01LP03
SS01LP04 caller
Stats requested, but no supporting subsystem boxes found to support them
Stats requested, but stats from one or more supporting subsystem boxes could not be read
442
z/OS DFSMSdfp Advanced Services
Appendix A. Control Blocks
The following control blocks are described here: v
“Data Extent Block (DEB) Fields” for EXCP and EXCPVR.
v
“Data Facilities Area (DFA) Fields” on page 449
Data Extent Block (DEB) Fields
The data extent block (DEB) fields shown here should only be used with EXCP and
EXCPVR (see z/OS DFSMSdfp Diagnosis53 for all fields in the DEB).
Common Name:
Data Extent Block
Macro ID:
IEZDEB
DSECT Name:
v DEB (DSECT card precedes AVT section) v DEBBASIC should be used for USING basic section.
v DEBDASD (DSECT name for direct access section) v DEBACSMD (DSECT name for access method sections) v DEBSUBNM (DSECT name for subroutine name section) v DEBXTN (DSECT name for DEB extension)
Owning Component:
Data Management, subcomponent OPEN/CLOSE/EOV
Eye-Catcher ID:
None
Subpool and Key:
230 and key 5
Size:
Variable (device and access method dependent sections)
Created by:
OPEN
Pointed to by:
DCBDEBAD field of the DCB data area. DEBDEBAD field of the DEB data area (next DEB on the chain)
Serialization:
LOCAL lock serializes the placing of a DEB on the TCB DEB chain and in the DEB table. OPEN/CLOSE/EOV processing is serialized by local lock and DEBCHK.
Function:
The DEB is a repository for information from the DCB, data set label, device and user. Each DEB is associated with a DCB, and the two point to each other. It contains information about the physical characteristics of the data set, and other information used by the control program. The DEB also serves to control the user program's access to the data set and its device.
Table 96. Partial Listing of DEB Fields
Offset Type Length Name Description
Appendage vector table section of the DEB pointed to by DEBAPPAD. It is not necessarily contiguous with the DEB or DEB prefix.
0(0)
0(0)
0(0)
1(1)
ADDRESS
BITSTRING
. . . . xxxx
ADDRESS
20
4
1
3
DEBAVT(0)
DEBEOEA(0)
DEBEOEAB
DEBEOENP
DEBEOEAD
Appendage vector table
Address of end-of-extent appendage routine
Flag byte
X'0F'– number of 2K pages to be fixed for the end–of–extent appendage
Address of end-of-extent appendage routine
© Copyright IBM Corp. 1979, 2017
443
Control Blocks
Table 96. Partial Listing of DEB Fields (continued)
Offset Type Length Name Description
4(4)
4(4)
5(5)
8(8)
8(8)
9(9)
12(C)
12(C)
13(D)
16(10)
16(10)
17(11)
1(1)
ADDRESS
BITSTRING
1. . . . . . .
.1. . . . . .
. .1. . . . .
. . .1 . . . .
. . . . xxxx
ADDRESS
ADDRESS
BITSTRING
. . . . xxxx
ADDRESS
ADDRESS
BITSTRING
1. . . . . . .
. . . . xxxx
ADDRESS
ADDRESS
BITSTRING
. . . . xxxx
ADDRESS
X''
ADDRESS
BITSTRING
ADDRESS
4
1
3
4
1
3
4
1
3
4
1
3
4
1
3
DEBSIOA(0)
DEBSIOAB
DEBPGFX
DEBSIOX
DEBIOVR
DEBFIX
DEBSIONP
DEBSIOAD
DEBPCIA(0)
DEBPCIAB
DEBPCINP
DEBPCIAD
DEBCEA(0)
DEBCEAB
DEBESMVR
DEBCENP
DEBCEAD
DEBXCEA(0)
DEBXCEAB
DEBXCENP
DEBXCEAD
DEBAVTE
DEBTCBB
Address of start I/O appendage routine
Flag byte
X'80' Address in DEBSIOAD can be used to determine the entry point to the page fix (PGFX) appendage routine by adding 4 to the address in
DEBSIOAD
X'40'– if zero, do not enter SIO appendage when ERP IS active. If one, enter
SIO appendage even when ERP is active.
X'20'– If one, EXCPVR request is valid. If zero, EXCPVR request is invalid and will not be executed. Currently has no effect.
X'10' Indication that DEB has been fixed
X'0F'– number of 2K pages to be fixed for the SIO appendage
Address of start I/O appendage routine
Address of PCI appendage routine
Flag byte
X'0F'–number of 2K pages to be fixed for the PCI appendage
Address of program controlled interruption (PCI) appendage routine
Address of channel end appendage routine
Flag byte
X'80',c'x' validity check for EXCPVR caller
X'0F'– number of 2K pages to be fixed for the channel–end appendage
Address of channel end appendage routine
Address of abnormal end appendage routine
Flag byte
X'0F'– number of 2K pages to be fixed for the abnormal–end appendage
Address of abnormal end appendage routine
"*" End of appendage vector table
DEB PREFIX TABLE. Addressable as negative offset from DEB basic section. Not necessarily contiguous with DEB appendage vector table.
-16(10)
-16(10)
-15(F)
-8(8)
-4(4)
-3(3)
BITSTRING
BITSTRING
ADDRESS
BITSTRING
16
1
7
4
1
CHARACTER 1
X'0'
X'1'
X'2'
X'4'
X'8'
X'10'
X'20'
X'20'
X'40'
X'81'
X'82'
X'84'
-2(2) UNSIGNED
X'24'
DEB basic section
2
DEBPREFX(0)
DEBWKARA
DEBDSCBA
DEBXTNP(0)
DEBLNGTH
DEBAMTYP
DEBAMNON
DEBAMVSM
DEBAMXCP
DEBAMGAM
DEBAMTAM
DEBAMBPM
DEBAMSAM
DEBAMBDM
DEBAMSUB
DEBAMVTM
DEBTBLOF
DEBPREFE
DEB prefix table
O/C/E work area (direct access)
DSCB address (BBCCHHR) used by O/C/E (direct access)
Pointer to DEB extension
Length of DEB in double words. If it exceeds 2040 bytes (X'FF' doublewords), the excess bits are ignored.
Access method type
"0" Access method type not known
"1" VSAM access method type
"2" EXCP access method type
Reserved
"8" Graphics access method type
"16" BTAM access method type
"32" BPAM access method type
"32" Sequential access method type
"64" Direct access method type
"129" subsystem access method type
"130" VTAM
® access method type
Reserved
For system use
"*" End of DEB prefix table
0(0)
0(0)
0(0)
DEBBASIC
DEBTCBAD(0)
DEBNMSUB
"*"
Address of TCB for this DEB
Number of subroutines loaded by OPEN executor routines and identified in the subroutine name section (DEBSUBID)
Address of TCB for this DEB
444
z/OS DFSMSdfp Advanced Services
Control Blocks
Table 96. Partial Listing of DEB Fields (continued)
Offset Type Length Name Description
4(4)
4(4)
5(5)
8(8)
8(8)
9(9)
12(C)
13(D)
14(E)
15(F)
16(10)
16(10)
ADDRESS
BITSTRING
ADDRESS
ADDRESS
BITSTRING xx. . . . . .
01. . . . . .
10 . . . . . .
11. . . . . .
. .1. . . . .
. . .1 . . . .
. . . . .1. .
. . . . . .1.
. . . . . . .1
ADDRESS
BITSTRING
1. . . . . . .
.0. . . . . .
. .xx . . . .
. . 01 . . . .
. .11 . . . .
. . . . xxxx
. . . . 0000
. . . . 1111
. . . . 0011
. . . . 0111
. . . . 0001
. . . . 0100
BITSTRING
BITSTRING
1. . . . . . .
.1. . . . . .
. . .1 . . . .
. . . . .1. .
. . . . . .1.
. . . . . . .1
BITSTRING
. . . . 1. . .
. . . . .1. .
. . . . . . 1.
ADDRESS
BITSTRING
3
4
1
4
1
1
1
3
1
1
4
1
DEBDEBAD(0)
DEBAMLNG
DEBDEBB
DEBIRBAD(0)
DEBOFLGS
DEBDISP
DEBDSOLD
DEBDSMOD
DEBDSNEW
DEBEOF
DEBRLSE
DEBSPLIT
DEBLABEL
DEBRERR
DEBIRBB
DEBOPATB
DEBABEND
DEBZERO
DEBPOSIT
DEBRERED
DEBLEAVE
DEBACCS
DEBINPUT
DEBOUTPT
DEBINOUT
DEBOUTIN
DEBRDBCK
DEBUPDAT
DEBQSCNT
DEBFLGS1
DEBPWCKD
DEBEOFDF
DEBEXCPA
DEBF1CEV
DEBAPFIN
DEBXTNIN
DEBFLGS2
DEBDSCMP
DEBDSNCP
DEB31UCB
DEBUSRPG(0)
DEBNMEXT
Address of the next DEB in the same task
Number of bytes in the access method dependent section. For BDAM this field contains the length expressed in number of words.
Address of the next DEB in the same task
IRB storage address used for appendage asynchronous exits
Data set status flags
X'C0'– data set disposition flags bit setting disposition
X'40' old data set
X'80' mod data set
X'C0' new data set
X'20'– end of file (EOF) encountered (tape input) format 1 DSCB bit 93.0
indicates that the current volume is the last volume of the data set (DASD input)
X'10'– release unused external storage (DASD) emulator tape with second generation format. Tape might contain blocks shorter than 12 characters.
(tape)
X'04'–7–track emulator tape with possible mixed parity records (tape)
X'02'– nonstandard labels
X'01'– use reduced error recovery procedure (tape) concatenated partitioned organization data sets processed using BPAM (DASD)
IRB storage address used for appendage asynchronous exits
Flags indicating both the method of I/O processing and the disposition that is to be performed when an end of volume (EOV) condition occurs
X'80'– set by abend indicating a sysabend or sysudump data set
X'40'– always zero
X'30'– data set positioning flags bit setting positioning
X'10' reread
X'30' leave
X'0F'– type of I/O accessing being done bit setting accessing
X'0' INPUT
X'F' OUTPUT or EXTEND
X'3' INOUT
X'7' OUTIN or OUTINX
X'1' RDBACK
X'4' UPDAT
PURGE (SVC 16) – Quiesce count. Number of devices executing user's channel programs, as shown by bits 5 and 6 of UCBFL1 fields.
Flag field
X'80'– password was supplied during OPEN. EOV will not request a password for each additional volume of a multivolume data set.
X'40'– set by EOV to inform close that an end of file has been encountered and, therefore, deferred user label processing is allowed.
X'10'– EXCP(VR) is authorized for this DEB
X'04'–not valid with an EXCP DCB.
X'02'– if on, authorized programs can be loaded
X'01'– if one, DEB extension exists
Flag field two
The following two flag bits are used by O/C/EOV to maintain a uniform recording mode (compaction or non-compaction) on tape data sets that span over more than one volume.
X'08' tape data set compaction mode
X'04' tape data set non-compaction mode
UCB address fields are four bytes. Use DEBSUCBA, DEBUCBAD,
DEBSDVMX or DEBDVMOD31 instead of DEBSUCBB, DEBUCBA,
DEBSDVM or DEBDVMOD.
Address of purged I/O restore list (PIRL)
Number of extent descriptions starting at DEBBASND. One extent per unit for extended format or PDSE data sets.
Appendix A. Control Blocks
445
Control Blocks
Table 96. Partial Listing of DEB Fields (continued)
Offset Type Length Name Description
17(11)
20(14)
20(14)
24(18)
24(18)
24(18)
25(19)
28(1C)
28(1C)
29(1D)
32(20)
ADDRESS
ADDRESS
BITSTRING
ADDRESS
BITSTRING
BITSTRING
ADDRESS
ADDRESS
ADDRESS
ADDRESS
3
4
1
4
1
1
3
4
1
3
DEBUSRPB
DEBRRQ(0)
DEBPRIOR
DEBDCBAD(0)
DEBPROTG(0)
DEBDEBID
DEBDCBB
DEBAPPAD(0)
DEBEXSCL
DEBAPPB
DEBBASND
Address of purged I/O restore list (PIRL)
Pointer to related request queue
Priority of the task owning DEB
Address of DCB or ACB associated with this DEB
Task protection key in high order 4 bits
A hex F in low–order 4 bits to identify this block as a DEB
Address of DCB or ACB associated with this DEB
Address of the I/O appendage vector table
This field is used to determine the size of the device dependent section. Two to this power gives the length of the device dependent section at
DEBBASND. Extent scale – 4 (16 bytes) for direct access device and 3525 card punch with device–associated data set support and 2 (4 bytes) for nondirect access device and communication device.
Address of the I/O appendage vector table
End of basic section
After the basic section is one or more device-dependent sections. DEBEXSCL contains its length. DEBNMEXT contains the number of device-dependent sections. All of the device-dependent sections are for the same device class.
Unit Record, Magnetic Tape, Telecommunications Devices Section
32(20)
32(20)
32(20)
33(21)
36(24)
ADDRESS
BITSTRING
1101 0011
1100 0011
1100 1011
0000 0011
0100 0011
1000 0011
1100 0011
1. . . . . . .
.1. . . . . .
. .1. . . . .
. . .1 . . . .
. . . . 1. . .
. . . . 1. . .
. . . . . .1.
. . . . . . .1
X'C2'
X'42'
ADDRESS
4
1
3
0
DEBDDS1
DEBSUCBA(0)
DEBSDVM
DEBMTDN4
DEBMTDN3
DEBMTDN2
DEBM7DN0
DEBM7DN1
DEBM7DN2
DEBMSTWI
DEBMTRF0
DEBMTRF1
DEBMTWI
DEBMINHS
DEBMCOMP
DEBCMPAC
DEBM3424
DEBMINHE
DEBM6250
DEBM1600
DEBSUCBB
DEBDEVED(0)
"*"
Device modifier. For magnetic tape, MODESET operation code. For unit record, not defined. Valid only if DEB31UCB is off.
X'D3' 9–track MODESET CCW CODE DENSITY=6250BPI
X'C3' 9–track MODESET CCW CODE DENSITY=1600BPI
X'CB' 9–track MODESET CCW CODE DENSITY= 800BPI 7–track TAPE
MODESET skeleton codes (must be completed with parity, translation and/or conversion)
X'03' 7–track MODESET SKELETON DENSITY=200BPI
X'43' 7–track MODESET SKELETON DENSITY=556BPI
X'83' 7–track MODESET SKELETON DENSITY=800BPI 3480 tape operation code
X'C3' 3480 set tape write immediate ccw code. Tape mode set function byte
X'80' tape recording format bit 0
X'40' tape recording format bit 1
X'20' tape write immediate (non-buffered write)
X'10' inhibit supervisor commands
X'08' compacted recording mode
"DEBMCOMP" COMPACTED RECORDING MODE
X'02' 3424 mode set flag
X'01' inhibit control unit ERP
"DEBMTRF0+ DEBMTRF1+ DEBM3424"SET 3424 DENSITY=6250BPI
"DEBMTRF1+ DEBM3424" SET 3424 DENSITY=1600BPI
Address of a UCB associated with a given data set
End of common tape and unit record fields if DEB31UCB is off.
Next four bytes present only if DEB31UCB is on
36(24)
37(25)
40(28)
BITS 1
CHARACTER 3
0
DEBSDVMX
DEBDVEDX
Device modifier. For magnetic tape, modeset operation code or modeset function byte. For unit record reserved. Present only if DEB31UCB is on.
Reserved
End of section if DEB31UCB is on.
The following fields are present only for the 3525 with device–associated data set support
36(24)
36(24)
37(25)
ADDRESS
BITSTRING
ADDRESS
4
1
3
DEBRDCB(0)
DEBRSV06
DEBRDCBA
446
z/OS DFSMSdfp Advanced Services
Control Blocks
Table 96. Partial Listing of DEB Fields (continued)
Offset Type Length Name Description
40(28)
40(28)
41(29)
44(2C)
44(2C)
45(2D)
ADDRESS
BITSTRING
ADDRESS
ADDRESS
BITSTRING
ADDRESS
4
1
3
4
1
3
Address of DCB for the read associated data set
Direct–access storage device section it follows the basic section. There is one of these sections for each extent, except for a pdse or extended format data set, in which case there is one section per device.
0(0) ADDRESS 4 DEBUCBAD
0(0)
1(1)
4(4)
5(5)
6(6)
8(8)
10(A)
12(C)
14(E)
BITSTRING
ADDRESS
BINARY
BINARY
BINARY
BINARY
BINARY
BINARY
BINARY
1
3
1
1
2
2
2
2
2
DEBPDCB(0)
DEBRSV07
DEBPDCBA
DEBWDCB(0)
DEBRSV08
DEBWDCBA
DEBASDSE
DEBDVMOD
DEBUCBA
DEBDVMOD31
DEBNMTRKHI
DEBSTRCC
DEBSTRHH
DEBENDCC
DEBENDHH
DEBNMTRK
DEBDASDE
Address of a UCB associated with this extent. The following applies to
DEBSUCBA, DEBSUCBB, DEBUCBAD and DEBUCBA: If the actual UCB is above the 16 MB line and the dynamic allocation nocapture option is not in effect, allocation normally captures the UCB to create a 24-bit address. When using EXCP and you specify the nocapture option of dynamic allocation but not the LOC=ANY option on the DCBE, then OPEN or EOV captures the
UCB until a later EOV or close. In these cases the high order byte of this word contains the device modifier byte. If you specify nocapture on the dynamic allocation and the actual DASD or tape UCB address is above the line and the DCB is for BSAM, BPAM, QSAM or EXCP and the DCBE has specified LOC=ANY, then the system does not capture the UCB. In that case
OPEN turns on the DEB31UCB bit to signify the 31-bit UCB address field is valid and that the device modifier byte is in DEBSDVMX or DEBDVMOD31.
It may remain on for subsequent volumes even though they have actual
24-bit addresses in a four-byte field.
Device modifier. File mask. Valid only if DEB31UCB is off.
Address of UCB for this extent. Valid only if DEB31UCB is off.
Reserved if DEB31UCB is off. File mask (device modifier) if DEB31UCB is on.
High order byte of number of tracks in extent. Low order two bytes are in
DEBNMTRK. DEBNMTRKHI combined with DEBNMTRK gives total number of tracks in this extent. DEBNMTRKHI is 0 for a basic format data set and may be non-zero for a large format data set.
Low order 16 bits of cylinder number of start of extent
High order 12 bits of cylinder number and four-bit track number of start of extent
Low order 16 bits of cylinder number of end of extent. Not set for a PDSE
High order 12 bits of cylinder number and four-bit track number of end of extent. For PDSE this field is reserved. For an extended format data set this field contains the track number of the format-1 dscb address.
Number of tracks allocated to a given extent. For a pdse this field is set to one(X'0001'). For an extended format sequential data set the first byte contains the record number of the format-1 dscb address, and the second byte is zero.
"*" end of DASD device section
Access method section. DEBAMLNG contains its length. The following is for EXCP, BSAM and QSAM.
0(0) BINARY 2 DEBVOLSQ Volume sequence number for multivolume sequential data sets
0(0)
1(1)
2(2)
4(4)
4(4)
4(4)
5(5)
8(8)
BITSTRING
SIGNED
BINARY
BINARY
ADDRESS
BITSTRING
ADDRESS
BITSTRING
1
1
2
8
4
1
3
4
DEBVOLBT
DEBVLSEQ
DEBVOLNM
DEBDSNM
DEBUTSAA
DEBRSV13
DEBUTSAB
DEBRSV14
First byte of debvolsq. Reserved for system use.
For direct access, sequence number of the volume of the data set relative to the first volume of the data set. For tape, sequence number of the volume of the data set relative to the first volume processed.
Total number of volumes in a multivolume sequential data set.
Member name. This field appears only when an output data set has been opened for a member name and the dscb specifies a partitioned data set.
Address of the user totaling save area
For system use
Address of the user totaling save area
For system use (if user totaling was specified)
Appendix A. Control Blocks
447
Control Blocks
Table 96. Partial Listing of DEB Fields (continued)
Offset Type Length Name Description
12(C)
14(E)
SIGNED
SIGNED
BPAM Dependent Section
2
2
DEBBLKSI
DEBLRECL
Maximum block size
Logical record length
0(0) BINARY 1 DEBEXTNM For a partitioned data set opened for input, each one–byte field contains the extent number of the first extent entry for each data set except the first, if two or more data sets are concatenated. The number of bytes in the field is equal to one less than the number of data sets concatenated.
0(0) CHARACTER 8 DEBDSNAM For a partitioned data set opened for output for a member name, this field is the member name.
BDAM Dependent Section For Fixed Length Records With The Option Of Relative Block Addressing
0(0)
0(0)
1(1)
BINARY
ADDRESS
BINARY
4
1
3
DEBDBLK
DEBDBPT
DEBDBPE
One four byte field for each extent described in the device dependent section
Number of blocks per track
Number of blocks per extent
Subroutine name section. DEBNMSUB contains how many names this section contains. It follows the access method dependent section or the device dependent section if there is no access method section.
0(0) CHARACTER 2 DEBSUBID Subroutine identification. Each access method subroutine, appendage subroutine, and irb routine will have a unique eight–byte name. The low–order two bytes of each routine name will be in this field if the subroutine is loaded by the OPEN routines.
DEB Extension Pointed To By DEBXTNP In The DEB Prefix
0(0)
2(2)
3(3)
SIGNED
BITSTRING
BITSTRING
.1. . . . . .
2
1
1
DEBXLNGH
DEBXFLG1
DEBXFLG2
DEBBYP
4(4)
8(8)
12(C)
16(10)
40(28)
40(28)
41(29)
. .1. . . . .
ADDRESS
BITSTRING
ADDRESS 4
CHARACTER 24
BITSTRING
BITSTRING
1. . . . . . .
.1. . . . . .
BITSTRING xx. . . . . .
1. . . . . . .
.1. . . . . .
. .1. . . . .
. . .x xx . .
. . .1 . . . .
. . . . 1 . . .
. . . . .1 . .
. . . 0 00 . .
. . . 0 01 . .
. . . 0 10 . .
. . . 0 11 . .
8
1
4
4
1
DEBCHCMP
DEBXDSAB
DEBXDBPR
DEBXDEF(0)
DEBDEFG1
DEBNSHED
DEBXVDEF
DEBGATTR
DEBECKD
DEBGAEX1
DEBGAEX2
DEBSTRTP
DEBGA345
DEBGA1
DEBGA2
DEBGA3
DEBNCACH
DEBBCACH
DEBICACH
DEBSCACH
Length of DEB extension
Flag byte—for system use
Flag byte
X'40'– when on EXCP scan routine will set iosbyp on and bypass building a prefix
X'20'– when on EXCP scan routine will set ioschcmp on and bypass building a prefix
Pointer to dsab
For system use
Pointer to DEB
For system use
Define extent data area
Flag byte
X'80' no seek head permitted
X'40' DEB def ext data parms valid. Must be on for dx data to be used.
Global attributes
X'C0' extent definition 2 b'00......' define extent operates as defined for fixed block arch b'11......' define extent operates as defined for ckd ext-cchh extents
X'80' extent definition 1
X'40' extent definition 2
X'20' data storage type-norm/temp b'..1.....' normal data storage b'..0.....' temporary data storage
X'1c' attributes bits 3,4,5 b'...000..' normal cache access b'...001..' bypass cache load b'...010..' inhibit cache load b'...011..' sequential access b'...100..' reserved b'...101..' reserved b'...111..' reserved b'......xx' reserved
X'10' attribute 1
X'08' attribute 2
X'04' attribute 3 b'...000..' normal cache access b'...001..' bypass cache load b'...010..' inhibit cache load b'...011..' sequential access b'...100..' sequential staging mode'...101..' record access mode b'...111..' reserved b'......xx' reserved
X'00' normal cache access
X'04' bypass cache load
X'08' inhibit cache load
X'0c' sequential access
448
z/OS DFSMSdfp Advanced Services
Control Blocks
Table 96. Partial Listing of DEB Fields (continued)
Offset Type Length Name Description
42(2A)
44(2C)
44(2C)
46(2E)
48(30)
52(34)
. . . . . .1.
. . . . . . .1
BITSTRING 2
CHARACTER 4
CHARACTER 2
CHARACTER 2
CHARACTER 4
CHARACTER 4
DEBNRD
DEBINHFW
DEBBLKSZ
DEBEXTOK
DEBNRDID
DEBIOPID
DEBBLKID
X'02' non-retentive data access
X'01' inhibit fast write b'......10' use non-retentive data b'......11' inhibit DASD fast write
Blocksize in bytes if less than or equal to 32760
Zero,extent locator or token
Subsystem function id: non-retentive data id or concurrent copy / xrc session id
For system use
Block id value used to calculate number of blocks in this tape volume for extended block count checking
Data Facilities Area (DFA) Fields
Except for DFADFVAD, all of the fields in the DFA are part of the intended programming interface.
Common Name:
Data Facilities Area
Macro ID:
IHADFA
DSECT Name:
DFA
Eye-Catcher ID:
DFAACRON
Subpool and Key:
Nucleus resident and Key 0; Resident below 16MB
Size:
112 bytes
Created by:
Assembled into nucleus
Pointed to by:
CVTDFA field of the CVT
Serialization:
N/A
Function:
Maps the Data Facilities Area, which contains information that applies to
DFSMS.
Table 97. DFA Fields
Offset Type/Value Length Name Description
0(0) UNSIGNED 2 DFALEN LENGTH OF THIS TABLE
VERSION, RELEASE, AND MODIFICATION LEVEL INFORMATION FOR DFP. THE FIRST THREE DIGITS OF DFAREL REPRESENTS THE LAST
LEVEL OF DFP(X'332'). THE FOURTH DIGIT OF DFAREL BEING NON-ZERO INDICATES THE LEVEL OF THIS PRODUCT IS HIGHER THAN THE
INDICATED LEVEL.
2(2) BITSTRING 2 DFAREL FOUR DIGITS = VERSION, RELEASE, MOD, X
THE FOLLOWING ARE THE FEATURE BYTES. WHEN A BIT IS ON, IT MEANS EITHER THAT THE CURRENT RELEASE SUPPORTS THE
FEATURE OR THAT THIS PARTICULAR INSTANCE OF THE SYSTEM SUPPORTS THE FEATURE. IF THE SOFTWARE SUPPORTS A FEATURE BUT
IT CANNOT BE USED, PERHAPS BECAUSE COREQUISITE SOFTWARE OR HARDWARE IS NOT AVAILABLE, THEN THE FEATURE BIT WILL BE
OFF.
4(4)
4(4)
SIGNED
BITSTRING
1... ....
.1.. ....
..1. ....
...1 ....
4
1
DFAFEATS(0)
DFAFEAT1
DFAXA
DFALSR
DFAEOS
DFAXRF
ALL FEATURES BYTES–USED BY CS INSTR
FEATURES BYTE 1
"X'80'" MVS/XA (COPY OF CVTMVSE IN CVT)
Multiple VSAM LSR pools supported (MVS/XA DFP 1.1.0 in 1983)
DASDM erase on scratch supported (MVS/XA DFP 2.1.0 in 1985)
Extended recovery facility (MVS/XA DFP 2.1.0)
Appendix A. Control Blocks
449
Control Blocks
Table 97. DFA Fields (continued)
Offset Type/Value
.... 1...
.... .1..
.... ..1.
.... ...1
Length Name
DFAEXPCI
DFAEOSIC
DFASMS
DFAPDSE
5(5)
6(6)
.... ...1
BITSTRING
1... ....
.1.. ....
..1. ....
...1 ....
.... 1...
.... .1..
.... ..1.
.... ...1
BITSTRING
1... ....
.1.. ....
.1.. ....
..1. ....
...1 ....
.... 1...
1
1
DFAIPDS
DFAFEAT2
DFADLS
DFAPML
DFAFMS
DFACMPAC
DFABPBLD
DFASSF
DFAMMEXT
DFAINDEF
DFAFEAT3
DFAVOLSN
DFASAMEX
DFASMSEX
DFAKSDEX
DFACMPCT
DFARLSJ3
7(7)
8(8)
12(C)
.... .1..
.... ..1.
.... ...1
BITSTRING
1... ....
.1.. ....
..1. ....
..1. ....
.... 1...
.... .1..
.... ..1.
.... ...1
CHARACTER
BITSTRING
1... ....
.1.. ....
..1. ....
...1 ....
1
4
1
DFARECAL
DFADEEXT
DFADLL
DFAFEAT4
DFAFDAT
DFANSRV
DFADYNL
DFACIR2
DFADYLPA
DFAFORK
DFASNBK
DFASNAP
DFAACRON
DFAFEAT5
DFAUPDSE
DFABTSREQ
DFABLDLS
DFAUSEAV
....1...
DFASAMHPF
..... .1..
450
z/OS DFSMSdfp Advanced Services
Description
EXPORT by control interval (MVS/XA DFP 2.1.0)
ERASE on scratch for ICF (MVS/XA DFP 2.1.0)
System managed storage (SMS) (MVS/DFP 3.1.0 in 1989)
"X'01'" PDSE SUPPORT AVAILABLE ON THE SYSTEM SET BY
IEAVNP26 WHEN DFP LEVEL IS 3.2.0 OR GREATER AND AN
APPROPRIATE LEVEL OF SP EXISTS.
"DFAPDSE" IPDS IS OLD NAME FOR PDSE
FEATURES BYTE 2
"X'80'" RESERVED
"X'40'" RESERVED
"X'20'" FILE MANAGEMENT SERVICES SUPPORTED
"X'10'" INSTALLATION DEFAULT FOR COMPACTION
"X'08'" BYPASS CHANNEL PROGRAM PREFIX BUILD
"X'04'" SSF SERVICES ARE AVAILABLE
"X'02'" MMS SUPPORTS XTIOT
"X'01'" COMPACTION DEFAULT EXPLICITLY SET BY
INSTALLATION
FEATURES BYTE 3
"X'80'" VOLSER EXTRACTED FROM SENSE INFO ACCEPTABLE
BY THE INSTALLATION
EXTENDED FORMAT SEQUENTIAL DATA SETS SUPPORTED
ALIAS FOR DFASAMEX
EXTENDED FORMAT KSDS SUPPORTED
DFSMS ACCESS METHOD COMPRESSION SUPPORTED. BIT SET
BY SMS SUB-SYSTEM INITIALIZATION.
THE SMSVSAM SERVER HAS SUCCESSFULLY INITIALIZED ON
THIS SYSTEM. THIS BIT IS USED BY SMS SCHEDULING. ONCE
ON, THIS BIT REMAINS ON FOR THE LIFE OF THE IPL. THIS BIT
DOES NOT INDICATE THAT THE SMSVSAM SERVER IS
CURRENTLY OPERATIONAL.
DATA SET RECALL CAPABILITY VIA
®
IS AVAILABLE.
THE ARCHRCAL MACRO
DESERV EXIT FUNCTION IS AVAILABLE
DFSMS DLL SUPPORT IS AVAILABLE
FEATURES BYTE 4
RESERVED
DFP NIP SERVICES CAN BE INVOKED VIA IGGSSRV MACRO
DYNAMIC LINKLIST IS SUPPORTED
THE CATALOG INFORMATION ROUTINE, IKJEHCIR, SUPPORTS
A FORMAT 2 WORK AREA, I.E., FULL WORD LENGTH FIELDS
DFSMS SUPPORT FOR DYNAMIC LPA IS AVAILABLE.
DFSMS LOADER FORK EXIT IS PRESENT
SOFTWARE SUPPORT PROVIDING “FAST” BACKUP USING THE
SNAPSHOT FEATURE OF THE RAMAC VIRTUAL ARRAY (RVA)
INSTALLED.
THE API SUPPORT FOR THE SNAPSHOT FEATURE OF THE
RAMAC VIRTUAL ARAY (RVA) IS INSTALLED.
ACRONYM FOR THIS CONTROL BLOCK.
FEATURES BYTE 5
UNMANAGED PDSE SUPPORT INSTALLED ON THIS SYSTEM.
1 means BLOCKTOKENSIZE=REQUIRE in IGDSMSxx member of
PARMLIB. Restrictions on opening large format data sets. 0 means
BLOCKTOKENSIZE=NOREQUIRE.
BLDL START= and STOP= parameters are supported.
System default USEEAV setting for an extended address volume
(EAV) when SMS is not active. Initially set on, to allow the use of
EAV, and changed to the IGDSMSxx PARMLIB specified or defaulted
USEEAV value if SMS is active.
SAM_USE_HPF, On = yes
Note: If DFASAMHPF is set but ZHPF=YES in IECIOSxx is not in effect, BAM will not use zHPF.
USS PIPES LBI support
Control Blocks
Table 97. DFA Fields (continued)
Offset Type/Value Length Name Description
13(D)
.... ..1.
.... ...1
BITSTRING
1111 ....
1
DFAALVER
DFAALFOR
DFAFEAT6
DFACPSDB
VERSION LEVEL AT WHICH NEW TAPE LABELS WILL BE
WRITTEN. OFF: ANSI LABEL VERSION 3. ON: ANSI LABEL
VERSION 4.
DETERMINES WHETHER INSTALLATION ISO/ANSI VERSION
LEVEL IS FORCED
FEATURES BYTE 6
COPYSDB VALUE IN DEVSUPxx IN PARMLIB. SYSTEM LEVEL
DEFAULT FOR THE SDB OPTION OF IEBGENER AND OTHER
COPYING PROGRAMS. VAE CONSTANTS BELOW DFACPS**
COPYSDB = NO
COPYSDB = YES
0001 ....
0010 ....
0010 ....
0011 ....
0100 ....
.... 1...
DFACPSNO
DFACPSYE
DFACPSSM
DFACPSIN
DFACPSLA
DFADCMET
COPYSDB = SMALL (SAME AS COPYSDB = YES)
COPYSDB = INPUT
COPYSDB = LARGE
Data class media enforced for all tapes outside of libraries
(ENFORCE_DC_MEDIA=ALMEDIATY)
.... .1..
.... ..1.
DFADCMEJ
DFAMTLAM
Data class media enforced for IBM 3592 outside of libraries
(ENFORCE_DC_MEDIA=MEDIA5PLUS)
When no media preference is expressed, accept all media types for a manual tape library (MTL_NO_DC_WORM_OK)
STOW supports the IFF operand
14(E)
.... ...1
UNSIGNED 2
DFASTIFF
DFABPV System default break point value (BPV) for an extended address volume (EAV) when the BPV is not specified in the SMS IGDSMSxx
PARMLIB or when SMS is not active. Initially set to 10 and changed to the IGDSMSxx SPECIFIED BPV value if SMS is active.
PRODUCT, VERSION, RELEASE, AND MODIFICATION LEVEL INFORMATION. BYTE 0 DEFINES A PRODUCT CODE, BYTES 1-3 DEFINE THE
VERSION, RELEASE, AND MODIFICATION LEVELS OF THIS PRODUCT. A PRODUCT BYTE (DFAPROD) OF X'00' INDICATES DFP AS A
PRODUCT, BYTES 1-3 OF DFARELS WILL ALSO BE X'00' IN THIS CASE. THE USER MAY CHOOSE TO CHECK DFAREL FOR THE RELEASE
LEVEL OF THE DFP PRODUCT IN THIS CASE. IF DFAPROD IS NOT EQUAL TO X'00', DFAREL SHOULD NOT BE CHECKED AS IT WILL BE
FROZEN AT THE LAST LEVEL OF DFP PRODUCT SHIPPED. A PRODUCT BYTE (DFAPROD) OF X'01' INDICATES DFSMS AS A PRODUCT BYTES
1-3 OF DFARELS WILL INDICATE THE VERSION, RELEASE AND MODIFICATION LEVELS OF THE DFSMS PRODUCT. A PRODUCT BYTE
(DFAPROD) OF X'02' INDICATES OS/390. THIS VALUE INDICATES THIS LEVEL OF DFSMS IS OS/390 EXCLUSIVE. SINCE DFSMS MIGHT NOT
BE REFRESHED WITH EACH OS/390 RELEASE, THE VERSION, RELEASE, AND MODIFICATION FIELDS INDICATE THE LEVEL OF OS/390 IN
WHICH THIS LEVEL OF DFSMS WAS FIRST SHIPPED. THE VERSION, RELEASE, AND MODIFICATION FIELDS ARE BINARY VALUES. (FOR
EXAMPLE TEN WOULD BE X'0A').
16(10)
16(10)
17(11)
18(12)
19(13)
20(14)
22(16)
23(17)
24(18)
28(1C)
32(20)
36(24)
40(28)
BITSTRING
BITSTRING
0000 0000
0000 0001
0000 0002
0000 0003
BITSTRING
BITSTRING
BITSTRING
SIGNED
UNSIGNED
1... ....
.1.. ....
..1. ....
...1 ....
.... 1...
.... .1..
.... ..11
UNSIGNED
ADDRESS
ADDRESS
ADDRESS
ADDRESS
ADDRESS
4
1
1
1
1
2
1
1
4
4
4
4
4
DFARELS
DFAPROD
DFADFP
DFADFSMS
DFAOS390
DFAZOS
DFAVER
DFARLSE
DFAMOD
DFAMSMDE
DFAVERBO
DFAMTPPRC
DFATVS
DFAFCXHS
DFASYMCF
DFAREJDEVGRP
DFAINCFC
*
DFASEFVR
DFACSSVT
DFADCVSO
DFADCVSD
DFADCVSC
DFAELNMP
4 BYTES = PRODUCT, VERSION, REL, MOD
PRODUCT BYTE
DFP PRODUCT CODE.
PRODUCT CODE FOR DFSMS.
PRODUCT CODE FOR OS/390 VERSION 2.
PRODUCT CODE FOR z/OS.
VERSION BYTE
RELEASE BYTE
MODIFICATION BYTE
MAXIMUM LENGTH OF THE SMDE IN THIS RELEASE WITH AN
8-BYTE ALIAS NAME
FLAGS
Multi-Target PPRC tvs flag
FlashCopy
® across Hyperswap enabled
Reserved: PPRC symmetrical configuration
SIO Exit Reject IO if
Multiple Incremental FlashCopy
Reserved
Data set format version for new sequential extended format data sets. This is set by the PS_EXT_VERSION keyword in the IGDSMSxx member of SYS1.PARMLIB.
CALLABLE SYSTEM SERVICES VECTOR TABLE ADDRESS
DATA CONVERSION SERVICES –OPEN.
DATA CONVERSION SERVICES –CONVERT.
DATA CONVERSION SERVICES –CLOSE.
Address of DFSMS element name. Name is mapped by DSECT
DFAELNM. See Table 98 on page 453. Valid only on z/OS 1.3 and
later.
Appendix A. Control Blocks
451
Control Blocks
Table 97. DFA Fields (continued)
Offset Type/Value Length Name Description
||
||||||
||||||
||||||
||||||
||||||
||||||
44(2C) ADDRESS 4 DFADFVAD DATA FACILITIES VECTOR TABLE ADDR
END OF DFA AS IT WAS WHEN IT WAS FIRST SHIPPED IN MVS/XA DFP VERSION 2 RELEASE 1 MODIFICATION LEVEL 0. PRIOR TO
REFERENCING ANY FIELD BEYOND THIS COMMENT, THE USER MUST ENSURE THAT DFARELS IS GREATER THAN OR EQUAL TO
X'02020A00' OR DFALEN IS BIG ENOUGH (SEE DFALEN).
48(30)
56(38)
INTEGER
BITSTRING
1... ....
.1.. ....
..1. ....
...1 ....
.... 1...
8
1
DFABLKSZ
DFAFEAT7
DFATADSN
DFATADS1
DFATARC8
DFATARC4
DFAXTBAM
LIMIT ON SYSTEM DETERMINED BLOCK SIZE. DEFAULT IS
32760. OBTAINED FROM DEVSUPxx PARMLIB MEMBER.
FEATURES BYTE 7
TAPEAUTHDSN=YES
TAPEAUTHF1=YES
TAPEAUTHRC8=WARN
TAPEAUTHRC4=FAIL
THE NON_VSAM_XTIOT OPTION OF THE DEVSUPxx MEMBER
OF PARMLIB HAS BEEN SET TO 'YES'.
TAPEMULTIVOLUMEERROR=ALLOW.
TAPEMULTIVOLUMEERROR=FAIL.
57(39)
.... .1..
.... ..1.
.... ...1
BITSTRING 1
DFATPMVA
DFATPMVF
DFA253
DFAFEAT8
SUBSYSTEMS SUPPORTED
FEATURES BYTE 8. The following 7 flags indicate VSAM and non-VSAM data set support for the Extended Addressing Space
(EAS) on an EAV.
THE FOLLOWING 8 FLAGS INDICATE VSAM AND NON-VSAM DATA SET SUPPORT FOR THE EXTENDED ADDRESSING SPACE (EAS) ON AN
EAV
1... ....
.1.. ....
DFAVSAMFOREAS
DFASEQFOREAS
VSAM enabled for EAS
Basic, large format sequential (QSAM, BSAM, BDAM access) enabled for EAS
58(3A)
60 (3C)
..1. ....
...1 ....
.... 1...
.... .1..
.... ..1.
.... ...1
Unsigned
Bit String
2
1
DFAPDSEFOREAS
DFAPDSFOREAS
DFADIRFOREAS
DFAEFSEQFOREAS
DFAUNDEFFOREAS
DFAEXPMSG
DFADDRSZ
DFAFEAT9
PDSE enabled for EAS
PDS enabled for EAS
Direct (BDAM access) enabled for EAS
Extended format sequential enabled for EAS
Undef DSORGs enabled for EAS
EXPIRATION_MESSAGE=NEVER
Storage size limit allowed in DDR swap (number of megabytes)
FEATURES BYTE 9
.... ..1.
.... ...1
1... ....
.1.. ....
DFABYPAUTH
DFAENCRYPT
DFAJ3AA
DFAMEMUX
61 (3D)
61 (3D)
61 (3E)
61 (3F)
64 (40)
64 (40)
68 (44)
72 (48)
73 (49)
74 (4A)
75 (4B)
76 (4C)
80 (50)
..1. ....
...1 ....
CHARACTER
Bit string
1... ....
.1.. ....
Bit string
Unsigned
Signed
Signed
Bit string
..1. ....
.... 1...
.... .1..
.... ..1.
.... ...1
Bit string
1... ....
Bit string
Bit string
Unsigned
1
3
1
1
8
4
4
4
4
1
8
1
1
4
32
DFAPDSEG
DFAZEDCCMP
DFADEVX1
DFAEOSV2
DFADDSFVOFF
DFADEVX2
DFA47S
DFA47MAX
DFA47CNT
DFAFEATC
DFAFCX_TTEDcw
DFAFCX_REL1
DFAFCX_ImbeddedLR
DFAFCX_FmtUpdWrt
DFAFCX_FmtWrite
DFAMAXGN
DCBE Bypass Authorization support is installed
DFSMS support for Data Set Encryption is installed
JES3_ALLOC_ASSIST=YES in DEVSUPxx
This level of the system supports IEBCOPY member selection user exits
PDSE Generation support is installed zEDC Compression support is installed
Reserved
Reserved
DEVSUPXX PARMLIB FLAG-1
Erase-On-Scratch PPRC Version 2
ICKDSF VERIFY OFFLINE support
DEVSUPXX PARMLIB FLAG-2
PRSDx47 counts (Use for QUERYFC)
Maximum PRSD47 so far
Current PRSDx47s count
HPF/FCX Feature Code bytes
Multi track operations supported
Transfer TCA Extension
FCX phase 1
Imbedded LR List
Format Update Writes
Second HPF feature code byte
Format Write Enable
Third HPF feature code byte
Fourth HPF feature code byte
Maximum number of generations allowed in a PDSE
Reserved
452
z/OS DFSMSdfp Advanced Services
Control Blocks
||||||
||||||
||||||
Table 97. DFA Fields (continued)
Offset Type/Value
80 (50) Unsigned
81 (51)
82 (52)
Bit string
1... ....
Length Name
1
1
DFACMPTYPE
DFACMPTYPEGEN
DFACMPTYPETLRD
DFACMPTYPEzEDCR
DFACMPTYPEzEDCP
DFAFEAT10
DFAROSEC
30
Description
Default compression type.
0 = Generic compression
1 = Tailored compression
2 = zEDC compression required
3 = zEDC compression prefered
Features byte 10
Read-Only Secondary support is installed on the system
Reserved.
Table 98. DFA Element Name
Offset Type/Value Length Name
0(0)
0(0)
2(2)
DSECT
UNSIGNED
CHARACTER
2
22
DFAELNM
DFAELNML
DFAEXTXT
Description
DSECT name
Length of significant characters in next field. Currently ten.
DFSMS element name in EBCDIC. May contain lower case characters. Currently is "z/OS DFSMS".
Appendix A. Control Blocks
453
Control Blocks
454
z/OS DFSMSdfp Advanced Services
Appendix B. Maintaining the System Image Library
This information describes how to maintain the system image library,
SYS1.IMAGELIB. SYS1.IMAGELIB is a partitioned data set (a PDSE is not supported) containing universal character set (UCS), forms control buffer (FCB), and printer control information for DFSMSdfp–supported IBM printers in the following forms, depending on the type of printer: v UCS images (also called modules) v UCS image tables v FCB images (also called modules) v
Control modules.
The system uses UCS images and image tables to relate a user-requested UCS to the corresponding print band/train. Most IBM standard UCS images are included in SYS1.IMAGELIB during system installation. Note that when you install a new release of DFSMS it replaces images that have the IBM-supplied names. If you modified or replaced any of these you might want to maintain a separate copy of them. The following table shows the standard character set images for the IBM
1403, 3203, and 3211 printers:
Printer
1403 or 3203
3211
Images
AN, HN, PCAN, PCHN, PN, QN, QNC, RN,
SN, TN, XN, YN
A11, G11, H11, P11, T11
For detailed, printer-specific information, or to determine which print bands/trains are available, see the publications listed in the following table:
Publication Title Contents
IBM 2821 Control Unit Component Description
Information on creating a user-designed chain/train for the 1403 Printer.
IBM 3203 Printer Component Description and
Operator's Guide
IBM 3211 Printer, 3216 Interchangeable Train
Cartridge, and 3811 Printer Control Unit
Component Description and Operator's Guide
Information on creating a user-designed train for the 3203 Printer.
Information on creating a user-designed train for the 3211 Printer.
IBM 3262 Model 5 Printer Product Description
Information on band IDs for the 3262 Model
5 Printer.
IBM 3800 Printing Subsystem Programmer's
Guide
Information on planning for, conversion to, and use of the IBM 3800 Model 1 Printing
Subsystem.
IBM 3800 Printing Subsystem Model 3
Programmer's Guide: Compatibility
Information on planning for, conversion to, and use of the IBM 3800 Model 3, 6, and 8
Printing Subsystem.
Information on band IDs for the 4245 Printer.
IBM 4245 Printer Model 1 Component
Description and Operator's Guide
IBM 4248 Printer Model 1 Description
IBM 6262 Printer Print Band Manual
Information on band IDs for the 4248 Printer.
Information on band IDs for the 6262 Printer.
© Copyright IBM Corp. 1979, 2017
455
Maintaining IMAGELIB
Publication Title
IBM 6262 Printer Model 014 User's Guide
Contents
Information on operating and maintaining the 6262 Model 14 Printer.
To use the information in this chapter, you should be familiar with the publications listed in the following table:
Publication Title Contents
z/OS DFSMS Macro Instructions for Data Sets
Describes the SETPRT macro. You can use it to specify the images (modules) that you want.
z/OS DFSMSdfp Utilities z/OS MVS JCL Reference
Describes the IEBIMAGE utility program.
Describes the CHARS, MODIFY, UCS, and
FCB parameters of the DD statement, that are processed at OPEN.
z/OS JES2 Initialization and Tuning Guide z/OS JES3 Initialization and Tuning Guide
Contains JES2 reference information.
Contains JES3 reference information.
Table 99 provides information about the printer-specific contents of
SYS1.IMAGELIB.
Table 99. SYS1.IMAGELIB Contents
Printer Type UCS Image UCS Image
Table
8
FCB Image
1403
3203
1
3211
3262 Model 5
2, 4, 5
4245
3
4248
3
6262 Model 14
2, 4, 5
3800
X
X
X
X
X
6
X
6
X
X
X
X
X
X
X
Control
Module
X
7
1.
The IBM 3203 Model 5 Printer is treated as a 3211 Printer by JES, except that the 3203 Model 5 does not support the 3211 indexing feature and ignores any indexing commands from JES. The 3203 Model 5 uses its own unique UCS images, but uses 3211 FCB images.
2.
You can operate this printer as if it were a 4248 operating in 4248 native mode.
In this case, use the 4248-related UCS sections of this chapter. The UCS information is contained in image tables.
3.
You can operate this printer in native mode, in which case the UCS information is contained in image tables. You can also operate these printers in 3211 compatibility mode, in which case the UCS information is contained in UCS images; you should then use the 3211-related UCS sections of this chapter.
4.
This printer uses the same image table as the 4248 printer. However, it does not support variable printer speeds or the horizontal copy feature and host stacker controls of the 4248 printer.
456
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
5.
This printer uses the same FCB image as the 4248 Printer.
6.
The image table is supplied by IBM. The contents of the 4245 image table are
shown in Table 100 on page 463. The contents of the 4248 image table are
shown in Table 101 on page 464.
7.
3800 Printing Subsystem control modules exist for: v Character arrangement tables v Graphics character modification tables v Copy modification tables v Library character sets v FCB images.
You can use the IEBIMAGE utility program to create and maintain these control modules. See z/OS DFSMSdfp Utilities for details about IEBIMAGE. IEBIMAGE and SYS1.IMAGELIB are not used when the printer is running in page mode.
In that case, PSF for z/O uses other types of modules from other libraries. See
3900 Product Description for more information.
8.
Figure 54 on page 463 defines and describes the structure of a UCS image table
entry.
UCS Images in SYS1.IMAGELIB
This information applies to the IBM 1403, 3203, and 3211 printers. SYS1.IMAGELIB
contains UCS images for these printers. You can use the assembler and linkage editor to add a UCS image to those that reside in SYS1.IMAGELIB. The assembler does not generate executable code. It merely prepares DC statements, and the linkage editor puts them into SYS1.IMAGELIB. Observe the following rules when creating a new UCS image:
1.
The member name must be 5 to 8 characters long; the first 4 characters must be the appropriate UCS prefix, as follows:
Prefix
UCS1
UCS2
UCS3
Meaning
1403 printer
3211 printer (or 3211-compatible printer)
3203 printer
These first four characters must be followed by a character set code, one to four characters long. Any valid combination of letters and numbers under assembler language rules is acceptable. However, do not use the single letters U or C, because they are symbols for special conditions recognized by the system.
Specify the assigned character set code on the DD statement or SETPRT macro to load the image into the UCS buffer.
You can supply an alias name for a new image with the ALIAS statement. (For more information on the ALIAS statement, see z/OS MVS Program Management:
User's Guide and Reference.)
2.
The first byte of the character set image load module specifies whether the image is a default. If a program issues an OPEN macro to a printer in which the UCS buffer has been loaded with a default image and the JCL does not specify a UCS name, the system uses the image in the buffer. If the buffer has not been loaded with a default image the system directs the operator to take action.
Specify the following in the first byte for JES2:
Value
X'00'
Meaning
Indicates that the image is not to be used as a default.
Appendix B. Maintaining the System Image Library
457
Maintaining IMAGELIB
Value
X'40'
X'80'
X'C0'
Meaning
Indicates that the output is to be folded.
Indicates a default image.
Indicates default image and folding.
For non-JES2, specify:
Value
X'00'
X'80'
Meaning
Indicates that the image is not to be used as a default.
Indicates a default image.
3.
The second byte of the load module indicates the number of lines (n) to be
printed for image verification. See “Verifying the UCS Image” on page 470 for
more information on image verification.
4.
Each byte of the next n bytes indicates the number of characters to be printed on each verification line. For the 3211 Printer, the maximum number of
characters printed per line is 48; the bytes of associative bits (see Rule 5, which
follows) do not print during verification.
5.
The UCS image itself must follow the previously described fields. The image must fill the number of bytes required by the printer; see the following table for image lengths. Note that, because of Assembler language syntax, you must code two apostrophes or two ampersands to represent a single apostrophe or a single ampersand, respectively, within a character set image.
Printer
1403
3203
3211
Image Length
240 bytes
304 bytes (240 characters followed by 64 bytes of associative bits)
512 bytes (432 characters followed by 15 bytes of X'00', 64 bytes of associative bits, and 1 reserved byte of X'00')
You must code associative bits to prevent data checks when adding a UCS image to SYS1.IMAGELIB. See the appropriate printer publication for more information on coding associative bits.
See the following information: v
“Examples of UCS Image Coding”
v
“UCS Image Alias Names” on page 462
v
“UCS Image Tables in SYS1.IMAGELIB” on page 462
v
“Alias Names in UCS Image Tables” on page 462
v
“Adding or Modifying a UCS Image Table Entry” on page 466
v
“Verifying the UCS Image” on page 470
Examples of UCS Image Coding
Figure 51 on page 459 shows an example of the JCL to add a 1403 UCS image, YN,
to SYS1.IMAGELIB. Notes, which apply to all examples, follow Figure 53 on page
458
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
//ADDYN
//STEP
JOB MSGLEVEL=1
EXEC PROC=ASMHCL,PARM.ASM=’NODECK,LOAD’,
// PARM.LKED=’LIST,OL,REFR,RENT,XREF’
//ASM.SYSIN DD *
UCS1YN CSECT
DC X’80’
DC AL1(6)
DC AL1(39)
DC AL1(42)
DC AL1(39)
DC AL1(39)
(THIS IS A DEFAULT IMAGE)
(NUMBER OF LINES TO BE PRINTED)
(39 CHARACTERS TO BE PRINTED ON LINE 1)
(42 CHARACTERS TO BE PRINTED ON LINE 2)
(39 CHARACTERS TO BE PRINTED ON LINE 3)
(39 CHARACTERS TO BE PRINTED ON LINE 4)
*
DC AL1(42)
DC AL1(39)
(42 CHARACTERS TO BE PRINTED ON LINE 5)
(39 CHARACTERS TO BE PRINTED ON LINE 6)
THE FOLLOWING SIX LINES REPRESENT THE TRAIN IMAGE
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.’
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.#-$’
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.’
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.’
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.#-$’
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.’
END
/*
//LKED.SYSLMOD DD DSNAME=SYS1.IMAGELIB(UCS1YN),DISP=OLD,
// SPACE= (OVERRIDE SECONDARY ALLOCATION)
Figure 51. Code to Add a 1403 UCS Image to SYS1.IMAGELIB
See Figure 53 on page 461 for the notes to this figure.
Figure 52 on page 460 shows an example of the JCL to add a 3203 UCS image, YN,
to SYS1.IMAGELIB. Notes to this figure follow Figure 53 on page 461.
Appendix B. Maintaining the System Image Library
459
Maintaining IMAGELIB
//ADYN3203 JOB MSGLEVEL=1
//STEP EXEC PROC=ASMHCL,PARM.ASM=’NODECK,LOAD’,
// PARM.LKED=’LIST,OL,REFR,RENT,XREF’
//ASM.SYSIN DD *
UCS3YN CSECT
DC X’80’
DC AL1(6)
DC AL1(39)
DC AL1(42)
DC AL1(39)
DC AL1(39)
(THIS IS A DEFAULT IMAGE)
(NUMBER OF LINES TO BE PRINTED)
(39 CHARACTERS TO BE PRINTED ON LINE 1)
(42 CHARACTERS TO BE PRINTED ON LINE 2)
(39 CHARACTERS TO BE PRINTED ON LINE 3)
(39 CHARACTERS TO BE PRINTED ON LINE 4)
*
DC AL1(42)
DC AL1(39)
(42 CHARACTERS TO BE PRINTED ON LINE 5)
(39 CHARACTERS TO BE PRINTED ON LINE 6)
THE FOLLOWING SIX LINES REPRESENT THE TRAIN IMAGE
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.’
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.#-$’
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.’
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.’
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.#-$’
*
*
DC C’1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.’
THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS,
UCSB BYTE POSITIONS 241-304
DC X’C01010101010101010100040000000000010’
DC X’101010101010101000404000000040001010’
DC X’101010101010004000000000101010101010’
DC X’10101010004000000000’
END
/*
//LKED.SYSLMOD DD DSNAME=SYS1.IMAGELIB(UCS3YN),DISP=OLD,
// SPACE= (OVERRIDE SECONDARY ALLOCATION)
Figure 52. Code to Add a 3203 UCS Image to SYS1.IMAGELIB
Notes:
See Figure 53 on page 461 for the notes to this figure.
Figure 53 on page 461 shows an example of the JCL to add a 3211 UCS image, A11,
to SYS1.IMAGELIB.
460
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
//ADDA11
//STEP
//
JOB MSGLEVEL=1
EXEC PROC=ASMHCL,PARM.ASM=’NODECK,LOAD’,
PARM.LKED=’LIST,OL,REFR,RENT,XREF’
//ASM.SYSIN DD *
UCS2A11 CSECT
DC
X’80’
DC
DC
AL1(9)
AL1(48)
DC
DC
AL1(48)
AL1(48)
DC
DC
AL1(48)
AL1(48)
DC
DC
DC
DC
AL1(48)
AL1(48)
AL1(48)
AL1(48)
(THIS IS A DEFAULT IMAGE)
(NUMBER OF LINES TO BE PRINTED)
(48 CHARACTERS TO BE PRINTED ON LINE 1)
(48 CHARACTERS TO BE PRINTED ON LINE 2)
(48 CHARACTERS TO BE PRINTED ON LINE 3)
(48 CHARACTERS TO BE PRINTED ON LINE 4)
(48 CHARACTERS TO BE PRINTED ON LINE 5)
(48 CHARACTERS TO BE PRINTED ON LINE 6)
(48 CHARACTERS TO BE PRINTED ON LINE 7)
(48 CHARACTERS TO BE PRINTED ON LINE 8)
(48 CHARACTERS TO BE PRINTED ON LINE 9)
*
*
THE FOLLOWING NINE LINES REPRESENT THE TRAIN IMAGE
NOTE 2 AMPERSANDS MUST BE CODED TO GET 1 IN ASSEMBLER SYNTAX
DC
DC
C’1<.+IHGFEDCBA*$-RQPONMLKJ%,&&ZYXWVUTS/@#098765432’
C’1<.+IHGFEDCBA*$-RQPONMLKJ%,&&ZYXWVUTS/@#098765432’
DC
DC
C’1<.+IHGFEDCBA*$-RQPONMLKJ%,&&ZYXWVUTS/@#098765432’
C’1<.+IHGFEDCBA*$-RQPONMLKJ%,&&ZYXWVUTS/@#098765432’
DC
C’1<.+IHGFEDCBA*$-RQPONMLKJ%,&&ZYXWVUTS/@#098765432’
DC
DC
C’1<.+IHGFEDCBA*$-RQPONMLKJ%,&&ZYXWVUTS/@#098765432’
C’1<.+IHGFEDCBA*$-RQPONMLKJ%,&&ZYXWVUTS/@#098765432’
DC
DC
C’1<.+IHGFEDCBA*$-RQPONMLKJ%,&&ZYXWVUTS/@#098765432’
C’1<.+IHGFEDCBA*$-RQPONMLKJ%,&&ZYXWVUTS/@#098765432’
DC
15X’00’ (RESERVED FIELD, BYTES 433-447)
THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS,
UCSB BYTE POSITIONS 448-5111
*
*
DC
DC
DC
DC
DC
END
X’C01010101010101010100040404240004010’
X’101010101010101000404041000040401010’
X’101010101010004040000000101010101010’
X’10101010004040444800’
X’00’ (RESERVED FIELD, BYTE 512)
/*
//LKED.SYSLMOD DD DSNAME=SYS1.IMAGELIB(UCS2A11”DISP=OLD,
// SPACE= (OVERRIDE SECONDARY ALLOCATION)
Figure 53. Sample Code to Add a 3211 UCS Image to SYS1.IMAGELIB
In the sample code in the Figure 51 on page 459, Figure 52 on page 460, and
Figure 53 be aware of the following:
v The RENT linkage editor attribute is required.
v For the 3203 and 3211 printers, to avoid data checks code the 64 bytes of associative bits. To determine how to code these bits for a particular image, see
IBM 3203 Printer Component Description and Operator's Guide or IBM 3211 Printer,
3216 Interchangeable Train Cartridge, and 3811 Printer Control Unit Component
Description and Operator's Guide.
v Executing the ASMHCL procedure does not generate executable code. The assembler/linkage editor merely places the UCS image into SYS1.IMAGELIB.
v The SPACE parameter is overridden here because the ASMHCL cataloged procedure has secondary allocation specified. You can specify use of the original secondary allocation amount by deleting the override.
Appendix B. Maintaining the System Image Library
461
Maintaining IMAGELIB
UCS Image Alias Names
Alias names are provided for many of the IBM-supplied print bands and trains.
For example, if the data set were printed on a 3211, a request for the 1403 TN train would assign the T11 train. The assigned alias names that follow the naming conventions currently used in SYS1.IMAGELIB are:
Image Alias
UCS1AN
UCS1HN
UCS1PN
UCS1TN
UCS2A11
UCS2H11
UCS2P11
UCS2T11
UCS1A11
UCS1H11
UCS1P11
UCS1T11
UCS2AN
UCS2HN
UCS2PN, UCS2RN, UCS2QN
UCS2TN
The image and alias names are included in SYS1.IMAGELIB at system installation.
Some bands/trains, such as SN and G11, do not have aliases because neither has an equivalent band/train on the other printer. An installation can assign an alias, if it chooses. (For details about the ALIAS statement, see z/OS MVS Program
Management: User's Guide and Reference.) If you do not specify a name (or alias), you must specify an installation-defined SYSOUT class or a printer routing code to assign the data set to the correct printer. If JES is directed to print a data set on a printer for which the specified image does not exist, JES notifies the operator. The operator can then cause the data set to be printed with a valid band/train or redirect the data set to the proper printer. If an installation defines a new band/train, it can supply an alias name for it through the ALIAS statement when including the image in SYS1.IMAGELIB.
UCS Image Tables in SYS1.IMAGELIB
This section applies only to the IBM 3262 Model 5, 4245 , 4248, and 6262 Model 14 printers. SYS1.IMAGELIB does not contain UCS images for these printers, but, instead, contains image tables. If you are running the printer in 3211 compatibility mode, UCS information is contained in image tables. Use the 3211-related sections of this chapter. The UCS image for each band is stored within the printer and is automatically loaded into the UCS buffer when you turn on machine power or
install a new band. See Figure 54 on page 463 for the format of image table entries,
and “Adding or Modifying a UCS Image Table Entry” on page 466 for information
on how to add or modify an image table entry.
SYS1.IMAGELIB contains one UCS image table for each type of printer that supports image tables. An image table contains an entry for most installation-standard IBM-supplied bands. The 4245 image table is named UCS5.
The shared 4248, 3262 Model 5, and 6262 Model 14 image table is named UCS6.
Alias Names in UCS Image Tables
The image tables also define alias names for most installation-standard print bands used on the IBM 4245 and 4248 printers. The IBM-supplied image tables do not provide alias names for the IBM 3262 Model 5 or 6262 Model 14 printers.
462
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
Some print bands, such as SN and KA22, do not have alias names because there is no equivalent band on other printers. You can add an alias name by adding or
0 1-4 5-8 9 10 11 12-15 16 17
Length of description data 1
Lengths of verification lines
2
(VLENGTH); one byte per line
Number of verification lines 2
Description data
1
Reserved (set to zero)
Description offset (set to zero if omitted)
Verification offset (set to zero if omitted)
Flag byte: X’00’ - Non-default image
X’40’ - Fold image
X’80’ - Default image
X’C0’ - Fold image/Default
UCS Image name
UCS Image Name or Alias (1- to 4-character name, left-justified and padded to a 4-character length with blanks, if necessary)
Length of this entry
Figure 54. UCS Image Table Entry Format
1.
This field is optional. The description data field is of variable length, up to a maximum of 32 bytes.
2.
This field is optional for the 4245 Printer. For the 3262 Model 5, 4248, and 6262
Model 14, this field does not apply and is set to X'00'.
The contents of the UCS image table UCS5 (IGGUCS5 macro) for the 4245 Printer
Table 100. UCS5 Image Table Contents
Name
AN21
AN21
AN21
AN21
HN21
Alias
AN21
AN
A11
40E1
HN21
Default
YES
NO
NO
NO
NO
Description
Default UCS image
1403/3203 AN image
3211 A11 image
4248 40E1 image
Nondefault UCS image
Appendix B. Maintaining the System Image Library
463
Maintaining IMAGELIB
SN21
4201
TN21
TN
T11
4181
GN21
G11
41C1
RN21
RN
Alias
HN
H11
4101
PL21
PN
P11
4121
KA21
4041
KA22
FC21
4161
Table 100. UCS5 Image Table Contents (continued)
SN21
SN21
TN21
TN21
TN21
TN21
GN21
GN21
GN21
RN21
RN21
Name
HN21
HN21
HN21
PL21
PL21
PL21
PL21
KA21
KA21
KA22
FC21
FC21
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
Default
NO
NO
NO
Description
1403/3203 HN image
3211 H11 image
4248 4101 image
Nondefault UCS image
1403/3203 PN image
3211 P11 image
4248 4121 image
Nondefault UCS image
4248 4201 image
Nondefault UCS image
1403/3203 TN image
3211 T11 image
4248 4181 image
Nondefault UCS image
3211 G11 image
4248 41C1 image
Nondefault UCS image
1403/3203 RN image
Nondefault UCS image
4248 4041 image
Nondefault UCS image
Nondefault UCS image
4248 4161 image
The contents of the UCS image table UCS6 (IGGUCS6 macro), for the 4248 printer,
Table 101. UCS6 Image Table Contents
Name
40E1
40E1
40E1
40E1
4101
4101
4101
4101
41C1
41C1
41C1
4121
Alias
40E1
AN21
AN
A11
4101
HN21
HN
H11
41C1
GN21
G11
4121
Default
NO
NO
NO
NO
YES
NO
NO
NO
NO
NO
NO
NO
Description
Default UCS image
4245 AN21 image
1403/3203 AN image
3211 A11 image
Nondefault UCS image
4245 HN21 image
1403/3203 HN image
3211 H11 image
Nondefault UCS image
4245 GN21 image
3211 G11 image
Nondefault UCS image
464
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
Table 101. UCS6 Image Table Contents (continued)
4061
40C1
4161
4161
4201
4201
4041
4041
Name
4121
4121
4121
4181
4181
4181
4181
Alias
PL21
PN
P11
4181
TN21
TN
T11
4061
40C1
4161
FC21
4201
SN21
4041
KA21
Default
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
Description
4245 PL21 image
1403/3203 PN image
3211 P11 image
Nondefault UCS image
4245 TN21 image
1403/3203 TN image
3211 T11 image
Nondefault UCS image
Nondefault UCS image
Nondefault UCS image
4245 FC21 image
Nondefault UCS image
4245 SN21 image
Nondefault UCS image
4245 KA21 image
Tip:
The image tables for the 4245 and 4248 printers include USA and Canada band IDs only. To support other national band IDs, modify the UCS image table.
See Table 102 and “Adding or Modifying a UCS Image Table Entry” on page 466.
The 3262 Model 5 and 6262 Model 14 printers use the 4248 UCS image table,
UCS6. However, IBM does not provide band names or aliases for either the 3262
Model 5 or 6262 Model 14 printer. To use 3262 Model 5 or 6262 Model 14 UCS
images, add the names and aliases to UCS6. “Adding or Modifying a UCS Image
Table Entry” on page 466 describes how to add entries to the UCS image table. For
a list of the bands available for the 3262 Model 5, see Table 102. For a list of the
bands available for the 6262 Model 14, see IBM 6262 Printer Print Band Manual and
IBM 6262 Printer Model 014 User's Guide.
For Table 102, be aware of the following:
v You can define any 1- to 4-character name as aliases of the UCS6 Band names.
v xx designates switch settings that are ignored. Switch number 3 must be on if you are using a special order (RPQ) band.
v Note that bb here represents a space.
Table 102. 3262 Model 5 Print Bands
Character Set Name UCS6 Band Name 3262 Model 5 Band Image
Select Switch Settings
(positions 1-8)
U.S./International
48 char EBCDIC
63 char EBCDIC
64 char EBCDIC
96 char EBCDIC
48 char AON OCR
48 char BON OCR
00bb
01bb
02bb
03bb
04bb
05bb
xx00 0000
xx00 0001
xx00 0010
xx00 0011
xx00 0100
xx00 0101
Appendix B. Maintaining the System Image Library
465
Maintaining IMAGELIB
Table 102. 3262 Model 5 Print Bands (continued)
Character Set Name UCS6 Band Name 3262 Model 5 Band Image
Select Switch Settings
(positions 1-8)
Austria/Germany
52 char EBCDIC
63 char EBCDIC
64 char EBCDIC
96 char EBCDIC
52 char AON OCR
52 char BON OCR
Canada/French
116 char EBCDIC
Katakana
96 char EBCDIC
128 char EBCDIC
UINN
128 char U.S. text
WTNN
128 char World Trade text
06bb
07bb
08bb
09bb
0Abb
0Bbb
0Cbb
0Dbb
0Ebb
0Fbb
10bb
xx00 0110
xx00 0111
xx00 1000
xx00 1001
xx00 1010
xx00 1011
xx00 1100
xx00 1101
xx00 1110
xx00 1111
xx01 0000
Adding or Modifying a UCS Image Table Entry
To use a new UCS image name/alias with the 3262 Model 5, 4245, 4248, or 6262
Model 14 printers, add an entry for that image name/alias to the UCS image table.
Use the assembler to create the image table object module, then link-edit the object module into SYS1.IMAGELIB, as shown in the following procedure. Similarly, to specify other images as defaults or change the description on an old image, change the image table.
To build new UCS table entries, or to change the format of old entries, use the
following procedure. For examples of coding the IGGUCSIT macro, see Figure 55
on page 469 and Figure 56 on page 470.
1.
To build a new UCS image table entry issue the IGGUCSIT macro, as described in the following text. If you are updating the image table as shown in the following examples, the linkage editor builds a new entry at the start of the table, even if you intended to replace an existing entry. When the system subsequently uses the table, it encounters the new entry first, thus the old one is effectively replaced.
2.
Include the UCS image table source, using the IGGUCS5 or IGGUCS6 macro, both of which reside in SYS1.MODGEN.
3.
Assemble the image table module (UCS5 or UCS6).
4.
Link-edit the assembled module into SYS1.IMAGELIB.
Requirement:
The RENT linkage editor attribute is required.
The format of the IGGUCSIT macro is:
466
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
►► IGGUCSIT
LIST
MF= DSECT ,NAME=image_name
,ALIAS=image_alias
►
NO
,DEFAULT= YES
,DESCR=description
,DEVICE=
4245
4248
►
,VLENGTH=(n1,n2,...n) NO
,FOLD= YES
►◄
►
►
MF=LIST or DSECT
Specifies the form of the macro instruction.
LIST
Produces a UCS image table entry based on the information supplied in other IGGUCSIT parameters. If LIST is selected or allowed to default, the
NAME parameter must also be coded.
DSECT
Produces a DSECT for a single UCS image table entry, similar to the
sample entry shown in Figure 54 on page 463. If you code DSECT, all other
parameters of IGGUCSIT are ignored.
LIST is the default.
NAME=image_name
Specifies the one to four character UCS image name.
ALIAS=image_alias
Specifies a one to four character alias name for the UCS image. If ALIAS is not specified, the image name coded in the NAME parameter will be entered in the UCS image table.
Exception:
The 3262, 4248, and 6262 printers have no band IDs in common.
Because these devices all use the UCS6 image table, select a unique alias name for each of these printer types. The alias must not appear in the image table more than once.
DEFAULT=YES or NO
Indicates whether the new UCS image is to be used as a default value.
YES
Indicates that this UCS image is a default. Default images are used by the system for jobs that do not request a specific image.
NO
Indicates that this UCS image should not be used as a default.
If the DEFAULT parameter is not specified, the new UCS image is not used as a default.
DESCR=description
Specifies descriptive information about the new UCS image. description can be up to 32 EBCDIC or hexadecimal characters long. You cannot use EBCDIC and hexadecimal characters in combination.
Appendix B. Maintaining the System Image Library
467
Maintaining IMAGELIB
Descriptive information is placed in the header line of the verification display, following the real UCS image name. If you omit the DESCR parameter, no description appears in the display. For more information on the verification
display, see “Verifying the UCS Image” on page 470.
If VLENGTH is not specified for the 4245 Printer, the DESCR parameter is ignored.
DEVICE=4245 or 4248
Specifies the type of device for which an image table entry is to be created.
If you specify MF=LIST on the first invocation of the IGGUCSIT macro,
DEVICE defaults to 4245. The default for subsequent invocations is the printer type that you specified (or the default) on the first invocation. Table entries with different DEVICE specifications are not allowed.
For the 3262 Model 5 or 6262 Model 14 printers, DEVICE=4248 should be specified to create the appropriate form of the image table entry.
VLENGTH=(n1,n2,. . . n)
Specifies the lengths of each line in the UCS verification display. The length of each line must be specified separately, even if all lines are of the same length.
n1 is the length of print line 1; n2 is the length of print line 2; n is the length of the last print line. To display the complete image, the sum of the verification line lengths should equal 350.
For details on the verification report, see “Verifying the UCS Image” on page
The VLENGTH parameter is not valid for the 3262 Model 5, 4248, or 6262
Model 14 printers.
FOLD=YES or NO
Indicates whether the UCS image is to be folded.
YES
Indicates that the UCS image is to be folded. Allows printing only uppercase characters from either upper- or lowercase data codes. Folding continues until an UNFOLD command is received.
NO
Indicates that the UCS image is not to be folded. This is the default.
Adding to the UCS Image Table
In Figure 55 on page 469, the band name RPQ1 with description “RPQ BAND” is
added to UCS5. In the UCS verification display, 7 lines of 50 characters each are printed. Macro IGGUCS5 causes the UCS image table source (as distributed by
IBM) to be included in the table entry.
468
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
72
//UCS5 JOB . . .
// EXEC ASMHCL,
//
//
PARM.ASM=’NODECK,LOAD’,
PARM.LKED=’OL,RENT,REUS’
//SYSPRINT DD SYSOUT=A
//ASM.SYSIN DD *
UCS5
TITLE ’UPDATED UCS5 IMAGE TABLE’
CSECT
IGGUCSIT NAME=RPQ1,
VLENGTH=(50,50,50,50,50,50,50),
DESCR=’RPQ BAND’
IGGUCS5
END
/*
//LKED.SYSLMOD DD DSN=SYS1.IMAGELIB(UCS5),DISP=OLD,
// SPACE= (OVERRIDE SECONDARY ALLOCATION)
X
X
Figure 55. Adding a New Band ID to the 4245 UCS Image Table (UCS5)
When adding a new band ID to the 4245 UCS image table as shown in Figure 55,
be aware of the following: v The RENT linkage editor attribute is required.
v Executing the ASMHCL procedure does not generate executable code. The assembler/linkage editor places the updated UCS image table into
SYS1.IMAGELIB.
v The SPACE parameter is overridden here because the ASMHCL cataloged procedure has a secondary allocation specified. Eliminating the override causes the original secondary allocation amount to be used.
In Figure 56 on page 470 the band name 40E1 DEFAULT BAND has been added to
UCS6 and defined as a default band. An alias name, HN21, is also defined for band 40E1. Macro IGGUCS6 causes the UCS image table source (as distributed by
IBM) to be included in the table entry.
Appendix B. Maintaining the System Image Library
469
Maintaining IMAGELIB
72
//UCS6 JOB . . .
// EXEC ASMHCL,
//
//
PARM.ASM=’NODECK,LOAD’,
PARM.LKED=’OL,RENT,REUS’
//SYSLIB
//
UCS6
DD
DD DSN=SYS1.AMODGEN,DISP=SHR
//SYSPRINT DD SYSOUT=A
//ASM.SYSIN DD *
TITLE ’UPDATED UCS6 IMAGE TABLE’
CSECT
IGGUCSIT NAME=40E1,
DEVICE=4248,
ALIAS=HN21,
DEFAULT=YES,
DESCR=’40E1 DEFAULT BAND’
IGGUCS6
END
/*
//LKED.SYSLMOD DD DSN=SYS1.IMAGELIB(UCS6),DISP=OLD,
// SPACE= (OVERRIDE SECONDARY ALLOCATION)
X
X
X
X
Figure 56. Adding a New Default Entry to the 4248 UCS Image Table (UCS6).
For Figure 56, be aware of the following:
v This method creates a duplicate entry for 40E1 that becomes the first entry in the table. Because the table is searched sequentially, the new entry is always found before the old entry, thus replacing the old entry.
v
The RENT linkage editor attributes is required.
v Executing the ASMHCL procedure does not generate executable code. The assembler/linkage editor places the updated UCS image table into
SYS1.IMAGELIB.
v The SPACE parameter is overridden because the ASMHCL cataloged procedure has a secondary allocation specified. Eliminating the override causes the original secondary allocation amount to be used.
Verifying the UCS Image
For the 1403 (with the UCS feature), 3203, 3211, 3262 Model 5, 4245, 4248, and 6262
Model 14 printers, you can print the UCS image for visual verification using either of the following parameters: v In JCL: UCS=(character set code,,VERIFY) v In the SETPRT macro: UCS=(character set code,,V).
These parameters have no effect for SYSOUT data sets.
You can also use these parameters for the 3262 Model 5, 4248, and 6262 Model 14 printers. However, because the UCS image cannot be read directly from the 3262
Model 5, 4248, or 6262 Model 14, only the header information is printed. The verification display header appears on the printer as follows:
UCS IMAGE VERIFICATION image_id [,FOLD] [description]
image_id
A one to four character name of the UCS image.
description
The descriptive information supplied for this UCS image in the UCS image table.
470
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
For more information about the UCS VERIFY parameters, see z/OS MVS JCL
Reference and z/OS DFSMS Macro Instructions for Data Sets.
FCB Images in SYS1.IMAGELIB
Two standard FCB images, STD1 and STD2, are included in SYS1.IMAGELIB
during system installation. The names of these standard images begin with the characters “FCB2”. You can define FCB images whose names begin with “FCB4” for the 4248, 3262 Model 5, and 6262 Model 14 Printers. These printers can use both the “FCB2”-prefixed images (referred to as 3211 format FCBs) and the
“FCB4”-prefixed images. All other printers, except the 3800, can use only
“FCB2”-prefixed images.
This section describes how you can create or replace “FCB2”-prefixed images. z/OS
DFSMSdfp Utilities describes how you can use the IEBIMAGE utility program to create, update, or replace an “FCB4”-prefixed image for the 3262 Model 5, 4248, or
6262 Model 14 Printers. For details about the “FCB4”-prefixed images, see either
IBM 6262 Printer Model 014 Product Description or IBM 4248 Printer Model 1
Description.
The 3262 Model 5, 4245, 4248, and 6262 Model 14 printers each load a default FCB image into the buffer when they are powered on. The 3262 Model 5 default FCB image is an 11-inch form with 6 lines per inch, a Channel 1 on the third print line, and a Channel 12 on line 64. The 4245 default FCB image is an 11-inch form with 6 lines per inch and a Channel 1 on the first print line. The 4248 default FCB image is the last FCB image loaded. The 6262 Model 14 default FCB image is either the last FCB image loaded and saved or the default shipped with the printer.
STD1 sets line spacing at 6 lines per inch for an 8½ inch form; STD2 is a default
FCB image that sets line spacing at 6 lines per inch for an 11-inch form. Channels for both images are evenly spaced, with Channel 1 on the fourth line and Channel
9 on the last line. See Figure 57 on page 472 and Figure 58 on page 473 for the
format of the standard STD1 and STD2 images.
The standard FCB image for the 3800 Printing Subsystem, STD3, is included in
SYS1.IMAGELIB during system installation. All models of the 3800 use FCB images whose names begin with “FCB3”. Use the IEBIMAGE utility to create and modify
FCB modules for the 3800 Printing Subsystem.
Appendix B. Maintaining the System Image Library
471
Maintaining IMAGELIB
FCB2STD1 CSECT
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
END
X’80’
AL1(48)
X’000000’
X’01’
X’000000’
X’02’
X’000000’
X’03’
X’000000’
X’04’
X’000000’
X’05’
X’000000’
X’06’
X’000000’
X’07’
X’000000’
X’08’
X’000000’
X’0A’
X’000000’
X’0B’
X’000000’
X’0C’
X’000000’
X’19’
Figure 57. Format of the Standard STD1 FCB Image
DEFAULT
FCB IMAGE LENGTH = 48
LINE 1, 2, 3
LINE 4, CHANNEL 1
LINE 5, 6, 7
LINE 8, CHANNEL 2
LINE 9, 10, 11
LINE 12, CHANNEL 3
LINE 13, 14, 15
LINE 16, CHANNEL 4
LINE 17, 18, 19
LINE 20, CHANNEL 5
LINE 21, 22, 23
LINE 24, CHANNEL 6
LINE 25, 26, 27
LINE 28, CHANNEL 7
LINE 29, 30, 31
LINE 32, CHANNEL 8
LINE 33, 34, 35
LINE 36, CHANNEL 10
LINE 37, 38, 39
LINE 40, CHANNEL 11
LINE 41, 42, 43
LINE 44, CHANNEL 12
LINE 45, 46, 47
LINE 48, CHANNEL 9-END OF FCB IMAGE
472
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
FCB2STD2 CSECT
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
END
X’80’
AL1(66)
X’000000’
X’01’
X’0000000000’
X’02’
X’0000000000’
X’03’
X’0000000000’
X’04’
X’0000000000’
X’05’
X’0000000000’
X’06’
X’0000000000’
X’07’
X’0000000000’
X’08’
X’0000000000’
X’0A’
X’0000000000’
X’0B’
X’0000000000’
X’0C’
X’00’
X’19’
DEFAULT
FCB IMAGE LENGTH = 66
LINE 1, 2, 3
LINE 4, CHANNEL 1
LINE 5, 6, 7, 8, 9
LINE 10, CHANNEL 2
LINE 11, 12, 13, 14, 15
LINE 16, CHANNEL 3
LINE 17, 18, 19, 20, 21
LINE 22, CHANNEL 4
LINE 23, 24, 25, 26, 27
LINE 28, CHANNEL 5
LINE 29, 30, 31, 32, 33
LINE 34, CHANNEL 6
LINE 35, 36, 37, 38, 39
LINE 40, CHANNEL 7
LINE 41, 42, 43, 44, 45
LINE 46, CHANNEL 8
LINE 47, 48, 49, 50, 51
LINE 52, CHANNEL 10
LINE 53, 54, 55, 56, 57
LINE 58, CHANNEL 11
LINE 59, 60, 61, 62, 63
LINE 64, CHANNEL 12
LINE 65
LINE 66, CHANNEL 9-END OF FCB IMAGE
Figure 58. Format of the Standard STD2 FCB Image
See the following information: v
“Adding an FCB Image to the Image Library”
v
“Modifying an FCB Image” on page 475
Adding an FCB Image to the Image Library
You can add a 3211-format FCB image to those that reside in SYS1.IMAGELIB, using the assembler and linkage editor. No executable code is generated; the assembler prepares DCs, and the linkage editor links them into SYS1.IMAGELIB.
The new FCB image must be structured according to the following rules:
1.
The member name cannot exceed 8 bytes and must begin with the prefix FCB2.
The characters that follow identify the FCB image and are referred to as the image identifier (ID). Any combination of valid assembler language characters can be used, with the exception of a single 'C' or 'U', because these are used by the system to recognize special conditions. To load the image into the FCB buffer, the image identifier must be specified in the FCB keyword of a DD statement or in the SETPRT macro.
2.
The first byte of the FCB load module specifies whether the image is the default. (Default images are used by the system for jobs that do not request a specific image.) Specify the following in the first byte:
Value
X'80'
X'00'
Meaning
Indicates a default image
Indicates a nondefault image
Appendix B. Maintaining the System Image Library
473
Maintaining IMAGELIB
3.
The second byte of the load module indicates the number of bytes to be transferred to the control unit to load the FCB image. This count includes the byte, if used, for the print position indexing feature.
4.
The third byte of the load module (the first byte of the FCB image) is either the print position indexing byte, or the lines-per-inch byte. The print position indexing byte is optional and, when used, precedes the lines-per-inch byte. The
3203 Model 5, 3262 Model 5, 4245, 4248, and 6262 Model 14 printers accept and discard the index byte if it is present, because they do not support the indexing feature. A description of the print position indexing feature and its use can be found in the publication IBM 3211 Printer, 3216 Interchangeable Train Cartridge,
and 3811 Printer Control Unit Component Description and Operator's Guide.
The special index flag in the third byte contains X'80' plus a binary index value, from 1 to 32 (the default is 1). This index value sets the left margin: 1 indicates flush-left; any other value indicates a line indented the specified number of spaces.
The form image begins with the lines-per-inch (LPI) byte. The LPI byte defines the number of lines per inch (6 or 8) and also represents the first line of the page.
Value
X'1n'
X'0n'
Requirement:
Printers controlled by JES2 require a channel 1 identifier here.
Typically, the length of an FCB image is consistent with the length of the form it represents. For example, an 8½ inch form to be printed at 6 LPI has an FCB image that is 51 bytes long (8½ inches times 6 LPI).
The LPI byte appears as follows:
Meaning
Sets 8 LPI
Sets 6 LPI
5.
All remaining bytes (lines) must contain X'0n', except the last byte, which must be X'1n'. The letter n can be a hexadecimal value from 1 to C, representing a channel (one to 12), or it can be 0, which means no channel is indicated.
In Figure 59 on page 475, an FCB load module is assembled and added to
SYS1.IMAGELIB. The image defines a print density of 8 lines per inch on an
11-inch form, with a right shift of 15 line character positions (1½ inches).
474
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
//ADDFCB JOB MSGLEVEL=1
//STEP EXEC PROC=ASMHCL,PARM.ASM=’NODECK,LOAD’,
// PARM.LKED=’LIST,OL,REFR,RENT,XREF’
//ASM.SYSIN DD *
FCB2ID1 CSECT
*THIS EXAMPLE IS FOR A FORM LENGTH OF 11 INCHES WITH 8 LPI (88 LINES)
DC
DC
X’80’
AL1(89)
THIS IS A DEFAULT IMAGE
LENGTH OF FCB IMAGE AND INDEXING BYTE
DC
DC
DC
X’8F’
X’10’
XL4’0’
OFFSET 15 CHARACTERS TO THE RIGHT
8 LINES PER INCH-NO CHANNEL FOR LINE 1
4 LINES NO CHANNEL
DC
DC
DC
DC
DC
DC
DC
DC
X’01’
XL6’0’
X’02’
XL6’0’
X’03’
XL6’0’
X’04’
XL6’0’
CHANNEL 1 IN LINE 6
6 LINES NO CHANNEL
CHANNEL 2 IN LINE 13
6 LINES NO CHANNEL
CHANNEL 3 IN LINE 20
6 LINES NO CHANNEL
CHANNEL 4 IN LINE 27
6 LINES NO CHANNEL
DC
DC
DC
DC
DC
DC
DC
DC
X’05’
XL6’0’
X’06’
XL6’0’
X’07’
XL6’0’
X’08’
XL6’0’
CHANNEL 5 IN LINE 34
6 LINES NO CHANNEL
CHANNEL 6 IN LINE 41
6 LINES NO CHANNEL
CHANNEL 7 IN LINE 48
6 LINES NO CHANNEL
CHANNEL 8 IN LINE 55
6 LINES NO CHANNEL
DC
DC
DC
DC
X’09’
XL6’0’
X’0A’
XL6’0’
CHANNEL 9 IN LINE 62
6 LINES NO CHANNEL
CHANNEL 10 IN LINE 69
6 LINES NO CHANNEL
DC
DC
DC
DC
X’0B’
XL6’0’
X’0C’
XL4’0’
X’10’
CHANNEL 11 IN LINE 76
6 LINES NO CHANNEL
CHANNEL 12 IN LINE 83
4 LINES NO CHANNEL
POSITION 88 LAST LINE IN IMAGE DC
END
/*
//LKED.SYSLMOD DD DSNAME=SYS1.IMAGELIB(FCB2ID1),DISP=OLD,
// SPACE= (OVERRIDE SECONDARY ALLOCATION)
Figure 59. Sample Code to Assemble and Add an FCB Load Module to SYS1.IMAGELIB
For Figure 59, be aware of the following:
v
The RENT linkage editor attribute is required.
v Executing the ASMHCL procedure does not generate executable code. The assembler/linkage editor is used to place the FCB image into SYS1.IMAGELIB.
v The SPACE parameter is overridden here because the ASMHCL cataloged procedure has a secondary allocation specified. Eliminating the override causes the original secondary allocation amount to be used.
Modifying an FCB Image
To modify an FCB image in virtual storage before loading it into a forms control buffer, use the following sequence of macro instructions to read the FCB image into virtual storage.
1.
An IMGLIB macro instruction, along with the OPEN parameter.
2.
A BLDL macro instruction to determine if the FCB image is in the image library.
3.
A LOAD macro instruction to load the image into virtual storage.
Appendix B. Maintaining the System Image Library
475
Maintaining IMAGELIB
4.
After the image has been read in, issue the IMGLIB macro instruction with the
CLOSE. parameter and the address of the DCB built by the first IMGLIB macro.
A SETPRT macro instruction can be used to load the forms control buffer with the modified image. Printers other than the 3800 require the use of an FCB entry in an exit list, as described in z/OS DFSMS Using Data Sets.
The formats of the BLDL and SETPRT macros are given in z/OS DFSMS Macro
Instructions for Data Sets; the format of the LOAD macro is given in z/OS MVS
Programming: Assembler Services Guide and z/OS MVS Programming: Assembler
Services Reference ABE-HSP.
The format of the IMGLIB macro is:
►►
label
IMGLIB OPEN
CLOSE,addr
►◄
OPEN
Opens SYS1.IMAGELIB and specifies that a DCB is to be built for it. The address of the DCB is returned in register 1.
CLOSE
Closes SYS1.IMAGELIB.
addr
Specifies the RX-type address of a word that points to the DCB. If coded in the form (reg), the register in parentheses contains the address of the DCB, not the address of the word.
Return Codes from IMGLIB
Return codes from the IMGLIB macro with the OPEN parameter are as follows:
Return Code Meaning
0 (X'00')
4 (X'04')
8 (X'08')
12 (X'0C')
Operation successful.
Either the volume containing SYS1.IMAGELIB is not mounted or a required catalog volume is not mounted.
Either SYS1.IMAGELIB does not exist on the volume to which the catalog points, or SYS1.IMAGELIB is not cataloged.
An error occurred in reading the catalog or VTOC.
BLDL and LOAD are the only macros that can refer to the DCB built by the
IMGLIB macro.
JES Support for the 3211 Indexing Feature
JES2 supports the 3211 indexing feature in two ways: v Specification of the INDEX parameter on the /*OUTPUT card.
v The extended FCB image.
The system supplies two special FCBs: FCB26 for 6 lines per inch and FCB28 for 8 lines per inch (specified as FCB=6 and FCB=8, respectively). These FCBs contain a
476
z/OS DFSMSdfp Advanced Services
Maintaining IMAGELIB
channel 1 indication in position 1, a special index flag in the third byte, and the number of lines per inch in the fourth byte of the image.
The special index flag in the third byte of FCB26 and FCB28 contains X'80' plus a binary index value, in the range 1 to 32 (default=1). The index value sets the left margin (1 indicates flush-left; other values cause indentation of the print line by
N-1 positions).
If JES2 is to use any other FCB images, the images must specify channel 1 in position 1; otherwise, JES2 positions the forms in the printer incorrectly. (Because
STD1 and STD2 do not specify channel 1 in position 1, they must be modified for
JES2.)
If the third byte of any other FCB image (specifying the number of lines per inch) contains a data character other than X'80', JES2 uses that specification and supplies an index value of 1.
JES3 does not support the 3211 indexing feature, and any indexing commands from JES3 are ignored by the 3203 Model 5.
Appendix B. Maintaining the System Image Library
477
478
z/OS DFSMSdfp Advanced Services
Appendix C. Using the extended address volume (EAV) migration assistance tracker
The EAV migration assistance tracker can help you find programs that you might need to change if you want to support extended address volumes (EAV). The EAV migration assistance tracker is an extension of the console ID tracking facility. It helps you: v Identify select systems services by job and program name, where the invoking programs might require analysis for changes to use new services. The program calls are identified as informational instances for possible migration actions.
They are not considered errors, because the services return valid information.
v
Identify possible instances of improper use of returned information in programs, like parsing 28-bit cylinder numbers in output as 16-bit cylinder numbers. These instances are identified as warnings.
v Identify instances of programs that will either fail or run with an informational message if they run on an EAV. These are identified as programs in error. The migration assistance tracker flags programs with the following functions, when the target volume of the operation is non-EAV, and the function invoked did not specify the EADSCB=OK keyword:
– OBTAIN
– CVAFDIR
– CVAFSEQ
– CVAFDSM
– CVAFFILT
– CVAFVSM - Note that the CVAFVSM interface is an internal system function that is not documented externally for general use.
– OPEN of VTOC
– DCB OPEN of an EAS eligible data set
This allows the system programmer to identify programs in error by job and program name, without failing the programs. It also allows you to exclude programs that are not yet ready for evaluation.
Programs identified in this phase of migration assistance tracking will continue to fail if the system service is issued for an EAV if you do not specify the
EADSCB=OK keyword for them.
The EAV migration assistance tracker can be manipulated with the following commands: v The SETGTZ operator command, which is used to activate and deactivate the tracking facility.
v The DISPLAY GTZ[,STATUS] operator command, which is used to display the current status of the tracking facility.
v The DISPLAY GTZ,TRACKDATA operator command, which is used to display any recorded instances of violations.
v The GTZPRMxx dynamic parmlib member, which is used to list violations that have already been identified in order to prevent them from being recorded again.
See The generic tracker facility in z/OS MVS Diagnosis: Tools and Service Aids for more information.
© Copyright IBM Corp. 1979, 2017
479
EAV migration assistance tracker
The following describe the instances identified and recorded by the EAV migration assistance tracker: v
“Information conventions for the EAV migration assistance tracker”
v
“DFSMS instances tracked by the EAV migration assistance tracker” on page 481
Information conventions for the EAV migration assistance tracker
The information returned by the EAV migration assistance tracker describes the occurrence of an instance in text. Like the console ID tracking facility, the EAV migration assistance tracker returns tracking information and a tracking value. The tracking information can be from 1 to 28 characters in length and the system can set any EBCDIC value. The tracking value is four bytes of binary data associated with this instance. For DFSMS, these values include data to associate an instance to a specific DFSMS function and to define the reason for the instance being recorded.
This standard allows for maximum flexibility in defining exclusion records that apply to DFSMS records.
The conventions for the tracking information and tracking value for a DFSMS instance follow.
Tracking information
The tracking information for a DFSMS instance might look as follows:
'SMS-I:3 LSPACE MSG= '
It can be broken down into several parts:
1.
The first portion of the tracking information will be set to ‘SMS-’ to identify this as a DFSMS instance.
2.
Appended to this is an error category, of "E" for error, "W" for warning, or "I" for informational, followed by a colon.
3.
Appended to the colon is a numeric value that will identify the reason for the recorded instance. These values are v 1 - EAV migration: EADSCB=OK keyword was not specified on an invoking program where the target volume was non-EAV. The invoking program fails if the target volume is an EAV.
v The invoking program would fail if the target volume was an EAV. The following section of the tracking information indicates the error that would have occurred. This instance is recorded in the tracker as an error message.
v
2
- EAV migration. Formatted output display may contain 28-bit cylinder numbers. Program usage of these track addresses may need to be changed.
Use macro TRKADDR for the comparison and manipulation of 28-bit cylinder numbers. This instance is recorded in the tracker as a warning message.
v 3 - EAV migration. The new function is available on the invoking program.
The identified program may want to exploit the available new function. This instance is recorded in the tracker as an informational message.
4.
The remaining tracking information must be an EBCDIC value that describes the function executing when the tracker recorded the instance.
In the example above, the 'SMS-I:3 LSPACE MSG= ' tracking information describes a DFSMS instance as an informational instance where new function is available that the invoking program might want to exploit. The function running when the tracker recorded this instance was LSPACE MSG=.
480
z/OS DFSMSdfp Advanced Services
EAV migration assistance tracker
Tracking value
For DFSMS instances, the EAV migration assistance tracker sets the tracking value as follows: v The system sets the low order byte of the track value to the same numeric value that identifies the reason for the instance.
v The remaining high order 3-bytes are left for the function recording the tracked instance. These 3-bytes are optional. For example, these values could be set to return and reason codes or parameter list flags.
Note that the tracking value must be set to a non-zero value in order for the
SETCON TRACKING=ONWITHABEND to be applicable when an instance is recorded in the tracker. If the track value is 0 or 128 no ABEND will be issued when you specify tracking ONWITHABEND.
DFSMS instances tracked by the EAV migration assistance tracker
LSPACE (SVC 78)
An LSPACE request with the DATA=, MSG=, or EXPMSG= keywords was issued.
Additional data from track-managed space is available with the EXPDATA= and
XEXPMSG= keywords. When this instance occurs for any volume type, it will be recorded in the tracker as an informational message.
These five keywords are mutually exclusive.
LSPACE processing (IGC0007H) will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-I:3 LSPACE reqtype ' where, reqtype = DATA= or MSG= or EXPMSG=
TRPL_TRACK_DATA =
Byte 0-1
Set to zero, not used.
Byte 2
Set to the LSPACE parameter flag byte
BIT 2 ON INDICATES THAT LSPACE WITH THE DATA= KEYWORD WAS
SPECIFIED
BIT 3 ON INDICATES THAT LSPACE WITH THE MSG= KEYWORD WAS SPECIFIED
BIT 4 ON INDICATES THAT LSPACE WITH THE EXPMSG=KEYWORD WAS
SPECIFIED
Byte 3
Set to 03.
DFSMS Tracking category 3: EAV Migration. Informational Message. New function is available. Additional data from track-managed space is available with the EXPDATA= and XEXPMSG= keywords.
TRPL_VIOLATORS_ADDR =
SET TO THE RESUME PSW OF THE RB THAT ISSUED SVC 78. TRACKER CODE WILL
DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
15.00.00 SYSTEM1
15.00.00 SYSTEM1
STATUS=ON NUM=3 d opdata,tracking
CNZ1001I 15.00.00 TRACKING DISPLAY 631
MAX=1000 MEM=7T EXCL=0 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-I:3 LSPACE MSG= 5003 ALLOCAS IEFW21SD 4CE5C 11 1
SMS-I:3 LSPACE DATA=
SMS-I:3 LSPACE EXPMSG=
2003 VTDS0IS1 VTDS0IS2
8803 VTDS0IS1 VTDS0IS2
118
118
28
28
2
2
SMS-I:3 LSPACE MSG= 9003 *MASTER* IEE70110 52F6 01 46
----------------------------------------------------------------------
Appendix C. Using the extended address volume (EAV) migration assistance tracker
481
EAV migration assistance tracker
SAMPLE EXCLUSION LIST =
* Jobname Pgmname *
* Tracking Information Mask Mask Mask Comments (ignored) *
*----------------------------+--------+--------+----------------------+
|SMS-I:3 LSPACE*
|SMS-I:3 LSPACE*
|SMS-I:3 LSPACE*
|SMS-I:3 LSPACE*
|*MASTER*|IEE70110| I SMF CALLS TO LSPACE|
|ALLOCAS |IEFW21SD| VARY DEVICE OFFLINE
|* |VTDSOIS2| VTDSOIS2 PROG CALLS
|VTDSOIS1|* | VTDSOIS1 JOB CALLS
|
|
|
DEVTYPE (SVC 24)
A DEVTYPE request with DEVTAB or UCBLIST without INFOLIST, returns the number of cylinders on the volume. This is in a two-byte field at offset 8, which is too small if the volume has more than 65 520 cylinders. Consider using
INFO=DASD which returns the number of cylinders in a four-byte field. When
INFO=DASD is specified additional fields are now provided. They include (see mapping macro IHADVA):
*
*
DVAIXVLD BIT
DVACYLMG BIT
*
*
DVAEADSCB BIT
*
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.
DVAMCU 8-BIT UNSIGNED INTEGER
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.
DVALCYL 16-BIT UNSIGNED INTEGER
* 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.
*
*
*
*
*
*
*
DVAVIRSZ 16-BIT UNSIGNED INTEGER
* 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.
When this instance occurs for any volume type, it will be recorded in the tracker as an informational message.
482
z/OS DFSMSdfp Advanced Services
EAV migration assistance tracker
DEVTYPE processing (IGC0002D) will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-I:3 DEVTYPE '
TRPL_TRACK_DATA =
Byte 0-2
Set to zero, not used.
Byte 3
Set to 03.
DFSMS Tracking category 3: EAV Migration. Informational Message. New function is available. Additional data from DEVTYPE INFO=DASD invocation is available. See mapping macro IHADVA.
TRPL_VIOLATORS_ADDR =
SET TO THE RESUME PSW OF THE RB THAT ISSUED SVC 24. TRACKER CODE WILL
DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
15.00.00 SYSTEM1
15.00.00 SYSTEM1
STATUS=ON NUM=1 d opdata,tracking
CNZ1001I 15.00.00 TRACKING DISPLAY 631
MAX=1000 MEM=7T EXCL=0 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-I:3 DEVTYPE 03 DEVTJOB DEVTPROG 4CE5C 11 1
----------------------------------------------------------------------
SAMPLE EXCLUSION LIST =
* Jobname Pgmname *
* Tracking Information Mask Mask Mask Comments (ignored) *
*----------------------------+--------+--------+----------------------+
|SMS*DEVTYPE* |* |* | ALL DEVTYPE |
IDCAMS LISTDATA PINNED
An IDCAMS LISTDATA PINNED request was processed. The track addresses for the PINNED tracks may contain 28-bit cylinder numbers.
When this instance occurs for any volume type, it will be recorded in the tracker as a warning message.
IDCAMS LISTDATA PINNED processing (IDCSS05) will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-W:2 IDCAMS LISTDATA PINN'
TRPL_TRACK_DATA =
Byte 0-2
Set to zero, not used.
Byte 3
Set to 02.
DFSMS Tracking category 2: EAV Migration. Warning Message.
An IDCAMS LISTDATA PINNED request was processed.
The track addresses for the
PINNED tracks may contain 28-bit cylinder numbers.
TRPL_VIOLATORS_ADDR =
SET TO THE RESUME PSW OF THE PRB WITH A VALID POINTER (RBCDE1) TO
THE 'IDCAMS' CDNAME.
USE THE PREVIOUS RB (RBLINKB) IF THIS PRB
IS NOT THE FIRST RB.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM
NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
STATUS=ON,ABEND NUM=1 MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
Appendix C. Using the extended address volume (EAV) migration assistance tracker
483
EAV migration assistance tracker
SMS-W:2 IDCAMS LISTDATA PINN 02 LISTDATA IDCAMS E48E 28 4
SAMPLE EXCLUSION LIST =
*
* Tracking Information Mask
Jobname Pgmname
Mask Mask Comments (ignored)
*----------------------------+--------+--------+----------------------+
*
*
|SMS*LISTDATA PINNED* |* |IDCAMS | All IDCAMS PGM CALLS |
IEHLIST LISTVTOC
An IEHLIST LISTVTOC request was processed. Extent descriptors may contain cylinder addresses 65520 or larger. Free space descriptors may contain track addresses 982800 or larger and/or full cylinders 65520 or larger. The generated report will display the information in different columns as compared to reports generated on releases prior to z/OS V1.10.
When this instance occurs for any volume type, it will be recorded in the tracker as a warning message.
IEHLIST LISTVTOC processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-W:2 IEHLIST LISTVTOC '
TRPL_TRACK_DATA =
Byte 0-2
Set to zero, not used.
Byte 3
Set to 02.
DFSMS Tracking category 2: EAV Migration. Warning Message.
An IEHLIST LISTVTOC request was processed. Extent descriptors may contain cylinder addresses 65520 or larger.
Free space descriptors may contain track addresses 982800 or larger and/or full cylinders
65520 or larger.
The generated report will display the information in different columns as compared to reports generated on releases prior to z/OS V1.10.
TRPL_VIOLATORS_ADDR =
SET TO THE RESUME PSW OF THE PRB WITH A VALID POINTER (RBCDE1) TO THE 'IEHLIST' CDNAME.
USE THE PREVIOUS RB (RBLINKB) IF THIS PRB IS NOT THE FIRST RB.
TRACKER CODE WILL DETERMINE
JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
STATUS=ON,ABEND NUM=1 MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-W:2 IEHLIST LISTVTOC 02 LNKLST LNKLST 2A 29 2
SMS-W:2 IEHLIST LISTVTOC
SMS-W:2 IEHLIST LISTVTOC
02 LST004 IEHLIST 2304 29 1
02 LST004 IEHLIST 34A6 29 1
SAMPLE EXCLUSION LIST =
* Jobname Pgmname
* Tracking Information Mask Mask Mask Comments (ignored)
*----------------------------+--------+--------+----------------------+
| SMS*IEHLIST LISTVTOC |* |IEHLIST | IEHLIST PGM CALLS |
*
*
484
z/OS DFSMSdfp Advanced Services
EAV migration assistance tracker
IDCAMS DCOLLECT
An IDCAMS DCOLLECT request for 'V' (Volume Record Field) and 'VL' (SMS
Volume Definition Field) records was processed. Additional data for track-managed space was recorded.
When this instance occurs for any volume type, it will be recorded in the tracker an informational message.
IDCAMS DCOLLECT processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-I:3 IDCAMS DCOLLECT '
TRPL_TRACK_DATA =
Byte 0-2
Set to zero, not used.
Byte 3
Set to 03.
DFSMS Tracking category 3: EAV Migration. Informational Message. An
IDCAMS DCOLLECT request for ’V’ (Volume Record Field) and ’VL’ (SMS
Volume Definition Field) records was processed. Additional data for track-managed space was recorded.
TRPL_VIOLATORS_ADDR =
SET TO THE RESUME PSW OF THE PRB WITH A VALID POINTER (RBCDE1) TO THE
'IDCAMS' CDNAME.
USE THE PREVIOUS RB (RBLINKB) IF THIS PRB IS NOT THE
FIRST RB.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS
ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
STATUS=ON,ABEND NUM=1 MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-I:3 IDCAMS DCOLLECT 03 DCOLLECT IDCAMS xxx 28 4
SAMPLE EXCLUSION LIST =
* Jobname Pgmname *
* Tracking Information Mask Mask Mask Comments (ignored) *
*----------------------------+--------+--------+----------------------+
|SMS*DCOLLECT* |* |IDCAMS | IDCAMS DCOLLECT PGM |
IDCAMS LISTCAT
An IDCAMS LISTCAT request was processed that printed extent descriptors for one or more EAS eligible data set (VSAM in z/OS V1R10). The returned extent descriptors may contain 28-bit cylinder numbers.
When this instance occurs for any volume type, it will be recorded in the tracker as a warning message.
IDCAMS LISTCAT processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-W:2 IDCAMS LISTCAT '
TRPL_TRACK_DATA =
Byte 0-2
Set to zero, not used.
Appendix C. Using the extended address volume (EAV) migration assistance tracker
485
EAV migration assistance tracker
Byte 3
Set to 02.
DFSMS Tracking category 2: EAV Migration.
Warning Message.
An IDCAMS LISTCAT request was processed that printed extent descriptors for one or more EAS eligible data set (VSAM in z/OS V1R10).
The returned extent descriptors may contain 28-bit cylinder numbers.
This instance will be recorded for both EAS and non-EAS capable volumes.
Please note thatAMS Listcat output format may change as a result of service and new function support. IBM recommends applications processing
LISTCAT output be updated to obtain results directly from the Catalog
Search Interface (CSI). For more information on CSI, see z/OS DFSMS Managing Catalogs and HLASM Programmer’s Guide.
TRPL_VIOLATORS_ADDR =
SET TO THE RESUME PSW OF THE PRB WITH A VALID POINTER (RBCDE1) TO THE
'IDCAMS' CDNAME.
USE THE PREVIOUS RB (RBLINKB) IF THIS PRB IS NOT THE
FIRST RB.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS
ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1
STATUS=ON,ABEND NUM=1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-W:2 IDCAMS LISTCAT 02 LISTCAT IDCAMS xxx 28 4
SAMPLE EXCLUSION LIST =
* Jobname Pgmname
* Tracking Information Mask Mask Mask Comments (ignored)
*----------------------------+--------+--------+----------------------+
|SMS*IDCAMS LISTCAT |* |IDCAMS | IDCAMS LISTCAT PGM |
*
*
OBTAIN (SVC 27)
OBTAIN was issued with the search or seek option to a non-EAV volume. The caller did not specify with EADSCB=OK That it supports the extended attribute
DSCBs and the target data set is EAS eligible.
When this instance occurs for a non-EAV volume type, it will be recorded in the tracker as an error message.
OBTAIN processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-E:1 DADSM OBTAIN '
TRPL_TRACK_DATA =
Byte 0
Set to zero, not used.
Byte 1-2
Operation code.
X’C100’ SEARCH for DSNAME.
X’C080’ SEEK for track address.
Byte 3
Set to 01.
DFSMS Tracking category 1: EAV Migration. Error Message. DADSM
OBTAIN was issued with the search or seek option to a non-EAV volume. The caller did not specify with EADSCB=OK That it supports the extended attribute DSCBs and the target data set is 'EAS eligible'.
486
z/OS DFSMSdfp Advanced Services
EAV migration assistance tracker
TRPL_VIOLATORS_ADDR =
SET TO THE RESUME PSW OF THE RB THAT ISSUED SVC 27.
TRACKER CODE WILL
DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
STATUS=ON,ABEND NUM=1 MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-E:1 DADSM OBTAIN C08001 OBTJBN OBTPGM xxx 28 4
SAMPLE EXCLUSION LIST =
* Jobname Pgmname *
* Tracking Information Mask Mask Mask Comments (ignored) *
*----------------------------+--------+--------+----------------------+
|SMS*OBTAIN* |* |* | DADSM OBTAIN |
CVAFDIR
CVAFDIR was issued with the search or seek option to a volume that does not support extended attribute DSCBs. The caller did not specify with EADSCB=OK
That it supports the extended attribute DSCBs and the target data set is ‘EAS eligible’. CVAF return code 4 and CVSTAT of X’52’ would have been set if issued to a volume that supports extended attribute DSCBs.
When this instance occurs for a volume that does not support extended attribute
DSCBs, it will be recorded in the tracker as an error message.
CVAFDIR processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-E:1 CVAFDIR STAT082 '
TRPL_TRACK_DATA =
Byte 0
Set to zero, not used.
Byte 1
CVAF Return Code = 4
Byte 2
CVAF Status Code = STAT082 (X'52')
Byte 3
Set to 01.
DFSMS Tracking category 1: EAV Migration. Error Message. CVAFDIR was issued with the search or seek option to a volume that does not support extended attribute DSCBs. The caller did not specify with
EADSCB=OK That it supports the extended attribute DSCBs and the target data set is 'EAS eligible'.
CVAF return code 4 and CVSTAT of
X'52' would have been set if issued to a device that supports extended attribute DSCBs.
TRPL_VIOLATORS_ADDR =
FOR BRANCH ENTRY CALLERS, SET TO THE CALLER OF CVAF RETURN ADDRESS.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
FOR SVC CALLS, SET TO THE RESUME PSW OF THE RB THAT ISSUED SVC 139.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
Appendix C. Using the extended address volume (EAV) migration assistance tracker
487
EAV migration assistance tracker
07.34.08 SYSTEM1
07.34.08 SYSTEM1
STATUS=ON,ABEND NUM=1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-E:1 CVAFDIR STAT082 045201 CVAFJBN CVAFPGM xxx 28 4
SAMPLE EXCLUSION LIST =
*
* Tracking Information Mask
Jobname Pgmname
Mask Mask Comments (ignored)
*----------------------------+--------+--------+----------------------+
|SMS*CVAFDIR STAT082* |* |* | CVAFDIR |
*
*
CVAFSEQ
CVAFSEQ was issued for physical sequential or index order to a volume that does not support extended attribute DSCBs. The caller did not specify with
EADSCB=OK That it supports the extended attribute DSCBs and the target data set is ‘EAS eligible’. CVAF return code 4 and CVSTAT of X’52’ would have been set if issued to a volume that supports extended attribute DSCBs.
When this instance occurs for a volume that does not support extended attribute
DSCBs, it will be recorded in the tracker as an error message.
CVAFSEQ processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-E:1 CVAFSEQ STAT082
TRPL_TRACK_DATA =
Byte 0
Set to zero, not used.
Byte 1
CVAF Return Code = 4
Byte 2
'
CVAF Status Code = STAT082 (X'52')
Byte 3
Set to 01.
DFSMS Tracking category 1: EAV Migration. Error Message. CVAFSEQ was issued for physical sequential or index order to a volume that does not support extended attribute DSCBs.
The caller did not specify with EADSCB=OK That it supports the extended attribute DSCBs and the target data set is 'EAS eligible'. CVAF return code 4 and CVSTAT of
X'52' would have been set if issued to a volume that supports extended attribute DSCBs.
TRPL_VIOLATORS_ADDR =
FOR BRANCH ENTRY CALLERS, SET TO THE CALLER OF CVAF RETURN ADDRESS.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
FOR SVC CALLS, SET TO THE RESUME PSW OF THE RB THAT ISSUED SVC 139.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1
STATUS=ON,ABEND NUM=1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-E:1 CVAFSEQ STAT082 045201 CVAFJBN CVAFPGM xxx 28 4
SAMPLE EXCLUSION LIST =
488
z/OS DFSMSdfp Advanced Services
EAV migration assistance tracker
*
* Tracking Information Mask
Jobname Pgmname
Mask Mask Comments (ignored)
*----------------------------+--------+--------+----------------------+
*
*
|SMS*CVAFSEQ STAT082* |* |* | CVAFSEQ |
CVAFDSM
CVAFDSM was issued to retrieve unallocated space on a volume that does not support extended attribute DSCBs. The caller did not specify with EADSCB=OK
That it supports the extended attribute DSCBs. CVAF return code 4 and CVSTAT of X’52’ would have been set if issued to a volume that supports extended attribute DSCBs.
When this instance occurs for a volume that does not support extended attribute
DSCBs, it will be recorded in the tracker as an error message.
CVAFDSM processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-E:1 CVAFDSM STAT082 '
TRPL_TRACK_DATA =
Byte 0
Set to zero, not used.
Byte 1
CVAF Return Code = 4
Byte 2
CVAF Status Code = STAT082 (X'52')
Byte 3
Set to 01.
DFSMS Tracking category 1: EAV Migration. Error Message. CVAFDSM was issued to retrieve unallocated space on a volume (CVAFDSM
ACCESS=MAPDATA, MAP=VOLUME, RTA4BYTE=YES) that does not support extended attribute DSCBs.
The caller did not specify with
EADSCB=OK That it supports the extended attribute DSCBs.
CVAF return code 4 and CVSTAT of X'52' would have been set if issued to a volume that supports extended attribute DSCBs.
CVAFVSM interface is an internal system function that is not documented externally for general use.
TRPL_VIOLATORS_ADDR =
FOR BRANCH ENTRY CALLERS, SET TO THE CALLER OF CVAF RETURN ADDRESS.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
FOR SVC CALLS, SET TO THE RESUME PSW OF THE RB THAT ISSUED SVC 139.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1
STATUS=ON,ABEND NUM=1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-E:1 CVAFDSM STAT082 045201 CVAFJBN CVAFPGM xxx 28 4
SAMPLE EXCLUSION LIST =
* Jobname Pgmname *
* Tracking Information Mask Mask Mask Comments (ignored) *
*----------------------------+--------+--------+----------------------+
|SMS*CVAFDSM STAT082* |* |* | CVAFDSM |
Appendix C. Using the extended address volume (EAV) migration assistance tracker
489
EAV migration assistance tracker
CVAFFILT
CVAFFILT was issued to obtain DSCB information for fully or partially qualified data set names on a volume that does not support extended attribute DSCBs. The caller did not specify with EADSCB=OK That it supports the extended attribute
DSCBs and the qualified data set is ‘EAS eligible’. CVAF return code 4 and
CVSTAT of X’56’ along with data set name status in the FCL (FCLDSNST) of X’06’ would have been set if the request was issued to a volume that supports extended attribute DSCBs.
When this instance occurs for a volume that does not support extended attribute
DSCBs, it will be recorded in the tracker as an error message.
CVAFFILT processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-E:1 CVAFFILT STAT086 '
TRPL_TRACK_DATA =
Byte 0
CVAF Return Code = 4
Byte 1
CVAF Status Code = STAT086 (X'56')
Byte 2
FCL data set status code = X'06'
Byte 3
Set to 01.
DFSMS Tracking category 1: EAV Migration. Error Message. CVAFFILT was issued to obtain DSCB information for fully or partially qualified data set names on a volume that does not support extended attribute DSCBs.
The caller did not specify with EADSCB=OK that is supports the extended attribute DSCBs and the qualified data set is
'EAS eligible'.
CVAF return code 4 and CVSTAT of X'56' along with data set name status in the FCL (FCLDSNST) of X'06' would have been set if the request was issued to a volume that supports extended attribute DSCBs.
TRPL_VIOLATORS_ADDR =
FOR BRANCH ENTRY CALLERS, SET TO THE CALLER OF CVAF RETURN ADDRESS.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
FOR SVC CALLS, SET TO THE RESUME PSW OF THE RB THAT ISSUED SVC 139.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1
STATUS=ON,ABEND NUM=1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-E:1 CVAFFILT STAT086 04560601 CVAFJBN CVAFPGM xxx 28 4
SAMPLE EXCLUSION LIST =
* Jobname Pgmname *
490
z/OS DFSMSdfp Advanced Services
EAV migration assistance tracker
* Tracking Information Mask Mask Mask Comments (ignored) *
*----------------------------+--------+--------+----------------------+
|SMS*CVAFFILT STAT086* |* |* | CVAFFILT |
CVAFVSM
CVAFVSM was issued to allocate space for a volume that is not an EAV. The caller did not specify with EADSCB=OK That it supports an EAV. CVAF return code 4 and CVSTAT of X’52’ would have been set if issued to an EAV.
When this instance occurs for a non EAV, it will be recorded in the tracker as an error message.
Note that the CVAFVSM interface is an internal system function that is not documented externally for general use.
CVAFVSM processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-E:1 CVAFVSM STAT082 '
TRPL_TRACK_DATA =
Byte 0
Set to zero, not used.
Byte 1
CVAF Return Code = 4
Byte 2
CVAF Status Code = STAT082 (X'52')
Byte 3
Set to 01.
DFSMS Tracking category 1: EAV Migration. Error message. CVAFVSM was issued to allocate space for a volume that is not an EAV. The caller did not specify with EADSCB=OK That it supports an EAV. CVAF return code 4 and CVSTAT of X'52' would have been set if issued to an EAV. CVAFVSM interface is an internal system function that is not documented externally for general use.
When this instance occurs for a non EAV, it will be recorded in the tracker as an error message.
TRPL_VIOLATORS_ADDR =
FOR BRANCH ENTRY CALLERS, SET TO THE CALLER OF CVAF RETURN ADDRESS.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
FOR SVC CALLS, SET TO THE RESUME PSW OF THE RB THAT ISSUED SVC 139.
TRACKER CODE WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1
STATUS=ON,ABEND NUM=1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-E:1 CVAFVSM STAT082 045201 CVAFJBN CVAFPGM xxx 28 4
SAMPLE EXCLUSION LIST =
* Jobname Pgmname *
Appendix C. Using the extended address volume (EAV) migration assistance tracker
491
EAV migration assistance tracker
* Tracking Information Mask Mask Mask Comments (ignored) *
*----------------------------+--------+--------+----------------------+
|SMS*CVAFVSM STAT085* |* |* | CVAFVSM |
DCB Open of a VTOC
A DCB Open of a VTOC was issued to a volume that does not support extended attribute DSCBs. The caller did not specify EADSCB=OK on the DCBE macro indicating that it supports the extended attribute DSCBs in the VTOC. Open would have issued an ABEND, MSGIEC142I 113-48 if an attempt was made to open the
VTOC of a volume that supported extended attribute DSCBs.
When this instance occurs for a volume that does not support extended attribute
DSCBs, it will be recorded in the tracker as an error message.
OPEN processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-E:1 DCB OPEN VTOC 113-48'
TRPL_TRACK_DATA =
Byte 0-2
Set to zero, not used.
Byte 3
Set to 01.
DFSMS Tracking category 1: EAV Migration. Error Message. A DCB Open of a VTOC was issued to a volume that does not support extended attribute DSCBs.
The caller did not specify EADSCB=OK on the
DCBE macro indicating that it supports the extended attribute DSCBs in the
VTOC.
Open would have issued an ABEND, MSGIEC142I 113-48 if an attempt was made to open the VTOC of a volume that supported extended attribute DSCBs.
TRPL_VIOLATORS_ADDR =
SET TO THE RESUME PSW OF THE RB THAT ISSUED THE OPEN SVC.
TRACKER CODE
WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
STATUS=ON,ABEND NUM=1 MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-E:1 DCB OPEN VTOC 113-48 01 OPENJBN OPENPGM xxx 28 4
SAMPLE EXCLUSION LIST =
* Jobname Pgmname *
* Tracking Information Mask Mask Mask Comments (ignored) *
*----------------------------+--------+--------+----------------------+
|SMS*DCB OPEN VTOC* |* |* | MSGIEC142I 113-48 |
DCB Open of EAS eligible data set
A DCB Open (MACRF = E for EXCP) of an EAS eligible data set was issued to a volume that does not support extended attribute DSCBs. The caller did not specify with EADSCB=OK on the DCBE macro to indicate that it supports the extended attribute DSCBs for an EAS eligible data set. Open would have issued an ABEND,
MSGIEC142I 113-44 if an attempt was made to open the EAS eligible data set on a volume that supported extended attribute DSCBs.
492
z/OS DFSMSdfp Advanced Services
EAV migration assistance tracker
When this instance occurs for a volume that does not support extended attribute
DSCBs, it will be recorded in the tracker as an error message.
OPEN processing will set the following tracking information:
TRPL_TRACK_INFO =
'SMS-E:1 DCB OPEN EAS 113-44'
TRPL_TRACK_DATA =
Byte 0-2
Set to zero, not used.
Byte 3
Set to 01.
DFSMS Tracking category 1: EAV Migration. Error Message.
A DCB Open (MACRF = E for EXCP) of an EAS eligible data set was issued to a volume that does not support extended attribute DSCBs. The caller did not specify with EADSCB=OK on the
DCBE macro to indicate that it supports the extended attribute
DSCBs for an EAS eligible data set. Open would have issued an ABEND, MSGIEC142I 113-44 if an attempt was made to open the
EAS eligible data set on a volume that supported extended attribute
DSCBs.
TRPL_VIOLATORS_ADDR =
SET TO THE RESUME PSW OF THE RB THAT ISSUED THE OPEN SVC.
TRACKER CODE
WILL DETERMINE JOB AND PROGRAM NAMES FROM THIS ADDRESS.
SAMPLE OUTPUT =
07.34.08 SYSTEM1
07.34.08 SYSTEM1
STATUS=ON,ABEND NUM=1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-E:1 DCB OPEN EAS 113-44 01 OPENJBN OPENPGM xxx 28 4
SAMPLE EXCLUSION LIST =
* Jobname Pgmname
* Tracking Information Mask Mask Mask Comments (ignored)
*----------------------------+--------+--------+----------------------+
|SMS*DCB OPEN VSAM* |* |* | MSGIEC142I 113-44 |
*
*
Other Sample exclusion list
SAMPLE EXCLUSION LIST =
* Jobname Pgmname *
* Tracking Information Mask Mask Mask Comments (ignored) *
*----------------------------+--------+--------+----------------------+
|SMS* |* |* | SMS all instances |
|SMS*E*
|SMS*W*
|SMS*I*
|SMS*:1*
|SMS*:2*
|SMS*:3*
|*
|*
|*
|*
|*
|*
|*
|*
|*
|*
|*
|*
| SMS Errors
| SMS Warnings
| SMS Informational
|
|
|
| EAV EADSCB=OK missing|
| EAV 28-bitcyls output|
| EAV new function |
Recommend exclusion list
For the recommended exclusion lists for DFSMS, see z/OS downloads
(www.ibm.com/systems/z/os/zos/downloads).
Appendix C. Using the extended address volume (EAV) migration assistance tracker
493
EAV migration assistance tracker
Summary of DFSMS instances
07.34.08 SYSTEM1
07.34.08 SYSTEM1 d opdata,tracking
CNZ1001I 07.34.08 TRACKING DISPLAY 673
STATUS=ON,ABEND NUM=1 MAX=1000 MEM=7T EXCL=5 REJECT=0
----TRACKING INFORMATION---- -VALUE-- JOBNAME PROGNAME+OFF-- ASID NUM
SMS-E:1 CVAFDIR STAT082 045201 CVAFJBN CVAFPGM 123 28 4
SMS-E:1 CVAFDSM STAT082
SMS-E:1 CVAFFILT STAT086
SMS-E:1 CVAFSEQ STAT082
SMS-E:1 CVAFVSM STAT082
045201 CVAFJBN
04560601 CVAFJBN
045201 CVAFJBN
045201 CVAFJBN
CVAFPGM
CVAFPGM
CVAFPGM
CVAFPGM
456
789
123
456
28
28
28
28
4
1
4
4
SMS-E:1 DADSM OBTAIN
SMS-E:1 DCB OPEN EAS 113-44
SMS-E:1 DCB OPEN VTOC 113-48
SMS-I:3 DEVTYPE
SMS-I:3 LSPACE MSG=
SMS-I:3 LSPACE DATA=
SMS-I:3 LSPACE EXPMSG=
SMS-I:3 IDCAMS DCOLLECT
SMS-W:2 IDCAMS LISTCAT
SMS-W:2 IDCAMS LISTDATA PINN
SMS-W:2 IEHLIST LISTVTOC
C08001 OBTJBN
01 OPENJBN
01 OPENJBN
OBTPGM
OPENPGM
OPENPGM
789 28 4
123 28 1
456 28 1
03 DEVTJOB DEVTPROG 4CE5C 11 1
5003 ALLOCAS IEFW21SD 4CE5C 11 1
2003 VTDS0IS1 VTDS0IS2 118 28 2
8803 VTDS0IS1 VTDS0IS2 118 28 2
03 DCOLLECT IDCAMS
02 LISTCAT IDCAMS
02 LISTDATA IDCAMS
02 LISTVTOC IEHLIST
123
456
E48E
123
28
28
28
28
4
4
4
4
494
z/OS DFSMSdfp Advanced Services
Appendix D. Accessibility
Accessible publications for this product are offered through IBM Knowledge
Center (www.ibm.com/support/knowledgecenter/SSLTBW/welcome).
If you experience difficulty with the accessibility of any z/OS information, send a detailed message to the Contact z/OS web page (www.ibm.com/systems/z/os/ zos/webqs.html) or use the following mailing address.
IBM Corporation
Attention: MHVRCFS Reader Comments
Department H6MA, Building 707
2455 South Road
Poughkeepsie, NY 12601-5400
United States
Accessibility features
Accessibility features help users who have physical disabilities such as restricted mobility or limited vision use software products successfully. The accessibility features in z/OS can help users do the following tasks: v Run assistive technology such as screen readers and screen magnifier software.
v Operate specific or equivalent features by using the keyboard.
v
Customize display attributes such as color, contrast, and font size.
Consult assistive technologies
Assistive technology products such as screen readers function with the user interfaces found in z/OS. Consult the product information for the specific assistive technology product that is used to access z/OS interfaces.
Keyboard navigation of the user interface
You can access z/OS user interfaces with TSO/E or ISPF. The following information describes how to use TSO/E and ISPF, including the use of keyboard shortcuts and function keys (PF keys). Each guide includes the default settings for the PF keys.
v
z/OS TSO/E Primer
v
z/OS TSO/E User's Guide
v
z/OS ISPF User's Guide Vol I
Dotted decimal syntax diagrams
Syntax diagrams are provided in dotted decimal format for users who access IBM
Knowledge Center with a screen reader. In dotted decimal format, each syntax element is written on a separate line. If two or more syntax elements are always present together (or always absent together), they can appear on the same line because they are considered a single compound syntax element.
Each line starts with a dotted decimal number; for example, 3 or 3.1 or 3.1.1. To hear these numbers correctly, make sure that the screen reader is set to read out
© Copyright IBM Corp. 1979, 2017
495
punctuation. All the syntax elements that have the same dotted decimal number
(for example, all the syntax elements that have the number 3.1) are mutually exclusive alternatives. If you hear the lines 3.1 USERID and 3.1 SYSTEMID, your syntax can include either USERID or SYSTEMID, but not both.
The dotted decimal numbering level denotes the level of nesting. For example, if a syntax element with dotted decimal number 3 is followed by a series of syntax elements with dotted decimal number 3.1, all the syntax elements numbered 3.1
are subordinate to the syntax element numbered 3.
Certain words and symbols are used next to the dotted decimal numbers to add information about the syntax elements. Occasionally, these words and symbols might occur at the beginning of the element itself. For ease of identification, if the word or symbol is a part of the syntax element, it is preceded by the backslash (\) character. The * symbol is placed next to a dotted decimal number to indicate that the syntax element repeats. For example, syntax element *FILE with dotted decimal number 3 is given the format 3 \* FILE. Format 3* FILE indicates that syntax element FILE repeats. Format 3* \* FILE indicates that syntax element * FILE repeats.
Characters such as commas, which are used to separate a string of syntax elements, are shown in the syntax just before the items they separate. These characters can appear on the same line as each item, or on a separate line with the same dotted decimal number as the relevant items. The line can also show another symbol to provide information about the syntax elements. For example, the lines
5.1*, 5.1 LASTRUN, and 5.1 DELETE mean that if you use more than one of the
LASTRUN and DELETE syntax elements, the elements must be separated by a comma.
If no separator is given, assume that you use a blank to separate each syntax element.
If a syntax element is preceded by the % symbol, it indicates a reference that is defined elsewhere. The string that follows the % symbol is the name of a syntax fragment rather than a literal. For example, the line 2.1 %OP1 means that you must refer to separate syntax fragment OP1.
The following symbols are used next to the dotted decimal numbers.
? indicates an optional syntax element
The question mark (?) symbol indicates an optional syntax element. A dotted decimal number followed by the question mark symbol (?) indicates that all the syntax elements with a corresponding dotted decimal number, and any subordinate syntax elements, are optional. If there is only one syntax element with a dotted decimal number, the ? symbol is displayed on the same line as the syntax element, (for example 5? NOTIFY). If there is more than one syntax element with a dotted decimal number, the ? symbol is displayed on a line by itself, followed by the syntax elements that are optional. For example, if you hear the lines 5 ?, 5 NOTIFY, and 5 UPDATE, you know that the syntax elements
NOTIFY and UPDATE are optional. That is, you can choose one or none of them.
The ? symbol is equivalent to a bypass line in a railroad diagram.
! indicates a default syntax element
The exclamation mark (!) symbol indicates a default syntax element. A dotted decimal number followed by the ! symbol and a syntax element indicate that the syntax element is the default option for all syntax elements that share the same dotted decimal number. Only one of the syntax elements that share the dotted decimal number can specify the ! symbol. For example, if you hear the lines 2? FILE, 2.1! (KEEP), and 2.1 (DELETE), you know that (KEEP) is the
496
z/OS DFSMSdfp Advanced Services
default option for the FILE keyword. In the example, if you include the FILE keyword, but do not specify an option, the default option KEEP is applied. A default option also applies to the next higher dotted decimal number. In this example, if the FILE keyword is omitted, the default FILE(KEEP) is used.
However, if you hear the lines 2? FILE, 2.1, 2.1.1! (KEEP), and 2.1.1
(DELETE) , the default option KEEP applies only to the next higher dotted decimal number, 2.1 (which does not have an associated keyword), and does not apply to 2? FILE. Nothing is used if the keyword FILE is omitted.
* indicates an optional syntax element that is repeatable
The asterisk or glyph (*) symbol indicates a syntax element that can be repeated zero or more times. A dotted decimal number followed by the * symbol indicates that this syntax element can be used zero or more times; that is, it is optional and can be repeated. For example, if you hear the line 5.1* data area
, you know that you can include one data area, more than one data area, or no data area. If you hear the lines 3* , 3 HOST, 3 STATE, you know that you can include HOST, STATE, both together, or nothing.
Notes:
1.
If a dotted decimal number has an asterisk (*) next to it and there is only one item with that dotted decimal number, you can repeat that same item more than once.
2.
If a dotted decimal number has an asterisk next to it and several items have that dotted decimal number, you can use more than one item from the list, but you cannot use the items more than once each. In the previous example, you can write HOST STATE, but you cannot write HOST HOST.
3.
The * symbol is equivalent to a loopback line in a railroad syntax diagram.
+ indicates a syntax element that must be included
The plus (+) symbol indicates a syntax element that must be included at least once. A dotted decimal number followed by the + symbol indicates that the syntax element must be included one or more times. That is, it must be included at least once and can be repeated. For example, if you hear the line
6.1+ data area
, you must include at least one data area. If you hear the lines
2+, 2 HOST, and 2 STATE
, you know that you must include HOST, STATE, or both. Similar to the * symbol, the + symbol can repeat a particular item if it is the only item with that dotted decimal number. The + symbol, like the * symbol, is equivalent to a loopback line in a railroad syntax diagram.
Appendix D. Accessibility
497
498
z/OS DFSMSdfp Advanced Services
Notices
This information was developed for products and services that are offered in the
USA or elsewhere.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
United States of America
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
© Copyright IBM Corp. 1979, 2017
499
This information could include missing, incorrect, or broken hyperlinks.
Hyperlinks are maintained in only the HTML plug-in output for the Knowledge
Centers. Use of hyperlinks in other output formats of this information is at your own risk.
Any references in this information to non-IBM websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM Corporation
Site Counsel
2455 South Road
Poughkeepsie, NY 12601-5400
USA
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
500
z/OS DFSMSdfp Advanced Services
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.
Terms and conditions for product documentation
Permissions for the use of these publications are granted subject to the following terms and conditions.
Applicability
These terms and conditions are in addition to any terms of use for the IBM website.
Personal use
You may reproduce these publications for your personal, noncommercial use provided that all proprietary notices are preserved. You may not distribute, display or make derivative work of these publications, or any portion thereof, without the express consent of IBM.
Commercial use
You may reproduce, distribute and display these publications solely within your enterprise provided that all proprietary notices are preserved. You may not make derivative works of these publications, or reproduce, distribute or display these publications or any portion thereof outside your enterprise, without the express consent of IBM.
Rights
Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either express or implied, to the publications or any information, data, software or other intellectual property contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use of the publications is detrimental to its interest or, as determined by IBM, the above instructions are not being properly followed.
You may not download, export or re-export this information except in full compliance with all applicable laws and regulations, including all United States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE
PUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING
BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,
Notices
501
NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
IBM Online Privacy Statement
IBM Software products, including software as a service solutions, (“Software
Offerings”) may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user, or for other purposes. In many cases no personally identifiable information is collected by the Software Offerings. Some of our Software Offerings can help enable you to collect personally identifiable information. If this Software
Offering uses cookies to collect personally identifiable information, specific information about this offering’s use of cookies is set forth below.
Depending upon the configurations deployed, this Software Offering may use session cookies that collect each user’s name, email address, phone number, or other personally identifiable information for purposes of enhanced user usability and single sign-on configuration. These cookies can be disabled, but disabling them will also eliminate the functionality they enable.
If the configurations deployed for this Software Offering provide you as customer the ability to collect personally identifiable information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for notice and consent.
For more information about the use of various technologies, including cookies, for these purposes, see IBM’s Privacy Policy at ibm.com/privacy and IBM’s Online
Privacy Statement at ibm.com/privacy/details in the section entitled “Cookies,
Web Beacons and Other Technologies,” and the “IBM Software Products and
Software-as-a-Service Privacy Statement” at ibm.com/software/info/productprivacy.
Policy for unsupported hardware
Various z/OS elements, such as DFSMS, JES2, JES3, and MVS, contain code that supports specific hardware servers or devices. In some cases, this device-related element support remains in the product even after the hardware devices pass their announced End of Service date. z/OS may continue to service element code; however, it will not provide service related to unsupported hardware devices.
Software problems related to these devices will not be accepted for service, and current service activity will cease if a problem is determined to be associated with out-of-support devices. In such cases, fixes will not be issued.
Minimum supported hardware
The minimum supported hardware for z/OS releases identified in z/OS announcements can subsequently change when service for particular servers or devices is withdrawn. Likewise, the levels of other software products supported on a particular release of z/OS are subject to the service support lifecycle of those products. Therefore, z/OS and its product publications (for example, panels, samples, messages, and product documentation) can include references to hardware and software that is no longer supported.
v For information about software support lifecycle, see: IBM Lifecycle Support for z/OS (www.ibm.com/software/support/systemsz/lifecycle)
502
z/OS DFSMSdfp Advanced Services
v For information about currently-supported IBM hardware, contact your IBM representative.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available at Copyright and Trademark information (www.ibm.com/legal/copytrade.shtml).
Notices
503
504
z/OS DFSMSdfp Advanced Services
Index
Numerics
1403 printer
28-bit cylinder address
perform calculations on 317 perform conversions on 317
31-bit IDAW (indirect addressing word) 177
3203 Model 5 printer
3211 printer
3262 Model 5 printer
3480/3490 Magnetic Tape Subsystem
3800 Printing Subsystem
4245 printer
4248 printer
6262 Model 14 printer
64–bit IDAW (indirect addressing word) 177
AMCAP
AMODE value
requirement to match UCB address 78
APF (authorized program facility)
appendages
PCI (program controlled interruption) 227
SYS1.PARMLIB listing 224 work areas available 224
authorization
A
ABE appendage
accessibility 495 contact IBM 495 features 495
actual track address to relative track address conversion routine 234
alias
retrieving catalog information 161
allocation
retrieval area format 295 retrieval list format 295
© Copyright IBM Corp. 1979, 2017
B
bit
bit maps, allocated DSCBs, VIRs 19
block ID, high-speed cartridge tape positioning 301
BLOCKTOKENSIZE parameter
BPX1PCT
BPX1PCT (continued)
DisplayFSStats, using
buffer
data transfer rate with EXCP 202 installing 202
lists
operating system overhead 202 performance considerations with
BWO (backup-while-open) facility
C
callable service, IECTRKAD 359
callable services
data set attribute retrieval 345
data set backup-while-open support 347
DFSMSdfp share attribute retrieval 353
system level determination 342
CAMLST macro
cartridge tape
catalog entry
information retrieval
505
catalog (continued) management
information retrieval 157 macro functions 157
non-VSAM data sets
CATALOG macro
CCW (channel command word) 187
cfltm macro
ChangeBufferLimits command 413
channel
control check 229 data check 229
channel error
channel program ending status 192
channel program
channel error 192 invalid ending status 192
channel programs
EXCP
initiation and execution 185, 189
translating virtual addresses to central storage addresses 232
problem program
translation
CHE appendage
CLOSE macro
communication vector table (CVT) 232,
contact
control block
data facilities area (DFA) 449
DCBE (data control block extension) 207
506
z/OS DFSMSdfp Advanced Services control block (continued)
conversion actual track address to relative track address
relative track address to actual track address
procedure 232 register usage 232
sector value, RPS devices 236, 245
virtual channel program to real channel program 186
count information
CSW (channel status word) 149, 188
CVAF (common VTOC access facility)
filter service
macros
return codes
CVAFDIR macro
examples 82 parameters 76, 77, 82 return codes 82
CVAFDSM macro
parameters 95, 101 return codes 101
CVAFFILT macro
control block address resolution 102
filter criteria list
partially-qualified names, examples 107
CVAFSEQ macro
parameters 122, 126 return codes 126
CVAFTST macro
CVPL (CVAF parameter list)
CVSTAT
D
DADSM (direct access device space management) 44
CAMLST macro
NUMBERDSCB operand 40 reading by absolute device address 40
non-VSAM data sets, deleting 145
OBTAIN routine
NUMBERDSCB operand 40 reading by absolute device address 40
RENAME macro
DADSM (direct access device space management) (continued)
SCRATCH macro
DASD (direct access storage device)
block size 202 buffer allocation 202
password protected data sets 250
reading and writing to, with XDAP
track capacity calculations 307
volume
initializing 144 restoring from tape 144
DASD rotational positioning sensing 187
DASDVOL
data
class
data control block extension (DCBE)
Data Extent Block (see DEB) 443
data facilities area (DFA)
data set allocation
deleting
non-VSAM
renaming
data set that might be in use 152 password protection 152
WRITE protection mode indicator 152
data set (continued) security
space allocation, releasing 43
DCB (data control block)
fields 196 format after OPEN (EXCP) 196
macro instruction
parameters
DCBD mapping macro for EXCP 207
DDR (dynamic device reconfiguration)
repositioning tape data sets 199
DEB (data extent block)
validating with DEBCHK 259, 263
DEBCHK macro
return codes 263 specification 260, 263
DELETE
DEQ macro, tape volume demount facility 299
DESERV Exit
global exit 365 interaction between task and global exits 365
determining DFSMSdfp release level 342
DEVD
device
end error recovery procedures 189
DEVTYPE macro
output 276, 278 return, reason codes 278
DFA
DFSMSdfp callable services data set
DFSMSdfp share attribute retrieval 353
reason codes 354 return codes 354
system attribute call 342 system level determination 342
DFSMSdfp level determination 321, 342
DFSMSdfp share attribute retrieval 353
DFSMSdss
DisplayBufferLimits command 412
DisplayGlobalStats command 413
DSCB (data set control block) 4, 14
access
indexed 67 physical sequential 67
reading
by address 75 by data set name 37, 75
Index
507
DSCB (data set control block) (continued) reading (continued)
writing
by address 75 by data set name 75
DSN order, accessing DSNs, DSCBs 67
dynamic device reconfiguration 199
E
EADSCB operand
on CAMLST SEEK macro 40 on OBTAIN macro 37, 40
EAV
migration assistance tracker 479
ECB (event control block)
end-of-data-set
EOE (end-of-extent) appendage
EOV (end-of-volume)
end-of-data-set routine, user 193
error
I/O recovery procedures (EXCP) 189
VTOC or index
processing 141 recovery from system or user errors 141
examples
exception
EXCP (execute channel program)
508
z/OS DFSMSdfp Advanced Services
EXCP (execute channel program)
(continued)
device-end error recovery procedures 189
indirect addressing word requirements 177
initiation and execution 185, 189
macros
multivolume data set requirement 172
real
channel programs 186 storage 186
EXCP(VR)
executing your own channel programs 169
EXCPVR macro
expiration date, overriding 146, 147
extended format data set
cannot be used as PASSWORD data set 249
extent area
extents
F
FCB (forms control buffer) image
standard image STD1 471 standard image STD2 471 standard images 471
SYS1.IMAGELIB
function 471, 476 modifying image 475, 476
FCL (filter criteria list)
file system
format-1 DSCB
free space
G
GDS (generation data set)
generation name
absolute 159 relative 159 number 159
GET
GTF trace of CVAF processing 142
H
HFS
HFS file system
HFS files
high-speed cartridge tape positioning 301
I
I/O
requests
IDAL (indirect addressing list) 177
IDAW (indirect addressing word) 177
IDCAMS
programming interfaces for 421
IEBUPDTE program
SYS1.PARMLIB appendage listing 224
IEDB (input/output error data block)
IEZDEB
IGWABWO call statement
IGWARLS call statement
IGWASMS call statement
IGWASYS call statement
IGWLSHR call statement
IHADFA
image
image (continued)
library
table
entries, adding or modifying 466 object module 466
image tables
buffer
DSCB
system
volume
restoring 144 updating 144 volume update 144
indexing feature for 3211 474, 476
indirect
INFO form
INFOLIST parameter
intercept condition 229 interface control check 229
interruption handling procedures 189
IOB (input/output block)
fields used with EXCP 210, 211
IOBE (input/output block common extension)
requesting extended error information 191
J
JES (job entry subsystem)
JFCB (job file control block) xi
macros used with
modifying
K
keyboard
L
large block interface
large format data set
cannot be used as PASSWORD data set 249
level
library
FCB images 475 maintenance 475
printer control information 455
LOCATE macro
retrieving catalog information 158
data return area 35 expanded message return area 35
M
macro data management
macro, mapping
Index
509
macros system
macros, data management
CAMLST
CLOSE
EOV
OPEN
VTOC access
management class
mapping macros
messages
displaying on 3480/3490
510
z/OS DFSMSdfp Advanced Services migration assistance tracker
MODE
MSG
MSGDISP macro parameters
multivolume data set
N
name
navigation
non-VSAM data set
nonindexed VTOC
NOPWREAD protection-mode indicator 252
NOQUEUE operand
NOWRITE protection-mode indicator 252
NUMBERDSCB operand
on CAMLST SEEK macro 40 on OBTAIN macro 37, 40
O
OPEN macro
DEQ at demount facility, tape volumes 299
EXCP
dummy data set restriction 172 procedures performed 172
TYPE=J
OPENJ (OPEN, TYPE=J) macro 302
P
page fix
appendage 226 list processing 226
partially-qualified data set name
partitioned data set space
PARTREL macro
counter maintenance 251 data set concatenation 251 deleting protected data set 251
parameter list
protection
renaming protected data set 251
PASSWORD data set
requirements 249 restrictions on 249
PCI (program controlled interruption)
PDDIRQTY (number of directory blocks) 50
PDPRIQTY (primary space request in tracks) 50
PDSE (partitioned data set extended)
space
pfsctl
callable service (BPX1PCT) 411
posting completion code in ECB
printer bands
national band IDs 465 special order (RPQ) 465
character set images 455 control information 455
default image
print position indexing feature 473 specifying defaults 473
printers
programming interfaces
parameter list
protection
PURGE macro
specification 304 purge routines 304
PUT
PWREAD protection-mode indicator 252
PWWRITE protection-mode indicator 252
R
RACF (resource access control facility)
RACF (resource access control facility)
(continued)
RACF (resource access naming facility)
RDJFCB macro
DCB exit list entry
format
allocation retrieval area 295 allocation retrieval list 295
retrieving allocation information
use by authorized programs 291
REALLOC macro
reason codes
recommendation
record
REFORMAT REFVTOC command
register
conversion routines usage
relative
to actual track address conversion routine 232
release, determining level of 321
RENAME
RENAME macro
SMS-managed volumes 151 specification 151
renaming a data set
multivolume considerations 151
renaming a data set that might be in use 152
renaming a data set (continued)
specifying volumes affected 151
unrenamable data sets and UNIX files 152
RENT
requesting different levels of ERP processing 192
requesting extended error information 191
requirement
SMS-managed non-VSAM data set 147
Resource Access Control Facility xi
restriction
partially-qualified data set name 158
retrieving data set attributes 345
retrieving DFSMSdfp share attributes 353
return codes
CVAF VTOC index error message 141
OBTAIN macro
reading from VTOC by absolute device address 42
reading from VTOC by data set name 40
track address convert routine 234
track address convert routines 235
Index
511
rotational position sensing 266
RPS (rotational position sensing)
S
SCRATCH macro
scratching a data set 145, 150
sector address
conversion routine 236, 245 number (RPS device) 236, 245
sequential data set
share attributes, retrieval of
SIO (start I/O) appendage
EXCP (execute channel program) 225
SMF (System Management Facilities)
SMS (Storage Management Subsystem)
release level 342 status 342 version 342
VTOC
SMS-managed non-VSAM data set
space allocation
status codes
subsystem statistics
subsystem status
512
z/OS DFSMSdfp Advanced Services
SVCUPDTE 363 replacing SVC routine 363
switching volumes, password protection 251
syntax diagram
SYS1.IMAGELIB data set adding
maintaining 455, 476 modifying FCB image 475, 476
system
system level determination 342
T
tape
recording
volumes
password protected data sets 250
tape, cartridge
task level exit (DESERV) 364, 365
TEST=YES
tip
track
TRKADDR macro
ABSTOREL parameter 317 calculating relative track number with 317
COMPARE parameter 318 comparing two track addresses with 318
converting normalized track address into absolute track address with 321
converting relative track number to
28-bit cylinder address with 320
TRKADDR macro (continued)
EXTRACTCYL parameter 318 extracting 28-bit cylinder number with 318
extracting 4-bit track number with 319
EXTRACTTRK parameter 319 incrementing track address with 319
normalize cylinder number with 320
SETCYL parameter 320 setting cylinder number with 320
TRKCALC macro
for extended sequential d.s. 273
parameter list
creating 314 empty, in-line 314
initialization 313 remote 313 storage definition 313
TYPE operand
U
UCATDX
UCB (unit control block)
UCB parameter
requirement to match AMODE value 78
UCBLIST parameter
UCS (universal character set) image
UCS (universal character set) (continued) image table
image names 466 modifying entries 466 object module 466
system image library maintenance 455
unit
UPDATE
user interface
V
validating the DEB (DEBCHK) 259, 263
VCB (volume control block) 158
VERIFY
VIER (VTOC index entry record)
retaining in virtual storage 79
VIO data sets
virtual
IDAW (indirect addressing word) 177
VIXM (VTOC index map) bit maps
allocated DSCBs, VIRs 19 description 19
maps of allocated space
volume
copying (VTOC) 144 indexed VTOC 144
list entry
scratch status code 149, 154 secondary status code 149, 154
volume (continued)
switching
multivolume data sets 251, 292
volume serial in CAMLST
VPSM (VTOC pack space map)
allocated cylinders and tracks 19 description 19
VSAM (virtual storage access method)
VTOC (volume table of contents)
DSCB directly, with CVAFDIR 64
access macros
deleting
non-VSAM data sets 145 temporary VSAM data sets 145
DSCB
defining data sets 2 formats 2
index
rebuilding 17 record 17 relationship 17
VTOC (volume table of contents)
(continued)
index (continued)
reading
DSN order 121 physical sequential order 121
VTOC index
W
X
XDAP (execute direct access program)
control blocks
macros
Z
z/OS UNIX files
device characteristics information 273
Index
513
514
z/OS DFSMSdfp Advanced Services
IBM®
Product Number: 5650-ZOS
Printed in USA
SC23-6861-30
ডাউনলোড
পাবলিক লিঙ্ক আপডেট করা হয়েছে
আপনার চ্যাটের পাবলিক লিঙ্ক আপডেট করা হয়েছে। You may view and manage your chat links after registration here.
নথির পাবলিক লিঙ্ক
বিজ্ঞাপন
