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 PDF.
Page Count: 372

DownloadGC33-5373-2_DOS_VS_Supervisor_and_IO_Macros_Rel_29_Nov73 GC33-5373-2 DOS VS Supervisor And IO Macros Rel 29 Nov73
Open PDF In BrowserView 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                      : 372
EXIF Metadata provided by EXIF.tools

Navigation menu