File No. S360-20 Order No. GC28-6550-10 os Systems Reference Library IBM System/360 Operating System: I Data Management for System Programmers OS Release 21 This publication consists of self-contained chapters, each of which provides information on how to modify, extend, or implement the data I management capabilities of the IBM System/360 Operating System control program. It is designed primarily for system programmers responsible for maintaining, updating, and extending the operating system features. Topics: Catalog and VTOC Maintenance IECDSECT, IEFJFCBN, and IEFUCBOB Macro Instructions The EXCP Macro Instruction The XDAP Macro Instruction Implementing Data Set Protection Adding a UCS Image to the System Library Tenth Edition (March, 1972) This is a major revision of, and obsoletes, GC28-6550-9 and Technical Newsletter GN28-2494. Changes or additions to the text and illustrations are indicated by a vertical line to the left of the change. I This edition applies to release 21 of IBM System/360 Operating system, and to all subsequent releases until otherwise indicated in new editions or Technical Newsletters. Changes are continually made to the information herein; before using this publication in connection with the operation of IBM systems, consult the latest IBM System/360 and System/370 SRL Newsletter, Order No. GN20-0360, for th€ editions that are current and applicable. Requests for copies of IBM publications should be made to your IBM representative or to the branch office serving your locality. A form for readers' comments is provided at the back of this publication. If the fonn has been removed, comments may be addressed to IBM Corporation, Programming Publications, Department D78, Monterey and Cottle Roads, San Jose, California 95114. Comments become the property of IBM. ©Copyright International Business Machines Corporation 1966,1967,1968,1969,1970,1971,1972 Preface This publication consists of self-contained chapters, each of which provides system programmers with information on how to modify, extend, or implement the data management capabilities of the IBM System/360 Operating system control program. Although the information in one chapter is sometimes related to information in another, all chapters have been written as separate and complete units. It is assumed that users of this publication are thoroughly familiar with the design of the operating system and its features. such information can be obtained in IBM System/360 Operating System: Introduction, GC28-6534. Each chapter contains its own introductory section and list of prerequisite publications. This organization has been used to reduce cross-referencing and to facilitate the addition of new chapters. Preface 3 4 Data Management for system Programmers Contents I SUMMARY OF AMENDMENTS FOR GC28-6550-10 -- os RELEASE 21 •• 9 SUMMARY OF AMENDMENTS FOR GC28-6550-9 OS RELEASE 20.1 10 SUMMARY OF AMENDMENTS FOR GC28-6550-8 AS UPDATED BY GN28-2452 -- OS RELEASE 20 • • • '. • • '. • • •• '. • • • • • • • 11 MAINTAINING THE CATALOG AND THE VOLUME TABLE OF CONTENTS • 15 How to Read a Block From the Catalog • • • • • 16 -By Specifying the Name of a Data Set • . ... '.. 16 -By specifying the Name of a Generation Data Set • • • • •• 17 -By specifying a Name Using an Alias 18 -By specifying by TTR • • 18 How to Build an Index •• • •• • • • • • • 19 How to Build a Generation Index '. • • ,. ,. • 20 How to Delete an Index • • • • • • • • 20 How to Assign an Alias • • • • • • 21 How to Delete an Alias • • • • • • 21 How to Connect Control Volumes • • • • • • • • • • 22 How to Disconnect Control Volumes • • • • • • 22 How to Catalog a Data Set • • • • • 23 -When Index Levels Exist •• • • • • • • • • 23 -By Creating Required Index Levels • • • • • • • • • • • • • 24 How to Remove Data Set References From the Catalog • 24 -Uncatalog and Retain Index Levels • • • • • • • • • • • 24 -Uncatalog and Remove Index Levels • • • • • 25 How to Recatalog a Data Set • • • • • '. • • • • 25 How to Read a Data Set Control Block From the Volume Table of Contents • • • •• • • • • • • • 26 How to De lete a Data Set. •• '. • • • • • 27 How to Rename a Data Set • • ••• ••• • • • • 28 How to Share Space on a Volume Initialized. Under DOS • 29 Appendix A: Catalog Block Entries • 30 Control Entries. • •• • • • • • • 30 Pointer Entries. .. • • •• • • • • • 31 The Volume Control Block Contents • • • 33 Appendix B: Device Code Designations • • 34 IECDSECT, IEFJFCBN, AND IEFUCBOB MACRO INSTRUCTIONS • • • 35 IECDSECT Macro Instruction • • • • • 36 IECDSECT Macro Definition • • • • • 36 IEFUCBOB Macro Instruction • • • • • • • • • 41 IEFUCBOB Macro Definition • • • 41 IEFJFCBN Macro Instruction • 44 IEFJFCBN Macro Definition • • • • • • • 44 EXECUTE CHANNEL PROGRAM (EXCP) MACRO INSTRUCTION • 47 Use of EXCP in system and Problem Programs • 48 System Use of EXCP • • • • • • • • • • • • • • • • 49 Programmer Use of EXCP • 49 EXCP Requirements • • • • • • • • • .. 50 Channel Program • • • • • • 50 Control Blocks • •• • • • • • • 50 Channel Program Execution. • • • • • 51 Interruption Handling and Error Recovery Procedures • • 53 Appenda,ges •••••••• • • • • • • • • ,. • 54 Start Input/Output (SIO) Appendage • • •• • • • 56 Program Controlled Interruption (PCI) Appendage • 57 End-of-Extent Appendage • • • • • • • • • • • • • 57 Contents 5 Channel End Appendage •• • • • • • • • 57 Abnormal End Appendage • • • • • • • • 58 Block Multiplexer Channel Programming Notes • • • 59 EXCP Programming Specifications • • • • • • 61 Macro Instructions • • • • • • • • • • • 61 DCB -- Define Data Control Block for EXCP • • 61 OPEN -- Initialize Data Control Block. • 68 EXCP -- Execute Channel Program • • • • 69 EOV -- End of Volume • • • • • • • • • 69 CLOSE -- Restore Data Control Block • • 70 Control Block Fields • • • • • • 70 Input/Output Block Fields • • • • 70 Event Control Block Fields • 72 Data Extent Block Fields • • • • • 73 Appendix: RESTORE and PURGE Macro Instruction • 74 RESTORE Macro Instruction • • • • • • • • · 74 PURGE Macro Instruction •• • •• • • • • • 75 ATLAS -- Assign an Alternate Track and Copy Data From the Defective Track • • • . • . • • • • • • • • • • • • 80 ATLAS Macro Instruction • • • • • 80 Use of ATLAS •• • • • • • • • • 81 Operation of the ATLAS program ••••• • 82 Return Codes • • • • • 82 EXECUTE DIRECT ACCESS PROGRAM (XDAP) MACRO INSTRUCTION • 87 Requirements for Execution of Direct Access Program • 88 XDAP Programming Specifications • • • • •• • 89 The XDAP Control Block • • • • • 91 Event Control Block (ECB) • • • • • • • 91 Input/Output Block (lOB) • 92 I Direct Access Channel Program • 92 XDAP Options • • • • • • • • • • • 93 Appendix: CVT Macro Instruction • 96 DATA SET PROTECTION •• • • • • • • ••• • • 97 Implementing Data Set Protection • • • • • 99 Password Data set Characteristics • •• • • • 99 Creating Protected Data Sets .100 Protection Feature Operating Characteristics .100 Using the PROTECT Macro Instruction to Maintain the Password Data Set . '. .101 Password Data Set Characteristics and Record Format When You Use the PROTECT Macro • • • • • • • • • • • • • • .102 Programming Conventions for the PROTECT Macro Instruction • • .103 PROTECT Macro Parameter Lists • •• • .103 Return Codes from the PROTECT Macro • .107 SYSTEM MACRO INSTRUCTIONS .109 System Macro Instructions in This Publication •• 110 Locate Device Characteristics (DEVTYPE) Macro Instruction • • • • • • 111 Device Characteristics Information • • • • .111 Output for Each Device Type • • • • • .113 Exceptional Returns • '. • • • • • • • .114 How to Read a Job File Control Block • • • • '. .115 OPEN -- Prepare the Data Control Block for Processing (S) .115 RDJFCB -- Read a Job File Control Block (S) • .116 Programming Notes • • • ••• • • • • • • • •••• 117 LABEL • .• • • '. • • • '. • • • • • • • .• • .119 Write Volume Sets (BSAM and QSAM -- Tape Only) .119 List Form •• .120 Execute Form ..120 6 Data Management for System Programmers ADDING A UNIVERSAL CHARACTER SET IMAGE OR FORMS CONTROL BUFFER IMAGE TO THE IMAGE LIBRARY. • • • • • • • • • • • • • • • • • .121 How to Add a UCS Image to the Image Library • • .. • • • •• • • .122 How to Add a Forms Control Buffer Image to the Image Library .125 INDEX • • • • • • • • • • • .. • • .127 Illustrations Figures Figure EXCP1. Data Control Block Format for EXCP (After OPEN) • 63 Figure EXCP2. Input/Output Block Format • • • • • • • • • • • • 71 Figure EXCP3. Event Control Block After Posting of Completion Code 73 Figure EXCP4. Error Locations and Return Codes if CCHH is in the Count Area Field • • • • • • • • • • • • • •••••••••• 84 Figure EXCP5. Error Locations and Return Codes if CCHHRKDD is in the Count Area Field .. • • • • • • • .. • • • • • • • • • • 85 Figure XDAP1. Event Control Block After Posting of Completion Code 91 Figure XDAP2. The XDAP Channel Programs ••••• • • 93 Figure PSWD1. Parameter List for Add Function •• 103 Figure PSWD2. Parameter List for Replace Function • • • • .105 Figure PSWD3. Parameter List for Delete Function •• 106 Figure PSWD4. Parameter List for List Function ••• 106 Figure PSWD5. Return Codes from the PROTECT Macro .107 Figure CTLG1. Catalog and VTOC Macro Instructions •• 129 Figure CTLG2. Return Codes of Catalog and VTOC Macro Instructions .131 Illustrations 7 8 Data Management for System Programmers Summary of Amendments for GC28-6550-10 OS Release 21 NEW DEVICE SUPPORT The Must Complete Function Job Queue Formatting Information is added to support the IBM The PRESRES Volume Characteristics 3803/3420 Magnetic Tape Subsystem and