GC28 3830 4_OS_VS2_3.8_System_Programming_Library_Data_Management_Oct1981 4 OS VS2 3.8 System Programming Library Data Management Oct1981

User Manual: GC28-3830-4_OS_VS2_3.8_System_Programming_Library_Data_Management_Oct1981

Open the PDF directly: View PDF .
Page Count: 178

Download
Open PDF In Browser	View PDF

GC26-3830-4
File No. S370-30

Systems

OS/VS 2 System
Programming Library:
Data Management
Release 3.8

•

-=-- -=-=
-=. =-------- ---------~-

-~-.-

\ ..

This publication was produced using the
IBM Document Composition Facility
(program number 5748-XX9) and
the maste~ was printed'on the IBM 3800 Printing Subsystem.

Fifth Edition (October 1981)
This ,i s, 'a.' major revisi on, of, and makes obsolete, GC26-3830-3, i tis
technical newsletters GN26-0942, ,GN26-0945, GN26-0950, GN26-0983,
GH26-0986, and GN26-0997, and the System Library Supplement,
0026-6017-0.'
This edition applies to Release 3.8 of OS/VS2 MVS and to any
subsequent releases until otherwise indicated in new editions or
technical ,newsl~tters.
The changes for this edition are summarized under "Summ~ry of
Amendments" following the preface. Specific changes are indicated
bv avert'ical bar,to the left of the change. These bars wi 11 be
deleted at any subsequent republication of the page affected.
Editorial changes that have no technical significance are not
noted.
Changes are periodically made to the information herein; before
using this pUblication in connection with the operation of IBM
systems, consult the latest IBM System/370 and 4300 Pro~~~
Bibilography, GC20-0001, for the editions that are applicable and
current.
.'
It is possible'that this mat~rial may contain reference to, or
informatinn about,'IBM productsCmachines ~nd programs),
programming, or services that are not announced in your country.
Such reference's or informat i on must not be constr~ed to' mean that
IBM interidsto announce such IBM product~,programming, or
services .i~ your country.
PUbli'cat i on5' are,.,not stocked at the address given below; requests
for IBM,puhlica-tions should be,ma'detoyour IBM representative or
to the IBM branch office serving your locality .

A', :form:for'reader' s.comments is provi dedatthe back ofthi s
publi·c~9tion. If the form, has been remov'ed, comments',may'be .
addressed to IBM Corporation, P.O. Box 50020~,Programming
Publishing, San Jose, California, U.S.A. 95150. IBM may use or
d:Lstribufe -any of, the i nfor'm'at: i on you supply in any way it
believes appropriate without incurring any obligati6h wh~tever.
You may, of course, continue to use the information you supply.
C Copyright International Business Machines Corporation 1974,

. •. 1 9 7 5, 197 6) 1'9 7 7, 1 981

PREFACE

This publication provides .information on how to modify and extend
the data manage~ent capabilities of the-MVS system control
program; _the intended audience i~ system programmers.
Some topics included are:
•

Using catalog management macro instructions

•

Maintaining the volume table of contents

•

Executing your own channel programs

•

Using XDAP to read and write data sets on direct-access
devices

•

Password-protecting your data sets

The MVS system control program provides simpler ways (for
example# access-method services, job control language, utility
programs# access-method routines) to do each of these things. The
information presented in this b~ok (consisting of macro
specifications and how-to information) is intended to provide
greater flexibility in using the data management capabilities of
NVS.
Other topics presented are:

•

Using system macro instructions to refer to, validate, and
modify system data areas. Other system macro instructions
de~cribed allow you to obtain device characte~istics, modify
a job file control block# protect data by verifying the data
extent bl~ck, stop the processing of I/O requests, and
perform track capacity calculations.

•

Adding to the image library and retrieving FeB images

•

JES2 printer support

•

Perform special processing before or after certain macro
instructions

•

How storage management routines control space on
direct-access volumes

c
PREREQUISITE READING

Readers are expected to understand how to:
•

Code programs in assembler language as descri bed
OS/VS-DOS/VS-VM/370 Assembler lang~age, GC33-4010.

•

Use the standard linkage conventions as described in OS/VS2
Supervisor_ Services and Macro Instructions, GC28-068~.

•

Maintain the catalog and VIOC as described in OS/VS2 Access
Method Services, GC26-3841# OS/VS2 MVS Utilities, GC26~3902,
and 05/VS2 MVS Data Management S~rvices Guide, GC26-3875.

•

Use the access methods to do input/output using the data
management macros as described in-OS~VS2 MVS Dat~ Management
Serv i cas Gu ide, GC26 -3875, and OS/VS2 NVS Data Nanagement
Macro Instructions, GC26-3873.

•

Protect-data sets as desc~ibed under "IEHPROGM" in OS/VS2 MVS
Utilities, GC26-3902.

Preface

iii

More specific prerequisite reading is listed at the beginning of
each chapter, as it relates to the pa rt i cu la r top i c.

\
RELATED READIUG

All of the chapters of this pUblication refer to OS/VS2 System
Programming library: Debuoginq Handbook, Volume I, GC28-0708,
OS/VS2 System Programming Library: Debugging Handbook, Volume 2,
GC28-0709, and OS/VS System Progrct'l1minJLliprary: Debu9.9.in.g
Handbook, Volume 3, GC28-0710, which contain detailed
descriptions of system control blocks and common work areas. More
specific related reading is listed at the beginning of each
chapter, as it relates to the topic under discussion.

other publications referenced in this manual are:

•

IBM System/370 Principles of Operation, GA22-7000

•

IBM 2821 Control Unit Component Description, GA24-3312

•

IBM 3203 Printer Component Description and Operator's Guide,
GA33-1515

•

IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and
3811 Print~r Control Unit Component Description and
Operator's Guide, GA24-3543

•

IBM 3800 Printing Subsystem Programmer's Guide, GC26-3846

•

MVS/System Proquct Release 2 Installation, Initialization,
and Tuning: JES2 Component, SC23-0046

•

OS/VS2 MVS Checkpoint/Restart, GC26-3877

•
•

OS/VS2 DADSM logic, SY26-3828

•

Device Support Facilities, GC35-0033

•

OS/VS2 I/O Supervisor logic, SY26-3823

•

OS/VS2 JCl, GC28-0692

•

OS/VS Message library: VS2 System Messages, GC38-1002

•

OS/VS2 MVS CVOl Processor, GC26-3864

•

OS/VS2 MVS Resource Access Control Facility (RACF): General
Information Manual, GC28-0722

•

OS/VS2 Open/Close/EOV logic, SY26-3827

•

OS/VS2. System Programming library: Initialization and Tuning
Guide, GC28-0681

•

OS/VS2 MVS System Programming library: JES2, GC23-0002

•

OS/VS2 System Programming library: JES3, GC28-0608

•

System Programming library:
JES2, SC23-0003

•

OS/VS2 System Programming library: Supervisor, GC28-0628

•

OS/VS2 System Programming library: System Generation
Reference, GC26-3792

•

OS/VS Tape labels, GC26-3795

•

OS/VS2 TSO Command language Reference, GC28-0646

Data Facility Device Support: User's Guide and Reference,
SC26-3952

' ........

Network Job Entry Facility for

OS/VS2 System Programming library: Data Management

c:~

•

OS/VS Virtual Storage Access Method (VSAM) Programmer's

•

OS/VS Linkage Editor and Loader, GC26-3813

Guide, GC26-3838

HOW TO USE THIS BOOK
You can use the chapter on catalog management macro instructions
to retrieve catalog information or add, delete, and update
catalog entries for non-VSAM data sets.
If you want to read a data set control block, rename a data set,
or delete a data set using the system macros, the chapter on
maintaining the volume table of contents (VTOe) provides macro
specifications, coding examples, and how-to information.
If you want to code your ot-m channel programs to modi fy the
control program or to provide support for unsupported I/O
devices, the chapter on using EXCP provides detailed descriptions
of the control blocks you must provide and the functions you must
perform.
Macro specifications and how-to information are provided for
using the XDAP macro instruction to read from and write to
direct-access devices without using access-method routines (SAM,
ISAM, or BDAM)'.
If you want to use data set protection for your facility, the
chapter on data set protection:
•

Tells how to build a PASSWORD data set.

•

Describes how the system control program responds to job
control language and IEHPROGM utility statements in
maintaining the PASSWORD data set.

•

Tells you how to use the PROTECT macro instruction to maintain
(add records to, delete records from, changes records in) and
read the PASSWORD data set.

The chapter on system macro instructions provides how-to
information and macro specifications for:

•

Using system mapping macros to allow you to access system
control blocks and work areas using symbolic names.

•

Examining device-type information in unit control blocks
(UCBs) .

•

Modifying a job file control block (JFCB) before opening a
data set.

•

Stopping the processing of specified I/O requests,
permanently or temporarily.

•

Protecting your data sets by verifying data extent blocks.

•

Performing track capacity calculations.

You can use the coding examples and how-to information in the
chapter on adding and retrieving from the image library to help
you add a universal character set (UCS) image or a forms control
buffer (FCB) image to the system image library (SYS1.IMAGELIB).
Other topics presented are:

•

1~03,

3203-5, and 3211 printers JES2 support

•

OPEN and EOV macro user exits form when a format-l DSCB cannot
be found

Preface

•

How you can perform special processing before and after the
CATALOG, SCRATCH, and RENAME macros by replacing the supplied
dummy modules

•

How ~h~ direct access device storage management (DADSM)
routines control space on DASD v~lum~s.

In this manual, any references made to an IBM program product are
not iritended to state or imply that IBM's program ptoduct only may
be used; any functionally equivalent program may be used instead.
This manual has references to the following IBM program product:
RACF - Resource Access Control Facility,
Program Number 5740-XXH

\..

c
vi

OS/VS2 System Programming Library: Data Management

SUMN~RY

OF AMENDMENTS

SAM-E ENHANCEMENTS
The section "Specifying Buffer Numbers for SAM-E DASD Data Sets"
has been added.

DATA FACILITY DEVICE SUPPORT--3375 SUPPORT
The information received from issuing the DEVTYPE macro for the
IBM 3375 has been included.

OTHER CHANGES
The section "Controlling Space on DASD Volumes" has been added.
This information was previously contained in OS/VS2 DADSM logic.
The explanation of return code 8 from the TRKCAlC macro has been
updated.

OS/VS2 MVS DATA FACILITV DEVICE SUPPORT ENHANCEMENTS
Information to support the above has been added to the section
"I nit i at i on of the Channel Program."

OS/VS2 MVS DATA FACILITY DEVICE SUPPOR~ (DFDS) PROGRAM PRODUCT
The information to support CVAF (Common VTOC Access Facility),
and the IBM 3375 and 3380 Disk Storage is included. For more
information see, Data Facility Device Support: User's Guide and
Reference, SC26-3952, Introduction to 3375 Direct Access Storage,
GA26-1666, and Introduction to 3380 Direct Access storage,
GA26-1662.

OS/VS2 MVS 3800 ENHANCEMENTS
IEBIMAGE can now be 'used to build library character set modules to
be stored in SYSl.IMAGELIB.

NEW PROGRAMMING SUPPORT
The information to support the IBM 3203 model 5 is now included.
For additional information about the IBM 3203 Printer, see IBM
3203 Printer Component Description and Operator's Guide,
--GA33-1515.
The figure "Output Obtained from Issuing DEVTYPE Macro" now
includes the 3203 Printer.
The sect ions" Add i ng to the Image Library and Retr i ev i ng FCB
Images," "Addi ng a UCS Image to the Image library," and "Add; ng an
FeB Image to the Image library" have been updated to include the
3203 Printer.
The fi gure "Sample Code to Add a 3203 UCS Image to SYSI. IMAGElIB"
ha 5 been added.

Summary 'of Amendments

vii

SERVICE CHANGES
The following sections have been updated:
•

Catalog Order of Search

•

Retrieving Information from a VS2 Catalog

•

Retrieving Information by Data Set Name (LOCATE and CAMLST
NAME)

•

Retrieving Information by Generation Data Set Name (LOCATE
and CAMLST NAME)

•

Deleting a Data Set (SCRATCH and CAMLST SCRATCH)

•

Renalfli ng a Data Set (RENAME and CAMLST RENAME)

•

Interruption Handling and Error Recovery Procedures

•

Start I/O (510) Appendage

•

Program Controlled Interruption (PCI) Appendage

•

ATLAS-Assigning an Alternate Track and Copying Data from the
Defective Track

•

Ex~cuting

•

Page Fix List Processing

•

Mapping System Data Areas

•

IEFUCBOB-Mapping the UCB

•

IEFJFCBN-Mapping the JFCB

•

CVT-Mapping the CVT

•

DEVTYPE Macro Specification

•

Read; ng and Modi fyi ng a Job Fi Ie Control Block

•

Adding a UCS Image to the Image Library

•

The figures:

Fixed Channel Programs in Real Storage (EXCPVR)

Sample Code to Add a 1403 UCS Image to SYS1.IMAGElIB
Sample Code to Add a 3211 UCS Image to SYS1.IMAGElIB
•

Adding an FCB Image to the Image library

•

The figures:
Sample of the Standard FCB Image STD1
Sample of the Standard FCB Image STD2
Sample Code to Assemble and Add an FCB Load Module to
SYSl.IMAGELIB

Two new figures have been added:

viii

•

Generation Index Pointer Entry

•

Al i as Entry

OS/VS2 System Programming Library: Data Management

"-...... /

OS/VS MVS DATA MANAGEMENT SUPPORT FOR MASS STORAGE SYSTEM (HSS) EXTENSIONS PROGRAM
PRODUCT
The MSS Extensions Program Product is supported by the addition of
the section "Scratch Dummy Nodule."

c.,
Summary of Amendments

CONTENTS

Using catalog Management Macro Instructions

...

Catalog Order of Search
........•.
Return Code Considerations
..........•..
Retrieving Information from an MVS Catalog
...•..
Retrieving Information by Data Set Name (LOCATE and
CAnL S T NA~lE)
...................•.
Retrieving Information by Generation Data Set Name
(LOCATE and CAMLST NAME)
.............. .
Retrieving Information by Alias (LOCATE and CAMLST NAME)
Reading a Block by Relative Block Address (LOCATE and
CAMLST BLOCK)
.................. .
Building and Deleting Indexes
...•..........•.•
Bui lding an Index (INDEX and CAMLST BlDX)
....
Building a Generation Index (INDEX and CAMLST BLDG)
Deleti ng an Index (INDEX and CAMLST DL TX)
..... .
Assigning an Alias for an Index (INDEX and CAMlST BLDA)
Deleting an Alias for an Index (INDEX and CAMlST DLTA)
Connecting and Disconnecting Control Volumes
..... .
Connecting Control Volumes (INDEX and CANLST LNKX)
Disconnecting Control Volumes (INDEX and CAMlST DRPX)
Working with NonVSAM Data Set Catalog Entries
.....
Cataloging a NonVSAM Data Set (CATALOG and CAMLST CAT)
Programming Considerations for Multiple-Step Jobs
...
Uncataloging a NonVSAM Data Set (CATALOG and CAMLST UNCAT)
Recataloging a NonVSAM Data Set (CATALOG and CAMLST RECAT)
CVOL Catalog Entry Formats
. . . ..
. ...
Volume Index Control Entry
..... .
Index Control Entry
.......... .
Index Link Entry and Index Pointer Entry
Data Set Pointer Entry
....... .
Volume Control Block Pointer Entry
... .
Volume Control Block
........... .
Control Volume (CVOL) Pointer Entry
Control Volume Pointer Entry (OLD)
Generation Index Pointer Entry
AI i a s Name
•••••••••••••••••

Maintaining the Volume Table of contents

•••••

-- Introduct ion
.....................•.•.
Reading a DSCB by Actual Device Address (OBTAIN and
CAMlST SEEK)
................. .
Deleting a Data Set (SCRATCH and CAMlST SCRATCH)
Renaming a Data Set (RENAME and CAMlST RENAME)

Executing Your Own Channel Programs (EXCP)

•••••

Executing Channel Programs in System and Problem Programs
System Use of EXCP
.................. .
Use of EXCP in Problem Programs
....... .
EXCP Operations in a Nonpageable Address Space
EXCP Requ i rements
...•.
Channel Program
..... .
Control Blocks
...... .
Input/Output Block (lOB)
Event Control Block (ECB)
Data Control Block (DCB)
... .
Data Extent Block (DEB)
.........
. .. .
Channel Program Executi on
...•.
. .. .
Initiation of the Channel Program
....... .
Modification of a Channel Program During Execution
Completion of Execution
........... .
Interruption Handling and Error Recovery Procedures
Appendages
...................•...
Start-I/O (SIO) Appendage
.....•....
Pr6gram Controlled lnterruption (PCI) Appendage
End-of-Extent (EOE) Appendage
.....
Channel-End (CHE) Appendage
Abnormal-End (ABE) Appendage
Contents

1
1

2
2

3
5
7
8
9
9

11
13
14'
15

16
16
17
18

19
19
21
22
24
24

25
26
27
28

29
30
30
31 .
32
33
33
35

44
44

45
45
46
46
46

47
47
47
47
47
47
47
48
49
49

50
51
51
53
53

54
xi

Making Your Appendages Part of the System
The Authorized Appendage list (IEAAPPOO)
Block Multiplexor Channel Programming Notes
..•..
Macro Specifications for Use With EXCP
....•.••.
DCB--Define Data Control Block for EXCP
•...•.
Foundation Block Parameters
......
. •••
EXCP Interface Parameters
...........•.••.
Foundation Block Extension and Common Interface
Parameters
.......... .
Device-Dependent Parameters
....... .
DSORG Parameter of the DCBD Macro
... .
OPEN-Initialize Data Control Block
...•.
EXCP-Execu te Channel Program
. . . . . . . . . • . .
ATlAS--Assigning an Alternate Track and Copying Data
from the Defect i ve Track
. . . . .
. . . • . .
Using ATLAS
.........
. ..•
Operation of the ATLAS Program
.•..
EOV--End of Volume
....
CLOSE-Restore Data Control Block
Control Block Fields
...... .
Input/Output Block Fields
...........•
Executing Fixed Channel Programs in Real Storage (EXCPVR)
Building the List of Data Areas to be Fixed
....•.
Page Fix (PGFX) and Start-I/O (510) Appendage
Page Fix list Processing
............... .
510 Appendage
.............. .

55
56

Using XDAP to Read and write to Direct-Access Devices

82
82
82
83
83
83
84

Introduct ion
.......
. . ..
...•.
XDAP Requirements
........•..
. ...
Macro Specifications for Use with XDAP
•...
DCB--Define Data Control Block
... .
OPEN-In it i al i ze Data Control Block
.... .
XDAP-Execute Direct-Access Program
.......•
Di rect-Access Channel Program
.....•......
Conversion of Relative Track Address to Actual Device
Address
.........................•.
Conversion of Actual Device Address to Relative Track
Address
.............•.........
Obtaining Sector Number of a Block on a Device with the RPS
Feature
............. .

Password protecting Your Data sets

58
58
60
60
60

62
65
65
67

68
69

70
72
73
73
73

78
79
79
79

89
89
91

Introduction
..........•..........
PASSWORD Data Set Ch~racteristics
Creating Protected Data Sets
....
Tape Volumes Containing More Than One
Password-Prote.cted Data S e t .
. ....•..
Protection Feature Operating Characteristics
Termination of Processing
............ .
Volume SloJi tchi ng
.....••......
Data Set Concatenation
... .
SCRATCH and RENANE Functi ons
.... .
Counter Ma i ntenance
...........•.
Using the PROTECT Macro Instruction to Maintain the
PASSWORD Data Set
................... .
PASS\·IORD Data Set Characteri sti cs and Record Format When
You Use the PROTECT Macro Instructi on
.....
Number of Records for Each Protected Data Set
Protection Mode Indicator
....•..•.•.
PROTECT Macro Specification
Return Codes From the PROTECT Macro

102

System Macro Instructions

103

Introduction
..... .
Mapping System Data Areas
I EFUCBOB--Mappi ng the UCB
IEFJFCBN-Mapping the JFCB
CVT-Mappi ng the CVT
....
Obtaining I/O Device Characteristics
DEVTYPE Nacro Specification
Device Characteristics Information

xii

OS/VS2 System Programming Library: Data Management

92
93
93
93
93
94
94
94
94

95
95
95
95
96

103
103
103
104
104
105
105

106

OPEN--Initialize Data Control Block for Processing the
J FC B
.......................•.
PURGE-Hal t or Fi ni sh I/O-Request Processi ng
Modifying the lOB Chain
.....
. . . .
RESTORE-Reprocess I/O Requests
TRKCALC--Perform Track Calculations
TRKCALC--Standard Form
Input Register Usage
Output from TRKCALC
· . .
TRKCALC--List Form
.
· . •
TRKCALC--Execute Form
TRKCALC-DSECT Only
· . .
TRKCALC Macro Examples
..... .
· . .

Adding to the Image Library and Retrieving FCB Images

Addi ng a UCS Image to the Image Library
. . . .
Addi ng an FCB Image to the Image Library
..••...
Retrieving an FCB Image
. . . . . . . . . . . . . .

JES2

suppor~

for the IBM 1403, 3203-5, and 3211 Printers

. ·113
122
. .

. .
. .
. .
. .

123

124
124
125
127
127
128
128
129
129

130

130
135
136

139

UCS Alias Names
................
The 3211 Indexing Feature
. . . . . . . • . .
3203-5 Pri nter
...................

139
139
140

Format-1 DSCB-Not-Found User Exit in OPEN and EOV·

141

CATALOG, SCRATCH, and RENAME Dummy Modules

143

SCRATCH Dummy Module

144

controlling Space on DASD Volumes

145

Introduction
.......... .
DADSM Rout i nes
..................... .
Allocating and Releasing Space on Direct-Access Volumes
VTDC-Related Service Routines
The Volume Table of Contents
Size of the Volume Table of Contents
Volume Table of Contents Integrity
DADSM Interrupt Recording Facility (DIRF)

145
145
146
147
147
152
152
153

spec;fying Buffer Numbers for SAM-E DASD Data sets

154

Index

155

Performance Consi derat ions

....

Contents

154

xiii

FIGURES

1.
2.
3.
4.
5.
6.
7•
8.
9.
10.

11.
12.
13.
14.
15.
16.

17.
18.
19.
20.

21.
22.
23.
24.
25.
26.

27.
28.

29.
30.
31.

32.
33.
34.

The Volume Index Control Entry
.
•.
The Index Control Entry
.. . . .
The Index link and Index Pointer Entries
The Data Set Po inter Entry
. . . . •
The Volume Control Block Pointer Entry
The Volume Control Block
..
.
....
.
The Control Volume (CVOl) Pointer Entry
Generat i on Index Po inter Entry
•. .•
Ali a s Name
.••
. . . •
Entry Poirits, Returns~ and Available Work Registers
for Appendages
.... . .
•.. .
Data Control Block Format for EXCP (After OPEN)
Input/Output Block Format
..
....
Event Control Block After Posting of Completion Code
( EXCP )
..
....•
.. .
...
Event Control Block Aft~r Posting of Completion Code
(XDAP)
..
.
..
The XDAP Channel Programs
..
Parameter list for ADD Funct ion
•
Parameter list for REPLACE Function
Parameter List for DELETE Function
.••.
Parameter list for LIST Function
.......•
Return' Codes from the PROtECT Macro Instruction
Output Obta i ned from I ssu i ng DEVTYPE Macro
....
Sample Code Usi ng RDJFCB Macro
...
..
.
Macro Definition, JCL, and Utility Statements for
Adding PURGE Macro to Your Macro Library
.
Macro Definition, JCl, arid Utility statements for
Adding RESTORE Macro to Your Macro Library
The PIRL and lOB Chain
. ..
• . . . . ..
Sample Code'to Add a 14~3 UCS Image to SYS1.IMAGELIB
Sam~le Code'to Add a 3211 UCS Image to SYS1.IMAGElIB
Sample Code to Add a 3203 UCS Image to SYSl.IMAGELIB
.
. ...•
Sampl e of the Standard FCB Image ST01
S~mple of the Standard FCB Image STD2
. . . . .
Sample Code to Assemble and Add an FCB Load Module to
SYS1'.IMAGELIB
.
.
..
...
. ..
Locating the Volume Table of Contents (VTOC)
DataSet Control Block (DSCB) Format Types and Use
Contents of VTOC-DSCBs Deseri bi ngData Sets

24
25
26
27

29
30

59
74

77
87
87
97
99
100

101
102
108
115
121

121
124
132
133
134
136

137
138
148
149
151

c
xiv

OS/VS2 System Programming Library: Data Managemerit

USING CATALOG MANAGEMENT MACRO INSTRUCTIONS

Using catalog management· macro instructions, you can do the
following things:
•

Retrieve information from an MVS catalog. Three kinds of
catalogs qualify as MVS catalogs: the MVS master catalog,
VSAM user catalogs, and OS CVOLs (control: volumes).

•

Catalog non-VSAM data sets.

•

Uncatalog non-VSAM data sets.

•

Recatalog non-VSAM data·sets.

•

Read a block from a CVOL.

•

Bu i I dan i n d ex ina CVOL.

•

Build a generation index in a CVOL.

•

Delete an index.

•

Assign an alias to a high-level index in a'CVOL.

•

Delete an index alias from a CVOL.

•

Connect two CVOLs.

.•

Disconnect two CVOls.

Before using the information in this chapter, you should be
familiar with the information contained in the following
publications:
•

.•

OS/VS-DOS/VS-VM/370 Assembler Language, 'whi ch contai ns
information you will need t6 code programs in the assembler
language.
OS/VS2 Access Method Serv ices, whi ch. tells how to use
programs that offer some of the same services as catalog
management macros plus additional services that catalog
management macros cannot provide.

•

OS/VS2 JCl, which tells how to catalog and uncatalog data sets
using job control language statements.

•

OS/VS2 MVS CVOL Processor, which tells how to use CVOLs in the
MVS environment.

Specifications for coding the macro instructions are presented
with each function to be performed. Accompanying the descriptions
are coding examples and programming notes; exception return codes
follow the coding examples. In the functional descriptions,
offsets into data areas are numbered from zero (the first byte is
byte zero).

CATALOG ORDER OF SEARCH

A CVOl is identified in the master catalog as a non-VSAM data set
with a name of the form SYSCTLG.~ where Y..'DL. is any unique
string, unless the CAMLST CVOL operand is to be specified in CVOl
requests. If CVOL is specified, the CVOL must be defined in the
MVS master catalog as a non-VSAM data set with the name
SYSCTLG. VYj~~ where YYYvvY is the volume ser i al number of the
CVOL. The hi gh level data set name is defi ned as an al i as of the
CVOL entry.

Using Catalog Management Macro -Instructions

The volume serial of a CVOl may be specified as the third operand
of the CAMlST macro (described later fn this section). If this
operand is specified, searching begins directly with the
specified CVOl. Searching may continue on the other CVOLs if these
CVOls have been connected with the CANlST LNKX "macro with the
high-level qualifier of the data set name. Searching will never go
to any VSAM format catalogs when the CVOl volume operand is
specified.
If the CVOl volume operand is not specified, searching begins in
the JOBCAT or STEPCAT catalog if specified. If not found or no
JOBCAT/STEPCAT Catalog was specified, searching continues in the
master catalog.
In the master catalog, a search is made to determine if the first
qualifier of the data set name is the name of a (VSAM) user
catalog or the alias of a private catalog (either a VSAM user
catalog or a CVOl).
If the first qualifier is the name or alias of a private catalog,
the search continues in the private catalog. Otherwise, the
process terminates in the master catalog.
For information about how CVOls are defined, identified, and
searched, see OS/VS2 MVS CVOl Processor.
RETURN CODE CONSIDERATIONS

The interpretation of catalog management return codes depends on
whether the request is initiated using a CANLST or a VSAM
parameter list, and whether the request is satisfied in a VSAM
catalog or a CVOl.
If a CANlST is used and the request is satisfied in a CVOL,
register 15 contains the CVOL return code and registers 0 and 1
may further describe the return code meaning. If a CAMlST is used
and the request is satisfied in a VSAM catalog, register 15
contains the CVOL return code, register 0 the VSAN return code,
and register 1 is zero.
If a VSAM parameter list is used and the request is satisfied in a
CVOL, register 15 contains the VSAM return code~ register 0 is not
meaningful, and register 1 is nonzero. If a VSAM parameter list is
used and the request is satisfied in a VSAM catalog, registers 15
and 0 contain a VSAM return code and a VSAM reason code
respectively. These codes are explained in OS/VS Message Library:
VS2 System Messages under message IDC009I.
Note that regardless of which parameter list is used, if the
request is sat i sf; ed ina VSAM catalog, regi ster 1 i.s zero, and if
the request is satisfied in a CVOL, register 1 contains X'08' in
the high-order byte and may contain return information in the
low-order byte.
RETRIEVING IUFORMATION FROM AN MVS CATALOG

To read an entry from an MVS catalog, use the lOCATE and CAMlST
macro instructions. You may specify the entry you want to read
into your work area by using either (1) the fully or partially
qualified name of a data set, or (2) the relative block address
(TTR) of the block within a CVOL containing the entry. If you
specify a fully qualified data set name, a list of volumes on
which the data set resides will be read into your work area. This
volume list always begins with a 2-byte entry that is the number
of volumes in the list. If the data set resides on more than 20
volumes and is cataloged iOn a CVOl, the address of a volume
control block will follow the volume list entries.
If you specify a partially qualified data set name, the first
block in the CVOL catalog pointed to by the lowest-level index
specified will be read into your work area. This is true if you
2

OS/VS2 System Programming Library: Data Management

specify two or more qualifiers, or if you specify the CVOl
parameter in the CAMlST macro. Register 15 will contain the rGturn
code 12. If you specify a single qualifier and do not include the
CVOl parameter, the CVOl identifier 'SYSCTlG.Vyyyyyy' is read
into your work area. You may then insert 'yyyyy~' as the CVOl
parameter in the CAMlST and reissue the lOCATE.
If you specify a relative block address (TTR), the block al that
relative address in the CVOL catalog will be read into your work
area.
For MVS, you must add a step when specifying either an unqualified
name or the highest level of a partially qualified name to
retrieve information from a CVOl. Because the search of the VSAM
master catalog is different from the search for the as/VSl and
OS/VS2 Release 1 system catalog, you do not receive the volume
information or the index block from the CVOl as you might expect.
You receive, instead, the volume information for the CVOl that is
found in the VSAM master catalog. In addition, the"'single
qualifier name that you specified is replaced by the
SYSCTlG.V~~~~ name. You may then use that information to
specify the CVOl volume serial number in your CAMlST so that the
search starts in the CVOl and gives you the information that you
expected.
See Figure 1 on page 24 through Figure 8 on page 31 for
descriptions of the contents of volume control block and the other
catalog data areas.

RETRIEVING INFORMATION BY DATA SET NAME (LOCATE AND CAHLST NANE)
When you specify a data set name, a volume list is built in your
work area. A volume list consists of an entry for each volume on
which part of the data set resides; it is preceded by a 2-byte
field that contains a count of the number of volumes in the list.
The count field is followed by a variable number of 12-byte
entries. Each 12-byte entry consists of a 4-byte device code, a
6-byte volume serial number, and a 2-byte data set sequence
number. As many as 20 of these 12-byte entries can be built in
your work area. (Device codes are presented in the UCBTYP data
area description of OS/VS2 System Programming library: Debugging
Handbook.)
If the named data set is stored on only one volume, bytes 252
through 254 of your area may contain the relative track address of
the DSCB for that data set; otherwise, these bytes are zero. Byte
255 contains zeros.
If the data set is cataloged in a CVOl and resides on more than
five volumes, the volume list in your work area is really a volume
control block (VeB) that has been read into your worK area. In a
VCB, the count field contains the number of volume entries in this
VCB and any following VCBs. Thus a count of 41 indicates two
following VCBs with counts of 21 and one, respectively. The
relative track address (TTR) of the next VCB is in bytes 252
through 254 of your work area. The last VCB for a data set has
binary zeros in bytes 252 through 254.
The format of the parameter list of this macro is described in
OS/VS2 System Programming library: Debugging Handbook in the
section "SVC Summary."
The format is:
[symbol]
listname

LOCATE
CAtlLST

list-addrx

NAME

,dsname-relexe
,[cvol-relexpl
,area-relex~

Using Catalog Management Macro Instructions

list-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.

NAME

this operand must be coded as shown to retrieve information
from an MVS catalog by name.

dsname-releXR
specifies the virtual storage location of a fully qualified
data se.t name. The area that contains the name must be 44
bytes long. The name may be defined by a C-type Define
Constant (DC) instruction.
cvol-releKe
specifies the virtual storage location of the 6-byte volume
serial number of the CVOL catalog to which this catalog
request is directed. For a discussion of the effect of
specifying or omitting this operand, see "Catalog Ordgr of
Search" earlier in this section.
area-relexp
specifies the virtual storage location of your 265-byte work
area, which you must define. The work area must begin on a
doubleword boundary:

Example: In the following example, the catalog entry containing a
list of the volumes on which data set A.B resides is read into
virtual storage.

LOCATE

IHDAB

Check Retut'ns

*INDAB
AS

lOCAREA

CAMlST
DC
OS
DS

NAME,AB"lOCAREA
CL44'A.B'
00
265C

READ CATALOG ENTRY
FOR DATA SET A.B.
INTO VIRTUAL STORAGE
AREA NAMED lOCAREA.
lOCAREA MAY ALSO
CONTAIN A 3-BYTE
TTR AND THE 6-BYTE
CVOL SERIAL

,,,--

The LOCATE macro instruction points to the CAMLST macro
instruction. NAME, the first operand of CAMLST, specifies that
the system is to search for a catalog entry using the name of a
data set. AB, the second operand, specifies the virtual storage
location of a 44-byte area into which you have plac~d the fully
qualified name of a data set. LOCAREA, the fourth operand,
specifies a 265-byte area you have reserved in virtual storage.
After execution of these macro instructions, the 265-byte area
contains a volume list or a volume control block for the data set
A.B.
Control will be returned to your program at the next executable
instruction after the LOCATE macro instruction. If the block has
been successfully read from the catalog, register 15 will contain
zeros. Otherwise, register 15 will contain one of the following
return codes.

c
4

OS/VS2 System Programming Library: Data Management

Code

11ean i ng

Either the required catalog does not exist or it cannot be
opened or there is a closed chain of CVOL pointers.

One of the followi ng happened:

•

The entry was not found. Regi ster 0 conta ins the number
of valid index levels if in a CVOL. Register 0 contains
the VSAM catalog return code if in a VSAM catalog.

•

The user is not authori zed to perform thi s operation.
Register 0 contains 56 (decimal).

•

A GOG alias L-laS found (VSAM catalog only). Regi ster 0
contains the number of valid index levels. The alias
name was replaced by the true name.

One of the following happened:
•

An index or generation base entry was found when the
list of qualified names was exhausted. Register 0
contains the number of valid index levels. The work
area contains the first block of the specified index.

•

An alias entry was found. The alias name was replaced by
the true narr.e.

•

An i nval i d low level GDG name was found.

A data set exists at other than the lowest index level
specified. Register 0 contains the number of the index
level where the data set was encountered.

A syntax error exists in the name.

One of the following happened:
•

Permanent I/O error occurred. Register 0 contains the
VSAM return code or 0 if in a CVOL.

•

Unrecoverable error occurred. Register 0 contains the
VSAM return code or 0 if in a CVOL.

•

Nonzero ESTAE return code.

•

Error in parameter list.

Relative track address supplied to LOCATE routine is
outside of the SYSCTLG data set extents.

Reserved.

RETRIEVING INFORMATION BY GENERATION DATA SET NAME (LOCATE AND CANLST NAME)
You specify the name of a generation data s~t by using the fully
qualified generation index name and the relative gener~tion
number of thn data set. The value of a relative generation number
reflects the position of a data set in a generation data group.
The following values can be used:

•

Zero-speci fi es the latest data set (hi ghest generati on
number) cataloged in a generation data group.

•

Negative number--specifies a data set cataloged before the
latest data set.

•

positive number--specifies a data set not yet cataloged in
the generation data 'group.

Using Catalog Management Macro Instructions

When you use zero or a negative number as the relative generation
number, a volume list (or a volume control block) is placed in
your work area, and the relative generation number is replaced by
the absolute generation name.
When you use a positive number as the relative generation number,
an absolute generation name is created and replaces the relative
generation number. Zeros are read into the first 256 bytes of your
work area, because there are no entries in the catalog.
The format of the parameter list of this macro is described in
OS/VS2 System Programming library: Debugging Handbook in the
section "SVC Summary."
The format is:
[~ymbol]

listname

LOCATE

list-addrx

CAtfLST

tMr1E

,dsname-relexp
,[cvol-relexp]
,area-relexp

l;st-addrx
points to the parameter list (labeled listname) set up by the
CANLST macro instruction.
NAME

this operand must be coded as shown in order to read a block
from the catalog by generation data set name.

dsname-relexe
specifies the virtual storage location of the name of the
generation index and the relative generation number. The
area that contains these must be 44 bytes long. The name may
be defined by a C-type Define Constant (DC) instruction.
cvol-relex.e
specifies the virtual storage location of the 6-byte volume
serial number of the CVOl catalog to which this catalog
request is directed. For a discussion of the effect of
speci fy; ng or omi tti ng thi s operand, see "Catalog Order of
Search" earlier in this section.
area-reI e,~.E
specifies the virtual storage location of your 265-byte work
area, which you'must define. The work area must begin on a
doubleword boundary. The first 256 bytes of the work area
will contain a volume list that is built from the catalog. If
the data set resides on one volume, bytes 252 through 254 may
contain the relative track address of the DSCB. This address
is relative to the beginning of the volume.
Example: In the following example, the list of volumes that
contain generation data set A.PAY(-3) is read into virtual
storage.

LOCATE

*
INDGX
APAY
lOCAREA

INDGX

Check Returns
CAMlST
DC
DS
DS

HAME,APAY"LOCAREA
CL44'A.PAY(-3)'
OD
265C

OS/VS2 System Programming library: Data Management

READ CATALOG ENTRY
FOR
DATA SET A.PAY (-3)"
INTO YOUR STORAGE
AREA NAMED lOCAREA.

The LOCATE macro instruction points to the CAMLST macro
.
instruction. NAME, the first operand of CAMLST, specifies that
the system is to search the catalog for a catalog entry by using
the name of a data set. APAY, the second operand, specifies the
virtual storage location of a 44-byte area into which you have
placed the name of the generation index and the relative
generation number of a data set in the generation data group.
LOCAREA, the fourth operand, specifies a 265-byte area you have
reserved to receive the catalog information.
After execution of these macro instructions, the system will have
replaced the relative generation number that you specified in
your 44-byte area with the data set's absolute generation name.
Control will be returned to your program at the next executable
instruction after the LOCATE macro instruction. If the entry has
been located and read successfully, register 15 will contain
zeros. Otherwise, register 15 will contain a return code. For a
description of the contents of the work area or the meaning of the
exception return codes, see "Retrieving Information by Data Set
Name (LOCATE and CAMLST NAME)."

RETRIEVING INFORMATION BY ALIAS (LOCATE AND CANLST NAME)
For each of the preceding functions, you can specify an alias as
the name of ~ data set. Each function is performed exactly as
previously described, with one exception: the alias name
specified is replaced by the true name. Hote: Aliases are not
allowed for generation data sets (GDGs) cataloged in CVOLs.
The format of the parameter list of this macro is described in
OS/VS2 Sy-stem Programming Librarv: Debugging Handbook in the
section "SVC Summary."
The format is:
[s~mbol]

listname

LOCATE
CAt'LST

list-addrx
NArIE

,dsname-relexE
,[cvol-relexp)
,area-reiexp

list-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.
NAt1E

this operand must be coded as shown to retrieve information
from an MVS catalog.
dsname-relexB,
specifies the virtual storage location of a fully qualified
data set name, the first or only name of which is the alias.
The area that contains the name must be 44 bytes long. The
name may be defined by a C-type Define Constant (DC)
instruction.
cvol-relexp
specifies the virtual storage location of the 6-byte volume
serial number of the CVOL catalog to which this ca~alog
request is directed. For a discussion of the effect of
speci fyi ng or omi tti ng thi s operand, see "Catalog Order of
Search" earlier in this section.

area-relexp
specifies the virtual storage location of your 265-byte work
area, which you must define. The work area must begin on a
doubleword boundary. The first 256 bytes of the work area
will contain a volume list that is read from a VS2 catalog.
If the data set resides on one volume, bytes 252 through 254

Using Catalog Management Macro Instructions

may contain the relative track address of the DSCB. This
address is relative to the beginning of the volume.
Example: In the following example, the catalog entry containing a

list of the volumes on which data set A.B.C resides is read into
virtual storage. (Data set A.B.C, however, is addressed by ~n
alias name, X.B.C.)

LOCATE

INDAB

Check Returns
INDAB
ABC
LOCAREA

CAMLST
DC
OS
DS

NAME,ABC"LOCAREA
CL44'X.B.C.'
OC
265C

READ CATALOG ENTRY
FOR
DATA SET X.B.C INTO
VIRTUAL STORAGE AREA
NAt'tED LOCAREA.

The LOCATE macro instruction points to the CAMLST macro
instruction. NAME, the first operand of CAMLST, specifies that
the system is to search the catalog for an entry using the name of
a data set. ABC, the second operand, specifies the virtual storage
location of a 44-byte are~ into which you have placed the fully
qualified name of a data set. (In this case, data set A.B.C is
addressed by its alias X.B.C.) LOCAREA, the fourth operand,
specifies a 265-byte area you have reserved in virtual storage.
For inf~rmation on return codes and the contents of your work area
after execution, see the section "Retrieving Information by Data
Set Name (LOCATE and CAMLST NAME)."

READING A BLOCK BY RELATIVE BLOCK ADDRESS (LOCATE AND CANLST BLOCK)
You ·can read any block in a CVOL catalog by specifying, in the
form TTR, the identification of the block and its location
relative to the beginning of the catalog. TT is the number of
tracks from the beginning of the catalog; R is the record number
of the desired block on the track.
The format of the parameter list of this macro is described in
OS/VS2 System Programming Library: Debugging Handbook in the
sect ion n S VC Summa ry. "
The format is:
[symbol]
listname

LOCATE
CAULST

list-addrx

BLOCK

,ttr-relexp
,cvol-relexp
,area-relexp

list-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.

BLOCK

you must code this operand as shown.

ttr-relexp
specifies the virtual storage location of a 3-byte relative
block address (TTR). This address indicates the position
relative to the beginning of the catalog data set, of the
track containing the block (TT), and the block
identification (R) on that track.

OS/VS2 System Programming Library: Data Management

.r-'
~./

cvol-relex..E.
specifies the virtual storage location of a 6-byte volume
serial number for the volume to be processed.
area-releKE
specifies the virtual storage location of your 265-byte work
area, which you must define. The work area must begin an a
doubleword boundary. The first 256 bytes of the work area
will contain the block that is read from the catalog, and the
last 6 bytes will contain the serial number of the volume on
which the block was found. If the data set resides on one
volume, bytes 252 through 254 will contain the relative
track address of the DSCB.

EXample: In the following example, the block at the location
indicated by TTR is read into virtual storage.

LOCATE

BLK

Check Exceptional Returns
BLK

**
TTR
VOLSER
LOCAREA

CAMLST
DC
DC
OC
OS
OS

BLOCK,TTR,VOLSER,LOCAREA
READ A BLOCK INTO
VIRTUAL STORAGE. AREA
HArlED LOCAREA
H'5'
RELATIVE TRACK 5
X'03'
Cnll!!!!'
BLOCK 3 ON TRACK
VOLUME SERIAL OF CVOl
00
265C
LOCAREA ALSO cotn AINS
6-BYTE SERIAL NO.

The LOCATE macro instruction points to the CAMLST macro
instruction. BLOCK, the first operand of CAf1LST, specifies that
the system is to search the catalog for the block indicated by
TTR, the second operand. VOLSER, the thi'rdoperand, spec; f; es the
virtual storage location of a 6-byte volume serial number for the
volume to be processed. LOCAREA, the fourfh"operand, specifies a
265-byte area you have reserved in virtual storage.
After execution of these macro instructions, the 265-byte area
contains: the 256-byte block and the 6-b~te serial number of the
volume on which the block was found (in bytes 259 through 264).
Control will be returned to your program at the next executable
instruction following the LOCATE macro instruction. If the index
block at the address you specified has been successfully located
and read into your work araa, register 15 will contain zeros.
Otherwise, register 15 will contain one of the exception return
codes described in "Retrieving Information by Data Set Name
(LOCATE and CAMLST NANE)."

BUILDING AND DELETING INDEXES
You handle CVOL i ndexes-bui Id them, delete them, and so
forth-by usi ng combi nati ons of the INDEX and CA~lLST macro
instructions.

BUILDING AN

INDE~

(INDEX AND CAMLST BLDXJ
To build a new index structure and add it to the catalog, you may
create each level of the index separately. (You can also create
index levels while you are cataloging a d5ta set onto those index
levels. To create each level of the index, use the INDEX and
CAMLST macro instructions.)

Using Catalog Management Macro Instructions

These two macro instructions can also be used to add index levels
to existing index structures.
The format of the parameter list of thi s macro is descri bed; n
OS/VS2 System Programming Library: Debugging'Handbook in the
section "SVC Summary."

"',

The format is:
[,2ymboll
listnam9

INDEX
CAULST

list-addrx

BLDX

,namerelex£
[,cvol-relexel

list-addrx
points to the parameter list (labeled listname) set up by the
CAMlST macro instruction.

BLDX

this operand must be coded as shown.

namerelexe
specifies the virtual storage location of the fully
qualified name of a data set or index level. The name cannot
exceed 44 characters. If the name is less than 44 characters,
it must be followed by blanks. The name may be defined by a
C-type define constant (DC) instruction.
cvol-re1exe
specifies the virtual storage location of a 6-byte volume
serial number of the CVOl catalog to which this cata16g
request is directed. For a discussion of the effect of
speci fyi ng or ami tti ng thi s operand, see "Catalog Order of
Search" earlier in this section.

Example: In the following example, index structure A.B.C is built
on the control volume whose serial number is 000045.

INDEX

INDEXA

BUILD INDEX A

Check Exceptional Returns
INDEX

INDEXB

BUILD INDEX STRUCTURE
A.B

Check Exceptional Returns
INDEX

INDEXC

BUILD INDEX STRUCTURE
A.B.C

Check Exceptional Returns
INDEXA
INDEXB
INDEXC
VOLNUM
ALEV EL
BLEVEl
CLEVEL

CAMLST
CAMLST
CA~'l S T
DC
DC
DC
DC

BLDX,AlEVEL,VOLNUM
BlDX,BLEVEL,VOLNUM
BlDX,ClEVEl,VOLNUM
Cl6'000045'
VOLUME SERIAL NUMBER
Cl2'A'
INDEX STRUCTURE NAMES
CL4'A.B'
FOLLOWED BY A BLANK
CL6'A.B.C'
WHICH DELIMITS FIELDS

Each INDEX macro instruction points to an associated CAMLST macro
instruction. BlDX, the first operand of CAMLST, specifies that an
index level be built. The second operand specifies the virtual
storage location of the area into which you have placed the fully
qual i fi ed name of an index level. The thi rd operand speci fi es the
virtual storage location of the area into which you have placed
10

OS/VS2 System Programming Library: Data Management

C"
,.

the 6-byte serial number of the volume on which the index level is
to be built.
Control will be returned to your program at the next executable
instruction following the INDEX macro instruction. If the index
has been built successfully, register 15 will contain zeros.
Otherwise, register 15 will contain one of the following
exception return codes:

Code

Interpretation

The CVOL does not exi st or cannot be opened.

One of the following happened:
•

The existing catalog structure is inconsistent with the
operation requested. If the error was detected while
processing in a CVOL, register 0 has the number of valid
index levels and register 1 has the return code that
would have resulted if a LOCATE macro had been issued on
the same entry name. If the error was detected during
master catalog processing, register 0 contains the VSAM
catalog return code and register 1 contains zero.

•

The user is not authorized to perform the operation.
Register 0 contains 56 (decimal); register 1 contains
O.

BUILDlt~G

An attempt was made to delete an index or generation index
that has an alias or has indexes or data sets cataloged
under it. The index is unchanged.

The qualified name specified when building an index or
generation index implies an index structure that does not
exist; the high level index, specified when connecting
control volumes, does not exist.

Space is not available on the specified control volume.

Not used with the INDEX macro instruction.

A permanent I/O error was found when processing the
catalog, or a nonzero return code from ESTAE was
encountered.

GEt~ERATION

INDEX (INDEX AND CAt'LST BLDG)

You build a generation index in a CVOl by using the IHDEX and
CAMLST macro instructions. All higher levels of the index must
exist. If the higher levels of the index are not in the catalog,
you must build them. Hbw to build an index has been explained
previously.
The format of the parameter list of this macro is described in
OS/VS2 System Programming library: Debugging Handbook in the
section "SVC Summary."
The format is:
[symbol]
listname

INDEX
CAULST

list-addrx
BLDG
,namerelexp
,[cvol-relexp]
,,[DELETE]
,[EMPTY]
,number-absexp

Using Catalog Management Macro Instructions

·llst-addrx
pOlnts to the parameter list (labeled listname) set up by the
CAMlST macro instruction.

BLDG

this operand must be coded as shown.

namerele.xp
specifies the virtual storage location of the fully
qualified name of a data set or index level. The name cannot
exceed 44 characters. If the name is less, it must be
followed by blanks. The name may be defined by a C-type
define constant (DC) instruction.
cvol-rele.x2
specifies the virtual storage location of a 6-byte volume
serial number of the CVOl catalog to which this catalog
request is directed. For a discussion of the effect of
specifying or omitting this operand, see "Catalog Order of
Search" earlier in this section.

DELETE

specifies that all data sets on direct-access volumes that
are removed from a ge.nerat i on data group are to be deleted,
that is, the space allocated to the data set(s) is to be made
available for reallocation. A SCRATCH macro instruction will
be issued by the catalog management routines to delete the
data set, which will be deleted from the volume if there are
~o conditions preventing deletion (for example, expiration
date not passed, password not verified, volume not mounted,
permanent I/O error encountered while trying to delete the
data set).

EMPTY

specifies that references to all data sets in a generation
data group cataloged in the generat ion index are to be
removed from the index when the number of entries specified
is ~xceeded.

number-abs~?5.E

specifies the number of data sets to be included in a
generation data group. This number must be specified, and
cannot exceed 255.
Exa~ple: In this example, generation index D is built on the
control volume, serial number 000045. The higher level indexes
A.B.C already exist. When the number of generation data sets in
the generation index D exceeds four, the oldest data set is
uncataloged. l~hen the data set has been successful I y uncataloged
and the DELETE operand has been specified, the catalog management
routines issue a SCRATCH macro (see "Maintaining the Volume Table
of Contents") to delete the data set. If there are no condi ti ons
pre~enting the data set'from being deleted (for example, the
expiration date was not passed, the password could not be
verified, or a permanent I/O error was encountered when trying to
delete the data set), the data set will be deleted.

INDEX

GEHINDX

BUILD GEHERATION INDEX

Check Exceptional Returns
GENIHDX
DlEVEL
VOLNUM

CAMLST
DC
DC

BLDG,DlEVEl,VOlNUM"DElETE,,4
ClB'A.B.C.D'
ONE BLANK, DELIMITER
Cl6'000045'

The INDEX macro instruction points to the CAMlST macro
instruction. BLDG, operand of CAMLST, specifies that a generation
index be built. DlEVEl specifies the virtual storage location of
12

OS/VS2 System Programming Library: Data Management

r"
~

an area into which you have placed the fully qualified name of a
generation index. VOLNUM specifies the virtual storage location
of the area into which you have placed the 6-byte serial number of
the volume on which the generation index is to be built. DELETE
specifies that all data sets dropped from the generation data
group are to be deleted. The final operand, 4, specifies the
number of data sets that are to be rna i nta i ned in the generat ion
data group. Control will be returned to your program at the next
executable instruction following the INDEX macro instruction. If
the generation index was built successfully, register 15 contains
zeros. Otherwise, register 15 will contain one of the exception
return codes described under "Building an Index (INDEX and CAMLST
BLDX) . "

c
DELETING AN ItIDEX

(It~DEX

AUD CANlST DL TX)

You can delete any number of index levels from an existing index
structure. Each level of the index is deleted separately.
Generation indexes are also removed this way_ (You can also delete
index levels automaticallY when you uncatalog a data set.) You
delete each level of the index by using the INDEX and CAMLST macro
instructions.
If an index level either has an alias, or has other index levels
or data sets cataloged under it, it cannot be deleted.
The format of the parameter list of this macro is described in
OS/VS2 System Programming library: Debugging Handbook in the
section "SVC Summary."
The format is:
[symbol]
listname

INDEX
CANLST

list-addrx
DLTX

,narnerelexp
[,cvol-relexp]

list-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.
DlTX

this operand must be coded as shown.

name- re 1 ex,p
specifies the virtual storage location of the fully
qualified name of a data set or index level. The name cannot
exceed 44 characters. If the name is less than 44 characters,
it must be followed by blanks. The name may be defined by a
C-type Define Constant (DC) instruction.
cvol-relex,p
specifies the virtual storage location of a 6-byte volume
serial number of the CVOl catalog to which this catalog
request is directed. For a discussion of the effect of
speci fy; n9 or omi tti ng thi s operand, see "Catalog Order of
Search" earlier in this section.

Example: In the following example,
index structure A.B.C.

ind~x

level C is deleted from

Using Catalog Management Macro Instructions

INDEX

DELETE

DELETE INDEX LEVEL
C FROM INDEX STRUCTURE
A.B.C

Check Exceptional Returns
DELETE
LEVELC

CAMLST
DC

DLTX,LEVELC
CL6'A.B.C'

ONE BLANK FOR
DELIMITER

The INDEX macro instruction points to the CAMLST macro
instruction. DLTX, the first operand of CAMLST, specifies that an
index level be deleted. lEVELC, the second operand, specifies the
virtual storage location of the area into which you have placed
the fully qualified name of the index structure whose lowest level
is to be deleted. Control will be returned to your program at the
next executable instruction following the INDEX macro
instruction. If the index level(s) was successfully deleted,
register 15 contains zeros. Otherwise, register 15 contains one
of the exception return codes described in "Building an Index
(INDEX and CANLST BLDX)."
ASSIGNIUG AN ALIAS FOR AN IHOEX (INDEX AND CANLST BLDA)

You assign an alias to an index level by using the INDEX and
CAMLST macro instructions. An alias can be assigned only to a high
level index; for example, index A of index structure A.B.C can
have an alias, but index B cannot. Assigning an alias to a high
level index effectively provides aliases for all data sets
cataloged under that index. An al i as cannot be assi gned to a
generation index.

.~
\ .....

The format of 'the parameter list of this macro is described in
OS/VS2 System Programming Library: Debugging Handbook in the
section "SVC Summary."
The format is:
[.a.ymbol]
listname

INDEX

CArtlST

list-addrx
BLDA
,index namerelexp
[,cvol-relexpl
,alias namerelexp

list-addrx
poin{s to the parameter list (labeled listname) set up by the
CAMLST macro instruction.

BlDA
i ndex

thi s operand must be coded as shown.
namer~.l.taxp

specifies the virtual storage location of the name of a
high-level index. The area that contains the name must be 8
bytes long. The name may be defined by a C-type Define
Constant (DC) instruction.

cvol-rele~.E

specifies the virtual storage location of a 6-byte volume
serial number of the·CVOL catalog to which this catalog
request is directed. For a discussion of the effect of
spec; fyi ng or omi tt i ng thi s operand, see "Catalog Order of
Search" earlier in this section.

OS/VS2 System Programming Library: Data Management

C
./

alias name-relexp
specifies the virtual storage location of the name that is to
be used as an alias for a high-level index. The area that
contains the name must be 8 bytes long. The name may be
defined by a C-type Define Constant (DC) instruction.
Example: In the following example, index level A is assigned an
alias of X.

INDEX

ALIAS

BUILD AN ALIAS FOR
A HIGH LEVEL INDEX

Check Exceptional Returns
ALIAS
DSNANE
DSALIAS

CAMLST
DC

BlDA,DSNAME"DSALIAS
CLa'A'
MUST BE a-BYTE FIELDS
CL8'X'

The INDEX macro instruction points to the CAMLST macro
instruction. BLDA, the first operand of CAMlST, specifies that an
alias be built. DSNAME, the second operand, specifies the virtual
storage location of an a-byte area into which you have placed the
name of the high-level index to be assigned an alias. DSAlIAS, the
fourth operand, specifies the virtual storage location of an
8-byte area into which you have placed the alias to be assigned.
Control will be returned to your program at the next executable
instruction following the INDEX macro instruction. If the alias
has been successfully assigned, register 15 will contain zeros.
Otherwise, register 15 will contain one of the exception return
codes described in "Building an Index (INDEX and CAMLST BLDX)."
DELETING AN ALIAS FOR AN INDEX (INDEX AND CAr1LST DL TA)
You can delete an alias previously assigned to a high level index
by using the INDEX and CAMlST macro instructions.
The format of the parameter list of this macro is described in
OS/VS2 System Programming library: Debugging Handbook in the
section "SVC Summary."
The format is:
[2.ymboll
listname

INDEX
CAr'ILST

list-addrx
DLTA
,alias namerelexp
[,cvol-rel~J

list-addrx
points to the parameter list (labeled listname) set up by the
CAMlST macro instruction.
DLTA

this operand must be coded as shown.

alias namerelex£
specifies the virtual storage location of the name that is to
be used as an al i as for a hi gh-Ievel index. The area that
contains the name must be 8 bytes long. The name may be
defined by a C-type Define Constant (DC) instruction.

cvol-relexE
specifies the virtual storage location of a 6-byte volume
serial number of the CVOL catalog to which this catalog

Using Catalog Management Macro Instructions

request is directed. For a discussion of the effect of
speci fyi ng or omi tti ng thi s operand, see "Catalog Order of
Search" earlier in this section.

Example: In the following example, alias X, previously assigned
as an alias for index level A, is deleted.
INDEX

DELALIAS

DELETE AN ALIAS FOR
A HIGH LEVEL INDEX

Check Exceptional Returns
DELALIAS
ALIAS

CAMLST
DC

DlTA,ALIAS
CL8'X'

MUST BE 8-BYTE FIELD

The INDEX macro instruction points to the CAMLST macro
instruction. DlTA, the first operand of CANLST, specifies that an
alias be deleted. ALIAS, the second operand, specifies the
virtual storage location of the 8-byte area into which you have
placed the alias to be deleted.

CONNECTING AND DISCONNECTING CONTROL VOLUMES
You connect and disconnect control volumes by using combinations
of the INDEX and CAMLST macro instructions.

CONNECTING CONTROL VOLUMES (INDEX AND CANLST LHKX)
You connect two control volumes (CVOLs) by using the INDEX AND
CAMLST macro instructions.
\ ....

You.must supply the serial number of the volume to be connected
and the high-level index name that will be used to associate the
two volumes. If the index name is an alias of a CVOL pointer entry
in the master catalog, then the serial number of the "from" volume
may be omitted. Otherwise, you must supply the serial numbers of
both volumes and the name of a high-level index associated with
the volume to be connected.
The result of connecting control volumes is that the volume serial
number of the control volume connected and the name of a
high-level index are entered into the volume index of the volume
to which it was connected. This entry is called a control volume
pointer.
The format of the parameter list of this macro is described in
OS/VS2 System Programming library: Debugging Handbook in the
sect ion "SVC Summary."
The format is:
[.2)!mboll
listname

INDEX
CAULST

list-addrx

LNKX

,index narnerelexp
,[cvol-relexpJ
, net.. cvol-relexp

list-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.

LNKX

th is operand must be coded as shown.

OS/VS2 System Programming Library: Data Management

index name relexp
specifies the virtual storage location of the name of a
high-level index. The area that contains the name must be 8
bytes long. The name may be defined by a C-type Define
Constant (DC) instruction.
cvol-rele?S...e
specifies the virtual storage location of a 6-byta volume
serial number of the CVOL catalog to which this catalog
request is directed. For a discussion of the effect of
speci fyi ng or omi tti ng thi s operand, see "Catalog Order of
Search" earlier in this section.
new cvol-relexp
specifies the virtual storage location of the 4-byta device
code and 6-byte volume serial number of the control volume
that is to be connected to another control volume.

Example: In the following example, the control volume whose

serial number is 001555 is connected to the control volume
numbered 000155. The name of the high-level index is HIGHINDX.

INDEX

CONNECT

CONNECT TWO CONTROL
VOLUf1ES

Check Exceptional Returns
CONNECT

*INDXNAME
OLDCVOl
NEWCVOl

CAMLST
DC
DC
DC
DC

LNKS,INDXNAME,OLDCVOL
WHOSE SERIAL NUMBERS
CL8'HIGHINDX'
ARE 000155 AND 001555.
CL6'OOOI55'
2314 DISK DEVICE CODE
X'30C02008'
CL6'001555'

The INDEX macro instruction points to the CAMLST macro
instruction. LNKX, the first operand of CAMLST, specifies that
control volumes be connected. INDXNAME, the second operand,
specifies the virtual storage location of the 8-byte area into
which you have placed the name of the high-level index of the
volume to be connected. OLDCVOL, the third operand, specifies the
virtual storage location of a 6-byte area into which you have
placed the serial number of the volume to which you are
connecting.
NEWCVOl, the fourth operand, specifies the virtual storage
location of a lO-byte area into which you have placed the 4-byte
binary device code of the volume to be connected followed by the
6-byte area to contain the volume serial number of the volume to
be connected.
Control will be returned to your program at the next executable
instruction following the INDEX macro instruction. If the control
volumes have been successfully connected, register 15 will
contain zeros. Otherwise, register 15 will contain one of the
except i on return codes descr i bed in the sect i on "au i ldi ng an
Index (INDEX and CAMlST BLDX)."

DISCONNECTING CONTROL VOLUMES (INDEX AND CANLST DRPXl
You disconnect two control volumes by using the INDEX and CAMLST
macro instructions.

C
oo

The result of disconoecting control volumes is that the control
volume pointer is removed from the volume index of the volume from
which you are disconnecting.

0
0 -

Using Catalog Management Macro Instructions

The format of the parameter list of this macro is described in
OS/VS2 System Programming Library: Debugging Handbook in the
section "SVC Summary."
The format is!
[symbol]
listname

INDEX
CAr1LST

list-addrx

DRPX

,index namerelexp
[,cvol-relex~J

list-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.

DRPX
index

thi s operand must be coded as shown.
namer~lex~

specifies the virtual storage location of the name of a
high-level index. The area that contains the name must be 8
bytes long. The name may be defined by a C-type Define
Constant (DC) instruction.

cvol-rele~~

specifies the virtual storage location of a 6-byte volume
serial number of the CVOL catalog to which this catalog
request is directed. For a discussion of the effect of
spec; fyi ng or omi tti ng thi 5 operand, see "Catalog Order of
Search" earlier in this section.

Example: In the following example, the control volume that
contains the high-level index HIGHINDX is disconn~cted from the
CVOL pointed to by the entry 'HIGHINDX' in the master catalog.
INDEX

DISCNECT

DISCONNECT TWO
CONTROL VOLUMES

Check Exceptional Returns
DISCNECT
It~DXNAME

CAr-1LST
DC

DRPX,INDXNAME
CL8'HIGHINDX'

MUST BE 8-BYTE FIELD

The INDEX macro instruction points to the CAMLST macro
instruction. DRPX, the first operand of CAMlST, specifies that
control volumes be disconnected. INDEXNAME, the second operand,
specifies the virtual storage location of the 8-byte area into
which you have placed the name of the high-level index of the
control volume to be disconnected.
Control will be returned to your program at the next executable
instruction following the INDEX macro instruction. If the control
volumes were successfully disconnected, register 15 will.contain
zeros. Otherwise, register 15 will contain one of the exception
return codes described in the section "Building an Index (INDEX
and CAMlST BlDX)."

WORKING WITH NONVSAM DATA SET CATALOG ENTRIES
You can catalog, uncatalog, and recatalog non-VSAM data sets by
using combinations of the CATALOG and CAMLST macro instructions.
CATALOG macro instructions are used to point to CAMLST macro
instructions; CAMLST macro instructions are used to specify
cataloging options.

OS/VS2 System Programming library: Data Management

CATALOGING A NONVSAM DATA SET (CATALOG AND CAMLST CAT)
The format of the parameter list of this macro is described in
OS/VS2 System 'Programming Library: Debugging Handbook in the
section "sve Summary."
The format of the CATALOG and CAMlST macros is:
[symboll
listname

CATALOG
CANLST

1 i s!,-ad.9l:..K
CAT'[BXl
,name-relexp
,[cvol-relexpl
,vol list-relexp
[,DSCBTTR=dscb ttr-relexpl

list-addrx
points to the parameter list (labeled listname) set up by the
CAMlST macro instruction.
CAT[SXl
this operand must be coded as shown. Either CAT or CATBX may
be coded but in either case missing indexes within a CVOl are
always automatically created.
name-releKe

specifie~ the virtual storage location of the fully
qUalified name of a data set. The name cannot exceed 44
characters. If the name is less than 44 characters, it must
be followed by blanks. The name may be defined by a C-type
Define Constant (DC) instruction.

cvol-rele.K,P
specifies the virtual storage location of the 6-byte volume
serial number of the CVOl catalog to which this catalog
request is directed. For a discussion of the effect of
specifying or omitting this operand, see "Catalog Order of
Search" earlier in this section.
vol Ii st-rel,exp
specifies the virtual storage location of an area that
contains a volume list. The list must begin on a halfword
boundary and consist of an entry for each volume on which the
data set is stored. The first two bytes of the list indicate
the number of entries in the volume list; the number cannot
be zero. Each 12-byte volume list entry consists of a 4-byte
device code, a 6-byte volume serial number, and a 2-byte data
set sequence number. The sequence number is always zero for
direct access volumes. (Device codes are presented in OS/VS2
System Programming library: Debugging Handbook.)
DSCBTTR=dscb ttr-relexp
specifies the virtual storage location of the 3-byte
relative track address (TTR) of the format-1 data set
control block (DSCB) for a data set that resides on only one
volume. The address is relative to the beginning of the
volume.

programming Considerat;ons for Multiple-Step Jobs
When you are executing multiple-step jobs, it is preferable to
catalog or uncatalog data sets usi ng JCL, instead of lIsi ng
IEHPROGM or a user program. Since AllOCATION/UNAlLOCATIONmonitors data sets during job execution, and it is not aware of
the functions performed by the user programs, conflicting
functions can be performed or GDG orientation can be lost.
UNAlLOCATION re-catalogs existing cataloged data sets at job
termination. This action occurs because the data set is opened
sometime during the job and the DSCB TTR was not found in the
catalog entry. Therefore, if you are using the CAMLST macro to
Using Catalog Management Macro Instructions

uncatalog and then catalog data sets with new volume information,
be sure to include the DSCB TTR.

Example: In the following example, the non-VSAM data set named
A.B.C is cataloged. The dataset is stored on two volumes.

CATALOG ADDABC

CATALOG DATA SET A.B.C.

Check Returns
ADDABC
DSNAME
VOLUMES

CAMLST
DC
DC
DC
DC
DC
DC
DC
DC

CAT,DSNAME"VOLUMES
Cl6'A.B.C'
ONE BLANK FOR DELIMITER
H'2'
DATA SET ON TWO VOLUMES
X'30C02008'
2314 DISK DEVICE CODE
CL6'0000I4'
VOLUME SERIAL HUMBER
H'O'
DATA SET SEQUENCE NUMBER
X'30C02008'
2314 DISK DEVICE CODE
CL6'OOOOI5'
VOLUME SERIAL NUMBER
H'O'
SEQUENCE NUMBER

The CATALOG macro instruction points to the CAMLST macro
instruction. CAT, the first operand ofCAMLST, specifies that a
data set is to be cataloged. DSNAME, the second operand, specifies
the virtual storage location of the area in which the name A.B.C
was placed. VOLUMES, the fourth· operand, specifies the virtual
storage location of the volume list that was built.
Control will be returned at the instruction following the CATALOG
macro instruction. If A.B.C was successfully cataloged, register
15 will contain zeros. Otherwise, register 15 will contain one of
the following return codes:

Code

Meaning

Ei ther the requi red catalog does not exi st, it is not open,
or the "do not allocate" bit is on.

One of the fo 11 ow i n9 happened:
•

The existing catalog structure is inconsistent with the
operation requested. If the error was detected while
processing in a CVOL, register 0 has the number of valid
index levels and register 1 has the return code that
would have resulted if a LOCATE macro had been issued
for the same entry name. If the error was detected in a
VSAM catalog, register 0 contains the VSAM catalog
return code and register 1 contains zero.

•

The user is not author; zed to perform the operat ion.
Register 0 contains decimal 56 and register 1 contains
zero.

Not used with the CATALOG macro instruction.

The index structure necessary to catalog the data set does
not exist.

There is insufficient space on the catalog data set.

An attempt was made to catalog an improperly named
generation data set, or the generation index is full and the
named data set is older than any currently in the index.

One of the following happened:
•

OS/VS2

A permanent I/O or unrecoverable error was encountered.

Sy~tem Progr~mminglibrary:

Data Management

'-._/

(

•

An error was found in a parameter list.

•
•

An I/O error occurred in a CVOL .
There was a

no~zero

return code from ESTAE .

UHCATALOGING A NONVSAM DATA SET (CATALOG AND CAr1LST UNCAT)

When the UNCAT or UCATDX operand of the CAMLST macro instruction
is used, a data set reference and unneeded indexes, with the
exception of the highest-level index, are removed.
.
The format of the parameter list of this macro is described in
OS/VS2 System Programming Library: Debugging Handbook in the
section "SVC Summary."
The format of the CATALOG and CAMlST macros is:
[ symbol]
listname

list-addrx

CATALOG
CANLST

UNCAT or UCATDX

,name-relexp
[,cvol-relexp]

list-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.
UNCAT

UCATDX

this operand must be coded as shown. Either UNCAT or UCATDX
may be coded but in either case unneeded indexes, with the
exception of the highest-level index, are always removed
along with the data set reference.
name-relexe
specifies the virtual storage location of the fully
qualified name of a data set or index level. The name cannot
exceed 44 characters. If the name is less than 44 characters,
it must be followed by blanks. The name may be defined by a
C-type Define Constant (DC) instruction.
cvol-rele~e

specifies the virtual storage location of the 6-byte volume
serial number of the CVOL catalog to which this catalog
request is directed. For a discussion of the effect of
spec; fyi ng or omi tti ng thi s operand, see "Catalog Order of
Search" earlier in this section.
In the following example, the catalog entry for data set A.B.C is
removed from an MVS catalog. In a CVOL, index B is removed unless
it contains references to other data sets. Index A remains because
it is the highest level index.

CATALOG REMOVE

REMOVE REFERENCES TO
DATA SET A.B.C FROM
CATALOG

Check Returns
REMOVE
OS NAME

CAMLST
DC

UNCAT,DSNAME
CL6~A.B.C'

ONE BLANK FOR DELIMITER

The CATALOG macro instruction points to the CAMlST macro
instruction. UN CAT specifies that references to a data set be
removed from the catalog. DSNAME specifies the virtual storage

Using Catalog Management Macro Instructions

location of the area into which you have placed the fully
qualified name of the data set whose"references are to be removed.
Control will be returned to your program at the instruction
following the CATALOG macro instruction. If your data set has been
successfully uncataloged, register 15 will contain zeros.
Otherwise, register 15 will contain one of the return codes
described in the section "Cataloging a NonVSAM Data Set (CATALOG
and CAMLST CAT)."
RECATALOGING A NONVSAN DATA SET (CATALOG AND CAMLST RECATl
You can recatalog a cataloged non-VSAM data set by using the
CATALOG and CAMLST macro instructions. Recataloging is usually
necessary if a data set is ext~nded to a new volume.
As in the original cataloging procedure, you must build a complete
volume list in virtual storage. This volume list consists of an
entry for each volume on which the data set resides. The first 2
bytes of the list indicate the number of entries in the list; the
number may not be zero. Each I2~byte volume pointer consists of a
4-byte device code, a 6-byte volume serial number, and a 2-byte
data set sequence number. The sequence number ;s always zero for
direct access volumes. (Device codes are presented in OS/VS2
System Programming library: Debugging Handbook.)
The format of the parameter list of this macro is described in
OS/VS2 System Programming Library: Debugging Handbook in the
section "SVC Summary."
The format of the CATALOG and CAMlST macros is:
[.21ml bol )
listname

CATALOG
CAt1LST

list-addrx

RECAT

,[,ame-rele.xe
,[cvol-rele.xE]
,vol list-relex..E
[,DSCBTTR=dscb ttr-relexel

list-addrx
points to the parameter list (labeled listname) set up by the
CAMlST macro instruction.
RECAT

this operand must be coded as shown.

name-relexpspecifies the virtual storage location of the fully
qualified name of a data set. The name cannot exceed 44
characters. If the name is less then 44 characters, it must
be followed by blanks. The name may be defined by a C-type
Define Constant (DC) instruction.
cvol-relex.E
specifies the virtual storage location of the 6-byte volume
serial number of the CVOl catalog to which this catalog
request is directed. For a discussion of the effect of
specifying or omitting this operand, see "Catalog Order of
Search" earlier in this section.
vol list-relexe
specifies the virtual storage location of an area that
contains a volume list. The area must begin on a half-word
boundary.
DSCBTTR=dscb ttr-r~lexE
specifies the virtual storage location of the 3-byte
relative track address (TTR) of the identifier (format-I)
DSCB for a data set that resides on only one volume. The
address is relative to the beginning of the volume.
22

OS/VS2 System Programming library: Data Management

Example: In the following example, the two-volume data set named
A.B.C is recataloged to add a third volume. An entry is added
the volume list, which previously contained only two entries.
CATALOG RECATLG

*
*

RECATALOG DATA SET
A.B.C. ADDING A NEW
VOLUME

Check Returns
RECATLG
DSNAME

CAMLST
DC

*
VOLUMES

DC
DC
DC
DC
DC
DC
DC
DC
DC

RECAT,DSNAME"VOLUMES
CL6'A.B.C'
POINTER TO THE VOLUME
LIST.
FOR DELIMITER ONE BLANK
H'3'
THREE VOLUMES.
X'30C02008'
2314 DISK DEVICE CODE
CL6'OOOO14'
VOLUME SERI~ NUMBER
SEQUENCE NUMBER
H'O'
X'30C02008'
2314 DISK DEVICE CODE
CL6'OOOO15'
VOLUME SERIAL NUMBER
H'Q'
SEQUENCE NUMBER
X'30C02008'
2314 DISK DEVICE CODE
CL6'OOOO16'
VOLUME SERIAL NUMBER
SEQUENCE NUMBER
H'O'

The CATALOG macro instruction points to the CAMLST macro
instruction. RECAT, the first operand of CAMlST, specifies that a
data set be recataloged. DSNAME, the second operand, specifies
the virtual storage locatt6n of an area into which you have placed
the fully qualified name of the data set to be recataloged.
VOLUMES, the fourth operand, specifies the virtual storage
location of the volume list you have built.
Control will be returned to your program at the instruction
following the CATALOG macro instruction. If the data set has been
successfully recataloged, register 15 will contain zeros.
Otherwise, register 15 will contain one of the return codes
descr i bed in the sect ion "Catalog i ng a NonVSAM Data Set (CAT ALOG
and CAMLST CAT)."

Using Catalog Management Macro Instructions

CVOL CATALOG ENTRY FORMATS
This section describes the format and contents of each of the
entries that may appear in the catalog.

'-.... /

VOLUME INDEX CONTROL ENTRY

Field I
X'OOOOOOOOOOOOOOOI'
Name

Field 2

Field 3

TTR of last
block in
volume index

Count

Field 4

Field 5

TTR of
last block
in SYSCTlG
data set
12

Field 6

Field 7

Field 8

Unused
bytes

TTR of first
unused block
in SYSCTlG
data set
16

<-----------------Total length: 22 Bytes------------------>
Field 1:

Name (8 bytes)-contai ns only a bi nary one to ensure that thi sentry is the
first entry in the first block of the index.

Field 2:

last-block address (3 bytes)--contains the relative track address (TTR) of
the last block in the volume index.

Field 3:

Halfword count (1'byte)-contains a binary five to indicate that five
halfwords follow.

Field 4:

Catalog upper limit (3 bytes)-contains the relative track address (TTR) of
the last block in the catalog data set.

Field 5:

Zero field (1 byte)--contains binary zeros.

Field 6:

First-available-block address (3 bytes)--contains the relative track
address (TTR) of the unused block in the catalog that is closest to the
beginning of the catalog data set.

Field 7:

Zero field (1 byte)-contains binary zeros.

Field 8:

Unused (2 bytes)

Figure 1. The Volume Index Control Entry

c·
24

OS/VS2 System Programming library: Data Management

INDEX CONTROL ENTRY

Field 1

Field 2

X'OOOOOOOOOOOOOOOOI'
Name

Field 3
03

TTR of
last
block in
this
index
8

Count

Field 4

Field 5

Field 6

TTR of
first
block in
this
index

Alias
count

Unused
bytes

<--------------------------Total length: 18 Bytes------------------------------->
This index control entry is quite similar to a volume index control entry, but it only
contains information about the index, which it begins. It is 18 bytes long and
contains six fields.

Field 1:

Name (8 bytes)-contai ns only a bi nary one to ensure that thi sentry,
because it has the lowest binary name value, is the first entry in the
1irst block of the index.

Field 2:

last block address (3 bytes)--contains the relative track address (TTR) of
the last block assigned to this index.

Field 3:

Halfword count (1 byte)--contains a binary three to indicate that 3
ha1fwords follow.

Field 4:

Index lower limit (3 bytes)--contains the relative track address (TTR) of
the block in which this entry appears.

Field 5:

Number of a1 i ases (1 byte)--contai ns the bi nary coun·t of ·the number of
aliases assigned to the index. If the index is not a high level index, this
f i el dis zero.

Field 6:

Unused (2 bytes)

Figure 2. The Index Control Entry

c
Using Catalog Management Macro Instructions

INDEX LINK ENTRY AND INDEX POINTER ENTRY

Index link Entry

Field I

X'FFFFFFFFFFFFFFFF'
Name

Field 2

Field 3

TTR of next block
in index (or zero
if no next block)

Count

<--------------------------Total length: 12 Bytes

Index Pointer Entry

Field 1

Field 2

Field 3

Index name (padded to
right with blanks if
necessary)

TTR of index

Count

<-----------------------------Total Length: 12 Bytes----------------------------->
The index link and index pointer entries are quite similar. An index link entry is used
to chain several blocks of an index together, and an index pointer entry is used to
chain an index to the next lowgr level index. An index link entry is always the last
entry in any index block. These blocks contain three fields and are 12 bytes lorig.

Field 1:

Name (8 bytes)--contains the name of the index to which this entry points.
If the entry is an index link entry, the name field contaios X'FF FF FF FF
FF FF FF FF' .

Field 2:

Address (3 bytes)-contains either the relative block address (TTR) of the
first block of the next level index if it is an index pointer entry, or the
relative block address (TTR) of the next block of the same level index if
it is"an index link entry.

Field 3:

Hal fword count (1 byte)-contai ns 1 byte of bi nary zeros to i ndi cate that
the entry ends here.

Figure 3. The Index link and Index Pointer Entries

OS/VS2 System Programming library: Data Management

DATA SET POINTER ENTRY

Field 1

Field 2

Field 3

Field 4

lowest level name of
data set or complemented
generation number
(if part'of GDG)

DSCB
TTR or
zeros

Count

Volume
count

Field 5

Field 6

Field 7

Device
Code

Serial number
of volume on
which data
set resides

Data set
sequence
number (zero
for direct
access

I a . - - - -Repeated
- - for
veach
-volume
--------'
<----------/ /----------Total Length: 26 to 74 Bytes

The data set pointer entry can appear in any index. It contains the simple name of a
data set and from one to five 12-byte fields, each of which identifies a volume on
which the named data set resides. If the data set resides on more than five volumes, a
volume control block pointer entry is substituted for the data set pointer entry. A
volume control block pointer entry'points to a volume control block or chain of volume
control blocks that point to the volumes that contain the data set.
The data set pointer entry varies in length. The length is determined by the formula 14
+ 12m, whera m is the number of volumes containing the data set. The variable m can be
from one to five. The data set pointer entry can appear in any index, and it contains
five fields.

Field 1:

Name (8 bytes )-conta ins the si mple name of the data set whose volumes are
identified in field 5. If part of a GDG, these names have the format
GxxxxV 0 0, l-lhere ~ is the complement of the GDG number.

Field 2:

OSCB TTR (3 bytes)-contains the track address (TTR) of the data set
control block if the data set- resides on one volume. If the data set
resides on more than one volume, this field contains binary zeros.

Field 3:

Halfword count (1 byte)--contains the binary count of the number of
halfwords that follow. The number is found by the formula 6m + 1, where m is
the number of volumes on which the data set resides. The varia~le m can be
from one to five.

Field 4:

Volume count (2 bytes)-contains the binary count of the number of volumes
identified in field 5 of this entry.

Field 5:

Dev ice code (4 bytes )-conta ins the dev ice code of the dev ice' on wh i ch the
volume loJi th the volume serial number in field 6 can be mounted.

Field 6:

Volume serial number (6 bytes)--contains the volume serial number of one of
the volumes of the data set.

Field 7:

Volume sequence number (2 bytes)-contains the sequence number of the data
set on a magnetic tape volume. It is zero for any other device class.

Figure 4. The Data Set Pointer Entry

Using Catalog Management Macro Instructions

VOLUME CONTROL BLOCK POINTER ENTRY

Field 1

Field 2

lowest level
of data set
name

Field 3

0000

Dummy
data
entry

Count

TTR of
volume
control
block
8

Field 4

<----------------------Total length: 14 Bytes----------------->
The volume control block pointer entry is used instead of a data set pointer entry when
the data set resides on more than five volumes. This entry points to a volume control
block, which, in turn, describes the data set. The entry is 14 bytes long.

Field 1:

Name (8 bytes)--contains the last name of the qualified name of the' data
set identified by this entry.

Field 2:

Address (3 bytes)-contains the relative block address (TTR) of the volume
control block identifying the volumes containing the data set named in
field 1.

Field 3:

Halfword count (1 byte)-contains a binary one to indicate that one
halfword follows.

Field 4:

Zero ,field (2bytes)-containsbinary zeros.

Figure 5. The Volume Control Block Pointer Entry

OS/VS2 System Programming library: Data Management

VOLUME CONTROL BLOCK

Field 1

Field 2

Field 3

Field 4

Count

Device
Code

Serial
number
of volume n

Data set sequence
number for the
volume described
in field 5. Zero
for direct access

m+4

m+l0

I~-------------------v------------------------~
Repeated once for each volume; maximum of 20

Field 5

Ten bytes
of zeros

242

Field 7

Field 6

TTR of next
volume control
block, or zero
if none
252

255

<-----------------------Total length: 256 Bytes-------/ /---->

A volume control block contains the description of all the volumes of a data set th~t
resides on more than five volumes. If a data set resides on less than six volume~, a
volume control block is not built and the volumes are d~scribed in a data set pointer
entry. One volume control block can describe as many as 20 volumes. Volume control
blocks may be chained together to catalog a data set residing on more than 2~ volumes.
The volume control block is always 256 bytes long, regardless of the number of volumes
described.

Field 1:

Volume count (2 bytes)-the fi rst volume control block contai ns the
binary count of the total number of volumes on which the data set
resides. The value of this field is reduced by 20 for each
subsequent volume control block. If, for example, the data set
resides on 61 volumes, there will be four volume control blocks for
the data set. The volume count field of each will contain 61, 41,
21, or 1, respectively.

Fields 2, 3, 4:

Volume identification (12 to 240 bytes)--contains from one to
twenty each of which identifies a volume on which the data set
resides. Each entry contains a 4-byte device code, a 6-byte volume
serial number, and a 2-byte data set sequence number. The data set
sequence number is zero for data sets on direct-access volumes.

Field 5:

Zero field (10 bytes)-contains binary zeros.

Field 6:

Chain address (3 bytes)--contains the relative block address (TTR)
of the next volume control block, if additional blocks are needed to
describe the data set. If this is the last volume control block for
the data set, this field will be set to binary zeros.
Zero field (1 byte)--contains binary zeros.

Figure 6. The Volume Control Block

Using Catalog Management Macro Instructions

CONTROL VOLUME (eVOl) POINTER ENTRY

,
Field 1

Field 2

Field 3

Name of index on
other control volume

Dummy pointer
field: zeros

Count

Field 4

Field 5

Device code of
control volume

Serial number of
control volume

<---------------------Total length: 22 Bytes------------->

Note: Prior to Release 17, the control volume pointer entry contained a count of 03
and did not have a device code field (field 4).
The CVOl pointer entry is used to indicate that a particular index resides on avolum~
other than the system residence volume. Control volume pointer entries can exist only
in the volume index. They are 22 bytes long.
Field 1:

Name (8 bytes)--contains a high-level index name that appears in
index of the control volume identified in fields 4 and 5.

Field 2:

Address (3 bytes)-contains zero·s, because thi s entry references no other
entry in the catalog.

Field 3:

Halfword count (1 byte)--contains the number 5 to indicate that five
halfwords follow.

Field 4:

CVOL device code (4 bytes)--This field contains the device code of the
specified control volume.

Field 5:

CVOL volume seri al number (6 bytes)--contai ns the volume seri al number of
the control volume which has an entry in its volume index of the same nam~
as thi sentry.

th~

volume

Figure 7. The Control Volume (CVOL) Pointer Entry

CONTROL VOLUHE POINTER ENTRY (OLD)
Until Release 17 of OS MFT/MVT, the control volume pointer entry
was the same as the present control volume pointer, except that
there was no field 4 (device code). The old CVOl pointer entry was
18 bytes long; after Release 17, it is 22 bytes long. Since some
control volumes may still contain entries in the old format, and
since the catalog management routines still check for it, it is
mentioned here.

OS/VS2 System Programming Library: Data Management

...

GENERATION INDEX POINTER ENTRY

(
Field 1

Field 2

Field 3

Field 4

Field 5

Field 6

Name

TTR

Count

Flags

Maximum
Count

Current
Count

<--------------------------Total length: 16 Bytes---------------------->
A generation index pointer entry is the entry that identifies a generation data group
(GOG). It represents the next to the lowest level of a group of generation data set
names. It is created by using the BLDG macro.

Field 1:

Name (8 bytes)--this name represents the GOG level that is next to the
lowest level of GOG data set names.

Field 2:

Address (3 bytes)--contains the relative track address (TTR) of the first
block of the level containing the lowest level GOG names. These names have
the format Gxxx~VOO, where ~ is a complement of the GOG number.

Field 3:

Count (1 byte )-X' 02' i'dent i fi es thi s entry and i ndi cates the number of
halfwords that follow this field.

Field 4:

Flags (1 byte)-indicates the options specified by the creator of the GDG.
X'02'=OElETE option.
X'01'=EMPTYoption.

(

Field 5:

Maximum Count (1 byte)--a binary number that specifies the maximum number
of generations allowed in the generation index at one time.

Field 6:

Current Count (2 bytes)--the binary count of the number of generations
currently cataloged in the generation data group (GOG).

Figure 8. Generation Index Pointer Entry

Using Catalog Management Macro Instructions

ALIAS NAME
\

Field I

Field 2

Alias Name

TTR
pointer

Field 3

Field 4

X'04'
Count
11

True Name
12

<----------------------Total length: 20 Bytes------------------>
An alias entry defines an alternate name for the high-level qualifier of a data set
name.

Field 1:

Name (8 bytes)-contains the alias of the high-level index whose relative
track address; s found at fi eld 2.

Fi eld 2:

Address (3 bytes)-contains the relative track address (TTR) of the first
block of the index named in field 4.
Halfword count (1 byte)--identifies this entry and contains the binary
count of the number of halfwords that follow. The number is X'04'.

Field 4:

True name (8 bytes)-contains the name of the index whose alias appears in
field 1.

Figure 9. Alias Name

OS/VS2 System Programming library: Data Management

"-.. -

MAINTAINING THE VOLUME TABLE OF CONTENTS

This chapter contains information on how to read and change the
volume table of contents (VTDC) used on direct-access storage
device volumes. The information consists of how-to information,
macro specifications, and coding examples for the OBTAIN,
SCRATCH, and RENAME macro instructions.
More detailed information about how the routines called by these
macros work is available in OS/VS2 DADSM Logic.
Before using the information in this chapter you should be
familiar with the information contained in the following
publications:

•

OS/VS-DOS/VS-VM/370 Assembler language, which contains
information you will need in order to code programs in the
assembler language.

•

OS/VS2 MVS Data Management Services Guide, contains a general
description of direct-access device characteristics and the
volume table of contents.

•

OS/VS2 MVS Utilities, tells how to use utility programs to
maintain the volume table of contents.

•

OS/VS2 System Programming Library: Debugging Handbook, which
contains descriptions of (1) the data set control block
(OSCB) formats and (2) the contents of the fields of each
DSCB.

•

Data Facility Device Support: User's Guide and Reference
contains information about VTDC indexes.

INTRODUCTION
In the same way that the catalog management routines keep track of
cataloged data sets, the direct-access device space management
(DAOSM) routines maintain the volume table of contents (VTDC) on
direct-access storage devices. This chapter tells how to use the
OBTAIN, SCRATCH, and RENAME macro instructions. These macros are
most commonly used by the system control program and the data set
utility programs (IEHMOVE, IEBCOPY, and IEHPROGM), but you may
use them in your own routines. The functions you can perform with
these macros are:
•

Reading a data set control block from the VTOC-OBTAIN

•

Deleting a data set-SCRATCH

•

Changi ng the name of a data set-REHAME

You can read a data set control block (DSCB) into virtual storage
by using the OBTAIN and CAMLST macro instructions. There are two
ways to specify the DSCB that you want to read: by using the name
of the data set associated with the OSCB, or by using the absolute
track address of the DseB. You must provide a 140-byte data area
in virtual storage, into which the OSCB will be read. When you
specify the name of the data set, an identifier (format-lor
format-4) DSCB is read into virtual storage. To read a DSCB other
than a format-lor a format-4 OSeB, you must specify an absolute
track address (see second example). (OSeB formats and field
descriptions are contained in OS/VS2 System Programming Library:
D~bugging Handbook.)
You can delete a data set by using the SCRATCH and CAMLST macro
instructions. This causes the OSCBs for the data set to be
deleted.
Maintaining the Volume Table of Contents

You can change a data set name by us~ng the RENAME and CAMLST
macro instructions. This causes the data set name in the
identifier (format-I) OSCB for the data set to be replaced with
new name.
Accompanying the descriptions of the macro instructions are
coding examples, programming notes, and exception return code
descriptions.
Note: OBTAIN, SCRATCH, and RENAME macro instructions cannot ba

used with a SYSIN or SYSOUT data set.

READING A DSeB BY NAME (OBTAIN AND CANLST SEARCH)
If you specify a data set name using OBTAIN and the CAMLST SEARCH
option, the 96-byte data portion of the identifier (format-I)
DSCB and the absolute track address of the DSCB are read into
virtual storage. The absolute track address is a 5-byte field in
the form CCHHR. The absolute track address field will contain
zeros for VSAM and VIa data sets.
The format of the parameter list of this macro is described in
OS/V~~st.em Pro9rammi n9 library: Debu99i n9 Handbook in the
section "SVC Summary."
The format is:
[.2..v.mboll
listname

OBTAIN
CANLST

list-addrx

SEARCii-,dsname-reiexp
,vol-relexp
,wkarea-relexp

l;st-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.

this operand must be coded as shown.

dsname-rel e.x£
specifies the virtual storage location of a fully qualified
data set name. The area that contains the name must be 44
bytes long.
Note: A DSNAME of 44 bytes of X' 04' can be used to read a

format-4 OSCB.

vol-relexl:?,
specifies the virtual storage location of the 6-byte volume
serial number of the volume on which the OSCB is located.
wk a r e a - r e IJt~.e

specifies the virtual storage location of a 140-byte work
area that you must define.

Example: In the following example, the identifier (format-I) OSCB
for data set A.B.C is read into virtual storage using the SEARCH
option. The serial number of the volume containing the OSCB is
770655.

as/VS2 System Programming library: Oata Management

OBTAIN

DSCBABC

READ DSCB FOR DATA
SET A.B.C INTO DATA
AREA NAMED WORKAREA

Check Returns
DSCBABC
DSABC
VOLNUM
WORKAREA

CAMlST
DC
DC
DS

SEARCH,DSABC,VOLNUM,WORKAREA
CL44'A.B.C'
DATA SET NAME
CL6'770655'
VOLUME SERIAL NUMBER
140C
140-BYTE WORK AREA

The OBTAIN macro instruction points to the CAMLST macro
instruction. SEARCH, the first operand of CAMLST, specifies that
a OSCB be read into virtual storage, uSlng the data set name you
have supplied at the address indicated in the second operand.
OSABC, the second operand, specifies the virtual storage location
of a 44-byte area into which you have placed the fully qualified
name of the data set whose format-l OSCB is to be read. VOLNU~l,
the third operand, specifies the virtual storage location of a
6-byte area into which you have placed the serial number of the
volume containing the required OSCB. WORKAREA, the fourth
operand, specifies the virtual storage location of a 140-byte
work area into which the OSCB is to be returned.
Control will be returned to your program at the next executable
instruction following the OBTAIN macro instruction. If the OSCB
has been successfully read into your work area, register 15 will
contain zeros. Otherwise, register 15 will contain one of the
following return codes:

Code

Meaning

The requ i red volume was not mounted.

A permanent 1/0 error was encountered, or an invalid
format-l OSCB was found when processing the ~pecified
volume, or an unexpected error return code was received
from CVAF (Common VTOC Access Facility).

Invalid work area pointer.

After execution of these macro instructions, the first 96 bytes of
the work area contain the data portion of the identifier (format-l
or format-4) OSCB; the next 5 bytes contain the absolute track
address (CCHHR) of the OSCB. These 5 bytes will contain zeros for
VSAM or VIO data sets.

READING A DSCB BY ACTUAL DEVICE ADDRESS (OBTAIN AND CAMLST SEEK)
You can read any OSCB from a VTOC using OBTAIN and the CAMLST SEEK
option. You specify the SEEK option by coding SEEK as the first
operand of the CAMLST macro and by providing the absolute device
address of the OSCB you want to read, unless the DSCB is for a VIO
data set. Only the SEARCH option can be used to read the DSCB of a
VIO data set.
The format of the parameter list of this macro is described in
OS/VS2 System Programming library: Debugging Handbook in the
section "SVC Summary."

Maintaining the Volume Table of Contents

The format is:
[s~mbol]

listname

OBTAIN
CAHLST

list-addrx
SEEK

,cchhr-relexp
,vol-relexp
,wkarea-relexp

list-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.
SEEK

this operand must be coded as shown.
cchhr-relexp
specifies the virtual storage location of the 5-byte
absolute device address (CCHHR) of a DSCB.
vol-relexp
specifies the virtual storage location of the 6-byte volume
serial number of the.vodume on which the DSCB is located.
wkarea-rele~..e

specifies the virtual storage location of a 140-byte work
area that you must define.
.

Example: In the following example, the DSCB at actual-device
address X'OO 00 00 01 07' is returned in the virtual storage
location READAREA, using the SEEK option. The DSCB resides on the
volume with the volume serial number 108745.
OBTAIN

ACTADDR

READ DSCB FROM
LOCATION SHOWN IN CCHHR
INTO STORAGE AT LOCATION
NAMED READAREA

Check Returns
ACTADDR
CCHHR
VOLSER
READAREA

CAMLST
DC
DC
DS

SEEK,CCHHR,VOLSER,READAREA
Xl5'OOOOOOOl07' ABSOLUTE TRACK ADDRESS
CL"108745'
VOLUME SERIAL HUMBER
140C
140-BYTE WORK AREA

The OBTAIN macro points to the CAMlST macro. SEEK, the first
operand of CAMlST, specifies that a DSCB be read into virtual
storage. CCHHR, the second operand, specifies the storage
location that contains the 5-byte actual-device address of the
DSCB. VOlSER, the third operand specifies the storage location
that conta·ins the volume serial number of the volume on which the
DSCB resides. The fourth operand, READAREA, specifies the storage
location to which the 140-byte DSCB is to be returned.
Control will be returned to your program at the next executable
instruction following the OBTAIN macro instruction. If the Dscn
has been successfully read into your work area, register 15 will
contain zeros. Otherwise, register 15 will contain one of the
following return codes:

c
36

OS/VS2 System Programming Library: Data Management

Code

Meaning

The required volume was not mounted.

The format-1 DSCB was not found in the VTaC of the specified
volume.

A permanent I/O error was encountered, or an invalid
format-4 DSCB was found when processing the specified
volume, or an unexpected error return code was received
from CVAF (Common VTOC Access Facility).

Invalid work area pointer.

The SEEK option L"as specified and the absolute track
address (CCHH) is not within the boundaries of the VTOC.

DELETING A DATA SET (SCRATCH AUD CAt1LST SCRATCH)

You delete a data set stored on direct-access volumes by using the
SCRATCH and CAMLST macro instructions. This causes all data set
control blocks (OSCBs) for the data set to be deleted, and all
space occupied by the data set to be made available for
reallocation. If you want to scratch a data set being processed
using virtual input/output (VIO), the data set must have been
allocated for use by YJur job. Scratching VIO data sets not
allocated to your job is not all oL.Jed.
If the data set to be deleted is sharing one or more cylinders
with one or more data sets (a split-cylinder data set), the space
will not be made available for reallocation until all data sets on
the shared cylinders are deleted.

A data set cannot be deleted if the expiration date in the
identifier (format-I) DSCB has not passed, unless you choose to
ignore the expiration date. You specify that the expiration date
is to be ignored by using the OVRD option in the CAMLST macro
instruction.
Refer to DS/VS2 MVS Resource Access Control Facility (RACF):
General Information Manual for information on RACF-defined data
sets. You may only scratch a RACF-defined data set (that is, the
DSCB indicates RACF-defined) if you have alter access authority
to either the data set/volume serial in the DATASET class, or to
the volume serial in the DASDVDL class (if the volume is
RACF-defined).
Refer to Data Facility Device Support: User's Guide and Reference
for information on scratching a VTDC index data set.
If a data set to be deleted is stored on more than one volume,
a; thar a devi ce must be avai lable on whi ch to mount the volumes,
or a-t least one volume must be mounted. In addi ti on, all other
required volumes must be serially mountable.
When deleting a data set, you must build a volume list in virtual
storage. This volume list consists of an entry for each volume on
which the data set resides. The first two bytes of the list
indicate the number of entries in the list. Each 12-byte entry
consists of a 4-byte device code, a 6-byte volume serial number,
and a 2-byte scratch status code which should be initialized to
zero. Device codes are presented in DS/VS2 System Programming
Library: Debusging Handbook.

Volumes are processed in the order that they appear in the volume
list. The volume at the beginning of the list is processed first.
If a volume is not mounted, a message is i5sued to the operator
requesting him to mount the volume. (A volume mount message will
not be issued for an MSS virtual volume; however, a status code
will be returned to your program.) This is only done if you
indicate the direct access device on which unmounted volumes are
Maintaining the Volume Table of Contents

to be mounted by loading register 0 with the address of the UCB
associated with the device to be used. (The device must be
allocated to your job.) If you do not load register 0 with a UCB
address, its contents must be zero, and at least one of the
volumes in the volume list must be mounted before the SCRATCH
macro instruction is issued.
If the operator cannot mount the requested volume, he issues a
reply indicating that he cannot fulfill the request. A condition
code is then set in the last byte of the volume pointer (the
second byte of the scratch status code) for the unavailable
volume, and the next volume indicated in the volume list is
processed.
The format is:
[s~mbol]

listname

SCRATCH
CAULST

list-addrx

SCRATCH

,dsname-relexp
"vol list-relexp
["OVRD)

list-addrx
points to the parameter list (labeled listname) set up by the
CAMLST macro instruction.

SCRATCH

thi s operand must be coded as shown.

dsname-relex,2
specifies the virtual storage location of a fully qualified
data set name. The area that contains the name must be 44
bytes long. The name must be defined by a C-type Define
Constant (DC) instruction.
vollist-relexp
specifies the virtual storage location of an area that
contains a volume list. The area must begin on a halfword
boundary.
OVRD

when coded as shown, specifies that the expiration date in
the DSCB should b~ ignored.

ExaMple: In the following example, data set A.B.C is deleted from
two ~olumes. The expiration date in the identifier (format-I)
DSCB is ignored.

SR
SCRATCH

0,0
DELABC

SET REG 0 TO ZERO
DELETE DATA SET A.B.C.
FROM TWO VOLUMES,
IGNORING EXPIRATION
DATE IN THE DSCB

Check Returns
DEL ABe
DSABC
VOL 1ST

CAMlST
DC
DC
DC
DC
DC
DC
DC
DC

SCRATCH,DSABC"VOLIST"OVRD
Cl44'A.B.C'
DATA SET HAMES
H'2'
HUMBER OF VOLUMES
X'30C02008'
2314 DISK DEVICE CODE
Cl6'000017'
VOLUME SERIAL NO.
H'O'
SCRATCH STATUS CODE
X'30C02008'
2314 DISK DEVICE CODE
CL6'000018'
VOLUME SERIAL NO.
H'O'
SCRATCH STATUS CODE

OS/VS2 System Programming Library: Data Management

The SCRATCH macro instruction points to the CAMLST macro
instruction. SCRATCH, the first operand of CAMLST, specifies that
a data set be deleted. DSABC, the second operand, specifies the
virtual storage location of a 44-byte area into which you have
placed the fully qualified name of the data set to be deleted.
VOLIST, the fourth operand, specifies the virtual storage
location of the volume list you have built. OVRD, the sixth
operand, specifies that the expiration date in the DSCB of the
data set to be deleted be ignored.
When you attempt to delete a password-protected data set which is
not also RACF-protected, the operating system issues a message
(IEC301A) to ask the operator at the console or terminal operator
of a remote console to enter the password. The data set will be
scratched only if the password supplied is associated with a WRITE
protection mode indicator. The protection mode indicator is
described in the chapter titled "Data Set Protection."
Control is returned to your program at the next executable
instruction following the SCRATCH macro instruction. If the data
set has been successfully deleted, register 15 will contain zeros
and the scratch status code ;n the volume list entry for each
volume will be set to zero. Otherwise, register 15 will contain
one of the return codes that follow. To determine whether the data
set has been successfully deleted from each volume on which it
resides, you must examine the scratch status code~ the last byte
of each entry· in the volume list.

Return
Code in
Reg. 15

Meaning

No volumes containing any part of the data set were
mounted, nor did register 0 contain the address of a
unit that was available for mounting a volume of the
data set. The data set may be a VIO data set that was
not allocated during your job. (This return code is
accompanied by a scratch status code of 5 in each entry
of the volume list.)

An unusual condition was encountered on one or more
volumes.

The volume list passed was invalid. The scratch status
code, the last byte of each volume list entry, will not
have been modified during scratch processing.

After the SCRATCH macro instruction is executed, the last byte of
each 12-byte entry in the volume list indicates the following
conditions in binary codes:

Scratch
status
Code

Meaning

All DSCBs for the data set have been deleted from the
VTOC on the volume pointed to.

The VTOC of this volume does not contain the format-l
DSCB for the data set to be deleted.

The macro instruction failed when the correct password
was not supplied in the two attempts allowed, or an
attempt was made to scratch a VSAM data space.

The data set was not deleted from this volume because
either the OVRD option was not specified or the
retention cycle has not expired.

A permanent I/O error was encountered, or an invalid
format-l DSCB was found when processing this volume, or
an unexpected error return code was received from CVAF
(Commo~ VTDC Access Facility).
Maintaining the Volume Table of Contents

It could not be verified that this volume was mounted,
and no device was available on which this volume could
be mounted.

The operator was unable to mount this volume. For MSS, a
volume mount failure occurred. For a JES3-managed
virtual volume, JES3 would not allow the volume to be
mounted.

The specified data set could not be scratched because
it was being used.

The DSCB indicates the data set is defined to RACF but
either the accessor is not authorized to the data set or
to the volume, or the data set is a VSAM data space, or
the data set is not defined to RACF.

The data set is defined to RACF but its definition could
not be deleted by RACF.

RENAMING A DATA SET (RENAME AND CAMLST RENAME)
You rename a data set stored on one or more direct-access volumes
by using the RENAME and CAMLST macro instructions. This causes the
data set name in all identifier (format-l) DSCBs for the data set
to be replaced by the new name that you supply. (VIO data sets
cannot be renamed.)
If a data set to be renamed is stored on more than'one volume,
either a device must be available on which to mount the volumes,
or at least one volume must be mounted. In addition, all other
volumes of the data set must be serially mountable.
Refer to OS/VS2 MVS Resource Access Control Facility (RACF):
General Information Manual for information on RACF-defined data
sets. Only an accessor with alter access authority may rename a
RACF-def)ned data set.
Refer to Data Facility Device Support: User's Guide and Reference
for information on renaming a VTDC index data set.
When renaming a data set, you must build a volume list in virtual
storage. This volume list consists of an entry for each volume on
which the data set resides. The first two bytes of the list
indicate the number of entries in the list. Each 12-byte volume
list entry consists of a 4-byte device code, a 6-byte volume
serial number, and a 2-byte rename status code which should be
initialized to zero. Device codes are presented in OS/VS2 System
Programming library: Debugging Handbook. Volumes are processed in
the order they appear in the volume list. The first volume on the
list is processed first. If a volume is not mounted~ a message is
issued to the operator requesting him to mount the volume. (A
volume mount message will not be issued for an MSS volume;
however, a status code will be returned to your program.) This is
only done, if you indicate the direct-access device on which
unmounted volumes are to be mounted by loading register 0 with the
address of the UCB assoc i ated with the dev ice to be used. (The
device must be allocated to your job.) If you do not load register
o with a UCB address, its contents must be zero, and at least one
of the volumes in the volume list must be mounted before the
RENAME macro instruction is executed.
If the operator cannot mount a volume in the volume list, he
issues a reply indicating that he cannot fulfill the request. A
condition code is then set ~n the last byte of the volume list
entry (the second byte of the rename status code) for the
unavailable volume, and the next volume indicated in the volume
list is processed or requested.

OS/VS2 System Programming Library: Data Management

The format is:
[s~mbol]

listname

RENAME
CAtlLST

list-addrx
RENAtlE

,dsname-re1ex..E.
,new name-relexp
,vol list-relexp

list-addrx
po;nts to the parameter list (labeled listname) set up by the
CAMlST macro instruction.
RENAME

this operand must be coded as shown.

dsname-rele~

specifies the virtual storage location of a fully qualified
data set name. The area that contains the name must be 44
bytes long. The name must be defined by a C-type Define
Constant (DC) instruction.
new

name-rel~xe

specifies the
data set name
that contains
be defined by

virtual storage location of a fully qualified
that is to be used as the new name. The area
the name must be 44 bytes long. The name must
a C-type Define Constant CDC) instruction.

vol list-relexp
specifies the virtual storage location of an area that
contains a volume list. The area must begin on a halfword
boundary.
Example: In the followi n9 example, data set A. B. Cis renamed

D.E.F. The data set resides on two volumes.

SR
RENAME

0,0
DSABC

SET REG 0 TO ZERO
CHANGE DATA SET
NAME A.B.C. TO D.E.F

Check Returns
DSABC
OlDNAME
NEWNAME
VOL 1ST

CAMlST
DC
DC
DC
DC
DC
DC
DC
DC
DC

RENAME,OLDNAME,NEWNAME,VOLIST
CL44'A.B.C'
OLD DATA SET NAME
CL44'D.E.F'
NEW DATA SET NAME
H'2'
TWO VOLUMES
X'30C02008'
2314 DISK DEVICE CODE
CL6'OOOOI7'
VOLUME SERIAL NO.
H'O'
RENAME STATUS CODE
X'30C02008'
2314 DISK DEVICE CODE
CL6'000018'
VOLUME SERIAL NO.
H'O'
RENAME STATUS ConE

The RENAME macro instruction points to the CAMLST macro
instruction. RENAME, the first operand of CAMLST, specifies that
a data set be renamed. OLDHAME, the second operand, specifies the
virtual storage location of a 44-byte area into which you have
placed the fully qualified name of the data set to be renamed.
NEWNAME, the third operand, specifies the virtual storage
locat i on of a 44-byte area into whi ch you have placed the nel.J name
of the data set. VOlIST, the fourth operand, specifies the virtual
storage location of the volume list you have built.
Control is returned to your program at the next executable
instruction following the RENAME macro instruction. If the data
set has been successfully renamed, register 15 will contain
zeros, and the rename status code in the volume list entry for
Maintaining the Volume Table of Contents

each volume will be set to zero. Otherwise, register 15 will
con·tain one of the return codes that·follow. To determine whether
the data set has been successfully renamed on each volume on which
it resi des, you must exami ne the rename status code, the last byte
of each entry in the volume list.

Return
Code in

Reg. 15

Meaning

No volumes containing any part of the data set were
mounted, nor did register 0 contain the address of a
unit that was available for mounting a volume of the
data set to be renamed. The data set may be a VIO data
set, which can't be renamed. (This return code is
accompanied by a rename status code of 5 in each entry
of the volume list.>

An unusual condition was encountered on one or more
volumes.

The volume list passed was invalid. The rename status
code, the last byte of each volume list entry, will not
have been modified during rename processing.

After the RENAME macro instruction is executed, the last byte of
each 12-byte entry in the volume list indicates one of the
following conditions in binary code:

Rename
status
Code

J1eaning

The format-l DSCB for the data set has been renamed in
the VTOC on the volume pointed to.

The VTOC of this volume does not contain'the format-l
DSCB for the data set to be renamed.

The macro instruction failed when the correct password
was not supplied in the two attempts allowed, or the
user tried to rename a VSAM data space.

A data set with the new name already exists on this
volume.

A permanent I/O error was encountered, or an invalid
format-l DSCB was found when trying to rename the data
set on this volume, or an unexpected error return code
was received from CVAF (Common VTOC Access Facility).

It could not be verified that the volume was mounted,
and no devi ce was ava; lable on wh; ch the volume could be
mounted.

The operator was unable to mount this volume. For MSS, a
volume mount failure occurred. For a JES3-managed
virtual volume, JES3 would not allow the volume to be
mounted.

The specified data set could not be renamed on this
volume because it was being used.

The data set is defined to RACF but either the accessor
is not alter authorized to the data set or the data set
is defined to RACF on multiple volumes.

OS/VS2 System Programming Library: Data Management

"-... ./

When you attempt to rename a password-protected data set, the
operating system issues a message (IEC301A) to ask the operator or
remote console operator to verify the password. The data set will
be renamed only if the password supplied is associated with a
WRITE protection mode indicator. The chapter titled "Password
Protecting Your Data Sets" provides a description of the
protection mode indicator.

Maintaining the Volume Table of Contents

EXECUTING YOUR OWN CHANNEL PROGRAMS (EXCP)

The execute-channel-program (EXCP) macro instruction provides you
with device dependence in organizing data and controlling I/O
devices. This chapter contains a general description of the
function and application of the EXCP macro instruction,
accompanied by descriptions of specific control blocks and macro
instructions used with EXCP. Factors that affect the operation of
EXCP, such as device variations and program modification, are
also discussed.
Before reading this chapter, you should be familiar with system
functions and with the structure of control blocks, as well as
with the operational characteristics of the I/O devices required
by your channel programs. Operational characteristics of specific
I/O devices are contained in IBM pUblications for each device.
To understand this chapter, you need to understand the
information in these publications:
•

OS/VS2 MVS Data Management Services Guide, which explains the
standard procedures for I/O processing under the operating
system.

•

OS/VS-DOS/VS-VM/370 Assembler languagg, which contains the
information necessary to code programs in the assembler
language.

•

OS/VS2 MVS Data Management Macro Instructions, which
describes the system macro instructions that can be used in
programs coded in the assembler language.
OS/VS2 System Programming library: Debuqging Handbook, which
contains format and field descriptions of the system control
blocks referred to in this chapter.

The execute-channel-program (EXCP) macro instruction causes a
supervisor-call interruption to pass control to the 1/0
supervisor. (I/O supervisor is the name this chapter uses for two
VS2 components, the EXCP processor and the I/O supervisor. For
your purposes, it's unnecessary to understand how input/output
processing is divided between the two.) EXCP also provides the I/O
supervisor with control information regarding a channel program
to be executed. When an IBM access method is being used, an
access-method routine is responsible for issuing EXCP. If you are
not using an IBM access method, you must issue EXCP in your
program. (The EXCP macro instruction cannot be used to process
SYSIN, SYSOUT, or VSAM data sets.)
.
You issue EXCP primarily for I/O programming situations to which
the standard access methods do not apply. If you are writing your
own acces~ method, you must include EXCP for I/O operations. EXCP
must also be used for processing nonstandard labels, including
read i ng and wr it i ng label sand posi t ion i ng magnet i c tape volumes.
To issue EXCP, you must provide a channel program (a list of
channel command words) and several control blocks in your program
area. The I/O supervisor then schedules I/O requests for the
device you have specified, executes the specified I/O commands,
handles 110 interruptions, directs error recovery procedures, and
posts the results of the I/O requests.

EXECUTING CHANNEL PROGRAMS IN SYSTEM AND PROBLEM PROGRAMS
This section briefly explains the procedurp-s performed by the
system and the programmer when EXCP is issued by the routines of
IBM access methods. The additional procedures that you must

OS/VS2 System Programming Library: Data Management

perform when issuing EXCP yourself are then described by direct
comparison.

SYSTEM USE OF EXCP
When using an IBM access method to perform I/O operations, the
programmer is relieved of coding channel programs and
constructing the control blocks necessary for the execution of
channel programs. To permi t I/O operat ions to be handled by an
access method, the programmer 'need only issue the following macro
i nstruc,t:i ons:
•

A DCB macro instruction, which produces a data control block
(DCB) for the data set to be retrieved or stored.

•

An OPEN macro instruction that initializes the data control
block and produces a data extent block (DEB) for the data set.

•

A macro instruction (for example, GET, WRITE) that requests
I/O operat ions.

Access method routines will then:
1.

Create a channel program that contains channel commands for
the I/O operations on the appropriate device.

Construct an input/output block (lOB) that contains
information about the channel program.

Construct an event control block (ECB) that is later posted
with a completion code each time the channel program
terminates.

Issue an EXCP macro i nstructi on to pass the address of the lOB
to the routines that initiate and supervise the I/O
operations.

The I/O supervisor will then:
5.

Construct a request queue element (RQE) for scheduling the
request.

If the requestor is in a pageable address space, fix the
buffers so that they cannot be paged out and translate the
requestor's virtual channel program into a real channel
program.

Issue a start input/output (SIO) instruction to cause the
channel to executa the real channel program.

Process I/O interruptions and schedule error recovery
procedures when necessary.

Post a completion code in the event control block after the
channel program has been executed.

Note: If the requestor is in a nonpageable address space, he
provides a real channel program, so item 6 is not performed.

The programmer is not concerned with these procedures and does not
know the status of I/O operations until they are completed.
Device-dependent operations are limited to those provided by the
macro instructions of the particular access method selected.

USE OF EXCP IN PROBLEM PROGRAMS

To issue the EXCP macro instruction directly, you must perform the
procedures that the ~ccess methods perform, as summarized in
items 1 through 4 of the preceding discussion. You must, in
addition to constructing and opening the data control block with
the DCB and OPEN macro instructions, construct a channel program,
Executing Your Own Channel Programs (EXCP)

an input/output block, and an event control block before you can
issue EXCP. The I/O supervisor always handles items 5 through 9.
After issuing EXCP, you should issue a WAIT macro instruction,
specifying the address of the event control block, to determine
whether the channel program has terminated. If volume switching
is necessary, you must issue an EOV macro instruction. When
processing of the data set has been completed, you must issue a
CLOSE macro instruction to restore the data control block.
EXCP OPERATIONS IN A UONPAGEABlE ADDRESS SPACE

User-constructed channel programs for I/O operations in a
nonpageable address space are not translated. Because the address
space is nonpageable, any CCWs created by the user have correct
real data addresses. (Translation would only recreate the user's
channel program, so the CCWs are used directly.)
Modification of an active channel program by data read in or by
CPU instructions is legitimate in a nonpageable address space,
but not in a pageable address space.

EXCP REQUIREMENTS
This section describes
in order to issue EXCP.
construct directly, or
instructions, are also

the channel program that you must provide
The control blocks that you must either
cause to be constructed by use of macro
described.

CHANNEL PROGRAM
The channel program supplied by you and executed through EXCP is
composed of channel command words (CCWs) on doubleword
boundaries. Each channel command word specifies a ~ommand to be
executed and, for commands initiating data transfer, the area to
or from which'the data is to be transferred.
Channel command word formats used with specific I/O devices can be
found in IBM publications for those devices. All channel command
words described in these publications can be used, with the
exception of REWIND and UNLOAD (RUN).· In addition, both data
chaining and command chaining may be used.
Chajning is the suc~essive loading of channel command words into a
channel from contiguous doubleword locations in real storage.
Data chaining occurs when a·new channel command word loaded into
the channel defines a new storage area for the original I/O
operation. Command chaining occurs when the new channel command
word specifies a new I/O operation. For detailed information
about chaining, refer to IBM System/370 Principles of Operation.
To specify either data chaining or command chaining, you must set
appropriate bits in the channel command word, and indicate the
type of chaining in the input/output block. Both data and command
chaining should not be specified in the same channel command word;
if they are, data chaining takes precedence.
If a channel program includes a list of channel command words that
chain data for reading operations, no channel command word may
alter the contents of another channel command word in the same
list. (If such alteration were allowed, specifications could be
placed into a channel command word without being checked for
validity. If the specifications were incorrect, the error could
not be detected until the chain was completed. Data could be read
into incorrect locations and the system could not correct the
error.)

C'
46

OS/VS2 System Programming Library: Data Management

CONTROL BLOCKS
When using EXCP, you must be familiar with the function and
structure of the input/output block (lOB), the event control
block (ECB), the data control block (DCB), and the data extent
block (DEB). lOB and ECS fields are illustrated in the section
"Control Block Fields." DCB fields are illustrated in the section
"Macro Specifications for Use with EXCP." Brief descriptions of
these control blocks follow.

Input/Output Block (IOBl
The input/output block is used for communication between the
problem program and the system. It provides the addresses of other
control blocks, and maintains information about the channel
program, such as the type of chaining and the progress of I/O
operations. You must define the input/output block and specify
its address as the only parameter of the EXCP macro i nstructi on.

Event Control Block (ECS)
The event control block provides you with a completion code that
describes whether the channel program was completed with or
without error. A WAIT macro instruction, which can be used to
synchronize I/O operations with the problem program, must
identify the event control block. You must define the event
control block and specify its address in the input/output block.

Data Control Block (DCBl
The data control block provides the system with information about
the characteristics and processing requirements of a data set to
be read or written by the channel program. A data control block
must be produced by a DCB macro instruction that includes
parameters for EXCP. If appendages are not being used, a short DCB
is const~ucted. Such a DCB does not support reduced error
recovery. You specify the address of the data control block in the
input/output block.

Data Extent Block (DEBl
The data extent block contains one or more extent entries for the
associated data set, as well as other control information. An
extent defines all or part of the physical boundaries on an I/O
device occupied by, or reserved for, a particular data set. Each
extent entry contains the address of a unit control block (UCS),
wh i ch prov ides i nformat i on about the type and 1 ocat i on of an I/O
device. More than one extent entry can contain the same UCB
address. For all I/O devices supported by the operating system,
the data extent block is produced during execution of the OPEN
macro instruction for the data control block. The system places
the address of the data extent block into the data control block.

CHANNEL PROGRAM EXECUTION
This section explains how the system uses your channel program and
control blocks after you issue EXCP.

INITIATION OF THE CHANNEL PROGRAM

By issuing EXCP, you request the execution of the channel program
specified in the input/output block. The I/O supervisor validates
the request by checking certain fields of the control blocks
associated with this request. If the I/O supervisor detects
invalid information in a control block, it initiates abnormal
termination procedures.

Executing Your Own Channel Programs (EXCP)

The I/O supervisor gets:

•

The address of the data control block from the input/output
block

•

The address of the data extent block from the data control
block

•

The address of the unit control block from the data extent
block

It places the lOB, TCB, DEB, and UCB addresses and other
information about the channel program into an area called a
request queue element (RQE). (Unless you are provicling appendage
routines-described in the section "Appendages"-you should not
be concerned with the contents of RQEs.)
If you have provided a start I/O (SID) appendage, the I/O
superv i sor noto.J passes contro I to it. The return address from the
510 appendage determines whether the I/O supervisor must:
•

Execute the I/O operation normally, o~

•

Skip the I/O operation.

See "Appendages" in th~s chapter for a descriptio~ of the 510
appendage and its l~nkage to the I/O supervisor.
If yoJ are issuing EXCP from in a pageable address space, the
channel program you construct contains virtual addresses. Because
channels cannot use virtual addresses, the I/O supervisor must:
•

Translate your virtual channel program into one that uses
only real addresses.

•

Fix in real storage the pages used as I/O areas for the data
transfer operations specified in your channel program.

The I/O supervisor builds the translated (real) channel program
in a portion of real storage called the system queue area. If the
I/O device is other than a direct-access device or a magnetic tape
device, the I/O supervisor then places the address of the
translated channel program into the channel address word (CAW)
and issues a start input/output (510) instruction.
For direct-access devices, specify the seek address in the
input/output block. The I/O supervisor constructs a command chain
to issue the seek, set the file mask specified in the data extent
block, and pass control to your real channel program. If your
channel program begins with a locate-record command, the I/O
supervisor bu~lds a define-extent command and passes control to
your real channel program. (You cannot issue the initial seek, set
the file mask, or define extent yourself. The file mask is set to
prohibit seek-cylinder commands, or, if space is allocated by
tracks, seek-head commands. If the data set is open for INPUT or
RDBACK, write commands are also prohibited.)
Before issuing 510 for a magnetic tape device, the I/O supervisor
constructs a command chain to set the mode specified in the data
extent block and passes control to your real channel program. (You
cannot set the mode yourself.)

MODIFICATION OF A CHAHNEl PROGRAM DURING EXECUTION
Any problem program that modifies an active channel program with
CPU instructions or with data read in by an I/O operation must be
run in a nonpageable address space. It cannot run in a pageable
address space because of the channel program translation
performed by the I/O supervisor. (In a pageable address space, an
attempt to modify an a~tive channel program affects only the
virtual image of the channel program, not the real channel program
being executed by the channel.)
48

OS/VS2 System Programming library: Data Management

"'--. .../

A program of this type can be changed to run in a pageable address
space by issuing another EXCP macro for the modified portion of
the channel program.

COMPLETION OF EXECUTION
The system considers the channel program completed when it
receives an indication of a channel end condition in the channel
status word (C5W). Unless a channel-end or abnormal-end appendage
directs otherwise, the request queue element for the channel
program is made available, and a completion code is placed into
the event control block. The completion code indicates whether
errors are associ ated wi th channel end. If devi ce end occurs
simultaneously with channel end, errors associated with device
end (that is, unit exception or unit check) are also accounted
for.
If device end occurs after channel end, and an error is associated
with device end, the completion code in the event control block
does not indicate the error. However, the status of the unit and
channel is saved in the unit control block (UCB) for the device,
and the UCB is marked as intercepted. The input/output block for
the next request directed to the I/O device is also marked as
intercepted. The error is assumed to be permanent, and the
completion code in the event control block for the intercepted
request indicates interception. The DCBIFLGS field of the data
control block is also flagged to indicate a permanent error. Note
that if a write-tape-mark or erase-long-gap CCH is the last or
only CCW in your channel program, the I/O supervisor will not
attempt recovery procedures for device end errors. In these
circumstances, command chaining a NOP CCW to your write-tape-mark
or erase-long-gap CCW ensures initiation of device-end error
recovery procedures.

To be prepared for device-end errors, you should be familiar with
device characteristics that can cause such errors. After one of
your channel programs has terminated, you should not release
buffer space until you have determined that your next request for
the device has not been intercepted. You may reissue an
intercepted request.

INTERRUPTION HANDLING AND ERROR RECOVERY PROCEDURES
An I/O interruption allows the CPU to respond to signals from an
I/O device which indicate either termination of a phase of I/O
operations or external action on the device. A complete
explanat i on of I/O interrupt ions i s conta i ned i n IJltL.fu~. stem/ 3 70
Principles of Operation. For descriptions of interruptions by
specific devices, refer to IBM publications for each device.
If error conditions are associated with an interruption, the I/O
supervisor schedules the appropriate device-dependent error
routine. The channel is then restarted with another request that
is not related to the channel program in error. (The paragraphs
followi ng thi s one under thi s topi c di scuss "related" channel
programs.) If the error recovery procedures fail to correct the
error, the system places ones in the first two bit positions of
the IFLG5 field of the data control block. You are informed of the
error by an error code that the system puts in the event control
block.
If a channel program depends on the successful completion of a
prev i ous channel program-a s when one chatHlel program retri eves
data to be used in building another-the previous channel program
is called a "related" request. Such a request must be identified
to the I/O supervi sor. To fi nd out how, see "Input/Output Control
Block Fields" in the section "Control Block Fields."

Executing Your Own Channel Programs (EXCP)

If a permanent error occurs in the channel program of a related
request, the I/O supervisor does the following:

•

Removes the request queue elements for all dependent channel
programs from their queue and makes them'available.

•

Chains together the lOBs (input/output blocks) for the
dependent channel programs.

The lOB chain reflects the order in which request queue elements
are removed from their queue.
For all requests dependent on the channel program in error, the
system places completion codes into the event control blocks. The
DCBIFlGS field of the data control block is also flagged. Any
requests for a data control block with error flags are posted
complete without execution. To reissue requests dependent on the
channel program in error, you must reset the first two bits of the
DCBIFlGS field of the data control block to zeros. You then
reissue EXCP for each channel program desired.
3800 Enhancements, a cancel key or a system restart required
paper jam causes both a lost data indicator to be set in DCBIFLGS
and a lost page count and channel page identifier to, be stored in
the UCB extension. (See also OS/VSl System DElta Area~ and
Reference Manual for the IBM 3800 Printing Subsystem.)

t~ith

APPENDAGES
An appendage is a programmer-written routine that provides
additional control over I/O operations. By using appendages, you
can examine the status of I/O operations and determine the actions
to be taken for various conditions. An appendage may receive
control when one of the following occurs:
.

•

Start I/O

•

Program controlled interruption

•

End of extent

•

Channel end

•

Abnormal end

Appendages get control in supervisor state, receiving the
following pointers from the I/O supervisor:

•

Regi ster 1: Points to the request queue element for the
channel program.

•
•

Regi ster 6: Points to the seek address if control is given to
an end-of-extent appendage.

•

Regi ster 7: Points to the unit control block (UCB).

•

Register 14: Points to the location in the I/O supervisor to
which control is to b~ returned after execution of an
appendage. When returning control to the I/O supervisor, you
may use displacements from the return .address in register 14.
Allowable displacements are summarized in Figure 10 on page
52 and described later for each appendage.

OS/VS2 System Programming Library: Data Management

•

The processing done by appendages is subject to these
requirements and restrictions!
•

Register 9, if used, must be set to binary zeros before
control is returned to the system. All other registers,
except those indicated in the descriptions of each appendage,
must be saved and restored if they are used. Figure 10 on page
52 summarizes register conventions.

•

No SVC instructions or instructions that change the st~tus of
the system (for example, WTO, LPSW, or any privileged
instructions) can be issued.

•

loops that test for the completion of I/O operations must not
be used.

•

7
storage used by the supervisor or I/O supervisor- must
not be
altered.

The types of appendages are described in the following sections,
with explanations of when they are created, how they return
control to the system, and which registers they may use without
saving and restoring their contents.

START-I/O (SID) APPENDAGE
Unless an error procedure is in control, the I/O superv!sor passes
control to the SIO appendage just before the I/O superVlsor
translates your channel program. If I/O activity is not initiated
because of a busy condition and the I/O request has not been
translated, the appendage is not reentered before the SIO
instruction is issued.
Optional return vectors give the I/O requestor the following
choices:
Reg. 14 + 0
Normal return. Normal channel program translation and SID
instruction execution occur.
Reg. 14 + 4
Skip the I/O operation. The channel program is not posted
complete, but the request queue element is made available.
You may post the channel program as follows:
1.

Save necessary registers.

Put the address of the post routine--found at CVTOPT01
in the communications vector table--in register 15.

Place ECB address from the lOB in register 11.

Set the completion code in register 10. These are the
four bytes of an ECB.

Go to the post routine using BALR 14,15.

PROGRAM CONTROLLED INTERRUPTION (PCI) APPENDAGE
This appendage is entered at least once if the channel finds one
or more PCI bits on in a channel program, and may be entered as
many times as the channel finds PCI bits on. Before the appendage
is entered, the contents of the channel status word are placed in
the "channel status word" fi eld of the input/output block.
A PCI appendage will be reentered if an error recovery procedure
is retrying a channel program in which a PCI bit is on. The lOB
error flag is set when the error recovery procedure is in control
(IOBFLAGl = X'20'). (Refer to the topic "Block Multiplexor
Executing Your Own Channel Programs (EXCP)

/----.,

Appendages

Entry
Point

EOE

Reg 15

Reg 14 + 0
Reg 14 + 4
Reg 14 + 8

Return
Skip
Try Again

Reg. 10, 11, 12, and 13

SID

Reg 15

Reg 14 + 0
Reg 14 + 4

Normal
Skip

Reg. 10, 11, and 13

PGFX

Reg 15

Reg 14 + 0

Normal

Reg. 10, 11, and 13

PCI

Reg 15

Reg 14 + 0

Normal

Reg. 10, 11, 12, and 13

CHE

Reg 15

Reg
Reg
Reg
Reg

14
14
14
14

+
+
+
+

4
8
12

Normal
Skip
Re-EXCP
By-Pass

Reg. 10, 11, 12, and 13

ABE

Reg 15

Reg
Reg
Reg
Reg

14
14
14
14

+
+
+
+

4
8

Normal
Skip
Re-EXCP
By-Pass

Reg. 10, 11, 12, and 13

Returns

Available Work Reg

1 Certain register conventi ons for passing parameters from appendages to the I/O
supervisor must be followed. These conventions are described in the appendage
descriptions.

Figure 10. Entry Points, Returns, and Available Work Registers for Appendages

Channel Programming Notes" later in this chapter for special PCI
conditions encountered with command retry.)
To post the channel program from a PCI appendage, the procedure
described for the start-I/O appendage is used if the step is
running ADDRSPC=VIRT. If the step is running ADDRSPC=REAl or SVC
114(EXCPVR) was issued, the PCI appendage uses real storage
addresses and the following procedure is used to post the channel
program from the PCI appendage.
1.

Put the completion code in register 10.

Put X'80' in the high-order byte of register 11 and the
address of the ECB in the low-order bytes. This BR 14 must be
in storage which is addressable from any address space (for
example, CVTBRET).

Put X'80' in the high-order byte of register 12 and the
address of a BR 14 instruction in the low-order bytes.

Put the address of the ASCB in regi ster 13.

Put the requestor's key in register

The next two paragraphs describe how to obtain the ASCB
address and are followed by sample instructions to illustrate
the procedure.
Get the SRB address associated with the I/O operation from the
RQE field, RQESRB (the RQE address was in register 1 when the
appendage was given control). Get the 10S8 address from
SRBPARM. From that IOSB get the identifier field, IOSASID.
Multiply IOSASID by four.
Get the pointer to the ASVT (address space vector table) found
at CVTASVT. The address of the ASCB can be found in the ASVT,
using the field ASVTENTY-4 indexed by the value obtained from
the SRBPASID.

OS/VS2 System Programming library: Data Management

USING
L

USING
LH
USING
LH
SLA
L

USING
L

RQE,1
Y,RQESRB
SRBSECT,Y
Y,SRBPARM
rOSB,Y
Y,IOSASID
Y,2
X,16
CVT,X
X,CVTASVT
ASVT,X
13,ASVTENTY-4(Y)

Note: X and Yare work registers.
6.

Put the address of the post routine--found at CVTOPTOI in the
communications vector table--in register 15.

Go to the post routine using BALR 14,15. Upon return, only
registers 9 and 14 are valid.

This procedure can be used even if the PCI appendage uses virtual
storage addresses, but performance may be slightly slower. For
more information on the POST routine, see OS/VS2 System
Programming Library: Supervisor.
To return control to the I/O supervisor for normal interruption
processing, use the return address in register 14.

END-Of-EXTENT (EOE) APPENDAGE
This appendage is entered when the seek address specified in the
input/output block is outside the allocated extent limi.ts
indicated in the data extent block.
If you use the return address in register 14 to return control to
the system, the abnormal-end appendage is entered. An
end-of-extent error code (X' 42') is placed in the "ECB code" fi eld
of the input/output block for subsequent posting in the ECB.
You may use the following optional return addresses:
•

Contents of regi ster 14 plus 4--The channel program is posted
complete; its request element is returned to the available
queue.

•

Contents of register 14 plus 8--The request is tried again.

You may use registers 10 through 13 in an end-of-extent appendage
without saving and restoring their contents.

Note: If an end-of-cylinder or file-protect condition occurs, the

I/O supervisor updates the seek address to the next higher
cylinder or track address, and reexecutes the request. If the new
seek address is within the data set's extent, the request is
executed; if the new seek address is not within the data set's
extent, the end-of-extent appendage is entered. If you wish to try
the request in the next extent, you must move the new seek address
to the location pointed to by register 6.
If a file protect is caused by a full seek (command code=07)
embedded within a channel program, the request is flagged as a
permanent error, and the abnormal end appendage is entered.

CHANNEL-END (CHE) APPENDAGE

This appendage is entered when a channel end (CHE), unit exception
(UEX) with or without channel end, or channel end with wrong
length record (WLR) occurs without any other abnormal-end
conditions.

Executing Your Own Channel Programs CEXCP)

If you use the return address 1n register 14 to return control to
the I/O supervisor, the channel program is posted complete, and
its request element is made avai lable. In the case of un; t
exception or wrong length record, the error recovery procedure is
performed before the channel program is posted complete, and the
IOBEX flag (X'04') in IOBFlAGl is set on. The CSW status may be
obtained from the IOBCSW field.
If the appendage takes care of the wrong length record and/or unit
exception, it may turn off the IOBEX (X'04') flag in IOBFlAGl and
return normally. The event will then be posted complete
(completion code X'7F' under normal conditions, taken from the
high-order byte of the IOBECBCC field). If the appendage returns
normally without resetting the IOBEX flag to zero, the request
will be routed to the associated device error routine, and then
the abnormal-end appendage will be immediately entered with the
completion code in IOBECBCC set to X'41'.
You may use the following optional return addresses:
•

Contents of register 14 plus 4--The channel program is not
posted complete, but its request element is made available.
You may post the channel program by using the calling sequence
described under the start-I/O appendage. This is especially
useful if you wish to post an ECB other than the ECB in the
input/output block.

•

Contents of register 14 plus 8--Thechannel program ;s not
posted complete, and its request element is placed back on the
request queue so that the I/O operation can be retried. For
correct reexecution of the channel program, you must
reinitialize the IOBFlAG1, IOBFlAG2, and IOBFlAG3 fields of
the input/output block and set the "Error Counts" fi eld to
zero. As an added precaution, the IOBSEHSO, IOBSENS!, and
IOBCSW fields should be cleared.

•

Contents of register 14 plus 12--The channel program is not
posted complete, and its request element is not made
available~ (This return must be used if, and only if, the
appendage has passed the RQE to the exit effector for use in
scheduling an asynchronous routine.)

You may use registers 10 through 13 in a channel-end appendage
without saving and restoring their contents.

ABNORMAL-END (ABE) APPENDAGE
This appendage may be entered on abnormal conditions, such as:
unit check. unit exception, wrong length indication, program
check, protection check, channel data check, channel control
check, interface control check, chaining check, out-of-extent
error, and intercept condition (that is. device end error). It may
also be entered when an EXCP is issued for a request queue element
that has already been purged.

When this appendage is entered because of a unit exception
and/or wrong length record indication, IOBECBCC is set to
X'4l'. For further information on these conditions see
"Channel-End (CHE) Appendage."

When the appendage ;s entered because of an out-of-extent
error, the IOBECBCC is set to X'42'.

When this appendage is entered with IOBECBCC set to X'4B', it
is because of:
a.

The tape ERP

The tape ERP fi ndi n9 zeros in the command address fi eld of
the CSW.

encounte~ing

an unexpected load point, or

OS/VS2 System Programming Library: Data Management

When the appendage is first entered because of an intercept
condition, the IOBECBCC is set to X'7E'. If it is then
determined that the error condition is permanent, the
appendage will be entered a second time with the IOBECBCC set
to X'44'. The intercept condition signals that an error was
detected at device end after channel end on the previous
request.

When the appendage is entered because of an EXCP being issued
to an already purged request queue element, this request will
enter the abnormal end appendage with the IOBECBCC set to
X'48'. This applies only to related requests.

If the appendage is entered with IOBECBCC set to X'7F', it may
be because of a unit check, program check, protection check,
channel data check, channel control check, interface control
check, or chaining check. If the IOBECBCC is X'7F', it is the
first detection of an error in the associated channel
program. If the IOBEX flag (bit 5 of the IOBFLkG1) is on, the
JOBECBCC field will contain a 41, 42, 48, 4B, or 4F in
hexadecimal, indicating a permanent I/O error.

To determine if an error is permanent, you should check the
IOBECBCC field of the lOB. To determine the type of error, check
the channel status word and the sense information in the lOB.
However, when the 10BECBCC is X'42', X'48', or X'4F', these fields
are not appli·cable. For X'44' the CSW is applicable, but the sense
is valid only if the unit check bit is set.
If you use the return address in register 14 to return control to
the system, the channel program is posted complete, and its
request element is made available. You may use the following
optional return addresses:

•

Contents of register 14 plus 8--The channel program is not
posted complete, and its request element is placed back on the
request queue so that the request can be retried. For correct
reexecution of the channel program, you must reinitialize the
IOBFLAG1, IOBFLAG2, and IOBFLAG3 fields of the input/output
block and set the IOBERRCT field to zero. As an added
precaution, the IOBSENSO, IOBSENS1, and IOBCSW fields should
be cleared.

•

Contents of register 14 plus 12--The channel program is not
posted complete, and its request element is not made
available. (This return must be used if, and only if, the
appendage has passed the RQE to the exit effector for use in
scheduling an asynchronous routine.)

(

You may use registers 10 through 13 in an abnormal-end appendage
without saving and restoring their contents.

MAKING YOUR APPENDAGES PART OF THE SYSTEM

Before your appendages can be executed, they must become members
of either the SYSl.LPALIB or SYSl.SVCLIB data set. There are two
ways to put appendages into SYS1.LPALIB or SYS1.SVCLIB: they can
be included at system generation using the DATASET macro
instruction (a full explanation appears in OS/VS2 System
Programming library: System Gen~ration Reference, or they can be
link-edited into SYSl.LPALIB or SYSl.SVCLIB after the system has
been generated. Each appendage must have an 8-character member
name, the first six characters being IGG019, the last two being
anything in the range of characters from WA to Z9. Note, however,
if your program runs in a non-pageable address space and uses a
PCI appendage, the PCI appendage and an~ appendage that the PCI
appendage refers to cannot be placed in SYS1.LPALIB. Instead,
Executing Your Own Channel Programs (EXCP)

these appendages must be placed in either SYSl.SVClIB or the fixed
link pack area (lPA). For information on providing a list of
programs to be fixed in storage, see OS/VS2 System Programming
llbrary: Initlal;zation and Tuning Guide.

THE AUTHORIZED

APPENDAG~

LIST (IEAAPPOO)

If an "unauthorized" program opens a DCB to be used with an EXCP
macro instruction, the names of any appendages associated with
the DCB must be listed in the IEAAPPOO member of SYS1.PARMlIB. (An
"authorized" program is one that runs in a protection key less
than 8 or one that· has been marked as authorized by the Authorized
Program Facility.)
If your app~ndages were put in SYSl.lPAlIB or SYSl.SVClIB at
system generation, their names are automatically put in IEAAPPOO.
If your appendages were added to SYS1.lPAlIB or SYSI. SVClIB after
system generation, you can add IEAAPPOO to SYS1.PARMlIB and put
the names of the appendages in it in one job step with the
IEBUPDTE utility.
Here is an example of JCl statements and IEBUPDTE input that will
add IEAAPPOO to SYS1.PARMlIB and put the names of one EOE
appendage, two SIO appendages, two CHE appendages, and one ABE
appendage in IEAAPPOQ:
//

//SYSPRIHT
//SYSUT2
//SYSIH
./

EOEAPP
SIOAPP
CHEAPP
ABEAPP

WA,

EXEC
DD
DD
DD
ADD

lEBUPDTE
SYSOUT=A
DSH=SYSl.PARMlIB,DISP=OlD

*
HAME=IEAAPPOO,lIST=All

Xl,X2,
Z3,Z4,
Z2

Hote the following about the IEBUPDTE input:

•

The type of appendage is identified by six characters that
begin in column 1. EOEAPP identifies an EOE appendage, SIOAPP
an 510 appendage, CHEAPP a CHE appendage, and ABEAPP an ABE
appendage. (The PCI appendage identifier, PCIAPP, is not
shown because the example adds no PCI appendage name to
IEAAppoo.)

•

Only the last two characters in an appendage's name are
specified, beginning in column 8.

•

Each statement that identifies one or more appendage names
ends in a comma, except the last statement.

OS/VS2 System Programming library: Data Management

\.... _/

You can also use IEBUPDTE to add appendage names later or delete
appendage names. Here is an example of JCL statements and IEBUPDTE
input that adds the names of a PCI and ABE appendage to the
IEAAPPOO appendage list that was created in the preceding
example, and deletes the name of an SIO appendage from that list:
//

//SYSPRINT
//SYSUT2
//SYSIN
./

PCIAPP
EOEAPP
SIOAPP
CHEAPP
ABEAPP

YI,
WA,
Xl,
Z3,Z4,
Z2,Z4

EXEC
DD
DD
DD
REPl

IEBUPDTE
SYSOUT=A
DSH=SYSI.PARMLIB,DISP=OLD

*NAME=IEAPPOO,lIST=All

Note the following about the IEBUPDTE input:
•

The command to IEBUPDTE in this case is REPl (replace).

•

All the appendage names that are to remain in IEAAPPOO are
repeated.

•

IGGO 19Z4 is both a CHE and ABE appendage.

BLOCK MULTIPLEXOR CHANNEL PROGRAMMING NOTES
Command retry is a function of the block multiplexor channel
supporting the 2305, 3330/3333, 3340/3344, 3350, 3375, and 3380
direct-access devices. When the channel receives a retry request,
it repeats the execution of the channel command word (CCW)
requiring no additional input/output interrupts. For example, a
control unit may initiate a retry procedure to recover from a
transient error.
A command retry during the execution of a channel program may
cause any of the following conditions to be detected by the
initiating program:
•

Modifying CCWs: A CCW used in a channel program must not be
modified before the CCW operation has been successfully
completed. Without the command retry function, a command was
fetched only once from storage by a. channel. Therefore, a
program could determine through condition codes or program
controlled interruptions (PCI) that a CCW had been fetched
and accepted by the channel. This permitted the CCW to be
modified before reexecution. With the command retry function,
this cannot be done, since the channel will fetch the CCW from
storage again on a command retry sequence. In the case of data
chaining, the channel will retry commands starting with the
first CCW in the data chain.

•

Program Controlled Interrupts: A CCW containing a PCI flag
may cause multiple program controlled interruptions to occur.
This happens if the PCI-flagged CCW was retried during a
command retry procedure, and a PCI could be generated each
time the CCW is reexecuted.

•

Residual Count: If a channel program is prematurely
terminated during the retry of a command, the residual count
in the channel status word (CSW) will not necessarily
indicate how much storage was used. For example, if the
control unit detects a "l-Jrong length record" error condition,
an erroneous residual count is stored in the CSW until the
command retry is successful. When the retry is successful,
the residual in the CSW reflects the correct length of the
data transfer.

Executing Your Own Channel Programs (EXCP)

•

Command.Address: When data chaining with command retry, the
CSW may not indicate how many CCWs have been executed at the
time of a PCI. For example:

CCWI

Chnnnel Program

Read, data chain
Read, data chain
Read, data chain, PCI
Re~d, command chain

2
3
4

In this example, assume that the control unit signals command
retry on Read #3 and the CPU accepts the PCI after the channel
resets the command address to Read #1 becatise of command
retry. The CSW stored for the PCI will contain the command
address of Read #1, when actually the channel has progressed
to Read ff3.
•

Testing Buffer Contents on Data Read: Any program that tests
a buffer to determine when a CCW has been executed and
continues to execute based on this data may get incorrect
results if an error is detected and the CCW is retried.

MACRO SPECIFICATIONS FOR USE WITH EXCP
If you are using the EXCP macro instruction, you must also use
DCB, OPEN, CLOSE, and, in some cases, the EOV macro instruction.
The para~eters of these macro instructions and the EXCP macro
instructions are explained here. A di~gram of the data control
block is included with the description of the DCB macro
instruction.

DCB--DEFINE DATA CONTROL BLOCK FOR EXCP
The EXCP form of the DCB macro instruction produces a data control
block that can be used with the EXCP macro instruction. You must
issue a DCB macro instruction for each data set to be processed by
your channel programs. Notation conventions and format
illustrations of the DCB macro instruction are given in OS/VS2 MVS
Data Management Macro Instructions. DCB parameters that apply to
EXCP may be divided into four categories, depending on the
following portions of the data control block that are generated
when they are specified:
•

Foundation block. This portion is required and is always 12
bytes in length. You must specify two of the parameters in
thi s category.

•

EXCP interface. This portion is optional. If you specify any
parameter in this category, 20 bytes are generated.

•

Foundation block extension and common interface. This
portion is optional and is always 20 byte5 in length. If this
portion is generated, the device-dependent portion is also
generated.

•

Device dependent. This portion is optional and is generated
only if the foundation block extension and common interface
portion is generated. Its size ranges from 4 to 20 bytes,
depending on specifications in the DEVD parameter. However,
if you do not specify the DEVD parameter (and the foundation
extension and common interface portion is generated), the
maximum 20 bytes for this portion are generated.

Some of the procedures performed by the system when the data
control block is opened and closed (such as writing file marks for
output data sets on direct-access volumes) require information
from optional data control block fields. You should make sure that
the data control block is large enough to provide all information
necessary for the procedures you want the system to handle.

OS/VS2 System Programming library: Data Management

C.·.'

Figure 11 shows the relative position of each portion of an opened
data control block. The fields corresponding to each parameter.of
the DCB macro instruction are also designated, with the exception
of DDNAME, which is not included in a data control block that has
been opened. The fields identified in parentheses represent
system information that is not associated with parameters of the
DCB macro instruction.

Sources of information for data control block fields other than
the DCB macro instruction are data definition (DD) statements,
data set labels, and data control block modification routines.
You may use any of these sources to specify DCB parameters~
However, if a portion of the data control block is not generated
by the DCB macro instruction, the system does not accept
information intended for that portion from any alternative
source.

The device dependent portion of the data control
block varies in length and format according to
specifications in the DSORG and nEVD parameters.
Illustrations of this portion for each device
type are included in the description of the DEVD
parameter.
20

BUFHO

BUFCB

BUFL

DSORG

IOBAD
32 BFTEK,

36
40
44
48
52
56
60
64
68

BFALN
HIARC

EODAD

RECFM

EXLST

l
J
l

> Device
Dependent

> Common
Interface

Foundation
l > Block

(TIOT)

MACRF

(IFlGS)

(DES Address)

(OFLGS)

Reserved

OPTCD

Reserved

J
l

Extension

> Foundation
Block

Reserved
EOEA

PCIA

SIOA

CENDA

XEHDA

Reserved

> EXCP
Interface

Figure 11. Data Control Block Format for EXCP (After OPEN)

Executing Your Own Channel Programs (EXCP)

Foundation Block Parameters
OOHAME=symbol
The name of the data definition (DO) statement that
describes the data set to be processed. This parameter must
be given.
MACRF=(E)
The EXCP macro instruction is to be used in processing the
data set. This operand must be coded.
REPOS={yIH}
Magnetic tape volumes: This parameter indicates to the ODR
routine whether the user is keeping an accurate block count.
If the user is keeping an accurate block count, the DDR
routine can attempt to swap the volume. (You must maintain
the block count in the DCBBlKCT field.)
Y--The user ;s keeping an accurate block count and the DOR
routine can attempt to swap the volume.
H--The block count is unreliable and the DOR routine cannot
and will not attempt to swap the volume.
If the operand is omitted, H is assumed.

EXCP Interface Parameters
EOEA=symbol
2-byte identification of an EOE appendage that you have
entered into the lPA library.
PCIA=symbol
2-byte identification of a PCI appendage that you have
entered into the lPA library.
SIOA=symbol
2-b,yte i denti fi cat; on of a SIO appendage that you have
entered into thelPA library.
CEHDA=symbol
2-byte identification of a CHE appendage that you have
entered into the lPA library.
XEHDA=symbol
2-bYte identification of an ABE appendage that you have
entered into the lPA library.
OPTCD=Z
indicates that for magnetic tape (input only) a reduced
error recovery procedure (5 reads only) will occur when a
data check is encountered. It should be specified only when
the tape is known to contain errors and the application does
not require that all records be p~ocessed. Its proper use
would include error frequency analysis in the SYNAO routine.
Specification of this parameter will also cause generation
of a foundation block extension. This parameter is ignored
unless it was selected at system generation.
IMSK=value
Any specification indicates that the system will not use
IBM-supplied error routines.

Foundation Block Extension and Common Interface Parameters
EXlST=address
the address of an exit list that you have written for
exceptional conditions. The format of this exit list is
given in OS/VS2 MVS Data Management Services Guide.

OS/VS2. System Programming library: Data Management

EODAD=address
the address of your end-of-data set routine for input data
sets. If this routine is not available when it is required,
the task is abnormally terminated.
DSORG={PSIPoIDAIIS}
the data set organization (one of
code indicates that the format of
portion of the data control block
generated for a particular access

Code

DCB Format for

PS
PO
DA
IS

QSAM or BSAM
BPAM
BDAM
QISAM or BISAM

the following codes), Each
the device-dependent
is to be similar to that
method:

For direct-access devices, if you specify PS or PO, you must
maintain the following fields of the device-dependent
portion of the data control block so that the system can
write a file mark for output data sets:
•

The track balance (DCBTRBAL) field, which contains a
2-byte binary number that indicates the remaining number
of bytes on the current track.

•

The full disk address ~OCBFDAD) field, which indicates
the location of the current record. The address is in the
form MBBCCHHR.

These fields are written into the format-l OSCB and are used
by Open routines fpr staging MSS data sets. Staging is done
only up through the last cylinder specified by these fields
if the data set is reopened for OUTPUT, INOUT, DUTIN, OUTIHX
or EXTEND.
If you specify PO for a direct-access device, the OCBOIRCT
field will not be updated. Therefore, you should be careful
when using EXCP with the STOW macro.
IOBAD=address
the address of an input/output block (lOB). If a pointer to
the current lOB is not required, you may use this field for
any purpose.
The following parameters are not used by the EXCP routines. They
provide additional information that the system will store for
later use by access methods that read or update the data set.
RECFM=code
the record format of the data set. Record format codes are
given in OS/VS2 MVS Data Managem~nt Macro Instructions. When
writing a data set to be read later, the RECFM, LRECL, and
BLKSIZE should be specified to identify the data set
attributes. LRECL and BLKSIZE can only be specified in a DO
statement, since these fields do not exist in a DCB used by
EXCP.
BFTEK= {S IE}
the buffer technique, either simple or exchange.
BFALN={Flo}
the word boundary alignment of each buffer, either fullword
or doublel.Jord.
BUFL=length
the length in bytes of each buffer; the maximum length is

32,767.

BUFNO=number
the number of buffers assigned to the associated data set;
the maximum number is 255.
Executing Your Own Channel Programs (EXCP)

BUFCB=address
the address of a buffer pool control block, that is, the
8-byte field preceding the buffers in a buffer pool.

Device-Dependent Parameters
DEVD=code
the device on which the data set may reside. The codes are
listed in order of descending space requirements for the
data control block:

Code

Device

DA
TA
PT
PR
PC
RD

Direct access
Magnetic tape
Paper tape
Printer
Card punch
Card reader

Note: For MSS virtual volumes, DA should be used.
If you do not wish to select ~ specific device until job set-up
time, you should specify the device type requiring the largest
area.
The following diagrams illustrate the device-dependent portion of
the data control block for each combination of device type
specified in the DEVD parameter and data set organization
specified in the OSORG parameter. Fields that correspond to
device-dependent parameters in addition to DEVD are indicated by
the parameter name. For special services, you may have to maintain
the fields shown in parentheses. The special servic~s are
explained in the note that follows the diagram.
Device-dependent portion of data control block when DEVD=DA and
DSORG=PS:
5

Reserved

DCBFDAD

DCBDVTBl
16

DCBKEYlE

DCBDEVT

DCBTRBAl

For output data sets, the system uses the contents of the full
disk address (OCBFDAD) field plus one to write a file mark when
the data control block is closed, provided the track balance
(DCBTRBAL) field indicates that space is available. You must
maintain the contents of these two fields yourself if the system
is to write a file mark. OPEN will initialize DCBDVTBl and
DCBDEVT.

C'62

OS/VS2 System Programming library: Data Management

Dev; ce-dependent port; on of data control block when DEVD:::DA an.d
DSORG:::DA:

16
DCBKEYLE

Reserved

Device-dependent portion of data control block when DEVD:::TA and
DSORG:::PS:
12

DCBBLKCT

16
DCBTRTCH

117 Reserved

DCBDEN

Reserved

The system uses the contents of the block count (DCBBlKCT) field
to write the block count in trailer labels when the data control
block ;s closed or when the EOV macro instruction is issued. You
must maintain the contents of this field yourself if the system is
to have the correct block count. (Note: The I/O supervisor
increments this field by the contents of the IOBIHCAM field at the
completion of each I/O request.)
When ~sing EXCP to process a tape data set open at a checkpoint,
you m~st be careful to maintain the correct count; otherwise, the
system may position the data set incorrectly when restart occurs.
If REPOS:::Y, the count must be maintained by you for repositioning
during dynamic device reconfiguration.
Device-dependent portion of data control block when DEVD:::PT and
DSORG:::PS:

DCBCODE

Reserved

Device-dependent portion of data control block when OEVD:::PR and
DSORG:::PS:
16

DCBPRTSP

Reserved

Device-dependent portion of data control block when DEVO:::PC or RD
and DSORG:::PS:

DCBNODE,DCBSTACK

Reserved

The following DCB operands pertain to specific devices and may be
specified only when the DEVD parameter is specified.
KEYlEN:::length
for direct-access devices, the length in bytes of the key of
a physical record, with a maximum value of 255. When a block
is read or wri tten, the number of bytes transmi tted is the
key length plus the record length.

c
Executing Your Own Channel Programs (EXCP)

CODE=value
for paper tape, the code in which records are punched:

Value

Code

IBM BCD

F
B
C

A
T
N

Friden
Burroughs
National Cash Register
ASCII
Teletype l
no conversion (format-F records only)

If this parameter is omitted, N ;s assumed.
DEN=value
for magnetic tape, the tape recording density in bits per
inch:

Value:
7-track tape device

Density:
9-track tape device

o 200 (2400 only)

1 556

2 800
3 -

4 -

800(NRZI)
1600CPE)
6250CGCR)

NRZI--Non-return-to-zero change to ones recording
PE--phase encoded recording
GCR--group coded recording
If this parameter ;s omitted, the highest density available
on the device is assumed.
TRTCH=value
for 7-track magnetic tape, the tape recording technique:

vaiue

Tape Recording Technique

C
E

Data conversion feature is available.
Even parity is used. (If omitted, odd parity is
assumed.)
BCDlC to EBCDIC translation is required.

~---"

MODE=value
for a card reader or punch, the mode of operation. Either C
Ccolumn binary mode) or E (EBCDIC code) may be specified.
STACK=value
for a card punch or card reader, the stacker bin to receive
cards, ei ther 1 or 2.
PRTSP=value
for a printer, the line spacing, either 0, 1, 2, or 3.

~----

Trademark of Teletype Corporation
64

OS/VS2 System Programming library: Data Management

DSORG Parameter of the DCBD Macro
In addition to the operands described in OS/VS2 MVS Data
Macro Instructions, for the DSORG parameter of the
DCBD macro, you may specify the following operands.

Managem~nt

DSORG=
XA

specifies a DCB with the EXCP interface section
(including appendage names)

specifies a DCB with the foundation block extension

OPEN--INITIALIZE DATA CONTROL BLOCK
The OPEN macro instruction initializes one or more data control
blocks so that their associated data sets can be processed. You
must issue OPEN for all data control blocks that are to be used by
your channel programs. (A dummy data set may not be opened for
EXCP.) Some of the procedures performed when OPEN is executed are:
•

Reading in the JFCB (job file control block)--unless the
TYPE=J option of the macro instruction was coded.

•

Construction of the data extent block (DEB).

•

Transfer of information from the JFCB and data set labels to
the DCB.

•

Verification or creation of standard labels.

•

Tape positioning.

•

Loading of your appendage routines.

The parameters of the OPEN macro instruction are:
[symbol]

OPEN

(deb address
,[(options)], ••• l

deb address--A-type address or (2-12)
the address of the data control block to be initialized.
(More than one data control block may be specified.)
optionl
the intended method of I/O processing of the data set. You
may specify this parameter as either INPUT, ROBACK, OUTPUT,
or EXTEND. For each of these, label processing when OPEN is
executed is as follows:
INPUT
ROBACK
OUTPUT
EXTEND

Header labels are verified.
Trailer labels are verified.
Header labels are created.
Header labels are created.

If this parameter is omitted, INPUT is assumed.
option2
the volume disposition that is to be provided when volume
switching occurs. The operand values and meanings are as
follows:

REREAD

Reposition the volume to process the data set again.

LEAVE

No additional positioning is performed at
end-of-yolume processing.

DISP

Specifies that a tape volume is to be disposed of in
the manner implied by the DD statement associated
with the data set. Direct-access volume positioning
Executing Your Own Channel Programs (EXCP)

and disposition are not affected by this parameter
of the OPEN macro instruction. There are several
dispositions that can be specified in the OISP
parameter of the DD statement:
DISP=PASS, DELETE, KEEP, CATLG, or UNCATlG. Only
DISP=PASS has significance at the time an
end-of-volume condition is encountered. The
end-of-volume condition may result from t~e issuance
of an FEOV macro instruction or may be the result of
reaching the end of a volume.
If OISP=PASS was coded in the DO statement, the tape
will be spaced forward to the logical end of the data
set on the current volume.
If a OISP option other than OISP=PASS is coded on the
DD statement, the action taken when an end-of-volume
condition occurs depends (1) on how many tape units
are allocated to the data set and (2) on how many
volumes are specified for the data set in the DD
statement. This is determined by the UNIT= and
VOLUME= operands of the DD statement associated with
the data set. If the number of volumes is greater
than the number of un; ts allocated, the current
volume will be rewound and unloaded. If the number
of volumes is less than or equal to the number of
units, the current volume is merely rewound.
If you intend to process a multivolume direct data set. you must
cause Open routines to build a data extent block for each volume
and issue mount messag~s for them. This can be done by reading in
the JFCB with a RDJFCB macro instruction and ope.ning each volume
of the data set. The following piece of code illustrates the
procedure:

OS/VS2 System Programming Library: Data Management

*
*
*
*
*
*lOOP
*
*
*
*
*
*
*
*

RDJFCB
SR

DCBl
R3,R3

R3,JFCBNVOL

R4,DCBl

R5,l

EQU
STH

* . . JFCBVLSQ
R5

READS IN THE JFCB
CLEARS REG 3; IT WIll
HOLD COUNT OF VOlS TO
BE OPENED
PUTS tt OF VOlS
IN REG 3
R4 POINTS TO DCB FOR
VOL TO BE OPENED
PUTS SEQUENCE tt OF
FIRST VOL TO BE
OPENED IN REG 5

PUTS SEQ ff OF VOL
TO BE OPENED WHERE
OPEN RTNS LOOK
OPEN (CR4),OUTPUT) . . TYPE=J
OPENS ONE Val
NOTE THAT THE TYPE=J OPTION OF THE MACRO MUS~ BE USED
R4,DCB2-DCBl(R4) INCREMENT REG 4 TO
lA
POINT TO THE DCB FOR
THE NEXT VOL TO BE
OPENED
R5,1(RS)
lA
INCREMENT TO SEQ I OF
HEXT VOL TO BE OPENED
BCT
R3,lOOP
lOOP UNTIL ALL VOlS
OPEN

JFCB

DS
ORG
JFCBVlSQ DS

Cl176
JFCB+70
H

JFCB READ IN HERE
SEQ I OF Val TO BE
OPENED

*
ORG
JFCB+117
JFCBNVOl OS
Fll
I OF VOLS IN DATA SET
ORG
* MAPPING MACRO IEFJFCBN MAY ALSO BE USED
DCBl DCB DDNAME=SYSUTl,MACRF=(E),EXlST=EXITS,DSORG=PS
DCB2 DCB DDNAME=SYSUT1,MACRF=(E),EXlST=EXITS,DSORG=PS
DCB3 DCB DDNAME=SYSUTl,MACRF=(E),EXlST=EXITS,DSORG=PS
DCB4 DCB DDNAME=SYSUTl,MACRF=(E),EXlST=EXITS,DSORG=PS
DCB5 DCB DDNAME=SYSUTl,MACRF=(E),EXlST=EXITS,DSORG=PS
* THIS PROCEDURE WORKS FOR 5 VOlS OR lESS; THE JFCB
* EXTENSION, WHICH IDENTIFIES ADDITIONAL VOlS, CAN'T
* BE READ IN
EXITS
OS
OF
DC
X'87',AL3(JFCB) 87 IDENTIFIES THIS AS
THE EXIT LIST ENTRY
THAT SHOWS WHERE JFCB
WILL BE READ IN
Use of the RDJFCB macro instruction and the OPEN macro instruction
with the TYPE=J opt ion is expla i ned ; n deta i I i n "Readi ng and
Modifying a Job File Control Block."
EXCP--EXECUTE CHANNEL PROGRAM
The EXCP macro instruction requests the initiation of the I/O
operations of a channel program. You must issue EXCP whenever you
want to execute one of your channel programs. The format of the
EXCP macro instruction is:
[.symbol]

EXCP

job-address

Executing Your Own Channel Programs (EXCP)

i ob-address.-A-type address, (2-12), or (1)
the address of the input/output block of the channel program
to be executed.

/-"

ATLAS--ASSIGNING AN ALTERNATE TRACK AND COPYING DATA FROM THE DEFECTIVE TRACK
A program that uses the EXCP macro instruction for input and
output and is APF authorized may use the ATLAS macro instruction,
during the execution of the program, to obtain an alternate track
and to copy a defective track onto the alternate track. With the
use of ATLAS, the program can recover from permanent (hard) errors
encountered in the execution of the following types of I/O
commands:
•

Search ID.

•

Write. (The error condition must be confirmed during the
execution of the channel program by a CCW that checks the data
written.)

•

Read count. Errors in the CCHHR part of the count area can be
recovered from unless the record is the home address or record
zero. Errors in the KDD part of the count area cannot be
recovered from unless·the user has identified the defective
record.

Note: ATLAS may be used for all direct-a6cess devices with the
exception of MSS volumes (3330V).

Your DCB must include the DCBRECFM field, and the field must show
whether the data set is in the track overflow format. If it is,
recovery from errors in last records on tracks depends on your
identifying the track overflow record segments.
Recovery takes the form of obtaining an alternate good track and
copying the defective track onto the good alternate one. Unless a
reexecution of the channel program by ATLAS can correct the
defect, the user should examine, and if necessary replace,
defective records in a subsequent job if the data set is to be
processed again.
The format is:
[symbol]

ATLAS

PARMADR=CaddressJ
[,CHANPRG=CRINRJl
[, CNTPTR=e.eTF1]
[,WRITS=(YESINOJl

PARMA DR

Address of a parameter address list of the following format:
0

/1'

Parameter list

/1'

lOB for the channel program that encountered
the error

/1'

Count area field

05/'52 System Programming library: Data Management

/'--~

The count area field contains the CCHHRKDD of a defective
record or the CCHH of a track that is to be copied.

address--A-type address, (2-12), or (1)

CHANPRG=(R(NR}

specTfies whether the channel program that encountered the
error can be executed again.

Channel program may be executed again by ATLAS. Before
permitting reexecution of the channel program by ATLAS,
you must reset the error indications of the previous
execution fields in the DCBIFLGS. (See thR example of
the use of ATLAS below.)

Channel program may not be executed again.

If this parameter is omitted, R is assumed.

CNTPTR

specifies whether the count area field contains a full count
area (CCHHRKDD) or a partial count area (CCHH).
P

Part of the count area (the CCHH address of the track to
be copi ed).

Full count area (CCHHRKDD count of the record that was
found defective).

If this parameter is omitted, P is assumed.

WRITS

track' overflow segment identification.
If your data set is in the track overflow format, this
identification determines recovery from errors in last
records on tracks.

(

VES

1ft his i s the las t r e cor don the t r a c k, i t i s a s e gme n t
other than the last of a track overflow record.

If thi sis the last record on the track, it is the last
or only segment of a track overflow record.

If this parameter is omitted, it is assumed that it cannot be
establ i shed L··lhether a last record is a segment of an overflow
record.
Using ATLAS
If a channel program encounters a unit check condition (shown in
the CSW) in its execution, the I/O supervisor program will place
the sense bytes in the lOB. ATLAS can be used to recover from
sense conditions shown by the following bit settings:
10BSENSO

X' 08'

Data check (except in the count area)

10BSENS!

X'80'

Data check in the count area

10BSENS!

X'02'

Missing address marker (see the following
for combinations of this bit setting
which ATLAS cannot handle).

However, defects in the home address record or the record zero
record cannot be recovered from through the use of ATLAS. These
conditions are shown by:
10BSENS! X'02' and IOBSENSO X'O!'--homa address defect.
10BSENS! X'OA'----record zero defect, or, home address cannot
be- located.

Executing Your Own Channel Programs (EXCP)

Also, before using ATLAS, you must
follows:
NI

DCBIFLGS,X'3F'

r~set

error indications as

Reset the DCBIFLGS error indications.

The ATLAS program wi 11 attempt to fi nd a good al ternate track and
will attempt to copy the defective track onto the good track,
including all error conditions in either key or data areas. The
error conditions may be rectified by reexecutlng the channel
program or through the use of the IEHATLAS utility program in a
subsequent step.

Example: The following illustrates the use of the ATLAS macro
instruction.

EXCP
WAIT
TM
BO

*
*

TM
BZ
TM
BO
TM
BO
TM

*
*
*

BO
ATLASGO EQU

*
*
*
*

NI
ATLAS

MYIOB
ECB=MYECB
MYECB,X'7F'
NEXT

TEST FOR 1/0 ERROR
NO, SUCCESSFUL, GO TO
ANOTHER ROUTINE
IOBCSW+3,X'02'
UNIT CHECK
OTHER
NO, DO OTHER ERROR
PROCESSING
IOBSENSO,X'08'
DATA CHECK
YES, VALID ERROR
ATLASGO
IOBSENS1,X'80'
DATA CHECK IN COUNT
ATLASGO
YES, VALID ERROR
IOBSENS1,X'OA'
MISSING ADDRESS
MARKER AND NO RECORD
FOUND
YES, ATLAS CANNOT
OTHER
HANDLE ERRORi DO
OTHER ERROR'
PROCESSING.
NO, MISSING ADDRESS
MARKER ONLY.
DCBIFLGS,X'3F'
RESET ERROR
INDICATORS
PARMADR=THERE,CHANPRG=R

/,'"
"-

Operation of the ATLAS Program
The ATLAS program (SVC 86):
•

Establ i shes the ava i labi 1 i ty and address of the next
alternate track from the format-4 DSCB of the VTOC.

•

Brings all count fields from the defective track into storage
to establish the description of the track.

•

Initializes the alternate track. (Writes the home address and
record zero.)

•

Brings the key and data areas of each record into storage, one
at a time, and combines them with their new count area to
write the complete record onto the alternate track.

•

When the copying is finished, chains the alternate to the
defective track and updates the VTOC.

Control is returned to your program at the next executable
instruction following th~ ATLAS macro instruction. The success of
the ATLAS macro instruction can be determined by examining the
contents of register 15, which will contain one of the return
codes described below. If register 15 contains 0,36,40, or 44,
the contents of register 0 may be significant.

OS/VS2 System Programming Library: Data Management

C""

Decimal
Return
Code

Meaning

Successful completion. Key and data areas have been
copied from the defective track onto a good alternate
one. The only error encountered was in the record
identified by the user's eCHHRKDD value.
If the channel program is reexecutable, it has been
successfully reexecuted.

This device type does not have alternate tracks that
can be assigned by programming.

All alternate tracks for the device have been assigned.

A request for storage (GETMAIN macro instruction) could
not be satisfied.

All attempts to initialize and transfer data to an
alternate track failed. The number of attempts made is
equal to lOY. of the assigned alternates for the device.

The type of error shown by the sense byte cannot be
handled through the use of the ATLAS ma6ro instruction.
The, condition is other than a data check (in the count
or data areas) or a missing address marker.

The format-4 DSeB of the VTOe cannot be read; therefore
alternate track information is not available to ATLAS.

The record specified by the user was the format-4 DSCB
and it could not be read.

An error found in count area of last record on the track
cannot be handled because last-record-on-track
identification is not supplied.

An error was encountered when reading or writing the
home address record or record zero. Ho error recovery
has taken place. If register 0 contains X'OI 00 00 00',
the defect is in record zero.

Successful completion. Key and data areas have been
copied from the defective track onto a good alternate
one. However, the alternate track may have records with
defective key or data areas. Register 0 identifies the
first three found defective as follows:

n RR R
n--The number of record numbers that follow (0, 1, 2, or
3) .

R--The number of the record found defective but copied
anyhol.J .
If the channel program is reexecutable, it has been
successfully reexecuted.
44

Error/Errors encountered and no alternate track has
been assigned. The return parameter register (register
0) will contain the R of a maximum of three error
records.
Error conditions that return this code are:
1.

C,
--

ATLAS received an error indication for a record
with a data length in the count field of zero.
Recovery was not possible because a distinction
cannot be made between an EOF record and an invalid
data length.
Executing Your Own Channel Programs (EXCP)

An error occurred while reading the count field of
a record and the KDD (key length-data length) was
found to be defective.

More than three records on the specified track
contained errors in their count fields.

No errors found on the track, no alternate assigned.
ATLAS wi 11 not assign an alternate unless a track has at
least one defective record.

1/0 error in reexecuting user's channel program. A good
alternate is chained to the defective track and data
has been transferred. The user's control blocks will
give indication of the error condition causing failure
in reexecution of the channel program.

The DCB reflects a track overflow data set, but the UCB
device type shows that the device does not support
track overflow.

The CCHH of the user-specified count area is not within
the extents of the data set.

The device is an MSS virtual device, which is not
supported.

EOV-END OF VOLUt1E

The EOV macro instruction identifies end-of-volume and
end-of-data set conditions. For an end-of-volume condition, EOV
causes switching of volumes and verification or creation of
standard labels. For an end-of-data set condition, EOV causes
your end-of-data set routine to be entered. Before processing
trailer labels on a tape input data set, you must decrement the
DCBBLKCT field. You issue EOV if switching of magnetic tape or
direct-access volumes is necessary, or if secondary allocation is
to be performed for a direct-access data set opened for output.
For magnetic tape, you must issue EOV when either a tapemark is
read or a reflective spot is written over. In these cases, bit
settings in the l-byte DCBOFLGS field of the data control block
determine the action to be taken when EOV is executed. Before
issuing EOV for magnetic tape, you must make sure that appropriate
bits are set in DCBOFLGS. Bit positions 2,3,6, and 7 of DCBOFLGS
are used only by the system; you are concerned with bit positions
0,1,4, and 5. The use of these DCBOFLGS bit positions is as
follows:
Bi t 0

Bi t 1
Bi t 4

Bit 5

set to 1 indicates that a write command was executed and that
a tape mark is to be written.
indicates that a backward read was the last 1/0 operation.
indicates that data sets of unlike attributes are to be
concatenated.
indicates that a tape mark has been read.

If bits 0 and 5 of DCBOFLGS are both off when EOV is executed, the
tape is spaced past a tapemark, and standard labels, if present,
are verified on both the old and new volumes. The direction of
spacing depends on bit 1. If bit 1 is off, the tape is spaced
forward; if bit 1 is on, the tape is backspaced.
If bit 0 is on when EOV is executed, a tapemark is written
immediately following the last data record of the data set.

OS/VS2 System Programming Library: Data Management

"--

... /

Standard labels, if specified, are created on the old and the new
volume.
After issuing EOV for sequentiallY organized output data sets on
direct-access volumes, you can determine whether additional space
was obtained on the same or a different volume. You do this by
examining the data extent block (DEB) and the unit control block
(UCB). If neither the address of the UCB, as shown in the DEB, nor
the volume serial number, as shown in the UCB, have changed,
additional space was obtained on the same volume. Otherwise,
space was obtained on a different volume.
The only parameter of the EOV macro instruction is:

I [symbol] I EOV

I dcb address

dcb address--A-type address, (2-12), or (1)
the address of the data control block that is opened for the
data set. If this parameter is specified as (1), register 1
must contain this address.

Note: To learn how the system disposes of a tape volume when an

EOV macro is issued, see the description of the DISP parameter in
"OPEN--Initialize Data Control Block."

CLOSE--RESTORE DATA CONTROL BLOCK
The CLOSE macro instruction restores one or more data control
blocks so that processing of their associated data sets can be
terminated. You must issue CLOSE for all data control blocks that
were used by your channel programs. Some of the procedures
performed when CLOSE is executed are:

•

Release of data extent block (DEB)

•

Removal of information transferred to data control block
fields when OPEN was executed

•

Verification or creation of standard labels

•

Volume disposition

•

Release of programmer-written appendage routines

When CLOSE is issued for data sets on magnetic tape volumes,
labels are processed according to bit settings in the DCBOFlGS
field of the data control block. Before issuing CLOSE for magnetic
tape, you must set the appropriate bits in DCBOFLGS. The DCBOFLGS
bit positions that you are concerned with are listed in the EOV
macro instruction description.
For information about the forms of the CLOSE macro and their
parameters, refer to OS/VS2 MVS Data Management Macro
Instructions.

CONTROL BLOCK FIELDS
The fields of the input/output block, event control block, and
data extent block are illustrated and explained here; the data
control block fields have been described with the parameters of
the DCB macro instruction in the section "EXCP Programming
Specifications."

INPUT/OUTPUT BLOCK FIELDS
The input/output block (lOB) is not automaticallY constructed by
a macro instruction; it must be defined as a series of constants
and must be on a fullword boundary. For unit-record and tape
Executing Your Own Channel Programs (EXCP)

devices, the lOB is 32 bytes in length. For direct-access,
teleprocessing, and graphic devices, 8 additional bytes must be
provided. You may want to use the system mapping macro IEZIOB,
which expands into a DSECT, to help in constructing an lOB.
In Figure 12 the diagonally-ruled areas indicate fields in which
you must specify information; the hyphen areas indicate fields in
which you may specify information. The other fields are used by
the system and must be defined as all zeros. You may not place
information into these fields, but you may examine them.

0(0)/1
1/1//////IIOBFLAG11/1//////1

---

1/1-

4(4)

IOBFLAG2

IOBSEHSO

10BSENS!

//////////////////////////////////////

IOBECBCC

/////////////// IOBECBPT /////////////
//////////////////////////////////////

8(8)
IOBFLAG3
IOBCSW

12(C)

16(10)

//////////////////////////////////////

IOBSIOCC

/////////////// IOBSTART /////////////

All
Devices

//////////////////////////////////////

20(14)

//////////////////////////////////////

Reserved

/////////////// IOBDCBPT /////////////
//////////////////////////////////////

24(18)
IOBRESTR

IOBRESTR+l

28(lC) /////////////////////////
//////////// IOBIHCAM //////////

IOBERRCT

////////////////////////////////

32(20) //////////
IOBSEEK / /
/ (first byte, M)

///

--,

> Direct Access,' Teleprocessing, and

Graphic Devices

33(21) ///////////////////////////////
//////////////////////////////////////
//////////////////////////////////////

///
////
IOBSEEK
/////////////////////// (second through eighth bytes, ////
///////////////////////
////
BBCCHHR)
/////////////////////////////////////////////////// 39(27)

l
J

Direct
Access
> storage
Devices
(DASD)

Figure 12. Input/Output Block Format

C'
74

OS/VS2 System Programming Library: Data Management

IOBFLAG1 (1 byte)
You must set bit positions 0, 1, and 6. One-bits in positions
o and 1 indicate data chaining and comm~nd chaining,
respectively. (If both data chaining and command chaining
are specified, the system does not use error recovery
routines except for the 2671, 1052, 2150 and the
direct-access devices.) A one-bit in position 6 indicates
that the channel program is not a 'related' request; that is,
the channel program is not related to any other channel
program. If you intend to issue an EXCP macro with a BSAM,
QSAM, or BPAM data control block, you may want to turn on bit
7 to prevent ~ccess-method appendages from processing the
I/O request.
IOBFlAG2 (1 byte)
If you set bit 6 in the IOBFlAGl field to zero, then bits 2
and 3 in this field must be set to:
•

00, if any channel program or appendage associated with
a related request might modify this lOB or channel
program.

•

01, if the conditions requiring a 00 setting don't
apply, but the CHE or ABE appendage might retry this
channel progr~m if it completes normally. or with the
unit-exception or wrong-length-record bits on in the
CSw.

10 in all other cases.

The three combi nat ions of bi ts 2 and 3 represent the three
kinds of related requests, known as type 1 (00), type 2 (01),
and type 3 (10). The type you u S9 determ i nes ho,,", much the I/O
supervisor can overlap the processing of related requests.
Type 3 allows the greatest overlap, normally making it
possible to quickly reuse a device after a channel-end
interruption. (Related requests that were executed on an
earlier system are executed as type-l requests if not
modified.)
IOBSENSO and IOBSENS1 (2 bytes)
are placed into the input/output block by the system when a
unit check occurs. On occasion the system is unable to obtain
any sense bytes because of unit checks when sense commands
are issued. In this case the system simulates sense bytes by
moving X'lOFE' to IOBSENSO and IOBSENS1.
IOBECBCC (1 byte)
the first byte of the completion code for the channel
program. The system places this code in the high-order byte
of the event control block when the channel program is posted
complete. The completion codes and their meanings are listed
under "Event Control Block Fi eIds."
IOBECBPT (3 bytes)
the address of the 4-byte event control block that you have
provided.
IOBFlAG3 (1 byte)
is used only by the system.
IOBCSW (7 bytes)
the low-order seven bytes of the channel status word, which
are placed into this field each time a channel-end or PCI
interruption occurs.
IOBSIOCC (1 byte)
in bits 0 and 1, the instruction-length code; in bits 2 and
3, the start I/O (SID) condition code for the SID instruction
the system issues to start the channel program; and in bits 4
through 7, the program mask.

Executing Your Own Channel Programs (EXCP)

IOBSTART (3 bytes)
the starting address of the channel program to be executed.
Reserved (1 byte)
used only by the system.

\"---./

IOBDCBPT (3 bytes)
the address of the data control block of the data set to be
read or written by the channel program.
IOBRESTR (1 byte)
used by the system for volume repositioning in error
recovery procedures.
IOBRESTR+l (3 bytes)
used by the system, if a related channel program is
permanently in error, to chain together lOBs that represent
dependent channel programs. To learn more about the
conditions under which the chain is built, refer to
"Interruption Handling and Error Recovery Procedures."
IOBINCAM (2 bytes)
for magnetic tape, the amount by which the block count
(DCBBLKCT) field in the device-dependent portion of the data
control block is to be incremented. You may alter these bytes
at any time. For forward operations, these bytes should
contain a binary positive integer (usually +1); for backward
operations, they should contain a binary negative integer.
When these bytes are not used, all zeros must be specified.
Reserved (2 bytes)
used only by the system.
IOBSEEK (first byte, M)
for direct-access devices, the extent entry in the data
extent block that is associated with the channel program (0
indicates the first entry; 1 indicates the second, etc.).
For, teleprocessing and graphic devices, it contains the UCB
index.
IOBSEEK (last 7 bytes, BBCCHHR)
for direct-access devices, the seek address for your channel
program.

EVENT CONTROL BLOCK FIELDS
You must define an event control block (ECB) as a 4-byte area on a
fullword boundary. When the channel program has been completed,
the input/output supervisor places a completion code containing
status information into the ECB (Figure 13 on page 77). Before
examining this information, you must test for the setting of the
"complete bit." If the complete bit is not on, and your problem
program cannot perform other useful operations, you should issue
a WAIT macro instruction that specifies the event control block.
Under no circumstances should you construct a program loop that
tests for the complete bit.

DATA EXTENT BLOCK FIELDS
The data extent block (DEB) is constructed by the system when an
OPEN macro instruction is issued for the data control block. You
may not modify the fields of the DEB, but you may examine them.
The DEB format and field descriptions are contained in OS/VS2
System Programming library: Debugging Handbook.

c
76

OS/VS2 System Programming Library: Data Management

(

WAIT bit=O

COMPLETE bit=!

Remainder of completion code

bit

Wait bit
A one-bit in this position indicates that the WAIT macro instruction has been
issued, but the channel program has not been completed.
Complete bi t
A one-bit in this position indicates that the channel program has been completed;
if it has not been completed, a zero-bit is in this position.
Completion code
This code, which includes the wait and complete bits, may be one of the following
4-byte hexadecimal expressions:

Code

Meaning

7FOOOOOO

The channel program has terminated without error.

41000000

The channel program has terminated

42000000

The channel program has terminated because a
address has been violated.

44000000

The channel program has been intercepted because of a permanent error
associated with a device end for the previous request. You may reissue
the EXCP macro instruction to restart the channel program.

48000000

The request queue element for a channel program has been made available
after it has been purged.

4BOOOOOO

One of the following errors occurred during error recovery processing
for a tape device.

4FOOOOOO

~ith

a permanent error.
direct-acces~

•

The CSW command address in the lOB is zeros.

•

An unexpected load point was encountered.

extent

Error recovery routines have been entered because of direct-access
error but are unable to read the home address or record O.

Figure 13. Event Cnntrol Block After Posting of Completion Code (EXCP)

EXECUTING FIXED CHANNEL PROGRAMS IN REAL STORAGE (EXCPVRl
The EXCPVR macro instruction provides you with the same functions
as the EXCP macro instruction (that is, a device-dependent means
of performing input/output operations). In addition, it allows
your program to improve the efficiency of the I/O operations in a
paging environment by translating its own virtual channel
programs t~ real channel programs. Authorized programs are
allowed to execute in a pageable area and provide the I/O
supervisor with real channel programs. This eliminates the
translation of channel programs by the I/O supervisor. The
program issuing the EXCPVR must remain in authorized state until
the completion of the channel programs.

Problem programs are authorized to use the EXCPVR macro
instruction under th~ authorized program facility (APF). A
description of how to authorize a program can be found in the
OS/VS2 System Programming Library: Supervisor.

Executing Your Own Channel Programs (EXCP)

[symbol]

EXCPVR

; ob-address "

iob-address--A-type address, (2-12), or (1) "
the address of the input/output block of the channel program
to be executed.
To use EXCPVR, you must do all the things you would do to execute
an EXCP request; in addition you must:
1.

Code PGFX=YES in the DCB associated with the EXCPVR requests
and provide a page-fix (PGFX) appendage by specifying
SIOA=symbol in the DCB.

Fix the data area that contains your channel program, the data
areas that are referred to by your channel program, your PCI
appendage (if your program can generate program controlled
interrupts), and any area referred to by your PCI appendage.
You fix these data areas by building a list that contains
these addresses of these areas. You should build the list in
your PGFX appendage.

Determine whether the data areas in virtual storage specified
in the address fi elds of your CCWs cross page boundari es. If
they do, you must build an indirect address list (IDAL) and
put the address of the IDAL in the affected CCW.

Translate the addresses in your CCWs from virtual to real
addresses.

Items ,3 and 4 must be done in your start-I/O (SIO) appendage. A
description of the SIO appendage is presented in the section
titled "Appendages."
There is no advantage in using EXCPVR with a virtual input/output
(VIO) data set. If EXCPVR is used, then virtual addresses must be
used in the CCWs and indirect address lists (IDALs) are not
allowed.
BUILDING THE" LIST OF DATA AREAS TO BE FIXED

The I/O supervisor expects programs using the EXCPVR macro
instruction to pass a list of data areas to be fixed. This list is
to be built in the PGFX appendage, as described below.
The data areas you must fix in real storage (if not already fixed
in real storage) are:
1.

The channel program. If the channel program ;s already ;n a .
fixed subpool, it does not have to be fixed.

The data areas from which your channel program will be writing
and to which your channel program will be reading. If the data
areas are already in a fixed subpool, they do not have to be
fixed.

The PCI appendage.

Any control blocks or other areas referred to in your PCI
appendage (as well as, the DEB). Control blocks can be divided
into two groups--system control blocks and user control
blocks. The control blocks can be fixed or not fixed. If the
control blocks are not fixed, they must be fixed in real
storage.

You need not fix areas that have already been fixed, such as the
modules that reside in the fixed link pack area (LPA).

OS/VS2 System Programming Library: Data Management

PAGE FIX (PGFX) AND START-I/O (SIO) APPENDAGE
This appendage comprises two essentially independent appendages.
The complete appendage can be viewed as a reenterable subroutine
having two entry points, one for the SID appendage and one for the
PGFX appendage.
The SID entry point ;s located at offset 0 in the subroutine; any
other location in the appendage may be branched to from this entry
point. The entry point of the PGFX appendage is at offset +4 ;n
the SID subroutine, which is set in register 15 as the entry point
of the PGFX appendage.

Page Fix (PGFX) APpendage: The purpose of this appendage is to

list all of the areas that must be fixed to prevent paging
exceptions during the execution of the current I/O request. This
appendage may be entered more than once. However, each time it ;s
entered, it must create the same list of areas to be fixed. The
appendage may use the 16-word save area pointed to by register 13.
Registers 10, 11, and 13 may be used as work registers.

PAGE FIX LIST PROCESSING
Each page fix entry placed in the list by the appendage must have
the following doubleword format:
X'OO'

Starting virtual
address of area
to be fixed

X'OO'

Ending virtual
address of
area to be fixed
+ 1

<--1 byte--> <----3 bytes----> <--1 byte--> <----3 bytes---->

On return from your PGFX appendage to the I/O supervisor (via the
return address provided in register 14), register 10 must point to
the first page-fix entry and register 11 must contain the number
of page-fix entries in the work area. The I/O supervisor then
fixes the pages corresponding to the areas listed by the PGFX
appendage. The pages remain fixed until the associated I/O
request terminates.
.
If either the channel end appendage or the abnormal end appendage
returns via the return address in register 14 plus 8, the PGFX
appendage is not normally reentered. Instead, the SIO appendage
is entered, and the page fix list built by the PGFX appendage is
still active. However, the PGFX appendage is entered after either
the channel end appendage or the.abnormal end appendage returns
via the return address in register 14 plus 8 when a PURGE macro
has been issued (for instance, when a memory swap has occurred).
In this case, when I/O is restored, the PGFX appendage is entered.

Note: The page-fix list must be in page-fixed storage.
SIO APpendage
If you are using EXCPVR to execute your channel program, you must
translate the virtual addresses in the operands of your channel
program to real addresses. This should be done in your SIO
appendage. If indirect addressing is requi~ed, the SIO appendage
should also build the IDALs and turn on the IDAL indicators in the
associated CCWs.

Translating virtual Addresses and Building the IDAL: You can use

the load real address (LRA) instruction to convert the virtual
addresses in the channel program to real addresses. You must also
check the areas whose addresses appear in bits 8-31 of your CCWs
to determine whether the data areas cross page boundaries. If they
Executing Your Own Channel Programs (EXCP)

do, you must provide an entry in the ·indirect address list (IDAl)
for each page boundary crossed. The channel uses the IDAL to
identify the address at which it will continue reading or writing
when a page boundary is crossed during a read or write operation.
If each buffer page is accessed, causing the page to be paged in,
the LRA instruction can be used to translate the virtual addresses
in the IDAl to real addresses. The IDAl must contain real
addresses when it is processed by the channel.
CCl..!

Command
Code

Address of the
IDAL
7 8

//////////
//////////

31 32

39 40
IDAL

Byte
Count

47 48

~------------>r-------------------------------'

First Indirect Address

Second Indirect Address
8

Subsequent Indirect
Address

Notes:
1.

You must put one entry in the IDAl for each 2K-byte page
boundary your data area crosses.

If the CCW has an IDAL address rather than a data address, b,t
37 mu~t be set to signal this to the channel.

The maximum number of entries needed in the IDAl is determined
from the count in the CCW as follows:
Number of IDAl entries=«CCW count - 1)/2048) + 1.
(Round up division to next highest integer if remainder is not
zer'o. )

The number of IDAL entries required ultimately depends on whether
the data crosses a 2K-byte page boundary. For example, if your
data is 800 bytes long and does not cross a 2K-byte page boundary,
no IDAL entries are required. If your data crosses a 2K-byte page
boundary, then two IDAl entries are required. If your data is 3000
bytes long, at least two IDAl entries are required. If your data
crosses two 2K-byte page boundaries, three IDAl entries are
required.
The first indirect address is the real address of the first byte
of the data area. The second and subsequent indirect addresses are
the real addresses of the second and subsequent pages (on a page
boundary of 2048 or X'800') of the data area.
For example, if the data area real address is X'707FF' and the
byte count is X'802' the IDAl would contain the following real
addresses (assuming the real addresses are contiguous, which may
not al",ays be the case):
707FF
70800
71000

OS/VS2 System

Programmi~g

Library: Data Management

r''''-..... "

If the data area real address is X'707FF' and the byte count i5
X'800' the IDAL would contain the following addres5Qs:
707FF
70800

c
Executing Your Own Channel Programs (EXCP)

USING XOAP TO READ AND WRITE TO DIRECT-ACCESS DEVICES

The execute direct-access program (XDAP) macro instruction
provides you with a means of readingl verifying, or updating
blocks on direct-access volumes without using an access method
and without writing your own channel program. This chapter
expl~ins what the XDAP macro instruction does and how you can use
it. The control block generated when XDAP is issued and the macro
instruction used with XDAP are also discussed.
Since most of the specifications for XDAP are similar to those for
the execute channel program (EXCP) macro instructionl you should
be familiar with the "Executing Your Own Channel Programs (EXCP)"
chapter of this publicationl as well as with the information
contained in PS/VS2 MVS Q~ta Management Services Guide, which
provides how-to information for using the access method routines
of the system control program.

INTRODUCTION
Execute direct-access program (XDAP) is a macro instruction that
you may use to readl verify, or update a block on a direct-access
volume. If you are not using the standard IBM data access methods,
you can, by issuing XDAP, generate the control information and
channel program necessary for reading or updating the records of a
data set. (XDAP cannot be used, however, to read, verify, or
update a SYSIN, SYSOUT, or VSAM data set.)
You cannot use XDAP to add blocks to a data set, but you can use it
to change the keys of existing blocks. Any block configuration and
any data set organization can be read or updated.
Although the use of XDAP requires less storage than do the
standard access methods, it does not provide many of the control
program services that are included in the access methods. For
example, when XDAP is issued, the system does not block or deblock
records and does not verify block length.
To issue XDAP, you must provide the actual device address of the
track containing the block to be processed. You must also provide
either the block identification or the key of th~ block, and
specify \'Jhich of these is to be used to locate the block. If a
block is located by identification, both the key and data portions
of the block may be read or updated. If a block is located by key,
only the data portion can be processed.
For additional control over I/O operations, you may write
appendages, which must be entered into the lPA library.
Descriptions of these routines and their coding specifications
are contained in the "Executing Your Own Channel Programs (EXCP)"
section of this publication.

XDAP REQUIREMENTS
When using the XDAP macro instruction, you must, somewhere in your
program, code a DCB macro instruction, which produces a data
control block (DCB) for the data set to be read or updated. You
must also code an OPEN macro instructionl which initializes the
data control block and produces a data extent block (DEB). The
OPEN macro instruction must be executed before any XDAP macro
instructions are executed.

OS/VS2 System Programming library: Data Management

When the XDAP macro instruction is assembled, a control block and
executable code are generated. This control block may be
logically divided into three sections:

C,'

•

An event control block (ECB), which is supplied with a
completion code each time the direct-access channel program
i s term i nated.

•

An input/output block (lOB), which contains information about
the direct-access channel program.

•

A direct-access channel program, which consists of three or
four channel command words (CCWs). The type of channel
program generated depends on specifications in the parameters
of the XDAP macro instruction. Whe.n executed, it locates a
block by ei ther its actual address or its key and reads,
updates, or verifies the block.

When the channel program has terminated, a completion code is
placed into the event control block. After issuing XDAP, you
should therefore issue a WAIT macro instruction, specifying the
address of the event control block, to regain control when the
direct-access program has terminated. If volume switching is
necessary, you must issue an EOV macro instruction. When
processing of the data set has been completed, you 'must issue a
CLOSE macro instruction to restore the data control block.

MACRO SPECIFICATIONS FOR USE WITH XDAP
When you are using the XDAP macro instruction, you must also code
DCB, OPEN, CLOSE, and, in some cases, the EOV macro instructions.
The parameters of the XDAP macro instruction are listed and
described here. For the other required macro instructions,
special requirements or options are explained, but you should
refer to "Macro Specifications for Use with EXCP" for listings of
their parameters.

DCB--DEFINE DATA CONTROL BLOCK
You must issue a DCB macro instruction for each data set to be
read, updated, or verified by the direct-access channel program.
Refer to "DCB-Defi ne Data Control Block for EXCP" to learn whi ch
macro instruction parameters to code.
OPEt~-INITIALIZE

DATA CONTROL BLOCK
The OPEN macro instruction initializes one or more data control
blocks so that their associated data sets can be processed. Yc '
must issue OPEN for all data control blocks that are to be used by
the direct-access program. Some of the procedures performed when
OPEN is executed are:

•

Construction of data extent block (DEB).

•

Transfer of information from DD statements and data set
labels to the data control block.

•

Verification or creation of standard labels.

•

loading of programmer-written appendage routines.

The two parameters of the OPEN macro instruction are the
addressees) of the'data control block(s) to be initialized, and
the intended method of I/O processing of the data set. The method
of processing may be specified as INPUT, OUTPUT, EXTEND; however,
if nothing is specified, INPUT is assumed.

Using XDAP to Read and Write to Direct-Access Devices

XDAP--EXECUTE DIRECT-ACCESS PROGRAM
The XDAP macro instruction produces the XDAP control block (that
is, the ECB, lOB, and channel program) and executes the
direct-access channel program. The format of the XDAP macro
instruction is:

XDAP

[s~mbol]

ecb-symbol
,h~

,dcb-addr
,area-addr
,1.~.!l9.ih-va I ue
,l(key-addr,keylength-value)]
,blkref-addr
, [sector-addr]
[, UF=tE'lI}l-

ecb-symbol--symbol or (2-12)
the symbolic name to be assigned to the XDAP event control
block. Registers can be used only with MF=E .

.bm.g-{RIIRKIHIIUKIVIIVKl

the type of 1/0 operation intended for the data set and the
method by which blocks of the data set are to be located. One
of the combinations shown must be coded in this field.
The codes and thei r meani ngs are:
R

Read a block.

Update a block.

Verify that the device is able to read the contents of a
block, but do not transfer data.

Locate a block by identification. (The key portion, if
present, and the data portion of the block are read,
updated, or verified.)

Locate a block by key. (Only the data portion of the
block is read, updated, or verified.) If you code this
value, you must code the k~y-addr key-length-value
operands.

dcb-addr--A-type address or (2-12)
the address of the data control block for the data set. If
this data control block is also being used by a sequential
access method (BSAM, BPAM, QSAM), you must reassemble the
XDAP macro instruction. Other~Jise, sequential access method
appendages will be called at the conclusion of the XDAP
channel program.
area-addr--A-type address or (2-12)
the address of an input or output area for a block of the
data set.
length-value.--absexp or (2-12)
the number of bytes to be transferred to or from the input or
output area. If blocks are to be located by identification
and the data set contains keys, the value must include the
length of the key. The maximum number of bytes transferred ;s
32,767.

key-addr--RX-type address or (2-12)
when blocks are to be located by key, the address of a
virtual. storage field that contains the key of the block to
be read, updated, or verified.
keylength-value--absexp or (2-12)
when blocks are to be located by key, the length of the key.
The maximum length is 255 bytes.
84

OS/VS2 System Programming Library: Data Management

C
-

address or (2-12)
the address of a field in virtual storage containing the
actual device address of the track containing the block to be
located. The actual address of a block is in the form
f~tIBBCCHHR, where Hindi cates whi ch extent entry in the data
extent block is associated with the direct-access program;
BB is not used but must be zero; CC indicates the cylinder
address; HH indicates the actual track address; and R
indicates the block identification. R is not used when
blocks are to be located by key. (See "Conversion of Relative
Block Address to Actual Devi ce Address" later in thi s
chapter for more detailed information.)

blkref-addr-RX-t~'pe

sector-addr-RX-t)'pe address or (2-12)
the address of a 1-byte field containing a sector value. The
sector-address parameter is used for rotational position
sensing (RPS) devices only. The parameter is optional, but
its use will improve channel performance. When the parameter
is coded, a set-sector CCW (using the sector value indicated
by the data address field) precedes the Search-ID-Equal
command in the channel program. The sector-address parameter
is ignored if the type parameter is coded as RK, WK, or VK.
If a sector-address is specified in the execute form of the
macro, then a sector-address, not necessarily the same, must
be specified in the list form. The sector address in the
executable form will be used.

Note: No validity check is made on either the address or the

sector value when the XDAP macro is issued. However, a unit
check/command reject interruption will occur during
channel-program execution if the sector value is invalid for
the device or if the sector-addr operand is used when
accessing a device LoJithout RPS. (See "Obtaining Sector
Number of a Block on a Device with the RPS Feature~ later in
this chapter for more detailed information.)

(

MF=

HF=E

HF=L

you may use the L-form of the XDAP macro instruction for a
macro expansion consisting of only a parameter list, or the
E-form for a macro expansion consisting of only executable
instructions.
The first operand (gcb-symbol) is required and may be coded
as a symbo I or suppl i ed in reg i sters 2 through 12. The iY..E.,g,
deb-addr, area-addr, and length-value operands may be
supplied in either the L- or E-form. The blkref-addr operand
may be supplied in the E-form or moved into the rOBSEEK field
by you. The sector-addr is optional; it may be coded either
in both the L- and E~form or in neither.
The fi rst two operands (eeb-symbol and .:b!£g) are requi red
and must be coded as symbols. If you choose to code
length-value or kevlength-value, they must be absolute
expressions. Other operands, if coded, must be A-type
addresses. (blkref-addr is ignored if coded.)

The dcb-addr, area-addr, blkref-addr, and sector-value operands
may be coded as RX-type addresses or supplied in regisiers 2
through 12. The l..'lll9th-va I ue and keyl ength-va lll~ operands can be
specified as an absolute expression or decimal integer or
supplied in registers 2 through 12.

Using XDAP to Read and Write to Direct-Access Devices

EOV--END OF VOLUME
The EOV macro instruction identifies end-of-volume and
end-of~data set conditions. For an end-of-volume condition, EOV
causes switching of volumes and verification ~r creation of
standard labels. For an end-of-data set condition, EOV causes
your end-of-data set routine to be entered. When using XOAP, you
issue EOV if switching of direct-access volumes is necessary, or
if secondary allocation is to be performed for a direct-access
dataset opened for output.
The only parameter of the EOV macro instruction is the address of
the data control block of the data set.

CLOSE--RESTORE DATA CONTROL BLOCK
The CLOSE macro instruction restores one or more data control
blocks 50 that processing of their associated data sets can be
terminated. You must issue CLOSE for all data sets that were used
by the direct-access channel program. Some of the procedures
performed when CLOSE is executed are:
•

Release of data extent block (DEB)

•

Removal of information transferred to data control block
fields when OPEN was executed

•

Verification or creation of standard labels

•

Release of programmer-written appendage routines

The CLOSE macro instruction must identify the address of at least
one data control block to be restored, and may specify other
options. See OS/VS2 MVS Data Management Macro Instr~ctions to
le~rn what these options are and how they are specified.

CONtROL BLOCKS USED WITH XDAP
The three control blocks generated during execution of the XOAP
macro instruction are described here.

EVENT CONTROL BLOCK
The event control block (ECB) begins on a fullword boundary and
occupies the first 4 bytes of the XOAP control block. Each time
the direct-access channel program terminates, the I/O supervisor
placQs a completion code containing status information into the
event control block (Figure 14 on page 87). Before examining this
information, you must wait for the completion of the channel
pro~ram by issuing a WAIT macro instruction that specifies the
addre~s of the event control block.

INPUT/OUTPUT BLOCK
The input/output block (lOB) is 40 bytes ;n length and immediately
follows the event control block. The "Control Block Fields"
section in the EXCP section of this publication contains a diagram
of the input/output block (Figure 14 on page 87). You may wish to
examine the IOBSENSO, IOBSENSl, and IOBCSW fields if the ECB is
posted with X'4l'.

c
86

OS/VS2 System Programmi ng Library: Data Management

~JAIT

COMPLETE bit

bi t

bit

l~a

Completion code
2

it bit
A one bit in this position indicates that the direct-access channel program has
not b~en completed.

Complete bit
A one bit in this position indicates that the channel program has been completed;
if it has not been completed, a zero bit is in this position.
Completion code
This code, which includes the wait and complete bits, may be one of the following
4-byte h~xadecimal expressions:

Code

Interpretation

7FOOOOOO

Direct-access program has terminated without error.

41000000

Direct-access program has terminated with permanent error.

42000000

Direct-access progr.am has terminated because a direct-access extent
address has been violated.

4FOOOOOO

Error recovery routines have been entered because of direct-access
error but are unable to read home address or record o.

Figure 14. Event Control Block After Posting of Completion Code (XDAP)

DIRECT-ACCESS CHANNEL PROGRAM
The direct-access channel program is 24 bytes in length (except
when set sector is used for RPS devices) and immediately follows
the input/output block. Depending on the type of I/O operation
specified in the XDAP macro instruction, one of four channel
programs may be generated. The three channel command words for
each of the four possible channel programs are shown in Figure 15.

Type of I/O Operation

CCW

Command Code

Read by identification

1
2

Search ID Equal
Transfer in Channel
Read Key and Data

Verify by identificationl
Read by key
Verify by keyl
Write by identification

3
1

2
3
1

2
3

Write by key

2
3

Search Key Equal
Transfer in Channel
Read Data
Search ID Equal
Transfer in Channel
Write Key and Data
Search Key Equal
Transfer in Channel
Write Data

lFor verifying operations, the third CCW is flagged to suppress
the transfer of information to virtual storage.

Figure 15. The XDAP Channel Programs

Using XDAP to Read and Write to Direct-Access Devices

When a sector address is speci fi ed wi th an RI, VI, or l~I
operat ion, the channel program i s 32 bytes in length. Each of the
channel programs in Figure 15 on page 87 would be, in this case,
preceded by a set sector command.

~
L

CONVERSION OF RELATIVE TRACK ADDRESS TO ACTUAL DEVICE ADDRESS
To issue XDAP, you must provide the actual device address of the
track containing the block to be processed. If you know only the
relative track address, you can convert it to the actual address
by using a resident system routine. The entry point to this
conversion routine is labeled IECPCNVT. The address of the entry
point (CVTPCNVT) is in the communication vector table (CVT). The
address of the CVT is in location 16. (For the displacements and
descriptions of the CVT fields, see OS/VS2 System Programming
library: Debugging Handbook.)
The conversion routine does all its work in general registers. You
must load registers 0, 1, 2, 14, and 15 with input to the routine.
Regi ster usage is as follows:

Use

Must be loaded wi th a 4-byte value of the form TTRN,
where TT is the number of the track relative to the
beginning of the data set, R is the identification of
the block on that track, and H is the concatenation
number of a BPAM data set. (0 indicates the first data
set in the concatenation, an unconcatenated BPAM data
set, or a non-BPAM data set.)

Must be loaded with the address of the data extent block
(DEB) of the data set.

Must be loaded with the address of an 8-byte area that
is to receive the actual address of the block to be
processed. The converted address is of the form
MBBCCHHR, where M indicates which extent entry in the
data extent block is associated with the direct-access
program (0 indicates the first extent, 1 indicates the
second, etc.); BB is two bytes of zeros; CC ;s the
cylinder address; HHis the actual track address; and R
is the block number.

3-8

Are not used by the conversion routine.

9-13

Are used by the conversion routine and are not
restored.

Must be loaded with the address to which control is to
be returned after execution of the ~onversion routine.

Is used by the conversi on routi ne as a base regi ster and
must be loaded with the address at which the conversion
routine is to receive control.

When control is returned to your program, register 15 will contain
one of the following return codes:

Code

Meaning

Successful conversion.

The relative block address converts to an actual device
address outside the extents defined in the DEB.

OS/VS2 System Programming library: Data Management

('
1"-. .. '

CONVERSION OF ACTUAL DEVICE ADDRESS TO RELATIVE TRACK ADDRESS

To get the relative track address when you know the actual device
address, you can use the conversion routine labeled IECPRlTV. The
address of the entry point (CVTPRlTV) is in the communication
vector table (CVT). The address of the CVT is in location 16.
The conversion routine does all its work in general registers. You
must load registers 1, 2, 14, and 15 with input to the routine.
Register usage is as follows:

Use

Will be loaded with the resulting TTRO to be passed back
to the caller.

Must be loaded with the address of the data extent block
(DEB) of the data set.

Must be loaded wi th the address of an 8-byte area
containing the actual address to be converted to a TTR.
The actual address is of the form MBBCCHHR.

3-8

Are not used by the conversi on routi nee

9-13

Are used by the conversi on rout; ne and are not
restored.

Must be loaded wi th the address to whi ch control is to
be returned after execution of the conversion routine.

Is used by the conversion routine as a base regi ster and
must be loaded with the address at which the conversion
routine is to receive control.

OBTAINING SECTOR NUMBER OF A BLOCK ON A DEVICE '-11TH THE RPS FEATURE

To obtain the performance improvement given by rotational
position sensing, you should specify the sector-addr parameter in
the XDAP, macro. For programs that can be used with both RPS and
non-RPS devices, the UCBRPS bit (bit 3 at an offset of 17 bytes
into the UCB) should be tested to determine whether the device has
rotational position sensing. If the UCBRPS bit is off, a channel
program wi th a "set sector" command must not be issued to the
device.
The sector-addr parameter on the XDAP macro specifies the address
of a one byte field in your region. You must store the sector
number of the block to be located in this field. You can obtain
the sector number of the block by using a resident conversion
routine, IECOSCRI. The address of this routine is in field
CVTOSCRI of the CVT, and the address of the CVT is in location 16.
-The routine should be invoked via a BAlR 14,15 instruction. If you
are passing the track balance to the routine, you invoke the
routine using a BAL 14,8(15),

Using XDAP to Read and Write to Direct-Access Devices

For RPS devices, the conversion routine does all its.~ork in
general registers. You must load re~isters 0, 2, 14, and 15 with
input to the routine. Register usage is as follows:

Use

For fixed, standard blocks or fixed, unblocked records
not in a partitioned data set: Register 0 must be
loaded wi th a 4-byte value in the form XXKR, where XX
is a 2-byte field containing the physical block size,
K is a 1-byte field containing the key length, and R 1S
a I-byte field containing the number of the record for
which a sector value is desired. The high-order bit of
register 0 must be turned off (set to 0) to indicate
fixed-length records.
Passing the track balance: Register 0 must be loaded
with the 4-byte value of the track balance of the
record preceding the required record.
For all other cases: Register 0 must be loaded with a
4-byte value in the form BBIR, where BB is the total
number of key and data bytes on ~he track up to, but
not including, the target record; I is a I-byte key
indicator (1 for keyed records, 0 for records without
keys); and R is a I-byte field containing the number of
the record for which a sector value is desired. The
high-order bit of register 0 must be turned on (set to
1) to indicate variable-length records.

Not used by the sector-convert routine.

Must be loaded with a 4-byte field in which the first
byte is the UCB device type code for the device
(obtainable from UCB+I9), and the remaining three
bytes are the address of a I-byte area that is to
re~eive the sector value.

3-8,12,13

Not used.

9-11

Used by the convert routi ne and are not saved or
restored.

Must be loaded wi th the address to whi.ch control is to
be returned after execution of the sector conversion
routine.

Used by the conversi on routi ne as a base regi ster and
must be loaded with the address of the entry point to
the conversion routine.

c
90

OS/VS2 System Programming library: Data Management

PASSWORD PROTECTING YOUR DATA SETS

OS/VS password protection does not apply to VSAM data sets.
Information about VSAM data set protection is in OS/VS Virtual
Storage Access Method (VSAM) Programmer's Guide and OS/VS2 Access
Method Services. Refer to OS/VS2 MVS Resource Access Control
Facility CRACF): General Information Manual for informati.on on
RACF and its relationship to password protection. To use the data
set protection feature of the operating system, you must create
and maintain a PASSWORD data set consisting of records that
associate the names of the protected data sets with the password
assigned to each data set. There are four ways to maintain the
PASSWORD data set:
•

You can write your own routines.

•

You can use the PROTECT macro instruction.

•

You can use the utility control statements of the IEHPROGM
utility program.

•

For OS/VS2 systems wi th TSO, you can use the TSO PROTECT
command.

This chapter discusses only the first two of the four ways--it
provides technical detail about the PASSWORD data set that is
necessary for writing your own routines, and it describes how to
use the PROTECT macro instruction. (The last two of the four ways
are discussed in other publications, as indicated in the list of
publications below.)
Before using the information in this chapter, you should be
familiar with information in several related publications. The
following publications are recommended:
•

OS/VS2 MVS Data Management Services Guide, which contains a
general description of the data set protection feature.

•

OS/VS Message Library: VS2 System Messages, which contains a
description of the operator messages and replies associated
with the data set protection feature for VS2.

•

OS/VS2 JCl, which contains a description of the data
definition (DO) statement parameter used to indicate that a
data set is to be password protected.

•

OS/VS2 DADSM logic, which contains a description of the
PASSWORD data set record format.

•

OS/VS2 MVS Utilities, which contains a description of how to
maintain the PASSWORD data set using the utility control
statements of the IEHPROGM utility program.

•

OS/VS2 T50 Command language Reference, which describes the
use of the TSO PROTECT command.

INTRODUCTION

In addition to the usual label protection that prevents opening of
a data set without the correct data set name, the operating system
provides data set security options that prevent unauthorized
access to confidential data. Password protection prevents ~ccess
to data sets, until a correct password is entered by the system
operator, or, for TSO, ~ remote terminal operator.

Password Protecting Your Data Sets

The follol.oJing are the types of access allowed to password
protected data sets:
•

Pl~READ/PWWRITE-A

password is required to read or write.

•

PWREAD/NOWRITE-A password is required to read. Writing is
not allOl.Jed.

•

NOPWREAD/PWWRITE--Reading;s allowed without a password.
password is required to write.

To prepare for use of the data set protection feature of the
operating system, you place a sequential data set, named
PASSWORD, on the system residence volume. This data set must
contain at least one record for each data set placed under
protection. In turn, each record contains a data set name, a
password for that data set, a counter field, a protection mode
indicator, and a field for recording any information you desire to
log. On the system residence volume, these records are formatted
as a "key area" (data set name and password) and a "data area"
(counter field, protection mode indicator, and logging field).
The data set is searched on the "key area."

Note: The area allocated to the data set should not have been
previously used for a PASSWORD data set as this may cause
unpredictable results when adding records to the data set.

You can write routines to create and maintain the PASSWORD data
set. If you use the PROTECT macro instruction to maintain the
PASSWORD data set, see the section in this chapter called "Using
the PROTECT Macro Instruction to Maintain the PASSWORD Data Set."
If you use the IEHPROGM utility program to maintain the PASSWORD
data set, see OS/VS2 Utilities. These routines may be placed in
your own library or the system's library (SYSl.LINKLIB). You may
use a data management access method or EXCP programming to read
from and write to the PASSWORD data set.
If a data set is to be placed under protection, it must have a
protection indicator set in its label (format-l DSCB or header 1
tape label). This is done by the operating system when the data
set is created, by the IEHPROGM utility program, or, by the
PROTECT macro when creating or adding the control password. The
protection indicator is set in response to a value in the LABEL:
operand of the DO statement associated with the data set being
placed under protection. OS/VS2 JCL describes the LABEL operand.

Note: Data sets on magnetic tape are protected only when standard
labels are used.

Password-protected data sets can only be accessed by programs
that can supply the correct password. When the system control
program receives a request to open a protected data set, it first
checks to see if the data set has already been opened for this job
step. If so, only the access mode will be checked to determi·ne
whether it is compatible with the protection mode under which it
was previously opened. If the data set has not been previously
opened by this job step, or if the access mode is not compatible
with the protection mode under which it was previously opened, a
message is issued that asks for the password. The message goes to
the operator console, or, if the program requesting that the data
set be opened is running under TSO in the foreground, to the TSO
terminal operator. If you want the password supplied by another
method in your installation, you can modify the READPSWD source
module or code a new routine to replace READPSWD in SYSl.LPALIB.

PASSWORD DATA SET CHARACTERISTICS
The PASSWORD data set must reside on the same volume as your
operating system. The space you allocate to the PASSWORD data set
must be contiguous, that is, its DSCB must indicate only one
extent. The amount of space you allocate depends on the number of
data sets your installation wants to protect. Each entry in the
92

OS/VS2 System Programming

Libr~ry:

Data Management

C.'

PASSWORD data set requires 132 bytes of space. The organization of
the PASSWORD data set is physical sequential, the record format is
unblocked, fixed-length records (RECFM=F). These records are 80
bytes long (lRECl=80,BlKSIZE=80) and form the data area of the
PASSWORD data set records on direct-access storage. In these
direct-access storage records, the data area is preceded by a key
area of 52 bytes (KEYlEN=52). The key area contains the fully
qualified data set name of up to 44 bytes and a password of one to
eight bytes, left justified with blanks added to fill the areas.
The password assigned may be from one to eight alphameric
characters in length. OS/VS2 DADSM Logic describes the PASSWORD
data set record format.
You can protect the PASSWORD data set itself by creating a
password record for it when your program initially builds the data
set. Thereafter, the PASSWORD data set cannot be opened (except by
the operating system routines that scan the data set) unless the
operator enters the password.

Note: If a problem occurs on a password-protected system data

set, maintenance personnel must be provided with the password in
order to access the data set and resolve the problem.

CREATING PROTECTED DATA SETS

A data definition (DO) statement parameter (LABEL=) is used to
indicate that a data set is to be placed under protection.
Operating procedures at your installation must ensure that
password records for all data sets currently under protection are
entered in the PASSWORD data set. You may, for example, create a
data set and set the protection indicator in its label, without
entering a password record for it in the PASSWORD data set.
However, once the data set is closed, any subsequent attempt to
open results in termination of the program attempting to open the
data set, unless the passloJord record is avai lable and the operator
can honor the request for the password. (Note that if the
protection mode is NOPWREAD and the request is to open the data
set for input, no password will be required.)

Tape Volumes containing More Than One Password-Protected Data Set
To password-protect a data set on a tape volume containing other
data sets, you must password-protect all the data sets on the
volume. (Standard Labels--SL, SUL, AL, or AUL--are required. See
OS/VS Tape Labels for definitions of these label types and the
protection-mode indicators that can be used.)
If you issue an OPEN macro instruction to create a data set
following an existing, password-protected data set, the password
of the existing data set will be verified during open processing
for the new data set. The password supplied must be associated
with a PWWRITE protection-mode indicator.

PROTECTION FEATURE OPERATING CHARACTERISTICS
The topics that follow
the protection feature
volume switching, data
functions, and counter

provide information concerning actions of
in relation to termination of processing,
set concatenation, SCRATCH and RENAME
maintenance.

Termination of processing

The operator cannot supply the correct password for the
protected data set being opened after two tries.

A password record does not exist in the PASSWORD data set for
the protected data set being opened.
Password Protecting Your Data Sets

........_............. ",_ .. ......... - - - - - - . -,_._ ... _,.,.,._.._,-,.. _.--., ...., , - - - - - - - - - "

The protection mode indicator in the password record, and the
method of I/O processing specified in the Open routine do not
agree, for example, OUTPUT specified against a read-only
protection mode indicator.

C
'

There is a mismatch in data set names for a data set involved
in a volume switching operation. This is discussed in the next
paragraph.

Volume switching
The system ensures a continuation of password protection when
volumes of a multivolume data set are switched. It accepts a
newly-mounted tape volume, to be used for input, or a
newly-mounted direct-access volume, regardless of its use, if
these conditions are met:
•

The data set name in the password record for the data set is
the same as the data set name in the JFCB. (This ensures that
the problem program has not changed the data set name in the
JFCB since the data set was opened.)

•

The protection-mode indicator in the password record is
compat i ble wi th the processi ng mode and a val i d passt.Jord has
been supplied.

The system accepts a newly-mounted tape volume to be used for
output under any of these conditions:
.

•

The security indicator in the HDRl label indicates password
protection, the data set n~me in the password record is the
same as the data set name in the JFCB, and the protection-mode
indicator is compatible with the processing mode. (If the
data set name in the'JFCB has been changed, a new password is
requested from the operator.)

•

The securi,ty i ndi cator in the HDRl label does not i ndi cate
password protection. (A new label will be written with the
security ~ndicator indicating password protection.)

•

Only a volume label exists. (A HDRI label will be written with
the security indicator indicating password protection.)

Data set concatenation
A password is requested for ev~ protected data set that is
involved in a concatenation of data sets, regardless of whether
the other data sets involved are protected or not.

SCRATCH and RENAME Functions
To delete or rename a protected data set, it is necessary that the
job step making the request be able to supply the password. The
system first checks to see if the job step is currently authorized
to write to the data set. If not, message IEC301A is issued to
request the password. The password provided must be associated
with a "WRITE" protection-mode indicator.

Counter Maintenance
The operating system increments the counter in the password
record on each usage, but no overflow indication will be given
(overflow after 65,535 openings). You must provide a counter
maintenance routine to che~k and, if necessary, reset this
counter.

c~
94

OS/VS2 System Programming Library: Data Management

USING THE PROT,ECT MACRO INSTRUCTION TO MAINTAIN THE PASSWORD DATA SET

To use the PROTECT macro instruction, your PASSWORD data set must
be on the system residence volume. The PROTECT macro can be used
to:
•

Add an entry to the PASSWORD data set.

•

Replace an entry in the PASSWORD data set.

•

Delete an entry from the PASSWORD data set.

•

Provide a list of information about an entry in the PASSWORD
data set; this list will contain the security counter, access
type, and the 77 bytes of security information in the "data
area" of the entry.

In addition, the PROTECT macro, updates the DSCB of a protected
direct-access data set to reflect its protection st.tus; this
feature eliminates the need for you to use job control language
whenever you protect a data set.

PASSWORD DATA SET CHARACTERISTICS AND RECORD FORMAT WHEN YOU USE THE PROTECT MACRO
INSTRUCTION
When you use the PROTECT macro, the record format and
characteristics of the PASSWORD data set are no different from the
record format and characteristics that apply when you use your own
routines to maintain it.

Number of Records for Each Protected Data Set
When you use the PROTECT macro, the PASSWORD data set must contain
at least one record for each protected data set. The password (the
last 8 bytes of the "key area") that you assign when you protect
the data set for the first time is called the control password. In
addition, you may create as many secondary records for the same
protected data set as you need. The passwords assigned to these
additional records are called secondary passwords. This feature
is helpful if you want several users to have access to the same
protected data set, but you also want to control the manner in
which they can use it. For example: One user could be assigned a
password that allowed the data set to be read and written, and
another user could be assi gnad a password that allowed the data
set to be read only.

Note: The PROTECT macro will update the protection mode indicator

in the format-l DSCB in the protected data set only when you issue
it for adding, replacing, or deleting a control password.

Protection Hode Indicator
You can set the protection mode indicator in the password record
to four different values:

•

X'OO' to indicate that the password is a secondary password
and the protected data set is to be read only (PWREAD).

•

X'80' to indicate that the password is the control password

•

X'O!' to i ndi cate that the password is a secondary password

•

X'81' to indicate that the password is the control password

and the protected data set is to be read only (PWREAD).
and the protected data set is to be read and wri tten
(PWREAD/PWWRITE).
and the protected data set is to be read and wri tten
(PWREAD/PWRITE).

Password Protecting Your Data Sets

Because the OSCB of the protected data set is updated only when
the control password is changed, you may request protection
attributes for secondary passwords that conflict with the
protection attributes of the control password.

('
"'-...

Because of the sequence in which the protection statu5 of a data
set is checked, the following defaults will occur!

If control password ;s:

Secondary password must be:

PWREAO/PWRITE or
Pl~READ/NOL~RI TE

PWREAO/PWWRITE or

NOPWREAO/PWWRITE

Pl~REAO/NOWRITE

If the control password is set to either of the settings in item 1
above, the secondary password will be set to To PWREAO/PWRITE if
you try to set it to NOPWREAO/PWWRITE.
If the control password is changed from either of the settings in
item 1 to the setting in item 2 above, the secondary password will
be automatically reset to NOPWREAD/PWWRITE.
If the control password is changed from the setting in item 2 to
either of the settings in ltem 1 above, the secondary password i9
set by the system to PWREAO/PWWRITE.

PROTECT MACRO SPECIFICATION
The format is:
[symbol]

PROTECT

parameter list address

parameter Ii st address-A-type address, (2-12) or (1)
indicates the location of the parameter list. The parameter
list must be set up before the PROTECT macro is issued. The
address of the parameter list may be passed in register 1, in
registers 2 through 12, or as an A-type address. The first
byte of the parameter list must be used to identify the
function (add, replace, delete, or list) you want to
perform. See Figure 16 on page 97 through Figure 19 on page
101 for the parameter lists and codes used to identify the
fun·cti ons.
I

('
\ '-.

c
96

OS/VS2 System Programming Library: Data Management

X'O!'
length of data set name

00 00 00

Pointer to data set name

00 00 00

Number of volumes

Protection code

String length

Pointer to control password

Pointer to volume list

Pointer to new password

Pointer to string

OX' 01'

Entry code indicating ADD function.

13 Pointer to control password.
The control password is the password assigned when the data set was placed under
protection for the first time. The pointer can be 3 bytes of binary zeros if the
new password is the con~rol password.
16 Number of volumes.
If the data set is not cataloged and you want to have it flagged as protected, you
have to specify the number of volumes in this field. A zero indicates that the
catalog information should be used.
17 Pointer to volume list.
If the data set is not cataloged and you want to have it flagged as protected, you
provide the address of a list of volume serial numbers in this field. Zeros
indicate that the catalog information should be used.
20 Protection code.
A one-byte number indicating the type of protection: X,OO, indicates default
protection (for the ADD function; the default protection is the type of
protection specified in the control password record of the data set); X'O!'
indicates that the data set is to be read and written; X'02' indicates that the
data set is to be read only; and X'03' indicates that the data set can be read
without a password, but a password is needed to write into it. The PROTECT macro
will use the protection code value, specified in the parameter list, to set the
protection mode indicator in the password record.
Figure 16 (Part 1 of 2). Parameter List for ADD Function

"
C
,.

Password Protecting Your Data Sets

21 Pointer to new password.
If the data set is being placed under protection for the first time, the new
password becomes the control password. If you are adding a secondary entry, the
new password is different from the control password.
24 String length.
The length of the character string (maximum 77 bytes) that you want to place in
the optional information field of the password record. If you don't want to add
information, set thi~ fi~ld to zero.
25 Pointer to string.
The address of the character string that is going to be put in the optional
information field. If you don't want to add additional information, set this
field to zero.
Figure 16 (Part 2 of 2).

Parame~er

list for ADD Function

OS/VS2 System' Programniing library: Data Management

\~/

c_
0

X'02'

length of data set name

00
12

Number of volumes

Protection code

String length

00 00 00

Pointer to data set name

Pointer to current password
13

Pointer to control password

Pointer to volume list

Pointer to new password

Pointer to string

o X'02'.

Entry code indicating REPLACE. function.

9 Pointer to current password.
The address of the password that is going to be replaced.
13 Pointer to control password.
The address of the password assigned to the data set when it was first placed
under protection. The pointer can be set to 3 bytes of binary zeros if the current
password is the control password.
16 Number of volumes.
If the data set is not cataloged and you want to have it flagged as protected, you
have to specify the number of volumes in this field. A zero indicates that the
catalog information should be used.
17 Pointer to volume list.
If the data set is not cataloged and you want to have it flagged as protected, you
have to provide the address of a list of volume serial numbers in this field. If
this field is zero, the catalog information will be used.
20 Protection code.
A one-byte number indicating the type of protection: X'OO' indicates that the
protection is default protection (for the REPLACE function the default protection
is the protection specified in the current password record of the data set);
X'O!' indicates that the data set is to be read and written; X'02' indicates that
the data set is to be read only; and X'03' indicates that the data set can be read
without a password, but a password is needed to write into the data set.
21 Pointer to new password.
The address of the password· that you want to replace the

~urrent

password.

Figure 17 (Part 1 of 2). Parameter List for REPLACE Function

c
Password Protect i,ng Your Data Sets

24 String length.
The length of the character string

• • •• • 0 ••

Must be zero.

A byte of zeros.

14,15

The two-byte ID of the address space associated with
the I/O requests you want purged. (Only meaningful if
bit 2 of byte 12 is on.)

Control will be returned to your program at the instruction
following the PURGE macro instruction. If the purge operation was
successful, register 15 will contain zeros. Otherwise, register
15 will contain one of the following hexadecimal return codes:

Code

Mean;ng

Your request to purge I/O requests associated with a given
TCB was not honored because that TCB did not point to the
job step TCB, as it must when the requestor is in problem
state.

Either you requested an address-space purge operation but
were not in supervisor state or you requested a data-set
purge operation but supplied no data-area address in bytes
1, 2, and 3 of the purge parameter list.

Another purge request has preempted your request. You may
want to reissue your purge request in a time-controlled
loop.

Note: Register 15 will contain zeros, regardless of the outcome
of the purge operation, if you set bit 7 in byte 0 of the
parameter list to zero.

MODIFYING THE lOB CHAIN

If you want to change the order in which purged I/O requests will
be restored or prevent a purged request from being restored, you
may change the sequence of lOBs in the IOe chain or remove an lOB
from the chain. The address of the lOB chain can be obtained from
the PIRl (see Figure 25 on page 124). (The address of the PIRl
will be at the location pointed to by bytes 9 through 11 of the
purge parameter list.)
System Macro Instructions

123

RESTORE--REPROCESS I/O REQUESTS
The RESTORE macro is coded as follows:

I [symbol] I RESTORE I restore address
restore address--RX-type address, (2-12) or (1)
address you specified at byte 9 of the purge parameter list.

PlRL
PlRRSTR 20(14)
'I

Pointer to the first lOB. If l's,
no I/O request was quiesced.

(where 1 is first lOB in chain)

~>IOB(l)

IOBRESTR 25(19)
I Pointer to the next lOB in the

I chain.

~>10B(nl

(where n is last lOB in chainl
IOBRESTR 25(19)
Contains l's.

Figure 25. The PIRL and lOB Chain

TRKCALC--PERFORM TRACK CALCULATIONS
The TRKCALC macro performs track capacity calculations. The
standard, list, execute, and DSECT form of the macro are
described. Examples of the TRKCALC macro follow the macro
descriptions. Using TRKCALC you may do the following:
•

Perform track capacity calculations

•

Determine the number of records of a given size which can be
written on a fulltrack or the remainder of a track

•

Perform track balance calculations as follows!
Determine if a given record size can be written in the
space remaining on the track and return the new track
balance.
Determine the maximum size record which can be written on
the track if the given record does not fit.

124

OS/VS2 System Programming Library: Data Management

('""

Determine the track balance if the last physical record
is removed from the track.
TRKCALC--STANDARD FORM
The format of the TRKCALC macro is:
[symbol]

TRKCALC

FUNCTN=CTRKBALITRKCAP)
CDEVTAB=addrl"UCB=addrl,TYPE=addr)
[, BALANCE"=addr]
--[ , REt!OVE=C YES-TNO)]
[,ttAXSIZE=(YESTfiO)]

[(,RKDD=addrl,R=2ddr,K=add~,DD=addr)]

[,REGSAVE={YESINO)]
[,MF=I]

FUNCTN={TRKBALITRKCAP}
specifies the function to be performed.

Note: You must specify one of the three keywords, DEVTAB,

UCB, or TYPE, to provide the macro a source for information.

TRKBAL
calculates the new track balance. Depending upon
whether the record fits on the track, one of the
following occurs:

•

The record fits on the track. Register 0 contains
the new track balance.

•

If the record does not fit on the track and
MAXSIZE=YES is not specified, a "record does not
fit" return code is given.

•

If the record does not fit and MAXSIZE=YES is
specified, one of the following happens:
The data length of the largest record that fits
in the remaining space is returned in register
O.

A code is returned that indicates no record
fits in the remaining space.
TRKCAP
calculates
be written
that could
number _ 1

the number of fixed length records that can
on a whole track or the number of records
be added to a partial track of R _ 1 (record
in the R or RKDD keywords).

DEVTAB=addr--RX-type address, (2-12), (0), (14)
addr speci fi es a word that contel1 ns the address of the Dev ice
Characteristics Table Entry (DCTE). If you specify a
register, it contains the address of the DCTE, not the
address of a word cOhtaining the address of the DCTE.
UCB=addr-RX-type address, (2-12), (0), (14)
addr specifies a word that contains the address of the UCB.
I f you spec i fy a reg i ster, it conta ins the address of the
UCB, not the address of a word containing the address of the
UCB.

TVPE=addr--RX-type address, (2-12), (0), (14)
You may specify the address of the UCB device type
(UCBTBYT4), or you may specify the one-byte UCB device type
in the low-order byte of a register.
address, (2-12), (0), (14)
You may specify either the address of a halfl>lord containing
the current track balance or you may specify the balance in

BAlAt~CE=Clddr-RX-type

System Macro Instructions

125

the low-order two bytes of a register. The value specified is
the value returned when you last issued TRKCAlC if R 1. If
R ~ 1 the balance is reset to track capacity by TRKCAlC.

REtmVE={YES INO}

indicates if a record is to be deleted from the track.

YES

specifies the record number (specified in the R
keyword) is being removed from the track. The track
balance is incremented instead of decremented.

Note: YES is valid only on a FUHCTH=TRKBAl call.
NO

specifies a record is not to be deleted from the track.
NO is the default.

MAXSIZE={YESINO)
YES

If the specified record does not fit, the largest
length of a record with the specified key length that
fits is returned (register 0).

Note: YES is valid only on a FUHCTH=TRKBAl call.
NO

Maximum size is not returned. HO is the default.

RKDD=addr--RX-type address, (2-12), (0), (14)
addr spec if i es a I,oJO rd conta in i ng a raco rd number (1 byte),
keylength (1 byte), and data length (2 bytes) (bytes 0, I,
and 2 and 3, respectively) or a register containing the
record number, key length, and data length. R, K, and DD may
be spec; fi ad by thi s keyword, or you may use the follow; ng
three keywords instead.

/-----"

R=addr-RX-type address, (2-12), (0), (14), or n
you may specify either the address of the cords's key length,
or you may specify the key length using the low-order byte of
a register or immediate data (n). Specify a decimal digit for
n (immediate data).
K=addr--RX-type address, (2-12), (0), (14), 0 r .!J.
you may specify either the address of the record's key
length, or you-may specify the record's data length using the
low-order two bytes of a register or immediate data (n).
Specify a decimal digit for n (immediate data).
DD=addr--RX-type address, (2-12), (0), (14), or n
you may specify either the address of the record's data
length, or you may specify the record's data length using the
low-order two bytes of a register or immediately date (n).
Specify a decimal digit for n (immediate data).

REGSAVE=CYESINO}
YES

NO
MF=I

126

specifies registers 1-14 are saved and restored in the
caller-provided save area (pointed to by register 13)
across the TRKCALC call. Otherwise, registers 1, 9,
10, 11, and 14 are modified. Registers 0 and 15 are
always modi fi ed by a TRKCALC call.
specifies registers are not saved across a TRKCAlC
call. HO is the default.

specifies to define the storage for the TRKCALC parameter
list and initialize the parameter list using the given
keywords and call the TRKCALC function. MF=I is the default.

OS/VS2 System Programming library: Data Management

INPUT REGISTER USAGE

Registers 0, 2-12, and 14 are available to provide input for
keywords.

parameter list for the MF=E call. Not available as an input
register.

OUTPUT FROM TRKCALC
FUHCTU=TRKBAL
Register 15=0

The record fits on the track. Register 0 contains the
new track balance.

Record does fit on the track. If MAXSIZE=YES is
speci'fied, a partial record does not fit either.
Register 0 is set to zero.

Record does not fit on the track. MAXSIZE=YES is
specified and a partial record does fit. Register 0 is
set to the maximum number of data bytes that fit on the
remainder of the track with the specified keylength.

Note:. The keylength is excluded from the count of
maximum data bytes.

STARBAL

This is the track balance field of the TRKCALC
parameter list. This field is first set to the
calculated input track balance or the specified record
number is 1. STARBAL is updated to the new (output)
track balance if the record does not fit. Otherwise,
STARBAL is left with the input track balance value.

FUNCTN=TRKCAP
Register 15=0

Register 0 contains the number of records that fit on
the track if R = 1, or the number of records that fit on
the remainder of the track if R t 1.

No records of the length specified fit on a full track
(R = 1) or a partial track (R
1). Register 0 is set to
zero.

STARBAL

This is the track balance field of the TRKCALC
parameter list. This field is set to the calculated
input track balance if you do not provide the balance,
or the specified record number is one.

c
System Macro Instructions

127

TRKCALC--LIST FORM
The list form of the TRKCAlC macro is used to construct an empty,
in-line parameter list. By coding only MF=l you construct a
parameter list and the actual values can be supplied by the
execute form of the TRKCAlC macro. Any parameters other than MF=l
are ignored.
[symbol]

TRKCALC

TRKCALC--EXECUTE FORti
A remote parameter list is referred to and can be modified by the
execute form of the TRKCAlC macro. The TRKCAlC routine 1S called.
The description of the standard form of the macro provides the
explanation of the function of each operand.
[symbol]

TRKCALC

[FUNCTN=CTRKBAlITRKCAP}]
[(,DEVTAB=addrl,UCS=addrl,TYPE=addr)]
[,SALANCE=addrl
[,R~MOVE={YESTNO}]

[,MAXSIZE={YES1RoJl
[(,RKDD=adg.r:I,R=Qgdr,K=addr,DD=addr)]
[,REGSAVE={YESINO}l
,tfF=(E,{~arameter list addressl(l)})
FUNCTN=CTRKBALITRKCAP]
It is coded as shown in the standard form. If this keyword is
omitted, any specification of REMOVE, MAXSIZE, LAST, and the
RX form of BALANCE, is ignored. In addition, DEVTAB is
assumed if UCB is coded and a failure occurs if TYPE is
specified. When you use FUNCTN, one of the keywords (DEVTAB,
UCB, or TYPE) must be specified to provide an information
source.
DEVTAS=addrl*--RX-type address, (2-12), (0), (14)
It is coded as shown in the standard form except for the *
subparameter. Specify an
when you have inserted the
address of the Device Characteristics Table Entry (DCTE) in
the parameter list.

UCS=addrl*--RX-type address, (2-12), (0), (14)
-rt:is coded as shown in the standard form except for the
subparameter. Specify an * when you have inserted the
address of the UCB in the parameter list.

TYPE=addrl*--RX-type address, (2-12), (0), (14)
It is coded as shown in the standard form except for the
subparameter. Specify an * when you have inserted the
address of the UCB type (UCBTYP) in the parameter list.

BALANCE=addrl*--RX-type address, (2-12), (0), (14)
It is coded as shown in the standard form except for the
subparameter. Specify an * when you have inserted the
balance in the parameter list.

REMOVE={YESINO}
It is coded as shown in the standard form.
HAXSIZE={YESINO}
It is coded as shown in the standard form.
RKDD=addr--RX-type address, (2-12), (0), (14)
It is coded as shown in the standard form.
R=addr--RX-type address, (2-12), (0), (14) or n
It is coded as shown in the standard form.

128

OS/VS2 System Programming library: Data Management

"-_/

K=addr--RX-type address, (2-12), (0), (14), or n
It is coded as shown in the standard form.
OO=addr--RX-type address, (2-12), (0), (14), or n
It is coded as shown in the standard form.
REGSAVE=(YESINOJ
It is coded as shown in the standard form.
MF=(E,{parameter list addressICl)J)
This operand specifies that the execute form of the TRKCALC
macro instruction is used, and an existing data management
parameter list is used.
E--Coded as shown
parameter list address--RX-type address, (2-12), (0), (14),
or ( l )

TRKCALC--OSECT ONLY
This call gives a symbolic expansion of the parameter list for the
TRKCAlC macro. No DSECT statement is generated. If a name is
spec i f i ad on the macro call, it appl i es to the beg'; nn i ng of the
list, after any necessary boundary alignment. The macro generated
s~lmbols all begi n wi th "STAR".

TRKCALC

[svmboll

MF=D

TRKCALC MACRO EXAMPLES
In this example, TRKCALC is coded to determine how many records of
a given size with lO-byte keys fit on a 3330 track. After issuing
the macro, the number of records is saved in NUMREC:
TRKCALC

Cl
UTYPE
NUMREC

FUNCTN=TRKCAP,TYPE=UTYPE,R=1,K=10,DD=DL
ST

O,NUMREC

SAVE HUMBER OF RECORDS

DC
DC
OS

H'xxxx'
X'09'

DATA LENGTH

MAX # OF RECORDS

In this example, TRKCAlC is coded to determine if another record
can fit on a track of a 3350, given a track balance.
TRKCAlC

FUHCTH=TRKBAl,TYPE=UTYPE,R=REC,K=KL,DD=DD,BALANCE=BAl

UTYPE
REC
Kl
DD
BAl

DC
DC
DC
DC
DC

X'OB'
X'xx'

X'xx'

H'xxxx'
H'xxxx'

After issuing the macro you would receive either:
Register 15=0.

c,
System Macro Instructions

129

ADDING TO THE IMAGE LIBRARY AND RETRIEVING FeB IMAGES

This chapter provides a detailed description of how to add either
an IBM UCS (universal character set) image or an IBM FCB (forms
control buffer) image to SYS1.IMAGELIB. It also describes a
procedure that can be used to read an FCB image into virtual
storage for the purpose of modifying it before loading it into the
forms control buffer.
For the IBM 3800 Printing Subsystem, a utility, IEBIMAGE, is
provided to build the 3800 control modules (character arrangement
table modules, forms control buffer modules, graphic character
modification modules, and copy modification modules) and store
them in SYSl.IMAGELIB. With 3800 Enhancements, IEBIMAGE can also
be used to build library character set modules to be stored in
SYSl.IMAGELIB. For additional information, see IBM 3800 Printing
Subsystem Programmer's Guide.
Before reading this section, you should be familiar with the
information in these publications:
•

IBM 2821 Control Unit Component Description contains the
information necessary to create a user-designed chain/train
for the 1403 Printer.

•

OS/VS2 MVS Data Management Macro Instructions describes the
SETPRT macro instruction that loads a UCS image and an FCB
image into their respective buffers.

•

OS/VS2 JCk describes the UCB and FCB parameters that can be
specified in a DD statement to load the UCS andFCB buffers
when they are opened.

•

IBM 3203 Printer Component Description and Operator's Guide
contains the information necessary to create a user-designed
train for the 3203 Printer.

•

IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and
3811 Print~r Control Unit Component De~cription and
Operator's Guide contains the information necessary to create
a user-designed train for the 3211 Printer.

•

OS/VS2 MVS System Pro9.!:.ammi ng library: JES2 or 1)ystem
Programminq Library: Network Job Entry Facility for JES2 for
reference information for JES2.

•

OS/VS2 System Programming Library: JES3 for reference
information for JES3.

ADDING A UCS IMAGE TO THE IMAGE LIBRARY

All IBM standard character set images are included in
SYSl.IMAGELIB at system generation, when you code the DATAMGT
macro. You may subsequently add a character set image to
SYS1.IMAGELIB by following these rules:
1.

130

The member name must be either the four characters UCSI for
the 1403,IUCS2 for the 3211, or UCS3 for the 3203 printer. The
member name must be followed by a unique character set code
that is one to four characters long. This character set code
can be any valid combination of letters and riumbers according
to the rules for assembler language symbols. The single
letters U or C should 'not be used as a character set code,
since they are symbols for special conditions recognized by
the system. The assi gnad character set code must be speci fi ed
on the DO statement or SETPRT macro in~truction to load the
image into the UCS buffer.

OS/VS2 System Programming library: Data Management

The first byte in the load module of a character set image
specifies whether or not the image is a default. (Default
images may be used by the system for jobs that do not request
a specific image.) You may specify the following in the first
byte if you have JES2:
JES2

X'80'
X'40'
X'CO'
X'OO'

indicates
indicates
indicates
indicates
default

a default image
the output is to be folded
default image and folding
that the image is not to be used as a

non-JES2
X'80' indicates a default image
X' 00' i ndi cates that the image is not to be used as a
default
3.

The second byte of the load module indicates the number of
lines (n) to be printed for image verification.

Each byte of the next n bytes i ndi cates the number of
characters to be printed on each verification line. (Hote:
For the 3211 printer, ~he maximum number of characters
printed per line is 48; the associative bytes are not printed
during verification.>

A 240-byte 1403 UCS image, a 240-byte 3203 UCS image, or a
512-byte 3211 UCS image must follow the previously described
fields. (A 3211 UCS image has 432 characters, followed by 15
bytes of X'OO', 64 bytes of associative bits, and a reserved
byte (the 512th byte) of X'OO'. A 3203 UCS image has 240
characters followed by 64 bytes of associative bits.) Two
apostrophes or two ampersands must be coded to represent a
single apostrophe or a single ampersand, respectively, which
is a part of a character set image.

Figure 26 on page 132 is an example of adding a 1403 UCS image,
1M, to the image library.
Figure 27 on page 133 shows the code used to add a 3211 UCS image
CIMG) to the image library. Two ampersands must be coded to
represent a single ampersand that is part of the character set
image.
The 64 bytes of associative bits must be coded to avoid data
checks. To determine how to code these bits for a particular
train, see IBM 3211 Printer, 3216 Interchangeable Train
Cartridge, and 3811 Printp-r Control Unit Component Description
and Operator's Guide.
Figure 28 on page 134 shows the code used to add a 3203 UCS image
eYN) to the image library. A 3203 UCS image has 240 characters,
followed by 64 bytes of associative bits. Two ampersands or two
apostrophes must be coded to represent a single ampersand or a
single apostrophe, respectively, that ;s part of the character
set image.
The 64 bytes of associative bits must be coded to avoid data
checks. To determine how to code these bits for a particular
train, see IBM 3203 Printer Component Description and Operator's
Guide.

Notes:

Executing the ASMFCL procedure does not actually generate
executable code. The assembler/linkage editor is used as a
vehicle to load the UCS image into the image library.

The SPACE parameter is overridden here because the
IBM-distributed ASMFCL cataloged procedure has secondary
allocation specified. All members must reside completely in
the first extent.
Adding to the Image Library and Retrieving FeB Images

131

IIADDIM
IISTEP
II
IIASM.SYSIN
UCSIIM

JOB MSGLEVEL=l
EXEC PROC=ASMFCL,PARM.ASM='NODECK,LOAD',
PARM.LKED='LISTpOl,REFR,RENT,XREF' (See note)
DD
*
CSECT
DC X'80'
(THIS IS A DEFAULT IMAGE)
DC AL1(6) (NUMBER OF LINES TO BE PRINTED)
DC AL1(39) (39 CHARACTERS PRINTED ON 1ST ~INE)
DC Al1(42) (42 CHARACTERS PRINTED ON 2ND LINE)
DC Al1(39) (39 CHARACTERS PRINTED ON 3RD LINE)
DC ALl(39) (39 CHARACTERS PRINTED ON 4TH LINE)
DC ALl(42) (42 CHARACTERS PRINTED ON 5TH LINE)
DC AL1(39) (39 CHARACTERS PRINTED ON 6TH LINE)
DC C'1234567890STABCDEFGHIJKlMNOPQRSTUVWXYZ*,.'
DC C'1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ*,.#-$'
DC C'1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ*,.'
DC C'1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ*,.'
DC C'1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ*,.I-$'
DC C'1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ*,.'
END

IILKED.SYSLMOD DD DSNAME=SYS1.IMAGELIB(UCS1IM),DISP=OLD,SPACE=

Hote: The RENT and REFR linkage editor attributes are used for performance
considerations in a paging environment and may be omitted.
I

Figure 26. Sample Code to Ndd a 1403 UCS Image to SYS1.IMAGELIB

('
132

OS/VS2 System Programming Library: Data Management

IIADDIMG
IISTEP
II
I/ASM.SYSIN
UCS2IMG

JOB MSGLEVEL=l
EXEC PROC=ASMFCL,PARM.ASM='NODECK,LOAD',
PARM.lKED='LIST,OL,REFR,REHT,XREF' (See note)

CSECT
DC X'80'
DC All(9)
DC Al1(48)
DC Al1(48)
DC ALl(48)
DC Al1(48)
DC AL1(48)
DC Al1(48)
DC Al1(48)
DC All(48)
DC ALl(48)

(THIS IS A DEFAULT IMAGE)
(NUMBER OF lINES TO BE PRINTED)
(48 CHARACTERS PRINTED ON 1ST LINE)
(48 CHARACTERS PRINTED ON 2ND LINE)
(48 CHARACTERS PRINTED ON 3RD LINE)
(48 CHARACTERS PRINTED ON 4TH LINE)
(48 CHARACTERS PRINTED ON 5TH LINE)
(48 CHARACTERS PRINTED ON 6TH LINE)
(48 CHARACTERS PRINTED ON 7TH LINE)
(48 CHARACTERS PRINTED ON 8TH lINE)
(48 CHARACTERS PRINTED ON 9TH LINE)
THE FOLLOWING NINE LINES REPRESENT
THE TRAIN IMAGE

DC C'1<.+IHGFEDCBA*$-RQPOHMLKJX,&&ZYXWVUTS/~#098765432'
DC C'1<.+IHGFEDCBA*$-RQPONMLKJX,&&ZYXWVUTS/~#098765432'
DC C'1<.+IHGFEDBCA*$-RQPONMLKJX,&&ZYXWVUTS/~#098765432'
DC C'1<.+IHGFEDCBA*$-RQPOHMLKJX,&&ZYXWVUTS/~#098765432'
DC C'1<.+IHGFEDBCA*$-RQPONMLKJX,&&ZYXWVUTS/~fta98765432'
DC C'1<.tIHGFEDCBA*$-RQPOHMLKJX,&&ZYXWVUTS/~#098765432'
DC C'1<.+IHGFEDBCA*$-RQPONMLKJX,&&ZYXWVUTS/~#098765432'
DC C'1<.+IHGFEDCBA*$-RQPOHMlKJX,&&ZYXWVUTS/~#098765432'
DC C'1<.+IHGFEDBCA*$-RQPONMLKJX,&&ZYXWVUTS/~#098765432'
DC 15X'OO'
RESERVED FIELD, BITS 433-447
THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS,
* . UCS~ BYTE POSITIONS 448-511
DC X'COI010101010101010100040404240004010'
DC X'101010101010101010004041000040401010"
DC X'101010101010004040000000101010101010'
DC X'10101010004040444800'
DC X'OO'
RESERVED FIELD, BYTE 512
E~~D

/ILKED.SYSlMOD

DSNAME=SYS1.IMAGELIB(UCS2IMG),DISP=OLD,SPACE=

Note: The RENT and REFR linkage editor attributes are used for performance
considerations in a paging environment and may be omitted.
Figure 27. Sample Code to Add a 3211 UCS Image to SYS1.IMAGELIB

c
Adding to the Image Library and Retrieving FCB Images

133

//ADYN3203
//STEP

JOB MSGlEVEl=l
EXEC PROC=ASMFCl,PARM.ASM='NODECK,lOAD',
//
PARM.lKED='lIST,Ol,REFR,RENT,XREF' (See note)
//ASM.SYSIN DD *
UCS3YN
CSECT
(THIS IS A DEFAULT IMAGE)
DC X'80'
DC All(6)
(NUMBER OF LINES TO BE PRINTED)
DC All(39)
(39 CHARACTERS PRINTED ON 1ST LINE)
DC All(42)
(42 CHARACTERS PRINTED ON 2ND LINE)
DC All(39)
(39 CHARACTERS PRINTED ON 3RD LINE)
DC All(39)
(39 CHARACTERS PRINTED ON 4TH LINE)
DC All(42)
(42 CHARACTERS PRINTED ON 5TH LINE)
DC Al1(39)
(39 CHARACTERS PRINTED ON 6TH LINE)
THE FOllOWING SIX LINES REPRESENT
THE TRAIN IMAGE
DC C'1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.'
DC C'1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.#-$'
DC C'1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.'
DC C'1234567890STABCDEFGHIJKlMNOPQRUVWXYZ*,.'
DC C'1234567890STABCDEFGHIJKLMNOPQRUVWXYZ*,.#-$'
DC C'1234567890STABCDEFGHIJKlMNOPQRUVWXYZ*,.'
* THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS,
* UCSB BYTE POSITIONS 241-304
DC X'COIOIOIOIOI0I01010100040000000000010'
DC X'lOlOlOlOlOlOlOI000404000000040001010'
DC X'lOI010101010004000000000101010101010'
DC X'lOI01010004000000000'
END
/*

//lKED.SYSlMOD

DSNAME=SYSl.IMAGElIB(UCS3YN),DISP=OLD,SPACE=

Note: The RENT and REFR linkage editor attributes are used for performance
considerations "in a paging environment and may be omitted.

Figure 28. Sample Code to Add a 3203 UCS Image to SYS1.IMAGELIB

c
134

OS/VS2 System Programming Library: Data Management

ADDING AN FeB IMAGE TO THE IMAGE LIBRARY
For the 3800 Printing Subsystem, refer to the IBM 3800 Printing
Subsystem Programmer's Guide.
Two standard FCB images, STOI and ST02, can be included in
SYS1.IMAGELIB during system generation for a 3211 or 3203 printer
(see Figure 29 on page 136 and Figure 30 on page 137 for a sample
of STDI and ST02 images). STOI prints six lines per inch on an
8-1/2-inch form. STD2 prints six lines per inch on an II-inch
form. Channe.ls for both images are evenly spaced, with channel one
on the fourth line and channel nine on the last line.
In addition to the IBM-supplied images, user images can be
defined. Each user image is added to the image library as part of
a load module. To add an FCB image to the image library, follow
these rules:
1.

The member name cannot exceed eight bytes. The first four
characters of this member name must be FCB2. The characters
that follow FCB2 identify the FCB image and are referred to as
the image identifier. Any combination of characters that are
valid in assembler language can be used with the exception of
a single "c" or a single "U" as an image identifier. The image
identifier must be specified in a DO statement or in the
SETPRT macro instruction to load the image in the FCB buffer.

The fi rst byte of the load module of a forms control image
sp~cifies whether or not the image is a default. A default
image is indicated by X'80' and is used for all jobs that do
not have the FCB parameter coded on the DO statement; X'OO'
indicates that the image is not to be used as a default.

The second byte of the load module i ndi cates the number of
bytes to be transferred to the control unit to load the FCB
image. Thi~ count includes the byte, if used, for the print
position indexing feature.

The third byte of the load module (the first byte of the FeB
image) is either the print position indexing byte or the lines
per inch byte. The print position indexing byte is optional
and, when used, precedes the lines per inch byte. A
description of the print position indexing feature and its
use may be found in IBM 3211 Printer, 3216 Interchangeable
Train Cartridge, and 3811 Printer Control Unit Component
Description and Operator's Guide.
The form image begins with the lines per inch (LPI) byte. The
LPI byte defines the number of lines per inch (6 or 8), and
also represents the first line of the page. It mayor may not
contain a channel identifier.
Typically, the length of an FCB image is constant with the
length of the form it represents. For example, an 8-1/2-inch
form to be printed at 6 lPI has an FCB image which is 51 bytes
in length (8-1/2-inches times 6 LPI).

•

X'ln' means eight lines are printed per inch.

•

X'On' means six lines are printed per inch.

All remaining bytes (lines) must contain X'On' except the
last byte. The last byte must be X'ln'. The letter n can be a
hexadecimal value from 1 to e, representing a channel (one to
twelve); or it can be zero (0), which means no channel is
indicated.

In Figure 29 on page 136, an FCB load module is assembled and
added to SYSl.IMAGElIB. The image defines a print density of eight
lines per inch on an II-inch form with a right shift of 15 line
character positions (1-1/2 inches).

Adding to the Image Library and Retrieving FeB Images

135

FCB2STD1

CSECT
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC

DC
DC
DC
DC
DC
DC
DC
DC
DC
END

~
I

X'80'
AL1(51)
X'OOOOOO'
X'Ol'
X'OOOOOO'
X'02'
X'OOOOOO'
X'03'
X'OOOOOO'
X'04'
X'OOOOOO'
X'05'
X'OOOOOO'
X'D6'
X'OOOOOO'
X'D7'

DEFAULT
FCB IMAGE LENGTH = 51
LINE 1,2,3
LINE 4
CHANNEL 1
LINE 5,6,7
CHANNEL 2
LINE 8
LINE 9,10,11
LINE 12
CHANNEL 3
LINE 13,14,15
LINE 16
CHANNEL 4
LINE 17,18,19
LINE 20
CHANNEL 5
LINE 21,22,23
LINE 24
CHANNEL 6
LINE 25,26,27
LINE 28
CHANNEL 7
X'f}f}f}f}f}f}'
L!~E 2,?,3Q,3!
LINE 32
CHANNEL 8
X'08'
X'OOOOOO'
LINE 33,34,35
LINE 36
CHANNEL 10
X'OA'
LINE 37,38,39
X'OOOOOO'
LINE 40
CHANNEL 11
X'OB'
X'OOOOOOOOOOOOOOOO' LINE 41,42,43,44,45,46,47,48
LINE 49
CHANNEL 12
X'OC'
LINE 50
X'OO'
CHANNEL 9--END OF FCB IMAGE
LINE 51
X'19'

'-_/

Figure 29. Sample of -the Standard FCB Image STDI

(r-----

RETRIEVING AN FeB IMAGE

\ ......

If you want to modify an FCB image in virtual storage before
loading it into a forms control buffer, you can use this sequence
of macro instructions to read the FCB image into virtual storage:
1.

An IMGLIB macro instruction, with the OPEN parameter.

A BLDL macro instruction, to determine whether the FCB image
you want is in the image library.

A LOAD macro instruction, to load the image into virtual
storage.

After the image has been read in, it's necessary to issue another
IMGLIB macro, but this time with the CLOSE parameter and the
address of the DCB that was built by the first IMGlIB macro. A
SETPRT macro instruction can be used to load the forms control
buffer with the modified image.
The format of the BLDL and the SETPRT macros is given in OS/VS2
MVS Data Management Macro Instructions; the format of the LOAD
macro is given in OS/VS2 Supervisor Services and Macro
Instructions. Shown here is the format of the IMGLIB macro:

I [symbol]
OPEN

136

IMGLIB

COPEHICLOSE,addrJ

specifies that a DCD is to be built for SYS1.IMAGELIB and
that SYS1.IMAGELIB is to be opened. The address of the DCB is
returned in register 1.

OS/VS2 System Programming library: Data Management

FCB2STD2

CSECT
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
·DC
DC
DC
DC
DC
END

X'80'
Al1(66)
X'OOOOOO'
X'OI'
X'OOOOOOOOOO'
X'02'
X'OOOOOOOOOO'
X'03'
X'OOOOOOOOOO'
X'04'
X'OOOOOOOOOO'
X'05'
X'OOOOOOOOOO'
X'06'
X'OOOOOOOOOO'
X'07'
X'OOOOOOOOOO'
X'08'
X'OOOOOOOOOO'
X'OA'
X'OOOOOOOOOO'
X'OB'
X'OOOOOOOOOO'
X'OC'
X'OO'
X'19'

DEFAUL T II"1AGE
FeB IMAGE LENGTH = 66
LINES 1,2,3
lINE 4
CHANNEL 1
LINE 5,6,7,8,9
LINE 10
CHANNEL 2
LINE 11,12,13,14,15
LINE 16
CHANNEL 3
LINE 17,18,19,20,21
CHANNEL 4
LINE 22
LINE 23,24,25,26,27
LINE 28
CHANNEL 5
LINE 29,30,31,32,33
LINE 34
CHANNEL 6
LINE 35,36,37,38,39
CHANNEL 7
LINE 40
LINE 41,42,43,44,45
CHANNEL 8
LINE 46
LINE 47,48,49,50,51
CHANNEL 10
LINE 52
LINE 53,54,55,56,57
CHANNEL 11
LINE 58
LINE 59,60,61,62,63
LINE 64
CHANNEL 12
LINE 65
CHANNEL 9-END OF FORM
LINE 66

Figure 30. Sample of the Standard FCB Image 5TD2

CLOSE
addr

specifies that SYSl.IMAGELIB is to be closed.
RX-type address of word that points to the DCB. If coded in
the form (1-12), then the register contains the address of
the DCB, not the address of the fullword.

Return codes for IMGLIB OPEN:

Decimal
Return Code

Meaning

Successful.

Either the volume containing SY51.IMAGELIB is not
mounted or a required catalog volume was not
mounted.

Either SY51.IMAGELIB does not exist on the volume
to which the catalog points, or it is not
cataloged.
.

An error occurred in reading the catalog or VTOC.

BLDL and LOAD are the only macros that may refer to the DCB built
by the IMGLIB macro.

Adding to the Image Library and Retrieving FCB Images

137

//ADDFCB
JOB
MSGLEVEL=1
//STEP
EXEC PROC=ASMFCL,PARM.ASM='NODECK,LOAD',
// PARM.LKED='LIST,OL,REFR,RENT,XREF' (See note)
//ASM.SYSIN
DD
*
FCB2IDI
CSECT
*THIS EXAMPLE IS FOR A FORM LENGTH OF 11 INCHES
*WITH 8 LINES OF PRINT PER INCH (88 LINES)
DC
X'80'
THIS IS A DEFAULT IMAGE
DC
ALl(89)
LENGTH OF FCB IMAGE
DC
X'8F'
OFFSET PRINT LINE 15
*CHARACTER POSITIONS TO THE RIGHT
DC
X'10'
8 LINES PER INCH-NO CHANNEL FOR LINE 1
DC
XL4'O'
4 LINES NO CHANNEL
DC
X'O!'
CHANNEL 1 IN LINE 6
DC
XL6'O'
6 LINES NO CHANNEL
DC
X'02'
CHANNEL 2 IN LINE 13
DC
XL6'O'
DC
X'03'
DC
XL6'O'
DC
X'04'
DC
XL6'O'
DC
X'OS'
DC
XL6'O'
DC
X'06'
DC
XL6'O'
DC
X'07'
DC
XL6'O'
DC
X'08'
DC
XL6'O'
DC
X' 09'
DC
XL6'O'
DC
X'OA'
DC
XL6'O'
DC
X'OS'
DC
XL6'O'
DC
X'OC'
CHANNEL 12 IN LINE 83
4'LINES NO CHANNEL
DC
XL4'O'
DC
X'lO'
LINE 88--LAST LINE IN IMAGE
END
/*

//LKED.SYSLMOD DD

"'-..

DSNAME=SYSl.IMAGELIBCFCB2IDl),DISP=OlD,SPACE=

Note: The RENT and REFR linkage editor attributes are used for performance
considerations in a paging environment and may be omitted.
Figure 31. Sample Code to Assemble and Add an FCB Load Module to SYSl.IMAGELIB

c·
138

OS/VS2 System Programming Library: Data Management

JES2 SUPPORT FOR THE IBH 1403, 3203-5, AND 3211 PRINTERS

The system assigns an alias for each installation-standard print
chain not actuallY defined on a given printer. This provides JES2
with flexibility in scheduling printers for SYSOUT data sets. For
example, a request for the 1403 TH train would be assigned the TIl
train, if the data set were printed on a 3211. The Dssigned alias
names, which follow the naming conventions currently used in
SYS1.IMAGELIB, are:

IMAGE

ALIAS

UCSIAH
UCS1HH
UCS1PH
UCS1TH
UCS2Ali
UCS2Ull
UCS2Pll
UCS2Tll

UCSIAII
UCSIHII
UCS1Pll
UCSITII
UCS2AN
UCS2HH
UCS2PH,UCS2RH,UCS2QH
UCS2TH

The image and alias names are included in SYS1.IMAGELIB at system
generation. (See the DATAMGT Macro in OS/VS2 System Programming
Library: System Generation Reference.)
Some trains, such as SN and GIl, do not have aliases because
neither has an equivalent train on the other printer. An
installation can assign an alias, if it so chooses. (See OS/VS
Link~q? Editor and Loader for details about the ALIAS statement.)
If an alias is supplied, JES2 will use it. If an alias is not
supplied, an installation-defined SYSOUT class or a printer
routing code (specified via the DEST parameter) should be used to
assign the data set to the correct printer. If a SYSOUT class or a
printer routing code is not used, and JES2 is directed to print a
data set on a printer for which the proper image is not supplied,
JES2 notifies the operator. The operator can then print the data
set with a valid train or redirect the data set to the proper
printer via the '$E' command.
If an installation defines a new train, it can supply an alias
name for that train, via the linkage editor ALIAS statement, when
including the image in SYS1.IMAGELIB.

THE 3211 INDEXING FEATURE
JES2 supports the 3211 Indexing Feature in two ways:
1.

Specification of the IHDEX parameter on the /*OUTPUT card.

The extended FCB image:
JES2 supplies two special FCBs: FCB26 for 6 lines/inch and
FCB28 for 8 lines/inch (specified as FCB=6 and FCB=8,
respectively). These FCBs contain a channell indication in
position 1, a special index flag in the third byte, and the
number of lines/inch in the fourth byte of the image.

c,"

The special index flag in the third byte of FCB26 and FCB28
contains X'80' plus a binary index value, in the range 1-32
(default=I). The index value sets the left-hand margin (1
indicates flush-left position; other values cause indentation
of the print line by H-l position).

JES2 Support for the IBM 1403, 3203-5, and 3211 Printers

139

If any other FCB images are to be used by JES2, they must
specify channel 1 in position 1; otherwise JES2 incorrectly
positions the forms in the printer. (STD1 and STD2 do not
specify channel 1 in position 1 and therefore must not be
specified, unless altered, for JES2.)
If the thi rd byte of any other FCB image conta ins a data
character (specifying the number of lines/inch) other than
X'80', JES2 uses that specification and supplies an index
value of 1.

3203-5 PRINTER
The 3203-5 Pri nter is treated the same as a 3211 pri nter by JES2
and JES2 NJE, except that the 3203-5 does not support the 3211
indexing feature, and any indexing commands from JES2 or JES2 NJE
are ignored by the 3203-5. The 3203-5 uses 3211 FCB images and its
own unique UCS images. UCS images are listed in OS/VS2 System
Programming Library: System Generation Reference.

~--,

c140

OS/VS2 System Programming library: Data Management

FORMAT-l DseB-NOT-FOUND USER EXIT IN OPEN AND EOV

The function of the Format-1 DSCB-not-found user exit in OPEN and
EOV is to determine if a m1ssing DSCB (such as a data set which
has been migrated to another volume) can be restored to the
volume. If your exit module restores the DSCB, it indicates this
when it returns control to the control program. The exit module,
IFGOEXOA, is given control whenever OPEN or EOV fails to find a
format-1 DSCB on a volume. There is an IBM-supplied exit module,
IFGOEXOA, in SYS1.PAlIB. If you wish to use your own exit module,
you must replace IFGOEXOA. Your exit module must have an entry
point name of IFGOEXOA. If you do not write your own exit module,
processing continues normally as the IBM-supplied exit returns a
zero return code.
The exit is taken even under conditions where abnormal
termination ordinarily would not occur. Two examples of these
conditions follow!
1.

When you have specified DISP=MOD and error recovery
processing is taking place because the last volume specified
in the JFCB does not contain the DSCB, but an earlier volume
does. For this case, if your return code from IFGOEXOA is zero
or if your return code is 4 and the DSCB has not been
restored, OPEN and EOV search the other volumes for the DSCB
after the exit is taken.

Another condition occurs during EOV output when space has not
yet been allocated on the new volume. Space is allocated after
the exit is taken if your return code from IFGOEXO~ is zero or
if your return code is 4 and the DSCB has not been restored.

When a DSCB is not found, IFGOEXOA is given control as follows!
•

In system protect key 5 (data management key)

•

In supervisor state

•

The system resource represented by the SYSZTIOT major name is
enqueued for shared control (this ENQ prevents the exit from
invoking system functions such as SCRATCH, RENAME, dynamic
allocation, or LOCATE).

Standard register linkage conventions are used when IFGOEXOA is
given control as follows!

contents

Unpredictable

Address of parameter list

2-12

Unpredictable

Address of 18-word save area

Return address

Address of entry point IFGOEXOA

The parameter list pointed to by register 1 consists of two
full w0 r d s. The fir s t f u I hJ 0 r d co n t a 1n s the add res s 0 f t he UCB for
the volume on which the DSCB was not found. The second fullword
contains the address of the 44-byte data set name, left justified,
and pad d e d LoJ i t h b I an k..s. Bit z e roo f the sec 0 n d full w0 r dis set to
one, indicating the last word in the parameter list. The data set
name must not be modified by the exit. The parameter list, save
area, and data set name are in protect key 5 virtual storage,
Format-l DSCB-Hot-Found User Exit in OPEN and EOV

1~1

which is not fetch protected. IFGOEXOA must be reenterable. All
work areas obtained through GETMAIN must be released through
FREEMAIN. The return from your module, IFGOEXOA, to OPEN or EOV
must be made as follows:
•

Using the return address passed to you in register 14

•

Registers 2-12 restored

•

In protect key 5

•

In supervisor state

•

Wi th a return code of 0, 4, or 8 in regi ster 15

The return code you set in register 15 has the following meanings:

Processing continues normally. This return code is given if
the exit does not restore the OSCB. Zero is the return code
always given by the IBM supplied exit module.

The volume is searched one more time by OPEN or EOV for the
OSCB. This return code is given if IFGOEXOA restores the OSCB
to the volume. If the OSCB is again not found, IFGOEXOA is
not given control and processing continues normally.

The task is abnormally terminated without attempting to
determine if OISP=MOO error recovery or allocation on the
new volume should occur. This return code is given if
IFGOEXOA encounters an error and you wish no further
processing to occur.

You should have IFGOEXOA establish its own error recovery
environment (such as through an ESTAE), intercept any
indeterminate errors, and return to the control program with
return code 8. Problem determination is the responsibility of
your exit module. A write-to-programmer (WTO with routing code
11) or a TPUT (if a TSO region) may be used to issue an
informative m~ssage.
During a parallel OPEN when two or more DCBs are being opened at
the same time, and two of the DCBs are opening the same data set,
the OSCB may be missing. If IFGOEXOA is called for the first of
the two DeBs and restores the DSCB, the channel program attempting
to read the oSCB for th~ second oCB may have been executed befor~
the restoration of the DSCB was complete. IFGOEXOA is then called
for the second DeB even though the OSeB has already been restored.
Return from IFGOEXOA with a return code 4 is appropriate in this
case.
IFGOEXOA is not given control when you are processing a VSAM data·
set with an ACB; however, it is given control when you are
processing a VSAM data space with a DCB. IFGOEXOA is bypassed if
the format-4 oSCB is not found on a volume, even if the OPEN ;s to
the VTOC data set name (data set name of 44 bytes of X'04').

c
142

OS/VS2 System Programming library: Data Management

CATALOG, SCRATCH, AND RENAME DUMMY MODULES

(
The load modules for CATALOG (SVC 26), SCRATCH (SVC 29), and
RENAME (SVC 30) contain as their entry points the dummy modules
IGG026DU, 1GG0290U, and 1GG0300U, respectively. These dummy
modules immediately pass control to the first processing module
for their respective SVCs without performing any processing
themselves. The CATALOG dummy module 1GG0260U receives control
from SVC 26 and immediately passes control to module 1GC0002F. The
SCRATCH dummy module 1GG029DU receives control from SVC 29 and
immediately passes control to module 1GC00021. The RENAME dummy
module, 1GG0300U, receives control from SVC 30 and immediately
passes control to 1GC00030.
If you require special processing either before or after SVC 26,
29, or 30, you replace the appropriate dummy module(s) with your
own module(s). Your replacement modules must follow all the
characteristics and programming conventions for SVC routines. For
information on writing SVC routines, characteristics of SVC
routines, programming conventions for SVC routines, and inserting
SVC routines into MVS, see OS/VS2 System Pr~qramming Library:
Supervisor. Your modules may replace 1GG026DU, 1GG029DU, and
1GG030DU in SYSl.AOSOO prior to system generation, or you may
replac~ the dummy modules in SYSl.LPAl1B after system generation.
1nform~tion on how to replace the dummy modules with your modules
can be obtained from the appropriate link-edit step of the STAGE I
system generation output. You may also obtain link-edit
information from the STAGE I system generation macro SGIEC40M in
SYS1.AGENl1B. You may apply PTFs to CATALOG, SCRATCH, or RENAME
with SMP without modifying your own versions of IGG026DU,
IGG029DU, and IGG0300U.

(

The prolog of each of the dummy modules contains register
conventions and other information about these modules.

c
CATALOG, SCRATCH, and RENAME Dummy Modules

143

SCRATCH DUMMY MODULE

The load module for SCRATCHCSVC29) contains the dummy module
IGG029DM. The SCRATCH dummy module IGG029DM receives control from
IGG0290D, when an error return code of 4 or 8 is indicated, and
immediately passes control to the location pointed to by register
14.
If special error processing is required after SVC29, the dummy
module can be replaced with your own module. Your replacement
module must follow all the characteristics and programming
conventions for SVC routines. For information on writing SVC
routines, characteristics of SVC routines, programming
conventions for SVC routines, and inserting SVC routines into MVS
see OS/VS2 System Programming library: Supervisor. Your module
may replace IGG029DM in SYSl.AOSDO prior to system generation, or
you may replace the dummy module in SYSl.lPAlIB after system
generation. Information on how to replace the dummy module with
your module can be obtained from the appropriate link-edit step of
the STAGE I system generatjon output. You may also obtain
link-edit information from the STAGE I system generation macro
SGIEC4DM in SYSl.AGENlIB. You may apply PTFs to SCRATCH with SMP
without modifying your own version of IGG029DM.
The prolog of the dummy module 60ntains register conventions and
other information about this module.

144

OS/VS2 System Programming Library: Data Management

CONTROLLING SPACE ON DASD VOLUMES

INTRODUCTION
The direct access device storage management (DADSM) routines
control allocation of space on direct-access volumes through the
volume table of contents (VTOC) of that volume. The VTae is built
when the volume is initialized by the direct-access stor~ge
device initialization (Device Support Facilities, IEHDASDR or
IBCDASDI) ut iIi ty program. See "The Volume Table of Contents" in
this section for more information about the VTOC.
The VTOC is a collection of data set control blocks (DSCBs). The
different types of DSCBs are:
1.

Free VTOC record DSCB----format-o

Identifier DSCB----format-1

Index DSCB----format-2

Extension DSCB--format-3

VTOC DSCB--format-4

Free space DSCB--format-5

Shared extent DSCB--format-6

Each DSCB corresponds either to a data set or data space currently
residing on the volume, or to contiguous, unassigned tracks on the
volume. DSCBs are the data set labels, which contain
characteristics of the data sets or data spaces and a description
of the tracks on which the data sets resides. DSCBs for unassigned
tracks indicate the location of unassigned, contiguous tracks.
The Allocate and Extend routines assign tracks and cylinders on
direct-access volumes. The Allocate routines are used by the
scheduler component to get space for new data sets. The Extend
routine is called by the system catalog management and
End-of-Volume components to get more space for a data set (or VSAM
data space) that has already been allocated, but negds more space.
Other DADSM routines (Scratch and Partial Release) are used to
release space that is no longer needed on a direct-access volume.
When space is needed on a volume, the DADSM routines check the
VTOC for enough contiguous, available tracks to satisfy the
request. If there are not enough contiguous tracks, the request is
filled using as many as five noncontiguous groups of free tracks.
The appropriate DSCBs are modified to reflect the assignment of
the t,·acks.
When space is released, the DADSM routines delete the DSCBs of the
deleted data set or data space. A free space (format-5) DSCB is
built, or modified if existent, to indicate that the tracks
containing the affected data set or data space can be reallocated.

DADSM ROUTINES
DADSM's space management routines are concerned with:
1.

Allocating primary space, which involves finding space for
new data sets or for VSAM data spaces. These are the Allocate
routines.

Controlling Space on DASD Volumes

145

Allocating secondary space, which involves finding additional
space for data sets or VSAM data spaces that have exceeded
their original, primary allocations. This is the Extend
routine.

r""

Releasing space, which involves both deleting entire data
sets or data spaces that are no longer needed, and freeing
unused space in data sets that are being retained. These are
the Scratch and Partial Release routines.

DADSM's VTOC-related service routines are concerned with:
1.

Changing the names of data sets. This is the Rename routine.

Making control information available for examination. This is
the Obtain routine.

Determining the space available on a direct-access volume.
This is the lSPACE routine.

M~intaining

the system PASSWORD data set, which controls
access to data sets and their associated control information.
This is the Protect routine.

ALLOCATING AND RELEASING SPACE ON DIRECT-ACCESS VOLUMES
The DADSM routines which allocate space (Allocate and Extend),
and release space (Scratch and Partial Release), add, delete, and
modify records of the VTOC. These records are called data set
control blocks (DSCBs). To make space available to a new data set
or to increase the space allocated to a data set, the appropriate
DSCBs are searched for available space; the space is allocated to
the data set by writing the description of the space, called an
extent, to the data set's DSCB and deleting the extent from the
space available for allocation. To release space allocated to a
data set, the allocate operation is reversed: the released extent
;s deleted from the data set's DSCB and added to the DSCB that
describes ava(lable space.
Components of the operating system use the DAOSM routines to
allocate and release space in response to data definition (DO)
statements. For example, job management (scheduler) routines call
the Allocate routines to obtain space for a new data set. The
End-of-Volume component of Open/Close/End-of-Volume (O/C/EOV)
calls the Extend routine when an existing data set needs more
space; the MVS catalog management routines call the Extend
roufine to get more ~pace for a VSAM data space; and the OS
catalog management routines call the Extend routine to allocate
additional space for an OS catalog. Similarly, job management
routines use the Scratch routine to delete data sets, and the
catalog management routines use the Scratch routine to delete a
data set loJhen uncata log i ng i nvo I ves delet i ng a data set of a
generation data group. Utility programs (IEHPROGM, IEHMOVE, and
IEBCOPY) use the Scratch and Allocate routines. Scratch
processing is also available to the system programmer through the
SCRATCH macro instruction.
The virtual
space using
These DADSM
routines to

storage access method (VSAM) allocates and releases
the DADSM Allocate, Extend, and Scratch routines.
routines are called by the MVS catalog management
allocate, extend, and delete VSAM data spaces.

The Partial Release routine is called by the Close routine of
O/C/EOV to release unused space before a data set is closed.
Partial Release is also called by the reposition-I/O routine of
Checkpoint/Restart to release unused space.

146

OS/VS2 System Programming library: Data Management

VTOC-RElATED SERVICE ROUTINES
While Rename, Obtain, LSPACE, and Protect routines are used to
read and change control information on the VTOC, none allocates or
releases space. System macro instructions can be used to invoke
the Rename, Obtain, and Protect routines (information for these
macro instructions is provided in the section "Using Catalog
Management f'lacro Instruct ions") .
The Rename routine finds the DSCB for a specified data set and
changes its name, after verifying that the requested name does not
duplicate one already on the volume.
The Obtain routine finds the DSCB for a specified data set, then
reads the DSCB into virtual storage. The Obtain routine is also
used to get information about VSAM data sets from the VTOC, the
MVS master catalog, or a VSAM user catalog.
The LSPACE routine is called either (1) by routines issuing
demount messages for direct-access volumes (for example,
scheduler and O/C/EOV) when the operator has issued a "MONITOR
SPACE" command or (2) by the System Management Facilities (S~'F).
The available space on the volume is calculated by searching and
totaling the extents contained in the free space (format-S)
DSCBs. At the same time, the largest available extent on the
volume is located. If SMF information is required, an SMF type-19
record is gathered and written to the SMF data set.
The Protect routine adds, replaces, deletes, or lists entries in
the PASSWORD data set. When the security protection status of a
data set changes, the Protect routine also modifies the
protection mode indicator field in the protected data set's DSCB.

THE VOLUt'E TABLE OF CONTENTS
The volume table of contents (VTOC) is a data set consisting of
140-byte data set control blocks (DSCBs) that describe the
contents of a direct-access storage device volume. The VTOC data
set resides in a single extent (that is, it is a continuous data
set); its address is located in the VOLVTOC field of the standard
volume label (see Figure 32 on page 148). There are seven
different kinds of DSCBs. Each has a different purpose and is,
consequently, given a different name and format number. Figure 33
on page 149 lists each DSCB and its use.

c
Controlling Space on DASD Volumes

147

Standard Volume Label

',---../
l1(B)

]

VOL VTOC (10 bytes)
CCHHR of VTOC
(format-4) DSCB

~,--------------~--~--------~------~

/
/

Cylinder 0 ' "
Track 0
,

/
/

-,----

Record
3

DSCB 1

VTOC Data Set
(Can be located anywhere on
the volume after cylinder 0,
track 0, and following the
volume label and IPL records.)

Figure 32. Locating the Volume Table of Contents (VTOe)

148

OS/VS2System Programming Library: Data Management

DSCB

Name

Format
Number

Identifier

DSCB

Function

How Many

How Found

Describes a data set
set or VSAM data
space and the first
three extents.

One for every
data set or
data space on
the volume,
except the
VTDC.

Search on key equal
to the data set
name.

Index

Describes the
indexes of an ISAM

See "ISAM Data
Set Allocation"
in DS/VS2
DADSM Logic

Chained from a
format-l DSCB that
represents the
data set.

Extension

Describes the 4th
through 16th extents
of a data set or
VSAM data space.
(Data sets and VSAM
data spaces are
restricted to 16
extents per volume.)

One for each
data set or
VSAM data space
on the volume
that has more
than three
extents.

Chained from a
format-2 or a
format-l DSCB that
represents the data
set or VSAM data
space.

VTOC

Describes the extent
and contents of the
VTDe and volume and
device characteristics.

One on each
volume.

VDlVTOC field of the
standard volume label
contains its address.
It is always the
first record in the
VTDC.

Free Space

Describes the space
on a volume that has
not been allocated
to a data set or to
a VSAM data space
(available space).

One for every
26 noncontiguous
extents of
available space
on the volume.

The first format-S
DSCB on the volume
;s always the second
record of the VTDC.
If there is more
than one format-5
DSeB, it will be
chained from the
first format-5
DSCB via the
DS5PTRDS field
of each format-5
DSeB.

Shared
Extent

Describes the
extents shared by
two or more data
sets (splitcylinder extents).

One for every
26 splitcylinder
extents on the
VTDC.

The address of the
first format-6 DSCB
is contained in the
DS4F6PTR field of
the format-4 DSCB.
If there is more
than one format-6
DSCB on the volume,
it will be chained
to the first via the
DS6PTRDS field of
the format-6 DSCB.

Figure 33 (Part 1 of 2). Data Set Control Block (DSCB) Format Types and Use

Controlling Space on DASD Volumes

149

DSCB

Name

Format
Humber

Free VTDC
Record

DSCB

Function

How Many

How Found

The unused records
in the VTDC, which
contains 140 bytes
of binary zeros. To
delete a OSCB from
the VTDC, a format-O
OSCB is written over
it.

One for every
unused 140-byte
record on the
VTDC. The
DS40SREC field
of the format-4
DSCB is a count
of the number of
format-O OSCBs
on the VTDC.

Search on key
equal to X'OO'
(sometimes
X'OOOOOOOO').

Figure 33 (Part 2 of 2). Data Set Control Block (OSCB) Format Types and Use

The first record in every VTOC is the VTOC (format-4) DSCB that
describes (1) the device that the volume resides on, (2) the
attributes of the volume itself, and (3) the size and contents of
the VTDC data set itself.
The format-4 OSCB is followed by a free-space (format-S) DSCB,
which lists the extents on the volume that have not been allocated
to a data set or VSAM data space. Each format-S DSCB contains 26
extents. If there are more than 26 available ~xtents on the
volume, another format-S DSCB will be built for every 26 extents.
The format-S OSCBs are chained using the last field of each
format-S OSCB. The third and subsequent DSCBs in the VTDC do not
necessarily occupy continuous space, nor do they have any
prescribed sequence.
A data set or VSAM data space is defined by one, two, or three
DSCBs in the VTDC of each volume on which it resides. The number
of DSCBs needed to define a data set or VSAM data space is
determined by (1) the org~nization of the data set (ISAM data sets
need a format-2 OSCB to describe the index) and (2) the number of
extents the data set or VSAM data space occupies (a format-3 OSCB
is needed to describe the fourth through the sixteenth extents).
Figure 34 on page 151 shows the general makeup of a VTDC and the
OSCBsneecled to define two types of data sets (ISAM and non-ISAM).
Data set A (in Figure 34 on page 151) is an ISAM data set; three
OSCBs, a format-I, format-2, and format-3, are required. Data
sets B, C, and D could be sequential, partitioned, or direct data
sets or VSAM data spaces. Data set B has more than three extents
and therefore requires both a format-l and a format-3 DSCB.
Data sets C and D have three or fewer extents and need only a
format-1 DSCB. The format-6 DSCB, pointed to by the format-4 DSCB,
is used to keep track of the extents allocated in order to be
shared by two or more data sets (split-cylinder data sets). For
example, if data sets C and D share an extent made up of one or
more cylinders, this extent would be described in the format-6
DSCB.· Note that spl i t-cyl i nder data sets can no longer be
allocated on MVS systems, but existing split-cylinder data sets
can still be processed.

150

DS/VS2 System Programming library: Data Management

./."

Standard Volume LabeJ

l1(B)
VOLVTOC
field
'~----'

VToe Data Set

Format-4 DSCB

First F5 DSCB

Description of
device, volume,
and the VTOC
extent

Description of
26 available

Description of
as many as 26
shared-cylinder
extents

Data Set A
::; Format-l DSCB

- --

Description of
as many as 26
available extents

Data Set D

Demipt~
the 4th-16th
extents of
data set A

DSCB for an ISAM data
set (Data Sct A)

Free VTOC Records
(Format-O DSCBs)

DSCB for a
Iloll-ISAM data
set (Data Sets B, C, D)
or a VSAM da ta space

Figure 34. Contents of VTOC--DSCBs Describing Data Sets

To prepare a volume for use (to initialize it), the Device Support
Facilities, IBCDASDI or IEHDASDR utility is used. One of the
things these utilities do is build the VTOC. After
initialization, this VTOC will contain a format-4 DSCB and a
format-5 DSCB. The format-5 DSCB contains an extent entry for all
the free space on the volume; the initial number of extents in the
Controlling Space on DASD Volumes

151

format-5 DseB is one or two, depending on where the VTOe is
located on the volume. If the VTOe is located somewhere other than
at the beginning or end of the volume, two extent entries are
needed to describe the free space that precedes and follows it.

,f""
1\...... /

SIZE OF THE VOLUME TABLE OF CONTENTS
The number of DSCBs in the VTOC determines the number of data sets
or VSAM data spaces that can reside on a volume and is therefore
essential information for the DADSM routines that allocate and
release space.

The types of direct-access storage devices supported by this
operating system and the number of DSCBs that will fit on a single
track of each type, are:

Direct-Access Device Type

Number of

DSCBs per'

Track

IBM 2305-1 Fixed Head storage

la/track

IBM 2305-2 Fixed Head storage

34/track

IBM 2314 Direct-Access Storage Facility

25/track

IBM 2319 Disk storage

25/track

IBM 3330 Disk Storage, models 1 and 11

39/track

IBM 3333 Disk Storage and Control, models 1 and 11

39/track

IBM 3340 Direct Access Storage Facility

27/track

IBM 3344 Direct Access Storage

27/track

IBM 3350 Direct Access Storage

47/track

IBM 3375 Direct Access Storage

51/track

IBM 3380 Direct Access Storage

53/track

/'",

The DS4DSREC field of the format-4 DSCB contains a count of the
number of free VTOC records (format-O DSCBs) in the VTOC. This
count is checked before each allocation. There must be enough free
VTOC records for all the DSCBs required to define the data set or
VSAM data space, as well as an extent or a combination of extents
large enough to contain the data set or VSAM data space. The
number of DSCBs needed to define a single data set or VSAM data
space can be one, two, or three, depending on (1) whether it is an
ISAM data set (a format-2 may be required) and (2) whether the
data set has more than three extents (a format-3 DSCB is needed to
list the fourth through the sixteenth extent). In addition, the
DADSM Allocate routines make sure there is room for an additional
format-5 in case it is necessary to create one during the
allocation.

VOLUME TABLE OF CONTENTS INTEGRITY
In an operating system with only one processor, two or more tasks
may require access to the same VTOC simultaneously for the purpose
of reading or updating (that is, adding, deleting, or modifying
DSCBs) that VTDC. If more than one processor has access to the
same device or devices, it becomes necessary to 'protect VTOCs from
being accessed while the DADSM routines are in process.
To be sure that a VTOC is not changed while the DADSM routines are
in process, the DADSM rout i nes issue RES ERVE, ENQ, and DEQ macro
instructions. These macro instructions provide exclusive control
of the VTOC for the task issuing the macro instruction. The
152

OS/VS2 System Programming Library: Data Management

('"

RESERVE macro instruction is needed for systems in which two or
more processors are processing concurrently, using the same data
sets. These macro instructions provide exclusive control of the
VTOC for the task issuing the macro instruction. Depending on the
macro instruction, the "set-must-complete" option or the
"release-must-complete" opt; on may be speci fi ed in an operand of
the macro instruction. The Allocate, Extend, Scratch, Rename,
Partial Release, LSPACE, and Protect routines of DADSM issue
these macro instructions. Of these routines, only Allocate,
Scratch, and Partial Release use S~1C=STEP in the ENQ and RESERVE
macros, and RMC=STEP in the DEQ macro. The Extend routine linKs to
the status rout i ne (rather than i ssu i n9 the EttQ macro) to obta in
"step-must-complete" status, if the task that called Extend has
not already done so.
The MVS catalog management routines modify the DS4AMCAT and
DS4AMTIM fields of the VTOC (format-4) DSCB. These routines also
issue the RESERVE, ENQ, and DEQ macro instructions to maintain
exclusive control while making modifications.

Note: When operating in an environment in which direct-access

storage devices are not shared among systems, the RESERVE macro
instruction defaults to (acts as) an ENQ macro instruction.

DADSM Interrupt Recording Facility (DIRFJ
If a system fails or a permanent I/O error occurs during
allocation of space or during a routine that updates the VTOC, the
VTOC will probably be in error. To make sure the error is
recorded, the DADSM routines use the DADSM interrupt-recording
facility (DIRF). DIRF processing involves turning on a bit in the
VTOe at entry to the DADSM function, and if no I/O errors occur
during DADSM processing, turning it off again at exit from that
function.
This bit is called the DIRF bit and is bit 5 of the DS4VTOCI field
of the format-4 DSCB. The Scratch and Partial Release routines
also turn on the DIRF bit jf they encounter overlapping extents in
a format-5 DSCB.
The next time an attempt is made to allocate space on a volume
that has the DIRF bit set, the VTOC Conversion routine is invoked
by Allocate or Extend, whichever is attempting to allocate more
space on the volume. The VTOC Conversion routine builds new
format-5 DSCBs to represent the available space on the volume,
updates the format-4 DSCB, and returns to Allocate or Extend to
continue the allocation. The "Diagnostic Aids" section of OS/VS2
DADSM l09i~ tells how to deactivate the VTOC conversion by
altering the DADSM routines.

Controlling Space on DASD Volumes

153

SPECIFYING BUFFER NUMBERS FOR SAM-E DASD DATA SETS

The BUFNO keyword in the DCB macro and the BUFNO 5ubparameter of
the DCB keyword in the DD statement determine how many buffers are
allocated when accessing a partitioned or sequential data set
using QSAM. The NCP keyword in the DCB macro determines how many
un-CHECKed READ or WRITE macro instruct ions are allo,,,ed when
accessing a sequential or partitioned data set using BSAM; one
buffer is used for each READ or WRITE macro instruction.
The sequential access method with SAM-E can construct a channel
program to transfer up to 30 buffers or 240,000 bytes of data,
whichever is less. If BUFNO or NCP is less than 30, no more than
that number of buffers can be transferred with a single channel
program.
BUFNO is defaulted in OPEN to 5 if it is not specified for a QSAM
DCB; NCP is defaulted to 1 in OPEN if it is not specified. The
QSAM access method manages buffers. The user program must manage
buffers when it uses BSAM.

PERFORMANCE CONSIDERATIONS
Buffer number and block size influence the rate with which data
can be transferred and the operating system overhead per block.
The use of more buffers reduces (per block transferred) the EXCP
and lOS overhead and the time waiting for the DASD device to seek
to the requested cylinder and rotate to the requested record
(device latency time). However, if more buffers are allocated
than a program can effectively process, the virtual pages
containing those buffers will be paged out, effectively adding to
the s~'stem overhead for the job. A large number of buffers also
cause a large amount of real storage to be allocated to the job
while the data is being transferred.
A job in a low-performance group may get swapped out more
frequently than a higher priority job. The number of buffers
allocated for the job contributes to the number of pages which
have to be swapped out.
Programs which access data sets with small block size (for
example, 80) can ea~ily make effective use of 30 buffers which fit
in, at most, two 4096-byte pages. The advantage of 30 buffers over
the default of five buffers is great: one channel program versus
six channel programs to transfer 30 blocks.
At the other end of the spectrum, usage of data sets with large
blocking f~ctors such as full-track blocking on 3350 or
half-track blocking on 3380 can still be effective when only 3 or
4 buffers, rather than 5 or more, are specified. The slightly
lower DASD performance and small increase in EXCP and lOS
instruction costs should be more than offset by a reduction in
paging or swapping in a constrained environment.
I t can be seen that proper select i on of buffer number can have a
positive effect on the elapsed time of a job and the system
overhead associated with the job. The DCB OPEN installation exit
(available in SAM-E Enhancements) can use installation criteria
to a default buffer number for QSAM DCBs. The NCP field of the DCB
must be set by the program for BSAM DCBs.

154

OS/VS2 System Programming Library: Data Management

/,"-,

c
•

ABE

54-55
appendage 54-55
access method routines, functions
performed in I/O operations 44
alias name
entry 32
of UCS images for JES2 139
use in retrieving catalog
information 7-8
allocate routine 145
alternate track, assigning 68-69
AM operand of DEBCHK macro 118
appendages
abnormal-end (ABE) 54-55
channel-end (CHE) 53
end-of-extent (EOE) 53
entry points 51
listing in SYS1.PARMLIB ·56
naming convention 56
page fix 79
PCI 51
programming restrictions 51
register usage 51
returns 51
start-I/O (SIO) 51
assigning alternate track 68-69
ATLAS macro instruction
coding example 70
how to use 69
operations performed 70
return codes 70-72
specification 68-69
with track overflow option 68
authorized appendage list 56-57
appenda~e

abnorm~1-end

BALANCE operand of TRKCALC macro
128, 129
BFALN operand of DCB macro 61
BFTEK operand of DCB macro 61
block multiplexor programming
notes 57-58
BUFCB operand of DCB macro 62
BUFL operand of DCB macro 61
BUFNO operand of DCB macro 61

CAMLST macro
with BLDA operand 14
with BLDG operand 11
with BLDX operand 9
with BLOCK operand 8
wi th CA T (DX) operand 19
wi th DLTA operand 15
wi th DLTX operand 13

125,

with DRPX operand 17
with LNKX operand 16
with RECAT operand 22
with UNCAT operand 21
catalog
dummy module 143
entry format 2
master 1, 2
order of search 1
private 2
user 1
CATALOG and CAMLST macro instructions
with CATCBX) operand 19
with RECAT operand 22
with UNCAT operand 21
catalog maintenance
using CATALOG macro 19-23
using LOCATE macro 3-9
cataloging non-VSAM data sets
coding example 20
macro specifications 19
return codes 20
CCW (channel command word) 48, 79, 81
See also channel program
translation, virtual addresses to
real addresses 48, 79-81
CENDA operand of DCB macro 60
channel program
appendages used l·Ji th 50
execution 47-48
initiation 47-48
related 50
restrictions or modification 48
translation 79-81
channel-end appendage 53
CHE appendage 53
checking the DEB 117-120
checkpointed data sets, processed with
EXCP macro 63
CLOSE macro instruction
used with EXCP macro 73
used with XDAP macro 86
CODE-operand of DCB macro 64
command retry 57
communication vector table (CVT) mapping
macro 104
completion codes 77, 87
See also return codes
following use of EXCP macro 77
fol101"ing use of XDAP macro 87
control blocks
DCB 47, 58
DEB 47
ECB 47,76
FCB 130-135
general description 47
lOB 47, 73-76
PIRL 49, 123
control password 91, 95
control volume pointer entry 30
conversion
actual device address to relative
track address 89
of sector value for RPS devices 89
relative track address to actual
device address 88
creating protected data sets 93
Inde><

155

CVOl
in CAMlST macro 2
order of searching 2
pointer entry 30
CVT (communication vector table) mapping
macro 104

DADSM routines 33, 145-153
data extent block (DEB)
use with EXCP macro 47
validating 116-120
data set control block
See DSCB
data set pointer entry 27
data set security
See password protection
DCB fields used with EXCP macro 58-65
DCBDIRCT field of DCB 61
DCBFDAD field, maintaining 61
DCBIFlGS field of DCB, permanent I/O
error indicators 49
DCBOFlGS field of DCB, meanings of bit
settings 72-73
DCBTRBAl field, maintaining 62
DO operand of TRKCALC macro 126, 129
DDNAME operand of DCB macro 60
ODR (dynamic de.vice reconfiguration),
repositioning t~pe data sets 60
DEB (data extent block)
use with EXCP macro 47
validating 116-120
DEBCHK macro instruction
functions of 117-120
specification 117-120
defective track
See assigning alternate track
define extent command 48
deleting a data set
coding example 38
macro instructions for 37-39
return codes 39
when volume not mounted 37
with password protection 39
DEN operand of DCB macro 64
DEQ
at demount facility 112
DEVD operand of DCB macro 62-63
device characteristics 105-110
device-dependent parameters in
DCB 62-64
DEVTAB operand of TRKCAlC macro 125, 128
DEVTYPE macro instruction
for RPS devices 105
output from 105-110
specification 105
direct-access device, channel program
(XDAP macro) 82-85
DSCB, reading from VTOC
by actual device address
coding example 36
macro specifications 35
return codes 36
by data set name
coding example 34
macro specifications 34
return codes 35
format 0-6 145-153
missing format-l 141
156

DSECT expansions
See CVT,IEFJFCBN, IEFUCBOB,TRKCAlC
DSORG operand of DCB macro 61, 62-63

ECB fields
used with EXCP macro 76
used wi th XDAP macro 86
end-of-extent appendage 53
end-of-volume
macro instruction 72-73, 86
ENQ 152
EODAD operand of DCB macro 61
EOE appendage 53
EOEA operand of DCB macro 60
EOV (end-of-volume) macro instruction
and mi:sing DSCB 141
used with EXCP macro 72-73
used with XDAP macro 86
error recovery procedures 49
event control block (ECB) fields
used with EXCP macro 76
used with XDAP macro 86
EXCP macro instruction
control blocks used with
DCB 58-65
DEB 76
ECB 76
lOB 73-76
in nonpageable address space 46
in problem programs 45
in real storage 77
in system control programs 44
macro specification 67
macros used loJi th
ATLAS 68-72
CLOSE 73
EOV 72-73
OPEN 65-67
multivolume data set requirement 67
EXCPVR macro instruction 77-78
executing channel programs
in problem programs 45
in real storage 77
in system control programs 44
exit
list entry for RDJFCB 110
used for missing DSCB 141
EXlST operand of DCB macro 60
expiration date, overriding 38
EXT END opt ion
OPEN macro 65, 112
routine 145

FCB (forms control buffer) image
adding image to
SYSl.IMAGELIB 130-135
how to modify before loading 135
JES2 Support 139
retrieving 136
rules 130-132
sample of 135
fixing data areas with EXCPVR 78
format 0-6 DSCB 145-153

OS/VS2 System Programming Library: Data Management

format-1 DSCB
missing 141
reading from VTOC 34
forms control buffer
See FeB image
foundation block of DCB 60
FUHCTN operand of TRKCALC macro

125-129

generation data set name, use in
retrieving catalog information 5
generation index pointer entry 31

I/O appendages
See appendages
I/O device characteristics 105-110
IDAL (indirect address list) 79-81
IEAAPPOO, authorized appendage list 56
IEBUPDTE utility
SYS1.PARMLIB 56-57
use in listing appendages in 56
IECPCNVT (relative track address to
actual device address conversion
routine) 88
IECPRLTV (actual device address to
relative track address conversion
routine) 89
IECOSCRI (sector conversion routine) 89
IEFJFCBN macro instruction 104
IEFUCBOB macro instruction 103
IEHATLAS utility program 70
IEHDASDR 145
IMGLIB macro instruction 136
IMSK operand of DCB macro 60
index
control entry 25
link entry 26
pointer entry 26
INDEX and CAMLST macro instructions
with BLDA operand 14-15
with BLDG operand 11-13
with BLDX operand 9-11
with DLTA operand 15-16
with DLTX operand 13-14
with DRPX operand 17-18
with LNKX operand 16-17
indexing feature for 3211 139
indirect address list (IDAL) 79-81
initializing a DASD volume 145
interruption handling procedures 49
lOB fields
used with EXCP macro 73-76
used with XDAP macro 86
lOB-chain modification 123
IOBAD operand of DeB macro 61
10BSENS fields with ATLAS macro 69

JES2 printer support 139-140
JES3
RENAME return code 42
SCRATCH return code 39
JFCB (job file control block) 104, 110,
111, 113, 114, 116
See also RDJFCB macro instruction
macros used wi th
OPEN 113
RDJFCB 114-116
mapping macro 104
modifying 111-113
processlng 110-113
job file control block
See J FCB

K operand of TRKCALC macro 126, 129
KEYLEN.operand of DCB macro 63

LABEL operand of DD statement
operand of CVT macro 104
operand of IEFJFCBN macro 104
operand of IEFUCBOB macro 103
password protected data set 92, 93
library character set modules 130
LIST
operand of CVT macro 104
operand of IEFJFCBN macro 104
operand of IEFUCBOB macro 103
LOCATE and CAMLST macro instructions
retrieving catalog information
by al i as name 7-8
by data set name 3-4
by generation name 5-7
by relative block address 8-9
locate record command 48

MACRFE=(E) operand of DCB macro 60
macros
ATLAS 68-72
CATALOG 19-23
CLOSE
used with EXCP macro 73
used with XDAP macro 86
CVT 104
DCB 58, 65
DEBCHK 117-120
DEVTYPE 105-110
EOV
and missing DSCB 141
used with EXCP macro 72-73
used with XDAP macro 86
EXCP 67
EXCPVR 77-78
Index

157

IEFJFCBN 104
IEFUCBOB 103
INGLIB 136
LOCATE 2-4
OBTAIN 33-36
OPEN
and missing DSCB 141
for JFCB 113-116
used with EXCP macro 65-67
PROTECT 95-102
PURGE 120-123
RDJFCB 110-116
RENAME 40-43
RESTORE 120-121, 124
SCRATCH 37-39
TRKCALC 124-129
used with XDAP macro 82
XDAP 82-85
maintaining 33, 43, 95, 102
See also PROTECT macro instruction
PASSWORD data set 95-102
volume table of contents
(VTOC) 33-43
mapping macros
CVT 104
IEFJFCBN 104
IEFUCBOB 103
TRKCALC 129
master catalog 2
MAXSIZE operand of TRKCALC macro 126,
128
MF
operand of DEBCHK macro 119
operand of TRKCALC macro 126-129
MODE operand of DCB macro 64
modifying
channel program during execution 48
FCB image 136
rOB chain 123
JFCB 111-113
multivolume data set, processing with
EXCP macro "66

nonpageable address space, EXCP
operations 1n 46
NOPWREAD 92, 93, 96
NOWRITE 92, 96

OBTAIN macro instruction 33-35
obtaining a sector number (RPS
devices) 89
OPEN m~cro instruction
and DEQ at Demount 112
and mi ssi ng DSCB 141
TYPE=J
example 66
invoking 112
specification 113
used with EXCP macro
dummy data set restriction
label processing 65
procedures performed 65

158

volume disposition 65
used with XDAP macro 83
opening a VTOC, restriction on changing
contents 115
OPENJ (OPEN, TYPE=J)" 113
OPTCD=Z operand of DCB macro 60
OUTINX option, OPEN macro 61, 112
output data sets, maintaining DCBBLKCT
field 60

page boundaries 79
page fi x
appendage 79
list 79
password
control 95
parameter list
add a record 102
delete a record 100
list a record 101
replace a record 99
protection mode indicator 95
record 93
secondary 95
standard label restriction 91
PASSWORD data set
characteristics 92
creating 93
password protecting data sets 91-102
password-protection
counter maintenance 94
data set concatenation 94
termination 93
volume switching 94
PCI (program controlled interruption)
appendage 51
operand of DCB macro 60
PCIA operand of DCB macro 60
PGFX appendage 79
PIRL (purged I/O restore list)
use in restoring I/O ~equests 49,
123, 12(t
posting completion code in ECB
following use of EXCP macro 76
following use of XDAP macro 86
PREFIX operand of IEFUCeOB macro 103
printer image
forms control buffer (FCB) 131-132
universal character set CUCS) 130
private catalog 2
program controlled interruption (PCI)
appendage 51
PROTECT macro instruction
parameter list 102
return codes 102
specification 96
protection mode indicator 9~
PRTSP operand of DCB macro 64
PURGE macro instruction
adding to macro library 120
definition 120
parameter list 122, 123
return codes 123
specification 122
purged I/O restore list 49, 122, 124
PWREAD 92, 96
PWWRITE 92, 93, 96

OS/VS2 System Programming library: Data Management

RKDD operand of TRKCALC macro 126, 128
RPS
G')
()
I'V
(j)

---.--------- ---

-~-y-

(!)

International Business Machines Corporation
Data Processing Division
1133 Westchester Avenue White Plains, N.Y. 10604
IBM World Trade Americas/Far East Corporation
Town of Mount Pleasant, Route 9, North Tarrytown, N.Y., U.S.A. 10591
IBM World Trade Europe/Middle East/Africa Corporation
360 Hamilton Avenue, White Plains, N.Y., U.S.A. 10601

.i::.

Reader's
Comment
Form

OS/VS2 System
Programming Library:
Data Management
GC26-3830-4

This manual is part of a library tha t serves as a reference source for systems analysts, programmers, and operators of
IBM systems. You may use this form to communicate your comments about this publication, its organization, or
subject matter, with the understanding that IBM may use or distribute whatever information you supply in any way
it believes appropriate without incurring any obligation to you.
Your comments will be sent to the author's department for whatever review and action, ifany, are deemed
appropriate. Comments may be written in your own language; English is not required.
Note: Copies of IBM publications are not stocked at the location to which this form is addressed. Please direct any

requests for copies ofpublications, or for assistance in using your IBM system, to your IBM representative or to
the IBM branch office serving your locality.

List TNLs here:
If you have applied any technical newsletters (TN Ls) to this book, please list them

h~re:

Last TNL _ _ _ _ _ _ _ _ __
Previous TNL

-------------------

Previous TN L ___________________

Fold on two lines, tape, and mail. No postage stamp necessary if mailed in the U.S.A.
(Elsewhere, an IBM office or representative will be happy to forward your comments or you
may mail directly to the address in the Edition Notice on the back of the title page.) Thank
you for your cooperation.

GC26-3830-4

Reader's Comment Form

c
~

0
en
.......

<
en
J\.)
en

Please do not staple

Fold and tape

-<
(f)

r-+
Cl)

3
""C

~
Q)

IIIII1

BUSINESS
FIRST CLASS

PERMIT NO. 40

NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

3
3

(.Q

C
0....
Q)

-<
0

MAIL

r-+
Q)

ARMONK, N.Y.

POSTAGE WILL BE PAID BY ADDRESSEE

~r'
Cl)

g",
~

r-+

IBM Corporation
P.O. Box 50020
Programming Publishing
San Jose, California 95150

CD
Z

?
en
w
-....J
0

.9
""C

........................................................................................................................
Please do not staple

Fold and tape

~.
~

r-+
Cl)

c..
~

en
~

G)
()
J\.)
(j)

- - ------------.
_w-r_
----.
------_.---_-~.. -

CX)

{~)

International Business Machines Corporation
Data Processing Division
1133 Westchester Avenue, White Plains, N.Y. 10604
IBM World Trade Americas/Far East Corporation
Town of Mount Pleasant, Route 9, North Tarrytown, N.Y., U.S.A. 10591
IBM World Trade Europe/Middle East/Africa Corporation
360 Hamilton Avenue, White Plains, N.Y., U.S.A. 10601

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-c041 52.342996, 2008/05/07-21:37:19
Create Date                     : 2017:11:26 11:43:41-08:00
Modify Date                     : 2017:11:26 12:01:40-08:00
Metadata Date                   : 2017:11:26 12:01:40-08:00
Producer                        : Adobe Acrobat 9.0 Paper Capture Plug-in
Format                          : application/pdf
Document ID                     : uuid:989227ba-c0be-0843-93e2-defd8665476d
Instance ID                     : uuid:00aa56f5-69e9-7a4e-b398-007da917c49a
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 178

EXIF Metadata provided by EXIF.tools

GC28 3830 4_OS_VS2_3.8_System_Programming_Library_Data_Management_Oct1981 4 OS VS2 3.8 System Programming Library Data Management Oct1981

Navigation menu

Versions of this User Manual:

Views

Navigation