GC33 5373 2_DOS_VS_Supervisor_and_IO_Macros_Rel_29_Nov73 2 DOS VS Supervisor And IO Macros Rel 29 Nov73
GC33-5373-2_DOS_VS_Supervisor_and_IO_Macros_Rel_29_Nov73 GC33-5373-2_DOS_VS_Supervisor_and_IO_Macros_Rel_29_Nov73
User Manual: GC33-5373-2_DOS_VS_Supervisor_and_IO_Macros_Rel_29_Nov73
Open the PDF directly: View PDF .
Page Count: 372
Download | |
Open PDF In Browser | View PDF |
GC33-5373-2 File No. 5370-30 Systems DOS/VS Supervisor and 1/0 Macros Release 29 Summary of Amendments This edition reflects the availability of virtual storage enhancements and support of the following new devices: System/370 Model 115 3203 and 5203 Printers 3340 Disk Storage 3540 Diskette I/O Unit 3780 Data Communication Terminal 5425 Multifunction Card Unit In addition, technical changes and editorial corrections have been made throughout the book. Changes in content are indicated by a vertical bar to the left of the change. Third Edition (November 1973) This is a major revision of, and obsoletes, GC33-5373-1. This edition applies to Version 5, Release 29, of the IBM Disk Operating System, DOS/VS, and all the subsequent versions and 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 Bibliography, GA22-6822, for the editions that are applicable and current. Requests for copies of IBM publications should be made to your IBM representative or to the IBM branch office serving your locality. Comments may be addressed to IBM Laboratory, Programming Publication Dept., P.O.Box 210,703 Boeblingen, Germany. Comments become the property of IBM. © Copyright International Business Machines Corporation 1972, 1973 IS THIS THE RIGHT BOOK FOR YOU? This book is intended as a reference for the programmer using DOS/VS macro instructions (macros). Both the DOS/VS Input/Output Control System (lOCS) macros and the DOS/VS supervisor macros are described. After a brief introduction to the use of macros, and a chapter on label processing, descriptions are given of the logical 10CS (LIOCS) macros for the access methods SAM, DAM, ISAM, and VSAM. Then follow descriptions of physical 10CS (PIOCS) macros, supervisor macros, multitasking macros, and program linkage macros. Those familiar with DOS Versions 3 or 4 (up to and including Release 27) may note that this book is based on DOS Supervisor & I/O Macros, GC24-5037, as modified by TNL GN33-8689 and by DOS Version 4, GC33-5007. This manual includes information on the macro support for the following DOS/VS features that were not part of Release 27: • VSAM macros As this book is intended for reference only, you should, before consulting it, be familiar with three others which introduce macro concepts and give important prerequisite information on macro usage: Introduction to DOS /VS, GC33-5770 DOS/VS Data Management Guide, GC33-5372 DOS/VS System Management Guide, GC33-5371 In addition, you should be familiar with the device manuals for those devices which you intend to use. Systems publications related to this one are listed below. IBM System/3 70 Principles of Operation, GA22-7000 virtual storage macros OS / VS and DOS / VS Assembler Language, GC33-4010 • changes to the program loading macros Guide to DOS / VS Assembler, GC33-4024 • modified and new interval timer macros DOS/VS System Control Statements, GC33-5376 • modified and new dump macros macro usage for I/O devices specific to Models 115 and 125 such as 5425 Multi-Function Card Unit and the 5203 Printer • macro usage for the IBM 3881 Optical Mark Reader and the IBM 3886 Optical Character Reader. macro usage for the IBM 3540 Diskette I/O Unit DOS/VS DASD Labels, GC33-5375 DOS/VS Tape Labels, GC33-5374 DOS/VS System Generation, GC33-5377 DOS/VS Serviceability Aids and Debugging Procedures, GC33-5380 Table of Contents Is this the right book for you? . . . . . . . . . . . . . . 3 Part 1. Introduction I 11 11 11 11 11 12 13 13 14 14 14 14 14 16 16 16 16 17 17 18 Reading a Tape Backwards . . . . . . . . . . . . Checking Standard Labels on Tape ....... Checking Nonstandard Labels on Tape .... Unlabeled Input Files on Tape . . . . . . . . . . 29 29 29 30 Part 2. Sequential Access Method Macro Types and Their Usage . . . . . . . . . . . . . Macro Definitions . . . . . . . . . . . . . . . . . . . . . Source-Program Macros . . . . . . . . . . . . . . . . Supervisor Macros . . . . . . . . . . . . . . . . . . IOCS Macros . . . . . . . . . . . . . . . . . . . . . . Macro Processing . . . . . . . . . . . . . . . . . . . . . DTF Declarative Macros . . . . . . . . . . . . . . . . Processing with SAM . . . . . . . . . . . . . . . . Processing with DAM . . . . . . . . . . . . . . . . Processing with ISAM . . . . . . . . . . . . . . . . Processing with PIOCS . . . . . . . . . . . . . . . Referencing the DTF Table .. . . . . . . . . . . Symbolic Unit Address in the DTFxx Macro Logic Module Generation Macros . . . . . . . . . . Providing the Logic Modules . . . . . . . . . . . Keeping Modules Small . . . . . . . . . . . . . . . Subsetting/Supersetting . . . . . . . . . . . . . . . Interrelationship of the Macros . . . . . . . . . . . . Module Names . . . . . . . . . . . . . . . . . . . . . Link-Editing Logical IOCS Programs ....... Program, DTF, and Logic Module Assembled Together . . . . . . . . . . . . . . . . . . . . . . . Program, DTF, and Logic Module Assembled Separately . . . . . . . . . . . . . . . . . . . . . . Using the Relocatable Library . . . . . . . . . . Self-Relocating Programs and IOCS . . . . . . . . Macro Format . . . . . . . . . . . . . . . . . . . . . . . Cards for Declarative Macros . . . . . . . . . . . Notational Conventions . . . . . . . . . . . . . . . Register Usage . . . . . . . . . . . . . . . . . . . . . 18 18 19 19 19 20 21 Declarative Macros . . . . . . . . . . . . . . . . . . . . 34 DTFCD Macro . . . . . . . . . . . . . . . . . . . . 34 CDMOD Macro . . . . . . . . . . . . . . . . . . . . 40 DTFCN Macro . . . . . . . . . . . . . . . . . . . . 42 DTFDI Macro . . . . . . . . . . . . . . . . . . . . . 44 DIMOD Macro . . . . . . . . . . . . . . . . . . . . 47 DTFDR Macro . . . . . . . . . . . . . . . . . . . . 48 DRMOD Macro . . . . . . . . . . . . . . . . . . . . 51 DFR Macro . . . . . . . . . . . . . . . . . . . . . . 52 DLINT Macro . . . . . . . . . . . . . . . . . . . . . 56 DTFDU Macro . . . . . . . . . . . . . . . . . . . . 58 DUMODFx Macro . . . . . . . . . . . . . . . . . . 62 DTFMR Macro . . . . . . . . . . . . . . . . . . . . 63 MRMOD Macro . . . . . . . . . . . . . . . . . . . 67 DTFMT Macro . . . . . . . . . . . . . . . . . . . 67 MTMOD Macro . . . . . . . . . . . . . . . . . . . 76 DTFOR Macro . . . . . . . . . . . . . . . . . . . . 78 ORMOD Macro . . . . . . . . . . . . . . . . . . . . 83 DTFPR Macro . . . . . . . . . . . . . . . . . . . . 84 PRMOD Macro . . . . . . . . . . . . . . . . . . . . 88 DTFPT Macro . . . . . . . . . . . . . . . . . . . . . 90 Paper Tape Processing Considerations . . . . . 94 PTMOD Macro . . . . . . . . . . . . . . . . . . . . 96 DTFSD Macro . . . . . . . . . . . . . . . . . . . . 98 SDMODxx Macro . . . . . . . . . . . . . . . . . 105 DTFSR Macro . . . . . . . . . . . . . . . . . . . 108 The DTFEN Card . . . . . . . . . . . . . . . . . 117 Label Processing . . . . . . . . . . . . . . . . . . . . . . DASD Standard Labels . . . . . . . . . . . . . . . . . OPEN and OPENR Macro Processing ..... End-of -Volume Processing . . . . . . . . . . . . . End-of-File Processing . . . . . . . . . . . . . . . User Standard Labels . . . . . . . . . . . . . . . . Diskette Labels . . . . . . . . . . . . . . . . . . . . . . OPEN and OPENR Macro Processing ..... End-of-Volume Processing . . . . . . . . . . . . . End-of-File Processing . . . . . . . . . . . . . . . Tape Labels . . . . . . . . . . . . . . . . . . . . . . . . . Tape Output Files . . . . . . . . . . . . . . . . . . . Tape Input Files . . . . . . . . . . . . . . . . . . . . 23 23 23 23 24 24 25 25 25 25 26 26 28 Imperative Macros . . . . . . . . . . . . . . . . . . .. Initialization Macros . . . . . . . . . . . . . . . . .. OPEN and OPENR Macros . . . . . . . . . . LBRET Macro . . . . . . . . . . . . . . . . . . . Processing Macros . . . . . . . . . . . . . . . . . . . GET Macro . . . . . . . . . . . . . . . . . . . . . . PUT Macro . . . . . . . . . . . . . . . . . . . . . . PUTR Macro . . . . . . . . . . . . . . . . . . . . . RELSE Macro . . . . . . . . . . . . . . . . . . . TRUNC Macro . . . . . . . . . . . . . . . . . . . CNTRL Macro . . . . . . . . . . . . . . . . . . . CHNG Macro . . . . . . . . . . . . . . . . . . . . ERET Macro . . . . . . . . . . . . . . . . . . . . . 18 124 124 124 127 ] 27 128 130 136 136 137 137 144 144 PRTOV Macro . . . . . . . . . . . . . . . . . . . READ Macro . . . . . . . . . . . . . . . . . . . . CHECK Macro . . . . . . . . . . . . . . . . . . . WAIT Macro . . . . . . . . . . . . . . . . . . . . . DISEN Macro . . . . . . . . . . . . . . . . . . . . LITE Macro . . . . . . . . . . . . . . . . . . . . . Optical Reader Macros-1287 .......... GET Macro . . . . . . . . . . . . . . . . . . . . . . CNTRL Macro . . . . . . . . . . . . . . . . . . . DSPLY Macro . . . . . . . . . . . . . . . . . . . , READ Macro . . . . . . . . . . . . . . . . . . . . RESCN Macro . . . . . . . . . . . . . . . . . . . RDLNE Macro . . . . . . . . . . . . . . . . . . . WAITF Macro . . . . . . . . . . . . . . . . . . . . Optical Character Reader Macros-3886 . .. READ Macro . . . . . . . . . . . . . . . . . . . . WAITF Macro . . . . . . . . . . . . . . . . . . . . CNTRL Macro . . . . . . . . . . . . . . . . . . . SETDEV Macro . . . . . . . . . . . . . . . . . . Work File Macros for Tape and Disk .... READ Macro . . . . . . . . . . . . . . . . . . . . WRITE Macro . . . . . . . . . . . . . . . . . . . CHECK Macro . . . . . . . . . . . . . . . . . . . NOTE Macro . . . . . . . . . . . . . . . . . . . . POINTR Macro . . . . . . . . . . . . . ...... POINTW Macro . . . . . . . . . . . . . . . . . . POINTS Macro . . . . . . . . . . . . . . . . . . . Completion Macros . . . . . . . . . . . . . . . .. FEOV Macro . . . . . . . . . . . . . . . . . . . . . FEOVD Macro . . . . . . . . . . . . . . . . . . . CLOSE and CLOSER Macros . . . . . . .. 144 145 145 146 146 146 147 147 147 147 148 148 149 149 149 149 150 150 150 150 151 151 152 152 152 153 153 154 154 155 155 Part 3. Direct Access Method Concepts of DAM . . . . . . . . . . . . . . . . . . . . Record Types . . . . . . . . . . . . . . . . . . . . . . . IOAREA Specification . . . . . . . . . . . . . . . . Reference Methods . . . . . . . . . . . . . . . . . .. Creating a File or Adding Records . . . . . . .. Data Area . . . . . . . . . . . . . . . . . . . . . . .. , Additional Information . . . . . . . . . . . . . . . . 159 159 159 161 162 164 164 Declarative Macros . . . . . . . . . . . . . . . . . . . 165 DTFDA Macro . . . . . . . . . . . . . . . . . . . 165 DAMOD Macro . . . . . . . . . . . . . . . . . . . 176 Imperative Macros . . . . . . . . . . . . . . . . . . .. Initialization Macros . . . . . . . . . . . . . . . . .. OPEN and OPENR Macro .......... LBRET Macro . . . . . . . . . . . . . . . . . . . Processing Macros . . . . . . . . . . . . . . . . . . . READ Macro . . . . . . . . . . . . . . . . . . . . WRITE Macro . . . . . . . . . . . . . . . . . . . WAITF Macro . . . . . . . . . . . . . . . . . . . . 179 179 179 180 180 181 181 183 CNTRL Macro . . . . . . . . . . . . . . . . . . . 183 Completion Macros . . . . . . . . . . . . . . . . . . 184 CLOSE and CLOSER Macros ........ 184 Part 4. Indexed Sequential Access Method Concepts of ISAM . . . . . . . . . . . . . . . . . . . Record Types . . . . . . . . . . . . . . . . . . . . . . . Storage Areas ....................... Organization of Records on DASD . . . . . . .. Indexes . . . . . . . . . . . . . . . . . . . . . . . .. Addition of Records and Overflow Areas . . . . . . . . . . . . . . . . . Programming Considerations . . . . . . . . . . Example of an ISAM File . . . . . . . . . . . . 187 187 187 187 189 190 191 192 Declarative Macros ...... . . . . . . . . . . . .. 194DTFIS Macro . . . . . . . . . . . . . . . . . . . . 194 ISMOD Macro . . . . . . . . . . . . . . . . . . . 201 Imperative Macros . . . . . . . . . . . . . . . . . . . . 205 Initialization Macros . . . . . . . . . . . . . . . . . . 205 OPEN and OPENR Macros . ......... 205 Processing Macros . . . . . . . . . . . . . . . . . . . 206 ERET Macro . . . . . . . . . . . . . . . . . . . . . 206 Loading or Extending a File . . . . . . . . . . . 207 WRITE Macro . . . . . . . . . . . . . . . . . . . 207 ENDFL Macro . . . . . . . . . . . . . . . . . . . 208 Adding Records to a File . . . . . . . . . . . . . 208 WRITE Macro . . . . . . . . . . . . . . . . . . . 208 Random Retrieval of Records . . . . . . . . . . 209 READ Macro . . . . . . . . . . . . . . . . . . . . 210 WRITE Macro . . . . . . . . . . . . . . . . . . . 210 WAITF Macro . . . . . . . . . . . . . . . . . . . . 210 Sequential Retrieval of Records ........ 211 SETL Macro . . . . . . . . . . . . . . . . . . . . . 211 GET Macro . . . . . . . . . . . . . . . . . . . . . . 212 ESETL Macro . . . . . . . . . . . . . . . . . . . . 213 Completion Macros . . . . . . . . . . . . . . . . . . 21 3 CLOSE and CLOSER Macros ........ 213 Part 5. Virtual Storage Access Method Concepts of VSAM . . . . . . . . . . . . . . . . . . . 217 Types of Processing . . . . . . . . . . . . . . . . 217 Types of Macros . . . . . . . . . . . . . . . . . . 218 Control Block Generating Macros ......... ACB Macro . . . . . . . . . . . . . . . . . . . . . EXLST Macro . . . . . . . . . . . . . . . . . . . . RPL Macro . . . . . . . . . . . . . . . . . . . . . . 220 220 222 224 Examples of ACB, EXLST, and RPL Macros . . . . . . . . . . . . . . . . . . . . . 226 Control Block Manipulating Macros . . . . . . . . GENCB Macro . . . . . . . . . . . . . . . . . . . MODCB Macro . . . . . . . . . . . . . . . . . . . SHOWCB Macro . . . . . . . . . . . . . . . . . . TESTCB Macro . . . . . . . . . . . . . . . . . . . 228 228 230 231 234 Opening and Closing FOes ............... OPEN Macro . . . . . . . . . . . . . . . . . . . . CLOSE Macro . . . . . . . . . . . . . . . . . . . TCLOSE Macro . . . . . . . . . . . . . . . . . . 239 239 240 241 Requesting Access to FOes .............. GET Macro . . . . . . . . . . . . . . . . . . . . . . PUT Macro . . . . . . . . . . . . . . . . . . . . . . POINT Macro . . . . . . . . . . . . . . . . . . . . ERASE Macro . . . . . . . . . . . . . . . . . . . ENDREQ Macro . . . . . . . . . . . . . . . . . . Return Codes for Request Macros ........ 242 242 242 243 243 243 243 Part 6. Physical IOCS Concepts of Physical IOCS . . . . . . . . . . . . . . Physical IOCS Macros . . . . . . . . . . . . . . . . . CCB Macro . . . . . . . . . . . . . . . . . . . . . EXCP Macro . . . . . . . . . . . . . . . . . . . . . WAIT Macro . . . . . . . . . . . . . . . . . . . . . DTFPH Macro . . . . . . . . . . . . . . . . . . . OPEN and OPENR Macros .......... LBRET Macro . . . . . . . . . . . . . . . . . . . FEOV Macro . . . . . . . . . . . . . . . . . . . . . SEOV Macro . . . . . . . . . . . . . . . . . . . . . CLOSE and CLOSER Macro ........ 249 249 249 253 254 254 257 259 260 260 260 Part 7. Supervisor, Multitasking, Program Linkage Supervisor Macros . . . . . . . . . . . . . . . . . . . . Program Loading .................... FETCH Macro . . . . . . . . . . . . . . . . . . . GENL Macro . . . . . . . . . . . . . . . . . . . . LOAD Macro . . . . . . . . . . . . . . . . . . . . Virtual Storage . . . . . . . . . . . . . . . . . . . . . . PFIX Macro . . . . . . . . . . . . . . . . . . . . . PFREE Macro . . . . . . . . . . . . . . . . . . . . RELPAG Macro . . . . . . . . . . . . . . . . . . FCEPGOUT Macro . . . . . . . . . . . . . . . . PAGEIN Macro . . . . . . . . . . . . . . . . . . . RUNMODE Macro . . . . . . . . . . . . . . . . SETPFA Macro . . . . . . . . . . . . . . . . . . . 265 265 265 266 266 266 267 268 268 269 270 271 271 VIRTAD Macro . . . . . . . . . . . . . . . . . . . 271 REALAD Macro . . . . . . . . . . . . . . . . . . 272 GETVIS Macro . . . . . . . . . . . . . . . . . . . 272 FREEVIS Macro . . . . . . . . . . . . . . . . . . 272 Program Communication . . . . . . . . . . .. . . . . 273 COMRG Macro . . . . . . . . . . . . . . . . . . . 274 MVCOM Macro . . . . . . . . . . . . . . . . . . 274 Releasing I/O Units . . . . . . . . . . . . . . . . . . 274 RELEASE Macro . . . . . . . . . . . . . . . . . . 274 Time of Day Macro . . . . . . . . . . . . . . . . . . 275 GETIME Macro . . . . . . . . . . . . . . . . . . 275 Interval Timer and Exit Macros .......... 275 Entering a Routine When Time Elapses . . . . . . . . . . . . . . . . . . . . . . . 276 SETIME Macro . . . . . . . . . . . . . . . . . . . 276 ITIMER Macro . . . . . . . . . . . . . . . . . . 276 STXIT Macro . . . . . . . . . . . . . . . . . . . . 276 EXIT Macro . . . . . . . . . . . . . . . . . . . . . 280 Executing a Program at Given Intervals . . . . . . . . . . . . . . . . . . 281 TECB Macro . . . . . . . . . . . . . . . . . . . . . 281 SETIME Macro . . . . . . . . . . . . . . . . . . . 281 ITIMER Macro . . . . . . . . . . . . . . . . . . 281 WAIT Macro . . . . . . . . . . . . . . . . . . . . . 281 WAITM Macro . . . . . . . . . . . . . . . . . . . 282 DUMP Macros . . . . . . . . . . . . . . . . . . . . . . 282 PDUMP Macro . . . . . . . . . . . . . . . . . . . 282 DUMP Macro . . . . . . . . . . . . . . . . . . . . 282 JDUMP Macro . . . . . . . . . . . . . . . . . . . 283 Cancel and EO] Macros ............... 283 CANCEL Macro . . . . . . . . . . . . . . . . . . 283 EOJ Macro . . . . . . . . . . . . . . . . . . . . . . 283 Checkpointing a Program .............. 283 CHKPT Macro . . . . . . . . . . . . . . . . . . . 283 Checkpoint File . . . . . . . . . . . . . . . . . . . 285 Repositioning I/O Files . . . . . . . . . . . . . . 285 DASD Operator Verification Table . . . . . . . . . . . . . . . . . . . . . . . . 287 Multitasking Macros . . . . . . . . . . . . . . . . . . Subtask Initiation and Normal Termination Macros .............. AITACH Macro . . . . . . . . . . . . . . . . . . DETACH Macro . . . . . . . . . . . . . . . . . . Resource Protection Macros ............. RCB Macro . . . . . . . . . . . . . . . . . . . . . ENQ Macro . . . . . . . . . . . . . . . . . . . . . DEQ Macro . . . . . . . . . . . . . . . . . . . . . Intertask Communication Macros . . . . . . . . . WAITM Macro . . . . . . . . . . . . . . . . . . . POST Macro . . . . . . . . . . . . . . . . . . . . . DASD Protection Macro . . . . . . . . . . . . . . . FREE Macro . . . . . . . . . . . . . . . . . . . . . Shared Modules and Files .............. 288 288 288 289 289 289 290 290 291 291 291 292 292 293 Program Linkage Macros . . . . . . . . . . . . . . . Linkage Registers . . . . . . . . . . . . . . . . . . . . Save Areas . . . . . . . . . . . . . . . . . . . . . . . . CALL Macro . . . . . . . . . . . . . . . . . . . . . SAVE Macro . . . . . . . . . . . . . . . . . . . . . RETURN Macro . . . . . . . . . . . . . . . . . . 295 297 297 298 300 300 Appendix A: Control Character Codes ...... 301 CTLCHR=ASA . . . . . . . . . . . . . . . . . . . . . 301 CTLCHR= YES . . . . . . . . . . . . . . . . . . . . . 301 Appendix B: Assembling Your Program, DTFs, and Logic Modules . . . . . . . . . . . . . . . 304 Appendix B.l: Assembling a Format Record for the 3886 Optical Character Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 Document Example . . . . . . . . . . . . . . . . . . . 319 Format Record Assembly Example ........ 319 Appendix C: Reading, Writing, and Checking with Nonstandard Labels . . . . . . . . . 324 Appendix 0: Writing Self-Relocating Programs . . . . . . . . . . . . . . . . . . . . . . . . . . Rules for Writing Self-Relocating Programs .. Advantage of Self-Relocating Programs ..... Another Way--The Relocating Loader. . . . . . Programming Techniques . . . . . . . . . . . . . . . 326 326 328 328 328 Appendix E: MICR Document Buffer Format . 331 Appendix F: American National Standard Code for Information Interchange (ASCII) ... 335 Appendix G: Page Fault Handling Overlap .... Register Usage . . . . . . . . . . . . . . . . . . . . Entry Linkage . . . . . . . . . . . . . . . . . . . . Page Fault Queue . . . . . . . . . . . . . . . . . . Processing at the Initiation of a Page Fault Processing at the Completion of a Page Faul.. . . . . . . . . . . . . . . . . . . 339 339 339 339 340 340 Appendix H: Operand Notation for VSAM GENCB, MODCB, SHOWCB, and TESTCB Macros . . 341 GENCB Macro Operands . . . . . . . . . . . . 342 MODCB Macro Operands . . . . . . . . . . . . 343 SHOWCB Macro Operands . . . . . . . . . . . 343 TESTCB Macro Operands . . . . . . . . . . . . 344 Appendix I: Parameter Lists for VSAM GENCB, MODCB, SHOWCB, and TESTCB Macros . . 345 The GENCB Parameter List .......... 346 The MODCB Parameter List .......... 347 The SHOWCB Parameter List ......... 348 The TESTCB Parameter List . . . . . . . . . . 349 Appendix J: Using ISAM Programs with VSAM Files . . . . . . . . . . . . . . . . . . . . . . . . 351 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 PARTl INTRODUCTION Macro Types aDd their Usage Label Processing MACRO TYPES AND THEIR USAGE A macro is a single assembler language instruction which generates a sequence of assembler language instructions. The macros you code in your program are called the source program macros. The assembler uses what is called the macro definition to generate the sequence of instructions requested by the source program macro. Use of macros simplifies the coding of programs and reduces the possibility of programming errors. Macro Definitions A macro definition is a set of statements which defines the name of, format of, and conditions for generating a sequence of assembler language instructions from a single macro instruction. Macro definitions are stored in the Macro Sublibrary of the source statement library. Source-Program Macros Source-program macros are those you specify in your program; they indicate to the assembler which macro definition is to be called from the library. With a source-program macro you specify operands and parameters which the assembler uses, together with the called macro definition, to determine what assembler instructions to generate. There are two different types of source-program macros: supervisor macros and IOCS macros. Supervisor Macros These macros enable you to make use of functions performed by the supervisor. The RUNMODE macro, for example, determines whether your program is to run in virtual or real mode. IOCS Macros IOCS macros are divided into basic categories: imperative 10CS macros and declarative 10CS macros. Imperative IOCS Macros These macros identify what 110 operation you want to perform. The GET macro, for example, indicates that you want to obtain a record. Declarative IOCS Macros Declarative 10CS macros for all access methods except VSAM are of two related types--DTFxx macros and logic module generation (xxMOD) macros. Declarative 10CS macros for VSAM are the ACB, EXLST, and RPL macros. For further details on DTF declarative macros see the section on DTF Declarative Macros. The logic module generation macros and VSAM declarative macros are briefly discussed below and described in detail later on. Logic Module Generation Macros. Logic module generation macros give information about the type of logic module to be generated. The module is the object code routine which will handle the conditions you specify in the module generation macro. For example, the CDMOD macro could generate a module to handle card input on a 2540 (as shown in the example in Appendix B). VSAM Macros. The Virtual Storage Access Method (VSAM) has a set of declarative macros different from the DTFxx and logic module generation macros described above. VSAM declarative macros are ACB, EXLST, and RPL. The ACB macro produces an access method control block which connects your program to the file. The access method control block contains information about the kind of processing to be done, and is usually specified only once in a program. The EXLST macro produces an exit list containing addresses of routines you supply to handle special situations--such as an end-of -data routine, or a routine to manage I/O buffers. This macro is also usually specified only once in your program. The RPL macro produces a request parameter list containing such information as a buffer address that is needed for execution of the VSAM imperative macros. VSAM has no logic module generation macros. Standard VSAM modules are placed in the core image library during system generation, and loaded into your partition when a VSAM file is opened. The possibility of coding your own modules with a Part 1. Introduction 11 logic module generation macro, and of assembling or link-editing modules with your program, does not exist with VSAM. Macro Processing A direct relationship exists between the two basic parts of the macro system--between the sourceprogram macros and the macro definitions--as described above. During assembly, the source-program macro specifies which macro definition is to be called from the library. Figure 1-1 depicts schematically the source program before and after inclusion of the macro expansion. This is accomplished by a selection and substitution process using the general information in the macro definition and the specific information in the macro itself. The insertion consists of a module, a table, or a small in-line routine and is called the macro expansion. After the insertion is made, the complete program consists of both source program statements and assembler language statements generated from the macro definition. In subsequent phases of the assembly, the entire program is processed to produce the machine-language program. IBM provides a number of tested macro definitions. The macro instructions needed to use these definitions are described in this manual. You can also write your own macro definitions and include them in the source statement library of your system. For additional information on this subject, see OS / VS and DOS/VS Assembler Language, GC33-4010. The IBM-supplied macros, which are explained in this book, are organized as follows: Part 2. Sequential Access Method (SAM) LIOCS macros. Part 3. Direct Access Method (DAM) LIOCS macros. Part 4. Indexed Sequential Access Method (lSAM) LIOCS macros. Part 5. Virtual Storage Access Method (VSAM) LIOCS macros. Part 6. PIOCS macros. Part 7. Supervisor macros. Multitasking macros. Program Linkage macros. SOURCE PROGRAM (After) ASSEMBLER OPERATIONS SOURCE PROGRAM (Before) 1 _ _ _ __ 2 _ _ _ __ -_ -_ -21 __ _ ,Locate Mac ro Definition Source Program Statements Source Program Statements 15 _ _ _ __ 15 _ _ _ _ _ Perform Indicated 16 Macro - - - - - - -...... < Selection and 17 Substitution 16 Mocro Merge with } Source Program _________ Mocro Expansion ~ ,,----- 17 ~:~='ts Figure 1-1 Schematic of macro processing 12 DOS/VS Supervisor & I/O Macros ----1 --------- processed by PIOCS (Physical Input/Output Control System). Figure 1-2 contains an example of a DTF source statement. For LIOCS operations, the DTF macro used depends on the type of processing that will be performed and upon the type of device used. For detailed information on LIOCS and PIOCS, please refer to the DOS / VS Data Management Guide, GC33-5372. DTF Declarative Macros With all access methods except VSAM, whenever you use logical IOCS imperative macros (such as GET, PUT, READ, or WRITE) in your program to control the input/output of records in a file, that file must be defined by a declarative macro called a DTF (Define The File). The DTF macro describes the characteristics of the file, indicates the type of processing for the file, and specifies the virtual storage areas and routines to be used in processing the file. For example, if a GET is issued, the DTF macro supplies such information as: The following is a list of DTFs available for the various types of processing. Processing with SAM Record type and length. This applies to input/output with serial or diskette devices, or with direct access devices when records are processed sequentially. (ISAM and VSAM may also be used with direct access devices when records are to be processed sequentially). The macros used for SAM processing are listed by device name in alphabetical order in Figure 1-3. For details refer to Part 2 of this manual. Input device from which the record is to be retrieved. Address of the area in storage where the record is to be located for processing by your program. Device-oriented DTF macros are available for defining files processed by LIOCS (Logical Input/Output Control System). An additional DTF macro is available for magnetic tape or DASD files I...,.,.... 1-· - . OL DM STR ~I, , ( .... '.~ 0"-'[ a-,~ I. " I, ,. ~~ ,. I C·"·,c 'h,C 'lie Icr,' I I I 'UNCH , ., 10 " Drr Flrtn " I I " c_"" I I I .. I ! I I I ' I I 11 : ,1 " : ! I I: I ' i : I I I Of ldenl,f'O:OI,,,,,- ., [ IZ E - 40 o. DD R- SY SO o 1 , DID R - EO F~ ST R, B L - S TID, 10 ~R EIA 1 - AR EA ON E , ER RP PT -C K~ LD B L K, HD R I NF 0- YE S, 10 IAR EIA 2 - AR E~ T~ 0, 10 RE G- ( 3 ) , LA BA DD R-icK len DB LK RE AD - F OR IWIA RD, RE CF OR M- F I XB L:K, RE CS I Z E - 80 , RE tNl ND -u NL ~DI, SE pIA S~ B- YE S. TY P E FL E- IN PU T, ~L RE RI~ -R EG8 BL KS DE VA Elo FA F I L~ PACE ICARDflECTRONUMlfII s....nc. 7J " 80 X X X X X P< X X X X X X X X X X X i I I I I I I Figure 1-2 Sample DTFMT macro Part I. Introduction 13 File to be processed on Macro Card device Console printer-keyboard DASD sequential Device independent 3540 Diskette I/O Unit Display operator console Magnetic reader (MICR) Magnetic tape Optical reader (excluding 3886) 3886 Optical character reader Optical reader/sorter Paper tape reader Paper tape punch Printer Sequential DASD Serial type device (for compatibility only) DTFCD DTFCN DTFSD DTFDI DTFDU DTFCN DTFMR DTFMT DTFOR DTFDR DTFMR DTFPT DTFPT DTFPR DTFSD DTFSR Figure 1-3 SAM declarative macros Processing with DAM Whenever a file on a direct access device is to be processed by DAM, DTFDA must be used. For details refer to Part 3 of this manual. program, you can obtain detailed information on the layout of DTF tables in the LIOCS Program Logical Manuals, SY33-8559, SY33-8560 and SY33-8561. Symbolic Unit Addresses in the DTFxx Macro In most of the DTF macros you can specify a symbolic unit name in the DEV ADDR operand. This symbolic unit name is also used in the ASSGN job control statement to assign an actual 110 device address to the file. For files on diskettes or direct access devices, the symbolic unit name is supplied in the DEV ADDR operand and I or with the EXTENT job control statement (if both are provided the EXTENT specification overrides the DEV ADDR specification). The symbolic unit name of a device is chosen from a fixed set of symbolic names. Programs are written considering only the device type (tape, card, etc.). At execution time, the actual physical device is determined and assigned to a given symbolic unit. For instance, a program that processes tape records can call the tape device SYSOOO. At execution time the operator (using ASSGN) assigns any available tape drive to SYSOOO. Processing with ISAM Whenever a file on a direct access device is to be organized or processed by ISAM, DTFIS must be used. For details refer to Part 4 of this manual. Processing with PIoes When PIOCS macros (EXCP, WAIT, etc.) are used for a file, the DTFPH macro is required only if standard labels are to be checked or written on a file on a direct access device or magnetic tape, or if the file on a direct access device is file-protected. For details refer to Part 6 of this manual. Referencing the DTF Table A DTFxx macro generates a DTF table that contains indicators and constants describing the file. You can reference this table by using the symbol filename+constant, or filenamex where x is a letter. When referencing the DTF table, you must ensure address ability through the use of an A-type constant, or through reference to a base register. Should you need to reference a DTF table in your 14 DOS/VS Supervisor & I/O Macros Figure 1-4 shows the relationship between the source program, the DTF table, and the job control 110 assignment. Source Program GET FllEl L....I Figure 1-4 DTF Table FllEl DTFCD Supervisor I/o Tables (Job Control Initiated) SYSOOO,cuu _--It ,'---__ DEVADDR=SYSOOO Relationship between source program, DTF table, and job control I/O assignment The fixed set of symbolic names that can be used with a DTF macro for a program in any partition is the same and is represented by SYSxxx. Programs in different partitions can reference the same logical unit providing different devices, or DASD extents, are assigned. These symbolic units are divided into system logical units and programmer logical units. System Logical Units SYSRDR Card reader, magnetic tape unit, disk extent, or diskette extent primarily for job control statements. SYSIPT Card reader, magnetic tape unit, disk extent, or diskette extent as the primary input unit for programs. SYSPCH Card punch, magnetic tape unit, disk extent, or diskette extent as the primary unit for punched output. SYSLST Printer, magnetic tape unit, disk extent, or diskette extent as the primary unit for printed output. SYSLOG Console printer-keyboard or display operator console for operator messages and for logging job control statements. Can also be assigned to a printer. SYSIN and SYSOUT are valid only to job control and cannot be referenced in a user program. Examples for the use of SYSIN and SYSOUT are given in the section System Files on Tape or Disk in the DOS/VS Systems Management Guide, GC33-5371. Programmer Logical Units SYSnnn SYSnnn represents all the other symbolic units in the system. These units vary from SYSOOO to SYSmax, where SYSmax represents the highest numbered programmer logical unit available for the system: SYSmax=255-NPART x 14 where NPART is the number of partitions. Each of these programmer logical units can be assigned to any partition without a prescribed sequence, except when using DAM (see Note, below). For a given part~tion, the maximum number of programmer logical units is equal to SYSmax minus the sum of all programmer logical units assigned to other partitions. SYSLNK Disk extent as input to the linkage editor. SYSVIS Disk extent for the page data set. SYSCAT Disk extent for the VSAM catalog. SYSCLB Disk extent for a private core image library. SYSRLB Disk extent for a private relocatable library. SYSUSE Disk extent used by the system for internal purposes. SYSSLB Disk extent for a private source statement library. Each declarative macro requiring a symbolic unit to be specified has a list of symbolic units that are valid for that macro. In that list, SYSnnn represents programmer logical units, while SYSxxx indicates either a system or a programmer logical unit. SYSREC Disk extent for error log records and for the hard copy file of the display operator console. For files processed by either SAM or DAM, only one symbolic unit may be assigned to all extents of a file on one volume. SYSIN Can be used if you want to assign SYSRDR and SYSIPT to the same card reader or magnetic tape unit. Must be used if you want to assign SYSRDR and SYSIPT to the same disk extent. SYSO UT Must be used if you want to assign SYSPCH and SYSLST to the same magnetic tape unit. Cannot be used to assign SYSPCH and SYSLST to disk because these two units must refer to separate disk extents. In physical IOCS, the symbolic unit name is specified in the CCB and in the DTFPH macros. Instead or additionally it is specified with the EXTENT job control statement. (If more than one of these is used to provide the specification, an EXTENT specification overrides a DTFPH specification, and a CCB specification overrides an EXTENT and/or a DTFPH specification.) Note: For DAM the EXTENT job control statements must be supplied in ascending order, and the symbolic units for multivolume files must be assigned in consecutive order. Figure 1-5 shows the relationship between the source program and the job controlI/O assignment. Part 1. Introduction 15 Source program~ CCB EXCP ccbname Figure 1-5 Supervisor I/o Table (Job Control Initiated) sySxxx-+----·- SYSxxx,cuu Relatioship between source program and job control I/O assignment the appropriate functions. In either case the omission of unneeded functions saves storage space for a particular module. Note: If you issue an imperative macro, such as WRITE or PUT, to a module that does not contain that function, an invalid supervisor call (SVC 50) is generated, the job is terminated, and a message is displayed. Subsetting/Supersetting Logic Module Generation Macros Each DTF except DTFCN DTFPH, and DTFSR must link to an IOCS logic module. A logic module is generated by a logic module generation (xxMOD) macro. The modules provide the necessary instructions to perform the input/output functions required by your program. For example, the module reads or writes data, tests for unusual input/ output conditions, blocks or deblocks records if necessary, or places records in a work area. Most imperative macros enter a logic module to perform the necessary function. Providing Logic Modules: There are two ways of providing logic modules for your DTFs: 1. Do not code the logic module generation macro needed by your DTF(s). In this case, the standard logic modules needed for your installation should have been assembled and cataloged (in the relocatable library) at system generation time. You can then autolink needed modules from the relocatable library at link-edit time. Some modules may be subset modules to a superset module. A superset module is one which performs all the functions of its subset or component modules, avoiding duplication and thereby saving storage space. The functions required by several similar DTFs (that is, several DTFCDs, or several DTFPRs, etc.) are thus available via a single xxMOD macro, even if the DTFs have slightly different parameters. An example 'is shown in Figure 1-6. Superset Module Functions Subset Module Functions Subset Module Functions Optional use of CNTRL macro CNTRL macro cannot be used Optional use of CNTRL macro Workarea and I/O area processing Work area and 1/ 0 area processing I/O area processing only Support of printer overflow No printer overflow support Support of printer overflow Support of userspecified error actions Support of userspecified error actions Support of userspecified error actions 2. Code the logic module generation macro needed by your DTF(s), assembling it either in-line with your program or supplying it at link-edit time. If you do not code the logic modules yourself, Keeping Modules Small IOCS will automatically perform all sub setting/ supersetting which is possible. Some of the module functions are provided on a selective basis, according to the parameters specified in the xxMOD macro. If you code the xxMOD macro yourself, you have the option of selecting or omitting some of these f~nctions according to the requirements of your program. If, as described above, you do not code the xxMOD macro yourself, IOCS will automatic~lly select or omit 16 DOS/VS Supervisor & I/O Macros Figure 1-6 Subset and superset module example If you code the logic modules yourself, subsetting/ supersetting can be achieved by coding a single xxMOD macro which contains all of the functions needed by all of the DTFs which will use that macro. In this case you may either: Not name the module and let IOCS name it for you--that is, specify no name for the xxMOD macro and also no MODNAME operands in the DTFs; or required logic module, or you can specify that name. Both methods are discussed below. Name the module--specifying a name for the xxMOD macro and also specifying the same name in the MODNAME operands of all of the DTFs which will use that module. IOCS Supplies the Name In order to make use of this facility omit the MODNAME operand from the DTF macro; the IOCS macro will then generate a standard module name as determined by the functions required by the DTF. Subsetting/ supersetting cannot be performed if you supply an xxMOD macro for each DTF of a given device type. In this case: If you did not name the modules, the assembler program will detect a double declaration error condition, or If you did name the modules, they will be gen- erated without any subsetting/ supersetting. Likewise, if you code your own module, the name should be omitted from the name field, and IOCS will generate a standard module name matching that referenced in the DTF. Standard module names used by IOCS are given under Standard CDMOD Names, Standard DIMOD Names, etc., following the discussion of the appropriate xxMOD macro. Interrelationship of the Macros Figure 1-7 shows the relationship between the program, the DTF, and the logic module. Imperative macros initiate the action to be performed by branching to the logic module entry point generated in the DTF table. TAPE is the name of the file. IJFFBCWZ is the name of the logic module. Program DTF Table M~ule IOCS Subset/Superset Names IOCS performs subsetting/ supersetting of modules with standard module names by collecting the services required by the DTFs and generating a single module with different entry points corresponding to the standard module names. If you are interested in seeing how IOCS forms subset/superset names, charts showing the name-building conventions are given throughout the book for the various logic modules-- under Subset/Superset CDMOD Names Subset/Superset DIMOD Names, etc., following the discussion of the appropriate module. The following is a model for these charts: I GET TAPE,WORK TAPE ~TFMJIJFF~CWZ UFFBCWZ ~T * + + + * x F BeN Y u Z Y Z Z ,v +E N+ V Z S Z + Subsetting/supersetting permitted. * No subsetting/supersetting permitted. Figure 1-7 Relationship between program, DTF and logic module Linkage between the program, DTF, and logic module is accomplished by the assembler and the linkage editor. Module Names As mentioned under Logic Module Generation Macros, you can have IOCS provide a name for the The letters indicate functions which can be performed by the logic module (these are fixed for a given module and are explained in the sections Standard CDMOD Names, Standard DIMOD Names, etc.). If a module name were composed of letters from the top row exclusively, it could only be a superset name; and names including letters from the second or lower rows would then be subset names to the top-row superset name. For example, the module IJxWESZZ is a subset module to superset module IJxWENZZ. IJxWEZZZ is 'anPart I. Introduction 17 other subset module to superset module IJxWENZZ. Similarly, IJxWEZZZ is also a subset module to superset module IJxWES~Z. An asterisk (*) over a column indicates that no sub setting or supersetting is permitted, while a plus (+) sign in a column indicates that both are permitted. Two plus signs in a single column divide that column into mutually exclusive sets. In this example, C is not a superset of N, S, or Z, and conversely, N, S, or Z is not a subset of C. The vertical arrangement of letters within a column is always in alphabetical order. If a column is divided by plus and/or asterisk signs into sets, then the vertical arrangement of letters within each set of a column is in alphabetical order. You Supply the Name Specify the name of the module in the MODNAME operand of the DTF macro. A module with this name must then be present in your program, or be supplied to your program when it is link-edited. Subsetting/ supersetting will occur if one module contains all of the functions needed by all of the DTFs which will use the module (all must reference it by the same name). Nothing is gained by giving your modules standard laCS names (see IOCS Supplies the Name, above), for lacs will supply the same name for you if you let it name the modules. Should you decide to name your modules, use names which are meaningful to you in the context of your program. Link-Editing Logical IOCS Programs You have the option of assembling your DTFs, and any logic modules which you code yourself, either with your main program or separately for later link-editing with the main program. These possibilities are discussed below and are illustrated in Appendix B. in logic modules). Further information on linkage editing can be found in the section Linkage Editor of the DOS / VS System Control Statements, GC33-5376. Program, DTF, and Logic Module Assembled Separately Specify the operand SEP ASMB= YES in the DTF macro or xxMOD macro which is to be separately assembled. For DTFs which are separately assembled, there are some symbolic linkages which you must define yourself in the form of EXTRNENTRY symbols. See Appendix B for a full description of which symbolic linkages you must define yourself. Supplying the SEP ASMB= YES operand in a DTF macro causes a CAT ALR card with the filename to be punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. Specifying the SEP ASMB = YES operand in an xxMOD macro causes a CATALR card with the module name to be punched ahead of the object deck and defines the module name as an ENTRY point in the assembly. In either case, a START card must not be used in a separate assembly. Using the Relocatable Library As stated earlier, considerable coding effort is saved if logic modules are cataloged in the relocatable library. The same applies to DTFs. Using DTFs cataloged in the relocatable library requires that you take care in naming the DTFs--that is, that you develop a set of standard names and then use them both for your DTFs and in all references your program makes to the DTFs. However, should you decide to name modules yourself, instead of letting lacs do it, then you make sure that you refer to precisely those modules in your DTFs by using their exact names (see Module Names above). If, at system generation time, a standard set of Program, DTF, and Logic Module Assembled Together If you assemble DTFs and logic modules with the main program, the linkage editor searches the input stream and resolves the symbolic linkages between tables and modules. This is accomplished by external-reference information (V -type address constants generated in DTF tables) and the control section definition information (CSECT definitions 18 DOS/VS Supervisor & I/O Macros logic modules needed by your installation has been generated, auto linking the appropriate modules to your DTFs presents no problem. This is particularly true if both the modules and DTF references to them use standard module names. Using logic modules which you named yourself--as opposed to those named by IOCS--cataloged in the relocatable library requires care. You should verify that the desired modules have been cataloged in the library by consulting a DSERV listing of the library. The linkage editor can perform an autolink only if there is an exact match of module names specified in the DTFs and the names of the modules themselves. Self-Relocating Programs and IOCS The Relocating Load feature, an option in supervisor generation, makes it unnecessary for you to write your own self-relocating programs. If, however, your supervisor does not have this feature and you want to make lacs imperative macros (except VSAM macros) and supervisor macros selfrelocating you must do the following: 1. Use the OPENR and CLOSER macro. 2. Use register notation within all your imperative macros (see Register Notation later in this chapter). Appendix D gives detailed instructions on writing self-relocating programs. Macro Format Macros, like assembler statements, have a name field, operation field, and operand field as shown below. Comments can also be included as in assembler statements. The name field in a macro may contain a symbolic name. Some macros require a name; for example, CCB, TECB, DTFxx. The operation field must contain the mnemonic operation code of the macro. The operands in the operand field must be written in either positional, keyword, or mixed formats. Positional Operands In this format, the parameter values must be in the exact order shown in the individual macro discussion. Each operand, except the last, must be followed by a comma, and no embedded blanks are allowed. If an operand is to be omitted in the macro and following operands are included, a comma must be inserted to indicate the omission. No commas need to be included after the last operand. Column 72 must contain a continuation punch (any nonblank character) if the operands fill the operand field and overflow onto another card. For example, GET uses the positional format. A GET for a file named CDFILE using WORK as a work area is punched: GET CDFILE,WORK Keyword Operands The exact parameters used are expressed as a keyword value. An operand written in keyword format has this form for example: LABADDR= MYLABELS where LABADDR is the keyword, MYLABELS is the parameter, and LABADDR=MYLABELS is the complete operand. The keyword operands in the macro may appear in any order, and any that are not required may be omitted. Different keyword operands may be punched in the same card, each followed by a comma except for the last operand of the macro. Or, they may be punched in separate cards as in Figure 1-2. Mixed Format The operand list contains both positional and key . . word operands. The keyword operands can be written in any order, but they must be written to the right of any positional operands in the macro. For additional information on coding macro statements, see os / VS and DOS / VS Assembler Language, GC33-4010. Cards for Declarative Macros The operands of the DTFxx and the module generation macros can be punched in a set of cards in the assembler format. Figure 1-2 shows an example of the cards used for a DTFMT macro. The DTF macros may be assembled in any order. The first card is a header card, and the continuation cards are detail cards. The header card is punched with: The symbolic name of the file in the name field. Programming Note: avoid using IJ as the first two letters when defining symbols as they may conflict with lacs symbols beginning with 11. Avoid symbols that are identical to a filename plus a single character suffix because lacs generates symbols by concatenating the filename with an additional character--for the Part 1. Introduction 19 filename RECIN, for example, IOCS generates the symbols RECINS, RECINL, etc. 4. Stacked options contained within brackets represent alternatives, one of which can be chosen for example: In a DTF, the symbolic filename may be up to seven characters long. This filename, if it is required on any of the standard label job control statements, must be the same as that used in the DTF header card. A name-field symbol in this assembly, or an operand of an EXTRN statement, or * (the Location counter). 5. An ellipsis (a series of three periods) indicates that a variable number of items may be included. For a module generation macro, the name may or may not be specified. See Module Names, above. The mnemonic operation code of the macro in the operation field. Keyword operands in the operand field, if desired. • A continuation punch in column 72, if a continuation card is necessary. The detail cards follow the header card, and may be arranged in any order. Each detail card is punched, beginning in column 16, with one or more keyword operands separated by commas. All detail cards except the final one must be punched with a comma immediately following the last operand and with a continuation punch in column 72. Comments may be included if a space is left after the comma following the last operand--or, for the last detail card, if a space is left after the last operand. ~~?:sJ 6. Stacked options contained within braces {} represent alternatives, one of which must be chosen. When the alternatives appear in a string, they are separated by a vertical bar (logical or) 7. filename Self-defining value, such as 3, X'04', (15), B'010'. 9. length 10'{A The following conventions are used in this book to illustrate the format of macros: 1. Uppercase letters and punctuation marks (except as described in these conventions) represent information that must be coded exactly as shown. 2. Lowercase letters and terms represent information which you must supply. More specifically, an n indicates a decimal number, an r indicates a decimal register number, and an x indicates an alphameric character. 3. Information contained within brackets [] represents an optional parameter that can be included or omitted, depending on the requirements of the program. 20 DOS/VS Supervisor & I/O Macros Absolute expression, as defined in OS/VS and DOS/VS Assembler Language, GC33-4010. l Underlined elements represent an assumed value in the event a parameter is omitted. ~) 11.{name } Ordinary register notation. Any register except 0 or 1. 12.~) (~)e name Special register notation (ordinary register notation can be used). (r) Notational Conventions Symbol appearing in the name field of a DTF macro. l ~ (1) Register Notation Certain operands can be specified in either of two ways: 1. You may specify the operand directly and produce code which cannot be executed in the SV A because it is not reentrant. I 2. You may load the address of the value into a register before issuing the macro. This way the macro is reentrant and will be executed in the SV A. When using register notation, the register should contain only the specific address and high order bits should be set to O. In the latter case, you must specify the register in the macro. (The registers that can be used for this purpose are discussed under Register Usage, below.) This method is known as ordinary register notation. When the macro is assembled, instructions are generated to pass the information contained in the specified register to IOCS or to the supervisor. For example, if an operand is writteq as (8), and if the corresponding parameter is to be passed to the supervisor in register 0, the macro expansion contains the instruction LR 0,8. You can save both storage and execution time by using what is known as special register notation. In this method, the operand is expressed as either (0) or (1). This notation is special for two reasons: • The use of registers 0 and 1 is not allowed unless specifically designated. The designation must be made by the specific three characters (0) or (1). When special register notation is indicated by (0) or (1) in a macro, you can use ordinary register notation and the macro expansion will contain an extra LR instruction. The format description for each macro shows whether special register notation can be used, and for which operands. The following example indicates that the filename operand can be written as (1) and the workname operand as (0): 2f GET) filename ~ '(l [' {workname} ) ] tions, such as a MICR stacker selection routine, may require different registers. Registers 0 and 1: Logical IOCS macros, the supervisor macros, and other IBM-supplied macros use these registers to pass parameters. Therefore, these registers may be used without restriction only for immediate computations. However, if you use these registers for computations not completed before IOCS requires them, you must save their contents and reload them later when required. Register 13: Control program subroutines, including logical IOCS, use this register as a pointer to a 72-byte, doublewordaligned save area. When using the CALL, SAVE, or RETURN macros, you can set the address of the save area at the beginning of each program phase, and leave it unchanged thereafter. However, when sharing a reentrant (read only) logic module among tasks, each time that module is entered by another task, register 13 must contain the address of another 72-byte save area to be used by that logic module. Registers 14 and 15: Logical IOCS uses these two registers for linkage. Register 14 contains the return address (to the program) from DTF routines, called programs, and your subroutines. Register 15 contains the entry point into these routines, and is used as a base register by the OPEN, OPENR, CLOSE, CLOSER, and certain DTF macros. (0) If either of these special register notations is used, your program must load the designated parameter register before executing of the macro expansion. Ordinary register notation can also be used. IOCS does not save the contents of these registers before using them. If you use these registers, you must either save their contents yourself (and reload them later) or finish with them before IOCS uses them. Register Usage Registers for Your Use Registers for Special Use Registers 2-12 are available for general usage. There are, however, a few restrictions. General registers 0, 1, 13, 14, and 15 have special uses, and are available to your program only under certain conditions. The following paragraphs describe the general uses of these registers by IOCS, but the description is not meant to be allinclusive. For more information on subroutine linkage through registers, refer to the Linkage Registers section of the Program Linkage Macros chapter. In addition, special applica- The assembler instruction for translate and test (TRT) makes special use of register 2. It is your responsibility to save the contents of this register before executing the TRT instruction if register 2 contains valuable information (such as pointers or counters) for later use in your program. After the TRT instruction has been executed, you can then restore the contents of register 2. Part I. Introduction 21 If an ISMOD logic module precedes a USING statement or follows your program, the use of registers 2-12 remains unrestricted even at assembly time. However, if the ISMOD logic module lies within the problem program, you should issue the same USING statement (which was issued before the logic module) directly following the logic mo- 22 DOS/VS Supervisor & I/O Macros dule. This action is necessary because the ISMOD logic module uses registers 1, 2, and 3 as base registers, and the ISMOD CORDATA logic module uses registers 1, 2, 3, and 5 as base registers. Each time either module is assembled, these registers are dropped. LABEL PROCESSING This section provides the information you need on order to process labels with the IOCS macros. More detailed information about labeling conventions and label processing considerations will be found in the DOSjVS Data Management Guide, GC33-5372, DOSjVS DASD Labels, GC33-5375, and DOSjVS Tape Labels, GC33-5374. DASD Standard Labels removed from all the volumes that it occupies or from only some of the volumes. If OPEN (or OPENR) determines that an existing file to be overlaid by the output file has not expired, the old file cannot be destroyed automatically. In this case, the following actions are possible. For SAM, DAM, physical IOCS, or work file processing: 1. Delete the unexpired file, or 2. Terminate the job, or Labels are required when processing files on direct access devices. Accordingly you must supply both a DASD label (DLBL) job control statement for each logical file to be processed, and one or more extent (EXTENT) job control statements to allocate one or more areas on a direct access device. Also, when processing standard labels, a LBLTYP job control statement is required to define virtual storage needed at link-edit time for label processing for files defined by DTFDA or DTFIS macros or by a DTFPH macro with the MOUNTED=ALL operand (more information will be found in DOSjVS System Control Statements, GC335376). OPEN and OPENR Macro Processing The OPEN and OPENR macros use the information supplied in the DLBL and EXTENT job control statements as well as information from the DTF for the file. For input, the extent(s) for a file must either coincide with, or be within, the existing extent(s) as defined in the Volume Table of Contents (VTOC). This is necessary input, IOCS opens only an existing file or a subset of an existing file. For output, the file to be written cannot overlap existing unexpired files. IOCS does not destroy an unexpired file without your explicit request, except when an internal system file (IJSYS) overlays an identical system file. However, if OPEN (or OPENR) determines that the output file will overlay an existing file that has expired, the macro OPEN (or OPENR) deletes the expired label(s) from the VTOC. This in effect removes the file from thtvolume. In a multi-volume file, the file may be 3. Bypass the extent. That extent and any remaining extents for that file are bypassed and the job is terminated. For ISAM processing: 1. Delete the unexpired file, or 2. Terminate the job. Reopening a File If further processing of a file which your program has closed is required at some later time in the program, the file must be reopened. When a file is processed in sequential order, IOCS checks the label(s) on the first volume and makes the first extent available, the same as at the original OPEN (or OPENR). When a file is processed by physical IOCS with the DTFPH operand MOUNTED = SINGLE, IOCS opens the next extent specified by your EXTENT job control statement. When a file is processed by DAM (defined by the DTFDA macro), by ISAM (defined by the DTFIS macro), or by physical IOCS with the DTFPH operand MOUNTED=ALL specified, all label processing is repeated and all extents are again made available. For more information on label processing see the discussion of the OPEN (or OPENR) macro' under the appropriate access method. End-of-Volume Processing During processing, IOCS recognizes an end-ofvolume condition when the extents on one volume have been processed and an extent for another Part I. Introduction 23 volume is encountered. When this condition occurs, 10CS branches to your LABADDR routine (if provided) to write or pass individually each user standard trailer label to be processed. After all user standard trailer labels are processed, 10CS processes the standard labels on the next volume and branches to your LAB AD DR routine to process user standard header labels. After the header labels are processed, 10CS continues to process the data. End-of-File Processing Output Files When all records for a logical output file have been written, the CLOSE (or CLOSER) macro must be issued to perform normal end-of-file processing. 10CS then branches to your LABADDR routine (if provided) to write user trailer labels, and the file is closed. If the end of the last extent specified for the file is reached before the CLOSE (or CLOSER) macro is issued, 10CS assumes an error condition. Input Files 10CS determines an end-of-file condition for a logical input file either by the ending address of the last extent specified for the file in the EXTENT job control statement, or by an end-of-file record read from the file. For SAM processing with DTFSD or DTFSR, 10CS branches to the EOFADDR routine upon an end-of-file condition. For sequential processing with DTFIS, 10CS posts the end-of-file condition in the field referred to as filenameC. You can then test this byte and take action necessary to close your file. However, when processing in random order you must determine the end-of-file by checking filenameC (DTFIS) or ERRBYTE (DTFDA). User Standard Labels If user standard labels are desired, you must supply a LABADDR routine, unless processing with physical 10CS. SAM and DAM process both user header and trailer standard labels. ISAM does not process user standard labels. User labels cannot be created for a file whose first extent is a split cylinder extent. DAM writes a user trailer label only on the first volume of a multi-volume file. When the LABADDR routine is entered, IOCS loads an alphabetic 0, V, or F into the low-order 24 DOS/VS Supervisor & I/O Macros byte of register O. 0 indicates header labels, V indicates trailer end-of-volume labels, and F indicates end-of-file labels. Your LABADDR routine can test this character to determine the labels to be processed. 10CS also loads the address of an 80byte 10CS label area in register 1; this is the address you use if checking labels, or from which you move the label to your program's label area if you are modifying labels. Within the LABADDR routine, you cannot issue a macro that calls a transient routine (such as OPEN (or OPENR), CLOSE (or CLOSER), DUMP, CANCEL, and CHKPT). For multi-volume files, the LABADDR routine should save registers 14 and 15 upon entry, and restore them before issuing the LBRET macro to return to 10CS. Writing User Standard Labels on Disk When you specify LABADDR, OPEN (or OPENR) reserves the first track of the first data extent as a user label area. At least one user header and trailer label must be written if the access method is to process it. For DAM, when TRLBL= YES is specified with LABADDR, trailer labels are processed. 10CS uses bytes 1-4 of the 80-byte label for the label identification (for example: UxLy, where x = H or T and y = 1,2, ... , 8). You can use the other 76 bytes as you wish. The maximum number of user standard header or trailer labels is eight for files on all DASDs except the 2321, and five for files on the 2321. 10CS stores the label information (UHLx or UTLx) that it generates in bytes 1-4 of the 10CS label area. You can test this information, in addition to registers 0 and 1, to determine the type and number of the label. (The label formats will be found in DOS/VS DASD Labels, GC33-5375.) In your area of vir tau I storage, build either an 80byte label, leaving the first four bytes free, or simply a 76-byte label. For the 80-byte label, load the address of the label area into register 0; for the 76-byte label, load the label area address minus four into register O. Then issue the LBRET macro. When the label is moved into the 10CS area, 10CS adds four to the address in register 0, thus only moving the 76 bytes of user information into the 10CS label area. When the label is ready to be written, the LBRET macro returns control to 10CS. If LBRET 2 is used, OPEN (or OPENR) writes the label and returns control to your label routine unless the maxi- mum number of labels has been written. If LBRET 1 is used, the label set is considered complete and no more labels can be created. When IOCS receives control, the IOCS routines move the label from the address you loaded into register 0 into the IOCS label area. If the maximum number of labels has not been written, IOCS increases the identification number by 1 and returns to your label routine unless LBRET 1 was used. If the maximum number of labels has been created, IOCS automatically terminates building of the label set. Checking User Standard Labels on Disk When a file on a DASD contains user standard trailer andlor header labels, IOCS makes these labels available one at a time if LAB AD DR is specified in the DTF (see DASD Standard Labels, above). If the labels are to be checked against information obtained from another input file, that file must be opened ahead of the file on a DASD. When your program has finished checking a label, it can update it or leave it unmodified. If it is to be updated, your program must move the label to an area within the program before modifying it. After the label is modified, the program must initialize register 0 with the address of the modified label before issuing the LBRET 3 macro. The program then updates the appropriate label fields by issuing the LBRET 3 macro. This causes the OPEN (or OPENR) routine to rewrite that label and read the next label. Register 1 points to the label in the IOCS label area. If the label is to remain unmodified, you can issue a LBRET 2 macro so OPEN or OPENR will read the next label. In either situation, if the end-of-file record is encountered at the end of the labels, OPEN (or OPENR) automatically terminates the label checking. If you wish to end label checking l;Jefore all the labels have been read, the LBRET 1 macro may be issued. Diskette Labels Labels are required when processing files on diskette 110 units. Accordingly you must supply a DASD label (DLBL) job control statement for each logical file to be processed, and one or more extent (EXTENT) job control statements (more information will be found in DOS/VS System Control Statements, GC33-5376. OPEN and OPENR Macro Processing The OPEN or OPENR macro uses the information supplied in the DLBL and EXTENT job control statements, information from the DTF for the file, and information from the file label on the diskette. For input, extent limits are taken directly from the file label in the VTOC on the diskette; extent limits provided in the extent statement(s) are ignored. Similarly for output files, the extent limits for the file are determined by OPEN (or OPENR) from available space on the diskette extent limits provided by the user are ignored. If the name of the output file to be created is the same as that of an unexpired or write-protected file already present on the volume, OPEN (or OPENR) will cause the job to be canceled. You will not be allowed to request that a duplicate file (unexpired or write-protected) be deleted. If the duplicate file has expired and is not write-protected or if a duplicate file is not being created, OPEN (or OPENR) will allocate space for the file, starting at the cylinder following the end of the last unexpired or write-protected file on the diskette. If expired and non-write-protected files are overlapped by this allocation, their labels are deleted from the VTOC. End-of -Volume Processing During processing, IOCS recognizes an end-ofvolume condition when end-of -extent is reached on a volume and more extents are available. When this occurs, IOCS processes the standard labels on the next volume and continues to process the data. End-of-File Processing Output Files When all records for an output logical file have been written, the CLOSE (or CLOSER) macro must be issued to perform normal end-of-file procedures. If the end of the last extent specified for the file is reached before the CLOSE (or CLOSER) macro is issued, IOCS assumes an error condition. Input Files IOCS determines an end-of-file for an input logical file by the end-of-data address. This address is specified in the file label in the VTOC of the last diskette of the file (first diskette if this is not a Part I. Introduction 25 I multi-volume file). IOCS branches to the EOFADDR routine upon an end-of-file condition. Tape Labels Under certain conditions, an unfilled block of records may be written at an EOV or EOF condition, even though the file is defined as having fixed-length blocked records. When this file is used for input, logical IOCS recognizes and processes this short block. You need not be concerned or aware of the condition. Tape Output Files For output on magnetic tape, OPEN (or OPENR), CLOSE (or CLOSER), or an end-of-volume condition rewinds the tape as specified in the DTFSR or DTFMT REWIND operand. No rewind can be defined in the DTFPH macro, and tape positioning depends on the labels to be processed and is your responsibility. If you write any user standard labels, a LABADDR routine must be supplied. (For ASCII tape files, the LABADDR routine may only be used to process user standard labels.) Your LABADDR routine, specified in the DTF, cannot issue a macro that calls a transient routine. For example, OPEN (or OPENR), CLOSE (or CLOSER), DUMP, CANCEL, and CHKPT cannot be issued. Also when processing multi-volume files, your label routine must save and restore register 15 if any logical IOCS macros other than LBRET are used. When user standard labels are written they always follow the standard labels on the tape. Label processing for the EOV condition resembles that for the EOF condition, except that a standard label is coded EOV instead of EOF. Also, only one tapemark is written after the label set or after the data for unlabeled files. In an ASCII file, two tapemarks follow the EOV labels. When IOCS detects the EOV condition, it switches to an alternate unit as designated in an ASSGN job control statement. If an alternate drive is not specified, the operator is requested to mount a new volume (on the same drive) or cancel the job. When the operator mounts the volume, IOCS checks the standard header labels and processing continues. In some cases, you may need to force an end-ofvolume condition at a point other than the reflective marker. You may want to discontinue writing the records on the present volume and continue on another volume. This may be necessary because of some major change in category of records or in processing requirements. The FEOV (forced EOV) macro is available for this function (see FEOV Macro in the Imperative Macros section of the Sequential Access Method Macros chapter). When all records of a file are processed, CLOSE (or CLOSER) can be issued to exec,ute the end-offile (EOF) routines. These routines write any record or blocks of records that are not already written. A partially filled record block is truncated; that is, a short block is written on the tape. Following the last record, IOCS writes a tapemark, the trailer labels, and two tapemarks, and executes the rewind option. If no trailer labels are written, two tapemarks are written and the rewind option is executed. In either case, if no rewind is specified and you have not specified any positioning, the tape is positioned between the two tapemarks at the end of the file. Writing Standard Labels on Tape When standard labels are written (DTFMT or DTFSR FILABL=STD or DTFPH TYPFLE=OUTPUT), you must supply the TLBL job control statement for standard label information. Also, when standard labels are processed, a LBLTYP job control statement is required to define virtual storage needed at link-edit time for label processing (more information will be found in DOS/VS System Control Statements, GC335376). If an end-of -volume (EOV) reflective marker is sensed on an output tape before a CLOSE (or CLOSER) is issued, logical IOCS prepares for closing the file by ensuring that all records are written on the tape. If you issue another PUT, indicating that more records are to be written on this output file, EOV procedures are initiated. If you issue a CLOSE (or CLOSER), the EOF procedures are initiated. When an OPEN (or OPENR) macro is issued and the tape is positioned at load point, the volume (VOLl) label is checked. Whether at load point or not, the old file header, if present, is read and checked to make sure that the file on the tape is no longer active and may be destroyed. If the file is inactive or if a tapemark was read, the tape is backspaced and the new file header (HDRl) label is written with the information you supply in the 26 DOS/VS Supervisor & I/O Macros tape label statement. The volume label is not rewritten, altered, or updated. A comparison is made between the specified density (800 or 1600 bpi) and the VOL1 density of the expired tape. If a discrepancy is found and the tape is at load point, the volume label(s) is (are) rewritten according to the specified density. If an output file begins in the middle of a reel, it is your responsibility to properly position the tape immediately past the tapemark for the preceding file before issuing the OPEN (or OPENR) macro. The MTC command can be used to do this. If the tape is improperly positioned, IOCS issues an appropriate message to the operator. If user standard labels are written, the LABADDR operand must be specified in the DTF (see Tape Output Files, above). After writing the standard label (header or trailer), IOCS loads register 0 (low-order byte) as follows: o indicates header labels. V indicates end-of-volume labels. F indicates end-of -file labels. Your LABADDR routine can test this character to determine what labels should be written. IOCS also loads the address of an 80-byte IOCS label area in register 1; this is the address you use if checking labels, or from which you move the label to your program's label area if you are modifying labels. Note: For ASCII files, you process your standard labels in EBCDIC. A maximum of eight user standard header (UHL), or trailer (UTL) labels can be written following the standard header (HDRl), or trailer (EOV1 or EOFl) labels. The user standard labels are 80 bytes long and are built entirely by you. Bytes 1-4 must contain the label identification (UxLy, where x=H or T and y=l, 2, ... , 8); the other 76 bytes can be used as desired. For ASCII tape files, you can have any number of user standard header or trailer labels. To comply with the standards for an ASCII file, these labels are identified by UHLa and UTLa, where a represents an ASCII character in the range 2/0 through 5/14, excluding 2/7 (apostrophe). The remaining 76 bytes can be used as desired. It is your responsibility to ensure that labels contain UHLa and UTLa in the first four bytes. Note: When creating user header and trailer labels for 7-track tapes, only unpacked data is valid in the 76-byte data portion of the label. You should build your labels in your area of virtual storage, and load the address of the label into register 0 before issuing the LBRET macro. When the label is ready to be written, you issue the LBRET macro, which returns control to IOCS. If LBRET 2 is used, IOCS writes the label and returns control to your label routine. If LBRET 1 is used, the label set is terminated and no more labels can be created. When IOCS receives control, IOCS writes the label on the magnetic tape and either returns control (LBRET 2) or writes a tapemark (LBRET 1). When a standard trailer label is written, IOCS accumulates the block count for the label when logical IOCS is used. However, if physical IOCS (DTFPH) is used, your program must accumulate the block count, if desired, and supply it to IOCS for inclusion in the standard trailer label. For this, the count (in binary form) must be moved to the 4-byte field within the DTF table named filenameB. For example, if the filename specified in the DTFPH header name is DELTOUT, the block count field is addressed by DELTOUTB. If checkpoint records are interspersed among data records on an output tape, the block count accumulated by logical IOCS does not include a count of the checkpoint records. Only data records are counted. Similarly, if physical IOCS is used, your program must omit checkpoint records and count data records only. After all trailer labels (including user labels, if any) are written at end-of-volume or end-of-file, IOCS initiates the EOF or EOV routines (see Tape Output Files, above). Writing Nonstandard Labels on Tape To write nonstandard labels, you must specify FILABL=NSTD and LABADDR=name. When the file is opened, the tape must be positioned to the first label that you wish to process. The MTC job control statement can be used to skip the necessary number of tapemarks or records to position the file. You must also write your own channel program and use physical IOCS macros to transfer the labels from virtual storage onto tape. For an example on reading, writing, and checking with unstandard labels see Appendix C. Part 1. Introduction 27 When a file is opened or closed, or when a volume is finished, IOCS supplies the hexadecimal representation (in the two low-order bytes of register 1) of the symbolic unit currently in use. See bytes 6 and 7 of the CCB for these values (the format of the CCB is given in the Physical IOCS Macros chapter). IOCS also loads register 0 (low-order byte) as follows: o indicates header labels. of -volume condition cause the tape to be rewound as specified by the DTFSR of DTFMT REWIND parameter. No rewind can be defined in the DTFPH macro. Tape positioning depends on the labels to be processed and is your responsibility. If any labels other than standard labels are to be checked, a LABADDR routine must be supplied. Your LABADDR routine, specified in the DTF, cannot issue a macro that calls a transient routine. This is the same as for the tape output files. V indicates end-of-volume labels. F indicates end-of-file labels. Your LABADDR routine can then test this character to determine the type of labels to be written. In your LABADDR routine, physical IOCS macros must be used to transfer labels from virtual storage onto tape. For each label record, a CCB and CCW must be established, and the EXCP macro must be issued (see the Physical IOCS Macros chapter). Other logical IOCS macros can be used for any processing other than the transfer of the labels from virtual storage to tape. Additional LABADDR routine restrictions are discussed above. After all labels are written, you return control to IOCS by use of the LBRET 2 macro. IOCS processing after LBRET is executed, has been discussed above. Note: Nonstandard labels are not permitted with ASCII. Writing Unlabeled Files on Tape If you use unlabeled files, you should specify FILABL=NO and omit TPMARK=NO in the DTF to improve the efficiency of your program. Your file must be positioned properly with the MTC job control statement, if necessary, and writing begins immediately. Other processing information can be found under Tape Input Files, below. For unlabeled ASCII files, TPMARK=NO is the only valid entry. If the operand is omitted entirely, TPMARK=NO is the default. Leading tapemarks are not supported on unlabeled ASCII files. Special error recovery procedures facilitate reading backwards. Tape Input Files For a magnetic tape input file, the macros OPEN (or OPENR), CLOSE (or CLOSER), or an end28 DOS/VS Supervisor & I/O Macros When an end-of -file condition occurs, IOCS branches to your EOF ADDR routine specified in the DTF. Generally, you issue a CLOSE (or CLOSER) in this routine to initiate a rewind operation for the tape (as specified by the DTF REWIND operand), and deactivate the file. If CLOSE (or CLOSER) is issued before the end of data is reached, the rewind option is executed and the file is deactivated without any subsequent label checking. When logical IOCS reads a tapemark on a tape input file, either an end-of-file or end-of-volume condition exists. This condition is determined by IOCS or by yourself, depending on the type of labels (if any) used for the file, and the appropriate functions are performed. IOCS can determine an end-of-volume condition only when trailer labels have been checked (see Checking Standard Labels on Tape or Checking Nonstandard Labels on Tape, below). If labels are not processed, your EOFADDR routine must process the condition (see FEOV Macro). When IOCS does detect the EOV condition, it switches to an alternate unit as designated in an ASSGN job control statement. If an alternate drive is not specified, a message to mount a new volume is issued. At this time, the operator may also cancel the job. When the operator mounts the volume, processing resumes. If the input file is processed by physical IOCS (DTFPH), you must issue an OPEN (or OPENR) macro for the new volume. Then, IOCS checks the header label(s) and processing continues. In some cases, you may desire to force an end-ofvolume condition at a point other than at the normal tapemark. You may want to discontinue reading the records on the present volume and continue reading records on the next volume. This may be necessary because of some major change in record category or in processing requirements. An FEOV (forced end-of-volume) is available for such cases (see FEOV Macro in the Imperative Macros section of the Sequential Access Method Macros chapter). Reading a Tape Backwards When reading backwards (READ=BACK), a labeled tape must be positioned so that the first record read, when OPEN (or OPENR) is executed, is the tapemark physically following the trailer labels. An unlabeled file must be positioned so that the first record read, when OPEN (or OPENR) is executed, is the tape mark physically following the first logical data record to be read (the last record written when the file was created). Although ASCII unlabeled tapes contain no leading tapemark, special error recovery procedures allow these tapes to be read backwards. Label checking of standard and nonstandard labels is similar. That is, lacs still processes standard labels, and your routine (if specified) still processes user or nonstandard labels. The only difference is that the volume label is not read immediately for standard labels, the trailer labels are processed in reverse order (relative to writing), and header labels are processed at EOF time, also in reverse order. If physical lacs macros are used to read records backwards, labels cannot be checked (DTFPH must not be specified). Because backwards reading is confined to one volume, an end-of-file condition always exists when the header label is encountered. At end-of-file for standard lables, lacs checks only the block count (which was stored from the trailer label) and then branches to your EOFADDR routine. At EOF for nonstandard labels, lacs branches to your LABADDR routine where the header label may be checked. To check labels, you must evoke physical lacs macros to read the label(s). Your LABADDR routine, specified in the DTF, cannot issue a macro that calls a transient routine. For example, OPEN (or OPENR), CLOSE (or CLOSER), DUMP, CANCEL, and CHKPT cannot be issued. Also, when processing multivolume files, your label routine must save and restore register 15 if any logical lacs macros other than LBRET are used. When user standard labels are checked, the ckecking is the same as that for standard labels. Checking Standard Labels on Tape When standard labels are to be checked (DTFMT or DTFSR FILABL=STD or DTFPH TYPFLE=INPUT), you must supply the TLBL job control statement for standard label information. Also, when processing standard labels, a LBLTYP job control statement is required to define virtual storage needed at link-edit time for label processing (more information will be found in DOS/VS System Control Statements, GC33-5376). When standard labeled files positioned at load point are opened, lacs requires that the first record be a volume (VOL 1) label. The next label could be any HDRI label preceding the file. lacs locates the correct file header (HDRl) label by checking the file sequence number. After checking the standard label (if user standard labels UHLI-UHLS or UTLI-UTLS are present for EBCDIC files, or UHLa or UTLa for ASCII files), lacs enters the LABADDR routine and enters an 0, V, or F in the low-order byte of register O. a indicates header labels. V indicates end-of-volume labels. F indicates end-of-file labels. Your routine can test this character to determine what labels should be checked. lacs also loads the address if an SO-byte lacs label area in register 1; this is the address you use if checking labels, or from which you move the label to your program's label area if you are modifying labels. After each label is checked, a LBRET 2 macro can be issued for lacs to read the next label. However, if a tapemark is read instead, label checking is terminated. If you wish to end label checking before all labels are read, you can issue a LBRET 1 macro. After all trailer labels are checked, lacs initiates EOV or EOF procedures (see Tape Input Files, above). Checking Nonstandard Labels on Tape Any tape labels not conforming to the standard label specifications are considered nonstandard. It is your responsibility to check such labels if they are present. The MTC job control statement can be issued to skip the necessary number of tapemarks or records to position the file. On input, nonstandard labels mayor may not be followed by a tapemark. The following possible conditions can thus be encountered: Part 1. Introduction 29 1. One or more labels, followed by a tapemark, are to be checked. 2. One or more labels, not followed by a tapemark, are to be checked. 3. One or more labels, followed by a tapemark, are not to be checked. 4. One or more labels, not followed by a tapemark, are not to be checked. For conditions 1 and 2, the DTFMT or DTFSR operands FILABL=NSTD and LABADDR=name must be specified. For condition 3, the operand FILABL=NSTD must be specified. If LABADDR is omitted, laCS skips all labels, bypasses the tapemark, and positions the tape at the first data record to be read. For condition 4, the entries FILABL=NSTD and LABADDR=name must be specified. In this case, laCS cannot distinguish labels from data records because there is no tapemark to indicate the end of the labels. Therefore, you must read all labels--even though checking is not desired--to position the tape at the first data record. Each time laCS opens a file or reads a tapemark, it supplies (in the low-order bytes of register 1) the hexadecimal representation of the symbolic unit currently used. These values are as shown in bytes 6 and 7 of the CCB. laCS also loads an alphabetic a into the low-order byte of register 0 when the file is opened. When your routine gains control, the tape is not moved by OPEN (or OPENR). Physical laCS 30 DOS/VS Supervisor & I/O Macros macros must be used to transfer labels from tape to virtual storage. Therefore, you must establish a CCB and a CCW. The macro EXCP is used to initiate the transfer. After all labels are checked, you return control to OPEN (or OPENR) by use of the LBRET 2 macro. When laCS reads a tapemark, it checks to determine if you have supplied a LABADDR routine. If a LABADDR routine was supplied, laCS exits to the routine. Otherwise, laCS skips the labels and branches to the EOF ADDR routine. In the LABADDR routine, you must use physical lacs macros to read your label(s). Furthermore, you must determine the EOF and/or EOV condition and indicate to lacs which condition exists by loading either EF (end-of-file) or EV (end-of-volume) into the two low-order bytes of register O. When this information is passed to laCS, it initiates the endof-file or end-of-volume procedures. Unlabeled Input Files on Tape The first record for unlabeled tapes (FILABL=NO) mayor may not contain a tapemark. Unlabeled tapes with ASCII contain no leading tapemark. If a tapemark is present, the next record is considered to be the first data record. If there is no tapemark, laCS reads the first record, determines that it is not a tapemark, and backspaces to the beginning of that record. The file can be properly positioned by use of the MTC job control statement. When the tape mark following the last data record is read, lacs branches to the end-offile address. PART 2 SEQUENTIAL ACCESS METHOD Declarative Macros DTFxx Macro Associated Macros Device Type DTFCD CDMOD Card DTFCN - Console DTFDI DIMOD Device Independent DTFDR DRMOD DFR DLINT 3886 Optical Character Reader DTFDU DUMODFx Diskette DTFMR MRMOD Magnetic Reader DTFMT MTMOD Magnetic Tape DTFOR ORMOD Optical Reader DTFPR PRMOD Printer DTFPT PTMOD Paper Tape DTFSD SDMODxx Sequential DASD DTFSR - Sequential Device Imperative Macros CHECK CHNG CLOSE CLOSER CNTRL DISEN DSPLY ERET FEOV FEOVR GET LBRET NOTE OPEN OPENR POINTR POINTS POINTW PRTOV PUT PUTR RDLINE READ RELSE RESCN SETDEV TRUNC WAITF WRITE Figure 2-1 summarizes the declarative and imperative macros which may be used for SAM processing on a given I/O device. V.l IV 0 0 en .......... < en f. ~DECLARATIVE MACROS INITIALIZATION / ~ en t: "0 .., (D <: r;;' ..,0 Pl ::l C. .::::: 0 3: Pl .., (j 0 [Il S ~ .= 1287/1288 OptIcal Reade. X X X X X 3211/5203 Prln... 00 1419 Magnetic Charac... Iteader . 2596/3504/3S05/35251~ -= = n 1442/2501/25ZV'254OI 1442/25ZV'254OI352~ ~. l'unc:h = X X 10 10 X X XX X X. X 15 4 15 13 22 X X X 20 21 4 15 20 12 4 X X X X XX X 4 15 X X 4 231"/2319/3330/~ X X XXX X XX 4 X X X 2671/1017 Paper Tape Reade. X .. 16 15 6 18 2 X 6 6 5 6 X 6 5 XXX X 15 X 6 7 XX 6 7 XX 8 6 X X 8 6 X X .. XX X .. XXX 4 5 16 XX X X XX 16 XX XX X X 6 16 15 9 6 XX X XX X X 6 X XX X 4 2321 Dalo Cell 4 15 6 XXX X XX XX X XXX .v 4 X X X 2400- Seri 3420 Magn.tic Tape Unit 4 X 14 X X 2311 Disk Unit 3340 Disk Unit 4 X 21 X X 11 X X 23 X IJCI 2560WCM! 5425 MFCU 11 X X 4 X X X X 11 XX X 4 1255/12~/ ~ ~ 11 4 1403/~32O:V ~ > 3: X COMPLETION XX X 4 n ."'=" PROCESSING X X Operator ConsoI. .::::: 0 IMPERA liVE MACROS Q~~dJA~_~f.t/~if£JI~~~H ~ 6 6 6 6 6 X XXX XX X 7 XX 8 6 X X X 2 X X 17 17 1018 Paper Tape l'unc:h X 3881 Optical Mark Read.. X X 3886 Optical Reader 3540 Disk.... V°Unit .X X XX _L..-I.--L...- X XX X X XX X X X .. 14 X 4 X X 4 1270/1275 OptIcal Reader.! Sa.... .. XX X X X X X XX X X X 4 16 X X Notes: 1. Use only with system logical units. 2. Recommended for compatibility use only. 3. Applies only if LABADDR is specified. 4. Always required for this file. 5. PUT rewrites an input DASD record if UPDATE is specified. GET and PUT cannot be used with workfiles. 6. Work files for DASD and magnetic tape only. 7. Applies only to blocked input records. 8. Applies only to blocked output records. 9. Applies only when 2 selector channels and one or more 2-channel simultanous-readwhile-write tape control units are installed. 10. Journal tape processing only. 11. 1287/1288 document processing only. 12. PUT punches on input card with additional information if TYPEFLE=CMBND is specified for the 1442, 2520, or 2540, or if FUNC=RP or RPW is specified for the 3525. PUT prints on the card for the 3525 with the print feature. 13. In the 2540, GET normally reads cards in the read feed. If TYPEFLE=CMBND is specified, GET reads cards at the punch-feed-read station. 14. For the 1419 or 1275 with the Pocket Light Feature. 15. This macro cannot be used with DTFDI. 16. Applies only if ERREXT specified. 17. Required if two I/O areas. 18. Valid for 2671 only. 19. 3525 Card Punch with read feature. 20. 3525 Card Punch with print feature. 21. Not supported for 2501, 3505, or 3525, respectively. 22. Not supported for 2501 or 3505. PUT is supported for any device that has a punch. 23. Not supported by 2596. Part 2. Sequential Access Method 33 DECLARATIVE MACROS As stated earlier, there are two related types of declarative macros: DTFxx macros and logic module generation macros. In this section each type of processing is divided by type of storage medium: card, magnetic tape, DASD, etc. The DTFxx macro used with the file is discussed first, and then (where applicable) the corresponding logic module generation macro. As discussed earlier, you need not specify names for your modules. IOCS will do this for you, making use of subsetting/ supersetting wherever it is possible (see Module Names in The Macro System chapter). The sections on module-naming conventions following the discussions of the logic module generation macros are therefore provided only for those who are interested in seeing how IOCS forms the names for the modules. punch, or print files, and enables macro sequence checking by the logic module of each associated file. One filename is required per DTF for associated files. \ Figure 2-2 defines the filename specified by the ASOCFLE operand for each of the associated DTFs. In ASOCFILE operand of ... FUNC= read DTFCD, punch DFTCD, specify filename of specify filename of RP punch DTFCD RW print DTFPR DTFCDMacro PW This macro defines a file for a card reader. However, it should not be used to read SYSIPT data if the program might be invoked by a catalogued procedure. In this case, the DTFDI macro should be used. RPW Enter the symbolic name of the file (filename) in the name field and DTFCD in the operation field. The detail entries follow the DTFCD header card in any order. Figure 2-3 lists the keyword operands contained in the operand field. ASOCFLE= rdename This operand is used together with the FUNC operand to define associated files for the 2560, 3525, or 5425. (For a description of associated files see the DOS/VS Data Management Guide, GC33-5372.) ASOCFLE specifies the filename of associated read, 34 DOS/VS Supervisor and I/O Macros Figure 2-2 punch DTFCD print DTFPR, specify filename of read DTFCD read DTFCD print DTFPR punch DTFCD print DTFPR read DTFCD ASOCFLE operand usage For example, if FUNC=PW is specified, specify the filename of the print DTFPR in the ASOCFLE operand of the punch DTFCD, and specify the filename of the punch DTFCD in the print DTFPR. Or if FUNC=RPW is specified, specify the filename of the punch DTFCD in the ASOCFLE operand of the read DTFCD; specify the filename of the print DTFPR in the punch DTFCD; and specify the filename of the read DTFCD in the print DTFPR. Applies to "'0 ..... 0. ..... 0 Q) !:: :sS = = = U ..... 0. !:: 0 x x x M DEV ADDR = SYSxxx Symbolic unit for reader-punch used for this file X X X M IOAREAl = xxxxxxxx Name of first I/O area, or seperate input area if TYPEFLE=CMBND and IOAREA2 are specified. X X 0 ASOCFLE = xxxxxxx Name for FUNC=RP, RW, RPW, PW X X X 0 BLKSIZE = nnn Length of one I/O area, in bytes. If omitted, 160 is assumed for a column binary on the 2560,3504,3505, or 3525; 96 is assumed for the 2596 or 5425, otherwise 80 is assumed. X X X 0 CONTROL = YES CNTRL macro used for this file. Omit CTLCHR for this file. Does not apply to 2501. X 0 CRDERR = RETRY Retry if punching error is detected. Applies to 2520 and 2540 only. X 0 CTLCHR = xxx (YES or ASA). Data records have control character. YES for S/370 character set; ASA for American National Standards Institute character set. Omit if TYPEFLE=CMBND. Omit CONTROL for this file. X 0 DEVICE = nnnn (1442,2501,2520, 2540, 2560P, 2560S,2596, 3504, 3505,3525, 5425P,or 5425S). If omitted, 2540 is assumed. X 0 EO FAD D R = xxxxxxxx Name of your end-of-file routine. X X X X X 0 ERROPT = xxxxxx IGNORE, SKIP, or name. Applies to 2560,3504, 3505, 3525 and 5425 only. X X 0 FUNC = xxx R, P, W, I, RP, RW, RPW, PW. Applies to 2560, 3525, and 5425 only. X X 0 10AREA2 = xxxxxxx Name of second I/O area, or separate output area if TYPEFLE=CMBND. Not allowed if FUNC=RP, RW, RPW, or PW. Not allowed for output file if ERROPT=IGNORE. X X 0 IOREG = (nn) Register number, if two I/O areas used and GET or PUT does not specify a work area. Omit WORKA. X X 0 MODE = xx (E or C) for 2560. (E, C, 0, R, EO, ER, CO, CR) for 3504 and 3505. (E, C, R, ER, CR) for 3535. If omitted, E is assumed. X M=Mandatory; O=Optional Figure 2-3 DTFCD macro (part 1 of 2) Part 2. Sequential Access Method 35 Applies to "'0 = ... ......= c.. :s 6 c.. = = 0= U Q) X 0 X X 0 MODNAME= xxxxxxxx Name of CDMOD logic module for this DTF. If omitted, 10CS generates standard name. X 0 OUBLKSZ = nn Length of IOAREA2 if TYPEFLE=CMBND. If OUBLKSZ omitted, length specified by BLKSZ is assumed for IOAREA2. X X X 0 RDONLY = YES Generates a read-only module. Requires a module save area for each task using the module. X X X 0 RECFORM = xxxxxx (FIXUNB, UNDEF, or VARUNB). If omitted, FIXUNB is assumed. Input or combined files always FIXUNB. 0 RECSIZE = (nn) Register number if RECFORM=UNDEF. General registers 2-12, written in parentheses. 0 SEPASMB = YES DTFCD is to be assembled separately. 0 SSELECT = n (t or 2) for 1442,2520,2596,3504, or 3525. (1,2, or 3) for 2540. (1,2,3, 4, or 5) for 2560. (1, 2, 3, or 4) for 5425. Stacker-select character. X X X X X X X X X 0 TYPEFLE = xxxxxx (INPUT, OUTPUT, or CMBND) If omitted INPUT assumed. CMBND may be specified for 1442N 1, 2520B 1, or 2540 punch-feed-read only. X X X 0 WORKA = YES GET or PUT specifies work area. Omit IOREG. Not allowed for output file if ERROPT=IGNORE. M=Mandatory; O=Optional Figure 2-3 DTFCD macro (part 2 of 2) 36 DOS/VS Supervisor and I/O Macros BLKSIZE=n Enter the length of the I/O area (IOAREA1). If the record format is variable or undefined, enter the length of the largest record. If the operand FUNC=I is specified for the 2560 or 3525, the length specified for BLKSIZE must be 80 data bytes if CTLCHR= YES or ASA is not specified, or 81 if CTLCHR= YES or ASA is specified. For the 3881, the BLKSIZE operand must be sufficient to contain: 6 bytes of record description information • Mark read data • Binary coded decimal (BCD) mark read data if the BCD feature is being used. • 7 bytes of serial number and batch number data if the serial number feature is being used. The BLKSIZE operand for the 3881 cannot exceed 900. If a BLKSIZE greater than 900 is specified, the BLKSIZE defaults to 900. stacker PI (punch), while correct cards are stacked in the stacker you select. If the CRDERR=RETRY operand is included and an error condition occurs, 10CS also notifies the operator and then enters the wait state. The operator can either terminate the job, ignore the error, or instruct 10CS to repunch the card. CTLCHR= IASA 1YES} This operand is required if first-character control is to be used on an output file. ASA denotes the American National Standards Institute, Inc. character set. YES denotes the System/370 character set. Appendix A contains a complete list of codes. This entry does not apply to combined files. If this operand is specified, CONTROL must be omitted. IPEVADDR= ISYSIPT 1SYSPCH 1SYSRDR 1 SYSnnn} This operand specifies the symbolic unit to be associated with a file. The symbolic unit represents an actual I/O device address and is used in the ASSG N job control statement to assign the actual I/O device address to the file. If the BLKSIZE operand is omitted, the length is assumed to be 80, with the following exceptions: 160 is assumed for column binary mode on the 2560, 3505, or 3525. • 96 is assumed for the 2596 or 5425. SYSIPT, SYSPCH, or SYSRDR must not be specified: • for the 2596 • for the 3881 900 is assumed for the 3881. CONTROL=YES This operand is specified if a CNTRL macro is to be issued for a file. If this operand is specified, CTLCHR must be omitted. The CNTRL macro cannot be used for an input file with two I/O areas (when the IOAREA2 operand is specified). This operand must not be specified for an input file used in association with a punch file (when the operand FUNC=RP or RPW is specified) on the 2560, 3525, or 5425; in this case, however, this operand can be specified in the DTFCD for the associated punch file. CRDERR=RETRY This operand applies to card output on the 2520 or 2540. It specifies the operation to be performed if an error is detected. From this specification, 10CS generates a retry routine and a save area for the card punch record. If a punching error occurs, it is usually ignored and operation continues. The error card is stacked in for 1442, 2520, or 2540 combined files (TYPEFLE=CMBND) • for 2560, 3525, or 5425 associated files (FUNC=RP, RW, RPW, or PW) if the operand FUN C = I is specified • if the MODE operand is specified with the C, 0, or R parameters. DEVICE=12540 114421250112520 12560P 1 2560S12596135041350513525 1 5425P 15425S 138811 This operand specifies the I/O device associated with a file. The "p" and "s" included with the "2560" and "5425" parameters specify primary or secondary input hoppers. EOFADDR=name This entry must be included for input and combined files and specifies the symbolic name of your end-offile routine. 10CS automatically branches to this routine on an end-of-file condition. In your routine you can perform any operations required for the end Part 2. Sequential Access Method 37 of the file (you generally issue a CLOSE instruction for the file). must be done for the card in error. 10CS continues processing by reading the next card. 10CS detects end-of-file conditions in the card reader by recognizing the characters / * punched in card columns 1 and 2. If the system logical units SYSIPT and SYSRDR are assigned to a 5425, 10CS requires that the /* card, indicating end-of-file, be followed by a blank card. An error condition results if cards are allowed to run out without a / * trailer card (and without a / & card if end-of-job). Note: When ERROPT is specified for an input file and an error occurs, there is a danger that the / * end-of-file card may be lost. This is because 10CS, after taking the action for the card in error specified by the ERROPT operand, returns to normal processing by reading the next card which is assumed to be a data card. If this card is in fact an end-of-file card, the end-of-file condition cannot be recognized. ERROPT={IGNORE I SKIP I name} This operand specifies the error exit option used for an input or output file on a 2560, 3504, 3505, 3525, or 5425. Either IGNORE, SKIP, or the symbolic name of an error routine can be specified for input files. Only IGNORE can be specified for output files. This operand must be omitted when using 2560 or 5425 associated output files. The functions of these parameters are described below. FUNC=IR I P I I I RP I RW I RPW I PW} This operand specifies the type of file to be processed by the 2560, 3525, or 5425. R indicates read, P indicates punch, and W indicates print. When FUNC=I is specified, the file will be both punched and interpreted; no associated file is necessary to achieve this. The information printed will be the same as the information punched, in contrast to FUNC=PW, where any relation between the information printed and the information punched is determined by your program. When FUNC=I is specified the file can have only one I/O area. IGNORE indicates that the error is to be ignored. The address of the record in error is put in register 1 and made available for processing. For output files, byte 3, bit 3 of the CCB is also set on (see Figure 6-1); you can check this bit and take the appropriate action to recover from the error. Only one I/O area and no work area is permitted for output files. When IGNORE is specified for an input file associated with a punch file (FUNC=RP or RPW) and an error occurs, a PUT for the card in error must nevertheless be given for the punch file. RP, RW, RPW, and PW are used, together with the ASOCFLE operand, to specify associated files; when one of these parameters is specified for one file, it must also be specified for the associated file(s). Associated files can each have only one I/O area. SKIP indicates that the record in error is not to be made available for processing. The next card is read and processing continues. IOAREAl =name This operand specifies the name of the input or output area used for this file. If name is specified, 10CS branches to your routine If issued for a combined file, this operand specifies the input area. If IOAREA2 is not specified, the when an error occurs, where you may perform whatever actions you desire. Register 1 contains the address of the record in error, and register 14 contains the return address. GET macros must not be issued in the error routine for cards in the same device (or in the same card path for the 2560 or 5425). If the file is an associated file, PUT macros must not be issued in the error routine for cards in the same device (for the 2560 or 5425 this applies to cards in either card path). If any other 10CS macros are issued in the routine, register 14 must be saved. If the operand RDONLY = YES is specified, register 13 must also be saved. At the end of your routine return to 10CS by branching to the address in register 14. If the input file is associated with an output file (FUNC=RP, RPW,or RW), no punching or printing 38 DOS/VS Supervisor and I/O Macros area specified in this operand is used for both input and output. IOAREA2=name This operand specifies the name of a second I/O area. If the file is a combined file and the operand is specified, the designated area is an output area. If this operand is specified for the 3881, the 10REG operand must also be specified. This operand must not be specified if FUNC=I, FUNC=RP, RPW, RW, or PW, or for output files if ERROPT=IGNORE. IOREG=(r) If work areas are not used but two input or output areas are, this operand specifies the register (2-12) in which IOCS puts the address of the record. For output files, 10CS puts the address where the user can build a record. This operand cannot be used for combined files. This operand must be specified for the 3881 if the IOAREA2 operand is specified. MODE={~ I C I 0 I R I EO I ER I CO I CRJ This operand specifies the mode used to process an input or output file for a 2560, 3504, 3505, or 3525. E indicates normal EBCDIC mode; C indicates column binary mode; 0 indicates optical mark read (OMR) mode; R indicates read column eliminate mode. E is also assumed if only 0 or R is specified. For the 2560, only E and C are valid entries. Valid entries for the 3504 and 3505 are E, C, 0, R, EO, ER, CO, and CR. Valid entries for the 3525 are E, C, R, ER, and CR. If 0 or R is specified (with or without E or C), a format descriptor card defining the card columns to be read, or eliminated, must be provided. See OMR considerations in the DOS/VS Data Management Guide, GC33-5372, for instructions on how to write this card as well as on how to code and process OMR data. Only E is valid for SYSIPT, SYSPCH, or SYSRDR. o and R (with or without E or C) cannot be specified for output files. E is assumed if the MODE operand is omitted. MODNAME = name This operand may be used to specify the name of the logic module that will be used with the DTF table to process the file. If the logic module is assembled with the program, MODNAME must specify the same name as the CDMOD macro. If this operand is omitted, standard names are generated for calling the logic module. If two DTF macros call for different functions that can be handled by a single module, only one module is called. OUBLKSZ=n This operand is used in conjunction with IOAREA2, but only for a combined file. Enter the maximum number of characters to be transferred at one time. If this entry is not included and IOAREA2 is specified, the same length as defined by BLKSIZE is assumed. RDONLY=YES This operand is specified if the DTF is used with a read-only module. Each time a read-only module is entered, register 13 must contain the address of a 72-byte doubleword-aligned save area. Each task should have its own uniquely defined save area. Each time an imperative macro (except OPEN or OPENR) is issued, register 13 must contain the address of the save area associated with that task. The fact that the save areas are unique for each task makes the module reentrant (that is, capable of being used concurrently by several tasks). For more information see Shared Modules and Files in the Multitasking Macros chapter. If an ERROPT routine issues I/O macros using the same read-only module that caused control to pass to the error routine, your program must provide another save area. One save area is used for the normal I/O operations, and the second for I/O operations in the ERR OPT routine. Before returning to the module that entered the ERROPT routine, register 13 must contain the save area address originally specified for the task. If this operand is omitted, the module generated is not reenterable, and no save area is required. RECFORM={FIXUNB I VARUNB I UNDEFJ This operand specifies the record format of the file: fixed length, variable length, or undefined. If the record format is FIXUNB, this operand may be omitted. If TYPEFLE = INPUT , TYPEFLE=CMBND, FUNC=I, or DEVICE=3881, this operand must be FIXUNB. RECSIZE=(r) For undefined records, this operand specifies the register (2-12) that contains the length of the output record. You must load the length of each record into the specified register before you issue the PUT macro for the record. SEPASMB=YES Include this operand only if the DTFCD is assembled separately. This causes a CATALR card with the filename to be punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. SSELECT=n This operand specifies the valid stacker-select character for a file. If this entry is not specified, cards are selected into NR (normal read) or NP (normal Part 2. Sequential Access Method 39 punch) stackers. For the 5425 cards are placed in stacker 1 when the cards came from hopper 1 and into stacker 5 ( 4) when they came from hopper 2. This operand must not be specified for combined files or for the 3881. This operand must not be specified for 2560, 3525, or 5425 read files associated with punch files (FUNC=RP or RPW); in this case the SSELECT=n operand may be specified for the associated output file. See the CNTRL Macro in the Processing Macros section later in this chapter for further information. Note: When this operand is used with a device other than a 1442 or 2596, the program ignores CONTROL= YES with input files. TYPEFLE={INPUT I OUTPUT I CMBNDI This operand specifies if a file is input, output, or combined. A combined file can be specified for a 1442 or 2520 or for a 2540 with the punch-feedread feature. TYPEFLE=CMBND is applicable if both GETs and PUTs are issued for the same card file. Only TYPEFLE=INPUT can be specified for the 3881. If TYPEFLE=OUTPUT or TYPEFLE=CMBND is specified, the DTF defaults to DEVICE=2540 and a non-executable CD MOD logic module is produced. The MNOTE "Improper device. 2540 assumed." is then printed at assembly time. If TYPEFLE=INPUT is omitted, INPUT is assumed. WORKA=YES If 110 records are processed in work areas instead of in the 110 areas, specify this operand. You must set up the work area in storage. The address of the work area, or a general-purpose register which contains the address, must be specified in each GET and PUT macro. If ERROPT=IGNORE is specified for an output file or if DEVICE=3881, WORKA=YES must not be specified. dule also processes files for which the CNTRL macro is not used. If this operand is specified, the CTLCHR operand must not be specified. This operand cannot be specified if IOAREA2 is used for an input file. This operand must not be specified for an input file used in association with a punch file (when the operand FUNC=RP or RPW is specified) on the 2560, 3525, or 5425; in this case, however, this operand can be specified in the DTFCD and CDMOD for the associated punch file. CRDERR=RETRY Include this operand if error retry routines for the 2540 and 2520 punch-equipment check are included in the module. Whenever this operand is specified, any DTF used with the module must also specify the same operand. This operand does not apply to an input or a combined file. CTLCHR={ASA 1YESI Include this operand if first character stacker select control is used. Any DTF to be used with this module must have the same operand. If CTLCHR is included, CONTROL must not be specified. This operand does not apply to a combined file or to an input file. DEVICE={2540 1144212501 12520 12560P 1 2560S1 25961 3504 13505 135251 5425P 15425S 138811 Include this operand to specify the 110 device used by the module. The "p" and "s" included with the "2560" and "5425" parameters specify primary or secondary input hoppers; regardless of which is specified, however, the module generated will handle DTFs specifying either hopper. Any DTF to be used with this module must have the same operand (except as just noted concerning the "p" and "s" specification for the 2560 or 5425). Listed here are the operands you can specify for CDMOD. The first card contains CDMOD in the operation field and may contain a module name in the name field. FUNC={R 1P 1I 1RP 1RW 1RPW 1PWI This operand specifies the type of file to be processed by the 2560, 3525, or 5425. Any DTF used with the module must have the same operand. R indicates read, P indicates punch, and W indicates print. CONTROL = YES Include this operamLif the CNTRL macro is used with the module and its associated DTFs. The mo- When FUNC=I is specified, the file will be both punched and interpreted; no associated file is necessary to achieve this. CDMODMacro 40 DOS/VS Supervisor and I/O Macros RP, RW, RPW, and PW specify associated files; when one of these parameters is specified for one file, it must also be specified for the associated file(s). Associated files can have only one I/O area each. IOAREA2=YES Include this operand if a second I/O area is used. Any DTF used with the module must also include the IOAREA2 operand. This operand is not required for combined files. This operand is not valid for associated files. RDONLY=YES This operand causes a read-only module to be generated. Whenever this operand is specified, any DTF used with the module must have the same operand. RECFORM=IFIXUNB I VARUNB I UNDEF} This operand specifies the record format: fixedlength, variable-length, or undefined. Any DTF used with the module must have the same operand. If TYPEFLE=INPUT, TYPEFLE=CMBND, or FUNC=I, this operand must be FIXUNB. For the 3881, only RECFORM=FIXUNB is valid. If this operand is omitted for the 3881, RECFORM=FIXUNB is assumed. module. CDMOD name = IJCabcde a = WORKA=YES This operand must be included if records are to be processed in work areas instead of in 1/ a areas. Any DTF used with the module must have the same operand. This operand is not valid for the 3881. Standard CDMOD Names Each name begins with a 3-character prefix (IJC) and continues with a 5-character field corresponding to the options permitted in the generation of the RECFORM=FIXUNB (always for INPUT, " CMBND, or FUNC=I files) V U RECFORM=VARUNB RECFORM=UNDEF b A Y"'C Z CTLCHR=ASA (not specified if CMBND) CTLCHR= YES CONTROL= YES CTLCHR or CONTROL not specified c B C RDONLY=YESandTYPEFLE=CMBND TYPEFLE=CMBND H RDONL Y= YES and TYPEFLE=INPUT I ""-TYPEFLE=INPUt N RDONL Y= YES and TYPEFLE=OUTPUT 0 TYPEFLE=OUTPUT d Z ......WORKA and IOAREA2 not specified W WORKA=YES I IOAREA2= YES B WORKA and IOAREA2 Z WORKA=YES not specified (CMBND file = only) o . . . . DEVICE=2540, 3881 e 1 2 3 4 5 SEPASMB=YES Include this operand only if the module is assembled separately. This causes a CATALR card with the module name (standard or user-specified) to be punched ahead of the object deck and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. TYPEFLE=lINPUT I OUTPUT I CMBND} This operand generates a module for either an input, output, or combined file. Any DTF used with the module must have the same operand. For the 3881, only TYPEFLE=INPUT is valid. If TYPEFLE=INPUT is omitted, INPUT is assumed. F 6 = 7 8 9 A B C D E F G H = I J K L M N 0 DEVICE= 1442, 2596 DEVICE=2520 DEVICE=2501 DEVICE=2540 and CRDER DEVICE=2520 and CRDERR DEVICE=3505 or 3504 DEVICE=3525 and FUNC=R/P or omitted DEVICE=2560 and FUNC=R/P or omitted DEVICE=5425 and FUNC=R/P or omitted DEVICE=3525 and FUNC=RP DEVICE=3525 and FUNC=RW DEVICE=3525 and FUNC=PW DEVICE=3525 and FUNC=I DEVICE=3525 and FUNC=RPW DEVICE=2560 and FUNC=RP DEVICE=2560 and FUNC=RW DEVICE=2560 and FUNC=PW DEVICE=2560 and FUNC=I DEVICE=2560 and FUNC=RPW DEVICE=5425 and FUNC=RP DEVICE=5425 and FUNC=RW DEVICE=5425 and FUNC=PW DEVICE=5425 and FUNC=I DEVICE=5425 and FUNC=RPW Subset/Superset eDMOD Names The following chart shows the subsetting and supersetting allowed for CDMOD names. All but one of the parameters are exclusive (that is, do not allow Part 2. Sequential Access Method 41 supersetting). A module name specifying C (CONTROL) in the b location is a superset of a module name specifying Z (no CONTROL or CTLCHR). A module with the name IJCFCIWO is a superset of a module with the name IJCFZIWO. See Ioes Subset/Superset Names in The Macro System chapter. * * * * * I J C F A B B V Y C I U H tV C I Z Z N + 0 0 1 2 3 4 5 6 7 8 9 A B C • M N o BLKSIZE=n This operand specifies the length of the I/O area; if the PUTR macro is used (TYPEFLE=CMBND is specified), this operand specifies the length of the output part of the I/O area. For the undefined record format, BLKSIZE must be as large as the largest record to be processed. The length must not exceed 256 characters. If the console buffering option is specified at system generation time and the device is assigned to SYSLOG, physical IOCS can increase throughput for each actual output record not exceeding 80 characters. This increase in throughput results from starting the output I/O command and returning to the program before output completion. Regardless of whether or not output records are buffered (queued on an I/O completion basis), they are always printed or displayed in a first-in-first-out (FIFO) order. DEVADDR={SYSLOG I SYSnnnJ This operand specifies the symbolic unit associated with the file. In a multiprogramming environment, DEVADDR=SYSLOG must be specified to obtain Background (BG), Foreground 1 (Fl), Foreground 2 (F2), Foreground 3(F3), or Foreground 4(F4) prefixes for message identification. DEVADDR=SYSLOG must be specified if TYPEFLE= CMBND is specified. + Subsetting/supersetting permitted. * No subsetting/supersetting permitted. DTFCN Macro DTFCN defines an input or output file that is processed on a 3210 or 3215 console printer-keyboard, or a display operator console. DTFCN provides GET /PUT logic as well as PUTR logic for a file. Enter the symbolic name of the file in the name field and DTFCN in the operation field. The detail entries follow the DTFCN header card in any order. Figure 2-4 lists the keyword operands contained in the operand field. 42 DOS/VS Supervisor and I/O Macros INPSIZE=n This operand specifies the length of the input part of the I/O area for PUTR macro usage. IOAREAl = name This operand specifies the name of the I/O area used by the file. For PUTR macro usage, the first part of the I/O area is used for output, and the second part is used for input. The lengths of these parts are specified by the BLKSIZE and INPSIZE operands respectively. The I/O area is not cleared before or after a message is printed, or when a message is canceled and reentered on the console. M DEVADDR = SYSxxx Symbolic unit for the console used for this file. M IOAREAl = xxxxxxxx Name of I/O area. 0 BLKSIZE = nnn Length in bytes of I/O area (for PUTR macro usage, length of output part of I/O area). If RECFORM=UNDEF, max. is 256. If omitted, 80 is assumed. 0 INPSIZE = nnn Length in bytes for input part of I/O area for PUTR macro usage. 0 MODNAME = xxxxxxx Logic module name for this DTF. If omitted, IOCS generates a standard name. The logic module is generated as part of the DTF. 0 RECFORM = xxxxxx (FIXUNB or UNDEF). If omitted, FIXUNB is assumed. 0 RECSIZE = (nn) Register number if RECFORM=UNDEF. General registers 2-12, written in parentheses. 0 TYPEFLE = xxxxxx (INPUT, OUTPUT, or CMBND). INPUT processes both input and output. CMBND must be specified for PUTR macro usage. If omitted, INPUT is assumed. 0 WORKA=YES GET or PUT specifies work area. M = Mandatory; 0 = Optional Figure 2-4 DTFCN macro MODNAME=name This operand specifies the name of the logic module generated by this DTFCN macro. If this entry is omitted, standard module names are generated for the logic module. A module name must be given when two phases (each containing a DTFCN macro) are link-edited into the same program. Under such conditions, omission of this operand results in unresolved address constants. RECFORM={FIXUNB I UNDEF} This operand specifies the record format of the file: fixed length or undefined. FIXUNB must be specified if TYPEFLE=CMBND is specified. FIXUNB is assumed if the RECFORM operand is omitted. RECSIZE=(r) For undefined records, this operand is required for output files and is optional for input files. It specifies a general register (2-12) that contains the length of the record. On output, you must load the length of each record into the designated register before you issue a PUT macro. If specified for input files, IOCS provides the length of the record transferred to storage. TYPEFLE={INPUT I OUTPUT I CMBND} This operand specifies a file as input, output, or combined. If INPUT is specified, code is generated for both input and output files. If OUTPUT is specified, code is provided for output files only. CMBND must be specified if you use the PUTR macro. CMBND specifies that coding be generated for both input and output files; in addition, coding is generated to allow usage of the PUTR macro to ensure that messages requiring operator action are Part 2. Sequential Access Metho.~ ~ 43 not deleted from the console. When CMBND is specified, DEVADDR=SYSLOG must also be specified. WORKA=YES This operand indicates that a work area is used with the file. A GET or PUT macro moves the record to or from the work area. A PUTR macro moves the record from and to the work area. DTFDI Macro The DTFDI macro provides device independence for system logical units. If several DTFDI macros are assembled within one program and all of them have the same RDONL Y condition, only one logic module (DIMOD) is required. Therefore, DTFDI processing requires fewer parameters and less storage than multiple LIOCS macros. It allows you to change device assignments without reassembling the logic module. The DTFDI macro should always be used to read SYSIPT data if the program migth be invoked by a catalogued procedure. The restrictions on DTFDI processing are: • Only fixed unblocked records are supported. • Only forward reading is allowed. • In a multivolume diskette file, new volumes are fed automatically. • The last volume of a multivolume diskette output file will be ejected automatically, but the last volume of a multivolume diskette input file will not. • If DTFDI is used with diskettes, special records (deleted or sequentially relocated records) on input files are skipped and not passed to the user. • Rewind options are not provided. • Combined file processing is not supported for reader-punches. Reading of cards is restricted to the first 80 bytes per card. • 44 The CNTRL and PRTOV macros cannot be used with this macro. DOS/VS Supervisor and I/O Macros • Reading, writing, or checking of standard or user-standard labels for tape/disk is not supported. • If ASA control character code is used in a multitasking environment and more than one DTF uses the same module with RDONL Y = YES, overprinting may occur. If DTFDI is used with DASD or diskettes, FOPT SYSFIL must have been specified at system generation time. The symbolic name of the file should be entered in the name field and DTFDI in the operation field. The entries for the DTFDI macro are discussed here and summarized in Figure 2-5. DEVADDR= {SYSIPT I SYSLST I SYSPCH I SYSRDR} This operand must specify the symbolic unit associated with this system file. Only the system names shown above may be specified. The logical device SYSLST must not be assigned to the 2560 or 5425. EOFADDR = name This operand must specify the name of your end-offile routine. It is required only if SYSIPT or SYSRDR is specified. IOCS branches to this routine when it detects an end-of-file condition. In this routine, you can perform any operations necessary for the end-of-file condition (you generally issue the CLOSE or CLOSER macro). IOCS detects the end-of-file condition by recognizing the characters /* in positions 1 and 2 of the record for cards, a tapemark for tape, and a file mark for disk. If the system logical units SYSIPT and SYSRDR are assigned to a 5425, IOCS requires that the /* card, indicating end-of-file, be followed by a blank card. An error condition results if the records are allowed to run out without a /* card (and without a / & card, if end-of-job). IOCS detects the end-of-file condition on diskette units by recognizing that end-of -data has been reached on the current volume and that there are no more volumes available. = SYSxxx (SYSIPT, SYSLST, SYSPCH, or SYSRDR). System logical unit. M DEVADDR M IOAREAl 0 EO FAD D R 0 ERROPT 0 IOAREA2 0 10REG 0 MODNAME 0 RDONLY = YES Generates a read-only module. Requires a module save area for each task using the module. 0 RECSIZE = nnn No. of chars. in record. Assumed values: 121(SYSLST), 81 (SYSPCH), 80( otherwise). 0 SEPASMB 0 WLRERR = xxxxxxxx = xxxxxxxx = xxxxxxxx = xxxxxxxx = (nn) = xxxxxxxx = YES = xxxxxxxx Name of first I/O area. Name of your end-of-file routine. (IGNORE, SKIP, or name of your error routine). Prevents termination on errors. If two I/O areas are used, name of second area. Register number. If omitted and 2 I/O areas are used, register 2 is assumed. General registers 2-12, written in parentheses. DIMOD name for this DTF. If omitted, 10CS generates a standard name. DTFDI to be assembled separately. Name of your wrong I~ngth record routine. M=Mandatory; O=Optional Figure 2-5 DTFDI macro ERROPT={IGNORE I SKIP rnameI This operand does not apply to output files. For output files for most devices, the job is automatically terminated after IOCS has attempted to retry writing the record; for 2560 or 5425 output files, normal error recovery procedures are followed. This operand does, however, apply to wrong-length records if WLRERR is omitted. If both ERROPT and WLRERR are omitted and wrong-length records occur, IOCS ignores the error. ERROPT specifies the function to be performed for an error block. If an error is detected when reading a magnetic tape, a disk pack, or a diskette volume, IOCS attempts to recover from the error. If the error is not corrected, the job is terminated unless this operand is included to specify other procedures to be taken. The three specifications are described below. IGNORE indicates that the error condition is to be ignored. The address of the error record is made available to you for processing (see CCB Macro in the chapter Physical IOCS). SKIP indicates that the error block is not to be made available for processing. The next record is read and processing continues. name indicates that IOCS is to branch to your routine when an error occurs, where you may perform whatever functions desired or note the error condition. The address of the error record is supplied in register 1. The contents of the IOREG register may vary and should not be used for error records. Also, you must not issue any GET instructions in your error routine. If you use any other IOCS macros, you must save the contents of register Part 2. Sequential Access Method 45 14. If RDONL Y = YES is specified, you must also save the contents of register 13. At the end of the error routine, return to IOCS by branching to the address in register 14. The next record is then made available for processing. task. The fact that the save areas are unique for each task makes the module reentrant (that is, capable of being used concurrently by several tasks). For more information see Shared Modules and Files in the Multitasking Macros chapter. If an ERROPT or WLRERR routine issues I/O IOAREAl =name This operand must specify the name of the input or output area used with the file. The input and/or output routines transfer records to or from this area. If the DTFDI macro is used to define a printer file, or a card file to be processed on a 2540, 2560, 3525, or 5425, the first byte of the output area must contain a control character. IOAREA2=name Two input or output areas can be allotted for a file to permit overlapped GET or PUT processing. If this operand is included, it specifies the name of the second I/O area. IOREG=l(r) I (2)} When two I/O areas are used, this operand specifies the general purpose register (2-12) that points to the address of the next record. For input files, it points to the logical record available for processing. For output files, it points to the address of the area where you can build a record. If omitted, and two I/O areas are used, register 2 is assumed. MODNAME=name This operand may be used to specify the name of the logic module used with the DTF table to process the file. If the logic module (DIMOD) is assembled with the program, the MODNAME parameter in this DTF must specify the same name as the DIMOD macro. If this entry is omitted, standard names are generated for calling the logic module. If two different DTF macros call for different functions that can be handled by a single module, only one standardnamed module is called. RDONLY=YES This operand is specified if the DTF is to be used with a read-only module. Each time a read-only module is entered, register 13 must contain the address of a 72-byte double word-aligned save area. Each task should have its own uniquely defined save area, and each time an imperative macro (except OPEN, OPENR or LBRET) is issued, register 13 must contain the address of the save area associated with that 46 DOS/VS Supervisor and I/O Macros macros using the same read-only module that caused control to pass to either error routine, the program must provide another save area. One save area is used for the initial I/O operations, and the second for I/O operations in the ERROPT or WLRERR routine. Before returning to the module that entered the error routine, register 13 must be set to the save area address originally specified for the task. If the operand is omitted, the module generated is not reenterable and no save area need be established. RECSIZE=n This operand specifies the length of the record. For input files (SYSIPT and SYSRDR), the maximum allowable record size is 80 bytes. For output files, RECSIZE must include one byte for control characters. The maximum length specification is 121 for SYSLST and 81 for SYSPCH. For printers and punches, DIMOD assumes a System/370 control character if the character is not a valid ASA character. The program checks ASA control characters before System/370 control characters. Therefore, if it is a valid ASA control character (even though it may also be a System/370 control character), it is used as an ASA control character. Otherwise, it is used as a System/370 control character. Control character codes are listed in Appendix A, except for the following: • 2520 stacker selection codes must be used for the 1442. • 2540 stacker selection 3 must not be used if device independence is to be maintained. If this operand is omitted, the following is assumed: 80 bytes for SYSIPT 80 bytes for SYSRDR. 81 bytes for SYSPCH. 121 bytes for SYSLST. The use of assumed values for the RECSIZE ope- I rand assures device independence. For disk and disk- ette files, the assumed values are required to assure device independence. SEPASMB=YES Include this operand only if the DTFDI is assembled separately. This causes a CATALR card with the filename to be punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. I WLRERR = name This entry applies only to input files on devices other than diskette units. It specifies the name of your routine to which 10CS branches if a wrong-length record is read on a tape or disk device. Because only fixed-length records are allowed, a wrong-length record error condition results when the length of the record read is not equal to that specified in the RECSIZE operand. If the length of the record is less than that specified in the RECSIZE operand, the first two bytes of the CCB (first 16 bytes of the DTF) contain the number of bytes left to be read (residual count). If the length of the record to be read is larger than that specified in the RECSIZE operand, the residual count is set to zero and there is no way to compute its size. The number of bytes transferred is equal to the value of the RECSIZE operand, and the remainder of the record is truncated. The address of the record is supplied in register 1. In your routine, you can perform any operation except issuing another GET for this file. Also if you use any other 10CS macros in your routine, you must save the contents of register 14. If RDONLY =YES, you must save the contents of register 13 as well. At the end of the routine, you must return to 10CS by branching to the address in register 14. When control returns to your program, the next record is made available. If this operand is omitted but a wrong-length record is detected by 10CS, the action depends on whether the ERROPT operand is included. • If the ERROPT operand is included, the wrong- length error record is treated as an error record and handled according to the ERROPT parameter. • If the ERROPT operand is omitted, 10CS ig- nores wrong-length errors and the record is made available to you. If, in addition to a wrong- length record error, an irrecoverable parity error occurs, the job is terminated. DIMODMacro Listed here are the operands you can specify for DIMOD. The header card contains DIMOD in the operation field and may contain a module name in the name field. If the module name is omitted, 10CS generates a standard module name. IOAREA2=YES Include this operand if a second I/O area is needed. A module with this operand can be used with DTFDls specifying either one or two I/O areas. If the operand is omitted or is invalid, one I/O area is assumed. RDONLY=YES This operand causes a read only module to be generated. Whenever this operand is specified, any DTF used with the module must have the same operand. SEPASMB=YES Include this operand only if the module is assembled separately. This causes a CATALR card with the module name (standard or user-specified) to be punched ahead of the object deck and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. TYPEFLE={OUTPUT I INPUT} Include this operand to specify whether the module is to process input or output files. If OUTPUT is specified, the generated module can process both input and output files. Standard DIMOD Names Each name begins with a 3-character prefix (IJ1) followed by a 5-character field corresponding to the options permitted in the generation of the module. DIMOD name = IJJabcde a = F b=C c = B TYPEFLE=OUTPUT(processes both input and output) d = I TYPEFLE=INPUT =I =Z IOAREA2=YES IOAREA2=YES is not specified e = C RDONLY=YES Part 2. Sequential Access Method 47 = D RDONLY=YES is not specified Subset/Superset DIMOD Names The following diagram illustrates the sub setting and supersetting allowed for DIMOD names. All of the variable entries allow subsetting. A module name specifying B is a superset of the mod Jle specifying I; for example, IJJFCBID is a superset of the module IJJFCIID. See IOeS Subset/Superset Names in The Macro System chapter. DEVADDR=SYSnnn Specifies the symbolic unit to be associated with the logical file. The symbolic unit (SYSnnn) is associated with an actual I/O device through the job control ASSGN statement. FRNAME= phasename Specifies the phase name of the format record to be loaded when the file is opened. DTFDR Macro FRSIZE= numbel Specifies the number of bytes to be reserved in the DTF expansion for format records. The number must equal at least the size of the largest DFR macro expansion and its associated DLINT macro expansions, plus four. This size is printed in the ninth and tenth bytes of the DFR macro expansion. For a description of these macro expansions, see DOS/VS LIOeS Volume 2, SAM, SY33-8560. You must use the DTFDR macro to define each 3886 file in your program. This macro defines the characteristics of the file, the format record to be loaded into the 3886 when the file is opened, and the storage areas and routines used. Enter the symbolic name of the file in the name field and DTFDR in the operation field. The entries of the DTFDR Macro are discussed here and illustrated in Figure 2-6. If you use the SETDEV macro in your program to change format records, you can reduce the library retrieval time by specifying a size large enough to contain all the frequently used format records. The area should then be equal to the sum of the format record sizes, plus four bytes for each format record. When the SETDEV macro is issued, the format record is loaded into this area from the core image library if it is not already present in the area. ++* I\.TJFCB IC I Z D + Subsetting/supersetting permitted. * No subsetting/supersetting pennitted. Besides the DTFDR Macro, the following declarative macros are required for a 3886 file: DRMOD Generate the logic module to process the file. DFR Define attributes common to a group of lines described in one format record. DLINT Describes the individual line in the format record. 48 DOS/VS Supervisor and I/O Macros EXITIND=name Specifies the symbolic name of the one-byte area in which the completion code is returned to the COREXIT routine for error handling from an I/O operation. M DEV ADDR = SYSxxx Symbolic unit assigned to 3886 optical character reader. M FRNAME = xxxxxxxx Phase name of format record to be loaded upon file opening. M FRSIZE Number of bytes to be reserved in DTF expansion for format records. M EXITIND = xxxxxxxx Name of completion code return area. M IOAREAl Name of file input area. M HEADER = xxxxxxxx Name of area for header record from 3886. M EO FAD D R = xxxxxxxx Address of your end-of-file routine. M COREXIT = xxxxxxxx Name of your error condition routine. 0 DEVICE = 3886 If omitted, 3886 is assumed. 0 RDONLY=YES If DTF is to be used with read-only module. 0 MODNAME = xxxxxxx Name of DRMODxx logic module for this DTF. If omitted, IOCS generates standard name. 0 BLKSIZE = nnn Length of area named by IOREG 1. If omitted, the maximum length of 130 is assumed. 0 SEPASMB =YES If DTFDR is to be assembled separately. 0 SETDEV = YES If SETDEV macro is issued in your program to load a different format record into the 3886. = nn = xxxxxxxx M=Mandatory; O=Optional Figure 2-6 DTFDR macro operands The meanings of the completion codes are: Code X'FO' X'Fl' X'F2' X'F3' X'F4' X'F9' Meaning No errors occured. (This code should not be present when the eOREXIT routine receives control.) Line mark station timing mark check error. Nonrecovery error (operator intervention is required). Incomplete scan. Line mark station timing mark check and equipment check. Permanent error. Note: If any of these errors occur while the file is being opened, the eOREXIT routine does not receive control and the job is canceled. IOAREAt =name Specifies the symbolic name of the input area to be used for the file. The area must be as large as the size specified in the BLKSIZE parameter. If BLKSIZE is not specified, the input area must be 130 bytes. HEADER = name Specifies the symbolic name of the 20-byte area to receive the header record from the 3886. EOFADDR=name Specifies the symbolic address of your end-of-file routine. LIOeS branches to this routine whenever end of file is detected on the 3886. Part 2. Sequential Access Method 49 Permanent error COREXIT=name Provides the symbolic name of your error correction routine. LIOeS branches to this routine whenever an error is indicated in the EXITIND byte. Note: If any of these errors occur while the file is being opened, the COREXIT routine does not receive control and the job is canceled. You can attempt to recover from various errors that occur on the 3886 through the COREXIT routine you provide. Your COREXIT routine receives control whenever one of the following conditions occurs: Figure 2-7 describes normal functions for the COREXIT routine for the various error conditions and provides the exits that must be taken from the COREXIT routine. • • • Error messages are provided to describe errors to the operator during program execution. Incomplete scan Line mark station timing mark check error Nonrecovery error Error Normal COR EXIT Function Exit to X'P2' Eliminate the data that has been read from this document and prepare to read the next input document (See Note I). Routine in your program to read the next document. X'P4' or X'P9' Do whatever processing is necessary before the job is canceled. (See Note 1). Your end-of-job routine. X'PI' Do any processing that may be required. The document may have been read incorrectly; you may want to delete all data records from the document (see Note 2). Branch to the address in register 14 to return to the instruction following the macro causing the error. X'P3' Rescan the line using another format record or using image processing and editing the record in your program (see Note 2). Branch to the address in register 14 to return to the instruction following the macro causing the error. Note 1: If in your COREXIT routine, you issue an I/O macro to the 3886 and an error occurs during that operation, control is returned to the beginning of the COREXIT routine. You must take precautions in the COREXIT routine to prevent looping in this situation. If no errors occur, control returns to the instruction following the I/O macro. Note 2: If, in your COREXIT routine, you issue an I/O macro to the 3886, control always returns to the instruction following the macro. You should then check the completion code to determine the outcome of the operation. Figure 2-7 cOREXIT routine functions 50 DOS/VS Supervisor and I/O Macros DEVICE=3886 Indicates that 3886 is the I/O device for this file. If this parameter is omitted, 3886 is assumed. RDONLY=YES This operand is specified if the DTF is used with a read-only module. Each time a read-only module is entered, register 13 must contain the address of a 72-byte doubleword-aligned save area. Each DTF should have its own uniquely defined save area. Each time an imperative macro (except OPEN, OPENR, LBRET, SETL, or SETFL) is issued using a particular DTF, register 13 must contain the address of the save area associated with that DTF. The fact that the save areas are unique or different for each task makes the module reentrant (that is, capable of being used concurrently by several tasks). For more information see Shared Modules and Files in the Multitasking Macros chapter. If a COREXIT routine issues I/O macros using the same read-only module that caused control to pass to either error routine, your program must provide another save area. One save area is used for the normal I/O operations, and the second for I/O operations in the COREXIT routine. Before returning to the module that entered the COREXIT routine, register 13 must contain the save area address originally specified for that DTF. Note: DOS/VS LIOCS does not allow you to block records read from the 3886. SEPASMB=YES Specifies the DTF is assembled separately. If this operand is specified, a CAT ALR card with the filename is punched before the deck and defines the filename as an entry point for the assembly. SETDEV=YES Specifies that the SETDEV macro is issued in your program to load a different format record into the 3886. DRMODMacro Listed here are the operands you can specify for DRMOD. The first card contains DRMOD in the operation field and may contain a module name in the name field. DEVICE=3886 Specifies that the 3886 is the input device. If this parameter is omitted, the 3886 is assumed. SEPASMB=YES Must be specified if the I/O module is assembled separately. This entry causes a CAT ALR card to be punched preceding the module. If this operand is omitted, the module generated is not reenterable, and no save area is required. MODNAME = name This operand may be used to specify the name of the logic module used with the DTF table to process the file. If the logic module (DRMOD) is assembled with the program, the MODNAME parameter in this DTF must specify the same name as the DRMOD macro. If this entry is omitted, standard names are generated for calling the logic module. If two different DTF macros call for different functions that can be handled by a single module, only one standardnamed module is called. BLKSIZE=nnn Specifies the length of the area named by the IOAREA1 keyword. The length of the area must be equal to the length of the longest record to be passed from the 3886. If this operand is omitted, the maximum length of 130 is assumed. RDONLY=YES This operand generates a read only module. RDONLY=YES must be specified in the DTF. For additional programming requirements concerning this operand, see the DTFDR RDONL Y operand. SETDEV=YES Is specified if the SETDEV macro may be used when processing a file with this I/O module. If SETDEV=YES is specified in the DRMOD macro but not in the DTFDR macro, the SETDEV macro cannot be used when processing that file. Standard DRMOD Names Each name consists of eight characters. They are: IJMZxxDO. The fifth and sixth characters are variables as follows: If SETDEV =YES is specified, the fifth charac- ter is S; otherwise it is Z. • If RDONLY = YES is specified, the sixth charac- ter is R; otherwise it is Z. Note: Subsetting/ supersetting is allowed with the Part 2. Sequential Access Method 51 SETDEV keyword, but not with the RDONL Y keyword. DFR Macro Two macros are provided for defining documents. One, the DFR macro, defines attributes common to a group of line types. The other, the DLINT macro, defines specific attributes of an individual line type. As many as 26 DLINT macros can be associated with one DFR macro as long as the number of line types plus the number of fields is less than or equal to 53. The DFR and associated DLINT macros are used in one assembly to build a format record module. Only one DFR with its associated DLINT macros may be specified in each assembly, and the DFR must precede all DLINT macros in the assembly. The format record must be link-edited into the core image library so that it can be loaded into the 3886 when the file is to be processed. The format record defines the types of lines to be read, the fields on the lines, the editing functions to be used, and the format of the data record to be passed to your program. For an example of how to build a format record using DFR and DLINT macros, see Appendix B.l: Assembling a Format Record for the 3886 Optical Character Reader. The format record is loaded into the 3886 during program execution. The initial format record is load- 52 DOS/VS Supervisor and I/O Macros ed when the file is opened and new format records can be loaded using the SETDEV macro. The DFR macro defines attributes common to a group of line types described by one format record. DLINT macros describe the individual lines. The DFR macro is specified first and provides the following information for the format record: • Default font • Reject character • Group and character erase symbol usage National symbol set option • Edit characters Serial and batch number control National numeric hand print (NHP) character set options For more information on any of these topics, see the discussion for the appropriate parameter. The format of the DFR macro is shown in Figure 2-8. here are the operands you can specify for DFR. The header card contains DFR in the operation field and may contain a module in the name field. If the module name is omitted, IOCS generates a standard module name. M FONT = xxxx Default font for all codes described by format record. 0 REJECT = x Replacement character for any reject character in the data record read by the 3886. If omitted, X'3F' is assumed. 0 ERASE = YES Group and character erase symbols are to be recognized. If omitted, NO is assumed. 0 CHRSET = n Specifies recognizing character (see Figure2-9 ). If omitted, 0 is assumed. 0 EDCHAR = (x, ... ) Characters that may be deleted from any field that is read. If omitted, no character deletion occurs. 0 BCH =n Batch numbering is to be performed by 3886. If used, BCHSER is invalid. 0 BCHSER = n Both batch and serial numbering are to be performed. If specified, BCH is invalid. 0 NATNHP=YES European Numeric Hand Printing (ENHP) characters 1 and 7 are used. If omitted, NO is assumed, indicating that Numeric Hand Printing (NHP) character 1 + 7 are used. M=Mandatory; O=Optional Figure 2-8 DFR macro operands OCR-A OCR-B Alphameric Mode Numeric Mode Alphameric Modes Numeric Mode Highspeed Printers or Typewriters Mode 1 (Highspeed) Printer) Highspeed Printers or Typewriters Mode 2 (Typewriter) $ £ $ $ $ $ i ¥ i ¥ N i ¥ N $ $ $ A A J\ *- *~ If 0 $ $ U Note A A :( ~ ij t5 0 0 ~ $ ¥ £ ¥ N $ $ Hexadecimal Code Format Record Codes 58 58 58 78 58 58 78 7C 58 78 7C 00 01 02 FO 05 03 04 Note: In OCR-A font the U is coded as a zero and should be used only in alphabetic fields. Figure 2-9 Character set option list Part 2. Sequential Access Method 53 FONT=code Specifies the default font for all fields described by the format record. The default font is used to read a field unless another font is specified for an individual field through the DLINT macro. This is the only required operand in the DFR macro. The valid codes and the fonts they represent are: Code Font NUMA Numeric OCR-A font ANAl Alphameric OCR-A font (mode 1) ANA2 Alphameric OCR-A font (mode2) NUMB Numeric OCR-B font (mode3) ANB1 Alphameric OCR-B font NHP1 Numeric hand printing (normal mode) NHP2 Numeric hand printing (verify mode) GOTH Gothic font MRKA Mark OCR-A font MRKB Mark OCR-B font For a description of these fonts, see IBM 3886 Optical Character Reader Component Description and Operating Procedures, GA21-9147. REJECT = character Indicates the character that is to be substituted in the data record for any reject character read by the device. If this parameter is omitted, X'3F' is assumed. Reject characters are characters that are not recognizable by the device. Note: This note applies to the keywords REJECT and EDCHAR. Apostrophes enclosing the character are optional for all characters except special characters used in macro operands. For a description of these characters, see OS/VS and DOS/VS Assembler Language, GC33-4010. ERASE={YES I NO} Specifies whether group and character erase symbols are to be recognized as valid symbols. If this operand is not specified, NO is assumed. For more information on group and character erase symbols, see IBM 3886 Optical Character Reader Component Description and Operating Procedures, GA21-9147. 54 DOS/VS Supervisor and I/O Macros CHRSET = t!! It I 2 I 3 I 4 I S} Specifies which one of the options shown in Figure 2-9 is to be used for recognizing characters. If this operand is not entered, 0 is assumed. EDCHAR=(x, ... ) Specifies up to six characters that may be deleted from any field that is read. The EDCHAR parameter in the EDITn keyword in the DLINT macro controls this function for individual fields. If this operand is omitted, no character deletion is performed. See the note under the REJECT parameter for characters that must be specified in quotes. For example, to specify the characters &, >, and ), you would code EDCHAR=(' & ','>',')'). BCH=U 1213} Indicates that batch numbering is to be performed by the 3886. Specifying 1, 2, or 3 indicates that documents routed to a stacker are to be batch numbered. Specifying 1 indicates stacker A, 2 indicates stacker B, 3 indicates both stackers. If this operand is entered, the BCHSER operand is invalid. If neither BCH nor BCHSER are entered, no batch numbering is performed. This parameter is valid only if the serial numbering feature is installed on the 3886. For more information on batch numbering, see IBM 3886 Optical Character Reader Component Description and Operating Procedures, GA21-9147. BCHSER={l I 2 I 3} Indicates that both batch and serial numbering are to be performed by the 3886. Specifying 1,2, or 3 indicates that documents routed to a stacker are to be batch and serial numbered. Specifying 1 indicates stacker A, 2 indicates stacker B, 3 indicates both stackers. If this operand is entered, the BCH operand is invalid. If this operand is omitted, batch and serial numbering are not performed. This parameter is valid only if the serial numbering feature is installed on the 3886. For more information on batch and serial numbering, see IBM 3886 Optical Character Reader Component Description and Operating Procedures, GA21-9147. NATNHP={YES I NO} Specifies which of the numeric hand printing character set options are used for the numbers 1 and 7. YES indicates that the European Numeric Hand Printing (ENHP) characters 1 and 7 are used; NO indicates the Numeric Hand Printing (NHP) characters 1 and 7 are used. If this operand is not entered, NO is assumed. M LFR = nn Line format record for this line. M LINBEG = nn Specifies beginning of a line. 0 IMAGE = YES Data record is to be in image mode. If omitted, NO (standard mode) is assumed. 0 NOSCAN = (n,n) Indicates an area on the document line that is to be ignored by the 3886. 0 FLDn = (n,n,NCRIT,xxx) Describes a field in a line. n in the FLD keyword may be from 1 to 14, if specified, a corresponding EDITn keyword must follow each FLDn keyword. 0 EDITn = (xxxxxx,EDCHAR) Specifies editing functions to be performed on the data by 3886. A corresponding FLDn keyword must precede each EDITn keyword. 0 FRENO = YES Indicates last DLINT macro for the format record. If omitted, NO is assumed meaning that further DLINT macros follow. M=Mandatory; O=optional Figure 2-10 DLiNT macro operands Part 2. Sequential Access Method 55 DLINT Macro The DLINT macro describes one line type in a format group and the individual fields in the line. As many as 26 DLINT macros can be associated with one DFR macro. The DLINT macro provides line and field information: Line information applies to the entire line; field information describes each of the fields on the line. Up to 14 fields can be scanned on each line. The format of the DLINT macro is shown in Figure 2-10. Listed here are the operands you can specify for DLINT. The header card contains DLINT in the operation field and may contain a module field. If the module name is omitted, IOCS generated a standard module name. Line Information Entries LFR=number This operand is required. It specifies, the line format record number for the line. The decimal number specified must be in the range of 0 through 63. The line format record describes the format of one type of line, the line format record number is used to identify the line format record. This number is specified in the READ macro when you read a line of data from a document. LINBEG=number This operand is required. It specifies the beginning of a line. The beginning position is the number of tenths of an inch from the left edge of the document to the left boundary of the first field. The limiting range of this position is 4 to 85. IMAGE = {YES I NO} This operand specifies whether the data record should be in standard mode (IMAGE=NO), or image mode (IMAGE=YES). If this operandJs not specified, IMAGE=NO is assumed. When the standard format is used (IMAGE=NO), all parameters in the DLINT macro are valid. The data read from the document line is edited as specified in the EDITn keywords, the fields in the data record are created as specified in the FLDn keywords, and the standard mode data record then contains fixed-length fields of edited data. The sequence of operations used to build the standard mode data record in the 3886 is: 56 DOS/VS Supervisor and I/O Macros 1. Recognition of all the characters in the record takes place. 2. Reject characters are removed and the reject code is substituted. 3. Edit characters (specified by the EDCHAR keyword in the DFR macro) are removed from the data (as specified by the EDITn keywords in the DLINT macro). 4. Blanks are removed from the data as specified by the EDITn keywords in the DLINT macro. 5. The length of the fields is checked against the field length specified, the fields are left- or rightjustified and padded or truncated as specified in the DLINT macro, and error indicators are set if errors have been detected. When the image mode is used (IMAGE=YES), all EDITn keywords and the field length parameter in the FLDn keyword are invalid. The image mode data record then contains 14 two-byte field length entries followed by the data fields. Image mode is provided to support exception application requirements where the standard fixed-field edited format does not suffice. It is also applicable for error handling purposes by rereading the same line. The sequence of operations used to build the image mode data record in the 3886 is: 1. Recognition of all the characters in the record takes place. 2. Reject characters are removed and the reject code is substituted. 3. Each field read and the field lengths are placed in the data record. NOSCAN = (field-end, ... ) Specifies an area on the document line that is to be ignored by the 3886. Field-end is a decimal number indicating the number of tenths of an inch from the left edge of the document to the right end of the NOSCAN field. The field immediately to the left of the NOSCAN field must end with an address delimiter rather than a character delimiter. Field Information Entries FLDn= ({address-delimiter I character-delimiter} [,field-lengthll,{NCRIT I font-code I NCRIT,font-code}) Describes each of the fields in a line. The n suffix is a number from 1 through 14 and the parameters are the same for keywords FLD1 through FLD14. The following rules apply when specifying these keywords: • Fields may be described in any order in the macro. • Each EDITn parameter must follow its associated FLDn parameter. • The n suffix need not be 1 for the first field in the line; however, the n suffix must increase for each field from left to right on the document line. address-delimiter is a decimal number that specifies the number of tenths of an inch from the left edge of the document to the right end of the field being defined. The last field in a line must end with an address delimiter. character delimiter specifies the character that indicates the end of a field. The character delimiter is not considered part of the data; it is not included in the data record nor used in determining the length of the field. Apostrophes enclosing the characters are optional for all characters except 0-9, and the special characters used in macro operands. For these characters, the apostrophes are required. For a description of these characters, see OS / VS and DOS / VS Assembler Language, GC33-401:0. If a field ends with a character delimiter, the next field must be read using a font from the same font group. The font groups are: • NPH1, NPH2, GOTH • ANAl, ANA2, NUMA, MRKA • NUMB,MRKB • ANB1 field-length is a decimal number specifying the length of the field in the edited record. The length specified cannot be less than 1 or more than 127. If IMAGE=NO is specified, this parameter is required; if IMAGE= YES is specified, this parameter is invalid. The length specified in this parameter refers to the length of the field after any EDITn options have been performed. The sum of the field lengths for a line cannot be greater than 130. NCRIT indicates that this is not a critical field. If this parameter is omitted, the field is assumed to be critical. font-code specifies a font for this field, different from the font specified in the DFR macro. If this parameter is not specified, the font specified in the DFR macro is used for the field. For information about the valid codes, see the DRF macro descriptions. EDITn=({code I ED CHAR I code,EDCHAR}) Describes the editing functions to be performed on the data by the 3886. The parameters are the same for keywords EDIT1 through EDIT14. There must be a FLDn keyword corresponding with each EDITn keyword you specify. If an EDITn keyword is specified, a code, EDCHAR, or both must be specified. When image mode is used, the EDITn keywords are invalid. When the editing functions are completed and the field is greater than the specified length, the field is truncated from the right and the wrong length field indicator is set on in the header record. If only blanks are truncated, the wrong length field indicator is not set. code specifies the blanks to be removed and the fill characters to be added to the field, if any. The valid codes and their meanings are: Code Meaning HLBLOF All high- and low-order blanks are removed, the data is left justified, and the field is padded with blanks on the right (see Note). ALBLOF All blanks are removed from the data, the data is left-justified, and the field is padded with blanks on the right. NOBLOF No blanks are removed, the data is leftjustified, and the field is padded on the right with blanks. HLBHIF All high- and low-order blanks are removed, the data is right-justified, and the field is padded to the left with EBCDIC zeros (X'FO') (see Note). ALBHIF All blanks are removed, the data is rightjustified, and the field is padded with EBCDIC zeros (X'FO') on the left. Part 2. Sequential Access Method 57 ALBNOF All blanks are removed; the data must be equal in length to the field length specified. No padding is done. Note: Two consecutive embedded blanks is the maximum number sent. If the EDITn keyword is omitted or if EDITn is specified and the code is omitted, ALBLOF is assumed. EDCHAR indicates that the characters specified in the EDCHAR keyword of the DFR macro are to be deleted from the field. If this parameter is omitted, the characters are not deleted. FREND={YES I NO} Indicates whether this is the last DLINT macro for the format record. NO indicates more DLINT macros follow; YES indicates this is the last one. If this keyword is omitted, NO is assumed. DTFDU Macro The DTFDU macro defines sequential (consecutive) processing for a file contained on a diskette. Note that special records (deleted or sequential relocated records) on an input file are skipped, and not passed to the user. The DTFDU macro cannot be used when a diskette file is to be processed under POWER. In this case, use the DTFDI macro. A DTFDU entry is included for each sequential input or output diskette file processed in the program. The DTFDU header entry and a series of detail entries describe the file. Enter the symbolic name of the file in the name field and DTFDU in the operation field. The detail entries follow the DTFDU header card in any order. The entries for the DTFDU macro are discussed here and are summarized in Figure 2-11. CMDCHN=nn This operand is specified to indicate the number of Read/Write CCWS to be command chained. Valid entries are 1, 2, 13, or 26; 1 is assumed if this entry is omitted. For each CCW specified by this operand, one record is processed (for example, if CMDCHN = 13, 13 records are command chained and are processed -- read or written -- as a group). For entries of 2, 13, or 26, either the 10REG operand or the WORKA operand must be specified. 58 DOS/VS Supervisor and I/O Macros DEVADDR=SYSxxx This operand specifies the symbolic unit (SYSxxx) associated with the file if an extent statement specification is not provided. And EXTENT statement is not required for single-volume input files. If an EXTENT statement is provided, its specification overrides any DEVADDR specification. SYSxxx represents an actual I/O device address, and is used in the ASSGN job control statement to assign the actual I/O device address to this file. A list of symbolic units applying to DTFDU can be found in the Symbolic Unit Addresses section of The Macro System chapter. DEVICE = 3540 This operand specifies that the file to be processed is on the 3540. If this parameter is unspecified, the 3540 is assumed. EOFADDR=name This operand specifies the symbolic name of your end-of-file routine. 10CS automatically branches to this routine on an end-of-file condition. You can perform any operations required for the end-of-file in this routine (you will generally issue the CLOSE or CLOSER macro). ERREXT=YES This operand enables your ERROPT routine to return to DUMODFx with ERET macro. It also enables permanent errors to be indicated to your program. For ERREXT facilities, the EROPT operand must be specified. However, to take full advantage of this option give the ERROPT=name operand. ERROPT={IGNORE I SKIP I name} Specify this operand if you don't want a job to be terminated when a permanent error cannot be corrected in the diskette error routine. If attempts to reread a chain of records are unsuccessful, the job is terminated unless the ERROPT entry is included. Either IGNORE, SKIP, or the name of an error routine can be specified. The functions of these parameters are described below. IGNORE The error condition is ignored. The records are made available for processing. On output, the error condition is ignored and the records are considered written correctly. X M EOFADDR = xxxxxxxx Name of your end-of-file routine. (Required for input only) X X M IOAREA 1=xxxxxxxx Name of first I/O area X X M RECSIZE=nnn Length of one record in bytes X X 0 CMDCHN=nn Number of read/write CCWs (records) to be commandchained X X 0 DEY ADDR=SYSxxx Symbolic unit, required only when not provided on an EXTENT statement X X 0 DEYICE=3540 Must be 3540. If omitted, 3540 is assumed. X X 0 ERREXT=YES Indicates additional errors and ERET desired. Specify ERROPT X X 0 ERROPT=xxxxxxxx IGNORE, or SKIP, or name of error routine X X 0 FEED=xxx YES means feed at end-of-file. NO means no feed, YES assumed if omitted. X 0 FILESEC= YES YES means create file secure. X X 0 IOAREA2=xxxxxxxx Name of second I/O area, if two areas are used. X X 0 IOREG=(nn) Register number. Omit WORKA. General register 2 to 12 in parentheses. X X 0 MODNAME=xxxxxxxx Name of DUMODFx logic module for this DTF. If omitted, 10CS generates standard name. X X 0 RDONLY=YES Generates a read-only module. Requires a module save area for each task using the module. X X 0 SEPASMB=YES DTFDU is to be assembled separately. X X 0 TYPEFLE=xxxxxx INPUT or OUTPUT. If omitted, INPUT is assumed. 0 YOLSEQ=YES YES means OPEN is to check sequencing of multivolume files. X 0 WORKA=YES GET or PUT specifies work area. Omit IOREG. X 0 WRTPROT=YES File will be created with Write-Protect on (cannot be overwri tten). X X M=Mandatory; O=Optional Figure 2-11 DTFDU macro operands Part 2. Sequential Access Method 59 SKIP No records in the error chain are made available for processing. The next chain of records is read from the diskette, and processing continues with the first record of that chain. On output, the SKIP option is the same as the IGNORE option. name IOCS branches to your error routine named by this parameter regardless of whether or not ERREXT =YES is specified. In this routine you can process or make note of the error condition as desired. IF ERREXT is not specified, register 1 contains the address of the first record in the error chain. When processing in the ERROPT routine, reference records in the error chain by referring to the address supplied in register 1. The contents of the IOREG register or work area are variable and should not be used to process error records. Also, GET macros must not be issued for records in the error chain. If any other IOCS macros (excluding ERET if ERREXT = YES) are used in this routine, the contents of register 13 (with RDONL Y) and 14 must be saved and restored after their use. At the end of the routine, return control to IOCS by branching to the address in register 14. For a read error, IOCS skips that error chain of records, and makes the first record of the next chain available for processing in the main program. If ERREXT is specified, register 1 contains the ad- dress of a two part parameter list containing the 4-byte DTFDU address and the 4-byte address of the first record in the error chain. Register 14 contains the return address. Processing is similar to that described above except for addressing the records in error. At the end of its processing, the routine returns to LIOCS by issuing the ERET macro. For an input file • The program skips the error chain and reads the next chain with an ERET SKIP. • Or, ignores the error with an ERET IGNORE. • Or, it makes another attempt to read the error chain with an ERET RETRY. For an output file • The program ignores the error condition ERET IGNORE or ERET SKIP. • Or, attempts to write the error chain with an ERET RETRY macro. Bad spot control records 60 DOS/VS Supervisor and I/O Macros (1,2, 13, or 26 records depending on the CMDCHN Factor) are written at the current diskette address, and the write chain is retried in the next 1, 2, 13, or 26 (depending on the CMDCHN factor) sectors on the disk. Also, for an output file, the only acceptable parameters are IGNORE or name. The DTFDU error options are shown in figure 2-12. The figure is divided into two parts: the lower part lists the error conditions which you specify in the DTF, and the upper part shows the action resulting from these specifications when an error occurs. FILESEC=YES This operand applies to output only. On output it causes OPEN or OPENR to set the security flag in the file label. For subsequent input, the security flag causes an operator message to be written. The operator must then reply in order to make the file available to be read. FEED={YES I NO} If YES is specified for this operand, when end of file is reached, the diskette being processed is fed to the stacker and a new diskette is fed to the disk drive (providing another diskette is still in the hopper). If NO is specified, the diskette is left mounted for the next job. IOAREAl =oame This operand specifies the symbolic name of the 1/0 area used by the file. IOCS either reads or writes records using this area. Note that you should provide an 110 area equal in size to the result obtained from multiplying the RECSIZE entry by the CMDCHN entry. assembled with the program, MODNAME must specify the same name as the DUMODx macro. If this entry is omitted, standard names are generated for calling the logic module. If two DTF macros call for different functions that can be handled by a single module, only one module is called. Control Is passed to your error routine Error record is skipped Desired function Error record is ignored Error record is retri ed The job is terminated Specifications required in your Progrern ERROPT = SKIP ERROPT = IGNORE ERR OPT = name - '1 X XX X2 Xl X X X X X ERROPT = nerne ERET SKIP ERR OPT = name ERET IGNORE ERR OPT = name ERET RETRY None X X If an ERROPT routine issues I/O macros using the I Input files only 2 Output files only Figure 2-12 RDONLY=YES This operand is specified if the DTF is used with a read-only module. Each time a read-only module is entered, register 13 must contain the address of a 72 byte double-word aligned save area. Each task should have its own uniquely defined save area. When an imperative macro (except OPEN, OPENR) is issued, register 13 must contain the address of the save area associated with the task. The fact that the save areas are unique for each task makes the module reentrant (that is, capable of being used concurrently by several tasks). DTFDU error options IOAREA2=name If two I/O areas are used by GET or PUT, this ope- rand is specified. Note that you should provide an I/O area equal in size to the result obtained from multiplying the RECSIZE entry by the CMDCHN entry. IOREG=(r) This operand specifies the general purpose register (2-12) in which 10CS puts the address of the logical record that is available for processing. At OPEN or OPENR time, for output files, IOCS puts the address of the area where the user can build a record in this register. The same register can be used for two or more files in the same program, if desired. If this is done, the problem program must store the address supplied by IOCS for each record. If this operand is specified, omit the WORKA operand. This operand must be specified if the CMDCHN factor is more than one for either input or output and records are processed in one I/O area, or if two I/O areas are used and records are processed in both I/O areas. MODNAME=name This operand specifies the name of the logic module which is to process the file. If the logic module is same read-only module that caused control to pass to the error routine, your problem program must provide another save area. One save area is used for the normal I/O operations, and the second for input/ output operations in the ERR OPT routine. Before returning to the module that entered the ERROPT routine, register 13 must be set to the save area address originally specified for that DTF. If this operand is omitted, the module generated cannot be reentered and no save area need be established. RECSIZE=nnn This operand specifies (in bytes) the length of each record in the input/output area (1-128 bytes). SEPASMB=YES Include this operand only if the DTFDU is assembled separately. This causes a CATALR card with the filename to be punched ahead of the object deck and defines the filename as an entry point in the assembly. If the operand is omitted, the macro assumes that the DTF is being assembled with the problem program and no CAT ALR card is punched. TYPEFLE={INPUT I OUTPUT} This operand indicates whether the file is an input or output file. VOLSEQ=YES This operand is only valid on input. If specified, it causes OPEN or OPENR to ensure that the volume sequence numbers (if specified) of a multi-volume Part 2. Sequential Access Method 61 file are in ascending and sequential order. If the volume sequence number of the first volume processed is blank, no volume sequence checking is done. WORKA=YES If I/O records are processed, or built, in work areas instead of in the I/O areas, specify this operand. You must set up the work area in storage. The address of the work area, on a general register containing the address, must be specified in each GET or PUT macro. For a GET or PUT macro, IOCS moves the record to or from, the specified work area. When this operand is specified, the IOREG operand must be omitted. WRTPROT=YES This operand indicates that an output file will be created with Write-Protect (meaning that the file cannot be overwritten). For 3540 support, this has no affect on subsequent input processing of the file. DUMODFx Macro Two categories of file characteristics are defined for diskette unit module generation macros: • DUMODFI - Diskette Unit MODule, Fixed length records, Input file. DUMODFO - Diskette Unit MODule, Fixed length records, Output file. The macro operation and the keyword operands define the characteristics of the module. The operands for the two macros are explained in the following section. erated to handle any of the three options (IGNORE, SKIP, or name) regardless of which option is specified in the DTF. This module also processes any DTF in which the ERROPT operand is not specified. If this operand is not included, your program is canceled whenever a permanent error is encountered. RDONLY=YES This operand causes a read-only module to be generated. If this operand is specified, any DTF used with this module must have the same operand. SEPASMB=YES Include this operand only if the logic module is assembled separately. This causes a CAT ALR card with the module name (standard or user-specified) to be punched ahead of the object deck, and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the logic module is being assembled with the problem program and no CAT ALR is punched. Standard DUMOD Names Each name begins with a 3-character prefix (UN) and continues with a 5-character field corresponding to the options permitted in the generation of the module, as shown below. DUMODFx name = UNabcde a b = I DUMODFI = ERREXT=YES Include this operand if permanent errors are returned to a problem program ERROPT routine or if the ERET macro is used with the DTF and module. The ERROPT operand must be specified for this module. ERROPT=YES This operand applies to both DUMODFx macros. This operand is included if the module handles any of the error options for an error chain. Logic is gen- 62 DOS/VS Supervisor and I/O Macros ODUMODFO c = C ERROPT=YES and ERREXT=YES = E ERROPT=YES = Z neither is specified d DUMODFx Operands A module name can be contained in the name field of this macro. The macro operation is contained in the operation field, either DUMODFI (for input) or DUMODFO (for output). The operands are contained in the operand field. =D e = = = Z Y RDONLY=YES Z RDONL Y not specified Subset/Superset DUMOD Names The following diagram illustrates the sub setting and supersetting allowed for DUMOD names. * +* * o E Z I.JNDICZY Z + Subsetting/supersetting permitted. * No subsetting/supersetting permitted. DTFMR Macro DTFMR defines an input file processed on a 1255, 1259, or 1419 magnetic character reader, or a 1270 or 1275 optical character reader/sorter. Some general characteristics of such processing are discussed below before the parameters of the DTFMR macro are described. Characteristic of Magnetic Ink Character Reader (MICR) and Optical Reader/Sorter Processing Important general characteristics of Magnetic Ink Character Reader (MICR) and Optical Reader/Sorter processing are given in the DOS/VS Data Management Guide, GC33-5372. In addition, examples of GET-PUT document processing and multiple 1419 operation (either all single or dual) will be found in DOS/VS System Generation, GC33-5377. MICR Document Buffer The MICR Document Buffer provides you with processing status indicators and detected error indicators. Before you can begin any MICR programming, you must be aware of the purpose and format of this buffer. Figure 2-13 is a storage map of the document buffer. The minimum number of document buffers you may specify is 12, and the maximum number is 254. Before any data is read into the document buffer, logical IOCS sets the entire buffer, including the status indicators, to binary zeros. The processing macro-GET if your program uses one MICR device, or READ if your program uses more than one MICR device--then engages the device, and documents are read into the I/O area until the MI CR device is out of documents, or until the I/O area is filled. The external interrupt routine of the supervisor continually monitors the reading of data so that processing of other document buffers is never disrupted. At the completion of each read for a MICR document, the external interrupt routine interrupts your program to give control to your stacker selection routine which then determines pocket selection for that document. Stacker Selection Routine for MICR Your stacker selection routine resides in your program area and gains control of the system whenever a document is ready to be stacker selected. This routine determines the pocket (stacker) selected to receive the document and whether batch numbering update is to be performed (1419 only). The entry point is specified in the DTFMR operand EXTADDR=name. All registers are saved upon exiting from, and restored upon returning to, your program. The use of the general registers in this routine is as follows: Register Comment 0-4,6,8-15 These registers are available to your stacker selection routine for any purpose. Because the program can be interrupted at any time, the contents of these registers are unpredictable. 5 When your stacker selection routine is entered, this register contains the address of the routine. Register 5 should be utilized as the base register for the routine. 7 This register always contains the address of the first byte of the buffer for the document being selected. Bytes 2 and 3 of the buffer (see Appendix E) indicate the read status of the document. The MICR document buffer format is given in Before entering your stacker selection routine, IOCS aids in stacker selection by setting the entire document buffer to binary zeros, reading the document into the document data area, and posting information in bytes 2 and 3. When the stacker selection routine has determined which pocket to select the document into, the actual stacker selection command code for this pocket must be placed into byte 4 of the document buffer pointed to by register 7. The final destination of the document is indicated in byte 5 of the buffer. This indication is the same as byte 4 except in the case of a late stacker select, an autoselected document, a program malfunction, or a device malfunction. Any of these results in an I/O error. The reject code X'CF' indicating that the document is placed in the reject pocket is placed in byte Appendix E. 5. Part 2. Sequential Access Method 63 - Beginning 0 document buffer area address specified in IOAREA1) -Byte 0-5 buffer status indicators (address specified in IOREG and in register 7 for your stacker selection routine) - Batch numbering updates r---- Error indicator for MICR device ....---Pocket you selected r-- Pocket document selected into ....--- Byte 6 - your additional work area II • ....--- Byte xxx - document data area I-B_O+8_0-+-00-+-1F--+-5_FJ-5_F+--_ _ _ Your work area. _ _ _-----1t--_Document records right-adjusted within _ this area. Length is specified in RECSIZE. Length is specified in ADDAREA ~111111 - ...~ __- - - - - - - - - - - - - - Maximum r - Length is 256 B y t e s - - - - - - - - - - - - - - - _ - . l 1 D Indicates the normal condition (no errors - all fields read) when the document is being processed and the stacker selection is complete to pocket 5 and batch numbering update was performed (1419 model 1 or 3). II Number of buffers is limited only by the amount of storage available (see BUFFERS operand). Figure 2-13 MICR document buffer The command codes to be used to select pockets are: Pocket Code A X'AF' B X'BF' 0 1 2 3 4 5 6 7 8 9 Reject I X'OF' X' 1 F' X'2F' X'3F' X'4F' X'SF' X'6F' X'7Ft X'SF' X'9F' X'eF' (1270, except models 1 and 3, 1275, and 1419 only) (1275 and 1419 only) (except 1270 models 1 and 3) 64 DOS/VS Supervisor and I/O Macros An invalid code placed in byte 4 puts the document into the reject pocket and posts bit 1 of byte 0 of the buffer. Byte 0, bit 2 of the next buffer is posted. Before returning to a 1419 external interrupt routine via the EXIT macro with the MR operand (required method), you can request a batch numbering update. You can do this only within your 1419 stacker selection routine by turning on byte 1, bit 0 in the current document buffer (01 1(7), X'80'). For the 1419 (dual address), you cannot obtain batch numbering update on an auto-selected document (byte 2, bit 6 on). Such requests are ignored by the external interrupt routine. Timings for Stacker Selection: Because the MICR readers continuously feed documents while engaged, it is necessary to reinstruct the readers within a certain time limit after a read completion is signaled by an external interrupt. This period is generally called minimum stacker selection time. This available time depends on the reader model, the length of documents being read, single or dual address adapter (1419, 1275), and the fields to be read on the 1419 or 1275 (dual address) only. Refer to the appropriate MICR publications listed in the latest SRL Newsletter for a more complete description of device timings. Failure to reinstruct the 1255, 1259, 1270, 1275, or 1419 (single address adapter) within the allotted time causes the document(s) processed after this time to be auto-selected into the reject pocket (late read condition). Failure to reinstruct the 1419 or 1275 (dual address adapter) within the allotted time causes the document being processed to be autoselected into the reject pocket (late stacker-select condition). Programming Considerations for 1419 or 1275 Stacker Selection The stacker selection routine operates in the program state with the protection key of its program and with 110 and external interruptions disabled. If your stacker selection routine fails to return to the supervisor (loops indefinitely), there is no possible recovery. If such looping occurs, the system must be re-IPLed to continue operation. It is therefore recommended that you thoroughly debug your stacker selection routine in a dedicated environment. In your stacker selection routine, no system macro other than EXIT MR can be used. The routine runs with an all zero program and system mask, but the machine check interruption is enabled and a program check cancels the program. Note: Any modification of floating point registers without saving and restoring them may cause erroneous processing by any concurrent program using floating-point instructions. When processing with the dual address adapter (1419 or 1275), you have more time for your stacker selection routine. The only additional processing you must do within the main line is to check byte 2, bit 0, of the document buffer for stacker selection errors. Note: Batch numbering update is not performed with the stacker selection of auto-selected documents, and batch numbering is not available on the 1275 optical reader I sorter. Checkpointing MICR Files This topic is discussed in the section Notes for DASD and MICR Files under CHKPT Macro in the Supervisor Macros chapter. DTFMR Operands Enter the symbolic name of the file in the name field and DTFMR in the operation field. The entries are discussed here and illustrated in Figure 2-14. ADDAREA=n This operand must be included only if an additional buffer work area is needed. The parameter n specifies the number of additional bytes you desire in each buffer. The sum of the ADDAREA and RECSIZE specifications must be less than or equal to 250. This area can be used as a work area andlor output area and is reset to binary zeros when the next GET or READ for a file is executed. ADDRESS=DUAL This operand must be included only if the 1419 or 1275 contains the dual address adapter. If the single address adapter is used, this operand must be omitted. BUFFERS=t25I nJ This operand is included to specify the number of buffers in the document buffer area. The limits for n are 12 and 254. 25 is assumed if this operand is omitted. DEVADDR=SYSnnn This operand specifies the symbolic unit to be associated with the file. The symbolic unit represents an actual 1/0 device address used in the ASSGN job control statement to assign the actual 110 device address to the file. ERROPT = name This operand may be included only if the CHECK macro is used. The parameter name specifies the name of the routine that the CHECK macro branches to if any error condition is posted in byte 0, bits 2-4 (and bit 5, if no control address is specified in the CHECK macro) of the buffer status indicators. It is your responsibility to exit from this routine (see the CHECK Macro in the Magnetic Reader Macros section later in this chapter). Part 2. Sequential Access Method 65 M DEY ADDR=SYSnnn Symbolic unit assigned to the magnetic character reader. M IOAREA 1 = xxxxxxxx Name of the document buffer area. 0 ADDAREA=nnn 0 ADDRESS=DUAL Must be included only if the device is a 1419 or 1275 with a dual address adapter. 0 BUFFERS=nnn Specifies the number of buffers needed. If omitted, 25 is assumed. 0 ERROPT=xxxxxxxx Name of your error routine. Required only if the CHECK macro is used. 0 EXT ADDR=xxxxxxxx Name of your stacker selection routine. Required only if SORTMDE=ON. 0 IOREG=(nn) Pointer register number. If omitted, register 2 is assumed. General registers 2-12, written in parentheses. 0 MODNAME=xxxxxxxx Name of your I/O module. Required only if a nonstandard module is referenced. 0 RECSIZE=nnn Specifies the maximum record length. If omitted, 80 is assumed. 0 SECADDR=SYSnnn Specifies secondary symbolic unit assigned to (dual address) 1275 or 1419. Required only if LITE macro is used. 0 SEPASMB= YES Required only if the DTF is assembled separately; otherwise it should be omitted. 0 SORTMDE=xxx ON-1255/1259/1270 or program sort mode used; OFF-1419/1275 sort mode used. If omitted, ON is assumed. Additional document buffer area (ADDAREA+RECSIZE=250). If omitted, no area is alloted. M=Mandatory; O=Optional Figure 2-14 DTFMR macro operands EXTADDR = name This operand specifies the name of your stacker selection routine to which control is given when an external interrupt is encountered while reading and sorting the documents internally. The only case when this operand may be omitted is when SORTMDE=OFF is specified. IOAREAl =name This operand specifies the name of the document buffer area used by the file. Figure 2-13 shows the format of the document buffer area. 66 DOS/YS Supervisor and I/O Macros IOREG={(~) I (r)J This operand specifies the general-purpose register (2-12) that the IOCS routines and your routines use to indicate which individual document buffer is available for processing. IOCS puts the address of the current document buffer in the specified register each time a GET or READ is issued. Register 2 is assumed if this operand is omitted. The same register may be specified in the IOREG entry for two or more files in the same program, if desired. In this case, your program may need to store the address supplied by IOCS for each record. MODNAME=name This operand specifies the name of the logic module MRMOD. If omitted, IOCS generates the standard system module name. ADDRESS={SINGLE I DUAL} Required only if the dual address adapter is utilized for the 1419 or 1275. If omitted, the single address adapter is assumed. RECSIZE= {SO I n} This operand specifies the actual length of the data portion of the buffer. The record size specified must be the size of the largest record processed. If this operand is omitted, a record size of 80 is assumed. The sum of the ADDAREA and RECSIZE specifications must be less than or equal to 250. BUFFERS = nnn A numeric value (nnn) equal to the corresponding value specified in the DTFMR macro. SECADDR=SYSnnn This operand specifies the symbolic unit to be associated with the secondary control unit address if the 1419 or 1275 with the dual address adapter and LITE macro are utilized. The operand should be omitted if the pocket LITE macro is not being used. SEPASMB=YES Include this operand only if the DTFMR is assembled separately. This causes a CAT ALR card with the filename to be .punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. SORTMDE={ON I OFF} This operand specifies the method of sorting done on the 1419. SORTMDE=ON indicates that the program sort mode is being used. SORTMDE=OFF indicates that sorting is under control of the magnetic character reader. If the operand is omitted, the program sort mode is assumed. SEPASMB=YES Include this operand only if the module is assembled separately. This causes a CATALR card with the module name (standard or user-specified) to be punched ahead of the object deck and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. DTFMT Macro 7t?fJE ~~.I;zt \"~. ,,>.~ , 'W A DTFMT macro is included for each EBCDIC or ASCII magnetic tape input or output file that is to be processed. Enter the symbolic name of the file in the name field and DTFMT in the operation field. The detail entries follow the header card in any order. The entries are discussed here and illustrated in Figure 2-15. ASCII=YES This operand specifies that processing of ASCII tapes is required. If this operand is omitted, EBCDIC processing is assumed. ASCII= YES is not permitted for work files. The first card contains MRMOD in the operation field and may contain a module name in the name field. If a module name is omitted, the following standard module name is generated by IOCS: BLKSIZE=n Enter the length of the I/O area. If the record format is variable or undefined, enter the length of the largest block of records. If a READ or WRITE macro specifies a length greater than n for work files, the record to be read or written will be truncated to fit in the I/O area. The maximum block size is 32,767 bytes. The minimum size of physical tape record (gap to gap) is 12 bytes. A record of eleven bytes or less is treated as noise. (S = single address adapter, and D = dual address adapter). The operands you can specify for MRMOD are listed below. For output processing of spanned records, the minimum physical record length is 18 bytes. If SPNBLK or SPNUNB and TYPEFLE=OUTPUTare specified in the DTFMT and the BLKSIZE is invalid or less than 18 bytes, a new MNOTE is generated and BLKSIZE= 18 is assumed. MRMODMacro Part 2. Sequential Access Method 67 Applies to ..... ..... ~ =' ~ 0 ~ x x x ....... M BLKSIZE=nnnnn Length of one I/O area in bytes (maximum = 32,767). x X x M DEV ADDR=SYSxxx Symbolic unit for tape drive used for this file. X M EOFADDR=xxxxxxxx Name of your end-of-file routine. X Mt FILABL=xxxx (NO, STD, or NSTD). If NSTD specified, include LABADDR. If omitted, NO is assumed. M 10AREA 1=xxxxxxxx Name of first I/O area. =' §" ~ X X X X X '0"" ~ X X 0 ASCII=YES ASCII file processing is required. X X 0 BUFOFF=nn Length of block prefix if ASCII= YES. 0 CKPTREC=YES Checkpoint records are interspersed with input data records. 10CS bypasses checkpoint records. X X X X 0 ERREXT=YES Additional errors and ERET are desired. X X X 0 ERROPT=xxxxxxxx (IGNORE, SKIP, or name of error routine). Prevents job termination on error records. X X X 0 HDRINFO=YES Print header label information if FILABL=STD. X X 0 10REG=(nn) Register number. Use only if GET or PUT does not specify work area or if two I/O areas are used. Omit WORKA. General registers 2-12, written in parentheses. X X 0 LABADDR=xxxxxxxx Name of your label routine if FILABL=NSTD, or if FILABL=STD and user-standard labels are processed. 0 LENCHK=YES Length check of physical records if ASCII= YES and BUFOFF=4. X 0 MODNAME=xxxxxxxx Name of MTMOD logic module for this DTF. If omitted, 10CS generates standard name. X 0 NOTEPNT=xxxxxx (YES or POINTS). YES if NOTE, POINTW, POINTR, or POINTS macro used. POINTS if only POINTS macro used. X X X M=Mandatory; O=Optional Figure 2-15 DTFMT macro operands (part 1 of 2) 68 DOS/VS Supervisor and I/O Macros Applies to ..... ::s = ..... 0.. ~ - 0 ~ x x x 0 RDONLY=YES Generate read-only module. Requires a module save area for each task using the module. X 0 READ=xxxxxxx (FORWARD or BACK). If omitted, FORWARD assumed. X 0 RECFORM=xxxxxx (FIXUNB, FIXBLK, VARUNB, VARBLK, SPNUNB, SPNBLK, or UNDEF). For work files use FIXUNB or UNDEF. If omitted, FIXINB is assumed. 0.. d ::s X x X 1-0 0 If RECFORM=FIXBLK, no. of characters in record. If X X X X X X RECSIZE=nnnn X 0 REWIND=xxxxxx (UNLOAD or NORWD). Unload on CLOSE or end-ofvolume, or prevent rewinding. If omitted, rewind only. X 0 SEPASMB=YES DTFMT is to be assembled separately. 0 TRMARK=NO Prevent writing a tape mark ahead of data records if FILABL=NSTD or NO. 0 TYPEFLE=xxxxxx (INPUT, OUTPUT, or WORK). If omitted, INPUT is assumed. 0 VARBLD=(nn) Register number, if RECFORM=VARBLK and records are build in the output area. General registers 2-12 are written in parentheses. 0 WLRERR=xxxxxxxx Name of wrong-length-record routine. 0 WORKA=YES GET or PUT specifies work area. Omit IOREG. X X X X X X X RECFORM=UNDEF, register number. Not required for other records. General registers 2-12, written in parentheses. 0 X M = Mandatory; 0 = Optional Figure 2-15 DTFMT macro operands (part 2 of 2) For ASCII tapes, the BLKSIZE includes the length of any block prefix or padding characters present. If ASCII= YES and BLKSIZE is less than 18 bytes (for fixed-length records only) or greater than 2048 bytes, an MNOTE is generated because this length violates the limits specified by American National Standards Institute, Inc. be included when ASCII= YES is specified. The contents of this field are not passed on to you. BUFOFF={!! I nJ This operand indicates the length of the block prefix. Enter the length of the block prefix if processing of the block prefix is required. This operand can only Part 2. Sequential Access Method 69 n can have the following values: Value Condition 0-99 If TYPEFLE=INPUT 0 4 IF TYPEFLE=OUTPUT If TYPEFLE=OUTPUT and RECFORM=VARUNB orVARBLK. In this case, the program automatically inserts the physical record length in the block prefix. ERROPT=UGNORE I SKIP I name I This operand specifies functions to be performed when an error block is encountered. If a parity error is detected when a block of tape CKPTREC=YES This operand is necessary if an input tape has checkpoint records interspersed among the data records. 10CS bypasses any checkpoint records encountered. This operand must not be included when ASCII=YES. DEVADDR=ISYSRDR I SYSIPT I SYSPCH I SYSnnn I SYSLSTI This operand specifies the symbolic unit to be associated with the file. An ASSGN job control statement assigns an actual channel and unit number to the unit. The ASSGN job control statement contains the same symbolic name as DEVADDR. When processing ASCII tapes, you must specify a programmer logical unit (SYSnnn). records is read, the tape is backspaced and reread a specified number of times before the tape block is considered an error block. Output parity errors are considered to be an error block if they exist after 10CS attempts to forward erase and write the tape output block a specified number of times. If ERREXT = YES is specified on output, and ERROPT=IGNORE or SKIP, the error will be ignored. If either FILABL=STD or CKPTREC, or both, is specified, the error block is included in the block count. After this the job is automatically terminated unless this ERROPT entry is included to specify other procedures to be followed in case of an error condition. Either IGNORE, SKIP, or the symbolic name of an error routine can be specified in this card. The functions of these specifications are: IGNORE The error condition is completely ignored, and the records are made available for processing. When reading spanned records, the entire spanned record or a block of spanned records is returned to the user rather than just the one physical record in which the error occurred. On output, the error is ignored and the physical record containing the error is treated as a valid record. The remainder, if any, of the spanned record segments are written, if possible. EOFADDR=name This operand specifies the name of your end-of-file routine. 10CS automatically branches to this routine on an end-of-file condition. This entry must be specified for input and work files. In your routine, you can perform any operations required for the end of file (generally you issue the CLOSE instruction for the file). 10CS detects endof-file conditions in magnetic tape input by reading a tapemark and EOF when standard labels are specified. If standard labels are not specified, 10CS assumes an end-of-file condition when the tapemark is read, if the unit is assigned to SYSRDR or SYSIPT when a / * is read. You must determine, in your routine, that this actually is the end of the file. ERREXT=YES This operand enables your ERROPT or WLRERR routine to return to MTMOD with the ERET (error return) macro. It also enables unrecoverable I/O errors occurring before data transfer takes place to be indicated to your program. To take full advantage of this option, the ERROPT=name operand must be specified. 70 DOS/VS Supervisor & I/O Macros SKIP No records in the error block are made available for processing. The next block is read from tape, and processing continues with the first record of that block. The error block is included in the block count. When reading spanned records, the entire spanned record or a block of spanned records is skipped rather than just one physical record. On output, the error is ignored and the physical record containing the error is treated as a valid record. The remainder, if any, of the spanned record segments are written. name 10CS branches to your error routine named by this parameter regardless of whether ERREXT = YES is specified. In this routine, you process or make note of the error condition as qesired. If ERREXT is not specified, register 1 contains the address of the physical record in error. When spanned records are processed, register 1 contains the address of the whole unblocked or blocked spanned record. Register 14 contains the return address. When processing in the ERROPT routine, refer the error block, or records in the error block to the address supplied in register 1. The contents of the IOREG register or work area (if either is specified) are variable and therefore should not be used for error processing. Furthermore, your routine must not issue any GET macros for records in the error block. If any other IOCS macros (excluding ERET if ERREXT= YES) are used in this routine, the contents of registers 13 (with RDONLY) and 14 must be saved and restored after their use. At the end of the routine, return control to IOCS by branching to the address in register 14. IOCS skips the physical record in error and makes the next logical record available for processing in the main program. A sequence error may occur if LIOCS is searching for a first segment of a logical spanned record and fails to find it. If WLRERR or ERROPT=name was specified, the error recovery procedure is the same as for wrong-length record errors. If neither WLRERR nor ERROPT=name was specified, LIOCS ignores the sequence error and searches for the next first segment. If ERREXT is specified, register 1 contains the ad- dress of a two-part parameter list containing the 4-byte DTFMT address and the 4-byte address of the physical record in error, respectively. Note: If ERREXT is not specified for an output file, no code is generated and an MNOTE is issued. If an error condition occurs, the job is canceled. Register 14 contains the return address. Processing is similar to that described for cases where ERREXT is not specified, except for addressing the physical record in error. The data transfer bit (byte 2, bit 2) of the DTF should be tested to determine if a nondata transfer error has occurred. If it is on, the physical record in error has not been read or written. If the bit is off, data was transferred and the routine must address the physical record in error to determine the action to be taken. At the end of its input processing, the routine returns to LIOCS by issuing the ERET macro. If any other IOCS macros are used in this routine, the contents of register 13 (with RDONL Y) and register 14 must be saved and restored after their use. At the end of the ERROPT output routine, the program must consider the device inoperative and must not attempt further processing on it. Any subsequent attempt to return to MTMOD results in job termination. The ERET macro can specify one of two actions to the MTMOD logic module. The error condition can be ignored with an ERET IGNORE, or the physical record in error can be skipped to process the next physical record with an ERET SKIP. ERET RETRY is invalid and results in job termination. Figure 2-16 shows the DTFMT error options for various combinations of error specifications and errors. The job is automatically terminated if a parity error still exists after IOCS attempts to write a tape output block a specified number of times. This includes erasing forward. The ERROPT operand applies to wrong-length records if the WLRERR operand is not included. If both ERROPT and WLRERR are omitted and wrong-length records occur, IOCS assumes the IGNORE option. Note: For ASCII tapes, the pointer to the block in error indicates the first logical record following the block prefix. FILABL=INO I STD I NSTDI This operand specifies what type of labels are to be processed. STD indicates standard labels, NO indicates no labels, and NSTD indicates nonstandard labels. You must furnish a routine to check or create the nonstandard labels by using your own 110 area and an EXCP macro to read or write the labels. The entry point of this routine is the operand of LABADDR. The specification FILABL=NSTD is not permitted for ASCII files (that is, when ASCII= YES). Labels and tape data are assumed to be in the same mode. HDRINFO= YES This operand, if specified with FILABL=STD, causes IOCS to print standard header label information (fields 3-10) on SYSLOG each time a file with standard labels is opened. It also prints the filename, logical unit, and device address each time an end-ofvolume condition is detected. Both FILABL= STD and HDRINFO= YES must be specified for header label information to be printed. Part 2. Sequential Access Method 71 IOAREAl=name This operand specifies the name of the I/O area. When variable-length records are processed, the size of the I/O area must include four bytes for the block size. This operand does not apply to work files. IOAREA2=name This operand specifies the name of a second I/O area. When variable-length records are processed, the size of the I/O area must include four bytes for the blocksize. This operand does not apply to work files. IOREG=(r) This operand specifies the register in which IOCS places the address of the logical record that is available for processing if: • • • • • two input or output areas are used. blocked input or output records are processed in the I/O area. variable unblocked records are read. undefined records are read backwards. neither BUFOFF=O nor WORKA=YES is specified for ASCII files. For output files, IOCS places in the specified register the address of the area where you can build a record. Any register (2-12) may be specified. Note: This operand cannot be used if WORKA=YES. LABADDR = name Enter the symbolic name of your routine to process user-standard or nonstandard labels. See the Tape Input Files section of the Label Processing chapter. For ASCII tapes, this operand may only be used for writing and checking user standard labels which conform to American National Standards Institute, Inc., standards. You must process these labels in EBCDIC. Nonstandard user labels are not permitted. 72 DOS/VS Supervisor & I/O Macros LENCHK::=YES This operand applies only to ASCII tape input if BUFOFF =4 and RECFORM= V ARUNB or V ARBLK. It must be included if the block length (specified in the block prefix) is to be checked against the physical record length. If an inequality is detected, the action taken is the same as described under the WLRERR operand, but the WLR bit (byte 5, bit 1) in the DTF is not set. MODNAME = name This operand specifies the name of the logic module used with the DTF table to process the file. If the logic module is assembled with the program, MODNAME must specify the same name as the MTMOD macro. If this entry is omitted, standard names are generated for calling the logic module. If two DTF macros call for different functions that can be handled by a single module, only one module is called. For example, if one DTF specifies READ = FORWARD and another specifies READ=BACK, only one logic module capable of handling both functions is called. NOTEPNT=iPOINTS I YES} If the parameter YES is specified, the NOTE, POINTW, POINTR, or POINTS macros are issued for a tape work file. If POINTS is specified, only POINTS macros can be issued for tape work files. The NOTEPNT operand must not be specified for ASCII tape files because work files are not supported. TAPE OUTPUT o IS termlna e {IJb. • td I'" Control is passed to your wrong length record routine Wrong l.enght Record Errors Desired Function Error record is skipped Error record is ignored Job is terminated ........ TAPE INPUT ,/ Errors other than Wrong l.enght Records Control passed to your error option routine Error record is skipped Error record is ignored - Job is terminated 1X ", ERROPT = IGNORE ERROPT = name ERR OPT = SKIP WLRERR =name ERR OPT = IGNORE, ERROPT =name, ERROPT = SKIP, XX X XX XX XX XX X WLRERR =name XX =name X WLRERR WLRERR X =name X X WLRERR = name ERET SKIP XX WLRERR = name ERET IGNORE X WLRERR =name ERET RETRY X X ERROPT =name, WLRERR ERET IGNORE ERROPT = name, WLRERR ERET RETRY ERROPT = name, WLRERR ERET SKIP =name =name XX X X XX X X X X =name XX XX X X NONE ........ X X X ERR OPT = name ERET RETRY WLRERR = name ERET SKIP X DTF Parameters: ERET Macro Options: IGNORE RETRY SKIP Figure 2-t6 X XX X WLRERR = name ERET IGNORE Specifications required in your Program ~ ERROPT ERROPT ERROPT WLRERR = name = IGNORE = = SKIP name DTFMT error options Part 2. Sequential Access Method 73 RDONLY=YES This operand is specified if the DTF is used with a read-only module. Each time a read-only module is entered, register 13 must contain the address of a 72-byte doubleword-aligned save area. Each task should have its own uniquely defined save area and each time an imperative macro (except OPEN (or OPENR) or LBRET) is issued, register 13 must contain the address of the save area associated with the task. The fact that the save areas are unique for each task makes the module reentrant (that is, capable of being used concurrently by several tasks). For more information see Shared Modules and Files in the Multitasking Macros chapter. If an ERROPT or WLRERR routine issues I/O macros which use the same read-only module that caused control to pass to either error routine, your program must provide another save area. One save area is used for the normal I/O operations and the second for I/O operations in the ERR OPT or WLRERR routine. Before returning to the module that entered the error routine, register 13 must be set to the save area address originally specified for the task. If the operand is omitted, the module generated is not reenterable and no save area is required. READ={FORWARD I BACKJ This operand specifies the direction in which the tape is read. If READ=BACK is specified and a wrong-length record smaller than the I/O area is encountered, the record is read into the I/O area right-justified. RECFORM={FIXUNB I FIXBLK I VARUNB I VARBLKI SPNBLK I SPNUNB I UNDEFJ This operand specifies the type of EBCDIC or ASCII records in the input or output file. Enter one of the following parameters: FIXUNB For fixed-length unblocked records FIXBLK For fixed-length blocked records VARUNB For variable-length unblocked records V ARBLK For variable-length blocked records SPNBLK For spanned variable-length blocked records (EBCDIC only) SPNUNB For spanned variable-length unblocked records (EBCDIC only) UNDEF For undefined records 74 DOS/VS Supervisor & I/O Macros Work files may only use FIXUNB or UNDEF. RECSIZE={n I (r)J For fixed-length blocked records, this operand is required. It specifies the number of characters in each record. When processing spanned records, you must specify RECSIZE= (r) where r is a register that contains the length of each record. For undefined records, this entry is required for output files and optional for input files. It specifies a general register (2-12) that contains the length of the record. On output, you must load the length of each record into the register before you issue a PUT macro. Spanned-record output requires a minimum record length of 18 bytes. A physical record less than 18 bytes is padded with binary zeros to complete the I8-byte requirement. This applies to both blocked and unblocked records. If specified for input, IOCS provides the length of the record transferred to virtual storage. REWIND={UNLOAD I NORWDJ If this specification is not included, tapes are auto- matically rewound to load point, but not unloaded, on an OPEN (or OPENR) or CLOSE (or CLOSER) macro or on an end-of-volume condition. If other operations are desired for a tape input or output file, specify: UNLOAD to rewind the tape on an OPEN (or OPENR) or to rewind and unload on CLOSE (or CLOSER) or or end-ofvolume condition. NORWD to prevent rewinding the tape at any time. This option positions the read/ write head between the two tapemarks on the end-of-file condition. SEPASMB=YES Include this operand only if the DTFMT is assembled separately. This causes a CATALR card with the filename to be punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. TPMARK=NO A tapemark is normally written for an output file if nonstandard labels are specified (FILABL=NSTD). If no tape mark is desired, this operand should be specified. This operand is ignored if standard labels are specified (FILABL=STD). For unlabeled tapes, TPMARK=NO is the default. TYPEFLE={INPUT I OUTPUT I WORKI Use this operand to indicate whether the file is used for input or output. If INPUT is specified, the GET macro is used. If OUTPUT is specified, the PUT macro is used. If WORK is specified, the READ/WRITE, NOTE/POINT, and CHECK macros are used. See Work File Macros for Tape and Disk under the Processing Macros section of the present chapter. The specification of WORK in this operand is not permitted for ASCII files. VARBLD=(r) This entry is required whenever variable-length blocked records are built directly in the output area (no work area specified). It specifies the number (r) of a general-purpose register (2-12) that always contains the length of the available space remaining in the output area. IOCS calculates the space still available in the output area, and supplies it to you in the V ARBLD register after the PUT macro is issued for a variable-length record. You can then compare the length of the next variable-length record with the available space to determine if the record will fit in the remaining area. This check must be made before the record is built. If the record does not fit, issue a TRUNC macro to transfer the completed block of records to the tape. The current record is then built as the first record of the next block. WLRERR=name This operand applies only to tape input files. It specifies the name of your routine to receive control if a wrong-length record is read. If ERREXT is not specified, the address of the physical record in error is supplied by IOCS in register 1. If ERREXT is specified, register 1 contains the address of a two-part parameter list. The first four bytes of the list are the DTF address and the second four bytes are the address of the physical record in error. If the block read is less than that specified in the BLKSIZE parameter, the first two bytes of the DTF contain the number of bytes left to be read (residual count). Therefore, the size of the actual block is equal to the specified block size minus the residual count. If the block to be read is larger than that specified in the BLKSIZE parameter, the residual count is zero, and there is no way to compute the record size. The number of bytes transferred is equal to that specified in the BLKSIZE parameter, and the remainder of the original block is truncated. Your WLRERR routine can perform any processing desired for wrong length records. However, it must not issue GET macros to this file. If the routine issues any other IOCS macros (excluding ERET if ERREXT=YES) the contents of registers 13 (with RDONLY) and 14 must be saved before and restored after their use. At the end of the routine, either control is returned to IOCS by branching to the address in register 14, or (if ERREXT is specified) the ERET IGNORE or SKIP option can be taken. When fixed-length unblocked records are specified (RECFORM=FIXUNB), a wrong-length record error condition is given when the length of the record read is not equal to that specified in the BLKSIZE parameter. For EBCDIC fixed-length blocked records, record length is considered incorrect if the physical tape record (gap to gap) that is read is not a mUltiple of the logical-record length (specified in DTF RECSIZE), Up to the maximum length of the block (specified in DTFMT BLKSIZE). This permits the reading of short blocks of logical records without a wrong-length record indication. For EBCDIC variable-length records (blocked and unblocked), the record length is considered incorrect if the length of the tape record is not the same as the block length specified in the 4-byte blocklength field. The residual count can be obtained by addressing the halfword at filename+98. For ASCII variable-length records (blocked and unblocked), a check on the physical record length is performed if LENCHK=YES is specified. The physical record length is considered incorrect if the tape record is not the same as the block length specified in the 4-byte block prefix. In this case, the WLR bit (byte 5, bit 1) in the DTF table is set off. The WLRERR option is taken for undefined records if the record read is greater than the size specified by the BLKSIZE parameter. If the WLRERR entry is omitted but a wronglength record is detected by IOCS, one of the following conditions results: Part 2. Sequential Access Method 75 • • If the ERROPT entry is included for this file, the wrong-length record is treated as an error block, and handled according to your specifications for an error (IGNORE, SKIP, or name of error routine). If the ERROPT entry is not included, IOCS assumes the IGNORE option of ERROPT. WORKA=YES If I/O records are processed in work areas instead of in the I/O areas, specify this operand. You must set up the work area in virtual storage. The address of the work area, or a general-purpose register containing the address, must be specified in each GET or PUT. Omit IOREG if this operand is included. WORKA= YES is required for spanned record processing. MTMODMacro Listed here are the operands you can specify for MTMOD. The first card contains MTMOD in the operation field and may contain a module name in the name field. ASCII=YES Include the operand if processing ASCII input or output files is required. This entry is not permitted for work files. If omitted, EBCDIC file processing is assumed. CKPTREC=YES Include this operand if input tapes processed by the module contain checkpoint records interspersed among the data records. The module also processes tapes that do not have checkpoint records; that is, those whose DTFs do not specify CKPTREC = YES. This entry is not needed for work files, and is not valid for ASCII files. ERREXT=YES Include this operand if additional I/O errors are to be indicated and/or the ERET macro is used with this DTF and module. ERROPT= YES should be specified in this module for work files, but is not needed for input or output files. ERROPT=YES Include this operand if the module is to handle any of the error options for an error block. Code is generated to handle any of the three options (IGNORE, SKIP, or name). The module processes also any files in which the ERROPT operand is not specified in 76 DOS/VS Supervisor & I/O Macros the DTF. This entry is needed for work files, but it is not needed for input or output files. NOTEPNT=IYES I POINTS} This operand applies only to work files (EBCDIC only). Include this operand if NOTE/POINT logic is used with the module. If YES is specified, the module processes any NOTE, POINTR, POINTW, or POINTS macro. If POINT~ is specified, only the POINTS macro is processed. Modules specifying either one of the two options also process work files for which the NOTE/POINT operand is not specified in the DTF. Modules specifying YES also process work files specifying only POINTS. RDONLY=YES This operand causes a read-only module to be generated. Whenever this operand is specified, any DTF used with the module must have the same operand. READ=IFORWARD I BACK} This operand generates a module that reads tape files forward or backward. If forward is specified, only code to read tape forward is generated. Any DTF used with the module must not specify BACK in the READ parameter statement. If the parameter is BACK, code to read tape both forward and back}Vard is generated, and any DTF used with the module may specify either FORWARD or BACK as its READ parameter. READ=BACK does not handle multi-volume files. This entry is not needed for work files. RECFORM=IFIXUNB I FIXBLK I VARUNB I VARBLKISPNBLKISPNUNBI UNDEF} This operand generates an input/ output module that processes either EBCDIC or ASCII fixed-length, variable-length or undefined records. If either FIXUNB or FIXBLK is specified, a module is generated that allows processing of both fixedlength blocked and fixed-length unblocked records. Similarly, if VARUNB or VARBLK is specified, a module is generated that allows processing of both types of variable and spanned records. ASCII files are not permitted in spanned record format. If UNDEF is specified, a module for processing undefined record types is generated. Any DTF used with the module must specify the same record format type as the module. For examp.le, if the module specifies RECFORM=FIXUNB, either RECFORM=FIXUNB or RECFORM=FIXBLK may be specified in the DTF. and of all forms of the module that process variablelength records (V,R,S). Name list for GET/PUT type modules: This operand is not needed for work files. a = F RECFORM=FIXUNB (or FIXBLK) (EBCDIC mode) = X RECFORM=FIXUNB (or FIXBLK) (ASCII mode) = V RECFORM=VARUNB (or VARBLK) (EBCDIC mode) = R RECFORM=VARUNB (or VARBLK) (ASCII mode) = S RECFORM=SPNUNB (or SPNBLK) (spanned records) = U RECFORM=UNDEF (EBCDIC mode) = N RECFORM=UNDEF (ASCII mode) If this operand is omitted, the module generated will allow processing of both fixed-length blocked and fixed-length unblocked records. SEPASMB=YES Include this operand only if the module is assembled separately. This causes a CAT ALR card with the module name (standard or user-specified) to be punched ahead of the object deck and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. MTMOD name = UFabcde b = B READ=BACK = Z READ=FORWARD, or if READ is not specified c = C CKPTREC= YES TYPEFLE=IOUTPUT I INPUT I WORK} This operand generates a module that processes either GET/PUT macros or READ/WRITE, NOTE/POINT and CHECK macros for work files (EBCDIC only). If the parameter of the operand specifies WORK, code to process work files is generated. Otherwise, a module to handle both input and output files is assumed. Only DTFs for work files may be used with work file modules. Only DTFs for input or output files may be used with an input/ output mo~ule. Note: INPUT and OUTPUT have the same table format and logic modules. WORKA=YES This operand is to be included if records are to be processed in work areas instead of I/O areas for the GET /PUT macros. This operand must be included if spanned records are processed. The module also processes files that do not use a work area. This entry is not needed for work files. = Z CKPTREC= YES is not specified d = WWORKA=YES = Z WORKA=YES is not specified e Name list for work file type modules (TYPEFLE= WORK): MTMOD name = UFabcde a=W b = E ERROPT=YES = In MTMOD there are two module classes: the module class for handling GET/PUT functions and the module class for handling READ/WRITE, NOTE/POINT, and CHECK functions (work files). Modules handling fixedlength (F ,X) and undefined (U ,N) records are mutually exclusive of each other Z ERROPT is not specified c = N NOTEPNT=YES = S NOTEPNT=POINTS = Z NOTEPNT is not specified d = Z always e Standard MTMOD Names Each name begins with a 3-character prefix (UF) and continues with a 5-character field containing the options permitted in module generation. = M ERREXT = YES and RDONLY= YES = N ERREXT=YES = Y RDONLY=YES = Z ERREXT and RDONLY not specified =M ERREXT=YES and RDONLY=YES ERREXT = YES = Y RDONLY=YES = Z ERREXT and RDONL Y not specified =N Subset/Superset MTMOD Names The following charts illustrate the subsetting and supersetting allowed for MTMOD names. Four of the GET/PUT parameters allow subsetting. For example, the module name IJFFBCWZ is a superset of IJFFBZWZ specifying fixed-length records. See Part 2. Sequential Access Method 77 I OCS Subset I Superset Names in The M aero System chapter. * ++++ I 1.1 F F B C W M N Z Z Z Y R U N X Z + + s V + Subsetting/supersetting permitted. * No subsetting/supersetting permitted. BLKFAC=o Undefined journal tape records are processed with greater throughput speeds when this operand is included. This is accomplished by reading groups of lines as blocked records. When undefined records are processed, BLKFAC specifies the blocking factor (n) that determines the number of lines read (through CCW chaining) as a block of data by one physical read. Deblocking is accomplished automatically by IOCS when the GET macro is used. The BLKFAC parameter is not used with RECFORM=FIXBLK, because the blocking factor is determined from the BLKSIZE and RECSIZE parameters. If the operand is included for FIXBLK, FIXUNB, or document processing, the operand is noted (MNOTE) and ignored. BLKSIZE= 138 I o} For Workfile Type Modules: ++ + I J F lv E N Z M y Z S Z + N Z + Subsetting/supersetting permitted. * No subsetting/supersetting permitted. DTFOR Macro When undefined journal tape records are read, the area must be large enough to accommodate the longest record to be read if the BLKFAC parameter is not specified. If the BLKFAC parameter is specified, the BLKSIZE value must be determined by mUltiplying the maximum length that must be accommodated for an undefined record by the blocking factor desired. A BLKSIZE value smaller than this results in truncated data. If two input areas are used for journal tape process- DTFOR is used to define an input file to be processed on a 1287 optical reader or 1288 optical page reader. Enter the symbolic name of the file in the name field and DTFOR in the operation field. The operands for DTFOR follow and are illustrated in Figure 2-17. DTFOR is not used for the 3881 Optical Mark Reader. The 3881 uses DTFCD. 78 DOS/VS Supervisor This operand indicates the size of the input area specified by IOAREAl. For journal tape processing, BLKSIZE specifies the maximum number of characters that can be transferred to the area at anyone time. & I/O Macros ing (IOAREA1 and IOAREA2), the size specified in this entry is the size of each 110 area. CONTROL =YES This entry must be included if a CNTRL macro is issued for a file. A CNTRL macro issues orders to the optical reader to perform nondata operations such as line marking, stacker selecting, document incrementing, etc. Applies to f-4 Q t""00 t""00 oo .-I .-I .-I .-I X X X x M COREXIT =xxxxxxxx Name of your correction routine X X X x M DEV ADDR=SYSnnn Symbolic unit assigned to the optical reader X X X X M EOFADDR=xxxxxxxx Name of your end-of-file routine X X X X M 10 AREA 1=xxxxxxxx Name of first input area X X 0 BLKFAC=nn If RECFORM=UNDEF in journal tape mode X X X X 0 BLKSIZE=nn Length of I/O area(s). If omitted, 38 is assumed. X X X X 0 CONTROL= YES If CNTRL macro is to be used for this file X X X X 0 DEVICE=xxxxx (1287D or 1287T). For 1288, specify 1287D. If omitted, 1287D is assumed. X X X 0 HEADER=YES If a header record is to be read from the optical reader keyboard by OPEN, OPENR 0 HPRMTY=YES If hopper empty condition is to be returned. l(') 00 ~ ~ ~ X 00 ~ X If two input areas are used, name of second input X X 0 IOAREA2=xxxxxxxx X X 0 10REG=(nn) Reg. No. if 2 input areas or UNDEF records are to be used. If omitted, reg.2 is assumed. General registers 2-12, written in parentheses. X X X X 0 MODNAME=xxxxxxxx Name of DTF's logic module. If omitted, 10CS generates a standard name. X X X X 0 RECFORM=xxxxxx FIXBLK, FIXUNB, or UNDEF). If omitted, FIXUNB is assumed. X X X X 0 RECSIZE=(nn) Reg. no. containing record size, if RECFORM=UNDEF. If omitted, reg. 3 is assumed. X X X X 0 SEPASMB= YES If the DTFOR is to be assembled separately. X X 0 WORKA=YES If records are to be processed in a work area. Omit 10REG. area. M=Mandatory; O=Optional Figure 2-17 DTFOR macro options Part 2. Sequential Access Method 79 EG (if used) points to the rightmost position of the record in the I/O area. You should test the RECSIZE register before moving records from the work area or the I/O area. COREXIT=name COREXIT provides an exit to your error correction routine for the 1287 or 1288. After a GET, WAITF, or CNTRL macro (to increment or eject and/or stacker select a document) is executed, an error condition results in an error correction routine with an indication provided in filename+80. Filename+80 contains the following hexadecimal bits indicating the conditions that occurred during the last line or field read. Filename+80 should also be tested after issuing the optical reader macros DSPLY, RESCN, RDLNE, CNTRL READKB, and CNTRL MARK. More than one error condition may be present. X'20' For the 1288, reading in unformatted mode, the end-of-page (EOP) condition has been detected. Normally, on an EOP indication, the problem program ejects and stacker selects the document. Filename + 80 should also be tested after issuing the optical reader macros CNTRL ESD, CNTRL SSD, CNTRL EJD in your COREXIT routine. These should only be tested for nonrecovery (X'10') and (X'20') late stacker selection. For the 1287, a stacker select was given after the allotted elapsed time and the document was put in the reject pocket. X'OI' A data check has occurred. Five read attempts for journal tape processing or three read attempts for document processing were made. X'02' The operator corrected one or more characters from the keyboard (1287T) or a hopper empty condition (see HPRMTY =YES operand) has occurred (1287D). X'04' A wrong-length record condition has occurred (for journal tapes, five read attempts were made; for documents, three read attempts were made). Not applicable for undefined records. X'08' An equipment check resulted in an incomplete read (ten read attempts were made for journal tapes or three for documents). If an equipment check occurs on the first character in the record, when processing undefined journal tape records, the RECSIZE register contains zero, and the IOR- 80 DOS/VS Supervisor & I/O Macros X'10' A nonrecoverable error occurred. X'40' The 1287D scanner was unable to locate the reference mark (for journal tapes, ten read attempts were made; for documents, three read attempts were made). Filename + 80 can be interrogated to determine the reason for entering the error correction routine. Choice of action in your error correction routine is determined by the particular application. If you issue I/O macros to any device other than the 1287 and/or 1288 in the COREXIT routine, you must save registers 0, 1, 14, and 15 upon entering the routine, and restore these registers before exiting. Furthermore, if I/O macros (other than the GET, WAITF, and/or READ, which cannot be used in COREXIT) are issued to the 1287 and/or 1288 in this routine, you must also save and later restore registers 14 and 15 before exiting. All exits from COREXIT should be to the address specified in register 14. This provides a return to the point from which the branch to COREXIT occurred. If the command chain bit is on in the READ CCW for which the error occurred, IOCS completes the chain upon return from the COREXIT routine. Note: Do not issue a GET, READ, or WAITF macro to the 1287 or 1288 in the error correction routine. Do not process records in the error correction routine. The record that caused the exit to the error routine is available for processing upon return to the mainline program. Any processing included in the error routine would be duplicated after return to the mainline program. When processing journal tapes, a nonrecovery error (torn tape, tape jam, etc.) normally requires that the tape be completely reprocessed. Restriction: In this case, your routine must not branch to the address in register 14 from the COREXIT routine or a program loop will occur. Following a nonrecoverable error: • the optical reader file must be closed • the condition' causing the nonrecovery must be cleared • the file must be reopened before processing can continue ! \ If a nonrecoverable error o~curs while processing a documents (indicating tqat jam occurred during a document incrementation operation, or a scanner control failure has occurred, or an end-of-page condition, etc.), the documept should be removed either manually or by nonprpcess mnout. Restriction: In such cases, your program should branch to read the next document. If the 1287 or 1288 scanner is unable to locate the document reference mark, the document cannot be processed. In this case, the document must be ejected and stacker selected before attempting to read the following document or a program loop will result. In any case, the routine must not branch to the address in register 14 from the COREXIT routine. If a nonrecoverable error occurs, the routine should ignore any output resulting from the document. Eight binary error counters are used to accumulate totals of certain 1287 and 1288 error conditions. These counters each occupy four bytes, starting at filename+48. Filename is the name specified in the DTF header entry. The error counters are: Counter and Address Contents 1 filename+48 Equipment check (see Note, below). 2 filename+52 Equipment check uncorrectable after ten read attempts for journal tapes or three read attempts for documents (see Note below). 3 filename + 5 6 Wrong-length records (not applicable for undefined records). 4 filename+60 Wrong-length records uncorrectable after five read attempts for journal tapes or three read attempts for documents (not applicable for undefined records). 5 filename + 64 Keyboard corrections (journal tape only). 6 filename+68 Journal tape lines (including retried lines) or document fields (including retried fields) in which data checks are present. 7 filename + 72 Lines marked (journal tape only). 8 filename + 7 6 Count of total lines read f.rom journal tape or the number of CCW chains executing during document processing. Note: Counters 1 and 2 apply to equipment checks that result from incomplete reads or from the inability of the 1287 or 1288 scanner to locate a reference mark (when processing documents only). All the previous counters contain binary zeros at the start of each job step and are never cleared. You may list the contents of these counters for analysis at end of file, or at end of job, or you may ignore the counters. The binary contents of the counters should be converted to a printable format. DEVADDR=SYSnnn This operand specifies the logical unit (SYSnnn) to be associated with the file. The logical unit represents an actual I/O device address used in the job control ASSGN statement to assign the actual I/O device address to this file. DEVICE=U287D I 1287T} This operand specifies the I/O device associated with this file. 1287D specifies a 1287 or 1288 document file. 1287T specifies a 1287 journal tape file. From this specification, IOCS sets up the devicedependent routines for this file. For document processing you must code the CCWs. If this operand is omitted, 1287D is assumed. EOFADDR=name This operand specifies the name of your end-of-file routine. 10CS automatically branches to this routine on an end-of-file condition. When reading data from documents, you can recognize an end-of-file condition by pressing the end-offile key on the console when the hopper is empty. When processing journal tapes on a 1287, you can detect an end-of-file by pressing the end-of-file key after the end of the tape is sensed. When IOCS detects an end-of-file condition, it branches to your routine specified by EOFADDR. You must determine if the current roll is the last roll to be processed when handling journal tapes. Regardless of the situation, the tape file must be closed for each roll within your EOF routine. If the current roll is not the last, OPEN (or OPENR) must be issued. The OPEN (or OPENR) macro allows header (identifying) information to be entered at the reader keyboard and read by the processor when using logical IOCS. Part 2. Sequential Access Method 81 The same procedure can be used for 1287 processing of multiple journal tape rolls, as well as the method described under OPEN (or OPENR) Macro in the section Imperative Macros later in this chapter. HEADER=YES This operand is required if the operator is to key in header (identifying) information from the 1287 keyboard. The OPEN (or OPENR) routine reads the header information only when this entry is present. If the entry is not included, OPEN (or OPENR) assumes no header information is to be read. The header record size can be as large as the BLKSIZE entry and is read into the high-order positions of IOAREAl. This operand cannot be used for 1288 files. HPRMTY=YES This operand is included if you want to be informed of the hopper empty condition. This condition occurs when a READ is issued and no document is present, and is recognized at WAITF time. When a hopper empty condition is detected, your COREXIT routine is entered with the condition indicated as X'02' in filename+80. This operand should be used when processing documents in the time-dependent mode of operation, which allows complete overlapping of processing with reading. (See Method 2 under Programming the 1287 in IBM 1287 Optical Reader Component Description and Operating Procedures, GA219064). With this method of processing, the HPRMTY parameter allows you to check for a hopper empty condition in your COREXIT routine. You can then select into the proper hopper the previously ejected document before return from COREXIT (via register 14). IOAREAl = name This operand is included to specify the name of the input area used by the file. When opening a file and before each journal tape input operation to this area, the designated area is set to binary zeros and the input routines then transfer records to this area. For document processing, the area is cleared only when the file is opened. IOAREA2=name A second input area can be allotted only for a journal tape file. This permits an overlap of data transfer and processing operations. The specified second 1/0 area is set to binary zeros before each input operation to this area occurs. 82 DOS/VS Supervisor & I/O Macros IOREG=I(~) I (r)} This operand specifies a general-purpose register (2-12) that the input routines use to indicate the beginning of records for a journal tape file. The same register may be specified in the IOREG operand for two or more files in the same program, if desired. In this case, your program may need to store the address supplied by IOCS for each record. Whenever this entry is included for a file, the DTFOR entry WORKA must be omitted, and the GET macro must not specify a work area. A read by an optical reader is accomplished by a backward scan. This places the rightmost character in the record in the rightmost position in the 1/0 area and subsequent characters in sequence from right to left. The register defined by IOREG indicates the leftmost position of the record. MODNAME = name This operand may be used to specify the name of the logic module used with the DTF table to process the file. If the logic module (ORMOD) is assembled with the program, the MODNAME parameter in this DTF must specify the same name as the ORMOD macro. If this entry is omitted, standard names are generated for calling the logic module. If two different DTF macros call for different functions that can be handled by a single module, only one standard-named module is called. RECFORM=IFIXUNB I FIXBLK I UNDEFJ This operand specifies the type of records in an optical reader file. One of the following specifications may be entered immediately after the = sign: FIXUNB For fixed-length unblocked records. FIXBLK For fixed-blocked records in journal tape mode. UNDEF For undefined records. . RECSIZE= n II(~) I (r)J For fixed-length unblocked records, this operand should be omitted and no register is assumed. For fixed-length blocked records (journal tape mode), this operand must be included to specify the number, n, of characters in an individual record. The input routines use this number to deblock records, and to check the length of input records. If this operand is omitted, an MNOTE is flagged in the macro assembly and fixed-length unblocked records are assumed. operation field and may contain a module name in the name field. For undefined journal tape records, this entry specifies the number (r) of the general-purpose register in which IOCS provides the length of each input record. For undefined document records, RECSIZE contains only the length of the last field of a document read by the CCW chain which you supply. Any register 2-12 may be specified, but if the entry is omitted, register 3 is assumed. Note: ORMOD is not used for the 3881 Optical Mark Reader. The 3881 uses CDMOD. Note: When processing undefined records in document mode, you gain complete usage of the register normally used in the RECSIZE operand. You can do this by ensuring that the suppress-length-indication (SLI) flag is always on when processing undefined records. SEPASMB=YES Include this operand only if the DTFOR is assembled separately. This causes a CATALR card with the filename to be punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. If t~e operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. WORKA=YES Input records (journal tape only) can be processed in work areas instead of in the input areas. If this is planned, the operand WORKA= YES must be specified,. and you must set up the work area in storage. The symbolic name of the work area, or a generalpurpose register containing the address of the work area, must be specified in each GET macro. When GET is issued, IOCS left-justifies the record in the specified work area. Whenever this operand is included for a file, the DTFOR IOREG operand must be omitted. 1288 Optical Page Reader Programming Considerations After a 1288 file is defined, the OPEN or OPENR macro makes it available for input. Processing is then accomplished by the CNTRL, READ, RESCN, and WAITF macros. When processing is completed, the CLOSE or CLOSER macro deactivates the file. 1288 processing adheres closely to the macros and DTF specifications used for 1287 document processing. ORMODMacro Listed here are the operands you can specify for ORMOD. The first card contains ORMOD in the IOAREA2=YES Include this operand (journal tape only) if a second 1/0 area is used. The DTFOR used with this module must also include the IOAREA2 parameter. RECFORM=IFIXUNB I FIXBLK I UNDEF} This operand generates a module that processes the specified record format. Any DTF used with the module must have the same operand. BLKFAC=YES Include this operand if RECFORM= UNDEF and groups of undefined journal tape records are to be processed as blocks of data. (See the DTFOR BLKFAC=n operand.) The DTFOR used with this module must also include RECFORM= UNDEF and BLKFAC=n. CONTROL=YES Include this operand if CNTRL macros are to be used with the associated DTFs. The module also processes files that do not use the CNTRL macro. DEVICE=U287D I 1287T} This operand must be included to specify the I/O device associated with this file. 1287D specifies a 1287 or 1288 document file. 1287T specifies a 1287 journal tape file. SEPASMB=YES Include this operand only if the module is assembled separately. This causes a CATALR card with the module name (standard or user-specified) to be punched ahead of the object deck and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. WORKA = YES Include this operand (journal tape only) if records are to be processed in work areas instead of in I/O areas. Any DTF used with the module must have the same operand. Standard ORMOD Names Each name begins with a 3-character prefix (11M) followed by a 5-character field corresponding to the Part 2. Sequential Access Method 83 options permitted in the generation of the module. ORMOD name a =F = UMabcde Figure 2-18 defines the filename specified by the ASOCFLE operand for each of the associated DTFs. RECFORM=FIXUNB In ASOCFLE operand of .,. = X RECFORM=FIXBLK = U RECFORM=UNDEF = D RECFORM=UNDEF and BLKFAC=YES FUNC= read DTFCD, specify filename of RW print DTFPR b = C CONTROL=YES = Z CONTROL=YES is not specified c =I IOAREA2=YES = W WORKA=YES = d e B both are specified neither is specified =Z =T =D =Z RPW punch DTFCD print DTFPR, specify filename of read DTFCD print DTFPR PW device is in tape mode device is in document mode punch DTFCD, specify filenarne of print DTFPR punch DTFCD read DTFCD always Subset/Superset ORMOD Names The following chart shows the subsetting and supersetting allowed for ORMOD names. One of the parameters allows subsetting. For example, the module IJMFCITZ is a superset of the module UMFZITZ. See IOCS Subset/Superset Names in The Macro System chapter. * +* * I IT H D C B D Z F Z I T U W X Z + Supersetting/subsetting permitted. * No subsetting/supersetting permitted. Figure 2-18 For example, if FUNC=PW is specified, specify the filename of the print DTFPR in the ASOCFLE operand of the punch DTFCD, and specify the filename of the punch DTFCD in the print DTFPR. Or if FUNC=RPW is specified, specify the filename of the punch DTFCD in the ASOCFLE operand of the read DTFCD; specify the filename of the print DTFPR in the punch DTFCD; and specify the filename of the read DTFCD in the print DTFPR. BLKSIZE= n This operand specifies the length of IOAREA 1. If the record format is variable or undefined, enter the length of the longest record. The maximum value which may be specified is: DTFPR Macro 151 for the 1403, 1443, 3203, or 3211 Enter the symbolic name of the file in the name field and DTFPR in the operation field. The detail entries follow the DTFPR header card in any order. Figure 2-19 lists the keyword operands contained in the operand field. ASOCFLE=filename This operand is used together with the FUNC operand to define associated files for the 2560, 3525, or 5425. (For a description of associated files see the DOS/VS Data Management Guide, GC33-5372.) ASOCFLE specifies the filename of an associated read and/or punch file, and enables macro sequence checking by the logic module of each associated file. One filename is required per DTF for associated files. 84 DOS/VS Supervisor ASOCFLE operand usage with print associated files & I/O Macros • • 384 for the 2560 64 for the 3525 128 for the 5203 or 5425 If this entry is omitted: • • 121 is assumed for the 1403, 1443, 3203, or 3211 64 is assumed for the 2560 or 3525 96 is assumed for the 5203 or 5425 CONTROL=YES This operand is specified if the CNTRL macro will be issued for the file. If this operand is specified, omit CTLCHR. This operand is not allowed for the 2560 or 5425. CTLCHR= IYES 1ASAI This operand is specified if firstcharacter-control is used. The parameter ASA specifie:; the American National Standards Institute, Inc. character set. The entry CTLCHR=YES specifies the System/370 character set. Appendix A contains the control character codes. If this parameter is specified, omit CONTROL. This operand must not be specified for the 2560 or 5425. If CTLCHR=ASA is specified for the 3525, the + character is not allowed. When CTLCHR=ASA is specified for 3525 print (not associated) files, you must issue either a space 1 command or skip to channel 1 command to print on the first line of a card. For 3525 print associated files, you must issue a space 1 command to print on the first line of a card. DEVADDR= ISYSLOG 1SYSLST 1SYSnnnl This operand specifies the symbolic unit to be associated with the printer. SYSLOG and SYSLST must not be specified for the 2560, 3525, or 5425. I DEVICE=U403 11443 12560P 12560S 132031 3211 1352515203 15425PI 5425S1 This operand specifies which device is used for the file. The "p" and "s" included with the "2560" and "5425" parameters specify primary or secondary input hoppers. If this operand is omitted 1403 is assumed. ERROPT=IRETRY 1IGNORE 1namel This operand specifies the action to be taken in the case of an equipment check error. The functions of the parameters are described below. RETRY can be specified only for the 3211. RETRY indicates that if an equipment check with command retry is encountered, the command is retried once. If the retry is unsuccessful a message is issued and the job canceled. IGNORE can be specified only for the 3525. IGNORE indicates that the error is to be ignored. The address of the record in error is put in register 1 and made available for processing. Byte 3, bit 3 of the CCB is also set on (see Figure 6-2); you can check this bit and take the appropriate action to recover from the error. IGNORE must not be specified for files with two 110 areas or a work area. The name parameter can be specified only for the 3211. It indicates that when an equipment check with command retry is encountered, the command is retried once. If the retry is unsuccessful a message is issued and the job canceled. With other types of errors (for these see the CCB, Figure 6-2) an error message is issued, error information is placed in the CCB, and control is given to your error routine, where you may perform whatever actions are desired. If any IOCS macros are issued in the routine, register 14 must be saved; if the operand RDONL Y = YES is specified, register 13 must also be saved. To continue processing at the end of the routine, return to IOCS by branching to the address in register 14. FUNC=IWITII RWITII RPWITII PWITII This operand specifies the type of file to be processed by the 2560, 3525, or 5425. W indicates print, R indicates read, P indicates punch, and T (for the 3525 only) indicates an optional 2-line printer. RW[T], RPW[T], and PW[T] are used, together with the ASOCFLE operand, to specify associated files; when one of these parameters is specified for a printer file it must also be specified for the associated file(s). If a 2-line printer is not specified for the 3525, multi-line print is assumed. T is ignored if CONTROL or CTLCHR is specified. Part 2. Sequential Access Method 85 I M DEV ADDR=SYSxxx Symbolic unit for the printer used for this file. M 10AREA 1=xxxxxxxx Name for the first output area. 0 ASOCFLE=xxxxxxxx Name of the associated file for FUNC=RW, RPW, PW. 0 BLKSIZE=nnn Length of one output area, in bytes. If omitted, 121 is assumed for 1403, 1443, 3203 or 3211; 64 is assumed for 2560 or 3525, 96 is assumed for 5203 or 5425. 0 CONTROL=YES CNTRL macro used for this file. Omit CTLCHR for this file. Not allowed for 2560 or 5425. 0 CTLCHR=xxx (YES or ASA). Data records have control character. YES for S/370 character set; ASA for American National Standards Institute character set. Omit CONTROL for this file. Not allowed for 2560 or 5425. 0 DEVICE=nnn (1403, 1443, 2560P, 2560S, 3203, 3211,3525,5203, 5425P, 5425S). If omitted, 1403 is assumed. 0 ERROPT=xxxxxxxx RETR Y or the name of your error routine for 3211. IGNORE for 3525. Not allowed for other devices. 0 FUNC=xxxx (W, RW, RPW, PW) for 2560 or 5425. (W[T), RW[T), RPW[T], PW[T) for 3525. 0 IOAREA2=xxxxxxxx If two output areas are used, name of second area. 0 10REG=(nn) Register number, if two output areas used and PUT does not specify a work area. Omit WORKA. 0 MODNAME=xxxxxxxx Name of PRMOD logic module for this DTF. If omitted, 10CS generates standard name. 0 PRINTOV=YES PRTOV macro used for this file. Not allowed for 2560 or 5425. 0 RDONLY=YES Generate a read-only module. Requires a module save area for each task using the module. 0 RECFORM=xxxxxx (FlXUNB, V ARUNB, or UNDEF). If omitted, FlXUNB is assumed. 0 RECSIZE=(nn) Register number if RECFORM=UNDEF. I M=Mandatory; O=Optional Figure 2-19 86 DTFPR macro (part 1 of 2) DOS/VS Supervisor & I/O Macros 0 SEPASMB=YES DTFPR is to be assembled separately. 0 STLIST=YES 1403 selective tape listing feature is to be used. Operand valid for DOS only. 0 UCS=xxx (ON) process data checks, (OFF) ignores data checks. Only for printers with the UCS feature or 321 1. If omitted, OFF is assumed. 0 WORKA=YES PUT specifies work area. Omit fOREG. M=Mandatory; O=Optional Figure 2-19 DTFPR macro (part 2 of 2) IOAREAl = name This operand specifies the name of the output area. IOAREA2=name This operand specifies the name of a second output area. IOREG=(r) If two output areas and no work areas are used, this operand specifies the address of the area where you can build a record. For (r) specify one of the registers 2-12. MODNAME=name This operand may be used to specify the name of the logic module that is used with the DTF table to process the file. If the logic module is assembled with the program, MODNAME must specify the same name as the PRMOD macro. If this operand is omitted, standard names are generated for calling the logic module. If two DTF macros call for different functions that can be handled by a single module, only one module is called. PRINTOV=YES This operand is specified if the PRTOV macro is included in your program. This operand is not allowed for the 2560 or 5425. RDONLY=YES This operand is specified if the DTF is used with a read-only module. Each time a read-only module is entered, register 13 must contain the address of a 72-byte doubleword-aligned save area. Each task requires its own uniquely defined save area. Each time an imperative macro (except OPEN or OPENR) is issued, register 13 must contain the address of the save area associated with the task. The fact that the save areas are unique for each task makes the module reentrant (that is, capable of being used concurrently by several tasks). For more information see Shared Modules and Files in the Multitasking Macros chapter. If an ERROPT routine issues I/O macros which use the same read-only module that caused control to pass to either error routine, your program must provide another save area. One save area is used for the normal I/O, and the second for I/O operations in the ERR OPT routine. Before returning to the module that entered the ERROPT routine, register 13 must be set to the save area address originally specified for the task. If this operand is omitted, the module generated is not reenterable and no save area need be established. RECFORM=IFIXUNB I UNDEF I VARUNB} The operand RECFORM=FIXUNB is specified whenever the record format is fixed. When the record format is FIXUNB, this entry may be omitted. The entry RECFORM= UNDEF is specified whenever the record format is undefined. If the output is variable and unblocked, enter VARUNB. RECSIZE=(r) This operand specifies the general register (2-12) that will contain the length of the output record of undefined format. The length of each record must be loaded into the register before issuing the PUT macro. SEPASMB=YES Include this operand only if the DTFPR is assembled separately. This causes a CAT ALR card with the filename to be punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. If the operand is omitted, the program asPart 2. Sequential Access Method 87 sumes that the DTF is being assembled with the problem program and no CATALR card is punched. have the same operand. If CTLCHR is specified, CONTROL must not be specified. STLIST=YES CTLCHR must not be specified for the 2560 or 5425. If CTLCHR=ASA is specified for the 3525, the + character is not allowed; when CTLCHR=ASA is specified for 3525 print (not associated) files, you must issue either a space 1 command or skip to channel 1 command to print on the first line of a card. For 3525 print associated files, you must issue a space 1 command to print on the first line of a card. If CTLCHR=ASA and RDONL Y = YES are specified in a multitasking environment where more than one DTFPR uses the same module, overprinting may occur. Include this operand if the selective tape listing feature (1403 only) is used. If this entry is specified, the CONTROL, CTLCHR, and PRINTOV entries are not valid and will be ignored if specified. If this operand is specified, RECFORM must have the parameter FIXUNB. UCS={OFF ION} I For a 1403 or 5203 printer with the universal character set feature or for a 3203 or a 3211, this operand determines whether data checks occurring in case of unprintable characters are indicated to the operator, printed as blanks, or ignored. The entry is especially useful if you are using first-character forms control and have modules that cannot process the CNTRL macro. ON Data checks are processed with an operator indication. OFF Data checks are ignored and blanks are printed for the unprintable character. WORKA=YES If output records are processed in work areas instead of in the 110 areas, specify this operand. You must set up the work area in storage. The address of the work area, or a general-purpose register which contains the address, must be specified in each PUT macro. PRMOD Macro j WlListed here are the operands you can specify for PRMOD. The first card contains PRMOD in the operation field and may contain a module name in the name field. CONTItOL=YES Include this operand if CNTRL macros are used with the associated DTFs. The module also processes files that do not use the CNTRL macro. If CONTROL is specified, the CTLCHR operand must not be specified. DEVICE = {1403 11443 12560P 12560S 132031 3211 13525 15203 15425PI 5425S} This operand specifies which device is used for the file. The "p" and "s" included with the "2560" and "5425" parameters specify primary or secondary input hoppers; regardless of which is specified, however, the module generated will handle DTFs specifying either hopper. Any DTF to be used with this module must have the same operand (except as just noted concerning the "p" and "s" specification for the 2560 or 5425). ERROPT=YES This operand must be specified if ERROPT=name is specified in a DTFPR to be used with the module. (ERROPT=name is applicable to the 3211 only.) If ERROPT is not specified in the DTFPR, or if ERROPT=RETRY (3211) or ERROPT=IGNORE (3525) is specified, ERROPT= YES must be omitted. FUNC={W(T) 1RW(T) 1RPW(T) 1PW(T)} This operand specifies the type of file to be processed by the 2560, 3525, or 5425. Any DTF used with the module must include the same operand. W indicates print, R indicates read, P indicates punch, and T (for the 3525 only) indicates an optional 2line printer. The CONTROL operand is not allowed for the 2560 or 5425. RW[T], RPW[T], and PW[T] are used to specify associated files; when one of these parameters is specified for a printer file it must also be specified for the associated file(s). CTLCHR={YES 1ASA} If a 2-line printer is not specified for the 3525, Include this operand if first-character carriage control is used. Any DTF used with the module must multi-line print is assumed. T is ignored if CONTROL or CTLCHR is specified. 88 DOS/VS Supervisor & I/O Macros IOAREA2=YES Include this operand if a second 110 area is used. Any DTF used with the module must also include the IOAREA2 operand. PRINTOV=YES Include this operand if PRTOV macros are used with the associated DTFs. The module also processes any files that do not use the PRTOV macro. b = A CTLCHR=ASA = Y CTLCHR= YES = C CONTROL=YES = S STLIST = YES = Z none of these is specified = T DEVICE=3525 with 2-line printer = U DEVICE=2560 = V DEVICE=5425 c This operand is not allowed for the 2560 or 5425. RDONLY=YES This operand causes a read-only module to be generated. Whenever this operand is specified, any DTF used with the module must have the same operand. RECFORM={FIXUNB I VARUNB I UNDEFJ This operand causes a module to be generated that processes the specified record format: fixed-length, variable-length, or undefined. Any DTF used with the module must include the same operand. WORKA=YES Include this operand if records are processed in work areas instead of in 110 areas. Any DTF used with the module must have the same operand. Standard PRMOD Names Each name begins with a 3-character prefix (IJD) followed by a 5-character field corresponding to the options permitted in the generation of the module. PRMOD name a =F = UDabcde RECFORM=FIXUNB = V RECFORM=VARUNB = U RECFORM=UNDEF ERROPT=YES and PRINTOV=YES = P PRINTOV=YES, DEVICE is not 3525, and ERROPT is not specified = I PRINTOV=YES, DEVICE=3525, and FUNC= W[T] or omitted =F PRINTOV=YES, DEVICE=3525, and FUNC=RW[T] =C PRINTOV=YES, DEVICE=3525, and FUNC=PW[T] = D PRINTOV=YES, DEVICE=3525, and FUNC=RPW[T] = Z PRINTOV=YES and ERROPT are not specified and DEVICE is not 2560, 3525, or 5425 = 0 PRINTOV=YES not specified, DEVICE=3525, and FUNC= W[T] or omitted SEPASMB=YES Include this operand only if the module is assembled separately. This causes a CATALR card with the module name (standard or user-specified) to be punched ahead of the object deck and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CAT ALR card is punched. STLIST=YES Include this operand if the selective tape listing feature (1403 only) is used. If this entry is specified, the CONTROL, CTLCHR, and PRINTOV entries are not valid, and are ignored if supplied. If this operand is specified, RECFORM must have the parameter FIXUNB. =B = R PRINTOV=YES not specified, DEVICE=3525, and FUNC=RW[T] =S PRINTOV=YES not specified, DEVICE=3525, and FUNC=PW[T] =T PRINTOV=YES not specified, DEVICE=3525, and FUNC=RPW[T] =E ERROPT=YES and PRINTOV=YES is not specified =U FUNC=W or omitted and DEVICE=2560 or 5425 = V FUNC=RW and DEVICE=2560 or 5425 = W FUNC=PW and DEVICE=2560 or 5425 = X FUNC=RPW and DEVICE=2560 or 5425 d = I IOAREA2= YES = Z IOAREA2=YES is not specified e =V -c::~...- RDONLY=YES and WORKA=YES = W WORKA";YES =Y RDONLY=YES = Z neither is specified Subset/Superset PRMOD Names The following chart shows the subsetting and supersetting allowed for PRMOD names. Two of the parameters allow subsetting. For example, the module name UDFCPIW is a superset of the module names UDFCZIW and UDFZZIW. No subsetting/ supersetting of PRMOD names is allowed for the 2560 or 5425. See IOCS Subset/Superset Names in The Macro System chapter. Part 2. Sequential Access Method 89 I ~1 * * * * * D F A U I V y V Z U S l\f T X U v + + p V W y Z Z C Z I 0 + + F R + C S + record. For fixed-length records, this area must be the same size as the record. If shift and delete characters are included in the record (the SCAN entry is specified), BLKSIZE indicates the number of characters required by the program after translation and compression. OVBLKSZ contains the number of characters to be read in to produce the BLKSIZE number. Output: For undefined records, the area must be at least equal to the longest record, including all shift characters that are to be included in the record. For fixed-length records, the area must be the same size as the record. For shifted codes (when the FSCAN and LSCAN entries are specified), BLKSIZE must contain the number of characters before translation and insertion of shift characters. OVBLKSZ must contain the number of characters after translation and insertion of shift characters. 0 T + B E * No subsetting/supersetting pennitted. + Subsetting/supersetting pennitted. DTFPT Macro A DTF entry is included for every paper tape input or output file that is processed by the program. The characteristics of a paper tape file are given in the DOS/VS Data Management Guide, GC33-5372. The first entry must be the DTFPT header entry. Enter the symbolic name of the file in the name field, and DTFPT in the operation field. The detail entries follow the DTFPT header card in any order. Figure 2-20 lists the keyword operands contained in the operand field. BLKSIZE=n This operand specifies the length of the input or output area. The maximum block size is 32,767 bytes. Input: For undefined records, this area must be at least one byte larger than the longest record including all shift and delete characters included in the 90 DOS/VS Supervisor & I/O Macros DELCHAR= X'nn' This operand specifies the configuration of the delete character and must be used for output files only, that is, when DEVICE= 1018 is specified. The constant X'nn' consists of two hexadecimal digits. The delete character is used in the error recovery procedure, and you must specify the correct configuration in accordance with the number of tracks of the output tape, as follows: X' IF' for five tracks. X'3F' for six tracks. X'7F' for seven tracks. X'FF' for eight tracks. Note: The delete character ~s required only if the 1018 has the error correction feature. DEVADDR=SYSnnn This operand speCifies the logical unit (SYSnnn) associated with this file. An actual channel and unit are assigned to the unit by an ASSGN job control statement. The ASSGN statement contains the same symbolic name as DEVADDR. DEVICE={26711101711018J This operand is required only to specify an I/O device other than 2671. If this entry is omitted, 2671 is assumed. Applies to .... = .... 0. ....= - 0 x x M BLKSIZE=n Length of your I/O areas. X X M DEY ADDR=SYSnnn Symbolic unit to be associated with this file. X X M 10 AREA 1=xxxxxxxx Name of first I/O area. 0 EOFADDR=xxxxxxxx Name of your end-of-file routine. X 0 DELCHAR=x'nn' Delete character. X 0 DEYICE=nnnn (2671, 1017, 1018). If omitted, 2671 is assumed. X 0 EORCHAR=x'nn X 0 ERROPT =xxxxxxxx (IGNORE, SKIP, or error routine name). Prevents job termination on error records. X 0 FSCAN=xxxxxxxx (For shifted codes). Name of your scan table used to select figure groups. 0 FfRANS=xxxxxxxx (For shifted codes). Symbolic address of your figure shift translate table. 0. I:: = X X X X , End-of-record character. (For RECFORM= UNDEF). X X 0 IOAREA2=xxxxxxxx Name of second I/O area. X X 0 IOREG=(nn) Used with two I/O areas. Register (2-12) containing current record address. X 0 LSCAN=xxxxxxxx (For shifted codes). Name of your scan table used to select letter groups. 0 LTRANS=xxxxxxxx (For shifted codes). Name of your letter shift translate table. X X X 0 MODNAME=xxxxxxxx For module names other than standard. X X 0 OYBLKSZ=n Used if I/O records are compressed or expanded. X X 0 RECFORM=xxxxxx (FIXUNB or UNDEF). If omitted, FIXUNB is assumed. M=Mandatory; O=Optional Fagure 2-20 DTFPT macro operands (part t of 2) Part 2. Sequential Access Method 91 Applies to ..... =' a. -= x = S=' 0 x X 0 RECSIZE=(nn) Register containing the record length. 0 SCAN =xxxxxxxx Name of your scan table for shift or delete character. X X 0 SEPASMB= YES DTF is assembled separately. X X 0 TRANS=xxxxxxxx Name of your table for code translation. 0 WLRERR=xxxxxxxx Name of wrong-length-record error routine. X M=Mandatory; O=Optional Figure 2-20 DTFPT macro operands (part 2 of 2) EOFADDR = name This operand specifies the name of your end-of-file routine. IOCS automatically branches to this routine on an end-of-file condition if the end-of-file switch is set on. The routine can execute any operation required for the end-of-file, issue the CLOSE or CLOSER macro for the file, or return to 10CS by branching to the address in register 14. In the latter case, IOCS reads in the next record. The end-of-file condition cannot occur on the 1018. EORCHAR=X'nn' This operand specifies the user-defined end-ofrecord (EOR) character, where nn is two hexadecimal digits. It must be used for output files with undefined record format only. IOCS writes this character after the last character of the undefined record. ERROPT={IGNORE I SKIP I namel This operand is specified if you do not want a job terminated when standard recovery procedure cannot recover from a read or write error. If the ERROPT entry is omitted and a read or write error occurs, IOCS terminates the job. cord as if no errors were detected. The ERROPT=SKIP option is ignored and causes IOCS to terminate the job. If two I/O areas are used, the CLOSE or CLOSER macro checks the last record, and the ERROPT=name option is treated as the ERROPT=IGNORE option. If IGNORE and SKIP are not specified, the name of your error routine must be supplied to process errors. On an error condition, IOCS reads or writes the complete record, including the error character(s), and then branches to the error routine. At the end of the eHor routine, return to IOCS by branching to the address in register 14. The next record is then read or written. You must not issue any GET or PUT macros for records in the error block. If the error routine contains any other 10CS macros, the contents of register 14 must be saved and restored. For input files, IGNORE allows IOCS to handle the record as if no errors were detected. If SKIP is specified, IOCS skips the record in error and reads the next record. FSCAN=name This operand must be included for every output file using a shifted code. For an input file, omit this operand. It specifies the name of a scan table in your program used to select groups of figures. This table must conform to the specifications of the machine instruction TRT. The entry in the table for each letter character must be the letter shift character, and all other entries must be hexadecimal zero. Any deviation from this results in incorrect translation. For output files with shifted codes, no ERROPT can be specified. For unshifted codes, the options ERROPT=IGNORE and ERROPT=name can be specified. IGNORE allows IOCS to handle the re- FTRANS = name This operand must be included for every input file using a shifted code and is not permitted for output files. It specifies the name of a figure shift table in 92 DOS/VS Supervisor & I/O Macros your program. This table must conform to the specifications of the machine instruction TR. IOAREAl =name This operand specifies the name of an input or output area. IOAREA2=name This operand specifies the name of a second input or output area. When this operand is specified, 10CS overlaps the 110 operation in one area with the processing of the record in the other. IOREG=(r) This operand must be included if two input or output areas are used. For input, it specifies the register into which 10CS puts the address of the logical record available for processing. For output, it specifies the address of the area into which your program can build a record. Any register from 2 to 12 may be specified. LSCAN=name This operand must be included for every output file using a shifted code and is not permitted for input files. It specifies the name of a scan table in your program used to select groups of letters. This table must conform to the specifications of the machi~e instruction TRT. The entry in the table for each figure character must be the figure shift character, and all other entries must be hexadecimal zero. Any deviation from this results in incorrect translation. LTRANS = name This operand must be included for every input file using a shifted code and is not permitted for output files. It specifies the name of a letter shift table in your program. This table must conform to the specifications of the machine instruction TR. MODNAME = name This operand may specify the name of the logic module used with the DTF table to process the file. If the logic module is assembled with the program, the MODNAME operand in this DTF must specify the same name as the PTMOD macro. If MODNAME=name is omitted, IOCS generates standard names for calling the logic module. OVBLKSZ=n For input files, this operand specifies the number of characters to be read (before translation and compression) to produce the number of characters specified in the BLKSIZE entry. OVBLKSZ is used only when SCAN and RECFORM=FIXUNB are both specified. If OVBLKSZ is omitted, 10CS assumes the number of characters to be read is equal to the number specified in the BLKSIZE entry. The maximum value is 32,767 bytes. For output files, OVBLKSZ specifies the number of characters indicated in the BLKSIZE entry, plus the number of shift characters to be inserted. If the size of OVBLKSZ is large enough to allow the insertion of all the shift characters required to build the output record, a single WRITE operation results from a PUT macro. On the other hand, if the size of OVBLKSZ (which must be at least one position larger than BLKSIZE) does not permit the insertion of all the shift characters, several WRITE operations result from a PUT macro. OVBLKSZ is used only when LSCAN and FSCAN are specified with the FIXUNB format. If OVBLKSZ is specified with UNDEF format, it is ignored. RECFORM=IFIXUNB I UNDEF} This operand specifies the record format for the file. Specify either format for shifted or unshifted codes. If the record format is FIXUNB, this entry may be omitted. RECSIZE=(r) This operand specifies the number of a register (212) that contains the length of the input or output record. This entry is optional for input files. If present, IOCS loads the length of each record read into the specified register. If input files contain shift codes or other characters requiring deletion, 10CS loads the compressed record length into the specified register. For output files, this entry must be included for undefined records. Before translation, your program must load each record length into the designated register before issuing the PUT macro for the record. SCAN = name This operand must be included for all input files using shifted codes. It may also be inGluded if you wish to delete certain characters from each record. The SCAN entry specifies the symbolic name of a table provided by your program. This table must conform to the specifications of the machine instruction TRT. It must contain nonzero entries for all delete characters and, where appropriate, for the figure and letter shift characters. The table entry for the figure shift character must be hexadecimal 04, and hexadecimal 08 for the letter shift character. Delete entries must be hexadecimal OC. All other entries in the table must be hexadecimal 00. OtherPart 2. Sequential Access Method 93 wise, incorrect translation results and may produce a program check. length error routines, the contents of register 14 must be saved and restored. The table must be large enough to hold the maximum value of coding for the tape being processed; that is, 255 bytes for 8-track tape. This prohibits erroneous coding on the tape from causing a scan function beyond the limits of the scan table. Note: A wrong-length condition appears during the first read operation on a 1017 if the combined length of the tape leader and the first record is greater than the length of the longest record anticipated (the length specified in BLKSIZE). SEPASMB=YES Include this operand only if the DTFPT is assembled separately. This causes a CAT ALR card with the filename to be punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. Paper Tape Processing Considerations TRANS=nHle The TRANS operand specifies the symbolic name of a table provided within your program. This table must conform to the specifications of the machine instruction TR. For input files, include this entry if a nonshifted code is to be translated into internal System/370 code. Omit the FTRANS and LTRANS entries if this entry is present. If none of these three entries is present, no translation takes place. For output files, include this entry if the internal System/370 code is translated into a shifted or nonshifted code, depending on whether the FSCAN and LSCAN entries are present or omitted. WLRERIl =name This operand applies only to paper tape input files when RECFORM= UNDEF is specified. When IOCS finds a wrong-length record, it branches to the symbolic name specified in the WLRERR , entry. If this entry is omitted and the ERROPT entry is included, IOCS considers the error uncorrectable and uses the ERROPT option specified. Absence of both ERROPT and WLRERR entries causes the wrong-length record to be accepted as a normal record. Wrong-length checking is not performed for fixed-length records because a fixed number of characters is read in each time. IOCS detects overlength undefined records when the incoming record fills the input area. The input area must, therefore, be at least one position longer than the longest record anticipated. At the end of the WLRERR routine, return to IOCS by branching to the address in register 14. The next IOCS read operation will normally cause the remainder of the overlength, undefined record to be read. If any other IOCS macros are included in the record-· 94 DOS/VS Supervisor & I/O Macros EOF Condition (Input Only) The EOF condition occurs with an end-of-tape condition when the EOF switch is on. When IOCS detects this EOF condition (unit exception flag on in first CSW status byte), it automatically branches to your end-of-file routine. However, at the end of the routine, you can choose to return to IOCS to read a new tape by branching to the address in register 14. If any IOCS macro is contained in this routine, the contents of register 14 must be saved and restored. If an end-of-tape condition is detected while reading characters other than blanks or deletes (all punched holes), the unit check bit in the first CSW status byte is set on. This applies only to the 1017, and causes the broken tape bit (bit 7) to appear in the sense byte. The broken tape condition may occur in addition to the EOF condition if the EOF switch is on. Trailer Length (Input Only) To avoid a broken tape condition that would result if the tape trailer is too short, the length of the trailer must be greater than: • For undefined records (read-EOR command): 2 inches. For fixed unblocked records (read command): Byte Count 10 + 2 inches Note: Byte count is either the count specified in BLKSIZE (record without shifted codes or records with shifted codes but without using the OVBLKSZ operand in the DTFPT), or the count specified in OVBLKSZ (records with shifted codes using the OVBLKSZ operand). However, when processing undefined records, and a trailer greater than BLKSIZE + 2 inches 10 Following an ignore decision, logical IOCS takes action in accordance with the parameter specified in ERROPT. is read, this trailer will be mistaken for a wronglength record. Error Conditions The paper tape reader or punch stops immediately on an error condition. If the error cannot be corrected and the job is not terminated, IOCS causes the entire record containing the error to be: • Translated and compressed, if needed (for input records). • Translated, expanded, and punched, before taking the error option specified by the problem program (for output records). Wrong Length For input files, the only wrong-length condition that can be detected is an overlength undefined record. This should be reflected in the BLKSIZE operand. Wrong-length record indication is impossible with fixed unblocked records, because each record is a sequence of a specified number of characters. Use the FIXUNB record format carefully, because specifying one character too few or too many in any record .causes all subsequent records to be out of phase. The problem program should use the RECSIZE operand to check for the correct length of the last record of any file. A record must be entirely on one reel of input tape. ERROPT=IGNORE The record is handled as if no errors were detected. ERR OPT = SKIP The erroneous record is skipped and the next record is read in. ERROPT=name The record is handled as if no errors were detected, and control is given to your error routine. At the end of this routine, return to IOCS by branching to the address in register 14. The next record is then read in or written out. ERR OPT = omitted The job is canceled. Note 1: The character in error is repunched preceded by its corresponding shift character: For output records expressed in a paper tape code where the delete character and one of the shift characters have the same configuration. Following a data check. Data Check The following shows the decision taken by logical IOCS, or possible operator actions, after an irrecoverable data check occurs: Type of Record Processed Input Operation Output Operation Fixed unblocked record in shifted code Action 1 Action 1 Fixed unblocked record in nonshifted code Action 2 Action 2 Undefined record in nonshifted code Action 2 Action 2 Undefined record in shifted code Action 2 Action 1 Action 1: Action 2: j Note 2: The entire erroneous record is repunched as if no errors were detected: • If an irrecoverable error occurs and ERROPT=name or ERROPT=IGNORE was specified in the DTFPT. • In the case of output records with two 110 areas, the CLOSE or CLOSER macro checks the successful completion of the last operation. Note 3: No error condition occurs on the 1018 if the setting of the tape width selector does not match the tape code specified in the problem program. The system automatically cancels the job. The operator may choose to: • cancel the job • ignore the error • retry the operation (for 2671 only) Part 2. Sequential Access Method 95 Note 4: When reading paper tape with physical 10CS, restore the CCW address in the CCB before using the EXCP macro. Programming Considerations For information about special equipment considerations for paper tape devices, refer to IBM 2671 Paper Tape Reader and IBM 2822 Paper Tape Reader Control, GA24-3388, and IBM System/360 Component Descriptions: 2826 Paper Tape Control Unit, 1017 Paper Tape Reader, 1018 Paper Tape Punch, GA33-4500. specified. Summary of PTMOD Figure 2-21 shows the only possible combinations of PTMOD operands and describes the resultant modules. Standard PTMOD Names Each name begins with a 3-character prefix (IJE) and continues with a 5-character field corresponding to the options permitted in the generation of the module. PTMOD Macro Listed here are the operands you can specify for PTMOD. The first card contains PTMOD in the operation field and may contain a module name in the name field. DEVICE={26711101711018} Required only to specify an I/O device other than 2671 used by the module. Any DTF used with the module must have the same operand. 2671 is assumed if this operand is omitted. RECFORM={FIXUNB I UNDEF} Required only if the operand SCAN = YES is present. If records of undefined format using the SCAN option are translated, specify the UNDEF parameter. If records of fixed U' "locked format are translated, the FIXUNB parameter may be specified or omitted. SCAN=YES Required for records containing shift characters and/ or characters that are automatically deleted by 10CS. SEPASMB=YES Include this operand only if the module is assembled separately. This causes a CATALR card with the module name (standard or user-specified) to be punched ahead of the object deck and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. TRANS=YES Required only if records using an unshifted code are translated and if the operand SCAN = YES is not 96 DOS/VS Supervisor & I/O Macros PTMOD name =I1Eabcde a =S b = = SCAN=YES SCAN=YES is not specified Z T TRANS=YES (SCAN=YES is not specified) = Z TRANS= YES is not specified c = F RECFORM=FIXUNB, and SCAN=YES = U RECFORM=UNDEF, and SCAN=YES = Z SCAN=YES is not specified, and/or DEVICE=1018 d = 1 DEVICE=1017 = 2 DEVICE=1018 = Z DEVICE=2671, or if this entry is omitted e = Z always Subset/Sup~rset PTMOD Names The following chart shows the PTMOD names. No subsetting or supersetting is allowed. See IOCS Subset/ Superset Names in The Macro System chapter. I I.T E * * * * Z Z Z Z Z Z T Z Z S Z F Z S Z u z z z z 1 Z T Z 1 S Z F 1 S Z U 1 S Z Z 2 Z T Z 2 * No subsetting/supersetting permitted. Operand* Resulting Module DEVICE RECFORM SCAN TRANS - Does not handle translation or shift or delete characters 2671 - YES 2671 YES - YES FIXUNB 2671 Handles translation of unshifted codes, but not delete characters Handles shift and delete characters for records of fixed unblocked format YES YES 2671 FIXUNB YES - UNDEF YES 2671 UNDEF YES Handles shift and delete characters for records of undefined format Does not handle translation or shift or delete characters to 17 to17 YES tol7 YES to 17 FIXUNB YES to 17 UNDEF YES Handles shift and delete characters for records of fixed unblocked format Handles shift and delete characters for records of undefined format to18 to18 YES to18 FIXUNB to18 FIXUNB to18 UNDEF 1018 UNDEF tol8 FIXUNB to18 UNDEF Handles translation of unshifted codes, if specified in DTFPT, for records of fixed unblocked format YES YES YES to18 Handles translation of unshifted codes, but no delete characters. Handles translation of unshifted codes, if specified in DTFPT, for records of ". -' format Handles shift characters for records of fixed unblocked format YES YES Handles shift characters for records of undefined format * In all cases, SEP ASMB= YES may either be specified or omitted. Figure 2-21 PTMOD operand combinations Part 2. Sequential Access Method 97 DTFSDMacro The DTFSD macro defines sequential (consecutive) processing for a file contained on a DASD. Only IBM standard label formats are processed. A DTFSD entry is included for each sequential input or output DASD file that is processed in the program. The DTFSD header entry and a series of detail entries describe the file. Enter the symbolic name of the file in the name field and DTFSD in the operation field. The detail entries follow the DTFSD header card in any order. Figure 2-22 lists the keyword operands contained in the operand field. BLKSIZE=n Enter the length of the I/O area. If the record format is variable or undefined, enter the length of the I/O area needed for the largest block of records. When processing spanned records, the size of the I/O area must be at least as large as the smaller of the values shown in Figure 2-25. For output files, the first 8 bytes of IOAREAl must be alloted for IOCS to construct a count field. CONTROL = YES This operand is specified if a CNTRL macro is to be issued to the file. A CCW is generated for control commands. DELETFL=NO Specify this operand if the CLOSE or CLOSER macro is not to delete the Format-l and Format-3 label for a work file. The operand applies to work files only. DEVADDR=SYSnnn This operand must specify the symbolic unit associated with the file if an extent is not provided. An EXTENT job control statement is not required for single-volume input files. If an EXTENT job control statement is provided, its specification overrides any DEVADDR specification. SYSnnn represents an actual I/O address, and is used in the ASSGN job control statement to assign the actual I/O device address to this file. A list of symbolic units applying to DTFSD can be found in the Symbolic Unit Addresses section of The Macro System chapter. The only symbolic unit within this list which is not applicable is SYSLOG. 98 DOS/VS Supervisor & I/O Macros DEVICE = 1231 1 1231412321 13330 133401 This operand is included to specify the device on which the file is located. If no device is specified, 2311 is assumed. Specify 2314 for 2319 and 3330 for 3333. EOFADDR=name This operand specifies the name of your end-of-file routine. IOCS automatically branches to this routine on an end-of-file condition. You can perform any operations required for the end of the file in this routine (you generally issue the CLOSEor CLOSER macro). ERREXT=YES This operand enables your ERROPT or WLRERR routine to return to SDMOD with the ERET macro. It also enables unrecoverable I/O errors (occuring before a data transfer takes place) to be indicated to your program. For ERREXT facilities, the ERR OPT operand must be specified. However, to take full advantage of this option give the ERROPT=name operand. ERROPT=UGNORE 1SKIP 1name I This operand is specified if a job is not to be terminated when a read or write error cannot be corrected in the disk error routines. If a parity error is detected when a block of records is read, the block is reread 256 times before it is considered an error block. After unsuccessfully reading 256 times, the job is terminated unless the ERROPT operand is specified. Either IGNORE, SKIP, or the name of an error routine can be specified. The functions of these parameters are described below. IGNORE The error condition is ignored. The records are made available for processing. When reading spanned records, the whole spanned record or block of spanned records is returned, rather than just the one physical record in which the error occurred. On output, the physical record in which the error occurred is ignored as if it were written correctly. If possible, any remaining spanned record segments are written. Applies to ....::3 Q. ....::3 ....Q. ::3 ~ 1-0 0 = 0 ~ x x x M BLKSIZE=nnnn Length of one I/O area, in bytes X M EOFADDR=xxxxxxxx Name of your end-of-file routine M I OAREA 1=xxxxxxxx Name of first I/O area X 0 CONTROL=YES CNTRL macro used for this file X 0 DELETFL=NO CLOSE, CLOSER macro is not to delete Format-I and Format-3 labels for work file X X X X X X X X 0 DEV ADDR=SYSnnn Symbolic unit required only when not provided on an EXTENT statement X X X 0 DEVICE=nnnn (2311,2314,2321,3330,3340). If omitted, 2311 is assumed X X X 0 ERREXT=YES Additional error and ERET are desired. Specify ERROPT X X X 0 ERROPT=xxxxxxxx (IGNORE, SKIP, or name of error routine). Prevents job termination on error records. Do not use SKIP for output files X X 0 FEOVD=YES Forced end of volume for disk is desired 0 HOLD=YES Employ the track hold function X X X X 0 IOAREA2=xxxxxxxx If two I/O areas are used, name of second area X X 0 10REG=(nn) Register number. Use only if GET or PUT does not specify work area or if two I/O areas are used. Omit WORK A X X 0 LABADDR=xxxxxxxx Name of your routine to check/write user-standard labels X X 0 MODNAME=xxxxxxxx Name of SDMODxx logic module for this DTF. If omitted, 10CS generates standard name X 0 NOTEPNT =xxxxxxx (YES or POINTRW). YES if NOTE/POINTR/POINTW /POINTS used. POINTRW if only NOTE/POINTR/POINTW used X X X 0 RDONLY=YES Generates a read-only module. Requires a module save area for each task using the module X X X 0 RECFORM=xxxxxx (FIXUNB, FIXBLK, VARUNB, VARBLK, SPNUNB, SPNBLK, or UNDEF). For work files use FIXUNB or UNDEF. If omitted, FIXUNB is assumed M=Mandatory; O=Optional Figure 2-22 DTFSD macro operands (part 1 of 2) Part 2. Sequential Access Method 99 Applies to ...=' ......=' =' 0. . ~ = - 0 X X 0 RECSIZE=nnnnn If RECFORM=FIXBLK, number of characters in record. If RECFORM=SPNUNB, SPNBLK, or UNDEF, register number. Not required for other records X X 0 SEPASMB= YES DTFSD is to be assembled separately. X X 0 TRUNCS=YES RECFORM=FIXBLK or TRUNC macro used for this file X X X 0 TYPEFLE=xxxxxx (INPUT, OUTPUT, or WORK). If omitted, INPUT is assumed X 0 UPDATE=YES Input file or work file is to be updated 0 VARBLD=(nn) Register number if RECFORM=VARBLK and records are built in the output area. Omit if WORKA=YES 0 VERIFY=YES Check disk records after they are written. For DEVICE=2321, YES is assumed 0 WLRERR=xxxxxxxx Name of your wrong-length-record routine 0 WORKA=YES GET or PUT specifies work area. Omit IOREG. Required for RECFORM=SPNUNB or SPNBLK. 0. X 0 ~ X X X X X X M=Mandatory; O=Optional Figure 2-22 DTFSD macro operands (part 2 of 2) SKIP No records in the error block are made available for processing. The next block is read from the disk, and processing continues with the first record of that block. When reading spanned records, the whole spanned record or block of spanned records is skipped, rather than just one physical record. On an UPDATE=YES file, the physical record in which the error occurred is ignored as if it were written correctly. If possible, any remaining spanned record segments are written. name IOCS branches to your error routine named by this parameter regardless of whether or not ERREXT = YES is specified. In this routine you can process or make note of the error condition as desired. If ERREXT is not specified, register 1 contains the address of the block in error. When spanned records 100 DOS/VS Supervisor & I/O Macros are processed, register 1 contains the address of the whole unblocked or blocked spanned record. Register 14 contains the return address. When processing in the ERROPT routine, reference the error block (or records within the error block) by referring to the address supplied in register 1. The contents of the IOREG register or work area (if either is specified) are variable and therefore should not be used for error block processing. Also, GET macros must not be issued for records in the error block. If any other IOCS macros (excluding ERET if ERREXT = YES) are used in this routine, the contents of register 13 (with RDONLY) and 14 must be saved and restored after their use. At the end of the routine, return control to IOCS by branching to the address in register 14. For a read error IOCS skips that error block and makes the first record of the next block available for processing in the main program. A sequence error may occur if LIOCS is searching for the first segment of a logical spanned record and fails to find it. If WLRERR or ERROPT=name is specified, the error recovery procedure is the same as for wrong-length record errors. If neither WLRERR nor ERROPT = name is specified, LIOCS ignores the sequence error and searches for the next first segment. Write errors are ignored. If ERREXT is specified, register 1 contains the ad- dress of a two part parameter list containing the 4-byte DTFSD address and the 4-byte address of the error block respectively. Register 14 contains the return address. Processing is similar to that described above except for addressing the error block and for the following considerations. The data transfer bit (byte 2, bit 2) of the DTF is tested to determine if a nondata transfer error has occurred: If this bit is on, the block in error was not read or written. If the bit is off, data was transferred and the routine must address the block in error to determine the necessary action. At the end of its processing, the routine returns to LIOCS by issuing the ERET macro. For an input file: • The program skips the block in error and reads the next block with an ERET SKIP. This operand applies to wrong-length records if the WLRERR operand is not included. If the ERROPT routine is used to process wrong-length records, the ERET RETRY option cannot successfully retry the option. ERET RETRY for this condition results in job termination. If both ERR OPT and WLRERR are omitted and wrong length records occur, IOCS assumes the IGNORE option. The DTFSD error options are shown in Figure 2-23. The figure is divided into two parts: the lower part lists the error conditions which you specify in the DTF, and the upper part shows the action resulting from these specifications when an error occurs. For example, assume that WLRERR=name is specified and the ERET macro is used with the RETRY option. The upper part of the table then shows that the job is terminated regardless of whether or not the error was due to a wrong-length record. FEOVD=YES This operand is specified if the forced end of volume for disk feature is desired. It forces the end-ofvolume condition before physical end of volume occurs. When the FEOVD macro is issued, the current volume is closed, and I/O processing continues on the next volume. Or, it ignores the error with an ERET IGNORE. Or it makes another attempt to read the block with an ERET RETRY. For an output file: The program ignores the error condition ERET IGNORE or ERET SKIP. • Or, attempts to write the block with an ERET RETRY macro. Also, for an output file, the only acceptable ERET parameters are IGNORE or name. On an UPDATE = YES file, the parameter SKIP ignores write errors. If an error occurs while rereading the physical block while updating spanned records, and neither WLRERR nor ERROPT is specified, the entire logical record is skipped. Likewise, if an error occurs when rereading the physical block that contains the last segment for blocked spanned records, the next entire logical record is skipped. If WLRERR and/ or ERROPT were specified, the error recovery procedure is the same as for nonspanned records. HOLD=YES This operand may be specified only if the track hold function was specified at system generation time and if it is employed when a data file or a work file is referenced for updating. See DASD Track Protection Macros in the Multitasking Macros chapter for more information. IOAREAl =name This operand specifies the symbolic name of the I/O area used by the file. IOCS either reads or writes records using this area. For variable-length or undefined records, this area must be large enough to contain the largest block or record. For output records, the first 8 bytes of IOAREA1 must be allotted for IOCS to construct a count field. When variablelength records are processed, the size of the I/O area must include four bytes for the block size. The I/O area must begin on a half-word boundary. When processing spanned records, the size of the I/O area must be at least as large as the smaller of the values shown in Figure 2-24. Part 2. Sequential Access Method 101 Control is passed to your wrong length record Wrong le ngth Record Errors Error record is skipped Error record is ignored Job is terminated Desired Functions Control is passed to your error option routine rror other t han Wrong le ngth Records Error record is skipped Error record is ignored Error record is retri ed ERET Macro Options: Job is terminated IGNORE RETRY SKIP ~ X ERROPT = IGNORE XX X ERR OPT = name ERR OPT = SKIP X ERR OPT = IGNORE, WLRERR = name ERROPT = name, WLRERR XX X =name ERR OPT = SKIP, WLRERR =name Specifications required in your Program ERROPT = name ERET IGNORE X ERR OPT = name RERET RETRY X X X WLRERR = name ERET RETRY WLRERR = name ERET SKIP XX X X X2 Xl Xl X 1 Input files only 2 Output files only 3 Record length not checked for DTFSD undefined records Figure 2-23 DTFSD error options 102 DOS/VS Supervisor & I/O Macros X X ERR OPT = name, WLRERR = name ERET SKIP NONE X2 Xl Xl X X =name ERROPT = name, WLRERR = name ERET RETRY X X X X X X2 Xl Xl WLRERR = name ERET IGNORE X X X ERR OPT = name ERET SKIP ERR OPT = name, WLRERR ERET IGNORE X X X X X X X WLRERR = name DTF Parameters: X X X X ERROPT ERROPT ERROPT WLRERR = name = IGNORE = SKIP = name Device Length (Decimal) 2311 Disk Drive 3625 * or BLKSIZE 2314, 2319 Disk Drive 7294* or BLKSIZE 2321 Data Cell 2000* or BLKSIZE 3330 and 3333 Disk Storage 13, 030* or BLKSIZE 3340 Disk Storage 8368* or BLKSIZE * Add 8 for output files Figure 2-24 I/O area requires when processing spanned records IOAREA2=name If two 1/0 areas are used by GET or PUT, this ope- rand is specified. When variable length records are processed, the size of the 1/0 area must include four bytes for the block size. Also, the 110 area must include eight bytes to build a count field for output files. IOREG=(r) This operand specifies the general purpose register (2-12) in which IOCS puts the address of the logical record that is available for processing. At OPEN time, for output files, IOCS puts in the register specified the address of the area where you can build a record. The same register may be used for two or more files in the same program, if desired. If this is done, the program must store the address supplied by IOCS for each record. This operand must be specified if blocked input or output records are processed in one 110 area, or if two 110 areas are used and the records are processed in both 110 areas. LABADDR=name Enter the name of the routine that enables you to process your own labels. See the sections Writing User Standard Labels on Disk and Checking User Standard Labels on Disk in the Label Processing chapter for a discussion of what the LABADDR routine should do. MODNAME = name This operand may be used to specify the name of the logic module that will be used with the DTF table to process the file. If the logic module is assembled with the program, MODNAME must specify the same name as the SDMODxx macro. If this operand is omitted, standard names are generated for calling the logic module. If two DTF macros call for different functions that can be handled by a single module, only one module is called. NOTEPNT=IPOINTRW I YES} The parameter POINTRW is specified if a NOTE, POINTR, or POINTW macro is issued for the file. If the parameter YES is specified, NOTE, POINTR, POINTW, and POINTS macros may be issued for the file. RDONLY=YES This operand is specified if the DTF is used with a read-only module. Each time a read-only module is entered, register 13 must contain the address of a 72-byte doubleword-aligned save area. Each task should have its own uniquely defined save area. When an imperative macro (except OPEN, OPENR, or LBRET) is issued, register 13 must contain the address of the save area associated with the task. The fact that the save areas are unique for each task makes the module reentrant (that is, capable of being used concurrently by several tasks). For more information see Shared Modules and Files in the Multitasking Macros chapter. If an ERROPT or WLRERR routine issues 1/0 macros using the same read-only module that caused control to pass to either error routine, your program must provide another save area. One save area is used for the normal 110 operations, and the second for 1/0 in the ERR OPT or WLRERR routine. Before returning to the module that entered the error routine, register 13 must be set to the save area address originally specified for the task. If the operand is omitted, the module generated is not reenterable and no save area need be established. RECFORM=IFIXUNB I FIXBLK I VARUNB I VARBLKISPNUNBISPNBLKI UNDEF} This operand specifies the type of records for input or output. Enter one of the following parameters: FIXUNB For fixed-length unblocked records Part 2. Sequential Access Method 103 FIXBLK For fixed-length blocked records V ARUNB For variable-length unblocked records VARBLK For variable-length blocked records SPNUNB For spanned variable-length unblocked records SPNBLK For spanned variable-length blocked records UNDEF For undefined records If RECFORM=SPNUNB or RECFORM=SPNBLK is specified and RECSIZE=(r) is not specified, an assembler diagnostic (MNOTE) is issued, and register 2 is assumed. If WORKA= YES is omitted, an MNOTE is issued and WORKA=YES is assumed. If RECFORM is omitted, FIXUNB is assumed. RECSIZE={n I (r)} For fixed-length blocked records, this operand is required. It specifies the number of characters in each record. When processing spanned records, you must specify RECSIZE=(r) where r is a register. For undefined records and variable-length spanned records, this entry is required for output files, is optional for input files, and is invalid for work files. It specifies a general register (2-12) that contains the length of the record. On output, you must load the length of each record into the designated register before issuing a PUT macro. If specified for input, IOCS provides the length of the record transferred to virtual storage. SEPASMB=YES Include this operand only if the DTFSD is assembled separately. This causes a CATALR card with the filename to be punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. TRUNCS=YES This operand is specified if FIXBLK DASD files contain short blocks embedded within an input file or if the input file was created with a modUle that specified TRUNCS. This entry is also specified if the TRUNC macro is issued for a FIXBLK output file. 104 DOS/VS Supervisor & I/O Macros TYPEFLE=UNPUT I OUTPUT I WORK} Use this operand to indicate whether the file is an input or output file. If WORK is specified, a work file is used. (See Work File Macros for Tape and Disk in the Processing Macros section later in this chapter.) If INPUT/OUTPUT is specified, the GET/PUT macros can be used. If WORK is specified, the READ/WRITE, NOTE/POINT, and CHECK macros can be used. UPDATE = YES This operand must be included if the DASD input or work file is updated--that is, if disk records are read, processed, and then transferred back (PUT) to the same disk record locations from which they were read. CLOSE writes any remaining records in sequence onto the disk. VARBLD=(r) Whenever variable-length blocked records are built directly in the output area (no work area specified), this entry must be included. It specifies the number (r) of a general-purpose register (2-12), which will always contain the length of the available space remaining in the output area. 10CS calculates the space still available in the output area, and supplies it to you in the designated register after the PUT macro is issued for a variable-length record. You then compare the length of your next variable-length record with the available space to determine if the record fits in the area. This check must be made before the record is built. If the record does not fit, you issue a TRUNC macro to transfer the completed block of records to the file. Then, the present record is built at the beginning of the output area in the next block. VERIFY=YES This operand is included if you want to check the parity of disk records after they are written. VERIFY is always assumed when 2321 records are written. If this operand is omitted, any records written on a disk are not verified. WLRERR=name This operand applies only to disk input files. It does not apply to undefined records. WLRERR specifies the symbolic name of your routine to receive control if a wrong-length record is read. If ERREXT is not specified, the address of the error block is supplied by 10CS in register 1. If ERREXT is specified, register 1 contains the address of a two part parameter list. The first four bytes of the list are the DTF address, and the second four bytes are the address of the error block. If the block read is less than the BLKSIZE parameter, the first two bytes of the DTF contain the number of bytes left to be read (residual count). Therefore, the size of the actual block is equal to the block size minus the residual count. If the block to be read is larger than the BLKSIZE parameter, the residual count is zero, and there is no way to compute its size. In this case, the number of bytes transferred is equal to the BLKSIZE parameter and the remainder of the original block is truncated. Your WLRERR routine performs any processing desired for wrong-length records. However, GET macros must not be issued in this routine. If the routine issues any other IOCS macros (excluding ERET if ERREXT = YES) the contents of registers 13 (with RDONL Y) and 14 must be saved before and restored after their use. At the end of the routine, return to IOCS by branching to the address in register 14. If ERREXT is specified, the ERET IGNORE or SKIP options can be taken. The ERET RETRY terminates the job. characteristics are separated into ten categories, and each category has a unique macro associated with it (see Figure 2-25). Macro Module Generated SDMODFI Sequential DASD Module, Fixed-length records l , Input file SDMODFC Sequential DASD Module, Fixed-length records l , Output file SDMODFU Sequential DASD Module, Fixed-length records l , Update file SDMODVI Sequential DASD Module, Variable-length records (including spanned records)2, Input file SDMODVC Sequential DASD Module, Variable-length records (including spanned records)2, Output file SDMODVU Sequential DASD Module, Variable-length records (including spanned records)2, Update file SDMODUI Sequential DASD Module, Undefined records 3 , Input file SDMODUO Sequential DASD Module, Undefined records 3 , Output file SDMODUU Sequential DASD Module, Undefined records 3 , Update file SDMODW Sequential DASD Module, Work file 4 If the WLRERR entry is omitted from the set of DTFSD entries but a wrong-length record is detected by IOCS, one of the following conditions results: If the ERROPT entry is included for this file, the wrong-length record is treated as an error block and handled according to your specifications for an error (IGNORE, SKIP, or name of error routine). If the ERROPT entry is not included, the error is ignored. Undefined records are not checked for incorrect record length. The record is truncated when the BLKSIZE specification is exceeded. 1 RECFORM=FIXUNB or FIXBLK in DTFSD 2 RECFORM=VARUNB, VARBLK, SPNUNB, or SPNBLK in DTFSD WORKA=YES 3 RECFORM=UNDEF in DTFSD If 110 records are processed, or built, in work areas instead of in the 110 areas, specify this operand. 4 RECFORM=FIXUNB or UNDEF in DTFSD You must set up the work area in storage. The address of the work area, or a general-purpose register which contains the address, must be specified in each GET or PUT macro. For a GET or PUT macro, IOCS moves the record to, or from, the specified work area. WORKA= YES is required for SPNUNB and SPNBLK. When this operand is specified for a file, the IOREG operand must be omitted. SDMODxx Macro Sequential DASD module generation macros differ from other IOCS module generation macros. The file Figure 2-25 SDMOD macros The macro operation code and the keyword operands define the characteristics of the module. Modules for a specific file can thus be generated more quickly than if there were only one macro. The operands for the ten macros are shown in Figure 2-26 and explained in the following section. Part 2. Sequential Access Method 105 SDMODxx Operands A module name may be contained in the name field of the macro. The macro operation code is contained in the operation field (SDMODFI, for example). The operands are contained in the operand field. CONTROL=YES This operand is specified if a CNTRL macro is issued for the file. This entry applies to all SDMODxx macros. The module also processes any DTF in which the CONTROL parameter is not specified. ERREXT=YES Include this operand if nondata transfer errors are returned to an ERROPT routine in your program or if the ERET macro is used with the DTF and module. If ERREXT is specified ERROPT must also be specified. ERROPT=YES This operand applies to all SDMODxx macros. It is included if the module handles any of the error options for an error block. Logic is generated to handle any of the three options (IGNORE, SKIP, or name) regardless of which option is specified in the DTF. The module also processes any DTF in which the ERROPT operand is not specified. If this operand is not included, your program is can- celed whenever any uncorrectable error except a wrong-length record error (which LIOCS ignores) is encountered. HOLD=YES This operand applies to update (SDMODFU, SDMODVU, and SDMODUU) and to work files (SDMODW) only. The operand is included if the track hold function is employed. Any DTF used with the module must have the same operand. FEOVD = YES This operand is specified if the forced end of volume for disk feature is desired. It forces the end of volume condition before physical end of volume occurs. When the FEOVD macro is issued, the current volume is closed, and 110 processing continues on the next volume. NOTEPNT=IPOINTRW I YESJ This operand applies to SDMODW (work files) only. It is included if any NOTE, POINTR, POINTS, or POINTW macros are used within the module. If the operand specifies POINTRW, logic to handle only NOTE, POINTR, and POINTW is generated. 106 DOS/VS Supervisor & I/O Macros If YES is specified, the routines to handle NOTE, POINTR, POINTS, and POINTW are generated and any files that specify NOTEPNT=POINTRW in the DTF are processed. In any case, any files that do not specify the NOTEPNT parameter in the DTF are processed. RDONLY = YES This operand causes a read-only module to be generated. Whenever this operand is specified, any DTF used with the module must have the same operand. RECFORM=ISPNUNB I SPNBLKJ This operand is required only for SDMODVI (input files), SDMODVO (output files), and SDMODVU (update files) if RECFORM=SPNUNB or SPNBLK is specified in th~ DTF. If RECFORM is specified incorrectly, an assembler diagnostic (MNOTE) is issued, and the module generation is terminated. SEPASMB=YES Include this operand only if the module is assembled separately. This causes a CATALR card with the module name (standard or user-specified) to be punched ahead of the object deck and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. TRUNCS=YES This operand applies to all SDMOD macros for fixed-length records. It generates a logic module which can handle the TRUNC macro. This operand is assumed for VARBLK output files. This operand is ignored if specified for VARBLK input or update files. It must be specified if any FIXBLK DASD files (processed by the module) contain short blocks embedded within them or if the input file was created with a module that specified TRUNCS. The module cannot process any DTF, for fixed-length records, in which the TRUNCS operand is not specified. UPDATE = YES This operand applies to the SDMODW only. It is assumed for SDMODFU, SDMODUU, and SDMODVU and generates a logic module which can handle the WRITE UPDATE macro with work files. Operand Required Comments CONTROL=YES If the CNTRL macro is to be issued for the file. Applies to all SDMODs. ERREXT=YES If the module returns nondata transfer errors or is used with the ERET macro. Applies to all SDMODs. ERROPT=YES If the module is to handle error options for an error block. Applies to all SDMODs. FEOVD=YES If the FEOVD macro is to be issued for the file. Applies to all SDMODs except SDMODW. HOLD=YES If the track hold function is to be employed. Applies to update and work file logic modules. NOTEPNT={POINTRW I YES} If NOTE, POINTR, POINTS, or POINTW macros are to be issued for the file. This parameter applies to SDMODW only. The operand POINTW generates logic for NOTE, POINTR, and POINTW. The operand YES generates logic for all macros. RDONLY=YES If a read-only module is to be generated. Applies to all SDMODs. RECFORM={SPNUNB I SPNBLK} If unblocked or blocked spanned records are to be processed. Applies to SDMODVI, SDMODVO, and SDMODVU only. SEPASMB= YES If the module is assembled separately from the DTF. Applies to all SDMODs. TRUNCS=YES If the TRUNC macro us to be issued for the file. Assumed for output files consisting of variablelength blocked records. Applies to all SDMODs for fixed-length records. UPDATE=YES If SDMODW is to process the WRITE UPDATE macro. Applies to SDMODW only. Figure 2-26 SDMODxx operands Standard SDMOD Names Each name begins with a 3-character prefix (UG) and continues with of a 5-character field corresponding to the options permitted in the generation of the module. a =C =F =R SDMODFx specifies HOLD= YES SDMODFx does not specify HOLD=YES SDMODUx specifies HOLD= YES = U SDMODUx does not specify HOLD=YES = P SDMODVx specifies HOLD= YES (spanned records) In SDMOD there are two module classes: • • Those which handle GET/PUT functions Those which handle READ/WRITE, NOTE/POINT, and CHECK functions (work files). Name List for GET/PUT Type Modules SDMODxx name = UGabcde =Q SDMODVx does not specify HOLD=YES (spanned records) =S SDMODVx specifies HOLD= YES = V SDMODVx does not specify HOLD=YES b = U SDMODxU = I SDMODxI = 0 SDMODxO c = C ERROPT=YES and ERREXT=YES = E ERROPT=YES Part 2. Sequential Access Method 107 = d +* +++ = M TRUNCS=YES and FEOVD=YES = e Z neither is specified IlTGCUCMB FIE T Y +0 T TRUNCS= YES Z ++ = W FEOVD= YES R W C U Z Z = p Q V + Z neither is specified =B CONTROL=YES and RDONLY=YES =C CONTROL=YES + p S = Y RDONLY=YES V =Z neither is specified + Subsetting/supersetting permitted. Name List for Workfile Type Modules (TYPEFLE=WORK) SDMODxx name = UGabcde a =T * No subsetting/supersetting permitted. For Workfile Type Modules: HOLD= YES +++++ = W HOLD=YES not specified b c = II.JGTCNCT C ERROPT=YES and ERREXT=YES ERROPT=YES = Z neither is specified Z + Subsetting/ supersetting permitted * Z NOTEPNT is not specified = Z CONTROL=YES is not specified C CONTROL=YES e = T RDONL Y= YES and UPDATE= YES = No subsetting/supersetting permitted NOTEPNT=POINTRW = = =U + U N NOTEPNT = YES =R d Z Z =E = l~ERZY UPDATE=YES Y RDONLY=YES DTFSR Macro The DTFSR macro is provided only for the convience of those who are converting to DOS/VS from the Basic Operating System/360. If you are not a former Basic Operating System/360 user, there is no reason to use the DTFSR macro. Use the DTFCD, DTFCN, DTFMT, DTFOR, DTFPR, DTFPT, and DTFSD macros instead, as they are easier to use, are more flexible, and take full advantage of the features of DOS/VS. = Z neither is specified Subset/Superset SDMOD Names The following diagrams illustrate the subsetting and supersetting allowed for SDMOD names. For the GET /PUT type modules, four parameters allow supersetting. For example, in the GET/PUT type module, the module IJGFUETC is a superset of a module with the name of IJGFUZTZ. See IOCS Subset/Superset Names in The Macro System chapter. 108 DOS/VS Supervisor & I/O Macros For those using DTFSR, enter the symbolic name of the file in the name field and DTFSR in the operation field. A begin-definition card follows, with DTFBG punched in the operation field and DISK in the operand field. The name field is blank. Detail entries follow the DTFBG card in any order. Figure 2-27 lists the keyword operands contained in the operand field. ALTIAPE=SYSnnn construct the count field of the CCW for an output file of fixed-length records. This operand is provided for BPS and BOS compatibility. check physical record length for a file of fixedlength blocked input records. BLKFAC=n Undefined journal tape records are processed faster when this operand is included because it reads groups of lines as blocked records. When undefined records are processed, BLKFAC specifies the blocking factor that determines the number of lines read (through CCW chaining) as a block of data by one physical read. Deblocking is accomplished automatically by IOCS when the GET macro is used. The BLKF AC operand is not used with RECFORM=FIXBLK, because the blocking factor is determined from the BLKSIZE and RECSIZE operands. If the BLKF AC operand is included for FIXBLK, FIXUNB, or document processing, an assembler diagnostic (MNOTE) results, and the operand is ignored. • determine if the space remaining in the output area is large enough to accommodate the next variable-length output record. CHECKPf=n This operand is for compatibility with BPS and BOS and is ignored by DOS/VS. CKPfREC=YES This operand is required if an input tape contains checkpoint records interspersed among the data records. When this entry is included, IOCS recognizes the checkpoint records and bypasses them. CONTROL= YES BLKSIZE=n This operand indicates the size of the input or output area specified by IOAREAl. BLKSIZE specifies the maximum number of characters that may be transferred to or from the area at one time. When variable-length records are read or written, the area must be large enough to accommodate the largest block of records, or the longest single record if the records are unblocked. When undefined journal tape records are read, the area must be large enough to accommodate the longest record to be read if the BLKFAC operand is not specified. If the BLKF AC operand is specified, the BLKSIZE value must be determined by multiplying the maximum length that must be accommodated for an undefined record by the blocking factor desired. A BLKSIZE value smaller than this results in truncation of data. This operand is specified if a CNTRL macro is to be issued for a file. If this operand is specified, CTLCHR must be omitted. COREXIT = name COREXIT provides an exit to your error correction routine for the 1287 optical reader or 1288 optical page reader. If an error occurs after a GET, WAITF, or CNTRL macro (to increment or eject and/or stacker select a document) is executed, the error correction routine is eJ}.tered with an indication provided at the address filename+80. Filename+80 contains the following hexadecimal values indicating the conditions that occurred during the last line or field read. Filename+80 should also be tested after issuing the optical reader macros DSPLY, RESCN, RDLNE, CNTRL READKB, and CNTRL MARK. More than one error condition may be present. X'20' For the 1288, reading in unformatted mode, the end-of-page (EOP) condition was detected. Normally, on an EOP indication, the program ejects and stacker-selects the document. X'Ol' A data check has occured. Five read attempts for journal tape processing or three read attempts for document processing were made. X'02' The operator corrected one or more characters from the keyboard (1287T), or a hopper empty condition (see the HPRMTY = YES operand) has occurred (1287D). If card-punch or printer output records include con- trol characters (that is, the CTLCHR operand is specified) and/or record-length fields for variablelength records (RECFORM=VARUNB), the BLKSIZE value must include the extra bytes allotted in the output area. If two input, or output, areas are used for a file (IOAREA1 and IOAREA2), the size specified in this entry is the size of each I/O area. IOCS uses this block size parameter to: construct the count field of the CCW for an input file. Part 2. Sequential Access Method 109 X'04' A wrong-length record condition has occurred after five read attempts were made for journal tapes or three for documents. Not applicable for undefined records. X'08' An equipment check resulted in an incomplete read after ten read attempts were made for journal tapes or three for documents. If an equipment check occurs on the first character in the record when processing undefined journal tape records, the RECSIZE register contains zero, and the 10REG (if used) points to the rightmost position of the record in the I/O area. Test the RECSIZE register before moving records from the I/O or work area(s). The test conditions are: X'20' A stacker-select command was given after the allotted time had elapsed and the document is sent to the reject pocket. X'40' The 1287D scanner was unable to locate the reference mark after ten read attempts were made for journal tapes or three for documents. Filename+80 should be checked to determine the reason for entry into the error correction routine. You may then perform whatever action is appropriate to recover from the error. your routine must not branch to the address in register 14 from the COREXIT routine or a program loop will result. Following a nonrecoverable error, the optical reader file must be closed, the condition causing the nonrecoverable error must be cleared, and the file must be reopened before processing can continue. When processing documents, a nonrecoverable error requires that the document be removed, either manually or by nonprocess runout. Such an error could result from a jammed document or a scanner control failure. In such cases, your program should branch to read the next document. Also, if the 1287 or 1288 scanner is unable to locate the document reference mark, the document cannot be processed. In this case, the document must be ejected and stacker selected before attempting to read the following document or a program loop will result. In any case, you must not branch to the address in register 14 from the COREXIT routine. You should ignore any output resulting from the document under any circumstances. Eight binary counters are used to accumulate totals of certain 1287 and 1288 error conditions. These counters each occupy four bytes, starting at filename +48. Filename is the name specified in the DTF header entry. The error counters are: 1 filename+48 Incomplete read (eqipment check) If you issue I/O macros to any device other than the 1287 and/or 1288 in the COREXIT routine, save registers 0, 1, 14, and 15 upon entering the routine, and restore these registers before exiting. Also, if I/O macros (other than GET and/or READ, which cannot be used in COREXIT) are issued to the 1287 and/ or 1288 in this routine, you must first save, and later restore registers 14 and 15. All exits from COREXIT should be to the address in register 14. This returns control to the point from which the branch to COREXIT occurred. If a READ document command chain is broken, 10CS completes the chain upon return from the COREXIT routine. Note: Do not issue a GET or a READ macro to the 1287 or 1288 in the error correction routine. Do not process records in this routine. The record that caused the exit to the error routine is available for processing upon return to the main program. Any processing attempted in the error routine would be duplicated after return to the main program. 2 filename+52 Incomplete read uncorrectable after ten read attenpts for journal tapes or three for documents 3 filename+56 Wrong-length records (not applicable for undefined records) 4 filename+60 Wrong-length records uncorrectable after five read attempts for journal tapes or three for documents (not applicable for undefined records) 5 filename+64 Keyboard corrections (journal tape only) 6 filename+68 Journal tape lines, including retried lines, or document fields, including retried fields, in which data checks are present 7 filename + 72 Lines marked (journal tape only) When processing journal tapes, a nonrecoverable error (torn tape, tape jam, etc.) normally requires the tape to be completely reprocessed. In this case, 110 DOS/VS Supervisor & I/O Macros 8 filename + 76 Count of total lines read from journal tape or the number of CCW chains executed during document processing. All of these counters contain binary zero at the start of each job step and are never cleared. You may list the contents of these counters for analysis at end of file, or at end of job, or you may ignore the counters. The binary contents of the counters should be converted to a printable format. CRDERR=RETRY This operand applies only to a card output file for the 2520 or 2540. It specifies the operation performed if an error is detected. Normally, if a punching error occurs, it is ignored and operation continues. The error card is stacked in pocket PI (punch). Correct cards are stacked in the pocket you specified. If the CRDERR operand is specified, however, IOCS also notifies the operator and then enters the wait state whenever an error condition occurs. The operator can then either terminate the job or instruct IOCS to repunch the card. IOCS automatically generates a retry routine and constructs a save area for the card punch record if this entry is included. Macro System chapter. SYSOPT, if used, is processed as if SYSPCH were specified. A reel of tape may be mounted on any tape unit available at the time the job is ready to run. This is done by assigning the device to the specified symbolic unit name. Whenever two devices are used for one logical file (such as an alternate tape unit specified in the ASSGN job control statement), this DEV ADDR entry specifies the symbolic unit name for the first device. The symbolic unit name must be specified for all units except the 2311 disk drive. For files on this device, DEVADDR may be omitted. If DEVADDR is omitted, the symbolic unit name for a disk drive is supplied by an EXTENT job control statement. DEVICE = This operand must be included to state the I/O device associated with this file. Enter one of the following: DISK11 For an input or output file on disk (2311) TAPE For an input or output file recorded on magnetic tape (3420 or 2400series). PRINTER For output printed on a 1403, 1443 or 3211. READ01 For an input card file in a 2501. READ20 For an input or output card file in a 2520. READ40 For an input or output card file in a 2540. When this operand is specified, IOCS routines cause the designated control character for printer or card punch order to be issued to the I/O device. Printing or punching begins with the second character in the record. When the CTLCHR entry is not included, any control functions desired must be performed by the CNTRL macro. READ42 For an input or output card file in a 1442. CONSOLE For input from and output to the console printer keyboard or the display operator console. PTAPERD For input from a 2671. DEVADDR=SYSxxx READ87T For a journal tape input file on a 1287. READ87D For a document input file on a 1287 or 1288. CTLCHR=YES The CTLCHR (control character) operand applies only to printer and punch output files. It is included if each logical record written or punched contains a control character (carriage control or stacker selection) in the record itself, or in the virtual storage output area. For fixed-length or undefined records, the control character must be the first character. For variable-length records, it is the first character after the record-length field. The control character codes are the same as the modifier bytes used for a punch or print command. This operand specifies the symbolic unit name to be associated with the file. The symbolic unit name represents an actual I/O device address and is used in the ASSGN job control statement to assign the actual I/O device address to this file. For a complete list of symbolic unit names that can be used for particular devices see Symbolic Unit Addresses in The This operand causes IOCS to set up the devicedependent routines for a file. For document process- Part 2. Sequential Access Method 111 ing on the 1287 or 1288 optical reader, or 1288 optical page reader, you have to code your own CCWs. If this operand is omitted, 1287D is assumed. EOFADDR=name This operand must be included for: • • Card reader files Magnetic tape input files Paper tape input files Sequential disk input files Optical reader files It specifies the symbolic name of your end-of-file routine. IOCS automatically branches to this routine on an end-of-file condition. IOCS detects end-of-file conditions as follows: • • Card Reader. By recognizing the characters /* punched in card columns 1 and 2. If cards are allowed to run out without a / * trailer card (and a / & card if end-of-job), an error condition is signaled to the operator (intervention required). Magnetic Tape Input. By reading a tapemark and EOF in the trailer label when standard labels are specified, or by reading the characters /* if the unit is assigned to SYSRDR or SYSIPT. If standard labels are not specified, IOCS assumes an end-of-file condition when the tapemark is read. You must determine, in your routine, that this actually is the end of the file. • Paper Tape Reader. By recognizing the end of tape when the end-of-file switch is set on. • Sequential Disk Input. By reading an end-of-file record or reaching the end of the last extent you supplied. • Optical Reader Input. When reading data from documents on a 1287 or 1288, end-of-file is recognized by pressing the end-of-file key on the console when the input hopper is empty. When processing journal tapes on a 1287, end-of-file is detected by pressing the end-of-file key after the end of the tape has been sensed. 112 DOS/VS Supervisor & I/O Macros When IOCS detects the end of file, it branches to your routine specified by EOFADDR. If journal tapes are being processed, it is your responsibility to determine if the current roll is the last roll to be processed. Regardless of the situation, the tape file must be closed for each roll within this routine. If the current roll is not the last, the OPEN or OPENR macro must be issued to allow header (identifying) information to be entered at the reader keyboard and read by the processor when using logical IOCS. The same procedure can be used for 1287 processing of multiple journal tape rolls as well as the method described in OPEN and OPENR Macros in the Imperative Macros section later in this chapter. ERROPT=UGNORE I SKIP I name} This operand applies to disk or magnetic tape input files. It specifies functions to be performed for an error block. If a parity error is detected when a block of se- quential disk records is read, the disk block is reread 256 times before it is considered an error block. If a parity error is detected when a block of tape records is read, the tape is backspaced and reread 100 times before the tape block is considered an error block. Unless the ERROPT operand is included to specify other procedures, the job is then automatically terminated. Either IGNORE, SKIP, or the name of an error routine can be specified in this entry. The functions of these three parameters are: IGNORE The error condition is completely ignored, and the records are made available for processing. SKIP No records in the error block are made available for processing. The next block is read from disk or tape, and processing continues with the first record of that block. The error block is included in the block count, however. name IOCS branches to your routine, where you may perform whatever functions you desire to process or note the error condition. Register 1 contains the address of the block in error, and register 14 contains the return address. In your error routine, address the error block (or records in the error block) by referring to the address supplied in register 1. The contents of the IOREG register or the work area (if either is speci- fied) may vary and, therefore, should not be used. Do not issue any GET macros for records in the error block. If you use any other 10CS macros in your routine, save and later restore the contents of register 14. At the end of the routine return to 10CS by branching to the address in register 14. When control returns to the problem program, the first record of the next block is available for processing in your program. The ERROPT entry does not apply to disk or tape output files. The job is automatically terminated if a parity error still existed after 10CS attempted to write a disk output block ten times, or to write a tape output block 15 times. The tape procedure includes 15 forward erases. This entry applies to wrong-length records if the DTFSR operand WLRERR is not included. If both ERROPT and WLRERR are omitted, 10CS ignores any wronglength records that occur. FILABL=NO I STD I NSTD This operand specifies what type of labels are to be processed. Enter one of the following parameters: NO STD For a tape that does not contain labels. The entry FILABL=NO may be omitted, if desired, and 10CS assumes that there are no labels. For tape input if standard labels are checked by 10CS, or for tape output if standard labels are written by 10CS. NSTD For tape input or output with nonstandard labels. You may process these labels yourself (see Writing Nonstandard Labels on Tape and Checking Nonstandard Labels on Tape in the Label Processing chapter). NSTD is specified for standard input labels if they are not to be checked by 10CS. HEADER=YES This operand is required if the operator must key in header (identifying) information from the 1287 keyboard. The OPEN or OPENR routine reads the header information only when this operand is present. If the entry is omitted, OPEN or OPENR assumes no header information is to be read. The header record size can be as large as the BLKSIZE specification and is read into the high-order positions of 10AREAl. This operand cannot be used for 1288 files. HPRMTY=YES This operand is included if you want to be informed of the hopper empty condition. This condi- tion occurs when a READ is issued and no document is present. When hopper empty is detected, your COREXIT routine is entered with the condition indicated as X'02' in filename+80. This operand should be used when processing documents in the time dependent mode of operation. This allows complete overlapping of processing with reading. (See method 2 under Programming the 1287 in IBM 1287 Optical Reader Component Description and Operating Procedures, GA21-9064. If the HPRMTY parameter is used with this method of processing, you are able to check for a hopper empty condition in your COREXIT routine. This allows you then to select the proper stacker for the previously ejected document, before returning from the COREXIT routine (via register 14). INAREA=name This operand applies only to a card file in a 1442 that is updated (TYPEFLE=CMBND) and for which separate input and output areas are required. INAREA specifies the name of the input area to which the card record is transferred. OUAREA is used in conjunction with INAREA, and both 10AREAl and IOAREA2 must be omitted. This entry does not apply to combined files in a 2520 or 2540. When the same I/O area is used for both input and output in a combined file for a 2520 or 2540, INAREA and OUAREA are omitted. IOAREA1 specifies the name of the I/O area used for both input and output files. INBLKSZ=':l This operand is used with INAREA for a combined file in the 1442 when separate input and output areas are required. It specifies the maximum number of characters that are transferred to the input area (INAREA) at anyone time. Whenever this operand is included, OUBLKSZ must also be included, and BLKSIZE must be omitted. IOAREAl =name This operand is included to specify the name of the input, or output, area used by this file. The input/ output routines transfer records to or from this area. For a disk output file, reserve eight bytes at the beginning of your I/O area, ahead of the positions allotted for data records. These eight bytes are necessary to allow 10CS to construct the count area for the disk record. For 1287 readers, this area is set to binary zeros before each input operaPart 2. Sequential Access Method 113 tion and before each tape input operation to this area. For document processing, the area is cleared only when the file is opened. This operand must not be included for a 1442 combined file if INAREA and OUAREA are specified for the file. For a 2520 and 2540 combined file, 10AREAl must be used for both the input and output area. IOAREA2 = name Two input, or output, areas can be allotted for a file, to permit an overlapping of data transfer and processing operations. When this is done, this IOAREA2 operand must be included to specify the name of the second I/O area. For a disk output file, reserve eight bytes at the beginning of your I/O area, ahead of the positions allotted for data records. These eight bytes are necessary to allow 10CS to construct the count area for the disk record. For the 1287 reader (journal tape only) this area is set to binary zeros before each input operation to this area. This operand must not be specified if DEVICE=READ87D or if TYPEFLE=CMBND. In the latter case, 10AREAl must be used for both the input and output areas. IOREG=(r) This operand specifies a general-purpose register (2-12) that the input/output routines can use to indicate which individual record is available for processing. 10CS puts the address of the current record in the specified register each time a GET or PUT is issued. The same register may be specified in the 10REG entry for two or more files in the same program, if desired. In this case, your program may need to store the address supplied by 10CS for each record. This operand must be included whenever: • Blocked input or output records (from disk, magnetic tape, or journal tape) are processed directly in the I/O area. • Variable-length unblocked or undefined tape records are read backwards and processed directly in the input area. • Two input, or output, areas are used and the records (either blocked or unblocked) are processed in the I/O areas. • Undefined records for journal tape are read. 114 DOS/VS Supervisor & I/O Macros Whenever this entry is included for a file, the WORKA operand must be omitted, and the GET or PUT macros must not specify work areas. Since a read by an optical reader is accomplished by a backward scan, the rightmost character in the record is placed in the rightmost position of the I/O area. Subsequent characters are placed in sequence from right to left. The register specified indicates the leftmost position of the record. LABADDR=name You may require one or more of your own disk or tape labels in addition to the standard file header label or trailer label (on tape). If so, include your own routine to check or build the label(s). The name of your routine is specified in this entry. 10CS branches to this routine after it has processed the standard label. This entry is also required whenever nonstandard labels are checked or written by your program. (FILABL=NSTD is specified.) LABADDR allows you to specify a single label routine for all types of labels for the file: header labels, end-of-file labels, and end-of-volume labels. For an input file, you can determine the type of label that was read by the identification in the label itself. For an output tape file, however, 10CS indicates to you the type of label by supplying a code in the low-order byte of register 0, as follows: o indicates header labels. F indicates end-of-file labels. V indicates end-of-volume labels. You can test this byte in your routine and then build the appropriate type of label. At the end of the routine, return to 10CS by use of the LBRET macro. You may not issue a macro that calls in a transient routine (OPEN, OPENR, CLOSE, CLOSER, DUMP, PDUMP, CANCEL, or CHKPT). For a more complete discussion, see the Label Processing chapter. OUAREA = name This operand is used with INAREA for a combined file on a 1442 that requires separate input and output areas. It specifies the name of the output area from which the updated card record is punched. If only one area is used for input and output, 10AREA 1 should be used. OUBLKSZ=n This operand is used with OUAREA for a combined file. It is similar to INBLKSZ, and specifies the maximum number of characters that are transferred from the output area (OUAREA) at any one time. If combined files use IOAREA1, BLKSIZE must be used. PRINTOV = YES This operand must be included whenever the PRTOV macro is used in your program. READ={FORWARD I BACK} This operand may be included for magnetic tape input to specify the direction in which the tape is to be read. If this entry is omitted, IOCS assumes forward reading. BACK specifies that the tape is to be read backwards. RECFORM={FIXUNB I FIXBLK I VARUNB I VARBLK I UNDEF} This operand specifies the type of records in the input or output file. Enter one of the following: FIXUNB For fixed-length unblocked records FIXBLK For fixed-length blocked records. This applies only to disk and magnetic tape input or output and optical reader journal tape input. VARUNB For variable-length unblocked records. This applies only to disk input or output (2311), magnetic tape input or output (240Q or 3420), card punch output (1442, 2520, or 2540), and printer output (1403, 1404, 1443, 1445, or 3211). VARBLK For variable-length blocked records. This applies only to disk and magnetic tape input or output. UNDEF For undefined records. This applies to any file except card input (1442, 2501, 2520, or 2540). The records in a file can be specified as follows: Disk and magnetic tape input or output: FIXUNB, FIXBLK, V ARUNB, V ARBLK, or UNDEF. Card input: FIXUNB. • Card output: FIXUNB, V ARUNB, or UNDEF. • Optical reader input: All modes: FIXUNB or UNDEF. Journal tape mode: FIXBLK. • Paper tape input: FIXUNB or UNDEF. Console printer-keyboard or display operator console input or output: FIXUNB or UNDEF. Printer output: FIXUNB, V ARUNB, or UNDEF. RECSIZE={n I (r)} For input or output files, this operand must be included for disk, magnetic tape, and optical reader journal tape records that are fixed-length blocked (RECFORM=FIXBLK) or undefined (RECFORM= UNDEF). For paper tape records, this entry may be included for fixed-length unblocked or for undefined records (RECFORM=FIXUNB or UNDEF). For other devices, this entry must be included whenever records are undefined (RECFORM=UNDEF). For fixed-length blocked disk, magnetic tape or optical reader journal tape records, this operand specifies the number of characters in an individual record. The input/output routines use this number to block or deblock records, and to check record length of input records. For undefined records, this operand specifies the number, (r), of the general-purpose register (2-12) that contains the length of each individual input or output record. When undefined records are read, IOCS supplies the physical record size in the register. In the case of paper tape records, this applies to both fixed unblocked and undefined records. When undefined records are built, you must load the length in bytes of each record into the specified register before issuing the PUT macro for the record. This becomes the count portion of the CCW that IOCS sets up for the file. Thus, it determines the length of the record to be transferred to an output device. If an undefined punch or printer output record contains a control character in the main-storage output area (the CTLCHR operand is specified), the length loaded into the RECSIZE register must also include one byte for this character. For undefined document records, RECSIZE contains only the length of the last field of a document read by the CCW chain which you supply. Note: When processing undefined records on an optical reader in document mode, you gain complete usage of the two registers normally used in the RECSIZE operand. To do this, make sure that Part 2. Sequential Access Method 115 the suppress length indicator is always on when processing undefined records. REWIND=IUNLOAD I NORWD} This operand may be specified with one of the following parameters: UNLOAD NORWD To rewind the tape on OPEN or OPENR, and to rewind and unload on CLOSE or CLOSR or on an endof-volume condition. To prevent rewinding the tape at any time. If this operand is omitted, tapes are automatically rewound, but not unloaded, on an OPEN or OPENR or CLOSE or CLOSER macro or on an end-of-volume condition. TPMARK=NO This operand is included if you do not want a tapemark written as the first record on a tape output file if labels are not specified. This operand is also included if no tape mark is written following nonstandard header lapels. If this operand is omitted for a tape output file, a tape mark is the first record if no labels are specified. If this operand is omitted, a tape mark is written following nonstandard header labels. For an input file if the TRUNC macro was issued to write short blocks when the file was originally created. TYPEFLE=IINPUT I OUTPUT I CMBND} This operand must be included to specify the type of file: input, output, or combined. INPUT must be specified for: • • • • • 2311 disk input (with or without updating) 2400, 3420 magnetic tape input 1442, 2501, 2520, 2540 card input 3210 or 3215 keyboard input (both GET and PUT macros may be issued) 1287, 1288 optical reader input OUTPUT must be specified for: • • 2311 disk output 2400, 3420 magnetic tape output 1403, 1404, 1443, 3211 printer output 1442, 2520, 2540 card output 3210 or 3215 printer output (only PUT macros may be issued). CMBND must be specified for a 1442, 2520, or 2540 card file that is updated. That is, card records are read, processed, and then punched (PUT) in the same cards from which they were read. If the TYPEFLE operand is omitted, INPUT is TRANS = name This operand applies to input data read from the 2671 paper tape reader: it specifies the name of a code translation table. The table must conform to the specifications of the TR machine instruction. The input records may be punched in 5-, 6-, 7-, or 8-channel paper tape, using anyone of several different recording codes. If a code other than EBCDIC is used, it must be translated to EBCDIC code for use in System/370 programming. For IOCS to perform this translation, you provide a translation table and specify the name of the table in this TRANS operand. The logical IOCS routines then translate the paper tape code and make the record available to you in usable form directly in the input area. TRUNCS=YES This operand applies to disk files with fixed-length blocked records (RECFORM=FIXBLK) when short blocks are processed. It must be included: • For an output file if the TRUNC macro is issued in your program. 116 DOS/VS Supervisor & I/O Macros assumed. UPDATE=YES This operand must be included if a disk input file (TYPEFLE=INPUT) is updated. That is, disk records are to be read, processed, and then transferred back (PUT) to the same disk record locations from which they were read. 1 VARBLD=(r) Whenever variable-length blocked records are built directly in the output area (no work area specified), this entry must be included. It specifies the number of a general-purpose register (2-12), which always contains the length of the available space remaining in the output area. After a PUT macro is issued for a variable-length record, IOCS calculates the space still available in the output area and supplies it to you in the designated register. You then compare the length of your next variable length record with the available space to determine if the record fits in the area. This check must be made before the record is built. If the record does not fit, issue a TRUNC macro to transfer the completed block of records to the tape file. Then, the present record is built at the beginning of the output area in the next block. If the WLRERR operand is omitted and a wrong- VERIFY=YES This operand is included if you want disk records to be parity checked after they are written. If this entry is omitted, any records written on disk are not verified. • WLRERR = name This operand applies only to disk, magnetic tape, or paper tape input files. It specifies the name of your routine to which 10CS branches if a wronglength record is read. In your routine, any operation desired for wrong-length records can be performed. GET macros, however, cannot be used in your routine. Also, if you use any other 10CS macros in your routine, save the contents of register 14. The address of the wrong-length record is supplied by 10CS in register 1. At the end of the routine return to 10CS by branching to the address in register 14. Whenever fixed-length blocked records or variablelength records are specified (RECFORM=FIXBLK, =VARUNB, or = VARBLK), a machine check for wrong-length records is suppressed. In this case, 10CS generates a program check for the wrong record length. For fixed-length blocked records, record length is considered incorrect if the physical disk or tape record (gap-to-gap) is not a multiple of the maximum logical record length specified in DTFSR RECSIZE. This permits the reading of short blocks of logical records, without a wrong length record indication. For variable-length records on disk or tape, the record length is considered incorrect if it is not the same as the block length specified in the 4-byte block length field. When fixed-length unblocked records are specified (RECFORM=FIXUNB), 10CS checks for a wrong-length-record indication that may result from an I/O operation. length record is detected by 10CS, one of the following conditions results: If the ERROPT operand is specified for this file, the wrong-length record is treated as an error block and handled according to your specifications for an error (IGNORE, SKIP, or name of error routine). • If the DTFSR ERROPT operand is not includ- ed, the wrong-length record is ignored. The WLRERR operand does not apply to undefined records because undefined records are not checked for incorrect record length. WORKA=YES If records are processed in work areas instead of in the I/O areas, specify this operand. You must set up the work area in storage. The address of the work area, or a general-purpose register which contains the address, must be specified in each GET or PUT macro. Whenever this operand is specified for a file, the 10REG operand must be omitted. For optical char~cter records, a work area can only be used when processing journal tape. The DTFEN Card An end-of-definition card must follow the last set of DTFSR cards that applies to a magnetic tape or DASD file. If two or more DTFSR macros are used in the same program, they must not be assembled separately from each other because duplicate labels may be generated. However, the set of DTFSR macros may be assembled separately from the program. The DTFEN card must be punched with DTFEN in the operation field and blanks in the name field. The operand field may be blank or it may contain OVLAY as a parameter (to provide compatibility with BOS). DOS/VS interprets the DTFEN card as a signal to begin generation of the required disk or tape I/O modules. Part 2. Sequential Access Method 117 x x x M DEVICE=READnn (01,20,40, or 42). For 2501,2520,2540, 1442, respectively. X X X M DEADDR=SYSxxx Symbolic unit for reader-punch used for this file. X M EOFADDR=xxxxxxxx Name of your end-of-file routine. X M TYPEFLE=xxxxxx (INPUT, OUTPUT, or CMBND). CMBND does not apply to 250l. 0 BLKSIZE=nn Length of one I/O area, in bytes. Omit INBLKSZ and OUBLKSZ. Do not use for 1442 CMBND file with separate I/O areas. X X X X X X X X 0 CONTROL=YES CNTRL macro used for this file. Omit CTLCHR for this file. Does not apply to 250l. X X 0 CRDERR=RETRY Retry if punching error is detected. Applies only to 2520 OUTPUT and to 2540 OUTPUT or CMBND. 0 CTLCHR=YES Data records have control character in first position. Omit CONTROL for this file. X 0 INAREA=xxxxxxxx Name of sep. input area for 1442 CMBND file. Also specify OUAREA, and omit IOAREAl and IOAREA2. Applies only to 1442. X 0 INBLKSZ=nn Length of INAREA. Also specify OUBLKSZ, and omit BLKSIZE. X X X X 0 IOAREA 1=xxxxxxxx Name of first I/O area. Omit INA REA or OUAREA. Do not use for 1442 CMBND file with separate I/O areas. X X X 0 IOAREA2=xxxxxxxxx If two I/O areas are used, name of second I/O area. X X 0 IOREG=(nn) Register number, if two I/O areas are used and GET or PUT does not specify a work area. Omit WORKA. X 0 OUAREA=xxxxxxxx Name of sep output area for 1442 CMBND file. Also specify INAREA, and omit IOAREAl and IOAREA2. Applies to 1442 only. X 0 OUBLKSZ=nn Length of OUAREA. Also specify INBLKSZ and omit BLKSIZE. 0 RECFORM=xxxxxx (FIXUNB) if TYPEFLE=INPUT. (FIXUNB, VARUNB, or UNDEF) if TYPEFLE=OUTPUT. If omitted, FIXUNB is assumed. 0 RECSIZE=nnnn Register number if RECFORM=UNDEF. 0 WORKA=YES GET or PUT specifies work area. Omit 10REG. X X X X X X X M=Mandatory; O=Optional Figure 2-27 (part 1 of 7) 118 DTFSR macro operands - card DOS/VS Supervisor & I/O Macros x x M DEVICE=DISK 11 x x M BLKSIZE=nnnn Length of I/O area, in bytes M EO FAD D R=xxxxxxxx Name e specified as a symbol or in register notation. The second parameter is the mnemonic code for the command to be performed. This must be one of a set of predetermined codes (see Figur~ 2-30). The third parameter, n 1, is required whenever a number is needed for stacker selection, immediate printer carriage control, or for line or page marking on the 3886. The fourth parameter, n~, applies to delayed spacing or skipping, or to timing mark check on the 3886. In the case of a printer file, the parameters n 1 and n2 may be required. The CNTRL macro must not be used for printer or punch files if the data records contain control characters and the entry CTLCHR is included in the file definition. Whenever CNTRL is issued in your program, the DTF CONTROL operand must be included (except for DTFMT and DTFDR) and CTLCHR must be omitted. If control characters are used when CONTROL is specified, the control characters are ignored and treated as data. Part 2. Sequential Access Method 137 IBM ..... lt Mnemonic Code 3420, 2400 Series Magnetic Tape ..... Its n n l REW Rewind Tape RI,III Rewind and ..... Ioad Tape ERG Erase Gap (Writes Blank Tape) WTM Write Tapemark BSR Backspace to Interrecord Gap BSF Backspace to Tapemark BSL Backspace Logical Record FSR Forward Space to FSF Forward Space to Tapemark FSL Interrec~rd Gap Forward Space Logical Record 1 2 Select Stacker 1 or 2 1442, 2520 Cord Read Punch SS 2540 Cord Read Punch 3504,3505 Cord Readers 3525 Cord Punch PS 1 2 3 Select Stacker 1, 2, or 3 (For 3S04, 3S05, and 3525, 3 Defaults to Stacker 2) 2S6O Multi-Function Cord Machine SS 1 2 3 4 5 Select Stacker 1, 2, 3, 4, or 5 2596 Cord Read Punch SS Eject to Stacker 1 (1442 only) E 1 Select Stacker 1 for Read, or Stacker 3 for Punch 2 Select Stacker 2 for Read, or Stacker 4 for Punch Select Stacker 1, 2, 3, or 4 5425 Multi-Function Card ..... it SS 1 2 3 4 1403, 1443, 3203, 3211, 5203 Printers 3525 Card Punch with Print Feature SP c See Note d SK c d UCS ON 1403, 5203 Printers with Universal Character Set Feature or 3203, 3211 Printers I Command 2 Carriage Space 1, 2, or 3 lines Skip to Channel c and/or d (For 3525, a Skip to Channel 1 is Valid Only for Print Only Files.) Data Checks are Processed with an Operator Indication Data Checks are Ignored and Blanks are Printed OFF 3211 Printer FOLD Print Upper Case Characters for any Byte with Equivalent Bits 2-7 UNFOLD Print Character Equivalents of any EBCDIC Byte 2321 Data Cell Drive SEEK Seek to Address RESTR Return Strip to Subcell 2311, 2314, 2319, 3330, 3333, 3340 DASD SEEK Seek to Address 3881 Optical Mark Reader PS 1287 Optical Reader 1 2 Select stacker 1 or 2 MARK Mark Error line in Tape Made READKB Read 1287 Keyboard in Tape Made Eject Document EJD SSD 1 2 3 4 ESD 1-4 Select Stacker A, B, Reject, or Alternate Stacking • Made Eject Document and Select Stacker INC 1288 Optical Page Reader ESD 3886 Optical Character Reader DMK Increment Document at Read Station Select Stacker A Reject Stacker (R) 1 3 INC LMK Increment Document at Read Station Page mark the document when it is stacker selected os specified in parameter nl. nome (r) number ~~:::ge~! Line mark the document when it is stocker selected os specified In parameter nl. number ESP 1 2 nome (r) number Note: c • An Integer that Indicates Immediate Printer Cantrol (before printing). d - An Integer that Indicates a Delayed Printer Cantrol. Figure 2-30 CNTRL macro command codes 138 DOS/VS Supervisor & I/O Macros Eject and stocker select the current dacument to stocker A or B. Perform line mark station timing mark check os Indicated In parameter n2. MagI!etic Tape Unit Codes The CNTRC macro controls magnetic tape functions that are not concerned with reading or writing data on the tape. These functions are grouped in the following categories: Rewinding tape to the load point REW- Rewind RUN - Rewind and unload Moving tape to a specified position BSR - Backspace to interrecord gap BSF - Backspace to tapemark FSR - Forward space to interrecord gap FSF - Forward space to tape mark Forward or backward logical record spacing FSL - Forward space logical record BSL - Backward space logical record Writing a tape mark WTM- Write tapemark Erasing a portion of the tape ERG - Erase gap (writes blank tape) The tape rewind (REW and RUN) and tape movement (BSR, BSF, FSR, and FSF) functions can be used before a tape file is opened. This allows the tape to be positioned at the desired location for opening a file, so that: • The tape can be positioned to a file located in the middle of a multi-file-reel. • Rewinding of the tape can be performed even if NORWD was specified in the DTF REWIND operand. Note: If you are using a self-relocating program, you must open the file before issuing any commands for it. The tape movement functions (BSR, BSF, FSR, and FSF) apply to input files only, and the following factors should be considered: 1. The FSR (or BSR) function permits you to skip over a physical tape record (from one interrecord gap to the next). The record passes without being read into storage. The FSF (or BSF) function permits you to skip to the end of the file (identified by a tapemark). 2. The functions of FSR, FSF, BSR, and BSF always start at an interrecord gap. 3. If blocked input records are processed and if you do not want to process the remaining records in the block, nor one or more succeeding blocks, issue a RELSE macro before the CNTRL macro. The next GET then makes the first record of the new block available for processing. If the CNTRL macro (with FSR, for example) is issued without a preceding RELSE, the tape is advanced. The next GET makes the next record in the old block available for processing. 4. For any I/O area combination except one I/O area and no work area, 10CS always reads one tape block ahead of the one that is being processed. Thus, the next block after the current one is in storage ready for processing. Therefore, if a CNTRL FSR is given, the ~econd block beyond the present one is passed without being read into storage. 5. If FSR or BSR is used, LIOCS does not update the block count. Furthermore, 10CS cannot sense tapemarks on an FSR or BSR command. Therefore, 10CS does not perform the usual EOV or EOF functions in these cases. The tape spacing functions (FSL or BSL) apply to spanned record input files only. These codes are used when logical record spacing is desired. Consider these factors when FSL or BSL is specified: 1. Logical record spacing is ignored if it immediately follows a RELSE macro. 2. Forward and backward spacing refer to the absolute direction of the spacing. For example, if BSL is specified on an input file with READ=BACK, only one logical record is skipped. 3. If an end-of-file, end-of-volume, or an error condition occurs while a FSL or BSL spacing function is being executed, the condition is handled as if it occurred during a normal GET operation. Printer Codes The CNTRL macro can be used for forms control on any printer. The codes for printer operation cause spacing (SP) over a specified number of lines, or skipping (SK) to a specified location on the form. The third parameter, nl, is required for immediate spacing and skipping (before printing). The fourth parameter, n2, is required for delayed spacing or skipping (after printing). Part 2. Sequential Access Method 139 The SP and SK operations can be used in any sequence. However, two or more consecutive immediate skips (SK) to the same carriage channel on the same printer result in a single skip immediate. Likewise, two or more consecutive delayed spaces (SP) and/ or skips (SK) to the same printer result in the last space or skip only. Any other combination of consecutive controls (SP and SK), such as immediate space followed by a delayed skip or immediate space followed by another immediate space, causes both specified operations to occur. Printer With the UCS Feature The CNTRL macro can be used before a PUT for the file to change the method of processing data checks. Data checks can be either processed with an indication given to the operator, or ignored with blanks printed in place of the unprintable characters. A data check occurs when a character except null, (hexadecimal 00), or blank, (hexadecimal 40) sent to the printer does not match any of the characters in the UCS buffer. Before opening a file, the BLOCK parameter of the UCS job control command determines for a 1403 whether data check processing takes place. For another UCS printer, the NOCHK option of the SYSBUFLD program (see DOS / VS System Control Statements, GC33-5373) has the same meaning. If several DTFPRs are assigned to the same physical unit, the UCS parameter of the DTF last opened determines whether data check processing takes place. If a DTFDI is opened for a UCS printer, it has the effect of a NOCHK option. This change is operated on the physical device and is valid for all DTFs assigned to this device. If the UCS form of the CNTRL macro is used for a printer without the UCS feature, the CNTRL macro is ignored. Except on a 1403, 3203, or 5203, the CNTRL macro can also be used before a PUT for the file to control the printing of lower-case letters. Lowercase letters can either be printed or replaced by upper-case equivalents. Prior to using a CNTRL macro, the printing of lower case letters is controlled by the UCB FOLD parameter of SYSBUFLD. If the FOLD parameter is specified, bits 0 and 1 are considered ones and the upper case equivalent of bits 2-7 is printed. If UNFOLD is specified, the character equivalent of the EBCDIC byte is printed. 140 DOS/VS Supervisor & I/O Macros 1442 and 2520 Card Read Punch Codes Cards fed in the 1442 and 2520 are normally directed to the stacker specified in the DTF SSELECT operand. If SSELECT is omitted, they go to stacker 1. The CNTRL macro can be used to temporarily override the normally selected stacker. Input File: CNTRL can be used only when one I/O area, with or without a work area, is specified for the file. To stack a particular card, the CNTRL macro should be issued after the GET for that card, and before the GET macro for the following card. When the next card is read, the previous card is stacked in the specified stacker. Note: If CNTRL is not issued after each GET, the same card remains at the read station. Output File: CNTRL can be used with any permissible combination of I/O areas and work areas. To stack a particular card, the CNTRL macro should be issued before the PUT for that card. After the card is punched, it is stacked into the specified pocket immediately. Combined File: CNTRL can be used with any permissible combination of I/O areas and work areas. If a particular card is to be selected, the CNTRL macro for the file should be issued after the GET and before the PUT for the card. When the next card is read, the previous card is stacked into the specified stacker. 2540 Card Read Punch Codes Cards read or punched on the 2540 normally fall into the stacker specified in the DTF SSELECT operand (or the R 1 or PI stacker if SSELECT is omitted). The CNTRL macro with code PS is used to select a card into a different stacker, which is specified by the third operand, n 1. The possible selections are shown below. (These selections are also those which may be specified in the DTF SSELECT operand.) Feed Stacker Value of n1 Read Read Read Punch Punch Punch Rl R2 RP3 PI P2 RP3 1 2 3 1 2 3 Input File: CNTRL can be used only when one I/O area, with or without a work area, is specified for the file. To stack a particular card, the CNTRL macro should be issued after the GET for that card. Before the next GET macro is executed, the card is stacked into the specified stacker. Note: If your program indicates that operator intervention is required on a 2540 (for example, to correct a card out of sequence in a card deck), your program has specified CONTROL =YES in CDMOD, and you do not use the CNTRL macro, then you should issue a CNTRL macro before the operator intervention is requested. Issuing CNTRL in this situation assures that subsequent commands issued to the 2540 after the operator intervention are not rejected as invalid. Output FOe: CNTRL can be used with any permissible combination of I/O and work areas. When you want to select a particular card, CNTRL must be issued before the PUT for that card. However, CNTRL does not have to precede every PUT. 2560 and 5425 Card Device Codes Cards fed into the 2560 or 5425 are normally directed to the output stacker specified in the DTF SSELECT operand. If SSELECT is omitted, cards which came from hopper 1 go to output stacker 1; and cards which came from hopper 2 go to output stacker 5 for the 2560, or output stacker 4 for the 5425. The CNTRL macro can be used to temporarily override the normally selected stacker. Single File: CNTRL cannot be used for a print file. For a read file, to stack a particular card the CNTRL macro must be issued after the GET for that card. For a punch file, or a punch/interpret file (DTFCD FUNC=I), to stack a particular card CNTRL must be issued before the·PUT for that card. Associated File: The sequence of CNTRL macro usage with associated files is described below and is summarized in the section GET/CNTRL/PUT Sequence for Associated Files under PUT Macro, above. CNTRL must be used with only one of the associated files: • With the read file if the associated file is read/ print. In this case, to stack a particular card CNTRL must be issued after the GET and before any PUT for that card. If no PUT is issued for that card, then CNTRL must be issued after the GET for that card and before the GET for the next card. • With the punch file if the associated file is anything other than read/print. In this case, to stack a card CNTRL must be issued before the PUT which punches that card. 2596 Card Read Punch Codes Cards fed into the 2596 are normally directed to the stacker specified in the DTF SSELECT operand. If SSELECT is omitted, cards go to stacker 1 for read and stacker 3 for punch. The CNTRL macro can be used to temporarily override the normally selected stacker. The possible selections are shown in Figure 2-25. (These selections are also those which may be specified in the DTF SSELECT operand.) Input File: CNTRL can be used only when one I/O area, with or without a work area, is specified for the file. To stack a particular card, the CNTRL macro should be issued after the GET for that card, and before the GET for the next card. When the next card is read, the previous card is stacked in the specified stacker. Output File: CNTRL can be used with any permissible combination of I/O areas and work area. To stack a particular card, the CNTRL macro should be issued before the PUT for that card. After the card is punched it is stacked into the specified stacker immediately. 3504 and 3505 Card Readers and 3525 Card Punch Codes Cards read on the 3504 or 3505 or punched on the 3525 are normally directed to the stacker specified in the DTF SSELECT operand. If SSELECT is omitted, stacker 1 is assumed. The CNTRL macro can be used to temporarily override the normally selected stacker. For input files, CNTRL can be used only when one I/O area is specified for the file. 3525 Card Printing Codes The CNTRL macro can control spacing and skipping to a specific line on a card for the 3525 card print feature. The command code SP is used to direct the 3525 to space one, two, or three lines on a card; and SK is used to skip to a channel (1-12) on a card. (See the section 3525 Printing under PUT Macro, above. The 3525 print channels correspond to specific rows on a printed card. The channels and their corresponding card rows are shown in Figure 2-31. Part 2. Sequential Access Method 141 Line Number Channel Number 1_ _ _ _ _ _ _ _ _ 1 2 3_________ 2 4 5_________ 3 6 7 _ _ _ _ _ _ _ _ _4 89 _ _ _ _ _ _ _ _ ~ 10 '11 _ _ _ _ _ _ _ _ _ 6 12 13 _ _ _ _ _ _ _ _ _ 7 14 15 _ _ _ _ _ _ _ _ _8 16 17 _ _ _ _ _ _ _ _ _ 9 (overflow) 18 19 _ _ _ _ _ _ _ _ .....l 0 20 21 _ _ _ _ _ _ _ _ _11 22 23 _ _ _ _ _ _ _ _ _ 12 (overflow) 24 25 Figure 2-31 3525 print channels DASD Codes The CNTRL macro to seek (SEEK) for any DASD device, or to restore (RESTR) for the 2321, permits access movement to begin for the next READ, WRITE, GET, or PUT macro. While the arm is moving for a SEEK or the strip is being restored on a data cell, you can process data and/or request I/O operations on other devices. IOCS seeks the track that contains the next block for that file without your having to supply a track address. If the CNTRL macro is not used, IOCS performs the seek or restore operations when a READ, WRITE, GET, or PUT macro is issued. 3881 Optical Mark Reader Codes Documents read by the 3881 are directed to the stacker specified in the CNTRL macro or to the stacker specified on the format control sheet. Stacker 1 is the normal stacker and stacker 2 is the select stacker. If you use both the CNTRL macro and the format control sheet to control stacker selection and either specifies stacker 2, data documents are !! 1~ DOS/VS Supervisor & I/O Macros stacked in stacker 2. The DTF SSELECT operand is not valid for the 3881. 1287 and 1288 Optical Reader Codes The CNTRL macro for the 1287 and 1288 is used for the nondata functions of marking a journal tape line, incrementing a document, and ejecting and/or stacker selecting a document. It is also used to read data from the 1287 keyboard when processing journal tapes. When the CNTRL macro is used with the READKB mnemonic, it allows a complete line to be read from the 1287 keyboard when processing journal tapes. This permits the operator to key in a complete line on the keyboard if a 1287 read error makes this type of correction necessary. When IOCS exits to your COREXIT routine, you may issue the CNTRL macro to read from the keyboard. The 1287 display tube then displays the full line and the operator keys in the correct line from the keyboard, if possible. The line read from the keyboard is always read leftjustified into the correct input area. The macro resets this area to binary zeros before the line is read. After CNTRL READKB is used, the contents of filename+80 are meaningful only for a wrong-length error indication (X'04'). Therefore, you must determine whether the operator was able to recognize the unreadable line of data. The CNTRL macro with the READKB mnemonic waits for completion of the order before returning control to the user. When processing journal tapes, the CNTRL macro with the MARK mnemonic marks (under program control) a line on the input tape that results in a data transfer error or is otherwise suspect of error. To ensure that the proper line is marked, the CNTRL macro must be issued in your error correction routine (specified in DTFOR COREXIT). If CNTRL is issued at any other time, the line following the one in error is marked. When processing is done in document mode on the 1287, each document may be ejected with a CNTRL macro. The EJD mnemonic causes the document to eject and the next document is fed. Documents may also be stacker selected by using the CNTRL macro with the SSD mnemonic. The CNTRL macro with the ESD mnemonic combines the ejection and stacker selection functions. To satisfy the alternate ejection and stacker selection functions, the combined mnemonic must not be immediately preceded by an eject or immediately followed by a stacker select. A document may be directed to stacker A, B, or R (reject stacker) by specifying a selection number of 1, 2, or 3 respectively. Also, documents may be selected into stackers A and B in an alternate stacking mode, with automatic stacker switching when one stacker becomes full. The selection number for alternate mode is 4. If selection number 4 is used in the first stacker selection macro, stacker A is filled first. If selection number 4 is used after other selection numbers, the last preceding selection number determines the first stacker to be filled. Only selection numbers 1 and 3 are available for the 1288. If a CNTRL macro is issued in a COREXIT routine and a late stacker select or nonrecoverable error condition occurs, IOCS branches to the next sequential instruction. Filename+80 should therefore be tested for these conditions after issuing a CNTRL macro. The CNTRL macro with the INC mnemonic may be used for document incrementation. This macro is not used with documents having a scannable area shorter than 6 inches. When this mnemonic is issued, the document is incremented forward 3 inches. This macro may be used only once per document. For the 1288, the CNTRL macro with the INC mnemonic can increment only documents with a scannable area longer than 6.5 inches. The document is incremented to the next stopping point as selected by console switches on the 1288. More than one CNTRL macro can be used per document. Document ejection and/or stacker selection and document increment functions can also be accomplished by including the appropriate CCW(s) within the CCW list addressed by the READ macro, rather than by using the CNTRL macro. This technique results in increased document throughput. Note: For processing documents in a multiprogramming environment where the partition containing 1287 support does not have highest priority, the eject and stacker select functions must be accomplished by a single command. However, when processing documents in a dedicated environment, the stacker select command can be executed separately. It must follow the eject command within 270 milliseconds if the document was incremented, or within 295 milliseconds if the document was not incremented. The eject and stacker select functions must occur alternately. If the timing requirements are not met, a late stacker selection condition occurs. 3886 Optical Character Reader Codes When you are using the 3886 Optical Character Reader, you can use the CNTRL macro to perform the following operations: ' • • • • Page mark the current document Line mark the current document Eject and stacker select the current document Perform timing mark check When the operation has been completed successfully, control is returned to the next instruction in your program. If the operation does not complete successfully, the COREXIT routine receives control. The end-of-file routine receives control when an operation is requested but no documents are available and the end-of-file key has been pressed. The contents of parameters n 1 and n2 vary depending on the mnemonic operation code specified. Therefore, this discussion treats each mnemonic code separately. DMK,nl: Specifies that the document currently being processed is to be marked when the next eject/stacker-select command is issued. The digits to be printed on the page are specified by the four loworder bits of the field indicated in parameter n1. The sum of the mark digits printed will equal the value specified in the four bits. The high-order four bits of the field are not used. You can specify the digits you want printed in one of three ways: • name specifies the symbolic name of a one-byte field in your program in which the low-order four digits indicate the combination of digits to be printed. • (r) indicates the number of the register that contains the address of the one-byte field used for page marking. • number indicates the sum of the digits to be printed. The decimal number may be from 1 through 15. LMK,nl: Specifies a line on the current document that is to be line-marked when the eject/ stackerselect command is issued. The digits to be printed and the line on which they should be printed are specified in a two-byte field. The digits to be printed are specified in the low-order four bits of the first byte as in the document marking operation. The line to be marked is specified in binary in the low-order six bits of the second byte of the field. You can specify the mark digits and line number in three ways: Part 2. Sequential Access Method 143 • name specifies the symbolic name of a two-byte hexadecimal field in your program that contains the necessary information. • ERET Macro (r) indicates the number of the register that contains the address of the two byte field with the necessary information. • number ,number provides first, the sum of the decimal digits to be printed (from 1 through 15) and second, the decimal line number to be marked (from 1 through 33). ESP,nl,n2: nl specifies that the current document should be ejected immediately and routed to stacker 1 or 2. (The valid entries are 1 and 2). A request for timing mark check can also be made in this parameter. If the number of timing marks on the document disagrees with the number you specify, either a nonrecovery error or timing mark check error occurs. You can specify the number of timing marks, by using parameter n2, in three ways: • name specifies the name of a one-byte hexadecimal field in your program that indicates the number of timing marks that should be on the document. • (r) specifies the number of the register that contains the address of the one-byte hexadecimal field containing the expected number of timing marks. • number is a decimal number from 0 through 33 specifying the number of timing marks there should be on the document. Name Operation Operand [name] ERET FORE {SKIP } \RETRY I I This macro enables your program's ERROPT or WLRERR routine to return to IOCS and specify an action to be taken. The macro applies only to DTFMT, DTFSD and DTFDU files with the ERREXT operand specified. The SKIP operand passes control back to the logic module to skip the block of records in error and process the next block. For disk or diskette output, an ERET SKIP is treated as an ERET IGNORE. The IGNORE operand passes control back to the module to ignore the error and continue processing with the block in error. The RETRY operand causes the module to retry the operation that resulted in the error. With MTMOD for any error or with SDMOD wrong-length record errors, RETRY cancels the job with an invalid SVC message. PRTOV Macro Name Operation [name] PRTOV Operand {mename}, {912} (1) [ , to<:e-name}] If the number of timing marks is not specified or if zero is specified, no timing mark check is performed. CHNGMacro Name Operation Operand [name] CHNG SYSnnn This macro is provided only for Basic Programming Support and Basic Operating System upward compatibility. No code is generated from this macro. In DOS/VS tape channel switching is handled automatically by PIOCS. 144 DOS/VS Supervisor & I/O Macros The PRTOV (printer overflow) macro is used with a printer file to specify the operation to be performed when a carriage overflow condition occurs. To use this macro, the PRINTOV = YES operand must be included in the DTFPR or DTFSR. PRTOV requires either two or three parameters. The first parameter must be the filename, written either as a symbol or in register notation. The second parameter must specify the number of the carriage control channel (9 or 12) used to indicate the overflow. When an overflow condition occurs, IOCS restores the printer carriage to the first printing line on the form (channell), and normal printing continues. The third parameter is required if you prefer to branch to your own routine on an overflow condition, rather than skipping directly to channel 1. It specifies the n~me of the routine, as a symbol or in register notation. However, the name should never be preloaded into register 1. If you specify the third parameter, 10CS does not restore the carriage to channell. In your routine you may issue any 10CS macro to perform whatever functions desired. If 10CS macros are used in the routine, register 14 must be saved. The CNTRL macro cannot be issued to the file unless CONTROL= YES is specified in the DTF. For example, you can print total lines, skip to channell, and print overflow page headings. At the end of the routine, return to 10CS by branching to the address in register 14. The PRTOV macro causes a skip to channell, or branches to your routine, if an overflow condition (channel 9 or 12) is detected on the preceding space or print command. An overflow condition is not recognized during a carriage skip operation. After the execution of any command which causes carriage movement (PUT or immediate CNTRL), you should issue a PRTOV macro before issuing the next CNTRL or PUT. This ensures that your overflow option is executed at the correct time. On the 3525 card punch, a channel 9 test indicates print line 17. A channel 12 test indicates print line 23. An overflow condition from either of these channels causes: • • a transfer of control to the overflow routine specified in the PRTOV macro, or a skip to channel one to begin printing on the next card for print only files. When the PRTOV macro is used on a 3525 2-line printer, the result of the test is always negative since lines 17 and 23 are not available. The test is logically a no-operation. Notes: PRTOV without the routine name option is invalid for 3525 associated files. A skip to channel one is valid only for 3525 print only files. PRTOV is not allowed for the 2560 or 5425. Magnetic Reader Macros Within a particular program, you should utilize either the GET macro or the READ, CHECK, WAITF combination. The READ, CHECK, and WAITF macros are described below. For a program operating with two or more MICR devices, the READ, CHECK, WAITF combination allows processing to continue within the program when any document buffer is ready for processing. On the other hand, the GET macro (suggested for a program operating with one MICR device) includes an inherent wait for a document buffer to become available within the file before processing begins. In a multiprogramming environment, control always passes to another partition whenever aWAIT condition occurs. Before any MICR document processing can be performed, the file(s) must be opened. If an unrecoverable II 0 error occurs when a GET macro is executed, no more GETs can be issued for the file. If an unrecoverable 110 error occurs when using the READ, CHECK, WAITF combination or when document processing for that file is complete, you can effectively continue by closing the file. Further READ, CHECK, WAITFs treat this file as having no documents ready for processing (see byte 0, bits 5 and 6 of the document buffer in Appendix E). READ Macro The READ macro makes the next sequential buffer available to you, but it does not verify that it is ready for processing (the CHECK macro is provided to make that test). If the buffer is not ready for processing, the next READ to that file points to the same buffer. Name Operation [name] READ Operand ffilename} l (1) ,MR The first operand specifies the name of the file associated with the record to be read. This name is the same as that specified in the DTFMR header entry for the file, written as a symbol or in register notation. The second operand signifies that the file is for a magnetic ink character reader (MICR). CHECK Macro Name Operation [name] CHECK Operand {filename} (1) [, {contr(~)ddress} ] The CHECK macro examines the buffer status indicators. A READ macro must therefore already have been issued to the file before a CHECK macro is issued. The first operand specifies the name of the file associated with the record to be checked. This name is Part 2. Sequential Access Method 145 the same as that specified for the DTFMR header entry for the file. The second operand indicates the address to which control passes when a buffer is waiting for data or when the file is closed. Both parameters can be specified either as a symbol or in register notation. CHECK determines whether the buffer contains data ready for processing, is waiting for data, contains a special nondata status, or the file (filename) is closed. If the buffer has data ready for processing, control passes to the next sequential instruction. If the buffer is waiting for data, or the file is closed, control passes to the control address, if present. If the buffer contains a special nondata status, control passes to the ERROPT routine for you to examine the posted error conditions before determining your action. (See byte 0, bits 2, 3, and 4, of the document buffer in Appendix E.) Return from the ERROPT routine to the next sequential instruction via a branch on register 14, or to the control address in register 0. One WAITF macro must be issued after a set of READ-CHECK combinations before your program attempts to return to a previously issued combination. Thus, the WAITF macro must be issued between successive executions of a particular READ macro. The operands required are the names of the files waiting to be processed. The names are the same as those specified in the DTFMR header entries. DISEN Macro This macro stops the feeding of documents through the magnetic character reader or optical reader/sorter. The program proceeds to the next sequential instruction without waiting for the disengagement to complete. You should continue to issue GETs or READs until the unit exception bit (byte 0, bit 3), of the buffer status indicators is set on (see Appendix E). Name Operation [name] DISEN If the buffer is waiting for data, or if the file is closed, and the control address is not present, control is given to you at your ERROPT address specified in the DTFMR macro. Operand ~fIlename} ~ (1) curs (with no control address) and no ERROPT address is present, control is given to you at the next sequential instruction. The only required operand specifies the name of the file to be disengaged. This name is the same as that specified for the DTFMR header entry for the file. The operand· can be specified either as a symbol or in register notation. If the waiting condition occurred, byte 0, bit 5 of the buffer is set to 1. If the file was closed, byte 0, bits 5 and 6 of the buffer are set to 1 (see Appendix E). LITE Macro If an error, a closed file, or a waiting condition oc- WAITFMacro UfIlename2} ... ,{ fIlenamen}J (rn) The WAITF (wait mUltiple) macro is essential when processing in a multiprogramming system. It allows processing of programs in other partitions while waiting for document data. If any device within the W AITF macro list has records or error conditions ready to be processed, control remains in the partition and processing continues with the instruction following the WAITF macro. ' 146 DOS/VS Supervisor & I/O Macros Operand [name] LITE ~filename~ [, {fIlename!} (d) (r2) Operation (1) Name Operation Operand [name] WAITF Name ~1ight (~;tches~J This macro lights any combination of pocket lights on a 1419 magnetic character reader or 1275 optical reader/sorter. Before using the LITE macro, the DISEN macro must be issued to disengage the device. Processing of the documents should be continued until the unit exception bit (byte 0, bit 3) of the buffer status indicators is set on (see Appendix E). When this bit is on, the follow-up documents have been processed, the MICR reader has been disengaged, and the pocket LITE macro can be issued. Bits 0 1 2 3 4 5 6 7 8 9 A B CDE F Pocket Lights A B 0 1 2 3 4 5 6 7 8 9 Reserved with binary zeros Error indicator bit Figure 2-32 Bit configuration for pocket light switch area of the 1419 The first operand is the name of the file; this name is the same as that specified for the DTFMR header entry for the file. The second operand indicates a 2-byte area containing the pocket light switches. Both operands can be given either as a symbol or in register notation. The bit configuration for the pocket light switch area is shown in Figure 2-32. The pocket lights that are turned on should have their indicator bits set to 1. If an error· occurs during the execution of the pocket lighting 110 commands, bit F is set to 1. This error condition normally indicates that the pocket light operation was unsuccessful. Optical Reader Macros -1287 GET Macro See GET Macro, above in this chapter. CNTRLMacro See CNTRL Macro, above in this chapter. DSPLY Macro Name Operation [name] DSPLY Operand ~filename~ ,(r),(r) the correct field from the keyboard, if possible. The field read from the keyboard is always read into the area (normally within IOAREAl) that was originally intended for this field as specified in the CCW. The macro first resets this area to binary zeros. At completion of the operation, the data is left-justified in the area. DSPLY always requires three parameters. The first parameter is the symbolic name specified in the DTFOR header entry for the 1287 file. The second parameter specifies a general-purpose register (2-12) into which the problem program places the address of the load format CCW giving the document coordinates for the field to be displayed. When the DSPLY macro is used in the COREXIT routine, the address of the load format CCW can be obtained by subtracting 8 from the 3-byte address that is rightjustified in the fullword location beginning at filename + 32. (The high-order fourth byte of this full word should be ignored.) If the DSPLY macro is not used in the COREXIT routine, you must determine the load format CCW address. The third parameter specifies a general-purpose register (2-12) into which you place the address of the load format CCW giving the coordinates of the reference mark associated with the displayed field. The contents of filename+80 are meaningful only for X'40' (1287 scanner cannot locate the reference mark) and X'04' (wrong-length record) after the DSPLY macro is issued. Therefore, you must determine whether the operator was able to recognize the unreadable line of data. (1) The DSPLY macro displays the document field on the 1287 display scope. A complete field may be keyboard-entered if a 1287 read error makes this type of correction necessary. An unreadable character may be replaced by the reject character either by the operator (if processing in the on-line correction mode) or by the device (if processing in the off-line correction mode). You may then use the DSPLY macro to display the field in error. The 1287 display tube displays the full field and the operator keys in Note: When using the DSPLY macro, you must ensure that the load format CCW is command chained to the CCW used to read that field. This provides the document coordinates for the field to be displayed. Part 2. Sequential Access Method 147 READ Macro The READ macro causes the next sequential 1287 or 1288 optical reader (document mode only) record to be read. Name Operation Operand [name] READ ~ fIlename ~ ,OR, ~ name~ (1) (r) The first parameter is the symbolic name specified in the DTFOR header for the file; it is always required. The parameter OR is required to indicate an optical character reader. The parameter name is always required; it specifies the address of the CCW list which you provide to be used to read a document from the 1287 or 1288. The register entry may be used in this parameter to provide the address of the CCW list. The first CCW in the list must not be a transfer-in-channel CCW. To accomplish document ejection and/or stacker selection and document increment functions, include the appropriate CCW(s) within the CCW list addressed by the READ macro. This technique results in increased processing throughput. This method is preferable to using the CNTRL macro for document control. commands, the input area is not cleared. When 1288 unformatted fields are read the RESCN macro should not be used. The first parameter specifies the symbolic name of the 1287D file as specified in the DTFOR header entry for the file. The second parameter specifies a general-purpose register (2-12) into which the program places the address of the load format CCW. When this macro is used in the COREXIT routine, the address of the load format CCW is obtained by subtracting 8 from the 3-byte address that is rightjustified in the fullword location beginning in filename+32. (The high-order fourth byte of this fullword should be ignored.) If the RESCN macro is not used in the COREXIT routine, you must determine the load format CCW address. The third parameter specifies a general-purpose register (2-12) into which the program places the address of the load format CCW for reading the reference mark. The previous three parameters are always required, and result in one attempted reread for the field. The fourth parameter, n1, allows you to specify the number of attempts (one to nine allowed) to reread the unreadable field. If this parameter is omitted, om' is assumed. The WAITF macro must be issued after the READ macro and before the program attempts to process an input record of the file. The fifth parameter, n2, indicates one more reread which forces on-line correction of any unreadable character(s) by individually projecting the unreadable character(s) on the 1287 display scope. RESCN Macro The operator must key in a correction (or reject) character(s). This operand cannot be used for 1288 processing. Name Operation Operand [name] RESCN ~ fIlename~ If the reread of the field results in a wrong-length , (d) , (r2) [,n1] [,n2] record, incomplete read, or an unreadable character, it is indicated in filename+80. (1) The RESCN macro selectively rereads a field on a document when a defective character(s) makes this type of operation necessary. The field is always right-justified into the area (normally within IOAREAl) that was originally intended for this field as specified in the CCW. The macro first resets this area to binary zeros. Notes: For the 1287 models 3 and 4 and the 1288, this macro can only be used with READ BACKWARD commands. If used with READ FORWARD 148 DOS/VS Supervisor & I/O Macros Note: When using RESCN macro, you must ensure that the load format CCW (giving the document coordinates for the field to be read, second parameter) is command chained to the CCW used to read that field. RDLNEMacro Name Operation [name] RDLNE Operand ~filename~ (1) The RDLNE macro provides selective on-line correction when processing journal tapes on the 1287 optical reader. This macro reads a line in the on-line correction mode while processing in the off-line correction mode. RDLNE should be used in the COREXIT routine only, or else the line following the one in error will be read in on-line correction mode. The WAITF macro accomplishes all checking for read errors on the 1287 or 1288 file and exits to your COREXIT routine for handling of these conditions, if necessary. Optical Character Reader Macros-3886 READ Macro Name Operation [narne] READ Operand ~ menarne~ (1) If the 1287 cannot read a character, IOCS first resets the input area to binary zeros and then retries the line containing the character which could not be read. If the read is unsuccessful, you are informed of this condition via your error correction routine (specified in DTFOR COREXIT). The RDLNE macro may then be issued to cause another attempt to read the line. If the character in the line still cannot be read, the character is displayed on the 1287 display scope. The operator keys in the correct character, if possible. If the operator cannot readily identify the defective character, he may enter the reject character in the error line. This condition is posted in filename+80 for your examination. Wrong-length records and incomplete read conditions are also posted in filename+80. This macro requires only one parameter, the symbolic name of the 1287 file from which the record is to be retrieved. This name is the same as that specified in the DTFOR header entry for the file. Operation [name] WAITF l nrune \ (r) number, number The READ macro reads one line of data from the document. Note: You must not issue any 110 macros to the 3886 between READ and WAITF macros. This would cause any errors detected during the read operation to be lost and the COREXIT routine would not be entered for that error. The first parameter specifies the name of the DTFDR macro for the file, filename, or indicates that the address of the DTFDR is in register one, (1). The second parameter, DR, is a required parameter that indicates a 3886 Optical Character Reader is the input device. The third parameter specifies the line number to be read and the format record for the line in one of three ways: WAITF Macro Name ,DR, Operand name provides the symbolic address of a twobyte hexadecimal field containing the line number in the first byte and the format record number in the second byte. )filename~ ) (1) The WAITF macro is used to ensure that the transfer of a 1287 or 1288 optical reader record (document mode only) is completed. It requires only one parameter: the symbolic name of the file containing the record. This instruction must be issued following a READ and before the problem program attempts to process an input record for the file concerned. The program waits until the transfer of data is complete. (r) provides the register number that contains the address of the two-byte hexadecimal field. • number,number provides the decimal line number to be read (1-33), followed by the format record number used to read the line (0-63). Note: The line number specified must always be Part 2. Sequential Access Method 149 equal to or greater than the line number specified for the previous read operation on the current document; otherwise, a permanent error occurs. The first parameter specifies the name of the DTFDR macro, filename, for this file, or indicates the address of the DTFDR is in register 1, (1). WAITF Macro The second parameter specifies the name of the format record to be loaded, phase name ; or indicates the register containing the address of an 8-byte area that contains the phasename, (r). Name Operation [name] WAITF Operand ~filename\ Work File Macros for Tape and Disk (1) The W AITF macro is used to ensure that an I/O operation is completed before execution continues. If the operation is not completed when the W AITF macro is issued, the active partition is placed in a wait condition until the I/O operation is completed. The completed operation is then tested for errors. If no errors were detected, control is returned to the next instruction in your program. If an error occurs during the I/O operation, control is passed to the COREXIT routine. If an I/O operation is requested, no more documents are available, and the end-of-file key has been pressed, control is given to the end-of-file routine. The only parameter of the W AITF macro specifies the name of the DTFDR macro for the file, filename, or indicates the address of the DTFDR is in register one (1). CNTRLMacro See CNTRL Macro above in this chapter. SETDEV Macro Name Ooeration [name] SETDEV Ooerand 1 ~ filename ~ , phasename ~ (1) (r) The SETDEV macro changes format records during execution of the program. When the new format record has been loaded into the 3886, control returns to the next sequential instruction in your program. If the operation is not successful, the completion code is posted at EXITIND and control is passed to the COREXIT routine, or the job is canceled. If you issue the SETDEV macro and no documents remain to be processed and the end-of-file key has been pressed on the device, control is passed to the end-of-file routine. 150 DOS/VS Supervisor & I/O Macros A work file can be used for disk and tape input, output, or both. If TYPEFLE=WORK is specified in the DTF, the work file macros READ, WRITE, and CHECK may be used. Also, if NOTEPNT=YES is specified, the work file macros NOTE, POINTR, POINTW, and POINTS may be used. Work files may contain only fixed-length unblocked records and undefined record formats. Tapes written in ASCII mode cannot be used for work files. A tape work file is a single-volume file used for both input and output. It passes intermediate results between successive phases or job steps; however, work files also can be written, read, and rewritten within a single phase, without requiring additional OPEN, OPENR or CLOSE or CLOSER processing. Work files are specified by the DTFMT and MTMOD TYPEFLE= WORK operand, and are accessed by the READ/WRITE and CHECK macros. The first time the volume for a work file is opened, it is opened as an output file. OPEN or OPENR examines the tape to determine whether it contains standard labels. The DTFMT FILABL operand, if present, is ignored. If the tape is labeled and the date in the header label has expired, a new label is created, consisting of HDRI followed by 76 blanks. Job control label information cards are not required. If the tape does not already contain standard labels, labels are not created for the tape. Trailer labels are not processed. If a work file with standard labels is reopened, OPEN or OPENR determines from the HDR label that the file is a work file and does not rewrite the labels. When a tapemark is sensed during a read operation, or when an end-of-reel reflective spot is sensed during a write operation, 10CS exits to the address you specified in the EOFADDR operand of DTFMT. Disk work files are supported as single-volume single-pack files. They are always opened as output files. You must supply standard label information. Both normal extents (type 1) and split extents (type 8) are supported. File protection for work files is ensured only if the labels are unexpired. Deleting a Work File After Use: The DTFSD DELETFL=NO operand must not be used. OPEN or OPENR creates a format 1 label for the file, and CLOSE or CLOSER destroys this label. The next job requiring a work file can use the same extents and filename. Saving a Work File After Use: The expiration date in the DLBL job control statement must not be the current date. The DTFSD DELETFL=NO operand must be specified. OPEN or OPENR creates a format 1 label, but CLOSE or CLOSER does not delete it. Thus, the file can be saved until the expiration date is reached. Deleting an Unexpired File: When you try to use the limits of an unexpired file, an operator message is printed to indicate the overlap condition. The operator can then delete the label, after which OPEN or OPENR creates a label for the new file and the job continues. The second parameter, SQ (for sequential), is always required. The third parameter, area, specifies the name (as a symbol or in register notation) of the input area used by the file. If tape is to be read backwards, area must be the address of the rightmost byte of the input area. The fourth parameter, length, is used only for records of undefined format (RECFORM= UNDEF). To read only a portion of a record, an actual length (or a register containing the number) can be specified. Or, an S can be provided to indicate that the entire physical record should be read. If the work file records are fixed length unblocked records (RECFORM=FIXUNB), this parameter must not be specified in the READ macro. In this case, the number of characters to be read is specified in the BLKSIZE operand. You can change this number (which is stored in the DTF table) at any time by referencing the halfword filenameL. WRITE Macro READ Macro The READ macro makes the next sequential record, or part of it, available to you. The record is read into the area of virtual storage indicated by the third operand. The DTF READ=FORWARD or BACK operand should specify the direction of reading for tape. The CHECK macro must be issued after the READ macro and before your program attempts to process an input record for the file. The WRITE macro writes a record from the indicated area into the file named. The record is stored following the last record written in this file. The CHECK macro must be issued after the WRITE macro to allow for completion of the input/output operation. Name Operation [name] WRITE Operand ~mename~ , (1) ~ area ~ (0) Name Operation [name] READ [, ~ UPDATE SQ f' ~ le(~~h ~ ] Operand ~mename ~ ,SQ, {area~ (1) (0) [r:(~)th~ ] The first parameter specifies the name of the file from which the record is to be read and is always required. This name is the same as the name specified in the DTFMT or DTFSD header entry for the file. The name can be specified as a symbol or in register notation. The first parameter specifies the name of the file to which the record is to be written and is always required. This name is the same as the name specified in the DTFMT or DTFSD header entry for this file. The name can be written as a symbol or in register notation. The second parameter specifies the type of WRITE to be executed. For magnetic tape, this parameter is always SQ. If SQ is specified for disk work files, a formatting WRITE (write count key and data) is executed. If UPDATE is specified, a nonformatting WRITE (write data) is executed. An update WRITE should be preceded by a READ, WRITE UPDATE, Part 2. Sequential Access Method 151 POINTR, or POINTW macro. A CLOSE or CLOSER macro (following an update write) protects the updated file by not writing an end-of-file record. If SQ is specified and a CLOSE or CLOSER immediately follows an OPEN or OPENR (no formatting WRITE commands were issued), an end-of-file record is not written. The third parameter, area, specifies the name, as a symbol or in register notation, of the output area used by the file. The fourth parameter, length, is used only for records of undefined format (RECFORM=UNDEF). Length specifies the actual number (or register containing the number) of bytes to be written. If fixed-length unblocked records (RECFORM=FIXUNB) are written, length is not used in the WRITE macro. The number of characters to be written is specified in the BLKSIZE entry. You can change this number, which is stored in the DTF table, at any time by referencing the halfword filenameL. For disk, the BLKSIZE entry should not include eight bytes for the length of a count field. CHECK Macro Name Operation Operand [name] CHECK ~filename~ (1) This macro must be used after each READ or WRITE. It prevents processing until completion of the inputI output operation, started by either a READ or a WRITE, for the device associated with the filename. If the 110 operation is completed without any error or other exceptional condition, CHECK returns control to the next instruction. If the operation results in a read error, CHECK processes the option specified in ERROPT. If CHECK finds an end-offile condition, control is passed to the routine specified in EOF ADDR. NOTE Macro Name Operation [name] NOTE Operand ~filename ~ (1) 152 DOS/VS Supervisor & I/O Macros The NOTE macro obtains identification for a physical record that is read or written during processing. The CHECK macro must be issued before the NOTE macro to ensure that the last operation has completed. For magnetic tape, the last record read or written is identified by the number of physical records read or written in the specified file from the load point. The physical record number is returned in binary in the three low-order bytes of register 1. The high-order byte contains binary zero. You must store the identification so that it can be used later in either a POINTR or POINTW macro. For disk, if a READ precedes the NOTE, the record identified is the last record read. If a WRITE precedes the NOTE, the record just written is the identified record. The identification is returned in register 1 in the form cchr, where • • cc = Cylinder number, h = Track number, r = Record number within the track. cc, h, and r are binary numbers. If NOTE follows a READ or WRITE to a disk file, the unused space remaining on the track following the end of the identified record is returned in register a as the binary number OOnn. You must construct a six-byte field and store in it the identification of the record and the remaining track capacity (in the form cchrnn) so that it can be used later in a P0INTR or POINTW macro to find the noted record again. The nn of cchrnn is needed only for WRITE SQ. POINTR Macro Name Operation [name] POINTR Operand ~ filename ~ , ~ address~ (1) (0) The POINTR macro repositions the file for reading a record identified by the NOTE macro. For magnetic tape, address specifies a 4-byte virtual storage location containing the required record identification. It can be expressed as a symbol or in register notation. The four-byte number must be in the form obtained from the NOTE macro. POINTR repositions the file to read the record that was read or written immediately before the NOTE that was used to create the record identification field was issued. For magnetic tape, a WRITE must not follow POINTR. For disk, address specifies a four-byte virtual storage location containing the required record identification. If WRITE SQ is used, two bytes containing the remaining track capacity must also be supplied. The disk address can be expressed as a symbol or in register notation. The four- or six-byte number must be supplied in the form obtained from the NOTE macro (cchr or cchrnn, where nn is the length remaining on the track). POINTR repositions the file to read the record identification returned when a previous NOTE macro was issued. If a WRITE UPDATE follows the POINTR macro, the noted record is overwritten. If a WRITE SQ follows the POINTR macro, the record after the noted record is written, and the remainder of the track is erased. Some programs using disk work files may include multiple WRITE macros following a NOTE macro. If a POINTR macro is used and the work file records are in undefined format, there may be occasions when a replacement record longer than the original record remains as the last record on the track when the next WRITE is performed. The replacement record is written as the first record on the next track of the file. POINTW Macro Name Operation [name] POINTW Operand {filename~ , {addreSs~ (1) (0) The POINTW macro repositions a file to write a record. For magnetic tape, address specifies a four-byte virtual storage location containing the required record identification. It can be expressed as a symbol or in register notation. The four-byte number must be in the form obtained from the NOTE macro (Obbb). POINTW repositions the file to write a record after the one previously identified by the NOTE. When a READ is issued to a tape file following a POINTW, the tape is positioned to read the record following the one identified by the NOTE. disk address can be expressed as a symbol or in register notation. The four- or six-byte number must be supplied in the form obtained from the NOTE macro (cchr or cchrnn, where nn is the length remaining on the track). POINTW repositions the file to write at the record location that was read or written immediately before the last NOTE macro was issued. If a WRITE UPDATE is issued, the noted record is overwritten. If a WRITE SQ is issued, the record following the noted record is written and the remainder of the track is erased. A READ macro can follow the POINTW macro, in which case the record identified by the NOTE is the record read. Some programs using disk work files may include multiple WRITE macros following a NOTE macro. If a POINTW macro is issued and the work file records are in undefined format, there may be occasions when a replacement record longer than the original record cannot be written in the space available on the track. In this case, when the next WRITE is performed, the original record remains as the last record on the track. The replacement record is written as the first record on the next track of the file. POINTS Macro The POINTS macro repositions a file to its beginning. Name Operation Operand [name] POINTS tilename~ (1) For a tape file, the tape is rewound. If the file contains any header labels, they are bypassed, and the tape is positioned to the first record following the label set. For disk, the file is repositioned to the lower limit of the first extent. An example of POINTS with workfile processing follows: For disk, address specifies a four-byte virtual storage location containing the required record identification. If WRITE SQ is used, two bytes containing the remaining track capacity must also be supplied. The Part 2. Sequential Access Method 153 L A NRITE 1 2, LENGTH (load length ofvarlength record to reg) F , SQ , OUT, (1 2) (write a record) (processing of data unrelated to OUT) FEOV Macro Name Operation [name] FEOV Operand {filename ~ (1) CHECK (wait until record is written) F (finish processing) (reposition to beginning of file) BNZ A POINTS F B READ F , SQ , IN, S (read physical record 1) • • CHECK F BNZ EOl] B (processing data unrelated to IN) (wait until record is read) (finish processing) On disk or magnetic tape, a POINTS followed by a WRITE SQ causes the new record to be written and the remainder of the track is erased. On disk, POINTS should not be followed by a WRITE UPDATE. Completion Macros The completion macros CLOSER and CLOSE are used after the processing of a file is completed. These macros end the association of the logical file declared in your program with a specific physical file on an 110 device. CLOSER or CLOSE must be issued to deactivate all files (with the exception of DTFCN files, for which CLOSER and CLOSE must not be issued--no deactivation of DTFCN files is necessary) . The FEOV (force end-of-volume) macro is used for either input or output files on magnetic tape (programmer logical units only); for system logical units see SEOV Macro in the Physical IOCS Macros chapter) to force an end-of-volume condition before sensing a tapemark or reflective marker. This indicates that processing of records on the current volume is finished, but that more records for the same logical file are to be read from, or written on, a following volume. If a spanned record is begun on an output file and there is not enough space to contain it, MTMOD issues an FEOV at the end of the last completed spanned record. The last spanned record (for which there was no room) is rewritten on a new volume. The name of the file, specified in the header entry, is the only parameter required. The name can be specified either as a symbol or in register notation. When LIOCS macros are used for a file, FEOV initiates the same functions that occur at a normal endof -volume condition, except for checking of trailer labels. For an input tape, FEOV immediately rewinds the tape (as specified by REWIND) and provides for a volume change (as specified by the ASSGN cards). Trailer labels are not checked. FEOV then checks the standard header label on the new volume and allows you to check any user-standard header labels if LABADDR is specified. If nonstandard labels are specified (FILABL=NSTD), FEOV allows you to check these labels as well. For an output tape, FEOV writes Included here under the category of completion macros are the FEON and FEOVD macros, which are used to force an end-of-volume condition for magnetic tape or disk, respectively. Use of these macros does not preclude the requirement to issue CLOSER or CLOSE when processing of a file is complete. A description of these completion macros follows. 154 DOS/VS Supervisor & I/O Macros • • A tapemark (two tapemarks for ASCII files.) A standard trailer label and user-standard labels (if any). A tapemark. If the volume is changed, FEOV then writes the header label(s) on the new volume (as specified in the DTFMT REWIND, FILABL, LABADDR operands, and the ASSGN cards). If nonstandard labels are specified, FEOV allows you to write trailer labels on the completed volume and header labels on the new volume, if desired. CLOSE and CLOSER Macros FEOVDMacro Name Operation Operand [name] FEOVD ~filename~ (1) The FEOVD (force end-of-volume for disk) macro is used for either input or output files to force an end-of-volume condition before it actually occurs. This indicates that processing of records on one volume is finished, but that more records for the same logical file are to be read from, or written on, the following volume. If extents are not available on the new volume, or if the format 1 label is posted as the last volume of the file, control is passed to the EOF address specified in the DTF. The name of the file is the only required operand. The name can be specified either symbolically or in register notation. When FEOVD is issued to an input file, an end of extent is posted in the DTF. When the next GET is issued for this file, any remaining extents on the current volume are bypassed, and the first extent on the next volume is opened. Normal processing is then continued on the new volume. When FEOVD is issued for an output file, a short last block is written, if necessary, with a standard end-of-file record containing a key length of one (indicating end of volume). An end-of -extent condition is posted in the DTF. When the next PUT is issued for the file, all remaining extents on the current volume are bypassed. The first extent on the next volume is then opened, and normal processing continues on the new volume. The DOS FEOVD EOV marker is compatible with the OS EOV marker. If the FEOVD macro is followed immediately by the CLOSE(R) macro, the end-of-volume marker is rewritten as an end-of-file marker, and the file is closed as usual. Op Operand for self-relocating programs CLOSER ~ftlenamel~ (d) [ '~ filename2 ~ ... , ~ filenamen ~ (r2) (rn) ] for progra [IlS that are not self-relocating CLOSE ~ filename 1 ~ (rl) [ , ~ ftlename2 ~ ... , ~ filenamen ~ ] (r2) (rn) The CLOSER or CLOSE macro must be issued to deactivate any file which was previously opened. Console files, however, cannot be closed. When CLOSER is specified, the symbolic address constants that CLOSER generates from the parameter list are self-relocating. When CLOSE is specified, the symbolic address constants are not selfrelocating. To write the most efficient code in a multiprogramming environment it is recommended that CLOSER be used. A CLOSE or CLOSER normally deactivates an output file by writing an EOF record and output trailer labels, if any. CLOSE(R) sets a bit in the format-l label to indicate the last volume of the file. A file may be closed at any time by issuing this macro. For diskette files, CLOSE or CLOSER sets the multivolume indicator in the HDRllabel to indicate the last volume of the file. Then, it sets up the end-ofdata address in the HDRI label and feeds the last diskette, determined by the FEED operand in the DTF. After a CLOSE or CLOSER, no further commands can be issued for the file unless it is reopened. Sequential DASD files cannot be successfully reopened for output unless the DTFSD table is saved before the file is first opened, and restored between closing the file and reopening it again as an output file. Enter the symbolic name of the file (DTF filename) in the operand field. A maximum of 16 files may be Part 2. Sequential Access Method 155 closed by with one CLOSE or CLOSER by entering the filenames as additional operands. macro. Alternately, you can load the address of the filename into a register and specify the register using ordinary register notation. The high-order 8 bits of this register must be zeros. For CLOSER, the address of filename may be preloaded into any of the registers 2-15. For CLOSE, the address of filename may be preloaded into register 0 or any of the registers 2-15. For the 3525, Figure 2-33 shows the card movement caused by issuing CLOSE(R). File Type Feed Caused by Close of: Read Read* Punch Punch Print Print you follow the standard practice of using only registers 2-12. Read/Print Print* If CLOSE(R) is issued to a magnetic tape input Read/Punch/Print Print** Read/Punch Punch** Punch/ Print Print Punch/Interpret Punch Notes: • • If you use register notation, we recommend that file that has not been opened, the option specified in the DTF REWIND operand is performed. If CLOSE(R) is issued to a magnetic tape output file that has not been opened, no tape mark or labels are written, and no REWIND option is performed. For a paper tape punch file with two I/O areas, CLOSE(R) checks for the successful completion of the last operation. For the 2560, 3525, or 5425, when CLOSE(R) is issued for a file it must also be issued for any associated files without any intervening input/ output operations. Reopening one associated file requires reopening the others. For 2560 or 5425 read associated files, the last card must not be punched or printed. When a read file (single or associated) is closed the last card read will be selected into the output stacker when 2560 "unit exception" has occurred--that is, when there is no following card. Two extra feed cycles are executed to perform this. When a punch or print file (without an associated read file) is closed, LIOCS performs one feed cycle to select the last card into the output stacker. When an associated punch-print file is closed, LIOCS performs one feed cycle to select the last card into the output stacker; if a print PUT was not specified for the last card, LIOCS executes the punch PUT before performing one feed cycle to select the card into the output stacker. When 0 or R have been included in the parameter specified in the DTFCD MODE operand for a 3504, 3505 or 3525 running batched jobs, a non-data card must follow the card which causes your program to close the file. 156 DOS/VS Supervisor & I/O Macros * A card feed us executed only if R has been specified in the DTFCD MODE operand. Programs using read column eliminate mode must detect an end-of-file condition themselves. ** Delimiter cards cannot be punched or printed in these files. CLOSE or CLOSER always issues a feed command. Figure 2-33 CLOSE or CLOSER card movement for the 3525 PART 3 DIRECT ACCESS METHOD Concepts of DAM Declarative Macros DTFDA DAMOD Imperative Macros CLOSE OPENR CLOSER READ CNTRL WAITF LBRET WRITE OPEN CONCEPTS OF DAM With DAM you can process DASD records in random order. You specify the address of the record to IOCS and issue a READ or WRITE macro to transfer the specified record. Variations in the parameters of the READ or WRITE macros permit records to be read, written, updated, or replaced in a file. Whenever DAM is used, the file must be defined by the declarative macro DTFDA (Define The File for Direct Access). The detail entries for this macro are described in the Declarative Macros section later in this chapter. In order to understand the use of some of these entries, however, it is first necessary to indicate how DAM processing uses them. Record Types DASD records that will be processed by DAM can exist on the DASD in either of two formats: with a key area, or without. records mayor may not contain key areas. A WRITE ID or READ ID reads or writes the data portion of the record. However, when KEYLEN is not specified in the DTF for a file, WRITE AFTER cannot be used to extend a file that has keys. IOCS considers all records as unblocked; if you want blocked records, you must perform your own blocking and deblocking. Records are also considered to be either fixed, variable, or undefined length. A spanned record indicates variable blocks where the size of each segment is a function of the track size and record size. The record size is set by a formatting WRITE macro (WRITE AFTER). All the variable record segments of a given spanned record are logically contiguous. The type of records in the file must be specified in the DTFDA RECFORM operand. Whenever records specified as undefined are written, you must determine the length of each record and load it in a register (specified by the DTFDA RECSIZE operand) before issuing the WRITE macro for that record. With key area: IOAREA Specification Without key area: When processing spanned records, this format applies only to the first segment. For additional information on spanned records, see the DOS / VS Data Management Guide, GC33-5372. Whenever records in a file have keys that are to be processed, every record must have a key and all keys must be the same length. When the DTFDA KEYLEN operand is not specified for a file, IOCS ignores keys, and the DASD The DTFDA IOAREA 1 operand defines an area of virtual storage in which records are read on input or built on output. Format The format of the 110 area is determined at assembly time by the following DTFDA operands: AFTER, KEYLEN, READID, WRITEID, READKEY, and WRITEKY. Figure 3-1 describes the types of DTF macros and the II 0 areas that they define. The information in this figure should be used to determine the length of the 110 area specified in the BLKSIZE operand. The 110 area must be large enough to contain the largest record in the file. If the DTF used requires it, the 1/0 area must include room for an 8-byte count field. The count is provided by IOCS. Part 3. Direct Access Method 159 I/O AREA DEFINED DTFDA MACRO ENTRIES AFTER KEYLEN READID WRITEID READKEY WRITKY X X • • • • , COUNT I KEY , COUNT • • D~TA I DATA d Length - I'" I BLKSIZE - n (Bytes) I. 8 I Largest Record IIOAREAl I , )( 0 • 0 • KEY I DATA I I I , L th I . ,BLKSIZE = n----t eng --lKEYLEN=n I (Bytes) I. I Largest Record I IIOAREAl I I 0 I 0 X 0 0 DATA:::! length I - BLKSIZE = n -t I (Bytes) I. largest Record I ! IOAREAl I x - Specified • - May also be specified 0- Of two entries, one ond/or the other is specified Figure 3-1 I/O areas resulting from different DTFDA macro entries for fixed unblocked and undefined record formats Contents Figures 3-1 and 3-2 give a summary of what the contents of 10AREAl are for the various types of DTF macros. These contents are provided by, or to, 10CS when an imperative macro is issued. When you build a record, you must place the contents shown in Figures 3-1 and 3-2 in the appropriate field of the I/O area. The contents that 10CS provides on input are always placed in the appropriate field of the I/O area. For example, if the DTF used for the file resulted in the uppermost format shown in Figure 3-1, the data would be located to the right of the count or key area. Control words DATA r-- 8 bytes- Largest record BLKSIZE=n t IOAREAl Figure 3-2 I/O areas for variable length and spanned unblocked DTFDA record format As oppposed to fixed unblocked and undefined records, the IOAREAl for variable length and spanned unblocked records is independent of the DTFDA macro entries. If you specify the KEYLEN entry of the DTFDA macro, the key is 160 DOS/VS Supervisor & I/O Macros I l l I X I Length -l • I ,BLKSIZE - n----t (Bytes) I. 8 IKEYLEN=n1 Largest Record IIOAREAl I transmitted to or from the field you specified on the KEYARG entry. The count field, if desired, is taken from an area reserved automatically by logicaIIOCS. The control words are built by logical 10CS except for the case when you create your file or add records to it by using the WRITE AFTER macro. You must, in that case, insert the data length of the record (plus four) into the 5th and 6th bytes of the control words. When you read a variable length or spanned unblocked record these bytes will contain the length of the record. When updating records you should not change any parts of the control words. • The maximum length of a logical record plus its key and control words, if any, is shown in Figure 3-3. RECFORM Device FIXUNB VARUNB UNDEF SPNUNB 2311 3625 32767 2314,2319 7294 32767 2321 2000 32767 3330/3333 13,030 32767 3340 8,535 32767 Figure 3-3 Maximum length of DTFDA records including key and control words Reference Methods With DAM, each record that is read or written is specified by providing IOCS with two references: • • Track reference. This gives the track on which the desired record is located. Record reference. This may be either the record key (if the records contain key areas) or the record identifier (ID). IOCS seeks the specified track, searches it for the individual record, and reads or writes the record as indicated by the macro. If a specified record is not found, IOCS sets a no-record-found indication in your error/status byte specified by the DTFDA ERRBYTE operand. This indication can be tested and appropriate action can be taken to suit your requirements. Multiple tracks can be searched for a record specified by key (SRCHM). If a record is not found after an entire cylinder (or the remainder of a cylinder) is searched, an end-of-cylinder bit is turned on instead of the no-record-found bit in ERRBYTE. When an I/O operation is started, control returns immediately to your program. Therefore, when the program is ready to process the input record, or build the succeeding output record for the same file, a test must be made to ensure that the previous transfer of data is complete. Do this by issuing a WAITF macro. After a READ or WRITE macro for a specified record has been executed, IOCS can make the ID of the next record available to your program. The W AITF macro should be issued to assure that the data transfer is complete. You must set up a field (in which IOCS can store the ID) to request that IOCS supply the ID. You must also specify the symbolic address of this field in the DTFDA IDLOC operand. When record reference is by key and multiple tracks are searched, the ID of the specified record (rather than the next record) is supplied. The function of supplying the ID is useful for a random updating operation, or for the processing of successive DASD records. If you are processing consecutively on the basis of the next ID and do not have an end-of-file record, you can check the ID supplied by IOCS against your file limits to determine when the end of the file has been reached. Track Reference To provide IOCS with the track reference, you set up a track reference field in virtual storage, assign a name in the DTFDA SEEKADR operand, and determine by DTFDA operand specifications which type of addressing system to use. Before issuing any READ or WRITE macro for a record, you must store the proper track identifier in either the first seven hexadecimal bytes (mbbcchh), the first three hexadecimal bytes (ttt), or the first eight zoned decimal (tttttttt) bytes of this field. The latter two track references, along with the DSKXTNT and RELTYPE operands, indicate that relative addressing is to be performed. Thus instead of providing the exact physical track location (mbbcchh), only the track number relative to the starting track of the file need be provided. If these operands are omitted, the physical addressing system is assumed. The fields for each of these track reference systems are shown in Figure 3-4. For reference to records by record number, r or rr is used (see Identifier (ID) Reference, below). When the READ or WRITE is executed, IOCS refers to this field to select the specific track on the appropriate DASD. Record Reference DAM allows records to be specified by either record key or record identifier. Key Reference If records contain key areas, the records on a particular track can be randomly searched by their keys. This allows you to refer to records by the logical control information associated with the records, such as an employee number, a part number, a customer number, etc. Part 3. Direct Access Method 161 For this type of reference you must specify the name of a key field in virtual storage in the DTFDA KEYARG operand. You then store each desired key in this field. count areas of the disk records. The r-byte (or bytes) specifies the particular record on the track. Identifier (lD ) Reference Records on a particular track can be randomly searched by their position on the track, rather than by control information (key). To do this, use the record identifier. The physical record identifier, which is part of the count area of the DASD record, consists of five bytes (cchhr). The first four bytes (cylinder and head) refer to the location of the track, and the fifth byte (record) uniquely identifies the particular record on the track. You may, however, use the relative track notation instead of cylinder and head notation if specified in the DSKXTNT and RELTYPE operands. When records are specified by ID, they should be numbered in succession (without missing numbers) on each track. The first data record on a track should be record number 1, the second number 2, etc. Your program can preformat a file or an extension to an existing file in one of two ways depending on the type of processing to be done. If the WRITE AFTER macro is used exclusively, the WRITE RZERD macro is enough for pre formatting the tracks. If nonformatting functions of the WRITE macro are used, the tracks should be preformatted with the IBM -supplied Clear Disk utility program. The Clear Disk utility also resets the capacity record to reflect an empty track. Whenever records are identified by a record ID, the r-byte of the track-reference field (see Figure 3-4) must contain the number of the desired record. When a READ or WRITE macro that searches by ID is executed, IDCS refers to the track-reference field to determine which record is requested by the program. The number in this field is compared with the corresponding fields in the Creating a File or Adding Records In addition to reading, writing, and updating records randomly, DAM permits you to create a file or write new records on a file. When this is done, all three areas of a DASD record are written: the count area, the key area (if present), and the data area. The new record is written after the last record previously written on a specified track. The remainder of the track is erased. This method is specified in a WRITE macro by the parameter AFTER. IDCS ensures that each record fits on the track specified for it. If the record fits, IDCS writes the record. If it does not fit, IDCS sets a no-roomfound indication in your error/status byte specified Decimal Identifier Contents in Zoned Decimal 0-7 tttttttt 0-16,777,215 Track number relative to the first track of the file. 8-9 rr 0-99 Record number relative to the first record on the track. If reference is by key, rr should be zero. Hexadecimal Identifier Contents in Hexadecimal ttt O-FFFFFF Track number relative to the first track of the file. r O-FF Record number relative to the first record on the track. If reference is by key, r should be zero. Bytes Bytes 0-2 3 Figure 3-4 Types of track reference fields (part 1 of 2) 162 DOS/VS Supervisor & I/O Macros Information Information Bytes Physical Identifier 0 m Contents in Hexadecimal OO-FF Information Number of the volume on which the record is located. Volumes and their symbolic units for a file must be numbered consecutively. The first volume number for each file must be zero, but the first symbolic unit may be any SYSnnn number. The system references the volume by adding its number to the first symbolic unit number. Example 1: The first extent statement / / EXTENT SYS005, ... and m=O result in the system referencing SYS005. Example 2: / / VOL SYS005, ... and m=2 results in the system referencing SYS007 (previous job control standard label card). 1-2 bb 0000 (disk) 0000-0009 (2321) For 3221 the first byte is zero. The cell number (0-9) is specified in the second byte. These two bytes are always zero for disk references. 3-4 cc 0000-00C7 (2311,2314,2319) 0000-0193 (3330,3333) 0000-015B (3348 model 35) 0000-02B7 (3348 model 70) 0000-1309 (2321) For disk, the maximum number of the cylinder in which the record can be located is: for 2311, 2314, 2319 : 199 for 3330, 3333 : 403 for 3340 with 3348 model 35 : 347 for 3340 with 3348 model 70: 695 These two bytes (cc), together with the next two (hh), provide the track identification. DAM does not permit the use of different data module sizes in a multivolume file on a 3340. For 2321, the number of sub cell (0-19) is located in the first byte; one of the ten strips (0-9) is located in the second byte. Note: The last four strips on each cell are reserved for alternate tracks. 5-6 hh 7 r 0000-0009 0000-0013 0000-0012 0000-0012 OOOO-OOOB 0000-0413 (2311) (2314) (3330) (3333) (3340) (2321) O-FF For disk, the number of the read/write head that applies to the record. The first byte is always zero and the second byte specifies one of the disk surfaces in a disk pack. For 2321, the first byte specifies one of the five head bar positions (0-4, equivalent to cylinders on disk). The second byte specifies one of the twenty head elements (0-19). Sequential number of the record on the track. Note: r=O if reference is by key. Figure 3-4 Types of track reference fields (part 2 of 2) Part 3. Direct Access Method 163 Data Area by the DTFDA ERRBYTE operand. If WRITE AFTER is specified, lacs also determines (from the capacity record) the location where the record is to be written. PhysicallD of last record written on track (cchhr) N umber of unused bytes remaining on track Whenever the AFTER option is specified, IOCS uses the first record on each track (RO) to maintain updated information about the data records on the track. Record 0 (Figure 3-5) has a count area and a data area, and contains the following: Flag used only for operating systems other than DOS/VS Count Area Each time a WRITE AFTER macro is executed, IOCS updates the data area of this record. Flag (normally not transferred to virtual storage) Physical Identifier Additional Information Key Length (KL) For more information about DAM processing--such as the organization of overflow areas--see the DOS/VS Data Management Guide, GC33-5372. Data Length (DL) COUNT AREA DATA AREA 01 C iR 01 01 0 Identifier ~ ~). c: ·c Identifier of Lost Record DL KL ~!~ '" ·0 !>"GIE afl-o co a:: Bytes - - . 0 5 1 6 7 I I I I 45 0 I I I I I Standard Information Canto i ns --.: :c I I I I I ! Figure 3-5 8 I Contents of record 0 for capacity-record option 164 DOS/VS Supervisor & I/O Macros C H H I Number R: of Unused I Bytes I I I 6 7 DECLARATIVE MACROS DAM files must first be defined by the declarative macros before the imperative macros, described later in this chapter, are used to operate on them. There are two related types of declarative macros-DTFDA and DAMOD. These two macros are described below. DTFDA should not be used to define SYSIPT if the program may be invoked by a catalogued procedure and SYSIPT contains data. In this case, the program must process the data sequentially, and the DTFDI macro should be used. This macro is described in Part 2: Sequential Access Method. DTFDA Macro Enter the symbolic name of the file (filename) in the name field and DTFDA in the operation field. The detail entries follow the DTFDA header card in any order. Figure 3-6 lists the keyword operands contained in the operand field. Applies to = 0.. = 0.. = = 0 ~ ~ I ~ x x M BLKSIZE=nnnn Length of one I/O area, in bytes X X M DEVICE=nnnn (2311, 2314, 2321, 3330, 3340). If omitted, 2311 is assumed X X M ERRBYTE=xxxxxxxx Name of 2-byte field for error/status codes supplied by 10CS X X M IOAREA 1=xxxxxxxx Name of I/O area X X M SEEKADR=xxxxxxxx Name of track-reference field X X M TYPEFLE=xxxxxx (INPUT or OUTPUT) X 0 AFTER=YES WRITE filename, AFTER or WRITE filename, RZERO macro is used for this file X X 0 CONTROL=YES CNTRL macro is used for this file X X 0 DEVADDR=SYSnnn Symbolic unit required only when no extent statement is provided X X 0 ERREXT=YES Nondata transfer errors are to be indicated in ERRBYTE X 0 FEOVD=YES Support for sequential disk end of volume records is desired X 0 HOLD=YES Employ the track hold function 0 DSKXTNT=n Indicates the number (n) of extent for a relative ID X X M=Mandatory; O=Optional Figure 3-6 DTFDA macro (part 1 of 2) Part 3. Direct Access Method 165 Applies to ...= ......= = Q., -= 0 x x 0 IDLOC=xxxxxxxx Name of field in which 10CS stores the ID of a record X X 0 KEY ARG=xxxxxxx Name of key field if READ filename, KEY or WRITE filename, KEY or WRITE filename, AFTER macro is used for this file X X 0 KEYLEN=nnn Number of bytes in record key if keys are to be processed. If omitted, 10CS assumes zero (no key) X X 0 LABADDR=xxxxxxxx Name of your routine to check/write user labels X X 0 MODNAME=xxxxxxx Name of DAMOD logic module for this DTF. If omitted, 10CS generates standard name X X 0 RDONLY=YES Generates a read-only module. Requires a module save area for each task using the module X 0 READID=YES READ filename, ID macro is used for this file X 0 READKEY=YES READ filename, KEY macro is used for this file Q., X X 0 RECFORM=xxxxxx (FlXUNB, SPNUNB, VARUNB, or UNDEF). If omitted, FlXUNB is assumed X X 0 RECSIZE=(nn) Register number if RECFORM=UNDEF X X 0 REL TYPE=xxx (DEC or HEX). Indicates decimal or hexadecimal relative addressing X X 0 SEPASMB= YES DTFDA is to be assembled separately X 0 SRCHM=YES Search multiple tracks, if record reference is by key X 0 TRLBL=YES Process trailer labels, LABADDR must be specified X 0 VERIFY=YES Check disk records after they are written. For DEVICE=2321, YES is assumed X X 0 WRITEID= YES WRITE filename, ID macro is used for this file X X a WRITEKEY = YES WRITE filename, KEY macro is used for this file X X 0 XTNTXIT =xxxxxxxx Name of your routine to process extent information M=Mandatory; O=Optional Figure 3-6 DTFDA macro (part 2 Of 2) 166 DOS/VS Supervisor & I/O Macros AFTER=YES This operand must be included if any records (or an additional record) are written in a file by a formating WRITE (count, key, and data) following the last record previously written on a track. The remainder of the track is erased. That is, whenever the macro WRITE filename,AFTER; or WRITE filename,RZERO; is used in a program, this operand is required. BLKSIZE=n This operand indicates the size of the 110 area by specifying the maximum number of characters that are transferred to or from the area at anyone time. When undefined, variable length or spanned records are read or written, the area must be large enough to accommodate the largest record. For details on how to compute n, see IOAREA Specification. IOCS uses this specification to construct the count field of the CCW for reading or writing records. CONTROL=YES Include this operand if a CNTRL macro is issued for this file. The CNTRL macro for seeking on a disk allows you to specify a track address to which access movement should begin for the next READ or WRITE macro. While the arm is moving, you may process data andlor request 110 operations on other devices. For the 2321, the CNTRL macro enables you to seek to a specific address or to restore the strip to its subcell. DEVADDR=SYSnnn This operand must specify the symbolic unit (SYSnnn) associated with a file if the symbolic unit is not provided via an EXTENT job control statement. If such a unit is provided, its specification overrides the DEVAD DR parameter. This specification, or symbolic unit, represents an actual 1/0 address and is used in the ASSGN job control statement to assign the actual 110 device address to the file. Note: EXTENT job control statements provided for DAM must be supplied in ascending order, and the symbolic units for multi-volume files must be assigned in consecutive order. I DEVICE=12311123141232113330 133401 This operand specifies the device on which the file is located. Specify 2314 for 2319 and 3330 for 3333. If this operand is omitted, 2311 is assumed. Note: DAM does not permit the use of different size data modules (on a 3340) for a multivolume file. I DSKXTNT=n This operand indicates the maximum number of extents (up to 256) that are specified for a file. When RECFORM=FIXUNB, V ARUNB, or UNDEF is specified with this operand, it indicates that a relative ID is used in the SEEKADR and IDLOC locations. If DSKXTNT=n is omitted, a physical ID is assumed in the SEEKADR and IDLOC locations. If RECFORM=SPNUNB is specified, DSKXTNT is required. If relative addressing is used, RELTYPE=DEC or HEX must also be specified. ERRBYTE=name This operand is required for IOCS to supply indications of exceptional conditions to your program. The name of a 2-byte field (in which IOCS ~an store the error-condition or status codes) is entered. The ERRBYTE codes are available for testing by your program after the attempted transfer of a record is complete. You must issue t4e WAITF macro before you interrogate the error s~atus information. After testing the ERRBYTE sta~us code, your program can return to IOCS by issuing another macro. One or more of the error status indication bits may be set to 1 by IOCS as in the bits shown in Figure 3-7. ERREXT=YES This operand enables irrecoverable 110 errors (occurring before a data transfer takes place) to be indicated to your program. This error information is indicated in the bytes named in the ERRBYTE operand and is available after the WAITF macro has been issued. FEOVD=YES This operand is specified if code is generated to handle end-of-volume records. It should be specified only when reading a file which was built using DTFSD and the FEOVD macro. HOLD=YES This operand can be specified only if the track hold function is specified • at system generation time, and Part 3. Direct Access Method 167 • • included in the DAMOD macro, and used when the file is referenced. If the SRCHM operand is used, only the first track IOCS seeks is protected. When a REAP is issued while spanned records are processed, the track containing the first segment is held until you release it. If a formating WRITE macro is issued, DAMOD reads ahead to determine if enough space exists to write the record. All the tracks required to write the record are held and then released, one by one, as they are written. 168 DOS/VS Supervisor & I/O Macros IDLOC=name This operand is included if you want IOCS to supply the ID of a record after each READ or WRITE (lD or KEY) is completed. Specify the name of a record reference field in which IOCS is to store the ID. WAITF should be used before referencing this field. IOCS supplies the ID in the same form as used in the SEEKADR location. The ID forms, given in Figure 3-4, are supplied in IDLOC in the same format except when physical IDs are used. Only the last five bytes of the physical ID (cchhr) are supplied as compared with the complete relative ID which includes leading zeros. Byte Bit Error/Status Code Indication Explanation 0 0 Not applicable Not applicable 0 1 Wrong-length record The wrong-length record indication is applicable to fixed-length, undefined length, variable-length, and spanned records. Fixed-length Records: This bit is set on under the following conditions: · · · · · A READ KEY or WRITE KEY is issued, and the keylength differs from the length as specified by KEYLEN=n. No data is transferred. A READ KEY is issued, and the data length differs form the specified length (BLKSIZE minus KEYLEN, or BLKSIZE minus KEYLEN plus 8 if AFTER=YES was specified). A READ ID is issued, and the length of the record (including key if KEYLEN was specified) differs from the specified length (BLKSIZE, or BLKSIZE minus 8 if AFTER=YES was specified). A WRITE KEY is issued, and the data length of the record is greater than specified in the count field in the DASD record on disk. The original record positions are filled, and the remainder of the updated record is truncated and lost. A WRITE ID is issued, and the record length is greater than specified in the count field in the DASD record on disk. The original record positions are filled, and the remainder of the updated record is truncated and lost. Note: If an updated record is shorter than the original record, it is padded with binary zeros to the length of the original record. The wrong-length record bit is not set on. Undefined-Length Records: This bit is set on under the following conditions: · · · · Figure 3-7 A READ KEY or WRITE KEY is issued, and the keylength differs from the length as specified by KEYLEN=n. No data is transferred. A READ KEY is issued, and the data length is greater than the maximum data size (BLKSIZE minus KEYLEN, or BLKSIZE minus KEYLEN plus 8 if AFTER=YES was specified). IOCS supplies the actual data length of the record read in the RECSIZE register. A READ ID is issued, and the length of the record (including key if KEY LEN was specified) is greater than the maximum record length (BLKSIZE, or BLKSIZE minus 8 if AFTER=YES was specified). IOCS supplies the actual data length of the record read in the RECSIZE register. A WRITE (KEY, ID, or AFTER) is issued, and the data length of the record (loaded into the RECSIZE register) is greater than the maximum d~ta size (BLKSIZE minus KEYLEN, or BLKSIZE minus KEYLEN plvs 8 if AFTER= YES was specified). The length of the record written is equal to the maximum data size. ERRBYTE error status indication bits (part 1 of 4) Part 3. Direct Access Method 169 Byte Bit Error Status Indication Explanation 0 1 Wrong-length record (continued) · A WRITE KEY is issued and the data length (loaded into the RECSIZE register) is greater than specified in the count field of the DASD record on disk. The original record positions are filled, and the remainder of the updated record is truncated and lost. · A WRITE ID is issued, and the record length is greater than specified in the count field of the DASD record on disk. The original record positions are filled, and the remainder of the updated record is truncated and lost. Note: If an updated record is shorter than the original record, it is padded with binary zeros to the length of the original record. The wrong length record bit is not set on. Variable-length records: This bit is set on under the following conditions: · · · When a READ is issued and the LL count 1 is greater than the maximum value specified by the BLKSIZE operand. When a nonformating WRITE is issued and the record is larger than the physical record on the device, the record is written with the loworder bytes truncated. The indicator also is set on if the record is shorter than the physical record, but the low-order bytes of the physical record are padded with binary zeros. When a formating WRITE is issued and the LL count l is greater than the maximum specified block size, the record is written with the low-order bytes truncated. Spanned Records: This bit is set on under the following conditions: · When a READ is issued and the logical record size is larger than the value specified by BLKSIZE minus 8. Only the number of bytes specified is read. · When a nonformating WRITE is issued and the record length is not the same as that of the record being processed. If the length specified is longer than the record being processed, the low-order bytes are ignored. If the length specified is less than the record being processed, it is padded with binary zeros. · If a formating WRITE is issued and the logical record size is larger than the size specifie9 with BLKSIZE minus 8, the record is truncated to the size specifieq;,'< · · If the first physical record encountered is not an only or first segment. The no-record-found ~rdicator ts also set on. i If another first segment is encountered after the first segment is read out before a middle or last segment. 1 The LL count is contained in the first two bytes of the block descriptor and counts the length of the physical block including all control information. For more detail see DOS/VS Data Management Guide, GC 33-5372. Figure 3-7 ERRBYTE error status indication bits (part 2 of 4) 170 DOS/VS Supervisor & I/O Macros Byte Bit Error/Status Code Indication Explanation 0 2 Non-data-transfer error The block in error was neither read or written. If ERREXT is specified and this bit is off, transfer took place and your program should check for other errors in the ERRBYTE field. 0 3 Not applicable Not applicable 0 4 No room found This indication is applicable only when the WRITE AFTER form of the macro is used for a file. The bit is set on if 10CS determines that there is not enough room left on the track to write the record. The record is not written. With spanned records the no-room-found condition is set if not at least one data byte will fit on the specified track in addition to the key, if any, and the 8 byte control field, or if any successive tracks required to transfer the record are not completely empty. 0 5 Not applicable Not applicable 0 6 Not applicable Not applicable 0 7 Reference outside extents The relative address given is outside the extent area of the file. No I/O activity has been started and the remaining bits should be off. If IDLOC is specified, its value is set to 9s for a zoned decimal ID or to Fs for a hexadecimallD. t 0 Data check in count area This is an irrecoverable error. 1 1 Track overrun The number of bytes on the track exceeds the theoretical capacity. 1 2 End of cylinder This indication bit is set on when SRCHM is specified for READ or WRITE KEY and the end-of-cylinder is reached before the record is found. If IDLOC is also specified, certain conditions also turn this bit on (see IDLOC operand). 1 3 Data check when reading key or data This is an irrecoverable error. 1 4 No record found This indication is given when a search ID or key is issued and a record is not found. This applies to both READ commands and WRITE commands and may be caused by: a. The record searched for does not exist in the file. b. The record cannot be found because of a machine error (that is, incorrect seek). For spanned record processing, if the first physical record encountered is not the first or only segment, this indicator is set on. Figure 3-7 ERRBYTE error status indication bits (part 3 of 4) Part 3. Direct Access Method 171 Byte Bit Error/Status Code Indication I 5 End of file This indication is applicable only when the record to be read has a data length of zero. The ID returned in IDLOC, if specified, is hexadecimal FFFF or, in the case of RELTYPE=DEC, zoned decimal 9's. The bit is set only after all the data records have been processed. For example, in a file having n data records (record n+ t is the end-of-file record), the end-of-file indicator is set on when you read the n+ t record. This bit is also posted when an end-of-volume marker is detected. It is your responsibility to determine if this bit means true EOF or end of volume on a SAM file. t 6 End of volume This indication is given in conjunction with the end-of-cylinder indication. This bit is set on if the next record ID (n+ t, 0, t) that is returned on the end of the cylinder is higher than the volume address limit. The volume address limit is: for 23 t t cylinder t 99, head 9 for 23 t 4 or 23 t 9 cylinder t 99, head t 9 for 3340 or 3333 cylinder 403 head t 8 for 3340 with 3348 model 35 cylinder 347, head t t for 3340 with 3348 model 70 cylinder 695, head t t for 232 t subcell 19, strip 5, cylinder 4, head 19 These limits allow for the reserved alternate track area. I Explanation If both the end of cylinder and EOV indicators are set on, the ID returned in IDLOC is FFFF or, in the case of RELTYPE=DEC, zoned decimal 9's. t 7 Figure 3-7 Not applicable Not applicable ERRBYTE error status indication bits (part 4 of 4) HOLD=YES This operand can be specified only if the track hold function is specified • • at system generation time, and included in the DAMOD macro, and used when the file is referenced. If the SRCHM operand is used, only the first track IOCS seeks is protected. When a READ is issued while spanned records are processed, the track containing the first segment is held until you release it. If a formating WRITE macro is issued, DAMOD reads ahead to determine if enough space exists to write the record. All the tracks required to write the record are held and then released, one by one, as they are written. IDLOC=name This operand is included if you want IOCS to supply the ID of a record after each READ or WRITE (ID or KEY) is completed. Specify the name of a record reference field in which IOCS is to store the ID. WAITF should be used before referencing this field. 172 DOS/VS Supervisor & I/O Macros IOCS supplies the ID in the same form as used in the SEEKADR location. The ID forms, given in Figure 3-4, are supplied in IDLOC in the same format except when physical IDs are used. Only the last five bytes of the physical ID (cchhr) are supplied as compared with the complete relative ID which includes leading zeros. IOCS either supplies the ID of the record specified in the READ/WRITE macro, or the ID of the next record location. The following may occur when this option is taken: • Whenever a READ or WRITE ID (or READ or WRITE KEY without SRCHM) is issued, the address returned is that of the next record location. Exception: When the record to be read or written is the last record of the cylinder, an end-ofcylinder indication is posted in ERRBYTE1, bit 2, and the address returned is that of the first record of the next cylinder. If, in addition, the end-of-volume indication is posted, the address returned in IDLOC is all 1 bits. • Whenever a READ or WRITE KEY with SRCHM is specified, the address returned is that of the same record location. Exception: When the record is not found, an end-of -cylinder condition is posted and the information returned is unpredictable. • If a READ or WRITE (ID or KEY) is issued for spanned records, the address returned is that of the first segment of the record whose IDLOC is requested. Figure 3-8 summarizes the IDLOC ID supplied under the various circumstances. ID SUPPLIED (Normal I/O Completion) MACRO With SRCHM Without SRCHM READ filename, KEY Same record Next record READ filename, ID Next record Next record WRITE filename, KEY Same record Next record WRITE filename, ID Next record Next record WRITE filename, RZERO Dummy record Dummy record WRITE filename, AFTER[,EOF] Dummy record Dummy record Figure 3-8 ID supplied after a READ or WRITE macro If IDLOC is specified and end of cylinder is reached on a disk, the cylinder number is increased by 1, the head number is set to 0, and the record number is set to 1. On the 2321, an end-ofcylinder condition with IDLOC specified causes the high-order position of the head number to be increased by 1, the low-order position of the head number to be set to 0, and the record number to be set to 1. An overflow from the high-order position of the head number causes the low-order position of the cylinder number to be increased by 1, and the high-order position of the head number is set to 0. The low-order position of the head number is 0, and the record number is set to 1. Subsequent overflows of address locations increase the next higher positions of the addresses. It is your responsibility to check the validity of the address returned in IDLOC. When using relative addressing with IDLOC specified, all user extents (except the last extent for each file) should end on cylinder boundaries. IOAREAl =name This operand must be included to specify the name of the input/output area used for the file. The input/ output routines transfer records to or from this area. The specified name must be the same as the name used in the DS instruction that reserves this area of storage. The input/output area must be large enough to contain the maximum number of bytes required in any READ or WRITE macro issued for a file in your program. This is affected by the length of record data areas, and by the use of the count and key areas and control information as shown in Figures 3-1 and 3-2 and described under IOAREA Specification. • If undefined records are specified in the DTFDA RECFORM operand, the area must provide space for the largest data record that will be processed. • If variable or spanned records are specified in the DTFDA RECFORM operand, the area must be large enough to contain the largest record in the file, plus an additional eight bytes for control words. You must place the first byte of your record in the ninth byte of the I/O area for all write operations. You must also place the data length plus four in bytes 4 and 5 of the I/O area. When a READ macro is issued, the record length is in bytes 4 and 5 of the I/O area and the first byte of the record is in the ninth byte of the I/O area. If the DTFDA KEYLEN operand is specified and any instructions that read or write the key area of a record are issued in your program, the input/output area (for records other than spanned and variable) must provide room for Part 3. Direct Access Method 173 the key area as well as for the data area. The length needed for the key is the length specified in KEYLEN. • If any write instructions that transfer the count area to a disk record are issued in your program, eight bytes must be allotted at the beginning of the I/O area to enable 10CS to construct the count field which is to be transferred to disk (for records other than spanned and variable). Whenever a WRITE macro is issued, 10CS assumes that the input/output area (see Figures 3-1 or 3-2) contains the information implied by the type of macro that is being executed. KEYARG=name This operand must be included if records are identified by key, that is, if the macro READ filename ,KEY ; or WRITE filename ,KEY ; is used in a program, this entry and the corresponding KEYLEN operand are required. KEYARG specifies the name of the key field in which you supply the record key for the READ/WRITE routines. The KEYARG operand is required for formating WRITE (WRITE filename, AFTER) operations for files containing keys if RECFORM= VARUNB or SPNUNB. It is required also when READ filename, ID; is specified and if KEYLEN is not zero. When record reference is by key, 10CS uses this specification at assembly time to construct the data address field of the CCW for search commands. KEYLEN=n This operand must be included if record reference is by key or if keys are read or written. It specifies the number of bytes in each key. All keys must be the same length. If this operand is omitted, 10CS assumes a key length of zero. If there are keys recorded on DASD and this entry is absent, a WRITE ID or READ ID reads or writes the data portion of the record. When record reference is by key, IOCS uses this specification to construct the count field of the CCW for this file. 10CS also uses this in conjunction with IOAREA1 to determine where the data field in the I/O area is located (see the section IOAREA Specification). LABADDR=name You may require one or more user labels in addition to the standard file label. If so, you must in- 174 DOS/VS Supervisor & I/O Macros clude your own routine to check, or write, the labels. The name of such a routine is specified in this operand. 10CS branches to this routine after it has processed the standard label. See Writing User Standard Labels on Disk and Checking User Standard Labels on Disk in the Label Processing chapter for a discussion of what the LABADDR routine should do. MODNAME = name This operand specifies the name of the logic module that is used with the DTF table to process the file. If the logic module is assembled with the program, MODNAME must specify the same name as the DAMOD macro. If this entry is omitted, standard names are generated for calling the logic module. If two DTF macros call for different functions that can be handled by a single module, only one module is called. RDONLY=YES This operand is specified if the DTF is used with a read-only module. Each time a read-only module is entered, register 13 must contain the address of a 72-byte double word-aligned save area. Each task should have its own uniquely defined save area. Each time an imperative macro (except OPEN, OPENR, or LBRET) is issued, register 13 must contain the address of the save area associated with the task. The fact that the save areas are unique for each task makes the module reentrant, that is, capable of being used concurrently by several tasks. For more information see Shared Modules and Files in the Multitasking Macros chapter. READID=YES This operand must be included if any input records are specified by ID (identifier) in your program, that is, whenever READ filename,ID is used. READKEY = YES This operand must be included if any input records are specified by key in your program, that is, whenever READ filename, KEY is used. RECFORM=IFIXUNB I SPNUNB I UNDEF I VARUNBI This operand specifies the type of records in the input or output file. The specifications are as follows: FIXUNB For fixed-length records. All records are considered unblocked. If you want blocked records, you must provide your own blocking and deblocking. SPNUNB For spanned records. This specification is for unblocked variable-length logical records of less than 32,768 bytes per record. UNDEF For undefined records. This specification is required only if the records are of undefined format. VARUNB For variable-length records. This specification is for unblocked variable-length records. For a definition of record formats see DOS/VS Data Management Guide, GC33-5372. RECSIZE=(r) This operand must be included if undefined records are specified (RECFORM=UNDEF). It specifies the number of the general-purpose register (2-12) that contains the length of each individual input or output record. Whenever an undefined record is read, IOCS supplies the length of the data area for that record in the specified register. When an undefined record is written, you must load the length of the data area of the record (in bytes) into this register, before you issue the WRITE macro for the record. IOCS adds the length of the key when required. When records are written (AFTER specified in the WRITE macro), IOCS uses the length to construct the count area written on DASD. IOCS adds the length of both the count and the key when required. RELTYPE=tDEC I HEX} This operand specifies whether the zoned decimal (DEC) or hexadecimal (HEX) form of the relative ID is to be used. When RECFORM=FIXUNB, VARUNB, or UNDEF, RELTYPE should only be supplied if the DSKXTNT operand (relative ID) is specified. If omitted, a hexadecimal relative ID is assumed. However, if DSKXTNT is also omitted, a physical ID is assumed in the SEEKADR and IDLOC addresses. When RECFORM=SPNUNB, RELTYPE must be specified when relative addressing is used. If RELTYPE is omitted, a physical' ID is assumed in the SEEKADR and IDLOC addresses. SEEKADR = name This operand must be included to specify the name of your track-reference field. In this field, you store the track location of the particular record read or written. The READ, WRITE, and CNTRL routines refer to this field to determine which volume and which track contains the desired record. Whenever records are to be located by searching for a specified ID, the track-reference field must also contain the number of the record on the track. See Figure 3-4 for the types of track reference fields that can be used. SEPASMB=YES Include this operand only if the DTFDA is assembled separately. This causes a CAT ALR card with the filename to be punched ahead of the object deck and defines the filename as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the DTF is being assembled with the problem program and no CATALR card is punched. SRCHM = YES If records are identified by key, this operand may be included to cause IOCS to search mUltiple tracks for each specified record. The macro RE~D filename ,KEY ; or WRITE filename,KEY; searches the track specified in the track-reference field and all following tracks in the cylinder, until the record is found or the end of the cylinder is reached. If the file ends before the end of the cylinder and the record is not found, the search continues into the next file, if any, on the cylinder. EOC, instead of NRF, is indicated. Without SRCHM= YES, each search is confined to the specified track. TRLBL=YES This operand, if specified with the LABADDR operand, indicates that user standard trailer labels are to be read or written following the user standard header labels on the user label track. Both operands must be specified for trailer label processing. For more information on processing labels, see the Label Processing chapter. TYPEFLE=tINPUT I OUTPUT} This operand must be included to indicate how standard volume and file labels are to be processed. INPUT indicates that standard labels are to be read; OUTPUT indicates that standard labels are to be written. For DASD files this entry is always required. Part 3. Direct Access Method 175 VERIFY = YES This operand is included if you want to check the parity of disk records after they are written. If this operand is omitted, any records written on a disk are not verified. VERIFY is always assumed when 2321 records are written. WRITEID=YES This operand must be included if the DASD storage location for writing any output record or updating an input file is specified by a record ID (identifier), that is, whenever the macro WRITE filename,ID is used in the program, this operand is required. WRITEKY = YES This operand must be included if the DASD location for writing any output record or updating an input file is specified by record key, that is, whenever WRITE filename,KEY is used. Bytes Contents 0 Extent type code (as specified in the extent statement) 1 Extent sequence number 2-5 Lower limit of the extent (cchh) 6-9 Upper limit of the extent (cchh) 10-11 Symbolic unit number (in hexadecimal format) 12 Old binary number 13 Present binary number of the extent (B2) Figure 3-9 Label extent information field DAMODMacro XTNTXIT =name This operand is included if you want to process label extent information. It specifies the name of your extent exit routine. During an OPEN, IOCS branches to your routine after each specified extent is checked and validated. Upon entering your routine, IOCS stores in register 1 the address of a 14-byte field that contains the label extent information (in binary form). If user labels are present, the user label track is returned as a separate extent and the lower limit of the first normal extent is increased by one track. The format of this field is shown in Figure 3-9. Return to IOCS by use of the LBRET macro. Registers 2 - 13 are available in the XTNTXIT routine. Within the routine you cannot issue a macro that calls a transient routine (such as OPEN, OPENR, CLOSE, CLOSER, DUMP, PDUMP, CANCEL, CHKPT, etc.). Listed here are the operands you can specify for DAMOD. The first card contains DAMOD in the operation field and may contain a module name in the name field. The parameters are explained here and summarized in Figure 3-10. AFfER =YES This operand generates a logic module that can perform a formating WRITE (count, key, and data). It performs the functions required by WRITE filename,AFTER; and WRITE filename,RZERO. The module also processes any files in which the AFTER operand is not specified in the DTF. HOLD=YES This operand is specified if the track hold function is • specified at system generation time, and included in the DTFDA macro, and • used when the file is referenced. For more information see the DTFDA HOLD operand. ERREXT=YES Include this operand if irrecoverable 110 errors (occurring before a data transfer takes place) are to be indicated to your program in the bytes named in the DTF ERRBYTE operand. 176 DOS/VS Supervisor & I/O Macros FEOVD=YES This operand is specified if coding is to handle endof-volume records. It should be specified only if you are reading a file built using DTFSD and the FEOVD macro. IDLOC=YES This operand generates a logic module that returns record identifier (ID) information to you. The module also processes any files in which the IDLOC operand is not specified in the DTF. RDONLY=YES This operand causes a read-only module to be generated. Whenever this operand is specified, any DTF used with the module must have the same operand. Name Operation Operand [ modname] DAMOD1_'l DAMODV:.! Remarks Must be included. AFTER =YES When WRITE with the operand AFTER or RZERO is used. ERREXT =YES Required if non-data-transfer error conditions are to be indicated in the ERRBYTE status bits. FEOVD=YES Required if support for sequential disk end-ofvolume records is desired. HOLD =YES Required if the track hold function is to be used. IDLOC=YES Required if IDLOC specified in DTFDA. RDONLY=YES Required if a read-only module is to be generated. I RECFORM= rXUNBI UNDEFI VARUNB2 SPNUNB2 RELTRK =YES SEPASMB =YES RELTRK=YES This operand generates a logic module that can process with both physical and relative identifiers. If the operand is omitt~d, the module can process only with physical identifiers. SEPASMB=YES Include this operand only if the module is assembled separately. This causes a CATALR card with the module name (standard or user-specified) to be pun~hed ahead of the object deck and defines the module name as an ENTRY point in the assembly. If the operand is omitted, the program assumes that the module is being assembled with the problem program and no CAT AL~ card is punched. Standard DAMOD Names Each name begins with a 3-character prefix (UI) and continues with a 5-character field corresponding to the options permitted in the generation of the module. DAMOD name = Ulabcde a = F RECFORM=FIXUNB =B RECFORM=UNDEF (handles both UNDEF and FIXUNBJ =S Describes record format. = b V =A RECFORM=SPNUNB RECFORM=VARUNB AFTER= YES = Z AFTER is not specified Required if the module is to process relative identifiers along with physical identifiers. c = E IDLOC=YES and FEOVD=YES =I =R =Z If the module is assembled separately. 1 - DAMOD is for fixed length unblocked and undefined records. 2 - DAMODV is for variable length unblocked and spanned unblocked records. Figure 3-10 fined records. If the operand is omitted or if FIXUNB is specified, the logic module generated can handle only fixed-length unblocked records. If SPNUNB is specified, the module can handle both format V (variable length) and spanned format records. If V AR UNB is specified, the module can handle only format V records. d DAMODmacro RECFORM=IFIXUNB I SPNUNB I UNDEF I VARUNB} If UNDEF is specified, the logic module generated can handle both unblocked fixed-length and unde- =H =P =R IDLOC=YES FEOVD= YES neither is specified ERREXT = YES and REL TRK= YES ERREXT = YES REL TRK= YES = Z neither is specified e = W HOLD=YES and RDONLY=YES =X =Y =Z HOLD=YES RDONLY=YES neither is specified Part 3. Direct Access Method 177 Subset/Superset DAMOD Names The following chart shows the subsetting and supersetting allowed for DAMOD names. Five parameters allow supersetting. For example, the module IJIBAIZZ is a superset of the module with the name IJIFAZZZ. See IOCS Subset/Superset Names in The Macro System chapter. +++++ I ,,} I BAEHX F ZIP Z S + Z Z + + +W V E H Y R R Z Z + Subsetting/supersetting permitted. 178 DOS/VS Supervisor & I/O Macros Notes: 1. The module IJIBAEHW will cause assembly error IPK154 TOO MANY ENTRY SYMBOLS. The valid entry points for this module total more than 100, which is the maximum for assembler language. Specify tess parameters for DAMOD if you can. Otherwise, you must assemble your own module for your program. 2. Your program can have only one DAMOD for fixed unblocked or undefined records and/or only one DAMOD for variable unblocked or spanned unblocked records; otherwise, duplicate name flagging occurs during assembly time. IMPERATIVE MACROS After the DAM files are defined by the declarative macros, the imperative macros can be used to operate on the files. The imperative macros are divided into three groups: those for initialization, processing, and completion. Initialization Macros The initialization macros OPENR or OPEN must be used to activate a DAM file for processing. These macros associate the logical file declared in your program with a specific physical file on a DASD. The association by OPENR or OPEN of your program's logical file with a specific physical file remains in effect throughout your processing of the file until you issue a CLOSE or CLOSER macro. Included here under the category of initialization macros is the LBRET macro, which is connected only with label and extent processing. LBRET is used to return to IOCS from a subroutine of your program which writes or checks labels and extents. OPEN and OPENR Macros Op Operand for self-rcilocating programs OPENR { filename 1 } (d) [ ,{ filename2} ... ,{ filenamen} ] (r2) (rn) for programs that are not self-relocating OPEN { filename 1} (d) [ '{ filename2} ... ,{ filenamen} ] (r2) (rn) The OPENR or OPEN macro activates all files. When OPENR is specified, the symbolic address constants that OPENR generates from the parameter list are self-relocating. When OPEN is specified, the symbolic address constants are not selfrelocating. To write the most efficient code in a multiprogramming environment it is recommended that OPENR be used. Self-relocating programs using LIOCS must use OPENR to activate all files, including console files. In addition to activating files for processing, OPENR relocates all address constants within the DTF tables (zero constants are relocated only when they constitute the module address). If OPEN or OPENR attempts to activate a LIOCS file (DTF) whose device is unassigned, the job is terminated. If the device is assigned IGN, OPEN or OPENR does not activate the file but turns on DTF byte 16, bit 2, to indicate the file is not activated. If DTF byte 16 bit 2 is on after issuing an OPEN or OPENR, input/output operations should not be performed for the file. Enter the symbolic name of the file (DTF filename) in the operand field. A maximum of 16 files may be opened with one OPEN or OPENR by entering the filenames as additional operands. Alternately, you can load the address of the DTF filename into a register and specify the register using ordinary register notation. The high-order 8 bits of this register must be zeros. If symbolic notation is used, you need to establish addressability through a base register. For OPENR, the address of filename may be preloaded into any of the registers 2-15. For OPEN, the address of filename may be preloaded into register 0 or any of the registers 2-15. Note: If you use register notation, we recommend that you follow the standard practice of using only registers 2-12. Whenever an input/output DASD file is opened and you plan to process user-standard labels (UHL only), you must provide the information for checking or building the labels. If this information is obtained from another input file, that file must be opened, if necessary, ahead of the DASD or tape file. To do this, specify the input file ahead of the DASD file in the same OPEN or OPENR or issue a separate OPEN or OPENR preceding the OPEN or OPENR for the file. Part 3. Direct Access Method 179 If an output file is created using DAM, all volumes used must be mounteq at the same time, and all the volumes are opened before the processing is begun. For each volume, OPEN(R) checks the standard VOL1 label and checks the extents specified in the extent cards for the following: in specifying record addresses. Then, the next volume is opened. After all the volumes are open, the file is ready for processing. If the DASD device is file protected, all extents specified in extent cards are available for use. 1. The extents must not overlap. LBRET Macro 2. Only type-1 extents can be used. Name Operation Operand 3. If user standard header labels are created, the first extent must be at least two tracks long. [name] LBRET {l1213} OPEN or OPENR checks all the labels in the VTOC to ensure that the created file does not destroy an existing unexpired file. OPEN or OPENR then creates the standard label(s) for the file and writes the label(s) in the VTOC. If you wish to create your own user labels (UHL) for the file, include the DTF LABADDR operand. OPEN or OPENR reserves the first track of the first extent for these header labels and gives control to your label routine. If the XTNTXIT operand is specified, OPEN or OPENR stores the address of a 14-byte extent information area in register 1. (See Figure 3-9 for the format of this area.) Then, OPEN or OPENR gives control to your extent routine. You can save this information for use in specifying record addresses. After the user labels are written, the next volume is opened. When all the volumes are open, the file is ready for processing. If the DASD device is file protected, all extents specified in extent cards are available for use. Direct access input processing requires that all volumes containing the file be on-line and ready at the same time. All volumes used are opened before any processing can be done. For each volume, OPEN or OPENR checks the standard VOL1labei and then checks the file label(s) in the VTOC. OPEN or OPENR checks some of the information specified in the extent cards for that volume. If LABADDR is specified, OPEN or OPENR makes the user standard header labels available one at a time for checking. If the XTNTXIT operand is specified, OPEN or OPENR stores the address of a 14-byte extent information area in register 1. (See Figure 3-9 for the format of this area.) Control is then given to your extent routine. You can save this information for use 180 DOS/VS Supervisor & I/O Macros The LBRET macro is issued in your subroutines when you have completed processing labels or extents and wish to return control to IOCS. LBRET applies to subroutines that write or check DASD user standard labels or handle extent information. The operand used depends on the function to be performed. See the Label Processing chapter. Checking User Standard DASD Labels: IOCS passes the labels to you one at a time until the maximum allowable number has been read and updated, or until you signify you want no more. In the label routine, use LBRET 3 if you want IOCS to update (rewrite) the label read and pass you the next label. Use LBRET 2 if you simply want IOCS to read and pass you the next label. If an end-of-file record is read when LBRET 2 or LBRET 3 is used, label checking is automatically ended. If you want to eliminate the checking of one or more remaining labels, use LBRET 1. Writing User Standard DASD Labels: Build the labels one at a time and use LBRET'to return to IOCS to write the labels. Use LBRET 2 if you want control returned to you after IOCS writes the label. If, however, IOCS determines that the maximum number of labels are written, label processing is terminated. LBRET 1 is used if you wish to stop writing labels before the maximum number is written. Checking DASD Extents: When using the direct access method, you can process your extent information. After each extent is processed, you should use LBRET 2 to obtain the next extent. Processing Macros Once DAM files have been readied for processing with the initialization macros, the READ, WRITE, W AITF, and CNTRL macros described in this section may be used. READ Macro Name Operation [name] READ Operand { filename (1) HKEY } ID The READ and W AITF macros transfer a record from DASD to an input area in virtual storage. The input area must be specified in the DTFDA IOAREA 1 operand. The READ macro is written in either of two forms depending on the type of reference used to search for the record. Both forms may be used for records in anyone DTFDA-specified file if the file has keys. This macro always requires two parameters. The first parameter specifies the name of the file from which the record is to be retrieved. This name is the same as that specified in the DTFDA header entry for the file and can be specified either as a symbol or in register notation. The second parameter specifies the type of reference used for searching the records in the file. If records are undefined (RECFORM=UNDEF), DAM supplies the data length of each record in the designated register in the DTF RECSIZE operand. Record Reference by Key If the record reference is by key (control information in the key area of the D ASD record), the second parameter in the READ macro must be the word KEY, and the READKEY operand must be specified in the DTFD A. Whenever this method of reference is used, your program must supply the desired record key to IOCS before the READ macro is issued. For this, the key must be stored in the key field (specified in the DTFDA KEYARG operand). When the READ macro is executed, IOCS searches the previously specified track (stored in the 8-byte track-reference field) for the desired key. When a DASD record containing the specified key is found, the data area of the record is transferred to the data portion of the input area. Only the specified track is searched unless you request that multiple tracks be searched on each READ (by including the SRCHM operand in the DTFDA). With this entry, the specified track and all following tracks are searched until the desired record is found or the end of the cylinder is reached. The search of multiple tracks continues through the cylinder even though part of the cylinder may be assigned to a different file. Record Reference by ID If the record reference is by ID (identifier in the count area of records), the second parameter in the READ macro must be the letters ID, and the READID operand must be included in the DTFDA. Whenever this method of reference is used, your program must supply both the track information and the record number in the track-reference field. When the READ macro is executed, IOCS searches the specified track for the particular record. When a record containing the specified ID is found, both the key area (if present and specified in the DTFDA KEYLEN operand) and the data area of the record are transferred to key and data portions of the input area. WRITE Macro Name Operation Operand [name] WRITE { filename} , (1) 1 !KEY ~TER [,EOF] RZERO The KEY, ID, or AFTER forms of the macro transfer an output record from virtual storage to DASD storage. The output area must be specified in the DTFDA IOAREA1 operand, and the WAITF macro must be used. The first parameter specifies the symbolic name of the file to which the record is transferred. This name is the same as the one specified in the DTFDA header entry for the file and can be given either as a symbol or in register notation. The second parameter specifies the type of reference that is used to find the proper location to write the output record. The third parameter is optional and applies only to the WRITE filename,AFTER form of the macro. This form writes an end-of-file record (a record with a length of zero) on a specified track after the last record on a track. Part 3. Direct Access Method 181 WRITE filename,RZERO resets the capacity record of a specified track to its maximum value and erases this track after record zero. If records in the file are undefined (RECFORM= UNDEF), you must determine the length of each record and load it into a register for IOCS use before you issue the WRITE macro for that record. The register for this purpose must be specified in the DTFDA RECSIZE operand. If you are creating variable length or spanned unblocked records with WRITE filename,AFTER you must put the data length of the record to be written plus 4 into the 5th and 6th bytes of the control words preceding the data. In the case that you are updating records previously read by a READ macro from the same physical file you should not change the control words. Otherwise, the wrong length record bit will be set in the error information returned to your program. Record Reference by Key If the DASD location for writing records is determined by the record key (control information in the key area of the DASD record), the word KEY must be entered as the second parameter of the WRITE macro. Also the WRITEKY operand must be included in the DTFDA. Whenever this method of reference is used, your program must supply the key of the desired record to IOCS before the WRITE is issued. The key must be stored in the key field (specified by the DTFDA KEYARG operand). When the WRITE is executed, IOCS searches the previously specified track (stored in the track-reference field) for the desired key. When a DASD record containing the specified key is found, the data in the output area is transferred to the data area of the DASD record. This replaces the information previously recorded in the data area. The DASD count field of the original record controls the writing of the new record. If a record is shorter than the original record, it is padded with zeros. A record longer than the original record is written only to the extent of the area indicated in the count field on the track, and any excess bytes are lost. IOCS turns on the wrong-length-record bit in the errorstatus field if any short or long records occur. Only the specified track is searched unless you request that multiple tracks be searched on each WRITE macro. Searching multiple tracks "is specified by including the SRCHM operand in the DTFDA. In this case, the specified track and all following tracks are searched until the desired record is found or the 182 DOS/VS Supervisor & I/O Macros end of the cylinder is reached. The search of multiple tracks continues through the cylinder even though part of the cylinder may be assigned to a different file. Record Reference by ID If the DASD location for writing records is determined by the record ID (identifier in the count area of records), ID must be entered as the second parameter of the WRITE macro and the WRITEID operand must be included in the DTFDA. Whenever this method of reference is used, your program must supply both the track information and the record number in the track-reference field. When the WRITE is executed, IOCS searches the specified track for the particular record. When the DASD record containing the specified ID is found, the information in the output area is transferred to the key area (if present and specified in DTFDA KEYLEN) and the data area of the DASD rerecord. If RECFORM is FIXUNB or UNDEF the key must precede your data in the IOAREAl, otherwise you must load the key into the key field (specified by the KEY ARG operand) before you issue the WRITE macro. This replaces the key and data previously recorded. IOCS uses the count field of the original record to control the writing of the new record. If a record is shorter than the original record, it is padded with zeros. A record longer than the original record is written only to the extent of the area indicated in the count field on the track, and any excess bytes are lost. IOCS turns on the wrong-Iengthrecord bit in the error/status field if any long records occur. If an updated record is shorter than the original record, it is padded with binary zeros to the length of the original record. The wrong-Iengthrecord bit is set set on. Record Reference by AFTER If a record is written following the last record previously written on a track (regardless of its key or ID), the second parameter of the WRITE macro must be AFTER and the AFTER operand mWit be included in the DTFDA. Whenever this method of reference is used for writing records, your program must supply the track information in the track-reference field. When WRITE is executed, IOCS examines the capacity record (record 0) on the specified track to determine the location and amount of space available for the record. If the remaining space is large enough, the information in the output area is transferred to the track in the location immediately following the last record. The count area, the key area (if present and specified by DTFDA KEYLEN), and the data area are written. IOCS then updates the capacity record. If the space remaining on the track is not large enough for the record, or the track is not followed by enough empty tracks in the case of spanned records, IOCS does not write the record and, instead, sets an indication in your error/status byte specified by the DTFDA ERRBYTE operand. Whenever a new file is built in an area of the disk pack or data cell containing outdated records, the capacity records must first be set up to reflect empty tracks by issuing the WRITE RZERO macro. For the 2311 and 2314, the capacity record will take into account a track tolerance of about 5 0/0, to ensure that minor hardware imprecisions on the disk tracks do not interfere with program execution. If a record is close to the maximum record size for a track, the capacity record could thus show a negative value. Record Reference by RZERO WRITE filename,RZERO resets the capacity record to reflect an empty track. Your program must supply, in SEEKADR, the cylinder and track number of the track to be reinitialized. Any record number is valid but will be ignored. IOCS writes a new RO with the maximum capacity of the track in a two byte field and erases the full track after RO. The maximum track capacities are: for for for for for 2311 2314 or 2319 3330 or 3333 3340 2321 3625 7294 13030 8368 2000 ameter can be specified either as a symbol or in register notation. This macro must be issued before your program attempts to process an input record which has been read or to build another output record for the file concerned. The program does not regain control until the data transfer is complete. Thus, the W AITF macro must be issued after any READ or WRITE macro for a file, and before the succeeding READ or WRITE macro for the same file. The WAITF macro makes error/status information, if any, available to your program in the field specified by the DTFDA ERRBYTE operand. CNTRL Macro Name Operation Operand [name] CNTRL ~filename \' code (1) The CNTRL (control) macro can begin DASD access movement (SEEK) or restore a data cell strip (RESTR) for the next READ or WRITE. It requires two parameters. The first parameter specifies the name of the file, which is the same name as that specified in the DTFDA header entry for the file, and can be specified either as a symbol or in register notation. The second parameter must be the word SEEK (for any DASD) or RESTR (for the 2321 only). The seek address must be provided in the field with the name given in the DTFDA SEEKADR operand before issuing the CNTRL macro. This form of the WRITE macro should be issued every time your program reuses a certain portion of a pack or data module. It may be used as a utility function to initialize a limited number of tracks or cylinders. WAITE Macro Name Operation [name] WAITF Operand ~filename ~ (1) The WAITF macro makes sure that the transfer of a record is complete. It requires only one parameter: the name of the file containing the record. The parPart 3. Direct Access Method 183 Completion Macros CLOSE and CLOSER Macros Op Operand for self-relocating programs CLOSER {fllenamel} (rt) [ , { filename 2} ... ,{ fIIenamen} ] (r2) (rn) for programs that are not self-relocating on input. A file may be closed at any time by issuing this macro. No further commands can be issued for the file unless it is reopened. When CLOSER is specified, the symbolic address constants that CLOSER generates from the parameter list are self-relocating. When CLOSE is specified, the symbolic address constants are not selfrelocating. To write the most efficient code in a multiprogramming environment it is recommended that CLOSER be used. The CLOSER or CLOSE completion macro must be used after the processing of a file is completed. These macros end the association of the logical file declared in your program with a specific physical file on a DASD. Enter the symbolic name of the file (assigned in the DTF header entry) in the operand field. A maximum of 16 files may be closed by one macro by entering additional filename parameters as operands. Alternately, you can load the address of the filename in a register and specify the register using ordinary register notation. The high-order 8 bits of this register must be zeros. For CLOSER, the address of filename may be pre loaded into any of the registers 2-15. For CLOSE, the address of filename may be preloaded into register 0 or any of the registers 2-15. The CLOSER or CLOSE macro deactivates any file which was previously opened. If trailer labels are specified, they are written on output, and checked Note: If you use register notation, we recommend that you follow the standard practice of using only registers 2-12. CLOSE { filename 1} (rt) [ {fllename2} ... ,{ fIIenamen} ] (r2) (rn) 184 DOS/VS Supervisor & I/O Macros PART 4 INDEXED SEQUENTIAL ACCESS METHOD Concepts of ISAM Declarative Macros DTFIS ISMOD Imperative Macros CLOSE CLOSER ENDFL ERET ESETL GET OPEN OPENR PUT READ SETFL SETL WAITF WRITE CONCEPTS OF ISAM With ISAM you can process DASD records in either random or sequential order. For random processing, you supply the key (control information) of the desired record to ISAM and issue a READ or WRITE macro to transfer the specified record. For sequential processing, you specify the first record to be processed and then issue GET or PUT macros until all desired sequential records are processed. The successive records are made available in sequential order by key. Variations in macros permit: Creating a DASD file Reading, adding to, or updating a DASD file Whenever ISAM is used, the file must be defined by the declarative macro DTFIS (Define The File for Indexed Sequential system). The detail entries for this macro are described in the Declarative Macros section later in this chapter. In order to understand the use of some of these entries, however, it is first necessary to indicate how ISAM processing uses them. For processing VSAM files with an ISAM program by means of the ISAM Interface Program (lIP), see Appendix J. Record Types When an ISAM file is originally organized, it is loaded onto the volume(s) from presorted input records. These records must be sorted by key and all records in the file must contain key areas: All keys must be the same length, and this length must be specified in the DTFIS KEYLEN operand. The logical records must be fixed length, and the length must be specified in the DTFIS RECSIZE operand. Logical records may be either blocked or unblocked, and this is specified in the DTFIS RECFORM operand. When blocked records are specified, the key of the highest (last) record in the block is the key for the block and, therefore, ISAM stores it in the key area of the record. The number of records in a block must be specified in the DTFIS NRECDS operand. Storage Areas Records of one logical file are transferred to, or from, one or more I/O areas in virtual storage. The areas must always be large enough to contain the key area and a block of records, or a single record if unblocked records are specified. Also, space must be allowed for the count area when a file is loaded, or when records are added to a file. For the functions of adding or retrieving records, the I/O area must also provide space for a sequence-link field used with overflow records (see Addition of Records and Overflow Areas, below). When an overflow record is brought into the I/O area, you should not alter the sequence-link field. The I/O area requirements are illustrated in Figure 4-1 and described in detail in the discussions of the DTFIS IOAREAL, IOAREAR, IOAREAS, and IOAREA2 operands. Records may be processed directly in the I/O area or in a work area for either random or sequential retrieval. If the records are processed in the I/O area, a register must be specified in the DTFIS IOREG operand. This register is used for indexing, and points to the beginning of each record. If the records are processed in a work area, the DTFIS WORKL, WORKR, or WORKS operand must be specified (WORKL must be specified in any event when creating or adding records to a file). ISAM moves each individual input record from the I/O area to the work area where it is available to your program for processing. Similarly, on output ISAM moves the completed record from the work area to the I/O area where it is available for transfer to DASD storage. Whenever a work area is used, no register is required. Organization of Records on DASD When a logical file of presorted records is loaded ont9 a DASD, ISAM organizes the file in a way that allows you to access any record. For any type Part 4. Indexed Sequential Access Method 187 LOAD Count Length (Bytes) 1 KEYLEN =n ... , I_ - - - - - - - RECSIZE x NRECDS--------'~I 1 ---1 8 /t Data Key 1 I (Minimum size = 10) IOAREAL or IOAREA2 ADD - Unblocked Records Data Count I Length (Bytes) ---l 1 I 8 t I KEYLEN (Unused) ~--------I------------or-------~---~ Key I SL 1 I 1 1 =n i l 0 I Data I 1 11--_ _ _ _ _ _ _ "",I RECS IZE =n ___________--.1.1 NRECDS - 1 I IOAREAL ADD - Blocked Records Key (of last record in the block) Count Data I I Length --1 (Bytes) / KEYLENoon ... II~-------RECSIZE x NRECDS-------------~./ 1 (Minimum size = One record + 10) 1 8 It IOAREAL SEQUENTIAL RETRIEVE - Unblocked Record Data Key (Unused) or SL I I Length - t KEYLEN oon 1 (Bytes) 1 t 10 I Data 1 RECSIZEoon NRECDSoo 1 I· 1 IOAREAS or IOAREA2 RANDOM RETRIEVE - Unblocked Records Length (Bytes) Data I SL I 10 i IOAREAR t : (Unused) Of / / / Data RECSIZE =n NRECDS=I I• I ./ RETRIEVE - Sequential or Random Blocked Records Record 1 SL Length (Bytes) Record 2 I Record 3 Record Length -~I:;...,----------RECSIZE x NRECDS - - - - - - - - - -...1 I (Minimum size = One record + 10) t IOAREAR, IOAREAS, or IOAREA2 SL = Sequence Link Figure 4-1 I/O areas resulting from different DTFIS operands 188 DOS/VS Supervisor & I/O Macros I of processing, the entire ISAM file must be on line. If an ISAM file is assigned ignore by JCL, no proc- essing can be done for that file. Reference can be made to records at random throughout the file, or to a series of records in the file in their presorted sequence. The organization also provides for additions to the file at a later time, while still maintaining both the random and sequential reference capabilities. ISAM loads the records into a specified area of the DASD volume. This area is called the prime area. Both the starting and ending limits of this area are specified by EXTENT job control statements. At least one record must be written at load time if an ISAM file is referenced. Indexes As ISAM loads a file of records sorted by key, it builds a set of indexes for it. The indexes: Highest Key Track Address Key Area Data Area Each entry is a separate record composed of both a key area and a data area. The key area contains the highest key on the track or cylinder, and its length is the same as that specified for logical data records in the DTFIS KEYLEN operand. The data area of each index is ten bytes long; it contains track information including the track address. The indexes are terminated by a dummy entry that contains a key of all one bits. Therefore you should not use a key of all one bits for any of your records. Examples of a track index, cylinder index, and master index are shown in the DOS/VS Data Management Guide, GC33-5372. Track Index • Permit rapid access to individual records for random processing. Supply the records in key order for sequential processing. Either two or three indexes are built: a track index and a cylinder index are always built, and a master index is also built if you specify the DTFIS MSTIND operand. Once a file is loaded and the related indexes are built, the ISAM routines search for specified records by referring to the indexes. When a particular record (specified by key) is requested, ISAM searches the master index (if used), and then the cylinder index, and then the track index, and finally the individual track. Each index narrows the search by pointing to the portion of the next-lower index whose range includes the specified key. Because of the high speed and efficiency of the direct access devices, a master index should be established only for exceptionally large files, for which the cylinder index occupies several tracks (five or more). That is, it is generally faster to search only the cylinder index (followed by the track index) when the cylinder index occupies four or less tracks. The indexes are made up of a series of entries, each of which includes the address of a track and the highest key on that track or cylinder. The track index is the lowest-level index for the logical file. A separate track index is built for each cylinder used, and contains index entries for that cylinder only; each track index is located on the cylinder that it is indexing. It always begins on track zero, and it may extend over more than one track. When the track indexes are originally constructed, they contain two similar entries (normal and overflow) for each track used on the cylinder. The use of two index records for each track is required because of overflow records that occur if more records are inserted in the file at a later time (see Addition of Records and Overflow Areas, below). When overflow records for a track exist, the second (overflow) index record contains the key of the highest record in the overflow chain and the address of the lowest record in the overflow chain for the track. The dummy entry indicates the end of the track index. Any following records are data records. Cylinder Index The cylinder index is an intermediate level index for the logical file. It contains an index entry for each cylinder occupied by the file. This index is built in the location which you specify in an EXTENT job control statement. You may change the upper extent limit; however, no validity check is. performed by the ISMOD and it is therefore your responsibility to make sure the change is correct. Part 4. Indexed Sequential Access Method 189 The cylinder index may not be built on one of the cylinders that contains prime data records. Also, it should not be built on a cylinder that contains overflow records as this could prevent future expansion of the overflow area. The cylinder index should be on a separate cylinder; or it may be on a separate volume that is on-line whenever the logical file is processed. The cylinder index may be located on one or more successive cylinders. Whenever the index is continued from one cylinder to another, the last index entry on the first cylinder contains a linkage field that points to the first track of the next cylinder. A cylinder index may not be continued from one volume to another, however. This index contains one entry for each cylinder occupied by the file. The key area contains the highest key associated with the cylinder, and the data area contains the address of the track index for that cylinder. The dummy entry indicates the end of the cylinder index. References to a cylinder index also apply to the 2321. The bar-position address of the data cell corresponds to the cylinder of a disk drive in ISAM. Master Index The optional master index is the highest-level index for a logical file. This index is built only if it is specified by the DTFIS MSTIND operand. A master index is built in the location specified by an EXTENT job control statement. Like the cylinder index, it may be located on the same volume with , the data records or on a different volume that is on-line whenever the records are processed. The master index must immediately precede the cylinder index on a volume, and it may be located on one or more successive cylinders. Whenever it is continued from one cylinder to another, the last index entry on the first cylinder contains a linkage field that points to the first track of the next cylinder. A master index may not be continued from one volume to another. The master index contains an entry for each track of the cylinder index. The key area contains the highest key on the cylinder index track, and the data area contains the address of that track. The dummy entry indicates the end of the master index. 190 DOS/VS Supervisor & I/O Macros Addition of Records and Overflow Areas After a logical file is organized on a DASD, it may subsequently become necessary to add records. These records may contain keys that are above the highest key presently in the file and thus constitute an extension of the file. Or these records may contain keys that fall between keys already in the file and therefore require insertion in the proper sequence in the file. If all records to be added have keys that are higher than the highest key in the file, the upper limit of the prime area of the file can be adjusted (if necessary) with an EXTENT job control statement. The new records can then be added by presorting them and loading them into the file. No overflow area is required, and the file is merely extended further on the volume. However, new records can be batched with the normal additions and added to the end of the file. However, if records must be inserted among those already in the file, an overflow area is required. ISAM uses the overflow area to permit the insertion of records without necessitating a complete reorganization of the established file. The fast random and sequential retrieval of records is maintained by inserting references to the overflow chains in the track indexes, and by using a chaining technique for the overflow records. For chaining, a sequence-link field is prefixed to your data record in the overflow area. The sequence-link field contains the address of the record in the overflow area that has the next-higher key. Thus a chain of sequential records can be followed when searching for a particular record. The sequence-link field of the highest record in the chain indicates the end of the chain. All records in the overflow area are unblocked, regardless of the specification in the DTFIS RECFORM operand for the data records in the file. An example of the addition of records to an ISAM file using an overflow area is shown in the DOS/VS Data Management Guide, GC33-5372. You may request two types of overflow areas: • A cylinder overflow area for each cylinder. Specify the number of tracks to be reserved for each cylinder overflow area with the DTFIS CYLOFL operand when a file is loaded or when records are added to an existing file. • An independent overflow area for the entire file, specified with an EXTENT job control statement. This area may be on the same volume as the file or on a different (on-line) volume of the same device type. An independent overflow area may be added to a file originally created without it when the DTFIS IOROUT operand specifies LOAD, ADD, or ADDRTR. The independent overflow area may be used in addition to cylinder overflow areas or without them. When used in addition to cylinder overflow areas, it is used whenever one of the cylinder overflow areas is filled. There must always be one prime data track available for a DASD EOF record when additions are made to the last track in the prime data area containing records. For additional information about overflow areas, see the WRITE Macro later in this chapter. complete sets of job control statements for ISAM will also be found there. DOS/VS does not support a null ISAM file. If an attempt is made to access a null file, an X' 10' error indication is placed in the field filenameC (FilenameC is described in the discussion of the DTFIS ERREXT operand, below). ISAM maintains a helpful set of statistics to assist you in determining when reorganization of an ISAM file is required. These statistics are maintained in the Format 2 DASD label recorded with the file; when the file is processed, the statistics occupy fields within the DTFIS table. You can test these fields as you process the file. The fields, and the names by which you reference them, are described below. • Programming Considerations Recordsize=keylength+(blocking factor x record length). The maximum record size possible for ISAM on the various direct access devices is shown below. Device Maximum Record Size (Bytes) 2311 3,605 2314 7,249 2319 7,249 2321 1,984 3330 12,974 3333 12,974 3340 8,293 Formulas to calculate the storage requirements for an ISAM file on the various direct-access devices are given in the DOS/VS Data Management Guide, GC33-5372. When writing ISAM programs, do not forget to include the LBLTYP, DLBL (or DLAB) job control statements. Information about these job control statements will be found in DOS/VS System Control Statements, GC33-5376. Examples of prime record count (filenameP). A four-byte count of the number of records in the prime data area. FilenameP is used for DTFIS ADD, while filenameP+4 is used for DTFIS LOAD. overflow record count (filenameO). A two-byte count of the number of records in the overflow area(s). • available independent overflow tracks (filenameI). A two-byte count of the number of tracks remaining in the independent overflow area, if used. • cylinder overflow areas full (filenameA). A two-byte count of the number of cylinder areas that are full, necessitating use of the independent overflow area. • non-first overflow reference (filenameR). A four-byte count of the number of times a random reference (READ) is made to records that are the second or higher links in an overflow chain. In addition to these fields maintained automatically by ISAM, there is another field--filenameT --which you can use to keep a count of records tagged for deletion. This field is kept in the Format 2 DASD label recorded with the file and is available in the DTFIS table when the file is processed. You may tag the records for deletion by any method you desire, so long as the keys of the records are not changed in such a way that the sequence in the file would be altered. For instance, you could overwrite the data portion of a record with zeros; or a spePart 4. Indexed Sequential Access Method 191 cial field within a record could indicate that the record is deleted. You can keep a count of such records in filenameT. When reorganizing the file, tagged or deleted records can be eliminated. Additional information on reorganizing an ISAM file appears in the DOS/VS Data Management Guide, GC33-5372. Example of an ISAM File Figure 4-2 shows schematically a simplified example of a file organized on a DASD by ISAM. This figure illustrates a file on a 3330, with the last two tracks on each cylinder used for the overflow area. The same file would have similar characteristics if it was created on another DASD type. The assumptions made and the items to be noted are: 1. The track index occupies part of the first track, and prime data records occupy the rest of the track. This is called a shared track. 2. The data records occupy part of track 0 and all of tracks 1-16. Tracks 17 and 18 are used for overflow records in this cylinder. 3. The master index is located on track X on a different cylinder. The cylinder index is located on tracks X + 1 through X + 20. 4. A dummy entry signals the end of each index. 5. The file was originally organized with records as follows: Track 0 1 2 Records 5-75 100-150 16 900-980 6. The track index originally had two similar entries for each track. It now shows that overflow records have occurred for tracks 1 and 16. searched in sequential order by following the SL fields: Record Sequence-Link Field (SL) 130 SL points to record with key 135 135 SL points to record with key 140 140 SL points to record with key 150 150 End of search. (Key 150 was the highest key on track 2 when the file was loaded.) 9. When the file was loaded, the last record on cylinder 1 was record 980; on cylinder 2, record 1850; and on cylinder 9, record 4730. This is reflected in the cylinder index. The first entry in the master index is the last entry of the first track of the cylinder index. 10. When cylinder overflow areas are used, the first record (record 0) in the track index for a cylinder is the Cylinder Overflow Control Record (COCR). It contains the address of the last overflow record on the cylinder and the number of tracks remaining in the cylinder overflow area. When the number of remaining tracks is zero, overflow records are written in the independent area. The format of record zero data field is as follows: hhrbbtxx overflow area. hh - last cylinder overflow track containing the records. r - last overflow record on the track. bb - the number of bytes remaining on the track (for fixed-length records this is binary zeros). 7. Records 150, 140, and 130 were forced off the track by insertions on the track. Record 135 was added directly in the overflow area. 8. A sequence-link field (SL) was prefixed to each overflow record. The records for track 1 can be 192 DOS/VS Supervisor & I/O Macros - the number of remaining tracks available in the cylinder overflow area. xx - reserved (with binary zeros). ~ 1· t TRACK INDEX o 1/751 Dmo o K DATA RECORDS i ~ So ~ ~ if i~. =- =- ~rock ,IOO! Dmo K D 1lOS I ~rock ~ ! • • r~k 210 D 1_-_. ---- - I 1JI Dma K I! a I Dma ___ ~ ___ ~5 ! ~ I'" 1 O Data __ ~ 12~ -- J[ -I I I ISO I SL I • I SL I~ I M 1 I ISO 1 Dma D K Data D I SL I~ I to I 135 I 980 I SL I • Data I Trock X :l K ~ S' 4730 I I Trock I" I X+I 18560 I .......... I I 0 K i SL 135 I to 1 I~ Da." __ 1m Data ___ ~ ~ - ! Data _ _ 2 __ _ l Da~ -- J -----'----=-r Trock I, - X +2 I Add.... I I All. I 1 B,ts I D 0 K Dummy 0 CYUNDER INDEX Trock X+I Q.. •• K en (1j 0 K 0 ! I I Cylinder 10 I 4730 I Trock 0 ! !Add.... ~ c(1j a Trock X+2 [ >- C'l C'l (1j CIl CIl 3: (1j ;. • I Cylinder II 1 I Cylinder 12 I 4800 ITrock 0 14a ITrock 0 I I.......... !Add.... 1 l K 0 K K 0 0 o Q.. ..... \0 !,;.) K D I Cylinder'151 1 1717111 Trock 0 I I IAddr... 1 I I Trock X+20 K=Key ........ D·Dmo ........ SL· s.q.-. LInk ·SL Indlcat. the end of the overflow chain • coca =Cylinder Overflow Control IIecanI (Contal..... In 10) I D D O D MASTER INDEX (1j ~ (1j K 1[- - - - . Trock 18 Q.. ~! ~ DaM OVElFlOW DATA RECORDS T"",k 17 K 'i:j 12~ Data 0 ___________________________ OVEIFLOW DATA RECORDS Pl H - - D D DATA RECORDS ~ ~ 1 Dma K Dmo D DATA RECORDS '< ~ I Trock l I ICylinder 160I AII 1B56101Trock 0 : 1-81tsl I IAdd .... K o K o DECLARATIVE MACROS ISAM files must first be defined by the declarative macros before the imperative macros, described later in this chapter, are used to operate on the files. There are two related types of declarative macros-DTFIS and ISMOD. These two macros are described below. DTFIS Macro Enter the symbolic name of the file (filename) in teh name field and DTFIS in the operation field. The detail entries follow the DTFIS header card in any order. Figure 4-3 lists the keyword operands contained in the operation field. Applies to ~ ..... ~ = ~ ..... ~ 0< "'0 Cd "'0 "'0 ~ 0 Cfl ~ < X X X x M DSKXTNT=n Maximum number of extents specified for this file X X X x M IOROUT=xxxxxx (LOAD, ADD, RETRVE, or ADDR TR X X X X M KEYLEN=nnn Number of bytes in record key (maximum is 255) X X X X M NRECDS=nnn Number of records in a block. Required for blocked records only; if unblocked, 1 is assumed. X X X X M RECFORM=xxxxxx (FIXUNB or FIXBLK) X X X X M RECSIZE=nnnn Number of characters in logical record X X X X 0 CYLOFL=nn Number of tracks for each cylinder overflow area. Maximum = 8 for 2311, 18 for 2314 and 2321, 17 for 3330 and 3333, 10 for 3340 X X X X 0 DEVICE=nnnn (2311,2314,2321,3330,3340). If omitted, 2311 is assumed X X X X 0 ERREXT=YES Non data-transfer error returns and ERET desired X X X X 0 HINDEX=nnnn (2311,2314,2321,3330,3340). Unit containing highest level index. If omitted, 2311 is assumed X X X 0 HOLD=YES Track hold function is desired X X 0 INDAREA=xxxxxxxx Symbolic name of cylinder index area X X a INDSKIP= YES Index skip feature is to be used X X 0 INDSIZE=nnnnn Number of bytes required for the cylinder index area Cd ~ M=Mandatory; O=Optional Figure 4-3 DTFIS macro (part 1 of 2) 194 DOS/VS Supervisor & I/O Macros Applies to "> ... :E = dATA I INDEXl This operand specifies, for the open ACB of a keysequenced file, whether the fields being displayed are for the data or the index. KEYLEN and RKP will contain the same value if the data or the index is being displayed. FS, NCIS, NDELR, NINSR, NIXL, NLOGR, NRETR, NSSS and NUPDR will contain zeros if the index is being displayed. Examples of the SHOWeB Macro The following examples show the use of the :~HOWCB macro to display information from VSAM control blocks. The first example shows the use of SHOWCB to display statistics about an open file: SHOWCB DISPLAY KEY LEN LRECL RKP LTR BNZ ACB=(2),AREA=DISPLAY,LENGTH=12, FIELDS=(KEYLEN,LRECL,RKP) 15,15 (SHOWCB successful?) SHOWERR (No, go to error routine) DC DS DS DS F F F 232 DOS/VS Supervisor OF & I/O Macros (Align on fullword boundary) The second example shows the use of retrieved: LTR BNZ RPL=(4) RPL=(4),AREA=DISPLAY,LENGTH=8, FIELDS=(RECLEN,RBA) 15,15 (SHOWCB successful?) (No go to error routine) SHOWERR DC DC DC OF F F GET SHOWCB DISPLAY LENGTH RBA SHoweB to display the length and REA of a record that has been (Align on fullword boundary) Part 5. Virtual Storage Access Method 233 TESTCB Macro The TESTCB macro tests values in an ACB, EXLST, or RPL against values that you specify in the macro. You examine the condition code after issuing a TESTCB macro and examining the return code in register 15. For keywords specified as an option (such as A for an operand of the EXLST macro), a test is for an equal or unequal comparison; for keywords specified as an address or value, a test is for an equal, unequal, high, low, not-high, or not-low comparison. In the comparison, A to B, B is the address, value, or option that you specify in the TESTCB macro. For example, if you test for a value in an ACB, a high comparison means the value in the block is higher than the value you specified in the TESTCB macro. The standard form of the TESTCB macro is: Name Op Operand [name] TESTCB [{ACB I EXLST I RPL}=addr] [,ERET=addrl ,keyword = {addr I n I option} [,OBJECT={DATA I INDEX} the processing program that it determines. It cannot return to VSAM. keyword=laddr I n I option} ... This operand specifies a field and a value. The contents of the field are compared with the value and the condition code is set. You can specify only one keyword at a time. There are three groups of operands that y~u can code with the TESTCB macro: • The addresses, values, options, and names that you can code with the ACB, EXLST, RPL, and GENCB macros • • The length of a control block or list The attributes of an open file or index indicated by the access-method control block If you code more than one operand, each of them must be compared equal to the corresponding value in the block or list for you to get an equal condition. Operands of the ACB, EXLST, and RPL Macros The operands in this group are identical to those of the ACB, EXLST, and RPL macros, except that: • You can code the operands in more ways, as shown in Appendix H. • In relation to the ACB macro, you can test for return codes from the Open and Close routines (see "Opening and Closing Files") by coding ERROR=code (as any absolute expression, except for a self-defining character term). IACB I EXLST I RPL}=addr This operand specifies whether you want to test an ACB, an EXLST, or an RPL and specifies its address. In relation to the EXLST macro, you can test whether an EXLST has an exit of a certain type by coding keyword=O. In the standard and list forms of TESTCB, you can omit this operand if you are testing only the standard length of a control block or list (see "Length of a Control Block or List" under the keyword operand). With the execute form of TESTCB, you can change the address of the block or list to be tested, but not the type. ERET=addr This operand specifies the address of a user-written routine that VSAM gives control if, because of an error, it is unable to test for the condition you specified (return code in register 15 is not X'OO'). When the ERET routine receives control, it should inspect the return code. If the return code is X'04', an error code will be set in register O. The section "Return Codes for the GENCB, MODCB, SHOWCB, and TESTCB Macros" describes the return codes and error codes which can be set by TESTCB. After completing its processing, the ERET rotine can terminate the job or pass control to a point in 234 DOS/VS Supervisor & I/O Macros In relation to the EXLST macro, you can test whether an address in an EXLST is active or not active or is the address of the name of a routine to be loaded, without specifying the address (keyword=[{A I N}][,L]). • In relation to the RPL macro, you can code the operand FDBK=code (as any absolute expression, except for a self-defining character term) to test for return codes from the request macros. (See Return Codes for the Request Macros under Requesting Access to Files.) You can code the operand RBA=n to test the relative byte address of the last record processed. Length of a Control Block or List You can code the operand EXLLEN=n, ACBLEN=n, or RPLLEN=n to test either the standard length of an EXLST, ACB, or RPL; or the actual length of a particular ACB, RPL, or EXLST. You test for a standard length by omitting the {ACB I EXLST I RPL} operand and coding only one (or more) of these length operands and no other operands. You test the actual length of a block or list by specifying the {ACB I EXLST I RPL} operand and the corresponding length operand. Attributes of an Open FOe or Index After a file is opened, the ACB contains information that it does not contain before it is opened or after it is closed. Whether you are testing for the attributes of the data or the index of a key-sequenced file is determined by the OBJECT operand. You can test whether the file is open by coding: OFLAGS=OPEN. You can test the following fields: Operand AVSPAC Meaning Number of bytes of available space in the data or the index. BUFNO Number of buffers being used for the data or the index. Size of a control interval in the data or CINV the index. Percent of free control intervals in each FS data control area of a key-sequenced file. KEYLEN Full length of the key field in each logical record. Maximum length of a logical record or, LRECL for an index, the index control interval size minus seven bytes. Number of control-interval splits in the NCIS file. NDELR Number of data records deleted from a key-sequenced file. NEXCP Number of EXCP commands issued since the data or the index was opened. Number of logical extents, data spaces NEXT or portions of data spaces, of the data or of the index. NINSR Number of records inserted into the file. NIXL Number of levels in the index of a keysequenced file. NLOGR NRETR NSSS NUPDR RKP STMST Number of data records in the file. Number of data records retrieved from the file. Number of control area splits in a keysequenced file. Number of data records updated in the file. Displacement of the key field from the beginning of a data record; the same value is displayed whether the object is index or data. System time stamp; the time and day (in microseconds) when the data or index was last closed. Bits 52-63 of the fields are unused. You can also test for these attributes: Operand ATRB=ESDS ,KSDS ,WCK ,SSWD ,REPL ,MACRF ,OPTCD Meaning Entry-sequenced file Key-sequenced file VSAM is verifying write operations Sequence set of the index is adjacent to the file Index records are replicated ACB options specified RPL options specified OBJECT=tDATA I INDEXl This operand specifies, for the open ACB of a keysequenced file, whether the field being tested is for the data or the index. KEYLEN and RKP will contain the same value if the data or the index is being tested. FS, NCIS, NDELR, NINSR, NIXL, NLOGR, NRETR, NSSS, and NUPDR will contain zero if the index is being tested. Examples of the TESTCD Macro The examples show how the TESTCB macro is used to test values in a VSAM control block. Part 5. Virtual Storage Access Method 235 In the first example, TESTCB is used to determine whether or not a file is open: TESTCB BE B ACB=(2),OFLAGS=OPEN, ERET=TESTERR OPEN UNOPEN (File open?) (Yes) (No) (Routine executed if TESTCB unsuccessful) TESTERR In the second example, an EODAF exit routine is not supplied and TESTCB is used to determine whether the LERAD exit routine was entered because of an end-of-file condition or a processing error: LOG ERR TESTCB BE B RPL=( 4), FDBK=4, ERET=TESTERR EODATA ERROR Return Codes for the GENeB, MODCB, SHOWCB, and TESTCB Macros When VSAM returns to your processing program after a GENCB, MODCB, SHOWCB, or TESTCB request, register 15 indicates the success or failure of the request. X'OO' means the operation has completed successfully. X'04' means an error was detected; register 0 contains an error code which indicates the type of error: X'02' X'03' X'04' X'05' X'06' X'07' X'08' (YES, go to EOF routine) (No, go to error routine) (Routine executed if TESTCB unsuccessful) TESTERR Error Code X'OI' (End-of-file?) Applicable Macros Meamng G M S T The request you indicated is invalid. G M S T You have not indicated an ACB, RPL, or EXLST. G M S T You have indicated an invalid keyword. M S T The block or list at the indicated address is not the type indicated. S T The ACB is closed - it must be opened. STYou have indicated a nonexistent index in the OBJECT operand There is no entry for the exit MS you have specified in the EXLST. There id not enough virtual G storage in your partitions to generate the requested blocks or lists. 236 DOS/VS Supervisor & I/O Macros X'09' X'OA' X'OB' X'OC' X'OD' X'OE' X'OF' Your work area is too small to generate the requested blocks or lists or to display the requested fields. You did not specify a new GM address for one of your EXLST operands when you specify the L subparameter, or you specified neither an address nor the subparameters A orN. The RPL is active - it must be M inactive. The ACB is open - it must be M closed. There is no EXLST address M indicated in the ACB. GM T You have specified inconsistent parameters. Your work area (WAREA parG S ameter) does not begin on a fullword boundary. G S X'08' in register 15 means that you have tried to use the execute form of a macro to change a nonexistent entry in the parameter list. X'OC' in register 15 means that the request was not executed because an error was encountered while VSAM routines were being loaded. List, Execute, and Generate Forms of the Control Block Macros The list and execute forms of the control block manipulation macros (GENCB, MODCB, SHOWCB, and TESTCB) allow you to save virtual storage by using one parameter list for two or more macros. You can also make your program reentrant; executable by more than one task at a time. The generate form of the macros enables you to make programs reentrant but it does not allow shared parameter lists. List and Execute Forms The list form of GENCB, MODCB, SHOWCB, and TESTCB has the same parameters as the standard form; except that it includes the parameter MF = {L I (L,addr[,labelD}. The parameter list of the macro is created inline when MF=L is coded. This version is not reentrant and register notation cannot be used for macro parameter addresses. When MF = (L,addr[,labelD is coded, the parameter list of the macro is created in the area specified by "addr". This form is reentrant. You must supply the area by a GETVIS macro when your program is executed. You can determine the size of the parameter list by coding the third operand "label". VSAM equates label to the length of the list. The execute form produces the executable code of the macros. The execute form is also identical to the standard form, except that it includes the operand MF = (E,addr), where II addr " points to the parameter list created by the list form of the macro. All of the other operands of the macro are optional and are coded only to change entries in the parameter list before the list is used. However, you cannot use the execute form to add or delete entries from the parameter list or to change the type of list. Generate Fonn The generate form of the macros allows you to make your program reentrant, but it does not create shared parameter lists. The generate form is the same as the standard form, except that you code MF = (G ,addr[,labelD. The parameter list is created in an area pointed to by "addr". To ensure that the parameter list is reentrant, "addr" should be coded in register notation. You must obtain this area by a GETVIS macro when the program is executed. You can determine the size of the parameter list by coding the third operand "label". VSAM equates "label" to the length of the list. Examples of the List, Execute, and Generate Forms The following examples show use of the list, execute, and generate forms of the control block manipulation macros. In the first example, MODCB is used to place the length of a record in the RPL before the record is written. The list and execute forms are used so that only one parameter list is created even though the macro is issued several times. Thos list from is not reentrant. LENMOD bytes) MODCB LTR BNZ PUT MF=(E,LENMOD),RECLEN=(7) 15,15 MODERR RPL=(4) (Current length in reg.7) (MODCB successful?) (No go to error routine) (Yes, write record) MODCB LTR BNZ PUT MF=(E,LENMOD) 15, 15 MOD ERR RPL=(4) (Length is 100 bytes) (MODCB successful?) (No, go to error routine) (Yes, write record) MODCB RPL=(4),RECLEN=100,MF=L (List forms has default length - 100 Part 5. Virtual Storage Access Method 237 In the second example, the generate form is used to create an ACB. It is reentrant because both the ACB itself anf the parameter list of the GENCB macro are created in areas obtained through a GETVIS macro. LA GETVIS LTR BNZ GENCB PASS LTR BNZ LR 10,PARMLEN (Load length for GETVIS) ADDRESS=(8),LENGTH=(10) (Get area for parm. list) 15,15 (GETVIS successful?) VISERR (No, go to error routine) BLK=ACB,MF=(G,(8),PARMLEN, EXLST=(3),BUFND=4,BUFNI=3, BUFSP=11064,DDNAME=VFILENM, MACRF=(KEY,SEQ,DIR,OUT), PASSWD=PASS 15,15 (GENCB successful?) GENERR (No, go to error routine) 2, 1 (Yes, save ACB address) DC FL'6' ,C'CHANGE' 238 DOS/VS Supervisor & I/O Macros OPENING AND CLOSING FILES The OPEN macro connects a processing program to a file, so the program can gain access to data. The CLOSE macro disconnects the program and the file. The TCLOSE macro performs some of the functions of CLOSE but leaves the program and the file connected so processing can continue without reopening the file. OPEN Macro Name Operation Operand [name] OPEN addr[,addr ... ] This operand specifies up to 16 addresses of ACBs and DTFs that specify the files to be opened. A return code is set in register 15 to indicate whether the ACBs were opened or closed successfully. ACBs should be coded together to ensure that the return code will apply to all of them. If, for example, you coded: error code to warn you if the data has been updated separately from its index. Open sets one of the following return codes in register 15. The return code will apply to all ACBs only if they are coded together (see example above): Return Code Meaning X'OO' All ACBs have been opened successfully. X'04' All ACBs opened successfully, but one or more ACBs had a warning message. X'08' One or more ACBs were not opened successfully. The entries with errors are restored to their pre-Open status. If register 15 contains X'04', an error code is set in one or more ACBs to indicate a warning message. All ACBs are open and, unless you prevent it, processing will continue on the file that the message applies to. You can use the ERROR keyword of a SHOWCB or TESTCB macro to examine the code. Error Code X'6C' OPEN ACBl,DTFl,ACB2 the return code will apply to ACB2 only. If ACB2 opened successfully and ACB 1 did not, the return code will still be X'OO'. (The VSAM Open routine sets register 15 to zero when it receives control after a DTF has been opened.) To ensure that the return code applies to both ACBs, the macro should be coded in one of the following ways: OPEN DTFl,ACBl,ACB2 OPEN ACBl,ACB2,DTFI The OPEN macro calls the Open routine, which verifies that the processing program has authority to process the file. Open constructs VSAM control blocks and loads VSAM routines into your partition. (VSAM routines, unlike those of other access methods, are not link-edited with the processing program.) By examining the DLBL statement indicated by the DDNAME operand in the ACB macro and the volume information in the catalog, Open verifies that the necessary volumes have been mounted. If a key-sequenced file is being opened, VSAM issues an X'74' Meaning The system time stamps of the data of a file and its index do not match; this indicates that either the data or the index has been updated separately and data integrity problems may result if the file is processed now. The file was not successfully closed the last time it was processed because (1) an error caused the job to terminate during CLOSE or before the CLOSE macro was issued or (2) the processing program did not issue a CLOSE macro. If records were added, deleted, or updated during previous processing, do not process the file now because of possible data integrity problems. Consult message 4n251 in DOSjVS Messages, GC33-5379. If records were only retrieved, the file will not have data integrity problems and can now be processed as intended. If register 15 contains X'08', an error code is set in one or more ACBs. You use the ERROR keyword of the SHOWCB or TESTCB macro to examine the code. Part 5. Virtual Storage Access Method 239 Error Code X'OO' X'04' X'OE' X'OF' X'II' X'12' X'22' X'24' X'32' X'50' X'6S' X'6E' X'75' X'SO' X'S4' X'SS' X'90' X'94' X'9S' Meaning No error (set when register 15 contains X'OO'). This ACB is already open. The symbolic unit in the DLBL statement is invalid. No job information block (Jms) are available from the supervisor. The address in an ASSGN statement for a VSAM module was set to IGN. The address in an ASSGN statement for a VSAM volume was set to UA. The volume serial numbers specified in the EXTENT statement do not match those specified in the catalog entry. More than 16 EXTENT statements were specified for the file. One or more VSAM processing modules cannot be loaded because the user's virtual partition is too small. 1. Attempt made to mount two volumes on the same unit when direct or keyed processing specified in the ACB. 2. Operator unable to mount required volume. The time stamp of the volume on which the file is stored does not match the system time stamp in the file's catalog entry. The extent information in the catalog entry may not agree with the extent infOrmation in the VTOC. . Attempt made to open an empty file (no records in it) for input only (MACRF=IN in the ACB). The symbolic unit specified in the EXTENT statement is not a valid device type. The DLBL statement is mi~sing or the filename in the DLBL does not match the ACB. A permanent I/O error occurred while VSAM was reading label information from the label information cylinder. Not enough virutual-storage space is available in your partition for work areas, control blocks, or buffers. A permanent I/O error occurred while VSAM was reading or writing a catalog entry. No entry was found in the catalog for this ACB (file not found). Security verification failed; the password specified in the ACB or supplied by the operator for a specific level of access does not match the password in the catalog for that level of access. 240 DOS/VS Supervisor & I/O Macros X' AO' Keyed access was specified in the ACB (ACB macro or GENCB macro) but the file is entry-sequenced. X'Al' User buffers (MACRF=UBF) has been specified with keyed or addressed access; it can only be specified wilh control interval access. X'A4' A permanent I/O error occurred while VSAM was reading the volume label of the volume the file is on. X'AS' The file is not available because it is being ( 1) updated by (under the exclusive control of) another ACB; or (2) exported by access method. X'B4' The VSAM catalog is not connected to the system on logical unit SYSCAT. X'FF' The unexpected error occurred during catalog processing; rerun the job and call your IBM Programming Systems Representative if the problem persists. CLOSE Macro Name Operation Operand [name] CLOSE addr[,addr ... ] This operand specifies up to 16 addresses of A CBs I and DTFs that specify the files to be closed. A return code is set in register 15 to indicate whether the ACBs were closed or closed successfully. ACBs should be coded together to ensure that the return code will apply to all of them. If, for example, you coded: CLOSE ACBl,DTFl,ACB2 the return code will apply to ACB2 only. If ACB2 closed successfully and ACBl did not, the return code will still be X'OO'. (The VSAM Close routine sets register 15 to zero when it receives control after a DTF has been closed.) To ensure that the return code applies to both ACBs, the macro should be coded in one of write the following ways: CLOSE DTFl,ACBl,ACB2 CLOSE ACBl,ACB2,DTFI The Close routine completes any I/O operations that are outstanding when a processing program issues a CLOSE macro for a file. It writes any output buffers that have not been stored. Close updates the catalog entries of the file, including pointers to the end of the file and statistics on file processing (such as number of records inserted). If the file was being loaded and the SPEED option was specified (in the catalog), Close formats the last control area in the file to ensure that the entire file is accessible. Close restores the ACB to the status that it had before the file was opened and frees the virtual storage that Open used to construct VSAM control blocks. Close sets one of the following return codes in register 15. The return code will apply to all ACBs only if they are coded together (see example above): This operand specifies the addresses of up to 16 ACBs. You cannot specify the addresses of DTFs with TCLOSE. A TCLOSE macro completes outstanding 110 operations and updates the catalog. Processing can continue without reopening the file. You use the TCLOSE macro to protect data while the file is being loaded or extended and the SPEED option was specified when the file was defined. When TCLOSE is issued, the Close routine formats the last control area in the file to ensure that all of the data that has been loaded is accessible. TCLOSE sets one of the following return codes in register 15: Error Code Meaning X'OO' All ACBs were closed successfully. X'04 One or more ACBs were not closed successfully. Return Code Meaning X'OO' All ACBs were closed successfully. X'04' One or more ACBs were not closed successfully. If register 15 contains X'04', an error code is set in one or more ACBs. You use the ERROR keyword of the SHOWCB or TESTCB macros to examine the error code. If register 15 contains X'04', an error code is set in one or more ACBs. You use the ERROR keyword of the SHOWCB or TESTCB macros to examine the error code. Error Code X'OO' Error Code X'OO' Meaning No error (set when register 15 contains X'OO'). X'04' The ACB was already closed. X'08' One or more close routines could not be loaded because there was not enough virtual storage space, or the modules could not be found. Processing cannot continue. X'88' Not enough virtual-storage space was available in your partition for a work area for the close routine. X'90' A permanent 110 error occurred while VSAM was reading or writing a catalog entry. X'B8' A permanent 110 error or an internal error in a VSAM routine occurred while VSAM was completing 110 requests. X'BC' The ACB is being used by either a SHOWCB macro or a TESTCB macro. Meaning No error (set when register 15 contains X'OO'). X'04' The ACB was already closed. X'08' One or more close routines could not be loaded because there was not enough virtual storage space, or the modules could not be found. Processing cannot continue. X'88' Not enough virtual-storage space was available in your partition for a work area for the Close routine. X'90' A permanent 110 error occurred while VSAM was reading or writing a catalog entry. X'B8' A permanent 110 error or an internal error in a VSAM routine occurred while VSAM was completing 110 requests. X'BC' The ACB is being used by either a SHOWCB macro or a TESTCB macro. TCLOSE Macro Name Operation Operand [name] TCLOSE addrLaddr... ] Part 5. Virtual Storage Access Method 241 REQUESTING ACCESS TO FILES The macros GET, PUT, POINT, and ERASE initiate all requests for access to data records. AREA parameter points to your work area or to a field in which VSAM will place a record address. When your program issues a request macro, its processing does not continue until VSAM completes the request. At that time, VSAM sets a return code in register 15. If end-of-file is reached or an error or other special condition occurs during the request, VSAM sets a code containing additional information in the feedback field of the RPL, and takes any required exit. The return codes and codes set in the feedback field of the RPL are described later in this section. You can also keep VSAM positioned for subsequent sequential or skip sequential processing when you issue a direct GET request with OPTCD=(DIR,NSP) or OPTCD=(DIR,UPD). With OPTCD=(DIR,UPD) however, positioning is cancelled when you issue a PUT for update or an ERASE following the GET for update. GET Macro Name Operation Operand [name] GET RPL=addr The operand contains the address of the RPL (or first RPL in a chain of them) that specifies the GET request. When you issue a GET macro, register 13 must contain the address of a 72-byte save area that you are providing. This macro retrieves the next record in key sequence with RPL operand OPTCD=(KEY,SEQ), and the next record in entry sequence with OPTCD= (ADR,SEQ). It retrieves the record specified by the key in the searchargument field with OPTCD=(KEY,SKP) or OPTCD=(KEY,DIR), and by the RBA in the search-argument field with OPTCD=(ADR,DIR). With skip sequential retrieval, each key that you specify must be greater in collating sequence than the key of the previous record retrieved. Get retrieves the next control interval with OPTCD=(CNV,SEQ) and the control interval specified by the RBA in the search-argument field with OPTCD=(CNV,DIR). You must issue a GET with OPTCD= UPD to update (PUT with OPTCD=UPD) or to delete (ERASE) a record. You can have the record moved to your work area (OPTCD=MVE) or you can have VSAM leave the record in its 110 buffer and pass you the address of the record (OPTCD=LOC). The 242 DOS/VS Supervisor & I/O Macros PUT Macro Name Operation Operand [name] PUT RPL=addr The operand contains the address of the RPL (or the first RPL in a chain of them) that specifies the PUT request. When you issue a PUT macro, register 13 must contain the address of a 72-byte save area that you are providing. This macro stores a new record in key sequence with OPTCD=(KEY,SKP,NUP), OPTCD=(KEY,DIR,NUP), OPTCD=(KEY,SEQ,NUP), or OPTCD=(KEY,DIR,NSP). When OPTCD=(KEY,DIR,NSP), VSAM is kept positioned at the next record in key sequence for subsequent sequential processing. PUT stores a new record at the end of an entrysequenced file with OPTCD=ADR (you cannot store a new record in a key-sequenced file with addressed access). With skip sequential storage, OPTCD=(KEY,SKP), the key of each record that you store must be greater in collating sequence than the key of the previous record stored. With controlinterval access, OPTCD=(CNV,NUP), PUT stores a new control interval at the end of an entrysequenced file. When loading or extending a file with the PUT macro, you must specify sequential or skip sequential processing (OPTCD=SEQ or OPTCD=SKP). To store a changed record or control interval, you must have previously retrieved it with OPTCD= UPD and also specify OPTCD= UPD when you issue a PUT. You cannot change the key of a record in a key-sequenced file. With OPTCD=ADR, you cannot change the length of a record in either a key-sequenced or an entry.sequenced file. The record to be added or updated with a PUT macro must be in your work area (OPTCD=MVE); you cannot use OPTCD=LOC with the PUT macro. The AREA parameter of the ACB points to your work area. register 13 must contain the address of a 72-byte save area that you are providing. This macro deletes the record previously retrieved for update (with the GET macro, OPTCD= UPD) . You can delete records in a key-sequenced file by keyed or addressed access, but you cannot delete records in an entry-sequenced file. You cannot delete control intervals (OPTCD=CNV). ENDREQ Macro POINT Macro Name Operation Operand [name] POINT RPL=addr The operand contains the address of the RPL (or the first RPL in a chain of them) that specifies the POINT request. When you issue a POINT macro, register 13 must contain the address of a 72-byte save area that you are providing. This macro positions VSAM at the record whose key (with OPTCD=KEY) you specify in the search-argument field. It can be used to position either forward or backward in the file for subsequent sequential or skip sequential processing. POINT positions VSAM at the record or control interval whose RBA (with OPTCD=ADR or OPTCD=CNV) you specify in the search-argument field. It can be used to position either forward or backward in the file for subsequent sequential processing. VSAM can also be positioned for sequential processing by either a direct GET or a direct PUT as described in the preceeding sections on the GET and PUT macros. ERASE Macro Name Operation Operand [name] ENDREQ RPL=addr The operand contains the address of the RPL (or first RPL in a chain of them) that specifies the request to be terminated. When you issue an ENDREQ macro, register 13 must contain the address of a 72-byte save area that you are providing. This macro caused VSAM to end a request. If an 110 operation was started, it will be allowed to complete. Also, 110 operations required to maintain the integrity of the file will be performed. If the request involves a chain of RPLs, all records specified by the request may not be processed. For example, two RPLs are chained in a PUT request to add two new records to the file and an ENDREQ is issued after VSAM started the 110 to add the first record. That 110 operation will be completed and, if it causes a control-interval split, subsequent 1/0 operations will be performed to complete the split and update the index. However, VSAM will then return control to the processing program without adding the second record. The ENDREQ macro also causes VSAM to cancel the position in the file established for that request. Return Codes for the Request Macros Name Operation Operand [name] ERASE RPL=addr The operand contains the address of the RPL (or the first RPL in a chain of them) that specifies the ERASE request. When you issue an ERASE macro, When VSAM returns to your processing program, a return code in register 15 indicates what happened. If an error occurred, additional information on the request will be in the RPL. Your processing program can examine the feedback field of the RPL with the FDBK keyword of the SHOWCB or TESTCB macro: register 1 contains the address of the RPL that defines the request that caused the error. Part 5. Virtual Storage Access Method 243 Control is returned to the instruction following your action macro when (1) the request is completed, (2) the request was not accepted because another request was using the RPL, or (3) an error occurred and you did not have an active exit routine. If you do have an active exit routine and it returns control to VSAM after processing the error, VSAM then returns control to the instruction following the action macro. Return Error Code Code X'OO' Request completed successfully. X'OO' Request completed successfully; no additional information. X'04' Request completed successfully; end-of-volume calling during request. When you gain control after a request, register 15 will contain one of the following return codes: X'04' Request not accepted; a request from another task is active on this RPL. X'OO' X'08' Logical error. X'04' End-of-file encountered, EODAD exit routine entered if one supplied. X'08' Duplicate record. X'OC' Record out sequence (record might be a duplicate). X'10' No record found. X'14' Record already held in exclusive control by another requester. X'18' Record is on a volume which is not mounted. X' 1C' All extents of file are full and VSAM cannot sub-allocate new extents because there is no available data spa~e on (1) a volume which already contains extents of the file or (2) a volume that is candidate for extension of the file. X'20' Invalid RBA specified. X'24' The key of the record to be inserted does not fall in an existing key range in the file. X'28' Insufficient virtual storage available to finish request. X'2C' The work area you have supplied (AREA parameter) is not large enough. X'30' One or more VSAM processing modules cannot be loaded because the user's virtual partition is not large enough. X'34' An internal error occurred in a VSAM routine. Save the program listing, console log, and dump, and contact your IBM Programming Support Representative. Request completed successully; the RPL might contain additional (non-error) information about the request. X'04' This request was not accepted because a request from another task is active on the same RPL; no additional information in the RPL. X'08' Logical error; the error code in the RPL identifies the specific error. X'OC' Uncorrectable I/O error; the error code in the RPL identifies the specific error. If the request completed with a logical error (X'08'), your LERAD exit routine is entered if you specified the LERAD exit in the EXLST and it is active. When you reach end-of-file, error code X'04' is set. Your EODAD exit routine will be entered. If you have no EODAD exit routine or it is inactive, your LERAD exit routine is entered. If the request completed with an I/O (physical) er- ror (X'OC'), your SYNAD exit routine is entered if you specified the SYNAD exit in the EXLST and it is active. The return code is not set in register 15 when the exit routine is entered. VSAM sets the return code in register 15 and returns control to the instruction following the action macro after you complete the exit routine. The feedback field in the RPL (FDBK parameter in SHOWCB and TESTCB) is a fullword with the following format: OOOOOOxx where xx is an error code which describes the error or, if the return code is zero, additional information about the request. 244 DOS/VS Supervisor & I/O Macros Return Error Code Code X'08' X'38' The VSAM catalog was accessed during processing of a request. An I/O error or an internal processing error occurred during catalog access. Use the LISTCAT command of Access Method Services to examine the catalog entry for this cluster. You can then attempt to rerun the job if the catalog entry is valid. It t~~J'erun is not successful, save the program listing, console log, LISTCAT listing, and dump and contact your IBM Programming Support Representative. X'40' As many requests are active as the number specified in the STRNO operand of the ACB; therefore, another request cannot be started. X'44' Type of accessing for the request not in ACB when file was opened: • Keyed access not specified • Output not specified • CNV processing not specified X'48' Keyed access requested for an entry-sequenced file. X'4C' Addressed or control-interval insertion requested for a key-sequenced file. X'50' ERASE macro specified for an entry-sequenced file or for controlinterval processing. X'54' Locate mode specified for PUT macro or for user buffer processing. X'58' VSAM not positioned (POINT) for sequential GET or you changed to keyed access after establishing position by addressed access. X'5C' X'60' X'64' X'68' X'6C' X'70' X'74' PUT update or ERASE issued without a preceding GET update. Attempt to change key when updating record. Attempt to change record length during update with addressed access. Invalid or conflicting RPL options. Record length specified that is larger than allowed maximum, equal or zero, or smaller than key length plus relative key position. Length of generic key is too large or equal to zero. Request other than sequential or skip sequential PUT to insert records specified during loading of the file. X'OC' Physical (I/O) Errors X'04' I/O error while reading data. X'08' I/O error while reading index set of index. X'OC' I/O error while reading sequence set of index. X'lO' 110 error while writing data. X'14' I/O error while writing index set of index. X'18' I/O error while writing sequence set of index. Part 5. Virtual Storage Access Method 245 PART 6 PHYSICAL IOCS Concepts of Physical IOCS Physical IOCS Macros CCB CLOSE CLOSER DTFPH EXCP FEOV LBRET OPEN OPENR SEOV WAIT CONCEPTS OF PHYSICAL IOCS Records can be transferred to or from an input/ output device by issuing physical IOCS macros. These macros relate directly to the physical IOCS routines and are distinct from the logical IOCS macros described in the SAM, DAM, ISAM, and VSAM chapters of this book. For more information on the distinction between physical and logical IOCS see the DOS/VS Data Management Guide, GC33-5372. When using physical IOCS macros, you must provide for such functions as the blocking or deblocking of records, performing programmed wronglength record checks, testing the CCB for certain errors, switching I/O areas when two areas are used, and setting up CCWs. You must also recognize and bypass checkpoint records if they are interspersed with data records on an input tape. netic tape labels are processed, or when D ASD file protect is present. The DTFPH, OPEN or OPENR, CLOSE or CLOSER, LBRET, FEOV, and SEOV macros can be used in this processing. The OPEN and the DTFPH macros are also necessary when a disk is used for a checkpoint file. PIOCS considerations for alternate tape switching and bypassing embedded checkpoint records on tape are given in the DOS/VS Data Management Guide, GC335372. The CCB, EXCP, and WAIT macros used for direct communication with PIOCS; the PIOCS DTFPH declarative macro; and the OPEN or OPENR, LBRET, FEOV, SEOV, and CLOSE or CLOSER imperative macros used with PIOCS, are described in the remainder of this chapter. Physical IOCS routines control the transfer of data to or from the external device. These routines perform the following: Physical IOCS Macros • • • • CCB Macro Starting I/O operations I/O interrupt handling Channel scheduling Device error handling Thus physical IOCS macros provide you with the capability of obtaining data and performing nondata operations with I/O devices using exactly the CCWs you request. For example, if your program handles only physical records, you do not need the logical IOCS routines for blocking and deblocking logical records. Three macros are available for direct communication with physical IOCS: CCB (command control block), EXCP (execute channel program), and WAIT. Whenever physical IOCS macros are used, you must construct the CCWs for input/output operations. Use the assembler instruction CCW statement to do this. A detailed technical description of the CCW can be found in IBM System/370 Principles of Operation, GA22-7000. Considerations for CCW programming are given in the DOS/VS Data Management Guide, GC335372. Macros normally used with files processed by logical IOCS are necessary in addition to the macros provided by PIOCS when standard DASD or mag- Name Op Operand blockname CCB SYSnnn,command-list-name [,X'nnnn'][,sense address] A CCB (command control block) macro must be specified in your program for each I/O device controlled by physical IOCS macros. The first 16 bytes of all the generated DTF tables--except DTFOR and DTFSR (optical reader)--contain the CCB. For DTFOR and DTFSR (optical reader), the CCB begins at filename +24 which includes the DTFPH. The CCB (see Figure 6-1) is necessary to communicate information to physical IOCS so that it can perform desired operations (for example, notifying your program of printer channel 9). The CCB also receives status information after an operation and makes this available to your program. blockname: The CCB macro must be given a symbolic name (blockname). This name can be used as the operand in the EXCP and WAIT macros which refer to the CCB. SYSnnn: This operand specifies the symbolic unit Part 6. PhysicallDCS 249 for the actual I/O unit with which this CCB is associated. A list of symbolic units applying to eCB can be found in the Symbolic Unit Addresse~ ~ection of The Macro System chapter. The actual I/O;unit can be assigned to the symbolic unit by ah ASSG N job control statement. command-list-name: This operand speCifies, the symbolic name of the first CCW used with CCB. This name must be the same as the name specified in the assembler CCW statement that constructs the CCW. Bytes Contents 0-1 After a record is transferred, 10CS places the residual count from the CSW in these two bytes. By subtracting the residual count from the original count in the CCW, your program can determine the length of the record that was transferred. This residual count is set to zero for negative values. 2-3 These next two bytes are for transmission of information between physical 10CS and your program. Your program can test any bit in bytes 2 and 3, using the mask given in the last column of Figure 6-2. More than one bit can be tested by the hexadecimal sum of the test values. a X'nnnn': A hexadecimal value used to set the CCB user option bits. Column 5 of Figure 6-2 gives the value used to set a user option bit on. It more than one bit must be set, the sum of the values is psed. For example, to set user option bits 3, 5, and 6 of byte 2 on, X'1600' is used. All bits are set to 0 when your program is assembled unless the X'nnnn' operand is specified. If this operand is specified, it is assembled into these two bytes. You may turn on bits 5 and 7 in byte 3 and bits 3 through 7 in byte 2. During execution, each bit may be set to 1 by your program or by a condition detected by physical 10CS. Any bits that can be turned on by physical 10CS during program execution are reset to zero by Ploes the next time an EXCP macro using the same CCB is executed. Figure 6-2 shows the condition indicated by the setting of each bit. ( (X'1600'=X'1000' + X'0400' + X'0200') The macro can set any of the bits iIi bytes 2 or 3 on. Normally, however, you need not be concerned with setting the remaining bits on. sense address: This operand, when, suppiied, indicates user error recovery (see Figure 6=-2 byte 2, bit 7) and generates a CCW for reading sense i~forma tion as the last field of the CCB. THe name field (sense address) of the area that you supply must have a length attribute assigned of at Jeast one byte. Physical 10CS uses this length attribute in the CCW to determine the number of bytes of sense information you desire. If the user has his own user error routine (byte 2, bit 7 of the CCB is on, or X'nnnn' in the CCll macro = X'0100') but has not specified the parameter 'sense address' in the CCB macro, the sense information is cleared by the supervisor in order to prevent deadlocks in the control unit. If the user then issues an EXCP with the CCW address for SENSE from the error routine, the information has already been destroyed. CCB Format From the above specifications, the macro sets up a 16-byte or 24-byte field (Figure 6-1) as follows: 250 DOS/VS Supervisor & I/O Macros 4-5 These two bytes are the status bytes of the CSW. If device-end posting is requested (byte 2, bit 5), device end status is ORed in. Byte 4 is set to X'OO' at EXCP time. Note: For nonteleprocessing devices, a program-controlled interruption (PCI) is ignored by the channel scheduler. 6 This byte indicates the type of CCB. 7 This byte is a hexadecimal representation of the symbolic unit for the I/O devices, as specified in the first operand of this CCB. 8-11 These four bytes contain the address of the CCW (or first address of a chain of CCWs) associated with this CCB and specified symbolically in the second operand. 12 You must not modify this byte. i Byt.. ~ u..d for - , :.. Reserved for Physical IOCS 12 Count .. • • Transml~lng _------_--_- Byte 6 Byte 7 I Between Physical 8its 8its X'Ou' Original CC8 I Hexacleci~1 IOCS and I I X'2u' Translated CC8 I Representation I Problem ... \0 Attentian I 0 Pragram-cantrolled I X' 411' 8TAM request original CC8 I rI SYSnnn I For details II Status madifier interruptian I X'6u' 8TAM request translated CCB I SYSRDR .. 00 I see 12 Cantrol unit end I 1 Incorrect length I X' Su' User-translated CC8 in virtual I SYSIPT • 01 3 Busy 2 PragrCJm check I partition I SYSPCH .. 02 Figure 6-2 14 Channel end 3 Protectioncheck I Note: Anyonefitheaboveincremented!SYSLST .. 03 5 Device end 4 Channel data check 1-- by X' 10' (bit 3 on) indicates I SYSLOG • 04 16 Utit check 5 Channel control check I automatic sWitching ta the I SYSLNK • 05 17 Utit exception 6 Interface control check I beginning rI the next cylinder I SYSRES • 06 7 Chaining check I at End rI Cylinder condition. I SYSSL8 • 07 I I Information ~ragrc ~ I ~ I r I I ---- - Byte 5 _ --.... I I I u: 0" the addr_ in byte 7 refers to a System logical Utit 1 • the addr_ in byte 7 refers to a Pragrammer Lagical Utit R !! I SYSRL8 I SYSYSE I SYSREC I SYSCL8 I SYSVIS I SYSCAT I SYSOOO I SYSOOI : SY~2 ISY~ "'tI ~ ?' ~ (l' e- o n rJl N va 08 09 OA 08 OC 00 00 01 02 ~. IX' SO' -eC8 being lused by ERP I IX' 40' -Channel I~ IR~'o;- Pr_t Ix 20 _ Sense hnformation IDesired I '10'-Message X IWriter I IX'OB' _ EU Tape I Error IX'04' OLTEP I I~ IAvallable IX'02' _ Tape ERP IRead Opposite IRecovery IX'OI' _ Seek ISeparation I (Nate 2) I I I I I Not. 1. Bytes 4 and 5 c8ntain the status bytes rI the Channel Status Word (Bits 32-47). If byte 2, bit 5 is on and device end results as a separate interrupt, device end will be OReel into CC8 byte 4. Nat. 2. SYSmax-255- (number rI partitions. 14). .. • • .. • .. • • .. IBuffer Offset: I Virtual or real I IlIfMIt Tapes I addrea fI CCW ASCII IX' 00' -X' 63' I _iated with I I this CC8 cIepen_ IASCII Output I ding an byte 6: ITapes Fixed I Real addr_ X'OO' I if byte IVariable: X'OO' or I X'2u', X' 6u', I X'04' I or X'SU'; I , , I Yirtualaddrea Utdefined: X 00 I If byte 6 • I X'Ou', or I X' 411' I 13 CCW Addrea -~~I--' in CWi s-. ccw I 15 1~ _ _ _ _ ~ Virtual addrea I 8 Bytes fI CCW painted I Appended ta the to the CWi at I CC8 when Sen.. Chann.1 End; I Information is (if byte 6· • Desired X'Su', it is the real addrea) or addrea rIthe Channel End AppeoIdage Routine Condition Indicated Bit Byte o (OFF) 1 (ON) 2 0 Traffic Bit (WAIT) I/O Completed. Normally set at Channel End. Set at Device End if bit 5 is on. 1 End of Fi Ie on System Input. /* Mask for Test Under Mask Instruction X'80' I/O requested and not completed. or /& on SVSRDR or SVSIPT. Byte 4, Unit exception Bit is also on. Ves No I/O error passed back due to program option or operator option. No program or operator option error was passed back. Return to user after physical 10CS attempts to correct I/o error. 2 Operator Option: Dependent on the Error X' 1000' X'10' Operator Options: Ignore, Retry, or Cancel. Ignore or Cancel. Return to user. Operator Option: Retry or Cancel. Cancel. X'OSOO' X'08' 51 Post at Device End. Device End condition is posted; that is, byte 2, bit 0 and byte 3, bits 2 and 6 set at Device End. Also byte 4, bit 5 is set. Device End conditions are not posted. Traffic bit is set at Channel End. X'Q400' X'04' 6 1 Retum: L1ncorrectable tape read data check (2400-series, 3420, or 2495); 1018, 2560 data check; 2520 or 2540 punch equipment check;2560 or 5425 equipment check; 3504, 3505, or 3525 permanent errors; DASD read or read verify data check;3211 passbaek requested. (Data checks on count not retumed 7 1 User Error Routine Retum to user: ofter physical 10CS attempts to correct 3211, tape, or DASD error; when 1018 or 2560 data check; when 2560 or 5425 equipment check; when 3504, 3505, or 3525 permanent error (byte 3, bit 3 is also on). Operator Option: Ignore or Concel for tapes, paper tape punch (1018), card punches other than 2560 and 5425. Retry or Cancel for DASD, 2560, or 5425. X'0200' X'02' User handles error recovery. 3 A physical IOCS error routine is used unless the CCB sense address operand is specified. The latter requires user error recovery. X'OI00' X'OI' 0 Data check in DASD count Field. Ves-Byte 3, bit 3 is off; Byte 2, bit 2 is on. Ves Ves Ves No 1 DASD Trae k overrun. 1017 broken tape. Keyboard correction 1287 in Journal Tape Mode. 3211 print qual ity error (equipment check) MICR intervention required. Ves Ves Ves No No No Ves No Ves No 2 End of DASD Cylinder. Hopper Empty 1287/1288 Document Mode. MICR - 1255/1259/1270/1275/1419, disengage. - 1275/14190, I/O error in extemal interrupt routine. 3211 line position error. 5 Ves Ves No No Document feeding stapped. No Chonnel data check or 8usout check. Yes No 3211 UCSB Parity Check (line complete) 2 Irrecoverable I/O Error 1 3 Accept Irrecoverable I/O Error (Bit 2 is ON) 4 1 2671 data check. 1017/1018 data checks. Retrun any DASD data c hec ks . 3 On Values for Third Operand in CCB Macro Data check - 1287 or 1288. MICR - SCU not operational. 3211 Print Check (equipment check). Figure 6-2 Conditions indicated by CCB bytes 2 and 3 (part 1 of 2) 252 DOS/VS Supervisor & I/O Macros X'4O' X'20' X' 80' No No No X' 40' X' 20' Condition Indicated Byte Bit o (OFF) 1 (ON) 3 3 Tape read data check (2400-series or 2495); 2520 or 2540 punch equipment check; any DASD data check. 1017, 1018, 2560 data check. 1287, 1288 equipment check. 2560, 5425 equipment check. 3504, 3505, 3525 permanent errors. 3211 data check (print check). Operation was unsuccessful. Byte 2, bit 2 is also on. Byte 3, bit 0 is off. Ves Ves Byte 2, bit 6 is also on. Byte 2, bit 6 is also on. Ves 4 Questionable Condition. Card: Unusual command sequence (2540). DASD: No record found. 1287/1288: Document jam or tom tape. Ves Nonrecovery UCSB parity check (command retry). Test Ulder -Mask Instruction X'10' No No No No No X'08' Ves Retry command if no record found condition occurs (disk). Set the questionable condition bit on and return to user. 6 Verify error for DASD or Carriage Channel 9 overflow Ves. (Set on when Channel 9 is reached only if Byte 2, bit 5 is on). Ves Ves No No No Retry begins at last CCW executed. Retry begins at first CCW or channel program. 7 1 Command Chain Retry IMask for for Third Operand in CCB Macro No 51 No record found condition 1287 document mode-late stacker select. 1288 End-of-Page (EOP). IOn Values X'OOO4' X'04' X'02' X'OOOI' X'OI' 1 User Option Bits. Set in CCB macro. Physical 10CS sets the other bits off at EXCP time and on when the condition specified accurs. 2 I/O program check, command reject. or tape equipment check always terminates the program. 3 Vou may handle Channel Control Checks and Interface Control Checks. The accurrence of a channel data check, unit check, or chaining check causes a byte 2, bit X' 20' of the CCB to turn on, and completion posting and dequeuing to accur. I/O program and protection checks always cause program termination. Incorrect length and unit exception are treated as normal conditions (posted with completion). Also, you must request device end posting (CCB byte 2, bit X'04') in order to obtain errors after channel end. 4 Error correction feature for 1018 is not supported by physical IOCS. When a 1018 data check occurs and CCB byte 2, bit X'02' is on, control returns directly to you with CCB byte 3, bit X' 10' turned on. 5 A line position error can accur as a result of an equipment check, data check, or FCB parity check. Figure 6-2 Conditions indicated by CCB bytes 2 and 3 (part 2 of 2) Bytes Contents 13-15 These bytes contain the virtual address of the CCW pointed to by the CSW at channel-end interrupt for this 1/0 operation. 16-23 EXCPMacro Name Operation Operand [name] EXCP rloCkname[,REAL] ~ (1) Note: Bytes 13-15 contain the address of the channel appendage routine when X'40' is set in byte 12. The EXCP (execute channel program) macro requests physical IOCS to start an inputI output operation for a particular 110 device. These bytes are allotted only when the sense address operand is supplied in the CCB macro. They contain the CCW for returning sense information to your program. Physical IOCS determines the device from the CCB specified by blockname, and places the CCB in a queue of such CCBs for this device. If the channel and device are available, the channel program is started and program control is returned to your program. 110 interruptions are used to process 1/0 Part 6. Physical IOCS 253 completion and to start I/O for requests if the channel or device was busy at EXCP time. blockname is the virtual address of the CCB established for the device. It can be given as a symbol or in register notation. indicates that the addresses in the CCWs and the address in the CCB pointing to the first CCW have already been translated into real addresses. The system's CCW translation routine will be skipped. The CCB, the channel program, and the I/O areas must be PFIXed prior to issuing EXCP ... ,REAL. REAL Note: For a program running in real mode, the parameter REAL is ignored. If the supervisor is generated without the option ECPREAL= YES in the FOPT supervisor generation macro, and REAL is specified, the issuing task is canceled. WAIT Mac,.o Name Operation [name] WAIT Operand ~blockname ~ I' name as that specified in the EXCP macro for the device. DTFPH Mac,.o When physical IOCS macros (EXCP, WAIT, etc.) are used in a program, DASD, diskette, or tape files with standard labels need to be defined by DTFPH entries (DTF for a file handled by physical IOCS). DTFPH must also be used for a checkpoint file on a disk; the following operands can be specified: Operand Optional CCWADDR=name X DEYADDR=SYSnnn X DEYICE=231l, 2314, 3330, 3340,3540 LABADDR=name Required X X MOUNTED=SINGLE X TYPEFLE=OUTPUT X Enter the symbolic name of the file (filename) in the name field and DTFPH in the operation field. The detail entries follow the DTFPH header card in any order. Figure 6-3 lists the keyword operands contained in the operand field. (1) This macro is issued whenever your program requires that an I/O operation (started by an EXCP macro) be completed before execution of the program continues. For example, transferring data (a physical record) to virtual storage must be completed before data can be added or moved to another area of virtual storage, or otherwise processed. When WAIT is executed in a batched job environment, processing is suspended until the traffic bit (byte 2, bit 0) of the related CCB is turned on. Then, processing automatically continues and the data can be processed. In a multiprogramming environment, the supervisor gives control to another program until the traffic bit is set on. The blockname (specified as a symbol or in register notation) of the CCB established for the I/O device is the only operand required. This is also the same 254 DOS/VS Supervisor & I/O Macros ASCII = YES This operand is required to process ASCII tape files. If this operand is omitted, EBCDIC processing is assumed. CCWADDR = name This operand allows you to use the CCB generated within the first 16 bytes of the DTFPH table. CCWADDR specifies the symbolic name of the first CCW used with the CCB generated within the DTFPH macro. This name must be the same as the name specified in the assembler CCW statement that constructs the CCW. If this operand is omitted, the location counter value of the CCB-CCW table address constant is substituted for the CCW address. -M TYPFLE=xxxxxx (INPUT or OUTPUT). Specifies type of file. 0 ASCII=YES ASCII file processing is required. 0 CCWADDR=xxxxxxxx If CCB is generated by DTFPH is to be used. 0 DEVICE=xxxx (TAPE, 2311, 2314, 2321,3330,3340, 3540). If omitted, T APE is assumed. 0 DEVADDR=SYSxxx Symbolic unit required only when not provided on an EXTENT statement. 0 HDRINFO= YES Print header label information. 0 LABADDR=xxxxxxxx Routine to check or built user standard labels. 0 MOUNTED = xxxxxx (ALL or SINGLE). Required for DASD files only; for diskette files, specify SINGLE. 0 XTNTXIT =xxxxxxxx If EXTENT statements are to be processed. DASD only. M=Mandatory; O=Optional Figure 6-3 DTFPHmacro DEVICE={TAPE 12311123141232113330 13340 1 35401 If the file is contained on DASD or diskette, enter the proper identification. Specify 2314 for 2319 and 3330 for 3333. TAPE applies to any 2400/3400series tape unit, and is the only valid entry in this operand for ASCII files. DEVADDR=SYSxxx This operand must specify the symbolic unit (SYSxxx) associated with the file if a symbolic unit is not provided via an EXTENT job control statement. If a symbolic unit is provided, its specification overrides a DEVADDR specification. This specification, or symbolic unit, represents an actual I/O address, and is used in the ASSGN job control statement to assign the actual I/O device address to this file. For a list of symbolic units applying to DTFPH, see Symbolic Unit Addresses in The Macro System chapter. The only symbolic unit in that section that is not applicable is SYSLOG. If SYSLST or SYSPCH are used as output tape units and alternate tape switching is desired upon detecting a reflective spot, the SEOV macro must be used (see SEOV Macro). When processing ASCn tape files, the only valid specification is a programmer logical unit (that is, SYSnnn). HDRINFO =YES This operand causes IOCS to print standard header label information (fields 3-10) on SYSLOG each time a file with standard labels is opened. Likewise, the filename, symbolic unit, and device address are printed each time an end-of-volume condition is detected. If HDRINFO= YES is omitted, no header or end-of-volume information is printed. LABADDR=name You may require one or more DASD or tape labels in addition to the standard file labels. If so, you must include your own routine to check (on input) or build (on output) your label(s). Specify the symbolic name of your routine in this operand. IOCS branches to this routine after the standard label is processed. LABADDR may be included to specify a routine for your header or trailer labels as follows: • DASD input or output: header labels only. • Tape input or output: header and trailer labels. Thus, if LABADDR is specified, your header labels can be processed for an input/ output DASD or tape file, and your trailer labels can be built for a tape Part 6. PhysicallOCS 255 output file. Physical 10CS reads input labels and makes them available to you for checking, and writes output labels after they are built. This is similar to the functions performed by logical 10CS. For a complete discussion of the LABADDR routine, see the Label Processing chapter. If physical 10CS macros are used for a tape file, an OPEN must be issued for the new volume. This causes 10CS to check the HDR11abel and provides for your checking of user standard labels, if any. When physical 10CS macros are used and DTFPH is specified for standard tape label processing, FEOV must not be issued for an input file. MOUNTED={ALL I SINGLEJ This operand must be included to specify how many extents (areas) of the file are available for processing when the file is initially opened. This operand must not be specified for tape. ALL is specified if all extents are available for processing. When a file is opened, 10CS checks all labels on each disk pack and makes available all extents specified by your control statements. Only one OPEN or OPENR is required for the file. ALL should be specified whenever you plan to process records in a manner similar to the direct access method. In any case, you must supply a LBLTYP statement. After an OPEN or OPENR is performed, you must be aware that the symbolic unit address of the first volume containing the file is in bytes 30 and 31 of the DTFPH table rather than in the CCB. Before executing any EXCPs you must place the symbolic address in bytes 6 and 7 of the CCB. SINGLE is specified if only the first extent on the first volume is available for processing. SINGLE should be specified when you plan to process records in sequential order. 10CS checks the labels on the first pack and makes the first extent specified by your control cards available for processing. You must keep track of the extents and issue a subsequent OPEN or OPENR whenever another extent is required for processing. You will find the information in the DTFPH table helpful in keeping track of the extents. The DTFPH table contains: 256 DOS/VS Supervisor & I/O Macros Bytes Contents 0-15 CCB (symbolic unit has been initialized in the CCB). 54-57 Extent upper limits (cchh). 58-59 Seek address (bb-bin or cell number). For a one-celled device such as disk it must be zero. 60-63 Extent lower limit (cchh). On each OPEN or OPENR after the first, 10CS makes available the next extent specified by the control cards. When you issue a CLOSE or OPENR for an output file, the volume on which you are currently writing records is indicated, in the file label, as the last volume for the file. TYPEFLE={INPUT I OUTPUTJ This operand must be included to specify the type of file: input or output. XTNTXIT = name This entry is included if you want to process label extent information. It specifies the symbolic name of your extent routine. The DTFPH MOUNTED = ALL operand must also be specified for the file. Whenever XTNTXIT is included, 10CS branches to your routine during the initial OPEN for the file. It branches after each specified extent is completely checked and after conflicts, if any, have been resolved. Upon entry to your routine, 10CS stores the address (in register 1) of a 14-byte area from which you can retrieve label extent information (in binary form). This area contains: Bytes To write the most efficient code in a multiprogramming environment it is recommended that OPENR be used. Contents Extent type code: 0 00 Next three fields do not indicate any extent. 01 The extent containing your data record. 02 Overflow area of an indexed sequential file. 04 Cylinder index or master index of an indexed sequential file. 40 User label track area. 80 Shared cylinder indicator. 1 Extent sequence number. 2-5 Lower limit of the extent (cchh). 6-9 Upper limit of the extent (cchh). 10-11 Symbolic unit (see Figure 6-1). 12 Old bin (cell) number. For a one-celled device such as disk, byte 12 contains zero. 13 Present bin number of the extent (b2). If OPEN or OPENR attempts to activate a logical IOCS file (DTF) whose device is unassigned, the job is terminated. If the device is assigned IGN, OPEN or OPENR does not activate the file and turns DTF byte 16, bit 2 on, to indicate the file is not activated. Return to IOCS by using the LBRET macro. OPEN and OPENR Op Self-relocating programs using LIOCS must use OPENR to activate all files, including console files. In addition to activating files for processing, OPENR relocates all address constants within the DTF tables (zero constants are relocated only when they constitute the module address). If symbolic notation is used, you must establish addressability through a base register. Macros Operand Enter the symbolic name of the file (DTF filename) in the operand field. A maximum of 16 files may be opened with one OPEN or OPENR by entering the filenames as additional operands. Alternately, you can load the address of the DTF filename into a register and specify the register using ordinary register notation. The high-order 8 bits of this register must contain zeros. For OPENR, the address of filename may be preloaded into any of the registers 2-15. For OPEN, the address of filename may be preloaded into register 0 or any of the registers 2-15. for self-relocating programs OPENR ~ filename 1 ~ (d) [, 1fIlename 2 ! ... , lfIlenamen! ] (r2) (rn) for programs that are not self-relocating OP~l:i ~ filename 1 ~ (d) [- 1fIlename 2 f ... ,1 fIlenamen f ] (r2) (rn) The OPENR or QPEN macro activates files processed with the DTFPH macro. These macros associ~ ate the logical file declared in your program with a specific physical file on a DASD. The association by OPENR or OPEN of your program's logical file with a specific physical file remains in effect throughout your processing of the file until you issue a CLOSE or CLOSER macro. When OPENR is specified, the symbolic address constants generated from the parameter list are selfrelocating. When OPEN is specified, the symbolic address constants are not self-relocating. Note: If you use register notation, we recommend that you follow the standard practice of using only registers 2-12. Whenever an input/output DASD or magnetic tape file is opened and you plan to process user-standard labels (UHL or UTL), or nonstandard tape labels, you must provide the information for checking or building the labels. If this information is obtained from another input file, that file must be opened, ahead of the DASD or tape file. Do this by specifying the input file ahead of the tape or DASD file in the same OPEN or OPENR, or by issuing a separate OPEN or OPENR preceding the OPEN or OPENR for the file. If an output tape (specified to contain standard la- bels) is opened and does not contain a volume label, a message is issued to the operator. He can then enter a volume serial number allowing the volume label to be written on the output tape. Single Volume Mounted--Output When processing output files with physical IOCS, OPEN or OPENR is used only if you want to build Part 6. Physical IOCS 257 standard labels. When the first OPEN or OPENR for the volume is issued, OPEN or OPENR checks the standard VOL 1 label and the extents specified in the EXTENT job control statements for the mounted volume: 1. The extents must not overlap each other. 2. If user standard header labels are written, the first extent must be at least two tracks long. 3. Only type 1 and type 8 extents are valid. OPEN or OPENR checks all the labels in the VTOC to ensure that the file to be created does not destroy an existing file whose expiration date is still pending. After this check, OPEN or OPENR creates the standard label(s) for the file and writes the label(s) in the VTOC. If you wish to create your own user standard header labels (UHL) for the file, you must include the LABADDR operand in the DTF. OPEN or OPENR reserves the first track of the first extent for these labels and gives control to your label routine. After this, the first extent of the file can be used. Each time you determine that all processing for an extent is completed, issue another OPEN or OPENR for the file to make the next extent available. When the last extent on the last volume of the file is processed, OPEN or OPENR issues a message. The system operator has the option of canceling the job, or typing in an extent on the printer-keyboard and continuing the job. If the system provides DASD file protection, only the extents opened for the mounted volume are available to you. Single Volume Mounted-- Input When processing input files with physical IOCS, OPEN or OPENR is used only if you want to check standard labels. When the mounted volume is opened for the first time, OPEN or OPENR checks the extents specified in the extent cards (for example, checks that the extent limit address for the device being opened is valid). OPEN or OPENR also checks the standard VOL1 label and then checks the file label(s) in the VTOC. If the system provides DASD file protection, only the extents opened for the mounted volume are available for use. If LABADDR is specified, OPEN or OPENR makes the user standard header labels (UHL) available to you one at a time for checking. Then, OPEN or OPENR makes the first extent available for processing. 258 DOS/VS Supervisor & I/O Macros Each time you determine that all processing for an extent is completed, issue another OPEN or OPENR for the file to make the next extent available. If another extent is not available, OPEN or OPENR stores the character F (for EOF) in byte 31 of the DTFPH table. You can determine the end of file by addressing and checking the byte at filename+30. All Volumes Mounted--Output If all output volumes are mounted when creating an output file with physical IOCS, each volume is opened before the file is processed. OPEN or OPENR is used only if standard labels are checked or written. For each volume, OPEN or OPENR checks the standard VOL1label and checks the extents specified in the EXTENT job control statements: 1. The extents must not overlap each other. 2. Only type-1 extents can be used. 3. If user standard header labels are created, the first extent must be at least two tracks long. 4. For 3340, all data modules must be of the same type. OPEN or OPENR checks all the labels in the VTOC to ensure that the created file does not destroy an existing file with an expiration date still pending. After this check, OPEN or OPENR creates the standard label(s) for the file and writes the label(s) in the VTOC. If you wish to create your own user standard header labels for the file, include the LABADDR operand in the DTF. OPEN or OPENR reserves the first track of the first extent for these labels and gives control to your label routine. If the XTNTXIT operand is specified, OPEN or OPENR stores the address of a 14-byte extent information area in register 1. (See the DTFPH XTNTXIT operand, above, for the format of this area.) Then, OPEN or OPENR gives control to your extent routine. You can save this information for later use in specifying record addresses. If your DASD file is file protected, you cannot write on any extents while in the XTNTXIT routine. When checking is complete, return control to OPEN or OPENR by issuing the LBRET 2 macro which opens the next volume. After all volumes are opened, the file is ready for processing. All Volumes Mounted--Input When all volumes containing the input file are online and ready at the same time, each volume is opened one at a time before any processing is done. OPEN(R) is used only when standard labels are to be processed. For each volume, OPEN(R) checks the extents specified in the EXTENT job control statements, and checks the standard VOL 1 label on track 0 and the file label(s) in the VTOC. If LABADDR is specified in the DTF, OPEN or OPENR makes the user standard labels available, one at a time, for checking. If XTNTXIT is specified in the DTF, OPEN or OPENR stores the address of a 14-byte extent information area into register 1. (See the DTFPH XTNTXIT operand, above, for the format of this area.) Then OPEN(R) gives control to your extent routine. For example, you can save this area and use the information later on for specifying record addresses. If the DASD file is file protected, you cannot write on any extents while in the XTNTXIT routine. Diskette Volumes--Output When processing output files on diskettes with physical IOCS, OPEN or OPENR is used to build standard labels. When OPEN or OPENR is issued for the first volume, it checks the VTOC on the diskette, and • ensures that the file to be created does not have the same name as an existing unexpired file, • ensures there is at least one track available to be allocated, and allocates space for the file, starting at the track following the last unexpired or write-protected file on the diskette. After this check, OPEN or OPENR creates the format-l label for the file and writes the label in the VTOC. Each time you determine that all processing for an extent is complete, you must feed to make the next diskette available and then issue another OPEN or OPENR for the file, to make the next extent available. CLOSE or CLOSER will automatically cause the last volume to be fed out. If the last extent of the file is completely processed before a CLOSE(R) is issued, OPEN or OPENR assumes an error condition and the job is canceled. Diskette Volumes--Input When processing input files on diskettes with physical IOCS, OPEN or OPENR is used to check stand- ard labels. When the first volume is opened, OPEN or OPENR checks the VTOC on the diskette and determines the extent limits of the file from the file label. After the label is checked, OPEN or OPENR makes the first extent available for processing. Each time you determine that all processing for a diskette is complete, you must feed to make the next diskette available, and then issue another OPEN or OPENR for the file, to make the next extent available. If another extent is not available, OPEN or OPENR stores the character F (for EOF) in byte 31 of the DTFPH table. You can determine the end of file by addressing and checking the byte at filename + 30. For a programmer logical unit, the last diskette will. always be fed out; for a system logical unit, the last diskette will not be fed out. LBRET Macro Name Operation Operand [name] LBRET {11213} The LBRET macro is issued in your subroutines when processing is completed and you wish to return control to IOCS. LBRET applies to subroutines that write or check DASD or magnetic tape user standard labels, write or check tape nonstandard labels, or check DASD extents. The operand used depends on the function to be performed (see the Label Processing chapter). Checking User Standard DASD Labels: IOCS passes labels to you one at a time until the maximum allowable number is read and updated, or until you signify you want no more. Use LBRET 3 in your label routine if you want IOCS to update (rewrite) the label read and pass you the next label. Use LBRET 2 if you want IOCS to read and pass you the next label. If an end-of-file record is read when LBRET 2 or LBRET 3 is used, label checking is automatically ended. If you want to eliminate the checking of one or more remaining labels, use LBRET 1. Writing User Standard DASD Labels: Build the labels one at a time and use LBRET to return to IOCS to write the labels. Use LBRET 2 if you wish to regain control after IOCS writes the label. If, however, lacs determines that the maximum number of Part 6. Physical IOCS 259 labels has been written, label processing is terminated. Use LBRET 1 to stop writing labels before the maximum number is written. The name of the file is the only parameter required. The name can be specified either as a symbol or in register notation. Checking DASD Extents: When processing an input file with all volumes mounted, you can process your extent information. After each extent is processed, use LBRET 2 to receive the next extent. When extent processing is complete, use LBRET 1 to return control to IOCS. When physical IOCS macros are used and DTFPH is specified for standard label processing, FEOV may be issued for output files only. In this case, FEOV writes a tapemark, the standard trailer label, and any user-standard trailer labels if DTFPH LABADDR is specified. When the new volume is mounted and ready for writing, IOCS writes the standard header label and user-standard header labels, if any. Checking User Standard Tape Labels: IOCS reads and passes the labels to you one at a time until a tapemark is read, or until you signify you want no more labels. Use LBRET 2 if you want to process the next label. If IOCS reads a tapemark, label processing is automatically terminated. Use LBRET 1 if you want to bypass any remaining labels. Writing User Standard Tape Labels: Build the labels one at a time and return to IOCS, which writes the labels. You are responsible for accumulating the block count, if desired, and supplying it to IOCS for inclusion in the standard trailer label; for this, the count (in binary form) must be moved to the 4-byte field named filenameB. When LBRET 2 is used, IOCS returns control to you (at the address specified in LABADDR) after writing the label. LBRET 1 must be used to terminate the label set. Writing or Checking Nonstandard Tape Labels: You must process all your nonstandard labels at once. LBRET 2 is used after all label processing is completed and you want to return control to IOCS. For an example see Appendix C. SEOV Macro Name Operation Operand [name] SEOV filename The SEOV (system end-of-volume) macro must only be used with physical IOCS to automatically switch volumes if SYSLST or SYSPCH are assigned to a tape output file. SEOV writes a tapemark, rewinds, unloads the file, and checks for an alternate tape. If none is found, a message is issued to the operator who can mount a new tape on the same drive and continue. If an alternate unit is assigned, the macro fetches the alternate switching routine to promote the alternate unit, opens the new tape, and makes it ready for processing. When using this macro, you must check for the end-of-volume condition in the CCB. (;.LOSE and CLOSER Macros Op FEOV Macro _ ~ Operand for self-relocating programs "f Name Operation [name] FEOV Operand CLOSER )filename~ ) (1) ~ filename I f (rl) [, {filename2~ ... , {filenamen~J (r2) (rn) for programs that are not self-relocating The FEOV (forced end-of-volume) macro is used for files on magnetic tape (programmer logical units only) to force an end-of-volume condition before sensing a reflective marker. This indicates that processing of records on one volume is considered finished, but that more records for the same logical file are to be read from, or written on, the following volume. For system units, see SEOV Macro, below. 260 DOS/VS Supervisor & I/O Macros CLOSE {filename I ~ (rl) f ... , f] [, {filename2 {filenamen (r2) (rn) The CLOSE or CLOSER macro is used to deactivate any file that was previously opened. Console files, however, cannot be closed. These macros end the association of the logical file declared in your program with a specific physical file on an 110 device. A file may be closed at any time by issuing this macro. No further commands can be issued for the iile'iiiiless it is opened. When CLOSER is specified, the symbolic address constants that CLOSER generates from the parameter list are self-relocating. When CLOSE is specified, the symbolic address constants are not selfrelocating. To write the most efficient code in a multiprogramming environment it is recommended that CLOSER be used. Enter the symbolic name of the file (assigned in the DTF header entry) in the operand field. A maximum of 16 files may be closed by one macro by entering additional filename parameters as operands. Alter- nately, you can load the address of the filename in a register and specify the register by using ordinary register notation. The high-order 8 bits of this register must be zeros. For CLOSER, the address of filename may be pre loaded into any of the registers 2-15. For CLOSE, the address of filename may be preloaded into register 0 or any of the registers 2-15. -. Notes: C If you use register notation, we recommend that you follow the standard practice of using only registers 2-12. 2 ....Jf CLOSS: or CLOSER.ls issued to an unopened tape input file,;, the option specifIed 10 the D I F rewind option is performed. If CLOSE or CLOSER is issued to an unopened tape output file, no tapemark or labels are written. Part 6. Physical IOCS 261 PART 7 SUPERVISOR MULTITASKING PROGRAM LINKAGE Supervisor Macros CANCEL CHKPT COMRG DUMP EOJ EXIT FCEPGOUT FETCH FREEVIS GENL GETIME GETVIS JDUMP LOAD MVCOM PAGEIN PDUMP PFIX PFREE REALAD RELEASE RELPAG RUNMODE SETIME SETPFA STXIT TECD TIIMER VIRTAD WAIT WAITM Multitasking Macros ATTACH DEQ DETACH ENQ FREE POST RCD WAITM Program Linkage Macros CALL RETURN SAVE SUPERVISOR MACROS The supervisor itself, and the services provided by supervisor macros, are introduced in the DOS/VS System Management Guide, GC33-5371. The present chapter describes specific macros available to you, their interrelationship, and requirements for their usage. sumed to consist of 34-byte entries in collating sequence. If SYS= YES is specified, the System Directory is scanned first. (This is the search order equivalent to that used when a $-phase is specified.) If either or both LIST and SYS are specified, register 1 points to a parameter list rather than to the phasenarne. This parameter list has the format: Program Loading Phases may be loaded into virtual storage from the system core image library or a private core image library with the FETCH and LOAD macros. FETCH gives control to the phase which was loaded; LOAD returns control to the phase which issued the macro. Provided the relocating load option was selected during supervisor generation, a relocation factor will be applied to all address constants when a relocatable phase is loaded. The system calculates this relocation factor by subtracting the load address determined at link-edit time from the load address specified in (or implied by) the FETCH or LOAD macro. If the load address is implied, the system maintains the correct displacement of the entire phase relative to the beginning of the partition for which the phase was link-edited. FETCH Macro Name ~peration Operand [name FETCH ~ph(st)ame ~E ~ en~6)Point} ] r LIST= ~lis~~)me~ ] [,SYS= ~ ~~sG EDE= ~~~s~J The FETCH macro loads the phase specified in the first parameter. The phase name can be 1-8 characters long. Control is passed to the address specified by the second parameter. If the second parameter is not specified, or if the specification causes an unresolved reference, control is passed to the entry point determined at link-edit time. If LIST is specified, the local directory list specified by listname (or r) is scanned for the required phasename. The directory list, which is generated by the GENL macro, is as- DC A(phasename) DC B'options' DC AL3 (list name ) If the first byte pointed to by register 1 contains X'OO', the parameter list is pointed to. DE= YES indicates that the phasename parameter points to a directory entry rather than a phase. If the directory entry that is then in virtual storage is active, the directory scan mechanism is bypassed, if not, the entry will be filled in by the supervisor. If relocating load was specified during supervisor generation, a relocatable phase will be loaded at the address calculated at link-edit time, adjusted with the relocation factor. Also the entry point and the address constants in the phase will then be updated using this relocation factor. The parameters can be specified either as symbols or in register notation. When register notation is used for phasename, the register must be pre loaded with the address of an 8-byte field that contains the phasename as alphameric characters. The phasename must be left-adjusted and padded with blanks, if necessary. If ordinary register notation is used for entryname, the absolute address of the entry point of the phase should not be preloaded into register 1. If, instead, a symbolic name is used for entryname, the macro expansion results in a V -type address constant. The entryname does not have to be identified by an EXTRN statement. If the physical transient overlap option is specified at supervisor generation time, an increase in throughput can result by overlapping FETCH I/O operations of one partition with program execution in another partition. Part 7. Supervisor Macros 265 GENL--Generate a Directory List Name Op Operand [name] GENL phasel, .......... ,phasen After execution of the macro, the entry-point address of the called phase is returned to you in register 1. For a non-relocatable phase, this address is the entry-point determined at link-edit time. For a relocatable phase the entry point is adjusted by the relocation factor. If the optional load-address parameter is provided, The GENL macro generates a directory Ust with a 34-byte entry for each of the specified phases. The format of the local directory list is compatible with the format of the core image directory. The phase name and the length field are generated at assembly time; the remainder of the entry is filled with X'OO' except the 4th byte which is made X'OB'. This local directory list can be scanned using th~ FETCH and LOAD macros. LOAD Macro Name Operation Operand [name] LOAD ~ph(st)ame~E poa(~Oint ~ ] ELIST= ~ lis~~)e ~ ] [,SYS= ~~~s~J EDE= ~ ~~S ~J ~ TXT= ~ ~gs~J The LOAD macro loads the phase specified in the first parameter and returns control to the calling phase. The phase name can be 1-8 characters long. LIST, SYS, and DE have the same function as they have when used with FETCH; for a full description of that use, look under FETCH. the TXT parameter has the same function as the DE parameter, only no text is loaded. This has two distinct advantages: 1. The directory entry can be filled in for later FETCH/LOAD calls without the overhead of text transfer. the load-point address specified to the linkage editor is overridden, and the phase is loaded at the specified address. The address used must be outside the supervisor area. When an overriding address is given, the entry-point address is relocated and returned in register 1. If the relocating load option was specified during supervisor generation, and the phase is nonrelocatable, none of the other addresses in the phase are relocated; if the phase is relocatable, however, the entry point and address constants are updated with the relocation factor. If the optional loadaddress parameter is provided and the relocating load option was specified during supervisor generation, a program containing V-type address constants must not be link-edited as a relocatable phase because the updated V-type address constants will be invalid. If the relocating load option was specified during supervisor generation and the address for LOAD is implicit (the load-address parameter is not specified), a relocatable phase will be loaded at the address calculated at link-edit time, adjusted with the relocation factor. The address constants in the relocatable phase will be updated with the relocation factor. The parameters can be specified either as symbols or in register notation. When register notation is used for phasename, the register must be preloaded with the address of an 8-byte field that contains the phasename. The phasename should be left-justified and padded with blanks, if necessary. If ordinary register notation is used for loadpoint, this parameter should not be preloaded into register 1. If the physical transient overlap option is specified at 2. You can establish whether a given phase is present by looking for the 'phase not found' condition, X'06', in the directory entry. In case TXT=NO is specified in combination with LIST =listname or DE= YES, the 'phase not found' condition, X'06', is set in the core directory entry if the phase is not present. The address of this condition byte minus a displacement of 16 is returned in register O. You can also check in which library or area the phase resides. 266 DOS/VS Supervisor & I/O Macros supervisor generation time, an increase in throughput can result by overlapping LOAD I/O operations of one partition with program processing in another partition. Virtual Storage The nature of virtual storage requires that certain programs be specially handled. DOS /VS provides a set of supervisor macros to perform these special functions. PFIX Macro The PFIX macro allows you to fix pages of virtual mode programs in real storage until you specify their release with the PFREE macro. Name Operation [name] PFIX With the RUNMODE macro, you can inquire in which mode -- virtual or real -your program is running. To use this macro, the supervisor must have been generated with support for page fault handling overlap. See Appendix G. The SETPF A macro allows you to establish linkage to routines which are to be entered at the beginning of a page fault and when a page fault has been satisfied. I begin address, t The RELP AG macro allows you to release the contents of one or more pages. When a location in a page thus released is referenced again during the same program execution, it is assigned a page frame of all zeros. The FCEPGOUT and PAGEIN macros allow you to override the selection algorithm and have specific pages paged out and in at your discretion. Operand ) end address [,begin address, f end address] ... ~ listname (1) t \ The PFIX macro causes specific pages to be brought into real storage and fixed in their page frames until they are released at some later time. Pages may only be fixed in the real partition corresponding to the virtual partition doing the fixing (for instance, pages from BG can only be fixed in BGR). For this reason, you must have allocated a real partition large enough to contain all the pages which are likely to be fixed at anyone time. In a single-partition system all except 16K of the real background partition is automatically available for fixing pages using the PFIX macro. Each time a page is fixed a counter for that page is incremented. This counter may never exceed 255 for any page. begin address: Points to the first location of the area to be fixed. end address: Points to the last location of the area to be fixed. The VIRTAD macro returns the virtual address corresponding to a specified real address and the REALAD macro returns the real address corresponding to a specified virtual address. Iistname: Is the symbolic name of a list of consecu- tive 8-byte entries as shown below. I I I o 4 0 With the GETVIS and FREEVIS macros you can dynamically retrieve and release blocks of storage in the GETVIS area of your partition or of the shared virtual area (SVA). The GETVIS area in a partition can be allocated in multiples of 2K. The GETVIS area in the SVA must be allocated in multiples of 4K. Any remainder above a multiple of 4K is ignored. The maximum size of the GETVIS area is 994K bytes in a partition and 12 168K bytes in the SVA. The amount of storage to be reserved as the GETVIS area in a partition must be set aside by means of the SIZE parameter of the EXEC job control statement. If the GETVIS area is part of the SVA, the system must have been generated with SVA= (nK,nK) in the VSTAB supervisor generation macro. address constant length minus 1 7 address constant: Points to the first byte of the area to be fixed. length: A binary constant indicating the length of the area to be fixed. A non-zero byte following an entry indicates the end of the list. Register notation may also be used. Exceptional Conditions If a PFIX causes the count of fixes for a page to exceed 255, the task issuing the PFIX is canceled. If it is not possible to fix all pages requested, then none will be fixed. Part 7. Supervisor Macros 267 If PFIX is issued in a program running in real mode it is ignored, and register 15 contains O. If the supervisor was not generated with PFIX= YES, the program issuing PFIX will be canceled. Return Codes in Register 15 if the pages were successfully fixed. o 4 if the number of pages to be fixed for one request exceeds the number of page frames in the real partition; in order for this PFIX request to be satisfied, the real partition must be reallocated and the PFIX reissued. 8 if not enough page frames available in the real partition due to previous PFIXes; this PFIX request could, however, be satisfied at another time without reallocating the real partition. I I I o 4 0 length minus I address constant 1 7 address constant: Points to the first byte of the area to be freed. length: A binary constant indicating the length of the area to be freed. A non-zero byte following an entry indicates the end of the list. Register notation may also be used. Exceptional Conditions If PFREE is issued by a program running in real mode, it is ignored. If the supervisor was not generated with PFIX= YES specified in the FOPT macro, the program issuing PFREE will be canceled. 12 if one of the addresses specified was invalid. Return Codes in Register 15 o if the pages were successfully freed. PFREEMacro 12 if one of the addresses specified was invalid. Name Operation Operand [name] PFREE beginn address, end address [,begin address, end address] ... ~1istnamet I (1) , Pages in the virtual address area are each assigned a 'PFIX counter'. If a page is not fixed--that is, if it is subject to normal page management--the counter is o. Whenever a page is fixed by using a PFIX macro its counter is increased by one. All pages whose counters are greater than 0 remain fixed in real storage. The PFREE macro decrements the counter of a specified page by 1. A PFREE issued for a page whose counter is 0 is ignored since the page has already been freed. begin address: Points to the first location of the area to be freed. end address: Points to the last location of the area to be freed. listname: Is the symbolic name of a list of consecutive 8-byte entries as shown below. 268 DOS/VS Supervisor & I/O Macros RELPAG Macro Name Operation [name] RELPAG Operand begin address, end address [ , begin address, ~ ) end address 1 ... ~ I I' 5listname t I (1) , \ The RELP AG macro causes the contents of one or more storage areas to be released. If the affected areas are in real storage when the RELP AG macro is executed, their contents are not saved but simply overwritten when the associated page frames are needed to satisfy pending page frame requests. After the RELPAG macro has been executed for an area and a location in that area is referenced again during the current program execution, the related page is attached to a page frame which contains all zeros. The storage area is released only if it contains at least one full page. You can be sure of this only if your area is 4K minus 1 byte or bigger. r----- First byte of page n 2 - The begin address is greater than the end address, or a negative length has been found. Starting address of specified area Oength=4k-2 bytes) 2k Page n 2k Page n+ 1 4 - The area, fully or partially, does not belong to the partition where the issuing program is running. The RELEASE request has only be executed for those pages which belong to the partition of t6.e issuing program. End address of specified area Last byte of page n+ 1 - - -.... Figure 7-1 8 - 1. At least one of the requested pages is temporarily fixed (via CCW -translation) and/or PFIXed. The RELEASE request has only been executed for the unfixed pages. 2. A page handling request (page fault, temporary fix, PFIX) for at least one of the requested pages is pending (caused by asynchronous processing within a partition). The RELEASE request has not been executed for those pages which are reinvolved in a page handling request. Worst case of an area not containing one full page begin address: Points to the first location of the area to be released. end address: Points to the last location of the area to be released. listname: Is the symbolic name of a list of consecutive 8-byte entries as shown below. I I I o 4 0 address constant Any combination of the return codes is possible. length minus I 7 address constant: Points to the first byte of the area to be released. FCEPGOUT Macro Name Operation [name] FCEPGOUl begiD address, end address l length: A binary constant indicating the length of the area to be released. [ , begin address, end address] 5listnamet \ A non-zero byte following an entry indicates the end of the list. Register notation may also be used. Exceptional Conditions • The program is running in real mode. Operand 1 (1) The area is, fully or partially, outside of the virtual partition of the requesting program. The FCEPGOUT macro causes a specific area in real storage to be paged-out at the next page fault. This request is ignored if the specified area does not contain a full page. This can happen up to an area size of 4K minus 2 bytes (see Figure 7.1). A page handling request is pending for the referenced page(s). begin address: Points to the first location of the area to be paged out. • The page (s) is (are) fixed. For these pages, the RELPAG request will be ignored. end address: Points to the last location of the area to be paged out. • The supervisor was not generated with PAGEIN=n in the SUPVR macro (in this case the program will be canceled). • listname: Is the symbolic name of a list of consecutive 8-byte entries as shown below. I I I o 4 0 Return Codes in Register 15 o - All referenced pages have been released or the request has been ignored because the requesting program is running in real mode. address constant 1 length minus I 7 address constant: Points to the first byte of the area to be paged out. Part 7. Supervisor Macros 269 length: A binary constant indicating the length of the area to be paged out. PAGEIN Macro Name Operatiol1 Operand [name] PAGEIN (begin address, end address A non-zero byte following an entry indicates the end of the list. Register notation may also be used. '[ , begin address, end address ] ... )f listname t 1 (l) \ Exceptional Conditions • The program is running in real mode. • The page(s) referenced by the macro is (are) outside of the requesting partition. • The page handling request(s) is (are) pending for the referenced page(s). • The page(s) is (are) not in real storage. • The page(s) is (are) fixed. For those pages the FCEPGOUT request will be ignored. • The supervisor was not generated with PAGEIN=n in the SUPVR macro. (In this case the program is canceled.) Return Codes in Register 15 0- All specified pages have been forced for pageout or the request has been ignored because the issuing program is running in real mode. 2 - The begin address is greater than the end address, or a negative length has been found. [l , ECB= l (eCb&),e ) \] The PAGEIN macro causes specific areas to be brought into real storage before their contents are needed by the requesting program. If the requested area is already in real storage the attached page frame will get low priority for the next page-outs. This function, however, does not include any fixing, so that it is not sure that all areas requested will still be in real storage when the entire request has been completed. begin address: Points to the first location of the area to be paged in. end address: Points to the last location of the area to be paged in. listname: Is the symbolic name of a list of consecutive 8-byte entries as shown below. 10 I address constant Ilength minus 1 o t 4 7 4 - At least one of the requested pages do not belong to the partition where the issuing program is running. The P AGEOUT request has only been executed for those pages which are belonging to the partition of the issuing program. address constant: Points to the first byte of the area to be paged in. 8 - 1. A non-zero byte following an entry indicates the end Jf the list. Register notation may also be used. 2. At least one of the requested pages is temporarily fixed (via CCW-translation) and/or PFIXed. This PAGEOUT request has only been executed for the unfixed pages. A page handling request (page fault, temporary fix, PFIX) for at least one of the requested page is pending (caused by asynchronous processing within a partition). The P AGEOUT -request has not been executed for those pages which are involved in a page handling request. Any combination of return codes is possible. 270 DOS/VS Supervisor & I/O Macros length: A binary constant indicating the length of the area to be paged in. ECB=ecbname: Specifies the name of the ECB, a fullword defined by your program, which is to be posted when the operation is complete. Register notation may also be used. The ECB parameter is optional. Return Information The return information can be obtained from the ECB, byte 2. Bits ofECB byte 2: Meaning if bit is one: o P AGEIN request is finished. 1 The page table is full, the request cannot be queued at this time for further handling. The request is ignored, bit 0 is set. 2 One or more of the requested pages are outside the requesting program's partition. PAGEIN is not performed for these pages. 3 At least one negative length has been detected in the area specifications, P AGEIN is not performed for these areas. 4 List of areas that are to be paged in is not completely in the requesting program's partition. The request is ignored, bit 0 is set. 5 Paging activity is too high in the system, no performance improvement is possible. Use the WAIT macro with the ecbname as operand for completion of the PAGEIN macro, before the return code is tested. Any combination of the return bits in the ECB is possible. SETPFA Macro Name Operation [name] SETPFA Operand ~entry address ~ (0) The SETP:F' A macro either tstablishes or terminates linkage to a page fault appendage routine that is to be entered each time a page fault occurs or is completed. You will find more information on how to write such a routine in Appendix G of this manual. If an entry address is specified, then the routine pointed to by the address will be entered every time a page fault in its task occurs or is satisfied. The routine to be entered and all areas referenced by the routine must be fixed in real storage using the PFIX macro before SETPF A is issued. The entry address may be specified as a symbol or in register notation. If SETPF A is issued without an operand, the linkage to the page fault appendage is terminated. Each issuance of SETPFA supersedes all previous SETPF A's for that task. The page fault appendage is only called when a page fault occurs in the task owning the appendage. If a page fault occurs in a supervisor service working for the owning task, the appendage is not called. See Appendix G for instructions on setting up a page fault appendage. VIRTAD Macro RUNMODE Macro Name Operation [name] RUNMODE The RUNMODE macro returns the following information to the program issuing it: • Name Operation Operand [name] VIRTAD rddress~ Operand Register 1 contains 0 if the issuing program is running in virtual mode. Register 1 contains 4 if the issuing program is running in real mode. No operand is required for this macro. (1) The VIRT AD macro returns the virtual address corresponding to a specified real address. address: Is the real storage address to be converted. It can be given as a symbol or in register notation. Register 0 returns the virtual address corresponding to the specified real address only if the page frame containing the specified real address contains a fixed page; otherwise register 0 contains O. Part 7. Supervisor Macros 271 Note: • The pages of a program running in real mode are considered to be fixed. I If the supervisor has been generated without the The start address (ADDRESS) of the requested virtual storage area is returned by the system either in the 4-byte field addressed by name I or in the specified register. (Register 15 must not be used becfluse it contains the return code.) The returned address is only valid if the return code in register 15 is zero. If the operand is omitted, the address is returned in register 1. parameter ECPREAL= YES in the FOPT supervisor generation macro instruction the issuing task is canceled. REALAD Macro Name Operation [name] REALAD The GETVIS macro retrieves a block or blocks of storage from the GETVIS area of your partition or of the SVA. Operand ~address ~ (1) The length (LENGTH) of the requested storage block may be specified by you either in the 4-byte field addressed by name2 or in a register. The length is specified in bytes. The smallest unit that can be requested by GETVIS is (a) 128 bytes if the GETVIS area is part of a partition or (b) 512 bytes if the GETVIS area is part of the SVA. If the specified length is not a multiple of 128 or 512, respectively, it is rounded to the next higher multiple of 128 or 512. If the operand is omitted, the system assumes that you have specified the length in register O. f The REALAD macro returns the real address corresponding to a specified virtual address. address: Is the virtual address to be converted. It can be given as a symbol or in register notation. Register 0 returns the real address corresponding to the specified virtual address if and only if the virtual address points to a fixed page, otherwise register 0 contains O. If you want the requested storage area to start on a page boundary, specify PAGE= YES. This may reduce page faults. Note: • • If POOL is specified, GETVIS starts searching for The pages of a partition running in real mode are treated as if they were fixed. the requested virtual storage area at the address specified in register 1. In this case, it is your responsibility to provide a meaningful address in register 1. If the supervisor is generated without the param- eter ECPREAL= YES in the FOPT supervisor generation macro the issuing task is canceled. If SVA= YES is specified, the GETVIS area in the SVA is used. Otherwise, the GETVIS area of the I current partition is taken. GETVIS Macro Name Operation Operand [name] GETVIS [ ADDRESS= ~ nWe 1 f ] [, LENGTH= ~ I n(~e2 f ] [, PAGE= ~ ~g ~J [, POOL= ~~~ [, SVA= fJ ~~~S ~] 272 DOS/VS Supervisor & I/O Macros I User programs can only use the SVA if they have a storage protection key of zero. Return Codes in Register 15 o GETVIS completed successfully. 4 The GETVIS area is OK. 8 The GETVIS macro was issued by a program running in real mode. 12 No more virtual storage is available in the GETVIS area, or the length specified is smaller than zero. If the return code is not zero, no action is taken by FREEVIS Macro Name Operation Operand [name] FREEVIS [ADDRESS= FREEVIS. 1n0;el ~J [,LENGTH= ~ (:e2 ~ ] [, SVA= ~ ~~S ~ ] The FREEVIS macro releases a block (or blocks) of virtual storage that was retrieved by the GETVIS macro. The start address (ADDRESS) of the virtual storage block to be released in the GETVIS area may be specified by you either in a 4-byte field addressed by name 1 or in a register. If the operand is omitted, the system assumes that you have specified the address in register 1. The length (LENGTH) of the virtual storage block to be released may be specified by you in a 4-byte field addressed by name2 or in a register. The length is specified in bytes. The smallest unit of virtual storage that can be released by FREEVIS is (a) 128 bytes if the GETVIS area is part of a partition or (b) 512 bytes if the GETVIS area is part of the SVA. If the specified length is not a multiple of 128 or 512, respectively, it is rounded to the next higher integral multiple of 128 or 512. If the operand is omitted, the system assumes that you have specified the length in register O. If SV A= YES is specified, the GETVIS area in the Program Communication For each partition the supervisor contains a storage area called the communication region. The supervisor uses the communication region, and your program also can use it. Your program can check the communication region of the partition in which your program runs; your program can also modify the user area of this communication region. Figure 7 -2 shows the portion of the communication region containing information of interest. This information is also described below. Field Length 8 bytes Calendar date. Supplied from system date whenever the JOB statement is encountered. The field can be two forms: mm/dd/yy or dd/mm/yy where mm is month, dd is day, yy is year. It can be temporarily overridden by a DATE statement. 4 bytes Reserved. 11 bytes User area for communication within a job step or between job steps. All 11 bytes are set to zero when the JOB statement for the job is encountered. 1 byte UPSI (user program switch indicators). Set to binary zero when the JOB statement for the job is encountered. Initialized by UPSI job control statement. 8 bytes Job name as found in the JOB statement for the job. 4 bytes Address of the uppermost byte of the program area. If the program was initiated with the SIZE parameter in the EXEC job control statement, this address gives the highest byte of the area determined by the SIZE parameter. SVA is used. Otherwise, the GETVIS area of the current partition is taken. User programs can only use the SVA if they have a storage protection key or zero. Return Codes in Register 15 8 The FREEVIS macro was issued by a program running in real mode. 12 The specified address is not within the GETVIS area or the address is not (a) a multiple of 128 bytes if the GETVIS area is part of a partition, or (b) a multiple of 512 bytes if the G ETVIS area is in the SVA. 16 The specified storage block (ADDRESS+ LENGTH) to be released exceeds the GETVIS area, or the length specified is smaller than zero. Information If the SIZE parameter was not specified, the address is the highest address in the partition (either real or virtual). 4 bytes Address of the uppermost byte of the current phase placed in the program area by the last FETCH or LOAD macro in the job. Part 7. Supervisor Macros 273 4 bytes EXEC statement has no operand, job control places in this location the ending address of the phase just link-edited. Highest ending virtual storage address of the phase among all the phases having the same first four characters as the operand on the EXEC statement. For the background partition only, job control builds a phase directory of these phases. The address may be incorrect if the program loads any of these phases above its link-edited origin address and the relocating loader is not used. If the 2 bytes Length of program label area. The COMRG and MVCOM macros allow your program to check and to modify the communication region. I in 0- Date Mo/Day/Yr or Day/Ma/Yr Reserved User Area - set to zero when JOB statement is read. (Communication within a job step or between job steps) 2'"CII ..c. Job Name (Entered from Job Control) ~ 'i V) E e ~ 078 Bytes ... 0 11 12 22 23 24 Address: Uppermost Byte of Problem Program Area 31 32 Address: Uppermost Byte of Current Problem Program Phase 3536 Address: Uppermost Byte of phase with highest ending address 3940 Length of Problem Program Label Area 43 44 45 } + Address cl first byte supplied in register 1 by COMRG Figure 7-2 Communication region COMRGMacro Name Operation [name] COMRG MVCOMMacro Operand Name Operation Operand [name] MVCOM to ,length , {from f (0) The COMRG macro places the address of the communication region of the partition from which the macro is issued in register 1. Your program can read any portion of its own partition's communication region by using register 1 as a base register. The MVCOM macro modifies the content of bytes 12-23 of the communication region of the partition from which the macro is issued. The operand from represents the address (either as a symbol or in register notation) of the bytes to be inserted. The operand length represents the number of bytes (1-12) inserted. The operand to is the address (relative to the first byte of the region) of the first communication region byte modified (12-23). 274 DOS/VS Supervisor & I/O Macros The following example shows how to move three bytes from the symbolic location DATA into bytes 16-18 of the communication region: MVCOM 16,3,DATA Time of Day Macro GETIME Macro Name Operation [name] GETIME Releasing I/O Units Operand rTANDARDl BINARY [, ~LOCA~GMT;:r~~~~u Figure 7-7 Direct linkage 296 DOS/VS Supervisor & I/O Macros Linkage Registers REGISTER NUMBER To standardize branching and linking, registers are assigned specific roles (see Figure 7-8). Registers 0, 1,13,14, and 15 are known as the linkage registers. Before a branch to another routine, the calling program is responsible for the following calling sequence: 1. Loading register 13 with the address of a register save area in that program which the called program is to use. 2. Loading register 14 with the address to which the called program will return control. 3. Loading register 15 with the address from which the called program will take control. ° 4. Loading registers and 1 with parameters, or loading register 1 with the address of a parameter list. A typical calling sequence could read: CALSEQ CNOP LA 2,4 13,SAVAR LA 1 , PARLST para list L BALR Load save area address Load address of a meter 15,=V(SU1?R) Load entry point address 14, 15 Load return address REGISTER NAME CONTENTS 0 Parameter regist"r Parameters to be passed to the called program. 1 Parameter register Parameters to be passed to the called program. or Parameter list register Address of a parameter list to be passed to either the control program or your subprogram' 13 Save area register Address of the register save area to be used by the called program. 14 Return register Address of the location in the calling program to which control s,hould be returned after execution of the called program. 15 Entry paint register Address of the entry point in the called program. Figure 7-8. Linkage registers After execution of the calling sequence, the following should occur as a result of called program execution: 1. The contents of registers 2 through 14, and the program mask are unchanged. 2. The contents of registers 0, 1, and 15, and the contents of the floating point registers, and the condition code may have been changed. 3. The parameter list addresses contain the results obtained from called program execution. Save Areas SAVAR PARLST DS DC 9D A(PAR1,PAR2) The address of the save area (SAVAR) and the parameter list (P ARLST) containing two parameters (PARI and PAR2) are passed to a subroutine (SUBR). SUBR returns control to this program at the next sequential instruction after BALR. A called program should save and restore the contents of the linkage registers, as well as the contents of any register that it uses. The registers are stored in a save area that the higher level (calling) program provided. This procedure conserves storage because the instruction to save and restore registers need not be repeated in each calling sequence. Every program must provide a save area and place its address in register 13 before it executes a direct linkage. This address is then passed to the called routine. A save area occupies nine double words and is aligned on a double word boundary. For programs to save registers in a uniform manner, the save area has a standard format shown in Figure 7 -9 and described below: Part 7. Program Linkage Macros 297 Word Displacement 1 0 Indicator byte and storage length; used by PL/I language program. 2 4 The address of the previous save area; that is, the save area of the subprogram that called this one (used for tracing purposes). 3 8 The address of the next save area; that is, the save area of the subprogram to which this subprogram refers. 4 12 The contents of register 14 containing the address to which return is made. 5 16 The contents of register 15 containing the address to which entry into this subprogram is made. 6 20 (The contents of) register O. 7 24 (The contents of) register 1. 8 28 (The contents of) register 2. 9 32 (The contents of) register 3. 10 36 (The contents of) register 4. 11 40 (The contents of) register 5. 12 44 (The contents of) register 6. 13 48 (The contents of) register 7. 14 52 (The contents of) register 8. 15 56 (The contents of) register 9. 16 60 (The contents of) register 10. 17 64 (The contents of) register 11. 18 68 (The contents of) register 12. Figure 7-9 Contents Save area words and contents in calling programs • Word 1: An indicator byte followed by three bytes that contain the length of allocated storage. Use of these fields is optional, except in programs written in the PL/I language. Word 2: A point~r to word 1 of the save area of the next higher level program. The address passed to a routine in register 13. The contents of register 13 must be stored by a calling program before it loads register 13 with the address of the current save area that is passed to a lower level routine (Figure 7-9, ST 13,SAVEB+4). • Word 3: A pointer to word 1 of the save area of the next lower level program, unless this called program is at the lowest level and does not have a save area. (The called program requires a save area only if it is also a calling program.) Thus, the called program, if it contains a save area, stores the save area address in this wor~l. • Word 4: The return address, which is register 14, when control is given to the called program. The called program may save the return address in this word. • Word S: The address of the entry point of the called program. This address is in register 15 when control is given to the called program. The called program stores the entry-point address in this word. • Words 6 through 18: The contents of registers 12, in that order. The called program stores the register contents in these words if it is programmed to modify these registers. o through In any routine, the contents of register 13 are saved so that the registers may be restored upon return. For purposes of tracing from save area to save area, the address of the new save area is stored. Only the registers to be modified in the routine need be saved. However, the safest procedure is to store all registers to ensure that later changes to the program do not result in the modification of the contents of a register that was not saved. CALL Macro The CALL macro passes control from a program to a specified entry point in another program. The pro- 298 DOS/VS Supervisor & I/O Macros gram issuing the CALL macro is the calling program. The program receiving control is the called program or routine. The called program must be in virtual storage when the CALL macro is executed. The called program is brought into virtual storage in one of two ways: 1. As part of the program issuing the CALL. In this case, the CALL macro must specify an entry point by symbolic name. The linkage editor includes the phase containing that entry point in the phase containing the CALL macro. 2. As the phase specified by a LOAD macro. In this case, the CALL macro specifies register 15 (the entry-point register) into which the address of the program to be called was loaded. The LOAD macro must precede the first CALL for that program. The format of the CALL macro is shown below. Name Operation Operand [name] CALL ~entryPOint } at the address in register 15. Specifying register 15 preceded by a LOAD macro is most useful when the same program is called many times during execution of the calling program, but is not needed in storage throughout execution of the calling program. parameter specifies an address (relocatable or absolute expression) to be passed as a parameter to the called program. Terms in the address must not be indexed. The parameter operands must be written in a sublist, as shown in the format description. If one or more parameter operands are written, a parameter list is generated. It consists of a fullword for each operand. Each fullword is aligned on a fullword boundary and contains the address to be passed in its three low-order bytes. When the called program is entered, register 1 (the parameter list register) contains the address of the parameter list. In the following examples, EXI gives control to an entry point named ENT. EX2 gives control to an entry point whose address is contained in register 15. Two parameters, ABC and DEF, are passed. Examples: (15) EXI CALLENT [,(parameter, ... )] EX2 CALL (15),(ABC,DEF) entrypoint specifies the entry point to which control is passed. If the symbolic name of an entry point is specified, an instruction L 15,= V(entrypoint) is generated as part of the macro expansion. The linkage editor makes the called program part of the calling program phase. The symbolic name must be either the name of a control section (CSECT) or an assembler language ENTRY statement operand in the called program. Control is given to the called program at this address. If a symbolic name is specified for the entry point operand, the called program resides in storage throughout execution of the calling program. This wastes storage if the called program is not needed throughout execution of the calling program. A typical macro expansion for the macro CALL SUBR,(Pl,P2 ... ,Pn) is: CNOP NAME L LA BALR DC ORG DC ORG 2,4 15,=V(SUBR) 14,*+6+4*n (return address) 1 , 15 A( P 1 , P2 ... , Pn ) *-4 X'80' NAME is the symbol in the name field of the macro. n is the number of fullwords in the parameter list. SUBR is the symbolic name of the entry point of the called program. PI through Pn are the addresses to' be passed to' the called prO'gram. If register 15 is specified, the entrypoint address should have been loaded into that register previously. The operand may be written as a self-defining value equal to 15 and enclosed in parentheses, in which case the V-type address constant instruction is not generated. Control is given to the called program Part 7. Program Linkage Macros 299 If r2 is omitted, only the register specified by rl is SAVE Macro The SAVE macro stores the contents of specified registers in the save area provided by the calling program. It is written at the entry point of a program, before any registers can be modified by the new program. Name Operation Operand [name] SAVE (rl[,r2]) The operands rl,r2 specify the range of the registers to be stored in the save area of the calling program. The address of this area is passed to the program in register 13. The operands are written as self-defining values so that they cause desired registers in the range of 14 through 12 (14, 15,0 through 12) to be stored when inserted in an STM machine instruction. Registers 14 and 15, if specified, are saved in words 4 and 5 of the save area. Registers 0 through 12 are saved in words 6 through 18 of the save area. The contents of a given register are always stored in a particular word in the save area. For example, register 3 is always saved in word 9 even if register 2 is not saved. 300 DOS/VS Supervisor & I/O Macros saved. RETURN Macro The RETURN macro restores the registers whose contents were saved and returns control to the calling program. Name Operation Operand [name] RETURN (rl [,r2]) The operands r 1,r2 specify the range of the registers to be reloaded from the save area of the program that receives control. The operands are written as self-defining values. When inserted in an LM machine instruction, the operands cause the desired registers in the range from 14 through 12 (14, 15,0 through 12) to be restored from words 4 through 18 of the save area. If r2 is omitted, only the register specified by r1 is restored. To access this save area, register 13 must contain the save area address. Therefore, the address of the save area is loaded into register 13 before execution of the RETURN macro. APPENDIX A: CONTROL CHARACTER CODES CTLCHR=ASA CTLCHR=YES If the ASA option is chosen, a control character must appear in each record. If the control character for the printer is not valid, a message is given and the job is canceled. If the control character for card devices other than the 2560 and 5425 is not V or W, the card is selected into stacker 1. The codes are: The control character for this option is the command-code portion of the CCW used in printing a line or spacing the forms. If the character is not one of the following characters, unpredictable events will occur. Code blank o - + 1 2 3 4 5 6 7 8 9 A B C V W X Y Z Interpretation Space one line before printingSpace two lines before printing space three lines before printing Suppress space before printing Skip to c~annel 1 before printing* Skip to channel 2 before printing Skip to channel 3 before printing Skip to channel 4 before printing Skip to channel 5 before printing Skip to channel 6 before printing Skip to channel 7 before printing Skip to channel 8 before printing Skip to channel 9 before printing Skip to channel 10 before printing Skip to channel 11 before printing Skip to channel 12 before printing Select stacker 1 Select stacker 2 Select stacker 3 (2560 and 5425 DTFCD files only) Select stacker 4 (2560 and 5425 DTFCD files only Select stacker 5 (2560 DTFCD file~ only) Hexadecimal Code Punch Combination Function Stacker Selection on 1442 and 2596 81 12,0,1 Select into stacker 1 Cl 12,1 Select into stacker 2 Stacker Selection on 2520 01 12,9,1 Select into stacker 1 41 12,0,9,1 Select into stacker 2 Stacker Selection on 2540 01 12,9,1 Select into stacker 1 41 12,0,9,1 Select into stacker 2 81 12,0,1 Select into stacker 3 For DTFDI files on 2560 and 5425 Primary hopper: select stacker 1 Primary hopper: select stacker 2 Secondary hopper: select stacker 5 (on 2560) V Secondary hopper: select stacker 4 (on 5425) W Secondary hopper: select stacker 3 V W V - For 3525 print (not associated) files, either space one or skip to channel 1 must be used to print on the first line of a card. For 3525 print associated files, only space one must be used to print on-the first line of a card. Appendix A 301 Hexa decimal Code Punch Combination Function Stacker Selec:tiQn on 2560 gnd ~~25 13 11,3,9 Primary hopper: select into stacker 1 23 0,3,9 Primary hopper: select into stacker 2 33 3,9 Primary hopper: select into stacker 3 43 12,0,3,9 Primary hopper: select into stacker 4 53 12,11,3,9 Primary hopper: select into stacker 5 (2560 only) 93 12,11,3 Secondary hopper: select into stacker 1 Hexadecimal Code Punch CombinatiOR Function Printer Control (Except for 3525) 89 12,0,9 Write and skip to channel 1 after printing 91 12,11,1 ~Jri 99 12,11,9 ~Jri Al 11,0,1 ~Jri A9 11,0,9 ~Jri B1 12,11,0,1 Write and skip to channel 6 after printing te and skip to channel 3 after printing te and skip to channel 4 after printing te and ski p to channel 5 after printing A3 11,0,3 B3 12,11,0,3 Secondary hopper: select into stacker 3 C3 12,3 Secondary hopper: select into stacker 4 B9 12,11,0,9 03 11,3 Secondary hopper: select into stacker 5 (2560 only) Write and ski P to channel 7 after printing C1 12,1 Write and skip to channel 8 after printing C9 12,9 Wri te and skip to channel 9 after printing 01 11,1 Write and ski P to channel 10 after printing 09 11,9 Write and skip to channel 11 after printing E1 11,0,9,1 Write and skip to channel 12 after printing Sta~~er: Secondary hopper: select into stacke~2 te and skip to channel 2 after printing Sele!;tjg[! gn 3504 1 3505 and 3525 01 12,9,1 Select into stacker 1 41 12,0,9,1 Select into stacker 2 Printer Control (Exce~t for 3525} 01 12,9,1 Wri te (no automatic space) 09 12,9,8,1 Write and space 1 line after printing 11 11,9,1 Wri te and space 2 1 i nes after printing 19 11,9,8,1 Write and space 3 1 i nes after printing 302 DOS/VS Supervisor & I/O Macros Hexadecimal Code Punch Combination Function Printer Control (Exceet for 3525) OB 12,9,8,3 Space 1 line immediately 13 11,9,3 Space 2 lines immediately IB 11,9,8,3 Space 3 lines imr.1ediately Printer Control for 3525 with Print Feature Hexadecimal Code Punch Combination Function 00 12,5,8,9 Print on 1 i ne 1 15 11,5,9 Print on line 2 10 11,5,8,9 Print on line 3 25 0,5,9 Print on line 4 20 0,5,8,9 Print on line 5 35 5,9 Print on line 6 3D 5,8,9 Print on line 7 45 12,0,5,9 Print on line 8 40 12,5,8 Print on line 9 55 12,11,5,9 Print on line 10 50 11,5,8 Print on 1 i ne 11 65 11,0,5,9 Print on line 12 60 0,5,8 Print on line 13 8B 12,0,8,3 Skip to channel 1 immediately 93 12,11,3 Skip to channel 2 immediately 9B 12,11,8,3 Skip to channel 3 immediately A3 11,0,3 Skip to channel 4 immediately AB 11,0,8,3 Skip to channel 5 immediately B3 12,11,0,3 Skip to channel 6 immediately BB 12,11,0, 8,3 Skip to channel 7 immediately 75 12,11,0, 5,9 Print on line 14 C3 12,3 Skip to channel 8 immediately 70 5,8 Print on line 15 85 12,0,5 Print on line 16 80 12,0,5,8 Print on Hne 17 95 12,11,5 Print on line 18 90 12,11,5,8 Print on line 19 A5 11,0,5 Print on line 20 AD 11,0,5,8 Print on line 21 B5 12,11,0,5 Print on line 22 BO 12,11,0 5,8 Print on line 23 C5 12,5 Print on line 24 CO 12,0,5,8, 9 Print on line 25 CB 12,0,9, 8,3 Skip to channel 9 immediately D3 11,3 Skip to channel 10 immediately DB 12,11,9 8,3 Skip to channel 11 immediately E3 0,3 Skip to channel 12 immediately 03 12,9,3 No operation Appendix A 303 APPENDIX B: ASSEMBLING YOUR PROGRAM, DTFS, AND LOGIC MODULES All the programs described in this appendix perform the same function, namely, a cardto-disk operation with the following equipment and options: 1. Card reader: 2. Disk: 2540 (SYS004). 3330 with user labels. 3. Record size: 80 bytes. 4. Block size: 408 bytes including. 8-byte count field (blocking factor of 5). 5. One I/O area and work 'area for the card reader. 6. Two I/O areas for the disk. The following methods may be used to furnish the DTFs and IOCS logic modules to the card-to-disk program. 1. DTFs, IOCS logic modules, and your program assembled together. 2. Logic modules assembled separately. 3. DTFs and logic modules assembled separately, label exit, EOF exit, and I/O areas assembled with DTFs. 304 DOS/VS Supervisor & I/O Macros 4. Same as in 3 except that I/O areas are moved back into main program. 5. Same as in 4 except that label exit and EOF exit are also moved back into main program. An example of each of these five methods of assembling the main program, modules, DTFs, and related functions follows. In the figures that accompany the examples, each dashed arrow represents a symbolic linkage, with an external reference at the base of the arrow, and a label or section definition designating the same symbol at the head of the arrow. At the points where an arrow is marked with a circle, it is your responsibility to define an ENTRY or EXTRN symbol, as applicable. Each dotted arrow represents a direct linkage. Components are represented by the small rectangles. Assemblies are represented by the larger bordered areas. The examples are followed by a comparison of the five methods. EXAMPLE 1: ASSEMBLING YOUR PROGRAM, DTFs, AND LOGIC MODULES TOGETHER Figure B-1 shows the assembly of the DTFs, logic modules, and your program. The assembly source deck is: CDTODISK NEXT SAVEAREA EOFCD START BALR USING LA OPEN GET PUT B OS 0 12,0 *,12 13,SAVEAREA CARDS,DISK CARDS,(2) DISK NEXT CLOSE EOJ CARDS,DISK Co 1 . 72 Initialize base- register Establish addressability. Use reg 13 as pointer to save area. Open both files. Read one card and move it to the disk output buffer. Return for next card. Save area is 72-byte, doubleword aligned. 90 At card-reader EOF, close both files and exit to job control. MY LABELS LBRET CARDS DISK OTFCO DTFSO DEVADDR=SYSOO4, EOFADDR=EOFCD, IOAREAI=Al, WORKA=YES BLKSIZE=408, IOAREAI=A2, IOAREA2=A3, IOREG=~2), LABADD =MYLABELS, RECFORM=FIXBLK, RECSIZE=80, TYPEFLE=OUTPUT DEVICE=3330 Al A2 A3 ( 1) OS OS OS Your label-processing routine. Return to main program. 2 X X X X X X X X X X X X X X Card-input buffer First disk buffer Second di~k buffer 80C 408C 408C CDMOD DEVICE=2540, TYPEFLE=INPUT, WORKA~YES X X X SDMOOFO END CDTODISK Program-start address Appendix B 305 Your Program •• • DTF's OPEN GET •• • • CARDS,DISK •••••••••••••••••••••••••••••••• •• •••• ••• •• ••••• ~DISK CA~DS/(2) : •••••••• ·~CARDS r-------------------~ ·· CARDS : DISK DTFSD DTFCD L. DeVADDR =SYS004 : ••••••••••••••••••••••••••••••••••••••••••• EOFADDR=EOFCD ··············IOAREA1=Al : : WORKA=YES ·· BLKSIZE=408 IOAREA1=A2 ••••••••••••• •••••••• IOAREA2=A3 : IOREG= (2) • LABADDR=MYLABELS····· RECFORM=FIXBLK • RECSIZE=80 TYPEFLE=OU TPUT I ·------~I----~ · . I I . I I I~ A I (Bulle, Are.) 1lIIlIlIlIlIIlIIllIIllIIlIroojoo: --t--------------~ EOFCD (End-of-File Processing) • ••• • I I MYLABELSI evr I I I I Rou'; •• ) A2 (Bull., Area) A3 (Buffer Area) : ·'j·"'1II1II1II1I1II1I1II11II1II r---------.J I • SDMODFO (Logic for a Card File) (logic for a Disk File) • ••• •• Figure B-1. ••• ••• Assembling Your Program DTFs and Modules Together (Example 1) 306 DOS/VS Supervisor & I/O Macros I 1II11I11I11I11I11I11I11I11r········· I I CDMOD : _ooofo: EXAMPLE 2: ASSEMBLING THE LOGIC MODULES SEPARATELy The main-program source deck is identical to that in Exam~le 1 until (1); at this point, you S1mp y furnish the END card. Figure B-2 shows the separation of the I/O logic modules. The two logic modules are assembled as follows: Co 1 ." 72 CDMOD Card logic module END Disk logic module X DEVICE=2540, X SEPASMB=YES, X TYPEFLE=INPUT, X WORKA=YES SDMODFO SEPASMB=VES X END Your Program ••• OPEN GET OTF's CAROS,OISK ••••••••••••••••••••••••••••••••••••••••••••••• ~DISK CA~OS,(2) • ••• : •••••••• ·~CAROS ~-------------------- CARDS OTFCO DISK OTFSO : OEVAOOR=SYSOO4 • ••••••••••••••••••••••••••••••••••••••••••• EOFAOOR~OFCD : L··············IOAREA1=Al : : WORKA=YES ~ : · : · A 1 (Buller Area) Ii.. :. I I I I 1 1 -:----------. I I EOFCO (End-of-File Proc_i~) • ••• • I ~T---'--------------~ MYLABELS (Yr 1 11111111111111111111111111- .. , BLKSIZE=408 IOAREA1=A2 ••••••••••••• : ••• ····IOAREA2=A3 : IOREG= (2) : LABAODR=MYLABELS···· RECFORM=fIXBLK RECSlZE=80 TYPEFLE=OU TPUT Routine) .. A2 (Buffer Area) I I ···T· I 1II1I1I1I1I1nllmlllllll~········· I :··i.·· I A3 (Buft'.r ANa) -11111111111111111111111110 r---------.J I • COMOO (Separately Assembled) (Logic for a Cord File) •• •• •• Figure B-2. SOMOOFO (Separately Assembled) (Logic for a Disk File) •• ••• • Logic Modules Assembled Separately (Example 2) Appendix B 307 After assembly, each logic module is preceded by the appropriate CATALR card. The modules may be added to the system re10catab1e library during a maintenance run. Thereafter, logic. modules are automatically included in your program by the linkage editor while it prepares the preceding main program for execution. Co 1 . 72 DISK DTFSD X BLKSIZE=408, SEPASMB=YES, EXAMPLE 3: ASSEMBLING THE DTFs AND LOGIC MYLABELS MODULEs sEpARATELy X X TYPEFLE=OUTPUT X DEVICE=3330 BALR 10,0 USING *,10 The main program is assembled: CDTODISK NEXT SAYEAREA START BALR USING LA OPEN GET PUT B DS 12,0 *,12 13,SAVEAREA CARDS,DISK CARDS,(2) DISK NEXT (4) (5) CARDS,DISK CDTODISK The logic modules are assembled as in Example 2. Fi?,ure B-3 shows the separation of the DTFs antl logic modules. The DTFCD and related functions are assembled: Co 1. 72 CARDS DTFCD DEVADDR=SYS004, SEPASMB=YES, EOFADDR=EOFCD, IOAREA1=A1, WORKA=YES USING *,14 EOFCD CLOSE CARDS,DISK EOJ EXTRN DISK (3) Al DS END 80C The DTFCD and related functions are assembled: 308 DOS/VS Supervisor & I/O Macros A2 A3 DS DS END 40BC 40BC In the card-file and the disk-file assemblies, a USING statement was added because certain routines are segregated from the main program and moved into the DTF assembly. 9D EXTRN END (2) LBRET 2 o X X X X X When your routines, such as error, label processing, or EOF routines, are segregated from the main progrm, it is necessary to establish addressability for these routines. You can provide thi5 addressability by assigning and injtializing a base register. In the special case of the EOF routine, the addressability is established by logical IOCS in register 14. For error exits and label-processing routines, however, this addressability is not supplied by logical IOCS. Therefore, if YO'u segregate your error routines, it is your responsibility to establish addressability for them. Figure B-4 contains the printer output. to show the coding of Example 3 would look when assembled. In Figure B-4, the standard name was generated for the logic modules: statement 13 of the DTFCD--V(IJCFZIWO), and statement 12 of the DTFSD--V(IJGtOZZZ). These module names appear in the External Symbol Dictionary of each of the respective logic module assemblies. Your Program •• • OPEN GET : DTF's (Au.~led Separately) CARDS,DISK-O·~------------·~DISK r-L-O_-J CARDS,(2) : •• -CARDS ~------------------~ CARDS DTFCD : L............ DISK DTFSD DEVADDR=SYS004 •••••••••••••••••••••••••••••••••••••••••••• EOFADDR~OFCD ··IOAREA1=Al : WORKA=YES : SEPASMB=YES ; BLKSIZE=408 IOAREA1=A2 ••••••••••••• •••••••• IOAREA2=A3 : IOREG= (2) : LABADDR=MYLABELS ••• : I I RECFORM~IX8LK RECSIZE=tlO TVPEFLE=OUTPUT SEPASMB=YES I ~'-------------------~ A 1 (Buffer Area) Il 111111111111111111111111111- 00, 00 : , ~:--------------~ EOFCD (End-of-File Proceui~) •• •• • I • CDMOD (Separately Assembled) (Logic for a Card File) Figure B-3. I I I I I A2 ("/fo, Area) I I 1II11111111111111111111111~"""'" I r----------..J •• •• •• t i I A3 (Buffer Area) : 00 000-\11111111111111111111111111 I I J SDMODFO (Separately Assembled) (Logic for a Disk File) •• •• • • Logic Modules and DTFs Assembled Separately (Example 3) Appendix B 309 ~--------------------------------------------------------------------------- MAIN PROGRAM PAGE EXTERNAL SYMBOL DICTIONARY SYMBOL TYPE ID CDTODISK CARDS DISK SD ER ER ADDR LENGTH LD ID 01 000000 000090 02 03 Section definition. Control section defined by START statement. Extemal reference. } Extemal reference., Defined by EXTRN statement. ---------------------------------------------------------------------------EXAMPLE 3 LOC OBJECT CODE ADDRl ADDR2 000000 000000 05CO 000002 000002 41DO C03E 00040 000006 000008 000008 OOOOOC OOOOOE 000010 000014 000018 OOOOle 0100 4110 C086 loBFF 0100 4500 COLA 00000000 00000000 OA02 00088 OOOOlE 000022 000024 000028 5810 e08E 1802 58Fl 0010 45EF 0008 00090 00002e 000030 000034 000038 000040 5alO 58Fl 45EF 41FO 00094 00010 OOOOC OOOlE e092 0010 oooe e01C 000000 000088 5B5Be2D6D7C5D540 000090 00000000 :)00094 00000000 OOOlC 00010 00008 STMT SOURCE STATEMENT PAGE DOS/VS ASSEMBLER V 28.0 09.44 13-05-16 1 CDTODISK START 0 2 BALR 12,0 INITIALIZE BASE REGISTER ESTABLISH ADDRESSABILITV 3 USING *,12 LA 13,SAVEAREA 4 USE REGISTER 13 AS POINTER TO SAVE 5 * OPEN THE FILE 6 OPEN CARDS,DISK OPEN BOTH FILES 1+* IOCS - OPEN - 5145-SC-IOX - REL. 28.0 8+ CNOP 0,4 9+ DC OF'O' 10+ LA 1,=C'$$BOPEN' 5-0 11+ SR 15,15 ZERO R15 FOR ERROR RETURN 12+ NOPR 0 WORD ALIGNMENT 5-0 13+IJJ00001 BAL 0,*+4+4*13-1) 14+ DC AICARDS) 15+ DC AIDISK) 16+ SVC 2 17 NEXT GET CARDS,(2) READ ONE CARD, MOVE TO WORK AREA 18+* IOCS AND DEVICE INDEPENDENT I/O - GET - 5145-SC-IOX - REL. 28.0 19+NEXT L 1,=AICARDS) GET DTF TABLE ADDRESS 20+ LR 0,2 GET' WORK AREA ADDRESS 21+ L 15,16(1) GET LOGIC MODULE ADDRESS 22+ BAL 14,8(15) BRANCH TO GET ROUTINE 23 PUT DISK WRITE ON DISK 24+* 10CS AND DEVICE INDEPENDENT I/O - PUT - 5745-SC-IOX - REL. 28.0 25+ L 1,=AIDISK) GET DTF TABLE ADDRESS 3-5 26+ L 15,16(1) GET LOGIC MODULE ADDRESS 3-5 27+ BAL 14,12(15) BRANCH TO PUT ROUTINE 28 B NEXT GO FOR NEXT CARD 29 SAVE AREA DS 9D 72-BYTE SAVE AREA 30 EXTRN CARDS,DISK END CDTODISK 31 32 =C'$$BOPEN ' 33 =AICARDS) 34 =AIDISK) ~--------------------------------------------------------------------------- Figure 8-4. Separate Assemblies, (Example 3) (Part 1 of 4) 310 DOS/VS Supervisor & I/O Macros DTFCD ASSEMBLY EXTERNAL SYMBOL DICTIONARY SYMBOL TYPE ID CARDSC CARDS IJCFlIWO DISK SD LD ER ER O~ ADDR PAGE LENGTH LD ID 000000 OOOOAO 000000 O~ 02 03 SectIon defInitIon. } by label defInitIon (entry poInt). Generated .-c lf ylng SEPASMIooYES In DTFCD macro. External reference. Correlponda to V-type add.... conatont generated In DTFCD. Extemal reference. Deftned by EXTRN .tatement. PAGE EXAMPLE 3 LOC OBJECT CODE ADDR~ ADDR2 STMT ~ DOS/VS ASSEMBLER V 28.0 09.44 T3-05-J,6 SOURCE STATEMENT CARDS DTFCD DEVADDR-SYS004, SEPASMB-YES, EOFADDR-EOFCD, X X X X IOAREA~-A~, 000000 000000 000000 000006 000007 000008 OOOOOC OOOO~O OOOOii 0000i4 0000305 0000i6 oooon OOOOll OOOOiC OOOOD 000020 000028 00002C 000032 000032 000080000000 O~ 04 00000020 00000000 00 000000 02 Oi 02 02 0000004C 00 00000034 0200001tC20000050 4700 0000 00000 D24F DOOO EOOO 00000 00000 000032 0700 000034 4~J.O E06E UFF 0700 4500 EO~6 00000000 00001tit 00000000 000041 OA02 000034 000031 OOOOJA 00003C 0000lt0 00001tA OAOE 0000ltC OOOOAO '.'IC2C3D3D3D6E2C' OOOAO 00041 ~ WORKA-YES 2+* IOCS AND DEVICE INDEPENDENT 110 - DTFCD - 5145-SC-IOX - REL. 28.0 3+ PUNCH' CATALR CARDS,4.0'- 4-0 4+CARDSC CSECT 5+ ENTRY CARDS 6+ DC OD'O' 7+CARDS DC X'000080000000 , RES. COUNT,COM. BYTES,STATUS BTS 8+ DC AL~(~) LOGICAL UNIT CLASS 9+ DC AL~(4) LOGICAL UNIT ~O+ DC A(IJCXOOO~) CCW ADDRESS ~~+ DC 4X'00' CCB-ST BYTE,CSW CCW ADDR. ~2+ DC AL~(O) SWITCH 3 4-0 ~3+ DC VL3(IJCFZIWO) ADDRESS OF LOGIC MODULE 3-3 ~4+ DC X'02' DT~ TYPE CREADER) ~5+ DC AL~C~) SWITCHES ~6+ DC AL~(2) NORMAL COMM.CODE ~7+ DC AL~(2) CNTROL COMM.CODE ~8+ DC ACA~) ADDR. OF IOAREA~ ~9+ DC AL~CO) JJ 20+ DC AL3(EOFCD) EOF ADDRESS JJ 2~+IJCXOOO~ CCW 2,A~,X'20',80 22+ NOP 0 LOAD USER POINTER REG. 23+ MVC 0(80,S3),OC~4) MOVE IOAREA TO WORKA 24+IJJZOOO~ EQU • 25 USING .,~4 ESTABLISH ADDRESSABILITY 26 • CLOSE THE FILE 27 EOFCD CLOSE CARDS ,DISK END OF FILE ADDRESS FOR CARD READER 28+* IOCS - CLOSE - 5145-SC-IOX - REL. 28.0 29+ CNOP 0,4 3O+EOFCD DC OF'O' 3~+ LA ~,-C"'BCLOSE' 32+ SR I ~5,~5 ZERO R i5 FOR ERROR RETURN 5-0 33+ NOPR 0 WORD ALIGNMENT 5-0 3lt+IJJC0002 BAL 0,.+4+4*C3-~) 35+ DC ACCARDS) 36+ DC ACDISK) 37+ SYC 2 38 EOJ 39+$ SUPYR COMMN MACROS - EOJ - '74'-SC-SUP - REL. 28.0 1tO+ SYC i4 4i EXTRN DISK 42 Ai DS 10C CARD 110 AREA 43 END ItIt -C'''.CLOSE' ~--------------------------------------------------------------------------- Figure B-4. Separate Assemblies, (Example 3) (Part 2 of 4) Appendix B 311 ~-------------------------------------------------------------------------- DTFSD ASSEMBLY EXTERNAL SYMBOL DICTIONARY SYMBOL TYPE ID DISKC DISK IJGFOZZZ SD LD ER ADDR PAGE LENGTH LD ID 01 000000 0003»4 000000 02 Section definition. } label definition (entry point). Generated by tpeelfylng SEPASMB-YES In DTFSD macro. Extemal ...ference. C~onds to V-type addr... constont generated In DTFSD. 01 ~-------------------------------------------------------------------------- PAGE EXAMPLE 3 LOC OIJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT 1 DISK 000000 000000 000000 000006 000007 000008 OOOOOC 000010 000011 000014 000015 000016 OOOOD OOOOlE 000024 000026 000027 000028 000029 00002C 000030 000034 000036 00003A 00003C 000040 000041 000042 000044 000048 000049 00004A 00004C 000051 000052 000054 000058 00005C 000060 000064 000065 000061 000070 000071 000080040DOO FF FF 00000068 00000000 00 000000 20 49 C4C9E2D2404040 04 000000000000 0000 08 00 00 OOOOAO 000000A4 80000000 0000 00000000 0000 OOOOFFOO 00 00 0190 00000000 17 04 OlaF FFFFFFFFFF 00 32E6 5821 0058 OOOOOOAC 00000050 00000231 OA 000000 0700003A40000006 310OOO3C40000005 0100007000000000 00058 DTFSD DOS/VS ASSEMBLER V 28.0 09.44 73-05-16 ILKSIZE-408, SEPASMI-YES, IOAREA1-A2, IOAREA2-A3, IOREG-(2), LAIADDR-MYLAIELS, RECFORM-FIXILK, RECSIZE-80, TYPEFLE-OUTPUT, DEVICE-3330 2+* SEQUENTIAL DISK IOCS - DTFSD - 5745-SC-DSK - REL. 28.0 3+ PUNCH' CATALR DISK,4.0' 4-0 4+DISKC CSECT 5+ ENTRY DISK 6+ DC OD'O' X'000080040000 , CCI 7+DISK DC 8+ DC AL1(255) LOGICAL UNIT CLASS AL1(255) LOGICAL UNIT NUMIER 9+ DC 10+ DC ACIJGC0001) CCI-CCW ADDRESS 11+ DC 4X'OO' CCI-ST IYTE,CSW CCW ADDRESS 12+ DC AL1CO) 3-3 13+ DC VL3CIJGFOZZZ) 3-8 14+ DC X'20' DTF TYPE 15+ DC AL1(73) OPEN/CLOSE INDICATORS 16+ DC CL7'DISK' FILENAME X'04' INDICATE 3330 4-0 17+ DC 18+ DC 6X'OO' ICCHHR ADDR OF Fl LAIEL IN VTOC 19+ DC 2X'OO' VOL SEQ NUMBER 20+ DC X'80' OPEN COMMUNICATIONS IYTE 21+ DC X'OO' XTENT SEQ NO OF CURRENT EXTENT 22+ DC X'OO' XTENT SEQ NO LAST XTENT OPENED 23+ DC AL3CMYLAIELS) USER'S LAIEL ADDRESS 24+ DC ACA2) ADDRESS OF IOAREA 4-0 25+ DC X'80000000' CCHH ADDR OF USER LABEL TRACK 26+ DC 2X'OO' LONER HEAD LIMIT 27+ DC 4X'OO' XTENT UPPER LIMIT 28+DISKS DC 2X'OO' SEEK ADDRESS-II 29'+ ])C X'OOOOFFOO' SEARCH ADDRESS-CCHH 30+ DC X'OO' RECORD NUMBER 31+ DC X'OO' KEY LENGTH 32+ DC H'400' DATA LENGTH 33+ DC 4X'OO' CCHH CONTROL FIELD 34+ DC AL1(23) R CONTROL FIELD 1'00000100' 3-2 ~:: ~ H'399' SIZE OF ILOCK-l 3-7 37+ DC 5X'FF' CCHHR IUCKET 38+ DC X'OO' 39+ DC H'13030' TRACK CAPACITY CONSTANT 40+ L 2,88(1) LOAD USER'S IOREG 4-0 41+ DC AeA2+8) DEILOCKER-INITIAL POINTER 42+ DC F'80' DEILOCKER-RECORD SIZE 43+ DC 3-9 AeA2+8+400-l) DEILOCKER LIMIT 44+ DC ALlelO) LOGICAL INDICATORS AL3eO) USER'S ERROR ROUTINE 45+ DC 7,*-46,64,6 SEEK 46+IJGCooOl CCN X'31',.-52,.4,5 SEARCH ID EQUAL 47+ CCN 8,.-8,0,0 TIC 41+ CCN X X X X X X X X X --------------------------------------------------------------------------Figure 8-4. Separate Assemblies, (Example 3) (Part 3 of 4) 312 DOS/VS Supervisor & I/O Macros ~-------------------------------------------------------------------------- DTFSD (Continued) EXAMPLE 3 LOC 00 000080 000088 000090 000098 OOOOAO OOOOAO 0000A2 OBJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT 49+ 50+ 5l+ 52+ 53+IJJZOOOl 54 MYLABELS 55 56 * 57 * 58 59+* IOCS 60+ 6:1. A2 62 A3 63 1D00023C00000198 3l00003C40000005 0800008800000000 lE0000983000000l 05AO 0000A2 OA09 0000A4 00023C PAGE 2 DOS/VS ASSEMBLER V 28.0 09.44 73-05-l6 CCW X'lD',A3,0,400+8 WRITE COUNT KEY AND DATA CCW X'3l',DISKS+2,64,5 SEARCH ID EQUAL CCW 8,*-8,0,0 TIC CCW 30,*,48,l VERIFY EQU * BALR lO,O INITIALIZE BASE REGISTER USING *,lO ESTABLISH ADDRESSABILITY USER'S LABEL PROCESSING ROUTINE LBRET 2 RETURN TO LIOCS LBRET - 5745-SC-IOX - REL. 28.0 SVC 9 BRANCH BACK TO IOCS DS 408C FIRST DISK 1/0 AREA DS 408C SECOND DISK 1/0 AREA END * * --------------------------------------------------------------------------CDMOD ASSEMBLY EXTERNAL SYMBOL DICTIONARY SYMBOL TYPE ID I-lCFZIWO SD ADDR LENGTH LD ID Ol 000000 000060 Section definition. CSECT name generated by CDMOD macra. EXAMPLE 3 LOC OBJECT CODE ADDRl ADDR2 STMT 2 3 73 SOURCE STATEMENT PRINT NOGEN CDMOD DEVICE=2540, SEPASMB=YES, TYPEFLE=INPUT, WORKA=YES END x X X X --------------------------------------------------------------------------SDMODFO ASSEMBLY EXTERNAL SYMBOL DICTIONARY SYMBOL TYPE ID I JGFOZZZ SD ADDR LENGTH LD ID Ol 000000 000lD4 Section definition. CSECT name generated by SDMODFO macro. --------------------------------------------------------------------------'EXAMPLE 3 LOC OBJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT 2 3 l69 PRINT NOGEN SDMODFO SEPASHB=YES END x [-------------------------------------------------------------------------~ Figure 8-4. Separate Assemblies, (Example 3) (Part 4 of 4) Appendix B 313 The DTF assembly generates a table that contains no executable code. Each of the DTF tables is preceded by the appropiate CATALR card. These two object decks can be cataloged as follows into the relocatable library together with the logic modules: II JOB CATRELOC (DTFCD Assembly) DTFs and LOGIC MODULES MA IN PROGRA~1 The main program is identical to Example 3 except the following four cards are inserted aft~r the card marked (2): Al A2 A3 II EXEC MAINT DS DS DS ENTRY 80C 408C 408C Al,A2,A3 The separate assembly of logic modules is identical to Example 3. (DTFSD Assembl,x) (CD~10D EXAMPLE 4: ASSEMBLED SEPARATELY, I/OC AREAS WITH Assembly) In the card-file assembly of Exam~le 3, replace the card marked (3) wlth he following card: (SDMODFO Assembly) 1* EXTRN Al Alternately, the object decks from these assemblies (DTF tables and logic modules) can be furnished to the linkage editor along with the main-program object deck. The sequence follows: EXTRN A2,A3 II JOB CATALOG II OPTION Figure B-5 shows the separation of the logic modules, DTFs and 1/0 areas. CATA~ INCLUDE PHASE name,* (Object deck, main program) (Object deck, DTFCD as s emb ly) (Object deck, DTFSD assembly) (Object deck, CD~1OD assembly) (Object deck, SDMODFO assembly) 1* II EXEC LNKEDT 1& Note: It is not necessary to remove the card because the linkage editor bypasses it. ~LR 314 DOS/VS Supervisor Similarly, in the disk-file assembly of the previous example, replace the cards marked (4) and (5) with the following card: & I/O Macros . Vour Program DTF's (Assembled Separately) • •• OPEN GET : CARDS,DISK- 0 - - CARDS, (2) L... - - 0 - - - . - --- - - - - - - - DISK f-C....,AR_D_S_ _ _ _ _ _ _....., •• • DISK DTFSD CARDS DTFCD DEV AD DR =SV 5004 EOFADDR=EOFCD -0- -IOAREA 1=A 1 WORKA=¥ES SEPASMB=VES 00000000000000000000000.0000000 000000000000 0 r 1 A 1 (Buffer Area) 1I1111111111111111111111111-"PO" I A3 (Buffer A.-a) 111111111111111111111111111- - , EOFCD (End-of-File Processing) I - - - - - - - - - - -.... ~-------------~ •• • •• I - r - I I I I I I I I I I I I -0- J : I I I I A2 (Buffer ANa) 1111111111111111111111 III If.- - ~ - BLKSIZE=408 - -0-IOAREA1=A2 -0- -IOAREA2=A3 IOREG= (2) o• oLABADDR=MVLABELS RECFORM=FIXBLK RECSIZE=80 TVPEFLE=<:>UTPUT SEPASMB=VES 0 -0- - - - 1- - - - - - .JI : -0- - - - - - - - - I _J I I I I I I J---------~~J I • • • SDMODFO CDMOD (Logic for a Card File) •• ••• • Figure 8-5. (Logic for a Disk File) •• •• •• Logic Modules and DTFs Assembled Separately, I/O Areas with Main Program (Example 4) Appendix B 315 EXAMPLE 5: ASSEMBLING OTFs AND LOGIC RODU[ES SEP~R~TE[V: 170 ~RE~S, [~BE[ EXIT, ~ND END-OF-FI[E EXIT ~ITR M~IN COTOOISK PROGR~M In addition to the changes in Example 4, the label exit and the end-of-f,le ex,t may be assembled separately. Figure B-6 shows these separate assemblies. The main program is assembled: NEXT SAVEAREA EOFCO START BALR USING LA OPEN GET PUT B OS 0 12,0 *,12 13,SAVEAREA CARDS,DISK CAROS,(2) DISK NEXT 90 CLOSE EOJ CAROS,DISK LBRET 2 EXTRN DS OS OS ENTRY END CARDS,DISK 80C 408C 408C Al,A2,A3,EOFCD,MYLABELS COTODISK MYLABELS Al A2 A3 316 DOS/VS Supervisor & I/O Macros I Your Program DTF's (Assembled Separately) •• • OPEN GET : CARDS,DISK-O- CARDS, (2) L.. - ·•• - -0- - - - - - --- - - - - - - - DISK !-CARDS ~----------------~ • CARDS DTFCD DISK DTFSD DEY AD DR =SYSOO4 -O-EOFADDR=EOFCD -IOAREA1=Al WORKA=¥ES SEPASMB=YES r - - - - - - - -- r0- I I I I I I r- - I t I I I I A 1 (Buffer Area) I 111111111111111111111111111+- - -0 I I I A2 (Buffer Area) A3 (Buffer Area) I I -0- - - - .L - - - - _...J I I I 0111111011111111111111111-- - -0- - - ! I I I J : 9_t III - - - - I I I I I I I I ~~~~~~UTPUT SEPASMB=YES 1 MYLABELS ! L?-(Yf'p.ouHnel - - J I I I :• I • I • ___________ J I I EOF.CD (End-af-File Praeeulr.a) BLKSIZE=408 -O-IOAREA 1=A2 -IOAREA2=A3 IOREG= (2) rOo LABADDR=MYLABELS I RECFORM=FIXBLK - I r - -0I I I I I 11111111111111111111111111..... - - I I I I -' i • SDMODFO CDMOD (Logic for a Disk File) (Lagle far a Card FUe) •• •• •• •• •• •• Figure B-6. DTFs, and Logic Modules Assembled Separately; I/O Areas, Label Exit, EOF Exit with Main Program (Example 5) The file definitions are separately assembled: DISK DTFSD BLKSIZE=408, TYPEFLE=OUTPUT, SEPASMa=YES, X X X ICAREAl=A2, IOAREA2=A3 A2,A3,MYLABELS X Col. 72 CARDS DTFCD EXTRN END DEVADDR=SYSOO4, WORKA=YES, EOFADDR=EOFCD, SEPASf4B=Y ES, IOAREAl=Al EOFCD,Al X X X X EXTRN END Appendix B 317 The separate assembly of logic modules is identical to Example 3 and Example 4. Comparison of the Five Methods Exam~le 1 requires the most assembly time and he least link-edit time. Because the linkage editor is substantially faster than the assembler, frequent reassembly of this program requires more total time for program preparation than examples 2 th rough 5. Example 2 segregates the lacs logic modules from the remainder of the program. Because these modules are generalized, they can serve several different applications. Thus, they are normally retained in the system relocatable library for ease of access and maintenance. When a system pack is generated or when it requires maintenance, the lacs logic modules that are required for all applications should be identified and generat·ed onto it. Each such modu1 e requires a separate assembly and a separate catalog operation, as shown in examples 2 through 5. Many assemblies, however, can be batched together as can many catalog operations. Object programs produced by COBOL, PL/I, and RPG require one or more IOCS logic modules in each executable program. These modules are usually assembled (as in Example 2) during generation of a system pack and are permanently cataloged into the system re10catab1e library. Example 3 shows ho~ a standardized lacs package can be separated almost totally from a main program. Only the imperative 318 DOS/VS Supervisor & I/O Macros lacs macros OPEN, OPENR, CLOSE, CLOSER, GET, and PUT remain. All file parameters, label processing, other lacs exits, and buffer areas are preassembled. If there are few lacs changes in an application compared to other changes, this method reduces to a minimum the total development/maintenance time. Thi~ approach aJso serves to standardize file descriptions so that they can be shared among several different applications. This reduces the chance of one program creating a file that is improperly accessed by subsequent programs. In example 3, you need only be concerned with the record format and the general register pointing to the record. You can virtually ignore the operands BLKSIZE, LABADDR, etc. in your program, although you must ultimately. consider their effect on virtual storage, job-control cards, etc. In example 4, a slight variant of example 3, the I/O buffer areas are moved into the main program rather than being assembled with the DTFs. In example 5, the label processing and exit tunct,ons are also moved into the main program. 4 and 5 show how buffers and lacs fac, ,t,es can be moved between main program and separately assembled modules. If user label processing is standard throughout an installation, label exits should be assembled together with the DTFs. If each application requires special label processing, label exits should be assembled into the main program. Exam~les APPENDIX B.l: ASSEMBLING A FORMAT RECORD FOR THE 3886 OPTICAL CHARACTER READER This section 3886 Optical are a sample assembly and 3886. 1 The job control language (JCL) statements indicate that the job is an assembly. The output of the assembly is to be cataloged with the phase name FORMAT. describes a use for the IBM Character Reader. Included document, a format record the data provided by the 2 The DFR macro specifies the characteristics common to all lines on the document: Document Example A typical application for an optical character reader is processing insurance premiums. Figure B-7 shows an insurance premium notice for the Standardacme Life Insurance Company. The document .has three lines of data to be read (see Figure B-4 for sample data). The first line contains one field, the name of the policy holder. The second line contains four fields: the second line of the policyholder's address, the policy number, the premium amount due and a code to be hand printed if the amount paid is different from the amount due. The third line contains one fiald that contains the amount paid if different from the amount due. Format Record Assembly Example To process documents like that in Figure B-7, one format record is used. The format record must be created in a separate assembly. The coding necessary to create the format record is shown in Figure B-8. The numbers at the left of the coding form correspond to those in the following text. FONT=ANAl: The alphameric OCR-A font is used for reading any fields that do not have another font specified in the DLINT macro field entries. REJECT=&: The commercial at sign (@) is substituted for any reject characters encountered. EDCHAR=(',',.): The comma and period are removed from one or more fields as indicated in DLINT entries (line 2, field 3). 3 The OLINT macro describes one line type in a format record described by the OFR macro. The following information is provided about the first line: LFR=1,LINBEG=4: The first line on the document has a line format record number cf 1. The first field read from the line begins four-tenths of an inch from the ST ANDARDACME LIFE NOTICE OF PAYMENT DUE INSURANCE COMPANY MO DUE DATE DAY ANNIV MONTH YR 06 23 72 07 DIST NO PREMIUM 249.75 45 DALE E. STUEMKE 1 1363 SE 10TH AVE. ROCHESTER, MINN 58395404 POLICY NUMBER 249.75 $ AMOUNT DUE INSURED DAWN STUEMKE I' IS other than shown, please nolily the ----------J-~ Company Please make check or money order payable to Standardacme Llle and present With nollce to your Company Representative or to • '---_ _ _ _ _ _ _ __ If your address PLEASE Figure B-7. RETURN WITH YOUR PAYMENT FOR COMPANY USE ONLY Premium Notice Example Appendix B. 1 319 left edge of the document. The data record is in the standard mode; editing is performed on the field. FLD1=(32,20,NCRIT),EDIT1=HLBLOF: The first and only field on the line ends 3.2 inches from the left edge of the document, the edited data is placed in a 20-character field. The field is not considered critical. All leading and trailing blanks are removed, the data should be leftjustified, and the field is padded to the right with blanks. The second line on t~e document is described as follows: LFR=2,LINBEG=4: The s~cond line of the document has a line f6rmat record number of 2~ The first field read begins fourtenths of an inch from the left edge of the document. The data record is in standard mode; editing is performed on all fields on the line. FLD1=(30,20,NCRIT),EDIT1=HLBLOF: The first field on the line ends 3.0 inches from the left edge of the document, the edited data is placed in a 20 byte field. The field is not considered critical. All leading and trailing blanks are removed, the data is left-justified, and the field is padded to the right with blanks. FLD2=(42,8),EDIT2=ALBNOF: The second field ends 4.2 inches from the left edge of the document, the edited data is placed in an eight-byte field, the field is critical. All leading and trailing blanks are removed from the field. The resulting field must be eight digits in length or a wrong length field indicator is set. 320 DOS/VS Supervisor & I/O Macros F~D3=(54,6),EDIT~=HLBHIF,EDCHAR: The third field ends 5.4 incnes from the left edge of the document, the edited data is placed in a six-byte field, the field is.critical. All leading and trailing blanks are removed, the data is right-justified, and the field is padded to the left with zeros. A comma, if present, and the decimal point are removed ,from the edited field. FLD4=(62,1,HHP1),EDIT4=ALBHIF: The fourth field ends 6.2 inches from the left edge of the document, the edited data is placed in a one-byte field, tH~ field is critical and is read using the numeric handprinting norma 1 mode. All b1an ks are. removed, th e data is right-justified, and the field is padded to the left with zeros. The third line on the document is described as follows: LFR=3,LINBEG=45: The third line on the document has a line format r~cord number of 3. The field to be read begins 4.5 inches from the left edge of the document. The data record is in standard mode; editing is performed. FLD1=(63,7,NHP1),EDIT1=ALBHIF: The field on th1S line ends 6.3 inches from the left edge of the documen~, th~ edited da~a is. placed in a seven-byte f1eld, the f1eld 1S critical and ts read using the numeric handprinting normal mode. All blanks are removed, the data is right-justified, and the field is padded to the left with zeros. FREND=YES: This is the format record end. No DLINT macros follow this statement. IBM PUNCHING PlOGRAINM.I - . I. DATE " I. '" Jk)B flO RM AT 10 P T I C~ CiA TAL PH ASE fO RIM AT ,+ 0, NP AU TO I I EX EC ~S SE 1MB LV , T IT LE '0 ~C L I ST - f "R ~A T ' ST ART II I I O~r;nd OpeftillOft 3• ~h""II.U " S I GRAPHIC INSH'UCTIONS 1 xa-_-4WMIIZ' IBM Ilyat8m/360 AoNmllle. CodIJlg 'arm ""GUM I I I PUNCH I I I I I'AGE ICAID ELlCTtO NUMlfI STATEMENT ... " -. * w-tInUlfI..- ., CO'IUI'III"II " '" 60 " 71 73 ** *,.** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** * .. ** ** ** ** ** ** ** ** ** ** ** ** ** ~* ** *** * I I * .... * TH IS AS SE ~B L~ ~ ILL CR EA TE A FO R~ IAT RE clo RO 10 ESC R I B I NG AN * * IN SU RA NCE PR E~J U~ INP T I C E , I i * * ** ** ****'**** ** **1* ** 1"* ** ** ** ** ****t* ** --***- r---c- ** *** ** ** ** ** ** ** ** ** ** ** ** ** ** * , :i I : I I ; I I I ,' ! I : I F R' if'" NT -A NA 1 , REj1E CT_ !Ci1, E DC HA R--- (,' LIN T L f R- 1, L I NB EG-", FL 01 ( 32 ,2 0, NC R I T ) ED IT 1 - HL B L f OL 111'01 T Lf R- 2 , L I NB EG , f L01 ( 30 ,2 0, ~C R I T ) , ED IT 1 - HL IL ~f 0 0 FL 02 ! I I : I ! i: - " .) X X -" ( 42 ,8 ) , ED IT 2- AL BN Of, fL 03 ( 5" ,6 ) , ED IT 3- ( H L BHI F , ED CH AR fL 10" ( 62 ,1 ,N HP 1) , - i ) , i X X X X X X X X I i I It ttandord cord form, 11M electro 6509, is avollobl. for punching tOurce ,totements from th" form. Inltrvctlons for utlng thIS form are in any laM Sys,."j360 Anembler R.ference Nonuol AdcIr... COf'/WI'Ief'Ih eonc.nu'SJ this fofm to IBM Corporation, Programming PublicotlOM, Deportmlfnt 232, San Jos., California 9511 ... Figure 8-8. Format Record Assembly Example (Part 1 of 2) Appendix B.l . A Of 321 11M 11M . . . . . . -• I. II EX E~ -r PUNCH_ • II a.o- . - '" .. . INSTlUCTIONS Dolfi ~ 10 ." " «I ~ I """'" I 10 • KE DT I~ ·A .... _.IIM ......... ._ . ._ . -........ It _ _ ... _ _ --..It_ .. It .................'.. _ _ ..... "'It-. ..,IIM~ Figure B-8. _ _ _ ,. • . . . . - . . .... _ ..... IIM~ ~232, SooJoto, C.Ufomlo95I1•• Format Record Assembly Example (Part 2 of 2) 322 DOS/VS Supervisor & I/O Macros ~ 1H-' .. u.s.A. T OIAPHIC STAIIMlNT ED IT 14- IAL Itt If 5. ID l INT L. I . 3. L I NI Ui • !, .N HP 1 ) fL Dl ( ED IT 1~ ~L IH If. fl EI~ ID- YES END L~ ........ ---WIllI'" 1- 55 c- I I I I I I .. MOl 01 I I~ " X X X - ....... . • Line 1: Header Record: (20 Bytes) Data Record: (130 Bytes) 01011000000000000000 DALEbE. bSTUEMKEb b b b b b ... b . -----v-~----------V ---------~ ~ Policyholder Field Pad to 130 Bytes Line 2: Header Record: (20 Bytes) Data Record: (130 Bytes) 02021000000000000000 ROCHESTER, bMINNb b b b b58395404024975 ob ... b Address Field ~ Policy Amount f 130 Bytes Number Due Lcode Line 3: Header Record: (20 Bytes) Data Record: (130 Bytes) Figure 8-9. 03031000000000000000 OOOOOOOb ... b ~ Amount Pad to Paid 130 Bytes Sample Data '\ Appendix B.t 323 APPENDIX C: READING, WRITING, AND CHECKING WITH NONSTAN· DARD LABELS - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - - - - - - - -- -- ---EXTERNAL SYMBOL DICTIONARY SYMBOL TYPE ID JJCFllZO IJFFZZlZ IJFFBlZZ IJDFZZZZ IJ210006 PC Eit ER ER Era SD TEST lOC AOCIt lENGT~ PAGE lO ID 01 003COO oeolt8c 02 03 04 05 06 003490 00CC64 CREATING AND PROCESSING NON-STANCARO OBJECT COCE ADDRI ADCR2 STHT SOURCE STATEMENT DOS/VS ASSEMBLER V 28.0 09.44 73-05-16 PRINT ON,NOGEN.NODATA START 12288 2 3 003000 PAGE. lAB~lS 4 • 5 READER 26 • 27 TAPEOUT 58 * 59 TAPEIN 93 94 129 130 151 152 221 222 003lAC 0520 003lAE 223 224 225 226 234 003106 47FO 2010 0311!E 239 244 245 2~3 2~4 003216 47FO 2050 031FE 2(:3 268 273 274 282 283 291 2~6 003252 47FO 20BC 0323A 301 302 311 317 320 00327A 4900 22A6 03454 oo327E 4770 20FO 032~E 003282 0227 221e 21ce 033CA 0337A Figure C-l. 321 322 323 324 328 334 DTFeD OEVICE-2540,DEVADDR-SYSIPT,BLKSIZE-80,TYPEFLE-INPUT, EOFADDR-ENOCARD,IOAREA1-IOAREA OTf"T NSTCOC04 NSTD0005 NSTC0006 *NSTD0007 NSTD0008 NSTDOC09 DEVADDRcSYS004,IOAREA1 c IOAREA,BlKSIZE-80,TYPEFlE-OUTPUT,.~STDOOI0 lABAODR-lABElOUT,REAO·FGR~ARO,FIlABL-NSTD NSTDOOll NSTD0012 ·OTf"T DcVADDR-SYS004,IOAREA1-IOAREA,BLKSIZE-80,TYPEFLE c INPUT, .NSTOOC13 EOFADDR-ENDTAPE,REAOcfCRWARD,FILABL-NSTD,REWIND-NORWC, *NSTDOOI4 ~STD0015 LABADDR-LABELIN • NSTD0016 TAPEIN2 OTFMT OEVAOOR.SYS004,IOAREA1-IOAREA,BLKSIZEc80,TYPEFLE-INP~T, *NSTCOCI7 EOfADDR=ENOTAPE2,READ-BACK,FIlABL-NSTD NSTD0018 * NSTC0019 PRINT OTFPR OEVICE-1403,DEVAOOR-SYSLST.IOAREA1-IOAREA,BLKSIZE-80 NST00020 • NST00021 CONSOLE uTFeN BLKSIZE-80,OEVACOR-SYSLCG,IOAREA1cCAREA,RECFORM=FIXU~B, *NSTD0022 WORK A-YES NST00023 NSTOOC24 * NST00025 *START BAlR 2,0 NSTD0026 SET UP A BASE REGISTER NSTDOC27 USING .,2 "STD0028 * *. ROUTINE TO WRITE TAPE NSTDOC29 TO WRITE NSTD RECORDS OPEN TAPEOUT READ A CARC FRO~ CARO READER NSTD0030 GETCARC GET READER NSTOOC31 WRITE CARD I~AGE ON TAPE P\JT TAPEOUT BRANCH AND GET ANOTHER CARD NSTDOC32 ~ "ETeARD NSTD0033 TO wRITE NSTD TRAILER LABEL ENOCARD ClOS~ TAPEOUT ,..ST00034 * *. ROUTINE TO READ TAPE FOR~ARD NSTD0035 TO PROCESS NSTD LABEL OPEN PRINT,TAPEIN NSTOOC36 GET A CARD IMAGE FROM TAPE GETTAPE GET TAPEIN PRINT CARD IMAGE ON PRINTER NSTD0037 PUT PRINT eQANCH AND GET ANOTHER TAPE RECORD NSTD0038 8 GETTAPE NSTDOC39 ENDTAPE CLOSE TAPEIN PROCESS NSTD LABELS NSTDC040 ••• RCUTINE TO READ TAPE BACKWARDS NSTD0041 8YPASS NSTD LABELS OPE~ TAPEIN2 READ A TAPE RECORD NSTD0042' GETTAPE2 GET TAPEIN2 NST00043 PRINT RECORD PUT PRINT NST00044 BRANCH AND GET ANOTHER TAPE RECORD B GETTAPE2. BYPASS NSTC RECORDS NST00045 ENCTAPE2 CLOSE PRINT,TAPEIN2 NST00046 CNTRL TAPEIN2,REW REWIND TAPE TO LeAD POINT NSTD0047 NORMAL END OF JOB EOJ NSTOOC48 ••• LABEL CREATION ROUTINf NSTD0049 OPEN Of CLOSE LABELCUT CH O,ALPHAO NSTC0050 BRANCH IF CLOSE SNE TRAILOUT NSTD0051 ~OVE HEAOER TO 1/0 AREA MVC IOAREA(40J,HEADER NSTDOC52 WRlTf LABEL RITELAB EXCP OUTe'B NSTDOC53 WAIT FOR CCMPLETION wAIT OUTeCB NSTD0054 RETURN CONTROL TO 10CS LBkET 2 Reading, Writing, and Checking with Nonstandard Labels (Part 1 of 2) ( 324 DOS/VS Supervisor & I/O Macros TEST lOC CRE~TING OBJECT CODE AND PROCESSING NON-STAND~~O AODR1 ADDR2 ST'-T 00329E 0221 221C 21F4 033CA 033A.2 0032A4 41FO 20DA 03288 331 338 339 340 341 342 346 352 353 354 355 356 351 0032AB 4900 .22A6 (l032AC 4180 212C 03454 032CA 0032C4 9101 2210 0341E 0032C8 4710 2164 03312 C·0~2CC 0521 .221C 21F4 e33CA 033A2 003202 4180 2102 032BO 003206 41FO 2152 C3300 3E:l 0032EE 0032F2 0032F6 0032FC 9101 4710 0521 4180 0341E 2210 0331(: 2168 033CA 0331A 221C 21CC 0321:A 212C 3E:1 3(:8 369 31C 311 003312 5800 22A2 003318 4040404040404040 00334A E4E2C50~40D3CIC2 00331A E4E2C50~40C8C5C1 0033A2 E4E.2C5D940E3D9Cl 0033CA 4040404040404(40 00343A 003440 003448 0031150 003454 0031AC 003458 003460 003468 00346C 003410 003414 003418 00341C 003480 003484 003488 OOOOOOOCOOOO 020033C40000(C28 010033CAOOOO(028 0000C5C6 0006 5B5BC20601C51:540 5B5BC2C3D3C6E2C5 00003000 00003038 00003C90 00003150 000030FO 0000342A 0000341A 00003180 0000334A 03450 311 380 381 384 385 3e6 3e1 388 389 390 loCI LABELS SOLRCE STATEMENT TRAILOlT M~C CC~ X'0~',IOAREA,X'00'~40 CCw DC. DC ENO X'01',IOAREA,X'OO',40 X'0000C5C6' X'00D6' START "C'S$BOPEN ' =C'SSBCLOSE' =ACKEACER. -AC TAP EOUT) =AlTAPEIN) =A( PRINT) -ACTAPEIN2. =ACOUTCCB' -AlINCCB. .. ACCONSOLe" =ACLABELERR) 411 4le 41<; 420 421 422 423 424 425 [----------=--- ----421; 421 (40 charact...) ~ e 1 ....a USER HEADER LABEL NST00056 NSTCOC51 NST00058 NST00059 NST00060 NST00061 II.ST00062 NST00063 NSTOOC61t NST00065 NST00066 NSTD0061 NSTC'OC68 NSTD0069 NSTC0010 NSTOOOl1 NSTOOC12 NSTD0013 NSTC0014 NSTC0015 NSTC0016 NSTCOCl1 NSTC0078 NSTDOC19 NST00080 NSTD0081 NST00082 II.ST00083 NSTC0084 NSTC0085 NST00086 NSTOOC88 NSTC0089 NSTOOC90 =-=-:-__-___-__-__ :J (40 charact.n) e ....~ ~ST00055 READ TAPE CCW WRITE tAPE CCW ~ - ... )J 2 DOS/VS ASSEMBLER V 28.0 09.44 73-05-16 MOVE TRAILER LABEL TC 1/0 AREA BRANCH TO WRITE THE LABEL IOAREAC40t,TRAILE~ 8 RI TfLAB ••• LABEL P~OCESSING ROUTINE O,At.PI1AO OPEN OR CLOSE LABEll" CH BE HEADIN OPEN TIME TRAILlI'\ EXC.P INCCB READ A TRAILER LABEL wAIT INC1.8 WAtT FeR 110 CO~PLETION TM INCCB+4,X'01' TEST FOP A TAPE WARK bO EXlTEOF BRANCH IF YES JOAREA(40),TRAILER eLC CCMP~RE TRAILER LABEL TRAIUN BE BRANCH TO GET ANOTHER RECORD iI ERRLAB BRA~CH IF LABELS CC NOT COMPARE HEADIrEXCP INCCB READ A HEADER LABEL wAIT INCCB WAIT fOR CC~PLETION TM INCCIH4,X' 011 TEST FOR A TAPE MARK bU EXIT BRANCH IF YES uc. IOAREA(40) ,HEADER DOES HEADER LABEL COMPARE BE HEADIN IF YES, BR~NCH ANC READ TAPE ERRLAB PuT CONSULE,LABELERP PUT LABEL ERROR MESSAGE EOJ TERMINATE JOB EXlTEOF L O,EOFIND INCICATE ECF TO 10CS EXIT LBkEY 2 RETURN CONTROL TO 10CS • CONSTANTS CAREA DC el50' , CONSOLE 1/0 AREA LABELERR DC COUSER LABELS DC NOT C(MPARE. ABNORMAL END OF JOB.' HEAI:ER DC CL40'USER HEADER LABEL' TRAILER DC CL40'USER TRAILER LABEL' ~L&O' , INPUT/OUTP~T AREA ICAREA LIe III.CCI.I CCB SYS004,INCC~ REAC TAPE eCB CUTCC!! eCB SYS004,OUTCCW WRITE TAPE CCB 412 INCCW 413 OUTCC~ 414 E(FINC 415 ALPHAC 416 Tape Output PAGE USER TRAILER LABEL J ~ ~ ....a .... 4 ~ 11 I e 1 I No....: 1. IOCS WlOt. the first tapemarlc beca~ the TAPEMARK =NO paramet.r WCII omitted. 2. IOCS always writes the tapemarlc following the data. 3. IOCS wrot. the two tapemarks aft.r the ~r trail.r label. (40 characters) Tape Input USER HEADER LABEL \~ ~ e ....I Data ••• ~ ) )1. ~ e 1 .! (40 charact. .) USER TRAILER LABEL e 1 ....a ....a t Not.: 1. IOCS reads the first tapemark or bypaaes it if Uler labels are not checked. 2. ~ erlCCMlterlng the second tapemark IOCS branches to Your label routln. add.... 3. Alter you reod the third tapemark you should iaue a LlRET 1 ancilOCS will branch to the Ind-af-fil. add,... Figure C-l. Reading, Writing, and Checking with Nonstandard labels (Part 2 of 2) Appendix C 325 APPENDIX D: WRITING SELF-RELOCATING PROGRAMS Use: DOS/VS has the capability of executing self-relocating programs. A se1frelocating program is an assemb1erlanguage program which can be executed at any location in virtual storage. If your system does not have the relocating loader, writing a self-relocating program is then an efficient coding technique because self-relocating programs are link-edited only once for execution in any partition. When link-editing, use OPTION CATAL and a PHASE card such as: PHASE EOF Phasename, +0 This causes the linkage editor to assume that the program is loaded at storage location zero, and to compute all absolute addresses f~om the beginning of the phase. The job control EXEC function recognizes a zero phase address and adjusts the origin address to compensa~e for the current partition boundary save area and label area (if any). Control is then given tO,the updated entry address of the phase. Programs that are written using se1frelocating techniques can be cataloged as either self-relocating or non-se1frelocating phases. 2. The program must relocate all address contants used in the program. Whenever possible, use the LA instruction to load an addres in a register instead of using an A-type address constant. For example, *,12 12,0 12,0(12) 12,0 12,0 1,EOF 1,AEOF L 10,AEOF EOF EOJ AEOF DC 326 DOS/VS Supervisor A(EOF) & I/O Macros 10,EOF EOJ 4. If physical IOCS is used, the program must relocate all CCW address fields. 5. Register notation must be used with imperative 1/0 macros and supervisor macros. An example of coding the GET macro with a work area in selfrelocating format follows: RCARDIN EQU RPRTOUT EQU RWORK EQU LA LA LA OPENR GET 4 5 6 RCARDIN,CARDIN RPRTOUT,PRTOUT RWORK,WORK (RCARDIN),(RPRTOUT) (RCARDIN),(RWORK) Note: Since the DTF name can be a maximum of seven characters, an R can be prefixed to this name to identify the file, Thus, RCARDIN in this example can immediately be associated with the corresponding DTF name CARDIN. Instead of Using: USING BALR LA BCTR BCTR LA ST LA If logical IOCS is used, the program must use the OPEHR and CLOSER macro to open and close all files including console files. In general, if a problem program is written to be self-relocating, these rules must be followed: The PHASE card must specify an origin of +0. *,12 12,0 12,0(12) 12,0 12,0 3. Rules for writing Self-Relocating Programs 1. USING BALR LA BCTR BCTR 6. Use II LBLTYP before II EXEC card. The following rules apply to programs consisting of more than one control section. 7. The relocation factor should be calculated and stored in a register for future use. For register economy, the base register can hold the relocation factor. For example: USING BALR LA BCTR BCTR or *,12 12,0 12,0(12) 12,0 12,0 L AR BALR where register 12 is the base register Register 12 now cQntains the relocation factor and the program base. 8. When branching to an external address, use one of the following techniques: L BAL 15,=V(EXTERNAL) 15,=V(EXTERNAL) 15,12 14,15 9. The calling program is responsible for relocating all address constants in the calling list(s). See Figure 0-1 for an example of the calling program relocating the address constants in a calling list. 14,0(12~15) II II II JOB A OPTION LINK EXEC ASSEMBLY CSECT1 START 0 USING *,12 BALR 12,0 LA 12,0(12) BCTR 12,0 BCTR 12,0 LA LA LA LA STM 01 LA L AR CALL LIST EQU EOJ SAVEAREA DC END Use load point value as the base to find the load point value. 1 ,A 2,B 3,C Modify the CALL address constant llst. 4,D 1,4,LIST LIST+12,X'80' Restore end of list blt In last adcon. 13,SAVEAREA 15,=V(EXTERNAL) 15,12 Adjust CALL address by relocatlng factor. ( 15),(A,B,C,D) *-16 For address constants (4 bytes each). 9D'0' 1* * II EXEC ASSEMBLY CSECT2 START 0 ENTRY EXTERNAL EXTERNAL SAVE (14,12) USING *,12 BALR 12,0 Establish new base RETURN ( 14 , 1 2 ) END 1* * II EXEC LNKEDT 1& Figure D-1. Relocating Address Constants in a Calling List Appendix D 327 Advantage of Self-Relocating Programs Self-relocating programs have the ability to run in anyone of the 5 partitions without having to be link-edited again. Another Way -- The Relocating Loader Self-relocating programs are slightly more time-consuming to write and they usually require slightly mpre storage. They may only be written in as~embler-language. For these reasons you may want to use the relocating loader instead. The relocating loader accomplishes the same thing as writing self-relocating programs but without any of these disadvantages. See the DOS/VS System Management Guide, GC33-5371, for a description of the relocating loader. modified by self-relocating macros must be modified by some other technique. After the program has been link-edited with a phase origin of +0, the contents of each address constant is the displacement from the begi nni ng of the -phase to the address pointed to by that address constant. The following techniques place relocated absolute addresses in address constants. These techniques are required only when the lA instruction cannot be used. Technique 1 Named A-type address constants: lA ST 4,ADCONAME 4,ADCON Programming Techniques ADCON DC A self-relocating program is capable of proper execution regardless of where it is loaded. DTFDI should be used to resolve the problem of device differences between partitions. A self-relocating program must also adjust all its own absolute addresses to point to the proper address. This must be done after the program is loaded, and Defore the absolute addresses are used. Technique 2 Within these self-relocating programs, some macros generate self-relocating code. For example the MPS utility macros are self-relocating (that is, they modify all of their own address constants to their proper values before using them). OPENR and CLOSER macros are used in selfrelocating programs. OPENR and CLOSER can be used in place of OPEN and CLOSE, and adjust all of the address constants in the DTFs opened and closed. OPENR and CLOSER can be used in any program because the OPENR macro computes the amount of relocation. If relocation is 0, the standard open is executed. In addition, all of the module generation (xxMOD) macros are self-relocating. The addresses of all address constants containing relocatable values are listed in the relocation dictionary in the assembly listing. This dictionary includes both those address constants that are modified by self-relocating macros, and those that are not. The address constants not 328 DOS/VS Supervisor & I/O Macros A(ADCONM1E) A-type address constants in the literal poo.l: LA LA ST 3,=A(ADCONAME) 4,ADCONAME 4,0(3) lTORG =A (ADCONM1E) Technique 3 A-type address constants with a specified length of three bytes, and a nonzero value in the adjacent left byte (as in CCWs): A. If the CCW list dynamically changes during program execution: lA STCM 4,IOAREA 4,X'07' ,TAPECCW TAPECCW CCW l,IOAREA,X'20' ,100 IOAREA DS Cl100 B. If the CCW list is static during program execution: TAPECCW 10AREA lA ST MVI 4,IOAREA 4,TAPECCW TAPECCW,l CCW 1,IOAREA,X ' 20 ' ,100 DS Cl100 or USING BAlR lA 12,0(12) BCTR 12,0 BCTR 12,0 Register 12 contains relocation factor. AlR ST 11,TAPECCW 11,12 11,TAPECCW TAPECCW CCW 1, I OAREA, XI 20 I ,100 IOAREA DS Cl100 l Technique 4 Named V-type or A-type address constants: lA S l AR ST 3,ADCONAST 3,ADCONAST Determi ne Relocation factor 4,ADCON 4,3 Add relocation factor 4,ADCON ADCONAST DC ADCON DC The load point of the phase is not synonymous with the relocation factor as developed in register 3 (technique 4). If the load point of the phase is taken from register 0 (or calculated by a BAlR and subtracting 2) immediately after the phase is loaded, correct results are obtained if the phase is link-edited with an origin of +0. If a phase is linkedited with an origin of * or S, incorrect results will follow. This is because the linkage editor and the program have both added the load point to all address constants. Figure D-2 shows an example of a self-relocating program. Appendix D 329 SOURCE STATEMENTS REPRO PHASE EXAMPLE,+O +0 ORIGIN IMPLIES SELF-RELOCATION PRINT NOGEN START 0 PROGRAM BALR 12,0 US I NG ::, 12 ROUTINE TO RELOCATE ADDRESS CONSTANTS LA l,PRINTCCW RELOCATE CCW ADDRESS ST l,PRINTCCB+8 IN CCB FOR PRINTER LA l,TAPECCW RELOCATE CCW ADDRESS ST l,TAPECCB+8 IN CCB FOR INPUT TAPE IC 2,PRINTCCW SAVE PRINT CCW OP CODE LA 1,OUTAREA RELOCATE OUTPUT AREA ADDRESS ST l,PRINTCCW IN PRINTER CCW STC 2,PRINTCCW RESTORE PRINT CCW OP CODE LA l,lNAREA RELOCATE INPUT AREA ADDRESS ST l,TAPECCW IN TAPE CCW MVI TAPECCW,READ SET TAPE CCW OP CODE TO READ H MAIN ROUTINE ... READ TAPE AND PRINT RECORDS READTAPE LA l,TAPECCB GET CCB ADDRESS EXCP (1) READ ONE RECORD FROM TAPE WAIT (1) WAIT FOR I/O COMPLETION LA 10,EOFTAPE GET ADDRESS OF TAPE EOF ROUTINE BAL 14,CHECK GO TO UNIT EXCEPTION SUBROUTINE MVC OUTAREA(10),INAREA EDIT RECORD MVC OUTAREA+15(70),INAREA+10 IN MVC OUTAREA+90(20),INAREA+80 OUTPUT AREA LA l,PRINTCCB GET CCB ADDRESS EXCP (1) PRINT EDITED RECORD WAIT (1) WAIT FOR I/O COMPLETION LA 10, CHA12 GET ADDRESS OF CHAN 12 ROUTINE BAL 14,CHECK GO TO UNIT EXCEPTION SUBROUTINE B READTAPE TM 4(1),1 CHECK CHECK FOR UNIT EXEC. IN CCB YES-GO TO PROPER ROUTINE BCR 1,10 BR 14 NO-RETURN TO MAINLINE CHA12 MVI PRINTCCW,SKIPT01 SET SEEK TO CHAN 1 OP CODE EXCP (1) SEEK TO CHAN 1 IMMEDIATELY WAIT (1) WAIT FOR I/O COMPLETION MVI PRINTCCW,PRINT SET PRINTER OP CODE TO WRITE BR 14 RETURN TO MAINLINE EOFTAPE EOJ END OF JOB CNOP 0,4 ALIGN CCB'S TO FULL WORD PRINTCCB CCB SYS004,PRINTCCW,X'0400' TAPECCB CCB SYS001,TAPECCW PRINTCCW TAPECCW OUTAREA INAREA SLI READ PRINT SKIPT01 Figure D-2. CCW CCW DC DC EQU EQU EQU EQU END PRINT,OUTAREA,SLI,L'OUTAREA READ,INAREA,SLI,L'INAREA CL110" CL100" X'20' 2 9 X'SB' PROGRAM Self-Relocating Sample Program 330 DOS/VS Supervisor & I/O Macros APPENDIX E: MICR DOCUMENT BUFFER FORMAT Buffer Status Indicators Byte 0, Bit Comment o The document is ready for processing (you need never test this bit). 1 Irrecoverable stacker select error, but all document data is present. You may continue to issue GETs and READs. 2 Irrecoverable I/O error. An operator I/O error message is issued. The file is inoperative and must be closed. 3 Unit Exception. You requested disengage and all follow-up documents are processed. The LITE macro may now be issued, and the next GET or READ engages the device for continued reading. 4 Intervention required or disengage failure. This buffer contains no data. The next GET or READ continues normal processing. This indicator allows your program to give the operator information necessary to select pockets for documents not properly selected and to determine unread documents. 5 The program issued a READ, no document is ready for processing, byte 0, bits 0-2 are off, or the file is closed (byte 0, bit 6 is on). The CHECK macro interrogates this bit. Note: You must test bits 1-4 and take appropriate action. from a buffer should not be processed if bits 2, 3, or 4 are on. ~data 6 The program has issued a GET or READ and the file is closed. Bit 5 is also on. 7 Reserved with zero. Figure E-l. MICR Document Buffer Format (Part 1 of 4) Appendix E 331 Buffer Status Indicator (Continued) Byte 1, Bit o 1-7 Comment Your stacker selection routine turns this bit on to indicate that batch numbering update (1419 only) is'to be performed in conjunction with the stacker selection for this document. The document is imprinted with the updated batch number unless a late stacker selection occurs (byte 3, bit 2). Reserved with zero. Note: If bits 6 or 7 (byte 2) are on, bit 0 is ignored by the external interrupt routine. With the 1419 (dual address) only, batch numbering update cannot be performed with the stacker selection of auto-selected documents. 2·, o 1-3 For 1419 or 1275 (dual address) only. An auto-select condition occurred after the termination of a READ command but before a stacker select command. The document is auto-selected into the reject pocket. Reserved with zero. 4 Data check occurred while reading. You should interrogate byte 3 to determine the error fields. 5 Overrun occurred while reading. Byte 3 snould be interrogated to determine the error fields. Overruns cause short length data fields. When the 1419 or 1275 is enabled for fixed-length data fi~lds, bit 4 is set. 6+7 The specific meanings of bits 6 and 7 depend on the device type, the model, and the Engineering Change level of the MICR reader, but if either bit is on, the document(s) concerned is autoselected into the reject pocket. 1. 1412 or 1270: Bit 6 on indicates that a late read condition occurred. Slt 7 on indicates that a document spacing error occurred. (Unique to the 1270, both the current document and the previous document are auto-selected into the reject pocket when this bit is on. This previous document reject cannot be detected by IOCS, and byte 5 of its document buffer does not reflect that the reject pocket was selected.) • Byte 2 (bits' 4, 5, 6, and 7) and byte 3 contain tlICR sense information . •• Only for the 1259 model 34 or 1419 model 32. Bits 0 and 1 are not used for other models. Figure E-l. HICR Document Buffer Format (Part 2 of 4) 332 DOS/VS Supervisor & I/O Macros Buffer Status Indicators (Continued) Byte Bit 3 -, Comment 2. 1275 and 1419 (single address) without engineering change *125358: Blt 6 lndlcates elther a late read condltlon or a document spacing error occurred. Bit 7 indicates a document spacing error for the current document. 3. 1255, 1259, 1275, and 1419 (single or dual address) with engineering change #125358: Bit 6 indicates that an auto-select codlntion occurred while reading a document. The bit is set at the termination of the READ command before entry into the stacker select routine. Bit 7 is always zero. o Field 6 valid.-- 1 Field 7 valid.-- 2 A late stacker selection (unit check late stacker select on the stacker select command). The document is auto-selected into the reject pocket. 3 Amount field valid (or field 1 valid).-- 4 Process control field valid (or field 2 valid).-- 5 Account number field valid (or field 3 valid).-- 6 Transit field valid (or field 4 valid).-- 7 Serial number field valid (or field 5 valid).-Note: 1. For the 1270, bits 3-7 are set to zero when the fields are read without error. ') c.. • For tile 1255,1259,1275, and 1419, bits 3-7 set on \'Ihen each respective field, including bracket symbols, is read without error. This applies to bits 0, 1, and 3-7 on the 1259 and 1419 model 32. 3. For the 1255, 1259, 1275, and 1419, unread fields contain zero bits. Errors are indicated when an overrun or data check condition occurs while reading the data field. - By~e 2 (bits 4, 5, 6, and 7) and byte 3 contain MICR sense information. -- Only for the 1259 model 34 or 1419 model 32. Bits 0 and 1 are not used for other models. Figure E-1. MICR document Buffer Format (Part 3 of 4) Appendix E 333 Buffer Status Indicators (Continued) Byte Bit Comment Inserted pocket code determination by your stacker select routine. Whenever byte 0, bits 2, 3, or 4 are on, this byte is X100 1 because no document was read and your stacker selection routine was not entered. Whenever auto-selection occurs, this value is ignored. A no-op (X ' 03 1) is issued to the device, and a reject pocket value (X'CF') is placed in byte 5. The pocket codes are: (byte 2, bit 6 or 7 on). 4 Pocket A. - X'AF ' Pocket 5 - X' 5F ' Pocket B•• -X'BF' Pocket 6 - X' 6F ' Except 1270 Pocket 0 - X'OF ' Pocket 7 - X' 7F ' models 1 and 3 Pocket 1 - X' 1F ' Pocket B - X'BF ' Pocket 2 - X' 2F ' Pocket 9 - X' 9F ' Pocket 3 - X' 3F ' Reject Pocket 4 - X' 4F ' Pocket - X'CF ' The actual pocket selected for the document. The contents are normally the same as that in byte 4. 5 Note: 1. X'CF' is inserted whenever auto-selection occurs (byte 2, bit 6; byte 2, bit 7; byte 2, bit 0; or byte 3 bit 2). These conditions may result from late READ commands, errant document spacing, or late stacker selection. a. Start I/O for stacker selection is unsuccessful (byte 0, bit 1). b. An I/O error occurs (for example, invalid pocket code) on the 1419 (dual address) secondary control unit when selecting this document. Additional User Work Areas This additional buffer area can be used as a work area and/or output area. Its size is determined by the DTFMR ADDAREA operand. The only size restriction is that this area, plus the 6-byte status indicators and data portion must not exceed 256 bytes. Note: This area may be omitted. Document Data Area The document data area immediately follows your work area. The data is right-adjusted in the document data area. The length of this data area is determined by the DTFMR RECSIZE operand . • 1275, 1419, and 1270 models 2 and 4 only . •• 1275 and 1419 only. Figure E-1. ~lICR 334 DOS/VS Supervisor Document Buffer Format '(Part 4 of 4) & I/O Macros APPENDIX F: AMERICAN NATIONAL STANDARD CODE FOR INFORMATION INTERCHANGE (ASCII) In addition to the EBCDIC mode, DOS/VS accepts magnetic tape files written in ASCII, a 128-character, 7-bit code. The high-order bit in this 8-bit environment is zero. ASCII is based on the specifications of the American National Standards Institute, INnc. DOS/VS processes ASCII files in EBCDIC. At system generation time, if ASCII=YES is specified in the SUPVR macro, two translate tables are included in the supervisor. Using these tables, logical IOCS translates from ASCII to EBCDIC as soon as the data is read into the I/O area. For ASCII output, logical IOCS translates data from EBCDIC to ASCII just before writing the record. Figure F-1 shows the relative bit pOSitions of the ASCII character set. An ASCII character is described by its column/row position in the table. The columns across the top of Figure F1 list the three highorder bits. The rows along the left side of Figure F-1 are the four low-order bits. For example, the letter P in ASCII is under column 5 and in row 0 and is described in ASCII notation as 5/0. ASCII 5/0 and EBCDIC Xl 50 1 represent the same binary configuration (B 1 01010000 1 ) . However, P graphically represents this configuration in ASCII and & in EBCDIC. ASCII notation is always expressed in decimal. For example, the ASCII Z is expressed 5/10 (not 5/A). For those EBCDIC characters direct equivalent in ASCII, character (SUB) is provided translation, See Figure F-2 EBCDIC correspondence. that have no the substitute during for ASCII to Note: If an EBCDIC file is translated into 1\S"CTI" and then you translate back into EBCDIC, this substitute character may not receive the expected value. Appendix F 335 b7 0 II ~ b5 ~bt s 0 0 0 II b3 ~ 0 b2 I 0 ~ ~ 0 0 0 NUL bl 0 0 0 II Row ~' 1 0 1 0 0 1 0 1 1 1 0 1 1 1 1 0 1 1 1 2 3 4 5 6 7 DLE SP 0 @ P '\ P a q 0 0 0 1 1 SOH DCl !CD 0 0 1 0 2 STX DC2 " 2 B R b r 0 0 1 1 3 ETX DC3 /I 3 C S c s 0 1 0 0 4 EOT DC4 S 4 D T d t 0 1 0 1 5 ENQ NAK % 5 E U e u 0 1 1 0 6 ACK SYN & 6 F V f v 0 1 1 1 7 BEL ETB I 7 G W g w 1 0 0 0 8 BS CAN ( 8 H X h x 1 0 0 1 9 HT EM ) 9 I Y i y 1 0 1 0 10 LF SUB * : J Z i z I 0 I I II VT ESC + ; K [ k f I I 0 0 12 FF FS I 1 I 0 I 13 CR GS - I I I 0 14 SO RS I I I 1 SI 15 1 A Q < L \ I = M ] m I N A@ n > / US I I I ? 0 - CD The graphic I (Logical OR) may also be used instead of ! (Exclamation Point). (]) The graphic -'(Logical NOT) may also be used instead of A (Circumflex). G) The 7 bit ASCII cade expands to 8 bits when in storage by adding a high order 0 bit. 0 , "" DEL Example: Pound sign (H) is represented by b7 o b6 0 b5 b4 b3 0 0 0 b2 bl Special Graphic Cllaracters Control Character Representations NUL SOH STX ETX EOT ENQ ACK BEL BS HT LF VT FF CR SO SI (CC) (FE) (IS) Null Start of Heading (CC) Start of Text (CC) End of Text (CC) End of Transmission (CC) Enquiry (CC) Acknowledge (CC) Bell Backspace (FE) Horizontal Tabulation (FE) Line Feed (FE) Vertical Tabulation (FE) Form Feed (FE) Carriage Return (FE) Shift Out Shift In DLE DCI DC2 DC3 DC4 NAK SYN ETB CAN EM SUB ESC FS GS RS US DEL Data link Escape (CC) Device Control I Device Control 2 Device Control 3 Device Control 4 Negative Acknowledge (CC) Synchronous Idle (CC) End of Transmission Block (CC) Cancel End of Medium Substitute Escape File Separator (IS) Group Separator (IS) Record Separator (IS) Unit Separator (IS) Delete Communication Control Format Effector Information Separator Fig u re F-l. ASCII Character Set 336 DOS/VS Supervisor & I/O Macros SP H S % & + / Space Exclamation Point Logical OR Quotation Marks Number Sign Dollar Sign Percent Ampersand Apostrophe Opening Parenthesis Closing Parenthesis Asterisk Plus Comma Hyphen (Minus) Periad (Decimal Point) Slant Colon Semicolon < > ? &J [ \ ] /\ Less Than Equals Greater Than Question Mark Commercial At Opening Brocket Reverse Slant Closing Brocket Circumflex Logical NOT Underline Grave Accent Opening Brace Vertical line (This graphic is stylized to distinguish it from Logical OR) Closing Brace Tilde EBCDIC ASCII Character NUL SOH STX ETX EOT ENQ ACK 8El 8S HT IF VT FF CR SO SI OLE OCI OC2 OC3 OC4 NAK SYN ET8 CAN EM SU8 ESC FS GS RS US SP lID , II S % & , ( . 1 + -' - / 0 I 2 3 4 5 6 7 8 9 : ; < = > ? Figure F-2. Col 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 I I I I I I I I I I I , I I I I , , I I I I I 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 I I I I , I 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 I J~ u 1 2 3 I I I I , I I I I , I I I I I · • • • · I I , Position 8it Position (in He.) Comments I I I .1 Col : Row 8it Row " 5 6 7 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 8 9 10 11 12 13 1" 15 0000 0000 I 0000 0000 0000 I I 0000 I 0000 I 0000 0000 0000 0000 0000 0000 0000 0000 0000 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0011 0011 0011 0011 0011 0011 0011 0011 0011 0011 0011 0011 0011 0011 0011 0011 I I I , I I I I I , .1 -.t I I , -'I I I I I , . I I I I ~ I I I I , 'I I I I I I I . I I .1 I I I I 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1011 1100 1101 1110 1111 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1011 1100 1101 1110 1111 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1011 1100 1101 1110 1111 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1011 1100 1101 1110 1111 0 0 0 0 3 2 2 2 1 0 2 0 0 0 0 0 1 1 1 1 3 3 3 2 1 1 3 2 1 1 1 1 4 I I , I I I I I ~ I , I I I I I I I , I , L I 4 7 ,I 7 5 6 5 I 7 .l I ·· " I I I 5 5 4 I 6 6 , 4 l 6 I F I F F F F I F I F I F I , F F 7 I 5 J. 4 I 7 I 6 I 6 · ! 0 1 2 3 7 D E F 6 5 5 8 C D E F 0 1 2 3 C D 2 6 8 9 F 7 C 0 E F 0 F F 8 8 C 0 0 0 0 C E 8 0 8 1 0 1 2 3 4 5 6 7 8 9 A E C E E F 0000 0000 0000 0000 0011 0010 0010 0010 0001 0000 0010 0000 0000 0000 0000 0000 0001 0001 0001 0001 0011 0011 0011 0010 0001 0001 0011 0010 0001 0001 0001 0001 0100 0100 0111 0111 0101 0110 0101 0111 0100 0101 0101 0100 0110 0110 0100 0110 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 0111 0101 0100 0111 0110 0110 I , I I I I I I .~ I I I I I I I I I I I I , , , J , , I I I , . I I I I I , . I I 0000 0001 ()I)10 0011 0111 1101 1110 1111 0110 0101 0101 1011 1100 1101 1110 1111 QOO(l 0001 0010 0011 1100 1101 0010 0110 1000 1001 1111 0111 1100 1101 1110 1111 0000 1111 1111 1011 1011 1100 0000 1101 1101 1101 1100 1110 1011 0000 I 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1110 1100 1110 1110 1111 , I I I , I I I I I I I Hyphen, Minus 1011 0001 I , logical OR ASCII to EBCDIC Correspondence (Part 1 of 2) Appendix F 337 , Character I I Col ASCII Col Bit Pattern Row I (in . I EBCDIC Row Bit Pattern I ~ex) Comments 1 @ A 8 C D E F G H I J K L M N 0 P Q R S T U V W X Y Z [ "J .... (2) -, 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 y z 7 { 7 7 7 7 7 g h i i k I m n 0 p Jt r s t u v w x : - J OEL , 1 I I I I J I I I I ..5 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 7 7 7 7 7 7 7 7 7 7 a b c d e f I 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 I I I I I , I I I I 1 _1 I I I I I I I I I I I I I I I I I I I , J , I 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 0 1 2 3 ..5 6 7 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 0100 0100 0100 0100 0100 0100 0100 0100 0100 0100 0100 0100 0100 0100 0100 0100 0101 0101 0101 0101 0101 0101 0101 0101 0101 0101 0101 0101 0101 0101 0101 0101 0110 0110 0110 0110 0110 0110 0110 0110 0110 0110 0110 0110 0110 0110 0110 0110 0111 0111 0111 0111 0111 0111 0111 0111 0111 0111 0111 0111 0111 0111 0111 0111 I ~ I I I I I I I I , , 1 I I I I I I I I I I , I I I I I I I I I I I I I I I I I I I I I I I I 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1011 1100 1101 1110 1111 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1011 1100 1101 1110 1111 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 1010 1011 1100 1101 1110 1111 0000 0001 0010 0011 0100 0101 0110 0111 1000 1001 101,Q 1011 1100 1101 1110 1111 7 C C C C C C C C C D D D D D D D D D E E E E E E E E I I I I I I C 1 2 3 4 5 6 I I I I I I I I I , 1 I I 7 8 9 1 2 3 4 5 6 7 8 9 2 3 4 5 4 6 7 8 9 A E 0 5 5 6 7 8 8 8 8 8 8 8 8 8 9 9 9 9 9 9 9 9 9 A A A A A A A A C 6 D A 0 I I 1 I I I , I I I I I I I I I I I I I ~ I I A F D 9 1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9 2 3 ..5 6 7 8 9 1010 0 I 0 1 1100 0110 1101 1010 I 7 0000 I A (]) Th. graphic I (Exclamation Point) can be used instead of I (logical OR). ~ Th. graphic" (Circumflex) can be used instead of -, (logical NOT). Figure F-2. ASCII to EBCDIC Correspondence (Part 2 of 2) 338 DOS/VS Supervisor & I/O Macros 0111 1100 1100 1100 1100 1100 1100 1100 1100 1100 1101 1101 1101 1101 1101 1101 1101 1101 1101 1110 1110 1110 1110 1110 1110 1110 1110 0100 1110 0101 0101 0110 0111 1000 1000 1000 1000 1000 1000 1000 1000 1000 1001 1001 1001 1001 1001 1001 1001 1001 1001 1010 1010 1010 1010 1010 1010 1010 t I 1100 0001 0010 0011 0100 0101 0110 0111 1000 1001 0001 0010 0011 0100 0101 0110 0111 1000 1001 0010 0011 0100 0101 0110 0111 1000 1001 1010 0000 1010 1111 1101 1001 0001 0010 0011 0100 0101 0110 0111 1000 1001 0001 OOJ9_ 0011 0100 0101 0110 0111 1000 1001 0010 0011 0100 0101 0110 0111 1000 1001 ()( IQO1C 10 I OC100 I 0001 0111 I I I I I I I I I I I I I I I I I , I I I I I 1 I I I , 1 1 I I I I , I I I I I , I I I I I Revene Slant Loaical NOT Undencore Grave Accent Vertical lin. Tild. APPENDIX G: PAGE FAULT HANDLING OVERLAP For some special types of processing, DOS/VS users often choose to write programs which, while executing as one DOS/VS user task, provide for the asynchronous processing of several tasks. This multitasking, which is not to be confused with DOS/VS multitasking, is generally used only in very sophisticated applications where no other technique would give acceptable performance. This type of asynchronous proce5sing (called 'private multitasking') is not supported by IBM and therefore is not documented as such. DOS/VS' does, however, provide one tool which aids the programmer doing private multitasking. This is the ability to overlap the handling of a page fault in one private subtask with the processing of another private subtask. If support is included in the supervisor (PHO=YES in the SUPVR macro), the user may set up an appendage routine which is to be entered whenever his DOS/VS task causes a page fault. This appendage routine acts as a 'dispatcher ' for the private subtasks originating in the same DOS/VS task. The routine is called by the DOS/VS supervisor whenever the DOS/VS task causes a page fault and whenever a page fault has just been handled for that task. The DOS/VS task is not put into the wait state when it causes a page fault as is usually the case, but remains dispatchable. The linkage to the appendage is established by issuing a SETPFA macro. In addition, the appendage routine must not cause a page fault and therefore must be fixed in real storage using the PFIX macro before the SETPFA macro is issued. The appendage routine is given control in the supervisor state, with I/O interrupts disabled, and with protection key zero. Following is a description of the conventions observed by page fault appendages in DOS/VS as well as suggestions how an appendage should be set up. REGISTER USAGE The following registers are used to pass information between the supervisor and the page fault appendage: • Register 7 contains the return address to the supervisor. • Regist~r 8 contains the address of the appendage routine, and can therefore be used as the base register of the routine. • Register 13 contains a parameter with information about the page fault to be handled. The information in register 13 has the following format: TIK Flags 0 I 1 Byte 0: I address of page TIK 2 PIK 3 Task interrupt key of interrupt task Flags = used by the system. Bytes 1-2: leftmost 16 bits of the address of the page which has to be handled. The remaining (rightmost) 8 bits of the address are considered to be zero. Byte 3: PIK of requesting task ENTRY LINKAGE The entry coding for the appendage should be as follows: USING B entry A ENTRY POINT AFTER PAGE FAULT *,8 USE REGISTER 8 AS BASE REGISTER B entry B ENTRY POINT AFTER PAGE FAULT COMPLETION The name specified in label is the entry point of the routine specified in the SETPFA macro. The branch to entry A is taken whenever the task causes a page fault and the branch to entry B is taken whenever a page fault for the task has been handled. PAGE FAULT QUEUE The appendage must have a queue with a four-byte entry for each private subtask controlled by that DOS/VS task. This queue is used to store the page fault information passed in register 13. Appendix G 339 The routine must then return control to the supervisor and pass a parameter in register 13. The parameter must either be zero, to indicate that a page fault request is pending for the DOS/VS task, or if no request is pending, the parameter must be the same as was passed to the appendage r 0 uti new hen i twa s .. c a 11 e d . PROCESSING AT THE INITIATION OF A PAGE FAULT When the routine is entered at entry A, register 13 contains information on the page fault which has just occurred. The appendage must store the contents of register 13 in the internal page fault queue, put the private subtask causing the page fault into an internal wait state, and, if possible, dispatch another private subtask. PROCESSING AT THE COMPLETION OF A PAGE FAULT In addition, the appendage routine must store (1) the contents of the save area of the DOS/VS task in the save area of the private subtask which is being deactivated and (2) the contents of the private subtask to be activated in the save area of the DOS/VS task. If no private subtask is dispatchable it is the responsibility of the appendage routine to change the contents of the task save area so that the t~sk will not continue to cause the same page fault each time it is dispatched. A possible solution is to dispatch a private task which does nothing but wait for a page fault to be handled. Whenever a page ·faul t request has been handled for the DOS/VS task, control is passed to entry B. The appendage routine dequeues the request which has just been handled from the internal page fault queue and posts the private subtask which caused the page fault. If there are any more page faults requests in the queue, the information for the next request to be handled must be returned in register 13, otherwise register 13 must contain zero. Figure G-1 is an example of how page faults are handled when the task causing the page faults has set up a page fault appendage. 5 U P E DOS dispatcher page fault (PFR4) R system page fault queue Page Fault Handler (request PFR4 is not enqueued to system queue) V I 5 Page Manager • • • • •~. get PF~l from queue • transfer cantrol to entry B when PFRl has been handled occupied by { IIII!!!=;;....~.. other DOS tasks '-::::;--';;::l1li o R enqueues PFR2 to system queue at locatian d PFRl page fault request PFR4 is transferred to appendage routine in register 13 A R E A P o A ·2 T S u R I Entry ~ of page fault appen age routine ...c set "private" subtask that caused PFR4 to internal wait state aetive another "private" subtask M T I o N Assumptians: ~ of page fault CifijieriCfage routine internal page fault queue • past "private" subtask that caused PFR1 dequeue PFR1 from internal queue •• lIIiIiiii••W. •• ; •• t~~jr••••~. ~ • enqueue PFR4 to internal ......_pa_ge_f_au_l_t_q... ue_u_e_ _ _..... • return via register 7 load internal register 13 with PFR2 from queue • return via register 7 • Sequence d page fault requests to be handled is PFR 1, 2, 3, 4 • • During handling d PFR1 3 other page fault requests have been caused by the same DOS/VS task Figure G-l. Page Fault Handling Overlap 340 DOS/VS Supervisor & I/O Macros APPENDIX H: OPERAND NOTATION FOR VSAM GENeD, MODeD, SHoweD, AND TESTeD MACROS The addresses, names, numbers, and options required with operands in GENCB, MODCB, SHOWCB, and TESTCB'can be expressed in a veriety of ways: • An absolute numeric expression, for example, COPIES=10 • A character string, for example, DDNAME=DATASET • A code or a list of codes separated by commas and enclosed in parentheses, for example, OPTCD=KEY or OPTCD=(KEY,DIR,IN) • An expression valid for a relocatable A-type address constant, for example, AREA=MYAREA+4 • A register from 2 through 12 that contains an address or numeric value, for example SYNAD=(3); equated labels can be used to designate a register, for example, SYNAD=(ERR). where the following equate statement has been included in the program: ERR EQU 3 • An expression of the form (S.scon). where scon is any expression valid for an S-type address constant, including the basedisplacement form • An expression of the form ( valid for an S-type address form; the address specified points to the location that .scon). where scon is any expression constant. including the base-displacement by scon is indirect. that is, it contains the value of the keyword If an indirect S-type address constant is used. the value it pOints to must meet the following criteria: • If it is a numeric quantity, a bit string representing codes. or a pointer. it must occupy a fullword of storage. • If it is an alphameric character string. it must occupy two words of storage. be left aligned, and be filled on the right with blanks. The expressions that can be used depend on the keyword specified. Additionally. register and S-type address constants cannot be used when MF=L is specified. Appendix H 341 GENCB MACRO OPERANDS Absolute Numeric Code Character String Register S-Type Address Indirect S-Type Address A-Type Address X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X GENCB Keywords BLK COPIES LENGTH WAREA X v .' X ACB Keywords (BLK=ACB) I BUFND BUFNI BUFSP DDNAME EXLST MACRF PASSWD STRNO X X X X X X EXLST Keywords (BLK=EXLST) f EO DAD EXCPAD LERAD SYNAD RPL Keywords (BLK",RPL) I ACB AREA AREAL EN ARG KEYLEN NXTRPL OPTOD RECLEN X X X 342 DOS/VS Supervisor X & I/O Macros X X MODCB MACRO OPERANDS Absolute Numeric Code Character String Register S-Type Address Indirect S-Type Address A-Type Address x x x x X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X MODCB Keyword {ACBI EXLSTI RPL} ACB Keywords BUFND BUFNI BUFSP DDNAME EXLST MACRF PASSWD STRNO X X X X X X EXLST Keywords EODAD EXCPAD LERAD SVNAD RPL Keywords ACB AREA AREALEN ARG KEYLEN NXTRPL OPTCD RECLEN X X X X X X X X X X X X X Register S-Type Address Indirect S-Type Address A-Type Address X X X X X X X X X X X X X X SHOWCB MACRO OPERANDS Absolute Numeric Code {ABCI EXLSTI RPL} AREA FIELDS LENGTH OBJECT Character String X X X X Appendix H 343 TESTCB MACRO OPERANDS Register S-Type Address Indirect S-Type Address A-Type Address X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X Absolute Numeric Code Character String TESTCB Ke,z::words {ABC I EXLST I RPL} ERET OBJECT X ACB Keywords ACBLEN ATRB AVSPAC BuFND BUFNI BUFNO BUFSP CINV DDNAME ERROR EXLST FS KEYLEN LRECL MACRF NCIS NDELR NEXCP NEXT NINSR NIXL NLOGR NRETR NSSS I~UPUR OF LAGS PASSWD RKP STMST STRNO X X X X X X X X X X X X X X X X X X X X X X X X X X X X X EXLST Keywords EODAD EXCPAD EXLLEN LERAD SYNAD RPL Ke,z::words ACB AREA AREAL EN ARG FDBK KEY LEN NXTRPL OPTCD RBA RECLEN RPLLEN X X X X X X X 344 DOS/VS Supervisor & I/O Macros X X X X APPENDIX I: PARAMETER LISTS FOR VSAM GENCD, MODCD, SHOWCD, AND TESTCD MACROS The VSAM macros for generating, modifying, displaying, and testing an access-method control block, exit list, or request parameter list use an internal parameter list to describe the actions that you specify when you code the macros. The standard form of these macros builds a parameter list in-line and processes it; the list form builds a parameter list in an area specified by the user; the execute form processes a previously built parameter list; the generate form builds a parameter list in an area specified by the user and also processes it. For special purposes, such as developing high-level programming languages, you may want to build and process parameter lists without using the macros. This appendix describes the format of the parameter lists and gives the codes used for the operands of ~ach of the macros. The formats and codes are fixed, so that you can build and alter them by your own methods. A parameter list contains a variable number of entries of three types: 1. At the beginning of the list, addresses of entries of the second and thlrd types; the addresses are fullwords, and the high-order bit of the.last fullword is 1. 2. Next, a header e~tth containing general informatlon abou e block or list that you want to generate, modify, display, or test. 3. At the end of the list, keyword entries describing each field that you want to generate, modify, display, or test. Entries of the second ~nd third types are described separately for GENCB, MODCB. SHOWCB, and TESTCB. Appendix I 345 THE GENeB PARAMETER LIST RPL Arr AL2(43) AREA 44 AREALEN 45 ARG 46 KEY LEN 48 I NXTRPL 51 OPTCD 52 RECLEN 53 The Header Entry o block or 1 i s t 1 X' 01 1 number of copies address of the area you are providing, or Os 4 length of the area, or Os 8 a You indicate the options for MACRF and OPTCD with a 1 in a bit of the fullword: (reserved) MACRF Option KEY ADR CNV SEQ SKP DIR IN OUT NUB UBF X'AO ' indicates access-method control block (ACB) X'BO 1' indicates exit list (EXLST) X'C0 indicates request parameter list (RPL) 1 Keyword Entries 2 3 4 5 6 7 8 9 OPTeD Uption KEY The parameter list for GENCB contains no keyword e~tries if you are generating a default ACB, Exit List, or RPL. ADR CNV SEQ DIR SKP NUP UPD NSP KEQ KGE FKS GEN MVE LOC (reserved) I {valuel addressloption name} o keyword code t 2 4 of the keyword 1 (required for some keywords' ) 8 S ACB "S"UrND BUFNI BUFSP DDNAr4E EXLST MACRF PASSWD ISTRNO EXLST "E:OITAIT IEXCPAD LERAD SYNAD , AL2(4) 5 7 9 12 18 30 32 Bit 0"" 1 2 3 4 5 8 9 10 11 12 13 14 15 16 The third fullword is required for the ACB operand DDNAME and for all of the EXLST operands, for which the third fullword indicates [,{AIN}] [,L]: Bit o 1 2 AL2(37) 38 40 41 bit lr 1 3 4-31 Meaning when set to 1 Addres is active (A) Address is not active (N) Address is of a field containing the name of an exit routine to be loaded (L) Address is specified in the preceding fullword of this entry Unused An entry for any of the other operands is 8 bytes long. 346 DOS/VS Supervisor & I/O Macros 'You indicate the options for MACRF and OPTCD with a 1 in a bit of the fullword: THE MODCB PARAMETER LIST The Header Entry o MACRF Option KEV X' 02 1 block or 1 is t 1 ADR CNV SEQ SKP (reserved) IN OUT NUB UBF X'AO ' indicates access-method control block (ACB) X'BO ' indicates exit list (EXLST) 1 X1C0 indicates request parameter list (RPL) J ADR CNV SEQ SKP NUB UPD NSP KEQ KGE FKS GEN MVE LOC Keyword f;ntries keyword code 1 I (reserved) 4 {val uel addressl option a I name} of the keyword 8 (required for some keywords ll 1 ACB BiJFND BUFNI BUFSP DDNAME EXLST MACRF PASSWD STRNO I EXLST rorrJm IEXCPAD LERAD SYNAD RPL ~ AREA AREALEN ARG I KEYLEN NXTRPL OPTCD RECLEN 7 9 AL2(37) 38 40 41 AL2(43) 44 45 46 48 51 52 53 7 8 9 Bit --0-1 2 3 4 5 8 9 10 11 12 13 14 15 16 With the MODeB macro, there are no defaults for these options. When you code a bit for the OPTeD operand, the contrary bit that was previously set is turned off. For example, if KEY was previously set, and you set ADR, KEY is turned off, since a request parameter list can be set for only one type of access. ) AL2(4) 5 12 18 30 32 6 OPTCD Option KEY DIR o 3 4 5 DIR address of the block or list to be modified 4 Bit -U1 2 3 The third fullword is required for the ACB operand DDNAME and for all of the EXLST operands, for which the third fullword indicates [,(AltO] [,L]: Bit o 1 2 3 4-31 Meaning when set to 1 Address is active (A) Address is not actlve (N) Address is of a field containing the name of an exit routine to be loaded (L) Address is specified in the preceding fullword of this entry Unused An entry for any of the other operands is 8 bytes long. Appendix I 347 THE SHOWCB PARAMETER LIST The Header Entry o block or list 1 I 0 X' 03 1 1 type of object to be displayed 4 address of the block or list to be displayed 8 address of the display area you are providing 12 1 length of the dis play a re a X'OO Keyword Entries keyword code1. 1- ACB ACBLEN AVSPAC BUFND BUFNl BUFNO BUFSP CINV UDNAME ERROR EXLST FS KEYLEN LRECL NClS NDELR NEXCP NEXT NlNSR NlXL NLOGR NRETR NSSS NUPDR PASSWD RKP STMST STRNO (reserved) indicates that no block or list is specified, to display the standard length of the block(s) or list(s) specified by'the keyword ACBLEN, EXLLEN, or RPLLEN X'AO ' indicates ACB X'BO ' indicates Exit List X1C0 1 indicates RPL I AL2(O) indicates the data of a file AL2(1) indicates the index of a file I AL2(3) 2 4 5 6 7 8 9 11 12 13 16 17 19 20 21 22 23 24 25 26 27 28 30 31 35 32 EXLST EODAD AL2(37) EXCPAD 38 EXLLEN 42 LERAD 40 SYNAD 41 I RPL ACB AL2(43) AREA 44 AREALEN 45 ARG 46 FDBK 56 48 KEYLEN NXTRPL 51 RBA 57 RECLEN 53 RPLLEN 55 I 348 DOS/VS Supervisor & I/O Macros (reserved) THE TESTCB PARAMETER LIST I The Header Entry o X' 04 1 block 1 or list type of object to be tested 4 address of the block or list to be tested 8 address of the routin& to return to for uneq ua 1 comparisons, or Os 12 (reserved) X10QI indicates that no block or list is specified, to test the $tandard length of the block(s) or list(s) specified by the operand ACBLEH, EXLLEN, or RPLLEN X'AO ' indicates ACB X'BO ' indicates Exit List X1C0 1 indicates RPL t AL2(0) indicates the data of a file AL2(1) indicates the index of a file Keyword Entries o keyword code 1 I 4 (reserved) {valueladdressloptio n2 Inamelcode 3 } of the keyword 8 (required for some ACB l\CB"LEN ATRB AVSPAC BUFND BUFNl BUFNO BUFSP ClNV DDNAME ERROR EXLST FS KEYLEN LRECL MACRF NClS NDELR NEXCP NEXT NI NS R NlXL NLOGR NRETR NSSS NUPDR OFLAGS PASSWD RKP s TMS T I STRNO :1 AL2(3) 1 2 4 5 6 7 8 9 11 12 13 16 17 18 19 keywords~) I EXLST rooAIJ EXCPAD EXLLEN LERAD SYNAD ALD2(37) 38 42 40 41 RPL ALD2(43) ill 44 AREA 45 AREALEN 46 ARG 56 FDBK 48 KEYLEN 51 NXTRPL 52 OPTCD 57 RBA 53 RECLEN 55 RPLLEN z You indicate the options for ATRB, MACRF, OFLAGS, and OPTCD by a 1 in a bit of the fullword: ATRB Oe tion KSDS ESDS WCK SSWD REPL MACRF KEY ADR CNV SEQ SKP DIR IN OUT UPD OFLAGS OPEN OPTeD KEY ADR CNV SEQ DlR SKP NUP UPD NSP KEQ KGE FKS GEN r4VE LOC O~tion Bit -0- 1 2 3 4 Bit -0- 1 2 3 4 5 6 7 8 O~tion °e tion Bit LJ Bit -01 2 3 4 5 8 9 10 11 12 13 14 15 16 20 21 22 23 24 25 26 27 28 29 30 31 35 32 Appendix I 349 3 The codes for ERROR are given in the section IIOpening and Closing Files in the VSAM chapter. The codes for FDBK are given in the section IIRequesting Access to Files in the VSAM chapter. ll ll ~ The third fullword is required for the ACB operands DDNAME and STMST and for all of the EXLST operands, for which the thi rd fullword i ndi cates [, {A IN} ] [,L] : 350 DOS/V~ Supervisor & I/O Macros Bit -U1 2 3 4-31 Meaning when set to 1 Address 1S actlve (A) Addres is not a~tive (N) Address is of a field containing the name of an exit routine to be loaded (L) Address is specified in the preceding fullword of this entry Unused An entry for any of the other operands is 8 bytes long. APPENDIX J: USING ISAM PROGRAMS WITH VSAM FILES The ISAM Interface Program (lIP) permits ISAM programs to process VSAM files. ISAM programs do not have to be reassembled or relinkedited to use the lIP. Also, both ISAM and VSAM files, through the lIP, can be processed concurrently. Bytes Contents 0-3 DTF address 4-7 Not supported by the lIP To use the lIP, you must convert your ISAM files to VSAM files and the job control statements of your ISAM program to VSAM job control statements. You must also ensure that ISAM programs meet certain restrictions for using the lIP. See the DOS/VS Data Management Guide, GC33-5372 for lnformation on converting files and job control statements and on lIP restrict10ns. 8.. 15 Not supported by the lIP You do not have to make any changes in the DTFIS to use ISAM programs with the lIP. The following DTFIS parameters are used by the lIP; all other parameters are ignored: 17 • • • • • • • • • • ERREXT=YES (See Figure J-1 for a description of the ERREXT parameter list with lIP.) 10AREA=name (used when 10ROUT=LOAD) 10AREAS=name (used if SETL BOF is issued) IOREG=(r) 10ROUT= LOAD ADD RETRVE ADDRTR KEYARG=name RECFORM= FIXUNB FIXBLK WORKL=name WORKR=name WORKS=YES The lIP interprets the error return codes from VSAM. If the VSAM condition corresponds to an ISAM condition, the respective bit in the filenameC byte in the DTFIS is posted. For unrecoverable errors that cannot be posted in the filenameC byte, a message is printed on the console, the VSAM file is closed (by the VSAM close routine), and the task is terminated. If an I/O error occurs and ERREXT=YES is specified in the DTFIS, the lIP posts additional error information in the ERREXT parameter list. Figure J-1 shows the format of the ERREXT parameter list, and Figures J-2 and J-3 show the formats of the filenameC byte for ISAM processing through the lIP. 16 : Bit 0 Bit 1 Btt 2 Bits 3.. 5 Bit 6 Bit 7 Data VSMI Sequence Set VSMl I ndex Set Not used Read operati9n Write operation Not supported by the lIP Figure J-l. ERREXT Parameter List for ISAM Programs with the lIP Bit Ca use i n I SA~' Cause in IIP/VSAM 0 DASD error DASD error 1 Wrong length record Not set 2 End of file End of fil e 3 No record found No record found 4 Illegal 10 specified Not supported by lIP 5 Duplicate record Duplicate record 6 Overflow area full No more VSAM data space available 7 Overflow Not set Figure J-2. FilenameC with lIP when IOROUT=ADD, RETRVE, or ADDRTR Appendix J 351 Bit Ca use i n I SA~1 Cause in -I IP/VSAt·1 0 DASD error DASD error 1 Wrong 1ength record Not set 2 Prime data area full No more space 3 Cylinder index area full No more VSAf.1 data space 4 r~ a s t No more space 5 Duplicate record Duplicate record 6 Sequence check Sequence check 7 Prime data area overflow Uot set full e r i nde x VSA~l VSA~l data dat, If there is no more VSAM data space, all three bits are set. Figure J-3. FilenameC with rIP when IOROUT=LOAD 352 DOS/VS Supervisor & I/O Macros GLOSSARY This glossary defines most of the terms used in this book. For a more complete list of data processing terms, refer to IBM Data Processing Glossary, GC20-1699. access method: Any of the data management techniques (sequential, direct, indexed sequential, or virtual storage) available for transferring data between virtual storage and an input/output device. ASCII (American National Standard Code for Information Interchange): A 128-character, 7-bit code. The high order bit in the System/370 8-bit environment is zero. associated fHe: A file for one function used in association with another file for another function to be performed in the same set of cards on a 2560, 3525, or 5425 card device. For example, with three associated files the same set of cards could be read and punched and printed. A file definition must be given for each associated file. Not synonymous with combined file. Basic Telecommunications Access Method (BTAM): A basic access method that permits a READ /WRITE communication with remote devices. CCW: See channel command word channel command word (CCW): A double word at the location in virtual storage specified by the channel address word. One or more CCWs make up the channel program. channel program: One or more channel command words (CCWs) that control(s) a specific sequence of channel operations. Execution of the specific sequence is initiated by a single SIO machine instruction. checkpoint record: A record containing the status of the job and of the system at the time the checkpoint routine writes the record. This record provides the necessary information for restarting a job without returning to the beginning of the job. checkpoint/restart: A means of restarting execution of a program at some point other thim the beginning. When a checkpoint macro is issued in a program, checkpoint records are created. These records contain the status of the job and the system. When it is desired to restart a program at a point other than the beginning, the restart procedure uses the checkpoint records to reinitialize the system. checkpoint routine: A routine that r.ecords information for a checkpoint. block: 1. To group records physically for the purpose of saving storage space or increasing the efficiency of access or processing. 2. A physical record on magnetic tape or DASD. combined fHe: A single file on the 1442, 2520, or 2540 card device which both reads and punches the same set of cards. Not synonymous with associated file. block prefix: An optional, 0-99 byte field preceding an ASCII record on magnetic tape. It contains data which you specify or, for variable length ASCII records, the physical record length. I command control block (CCB): A 16-byte field required for each channel program executed by physicaiIOCS. This field is used for communication between physical IOCS and the program. buffer: 1. A storage device in which data is assembled temporarily during data transfer. An example is the 2821 control unit, a control and buffer storage unit for card readers, card punches, and printers. 2. During I/O operations, a portion of virtual storage into which data is read or from which data is written. ~ynonymous with I/O area. communication region: An area of the supervisor set aside for interprogram and intraprogram communication. It contains information useful to both the supervisor and your program. CCB: See command control block control program: A group of programs that provides functions such as the handling of input/output operations, error detection and recovery, program loading, and co~munication between the prograrp. and the operator.' IPL, supervisor, and job control make up the control program in DOS/VS. Glossary 353 control section: The smallest separately relocatable unit of a program; that portion of code which you specify to be an entity, all elements of which are to be loaded into contiguous virtual storage locations. data conversion: The process of changing data from one form of representation to another. data set security: A feature that provides protection for disk files. A secured file cannot be accidentally accessed by a program. device independence: The capability of a program to process the same type of data on devices (printers, magnetic tape, or disk). DTF {define the file} macro: A macro used for all access methods except VSAM to describe the characteristics of an input/output file, indicate the type of processing for the file, and specify the virtual storage areas and routines to be used in processing the file. These things are described using the appropriate parameters in the keyword operands of the DTF macro. not represent any physical file which has the same logical characteristics. f"txed length record: A record having the same length as all other records with which it is logically or physically associated. header label: A file label that precedes the data records on a unit of recording media. I/O area: A portion of storage into which data is read or from which data is written. I/O means Input/ Output. I/O area is synonymous with buffer (definition 2). IOCS (input/output control system): A group of macros and the routines which process them provided by IBM for handling the transfer of data between virtual storage and external storage devices. load: To read a phase into virtual storage, returning control to the calling phase. dump: To display the contents of virtual storage. load point: The beginning of the recording area on a reel of magnetic tape. extent: A contiguous space on a direct access storage device occupied by, or reserved for, a particular file. logic module: The logical IOCS routine that provides an interface between a processing program and physical IOCS. fetch: 1. To bring a program phase into virtual storage from a core image library for immediate execution. 2. The routine that retrieves requested phases and loads them into virtual storage, 3. The name of a macro (FETCH) used to transfer control to the system loader. 4. To transfer control to the system loader. logical file: See file, definition 2. f"tle: 1. The major unit of physical data, consisting of a collection of physical records in one of several prescribed arrangements and described by control information to which the system has access. For example, a deck of cards containing payroll data (one record for each employee describing his rate of pay, deductions, etc.), or a disk extent containing inventory information (one block for each inventory item describing the cost, selling price, number in stock, etc.). 2. A representation within a program of the logical characteristics of a file as defined in definition 1, above. The representation is achieved by a DTF macro or by an ACB, EXLST, and RPL macro. A given file within a program can- 354 DOS/VS Supervisor & I/O Macros logical record: A record identified from the standpoint of its content, function, and use rather than its physical attributes; that is, one which is meaningful with respect to a program. (Contrasted with physical record). macro: A single assembler language instruction which is equivalent to a sequence of assembler language instructions. Thus when you specify one macro, the assembler generates a number of assembler language instruction. macro definition: A set of statements which defines the name of, format of, and conditions for generating a sequence of assembler language instructions from a single source instruction. macro system: The method by which macros are coded and by which the assembler program analyzes the macros and generates the appropriate sequence of assembler language instructions. main task: The main program within a partition in a multiprogramming environment. (Compare with subtask). MPS: See multiprogramming system. multi-rde volume: A unit of recording media, such as a magnetic tape reel or disk pack, that contains more than one file. multiprogramming: A technique whereby two or more problem programs may execute concurrently in one computer, sharing system resources between them. multitasking: A technique whereby one or more subtasks, attached to a main task within one partition, can execute concurrently. multi-volume file: A file which, due to its size, requires more than one unit of recording media (such as magnetic tape reel or a disk pack) to contain the entire file. nonstandard labels: Labels that do not conform to the System/370 standard label conventions. They can be any length, need not have a specified identification, and do not have a fixed format. operating system: A collection of programs that enables a data processing system to supervise its own operations, automatically calling in programs, routines, language processors, and data as needed for continuous throughput of a series of jobs. phase: The smallest complete unit that can be referenced in a core image library. Each program overlay is a complete phase. If the program has no overlays, the program itself is a complete phase. physical file: See file, definition 1. physical record: A record identified from the standpoint of the manner or form in which it is stored and retrieved; that is, one that is meaningful with respect to access. (Contrasted with logical record). private Hbrary: A relocatable, core image, or source statement library that is separate and distinct from the corresponding system library. problem program: 1. Your object program. It can be produced by any of the language translators. It consists of instructions and data necessary to solve your data-processing problem or to achieve a certain result. 2. A general term for any routine that is executed in the data processing system's problem state; that is, any routine that does not contain privileged operations. (Contrasted with supervisor). processing program: A general term for any program that is both loaded and supervised by the control program. This includes IBM -supplied programs such as language processors, linkage editor, librarian, sort/merge, and utilities, as well as programs which you supply. The term processing program is in contrast to the term control program. real address area: The area of virtual storage where virtual addresses are equal to real addresses. real partition: A division of the real address area of virtual storage that may be allocated for programs that are not to be paged, or programs that contain pages that are to be fixed. real storage: The storage of a System/370 computing system from which the central processing unit can directly obtain instructions and data, and to which it can directly return results. record: A general term for any unit of data that is distinct from all others when considered in a particular context. reenterable: The attribute of a set of code that allows the same copy of the set of code to be used concurrently by two or more tasks. relocatable: The attribute of a module, control section, or phase whose address constants can be modified to compensate for a change in origin. relocatable program: A program that can be loaded into any area of virtual storage by the loader of a supervisor with relocating load support. resource: Any facility of the computing or operating system required by a job or task. This includes virtual storage, input/output devices, the central processing unit, files, and control and processing programs. restart: See checkpoint/restart. self-relocating: A routine that is loaded at any doubleword boundary in the problem program area and can adjust its address values so as to be executed at that location. self-relocating program: A program that can be loaded into any area in the problem program area of storage by having an initialization routine to modify all address constants at object time. shared virtual area: An area located in the highest Glossary 355 addresses of virtual storage. It can contain a system directory list of highly used phases and resident programs that can be shared between partitions. storage: The term as used in this book is synonymous with virtual storage. See virtual storage. subset module: A logic module which is a subset or component of a superset module. subtask: A task in which control is initiated by a main task by means of a macro that attaches it. superset module: A logic module which performs all of the functions of its subset or component modules, avoiding duplication and therefore saving storage space. supervisor: The main control program. It consists of routines to control the functions of program loading, machine interruptions, external interruptions, operator communications, and physical IOCS requests and interruptions. It coexists in storage with problem programs. symbolic I/O assignment: A means by which your program can refer to an I/O device by a symbolic name. Before a program is executed, job control can be used to assign a specific I/O device to that symbolic name. system directory list: A list containing directory entries of highly used phases and of all phases resident in the shared virtual area. This list is placed in the shared virtual area. telecommunication: Data transmission between a computer and remote stations. teleprocessing: Same as telecommunication. 356 DOS/VS Supervisor & I/O Macros track hold: A function for protecting DASD tracks that are currently being processed. When track hold is specified in the DTF, a track that is being modified by one program cannot be concurrently accessed by another program. undefined record: A record having an unspecified or unknown length. variable length record: A record having a length independent of the length of other records with which it is logically or physically associated. (Contrasted with fixed-length record). It contains fields specifying physical and logical record lengths. virtual address area: The area of virtual storage whose addresses are greater than the highest address of the real address area. virtaul partition: A division of the virtual address area of virtual storage that is allocated for programs that be paged. virtual storage: Addressable space that appears to you as real storage, from which instructions and data are mapped into real storage locations. The size of virtual storage is limited bu the addressing scheme of the computing system and by the amount of auxiliary storage available, rather than by the actual number of real storage locations. volume: That portion of a single unit of storage media that is accessible to a single read/write mechanism. For example, a reel of magnetic tape on a 2400-series magnetic tape drive, or a disk pack on a 3330 disk storage drive. work area: A portion of virtual storage used for processing an individual record. INDEX abnormal termination codes . . . . . . . .. 277, 278 ACB macro . . . . . . . . . . . . . . . . . . .. 220, 277 examples . . . . . . . . . . . . . . . . . . . . . . .. 227 access method (see also DAM; ISAM; SAM; VSAM) access-method control block (ACB) for VSAM . . . . . . . . . . . . . . . . . . . . . 220 direct (DAM) . . . . . . . . . . . . . . . . . . . .. 159 indexed sequential (ISAM) ........... 185 sequential (SAM) ... . . . . . . . . . . . . . . . . 31 virtual storage (VSAM) . . . . . . . . . . . . . . 215 address area address constants, relocation of .......... 328 addressed access . . . . . . . . . . . . . . . .. 217, 218 addresses, symbolic unit ................ 14 area (see address area; I/O area; MICR document buffer; overflow; work area) ASA control character codes ............ 301 ASCII (American National Standard Code for Information Interchange) character set ..................... 335 comparison to EBCDIC. . . . . . . . . . . . .. 337 files ............................ 27 label processing .................... 27 tape files ......................... 27 assembling program, DTFs, and modules ....... 18, 304 format record for the 3886 optical character reader .......................... 319 associated files processing ................ 134, 141, 156 specifying for CDMOD .................... 41 for DTFCD ....... . . . . . . . . . . . . . . 34 for DTFPR ..................... 84 for PRMOD . . . . . . . . . . . . . . . . . . . . . 88 ATTACH macro .................... 288 autolinking logic modules. . . . . . . . . . . .. 16, 18 autoselection for MICR ................. 64 backwards, reading tape ............ 29, 130 Basic Operation System/360 CHNG macro .................... 144 DTFSR macro .................... 108 begin-definition card for DTFSR ......... 108 block access-method control . . . . . . . . . . . . . . . 220 blocked records GET macro processing .............. 129 PUT macro processing . . . . . . . . . . . . . .. 132 BOS/360 (Basic Operating System/360) CHNG macro .................... 144 DTFSR macro ..................... 108 braces, brackets, notational conventions . 20, 218 buffer (see also I/O area) console .......................... 42 MICR . . . . . . . . . . . . . . . . . . . . . .. 63, 331 printer-keyboard . . . . . . . . . . . . . . . . . . . . 42 CALL macro ....................... 298 called program ...................... 299 calling program ..................... 299 CANCEL macro .................... 283 capacity record. . . . . . . . . . . . . . . . .. 164, 183 card detail ........................... 19 device control .................... 135 file (DTFCD) ..................... 34 header . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 module (CDMOD) .................. 40 punch control ....................... 140 file (DTFCD) .................... 34 module (CDMOD) ................ 40 reader control ....................... 140 EOF condition (DTFSR) . . . . . . . . . .. 112 file (DTFCD) .................... 34 module (CDMOD) ................ 40 catalog (VSAM) . . . . . . . . . . . . . . . . . . . . . 220 cataloging declarative macros . . . . . . . . . . . . . 18 CCB (command control block) conditions shown in bytes 2-3 ......... 252 format of . . . . . . . . . . . . . . . . . . . . . . . . 250 macro .......................... 249 CCW (channel command word) .......... 249 CDMOD macro . . . . . . . . . . . . . . . . . . . . . . 40 chaining ISAM overflow records . . . . . . . . .. 190 chaining RPLs (VSAM) ........ 225, 222, 224 channel command word (CCW) .......... 249 character, control (see control character) character, end-of-record ................ 92 CHECK macro for magnetic reader ................. 145 for work files ..................... 152 checking nonstandard labels .................. 29 output file in VTOC . . . . . . . . . . . . . . .. 126 standard labels " ................... 29 user standard labels Index 357 on disk .................... 25, 127 on tape .................... 29, 127 checkpoint DTFPH entries for . . . . . . . . . . . . . . . .. 254 file ............................ 285 macro .......................... 283 record ........................... 27 on tape ........................ 27 checkpoint/restart (see checkpoint) CHKPT macro ...................... 283 CHNG macro ...................... 144 CLOSE/ CLOSER macro for DAM ........................ 184 for ISAM ........................ 213 for PIOCS ....................... 260 for SAM ........................ 155 CLOSE macro for VSAM ....................... 239 closing (see CLOSE/CLOSER macro) CNTRL macro command codes ............... 138, 183 for DAM ........................ 183 for SAM ........................ 137 codes abnormal termination ............ 277,278 CNTRL macro . . . . . . . . . . . . . . .. 138, 183 control character .................. 301 ISAM condition ............... 196, 197 MICR pocket selection ............... 63 termination, abnormal . . . . . . . . . .. 277, 278 universal character set . . . . . . . . . . . . . ., 140 combined file example . . . . . . . . . . . . . . . . . . . . . . . .. 134 specifying .................... 43, 133 command chained records (diskette) GET macro processing .............. 130 PUT macro processing .............. , 132 command codes for CNTRL macro ... 138, 183 command control block (CCB) conditions shown in bytes 2-3 ......... 252 format of . . . . . . . . . . . . . . . . . . . . . . . . 250 macro .......................... 249 communication, intertask . . . . . . . . . . . . . . . 291 communication region format of ........................ 274 macros for ....................... 274 completion macros for DAM ........................ 184 for ISAM ........................ 213 for SAM ........................ 154 COMRG macro . . . . . . . . . . . . . . . . . . . . . 274 concepts of ISAM ................... 187 of VSAM ....................... 217 concurrent request processing (VSAM) . 221, 224 condition codes for ISAM .......... 196, 197 358 DOS/VS Supervisor & I/O Macros console buffer ........................... 42 file (DTFCN) ..................... 42 console printer-keyboard buffer ........................... 42 file (DTFCN) ..................... 42 constants, relocation of ................ 328 continuation punch . . . . . . . . . . . . . . . . . . . . 20 control area (VSAM) ................. 217 control block (see command control block) /tf/ operand notation .................. 341 parameter lists .................... 345 control block generation macros . . . . . . . . .. 220 control block manipulation macros ........ 228 control character codes .......................... 301 PUT macro processing . . . . . . . . . . . . . .. 135 control interval (VSAM) .. . . . . . . . . . . . . . 217 control macro (see CNTRL macro) conventions for notation ............ 20, 218 cylinder index for ISAM ............... 189 resident . . . . . . . . . . . . . . . . . . . .. 198, 202 cylinder overflow areas full ............. 190 area ........................... 190 DAM (Direct Access Method) adding records .................... 162 creating a file . . . . . . . . . . . . . . . . . . . .. 162 declarative macros ................. 165 description of . . . . . . . . . . . . . . . . . . . .. 159 EXTENT statement restriction . . . . . . . . . . 15 file (DTFDA) .................... 165 imperative macros . . . . . . . . . . . . . . . . .. 179 keys (see keys) logic module (DAMOD) ............. 176 multi-volume file restriction .. . . . . . . . . . . 15 record types ...................... 159 reference methods .................. 161 DAMOD macro ..................... 176 DASD (direct access storage device) CNTRL macro codes ........... 138, 142 file DAM (DTFDA) . . . . . . . . . . . . . . . .. 165 ISAM (DTFIS) .................. 194 SAM (DTFSD) .............. 98, 105 labels ........................... 23 logic module DAM (DAMOD) ................ 176 ISAM OSMOD) ................. 201 SAM (SDMODxx) ............... 105 operator verification table ............ 287 track protection macros .............. 292 data cell (see DASD) data check . . . . . . . . . . . . . . . . . . . . . . . . . . 95 declarative IOCS macros (see also DTF macro; logic module generation macro) assembling. . . . . . . . . . . . . . . . . . .. 18, 304 description of . . . . . . . . . . . . . . . . . . . . . . 11 for DAM . . . . . . . . . . . . . . . . . . . .. 14, 165 for ISAM ..................... 14, 194 for PIOCS . . . . . . . . . . . . . . . . . . .. 14, 254 for SAM ................... 13, 31, 34 for VSAM .................... 11,220 format. . . . . . . . . . . . . . . . . . . . . .. 19, 218 define the file macro (see DTF macro) DEFINE statement (Access Method Services) ........................ 220 deletion, ISAM records tagged for ........ 191 DEQ macro ........................ 290 dequeue macro ...................... 290 DETACH macro .................... 289 detail card . . . . . . . . . . . . . . . . . . . . . . . . . . 19 device independence file (DTFDI) ...................... 44 module (DIMOD) ................... 47 DFR macro ..................... 52,319 DIMOD macro . . . . . . . . . . . . . . . . . . . . . . . 47 direct access (see also DASD) file (DTFDA) .................... 165 method (see DAM) module (DAMOD) ................. 176 storage device- (see DASD) DISEN macro ...................... 146 disengage macro . . . . . . . . . . . . . . . . . . . .. 146 disk (see DASD) diskette file (DTFDU) ..................... 58 label processing .................... 25 module (DUMODFx) ................ 62 display control block (SHOWCB) macro ......................... , 231 display macro . . . . . . . . . . . . . . . . . . . . . .. 147 displaying VSAM blocks and lists . . . . . . . . . 231 DLBL job control statement ............. 23 DLINT macro ....................... 56 document buffer, MICR ................ 63 document processing (see MICR) DRMOD macro ... . . . . . . . . . . . . . . . . . . . 51 DSPLY macro ...................... 147 DTF (define the file) macro assembling . . . . . . . . . . . . . . . . . . .. 18, 304 cataloging ........................ 18 description of . . . . . . . . . . . . . . . . . .. 11, 13 examples (see coding form examples) for DAM (DTFDA) ............. 14, 165 for ISAM (DTFIS) ......... . . . .. 14, 194 for PIOCS (DTFPH) ............ 14,254 for SAM ... . . . . . . . . . . . . . . .. 13, 31, 34 format . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 DTF table, referencing ............. 14, 191 DTFBG card ........ . . . . . . . . . . . . . .. 108 DTFCD macro . . . . . . . . . . . . . . . . . . . . . . . 34 DTFCN macro ....................... 42 DTFDA macro . . . . . . . . . . . . . . . . . . . . .. 165 DTFDI macro ....................... 44 DTFDR macro ....................... 48 DTFDU macro . . . . . . . . . . . . . . . . . . . . . . . 58 DTFEN card ... . . . . . . . . . . . . . . . . . . .. 117 DTFIS macro. . . . . . . . . . . . . . . . . .. 194, 351 DTFMR macro ...................... 63 DTFMT macro . . . . . . . . . . . . . . . . . . . . . . . 67 DTFOR macro . . . . . . . . . . . . . . . . . . . . . . . 78 DTFPH macro . . . . . . . . . . . . . . . . . . . . . . 254 DTFPR macro . . . . . . . . . . . . . . . . . . . . . . . 84 DTFPT macro ....................... 90 DTFSD macro . . . . . . . . . . . . . . . . . . . . . . . 98 error options ..................... 102 DTFSR macro ...................... 108 DTFxx macro (see DTF macro) dummy entry for ISAM indexes .......... 189 DUMODFx macro .................... 62 dump macros for ....................... 282 DUMP macro ...................... 282 dump partition macro ................. 282 ECB (event control block) ............. 288 editing (see link-editing) end file load mode macro .............. 208 DASD label processing ............... 24 diskette processing .................. 25 magnetic tape label processing input files ...................... 28 output files ..................... 26 paper tape processing ................ 94 end-of-job-step macro ................. 283 end-of-record character for paper tape ...... 92 end-of-volume DASD label processing ............... 23 diskette processing .................. 25 forced for PIOCS ..................... 260 for SAM ...................... 154 magnetic tape label processing input files ...................... 28 output files ..................... 26 end set limit macro . . . . . . . . . . . . . . . . . . . 213 ENDFL macro ...................... 208 ENDREQ macro ............. 242, 222, 224 ENHP (european numeric hand printing) . . . . . 54 ENQ macro . . . . . . . . . . . . . . . . . . . . . . . . 290 enqueue macro ...................... 290 EODAD VSAM exit routine ............ 222 Index 359 EOF (see end-of-file) EO] macro ........................ 283 EOV (see end-of-volume) ERASE macro ...................... 242 ERET macro for ISAM . . . . . . . . . . . . . . . . . . . . . . .. 206 for SAM ........................ 144 error conditions CCB ......................... 252 DAM .................... 167, 169 ISAM .................... 196, 197 paper tape ...................... 95 options (DTFSD) .................. 102 return macro (see ERET macro) status indication bits (DAM) .......... 169 ESETL macro ...................... 213 event control block (ECB) ............. 288 example address constants, relocating ...... 328, 329 assembling a format record for the 3886 optical character reader ........ 319 assembling program, DTFs, and modules . . 304 coding form (see coding form examples) combined file ..................... 134 GET macro processing .............. 129 ISAM file ....................... 192 nonstandard label processing .......... 324 relocating address constants . . . . . .. 328, 329 relocating program ................. 330 self-relocating program .............. 330 subset-superset module ........................ 16 names chart . . . . . . . . . . . . . . . . . . . . . 17 EXCP macro ....................... 253 EXCPAD VSAM exit routine ........... 223 execute form of control block manipulation macros . . . . . . . . . . .. 236, 228 examples ....................... , 236 exit list (EXLST) for VSAM . . . . . . . . . . . . 222 EXIT macro ....................... 280 exit supervisor macros ................. 276 EXLST macro ...................... 222 examples ... . . . . . . . . . . . . . . . . . . . . . 227 extent job control statement ............. 14, 23 split cylinder ..................... 126 EXTENT job control statement . . . . . . .. 14, 23 external references in DTF table .......... 18 FCEPGOUT macro .................. 269 FEOV macro for PIOCS . . . . . . . . . . . . . . . . . . . . . . . 260 for SAM ........................ 154 360 DOS/VS Supervisor & I/O Macros FEOVD macro ...................... 155 FETCH macro . . . . . . . . . . . . . . . . . . . . . . 265 field information (DLINT) ................ 56 name ............................ 19 operand .......................... 19 operation . . . . . . . . . . . . . . . . . . . . . . . . . 19 sequence-link . . . . . . . . . . . . . . . .. 192, 200 file associated (see associated files) checkpoint . . . . . . . . . . . . . . . . . . . . . . . 285 combined (see combined file) definition macro (see DTF macro) entry-sequenced (VSAM) ............ 217 key-sequenced (VSAM) ............. 217 labels (see labels) shared .......................... 293 work ........................... 150 filename for declarative macros ........... 19 filename A ......................... 191 filenameC .................. 196, 206, 208 filenamel . . . . . . . . . . . . . . . . . . . . . . . . . . 191 filenameO ......................... 191 filenameP ......................... 191 filenameR ......................... 191 filename T ......................... 191 filename+48 - filename + 76 for DTFOR ....................... 81 for DTFSR ...................... 110 filename + 80 for DTFOR . . . . . . . . . . . . . . . . . . . . . . . 80 for DTFSR ...................... 109 fix page macro . . . . . . . . . . . . . . . . . . . . . . 267 font codes for 3886 ................... 54 forced end-of-volume for PIOCS ....................... 260 for SAM ........................ 154 format CCB ........................... 250 communication region ............... 273 conventions ....................... 20 descriptor card ..................... 39 keyword ......................... 19 macro '" . . . . . . . . . . . . . . . . . . .. 19,218 mixed ........................... 19 positional . . . . . . . . . . . . . . . . . . . . . . . . . 19 FREE macro ....................... 292 free page macro ..................... 292 FREEVIS macro .................... 273 GENCB (generate control block) macro .... 228 examples ........................ 229 generate form of control block manipulation macros .......... 236, 228 examples . . . . . . . . . . . . . . . . . . . . . . . . 237 generating logic modules . . . . . . . . . . . . . . . . . .. 11, 16 VSAM blocks and lists .............. 228 GENL (generate a directory list) macro .... 266 GET macro for ISAM . . . . . . . . . . . . . . . . . . . . . . . . 202 for SAM . . . . . . . . . . . . . . . . . . . . . . . . 128 for VSAM . . . . . . . . . . . . . . . . . . . . . . . 241 GETIME macro . . . . . . . . . . . . . . . . . . . . . 275 GETVIS macro . . . . . . . . . . . . . . . . . . . . . 272 header card .......... . . . . . . . . . . . . . . . 19 heaqer labels DASD . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 magnetic tape . . . . . . . . . . . . . . . . . . . . . . 27 hexadecimal control character codes ....... 301 hold, track (see track hold) IBM-supplied macros .................. 12 identifier, DAM record ............ 162, 163 lIP (ISAM Interface Program) ....... 187,351 IJCxxxxx (CDMOD) .................. 41 IJDxxxxx (PRMOD) . . . . . . . . . . . . . . . . . . . 89 IJExxxxx (PTMOD) ................... 96 IJFxxxxx (MTMOD) .................. 78 IJGxxxxx (SDMODxx) ................ 107 IJHxxxxx (ISMOD) .................. 203 IJlxxxxx (DAMOD) .................. 177 IJJxxxxx (DIMOD) .................... 47 IJMxxxxx (ORMOD) .................. 84 IJUxxxxx (MRMOP) .................. 67 imperative 10CS macros description of . . . . . . . . . . . . . . . . . . . . . . 11 for DAM . . . . . . . . . . . . . . . . . . . . . . . . 179 for ISAM . . . . . . . . . . . . . . . . . . . . . . . . 295 for SAM . . . . . . . . . . . . . . . . . . . . . 31, 124 for VSAM . . . . . . . . . . . . . . . . . . . . . . . 238 restriction regarding modules ........... 16 independence (see device independence) independent overflow area . . . . . . . . . . . . .. 191 index,ISAM cylinder . . . . . . . . . . . . . . . . . . . . . . . . . 189 master . . . . . . . . . . . . . . . . . . . . .. 190, 200 SKIP feature ..................... 198 track . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Indexed Sequential Access Method (see ISAM) indexed sequential file (DTFIS) .......... 194 indexed sequential module (ISMOD) ....... 201 initialization macros for DAM . . . . . . . . . . . . . . . . . . . . . . . . 179 for ISAM '. . . . . . . . . . . . . . . . . . . . . . . . 205 for Ploes . . . . . . . . . . . . . . . . . . . . . . . 257 for SAM . . . . . . . . . . . . . . . . . . . . . . . . 124 for VSAM . . . . . . . . . . . . . . . . . . . . . . . 238 initiation, subtask . . . . . . . . . . . . . . . . . . . . 288 input files DASD labels . . . . . . . . . . . . . . . . . . . . . . 24 diskette labels . . . . . . . . . . . . . . . . . . . . . 25 magnetic tape labels ................. 28 input/output area (see I/O area) interrupt interval timer . . . . . . . . . . . . . . . . . . . . . 276 intertask communication macros . . . . . . . . . . 291 jnterval timer macros ................. 276 10CS macros . . . . . . . . . . . . . . . . . . .. 11, 249 ISAM (Indexed Sequential Access Method) adding records ............. 190, 198, 208 completion macros ................. 213 concepts of . . . . . . . . . . . . . . . . . . . . . . 187 creating a file . . . . . . . . . . . . . . . .. 198, 205 declarative macros ................. 194 example of file . . . . . . . . . . . . . . . . . . .. 192 extending a file . . . . . . . . . . . . . . .. 205, 207 file (DTFIS) . . . . . . . . . . . . . . . . . . . . . 194 null. . . . . . . . . . . . . . . . . . . . . . . . .. 191 imperative macros . . . . . . . . . . . . . . . . . . 205 indexes . . . . . . . . . . . . . . . . . . . . . . . . . 189 initialization macros ................ 205 I/O areas . . . . . . . . . . . . . . . . . . . . . . . 188 keys (see keys) loading a file ................. 198, 207 logic module . . . . . . . . . . . . . . . . . . . . . 200 organization. . . . . . . . . . . . . . . . . . . . .. 187 overflow . . . . . . . . . . . . . . . . . . . . . . . . 190 processing macros . . . . . . . . . . . . . . . . . . 206 programming considerations . . . . . . . . . .. 191 programs, processing VSAM files . . . . . . . . . . . . . . . . . . . . 187 random retrieval ............ 198, 201, 209 random updating . . . . . . . . . . . . . . . . . . . 210 record types . . . . . . . . . . . . . . . . . . . . .. 187 sequential retrieval .......... 198, 201, 211 statistics . . . . . . . . . . . . . . . . . . . . . . . . 191 storage areas . . . . . . . . . . . . . . . . . . . . . 187 work area . . . . . . . . . . . . . . . . . . . . . . . 201 ISAM Interface Program (lIP) ........... 187 ISMOD macro . . . . . . . . . . . . . . . . . . . . . . 201 I/O area description of . . . . . . . . . . . . . . . . . . . .. 128 use of for DAM . . . . . . . . . . . . . . . . .. 159, 173 for ISAM . . . . . . . . . . . . . . . . . . . . .. 188 for SAM .................. 105, 129 I/O assignment, symbolic description of . . . . . . . . . . . . . . . . . . . . . . 14 releasing . . . . . . . . . . . . . . . . . . . . . . . . 275 JDUMP macro . . . . . . . . . . . . . . . . . . . . . . 283 Index 361 key-sequenced file ................... 217 keyed access ....................... 217 keys for DAM description of . . . . . . . . . . . . . . . . . .. 159 processing of ............ 174, 176, 181 for ISAM description of . . . . . . . . . . . . . . . . . .. 187 keyword operand ..................... 19 LABADDR routine .......................... 24 labels DASD standard .................... 23 diskette . . . . . . . . . . . . . . . . . . . . . . . . . . 25 header DASD ......................... 24 magnetic tape .................... 27 magnetic tape . . . . . . . . . . . . . . . . . . . . . . 26 processing ........................ 23 routine .......................... 24 tape ............................ 26 trailer DASD ......................... 24 magnetic tape .................... 27 user standard .................... 24 LBLTYP job control statement ........ 23, 26 LBRET macro for DAM ........................ 180 for PIOeS . . . . . . . . . . . . . . . . . . . . . . . 259 for SAM ........................ 127 LERAD VSAM exit routine . . . . . . . . . . . . . 223 library· macro ........................... 11 relocatable, how to use ............... 18 source statement .................... 11 light macro ........................ 146 limitations (see restrictions) link-editing ..................... 18, 326 link field for ISAM chaining ........ 192, 200 linkage editing ................... 18, 326 linkage macros ...................... 295 linkage registers . . . . . . . . . . . . . . . . . . . . . 297 list form of control block manipulation macros ....... 236, 228, 345 examples . . . . . . . . . . . . . . . . . . . . . . . . 236 listing, selective tape . . . . . . . . . . .. 88, 89, 131 LITE macro . . . . . . . . . . . . . . . . . . . . . . .. 146 LOAD macro . . . . . . . . . . . . . . . . . . . . . . . 266 loader, relocating .................... 328 loading a program, macros for ........... 266 locate mode (VSAM) ................. 217 362 DOS/VS Supervisor & I/O Macros logic module assembling . . . . . . . . . . . . . . . . . . . . . . . . 18 cataloging ........................ 18 eDMOD ......................... 40 DAMOD ........................ 176 description of . . . . . . . . . . . . . . . . . .. 11, 16 DIMOD ......................... 47 entry points . . . . . . . . . . . . . . . . . . . . . . . 17 generation macro ................ 11, 16 ISMOD ......................... 200 link-editing ................... 18, 326 linkage with DTF . . . . . . . . . . . . . .. 18, 304 macro . . . . . . . . . . . . . . . . . . . . . . .. 11, 16 MRMOD ......................... 67 MTMOD ......................... 76 names ........................... 17 ORMOD . . . . . . . . . . . . . . . . . . . . .. 83, 84 PRMOD ......................... 88 providing . . . . . . . . . . . . . . . . . . . . . . . . . 17 PTMOD ................... 16, 96, 97 restriction ........................ 16 SDMODxx . . . . . . . . . . . . . . . . . . . . . .. 105 shared .......................... 293 subset description of . . . . . . . . . . . . . . . . . . . . 17 superset description of . . . . . . . . . . . . . . . . . . . . 17 ways of providing . . . . . . . . . . . . . . . . . . . 17 logical units programmer . . . . . . . . . . . . . . . . . . . . . . . 15 system ........................... 15 macro assembling . . . . . . . . . . . . . . . . . . . . . . . . 18 cataloging ........................ 18 categories of ...................... 11 coding example . . . . . . . . . . . . . . . . . . . . . 13 communication . . . . . . . . . . . . . . . . . . . . 274 completion for DAM ...................... 184 for ISAM ...................... 213 for PIOeS ..................... 260 for SAM ...................... 154 for VSAM ..................... 239 declarative description of . . . . . . . . . . . . . . . . . . .. 11 for DAM ...................... 165 for ISAM . . . . . . . . . . . . . . . . .. 194, 201 for PIOeS . . . . . . . . . . . . . . . . . . . . . 254 for SAM .................... 31, 34 for VSAM .................. 11,220 definition (see macro definition) DTFxx (see DTF macro) example .......................... 13 expansion ........................ 12 format. . . . . . . . . . . . . . . . . . . . . .. 19,218 imperative description of . . . . . . . . . . . . . . . . . . . . 11 for DAM ...................... 179 for ISAM ...................... 205 for SAM ................... 31, 124 for VSAM ..................... 238 initialization for DAM ...................... 179 for ISAM . . . . . . . . . . . . . . . . . . . . . . 205 for PIOCS . . . . . . . . . . . . . . . . . . . . . 257 for SAM ...................... 124 for VSAM ..................... 238 interrelationship .................... 17 intertask communication ............. 291 interval timer ..................... 276 IOCS (see macro, declarative macro, imperative) library ........................... 11 link-editing ....................... 18 LIOCS (logical IOCS) . . . . . . . . . . . . . . . . 31 (see also macro, declarative macro, imperative) list of types ....................... 13 logic module generation (see logic module) logicallOCS ...................... 31 (see also macro, declarative macro, imperative) multitasking . . . . . . . . . . . . . . . . . . . . . . 288 PIOCS (physical IOCS) . . . . . . . . . . . . . . 249 processing for DAM ...................... 180 for ISAM ...................... 206 for SAM ...................... 127 for VSAM ..................... 241 protection DASD track . . . . . . . . . . . . . . . . . . . . 292 resource ....................... 289 program loading . . . . . . . . . . . . . . . . . . . 266 resource protection ................. 289 self-relocating, how to make ........... 19 source program . . . . . . . . . . . . . . . . . . . . . 11 storage, virtual . . . . . . . . . . . . . . . . . . . . 266 sublibrary ........................ 11 supervisor .................... 11, 265 system (see macro system) timer ........................... 276 time-of-day ...................... 275 track protection ................... 292 types of .......................... 11 usage ........................... 11 virtual storage .................... 266 macro definition description of . . . . . . . . . . . . . . . . . . . . . . 11 macro system description of . . . . . . . . . . . . . . . . . . . . . . 11 magnetic ink character reader (see MICR) magnetic reader file (DTFMR) ..................... 63 imperative macros . . . . . . . . . . . . . . . . .. 145 module (MRMOD) .................. 67 magnetic tape backwards reading .............. 29, 130 checkpointing . . . . . . . . . . . . . . . . .. 27, 283 CNTRL macro codes ............... 139 file (DTFMT) ..................... 67 labels . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 module (MTMOD) .................. 76 reading backwards .............. 29, 130 repositioning for restart .............. 286 master index for ISAM ............ 190, 200 MICR (magnetic ink character reader) buffer, document ............... 63, 331 characteristics ...................... 63 checkpoint file .................... 285 document buffer . . . . . . . . . . . . . . .. 63, 331 file checkpoint . . . . . . . . . . . . . . . . . . . . . 285 declaration (DTFMR) .............. 63 module (MRMOD) .................. 67 processing characteristics . . . . . . . . . . . . . . 63 stacker selection routine .............. 63 mixed format ........................ 19 MODCB (modify control block) macro . . . . . 230 modifying VSAM blocks and lists . . . . . . . . . 230 module (see logic module) move mode (VSAM) ................. 217 move to communication region macro ...... 275 MRMOD macro ...................... 67 MTMOD macro ...................... 76 multitasking macros .................. 288 MVCOM macro ..................... 274 names field . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 file ............................. 18 logic module ...................... 17 standard ......................... 17 subset/ superset description ............ 17 symbolic unit . .o......... . . . . . . . . . . . 15 user-supplied ...................... 18 NHP (numeric hand printing) ............ 54 nonstandard labels processing . . . . . . . . .. 27, 29 notation, register ..................... 20 notational conventions ............. 20, 218 NOTE macro ....................... 152 null file, ISAM ...................... 191 Index 363 OCR (see optical reader) opening (see OPEN(R) macro) OPEN(R) macro DASD label processing ........... 23, 124 diskette label processing .......... 23, 126 for DAM. . . . . . . . . . . . . . . . . . .. 179, 180 for ISAM . . . . . . . . . . . . . . . . . . . . . . . . 205 for PIOCS . . . . . . . . . . . . . . . . . . . . . . . 257 for SAM ........................ 124 for VSAM ....................... 238 operand cards ............................ 19 field ............................ 19 keyword ......................... 19 mixed ........................... 19 notation for VSAM macros ........... 341 positional . . . . . . . . . . . . . . . . . . . . . . . . . 19 operation field ....................... 19 operator verification table .............. 287 optical character reader (3886) declarative macros .................. 48 define format record (DFR) . . . . . . . . . . . . 52 define line type (DLINT) ............. 56 field information entries (DLINT) ....... 56 line information entries ............... 56 file (DTFDR) . . . . . . . . . . . . . . . . . . . . . . 48 imperative macros. . . . . . . . . . . . . . . . .. 149 module (DRMOD) .................. 51 sample format record assembly . . . . . . . . . 319 optical mark reader (3881) restrictions concerning CDMOD . . . . . . . . . 41 optical reader (1287) file (DTFOR) ..................... 78 format descriptor, card ............... 39 imperative macros . . . . . . . . . . . . . . . . .. 147 module (ORMOD) ............... 83,84 processing considerations . . . . . . . . . .. 63, 83 restrictions concerning GET or READ ... 112 ordinary register notation ............... 20 ORMOD macro . . . . . . . . . . . . . . . . . .. 83, 84 output files DASD labels ...................... 24 diskette labels ..................... 25 magnetic tape labels ................. 26 overflow, ISAM area ........................... 190 cylinder . . . . . . . . . . . . . . . . . . . . . .. 190 independent . . . . . . . . . . . . . . . . . . .. 191 statistics ........................ 191 overflow, printer macro .......................... 144 overlap, physical transient .............. 265 page fix macro . . . . . . . . . . . . . . . . . . . . . . 267 364 DOS/VS Supervisor & I/O Macros page free macro 268 270 PAGEIN macro paper tape data check ........................ 95 end-of-file ........................ 94 end-of-record character . . . . . . . . . . . . . . . 92 errors ..................... 92, 94, 95 file (DTFPT) ...................... 90 length ........................... 95 listing on 1403 . . . . . . . . . . . . . . . .. 89, 131 module (PTMOD) ............... 96, 97 processing considerations . . . . . . . . . .. 94, 95 selective tape listing on 1403 ....... 89, 131 trailer length ...................... 95 wrong length ...................... 95 parameter lists for VSAM macros ................. 228 parentheses ........................ 218 partial dump macro ................... 282 PDUMP macro ..................... 282 PFIX macro . . . . . . . . . . . . . . . . . . . . . . . . 267 PFREE macro ...................... 268 phase fetching . . . . . . . . . . . . . . . . . . . . . . . . . 265 loading ......................... 266 physical IOCS concepts of ...................... 249 file (DTFPH) . . . . . . . . . . . . . . . . . . . . . 254 macros ...................... 249-261 physical transient overlap .............. 265 PIOCS (see physical IOCS) pocket selection for MICR ........... 63, 64 POINT macro ...................... 242 POINTR macro ..................... 152 POINTS macro ..................... 153 POINTW macro ............. 153 positional operand .................... 19 POST macro ....................... 291 pre loading registers . . . . . . . . . . . . . . . . . . . . 20 prime record count . . . . . . . . . . . . . . . . . .. 191 printer codes .......................... 139 control ..................... 135, 302 file (DTFPR) . . . . . . . . . . . . . . . . . . . . . . 84 module (PRMOD) .................. 88 overflow macro ................... 144 printer keyboard buffer ........................... 42 file (DTFCN) ..................... 42 PRMOD macro ...................... 88 processing macros for DAM ........................ 180 for ISAM . . . . . . . . . . . . . . . . . . . . . . . . 206 for SAM ........................ 127 for VSAM ....................... 241 t ••••••• processing, sequential (see SAM) program assembling .................. " 18, 304 called .......................... 299 calling . . . . . . . . . . . . . . . . . . . . . . . . . . 299 communication macros .......... 273, 274 communication region (see communication region) linkage macros .................... 295 loading macros . . . . . . . . . . . . . . . . . . . . 265 self-relocating how to write .................... 19 programmer logical units . . . . . . . . . . . . . . . . 15 protection macros DASD track ...................... 292 resource ........................ 289 track ........................... 292 PRTOV macro ...................... 144 PTMOD macro ................... 96, 97 punch (see card punch) PUT macro for ISAM ........................ 212 for SAM ........................ 130 for VSAM ....................... 241 PUTR macro ....................... 136 random retrieval for ISAM ...... 198, 201, 209 RBA (relative byte address) ............. 217 RCB macro ........................ 289 RDLNE macro ...................... 149 read line macro ..................... 149 READ macro for DAM ........................ 181 for ISAM ........................ 210 for magnetic reader ................. 145 for optical character reader (3886) ...... 149 for optical reader (1287) ............. 148 for work files . . . . . . . . . . . . . . . . . . . .. 151 reader (see card reader; magnetic reader; optical reader) reading tape backwards .............. 29,130 REALAD macro .................... 272 record blocked GET macro processing ............ 129 PUT macro processing . . . . . . . . . . . .. 132 capacity ...................... 164,183 command chained GET macro processing ............ 130 PUT macro processing . . . . . . . . . . . .. 132 DAM, types for ................... 159 ISAM, organization of ............... 187 reference for DAM . . . . . . . . . . . .. 161, 162 spanned DTFMT, I/O area for. . . . . . . .. 176, 130 DTFSD, I/O area for ......... 103, 130 GET macro processing ............ 130 PUT macro processing . . . . . . . . . . . .. 133 types for DAM . . . . . . . . . . . . . . . . . . .. 159 unblocked GET macro processing ............ 129 PUT macro processing . . . . . . . . . . . .. 132 undefined GET macro processing ............ 130 PUT macro processing . . . . . . . . . . . .. 133 variable-length PUT macro processing . . . . . . . . . . . .. 132 zero (DAM capacity record) ....... 164,183 record identifiers (DAM) . . . . . . . . . . . . . .. 162 record keys (DAM) ............... 159-162 references, external in DTF table ........ 14,18 register conventions ....................... 20 linkage ......................... 297 notation . . . . . . . . . . . . . . . . . . . . . . . . . . 20 pre loading .................. . . . . . . 20 restoring ........................ 297 restriction for 1275 and 1419 ........... 65 saving and restoring ................ 297 usage ........................... 21 relative byte address (RBA) . . . . . . . . . . . .. 217 RELEASE macro . . . . . . . . . . . . . . . . . . . . 275 (see also RELSE macro) releasing I/O units ................... 275 relocatable library, how to use .................. 18 programs . . . . . . . . . . . . . . . . . . . .. 19, 326 relocating loader . . . . . . . . . . . . . . . . . . . . . 328 relocation of address constants . . . . . . . . . . . 326 RELPAG macro ..................... 268 RELSE macro ...................... 136 (see also RELEASE macro) reopening a file ...................... 23 repositioning magnetic tape ............. 286 request macros (VSAM) ............... 241 request parameter list (RPL) for VSAM ................... 224,241 chaining RPLs ............. 225, 222, 224 RESCN macro . . . . . . . . . . . . . . . . . . . . .. 148 resource control block macro (RCB) ........... 289 macros ......................... 289 protection macros .................. 289 restart (see checkpoint) restoring registers .................... 297 return codes from GENCB, MODCB, SHOWCB, and TESTCB macros . . . . . . . . . . . . . . 235 from CLOSE macro ................ 240 Index 365 from OPEN macro ................. from request macros ................ from TCLOSE macro ............... RETURN macro .................... RPL macro ........................ examples ... . . . . . . . . . . . . . . . . . . . . . RUNMODE macro ................... RZERO for DAM ............... 164, 238 242 240 300 224 227 271 183 SAM (Sequential Access Method) card file (DTFCD) .................. 34 card module (CDMOD) .............. 40 CDMOD ......................... 40 completion macros ................. 154 console file (DTFCN) . . . . . . . . . . . . . . . . 42 DASD file (DTFSD) ................. 98 DASD module (SDMODxx) . . . . . . . . . .. 105 declarative macros ............ 13, 31, 34 device independent file (DTFDI) ........ 44 device independent module (DIMOD) ..... 47 DFR ............................ 52 DIMOD ......................... 47 disk file (DTFSD) .................. 98 disk module (SDMODxx) ............ 105 DLINT .......................... 56 DRMOD ......................... 51 DTFCD .......................... 34 DTFCN ......................... 42 DTFDI .......................... 44 DTFDR .......................... 48 DTFMR ......................... 63 DTFMT ......................... 67 DTFOR .......................... 78 DTFPR .......................... 84 DTFPT .......................... 90 DTFSD .......................... 98 DTFSR ......................... 108 imperative macros . . . . . . . . . . . . . .. 31, 124 magnetic reader file (DTFMR) ................... 63 macros for processing ............. 145 module (MRMOD) ................ 67 magnetic tape file (DTFMT) ........... 67 magnetic tape module (MTMOD) ........ 76 MRMOD ......................... 67 MTMOD ......................... 76 optical reader file (DTFOR) . . . . . . . . . . . . . . . . . . . . 78 macros for processing ......... 147, 149 module (ORMOD) ................ 83 ORMOD ......................... 83 paper tape file (DTFPT) .............. 90 paper tape module (PTMOD) ....... 16, 96 printer file (DTFPR) . . . . . . . . . . . . . . . . . 84 366 DOS/VS Supervisor & I/O Macros printer module (PRMOD) ............. 88 PRMOD ......................... 88 processing macros .................. 127 PTMOD ......................... 96 SDMODxx . . . . . . . . . . . . . . . . . . . . . .. 105 sequential DASD file (DTFSD) ......... 98 sequential DASD module (SDMODxx) ... 105 serial device file (DTFSR) ............ 108 workfile macros ................... 150 save area program linkage ................... 297 register ......................... 297 subtask ......................... 288 SAVE macro . . . . . . . . . . . . . . . . . . . . . . . 300 SDMODxx macro . . . . . . . . . . . . . . . . . . .. 105 subsetI superset names . . . . . . . . . . . . . .. 108 selective tape listing feature . . . . . . . . . . . .. 131 self-relocating program exampk . . . . . . . . . . . . . . . . . .. 326, 330 rules for writing .............. 19, 326 SEOV macro . . . . . . . . . . . . . . . . . . . . . . . 260 sequence-link field ............... 192, 200 Sequential Access Method (see SAM) sequential DASD file (DTFSD) ........... 98 sequential DASD module (SDMODxx) ..... 105 sequential retrieval for ISAM ..... 198, 201, 211 serial device file (DTFSR) . . . . . . . . . . . . .. 108 set exit macro (STXIT) ................ 276 set file load mode macro (SETFL) ........ 207 set interval timer macro (SETIME) ........ 276 set limits macro (SETL) ............... 211 set linkage to routines macro (STXIT) ........................ 276 set page fault appendage macro (SETPFA) ....................... 271 set timer macro (SETIME) ............. 276 SETDEV macro (3886) ............... 150 SETFL macro ...................... 207 SETIME macro ..................... 276 SETL macro ....................... 211 SETPFA macro ..................... 271 shared file . . . . . . . . . . . . . . . . . . . . . . . . . 293 shared module ...................... 293 SHOWCB (display control block) macro . . . . 231 examples ........................ 232 skip sequential processing .............. 217 source-program macro . . . . . . . . . . . . . . . . . . 11 source statement library ................ 11 spanned records. DTFDA I/O area for ............... 160 DTFMT 110 area for ............... 130 DTFSD I/O area for. . . . . . . . . . .. 103, 130 GET macro processing .............. 130 PUT macro processing . . . . . . . . . . . . . .. 133 special register notation . . . . . . . . . . . . . . . . . 20 split-cylinder extents . . . . . . . . . . . . . . . . .. 126 stacker selection routine, MICR . . . . . . . . . . . 63 standard form of control block manipulation macros . . . . . . . . . . .. 228, 345 standard labels DASD ............ " ............. 23 user ............................ 24 standard module names . . . . . . . . . . . . . . . . . 17 status code for DAM ........................ 169 for ISAM . . . . . . . . . . . . . . . . . . . . . . .. 196 storage area (see I/O area) virtual access method (see VSAM) macros ....................... 266 STXIT macro ....................... 276 sublibrary, macro ..................... 11 subset module description of . . . . . . . . . . . . . . . . . . . . . . 16 names ........................... 17 sub task initiation macro ................... 288 save area . . . . . . . . . . . . . . . . . . . . . . . . 288 termination macro .................. 289 superset module description of . . . . . . . . . . . . . . . . . . . . . . 16 names ........................... 17 supervisor communication region ............... 274 macros ...................... 11, 265 symbolic I/O assignment description of . . . . . . . . . . . . . . . . . . . . . . 14 symbolic unit addresses ................. 14 symbolic unit names . . . . . . . . . . . . . . . . . . . 14 SYNAD VSAM exit routine ............. 224 SYSCAT .......... ~ ................ 15 SYSCLB ........................... 15 SYSIPT ............................ 15 SYSLNK ........................... 15 SYSLOG ........................... 15 SYSLST ........................... 15 SYSmax ........................... 15 SYSnnn ............................ 15 SYSPCH ........................... 15 SYSRDR .. " ....................... 15 SYSREC ........................... 15 SYSRES ........................... 15 SYSRLB ........................... 15 SYSSLB ........................... 15 system end-of-volume macro (SEOV) ...... 264 system logical units .................... 15 SYSVIS ............................ 15 table, operator verification . . . . . . . . . . . . . . 287 tape (see magnetic tape; paper tape) task (see subtask) TCLOSE macro . . . . . . . . . . . . . . . . . . . . . 240 TECB macro . . . . . . . . . . . . . . . . . . . . . . . 281 termination abnormal, codes for ................ 277 macros ..................... 283,289 (see also completion macros) subtask ..................... 283, 289 test time interval macro (TTIMER) ....... 276 TESTCB (test control block) macro ....... 233 examples " ...................... 235 testing VSAM blocks and lists ........... 233 time-of-day macro (GETIME) ........... 275 timer event control block macro (TECB) .,. 281 timer macros ....................... 281 timing for MICR stacker selection ......... 64 track hold description of . . . . . . . . . . . . . . . . . . . . . 292 macros for. . . . . . . . . . . . . . . . . .. 202, 292 track index for ISAM ................. ~ 89 track protection ................. 198, 292 (see also track hold) track reference for DAM ............... 161 trailer labels DASD ........................... 24 magnetic tape . . . . . . . . . . . . . . . . . . . . . . 27 transient overlap, physical .............. 265 TRUNC macro ..................... 137 truncate macro (TRUNC) .............. 137 TTIMER macro ................. 276,281 UCS (universal character set) codes ....... 140 unblocked records GET macro processing .............. 129 PUT macro processing . . . . . . . . . . . . . .. 132 undefined records GET macro processing .............. 130 PUT macro processing . . . . . . . . . . . . . ., i 3:3 unit addresses, symbolic ................ 14 unit names, symbolic . . . . . . . . . . . . . . . . . . . 14 units, system logical ................... 15 units, programmer logical . . . . . . . . . . . . . . . . 15 universal character set codes ............ 140 unlabeled tape files . . . . . . . . . . . . . . . . . . . . 28 updating .......................... 133 (see also associated files; combined file) , user-standard labels ................... 24 user-supplied names ................... 18 variable-length record PUT macro processing . . . . . . . . . . . . . .. 132 VIRTAD macro . . . . . . . . . . . . . . . . . . . . . 271 Virtual Storage Access Method (see VSAM) Index 367 virtual storage macros . . . . . . . . . . . . . . . . . 266 volume end of (see end-of-volume) label . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 volume table of contents (VTOC) ......... 23 VSAM (Virtual Storage Access Method) . . .. 215 control blocks and lists .............. 220 description . . . . . . . . . . . . . . . . . . .. 11, 217 ISAM Interface Program (lIP) ......... 187 types of macros ................... 218 control block generation macros . . . . . . . . . . . . . . 220 mahipulation macros ............ 228 OPE~, and (T)CLOSE macros ....... 238 request macros . . . . . . . . . . . . . . . . . . 24 ~ types of processing . . . . . . . . . . . . . . . . . 217 VTOC (volume table of contents) ......... 23 WAIT macro . . . . . . . . . . . . . . . . . . . . . . . 254 WAITF macro for DAM . . . . . . . . . . . . . . . . . . . . . . . . 183 for ISAM . . . . . . . . . . . . . . . . . . . . . . . . 210 for magnetic reader ............... " 146 for optical character reader (3886) ...... 150 for optical reader (1287) ............. 149 for SAM ................. 146, 149, 150 WAITM macro ................. 282, 291 work area description of . . . . . . . . . . . . . . . . . . . .. 128 ISAM storage requirements ........... 201 MICR document buffer ............... 63 use with I/O area for ISAM . . . . . . . . . . . . . . . . . . . . .. 188 for SAM ...................... 128 work file macros . . . . . . . . . . . . . . . . . . . .. 150 WRITE macro for DAM . . . . . . . . . . . . . . . . . . . . . . . . 181 for ISAM ................. 207, 2{)8, 210 for workfiles ..................... 151 wrong-length paper tape records . . . . . . . . . . . 95 xxMOD macro (see logic module generation macro) 368 DOS/VS Supervisor & I/O Macros 1287 CNTRL macro codes ........... 138, 142 macros . . . . . . . . . . . . . . . . . . . . . . . . . 147 1288 CNTRL macro codes ........... 138, 142 programming considerations . . . . . . . . . . . . 83 1403 CNTRL macro codes ........... 138, 140 selective tape listing feature . . . . . . . . . .. 131 1442 CNTRL macro codes ........... 138, 140 control character codes ........... :.. 301 2520 CNTRL macro codes ........... 138, 140 control character codes .............. 301 2540 CNTRL m,!cro codes ........... 138, 140 control character codes .............. 301 2560 card device codes .............. 138, 141 control character codes .......... 301, 302 printing . . . . . . . . . . . . . . . . . . . . . . . . , 135 2596 CNTRL macro codes ........... 138, 141 control character codes .............. 301 3211 CNTRL macro codes ......... 138, 140 3504 CNTRL macro codes ........... 138, 141 control character codes .......... 302, 303 3505 CNTRL macro codes ........... 138, 141 control character codes .......... 302, 303 3525 CLOSE(R) card movement ........... 156 CNTRL macro codes ........... 138, 141 control character codes .......... 302, 303 printing ..........." . . . . . . . . . . . . .. 135 3881 138, 142 CNTRL macro codes 3886 CNTRL macro codes 138, 143 macros . . . . . . . . . . . . . . . . . . . . . . . . . 149 5425 card device codes .............. 138, 141 control character codes .......... 301, 302 printing . . . . . . . . . . . . . . . . . . . . . . . .. 135 DOS/VS Supervisor and I/O Macros READER'S COMMENT FORM GC33-5373-2 This sheet is for comments and suggestions about this manual. We would appreciate your views, favorable or unfavorable, in order to aid us in improving this publication. This fonn will be sent directly to the author's department. Please include your name and address if you wish a reply. Contact your IBM branch office for answers to technical questions about the system or when requesting additional publications. Thank you. Name How did you use this manual? Address As a reference source As a classroom text As a self-study text What is your occupation? Your comments* and suggestions: * We would especially appreciate your comments on any of the following topics: Clarity of the text Organization of the text Accuracy Cross-references Index Tables Illustrations Examples Appearance Printing Paper Binding YOUR COMMENTS, PLEASE ... This manual is part of a library that serves as a reference source for systems analysts, programmers and operators of IBM systems. Your answers to the questions on the back of this form, together with your comments, will help us produce better publications for your use. Each reply will be carefully reviewed by the persons responsible for writing and publishing this material. All comments and suggestions become the property of IBM .. n c -l » r o Z C') -l J: en Please note: Requests for copies of publications and for assistance in utilizing your IBM system should be directed to your IBM representative or to the IBM sales office serving your locality. r Z m Fold Fold t •••••••••••••••••••••••••••••• • •• •• •••• •••••••••••••• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• : FIRST CLASS PERMIT NO. 1359 WHITE PLAINS. N. Y. BUSINESS REPLY MAIL NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES o oen < en POSTAGE WILL BE PAID BY ... en c: "i I BM Corporation 1133 Westchester Avenue White Plains, N.Y. 10604 < iii· g II) ::l c.. o s: Attention: Department 813 BP II) (') ..................................................................................................................... a VI 41 s· [ Fold Fold s· c en » G> (") Co) Co) I C1'I Co) -.....I Co) I N International Business Machines Corporation Data Processing Division 1133 Westchester Avenue, White Plains, New York 10604 (U.S.A. only) IBM World Trade Corporation 821 United Nations Plaza, New York, New York 10017 (International) GC33-5373-2 o oCIJ < CIJ CIJ c: '0 CD =2 Q iii' OJ :::J 0. International Business Machines Corporation Data Proceislng Division 1133 Westchester Avenue, White Plains, New York 10604 (U.S.A. only) IBM wor,ld Trade Corporation 821 UniteCi Nations Plaza, New York, New York 10017 (International)
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : No XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37 Create Date : 2012:05:24 17:35:37-08:00 Modify Date : 2012:05:24 19:07:45-07:00 Metadata Date : 2012:05:24 19:07:45-07:00 Producer : Adobe Acrobat 9.51 Paper Capture Plug-in Format : application/pdf Document ID : uuid:8695dbdb-380c-4ea2-9ec4-1b1e4420dc18 Instance ID : uuid:0308fcce-3131-4f12-a5ac-12b7c2371388 Page Layout : SinglePage Page Mode : UseNone Page Count : 372EXIF Metadata provided by EXIF.tools