GC26 3793 1_OS_VS_Data_Management_Macro_Instructions_Sep72 1 OS VS Data Management Macro Instructions Sep72

User Manual: GC26-3793-1_OS_VS_Data_Management_Macro_Instructions_Sep72

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

Download
Open PDF In Browser	View PDF

GC26-3793-1

Systems

OS/ VS Data Management
Macro Instructions
VS1 Release 2
VS2 Release 1

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

Second Edition (September 1972)

This edition, as amended by technical newsletter GN26-0748, applies both to Release 2 of OS/VS1
and to Release 1 of OSNS2, and to all subsequent releases of either system unless otherwise
indicated in new editions or technical newsletters.
Significant system changes are summarized under "OS/VS1 Summary of Changes" or "OSNS2
Summary of Changes" following the Preface.

Information in this publication is subject to significant change. Any such changes will be published
in new editions or technical newsletters. Before using the publication, consult the latest IBM SRL
Newsletter, GN20.0360, that amends IBM Systemj360 and Systemj370 Bibliography, GA22-6822,
to learn which editions and technical newsletters are applicable and current.
Requests for copies of IBM publications should be made to the IBM branch office that serves you.
Forms for readers' comments are provided at the back of this publication. If the forms have been
removed, comments may be addressed to IBM Corporation, Programming Center-Publishing,
Department 058, Monterey and Cottle Roads, San Jose, California 95114. All comments become
the property of IBM.

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

PREFACE
This publication contains descriptions and definitions for the data management macro
instructions available in the assembler language. It provides application and system
programmers with the necessary information to code the macro instructions.
Most of the information in this book applies to both OS/VSl and OS/VS2.
Information that applies only to OS/VSl or OS/VS2 is explicitly identified in the text.
This publication is divided into these parts:
"Introduction," which contains a general description of macro instructions, the rules
to be followed when macro instructions are coded, and a description of the
notational conventions used throughout the publication.
•

"Macro Instruction Descriptions," which describes the function of each macro
instruction and defines how each macro instruction is to be coded. The macro
instructions are presented in alphabetic order with each macro instruction beginning
on a right-hand page. The standard form of each macro instruction is described
first, followed by the description of the list and execute form instruction; the list
and execute forms are available only for those macro instructions that pass
parameters in a list.

•

"Appendix A: Status Information Following an Input/Output Operation," which
includes information about error indications available following an input/output
operation.

•

"Appendix B: Data Management Macro Instructions Available by Access
Methods," which lists the macro instructions available for each of the data
management access methods.

•

"Appendix C: Device Capacities," which lists device capacities that can be used as
a guide when coding the blocksize and logical record length operands in the DCB
macro instruction.

•

"Appendix D: DCB Exit List Format and Contents," which describes the format
and content of the data control block exit list.

•

"Appendix E: Control Characters," which contains information about the control
characters used to control spacing and skipping (printers) and stacker selection
(card read punch or card punch).

•

"Appendix F: Data Control Block Symbolic Field Names," which lists the location,
alignment, and description of the data control block symbolic field names.

•

"Appendix G: Event Control Block," which lists the location, alignment, and
description of the event control block symbolic field names.
"Index," which provides topic references to information in this book.

Prerequisite Publications
Before coding data management macro instructions, you should be familiar with the
information in the following publications:
• OS/VS and DOS/VS Assembler Language, GC33-4010
• OS/VS Data Management Services Guide, GC26-3783
• OS/VS Supervisor Services and Macro Instructions, GC27-6979

Preface iii

Related Macro Instruction Publications
The following publications contain descriptions of macro instructions for specialized
applications such as teleprocessing, graphics, and magnetic/optical character
recognition devices:
• OS/VS BTAM, GC27-6980
OS Data Management Services and Macro Instructions for IBM
1285/1287/1288, GC21-S004
• OS Data Management Services and Macro Instructions for IBM 1419/1275,
GC21-S006
• OS/VS Graphic Programming Services (GPS) for IBM 2250 Display Unit,
GC27-6971
• OS/VS Graphic Programming Services (GPS) for IBM 2260 Display Station
(Local Attachment), GC27-6972

Related System Publications
This book refers to other publications that contain additional information about the
operating system. Depending on the requirements of the individual installation, an
application or system programmer may need these publications to code programs
for the data management access methods.
In the list that follows, books designated OS/VS apply to both VSl and VS2; books
designated OS/VSl apply only to VSl; and books designated OS/VS2 apply only to
VS2.
• OS/VS Checkpoint/Restart, GC26-3784
• OS/VS Data Management for System Programmers, GC28-0631
• OS/VS1 Debugging Guide, GC24-S093
• OS/VS2 Debugging Guide, GC28-0632
• OS/VS Linkage Editor and Loader, GC26-3813
• OS/VS1 System Generation Reference, GC26-3791
• OS /VS2 System Generation Reference, GC26-3792
• OS/VS Utilities, GC3S-000S

iv OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

OS/VSl SUMMARY OF CHANGES

Release 2
New Devices
•

The 3505 Card Reader and the 3525 Card Punch are now supported by VS1; the
macro instructions affected by this change are CLOSE, CNTRL, DCB (BSAM and
QSAM), OPEN, and PRTOV.

•

The 2305-1 Drum Storage and the new 3333 Disk Storage are also now supported
by VS 1; capacity data for these devices has been added to the tables in Appendix
C.

•

DEB validity checking, a data protection feature formerly supported only by VS2, is
now supported by VS 1; this change affects the OPEN macro instruction.

New Function

Miscellaneous Changes
•

Describe register contents upon entry to an EODAD routine (DCB macro
instruction for BPAM, BSAM, QISAM, and QSAM).

•

Restrict use of the temporary close (TYPE=T) option in a SYNAD routine
(CLOSE macro instruction).

•

Expand the description of the LEAVE option (FEOV macro instruction for BSAM
and QSAM).

•

Define a new return code for the CHKPT macro instruction.

•

Delete tape labels as a source of buffer alignment (BF ALN) data (DCB macro
instruction for all access methods).

OS/VS 1 Summary of Changes v

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

CONTENTS
Page

iv
iv

Preface
Prerequisite Publications
Related Macro Instruction Publications
Related System Publications

v
v
v
v
v

OSNSI Summary of Changes
Release 2
New Devices
New Function
Miscellaneous Changes

iii
iii

Figures

1
1
1
2
4
5

Introduction
Data Management Macro Instructions
Coding Aids
Coding Macro Instructions
Rules for Register Usage
Rules for Continuation Lines

7
9
13
15
17
19
21
23
25
29
31
33
37
39
41
45
53
59
67
83
93
109
111
113
115

Macro Instruction Descriptions
BLDL - Build a Directory Entry List (BP AM)
BSP - Backspace a Physical Record (BSAM - Magnetic Tape and Direct
Access Only)
BUILD - Build a Buffer Pool (BDAM, BISAM, BP AM, BSAM,
QISAM, and QSAM)
BUILDRCD - Build a Buffer Pool and a Record Area (QSAM)
BUILDRCD - List Form
BUILDRCD - Execute Form
CHECK - Wait for and Test Completion of a Read or Write Operation
(BDAM, BISAM, BPAM, and BSAM)
CHKPT - Take a Checkpoint for Restart Within a Job Step (BDAM,
BISAM, BP AM, BSAM, QISAM, and QSAM)
CHKPT - List Form
CHKPT - Execute Form
CLOSE - Logically Disconnect a Data Set (BDAM, BISAM, BPAM,
BSAM, QISAM, and QSAM)
CLOSE - List Form
CLOSE - Execute Form
CNTRL - Control Online Input/Output Device (BSAM and QSAM)
DCB - Construct a Data Control Block (BDAM)
DCB - Construct a Data Control Block (BISAM)
DCB - Construct a Data Control Block (BP AM)
DCB - Construct a Data Control Block (BSAM)
DCB - Construct a Data Control Block (QISAM)
DCB - Construct a Data Control Block (QSAM)
DCBD - Provide Symbolic Reference to Data Control Blocks
(BDAM, BISAM, BPAM, BSAM, QISAM, and QSAM)
ESETL - End Sequential Retrieval (QISAM)
FEOV - Force End of Volume (BSAM and QSAM)
FIND - Establish the Beginning of a Data Set Member (BP AM)
Contents vii

Page
117
119
121
123
125
127
129
131
133
137
139
141
143
145
147
149
151
155
157
159
161
163
165
167
169
171
175
177
179
183
187
189
191
195
197
199
203
205

FREEBUF - Return a Buffer to a Pool (BDAM, BISAM,
BP AM, and BSAM)
FREEDBUF - Return a Dynamically Obtained Buffer (BDAM
and BISAM)
FREEPOOL - Release a Buffer Pool (BDAM, BISAM, BPAM, BSAM,
QISAM, and QSAM)
GET - Obtain Next Logical Record (QISAM)
GET - Obtain Next Logical Record (QSAM)
GETBUF - Obtain a Buffer (BDAM, BISAM, BPAM, and BSAM)
GETPOOL - Build a Buffer Pool (BDAM, BISAM, BP AM, BSAM,
QISAM, and QSAM)
NOTE - Provide Relative Position (BP AM and BSAM - Tape and Direct
Access Only)
OPEN - Logically Connect a Data Set (BDAM, BISAM, BPAM,
BSAM, QISAM, and QSAM)
OPEN - List Form
OPEN - Execute Form
POINT - Position to a Relative Block (BP AM and BSAM - Tape
and Direct Access Only)
PRTOV - Test for Printer Carriage Overflow (BSAM and QSAM - Online
Printer and 3525 Card Punch, Print Feature)
PUT - Write Next Logical Record (QISAM)
PUT - Write Next Logical Record (QSAM)
PUTX - Write a Record From an Existing Data Set (QISAM and QSAM)
READ - Read a Block (BDAM)
READ - Read a Block of Records (BISAM)
READ - Read a Block (BP AM and BSAM)
READ - Read a Block (Offset Read of Keyed BDAM Data Set Using
BSAM)
READ - List Form
READ - Execute Form
RELEX - Release Exclusive Control (BDAM)
RELSE - Release an Input Buffer (QISAM and QSAM Input)
SETL - Set Lower Limit of Sequential Retrieval (QISAM Input)
SETPRT - Load UCS and FCB Images (BSAM and QSAM)
SETPRT - List Form
SETPRT - Execute Form
STOW - Update Partitioned Data Set Directory (BP AM)
SYNADAF - Perform SYNAD Analysis Function (BDAM, BISAM, BPAM,
BSAM, QISAM, and QSAM)
SYNADRLS - Release SYNADAF Buffer and Save Areas (BDAM, BISAM,
BP AM, BSAM, QISAM, and QSAM)
TRUNC - Truncate an Output Buffer (QSAM OutputFixed- or V ariable-Length Blocl~ed Records)
WRITE - Write a Block (BDAM)
WRITE - Write a Logical Record or Block of Records (BISAM)
WRITE - Write a Block (BPAM and BSAM)
WRITE - Write a Block (Create a BDAM Data Set with BSAM)
WRITE - List Form
WRITE - Execute Form

viii OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

Page
207

XLATE - Translate to and from ASCII (BDAM, BISAM, BP AM,
BSAM, QISAM, and QSAM)

209
209

Appendix A: Status Information Following an Input/Output Operation
Data Event Control Block

219

Appendix B: Data Management Macro Instructions Available by Access
Method

221

Appendix C: Device Capacities

223

Appendix D: DCB Exit List Format and Contents

225

Appendix E: Control Characters

227

Appendix F: Data Control Block Symbolic Field Names

241 ;' Appendix G: Event Control Block
243

Index

Contents ix

Page of GC26-3793-1
Revised December 15,1972
By TNL GN26-0748

FIGURES
Page

210
212
214
215
215
216

Figure
Figure
Figure
Figure
Figure
Figure

4.
5.
6.

217

Figure

1. Exception Code Bits -

BISAM
QISAM
Exception Code Bits - BDAM
Register Contents on Eutry to SYNAD Routine - QISAM
Register Contents on Entry to SYNAD Routine - BISAM
Register Contents on Entry to SYNAD Routine - BDAM,
BPAM, BSAM, and QSAM
Status Indicators for the SYNAD Routine - BDAM,
BP AM, and BSAM

2. Exception Code Bits 3.

Figures xi

HOW OS/VS MACROS DIFFER FROM OS/MFf AND OS/MVT
MACROS
The functional differences between VS and MFT and MVT macros are minimal. The
HIARCHY operand (DCB and GETPOOL macro instructions), which in MFT and
MVT allows you to specify the storage hierarchy in which a buffer pool is constructed,
is not necessary in VS because of the pageable storage feature in VS.

How OS/VS Macros Differ from OS/MFT and OS/MVT Macros xiii

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

INTRODUCTION
Data Management Macro Instructions
A set of macro instructions is provided by IBM for communicating service requests to
the data management access method routines. These macro instructions are available
only when the assembler language is being used, and they are processed by the
assembler program using macro definitions supplied by IBM and placed in the macro
library when the operating system is generated.
The processing of the macro instruction by the assembler program results in a macro
expansion, generally consisting of executable instructions and data in the form of
assembler-language statements. The data fields are the parameters to be passed to the
access method routine; the executable instructions generally consist of a branch around
the data fields, instructions to load registers, and either a branch instruction or
supervisor call (SVC) to give control to the proper program. The exact macro
expansion appears as a part of the assembler listing.
A listing of a macro definition from SYS 1.MACLIB (the library in which macro
definitions are stored) can be obtained by using the utility program IEBPTPCH, which
is described in OS /VS Utilities.
Before macro instructions are coded using this publication, the user should be familiar
with the information contained in OS/VS Data Management Services Guide.
When programs that request supervisor services are being coded, the user should be
familiar with the information contained in OS /VS Supervisor Services and Macro
Instructions.
When programs are being coded for more specialized applications such as
teleprocessing, graphics, and character recognition, the publication that describes the
specific access method and/or device type should be used. Publications containing
descriptions of the macro instructions for teleprocessing, graphics, and character
recognition devices are listed in the preface of this publication.
The operation of some macro instructions depends on the options selected when the
macro instruction is coded. For these macro instructions, either separate descriptions
are provided or the differences are listed within a single description. If no differences
are explicitly listed, none exist. The description of each macro instruction starts on a
right-hand page; the descriptions that do not apply to the access methods being used
can be removed. Appendix B provides a list of the macro instructions available for
each access method.

Coding Aids
The symbols [ ], { }, and ,... are used in this publication to help defined the macro
instructions. These symbols are not coded; they are only to indicate how a macro
instruction may be written; their general definitions are given below:
[]

indicates optional operands. The operand enclosed in the brackets mayor may
not be coded, depending on whether or not the associated option is desired.
If more than one item is enclosed in brackets, for example, [REREAD], one
[LEAVE]
or none of the items may be coded.

Introduction 1

{}

indicates that a choice must be made. One of the operands from the vertical
stack within braces, for example, {INPUT}, must be coded, depending on
{OUTPUT}
which of the associated services is desired.
indicates that more than one set of operands may be designated in the same
macro instruction.

Coding Macro Instructions
Data management macro instructions are written in the assembler language and, as
such, are subject to the rules contained in OS/VS and DOS/VS Assembler Language.
Data management macro instructions, like all assembler language instructions, are
written in the following format:
Name

Operation

Operands

symbol
or
blank

Macro name

None, one or more operands separated
by commas

Comments

The operands are used to specify services and options to be used and are written
according to the following general rules:
• If the selected operand is shown in bold capital letters (for example, MACRF=WL),

code the operand exactly as shown.
• If the selected operand is a character string in bold type (for example, if the type

operand of a READ macro instruction is SF), code the operand exactly as shown.
• If the operano is shown in italic lowercase letters (for example, deb address),

substitute the indicated address, name, or value.
• If the operand is a combination of bold capital letters and italic lowercase letters (for
example, LRECL= absexp), code the capital letters and equal sign exactly as shown

and substitute the apporpriate address, name, or value for the italic lowercase letters.
• Commas and parentheses are coded exactly as shown, except that the comma
following the last operand coded should be omitted. The use of commas and
parentheses is indicated by brackets and braces in the same manner as brackets and
braces indicate the use of operands.
• Several macro instructions contain the designation'S'. This operand, when used,
must have the apostrophe on both sides of the S.
When substitution of a name, value, or address is required, the notation used to specify
the operand depends on the operand being coded. The following shows two examples
of the notations used to indicate how an operand can be coded.
DDNAME= symbol
In the above example, the only type of operand that can be coded is a valid
assembler-language symbol.

2 OS/VS Data Management Macro Instructions

deb address -

RX-Type Address, (2-12), or (1)

In the above example, the operand that can be substituted can be an RX-type address,
any of the general registers 2 through 12,. or general register 1.
The following describes the meaning of each notation used to show how an operand
can be coded.
symbol
When this notation is shown, the operand can be any valid assembler-language symbol.
decimal digit
When this notation is shown, the operand can be any decimal digit up to the maximum
value allowed for the specific operand being described.
(2-12)
When this notation is shown, the operand specified can be any of the general registers
2 through 12. All registers as operands must be coded in parentheses; for example, if
register 3 is coded, it is coded as (3). When one of the registers 2 through 12 is used,
it can be coded as a decimal digit, symbol (equated to a decimal digit), or an expression
that results in a value of 2 through 12.
(1)

When this notation is shown, general register 1 can be used as an operand. When used
as an operand in a macro instruction, the register must be specified as the decimal digit
1 enclosed in parentheses as shown above.
(0)

When this notation is shown, general register 0 can be used as an operand. When used
as an operand in a macro instruction, the register must be specified as the decimal digit
o enclosed in parentheses as shown above.
RX-Type Address
When this notation is shown, the operand can be specified as any valid
assembler-language RX-type address. The following shows examples of each valid
RX-type address:
Name

Operation

Operand

ALPHAI
ALPHA2
BETA1
BETA2
GAMMAI
GAMMA2
GAMMA3
LAMBDA1

L
L

1,39(4,10)
REG 1,39( 4,TEN)
2,ZETA(4)
REG2,ZET A(REG4)
2,ZETA
REG2,ZETA
2,=F'1000'
3,20(,5)

L
L

Both ALPHA instructions specify explicit addresses; REG 1 and TEN are absolute
symbols. Both BET A instructions specify implied addresses, and both use index
registers. Indexing is omitted from the GAMMA instructions. GAMMA 1 and
GAMMA2 specify implied addresses. The second operand of GAMMA3 is a literal.
LAMBDA1 specifies an explicit address with no indexing.
Introduction 3

A-Type Address
When this notation is shown, the operand can be specified as any address that can be
written as a valid assembler-language A-type address constant. An A-type address
constant can be written as an absolute value, a relocatable symbol, or relocatable
expression. Operands that require an A-type address are inserted into an A-type
address constant during the macro expansion process. For more details about A-type
address constants, refer to OS/VS and DOS/VS Assembler Language.
absexp
When this notation is shown, the operand can be an absolute value or expression. An
absolute expression can be an absolute term or an arithmetic combination of absolute
terms. An absolute term can be a nonrelocatable symbol, a self-defining term, or the
length attribute reference. For more details about absolute expressions, refer to
OS/VS and DOS/VS Assembler Language.
relexp
When this notation is shown, the operand can be a relocatable symbol or expression.
A relocatable symbol or expression is one whose value changes by n if the program in
which it appears is relocated n bytes away from its originally assigned area of storage.
For more details about relocatable symbols and expressions, refer to OS/VS and
DOS / VS Assembler Language.

Rules for Register Usage
Many macro instruction expansions include instructions that use a base register
previously defined by a USING statement. The USING statement must establish
address ability so that macro expansion can include a branch around the in line
parameter list, if present, and refer to data fields and addresses specified in the macro
instruction operands.
Macro instructions that use a BAL or BALR instruction to pass control to an access
method routine, normally require that register 13 contain the address of an 18-word
register-save area. The READ, WRITE, CHECK, GET, and PUT macro instructions
are of this type.
Macro instructions that use a supervisor call (SVC) instruction to pass control to an
access method routine may modify general registers 0, 1, 14, and 15 without restoring
them. Unless otherwise specified in the macro instruction description, the contents of
these registers are undefined when the system returns control to the problem program.
When an operand is specified as a register, the problem program must have inserted the
value or address to be used into the register as follows:
•

If the register is to contain a value, it must be placed in the low-order portion of

the register unless the macro instruction description states otherwise. Any unused
bits in the register should be set to zero.
•

If the register is to contain an address, the address must be placed in the low-order

three bytes of the register, and the high-order byte of the register should be set to
zero.

4 OS/VS Data Management Macro Instructions

Rules for Continuation Lines
The operand field of a macro instruction can be continued on one or more additional
lines as follows:
1. Enter a continuation character (not blank, and not part of the operand coding) in
column 72 of the line.
2. Continue the operand field on the next line, starting in column 16. All columns to
the left of column 16 must be blank.
The operand field being continued can be coded in one of two ways. The operand
field can be coded through column 71, with no· blanks, and continued in column 16 of
the next line, or the operand field can be truncated by a comma, where a comma
normally falls, with at least one blank before column 71, and then contiriued in column
16 of the next line. An example of each method is shown in the following illustration:

Name

Operation

Operand

Comments

NAME 1

OPl

OPERAND1,OPERAND2,OPERAND3,OPERAND4,OPERAND5,OPERAND6,OPX
ERAND7
THIS IS ONE WAY

NAME 2

OP2

OPERAND1,OPERAND2, THIS IS ANOTHER WAY
OPERAND3,
OPERAND4

x
X

Introduction 5

MACRO INSTRUCTION DESCRIPTIONS

Macro Instruction Descriptions 7

BLDL

BLDL -

Build a Directory Entry List (BPAM)
The BLDL macro instruction is used to complete a list of information from the
directory of a partitioned data set. The problem program must supply a storage area;
the area must include information about the number of entries in the list, the length of
each entry, and the name of each data set member (or alias) before the BLDL macro
instruction is issued. Data set member names in the list must be in alphameric order.
All read and write operations using the same data control block must have been tested
for completion before the BLDL macro instruction is issued.
The BLDL macro instruction is written as follows:

BLDL

[symbol]

deb address -

deb address, list address

RX-type Address, (2-12), 0), or the Decimal Digit 0

The deb address operand specifies the address of the data control block for an open
partitioned, data set, or zero can be specified to indicate that the data set is in a job
library, step library, or link library.
list address -

RX-Type Address, (2-12), or (0)

The list address operand specifies the address of the list to be completed when the
BLDL macro instruction is issued. The list address must be on a halfword
boundary. The following illustration shows the format of the list:

List

List
Description

0 or
More

List

Address ~_ _ _ _ _ _ _ _E~n.....
tr_Y_(_LL_b_Y_t_es_)_ _ _~y.,-_ _ _E_n_tr_ie.....s.....(_FF_to_ta_I-..,)

lengj FF
{bytes}

Lli

NAME 1

I I+H
TTR
3

1 1 1

USER DATA

NAME 2

)

to 62

Macro Instruction Descriptions 9

This field must contain a binary value indicating the total number of
entries in the list.

This field must contain a binary value indicating the length, in bytes, of
each entry in the list (must be an even number of bytes). If the exact
length of the entry is known, specify the exact length. Otherwise,
specify at least 58 bytes (decimal) if the list is to be used with an
ATTACH, LINK, LOAD, or XCTL macro instruction. The minimum
length for a list is 12 bytes.

NAME This field must contain the member name or alias to be located. The
name must start in the first byte of the name field and be padded to the
right with blanks (if necessary) to fill the 8-byte field.
When the BLDL macro instruction is executed, five fields of the directory entry list are
filled in by the system. The specified length (LL) must be at least 14 to fill in the Z
and C fields. If the LL field is 12, only the NAME, IT, R, and K fields are returned.
The five fields are:

Indicates the relative track number where the beginning of the data set
member is located.

Indicates the relative block (record) number on the track indicated by
IT.

Indicates the concatenation number of the data set. For the first or only
data set, this value is zero.

Indicates where the system found the directory entry:

Private library
1
Link library
2
Job, task, or step library
3-255 Job, task, or step library of parent task n, where n = Z-2

Indicates the type (member or alias) for the name, the number of note
list fields (TTRNs), and the length of the user data field (indicated in
halfwords). The following describes the meaning of the eight bits:
Bit 0=0
Bit 0=1
Bits 1-2
Bits 3-7

Indicates a member name.
Indicates an alias.
Indicate the number of TTRN fields (maximum of
three) in the user data field.
Indicate the total number of halfwords in the user
data field. If the list entry is to be used with an
ATTACH, LINK, LOAD, or XCTL macro
instruction, the value in bits 3 through 7 is 22
(decimal).

USER DATA The user data field contains the user data from the directory entry.
If the length of the user data field in the BLDL list is equal to or greater than

the user data field of the directory entry, the entire user data field is entered
into the list. Otherwise, the list contains only the user data for which there is
space.

10 OS/VS Data Management Macro Instructions

BLDL

Completion Codes
When the system returns control to the problem program, the low-order byte of
register 15 contains a return code; the three high-order bytes of register 15 are set to
zero. The return codes are:
Hexadecimal Meaning
Code

Successful completion.

One or more entries in the list could not be filled; the list supplied may
be invalid. If a search is attempted but the entry is not found, the R field
(byte 11) for that entry is set to zero.

A permanent input/output error was detected when the system attempted
to search the directory.

Macro Instruction Descriptions 11

BSP

BSP - Backspace a Physical Record (BSAM Access Only)

Magnetic Tape and Direct

The BSP macro instruction causes the current volume to be backspaced one data block
(physical record). All input and output operations must be tested for completion
before the BSP macro instruction is issued. The BSP macro instruction should not be
used if the CNTRL, NOTE, or POINT macro instructions are being used.
Magnetic Tape: A backspace is always made toward the load point.
Direct Access: A BSP macro instruction must not be issued for a data set created by
using track overflow.
With SYSIN or SYSOUT data sets a BSP macro instruction is ignored, but a
completion code is returned.
The BSP macro instruction is written as follows:

BSP

[symbol]

deb address -

deb address

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for the
volume to be backspaced. The data set on the volume to be backspaced must be
opened before issuing the BSP macro instruction.

Successful completion.

Unsuccessful completion (includes encountering a tapemark or beginning
of an extent).

A backspacing request was ignored on a SYSIN or SYSOUT data set.

Macro Instruction Descriptions 13

BUILD

BUILD QSAM)

Build a Buffer Pool (BDAM, BISAM, BPAM, BSAM, QISAM, and

The BUILD macro instruction is used to construct a buffer pool in an area provided by
the problem program. The buffer pool may be used by more than one data set through
separate data control blocks. Individual buffers are obtained from the buffer pool
using the GETBUF macro instruction, and buffers are returned to the buffer pool using
a FREEBUF macro instruction. Refer to OS/VS Data Management Services Guide
for an explanation of the interaction of the DeB, BUILD, and GETBUF macro
instructions in each access method, as well as the buffer size requirements.
The BUILD macro instruction is written as follows:

BUILD

[symbol]

area address -

area address, {number of buffers, buffer length
(0)

RX-Type Address, (2-12), or (1)

The area address operand specifies the address of the area to be used as a buffer
pool. The area must start on a fullword boundary. The following illustration shows
the format of the buffer pool:
Area Address

I
Buffer Pool
Control
Block

I--

8 b les

Buffer

-L

Buffer

length

[

Buffer

length

Area length
Area length=(Buffer Length) x (Number of Buffers) + 8

number of buffers -

Buffer

symbol, decimal digit, absexp, or (2-12)

The number-of-buffers operand specifies the number of buffers in the buffer pool up
to a maximum of 255.

Macro Instruction Descriptions 15

buffer length -

symbol, decimal digit, absexp, or (2-12)

The buffer length operand specifies the length, in bytes, of each buffer in the buffer
pool. The value specified for the buffer length must be a fullword multiple;
otherwise the system rounds the value specified to the next higher fullword multiple.
The maximum length that can be specified is 32,760 bytes. For QSAM, the buffer
length must be at least as large as the value specified in the blocksize (DCBBLKSI)
field of the data control block.
(0) -

Coded as shown

The number of buffers and buffer length can be specified in general register O. If
(0) is coded, register 0 must contain the binary values for the number of buffers
and buffer length as shown in the following illustration.
Register

a
Buffer Length

Number of Buffers

Bits:

16 OS/VS Data Management Macro Instructions

BUILDRCD

BUILDRCD -

Build a Buffer Pool and a Record Area (QSAM)
The BUILDRCD macro instruction causes a buffer pool and a record area to be
constructed in a user-provided storage area. The macro is used only for
variable-length, spanned records processed in QSAM locate mode. Use of this macro
before the data set is opened, or before the end of the DCBEXIT routine, will
automatically invoke a logical-record interface rather than a segment interface for
variable-length, spanned records.
The standard form of the BUILDRCD macro instruction is written as follows (the list
and execute forms are shown following the description of the standard form):

BUILDRCD

[symbol]

area address, number of buffers, buffer length,
record area address[, record area length]

area address -- A~Type Address or (2-12)

Addre~

~--B-u-ff-er~p-o-o-I--~------------~-------~-'~

;_I~_:_t~_OI____~____B_u_ff_e_r___-+-__--' '(

Buffer

L -__

--12 bYte,--1-- ~~:;~ -l

l- ~~:;;h

...-------------------Area Length ------------~
Area Length={Buffer Length) x (Number of Buffers) + 12

Macro Instruction Descriptions 17

The buffer control block contains the address of the record area and a flag that
indicates logical-record interface processing of variable-length, spanned records.
number of buffers -

symbol, decimal digit, absexp, or (2-12)

The number of buffers operand specifies the number of buffers, up to a maximum
of 255, to be in the buffer pool.
buffer length -

symbol, decimal digit, absexp, or (2-12)

The buffer length operand specifies the length, in bytes, of each buffer in the buffer
pool. The value specified for the buffer length must be a fullword multiple;
otherwise, the system rounds the value specified to the next higher fullword
mUltiple. The maximum length that can be specified is 32,760.
record area address -

A-Type Address or (2-12)

The record area address operand specifies the address of the storage area to be
used as a record area. The area must start on a doubleword boundary and have a
length of the maximum logical record (LRECL) plus 32 bytes.
record area length -

symbol, decimal, digit, absexp, or (2-12)

The record area length operand specifies the length of the record area to be used.
The area must be as long as the maximum length logical record plus 32 bytes for
control information. If the record area length operand is omitted, the problem
program must store the record area length in the first four bytes of the record area.
Note: It is the user's responsibility to release the buffer pool and the record area after
a CLOSE macro instruction has been issued for all the data control blocks using the
buffer pool and the record area.

18 OS/VS Data Management Macro Instructions

BUILDRCD -

List Form

List Form
The list form of the BUILDRCD macro instruction is used to construct a program
parameter list. The description of the standard form of the BUILDRCD macro
instruction provides the explanation of the function of each operand. The description
of the standard form also indicates which operands are totally optional and those
required in at least one of the pair of list and execute forms. The format description
below indicates the optional and required operands in the list form only.
The list form of the BUILDRCD macro instruction is written as follows:
[symbol]

BUILDRCD

area address, number of buffers, buffer length,
record area address[,record area length]
,MF=L

area address -

A-Type Address

number of buffers buffer length -

symbol, decimal digit, or absexp

record area address record area length -

MF=L -

symbol, decimal digit, or absexp

A-Type Address
symbol, decimal digit, or absexp

Coded as shown

The MF=L operand specifies that the BUILDRCD macro instruction is used to
create a control program parameter list that will be referenced by an execute form
instruction.
Note: A control program parameter list can be constructed by coding only the MF=L
operand (without the preceding comma); in this case, the list is constructed for the
area address, number of buffers, buffer length, and record area address operands.
If the record area length operand is also required, the operands can be coded as
follows:
[symbol] BUILDRCD

""O,MF = L

The preceding example shows the coding to construct a list containing address
constants with a value of 0 in each constant. The actual values can then be supplied by
the execute form of the BUILDRCD macro instruction.

Macro Instruction Descriptions 19

BUILDRCD -

Execute Form

Execute Form
A remote control program parameter list is referred to, and can be modified by, the
execute form of the BUILDRCD macro instruction. The description of the standard
form of the BUILDRCD macro instruction provides the explanation of the function of
each operand. The description of the standard form also indicates which operands are
totally optional and those required in at least one of the pair of list and execute forms.
The format description below indicates the optional and required operands for the
execute form only.
The execute form of the BUILDRCD macro instruction is written as follows:
[symbol]

BUILDRCD

[area address], [number of buffers],
[buffer length], [record area addressl,
[record area length],
MF=(E, {control program I ist address})

(1)

area address -

RX-Type Address or (2-12)

number of buffers buffer length -

absexp

record area address record area length -

MF=(E,

absexp

RX-Type Address or (2-12)
absexp

I control program list address })
I(I)

}

This operand specifies that the execute form of the BUILDRCD macro instruction
is used, and an existing control program parameter list (created by a list-form
instruction) will be used. The MF= operand is coded as described in the following:
E-

Coded as shown

control program list address -

RX-Type Address, (2-12), or (1)

Macro Instruction Descriptions 21

CHECK

CHECK - Wait for and Test Completion of a Read or Write Operation
(BDAM, BISAM, BPAM, and BSAM)
The CHECK macro instruction causes the active task to be placed in the wait
condition, if necessary, until the associated input or output operation is completed. The
input or output operation is then tested for errors and exceptional conditions. If the
operation is completed successfully, control is returned to the instruction following the
CHECK macro instruction. If the operation is not completed successfully, the error
analysis (SYNAD) routine is given control or, if no error analysis routine is provided,
the task is abnormally terminated. The error analysis routine is discussed in the
SYNAD operand of the DCB macro instruction.
The following conditions are also handled for BP AM and BSAM only:
When Reading: Volume switching is automatic. The end-of-data-set (EODAD)
routine is given control if an input request is made after all the records have been
retrieved.
When Writing: Additional space on the device is obtained when the current space is
filled and more WRITE macro instructions have been issued.
For BPAM and BSAM, a CHECK macro instruction must be issued for each input and
output operation, and must be issued in the same order as the READ or WRITE macro
instructions were issued for the data set. For BDAM or BISAM, either a CHECK or
WAIT macro instruction can be used. However, if both a CHECK and WAIT macro
instruction are used, the CHECK macro instruction must be issued after the WAIT
macro instruction.
If the ASCII translation routines are included when the operating system is generated,

translation can be requested by coding LABEL=(,AL) or (,AUL) in the DD statement,
or it can be requested by coding OPTCD=Q in the DCB macro instruction or DCB
subparameter of the DO statement. If translation is requested, the Check routine
automatically translates BSAM records, as they are read, from ASCII code to EBCDIC
code, provided that the record format is F, FB, 0, DB, or U. Translation occurs as
soon as the Check routine determines that the input buffer is full. For translation to
occur correctly, all input data must be in ASCII code.
The CHECK macro instruction is written as follows:

[symbol]

decb address -

CHECK

decb address [,DSORG=

{~~L}

RX-Type Address, (2-12), or (1)

The decb address operand specifies the address of the data event control block
created by the associated READ or WRITE macro instruction or used by the
associated input or output operation.

Macro Instruction Descriptions 23

DSORG=

{IS}
{ALL}

The DSORG operand specifies the type of data set organization. The following
describes the characters that can be coded.
IS

Specifies that the program generated is for BISAM use only.

ALL - Specifies that the program generated is for BDAM, BISAM, BPAM, or
BSAM use only.
If the DSORG operand is omitted, the program generated is for BDAM, BP AM, and

BSAM use only.

24 OS/VS Data Management Macro Instructions

CHKPT

CHKPT - Take a Checkpoint for Restart Within a Job Step (BDAM, BISAM,
BPAM, BSAM, QISAM, and QSAM)
The CHKPT macro instruction establishes a checkpoint for the job step. If the step
terminates abnormally, it is automatically restarted from the checkpoint. On restart,
execution resumes with the instruction that follows the CHKPT instruction. If the step
again terminates abnormally (before taking another checkpoint), it is again restarted
. from the checkpoint. When several checkpoints are taken, the step is automatically
restarted from the most recent checkpoint.
Automatic restart from a checkpoint is suppressed if:
1. The job step completion code is not one of a set of codes specified at system
generation.
2. The operator does not authorize the restart.
3. The restart definition parameter of the JOB or EXEC statement specifies no restart
(RD=NR) or no checkpoint (RD=NC or RD=RNC).
4. The CANCEL operand appears in the last CHKPT macro instruction issued before
abnormal termination.
Under any of these conditions, automatic checkpoint restart does not occur. Automatic
step restart (restart from the beginning of the job step) can occur, except under
condition 1 or 2, or when the job step was restarted from a checkpoint prior to
abnormal termination. Automatic step restart is requested' through the restart definition
parameter of the JOB or EXEC statement (RD=R or RD=RNC).
When automatic restart is suppressed or unsuccessful, a deferred restart can be
requested by submitting a new job. .The new job can specify restart from the beginning
of the job step or from any checkpoint for which there is an entry in the checkpoint
data set.
The checkpoint data set contains the information necessary to restart the job step from
a checkpoint. The control program records this information when the CHKPT macro
instruction is issued. The macro refers to the data control block for the data set, which
must be on a magnetic tape or direct-access volume. A tape can have standard labels,
nonstandard labels, or no labels.
If the checkpoint data set is not open when CHKPT is issued, the control program
opens the data set and then closes it after writing the checkpoint entry. If the data set

is physically sequential and is opened by the control program, the checkpoint entry is
written over the previous entry in the data set, unless the DD statement specifies
DISP=MOD. By writing entries alternately into two checkpoint data sets, it is possible
to keep the entries for the two most recent checkpoints while deleting those for earlier
checkpoints.
The data control block for the checkpoint data set must specify:
DSORG=PS or PO, RECFM=U or UT, MACRF=(W), BLKSIZE= nnn, and
DDNAME= any name
where nnn is at least 600 bytes, but not more than 32,760 bytes for magnetic tape and
not more than the track length for direct access. (If the data set is opened by the
Macro Instruction Descriptions 25

control program, blocksize need not be specified; the device-determined maximum
blocksize is assumed if no blocksize is specified.) For seven-track tape, the data control
block must specify TRTCH=C; for direct access, it must specify or imply
KEYLEN=O. Torequest chained scheduling, OPTCD=Cand NCP=2 must be
specified. With direct access, OPTCD= W can be specified to request validity checking
for write operations, and OPTCD= WC can be specified to combine validity checking
and chained scheduling.
The standard form of the CHKPT macro instruction is written as shown below.
Information about the list and execute forms follows this description.
[symbol]

CHKPT

1deb
address f·eheekid address[,eheekid length]] I
CANCEL
,'$'

deb address

is the address of the data control block for the checkpoint data set.
eheekid address

is the address of the checkpoint identification field. The contents of the field are
used when the job step is to be restarted from the checkpoint. They are used by
the control program in requesting operator authorization for automatic restart. You
can use it for requesting deferred restart.
If the next operand specifies the length of the field (checkid length), or if it is

omitted to imply a length of eight bytes, the field must contain the checkpoint
identification when the CHKPT macro instruction is issued. If the next operand is
written as'S', the identification is generated and placed in the field by the control
program. If both operands are omitted, the control program generates the
identification, but does not make it available to the problem program. In each case,
the identification is written in a message to the operator.
The control program writes the checkpoint identification as part of the entry in the
checkpoint data set. For a sequential data set, the identification can be any
combination of up to 16 letters, digits, printable special characters, and blanks. For
a partitioned data set, it must be a valid member name of up to eight letters and
digits, starting with a letter. The identification for each checkpoint should be
unique.
If the control program generates the identification, the identification is eight bytes
in length. It consists of the letter C followed by a seven-digit decimal number.

The number is the total number of checkpoints taken by the job, including the
current checkpoint, checkpoints taken earlier in the job step, and checkpoints taken
by any previous job steps.
eheekid length

is the length in bytes of the checkpoint identification field. The maximum length is
16 bytes if the checkpoint data set is physically sequential, 8 bytes if it is
partitioned. For a partitioned data set, the field can be longer than the actual
identification, .if the unused portion is blank. If the operand is omitted, the implied
length is eight bytes.

26 OS/VS Data Management Macro Instructions

CHKPT
If you code '8' the control program supplies the checkpoint identification. The

implied field length is eight bytes.

CANCEL
cancels the request for automatic restart from the most recent checkpoint. If
another checkpoint is taken before abnormal termination, the job step can be
restarted at that checkpoint.
When control is returned, register 15 contains one of the following return codes:
Hexadecimal
Code

Meaning

Successful completion. Code 00 is also returned if the RD parameter
was coded as RD=NC or RD=RNC to totally suppress the function of
CHKPT.

Restart has occurred at the checkpoint taken by the CHKPT macro
instruction during the original execution of the job. A request for
another restart of the same checkpoint is normally in effect. If a
deferred restart was performed and RD=NC, NR, or RNC was
specified in the resubmitted deck, a request for another restart is not in
effect.

Unsuccessful completion. A checkpoint entry was not written, and a
restart from this checkpoint was not requested. A request for an
automatic restart from a previous checkpoint remains in effect.

One of the following conditions exists:
• The parameters passed by the CHKPT macro instruction are
invalid.

•

The CHKPT macro instruction was executed in an exit routine
other than the end-of-volume exit routine.

•

A STIMER macro instruction has been issued, and the time interval
has not been completed.

•

A WTOR macro instruction has been issued, and the reply has not
been received.

•

The checkpoint data set is on a direct-access volume and is full.
Secondary space allocation was requested and performed.
(Secondary space allocation is performed for a checkpoint data set,
but the allocated space is not used. However, had secondary
allocation not been requested, the job step would have been
abnormally terminated.)

•

The CHKPT macro instruction was issued for a data set on a
graphics device.

Unsuccessful completion. An uncorrectable error occurred in writing
the checkpoint entry or in completing queued access method
input/ output operations that were begun before the CHKPT macro
instruction was issued. A partial, invalid checkpoint entry may have

Macro Instruction Descriptions 27

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

been written. If the entry has a programmer-specified checkid, and
the checkpoint data set is sequential, a different checkid should be
specified the next time CHKPT is executed. If the data set is
partitioned, a different checkid need not be specified. This code is also
returned if the checkpoint routine tries to open the checkpoint data set
and the DD statement for the data set is missing.
10

Successful completion with possible error condition. The task has
control, by means of an explicit or implied use of the ENQ macro
instruction, of a serially reusable resource; if the task terminates
abnormally, it will not have control of the resource when the job step
is restarted. The user's program must, therefore, reissue the ENQ
macro instruction.

Checkpoint not taken. End of volume occurred while writing the
checkpoint entry on a tape data set.

When one of the errors indicated by code 08, OC, 10, or 14 occurs, the system prints
an error message on the operator's console. The message indicating code 08 or OC
contains a code that further identifies the error. The operator should report the
message contents to the programmer.
Note: Successful use of the CHKPT macro instruction requires some care in the
selection of checkpoints. For a detailed discussion of checkpoint requirements, refer to
OS / VS Checkpoint/Restart.

28 OS/VS Data Management Macro Instructions

CHKPT -

List Form

List Form
The list form of the CHKPT instruction is used to construct a control program
parameter list.
The description of the standard form of the CHKPT macro provides the explanation of
the function of each operand. The description of the standard form also indicates
which operands are optional and which are required in at least one of the list and
execute forms. The format description below indicates the optional and required
operands in the list form only. Note that the CANCEL operand, which can be coded
in the standard form, cannot be coded in the list form.
The list form of the CHKPT macro instruction is written as follows:

[symbol]

CHKPT

[deb address ],[ eheekid address] ,[eheekid length]
MF=L
'5'

symbol

is any symbol valid in the assembler language.
address

is any address that may be written in an A-type address constant.
length

is any absolute expression that is valid in the assembler language.
MF=L

indicates the list form of the CHKPT macro instruction.

Macro Instruction Descriptions 29

CHKPT -

Execute Form

Execute Form
A control program parameter list is referred to, and can be modified by, the execute
form of the CHKPT macro.
The description of the standard form of the CHKPT macro provides the explanation of
the function of each operand. The description of the standard form also indicates
which operands are optional and which are required in at least one of the list and
execute forms. The format description below indicates the optional and required
operands for the execute form only. Note that the CANCEL operand, which can be
coded in the standard form, cannot be coded in the execute form.·
The execute form of the CHKPT macro instruction is written as follows:
CHKPT

[symbol]

[deb address] ,[ eheekid address], [checkid lenglh]
·'5'
, MF=(E , co nlro I program Ii sl address!)
(1)

symbol

is any symbol valid in assembler language.
address

is any address that is valid in an RX-type instruction, or one of the general registers
2 through 12, previously loaded with the indicated address. You may designate the
register symbolically or with an absolute expression; always code it in parentheses.
length

is any absolute expression that is valid in assembler language, or one of the general
registers 2 through 12, previously loaded with the indicated value. You may
designate the register symbolically or with an absolute expression; always code it in
parentheses.

MF=(E,

t control
t

program list address D
(1)

indicates the execute form of the macro instruction using a control program
parameter list. The address of the control program parameter list can be coded as
described under address, or can be loaded into register I, in which case code
MF=(E,(1

».

Macro Instruction Descriptions 3 1

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

CLOSE - Logically Disconnect a Data Set (BDAM, BISAM, BPAM, BSAM,
QISAM, and QSAM)
The CLOSE macro instruction causes output data set labels to be created, and volumes
to be positioned as specified by the user. The fields of the data control block are
restored to the condition that existed before the OPEN macro instruction was issued,
and the data set is disconnected from the processing program. Final volume positioning
for the current volume can be specified to override the positioning implied by the DD
control statement DISP parameter. Any number of deb address operands and
associated options may be specified in the CLOSE macro instruction.
Associated data sets for a 3525 card punch can be closed in any sequence, but if one
data set is closed, I/O operations cannot be initiated for any of its associated data sets.
Additional information about closing associated data sets is contained in OS / VS Data
Management Services Guide.
A FREEPOOL macro instruction should normally follow a CLOSE macro instruction
to regain the buffer pool storage space and to allow a new buffer pool to be built if the
DCB is reopened with different record size attributes.
A special operand, TYPE = T, is provided for processing with BSAM.
The standard form of the CLOSE macro instruction is written as follows (the list and
execute forms are shown following the description of the standard form):

[ symbol]

deb address -

(deb address, [option] , ... )

L, TYPE=T]

A-Type Address or (2-12)

The deb address operand specifies the address of the data control block for the
opened data set that is to be closed.
option
One of four options can be specified for a data set on magnetic tape or a
direct-access device only. These options indicate the volume positioning that is to
occur when the data set is closed. The option operand is ignored for ISAM data
sets. The options are:

REREAD -

Specifies that the current volume is to be positioned to reprocess the
data set.

LEAVE

Specifies that the current volume is to be positioned to the logical
end of the data set.

REWIND -

Specifies that the current volume is to be positioned at the load
point, regardless of the direction of processing. REWIND cannot be
specified when TYPE =T is specified.

Macro Instruction Descriptions 33

Page of GC26-3793-1
Revised December 15, 1972
By TNL_ GN26-0748

DISP

Specifies that the current volume is to be positioned according to
the position implied by the DISP parameter of the corresponding
DD statement, as follows:
DISP Parameter

Action

PASS

Forward space to the end of data set on
the current volume.

DELETE

Rewind the current volume.

KEEP, CATLG, or
UNCATLG

Rewind and unload the current volume.

When the option operand is omitted, the following volume positioning occurs:
•

If TYPE = T is coded, LEAVE is assumed.

•

If TYPE=T is not coded, DISP is assumed.

TYPE=T -

Coded as shown

You can code CLOSE (TYPE=T) and temporarily close sequential data sets on
magnetic tape and direct-access volumes processed with BSAM. When you use
TYPE=T, the DCB used to process the data set maintains its open status, and you
don't have to issue another OPEN macro instruction to continue processing the
same data set. This option cannot be used in a SYNAD routine.
A request to temporarily close a data set causes the system control program to
process labels, modify some of the fields in the system control blocks for that data
set, and reposition the volume (or current volume in the case of multivolume data
sets) in much the same way that the normal CLOSE macro does. When you code
TYPE = T, you can specify that the volume either be positioned at the end of data
(the LEAVE option) or be repositioned at the beginning of data (the REREAD
option). Magnetic-tape volumes are repositioned either immediately before the first
data record or immediately after the last data record; the presence of tape labels has
no effect on repositioning. The following figure, which assumes a sample data set
containing 1000 records, illustrates the relationship between each positioning option
and the point at which you resume processing the data set after issuing the
temporary close.

34 OS/VS Data Management Macro Instructions

Beg i n process i ng
tape data set
(open for read

Begin
processing

bee kw ard) " ' "
c

Record

c
I

(

999

Record
1000

If you issue CLOSE (TYPE=T)
and specify

After temporary close, you
will resume processing

LEAVE

Immediately after record 1000

LEAVE (with tape data set open
for read backward)

Immediatel y before record I

REREAD

Immediately before record I

REREAD (with tape data set open
for read backward)

Immediately after record 1000

If you code the release (RLSE) operand on the DO statement for the data set, it is
ignored by temporary close, but any unused space will be released when you finally
issue the normal CLQSE macro instruction.
It is possible to use BSAM to process a data set that is not physical-sequential; if
you use CLOSE (TYPE=T) for them, the following restrictions apply;

The DCB for the data set you are processing must specify OSORG=PS or
DSORG=PSU.
•

The DCB for the partitioned data set you are processing must be open to the
entire partitioned data set, not just a member.

•

If you open the data set for output and issue CLOSE (TYPE=T), the volume
will be repositioned only if the identifier (format-I) OSCB for your data set
specifies DSORG=PS or DSORG=PSU. (This restriction prohibits the use of
temporary close following or during the building of a BOAM data set.)

•

If you open the data set for input and issue CLOSE (TYPE= T) with the
LEAVE option, the volume will be repositioned only if the identifier
(format-I) DSCB for your data set specifies DSORG=PS or OSORG=PO.

Note: When a data control block is shared among multiple tasks, the task that opened
the data set must also close it; however, a- subtask of the task that opened the DCB can
issue the CLOSE macro instruction with the TYPE = T option.

Macro Instruction Descriptions 35

CLOSE -

List Form

List Form
The list form of the CLOSE macro instruction is used to construct a data management
parameter list. Any number of operands (data control block addresses and associated
options) can be specified.
The CLOSE macro instruction can be used with a variable-length parameter list. The
length of a list generated by a list-form instruction must be equal to the maximum
length required by an execute-form instruction that refers to the same list. A
maximum length list can be constructed by one of two methods:
Code a list-form instruction with the maximum number of parameters that are
required by an execute-form instruction that refers to the list.
Code a maximum length list by using commas in a list-form instruction to acquire a
list of the appropriate size. For example, coding ("""",) would provide a list of five
fullwords (five dcb addresses and five options).
A parameter list constructed by a CLOSE macro instruction, list form, can be referred
to by either an OPEN or CLOSE execute-form instruction.
The description of the standard form of the CLOSE macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates which operands are completely optional and those required in at least one of
the pair of list and execute forms. The format description below indicates the optional
and required operands in the list form only.
The list form of the CLOSE macro instruction is written as follows:

~ymbolJ

deb address option -

([deb address], [option], ... ) [, TYPE=T] ,MF=L

A-Type Address

Same as standard form

TYPE=T -

Coded as shown

The TYPE=T operand can be coded in the list-form instruction to allow the
specified option to be checked for validity when the program is assembled.
MF=L -

Coded as shown

The MF=L operand specifies that the CLOSE macro instruction is used to create a
data management parameter list that will be referred to by an execute-form
instruction.

Macro Instruction Descriptions 37

CLOSE -

Execute Form

Execute Form
A remote data management parameter list is used in and can be modified by the
execute form of the CLOSE macro instruction. The parameter list can be generated by
the list form of either an OPEN macro instruction or a CLOSE macro instruction.
The description of the standard form of the CLOSE macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates which operands are totally optional and those required in at least one of the
pair of list and execute forms. The format description below indicates the optional and
required operands in the execute form only.
The execute form of the CLOSE macro instruction is written as follows:

[symbol]

[( [deb address], [option], ... )]

r, TYPE=T]

,MF=(E, { data management Iist address} )
(1 )

deb address option -

Same as standard form

TYPE=T MF=(E,

RX-Type Address or (2-12)

Same as standard form
{data management list address })
{

(1)

}

This operand specifies that the execute form of the CLOSE macro instruction is
being used, and an existing data management parameter list (created by a list-form
instruction) will be used. The MF= operand is coded as described in the following:
E-

Coded as shown

data management list address -

RX-Type Address, (2-12), or (1)

Macro Instruction Descriptions 39

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

CNTRL

CNTRL -

Control Online Input/Output Device (BSAM and QSAM)
The CNTRL macro instruction is used to control magnetic tape drives (BSAM only)

I and to control online card readers, 3525 card punches (read and print features), and
printers (BSAM and QSAM). The MACRF operand of the DCB macro instruction
must specify a C. The CNTRL macro instruction is ignored for SYSIN or SYSOUT
data sets. For BSAM, all input and output operations must be tested for completion
before the CNTRL macro instruction is issued. The control facilities available are as
follows:
Card Reader: Provides stacker selection.
QSAM - The CNTRL macro instruction is issued whenever it is necessary to read
a new card. For unblocked records, a CNTRL macro instruction should be issued
after every input request except the last. For blocked records, a CNTRL macro
instruction is issued after the last logical record on each card is retrieved, except for
the last input request. The move mode of the GET macro instruction must be used,
and the number of buffers (BUFNO field of the DCB) must be one.
BSAM - The CNTRL macro instruction should be issued after every input
request. If, however, the device is allocated to SYSIN, the CNTRL macro
instruction does not need to be issued after the request because the CLOSE macro
instruction places the last card in the same stacker as the preceding card.
Printer: Provides line spacing or a skip to a specific carriage control channel. A
CNTRL macro instruction cannot be used if carriage control characters are
provided in the record. If the printer contains the universal character set feature,
data checks should be blocked (OPTCD=U should not appear in the data control
block).
Magnetic Tape: Provides method of forward spacing and backspacing (BSAM only).
If OPTCD=H is indicated in the data control block, the CNTRL macro instruction

can be used to perform record positioning on DOS tapes that contain embedded
checkpoint records. Embedded checkpoint records encountered during the record
positioning are bypassed and are not counted as blocks spaced over. OPTCD=H
must be specified in a job control language DD statement. The CNTRL macro
instruction cannot be used to backspace DOS 7-track tapes that are written in data
convert mode that contain embedded checkpoint records (BSAM).
3525 Printing: Provides line spacing or a skip to a specific printing line on the card.
The card contains 25 printing lines; the odd numbered lines 1 through 23
correspond to the printer skip channels 1 through 12 (see the SK operand). For
additional information about 3525 printing operations, refer to OS jVS Data
Management Services Guide.

Macro Instruction Descriptions 41

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

The CNTRL macro instruction is written as follows:

[symbol]

CNTRL

dcb address,

55,

{~}

sp,G}
, SK,

{;;OU9h }

B5M
F5M
B5R [, number of blocks]
F5R [, number of blocks]
-'

deb address

The deb address operand specifies the address of the data control block for the data
set opened for the online device.
SS,

HJ
12J
The SS operand is coded as shown to indicate that the control function requested
is stacker selection on a card reader; either 1 or 2 must be coded to indicate
which stacker is to be selected.

SP,

HJ
12J
13J
The SP operand is coded as shown to indicate that the control function requested
is printer line spacing or 3525 card punch line spacing; either 1, 2, or 3 must be
coded to indicate the number of spaces for each print line.

HJ
SK, Ithrough}

H2J
The SK operand is coded as shown to indicate that the control function requested is
a skip operation on the printer or 3525 card punch, print feature; a number (1
through 12) must be coded to indicate the channel or print line to which the skip is
to be taken.
BSM -

Coded as shown

The BSM operand indicates that the control function requested is to backspace the
magnetic tape past a tapemark, then forward space over the tapemark. When this
operand is specified, the DCBBLKCT field in the data control block is set to zero.

42 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

CNTRL
FSM -

Coded as shown

The FSM operand indicates that the control function requested is to forward space
the magnetic tape over a tapemark, then backspace past the tapemark. When this
operand is specified, the DCBBLKCT field in the data control block is set to zero.
BSR -

Coded as shown

The BSR operand indicates that the control function requested is to backspace the
magnetic tape the number of blocks indicated in the number-oj-blocks operand.
FSR -

Coded as shown

The FSR operand indicates that the control function requested is to forward space
the magnetic tape the number of blocks indicated in the number-oj-blocks operand.

number oj blocks -

symbol, decimal digit, absexp, or (2-12)

The number-oj-blocks operand specifies the number of blocks to backspace (see
BSR operand) or forward space (see FSR operand) the magnetic tape. The
maximum value that can be specified is 32,767. If the number-oj-blocks operand is

omitted, one is assumed.
If the forward space or backspace operation is not completed successfully, control is

passed to the error analysis (SYNAD) routine; if no SYNAD routine is designated, the
task is abnormally terminated. Register contents, when control is passed to the error
analysis routine, are shown in Appendix A. If a tapemark is encountered for BSR or
FSR, control is returned to the processing program, and register 15 contains a count of
the uncompleted forward spaces or backspaces. If the operation is completed normally,
register 15 contains the value zero.

Macro Instruction Descriptions 43

DCB-BDAM

DCB -

Construct a Data Control Block (BDAM)
The data control block for a basic direct access method (BDAM) data set is
constructed during assembly of the problem program. The DCB macro instruction
must not be coded within the first 16 bytes of a control section (CSECT). The
DSORG and MACRF operands must be coded in the DCB macro instruction, but the
other operands can be supplied from other sources. Each of the BDAM DCB operand
descriptions contains a heading, "Source." The information under this heading describes
the sources from which an operand can be supplied to the data control block.
Before a DCB macro instruction for a BDAM data set is coded, the following
characteristics of direct data sets should be considered.
•

The problem program must synchronize I/O operations by issuing a CHECK or
WAIT macro instruction to test for completion of read and write operations.

•

A BDAM data set is created using the basic sequential access method (BSAM). A
special operand (MACRF=WL) specifies that BSAM is being used to create a
BDAM data set. Operand descriptions for the BDAM DCB macro instruction
include information about both creating and processing a BDAM data set.

•

Although a BDAM data set can contain blocked records, the problem program must
perform all blocking and deblocking of records. BDAM provides only the capability
to read or write a data block, but the data block can contain mUltiple logical records
assembled by the problem program.

•

When a BDAM data set is being created, buffers can be acquired automatically, but
buffer control must be provided by the problem program. The problem program
must place data in the output buffer before issuing a WRITE macro instruction to
write the data block.

•

When a BDAM data set is being processed, the problem program can control all
buffering, or dynamic buffering can be specified in the DCB macro instruction and
subsequently requested in a READ macro instruction.

•

The actual organization of a direct data set is determined by the programmer to
meet the needs of the application. The data set can be processed by using one of
the following addressing methods:

•

Actual device addresses (in the form MBBCCHHR).

•

Relative track addresses (in the form TTR). These addresses specify a track (and a
record on the track) of the direct-access device relative to the beginning of the data
set.

•

Relative block addresses can be used with fixed-length records. These addresses
specify a data block relative to the beginning of the data set.

For additional information about the characteristics of BDAM data sets, refer to
OS/VS Data Management Services Guide.

Macro Instruction Descriptions 45

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

The following describes the DeB operands that can be specified for creating and
processing a BDAM data set:
{F}

BFALN= {D}

The BFALN operand specifies the boundary alignment for each buffer in the buffer
pool. The BFALN operand can be specified when (I) BSAM is being used to
create a BDAM data set and buffers are acquired automatically, (2) when an
existing BDAM data set is being processed and dynamic buffering is requested, or
(3) when the GETPOOL macro instruction is used to construct the buffer pool. If
the BFALN operand is omitted, the system provides doubleword alignment for each
buffer. The following describes the characters that can be specified:
F

Specifies that each buffer is aligned on a fullword boundary that is not
also a doubleword boundary.

Specifies that each buffer is aligned on a doubleword boundary.

If the BUILD macro instruction is used to construct the buffer pool or if the

problem program controls all buffering, the problem program must provide the area
for the buffers and control buffer alignment.
Source: The BFALN operand can be supplied in the DeB macro instruction, in the
DeB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine. If both the BFALN and BFTEK operands are
specified, they must be supplied from the same source.
BFTEK=R

The BFTEK operand specifies that the data set is being created for or contains
variable-length spanned records. The BFTEK operand can be coded only when the
record format is specified as RECFM= VS.
When variable-length spanned records are written, the data length can exceed the
total capacity of a single track on the direct-access device being used, or it can
exceed the remaining capacity on a given track. The system divides the data block
into segments (if necessary), writes the first segment on a track, and writes the
remaining segment(s} on the following track(s}.
When a variable-length spanned record is read, the system reads each segment and
assembles a complete data block in the buffer designated in the area address
operand of a READ macro instruction.
Note: Variable-length spanned records can also be read using BSAM. When BSAM is
used to read a BDAM variable-length spanned record, the record is read one segment
at a time, and the problem program must assemble the segments into a complete data
block. This operation is described in the section for the BSAM DeB macro instruction.
Source: The BFTEK operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine. If both the BFTEK and BFALN operands are
specified, they must be supplied from the same source.
BLKSIZE= absexp (maximum value is 32,760)

The BLKSIZE operand specifies the length, in bytes, of each data block for
fixed-length records, or it specifies the maximum length, in bytes, of each data

46 OS/VS Data Management Macro Instructions

DCB-BDAM
block for variable-length or undefined-length records. If keys are used, the length
of the key is not included in the value specified for the BLKSIZE operand.
The actual value that can be specified in the BLKSIZE ope~and depends on the
record format and the type of direct-access device being used. If the
track-overflow feature is being used or if variable-length spanned records are being
used, the value specified in the BLKSIZE operand can be up to the maximum. For
all other record formats(F, V, VBS, and U), the maximum value that can be
specified in the BLKSIZE operand is determined by the track capacity of a single
track on the direct-access device being used. Device capacity for direct-access
devices is described in Appendix C of this publication. For additional information
about device capacity and space allocation, refer to OS/VS Data Management
Services Guide.
Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a'DD statement, by the problem program before completion of
the data control block exit routine, or by the data set label of an existing data set.
BUFCB= relexp
The BUFCB operand specifies the address of the buffer pool control block when
the buffer pool is constructed by a BUILD macro instruction.
If the buffer pool is constructed automatically, dynamically, or by a GETPOOL

macro instruction, the system places the address of the buffer pool control block
into the data control block, and the BUFCB operand is not required. The BUFCB
operand is not required if the problem program controls all buffering.
Source: The BUFCB operand can be supplied in the DCB macro instruction or by the
problem program before completion of the data control block exit routine.
BUFL= absexp (maximum value is 32,760)
The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool
when the buffers are acquired automatically (create BDAM) or dynamically
(existing BDAM).
When buffers are acquired automatically (create BDAM), the BUFL operand is
optional; if specified, the value must be at least as large as the sum of the values
specified for the KEYLEN and BLKSIZE operands. If the BUFL operand is
omitted,the system constructs buffers with a length equal to the sum of the values
specified in the KEYLEN and BLKSIZE operands.
The BUFL operand must be specified when an existing BDAM data set is being
processed and dynamic buffering is requested. Its value must be at least as large as
the value specified for the BLKSIZE operand when the READ or WRITE macro
instruction specifies a key address, or the value specified in the BUFL operand must
be at least as large as the sum of the values specified in the KEYLEN and BLKSIZE
operands if the READ and WRITE macro instructions specify'S' for the key
address.
The BUFL operand can be omitted if the buffer pool·is constructed by a BUILD or
GETPOOL macro instruction or if the problem program controls all buffering.
Source: The BUFL operand can be supplied in the DCB macro instruction, in the DCB
subparameter of a DD statement, or by the problem program before completion of the
data control block exit routine.

Macro Instruction Descriptions 47

BUFNO= absexp (maximum value is 255)
The BUFNO operand specifies the number of buffers to be constructed by a
BUILD macro instruction, or it specifies the number of buffers and/or segment
work areas to be acquired by the system.
If the buffer pool is constructed by a BUILD macro instruction or if buffers are

acquired automatically when BSAM is used to create a BDAM data set, the number
of buffers must be specified in the BUFNO operand.
If dynamic buffering is requested when an existing BDAM data set is being

processed, the BUFNO operand is optional; if omitted, the system acquires two
buffers.
If variable-length spanned records are being processed and dynamic buffering is
requested, the system also acquires a segment work area for each buffer. If

dyanmic buffering is not requested, the system acquires the number of segment
work areas specified in the BUFNO operand. If the BUFNO operand is omitted
when variable-length spanned records are being processed and dynamic buffering is
not requested, the system acquires two segment work areas.
If the buffer pool is constructed by a GETPOOL macro instruction or if the

problem program controls all buffering, the BUFNO operand can be omitted, unless
it is required to acquire additional segment work areas· for variable-length spanned
records.
Source: The BUFNO operand can be supplied in the DeB macro instruction, in the
DeB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine.
DDNAME= symbol
The DDNAME operand specifies the name used to identify the job control language
data definition (DD) statement that defines the data set being created or processed.
Source: The DDNAME operand can be supplied in the DeB macro instruction or by
the problem program before an OPEN macro instruction is issued to open the data set.
IDA}
DSORG= IDAU}
The DSORG operand specifies the data set organization and if the data set contains
any location-dependent information that would make it unmovable. For example,
if actual device addresses are used to process a BDAM data set, the data set may be
unmovable. The following describes the characters that can be specified:
DA

Specifies a direct organization data set.

DAU -

Specifies a direct organization data set that contains location-dependent
information.

When a BDAM data set is created, the basic sequential access method (BSAM) is
used. The DSORG operand in the DeB macro instruction must be coded as
DSORG=PS or PSU when the data set is created, and the DeB subparameter in
the corresponding DD statement must be coded as DSORG=DA or DAU. This
creates a data set with a data set label identifying it as a BDAM data set.
Source: The DSORG operand must be specified in the DeB macro instruction. See
the above comment about creating a BDAM data set.

48 OS/VS Data Management Macro Instructions

DCB-BDAM
EXLST = relexp
The EXLST operand specifies the address of the problem program exit list. The
EXLST operand must be specified if the problem program processes user labels
during the Open or Close routine, if the data control block exit routine is used for
additional processing, or if the DCB ABEND exit is used for ABEND condition
analysis.
Refer to Appendix 0 of this publication for the format and requirements of exit list
processing. For additional information about exit list processing, refer to OS / VS
Data Management Services Guide.
Source: The EXLST operand can be supplied in the DCB macro instruction or by the
problem program before the exit is needed.
KEYLEN= absexp (maximum value is 255)
The KEYLEN operand specifies the length, in bytes, of all keys used in the data set.
When keys are used, a key is associated with each data block in the data set. If
the key length is not supplied by any source, no input or output requests that
require a key can be specified in a READ or WRITE macro instruction.
Source: The KEYLEN operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DO statement, by the problem program before the completion
of the data control block exit routine, or by an existing data set label.
LIMCT= absexp
The LIMCT operand specifies the number of blocks or tracks to be searched when
the extended search option (OPTCD=E) is requested.
When the extended search option is requested and relative bloc~ addressing is used,
the records must be fixed-length record format. The system converts the number
of blocks specified in the LIMCT operand into the number of tracks required to
contain the blocks, then proceeds in the manner described below for relative track
addressing.
When the extended search option is requested and relative track addressing is used
(or the number of blocks has been converted to the number of tracks), the system
searches for the block specified in a READ or WRITE macro instruction (type DK),
or it searches for available space in which to add a block (WRITE macro
instruction, type DA). The search is as follows:
•

The search begins at the track specified by the block address operand of a
READ or WRITE macro instruction.

•

The search continues until the search is satisfied, the number of tracks
specified in the LIMCT operand have been searched, or the entire data set has
been searched. If the search has not been satisfied when the last track of the
data set is reached, the system continues the search by starting at the first track
of the data set. This operation allows the number specified in the LIMCT
operand to exceed the size of the data set, causing the entire data set to be
searched.

Macro Instruction Descriptions 49

The problem program can change the DCBLIMCT field in the data control block at
any time, but if the extended search option is used, the DCBLIMCT field must not
be zero when a READ or WRITE macro instruction is issued.
If the extended search option is not requested, the system ignores the LIMCT

operand, and the search for a data block is limited to a single track.
Source: The LIMCT operand can be supplied in the DCB macro instruction, the DCB
subparameter of a DD statement, or by the problem program before the count is
required by a READ or WRITE macro instruction.
MACRF= {(R {K

U
{KI
{(W {A
{K

}
}
}

IX I
IS I
IXS I

IC))

} IC))
}
}

{AK }
{AI }
{KI }
{AKI}
{(R {K

U
{KI

}
}
}

IX I
IS I
IXS I

ICI

{A
{K

}
}
}

IC)) }

{AK }
{AI }
{KI }
{AKI}
The MACRF operand specifies the type of macro instructions (READ, WRITE,
CHECK, and WAIT) used when the data set is processed. The MACRF operand
also specifies the type of search argument and BDAM functions used with the data
set. When BSAM is used to create a BDAM data set, the BSAM operand
MACRF= WL is specified. This special operand invokes the BSAM routine that can
create a BDAM data set. The following describes the characters that can be
specified:
A

Specifies that data blocks are to be added to the data set.

Specifies that CHECK macro instructions are used to test for completion
or read and write operations. If C is not specified, WAIT macro
instructions must be used to test for completion of read and write
operations.

Specifies that the search argument is to be the block identification portion
of the data block. If relative addressing is used, the system converts the
relative address to a full device address (MBBCCHHR) before the
search.

Specifies that the search argument is to be the key portion of the data
block. The location of the key to be used as a search argument is
specified in a READ or WRITE macro instruction.

50 OS/VS Data Management Macro Instructions

DCB-BDAM
R

Specifies that READ macro instructions are used. READ macro
instructions can be issued when the data set is opened for INPUT,
OUTPUT, or UPDAT.

Specifies that dynamic buffering is requested by specifying'S' in the area
address operand of a READ or WRITE macro instruction.

Specifies that WRITE macro instructions are used. WRITE macro
instructions can be issued only when the data set is opened for OUTPUT
OR UPDAT.
Specifies that READ macro instructions request exclusive control of a
data block. When exclusive control is requested, the data block must be
released by a subsequent WRITE or RELEX macro instruction.

Source: The MACRF operand must be supplied in the DCB macro instruction.
OPTCD= [R)(E)[F)(W]
(A]

The OPTCD operand specifies the optional services that are to be used with the
BDAM data set. These options are related to the type of addressing used, the
extended search option, block position feedback, and write-validity checking. The
following describes the characters that can be specified; the characters can be
specified in any order and no commas are required between characters.
A

Specifies that actual device addresses (MBBCCHHR) are provided to the
system when READ or WRITE macro instructions are issued.

Specifies that the extended search option is used to locate data blocks or
available space into which a data block can be added. When the
extended search option is specified, the number of blocks or tracks to be
searched must be specified in the LIMCT operand. The extended search
option is ignored if actual addressing (OPTCD=A) is also specified.

Specifies that block position feedback requested by a READ or WRITE
macro instruction is to be in the same form that was originally presented
to the system in the READ or WRITE macro instruction. If the F
operand is omitted, the system provides feedback, when requested, in the
form of an 8-byte actual device address.

Specifies that relative block addresses (in the form of a 3-byte binary
number) are provided to the system when a READ or WRITE macro
instruction is issued.

Specifies that the system performs a validity check for each record
written.

Note: If OPTCD=A and R are both omitted, the system requires that READ and
WRITE macro instructions provide 3-byte relative track addresses (in the form TTR).
Source: The OPTCD operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before an OPEN
macro instruction is issued to open the data set.

Macro Instruction Descriptions 51

RECFM= {V
{V (S)

J
J

(BS)
{F IT)

}

The RECFM operand specifies the format and characteristics of the records in the
data set. The following describes the characters that can be coded; if the optional
characters are. coded, they must be coded in the order shown above.
B

Specifies that the data set contains blocked records. The record format
RECFM= VBS is the only combination in which B can be specified.
RECFM= VBS does not cause the system to process spanned records; the
problem program must block and segment the records. RECFM= VBS is
treated as a variable-length record by BDAM.

Specifies that the data set contains fixed-length records.

Specifies that the data set contains variable-length spanned records when
it is coded as RECFM= VS. When RECFM= VBS is coded, the records
are treated as variable-length records, and the problem program must
block and segment the re.cords.

Specifies that the tr~ck-overflow feature is used with the data set. The
track-overflow feature allows a record to be partially written on one
track and the remainder is written on the following track (if required).

Specifies that the data set contains undefined-length records.

Specifies that the data set contains variable-length records.

The SYNAD operand specifies the address of the error analysis routine to be given
control when an uncorrectable input/output error occurs. The contents of the
registers when the error analysis routine is given control are described in Appendix
A of this publication.
The error analysis routine must not use the save area pointed to by register 13
because this area is used by the system. The system does not restore registers when
it regains control from the error analysis routine .. The error analysis routine can
issue a RETURN macro instruction which uses the address in register 14 to return
control to the system. When control is returned in this manner, the system returns
control to the problem program and proceeds as though no error had been
encountered. When a BDAM data set is being created, a return from the error
analysis routine to the system causes abnormal termination of the task.
If the SYNAD operand is omitted, the task is abnormally terminated when an

uncorrectable input/output error occurs.
Source: The SYNAD operand can be supplied in the DCB macro instruction or by the
problem program. The problem program can also change the error routine address at
any time.

52 OS/VS Data Management Macro Instructions

DCB-BISAM

DCB -

Construct a Data Control Block (BISAM)
The data control block for the basic indexed sequential access method (BISAM) is
constructed during assembly of the problem program. The DCB macro instruction
must not be coded within the first 16 bytes of a control section (CSECT). The
DSORG and MACRF operands must be coded in the DCB macro instruction, but the
other DCB operands can be supplied from other sources. Each BISAM DCB operand
description contains a heading, "Source." The information under this heading describes
the sources from which the operand can be supplied to the data control block.
Before a DCB macro instruction for a BISAM data set is coded, the following
characteristics of BISAM data sets should be considered:
•

BISAM cannot be used to create an indexed sequential data set.

•

BISAM performs the functions of direct retrieval of a logical record by key, direct
update-in-place for a block of records, direct insertion of a new record in its
correct key sequence.

•

Buffering can be controlled by the problem program, or dynamic buffering can be
specified in the DCB macro instruction and subsequently requested in a READ
macro instruction.

•

The problem program must synchronize I/O operations by issuing a CHECK or
WAIT macro instruction to test for completion of Read and Write operations.

•

Additional DCB operands provide the capability of reducing input/output
operations by defining work areas to contain the highest level master index and the
records being processed.

For additional information about the characteristics of BISAM processing, refer to
OS/VS Data Management Services Guide.
The following describes the DCB operands that can be supplied when the basic indexed
sequential access method is used.
{F}

BFALN= {D}
The BFALN operand specifies the boundary alignment for each buffer in the buffer
pool when the buffer pool is acquired for use with dynamic buffering or when the
buffer pool is constructed by a GETPOOL macro instruction. If the BFALN
operand is omitted, the system provides doubleword alignment for each buffer. The
following describes the characters that can be specified.
F

Specifies that each buffer is on a fullword boundary that is not also a
double word boundary.

Specifies that each buffer is on a doubleword boundary.

If the BUILD macro instruction is used to construct the buffer pool or the problem
program controls all buffering, the problem program must provide an area for the
buffers and control buffer alignment.

Macro Instruction Descriptions 53

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

Source: The BFALN operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine.
BUFCB= relexp
The BUFCB operand specifies the address of the buffer pool control block when
the buffer pool is constructed by a BUILD macro instruction.
If dynamic buffering is requested or the buffer pool is constructed by a GETPOOL

macro instruction, the system places the address of the buffer pool control block
into the data control block, and the BUFCB operand must be omitted. The BUFCB
operand must be omitted if the problem program controls all buffering.
Source: The BUFCB operand can be supplied in the DCB macro instruction or by the
problem program before completion of the data control block exit routine.
BUFL= absexp (maximum value is 32,760)
The BUFL operand specifies the length of each buffer to be constructed by a
BUILD or GETPOOL macro instruction. When the data set is opened, the system
computes the minimum length required and verifies that the length in the buffer
pool control block is equal to or greater than the minimum required. The system
then inserts the computed length into the BUFL field of the data control block.
If dynamic buffering is requested, the system computes the buffer length required,

and the BUFL operand is not required.
If the problem program controls all buffering, the BUFL operand is not required.

However, an ISAM data set requires additional buffer space for system use. For a
description of the buffer length required for various ISAM operations, refer to
OS/VS Data Management Services Guide.
Source: The BUFL operand can be supplied in the DCB macro instruction, in the DCB
subparameter of a DD statement, or by the problem program before completion of the
data control block exit routine.
BUFNO= absexp (maximum value is 255)
The BUFNO operand specifies the number of buffers requested for use with
dynamic buffering, or it specifies the number of buffers to be constructed by a
BUILD macro instruction. If dynamic buffering is requested but the BUFNO
operand is omitted, the system automatically acquires two buffers for use with
dynamic buffering.
If the GETPOOL macro instruction is used to construct the buffer pool, the

BUFNO operand is not required.
Source: The BUFNO operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine.
DDNAME= symbol
The DDNAME operand specifies the name used to identify the job control language
data definition statement that defines the ISAM data set to be processed.

54 OS/VS Data Management Macro Instructions

DCB -

BISAM

Source: The DDNAME operand can be supplied in the DCB macro instruction or by
the problem program before an OPEN macro instruction is issued to open the data set.
DSORG=IS
The DSORG operand specifies the indexed sequential organization of the data set.
IS is the only combination of characters that can be coded for BISAM.
Source: The DSORG operand must be coded in the DCB macro instruction.
EXLST= relexp
The EXLST operand specifies the address of the problem program exit list. The
EXLST operand is required if the problem program uses the data control block exit
routine for additional processing or if the DCB ABEND exit is used for ABEND
condition analysis.
Refer to Appendix D of this publication for the format and requirements for exit list
processing. For additional information about exit list processing, refer to OS / VS
Data Management Services Guide.
Source: The EXLST operand can be supplied in the DCB macro instruction or by the
problem program before the associated exit is required.
{(R
MACRF=

[S) [CD

{U}
{(W {A} [CD
{UA}
{(R

LS) [C),W {U} [CD}
[U)
{A}
[US)
{UA}

TheMACRF operand specifies the type of macro instructions (READ, WRITE,
CHECK, WAIT, and FREEDBUF) and type of processing (add records, dynamic
buffering, and update records) to be used with the data set being processed. The
operand can be coded in any of the combinations shown above; the following
describes the characters that can be coded.
A

Specifies that new records are to be added to the data set. This character
must be coded if WRITE KN macro instructions are used with the data
set.

Specifies that the CHECK macro instruction is used to test I/O
operations for completion. If C is not coded, WAIT macro instructions
must be used.

Specifies the READ macro instructions are used. When R is coded, the
routines that allow the FREEDBUF macro instruction to be used are also
included.

Specifies that dynamic buffering is requested in READ macro
instructions.

Specifies that records in the data set will be updated in place. If U is
coded in combination with R, it must also be coded in combination with
W. For example, MACRF=(RU,WU).

Specifies that WRITE macro instructions are used.
Macro Instruction Descriptions 55

Source: The MACRF operand must be coded in the DCB macro instruction.
MSHI = relexp
The MSHI operand specifies the address of the storage area used to contain the
highest level master index for the data set. The system uses this area to reduce the
search time required to find a given record in the data set. The MSHI operand is
coded only when the SMSI operand is coded.
Source: The MSHI operand can be supplied in the DCB macro instruction or by the
problem program before completion of the data control block exit routine.
MSW A= relexp
The MSW A operand specifies the address of the storage work area to be used by
the system when new records are being added to the data set. This operand is
optional, but the system acquires a minimum-size work area if the operand is
omitted. The MSW A operand is coded only when the SMSW operand is coded.
Processing efficiency can be increased if more than a minimum-size work area is
provided. For more detailed information about work area size, refer to OS/VS
Data Management Services Guide.
Note: QISAM uses the DCBMSW A, DCBSMSI, and DCBSMSW fields in the data
control block as a work area; these fields contain meaningful information only when
the data set is opened for BISAM.
Source: The MSW A operand can be supplied in the DCB macro instruction or by the
problem program before completion of the data control block exit routine.
NCP= absexp (maximum value is 99)
The NCP operand specifies the maximum number of READ/WRITE macro
instructions that are issued before the first CHECK (or WAIT) macro instruction is
issued to test for completion of the I/O operation. The maximum number that can
be specified may be less than 99 depending on the limit established when the
operating system is generated. If the NCP operand is omitted, one is assumed. If
dynamic buffering is used, the value specified for the NCP operand must not exceed
the number of buffers specified in the BUFNO operand.
Source: The NCP operand can be supplied in the DCB macro instruction, in the DCB
subparameter of a DD statement, or by the problem program before an OPEN macro
instruction is issued to open the data set.
SMSI= absexp (maximum value is 65,535)
The SMSI operand specifies the length, in bytes, required to contain the highest
level master index for the data set being processed. The size required can be
determined from the DCBN CRHI field of the data control block. When an ISAM
data set is created (with QISAM), the size of the highest level index is inserted into
the DCBNCRHI field. If the value specified in the SMSI operand is less than the
value in the DCBNCRHI field, the task is abnormally terminated.
Note: QISAM uses the DCBMSW A, DCBSMSI, and DCBSMSW fields as a work
area; these fields contain meaningful information only when the data set is opened for
BISAM.

56 OS/VS Data Management Macro Instructions

DCB -

BISAM

Source: The SMSI operand can be supplied in the DCB macro instruction or by the
problem program before completion of the data control block exit routine.
SMSW= absexp (maximum value is 65,535)
The SMSW operand specifies the length, in bytes, of a work area that is used by
BISAM. This operand is optional, but the system acquires a minimum-size work
area if the operand is omitted. The SMSW operand is coded only when the MSW A
operand is also coded. If the SMSW operand is coded but the size specified is less
than the minimum required, the task is abnormally terminated. OS / VS Data
Management Services Guide describes the methods of calculating the size of the
work area.
If unblocked records are used, the work area must be large enough to contain all

the count fields (eight bytes each), key fields, and data fields contained on one
direct-access device track.
If blocked records are used, the work area must be large enough to contain all the

count fields (eight bytes each) and data fields contained on one direct-access device
track plus additional space for one logical record (LRECL value).
Note: QISAM uses the DCBMSW A, DCBSMSI, and DCBSMSW fields in the data
control block as a work area; these fields contain meaningful information only when
the data set is opened for BISAM.
Source: The SMSW operand can be supplied in the DCB macro instruction or by the
problem program before completion of the data control block exit routine.
SYNAD= relexp
The SYNAD operand specifies the address of the error anlaysis routine given
control when an uncorrectable input/output error occurs. The contents of the
registers when the error analysis routine is given control are described in Appendix
A of this publication.
The error anlaysis routine must not use the save area pointed to by register 13
because this area is used by the system. The system does not restore registers when
it regains control from the error analysis routine. The error analysis routine can
issue a RETURN macro instruction which uses the address in register 14 to return
control to the system. When control is returned in this manner, the system returns
control to the problem program and proceeds as though no error had been
encountered. If the error analysis routine continues processing, the results are
unpredictable.
For ISAM data sets, if the error analysis routine receives control from the Close
routine, bit 3 of the IOBFLAG 1 field in the input/output block is set to one. In
this case, the error analysis routine must not issue a CLOSE macro instruction. To
complete Close processing, the error analysis routine must return control to the
Close routine with a branch to the address in register 14.
If the SYNAD operand is omitted, the task is abnormally terminated when an

DCB-BPAM

DCB -

Construct a Data Control Block (BPAM)
The data control block for the basic partitioned access method (BP AM) is constructed
during assembly of the problem program. The DCB macro instruction can be coded at
any point in a control section (CSECT). The DSORG and MACRF operands must be
specified in the DCB macro instruction, but the other DCB operands can be supplied
from other sources. Each of the BP AM DCB operand descriptions contains a heading,
"Source." The information under this heading describes the sources which can supply
the operand to the data control block.
Before a DCB macro instruction for a BP AM data set is coded, the following
characteristics of partitioned data sets should be considered:
•

The entire partitioned data set must reside on one direct-access volume, but several
such data sets, on the same or different volumes, can be concatenated for input.

•

When a partitioned data set is being created, the first (or only) DD statement for
the data set must contain a SPACE parameter defining the size of the entire data
set and its directory. From this information, the system allocates space for the data
set and pre-formats the data set directory. As subsequent data set members are
added, they are added in the space originally allocated.

•

A single member of a partitioned data set can be added or retrieved using BSAM or
QSAM without using the BLDL, FIND, or STOW macro instructions. In this case,
the data set member is being processed as a sequential data set (DSORG=PS).
Processing a member in this manner does not provide the full capability of the basic
partitioned access method. For more information about processing a member using
BSAM or QSAM, refer to OS/VS Data Management Services Guide.

•

A single member or multiple members can be added, retrieved, or updated using
BPAM (many of the routines used by BPAM are actually BSAM routines).

•

Buffers for a BPAM data set can be acquired automatically, but buffer control must
be provided by the problem program. The problem program must issue a READ
macro instruction that provides a buffer address to fill an input buffer, and it must
place the data in an output buffer before issuing a WRITE macro instruction to
write a data block.

•

Although a BPAM data set can contain blocked records, the problem program must
perform all blocking and deblocking of records. BPAM provides only the capability
to read or write a data block, but the data block can contain multiple logical records
assembl~d by the problem program.

•

The STOW macro instruction can be used to add, delete, change, or replace a
member name or alias in the directory.

•

Multiple members of the data set can be processed by building a list of member
locations (with a BLDL macro instruction) and using the FIND macro instruction
(in conjunction with the list) to locate the beginning of each member.

•

The problem program must synchronize 110 operations by issuing a CHECK macro
instruction for each READ or WRITE macro instruction issued.

Macro Instruction Descriptions 59

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

These characteristics of partitioned data sets and the basic partitioned access method
are described in more detail in OS/VS Data Management Services Guide.
The following describes the DCB operands that can be specified when a BP AM data
set is being created or processed.

{F}
BFALN= {D}

The BFALN operand specifies the boundary alignment for each buffer in the buffer
pool when the buffer pool is constructed automatically or by a GETPOOL macro
instruction. If the BFALN operand is omitted, the system provides double word
alignment for each buffer. The following describes the characters that can be
specified in the BFALN operand.
F

Specifies that each buffer is aligned on a fullword boundary that is not
also a doubleword boundary.

Specifies that each buffer is aligned on a doubleword boundary.

If the BUILD macro instruction is used to construct the buffer pool or if the

problem program controls all buffering, the problem program must provide an area
for the buffers and control buffer alignment.
Source: The BFALN operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine.
BLKSIZE= absexp (maximum value is 32,760)

The BLKSIZE operand specifies the length, in bytes, of each data block for
fixed-length records, or it specifies the maximum length, in bytes, for
variable-length or undefined-length records. If keys are used, the length of the key
is not included in the value specified for the BLKSIZE operand.
The actual blocksize that can be specified depends on the record format and the
type of direct-access device being used. If the track-overflow feature is used, the
blocksize can be up to the maximum. If the track-overflow feature is not used, the
maximum blocksize is determined by the track capacity of a single track on the
direct-access device being used. Device capacity for direct-access devices is
described in Appendix C of this publication. For additional information about
device capacity and space allocation, refer to OS/VS Data Management Services
Guide.
For variable-length records, the value specified in the BLKSIZE operand must
include the maximum logical record length (up to 32,756 bytes) plus four bytes for
the block descriptor word (BDW).
For undefined-length records, the value specified for the BLKSIZE operand can be
altered by the' problem program when the actual length becomes known to the
problem program. The value can be inserted into the DCBBLKSI field of the data
control block or specified in the length operand of a READ/WRITE macro
instruction.

60 OS/VS Data Management Macro Instructions

DCB-BPAM
Source: The BLKSIZE operand can be supplied in the DeB macro instruction, in the
DeB subparameter of a DD statement, by the problem program before completion of
the data control block exit routine, or by the data set label of an existing data set.
BUFCB= relexp
The BUFCB operand specifies the address of the buffer pool control block when
the buffer pool is constructed by a BUILD macro instruction.
If the buffer pool is constructed automatically or by a GETPOOL macro

instruction, the system places the address of the buffer pool control block into the
data control block and the BUFCB operand can be omitted. Also, if the problem
program controls all buffering, the BUFCB operand should be omitted.

Source: The BUFCB operand can be supplied in the DeB macro instruction or by the
problem program before completion of the data control block exit routine.
BUFL= absexp (maximum value is 32,760)
The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool
when the buffer pool is acquired automatically. If the BUFL operand is omitted
and the buffer pool is acquired automatically, the system acquires buffers with a
length that is equal to the sum of the values specified in the KEYLEN and
BLKSIZE operands. If the problem program requires longer buffers, the BUFL
operand should be specified.
If the problem program controls all buffering, the BUFL operand is not required.

Source: The BUFL operand can be supplied in the DeB macro instruction, in the DeB
subparameter of a DD statement, or by the problem program before completion of the
data control block exit routine.
BUFNO= absexp (maximum value is 255)
The BUFNO operand specifies the number of buffers to be constructed by a
BUILD macro instruction, or it specifies the number of buffers to be acquired
automatically by the system.
If the problem program controls all buffering or if the buffer pool is constructed by

a GETPOOL macro instruction, the BUFNO operand should be omitted.

Source: The BUFNO operand can be supplied in the DeB macro instruction, in the
DeB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine.
DDNAME= symbol
The DDNAME operand specifies the name used to identify the job control language
data definition (DD) statement that defines the data set being created or processed.

Source: The DDNAME operand can be supplied in the DeB macro instruction or by
the problem program before an OPEN macro instruction is issued to open the data set.

Macro Instruction Descriptions 61

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-074S

{POI
DSORG= {POUI
The DSORG operand specifies the data set organization and if the data set contains
any location-dependent information that would make it unmovable. The following
describes the characters that can be specified.
PO

Specifies a partitioned data set organization.

POU -

Specifies a partitioned data set organization and that the data set
contains location-dependent information.

Note: If BSAM or QSAM is used to add or retrieve a single member of a partitioned
data set, a sequential access method is being used, and the DSORG operand is
specified as PS or PSU. The name of the member being processed in this manner is
supplied in a DD statement.
Source: The DSORG operand must be specified in the DCB macro instruction.
EODAD= relexp
The EODAD operand specifies the address of the routine given control when the
end of the input data set is reached. Control is given to this routine when an input
request is made (READ macro instruction) and there are no additional input
records to retrieve. The routine is entered when a CHECK macro instruction is
issued and the end of the data set is reached. When your EODAD routine receives
control, register contents (except for register 15) will be the same as they were
when the last CHECK macro instruction was issued. Register 15 will contain a
hexadecimal 4 if you have processed an end-of-volume tape label; otherwise,
register 15 will contain a O. If the end of the data set is reached and no EODAD
address has been supplied, the task is abnormally terminated.
Source: The EODAD operand can be supplied in the DCB macro instruction or by the
problem program before the end of the data set is reached.
EXLST= relexp
The EXLST operand specifies the address of the problem program exit list. The
EXLST operand is required if the problem program uses the data control block exit
routine for additional processing or if the DCB ABEND exit is used for ABEND
condition analysis.
Refer to Appendix D of this publication for the format and requirements of the exit
list processing. For additional information about exit list processing, refer to
OS/VS Data Managetnent Services Guide.
Source: The EXLST operand can be supplied in the DCB macro instruction or by the
problem program before the OPEN macro instruction is issued to open the data set.
KEYLEN= absexp (maximum value is 255)
The KEYLEN operand specifies the length, in bytes, of the key associated with each
data block in the direct-access device data set. If the key length is not supplied
from any source by the end of the data control block exit routine, a key length of
zero (no keys) is assumed.
Source: The KEYLEN operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, by the problem program before the completion
of the data control block exit routine, or by the data set label of an existing data set.
62 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Added December 15, 1972
By TNL GN26-0748

DCB-BPAM

LRECL= absexp (maximum value is 32,760)
The LRECL operand specifies the length, in bytes, of each fixed-length logical
record in the data set; It is required only for fixed-length records. The value

Macro Instruction Descriptions 62.1

DCB-BPAM
specified in the LRECL operand cannot exceed the value specified in the BLKSIZE
operand.
If the records are unblocked, the value specified in the LRECL operand must equal
the value specified in the BLKSIZE operand. If the records are blocked, the value
specified in the LRECL operand must be evenly divisible into the value specified in
the BLKSIZE operand.

Source: The LRECL operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, by the problem program before completion of
the data control block exit routine, or by the data set label of an existing data set.
MACRF= {(R)}
{(W)}

{(R,W)}
The MACRF operand specifies the type of macro instructions (READ, WRITE, and
NOTE/POINT) that are used to process the data set. The following describes the
characters that can be specified:
R

Specifies that READ macro instructions are used. This operand
automatically provides the capability to use both the NOTE and POINT
macro instructions with the data set.

Specifies that WRITE macro instructions are used. This operand
automatically provides the capability to use the NOTE macro instruction
with the data set.

All BP AM READ and WRITE macro instructions issued must be tested for
completion using a CHECK macro instruction. The MACRF operand does not
require any coding to specify that a CHECK macro instruction will be used.
Source: The MACRF operand must be specified in. the DCB macro instruction.
NCP= absexp (maximum value is 99)
The NCP operand specifies the maximum number of READ and WRITE macro
instructions that will be issued before the first CHECK macro instruction is issued.
The maximum number may be less than 99 depending on the limit established when
the operating system is generated. If chained scheduling is specified, NCP must be
specified as more than one. If the NCP operand is omitted, one is assumed.
Source: The NCP operand can be supplied in the DCB macro instruction, in the DCB
subparameter of a DO statement, or by the problem program before an OPEN macro
instruction is issued to open the data set.
OPTCD= {C}
{WI
{WC}
The OPTCD operand specifies the optional services performed by the system. The
following describes the characters that can be specified; they can be specified in any
order and no commas are required between characters.

Macro Instruction Descriptions 63

Specifies that chained scheduling is used. OS/VS supports chained
scheduling in nonpageable storage only. If chained scheduling is
requested in page able storage, the request is ignored and normal
scheduling is substituted.

Specifies that the system performs a validity check for each record
written.

Source: The OPTCD operand can be supplied in the DCB macro instruction, in the

DCB subparameter of a DO statement, or by the problem program before an OPEN
macro instruction is issued to open the data set. However, all optional services must be
requested from the same source.
RECFM= {U

(T)

(A)
1M)

{V (B)

(A)
(T) (M)
(BT)

(B) (A)
tTl (M)
(BT)

The RECFM operand specifies the record format and characteristics of the data set
being created or processed. All the record formats shown above can be specified,
but in those formats that show blocked records, the problem program must perform
the blocking and deblocking of logical records; BPAM recognizes only data blocks.
The following describes the characters that can be specified.
A

Specifies that the records in the data set contain American National
Standards Institute (ANSI) control characters. Refer to Appendix E for a
description of control characters.

Specifies that the data set contains blocked records.

Specifies that the data set contains fixed-length records.

Specifies that the records in the data set contain machine code control
characters. Refer to Appendix E for a description of control characters.

Specifies that the track-overflow feature is used with the data set. The
track-overflow feature allows a record to be written partially on one
track of a direct-access device and the remainder of the record written on
the following track (if required). Chained scheduling (OPTCD=C)
cannot be used if the track-overflow feature is used.

Specifies that the data set contains undefined-length records.

Specifies that the data set contains variable-length records.

Source: The RECFM operand can be supplied in the DCB macro instruction, in the

DCB subparameter of a DO statement, by the problem program before completion of
the data control block exit routine, or by the data set label of an existing data set.
SYNAD= relexp

The SYNAD operand specifies the address of the error analysis (SYNAD) routine
to be given control when an uncorrectable input/output error occurs. The contents
of the registers when the error analysis routine is given control are described in
Appendix A.
64 OS/VS Data Management Macro Instructions

DCB -

BPAM

The error analysis routine must not use the save area pointed to by register 13,
because this area is used by the system. The system does not restore registers when
it regains control from the error analysis routine. The error analysis routine can
return control to the system by issuing a RETURN macro instruction. If control is
returned to the system, the system returns control to the problem program and
proceeds a~ though no error had been encountered.
If the SYNAD operand is omitted, the task is abnormally terminated when an
uncorrectable input/output error occurs.
Source: The SYNAD operand can be supplied in the DCB macro instruction or by the

problem program. The problem program can also change the error routine address at
any time.

Macro Instruction Descriptions 65

DCB-BSAM

DCB -

Construct a Data Control Block (BSAM)
The data control block for the basic sequential access method (BSAM) is constructed
during assembly of the problem program. The DCB macro instruction must not be
coded within the first 16 bytes of a control section (CSECT). The DSORG and
MACRF operands must be coded in the DCB macro instruction, but the other DCB
operands can be supplied, to the data control block, from other sources. Each DCB
operand description contains a heading, "Source." The information under this heading
describes the sources from which an 'operand can be supplied.
Before a DCB macro instruction for creating or processing a BSAM data set is coded,
the following characteristics of BSAM data sets should be considered:
•

Although several record formats with blocked records can be specified for BSAM,
the problem program must perform all blocking and deblocking of records. BSAM
provides only the capability to read or write a data block, but the block can contain
one or more logical records assembled by the problem program.

•

Buffers for a BSAM data set can be acquired automatically, but buffer control must
be provided by the problem program. The problem program must issue a READ
macro instruction that provides a buffer address to fill an input buffer, and it must
place the data in an output buffer before issuing the WRITE macro instruction to
write a data block.

•

The problem program must synchronize I/O operations by issuing a CHECK macro
instruction for each READ and WRITE macro instruction issued.

•

BSAM provides capability for nonsequential processing by using the NOTE and
POINT macro instructions.

•

Keys for direct-access device records can be read or written using BSAM.

•

Specifying the DEVD operand in the DCB macro instruction can make the program
device dependent.

These characteristics of basic sequential access method data sets are described in more
detail in OS/VS Data Management Services Guide.
The following describes the operands that can be specified in the DCB macro
instruction for a BSAM data set.
BFALN=

IF}
ID}

The BFALN operand specifies the boundary alignment for each buffer in the buffer
pool when the buffer pool is constructed automatically or by a GETPOOL macro
instruction. If the BFALN operand is omitted, the system provides doubleword
alignment for each buffer.
If the data set being created or processed contains ASCII tape records with a block

prefix, the block prefix is entered at the beginning of the buffer, and data alignment
depends on the length of the block prefix. For a description of how to specify the
block prefix length, refer to the DCB BUFOFF operand.

Macro Instruction Descriptions 67

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

The following describes the characters that can be specified.
F

Specifies that each buffer is on a fullword boundary that is not also a
doubleword boundary.

Specifies that each buffer is on a double word boundary.

If the BUILD macro instruction is used to construct the buffer pool or if the

problem program controls all buffering, the problem program must provide an area
for the buffers and control buffer alignment.
Source: The BFALN operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data block exit routine. If both the BFALN and BFTEK operands are specified,
they must be supplied by the same source.
BFTEK=R

The BFfEK=R operand specifies that BSAM is used to read unblocked
variable-length spanned records with keys from a BDAM data set. Each read
operation reads one segment of the record and places it in the area designated in
the READ macro instruction. The first segment enters at the beginning of the area,
but all subsequent segments are offset by the length of the key (only the first
segment has a key). The problem program must provide an area in which to
assemble a record, identify each segment, and assemble the segments into a
complete record.
Source: The BYrEK operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine. If both the BYrEK and BFALN operands are
specified, they must be supplied from the same source.
BLKSIZE= absexp (maximum value is 32,760)

The BLKSIZE operands specifies the length, in bytes, for fixed-length records, or it
specifies the maximum length, in bytes, for variable-length or undefined-length
records. The BLKSIZE operand includes only the data block length; if keys are
used, the length of the key is not included in the value specified for the BLKSIZE
operand.
The actual value that can be specified in the BLKSIZE operand depends on the
device type and the record format being used. Device capacity is shown in
Appendix C of this publication. For additional information about device capacity,
refer to OS/VS Data Management Services Guide. For direct-access devices when
the track-overflow feature is used or variable-length spanned records are being
processed, the value specified in the BLKSIZE operand can be up to the maximum
value. For other record formats used with direct-access devices, the value specified
for BLKSIZE cannot exceed the capacity of a single track.
If fixed-length records are used for a SYSOUT data set, the value specified in the
BLKSIZE operand must be an integral multiple of the value specified for the logical
record length (LRECL); otherwise the system will adjust the blocksize downward to

the nearest multiple.
If variable-length records are used, the value specified in the BLKSIZE operand

must include the maximum logical record length (up to 32,756 bytes) plus the four
bytes required for the block descriptor word (BDW). For format-D

68 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15,1972
By TNL GN26-0748

DCB-BSAM
variable-length records (ASCII data sets), the minimum value for BLKSIZE is 18
and the maximum value is 2,048.
If ASCII tape records with a block prefix are processed, the value specified in the

BLKSIZE operand must also include the length of the block prefix.
If BSAM is used to read variable-length spanned records from a BDAM data set,

the value specified for the BLKSIZE operand must be as large as the longest
possible record segment in the BDAM data set, including four bytes for the segment
descriptor word (SDW) and four bytes for the block descriptor word (BDW).
If undefined-length records are used, the value specified for the BLKSIZE operand

can be altered by the problem program when the actual length becomes known to
the problem program. The value can be inserted directly into the DCBBLKSI field
of the data control block or specified in the length operand of a READ /WRITE
macro instruction.

Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, by the problem program before completion of
the data control block exit routine, or by the data set label of an existing data set.
BUFCB= relexp
The BUFCB operand specifies the address of the buffer pool control block in a
buffer pool constructed by a BUILD macro instruction.
If the buffer pool is constructed automatically or by a GETPOOL macro
instruction, the system places the address of the buffer pool control block into the
data control block, and the BUFCB operand should be omitted. If the problem
program controls all buffering, the BUFCB operand is not required.

Source: The BUFeB operand can be supplied in the DCB macro instruction or by the
problem program before completion of the data control block exit routine.
BUFL= absexp (maximum value is 32,760)
The BUFL operand specifies the length, in bytes, for each buffer in the buffer pool
when the buffer pool is acquired automatically. The system acquires buffers with a
length equal to the sum of the values specified in the KEYLEN and BLKSIZE
operands if the BUFL operand is omitted; if the problem program requires larger
buffers, the BUFL operand must be specified. If the BUFL operand is specified, it
must be at least as large as the value specified in the BLKSIZE operand. If the data
set is for cardimage mode, the BUFL operand should be specified as 160. The
description of the DEVD operand contains a description of card image mode.
If the data set contains ASCII tape records with a block prefix, the value specified

in the BUFL operand must include the block length plus the length of the block
prefix.
If the problem program controls all buffering or if the buffer pool is constructed by

a GETPOOL or BUILD macro instruction, the BUFL operand is not required.

Source: The BUFL operand can be supplied in the DCB macro instruction, in the DCB
subparameter of a DD statement, or by the problem program before completion of the
data control block exit routine.

Macro Instruction Descriptions 69

BUFNO= absexp (maximum value is 255)
The BUFNO operand specifies the number of buffers constructed by a BUILD
macro instruction or the number of buffers to be acquired automatically by the
system.
If the problem program controls all buffering or if the buffer pool is constructed by

a GETPOOL macro instruction, the BUFNO operand should be omitted.
Source: The BUFNO operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine.
BUFOFF= { absexpJ
{LJ
The BUFOFF operand specifies the length, in bytes, of the block prefix used with
an ASCII tape data set. When BSAM is used to read an ASCII tape data set, the
problem program must use the block prefix length to determine the location of the
data in the buffer. When BSAM is used to write an output ASCII tape data set, the
problem program must insert the block prefix into the buffer followed by the data
(BSAM considers the block prefix as data). The block prefix and data can consist
of any characters that can be translated into ASCII code; any character that cannot
be translated is replaced with a substitute character. The following can be specified
in the BUFOFF operand:
absexp -

Specifies the length, in bytes, of the block prefix. This value can be
from 0 to 99 for an input data set. The value must be 0 for writing an
output data set with fixed-length or undefined-length records (BSAM
considers the block prefix part of the data record).

Specifies that the block prefix is 4 bytes long and contains the block
length. BUFOFF=L is used when format-D records (ASCII) are
processed. When BUFOFF=L is specified, the BSAM problem
program can process the data records (using READ and WRITE macro
instructions) in the same manner as if the data were in format-V
variable-length records.
If the BUFOFF operand is omitted for an input data set with format-D

records, the system inserts the record length into the DCBLRECL field of
the data control block; the problem program must obtain the length from
this field to process the record.
If the BUFOFF operand is omitted from an output data set with format-D

records, the problem program must insert the actual record length into the
DCBBLKSI field of the data control block or specify the record length in
the length operand of a WRITE macro instruction.
Source: The BUFOFF operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before an OPEN
macro instruction is issued to open the data set.
DDNAME= symbol
The DDNAME operand specifies the name used to identify the job control language
data definition {DD) statement that defines the data set being created or processed.
Source: The DDNAME operand can be supplied in the DCB macro instruction or by
the problem program before an OPEN macro instruction is issued to open the data set.

70 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

DCB-BSAM
DEVD=

{DA [,KEYLEN= absexp]
{TA [,DEN=

{OI][,TRTCH= {CI] I
{EI
ttl
{TI
{21
{ETI
{31

{PT [,CODE= {Al]
{BI
{CI
{FI

{II
{NI
{TI

{PR (,PRTSP= {Ol]
ttl

{21

{31

{PC (,MODE= (C]

(R][,STACK=

(E]

{RD [,MODE=[C]
(E]

UI)(,FUNC=

{21

{P
{PW[XT]
{R
{RP(D]
{RW(T]
{RWP[XT](D]
{WIT]

[O]][,STACK= ttl][,FUNC=
(R]

{21

{P
{PW[XT]
{R
{RP(D]
{RW(T]
{RWP(XT](D]
{WIT]

In
I
I
I
I
I
I
I
In
I
I
I
I
I
I
I

The DEVD operand specifies the device type on which the data set can or does
reside. The device types above are shown with the optional operand(s) that can be
coded when a particular device is used. The devices are listed in order of
device-independence. For example, if DEVD=DA is coded in a DeB macro
instruction (or the DEVD operand is omitted, which causes a default to DA), the
data control block constructed during assembly could later be used for any of the
other devices, but if DEVD=RD is coded, the data control block can be used only
with a card reader or card reader punch. Unless you are certain that device
interchangeability is not required, you should either code DEVD=DA or omit the
operand and allow it to default to DA.
If system input is directed to an intermediate storage device, the DEVD operand is
omitted, and the job control language for the problem program designates the
system input device to be used. Likewise, if system output is directed to an
intermediate storage device, the DEVD operand is omitted, and the job control
language for the problem program designates the system output device to be used.

Macro Instruction Descriptions 71

The following describes the device type and the optional operands that can be
specified for each device type:
DA -

Specifies that the data control block can be used for a direct-access
device (or any of the other device types described following DA).
KEYLEN = absexp
The KEYLEN operand can be specified only for data sets that
reside on direct-access devices. Since the KEYLEN is usually
coded without a DEVD operand (default taken), the description
of the KEYLEN operand is in alphabetic sequence with the other
operands.

TA -

Specifies that the data control block can be used for a magnetic tape
data set (or any of the other device types described following TA). If
TA is coded, the following optional operands can be coded.
DEN= to}
{I}

{2}
{3}

The DEN operand specifies the recording density in the number of
bits-per-inch per track as shown in the following chart.
DEN 7-Track Tape 9-Track Tape

o
1
2

200
556
800

9-Track Tape 9-Track Tape
(Phase Encoded) (Dual Density)

800

1600

800 (NRZI)
1600 (PE)

NRZI is for non-return-to-zero-inverse mode
PE is for phase encoded mode
Specifying DEN =0 for a 7 track, 3420 tape will result in a 556
bits-per-inch recording density, but corresponding messages and tape
labels will indicate a 200 bits-per-inch recording density.
If the DEN operand is not supplied by any source, the highest

applicable density is assumed.
TRTCH= {C}

{E}
{ET}

{T}
The TRTCH operand specifies the recording technique for 7-track
tape. One of the above four character combinations can be coded. If
the TRTCH operand is omitted, odd parity with no translation or
conversion is assumed. The following describes the characters that can
be specified:
C

Specifies that the data-conversion feature is used with odd
parity and no translation.

Specifies even parity with no translation or conversion.

Specifies even parity with BCDIC to EBCDIC translation
required and no data-conversion feature.

Specifies that BCDIC to EBCDIC translation is required
with odd parity and no data-conversion feature.

72 OS/VS Data Management Macro Instructions

DCB-BSAM
PI -

Specifies that the data control block is used for a paper tape device (or
any of the other devices following PI). If PI is coded, the following
optional operand can be coded.
CODE=

{AI
{BI
{CI

{F}
01
{N}
{TI
The CODE operand specifies the code in which the data was punched.
The system converts these codes to EBCDIC code. If the CODE
operand is not supplied by any source, CODE=I is assumed. The
following describes the characters that can be specified.

PR-

Specifies 8-track tape in ASCII code.

Specifies Burroughs 7-track tape.

Specifies National Cash Register 8-track tape.

Specifies Friden 8-track tape.

Specifies IBM BCD perforated tape and transmission code
with 8 tracks.

Specifies that no conversion required.

Specifies Teletype l 5-track tape.

Specifies that the data control block is used for an online printer (or
any of the other device types following PR). If PR is coded, the
following optional operand can be coded.
PRTSP= {Ol

ttl
{21
{31

The PRTSP operand specifies the line spacing on the printer. This
operand is not valid if the RECFM operand specifies either machine
(RECFM=M) or ANSI (RECFM=A) control characters. If the
PRTSP operand is not specified from any source, one is assumed. The
following describes the characters that can be specified.

Specifies that spacing is suppressed (no space).

Specifies single-spacing.

Specifies double-spacing (one blank line between pnnted
lines).

Specifies triple-spacing (two blank lines between printed
lines).

Trademark of Teletype Corporation.

Macro Instruction Descriptions 73

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

Specifies that the data control block is used for a card punch (or any
of the other device types following PC). If PC is coded, the following
optional operands can be specified.
MODE= [CnR]
[E]

The MODE operand specifies the mode of operation for the card
punch. The following describes the characters that can be specified. If
the MODE operand is omitted, E is assumed.
C

Specifies that the cards are to be punched in card image
mode. In card image mode, the 12 rows in each card
column are punched from two consecutive bytes in virtual
storage. Rows 12 through 3 are punched from the
low-'-order 6 bits of one byte and rows 4 through 9 are
punched from the low-order 6 bits of the following byte.

Specifies that cards are to be punched in EBCDIC code.

Specifies that the program runs in read-column-eliminate
mode (3505 card reader or 3525 card punch, read feature).

Note: If the MODE operand is specified in the DCB subparameter of
a DD statement, either C or E must be specified if R is specified.
STACK= {l}
{2}

The STACK operand specifies the stacker bin into which the card is
placed after punching is completed. If this operand is omitted, stacker
number 1 is used. The following describes the characters that can be
specified:
1

Specifies stacker number 1.

Specifies stacker number 2.

FUNC=

}

{P
{PW[XT]
{R
{RP[D]
{RW[T]
{RWP[XT][D]
{WIT]

}
}
}
}
}
}
}

I The FUNC operand defines the type of 3525 card punch data sets that
are used. If the FUNC operand is omitted from all sources, a data set
opened for input defaults to read only, and a data set opened for
output defaults to punch only. The following describes the characters
that can be specified in the FUNC operand.
D

74 OS/VS Data Management Macro Instructions

Specifies that the data protection option is to be used. The
data protection option prevents punching information into
card columns that already contain data. When the data
protection option is used, an 80-byte data protection image
(DPI) must have been previously stored in
SYS l.IMAGELIB. Data protection applies only to the

DCB-BSAM
output/punch portion of a read and punch or read punch
and print operation.
I

Specifies that the data in the data set is to be punched into
cards and printed on the cards; the first 64 characters are
printed on line 1 of the card and the remaining 16
characters are printed on line 3.

Specifies that the data set is for punching cards. See the
description of the character X for associated punch and
print data sets.

Specifies that the data set is for reading cards.

Specifies that the two-line print option is used. The
two-line print option allows two lines of data to be printed
on the card (lines 1 and 3). If T is not specified, the
multiline print option is used; this allows printing on all 25
possible print lines. In either case, the data printed may be
the same as the data punched in the card, or it may be
entirely different data.

Specifies that the data set is for printing. See the
description of the character X for associated punch and
print data sets.

Specifies that an associated data set is opened for output for
both punching and printing. Coding the character X is used
to distinguish the 3525 printer output data set from the
3525 punch output data set.

Note: If data protection is specified, the data protection image (DPI)
must be specified in the FCB subparameter of the DD statement for
the data set.
RD -

The MODE operand specifies the mode of operation for the card
reader. The following describes the characters that can be specified:
C

Specifies that the cards to be read are in card image mode.
In card image mode, the 12 rows in each card column are
read into two consecutive bytes of virtual storage. Rows 12
through 3 are read into one byte and rows 4 through 9 are
read into the following byte.

Specifies that the cards to be read contain data in EBCDIC
code.

Macro Instruction Descriptions 75

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

Specifies that the program runs in optical-mark-read mode
(3505 card reader).

Specifies that the program runs in read-column-eliminate
mode (3505 card reader and 3525 card reader).

Note: If the MODE operand for a 3505 or 3525 is specified in the
DCB subparameter of a DD statement, either C or E must be specified
if R or 0 is specified.
STACK=

ttl
{21

The STACK operand specifies the stacker bin into which the card is
placed after reading is completed. If this operand is omitted, stacker
number 1 is used. The following describes the characters that can be
specified.
1
Specifies stacker number 1.
2 Specifies stacker number 2.
FUNC=

I
I
{PWIXT]
I
{R
I
{RPID]
I
{RWIT]
I
{RWPIXT]ID] I
{WIT]
I
{I
{P

The FUNC operand defines the type of 3525 card punch data sets that
are used. If the FUNC operand is omitted from all sources, a data set
opened for input defaults to read only, and a data set opened for
output defaults to punch only. The following describes the characters
that can be specified in the FUNC operand.
D

Specifies that the data set is for punching cards. See the
description of the character X for associated punch and
print data sets.

Specifies that the data set is for reading cards.

Specifies that the two-line print option is used. The
two-line print option allows two lines of data to be printed

76 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

DCB-BSAM
on the card (lines 1 and 3). If T is not specified, the
multiline print option is used; this allows printing on all 25
possible print lines. In either case, the data printed may be
the same as the data punched in the card, or it may be
entirely different data.
W

Specifies that the data set is for printing. See the
description of the character X for associated punch and
print data sets.

Note: If data protection is specified, the data protection image (DPI)
must be specified in the FCB subparameter of the DD statement for
the data set.
Source: The DEVD operand can be supplied only in the DCB macro instruction.
However, the optional operands can be supplied in the DCB macro instruction, the
DCB subparameter of a DD statement, or by the problem program before
completion of the data control block exit routine.
DSORG= IPS}
{PSU}
The DSORG operand specifies the organization of the data set and if the data set
contains any location-dependent information that would make it unmovable. The
following can be specified.
PS

Specifies a physical sequential data set.

PSU -

Specifies a physical sequential data set that contains location-dependent
information that would make it unmovable.

Source: The DSORG operand must be coded in theDCB macro instruction.
EODAD= relexp
The EODAD operand specifies the address of the routine given control when the
end of an input data set is reached. Control is given to this routine when a READ
macro instruction is issued and there are no additional input records to be retrieved.
If the record format is RECFM=FS or FBS, the end-of-data condition is sensed
when a file mark is read or when more data is requested after reading a truncated
block. The end of data routine is entered when the CHECK macro instruction
determines that the READ macro instruction reached the end of the data. When
your EODAD routine receives control, register contents (except for register 15) will
be the same as they were when the last CHECK macro instruction was issued.
Register 15 will contain a hexadecimal 4 if you have processed an end-of-volume
tape label; otherwise, register 15 will contain a O. If the end of the data set is
reached but no EODAD address has been supplied, the task is abnormally
terminated.
When the data set has been opened for UPDAT and volumes are to be switched,
the problem program should issue a FEOV macro instruction after the EOOAD
routine has been entered.
Macro Instruction Descriptions 77

Source: The EODAD operand can be supplied in the DCB macro instruction or by the
problem program before the end of the data set is reached.
EXLST= relexp
The EXLST operand specifies the address of the problem program exit list. The
EXLST operand is· required if the problem program requires additional processing
for user labels, user totaling, data control block exit routine, end-of-volume, block
count exits, to define a forms control buffer (FCB) image, or to use the DCB
ABEND exit for ABEND condition analysis.
Refer to Appendix D of this publication for the format and requirements of exit list
processing. For additional information about exit list processing, refer to OS/VS
Data Management Services Guide.
Source: The EXLST operand can be supplied in the DCB macro instruction or by the
problem program any time before the exit is required by the problem program.
KEYLEN= absexp (maximum value is 255)
The KEYLEN operand specifies the length, in bytes, for the key associated with
each data block in a direct-access device data set. If the key length is not supplied
from any source before completion of the data control block exit routine, a key
length of zero (no keys) is assumed.
Source: The KEYLEN operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, by the problem program before the completion
of the data control block exit routine, or by the data set label of an existing data set.
LRECL= { absexp}
{X}

The LRECL operand specifies the length, in bytes, for fixed-length records, or it
specifies the maximum length, in bytes, for variable-length records. LRECL=X is
used for variable-length spanned records that exceed 32,756 bytes. Except when
variable-length spanned records are used, the value specified for the LRECL
operand cannot exceed the value specified for the BLKSIZE operand.
Except when variable-length spanned records are used, the LRECL operand can be
omitted for BSAM; the system uses the value specified in the BLKSIZE operand. If
the LRECL value is coded, it is coded as described in the following.
For fixed-length records that are unblocked, the value specified in the LRECL
operand should be equal to the value specified in the BLKSIZE operand. For
blocked fixed-length records, the value specified in the LRECL operand should be
evenly divisible into the value specified in the BLKSIZE operand.
For variable-length records, the value specified in LRECL must include include the
maximum data length (up to 32,752 bytes) plus 4 bytes for the RDW.
For undefined-length records, the LRECL operand should be omitted; the actual
length can be supplied dynamically. in a READ/WRITE macro instruction. When
an undefined-length record is read, the actual length of the record is returned by
the system in the DCBLRECL field of the data control block.
When BSAM is used to create a BDAM data set with variable-length spanned
records, the LRECL value should be the maximum data length (up to 32,752) plus
four bytes for the record descriptor word (RDW), or if the logical record length is

78 OS/VS Data Management Macro Instructions

DCB-BSAM
greater than 32,756 bytes, LRECL=X is specified.
Source: The LRECL operand can be supplied in the DCB macro instruction, in the
DCB· subparameter of a DD statement, by the problem program before completion of
the data control block exit routine, or by the data set label of an existing data set.
MACRF= I(R [C))
[P]

{(W [C))

}

[P]

[L]

{(R [C],W

[C)) }

The MACRF operand specifies the type of macro instructions (READ, WRITE,
CNTRL, and NOTE/POINT) that are used with the data set being created or
processed. The BSAM MACRF operand also provides the special form
(MACRF=WL) for creating a BDAM data set. The MACRF operand can be coded
in any of the forms shown above. The following characters can be coded:
C

Specifies that the CNTRL macro instruction is used with the data set. If
C is specified to be used with a card reader, a CNTRL macro instruction
must follow every input request.

Specifies that BSAM is used to create a BDAM data set. This character
can be specified only in the combination MACRF=WL.

Specifies that POINT macro instructions are used with the data set being
created or processed. Specifying P in the MACRF operand also
automatically provides the capability of using NOTE macro instructions
with the data set.

Specifies that READ macro instructions are used.

Specifies that WRITE macro instructions are used.

Note: Each READ and WRITE macro instruction issued in the problem program must
be checked for completion by a CHECK macro instruction.
Source: The MACRF operand must be specified in the DCB macro instruction.
NCP= absexp (maximum value is 99)
The NCP operand specifies the maximum number of READ/WRITE macro
instructions that will be issued before the first CHECK macro instruction is issued
to test for completion of the I/O operation. The maximum number may be less
than 99 depending on the limit established when the operating system is generated.
If chained scheduling is specified (OPTCD=C), NCP must be specified as more
than one. If the NCP operand is omitted, one is assumed.
Source: The NCP operand can be supplied in the DCB macro instruction, in the DCB
subparameter of a DD statement, or by the problem program before an OPEN macro
instruction is issued to open the data set.

Macro Instruction Descriptions 79

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

OPTCD= {B}

{T}
{V[C]}

{C[T)[B]}
{H[Z][B]}
{W(C)[T)[B]}
{Z[ C)[T][B]}
{Q[C][B][ {T}]}

{Z}
The OPTCD operand specifies the optional services that are used with the BSAM
data set. Two of the optional services, OPTCD=B and OPTCD=H, cannot be
specified in the DCB macro instruction. They are requested in the DCB
subparameter of a DD statement. Since all optional services requests must be
supplied by the same source, the OPTCD operand must be omitted from the DCB
macro instruction if either of these options is requested in a DD statement. The
following describes the charact~rs that can be specified; these characters can be
specified in any order (in one of the combinations shown above), and no commas
are required between characters.
C

Requests that chained scheduling be used. OPTCD=C cannot be
specified if BFfEK=R is specified for the same data control block. Also,
chained scheduling cannot be specified for associated data sets or printing
on a 3525. OS/VS supports chained scheduling in nonpageable storage
only. If chained scheduling is requested in pageable storage, the request
is ignored and normal scheduling is substituted.

Requests that ASCII tape records in an input data set be converted to
EBCDIC code after the input record has been read. Translation is done
at CHECK time for input. It also requests that an output record in
EBCDIC code be converted to ASCII code before the record is written.

Requests the user totaling facility. If this facility is requested, the EXLST
operand should specify the address of an exit list to be used.

Specified only for a printer with the universal character set (UCS)
feature. This option unblocks data checks (permits them to be
recognized as errors) and allows analysis by the appropriate error analysis
routine (SYNAD routine). If the V option is omitted, data checks are
not recognized as errors.

Specifies that the system performs a validity check on each record written
on a direct-access device.

For magnetic tape, input only, the Z option requests the system to
shorten its normal error recovery procedure to consider a data check as a
permanent I/O error after five unsuccessful attempts to read a record.
This option is available only if it is selected when the operating system is
generated. OPTCD=Z is used when a tape is known to contain errors
and there is no need to process every record. The error analysis routine
(SYNAD) should keep a count of permanent errors and terminate
processing if the number becomes excessive.
For direct-access devices only, the Z option requests the system to use
the search direct option to accelerate the input operations for a data set.

80 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

DCB-BSAM
OPTCD=Z cannot be specified when RECFM=UT, FS, FBT, VS, or
VBS.

Note: The following describes the optional services that can be requested in the
DCB subparameter of a DD statement. If either of these options is requested, the
complete OPTCD operand must be ~upplied in the DD statement.
B

If OPTCD=B is specified in the DCB subparameter of a DD statement, it

forces the end-of-volume (EOV) routine to disregard the end-of-file
recognition for magnetic tape. When this occurs, the EOV routine uses
the number of volume serial numbers to determine end of file.
H

If OPTCD=H is specified in the DeB subparameter of a DD statement,
it specifies that the DOS/OS interchange feature is being used with the
data set.

Source: The OPTCD operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before an OPEN
macro instruction is issued to open the data set. However, all optional services must be
requested from the same source.
RECFM= IV [T] [An
[M)

IV [B]
IS]

[An
[M]

[T)

[BS]
(BT)
ID [B)
IF (B]

[An
(An

(S]
[T)

(M]

(BS)
(BT]
The RECFM operand specifies the record format and characteristics of the data set
being created or processed. All the record formats shown above can be specified,
but in those record formats that specify blocked records, the problem program must
perform the blocking and deblocking of logical records; BSAM recognizes only data
blocks. The following describes the characters that can be specified:
A

Specifies that the records in the data set contain American National
Standards Institute (ANSI) control characters. Refer to Appendix E for a
description of control characters.

Specifies that the data set contains blocked records.

Specifies that the data set contains variable-length ASCII tape records.
See OPTCD=Q and the BVFOFF operand for a description of how to
specify ASCII data sets.

Specifies that the data set contains fixed-length records.

Specifies that the records in the data set contain machine code control
characters. Refer to Appendix E for a description of control characters.
RECFM=M cannot be used with ASCII data sets.

Macro Instruction Descriptions 81

For fixed-length records, S specifies that the records are written as
standard blocks; the data set does not contain any truncated blocks or
unfilled tracks, with the exception of the last block or track in the data
set.
For variable-length records, S specifies that a record can span more than
one block. Spanned records can be read (reading a BDAM data set) or
written (creating a BDAM data set) using BSAM.

Specifies that the track-overflow feature is used with the data set. The
track-overflow feature allows a record to be written partially on one
track of a direct-access device and the remainder of the record written on
the following track (if required). Chained scheduling cannot be used if
the track-overflow feature is used.

Specifies that the data set contains undefined-length records.

Specifies that the data set contains variable-length records.
Note: RECFM=V cannot be specified for a card reader data set or an
ASCII tape data set.

Note: The record format RECFM= VBS does not provide the spanned record function;
if this format is used, the problem program must block and segment the records.
Source: The RECFM operand can be supplied in the DeB macro instruction, in the
DCB subparameter of a DD statement, by the problem program before completion of
the data control block exit routine, or by the data set label of an existing data set.
SYNAD= relexp
The SYNAD operand specifies the address of the error analysis (SYNAD) routine
to be given control when an uncorrectable input/output error occurs. The contents
of the registers when the error analysis routine is given control are described in
Appendix A of this publication.
The error analysis routine must not use the save area pointed to by register 13,
because this area is used by the system. The system does not restore registers when
it regains control from the error analysis routine. The error analysis routine can
issue a RETURN macro instruction which uses the address in register 14 to return
control to the system. If control is returned to the system, the system returns
control to the problem program and proceeds as though no error had been
encountered.
If the SYNAD operand is omitted, the task is abnormally terminated when an
uncorrectable input/output error occurs.

82 OS/VS Data Management Macro Instructions

DCB-QISAM

DCB -

Construct a Data Control Block (QISAM)
The data control block for a queued indexed sequential access method (QISAM) data
set is constructed during assembly of the problem program. The DCB macro
instruction must not be coded within the first 16 bytes of a control section (CSECT).
The DSORG and MACRF operands must be coded in the DeB macro instruction, but
the other DCB operands can be supplied from other sources. Each QISAM DeB
operand description contains a heading, "Source." The information under this heading
describes the sources which can supply the operand to the data control block.
Before a DCB macro instruction for a QISAM data set is coded, the following
characteristics of QISAM should be considered:
•

The characteristics of a QISAM data set are established when the data set is
created; these characteristics cannot be changed without reorganizing the data set.
The following DeB operands establish the characteristics of the data set and can be
coded only when creating the data set: BLKSIZE, CYLOFL, KEYLEN, LRECL,
NTM, OPTCD, RECFM, and RKP.

•

The data set can contain the following record formats: Unblocked fixed-length
records (F), blocked fixed-length records (FB), unblocked variable-length records
(V), or blocked variable-length records (VB).

•

QISAM can create an indexed sequential data set (QISAM, load mode), add
additional data records at the end of the existing data set (QISAM, resume load
mode), update a record in place, or retrieve records sequentially (QISAM, scan
mode).

•

The track-overflow feature cannot be used to create an ISAM data set.

•

When an indexed sequential data set is being created, space for the prime area of
the data set, the overflow area of the data set, and the cylinder/master index(es)
for the data set can be allocated on the same or separate volumes. For information
about space allocation, refer to OS/VS JCL Reference manual.

•

The system automatically creates one track index for each cylinder in the data set
and one cylinder index for the entire data set. The DCB NTM and OPTCD
operands can be specified to indicate that the data set requires a master index(es);
the system creates and maintains up to three levels of master indexes. OS/VS
Data Management Services Guide contains additional information about indexes
for indexed sequential data sets.

•

A record deletion option can be specified (OPTCD=L) when the ISAM data set is
created. This option allows a record to be flagged for deletion by placing a
hexadecimal value of 'FF' in the first data byte of the record (first byte of a
fixed-length record or fifth byte of a variable-length record). Records marked for
deletion are ignored during sequential retrieval by QISAM.

•

Reorganization statistics can be obtained by specifying OPTCD=R when the ISAM
data set is created. These statistics can be used by the problem program to
determine the status of the overflow areas allocated to the data set. Reorganization
of ISAM data sets is described in OS/VS Data Management Services Guide.

Macro Instruction Descriptions 83

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

•

When an ISAM data set is created, the records must be written with the keys in
ascending order.

These characteristics of queued indexed sequential access method data sets are
described in more detail in OS/VS Data Management Services Guide.
The following describes the DCB operands that can be specified when a QISAM data
set is being created or processed.
BFALN= tF}
tD}

The BFALN operand specifies the alignment of each buffer in the buffer pool when
the buffer pool is constructed automatically or by a GETPOOL macro instruction.
If the BFALN operand is omitted, the system provides doubleword alignment for
each buffer. The following describes the characters that can be specified:
F

Specifies that each buffer is on a fullword boundary that is not also a
double word boundary.

Specifies that each buffer is on a double word boundary.

If the BUILD macro instruction is used to construct the buffer pool, the problem

program must provide a storage area for the buffers and control buffer alignment.
Source: The BFALN operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine.
BLKSIZE= absexp (maximum value is device-dependent)

The BLKSIZE operand specifies the length, in bytes, for each data block when
fixed-length records are used, or it specifies the maximum length in bytes, for each
data block when variable-length records are used. The BLKSIZE operand must be
specified when an ISAM data set is created. When an existing ISAM data set is
processed, the BLKSIZE operand must be omitted (it is supplied by the data set
label).
Track capacity of the direct-access device being used must be considered when the
BLKSIZE for an ISAM data set is specified. For fixed-length records, the sum of
the key length, data length, and device overhead plus 10 bytes (for ISAM use) must
not exceed the capacity of a single track on the direct-access device being used.
For variable-length records the sum of the key length, block-descriptor word
length, record-descriptor word length, data length, and device overhead plus 10
bytes (for ISAM use) must not exceed the capacity of a single track on the
direct-access device being used. Device capacity and device overhead are described
in Appendix C of this publication. For additional information about device capacity
and space allocation, refer to OS/VS Data Management Services Guide.
If fixed-length records are used, the value specified in the BLKSIZE operand must
be an integral multiple of the value specified in the LRECL operand.

Source: When an ISAM data set is created, the BLKSIZE operand can be supplied in
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the
problem program before completion of the data control block exit routine. When an
existing ISAM data set is processed, the BLKSIZE operand must be omitted from the
other sources, allowing the data set label to supply the value.

84 OS/VS Data Management Macro Instructions

DCB-QISAM
BUFCB= relexp
The BUFCB operand specifies the address of the buffer pool control block
constructed by a BUILD macro instruction.
If the system constructs the buffer pool automatically or if the buffer pool is

constructed by a GETPOOL macro instruction, the system places the address of the
buffer pool control block into the data control block, and the BUFCR operand
should be omitted.
Source: The BUFCB operand can be supplied in the DeB macro instruction or by the
problem program before completion of the data control block exit routine.
BUFL= absexp (maximum value is 32,760)
The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool
when the buffer pool is constructed by a BUILD or GETPOOL macro instruction.
When the data set is opened, the system computes the minimum buffer length
required and verifies that the length in the buffer pool control block is equal to or
greater than the minimum length required. The system then inserts the computed
length into the data control block.
The BUFL operand is not required for QISAM if the system acquires buffers
automatically; the system computes the minimum buffer length required and inserts
the value into the data control block.
If the buffer pool is constructed with a BUILD or GETPOOL macro instruction,

additional space is required in each buffer for system use. For a description of the
buffer length required for various ISAM operations, refer to OS/VS Data
Management Services Guide.
Source: The BUFL operand can be supplied in the DeB macro instruction, in the DeB
subparameter of a DD statement, or by the problem program before completion of the
data control block exit routine.
BUFNO= absexp (maximum value is 255)
The BUFNO operand specifies the number of buffers to be constructed by a
BUILD macro instruction, or it specifies the number of buffers to be acquired
automatically by the system. If the BUFNO operand is omitted, the system
automatically acquires two buffers.
If the GETPOOL macro instruction is used to construct the buffer pool, the

BUFNO operand is not required.
Source: The BUFNO operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine.
CYLOFL= absexp (maximum value is 99)
The CYLOFL operand specifies the number of tracks on each cylinder that is
reserved as an overflow area. The overflow area is used to contain records that are
forced off prime area tracks when additional records are added to the prime area
track in ascending key sequence. ISAM maintains pointers to records in the
overflow area so that the entire data set is logically in ascending key sequence.
Tracks in the cylinder overflow area are used by the system only if OPTCD=Y is
Macro Instruction Descriptions 85

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

specified. For a more complete description of cylinder overflow area, refer to the
space allocation section of OS / VS Data Management Services Guide.
Source: When an ISAM data set is created, the CYLOFL operand can be supplied in
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the
problem program before completion of the data control block exit routine. When an
existing ISAM data set is processed, the CYLOFL operand must be omitted, allowing
the data set label to supply the operand.
DDNAME= symbol
The DDNAME operand specifies the name used to identify the job control language
data definition (DD) statement that defines the data set being created or processed.
Source: The DDNAME operand can be supplied in the DeB macro instruction or by
the problem program before an OPEN macro instruction is issued to open the data set.
DSORG= {IS}
{ISU}
The DSORG operand specifies the organization of the data set and if the data set
contains any location-dependent information that would make it unmovable. The
following characters can be specified.
IS
ISU -

Specifies an indexed sequential data set organization.
Specifies an indexed sequential data set that contains
location-dependent information. ISU can be specified only when an
ISAM data set is created.

Source: The DSORG operand must be specified in the DCB macro instruction. When
an ISAM data set is created, DSORG=IS or ISU must also be specified in the DeB
subparameter of the corresponding DD statement.
EODAD= relexp
The EO DAD operand specifies the address of the routine to be given control
when the end of an input data set is reached. For ISAM, this operand would
apply only to scan mode when a data set is open for an input operation. Control
is given to this routine when a GET macro instruction is issued and there are no
more input records to retrieve. When your EODAD routine receives control,
register contents (except for register 15) will be the same as they were when the
last GET macro instruction was issued. Register 15 will contain a hexadecimal 4
if you have processed an end-of-volume tape label; otherwise, register 15 will
contain a O.
Source: The EODAD operand can be supplied in the DeB macro instruction or by the
problem program before the end of the data set is reached.
EXLST= relexp
The EXLST operand specifies the address of the problem program exit list. The
EXLST operand is required only if the problem program uses the data control
block exit routine for additional processing or if the DCB ABEND exit is used for
ABEND condition analysis.
Refer to Appendix D of this publication for the format and requirements for exit
list processing. For additional information about exit list processing, refer to
OS/VS Data Management Services Guide.
Source: The EXLST operand can be supplied in the DCB macro instruction or by the
problem program before the associated exit is required.
86 OS/VS Data Management Macro Instructions

DCB -QISAM
KEYLEN= absexp (maximum value is 255)
The KEYLEN operand specifies the length, in bytes, of the key associated with
each record in an indexed sequential data set. When blocked records are used,
the key of the last record in the block (highest key) is used to identify the block.
However, each logical record within the block has its own identifying key which
ISAM uses to access a given logical record.
Source: When an ISAM data set is created the KEYLEN operand can be supplied in
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the
problem program before completion of the data control block exit routine. When an
existing ISAM data set is processed, the KEYLEN operand must be omitted, allowing
the data set label to supply the key length value.
LRECL= absexp (maximum value is device-dependent)
The LRECL operand specifies the length, in bytes, for fixed-length records, or it
specifies the maximum length, in bytes, for variable-length records. The value
specified in the LRECL operand cannot exceed the value specified in the
BLKSIZE operand. When unblocked records are used and the relative key
position (as specified in the RKP operand) is zero, the value specified in the
LRECL operand should include only the data length (the key is not written as
part of the record when RKP=O).
The track capacity of the direct-access device being used must be considered if
maximum length logical records are being used. For fixed-length records, the
sum of the key length, data length, and device overhead plus 10 bytes (for ISAM
use) must not exceed the capacity of a single track on the direct-access device
being used. For variable-length records, the sum of the key length, data length,
device overhead, block-descriptor-word length, and record-descriptor-word
length plus 10 bytes (for ISAM use) must not exceed the capacity of a single
track on the direct-access device being used. Device capacity and device
overhead are described in Appendix C of this publication. For additional
information about device capacity and space allocation, refer to OS / VS Data
Management Services Guide.
Source: When an ISAM data set is created, the LRECL operand can be supplied in the
DCB macro instruction, in the DCB subparameter of a DD statement, or by the
problem program before completion of the data control block exit routine. When an
existing ISAM data set is processed, the LRECL operand must be omitted, allowing the
data set label to supply the value.
MACRF= {(PM)
{(PL)
{(GM[,S
{(GL[,S

[K]D
[I]

}
}
}

[K]][,PUD
[1]

The MACRF operand specifies the type of macro instructions, the transmittal mode,
and type of search to be used with the data set being processed. The operand can
be coded in any of the combinations shown above; the following describes the
characters that can be coded.

Macro Instruction Descriptions 87

The following characters can be specified only when the data set is being created
(load mode) or additional records are being added to the end of the data set
(resume load).
PL -

Specifies that PUT macro instructions "are used in the locate transmittal
mode; the system provides the problem program with the address of a
buffer containing the data to be written into the data set.

PM -

Specifies that PUT macro instructions are used in the move transmittal
mode; the system moves the data to be written from the problem
program work area to the buffer being used.

The following characters can be specified only when the data set is being processed
(scan mode) or when records in an ISAM data set are being updated in place.
GL -

Specifies that GET macro instructions are used in the locate transmittal
mode; the system provides the problem program with the address of a
buffer containing the logical record read.

GM -

Specifies that GET macro instructions are used in the move mode; .the
system moves the logical record from the buffer to the problem program
work area.

Specifies that actual device addresses (MBBCCHHR) are used to search
for a record (or the first record) to be read.

Specifies that a key or key class is used to search for a record (or the first
record) to be read.

Specifies that PUTX macro instructions are used to return updated
records to the data set.

Specifies that SETL macro instructions are used to set the beginning
location for processing the data set.

Source: The MACRF operand must be coded in the DCB macro instruction.
NTM= absexp (maximum value is 99)
The NTM operand specifies the number of tracks to be created in a cylinder index
before a higher-level index is created. If the cylinder index exceeds this number, a
master index is created by the system; if a master index exceeds this number, the
next level of master index is created. The system creates up to three levels of
master indexes. The NTM operand is ignored unless the master index option
(OPTCD=M) is selected.
Source: When an ISAM data set is being created, the NTM operand can be supplied in
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the
problem program before completion of the data control block exit routine. When an
ISAM data set is being processed, master index information is supplied to the data
control block from the data set label, and the NTM operand must be omitted.

88 OS/VS Data Management Macro Instructions

DCB -

QISAM

OPTCD= (I)[L)[M)[R)[U)[W)(Y)
The OPTCD operand specifies the optional services performed by the system when
an ISAM data set is being created. The following describes the characters that can
be specified; these characters can be specified in any order, and no commas are
required between characters.
I

Specifies that the system uses the independent overflow areas to contain
overflow records. Allocated independent overflow areas are not used
unless OPTCD=I is specified.

Specifies that the data set will contain records flagged for deletion. A
record is flagged for deletion by placing a hexadecimal value of 'FF' in
the first data byte. Records flagged for deletion remain in the data set
until the space is required for another record to be added to the track.
Records flagged for deletion are ignored during sequential retrieval of the
ISAM data set (QISAM, scan mode). This option cannot be specified for
blocked fixed-length records if the relative key position is zero (RKP=O),
or it cannot be specified for variable-length records if the relative key
position is four (RKP=4).
When an IS AM data set is being processed with BISAM, a record with a
duplicate key can be added to the data set (WRITE KN macro
instruction, only when OPTCD=L has been specified and the original
record (the one whose key is being duplicated) has been flagged for
deletion.

Specifies that the system creates and maintains a master index(es)
according to the number of tracks specified in the NTM operand.

Specifies that the system places reorganization statistics in· the
DCBRORGl, DCBRORG2, and DCBRORG3 fields of the data control
block. The problem program can analyze these statistics to determine
when to reorganize the data set. If· the OPTCD operand is omitted
completely, the reorganization statistics are automatically provided.
However, if the OPTCD operand is supplied, OPTCD=R must be
specified to obtain the reorganization statistics.

Specifies that the system accumulates track index entries in storage and
writes them as a group for each .track of the track index. OPTCD=U can
be specified only for fixed-length records. The entries are written in
fixed-length unblocked format.

Specifies that the system performs a validity check on each record
written.

Specifies that the system uses the cylinder overflow area(s) to contain
overflow records. If OPTCD=Y is specified, the CYLOFL operand
specifies the number of tracks to be used for the cylinder overflow area.
The reserved cylinder overflow area is not used unless OPTCD= Y is
specified.

Source: When an ISAM data set is created, the OPTCD operand can be supplied in
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the
problem program before an OPEN macro instruction is 'issued to open the data set.
However, all optional services must be requested from the same source. When an
Macro Instruction Descriptions 89

existing ISAM data set is processed, the optional service information is supplied to the
data control block from the dataset label, and the OPTCD operand must be omitted.
{V[B]}
RECFM= {F[B]}
The RECFM operand specifies the format and characteristics of the records in the
data set. If the RECFM operand is omitted, variable-length records (unblocked)
are assumed. The following describes the characters that can be specified.
B

Specifies that the data set contains blocked records.

Specifies that the data set contains fixed-length records.

Specifies that the data set contains variable-length records.

Source: When an ISAM data set is created, the RECFM operand can be supplied in
the DeB macro instruction, in the DeB subparameter of a DD statement, or by the
problem program before an OPEN macro instruction is issued to open the data set.
When an existing ISAM data set is processed, the record format information is supplied
by the data set label, and the RECFM operand must be omitted.
RKP= absexp
The RKP operand specifies the relative position of the first byte of the key within
each logical record. For example, if RKP=9 is specified, the key starts in the tenth
byte of the record. The delete option (OPTCD=L) cannot be specified if the
relative key position is the first byte of a blocked fixed-length record or the fifth
byte of a variable-length record. If the RKP operand is omitted, RKP=O is
assumed.
If unblocked fixed-length records are used, the key is not written as a part of the
data record, and the delete option can be specified. If blocked fixed-length records

are used, the key is written as part of each data record; either RKP must be greater
than zero or the delete option must not be used.
If variable-length records (blocked or unblocked) are used, RKP must be four or

greater if the delete option is not specified; if the delete option is specified, RKP
must be specified as five or greater. The four additional bytes allow for the block
descriptor word in variable-length records.
Source: When an ISAM data set is created, the RKP operand can be supplied in the
DeB macro instruction, in the DeB sub parameter of a DD statement, or by the
problem program before completion of the data control block exit routine. When an
existing ISAM data set is processed, the RKP information is supplied by the data set
label and the RKP operand must be omitted.
SYNAD= relexp
The SYNAD operand specifies the address of the error analysis routine given
control when an uncorrectable input/output error occurs. The contents of the
registers when the error analysis routine is given control are described in Appendix
A of this publication.
The error analysis routine must not use the save area pointed to by register 13,
because this area is used by the system. The system does not restore registers when
it regains control from the error analysis routine. The error analysis routine can
issue a RETURN macro instruction which uses the address in register 14 to return
control to the system. When control is returned in this manner, the system returns

90 OS/VS Data Management Macro Instructions

DCB -QISAM

control to the problem program and proceeds as though no error had been
encountered; if the error analysis routine continues processing, the results may be
unpredictable.
For ISAM data sets, if the error analysis routine receives control from the Close
routine, bit 3 of the IOBFLAG 1 field in the input/output block is set to one. In
this case, the error analysis routine must not issue a CLOSE macro instruction. To
complete close processing, the error analysis routine must return control to the
Close routine with a branch to the address in register 14.
Source: The SYNAD operand can be supplied in the DCB macro instruction or by the
problem program. The problem program can also change the error1analysis routine
address at any time.

Macro Instruction Descriptions 91

DCB-QSAM

DCB -

Construct a Data Control Block (QSAM)
The data control block for the queued sequential access method (QSAM) is constructed
during assembly of the problem program. The DCB macro instruction must not be
coded within the first 16 bytes of a control section (CSECT). The DSORG and
MACRF operands must be coded in the DCB macro instruction, but the other DCB
operands can be supplied, to the data control block, from other sources. Each DCB
operand description contains a heading, "Source." The information under this heading
describes the sources from which the operand can be supplied.
Before a DCB macro instruction for creating or processing a QSAM data set is coded,
the following characteristics of QSAM data sets should be considered.
•

All record formats can be processed.

•

Automatic blocking and deblocking of records is provided.

•

Automatic buffer control is provided; this function fills input buffers when they are
empty and writes output buffers when they are full.
A logical record interface is provided; a GET macro instruction retrieves the next
sequential logical record from the input buffer, and a PUT macro instruction places
the next sequential logical record in the output buffer.

•

I/O operations are synchronized automatically.

•

Four transmittal modes (move, locate, data, and substitute) are provided. These
transmittal modes provide flexibility in buffer management and data movement
between buffers.

•

Keys for direct-access device records cannot be read or written using QSAM.
Specifying the DEVD operand in the DCB macro instruction can cause the program
to be device-dependent.

These characteristics of queued sequential access method data sets are described in
more detail in OS/VS Data Management Services Guide.
The following describes the operands that can be specified in the DCB macro
instruction for a QSAM data set.

{F}
BFALN= {D}
The BFALN operand specifies the boundary alignment of each buffer in the buffer
pool when the buffer pool is constructed automatically or by a GETPOOL macro
instruction. If the BFALN operand is omitted, the system provides double word
alignment for each buffer.
If the data set being created or processed contains ASCII tape records with a block

Macro Instruction Descriptions 93

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

The following describes the characters that can be specified.
F

Specifies that each buffer is on a fullword boundary that is not also a
double word boundary.

Specifies that each buffer is on a double word boundary.

When exchange buffering (BFTEK=E) is specified and the records are in blocked
fixed-length format, each buffer segment is aligned as specified in the BFALN
operand.
If the BUILD macro instruction is used to construct the buffer pool, the problem

program must control buffer alignment.
Source: The BFALN operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine. If both the BFALN and BFTEK operands are
specified, they must be supplied from the same source.
lSI
BFTEK= lEI
IAI

The BFTEK operand specifies the buffering technique that is used when the QSAM
data set is created or processed. If the BFTEK operand is omitted, simple buffering
is assumed. The following describes the characters that can be specified.
S

Specifies that simple buffering is used.

Specifies that exchange buffering is used. Exchange buffering can be
used only with record formats (RECFM operand) F, FB, FBS, or FS; the
track-overflow feature cannot be used with exchange buffering. If
exchange buffering is used with ASCII tape records, the BUFOFF
operand must be zero (no block prefix).

Specifies that a logical record interface is used for variable-length
spanned records. When BFTEK=A is specified, the Open routine
acquires a record area equal to the length specified in the LRECL field
plus 32 additional bytes for control information. When a logical record
interface is requested, the system uses the simple buffering technique.

To use the simple or exchange buffering technique efficiently, the user should be
familiar with the four transmittal modes for QSAM and the buffering techniques as
described in OS/VS Data Management Services Guide.
Source: The BFTEK operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before completion
of the data control block exit routine. If both the BFTEK and BFALN operands are
specified, they must be supplied from the same source.
BLKSIZE= absexp (maximum value is 32,760)

The BLKSIZE operand specifies the length, in bytes, of a data block for
fixed-length records, or it specifies the maximum length, in bytes, of a data block
for variable-length or undefined-length records.

94 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

DCB-QSAM
The actual value that can be specified in the BLKSIZE operand depends on the
device type and record format being used. Device capacity is shown in Appendix C
of this publication. For additional information about device capacity, refer to
OSjVS Data Management Services Guide. For direct-access devices when the
track-overflow feature is used or variable-length spanned records are being
processed, the BLKSIZE operand can be up to the maximum value. For other
record formats used with direct-access devices, the value specified in the BLKSIZE
operand cannot exceed the capacity of a single track.
Since QSAM provides a logical record interface, the device capacities shown in
Appendix C also apply to a maximum length logical record. One exception to the
device capacity for a logical record is the size of variable-length spanned records.
Their length can exceed the value specified in the BLKSIZE operand (see the
description of the LRECL operand).
If fixed-length records are used for a SYSOUT data set, the value specified in the

BLKSIZE operand must be an integral multiple of the value specified in the LRECL
operand; otherwise, the system will adjust the blocksize downward to the nearest
multiple. If the records are unblocked fixed-length records, the value specified in
the BLKSIZE operand must equal the value specified in the LRECL operand if the
LRECL operand is specified.
If variable-length records are used, the value specified in the BLKSIZE operand

must include the data length (up to 32,756 bytes) plus four bytes required for the
block descriptor word (BDW). For format-D variable-length records, the minimum
blocksize is 18 bytes and the maximum is 2048 bytes.
If ASCII tape records with a block prefix are processed, the value specified in the

BLKSIZE operand must also include the length of the block prefix.
If variable-length spanned records are used, the value specified in the BLKSIZE

operand can be the best one for the device being used or the processing being done.
When unit record devices (card or printer) are used, the system assumes records are
unblocked; the value specified for the BLKSIZE operand is equivalent to one print
line or one card. A logical record that spans several blocks is written one segment
at a time.
If undefined-length records are used, the problem program can insert the actual
I

record length into the DCBLRECL field. See the description of the LRECL
operand.

instruction, the system places the address of the buffer pool control block into the
data control block, and the BUFCB operand should be omitted.

Macro Instruction Descriptions 95

Source: The BUFCB operand can be supplied in the DCB macro instruction or by the
problem program before completion of the data control block exit routine.
BUFL= absexp (maximum value is 32,760)
The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool
when the buffer pool is acquired automatically. The system acquires buffers with a
length equal to the value specified in the BLKSIZE operand if the BUFL operand is
omitted; if the problem program requires larger buffers, the BUFL operand is
required. If the data set is for card image mode, the BUFL operand is specified as
160 bytes. The description of the DEVD operand contains a description of card
image mode.
If the data set contains ASCII tape records with a block prefix, the value specified

in the BUFL operand must also include the length of the block prefix.
If the buffer pool is constructed by a BUILD, BUILDRCD, or GETPOOL macro

instruction, the BUFL operand is not required.
Source: The BUFL operand can be supplied in the DCB macro instruction, in the DCB
subparameter of a DD statement, or by the problem program before completion of the
data control block exit routine.
BUFNO= absexp (maximum value is 255)
The BUFNO operand specifies the number of buffers in the buffer pool constructed
by a BUILD or BUILDRCD macro instruction, or it specifies the number of buffers
to be acquired automatically. If the BUFNO operand is omitted and the buffers are
acquired automatically, the system acquires three buffers if the device is a 2540
card read punch or two buffers for any other device type.
If the buffer pool is constructed by a GETPOOL macro instruction, the BUFNO

operand is not required.
Source: The BUFNO operand can be supplied in the DCB macro instruction, in the
DCB sub parameter of a DD statement, or by the problem program before completion
of the data control block exit routine.
{ absexp}
BUFOFF= {L}

The BUFOFF operand specifies the length, in bytes, of the block prefix used with
ASCII tape data sets. When QSAM is used to read ASCII tape records, only the
data portion (or its address) is passed to the problem program; the block prefix is
not available to the problem program. Block prefixes (except BUFOFF=L) cannot
be included in QSAM output records. The following can be specified in the
BUFOFF operand:
absexp -

Specifies the length, in bytes, of the block prefix. This value can be
from 0 to 99 for an input data set. The value must be 0 for writing
an output data set with fixed-length or undefined-length records.

Specifies that the block prefix is 4 bytes long and contains the block
length. BUFOFF=L is used when format-D records (ASCII) are
processed. QSAM uses the four bytes as a block-descriptor word
(BDW).

96 OS/VS Data Management Macro Instructions

DeB-QSAM
Source: The BUFOFF operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program before an OPEN
macro instruction is issued to open the data set.
DDNAME= symbol

The DDNAME operand specifies the name used to identify the job control
language data definition (DD) statement that defines the data set being created or
processed.
Source: The DDNAME operand can be supplied in the DCB macro instruction or by

the problem program before an OPEN macro instruction is issued to open the data set.
DEVD=

{DA
{TA (,DEN=

to)]
{l}
{2}
{3}

(,TRTeH=

}
{e}] }

{E}
{T}
{ET}
}

{PT (,eODE= {A}]
{B}
{e}
{F}
{I}
{N}
{T}

{PR (,PRTSP=

to})
{I}
{2}
{3}

{PC (,MODE= (e)
(E)

(R)(,STACK=

{RD (,MODE= (e)
[E)

(O)(,STAeK=
[R)

{I})(,FUNe= {I
{2}
{P
{PWlXT)
{R
{RP(D)
{RW(T)
{RWP(XT)(D)
{WIT)

{I})(,FUNe= {I
{2}
{P
{PW(XT)
{R
{RP(D)
{RW(T)
{RWP[XT)[D)
{WIT)

}
}
}
}
}
}
}

The DEVD operand specifies the device type on which the data set can or does

reside. The device types above are shown with the optional operand(s) that can be
coded when a particular device is used. The devices are listed in order of
device-independence. For example, if DEVD=DA is coded in a DCB macro
instruction (or the DEVD operand is omitted, which causes a default to DA), the
Macro Instruction Descriptions 97

Revised December 15, 1972
By TNL GN26-0748

data control block constructed during assembly could later be used for any of the
other devices, but if DEVD=RD is coded, the data control block can be used only
with a card reader or card reader punch. Unless you are certain that device
interchangeability is not required, you should either code DEVD=DA or omit the
operand and allow it to default to DA.
If system input is directed to· an intermediate storage device, the DEVD operand is

omitted, and the job control language for the problem program must designate the
system input to be used. Similarly, if system output is directed to an intermediate
storage device, the DEVD operand is omitted, and the job control language for the
problem program must designate the system output to be used.
The following describes the device type and the optional operands that can be
specified for each device type.
DA -

Specifies that the data control block can be used for a direct-access device
(or any of the other device types described following DA).

TA -

Specifies that the data control block can be used for a magnetic tape data
set (or any of the other device types described following TA). If TA is
coded, the following optional operands can be coded:
{OJ

HJ
DEN= {2J
{3J

The DEN operand specifies the recording density in the number of
bits-per-inch per track as shown in the following chart.
DEN

o
1
2
3

7-Track Tape 9-Track Tape 9-Track Tape
9-Track Tape
(Phase Encoded) Dual Density
200
556
800

800
1600

800 (NRZI)
1600 (PE)

NRZI is for non-return-to-zero-inverse mode
PE is for phase encoded mode
Specifying DEN =0 for a 7 track, 3420 tape will result in a 556 bits-per-inch
recording density, but corresponding messages and tape labels will indicate a
200 bits-per-inch recording density.
If the DEN operand is not supplied by any source, the highest applicable

density is assumed.
TRTCH= {CJ
{EJ
{ETJ

tTJ
The TRTCH operand specifies the recording technique for 7-track tape. One
of the above character combinations can be coded. If the TRTCH operand is

98 OS/VS Data Management Macro Instructions

DCB-QSAM
omitted, odd parity with no translation or conversion is assumed. The following
describes the characters that can be specified:

PT -

Specifies that the data-conversion feature is used with odd parity
and no translation.

Specifies even parity with no translation or conversion.

Specifies even parity with BCDIC to EBCDIC translation required,
but no data-conversion feature.

Specifies that BCDIC to EBCDIC translation is required with odd
parity and no data-conversion feature.

Specifies that the data control block is used for a paper tape device (or any of
the other devices following PT). If PT is coded, the following optional
operand can be coded.
CODE=

{AI
{DI
{CI
{FI

tIl
{NI

ITI
The CODE operand specifies the code in which the data was punched. The
system converts these codes to EBCDIC code. If the CODE operand is not
supplied by any source, CODE=I is assumed. The following describes the
characters that can be specified.

PR -

Specifies 8-track tape in ASCII code.

Specifies Burroughs 7-track tape.

Specifies National Cash Register 8-track tape.

Specifies Friden 8-track tape.

Specifies IBM BCD perforated tape and transmission code with
8-tracks.

Specifies that no conversion required.

Specifies Teletype I S-track tape.

Specifies that the data control block is used for an on-line printer (or any of
the other device types following PR). If PR is coded, the following optional
operand can be coded.
PRTSP= IOI

ttl

121
131
The PRTSP operand specifies the line spacing on the printer. This operand is
not valid if the RECFM operand specifies either machine (RECFM=M) or
ANSI (RECFM=A) control characters. If the PRTSP operand is not specified
1.

Trademark of Teletype Corporation.

Macro Instruction Descriptions 99

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

from any source, one is assumed. The following describes the characters that can be
specified.

o
1
2
3
PC -

Specifies
Specifies
Specifies
Specifies

that spacing is suppressed (no space).
single-spacing.
double-spacing (one blank line between printed lines).
triple-spacing (two blank lines between printed lines).

Specifies that the data control block is used for a card punch (or any of the
other device types following PC). If PC is coded, the following optional
operands can be specified.
MODE= (CUR]
(E]

The MODE operand specifies the mode of operation for the card punch. The
following describes the characters that can be specified. If the MODE operand
is omitted, E is assumed.
C

Specifies that the cards are punched in card image mode. In card
image mode, the 12 rows in each card column are punched from
two consecutive bytes of virtual storage. Rows 12 through 3 are
punched from the low-order 6 bits of one byte, and rows 4-9 are
punched from the 6 low-order bits of the following byte.

Specifies that cards are punched in EBCDIC code.

Specifies that the program runs in read-column-eliminate mode
(3505 card reader or 3525 card punch, read feature).

Note: If the MODE operand is specified in the DCB subparameter of a DD
statement, either C or E must be specified if R is specified.
STACK= U}
{2}

The STACK operand specifies the stacker bin into which the card is placed
after punching is completed. If this operand is omitted, stacker number 1 is
used. The following describes the characters that can be specified:
1

Specifies stacker number 1.

Specifies stacker number 2.

FUNC=

{I
}
{P
}
{PW(XT]}
{R
}
{RP(D] }
{RW(T] }
{RWP(XT](D ]}
{W(T] }

I The FUNC operand defines the type of 3525 card punch data sets that are
used. If the FUNC operand is omitted from all sources, a data set opened for
input defaults to read only, and a data set opened for output defaults to punch
only. The following describes the characters that can be specified in the FUNC
operand.

100 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

DCB-QSAM
D

Specifies that the data protection option is to be used. The data
protection option prevents punching information into card columns
that already contain data. When the data protection option is used,
an 80-byte data protection image (DPI) must have been previously
stored in SYS1.1MAGELIB. Data protection applies only to the
output punch portion of a read and punch or read, punch, and print
operation.

Specifies that the data in the data set is to be punched into cards
and printed on the cards; the first 64 characters are printed on line
1 of the card and the remaining 16 characters are printed on line 3.

Specifies that the data set is for punching cards. See the description
of the character X for associated punch and print data sets.

Specifies that the data set is for reading cards.

Specifies that the two-line option is used. The two-line print
option allows two lines of data to be printed on the card (lines 1
and 3). If T is not specified, the multiline print option is used; this
allows printing on all 25 possible print lines. In either case, the data
printed may be the same as the data punched in the card, or it may
be entirely different data.

Specifies that the data set is for printing. See the description of the
character X for associated punch and print data sets.

Specifies that an associated data set is opened for output for both
punching and printing. Coding the character X is used to
distinguish the 3525 printer output data set from the 3525 punch
output data set.

Note: If data protection is specified, the data protection image (DPI) must be
specified in the FCB subparameter of the DD statement for the data set.
RD-

Specifies that the data control block is used with a card reader or card read
punch. If RD is specified, the data control block cannot be used with any
other device type. When RD is coded, the following optional operands can be
specified.
MODE= IC)(O]
IE)(R]
The MODE operand specifies the mode of operation for the card reader. The
following describes the characters that can be specified.
C

Specifies that the cards to be read are in card image mode. In card
image mode, the 12 rows of each card column are read into two
consecutive bytes of virtual storage. Rows 12 through 3 are read
into the low-order 6 bits of one byte, and rows 4 through 9 are
read into the low-order 6 bits of the following byte.

Specifies that the cards to be read contain data in EBCDIC code.

Specifies that the program runs in optical mark read mode (3505
card reader).
Macro Instruction Descriptions 101

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

Specifies that the program runs in read-column-eliminate mode
(3505 card reader and 3525 card punch, read feature).

Note: If the MODE operand for a 3505 or 3525 is specified in the DeB
subparameter of a DD statement, either C or E must be specified if R or 0 is
specified.
STACK= {II
{2I

The STACK operand specifies the stacker bin into which the card is placed
after reading is completed. If this operand is omitted, stacker number 1 is
used. The following describes the characters that can be specified.
1
Specifies stacker number 1.
2
Specifies stacker number 2.
FUNC=

{I
I
{P
I
{PW[XT]}
{R
I
{RP[D] I
{RW[T] I
{RWP[XT][D]}
{W[T] I

The FUNC operand defines the type of 3525 card punch data sets that are
used. If the FUNC operand is omitted from all sources, a data set opened for
input defaults to read only, and a data set opened for output defaults to punch
only. The following describes the characters that can be specified in the FUNC
operand.
D

Specifies that the data protection option is to be used. The data
protection option prevents punching information into card columns
that already contain data. When the data protection option is used,
an 80-byte data protection image (DPI) must have been previously
stored in SYS 1.1MAGELIB. Data protection applies only to the
output punch portion of a read and punch or read, punch, and print
operation.

Specifies that the data in the data set is to be punched into cards
and printed on the cards; the first 64 characters are printed on line
1 of the card and the remaining 16 characters are printed on line 3.

Specifies that the data set is for punching cards. See the description
of the character X for associated punch and print data sets.

Specifies that the data set is for reading cards.

Specifies that the data set is for printing. See the description of the
character X for associated punch and print data sets.

102 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised Decem ber 15, 1972
By TNL GN26-0748

DCB-QSAM
X

-Specifies that an associated data set is opened for output for both
punching and printing. Coding the character X is used to
distinguish the 3525 printer output data set from the 3525 punch
output data set.

Note: If data protection is specified, the data protection image (DPI) must be
specified in the FCB subparameter of the DD statement for the data set.
Source: The DEVD operand can be supplied only in the DCB macro instruction.
However, the optional operands can be supplied in the DCB macro instruction, the
DCB subparameter of a DD statement, or by the problem program before
completion of the data control block exit routine.
DSORG= {PSI
{PSU}
The DSORG operand specifies the organization of the data set and if the data set
contains any location-dependent information that would make it unmovable. The
following can be specified in the DSORG operand:
PS

Specifies a physical sequential data set.

PSU

Specifies a physical sequential data set that contains location-dependent
information.

Source: The DSORG operand must be coded in the DCB macro instruction.
EODAD= relexp
The EODAD operand specifies the address of the routine given control when the
end of an input data set is reached. Control is given to this routine when a GET
macro instruction is issued and there are no additional records to be retrieved.
When your EODAD routine receives control, register contents (except for register
15) will be the same as they were when the last GET macro instruction was issued.
Register 15 will contain a hexadecimal 4 if you have processed an end-of-volume
tape label; otherwise, register 15 will contain a O. If the record format is
RECFM=FS or FBS the end-of-data condition is sensed when file mark is read or
if more data is requested after reading a truncated block. A GET macro instruction
should not be issued after an end-of-data condition is sensed. If the end of the
data set has been reached but no EODAD address has been supplied to the data
control block, the task is abnormally terminated.
Source: The EODAD operand can be supplied in the DCB macro instruction or by the
problem program before the end of the data set has been reached.
EROPT =

{ACC}
{SKP}
{ABE}

The EROPT operand specifies the action taken by the system when an
uncorrectable input/output data validity error occurs and no error analysis
(SYNAD) routine address has been provided, or it specifies the action taken by the
system after the error analysis routine has returned control to the system with a
RETURN macro instruction. The specified action is taken for input operations or
for output operations to a printer.

Macro Instruction Descriptions 103

Uncorrectable input/output errors resulting from channel operations or
direct-access operations that make the next record inaccessible cause the task to be
abnormally terminated regardless of the action specified in the EROPT operand.
ACC -

Specifies that the problem program accepts the block causing the error.
This action can be specified when a data set is opened for INPUT,
RDBACK, UPDAT, or OUTPUT (OUTPUT applies to printer data sets
only).

SKP -

Specifies that the block that caused the error is skipped. Specifying
SKP also causes the buffer associated with the data block to be
released. This action can be specified when a data set is opened for
INPUT, RDBACK, or UPDAT.

ABE -

Specifies that the error results in the abnormal termination of the task.
This action can be specified when the data set is opened for INPUT,
OUTPUT, RDBACK, or UPDAT.

If the EROPT operand is omitted, the ABE action is assumed.

Source: The EROPT operand can be specified in the DCB macro instruction, in the
DCB subparameter of a DD statement, or by the problem program at any time. The
problem program can also change the action specified at any time.
EXLST= relexp
The EXLST operand specifies the address of the problem program exit list. The
EXLST operand is required if the problem program requires additional processing
for user labels, user totaling, data control block exit routine, end-of-volume, block
count exits, to define a forms control buffer (FCB) image, or to use the DCB
ABEND exit for ABEND condition analysis.
Refer to Appendix D of this publication for the format and requirements of exit list
processing. For additional information about exit routine processing, refer to
OS / VS Data Management Services Guide.
Source: The EXLST operand can be supplied in the DCB macro instruction or by the
problem program any time before the exit is required by the problem program.
LRECL=

{absexp} {X}

The LRECL operand specifies the length, in bytes, for fixed-length logical records,
or it specifies the maximum length, in bytes for variable-length or
undefined-length (output only) logical records. The value specified in the LRECL
operand cannot exceed the value specified in the BLKSIZE operand except when
variable-length spanned records are used.
For fixed-length records that are unblocked, the value specified in theLRECL
operand must be equal to the value specified in the BLKSIZE operand. For
blocked fixed-length records, the value specified in the LRECL operand must be
evenly divisible into the value specified in the BLKSIZE operand.
For variable-length logical records, the value specified in the LRECL operand must
include the maximum data length (up to 32,752) plus four bytes for the
record-descriptor word (RDW).

104 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Added December 1 S, 1972
By TNL GN26-0748

DCB-QSAM
For undefined-length records, the problem program must insert the actual logical
record length into the DCBLRECL field before writing the record, or the maximum
length record will be written.
F or variable-length spanned records, the logical record length (LRECL) can exceed
the value specified in the BLKSIZE operand, and a variable-length spanned record
can exceed the maximum blocksize. When the logical record length exceeds the
maximum blocksize, the logical record length is specified as LRECL=X.

Macro Instruction Descriptions 104.1

DCB-QSAM
Source: The LRECL operand can be supplied in the DCB macro instruction, in the
DCB subparameter of a DD statement, by the problem program before completion of
the data control block exit routine, or by the data set label of an existing data set.
MACRF= HG {M} [CI)
{L }

{T }
{D }
HP

{M} [CI) ,P {M} [CD}
{L}
{L }

{T }

{T}

{D }

{D}

HG {M} [CI)
{L }

{T }
{D}
The MACRF operand specifies the type of macro instructions (GET, PUT or
PUTX, CNTRL, RELSE, and TRUNC) and the transmittal modes (move, locate,
data, and substitute) that are used with the data set being created or processed.
The operand can be coded in any of the combinations shown above; the following
describes the characters that can be coded:
C

Specifies that the CNTRL macro instruction is used with the data set. If
the CNTRL macro instruction is specified, the data set should be for a
card reader (stacker selection) or printer (carriage and spacing control).
The CNTRL option can be specified with GET in the move mode only.

Specifies that the data transmittal mode is used (only the data portion of
a record is moved to or from the work area). Data mode is used only
with variable-length spanned records.

Specifies that GET macro instructions are used. Specifying G also
provides the routines that allow the problem program to issue RELSE
macro instructions.

Specifies that the locate transmittal mode is used; the system provides the
address of the buffer containing the data.

Specifies that the move transmittal mode is used; the system moves the
data from the buffer to the work area in the problem program.

Specifies that PUT or PUTX macro instructions are used. Specifying P
also provides the routines that allow the problem program to issue
TR UN C macro instructions.

Specifies that the substitute transmittal mode is used; the system
substitutes a buffer for a work area contained in the problem program.

Note: For data sets on paper tape that are processed by QSAM, only MACRF=(GM)
can be specified.
Source: The MACRF operand can be supplied only in the DCB macro instruction.

Macro Instruction Descriptions 105 "

P~ge of GC26-3793-1
. Revised December 15, 1972
By TNL GN26-0748

{BI
{TI
{VICU
{CIT][BU
OPTCD= {HIZ)[BU
{W[C)[T)[BU
{ZIC)[T)[BU
{QIC)[B)[{TIU
{Zl
The OPTeD operand specifies the optional services used with the QSAM data set.
Two of the optional services, OPTCD=B and OPTCD=H, cannot be specified in
the DCB macro instruction. They are requested in the DCB subparameter of a DD
statement. Since all optional services codes must be supplied by the same source,
the OPTCD operand must be omitted from the DCB macro instruction if either of
these options is requested in a DD statement. The following describes the
characters that can be specified.
C

Requests that chained scheduling be used. OPTCD=C cannot be
specified when either BFTEK=A or BFTEK=R is specified for the same
data control block. Also, chained scheduling cannot be specified for
associated data sets or printing on a 3525. OS/VS supports chained
scheduling in nonpageable storage only. If chained scheduling is
requested in pageable storage, the request is ignored and normal
scheduling is substituted.

Requests that ASCII tape records in an input data set be converted to
EBCDIC code when the input record has been read, or an output record
in EBCDIC code be converted to ASCII code before the record is
written.

Requests the user totaling facility. If this facility is requested, the EXLST
operand should specify the address of an exit list to be used.

Specified only for a printer with the universal-character-set feature. This
option unblocks data checks (permits them to be recognized as errors)
and allows analysis by the appropriate error analysis routine (SYNAD
routine). If the V option is omitted, data checks are not recognized as
errors.

W
Z

Specifies that the system performs a validity check for each record
written on the direct-access device being used.
For magnetic tape, input only, the Z option requests the system to
shorten its normal error recovery procedure to consider a data check as a
permanent I/O error after five unsuccessful attempts to read a record.
This option is available only if it is selected when the operating system is
generated. OPTCD=Z is used when a tape is known to contain errors
and there is no need to process every record. The error analysis routine
(SYNAD) should keep a count of permanent errors and terminate
processing if the number becomes excessive.
For direct-access devices only, the Z option requests the system to use
the search direct option to accelerate the input operations for a data set.
OPTCD=Z cannot be specified when RECFM=VT, FS, FBT, VS, or
VBS.

106 OS /VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

DCB-QSAM

Note: The following describes the optional services that can be specified in the DCB
subparameter of a DD statement. If either of these options is requested, the complete
OPTCD operand must be supplied in the DD statement.
If OPTCD=B is specified in the DCB subparameter of a DD statement, it

B-

forces the end-of-volumo/(EOV) routine to disregard the end-:-of-file
recognition for magnetic tape. When this occurs, the EOV routine uses the
number of volume serial numbers to determine end of file.
H -

If OPTCD=H is specified in the DCB subparameter of a DD statement, it

specifies that the DOS/OS interchange feature is being used with the data set.
RECFM=

)
(B
)
(S
)
(T
(BS )
(BT )
(ST )
(BST)

(B
(S
(T
(BS
(BT

[Al)
(M)

(Al)
(M)

(Al)

(Al)
(M)

The RECFM operand specifies the record format and characteristics of the data set
being created or processed. All record formats can be used in QSAM. The
following describes the characters that can be specified.
A

Specifies that the records in the data set contain American National
Standards Institute (ANSI) control characters. Refer to Appendix E for a
description of control characters.

Specifies that the data set contains blocked records.

Specifies that the data set contains variable-length ASCII tape records.
See OPTCD=Q and the BUFOFF operand for a description of how to
specify ASCII data sets.

Specifies that the data set. contains fixed-length records.

Specifies that the records in the data set contain machine code control
characters. Refer to Appendix E for a description of control characters.
RECFM=M cannot be used with ASCII data sets.

For fixed-length records, S specifies that the records are written as
standard blocks; the data set does not contain any truncated blocks or
unfilled tracks, with the exception of the last block or track in the data
set.
For variable-length records, S specifies that a record can span more than
one block. If spanned records are used, exchange buffering (BFTEK=E)
cannot be specified.
Macro Instruction Descriptions 107

Specifies that the track-overflow feature is used with the data set. The
track-overflow feature allows a record to be written partially on one
track and the remainder of the record on the following track (if required).
Chained scheduling (OPTCD=C) and exchange buffering (BFTEK=E)
cannot be used if the track-overflow feature is used.

Specifies that the data set contains undefined-length records.

Specifies that the data set contains variable-length records.
Note: RECFM= V cannot be specified for a card reader data set or an
ASCII tape data set.

Source: The RECFM operand can be supplied in the DCB macro instruction, in the
DeB subparameter of a DD statement, by the problem program before completion of
the data control block exit routine, or by the data set label of an existing data set.
SYNAD= relexp
The SYNAD operand specifies the address of the error analysis routine given
control when an uncorrectable input/output error occurs. The contents of the
registers when the error analysis routine is given control are described in Appendix
A of this publication.
The error analysis routine must not use the save area pointed to by register 13,
because this area is used by the system. The system does not restore registers when
it regains control from the error analysis routine. The error analysis routine can
issue a RETURN macro instruction that uses the address in register 14 to return
control to the system.
If the error condition was the result of a data-validity error, the control program

takes the action specified in the EROPT operand; otherwise, the task is abnormally
terminated. The control program takes these actions when the SYNAD operand is
omitted or when the error analysis routine returns control.
Source: The SYNAD operand can be supplied in the DCB macro instruction or by the
problem program. The problem program can also change the error routine address at
any time.

108 OS/VS Data Management Macro Instructions

DeBD

DCBD - Provide Symbolic Reference to Data Control Blocks (BDAM, BISAM,
BPAM, BSAM, QISAM, and QSAM)
The DCBD macro instruction is used to generate a dummy control section that
provides symbolic names for the fields in one or more data control blocks. The names
and attributes of the fields appear as part of the description of each data control block
in Appendix F of this publication. Attributes of the symbolically named fields in the
dummy section are the same as the fields in the data control blocks, with the exception
of fields containing 3-byte addresses. The symbolically named fields containing 3-byte
addresses have length attributes of four and are aligned on fullword boundaries.
The name of the dummy control section generated by a DCBD macro instruction is
IHADCB. The use of any of the symbolic names provided by the dummy section must
be preceded by a USING instruction specifying IHADCB and a dummy section base
register (which contains the address of the actual data control block). The DCBD
macro instruction can only be issued once within any assembled module; however, the
resulting symbolic names can be used for any number of data control blocks by
changing the address in the dummy section base register. The DCBD macro instruction
can be coded at any point in a control section; if coded at any point other than at the
end of a control section; however, the control section must be resumed by coding a
CSECT instruction.
The DCBD macro instruction is written as follows:

DCBD

blank

[DSORG=«([B~ [, DA] [, IS] [, LR] [, PO] [, Ps] [as]])J
~DEVD=([DA] [,PC] [,PRJ [,PT] [,RD] [, TA] [,MR]B

DSORG=(~~

)
«BS][,DA][,IS)[,LR][,PO][,PS][,QS) )

The DSORG operand specifies the types of data control blocks for which symbolic
names are provided. If the DSORG operand is omitted, the DEVD operand is
ignored, and symbolic names are provided only for the "foundation block" portion
that is common to all data control blocks. One or more of the following pairs of
characters can be specified; each pair of characters must be separated by a comma:
BS

Specifies a data control block for a sequential data set and basic access
method.

Specifies a data control block for a direct data set.

Specifies a data control block for an indexed sequential data set.

Specifies a dummy section for the logical record length field
(DCBLRECL) only.

Specifies a data control block for a partitioned data set.

Specifies a data control block for a sequential data set. PS includes
both BS and QS.

Macro Instruction Descriptions 109

Specifies a data control block for a sequential data set and queued
access method.

Specifies a data control block for graphics; this operand cannot be used
in combination with any of the above.

DEVD= [DA][,PC)[,PR][,PI)[,RD)[,TA][,MR]

The DEVD operand specifies the types of devices on which the data set can reside.
If the DEVD operand is omitted and a sequential data set is specified in the
DSORG operand, symbolic names are provided for all of the device types listed
below. One or more of the following pairs of characters can be specified; each pair
of characters must be separated by a comma:
DA-

Direct-access device

Online punch

Online printer

Paper tape

Online card reader or read punch feed

Magnetic tape

Magnetic character reader

110 OS/VS Data Management Macro instructions

ESETL

ESETL -

End Sequential Retrieval (QISAM)
The ESETL macro instruction ends the sequential retrieval of data from an indexed
sequential data set and causes the buffers associated with the specified data control
block to be released. An ESETL macro instruction must separate SETL macro
instructions issued for the same data control block.
The ESETL macro instruction is written as follows:

[ symbol]

deb address -

ESETL

deb address

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block opened for
the indexed sequential data set being processed.

Macro Instruction Descriptions 111

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

FEOV

FEOV -

Force End of Volume (BSAM and QSAM)
The FEOV macro instruction causes the system to assume an end-of-volume
condition, and causes automatic volume switching. Volume positioning for magnetic
tape can be specified by the option operand. If no option is coded, the positioning
specified in the OPEN macro instruction is used. Output labels are created as required
and new input labels are verified. The standard exit routines are given control as
specified in the data control block exit list. For BSAM, all input and output operations
must be tested for completion before the FEOV macro instruction is issued. The
end-of-data-set (EODAD) routine is given control if an input FEOV macro
instruction is issued for the last volume of an input data set.
The FEOV macro instruction is written as follows:
[symbol]

deb address -

FEOV

,REWIND]
deb address [ , LEAVE

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for an
opened sequential data set.
The following operands request optional services.
REWIND

Requests that the system position the tape at the load point regardless
of the direction of processing.

LEAVE

Requests that the system position the tape at the logical end of the
data set on that volume~ this option causes the tape to be positioned at
a point after the tapemark that follows the trailer labels. Note that
multiple tape units must be available to achieve correct positioning. If
only one tape unit is available, its volume is rewound and unloaded.

Macro Instruction Descriptions 113

FIND

FIND -

Establish the Beginning of a Data Set Member (BPAM)
The FIND macro instruction causes the system to use the address of the first block of a
specified partitioned data set member as the starting point for the next READ macro
instruction for the same set. All previous input and output operations that specified the
same data control block must have been tested for completion before the FIND macro
instruction is issued.
The FIND macro instruction is written as follows:

FIND

[symbol]

deb address -

deb address, {name address, D
}
relative address list,e

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for the
opened partitioned data set being processed.
name address -

RX-Type Address, (2-12), or (0)

The name address operand specifies the address of a doubleword that contains the
data set member name. The name must start in the first byte of the doubleword
and be padded on the right (if necessary) to complete the eight-byte doubleword.
D

Specifies that only a member name has been supplied, and the access
method must search the directory of the data set indicated in the data
control block to find the location of the member.

relative address list -

RX-Type Address, (2-12), or (0)

The relative address list operand specifies the address of the area that contains
the relative address (TTRK) for the beginning of a data set member. The
relative address can be a list entry completed by using a BLDL macro
instruction for the data set being processed, or the relative address can be
supplied by the problem program.

Specifies that a relative address has been supplied, and no directory
search is required. The relative address supplied is used directly by the
access method for the next input operation.

Macro Instruction Descriptions 115

Completion Codes
When the system returns control to the problem program, the low-order byte of
register 15 contains one of the following return codes; the three high-order bytes of
register 15 are set to zero.

name address, D

relative address list, C

- Successful execution

- Name not found

- Permanent input/output
error found during
directory search

00 - At all times. If the relative
address is in error, execution
of the next READ macro
instruction causes control to
be passed to the error
analysis (SYNAD) routine.

116 OS/VS Data Management Macro Instructions

FREEBUF

FREEBUF -

Return a Buffer to a Pool (BDAM, BISAM, BPAM, and BSAM)
The FREEBUF macro instruction causes the system to return a buffer to the buffer
pool assigned to the specified data control block. The buffer must have been acquired
using a GETBUF macro instruction.
The FREEBUF macro instruction is written as follows:

FREEBUF

[symbol]

deb address -

deb address, register

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for an
opened data set to which the buffer pool has been assigned.
register -

(2-12)

The register operand specifies one of registers 2 through 12 that contains the
address of the buffer being returned to the buffer pool.

Macro Instruction Descriptions 117

FREEDBUF

FREEDBUF -

Return a Dynamically Obtained Buffer (BDAM and BISAM)
The FREEDBUF macro instruction causes the system to return a buffer to the buffer
pool assigned to the specified data control block. The buffer must have been acquired
through dynamic buffering; that is, by coding '8' for the area address operand in the
associated READ macro instruction.
Note: A buffer acquired dynamically can also be released by a WRITE macro
instruction; refer to the description of the WRITE macro instruction for BDAM or
BISAM.
The FREEDBUF macro instruction is written as follows:

[symboU

deeb address -

FREEDBUF

deeb address,{ ~} ,deb address

RX-Type Address, (2-12), or (0)

The deeb address operand specifies the address of the data event control block
(DECB) used or created by the READ macro instruction that acquired the buffer
dynamically.
K

Specifies that BISAM is being used.

Specifies that BDAM is being used.

deb address -

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for the
opened data set being processed.

Macro Instruction Descriptions 119

FREEPOOL

FREEPOOL - Release a Buffer Pool (BDAM, BISAM, BPAM, BSAM,
QISAM, and QSAM)
The FREEPOOL macro instruction causes an area of storage, previously acquired for a
buffer pool for a specified data control block, to be released. The area must have been
acquired either automatically or by the execution of a GETPOOL macro instruction.
For queued access methods, the FREEPOOL macro instruction must not be issued
until after a CLOSE macro instruction has been issued for all the data control blocks
using the buffer pool. For basic access methods, the FREEPOOL macro instruction
can be issued as soon as the buffers are no longer required. A buffer pool should be
released only once, regardless of the number of data control blocks sharing the buffer
pool.

If BFALN=F is supplied from a source other than the DCB macro instruction, the
CLOSE macro instructions removes the bit that designates fullword alignment from the
data control block. In this case, if a FREEPOOL macro instruction is issued after the
CLOSE macro instruction, the system does not release the complete buffer area (eight
bytes are not released).
The FREEPOOL macro instruction is written as follows:

[symbol]

deb address -

FREEPOOL

I deb address

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of a data control block to which the
buffer pool has been assigned.

Macro Instruction Descriptions 121

GET-QISAM

GET -

Obtain Next Logical Record (QISAM)
The GET macro instruction causes the system to retrieve the next record. Control is
not returned to the problem program until the record is available.
The GET macro instruction is written as follows:

GET

[symbol]

deb address -

deb address [, area addres~

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for the
opened input data set being retrieved.
area address -

RX-Type Address, (2-12), or (0)

The area address operand specifies the storage address into which the system is to
move the record (move mode only). Either the move or locate mode can be used
with QISAM, but they must not be mixed within the specified data control block.
The following describes operations for move and locate modes:
Locate Mode: If the locate mode has been specified in the data control block, the
area address operand must be omitted. The system returns the address of the
buffer segment containing the record in register 1.
Move Mode: If the move mode h'ls been specified in the data control block, the
area address operand must specify the address in the problem program into which
the system will move the record. If the area address operand is omitted, the system
assumes that register 0 contains the area address. When control is returned to the
problem program, register 0 contains the area address, and register 1 contains the
address of the data control block.

Notes:
1. The end-of-data-set (EODAD) routine is given control if the end of the data set is
reached; the data set must be closed or an ESETL macro instruction must be issued.
An attempt to continue to use the data set will have unpredictable results.
2. The error analysis (SYNAD) routine is given control if the input operation could
not be completed successfully. The contents of the general registers when control is
given to the SYNAD routine are described in Appendix A.
3. When the key of an unblocked fixed-length record is retrieved with the data, the
address of the key is returned as follows (see the SETL macro instruction):
Locate mode -

The address of the key is returned in register O.

Move mode -

The key appears in front of the record in your buffer area.

4. If a GET macro instruction is issued for a data set and the previous request issued
for the same data set was an OPEN, ESETL, or unsuccessful SETL (no record
found), a SETL B (key and data) is invoked automatically, and the first record in
the data set is returned.

Macro Instruction Descriptions 123

GET-QSAM

GET -

Obtain Next Logical Record (QSAM)
The GET macro instruction causes the system to retrieve the next record. Various
modes are available and are specified in the DCB macro instruction. In the locate
mode, the GET macro instruction locates the next sequential record or record segment
to be processed. The system returns the address of the record in register 1 and places
the length of the record or segment in the logical-record-Iength (DCBLRECL) field of
the data control block. The user can process the record within the input buffer or
move the record to a work area.
In the move mode, the GET macro instruction moves the next sequential record to the
user's work area. This work area must be big enough to contain the largest logical
record of the data set and its record-descriptor word (variable-length records). The
system returns the address of the work area in register 1. (This feature provides
compatibility with the substitute mode GET.) The record length is placed in the
DCBLRECL field. The move mode can be used only with simple buffering.
In the data mode, which is available only for variable-length spanned records, the GET
macro instruction moves only the data portion of the next sequential record to the
user's work area.
In the substitute mode, the GET macro instruction transfers ownership of the next
sequential record in a data set from the system to the user. In return, the ownership of
a work area is transferred from the user to the system for future use as an input buffer.
There is no movement of data. The address of an input buffer containing the record is
returned to the user in register 1 after the instruction is executed. The system returns
the record length in the DCBLRECL field. For undefined-length records, the
DCBLRECL field is equal to the BLKSIZE field for chained scheduling. The
substitute mode can be used only with exchange buffering and cannot be used with
variable-length records.
If the ASCII translation routines are included when the operating system is generated,

translation can be requested by coding LABEL=(,AL) or (,AUL) in the DD statement,
or it can be requested by coding OPTCD=Q in the DCB macro instruction or DCB
subparameter of the DD statement. When translation is requested, all QSAM records
whose record format (RECFM operand) is F, FB, D, DB, or U are automatically
translated from ASCII code to EBCDIC code as soon as the input buffer is full. For
translation to occur correctly, all input data must be in ASCII code.
The GET macro instruction is written as follows:

[symbo~
deb address -

GET

deb address [,area address]

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the' data control block for the
opened input data set being retrieved.

Macro Instruction Descriptions 125

area address -

RX-Type Address, (2-12), or (0)

The area address operand specifies the address of an area into which the system is
to move the record (move or data mode), or it specifies the address of an area to be
exchanged for the buffer containing the record (substitute mode). The move,
locate, data, or substitute mode can be used with QSAM, but they must not be
mixed within the specified data control block. If the area address operand is
omitted in the move, data, or substitute mode, the system assumes that register 0
contains the area address. The following describes the operation of the four modes:
Locate mode: If the locate mode has been specified in the data control block, the
area address operand must be omitted. The system returns the address of the
buffer segment containing the record in register 1.
When retrieving variable-length spanned records, the records are obtained one
segment at a time. The problem program must retrieve additional segments by
issuing subsequent GET macro instructions, except when a logical record interface
is requested (by specifying BFTEK=A in the DCB macro instruction or by issuing a
BUILDRCD macro instruction.) In this case, the control program retrieves all
record segments and assembles the segments into a complete logical record. The
system returns the address of this record area in register 1. To process a record
when the logical record length is greater than 32,756 bytes, LRECL=X must be
specified in the data control block, and the problem program must assemble the
segments into a complete logical record.
Move mode: If the move mode has been specified in the data control block, the
area address operand specifies the address of an area in the problem program into
which the system will move the record.
For variable-length spanned records, the system constructs the record-descriptor
word in the first four bytes of the area and assembles one or more segments into
the data portion of the logical record; the segment descriptor words are removed.
Data mode: If the data mode has been specified in the data control block (data
mode can be specified for variable-length spanned records only), the area address
operand specifies the address of the area in the problem program into which the
system will move the data portion of the logical record; a record-descriptor word is
not constructed when data mode is used.
Substitute mode: If the substitute mode is specified in the data control block, the
area address operand specifies the address of an area in the problem program that
will be exchanged for the buffer containing the record. The system returns the
address of the buffer containing the record in register 1.

GET Routine Exits
The end-of-data-set (EODAD) routine is given control if the end of the data set is
reached; the data set must be closed. Issuing a GET macro instruction in the EODAD
routine results in abnormal termination of the job step.
The error analysis (SYNAD) routine is given control if the input operation could not be
completed successfully. The contents of the general registers when control is given to
the SYNAD routine are described in Appendix A.

126 OS /VS Data Management Macro Instructions

GETBUF

GETBUF -

Obtain a Buffer (BDAM, BISAM, BPAM, and BSAM)
The GETBUF macro instruction causes the control program to obtain a buffer from the
buffer pool assigned to the specified data control block and to return the address of the
buffer in a designated register. The BUFCB field of the data control block must
contain the address of the buffer pool control block when the GETBUF macro
instruction is issued. The system returns control to the instruction following the
GETBUF macro instruction. The buffer obtained must be returned to the buffer pool
using a FREEBUF macro instruction.
The GETBUF macro instruction is written as follows:

~ymbolJ

GETBUF

deb address -

deb address, register

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block that
contains the buffer pool control block address.
register -

(2-12)

The register operand specifies one of the registers 2 through 12 in which the system
is to place the address of the buffer obtained from the buffer pool. If no buffer is
available, the contents of the designated register are set to zero.

Macro Instruction Descriptions 127

GETPOOL

GETPOOL and QSAM)

Build a Buffer Pool (BDAM, BISAM, BPAM, BSAM, QISAM,

The GETPOOL macro instruction causes a buffer pool to be constructed in a storage
area acquired by the system. The system places the address of the buffer pool control
block in the BUFCB field of the data control block. The GETPOOL macro instruction
must be issued either before an OPEN macro instruction is issued or during the data
control block exit routine for the specified data control block.
The GETPOOL macro instruction is written as follows:

rsymbol]
deb address -

GETPOOL

deb address,Inumber of buffers, buffer length
(0)

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block to which
the buffer pool is assigned. Only one buffer pool can be assigned to a data control
block.
number of buffers -

symbol, decimal digit, absexp, or (2-12)

The number-or-buffers operand specifies the number of buffers in the buffer pool up
to a maximum of 255.
buffer length -

symbol, decimal digit, absexp, or (2-12)

The buffer length operand specifies the length, in bytes, or each buffer in the buffer
pool. The value specified for the buffer length must be a double word multiple;
otherwise the system rounds the value specified to the next higher double word
multiple. The maximum length that can be specified is 32,760 bytes. For QSAM,
the buffer length must be at least as large as the value specified in the blocksize
(DCBBLKSI) field in the data control block.
(0) - Coded as shown
The number of buffers and buffer length can be specified in general register o. If
(0) is coded, register 0 must contain the binary values for the number of buffers
and buffer length as shown in the following illustration:
Register 0
Number of Buffers

Bits:

Buffer Length

Macro Instruction Descriptions 129

The following illustration shows the format of the buffer pool. The buffer pool and the
associated storage area are released by issuing a FREEPOOL macro instruction after
issuing a CLOSE macro instruction for the data set indicated in the specified data
control block.
Area Addre ss

I
Buffer Pool
Control
Block

14- 8 b tes
Y

""'"-

Buffer

-L --.J
Buffe'
Length

[

Area Length
Area Length=(Buffer Length) x (Number of Buffers) + 8

130 OS/VS Data Management Macro Instructions

Buffer

Buffer
Length

NOTE

NOTE - Provide Relative Position (BPAM and BSAM Access Only)

Tape and Direct

The NOTE macro instruction causes the system to return the relative position of the
last block read from or written into a data set. All input and output operations using
the same data control block must be tested for completion before the NOTE macro
instruction is issued.
The capability of using the NOTE macro instruction is automatically provided when a
partitioned data set is used (DSORG=PO or POU), but when a sequential data set
(BSAM) is used, the use of NOTE/POINT macro instructions must be indicated in the
MACRF operand of the DCB macro instruction. The relative position, in terms of the
current volume, is returned in register 1 as follows:
Magnetic Tape: The block number is in binary, right-adjusted in register 1 with
high-order bits set to zero. Do not use a NOTE macro instruction for tapes without
standard labels when:
• The data set is opened for RDBACK (specified in the OPEN macro instruction).
• The DISP parameter of the DD statement for the data set specifies DISP=MOD.
Direct-Access Device: TTRz format, where:
TT is a 2-byte relative track number.
R

is a I-byte block (record) number on the track indicated by TT.

is a byte set to zero.

Note: When a direct-access device is being used, the amount of remaining space on
the track is returned in register 0 if a NOTE macro instruction follows a WRITE macro
instruction; if a NOTE macro instruction follows a READ macro instruction, the track
capacity of the direct-access device is returned in register O.
The NOTE macro instruction is written as follows:
~ymboQ

deb address -

NOTE

·1

deb address

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block opened for
the partitioned or sequential data set being processed.

Macro Instruction Descriptions 131

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

OPEN

OPEN - Logically Connect a Data Set (BDAM, BISAM, BPAM, BSAM,
QISAM, and QSAM)
The OPEN macro instruction causes the specified data control block(s) to be
completed and the data set(s) identified in the data control block(s) to be prepared for
processing. Input labels are analyzed and output labels are created. Control is given to
exit routines as specified in the data control block exit list. The processing method
(option 1) is designated to provide correct volume positioning for the data set and
define the processing mode (INPUT, OUTPUT, etc.) for the data set(s). Final volume
positioning (when volume switching occurs) can be specified (option 2) to override the
positioning implied by the DD statement DISP parameter. Any number of data control
block addresses and associated options may be specified in the OPEN macro
instruction.
If associated data sets for a 3525 card punch are being opened, all associated data sets

must be open before an I/O operation is initiated for any of the data sets. For a
description of associated data sets, refer to OS/VS Data Management Services Guide.

I To support DEB validity checking in OS/VS, an OPEN macro instruction must be
issued for every data extent block (DEB) created.
The standard form of the OPEN macro instruction is written as follows (the list and
execute forms are shown following the description of the standard form):

[symbol]

dcb address -

OPE,N

(deb address, [(options) ] ' .•. )

A-Type Address or (2-12)

The dcb address operand(s) specifies the address of the data control block(s) for
the data set(s) to be prepared for processing.
options

The options operands shown in the following illustration indicate the volume
positioning available based on the device type and access method being used. If
option 1 is omitted, INPUT is assumed. If option 2 is omitted, DISP is assumed.
Option 1 must be coded if option 2 is coded. Options 1 and 2 are ignored for
BISAM and QISAM (in the scan mode), and the data control block indicates the
operation. OUTPUT or OUTIN must be specified when creating a data set.

Macro Instruction Descriptions 133

DEVICE TYPE
ACCESS
METHOD

QSAM

BSAM

Magnetic tape
Option 1

[INPUT

Direct access
Option 1

Option 2
[,REREAD]
]

[OUTPUT]

[,LEAVE

[ROBACK]

[,DISP

[INPUT

[,REREAD]
[,LEAVE ]

[OUTPUT]
[INOUT ]

[,DISP

]

]
[OUTIN
[ROBACK]

[INPUT
[OUTPUT]
[UPDAT ]
[INPUT
[OUTPUT]
[lNOUT ]
[OUTIN
[UPDAT

Other Types

Option 2

Option 1

[,REREAD]
[,LEAVE ]

[INPUT

[,DISP

[OUTPUT]

]

[,REREAD]
[,LEAVE ]
[,DISP

Option 2

[INPUT
[OUTPUT]

]

]
]

[OUTPUT]

QISAM
(Load Mode)

[INPUT
[OUTPUT]

BPAM,
BDAM

[UPDAT

]

The following describes the options shown in the preceding illustration. All option
operands are coded as shown.
Option 1

Meaning

INPUT

Input data set.

INOUT

The data set is first used for input and, without reopening, it is used as
an output data set. The data set is processed as INPUT if
LABEL=(",IN) is specified in the DD statement.

OUTPUT

Output data set (for BDAM, OUTPUT is equivalent to UPDAT).

OUTIN

The data set is first used for output and, without reopening, it is used
as an input data set. The data set is processed as output if
LABEL = (",OUT) is specified in the DD statement.

RDBACK

Input data set, positioned 'to read backward.

UPDAT

Data set to be updated in place.

Option 2

Meaning

LEAVE

Positions the current volume to the logical end of the data set.

REREAD

Positions the current volume to reprocess the data set when volume
switching occurs.

DISP

Performs volume positioning implied by the DISP parameter of the DD
control statement, as follows:

DISP Parameter
PASS

Action

Forward space to the end of the data set on the
current volume

DELETE

Rewind the current volume

KEEP, CATLG, or
UNCATLG

Rewind and unload the current volume

134 OS/VS Data Management Macro Instructions

OPEN
Note: When the DELETE option is specified, the system waits for the completion of
the rewind operation before it continues processing subsequent reels of tape.
After the OPEN macro instruction has been executed, bit 3 of the DCBOFLGS field in
the data control block is set to 1 if the data control block has been opened successfully,
but is set to 0 if the data control block has not been opened successfully.
Note: The following errors cause the results indicated:
Error

Result

Opening a data control block that
is already open.

No action.

Attempting to open a data control
block when the deb address
operand does not specify the
address of a data control block.

Unpredictable.

Opening a data control block when
a corresponding DD statement has
not been provided.

A "DD STATEMENT MISSING" message
is issued. An attempt to use the
data set causes unpredictable results.

The last of these errors can be detected by testing bit 3 of the DCBOFLGS field in the
data control block. Bit 3 is set to 0 in the case of an error and can be tested by the
sequence:
TM DCBOFLGS,X'10'
BZERRORRTN

(Branch to user's error routine)

Executing the two instructions shown above requires writing a DCBD macro instruction
in the program, and a base register must be defined with a USING statement before
the instructions are executed.

Macro Instruction Descriptions 135

OPEN -

List Form

List Form
The list form of the OPEN macro instruction is used to construct a data management
parameter list. Any number of operands (data control block addresses and associated
options) can be specified.
The OPEN macro instruction can be used with a variable-length parameter list. The
length of a list generated by a list form instruction must be equal to the maximum
length list required by any execute form instruction that refers to the same list. A
maximum length list can be constructed by one of two methods:
• Code a list-form instruction with the maximum number of parameters that are
required by an execute form instruction that refers to the list.
• Code a maximum length list by using commas in a list-form instruction to acquire a
list of the appropriate size. For example, coding OPEN ("""",) would provide a list
of five fullwords (five dcb addresses and five options).
A parameter list constructed by an OPEN, list form, macro instruction can be referred
to by either an OPEN or CLOSE execute form instruction.
The description of the standard form of the OPEN macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates which operands are completely optional and those required in at least one of
the pair of list and execute forms. The format description below indicates the optional
and required operands in the list form only.
The list form of the OPEN macro instruction is written as follows:

[symbol]

deb address MF=L -

OPEN

([deb address] , [(options)], ... ),MF=L

A-Type Address

Coded as shown

The MF=L operand specifies that the OPEN macro instruction is used to create a
data management parameter list that is referenced by an execute form instruction.

Macro Instruction Descriptions 137

OPEN -

Execute Form

Execute Form
A remote data management parameter list is used in, and can be modified by, the
execute form of the OPEN macro instruction. The parameter list can be generated by
the list form of either an OPEN or CLOSE macro instruction.
The description of the standard form of the OPEN macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates which operands are totally optional and those required in at least one of the
pair of list and execute forms. The format description below indicates the optional and
required operands in the execute form only.
The execute form of the OPEN macro instruction is written as follows:

[symbol]

[([deb address]' [(options)J , .•• )J

OPEN

,MF=(E,1 data management list address

deb address -

MF=(E,

RX-Type Address or (2-12)

{data management list address J
{
(1)
D

This operand specifies that the execute form of the OPEN macro instruction is
used, and an existing data management parameter list (created by a list-form
instruction) is used. The MF= operand is coded as follows:
E-

Coded as shown

data management list address -

RX-Type, (2-12), (1)

Macro Instruction Descriptions 139

POINT

POINT - Position to a Relative Block (BPAM and BSAM Direct Access Only)

Tape and

The POINT macro instruction causes the system to start processing the next READ or
WRITE operation at the specified block in the data set on the current volume. All
input and output operations using the same data control block must have been tested
for completion before the POINT macro instruction is issued. When processing a data
set that has been opened for UPDAT, the POINT macro instruction must be followed
by a READ macro instruction. When processing an output data set, the POINT macro
instruction must be followed by a WRITE macro instruction prior to closing the data
set, unless a CLOSE macro instruction (with TYPE=T specified) was issued prior to
the POINT macro instruction. Issuing a POINT macro instruction for the system input
data set or a system output data set on magnetic tape results in an effective Nap
instruction.

The POINT macro instruction is written as follows:

[symbol]

dcb address -

POINT

deb address, block address

RX-Type Address, (2-12), or (1)

The dcb address operand specifies the address of the data control block for the
opened data set that is to be positioned.
block address -

RX-Type Address, (2-12), or (0)

The block address operand specifies the address of a fullword on a fullword
boundary containing the relative address of the block in the data set that is to be
processed next. The relative address is specified as follows:
Magnetic Tape: The block number is in binary and is right-adjusted in the
fullword with the high-order bits set to zero; add one if reading tape backward. Do
not use the POINT macro instruction for tapes without standard labels when:
•

The data set is opened for RDBACK.

•

The DD statement for the data set specifies DISP=MOD.

If OPTCD=H is indicated in the data control block, the POINT macro instruction

can be used to perform record positioning on DOS tapes that contain embedded
checkpoint records. Any embedded checkpoint records that are encountered during
the record positioning are bypassed and are not counted as blocks spaced over.
OPTCD=H must be specified in a job control language DD statement. Do not use
the POINT macro instruction to backspace DOS 7-track tapes that are written in
data convert mode and that contain embedded checkpoint records.
Direct-Access Device: The fullword specified in the block address operand contains
the relative track address (in the form TTRz), where:
TT is a 2-byte relative track number.
R is a I-byte block (record) number on the track indicated by TT.

Macro Instruction Descriptions 141

is a byte set to zero; it may also be set to 1 to retrieve the block following the
TTR block.

Note: The first block of a magnetic tape data set is always specified by the
hexadecimal value 00000001. The first block of a direct-access device data set can
be specified by either hexadecimal 00000001 or 00000100 (see the previous
description of TTRz).
If the volume cannot be positioned correctly or if the block identification is not of the

correct format, the error analysis (SYNAD) routine is given control when the next
READ or WRITE macro instruction is executed.

142 OS/VS.Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

PRTOV

PRTOV - Test for Printer Carriage Overflow (BSAM and QSAM Printer and 3525 Card Punch, Print Feature)

Online

The PRTOV macro instruction is used to control the page format for an online printer
when carriage control characters are not being used or to supplement the carriage
control characters that are being used.
The PRTOV macro instruction causes the system to test for an overflow condition on
the specified channel (either channel 9 or channel 12) of the printer carriage control,
and either skip the printer carriage to the line corresponding to channel 1, or transfer
control to the exit address, if one is specified. Overflow is detected after printing the
line that follows the line corresponding to channel 9 or channel 12.
When the PRTOV macro instruction is used with a 3525 card punch, print feature,
channel 9 or 12 can be tested. If an overflow condition occurs, control is passed to the
overflow exit routine if the overflow exit address is coded, or a skip to channel 1 (first
print-line of the next card) occurs.
When requesting overprinting (for example, to underscore a line), the PRTOV macro
instruction is issued before the first PUT or WRITE macro instruction only. The
PRTOV macro instruction should be issued only when the device type is an online
printer. PRTOV cannot be used to request overprinting on the 3525.
The PRTOV macro instruction is written as follows:

[symbol]

deb address -

PRTOV

deb

address/ll~ ~ ~overflow

exit address]

RX-Type Address or (2-12)

The deb address operand specifies the address of the data control block opened for
output to an online printer or 3525 card punch with a print feature.
9

Coded as shown

These operands specify which channel is to be tested by the PRTOV macro
instruction. For an online printer, 9 and 12 correspond to carriage control channels
and 12. For the 3525 card punch, 9 corresponds to print line number 17, and 12
corresponds to print line number 23. More detail about the card print-line format
is included in OS / VS Data Management Services Guide.

overflow exit address -

RX-Type Address or (2-12)

The overflow exit address operand specifies the address of the user-supplied routine
to be given control when an overflow condition is detected on the specified channel.
If this operand is omitted, the printer carriage skips to the first line of the next page
or the 3525 skips to the first line of the next card before executing the next PUT or
WRITE macro instruction.

Macro Instruction Descriptions 143

When the overflow exit routine is given control, the contents of the registers are as
follows:
Register

Contents

o and

The contents are destroyed.
The same contents as before the macro instruction was executed.
Return address.
Overflow exit routine address.

2 - 13
14
15

144 OS/VS Data Management Macro Instructions

PUT-QISAM

PUT -

Write Next Logical Record (QISAM)
The PUT macro instruction causes the system to write a record into an indexed
sequential data set. If the move mode is used, the PUT macro instruction moves a
logical record into an output buffer from which it is written. If the locate mode is
specified, the address of the next available output buffer segment is available in register
1 after the PUT macro instruction is executed. The logical record can then be
constructed in the buffer for output as the next record. The records are blocked by the
system (if specified in the data control block) before being placed in the data set. The
system uses the length specified in the record length (DCBLRECL) field of the data
control block as the length of the record currently being written. When constructing
blocked variable-length records in the locate mode, the problem program may either
specify the maximum record length once in the DCBLRECL field of the data control
block or provide the actual record length in the DCBLRECL field before issuing each
PUT macro instruction. Use of the maximum record length may result in more but
shorter blocks, since the system uses this length when it tests to see if the next record
can be contained in the current block.
The PUT macro instruction is used to create or extend an indexed sequential data set.
To extend the data set, the key of any added record must be higher than the highest
key existing in the data set, and the disposition parameter of the DD card must be
specified as DISP=MOD. The new records are placed in the prime data space, starting
in the first available space, until the original space allocation is exhausted.
To create a data set using previously allocated space, the disposition parameter of the
DD card must specify DISP=OLD.
The PUT macro instruction is written as follows:

PUT

[symbol]

deb address -

deb address [, area address]

RX-Type Address, (2-12), or (1)

The· deb address operand specifies the address of the data control block for the
opened ISAM data set.
area address -

RX-Type Address, (2-12), or (0)

The area address operand specifies the address of the area that contains the record
to be written (move mode only). Either move or locate mode can be used with
QISAM, but they must not be mixed within the specified data control block. The
following describes operations for locate and move modes:
Locate Mode: If the locate mode is specified in the data control block, the area
address operand must be omitted. The system returns the address of the next
available buffer in register 1; this is the buffer into which the next record is placed.
The record is not written until another PUT macro instruction is issued for the same
data control block. The last record is written when a CLOSE macro instruction is
issued to close the data set.

Macro Instruction Descriptions 145

Move Mode: If the move mode has been specified in the data control block, the
area address operand must specify the address in the problem program that contains
the record to be written. The system moves the record from the area to an output
buffer before control is returned. If the area address operand is omitted, the system
assumes that register zero contains the area address.

Put Routine Exit
The error analysis (SYNAD) routine is given control if the output operation could not
be completed satisfactorily. The contents of the registers when the error analysis
routine is given control are described in Appendix A.

146 OS/VS Data Management Macro Instructions

PUT-QSAM

PUT -

Write Next Logical Record (QSAM)
The PUT macro instruction causes the system to write a record in a sequential data set.
Various modes are available and are specified in the DCB macro instruction. In the
locate mode, the address of an area within an output buffer is returned in register 1
after the macro instruction is executed. The user should subsequently construct, at this
address, the next sequential record or record segment. The move mode of the PUT
macro instruction causes a logical record to be moved into an output buffer. In the
data mode, which is available only for variable-length spanned records, the PUT macro
instruction moves only the data portion of the record into one or more output buffers.
When the substitute mode is specified, the macro transfers ownership of a work area
containing a record to the control program. In return, the ownership of a buffer
segment is transferred to the user, for use as a work area. There is no movement of
data in storage.
The records are blocked by the control program (as specified in the data control block)
before being placed in the data set. For undefined-length records, the DCBLRECL
field determines the length of the record that is subsequently written. For
variable-length records, the DCBLRECL field is used to locate a buffer segment of
sufficient size (locate mode), but the length of the record actually constructed is
verified before the record is written (the output block can be filled to the maximum if,
before issuing the PUT macro, DCBLRECL is set equal to the record length). For
variable-length spanned records, the system segments the record according to the
record length, buffer length, and amount of unused space remaining in the output
buffer. The smallest segment created will be 5 bytes, 4 for the segment descriptor
word plus one byte of data.
If the ASCII translation routines are included when the operating system is generated,

translation can be requested by coding LABEL=(,AL) or (,AUL) in the DD statement,
or it can be requested by coding OPTCD=Q in the DCB macro instruction or DCB
subparameter of the DD statement. When translation is requested, all QSAM records
whose record format (RECFM operand) is F, FB, D, DB, or U are automatically
translated from EBCDIC code to ASCII code. For translation to occur correctly, all
output data must be in EBCDIC code; any EBCDIC character that cannot be
translated into an ASCII character is replaced by a substitute character.
The PUT macro instruction is written as follows:

[symbo~
deb address -

PUT

deb address

~area address]

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for the data
set opened for output.
area address -

RX-Type Address, (2-12), or (0)

The area address operand specifies the address of an area that contains the record
to be written (move or data mode), or it specifies the address of an area to be
exchanged for a buffer (substitute mode). The move, locate, data, or substitute
Macro Instruction Descriptions 147

mode can be used with QSAM, but they must not be mixed within the specified
data control block. If !he area address operand is omitted in the move, data, or
substitute mode, the system assumes that register zero contains the area address.
The following describes the operation of the four modes:
Locate Mode: If the locate mode is specified, the area address operand must be
omitted. The system returns the address of the next available buffer in register 1;
this is the buffer into which the next record is placed.

When variable-length spanned records are used and a record area has been
provided for a logical record interface (BFTEK=A has been specified in the data
control block or a BUILDRCD macro instruction has been issued), the address
returned in register 1 points to an area large enough to contain the maximum record
size (up to 32,756 bytes). The system segments the record and writes all segments,
providing proper control codes for each segment. If, for variable-length spanned
records, an area has not been provided, the actual length remaining in the buffer
will be returned in register O. In this case, it is the user's responsibility to segment
the records and process them in terms of record segments. The record or segment
is not written until another PUT macro instruction is issued for the same data
control block. The last record is written when the CLOSE macro instruction is
issued.
When a PUT macro instruction is used in the locate mode, the address of the buffer
for the first record or segment is obtained by issuing a PUT macro instruction;
QSAM returns the address of the buffer, but the record is not written until the next
PUT macro instruction is issued.
Move Mode: If the move mode has been specified in the data control block, the
area address operand specifies the address of the area that contains the record to be
written. The system moves the record to an output buffer before control is
returned. The address of the storage area is returned in register 1 (this action
provides compatibility with substitute mode operations, and makes it possible for
the problem program to be used in instances where substitute mode is requested but
cannot be supported by the system).
Data Mode: If the data mode is specified in the data control block (data mode can
be specified for variable-length spanned records only), the area address operand
specifies the address of an area in the problem program that contains the data
portion of the record to be written. The system moves the data portion of the
record to an output buffer before control is returned. The user must place the total
data length in the DCBPRECL (not DCBLRECL) field of the data control block
before the PUT macro instruction is issued.
Substitute Mode: If the substitute mode is specified in the data control block, the
area address operand specifies the address of an area in the problem program that
contains the next record to be written. The area is exchanged for an empty buffer.
The address of the empty buffer is returned in register 1.

Put Routine Exit
The error analysis (SYNAD) routine is given control if an output operation could not
be completed satisfactorily. If the output operation could not be completed
satisfactorily, the error analysis (SYNAD) routine is given control after the next PUT
instruction is issued. The contents of the registers when the error analysis routine· is
given control are described in Appendix A.
148 OS/VS Data Management Macro Instructions

PUTX

PUTX- Write a Record from an Existing Data Set (QISAM and QSAM)
The PUTX macro instruction causes the control program to return an updated record
to a data set (QISAM and QSAM) or to write a record from an input data set into an
output data set (QSAM only). There are two modes of the PUTX macro instruction.
The output mode (QSAM only) allows writing a record from an input data set on a
different output data set. The output data set may specify the spanning of
variable-length records, but the input data set must not contain spanned records, unless
the user specifies an area for logical' record interface by specifying BFTEK=A in the
DCB macro instruction or by issuing the BUILDRCD macro instruction.
The update mode returns an updated record to the "data set from which it was read.
The record must always have been brought into storage by a locate mode GET macro
instruction. The logical records are blocked by the control program, as specified in the
data control block, before they are placed in the output data set. The control program
uses the length specified in the DCBLRECL field as the length of the record currently
being stored. Control is not returned to the user's program until the control program
has processed the record.
The PUTX macro instruction can be used only in the output mode for SYSIN or
SYSOUT data sets.
The PUTX macro instruction is written as follows:

[symbol]

PUTX

deb address ~ input deb address]

deb address RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for a data
set opened for output.
input deb address -

RX-Type Address, (2-12), or (0)

The input deb address operand specifies the address of a data control block opened
for input. The PUTX macro instruction can be used for the following modes:
Output Mode: This mode is used with QSAM only. The input deb address
operand specifies the address of the data control block opened for input. If this
operand is omitted, the system assumes that register 0 contains the input dcb
address.
Update Mode: The input deb address operand is omitted for update mode.

PUTX Routine Exit
The error analysis (SYNAD) routine is given control if the operation is not completed
satisfactorily. The contents of the registers when the error analysis routine is given
control are described in Appendix A.

Macro Instruction Descriptions 149

READ-BDAM

READ -

Read a Block (BDAM)
The READ macro instruction causes a block to be retrieved from a data set and placed
in a designated area of storage. Control may be returned to the problem program
before the block is retrieved. The input operation must be tested for completion using
a CHECK or WAIT macro instruction. A data event control block, shown in
Appendix A, is constructed as part of the macro expansion.
The standard form of the READ macro instruction is written as follows (the list and
execute forms are shown following the descriptions of the standard form):
deeb name, type, de b address, {area address} ~ ength},

READ

[symbol]

'5'

{key address}, block address[,next address]

's •
decb name -

symbol

The decb name operand specifies the name assigned to the data event control block
created as part of the macro expansion.
type -

{DI [F)

[R)
[X)

{DK

}
[RU)

[F)

(R)

(X)

(RU)

}

The type operand is coded in one of the combinations shown above to specify the
type of read operation and the optional services performed by the system.

DI -

Specifies that the data and key, if any, are to be read from a specific
device address. The device address, which can be designated by any of
the three addressing methods, is supplied by the block address operand.

DK -

Specifies that the data (only) is to be read from a device address
identified by a specific key. The key to be used as a search argument
must be supplied in the area specified by the key address operand; the
search for the key starts at the device address supplied in the area
specified by the block address operand. The description of the DCB
macro instruction, LIMCT operand, contains a description of the search.

Requests that the system provide block position feedback into the area
specified by the block address operand. This character can be coded as a
suffix to DI or DK as shown above.

Requests exclusive control of the data block being read, and it requests
that the system provide block position feedback into the area specified by
the block address operand. The descriptions of the WRITE and RELEX
macro instructions contain a description of releasing a data block that is
under exclusive control. This character can be coded as a suffix to DI or
DK as shown above.

Macro Instruction Descriptions 151

R-

Requests that the system provide next address feedback into the area
specified by the next address operand. When R is coded, the feedback is
the relative track address of the next data record. This character can be
coded as a suffix to 01 or OK, OIF, DIX, DKF, or DKX as shown above,
but it can be coded only for use with variable-length spanned records.

RU -

Requests that the system provide next address feedback into the area
specified by the next address operand. When RU is coded, the feedback
is the relative track address of the next capacity record (RO) or data
record whichever occurs first. These characters can be coded as a suffix
to DI, DK, DIF, DIX, DKF, or DKX, but it can be coded only for use
with variable-length spanned records.

deb address -

A-Type Address or (2-12)

The deb address operand specifies the address of the data control block opened for
the data set to be read.
area address -

A-Type Address, (2-12), or'S'

The area address operand specifies the address of the area into which the data
block is to be placed. If'S' is coded instead of an address, dynamic buffering is
requested (dynamic buffering must 'also be specified in the MACRF operand of the
DCB macro instruction). When dynamic buffering is used, the system acquires a
buffer and places its address in the data eve,nt control block.
length -

symbol, decimal digit, absexp, (2-12), or'S'

The length operand specifies the number of data bytes to be read up to a maximum
of 32,760. If'S' is coded instead of a length, the number of bytes to be read is
taken from the data control block.
key address -

A-Type Address, (2-12), 'S', or 0

The key address operand specifies the address of the area for the key of the desired
data block. If the search operation is made using a key, the area must contain the
key. Otherwise, the key is read into the designated area. If the key is read and'S'
was coded for the area address, 'S' can also be coded for the key address; the key
and data are read sequentially into the buffer acquired by the system. If the key is
not to be read, specify 0 instead of an address or'S'.
block address -

A-Type Address or (2-12)

The block address operand specifies the address of the area containing the relative
block address, relative track address, or actual device address of the data block to
be· retrieved. The device address of the data block retrieved is placed in this area if
block position feedback is requested. The length of the area that contains the
address depends on whether the feedback option (OPTCD=F) has been specified in
the data control block and if the READ macro instruction requested feedback.
If OPTCD=F has been specified, feedback (if requested) is in the same form as

was originally presented by· the READ macro instruction, and the field can be either
three or eight bytes long depending on. the type of addressing.
If OPTCD=F has not been specified, feedback (if requested) is in the form of an
actual device address, and the field must be eight bytes long.

152 OS/VS Data Management Macro Instructions

READ-BDAM
next address -

A-Type Address or (2-12)

The next address operand specifies the address of the storage area where the system
places the relative address of the next record. The length operand must be specified
as'S'. When the next address operand is specified, an R or RU must be added to
the type operand (for example, DIR or DIRU). The R indicates that the next
address returned is the next data record. RU indicates that the next address
returned is for the next data or capacity record, whichever occurs first. The next
address operand can be coded only for use with variable-length spanned records.

Macro Instruction Descriptions 153

READ-BISAM

READ -

Read a Block of Records (BISAM)
The READ macro instruction causes an unblocked record, or a block containing a
specified logical record, to be retrieved from a data set. The block is placed in a
designated area of storage, and the address of the logical record is placed in the data
event control block. The data event control block is constructed as part of the macro
expansion and is described in Appendix A.
Control may be returned to the problem program before the block is retrieved. The
input operation must be tested for completion using a WAIT or CHECK macro
instructioft.
The standard form of the READ macro instruction is written as follows for BISAM
(the list and execute forms are shown following the descriptions of the standard form):

READ

[symboO

deeb name, type,deb address, area address! '
'$'

{length

,key address}

'$'

decb name -

symbol

The decb name operand specifies the name assigned to the data event control block
(DECB) created as part of the macro expansion.
type -

{K} {KU}

The type operand is coded as shown to specify the type of read operation.
K

Specifies normal retrieval.

KU Specifies that the record retrieved is to be updated and returned to the data

set; the system saves the device address to be returned.
When an ISAM data set is being updated with a READ KU macro instruction
and a WRITE K macro instruction, both the READ and WRITE macro
instructions must refer to the same data event control block. This update
operation can be performed by using a list-form instruction to create the list
(data event control block) and by using the execute form of the READ and
WRITE macro instructions to refer to the same list.
dcb address -

A-Type Address or (2-12)

The dcb address operand specifies the address of the data control block for the
opened data set to be read.
area address - A-Type Address, (2-12), or'S'
The area address operand specifies the address of the area into which the data
block is placed. The first sixteen bytes of this area are used by the system and do
not contain information from the data block. Dynamic buffering is specified by
coding '8' instead of an address; the address of the acquired storage area is returned
in the data event control block. Indexed sequential buffer and work area
requirements are described in OS/VS Data Management Services Guide.

Macro Instruction Descriptions 155

length -

symbol, decimal digit, absexp, (2-12), or '8'

The length operand specifies the number of bytes to be read up to a maximum of
32,760. If '8' is coded instead of a length, the number of bytes to be read is taken
from the count field of the record; for blocked records, '8' must be coded.
key address -

A-Type Address or (2-12)

The key address operand specifies the address of the area in the problem program
containing the key of a logical record in the block that is to be retrieved. When the
input operation is completed, the storage address of the logical record is placed in
the data event control block.

156 OS/VS Data Management Macro Instructions

READ -

BPAM and BSAM

Read a Block (BP AM and BSAM)
The READ macro instruction causes a block to be retrieved from a data set and placed
in a designated area of storage. Control may be returned to the problem program
before the block is retrieved. The input operation must be tested for completion using
a CHECK macro instruction. A data event control block, shown in Appendix A, is
constructed as part of the macro expansion.
If the OPEN macro instruction specifies UPDAT, both the READ and WRITE macro

instruction must refer to the same data event control block. Refer to the list form of
the READ or WRITE macro instruction for a description of how to construct a data
event control block; refer to the execute form of the READ or WRITE macro
instruction for a description of how to modify an existing data event control block.
The standard form of the READ macro instruction is written as follows (the list and
execute forms are shown following the descriptions of the standard form instructions):

READ

[symbol]

deeb name,type,deb address/area address,

length

'5'

t
~

symbol

deeb name -

The deeb name operand specifies the name assigned to the data event control block
(DECB) created as part of the macro expansion.
type -

{SF} {SB}

The type operand is coded as shown to specify the type of read operation.
SF

Specifies normal, sequential forward, retrieval.
SB

Specifies a read backward operation; this operand can be specified only
for magnetic tape with format-F or format-U records.
deb address -

A-Type Address or (2-12)

The deb address operand specifies the address of the data control block for the
opened data set to be read.
area address -

A-Type Address or (2-12)

The area address operand specifies the address of the problem program area into
which the record is placed. When a READ SB macro instruction is issued, the area
address must be the address of the last byte of the area into which the record is
read. If the data set contains keys, the key is read into the buffer followed by the
data.

Macro Instruction Descriptions 157

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

length -

symbol, decimal digit, absexp, (2-12), or'S'

The length operand specifies the number of data bytes to be read, to a maximum of
32,760. (If the data is translated from ASCII code to EBCDIC code, the maximum
number of bytes that can be read is 2048.) A number can be coded only for
format-U records. The number of bytes to be read is taken from the data control
block if'S' is coded instead of a number. (This operand is ignored for format-F or
format-V records.) For format-D records only, the length of the record just read is
automatically inserted into the DCBLRECL field if BUFOFF=(L) is not specified
in the data control block.

158 OS/VS Data Management Macro Instructions

READ-BSAM

READ -

Read a Block (Offset Read of Keyed BDAM Data Set Using BSAM)
The READ macro instruction causes a block to be retrieved from a data set and placed
in a designated area of storage. The data set is a BDAM data set and its record format
is unblocked variable-length spanned records. BFTEK=R must be specified in the
data control block. Control may be returned to the problem program before the block
is retrieved. The input operation must be tested for completion using a CHECK macro
instruction. A data event control block, shown in Appendix A, is constructed as part
of the macro expansion.
The standard form of the READ macro instruction is written as follows (the list and
execute forms are shown following the descriptions of the standard form):
(symbol]

deeb name -

READ

deeb name,type,deb address, area address

symbol

The deeb name operand specifies the name assigned to the data event control block
(DECB) created as part of the macro expansion.
SF
The type operand is coded as shown to specify the type of read operation.

type -

Specifies normal, sequential, forward operation.
deb address -

A-Type Address or (2-12)

The deb address operand specifies the address of the data control block for the
opened BDAM dataset to be read.
area address -

A-Type Address or (2-12)

The area address operand specifies the address of the area into which the record is
placed.
When a spanned BDAM data set is created with keys, only the first segment of a
record has a key; successive segments do not. When a spanned record is retrieved by
the READ macro instruction, the system places a segment in a designated area
addressed by the area address operand. The problem program must assemble all the
segments into a logical record. Since only the first segment has a key, the successive
segments are read into the designated area offset by key length to ensure that the
block-descriptor word and the segment-descriptor word are always in the same relative
position.

Macro Instruction Descriptions 159

READ -

List Form

List Form
The list form of the READ macro instruction is used to construct a data management
parameter list in the form of a data event control block (DECB). Refer to Appendix A
for a description of the various fields of the DECB for each access method.
The description of the standard form of the READ macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates the operands used for each access method, as well as the meaning of '8' when
coded for the area address, length, and key address operands. For each access method,
'8' can be coded only for those operands for which it can be coded in the standard
form of the macro instruction. The format description below indicates the optional and
required operands in the list form only.
The list form of the READ macro instruction is written as follows:
[symbol]

READ

decb name, type, [dcb address], ~rea addres~,
'5'
~ength}~ey addres~, [block address], [next address]
'5'
'5'

,MF=L

decb name

symbol

type

Code one of the types shown in the· standard form

deb address

A-Type Address or '8'

area address

A-Type Address or '8'

length

symbol, decimal digit, absexp, or '8'

key address

A-Type Address or '8'

block address

A-Type Address

next address

A-Type Address

MF=L

Coded as shown

The MF=L operand specifies that the READ macro instruction is used to create a
data event control block that can be referenced by an execute-form instruction.

Macro Instruction Descriptions 161

READ -

Execute Form

Execute Form
A remote data management parameter list (data event control block) is used in, and
can be modified by, the execute form of the READ macro instruction. The data event
control block can be generated by the list form of either a READ or WRITE macro
instruction.
The description of the standard form of the READ macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates the operands used for each access method, as well as the meaning of '8' when
coded for the area address, length, and key address operands. For each access method,
'S' can be coded only for those operands for which it can be coded in the standard
form of the macro instruction. The format description below indicates the optional and
required operands in the execute form only.
The execute form of the READ macro instruction is written as follows:
[symbol]

READ

decb address, type, [dcb address],[area address}
.
.ISI

~engt~ {key addresJ' [block address], [next address]
lSI

lSI

,MF=E

decb address

RX-Type Address or (2-12)

type

Code one of the types shown in the standard form

deb address

RX-Type Address or (2-12)

area address

RX-Type Address, (2-12), or'S'

length

symbol, decimal digit, absexp, (2-12), or'S'

key address

RX-Type Address, (2-12), or'S'

block address

RX-Type Address, or (2-12)

next address

RX-Type Address or (2-12)

MF=E

Coded as shown

The MF=E operand specifies that the execute form of the READ macro
instruction is used, and that an existing data event control block (specified in the
decb address operand) is used by the access method.

Macro Instruction Descriptions 163

RELEX

RELEX -

Release Exclusive Control (BDAM)
The RELEX macro instruction causes release of a data block fr.om exclusive control.
The block must have been requested in an earlier READ macro instruction which
specified either DIX and DKX. The RELEX macro instruction must be issued by the
same task that opened the data set.
Note: A WRITE macro instruction that specifies either DIX or DKX can also be used
to release exclusive control.
The RELEX macro instruction is written as follows:

[symbol]

D-

RELEX

DI dcb address I block address

Specifies direct access.

dcb address -

RX-Type Address, (2-12), or (1)

The dcb address operand specifies the address of the data control block for a
BDAM data set opened for processing. The dcb address operand must specify
the same data control block as designated in the associated READ macro
instruction.
block address -

RX-Type Address, (2-12), or (0)

The block address operand specifies the address of the area containing the
relative block address, relative track address, or actual device address of the data
block being released. The block address operand must specify the same area as
designated in the block address operand of the associated READ macro
instruction.

Meaning

Code
00

Operation completed successfully.

The specified data block was not in the exclusive control list.

The relative track address, relative block address, or actual device
address was not within the data set.

Macro Instruction Descriptions 165

RELSE

RELSE -

Release an Input Buffer (QISAM and QSAM Input)
The RELSE macro instruction causes immediate release of the current input buffer.
The next GET macro instruction retrieves the first record from the next input buffer.
For variable-length spanned records (QSAM), the input data set is spaced to the next
segment which starts a logical record in a subsequent block. Thus; one or more blocks
of data or records may be skipped. The RELSE macro instruction is ignored if a buffer
has just been completed or released, or if the records are unblocked.
The RELSE macro instruction is written as follows:

[ symbol]

deb address -

RELSE

deb address

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for the
opened input data set.

Macro Instruction Descriptions 167

SETL

SETL -

Set Lower Limit of Sequential Retrieval (QISAM Input)
The SETL macro instruction causes the control program to start processing the next
input request at the specified record or device address. Sequential retrieval of records
using the GET macro instruction continues from that point until the end of the data set
is encountered or a CLOSE or ESETL macro instruction is issued. An ESETL macro
instruction must be issued between SETL macro instructions that specify the same data
set.
The SETL macro instruction can specify that retrieval is to start at the beginning of the
data set, at a specific address on the device, at a specific record, or at the first record
of a specific class of records. In each case, retrieval starts with the first record that has
not been marked for deletion.
The SETL macro instruction is written as follows:
~

[symbol]

SEll

deb address,

K[H], lower limit address
KC, lower limit address
KD[H], lower limit address
KCD, lower limit address
I, lower limit address
ID, lower limit address
B
BD

deb address -

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block opened for
the indexed sequential data set being processed.
The following operands are coded as shown, and they specify the starting point and
type of retrieval.

K
Specifies that the next input operation begins at the record containing the key
specified in the lower-limit address operand.
KC
Specifies that the next input operation begins at the first record of the key class
specified in the lower-limit address operand. If the first record of the specified key
class has been deleted, retrieval begins at the next nondeleted record regardless of
key class.
H
This option, used with either K or KD, specifies that, if the key in the lower-limit
address operand is not in the data set, retrieval begins at the next higher key. The
character H cannot be coded with the key class operands (KC,and KCD).

Macro Instruction Descriptions 169

KD
Specifies that the next input operation begins at the record containing the key
specified in the lower-limit address operand, but only the data portion of the record
is retrieved. This operand is valid only for unblocked records.

KeD
Specifies that the next input operation begins at the first record of the key class
specified in the lower-limit address operand, but only the data portion of the record
is retrieved. This operand is valid only for unblocked records.
I

Specifies that the next input operation begins with the record at the actual device
address specified in the lower-limit address operand.
ID

Specifies that the next input operation begins with the record at the actual device
address specified in the lower-limit address operand, but only the data portion of the
record is retrieved. This operand is valid only for unblocked records.
B

Specifies that the next input operation begins with the first record in the data set.
BD

Specifies that the next input operation begins with the first record in the data set,
but only the data portion is retrieved. This operand is valid only for unblocked
records.
lower limit address -

RX-Type Address, (2-12), or (0)

The lower-limit address operand specifies the address of the area containing the key,
key class, or actual device address that designates the starting point for the next
input operation. If I or ID has been specified, this area must contain the actual
device address (in the form MBBCCHHR) of a prime data record; the other types
require that the key or key class be contained in this area.

SETL Exit
The error analysis (SYNAD) routine is given control if the operation could not be
completed successfully. The exceptional condition code and general registers are set as
shown in Appendix A. If the SETL macro instruction is not reissued, retrieval starts at
the beginning of the data set.

170 OS/VS Data Management Macro Instructions

SETPRT

SETPRT -

Load DCS and FCB Images (BSAM and QSAM)
The SETPRT macro instruction is used with printers that have a universal character set
(UCS) buffer or a forms control buffer (FCB). When a SETPRT macro instruction is
issued, UCS and FCB images are fetched from the image library and loaded from
storage into their respective buffers. The SETPRT macro instruction is also used to
block or unblock printer data checks.
IBM character sets and forms control images are included in the image library at system
generation; user-defined character sets and forms control images can be added to the
image library as described in OS / VS Data Management for System Programmers.
The FCB (EXLST) parameter of the DCB macro instruction.
When BSAM is being used, all write operations must be checked for completion before
the SETPRT macro instruction is issued; any incomplete write operations are purged.
Issuing the SETPRT macro instruction for a device other than an online UCS printer
results in a NOP instruction.
The standard form of the SETPRT macro instruction is written as follows (the list and
execute form are shown following the standard form):

[symbol]

SETPRT

deb address

"'"

,UCS= (ese IF[OlD]
,F[OLD] ,V[ERIFY] )
" V[ERIFY]

[, FeB= Omage-;d [, V[ERIFY]]) [,OPTCD= {~}]
,A[U GN]

,FeB= (;mage-;d [, VIl'RIFY]])
,OPTCD= ( {B } [, F[OLD]

deb address -

,OPTeD= ( {B }[, F[OLD]
U

,A[U GN]

J)]

,U[NFOLD]

A-Type Address or (2-12)

The deb address operand specifies the address of the data control block for the data
set to be printed; the data set must be opened for output before the SETPRT macro
instruction is issued.
UCS= A character code with options
The UCS operand specifies that the UCS buffer is to be loaded from the image
library. When the UCS operand is specified, the FCB and OPTCD operands can
also be specified.
esc (character set code)

The esc operand specifie~ the character set to be loaded. A character set is
identified by a 1-4 character code.

Macro Instruction Descriptions 171

Codes for standard IBM character sets are as follows:
1403 Printer: AN, UN, PCAN, PCHN, PN, QN, QNC, RN, SN, TN, XN,
and YN
3211 Printer: All, H11, G11, P11, and T11
For descriptions of the standard IBM character sets, refer to OS/VS1 System
Generation Reference or OS/VS2 System Generation Reference; codes for
user-designed character sets are defined by the installation.
F or FOLD
Specifies that the character set image is to be loaded in the fold mode. The
fold mode is most often used when the EBCDIC code for lowercase alphabetic
characters is printed as uppercase characters by a print train with lowercase
type.
V or VERIFY

Requests that the character set image be displayed on the printer for visual
verification.
FCB= A character code with options
The FCB operand specifies that the forms control buffer (FCB) is to be loaded
from the image library. When the FCB operand is specified, the OPTCD operand
can also be specified.
image id
The image id operand specifies the forms control image to be loaded. A forms
control image is identified by a 1-4 character code. IBM-supplied images are
identified by image id value of STDI and STD2; user-designed forms control
images are defined by the installation.
V or VERIFY

Requests that the forms control image be displayed on the printer for visual
verification. This operand allows forms alignment using the WTOR macro
instruction.
A or ALIGN

Allows forms alignment using the WTOR macro instruction.
OPTCD= A printer option code
The OPTCD operand specifies whether UCS printer data checks are blocked or
unblocked and if the printer is to operate in fold or normal mode.
B

Specifies that UCS printer data checks are blocked; this option updates the
DCBOPTCD field of the data control block.

u
Specifies that UCS printer data checks are unblocked; this option updates the
DCBOPTCD field of the data control block.
F or FOLD
Specifies that printing is in fold mode.
U or UNFOLD
Specifies that printing is in normal mode; this operand causes fold mode to
revert to normal mode.

1720S/VS Data Management Macro Instructions

SETPRT

Completion Codes
After the SETPRT macro instruction is executed, a return code is placed in register 15,
and control is returned to the instruction following the SETPRT macro instruction.
Bits 16-23 indicate the result of the attempt to load the forms control buffer (FCB).
Bits 24-31 indicate the result of the attempt to load a universal-character-set (UCS)
buffer. For completion codes 18, 1C, 20, and 24, bits 24-31 apply to both FCB and
UCS loading. The codes in the following table are in hexadecimal.

Bits 16-23
FCB Code

Bits 24-31
UCS Code

Successful completion.

The operator canceled the load because either the image
could not be found in the image library or, in the case
of the UCS image, the requested chain or train was not
available.

A permanent I/O error was detected when the BLDL
macro instruction was issued to locate the image in the
image library.

A permanent I/O error persisted after two attempts
were made to load the FCB/UCS buffer.

A pemianent I/O error was detected when an attempt
was made to display the character set image or forms
control image on the printer for visual verification.

The operator canceled the load because the wrong
image was displayed for visual verification.

Bits 24-31
FCB/UCS
Code
18

Meaning

No operation was performed for one of the following
reasons:
• The data control block was not open.
• The data control block was not valid for a
sequential data set .
• The SETPRT parameter list was not valid.
• The output device was not a UCS printer.
No operation was performed because an uncorrectable
error occurred in a previously initiated output operation.
The error analysis (SYNAD) routine is entered when
the next PUT or CHECK macro instruction is issued.
No operation was performed because an uncorrectable
error occurred when the Block Data Check or Reset
Block Data Check command was issued by SETPRT.

Not enough space has been provided for the
IMAGELIB control blocks. Increase the amount of
space allocated for the job step.

SYS I.1MAGELIB cannot be opened to load the
specified UCS/FCB image.
Macro Instruction Descriptions 173

SETPRT -

List Form

List Form
The list form of the SETPRT macro instruction is used to construct a data management
parameter list.
The description of the standard form of the SETPRT macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates which operands are totally optional and those required in at least one of the
pair of list and execute forms. The format description below indicates the optional and
required operands for the list form only.
The list form of the SETPRT macro instruction is written as follows:
~ymbol]

SETPRT

deb address

.....

, UCS= (ese

[F[OLD]
, F[OLD] , V[ERIFY]~ )
" V[ERIFY]

[.FCB= (image-id [V[ERIFY]J) [.OPTCD= {B}J
,A[UGN]

.FCB=(image-id [V[ERIFY~]) [.OPTCD= ({B} [FrOLD]
,A[U GN]

.OPTCD= ({B}fF[OLD]

~)]

, U[NFOLD]

])

U ,U[NFOLD]

,MF=L

deb address -

A-Type Address

UCS= A character code with options
It is coded as described in the standard form of the macro instruction.

FCB= A character code with options
It is coded as described in the standard form of the macro instruction.

OPTCD= A printer option code
It is coded as described in the standard form of the macro instruction.
MF=L

The MF=L operand specifies that the list form of the macro instruction is used to
create a parameter list that can be referenced by an execute form of the SETPRT
macro instruction.

Macro Instruction Descriptions 175

SETPRT -

Execute Form

Execute Form
A remote data management parameter list is referred to, and can be modified by, the
execute form of the SETPRT macro instruction.
The description of the standard form of the SETPRT macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates which operands are totally optional and those required in at least one of the
pair of list and execute forms. The format description below indicates the optional and
required operands for the execute form only.
The execute form of the SETPRT macro instruction is written as follows:

[symbol]

r--

.....

deb address

SETPRT

, UCS= (ese [F[OLD]
, F[OLD] , V[ERIFY] )]
" V[ERI FY]
[, FCB~ (image-id [V[ERIFY]J)

,A[LI GN]

,FCB~ (image-id

[,OPTCD~ ( {B }

[, VLERIFY]J)

,A[LlGN]

,OPTCD~ ( {B}

'"--

F[OLD]

{~}] >

F[OLD]

])

,U[NFOLD]

])

, U[NFOLD]

data management list address

,MF- (E,

[,OPTCD=

)

(1 )

deb address -

RX-Type Address or (2-12)

UCS= A character code with options
It is coded as shown in the standard form of the macro instruction.

FCB = A character code with options
It is coded as shown in the standard form of the macro instruction.

OPTCD= A printer option code
It is coded as shown in the standard form of the macro instruction.
MF=(E,

{data management list address

})

{

}

(1)

This operand specifies that the execute form of the SETPRT macro instruction is
used, and an existing data management parameter list is used.
E-

Coded as shown

data management list address -

RX-Type Address, (2-12), or (1)

Macro Instruction Descriptions 177

STOW

STOW -

Update Partitioned Data Set Directory (BPAM)
The STOW macro instruction causes the system to update a partitioned data set
directory by adding, changing, replacing, or deleting an entry in the directory. Only
one entry can be updated at a time using the STOW macro instruction. If the entry to
be added or replaced is a member name, the system writes an end-of-data indication
following the member. All input/output operations using the same data control block
must have previously been tested for completion.
The STOW macro instruction is written as follows:

STOW

[symbol]

deb address -

dcb address, list address [,directory action]

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for the
opened partitioned data set. The STOW macro instruction can be used only when
the data set is opened for OUTPUT, UPDAT or OUTIN (BSAM).
list address -

RX-Type Address, (2-12), or (0)

The list address operand specifies the address of the area containing the information
required by the system to maintain the partitioned data set directory. The size and
format of the area depend on the directory action requested as follows:
Adding or Replacing a Directory Entry: The list address operand must specify an
area at least 12 bytes long and beginning on a halfword boundary. The following
illustration shows the format of the area:
list Address

Le~j
Bytes

NAME
8

TTR
3

USER DATA

NAME
Specifies the member name or alias being added or replaced. The name
must begin in the first byte of the field and be padded on the right with
blanks, if necessary, to complete the 8-byte field.

IT
Specifies the relative track number on which the beginning of the data set is
located.
R

Specifies the relative block (record) number on the track identified by IT.

Macro Instruction Descriptions 179

Note: The TTR field shown above must be supplied by the problem program if an
alias (alias bit is 1) is being added or replaced. The system supplies the TTR field
when a member name is being added or replaced.
C

Specifies the type of entry (member or alias)· for the name, the number of
note list fields (TTRNs), and the length in halfwords, of the user data field.
The following describes the meaning of the eight bits.
Indicates a member name.
Bit 0=0
Indicates an alias.
Bit 0= 1
Bits 1 and 2
Indicate the number of TTRN fields (maximum of
three) in the user data field.
Bits 3-7
Indicate the total number of halfwords in the user data
field.
Deleting a Directory Entry: The list address operand must specify an 8-byte area
that contains the member name or alias to be deleted. The name must begin in the
first byte of the area and be padded on the right with blanks, if necessary, to
complete the eight bytes.
Changing the Name of a Member: The list address operand must specify the address
of a 16-byte area; the first 8 bytes contain the old member name or alias, and the
second 8 bytes contain the new member name or alias. Both names must begin in
the first byte of their 8-byte area and be padded on the right with blanks, if
necessary, to complete the 8-byte field.
directory action -

(A)
(C)
(D)
(R)

The directory action operand is coded as shown to specify the type of d:rectory
action. If the operand is not coded, A (add an entry) is assumed.
A

Specifies that an entry is to be added to the directory.
C

Specifies that the name of an existing member or alias is to be changed.
D

Specifies that an existing directory entry is to be deleted.
R

Specifies that an existing directory entry is to be replaced by a new directory
entry. If R is coded but the old entry is not found, the new entry is added to
the directory and a completion code of X'08' is returned in register 15.

180 OS/VS Data Management Macro Instructions

STOW

Completion Codes
When the system returns control to the problem program, register 15 contains one of
the following return codes in the low-order byte; the three high-order bytes of register
15 are set to zero.

Directory Action

Code
(Hexadecimal)

The update of the directory was completed successfully

The directory
already contains
the specified name.

The directory already contains
the specified new name.
The specified name could
not be found.

The specified old name could
not be found.

No space left in the directory.
The entry could not be added
or replaced.

A permanent input or output error was detected when attempting to update the
directory. Control is not given to the error analysis (SYNAD) routine.

The specified data control block is not open or is opened incorrectly.

Conditional GETMAIN with STOW macro instruction was unsuccessful.

Macro Instruction Descriptions 181

SYNADAF

SYNADAF - Perform SYNAD Analysis Function (BDAM, BISAM, BPAM,
BSAM, QISAM, and QSAM)
The SYNADAF macro instruction is used in an error analysis routine to analyze
permanent input/output errors. The routine can be a SYNAD routine specified in a
data control block for BDAM, BISAM, BP AM, BSAM, QISAM, QSAM, or a routine
that is entered directly from a program that uses the EXCP macro instruction. (The
EXCP macro instruction is described in OS/VS Data Management for System
Programmers .)
The SYNADAF macro instruction uses register 1 to return the address of a buffer
containing a message. The message describes the error, and can be printed by a
subsequent PUT or WRITE macro instruction. The message consists of EBCDIC
information and is in the form of a variable-length record. The format of the message
is shown following the descriptions of the SYNADAF operands.
The system does not use the save area whose address is in register 13. Instead, it
provides a save area for its own use, and then makes this area available to the error
analysis routine. The system returns the address of the new save area in register 13
and in the appropriate location (word 3) of the previous save area; it also stores the
address of the previous save area in the appropriate location (word 2) of the new save
area.
The SYNADAF macro instruction passes parameters to the system in registers 0 and 1.
When used in a SYNAD routine, it passes the parameters that are in these registers
when the routine is entered, and it should therefore be coded at the entry point of the
routine. (Refer to Appendix A, Figures 2 and 3.) To save these parameters for use by
the SYNAD routine, the system stores them in a parameter save area that follows the
message buffer as shown in the message buffer format. The system does not alter the
return address in register 14 or the entry point address in register 15.
When a SYNADAF macro instruction is used, a SYNADRLS macro instruction must
be used to release the message buffer and save areas, and to restore the original
contents of register 13.
The SYNADAF macro instruction is written as follows:

[symbol]

SYNADAF

rSMETH=BDAM!
ACSMETH=BPAM
.
. 1
ACSMET H=BSA M [, PA RM 1=pa,m 'eg ",ee]
[, PA RM2~pa'm 'eg "'e,
ACSMETH=QSAM
ACSMETH=BISAM
ACSMETH=EXCP [, PARM 1=iob address]
\ ACSMETH=QISAM[,PARM1=dcb address] [,PARM2=parm register]

ACSMETH=BDAM, BPAM, BSAM, QSAM, BISAM, EXCP, or QISAM
The ACSMETH operand specifies the access method used to perform the
input/ output operation for which error analysis is performed.

Macro Instruction Descriptions 183

PARMl= parm register, iob address, or deb address -

(2-12) or (1)

The PARMI operand specifies the address of information that is dependent on the
access method being used. For BDAM, BISAM, BPAM, BSAM, or QSAM, the
operand specifies a register that contains the information that was in register 1 on
entry to the SYNAD routine. For QISAM, the operand specifies the address of the
data control block; for EXCP, it specifies the address of the input/output block. If
the operand is omitted, PARMI =(1) is assumed.

PARM2= parm register- (2-12), (0), or RX-Type Address (only if
ACSMETH=QISAM)

The PARM2 operand specifies the address of additional information that is
dependent on the access method being used. For BDAM, BISAM, BPAM, BSAM,
QISAM, and QSAM, the operand specifies a register that contains the information
that was in register 0 on entry to the SYNAD routine. For EXCP, the operand is
meaningless and should be omitted. If the operand is omitted, except in the case of
EXCP, PARM2=(O) is assumed.

Completion Codes
When the system returns control to the problem program, the low-order byte of
register 0 contains one of the following return codes; the three high-order bytes of
register 0 are set to zero.
Hexadecimal Code

Meaning

Successful completion. Bytes 8-13 of the message buffer
contain blanks.

Successful completion. Bytes 8-13 of the message buffer
contain binary data.

Unsuccessful completion. The message can be printed, but
some information is missing in bytes 50-127 and is
represented by asterisks. Bytes 8-13 contain either blanks or
binary data.

184 OS/VS Data Management Macro Instructions

SYNADAF

Message Buller Format
The following illustration shows the format of the message buffer; the address of the
buffer is returned in register 1.
8
Messalile Buffer
Byte 0

l b b

Input:

II I

b b

Doubleword
Boundary
LL = 128; II = 124; bb = 000

12
No. of
Bytes
Read

Input
Buffer
Address

1'4

8
Output:

114
(Blanks)

Jobname

Device
Type

Stepname

Error Description

DDname

107

91
Operation
Attempted

I, ISO
84

(Blanks)

107
Access
Method

(Asterisks)

Unit Record:

Relative Block
Number (decimal)

Magnetic Tape:

Access
Method

Parameter Save Area
128
132
Parameter
Parameter
Register 0
Register 1
(PARM2)
(PARM 1)

Actual Track Address and Block Number
(BBCCHHR in hexadecimal format)

(End of Buffer -Beginning of
Parameter Save Area)

(Blanks)
128

122

107
Direct Access:

128

120

115

107

Access
Method

136

Notes
The device type field (bytes 72-73) contains UR for a unit record device, TA for a
magnetic tape device, or DA for a direct-access device.
•

If a message field (bytes 91-105) is not applicable to the type of error that
occurred, it contains N/ A or NOT APPLICABLE.
If no data was transmitted, or if the access method is QISAM, bytes 8-13 contain
blanks.

•

If the access method is BISAM, bytes 68-70, 84-89, and 107-120 contain
asterisks.

•

If the access method is BDAM, and if the error was an invalid request, bytes
107-120 contain EBCDIC zeros.

Macro Instruction Descriptions 185

SYNADRLS

SYNADRLS - Release SYNADAF Buffer and Save Areas (BDAM, BISAM,
BPAM, BSAM, QISAM, and QSAM)
The SYNADRLS macro instruction releases the message buffer, parameter save area,
and register save area provided by a SYNADAF macro instruction. It must be used to
perform this function whenever a SYNADAF macro instruction is used.
When the SYNADRLS macro instruction is issued, register 13 must contain the address
of the register save area provided by the SYNADAF macro instruction. The control
program loads register 13 with the address of the previous save area, and sets word 3
of that save area to zero. Thus, when control is returned, the save area pointers are
the same as before the SYNADAF macro instruction was issued.
The SYNADRLS macro instruction is written as follows:

[symboO

SYNADRlS

When the system returns control to the problem program, the low-order byte of
register 0 contains one of the following return codes; the three high-order bytes of
register 0 are set to zero.
Hexadecimal Code

Meaning

Successful completion.

Unsuccessful completion. The buffer and save areas were not
released; the contents of register 13 remain unchanged.
Register 13 does not point to the save area provided by the
SYNADAF macro instruction, or this save area is not properly
chained to the previous save area.

Macro Instruction Descriptions 187

TRUNC

TRUNC - Truncate an Output Buffer (QSAM Output Variable-Length Blocked Records)

Fixed- or

The TRUNC macro instruction causes the current output buffer to be regarded as full.
The next PUT or PUTX macro instruction specifying the same data control block uses
the next buffer to hold the logical record.
When a variable-length spanned record is being truncated and logical record interface
is specified (that is, if BFTEK=A is specified in the DCB macro instruction, or if a
BUILDRCD macro instruction is issued), the system segments and writes the record
before truncating the buffer. Therefore, the block being truncated is the one that
contains the last segment of the spanned record.
The TRUNC macro instruction is ignored if it is used for unblocked records; if it is
used when a buffer is full, or if it is used without an intervening PUT or PUTX macro
instruction.
The TRUNC macro instruction is written as follows:

[symbolJ

deb address -

TRUNC

I deb address

RX-Type Address, (2-12), or (1)

The deb address operand specifies the address of the data control block for the
sequential data set opened for output. The record format in the data control block
must not indicate standard blocked records (RECFM=FBS).

Macro Instruction Descriptions 189

WRITE-BDAM

WRITE -

Write a Block (BDAM)
The WRITE macro instruction causes the system to add or replace a block in an
existing direct data set. (This version of the WRITE macro instruction cannot be used
to create a direct data set because no capacity record facilities are provided.) Control
may be returned before the block is written. The output operation must be tested for
completion using a CHECK or WAIT macro instruction. A data event control block,
shown in Appendix A is constructed as part of the macro expansion.
The standard form of the WRITE macro instruction is written as follows (the list and
execute forms are shown following the descriptions of the standard form):

WRITE

[symbol]

I I'I
en9 t h

'5'

decb name -

deeb name, type, deb address, {area address},

'5'

key add ress ,b lock address

'5'
0

symbol

The decb name operand specifies the name assigned to the data event control block
created as part of the macro expansion.
type -{DA

(F)}

{DI

(F)}
(X]

{DK

(F)}
(X]

The type operand is coded in one of the combinations shown to specify the type of
write operation and optional services performed by the system.
DA

Specifies that a new data block is to be added to the data set in the first
available space; the search for available space starts at the device address
indicated in the area specified in the block address operand. The description of
the DCB macro instruction, LIMCT operand, contains a description of the
search.

DI
Specifies that a data block and key, if any, are to be written at the device
address indicated in the area specified in the block address operand. Any
attempt to write a capacity record (RO) is an invalid request when relative
track addressing or actual device addressing are used, but when relative block
addressing is used, relative block 0 is the first data block in the data set.

Macro Instruction Descriptions 191

Specifies that a data block (only) is to be written using the key in the area
specified by the key address operand as a search argument; the search for the
block starts at the device address indicated in the area specified in the block
address operand. The description of the DCB macro instruction, LIMCT
operand, contains a description of the search.
F

Requests that the system provide block position feedback into the area
specified in the block address operand. This character can be coded as a suffix
to DA, OJ, or OK as shown above.

x
Requests that the system release the exclusive control requested by a previous
READ macro instruction and provide block position feedback into the area
specified in the block address operand. This character can be coded as a suffix
to OJ or OK as shown above.
dcb address -

A-Type Address or (2-12)

The dcb address operand specifies the address of the data control block for the
opened BDAM data set.
area address -

A-Type Address, (2-12), or'S'

The area address operand specifies the address of the area that contains the data
block to be written. 'S' can be coded instead of an area address only if the data
block (or key and data) are contained in a buffer provided by dynamic buffering;
that is, 'S' was coded in the area address operand of the associated READ macro
instruction. If'S' is coded in the WRITE macro instruction, the area address from
the READ macro instruction data event control block must be moved into the
WRITE macro instruction data event control block; the buffer area acquired by
dynamic buffering is released after the WRITE macro instruction is executed. See
Appendix A for a description of the data event control block.
length -

symbol, decimal digit, absexp, (2-12) or'S'

The length operand specifies the number of data bytes to be written up to a
maximum of 32,760. If'S' is coded, it specifies that the system uses the value in
the blocksize (DCBBLKSI) field as the length. When undefined-length records are
used, if the WRITE macro instruction is for update and the length specified differs
from the original block, the new block will be truncated or padded with binary
zeros accordingly. The problem program can check for this situation in the SYNAD
routine.
If the length operand is omitted for format-U records, no error indication is given

when the program is assembled, but the problem program must insert a length into
the data event control block before the WRITE macro instruction is executed.
key address -

A-Type Address, (2-12), 'S', or 0

The key address operand specifies the address of the area that contains the key to
be used. 'S' is specified instead of an address only if the key is contained in an area
acquired by dynamic buffering. If the key is not written or used as a search
argument, zero is specified instead of a key address.

192 OS/VS Data Management Macro Instructions

WRITE-BDAM
block address -

A-Type Address or (2-12)

The block address operand specifies the address of the area that contains the
relative block address, relative track address, or actual device address used in the
output operation. The length of the area depends on the type of addressing used
and if the feedback option (OPTCD=F) is specified in the data control block.
If OPTCD=F has been specified, feedback, when requested, is in the same form as

was originally presented by the WRITE macro instruction; the area is either three or
eight bytes long depending on the type of addressing.
If OPTCD=F has not been specified, feedback, when requested, is in the form of

an 8-byte actual device address (MBBCCHHR); the area must be eight bytes.

Macro Instruction Descriptions 193

WRITE -

BISAM

Write a Logical Record or Block of Records (BISAM)
The WRITE macro instruction causes the system to add or replace a record or replace
an updated block in an existing indexed sequential data set. Control may be returned
to the problem program before the block or record is written. The output operation
must be tested for completion using aWAIT or CHECK macro instruction. A data
event control block, shown in Appendix A, is constructed as part of the macro
expansion.
The standard form of the WRITE macro instruction is written as follows (the list and
execute forms are shown following the descriptions of the standard form):

WRITE

[symbol]

deeb name type, deb address {area addreSS}
,
"5"
{,ength}
'5'
,key address

deeb name -

symbol

The deeb name operand specifies the name assigned to the data event control block
created as part of the macro expansion.
type -

{K} {KN}

The type operand is coded as shown to specify the type of write operation.
K

Specifies that either an updated unblocked record or a block containing an
updated record is to be written. If the record has been read using a READ
KU macro instruction, the data event control block for the READ macro
instruction must be used as the data event control block for the WRITE macro
instruction, using the execute form of the WRITE macro instruction.

KN Specifies that a new record is to be written, or a variable-length record is to be
rewritten with a different length. All records or blocks of records read using
READ KU macro instructions for the same data control block must be written
back before a new record can be added except when the READ KU and
WRITE KN refer to the same DECB.
deb address -

A-Type Address or (2-12)

The deb address operand specifies the address of the data control block for the
opened existing indexed sequential data set. If a block is written, the data control
block address must be the same as the deb address operand in the corresponding
READ macro instruction.
area address -

A-Type Address, (2-12), or'S'

The area address operand specifies the address of the area containing the logical
record or block of records to be written. The first sixteen bytes of this area are
used by the system and should not contain your data. When new records are
written (or when variable-length records are rewritten with a different length), the
Macro Instruction Descriptions 195

area address of the new record must always be supplied by the problem program.
This area may be altered by the system. '8' may be coded instead of an address
only if the block of records is contained in an area provided by dynamic buffering;
that is, '8' was coded for the area address operand in the associated READ KU
macro instruction. This area is released after execution of a WRITE macro
instruction using the same DECB. The area can also be released by a FREEDBUF
macro instruction.

The following illustration shows the format of the area:
Area_
Address
Control
Program
Use

Logical Record (WRITE KN) or Block of Records (WRITE K)

Indexed sequential buffer and work area requirements are discussed in OS / VS Data
Management Services Guide.
length - ,symbol, decimal digit, absexp, (2-12) or'S'

The length operand specifies the number of data bytes to be written, up to a
maximum of 32,760. Specify'S' unless a variable-length record will be rewritten
with a different length.
key address -

A-Type Address or (2-12)

The key address operand specifies the address of the area containing the key of the
new or updated record. For blocked records, this is not necessarily the high key in
the block. For unblocked records, this field should not overlap with the work area
specified in the MSWA parameter of the DCB macro instruction.
Note: When new records are written, the key area may be altered by the system.

196 OS/VS Data Management Macro Instructions

WRITE -

BPAM and BSAM

Write a Block (BPAM and BSAM)
The WRITE macro instruction causes the system to add or replace a block in a
sequential or partitioned data set being created or updated. Control may be returned
to the problem program before the block is written. The output operation must be
tested for completion using the CHECK macro instruction. A data event control block,
shown in Appendix A, is constructed as part of the macro expansion.
If translation from EBCDIC code to ASCII code is requested, issuing mUltiple WRITE

macro instructions for the same record causes an error because the first WRITE macro
instruction issued causes the output data in the output buffer to be translated into
ASCII code.
If the OPEN macro instruction specifies UPDAT, both the READ and WRITE macro

instructions must refer to the same data event control block. Refer to the list form of
the READ or WRITE macro instruction for a description of how to construct a data
event control block; refer to the execute form of the READ or WRITE macro
instruction for a description of modifying an existing data event control block.
The standard form of the WRITE macro instruction is written as follows (the list and
execute forms are shown following the descriptions of the standard form):

[symbol]

deeb name -

WRITE

deeb name/type,deb address, area address [, Ie. ngthJ
, '5'

symbol

The deeb name operand specifies the name assigned to the data event control block
created as part of the macro expansion.
type -

This operand is coded as shown to specify the type of Write operation.
SF Specifies normal, sequential forward operation.
deb address -

A-Type Address, or (2-12)

The deb address operand specifies the address of the data control block for the
opened data set being created or processed. If the data set is being updated, the
data control block address must be the same as the deb address operand in the
corresponding READ macro instruction.
area address -

A-Type Address or (2-12)

The area address operand specifies the address of the area that contains the data
block to be written; if a key is written, the key must precede the data in the same
area.

Macro Instruction Descriptions 197

length -

symbol, decimal digit, absexp, (2-12) or'S'

The length operand specifies the number of bytes to be written; this operand is
specified for only undefined-length records (RECFM= U) or ASCII records
(RECFM=D) when the DCB BUFOFF operand is zero. If the data is to be
translated from EBCDIC code, to ASCII code the maximum length is 2048;
otherwise, the maximum length is 32,760 bytes. 'S' can be coded to indicate that
the value specified in the blocksize (DCBBLKSI) field of the data control block is
used as the length to be written. The length operand should be omitted for all
record formats except format-U and format-D (when BUFOFF=O).
If the length operand is omitted for format-U or format-D (with BUFOFF=O)
records, no error indication is given when the program is assembled, but the
problem program must insert a length into the data event control block before the
data set is opened.

198 OS/VS Data Management Macro Instructions

WRITE-BSAM

WRITE -

Write a Block (Create a BDAM Data Set with BSAM)
The WRITE macro instruction causes the system to add a block to the direct data set
being created. For fixed-length blocks, the system writes the capacity record
automatically when the current track is filled; for variable- and unspecified-length
blocks, a WRITE macro instruction must be issued for the capacity record. Control
may be returned before the block is written. The output operation must be tested for
completion using a CHECK macro instruction. A data event control block, shown in
Appendix A, is constructed as part of the macro expansion.
The standard form of the WRITE macro instruction is written as follows (the list and
execute forms are shown following the descriptions of the standard form):

[symbol]

WRITE

decb name -

symbol

decb name, type, deb address,area addreSs~lengt~ ~next addres~
, 'S'

The decb name operand specifies the name assigned to the data event control block
created as part of the macro expansion.
type -

{SF }
{SFR}
{SD }
{SZ

}

The type operand is coded as shown, to specify the type of write operation
performed by the system.
SF

Specifies that a new data block is to be written in the data set.
SFR

Specifies that a new variable-length spanned record is to be written in the data
set, and next address feedback is requested. This operand can be specified
only for variable-length spanned records (BFTEK=R and RECFM= VS are
specified in the data set control block).
SD
Specifies that a dummy data block is to be written in the data set; dummy data
blocks can be written only when fixed-length records with keys are used.
SZ

Specifies that a capacity record (RO) is to be written in the data set; capacity
records can be written only when variable-length or undefined-length records
are used.

Macro Instruction Descriptions 199

deb address -

A-Type Address or (2-12)

The deb address operand specifies the address of the data control block opened for
the data set being created. DSORG=PS (or PSU) and MACRF=WL must be
specified in the DCB macro instruction to create a BDAM data set.
area address -

A-Type Address or (2-12)

The area address operand specifies the address of the area that contains the data
block to be added to the data set. If keys are used, the key must precede the data
in the same area. For writing capacity records (SZ), the area address is ignored and
can be omitted (the system supplies the information for the capacity record). For
writing dummy data blocks (SO), the area need be only large enough to hold the
key plus one data byte. The system constructs a dummy key with the first byte set
to all one bits (hexadecimal FF) and adds the block number in the first byte
following the key. When a dummy block is written, a complete block is written
from the area immediately following the area address; therefore, the area address
plus the value specified in the BLKSIZE operand must be within the area allocated
to the program writing the dummy blocks.
length -

symbol, decimal digit, absexp, (2-12), or'S'

The length operand is used only when undefined-length (RECFM= U) blocks are
being written. The operand specifies the length of the block, in bytes, up to a
maximum of 32,760. If'S' is coded, it specifies that the system is to use the length
in the blocksize (DCBBLKSI) field of the data control block as the length of the
block to be written~
If the length operand is omitted for format-U records, no error indication is given
when the program is assembled, but the problem program must insert a length into
the data event control block before the data set is opened.
next address -

A-Type Address or (2-12)

The next address operand specifies the address of the area where the system places
the relative track address of the next record to be written. Next address feedback
can be requested only when variable-length spanned records are used.
Note: When variable-length spanned records are used (RECFM= VS and BFTEK=R
are specified in the data control block), the system writes capacity records (RO)
automatically in the following cases:
•

When a record spans a track.

•

When the record cannot be written completely on the current volume. In this case,
all capacity records of remaining tracks on the current volume are written; tracks
not written for this reason are still counted in the search limit specified in the
LIMCT operand of the data control block.

•

When the record written is the last record on the track, the remaining space on the
track cannot hold more than ei~ht bytes of data.

200 OS/VS Data Management Macro Instructions

WRITE-BSAM

Meaning
Fixed-Length

Variable- or Unspecified-Length

(SF or SD)

(SF or SFR)

(SZ)

Block was written. (If the previous return code
was 08, a block is written only if the nn
statement specifies secondary space allocation
and sufficient space is available.

Block was written,
followed by a capacity
record.

Block was written,
followed by capacity
record. The next block
requires secondary
space allocation.

Block will not be written; issue a CHECK macro instruction for the previous
WRITE macro instruction, then reissue the WRITE macro instruction.

Capacity record was
written; another track
is available.

Block was not written;
write a capacity record
(SZ) to complete
the current track, then
reissue.
Capacity record was
written. The next
block requires secondary
space allocation. This
code is not issued if
the WRITE SZ is the
only WRITE macro
instruction issued on
a one-track secondary
extent.

Macro Instruction Descriptions 201

WRITE -

List Form

List Form
The list form of the WRITE macro instruction is used to construct a data management
parameter list in the form of a data event control block (DECB). Refer to Appendix A
for a description of the various fields in the DECB for each access method.
The description of the standard form of the WRITE macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates the operands used for each access method as well as the meaning of '8' when
coded for the area address, length, and key address operands. For each access
method, '8' can be coded only for those operands for which it can be coded in the
standard form of the macro instruction. The format description below indicates the
optional and required operands in the list form only.
The list form of the WRITE macro instruction is written as follows:

WRITE

[symbol]

decb name, type, [dcb address],~rea addres~,

'5'
~engt~ ,[key addres~, [block address], [next address]
'S~

·s·

,MF=L

decb name

symbol

type

Code one of the types shown in the standard form

dcb address -

A-Type Address

area address -

A-Type Address or'S'

length

symbol, decimal digit, absexp, or '8'

key address -

A-Type Address or '8'

block address -

A-Type Address

next address -

A-Type Address

Coded as shown

MF=L

The MF=L operand specifies that the WRITE macro instruction is used to create a
data event control block that wiU be referenced by an execute-form instruction.

Macro Instruction Descriptions 203

WRITE -

Execute Form

Execute Form
A remote data management parameter list (data event control block) is used in, and
can be modified by, the execute form of the WRITE macro instruction. The data event
control block can be generated by the list form of either a READ or WRITE macro
instruction.
The description of the standard form of the WRITE macro instruction provides the
explanation of the function of each operand. The description of the standard form also
indicates the operands used for each access method, as well as the meaning of '8' when
coded for the area address, length, and key address operands. For each access
method, '8' can be coded only for those operands for which it can be coded in the
standard form of the macro instruction. The format description below indicates the
optional and required operands in the execute form only.
The execute form of the WRITE macro instruction is written as follows:
WRITE

[symbol]

decb address, type, [dcb address], ~rea addresJ'
'$'

~engthJ' [key addres~ , [block address], [next address]
'5'
'5'

,MF=E

decb address -

RX-Type Address or (2-12)

type

Code one of the types shown in the standard form

deb address -

RX-Type Address or (2-12)

area address -

RX-Type Address, (2-12), or '8'

length

key address -

symbol, decimal digit, absexp, (2-12), or '8'
RX-Type Address, (2-12), or '8'

block address- RX-Type Address or (2-12)
next address -

MF=E

RX-Type Address or (2-12)
Coded as shown

The MF=E operand specifies that the execute form of the WRITE macro
instruction is used, and an existing data event control block (specified in the decb
address operand) is to be used by the access method.

Macro Instruction Descriptions 205

XLATE

XLATE - Translate to and from ASCII (BDAM, BISAM, BPAM, BSAM,
QISAM, and QSAM)
The XLATE macro instruction is used to translate the data in an area in virtual storage
from ASCII code to EBCDIC code or from EBCDIC code to ASCII code.
The XLATE macro instruction is written as follows:

[symbol]

area address -

XLATE

I:I]

area address, Ie ngth [, T0:

RX-Type Address, symbol, decimal digit, absexp, or (2-12)

The area address operand specifies the address of the area that is to be translated.
length -

symbol, decimal digit,

absexp~

or (2-12)

The length operand specifies the number of bytes to be translated.
TO

{AI
{EI

The TO operand specifies the type of translation that is requested. The following
describes the characters that can be specified. If this operand is omitted, E is
assumed.
A

Specifies that translation from EBCDIC code to ASCII code is requested.
E

Specifies that translation from ASCII code to EBCDIC code is requested.

Macro Instruction Descriptions 207

APPENDIX A: STATUS INFORMATION FOLLOWING AN
INPUT /OUTPUT OPERATION
Following an input/output operation, the control program makes certain status
information available to the problem program. This information is a 2-byte exception
code, or a 16-byte field of standard status indicators, or both.
Exception codes are provided in the data control block (QISAM), or in the data event
control block (BISAM and BDAM). The data event control block is described below,
and the exception code lies within the block as shown in the illustration for the data
event control block. If a DCBD macro instruction is coded, the exception code in a
data control block can be addressed as two I-byte fields, DCBEXCD 1 and
DCBEXCD2. The exception codes can be interpreted by referring to Figures 1-3.
Status indicators are available only to the error analysis routine designated by the
SYNAD entry in the data control block. A pointer to the status indicators is provided
either in the data event control block (BSAM, BPAM, and BDAM), or in register 0
(QISAM and QSAM). The contents of registers on entry to the SYNAD routine are
shown in Figures 4-6; the status indicators are shown in Figure 7.

Data Event Control Block
A data event control block is constructed as part of the expansion of READ and
WRITE macro instructions and is used to pass parameters to the control program, help
control the read or write operation, and receive indications of the success or failure of
the operation. The data event control block is named by the READ or WRITE macro
instruction, begins on a fullword boundary, and contains the information shown in the
following illustration:

Field Contents
Offset From DECB
Address (Bytes)

BSAM and BPAM

0
+4

ECB

ECB1

Type

BISAM

BDAM

Length

DCB address

+12

Area address

lOB address
(Figure 7)

Logical record
address

lOB address
(Figure 7)

Key address

Exception code

Block address

+1f)

+20
+24

(2 bytes)
(Figure 1)

+28

Next address

Exception codes are returned in the second and third bytes of the ECB by the control program.

See Figure 3.

Appendix A: Status Information Following an Input/Output Operation 209

The event control block (ECB) is used by the control program to test for completion of
the read or write operation. The type, length, data control block address, area address,
key address, block address, and next address information is taken from the operands of
the macro instruction for use by the control program. Exception codes are returned by
the control program after the corresponding WAIT or CHECK macro instruction is
issued, as indicated in Figure 1; for BDAM, BSAM, and BP AM the control program
provides a pointer to the lOB containing the status indicators shown in Figure 7.
Exception
Code Bit

READ

WRITE

Condition if On

Type K

Record not found

Record length check

Type KN

Space not found

Type K

Invalid request

Uncorrectable I/O
error

Unreachable block

Overflow record

Type KN

8-15

Figure 1. Exception Code Bits -

Duplicate record
Reserved for
control program use

BISAM

Record Not Found: This condition is reported if the logical record with the specified
key is not found in the data set, if the specified key is higher than the highest key in
the highest level index, or if the record is not in either the prime area or the overflow
area of the data set.
Record Length Check: This condition is reported, for READ and update WRITE
macro instructions, if an overriding length is specified and (1) the record format is
blocked, (2) the record format is unblocked but the overriding length is greater than
the length known to the control program, or (3) the record is fixed length and the
overriding length does not agree with the length known to the control program. This
condition is reported for the add WRITE macro instruction if an overriding length is
specified.
When blocked records are being updated, the control program must find the high key in
the block in order to write the block. (The high key is not necessarily the same as the
key supplied by the problem program.) The high key is needed for writing because the
control unit for direct-access devices permits writing only if a search on equal is
satisfied; this search can be satisfied only with the high key in the block. If the user
were permitted to specify an overriding length shorter than the block length, the high
key might not be read; then, a subsequent write request could not be satisfied. In
addition, failure to write a h~gh key during update would make a subsequent update
impossible.

210 OS/VS Data Management Macro Instructions

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

Space Not Found in Which to Add a Record: This condition is reported if no room
exists in either the appropriate cylinder overflow area or the independent overflow area
when a new record is to be added to the data set. The data set is not changed in any
way in this situation.
Invalid Request: This condition is reported for either of two reasons. First, if byte 25
of the data event control block indicates that this request is an update WRITE macro
instruction corresponding to a READ (for update) macro instruction, but the
input/ output block (lOB) for the READ is not found in the update queue. This
condition could be caused by the problem program altering the contents of byte 25 of
the data event control block. Second, if a READ or WRITE macro instruction
specifies dynamic buffering (that is, 'S' in the area address operand) but the
DCBMACRF field of the data control block does not specify dynamic buffering.
Uncorrectable Input/Output Error: This condition is reported if the control program's
error recov"ery procedures encounter an uncorrectable error in transferring data.
Unreachable Block: This condition is reported if an uncorrectable input/output error
occurs while searching the indexes or following an overflow chain. It is also posted if
the data field of an index record contains an improper address (that is, points to the
wrong cylinder or track or is an invalid address).
Overflow Record: This condition is reported if the record just read is an overflow
record. (See the section on Direct Retrieval and Update of an Indexed Sequential Data
Set in OS/VS Data Management Services Guide for consideration during BISAM
updating.)
Duplicate Record Presented for Inclusion in the Data Set: This condition is reported if
the new record to be added has the same key as a record in the data set. However, if
the delete option was specified and the record in the data set is marked for deletion,
this condition is not reported. Instead the new record replaces the existing record.
If the record format is blocked and the relative key position is zero, the new record
cannot replace an existing record that is of equal key and is marked for deletion.

Record Not Found: This condition is reported if the logical record with the specified
key is not found in the data set, if the specified key is higher than the highest key in
the highest level index, or if the record is not in either the prime area or the overflow
area of the data set.
Invalid Actual Address for Lower Limit: This condition is reported if the specified lower
limit address is outside the space allocated to the data set.
Space Not Found in Which to Add a Record: -This condition is reported if the space
allocated to the data set is already filled. In the locate mode, a buffer segment address
is not provided. In the move mode, data is not moved.
Invalid Request: This condition is reported if (1) the data set is already being referred
to sequentially by the problem program, (2) the buffer cannot contain the key and the
data, or (3) the specified type is not also specified in the DCBMACRF field of the
data control block.
Uncorrectable Input Error: This condition is reported if the control program's error
recovery procedures encounter an uncorrectable error when transferring a block from
secondary storage to an input buffer. The buffer address is placed in register 1, and

Appendix A: Status Information Following an Input/Output Operation 211

Exception Code
Field

Bit

DCBEXCDl

Code Set by
CLOSE

GET

PUT

PUTX

Type I

Invalid actual address for lower limit

Sequence check

Duplicate record
Data control block closed when error routine
entered

Overflow record 1

Block could not be reached (input)
Block could not be reached (update)

Uncorrectable output error

X
X

Invalid request
Uncorrectable input error

Record Not Found

DCBEXCD2

Type K

Space not found in which to add a record

Condition if On

SETL

5-7

Incorrect record length
Reserved for future use

1The SYNAD routine is entered only if bit 4, 5, 6, or 7 of DCBEXCD1 is also on.

Figure 2. Exception Code Bits -

QISAM

the SYNAD routine is given control when a GET macro instruction is issued for the
first logical record.
Uncorrectable Output Error: This condition is reported if the control program's error
recovery procedures encounter an uncorrectable error when transferring a block from
an output buffer to secondary storage. If the error is encountered during closing of the
data control block, bit 2 of DCBEXCD2 is set to 1 and the SYNAD routine is given
control immediately. Otherwise, control program action depends on whether load mode
or scan mode is being used.
If a data set is being created (load mode), the SYNAD routine is given control when

the next PUT or CLOSE macro instruction is issued. In the case of a failure to write a
data block, register 1 contains the address of the output buffer, and register contains
the address of a work area containing the first 16 bytes of the lOB; for other errors,
the contents of register 1 are meaningless. After appropriate analysis, the SYNAD
routine should close the data set or end the job step. If records are to be subsequently
added to the data set using the queued indexed sequential access method (QISAM), the
job step should be terminated by issuing an ABEND macro instruction. (ABEND
closes all open data sets. However, an ISAM data set is only partially closed, and it
can be reopened in a later job to add additional records by using QISAM). Subsequent
execution of a PUT macro instruction would cause reentry to the SYNAD routine,
since an attempt to continue loading the data set would produce unpr~dictable results.

If a data set is being processed (scan mode), the address of the output buffer in error is

placed in register 1, the address of a work area containing the first 16 bytes of the lOB
is placed in register 0, and the SYNAD routine is given control when the next GET

212 OS/VS Data Management Macro Instructions

macro instruction is issued. Buffer scheduling is suspended until the next GET macro
instruction is reissued.
Block Could Not be Reached (Input): This condition is reported if the control program's
error recovery procedures encounter an uncorrectable error in searching an index or
overflow chain. The SYNAD routine is given control when a GET macro instruction is
issued for the first logical record of the unreachable block.
Block Could Not be Reached (Output): This condition is reported if the control
program's error recovery procedures encounter an uncorrectable error in searching an
index or overflow chain.
If the error is encountered during closing of the data control block, bit 2 of

DCBEXCD2 is set to 1 and the SYNAD routine is given control immediately.
Otherwise, the SYNAD routine is given control when the next GET macro instruction
is issued.
Sequence Check: This condition is reported if a PUT macro instruction refers to a
record whose key has a smaller numerical value than the key of the record previously
referred to by a PUT macro instruction. The SYNAD routine is given control
immediately; the record is not transferred to secondary storage.
Duplicate Record: This condition is reported if a PUT macro instruction refers to a
record whose key duplicates that of the record previously referred to by a PUT macro
instruction. The SYNAD routine is given control immediately; the record is not
transferred to secondary storage.
Data Control Block Closed When Error Routine Entered: This condition is reported if
the control program's error recovery procedures encounter an uncorrectable output
error during closing of the data control block. Bit 5 or 7 of DCBEXCD 1 is set to 1,
and the SYNAD routine is immediately given control. After appropriate analysis, the
SYNAD routine must branch to the address in return register 14 so that the control
program can finish closing the data control block.
Overflow Record: This condition is reported if the input record is an overflow record.
Incorrect Record Length: This condition is reported if the length of the record as
specified in the record-descriptor word (RDW) is larger than the value in the
DCBLRECL field of the data control block.
Record Not Found: This condition is reported if the search argument is not found in the
data set.
Record Length Check: This condition occurs for READ and WRITE (update) and
WRITE (add). For WRITE (update) variable-length records only, the length in the
BDW does not match the length of the record to be updated. For all remaining READ
and WRITE (update) conditions the BLKSIZE, when'S' is specified in the READ or
WRITE macro, or the length given with these macros does not agree with the actual
length of the record. For WRITE (add), fixed-length records, the BLKSIZE, when'S'
is specified in the WRITE macro, or the length given with this macro does not agree
with the actual length of the record. For WRITE (add), all other conditions, no error
can occur.
Space Not Found in Which to Add a Record: This condition occurs if either, there is no
dummy record when adding an F-format record, or there is no space available when
adding a V or U-format record.

Appendix A: Status Information Following an Iriput/Output Operation 213

Exception
Code Bit

READ

WRITE

Condition if On

Record not found

Record length check

Space not found

2
3

Invalid request -

Uncorrectable I/O error

End of data

Uncorrectable error

Type X

see bits 9-15

Not read with exclusive control
Not used

WRITE to input data set

Extended search with DCBLlMCT=O

Block or track requested was outside data set

Tried to write capacity record

12
13

Specified key as search argument when KEYLEN =0 or no
key address supplied

Request for options not in data control block

Attempt to add fixed-length record with key beginning
with hex FF

Figure 3. Exception Code Bits -

BDAM

Invalid Request: Occurs whenever one of the following bits are set to one;
Bit 9 Bit 10 Bit 11
Bit 12 Bit 13
Bit 14
Bit 15

A WRITE was attempted for an input data set.
An extended search was requested, but LIMCT was zero.
A WRITE (add) with fixed-length was attempted with the key
beginning with X'FF'.
Writing a capacity record (RO) was attempted.
A READ or WRITE with key was attempted, but either KEYLEN
equaled zero or the key address was not supplied.
The READ or WRITE macro options conflict with the OPTCD or
MACRF parameters.
The relative block or relative track requested was not in the data set.

Uncorrectable Input/Output Error: This condition is reported if the control program's
error recovery procedures encounter an uncorrectable error in transferring data
between real and secondary storage.
End of Data: This only occurs as a result of a READ (type DI, DIF, or DIX) when the
record requested is an end-of-data record.
Uncorrectable error: Same conditions as for bit 4.
Not Read With Exclusive Control: A WRITE, type DIX or DKX, has occurred for
which there is no previous corresponding READ with exclusive control.

214 OS/VS Data Management Macro Instructions

Bits

Meaning

0-7

Not used.

8-31

Address of a work area containing the first 16 bytes of the lOB (after an
uncorrectable input/output error caused by a GET, PUT, or PUTX macro
instruction; original contents destroyed in other cases). If the error condition was
detected before I/O was started, register 0 contains all zeros.

0-7

Not used.

8-31

Address of the buffer containing the error record (after an uncorrectable
input/output error caused by a GET, PUT, or PUTX macro instruction while
attempting to read or write a data record; in other cases this register contains 0).

2-13

0-31

Contents that existed before the macro instruction was issued.

0-7

Not used.

8-31

Return address. This address is either an address in the control program's Close
routine (bit 2 of DCBEXCD2 is on), or the address of the instruction following the
expansion of the macro instruction that caused the SYNAD routine to be given
control (bit 2 of DCBEXCD2 is off).

0-7

Not used.

8-31

Address of the SYNAD routine.

Figure 4. Register Contents on Entry of SYNAD Routine -

QISAM

Bits

Meaning

0-7

Not used.

8-31

Address of the first lOB sense byte. (Sense information is valid only when
associated with a unit check condition.)

0-7

Not used.

8-31

Address of the DECB.

2-13

0-31

Contents that existed before the macro instruction was issued.

0-7
8-31

Not used.
Return address.

0-7
8-31

Not used.
Address of the SYNAD routine.

Figure 5. Register Contents on Entry to SYNAD Routine -

BISAM

Appendix A: Status Information Following an Input/Output Operation 215

Bits

Meaning

0-7

Value to be added to the status indicators address to provide the address of the
first CCW (QSAM only).
Address of the associated data event control block for BDAM, BPAM, and BSAM;
address of the status indicators shown in Figure 6 for QSAM.

8-31
0
1
2

7
8-31

Bit is on for error caused by input operation.
Bit is on for error caused by output operation.
Bit is on for error caused by BSP, CNTRL, or POINT macro instruction (BPAM
AN 0 BSAM only).
Bit is on if error occurred during update of existing record or if error did not
prevent reading of the record. Bit is off if error occurred during creation of a new
record or if error prevented reading of the record.
Bit is on if the request was invalid. The status indicators pointed to in the data
event control block are not present (BDAM, BPAM, and BSAM only).
Bit is on if an invalid character was found in paper tape conversion (BSAM and
QSAM only).
Bit is on for a hardware error (BDAM only).
Bit is on if no space was found for the record (BDAM only).
Address of the associated data control block.

2-13

0-31

Contents that existed before the macro instruction was issued.

0-7
8-31

Not used.
Return address.

0-7
8-31

Not used.
Address of the error analysis routine.

3
4
5
6

Figure 6. Register Contents on Entry to SYNAD Routine and QSAM

216 OS /VS Data Management Macro Instructions

BDAM, BPAM, BSAM,

Offset From
lOB Address
Byte

Bit

Meaning

Name

Command reject
Intervention required
Bus-out check
Equipment check
Data check
Overrun
Device-dependent information
Refer to the appropriate device
manual

Sense byte 1

1
2
3
4

5
6,7
+3

0-7

0
1
2
3
4

5
6

7
+13

0
2
3
4

5
6

7
+14

Beginning of a channel status word
Command address

+9
+12

Sense byte 2

Attention
Status modifier
Control unit end
Busy
Channel end
Device end
U nit check - must be on for
sense bytes to be meaningful
Unit exception

Status byte 1
(Unit)

Program-controlled interrupt
I ncorrect length
Program check
Protection check
Channel data check
Channel control check
I nterface control check
Chaining check

Status byte 2
(Channel)

channel
status
word

Count field

Figure 7. Status Indicators for the SYNAD Routine -

BDAM, BP AM, and BSAM

Appendix A: Status Information Following an Input/Output Operation 217

APPENDIX B: DATA MANAGEMENT MACRO INSTRUCTIONS
AVAILABLE BY ACCESS METHOD

Macro Instruction
BLDL
BSP
BUILD
BUILDRCD
CHECK
CHKPT
CLOSE
CNTRL
DCB
DCBD

BDAM

BISAM

BPAM

BSAM

QISAM

QSAM

X
X

X
X
X

X
X
X
X

X
X

X
X
X

X
X

ESETL

FEOV
FIND
FREEBUF
FREEDBUF
FREEPOOL

X
X
X

GET
GETBUF
GETPOOL

X
X

NOTE
OPEN

POINT
PRTOV
PUT
PUTX
READ
RELEX
RELSE
SETL
SETPRT
STOW
SYNADAF
SYNADRLS

X
X

X
X
X

X
X
X
X

X
X

X
X
X

X
X

X
X
X

TRUNC

X
X
X

WRITE

XLATE

Appendix B: Data Management Macro Instructions Available by Access Method 219

APPENDIX C: DEVICE CAPACITIES
The following information provides a guide to coding the blocksize (BLKSIZE) and
logical record length (LRECL) operands in the DCB macro instruction. These values
can be used to determine the maximum blocksize and logical record length for a given
device, and they can be used to determine the optimum blocking factor when records
are to be blocked.

Card Readers and Card Punches
Format F, V, or U records are accepted by readers and punches but the logical record
length for a card reader or card punch is fixed at 80 bytes. The logical record length
for an IBM 2596 Card Reader is 96 bytes. If the optional control character is
specified, the logical record length is 81 (the control character is not part of the data
record). If card image mode is used, the buffer required to contain the data must be
160 bytes.

Printers
The following shows the record length that can be specified for the various printers. In
some cases, two values are shown; the larger of the two values requires that an optional
feature be installed on the printer being used. If the optional control character is
specified to control spacing and skipping, the record length is specified as one greater
than the actual data length (the control character is not part of the data record).
1403 printer
1443 printer
3211 printer
1052 printer keyboard
3210 printer keyboard
3215 printer keyboard
3525 card punch,
print feature

120 or 132 bytes
120 or 144 bytes
132 or 150 bytes
130 bytes
130 bytes
130 bytes
64 bytes

Paper-Tape Reader
2671 paper tape -

32,760 bytes

Magnetic-Tape Units
2400/3400 magnetic-tape units -

32,760

(7 tracks and 9 tracks)

Appendix C: Device Capacities 221

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

Direct-Access Devices
The following table shows the capacity of direct-access devices by track, cylinder, and
total capacity in bytes.
Device
Type

Track
Track
Capacity!
Volume Capacity!
Type
Without Keys With Keys

2314/2319
3330/3333
2305-1
2305-2

Disk
Disk
Drum
Drum

7294
13165
14136
14858

7249
12974
13934
14569

Tracks/
Cylinder

Number
Cylinders

20
19
8
8

200
404
48
96

Capacity indicated in bytes (when RO is used by the IBM programming system).

Each record written on a direct-access device requires some "device overhead." The
term device overhead means the space required by the device for address markers,
count areas, gaps between the count, key, and data areas, and gaps between blocks.
The following formulas can be used to compute the number of bytes required for each
data block including the space required for device overhead. Note that any fraction of
a byte must be treated as an extra byte. For example, if the formula computation
results in 15.067 bytes, 16 bytes must be used to determine track capacity.

Device
Type

Bytes Required by Each Data Block
Blocks With Keys
Bi
Bn

Blocks Without Keys
Bi

2314/2319
3330/3333
2305-1
2305-2

146+(KL+DL)534/512
191+KL+DL
632+KL+DL
289+DL+DL

101 +(DL)534/512
135+DL
430+DL
198+DL

DL
135+DL
430+DL
198+DL

45+KL+DL
191 +KL+DL
632+KL+DL
289+KL+DL

Bi is any block but the last on the track.
Bn is the last block on the track.
DL is data length.
KL is key length.

When the track-overflow feature is being used or variable-length spanned records are
written, the size of a data block or logical record can exceed the capacity of a single
track on the direct-access device used.

222 OS/VS Data Management Macro Instructions

APPENDIX D: DCB EXIT LIST FORMAT AND CONTENTS
The following shows the format and contents that must be supplied by the problem
program when the EXLST operand is specified in a DCB macro instruction. The exit
list must begin on a fullword boundary and each entry in the list requires one fullword.
Hexadecimal
Code
3-Byte Routine Address -

Routine Type
Inactive entry
Input header label
Output header label
Input trailer label
Output trailer label
Data control block exit
End-of-volume
User totaling
Block count exit
Defer input trailer
label

00
01
02
03
04
05
06
OA
OB
OC

Defer nonstandard
input trailer label

FCB Image
DCB ABEND exit

10
11

Last entry

Purpose

Ignored; the entry is not active.
Process a user input header label.
Create a user output header label.
Process a user input trailer label.
Create a user output trailer label.
Data control block exit routine.
End-of-volume exit routine.
Pointer to user's totaling area.
Block count unequal exit routine.
Defer processing of a user input trailer label
from the end-of-data until the CLOSE macro
instruction is issued.
Defer processing a nonstandard input trailer
label on magnetic tape unit from the end-ofdata until the CLOSE macro instruction is
issued (no exit routine address).
Define an FCB image.
Allow analysis of ABEND condition and select
one of several options.
Last entry in list. A high-order bit can be
specified with any of the above codes but must
always be specified with the last entry.

The list can be dynamically shortened during execution by setting the high-order bit of
a word to a value of 1. An entry in the list can be made inactive dynamically by
setting the high-order byte of the word to a value of hexadecimal 00.
When control is passed to an exit routine, the general registers contain the following
information:
Register

Contents

Variable; the contents depend on the exit routine used.

The three low-order bytes contain either the address of the DCB
currently being processed or, when certain exits are taken, the
address of the exit parameter list. These exits are: user-label
exits (X'O! '-'04'), deferred nonstandard input trailer exit
(X'OD'), and DCB ABEND exit (X'II').

2-13

Contents prior to execution of the macro instruction.

Return address (must not be altered by the exit routine).

Address of the exit routine entry point.

Appendix D: DCB Exit List Format and Contents 223

The conventions for saving and restoring registers are as follows:
The exit routine must preserve the contents of register 14. It need not preserve the
contents of other registers. The control program restores registers 2-13 before
returning control to the problem program.
•

The exit routine must not use the save area whose address is in register 13, because
this area is used by the control program. If the exit routine calls another routine or
issues supervisor or data management macrO instructions, it must provide the
address of a new save area in register 13.

For a detailed description of each exit list processing option, refer to OS/VS Data
Management Services Guide.

224 OS/VS Data Management Macro Instructions

APPENDIX E: CONTROL CHARACTERS
Each logical record, in all record formats, can contain an optional control character.
This control character is used to control stacker selection on a card punch or card read
punch, or it is used to control printer spacing and skipping. If 'a record containing an
optional control character is directed to any other device, it is considered to be the first
data byte, and it does not cause a control function to occur.
In format-F and format-U records, the optional control character must be in the first
byte of the logical record.
In format-V records, the optional control character must be in the fifth byte of the
logical record, immediately following the block descriptor word of the record.
Two control character options are available. A control character option is selected by
coding the appropriate character in the RECFM operand of the DCB macro
instruction. If either option is specified in the data control block, a control character
must be included in each record, and other spacing or stacker selection options also
specified in the data control block are ignored.

Machine Code
The record format field in the data control block indicates that the machine code
control character has been placed in each logical record. If the record is written, the
appropriate byte must contain the command code bit configuration specifying both the
write and the desired carriage or stacker select operation. If the record is not written,
the byte can specify any command other than write.
Command codes for specific devices are contained in IBM System Reference Library
publications describing the control units or devices.

American National Standards Institute Control Characters
In place of machine code, control characters defined by the American National
Standards Institute (ANSI) can be specified. These characters must be represented in
EBCDIC code.

Appendix E: Control Characters 225

American National Standards Institute (ANSI) control characters are as follows:
Code

Action Before Printing a Line

Space one line (blank code)
Space two lines
Space three lines
Suppress space
Skip to channel 1
Skip to channel 2
Skip to channel 3
Skip to channel 4
Skip to channel 5
Skip to channel 6
Skip to channel 7
Skip to channel 8
Skip to channel 9
Skip to channel 10
Skip to channel 11
Skip to channel 12
Select punch pocket 1
Select punch pocket 2

o
+
1
2
3
4
5
6
7
8
9
A
B
C
V
W

These control characters include those defined by ANSI FORTRAN. If any other
character is specified, it is interpreted as 'b' or V, depending on the device being used;
no error indication is returned.

226 OS/VS Data Management Macro Instructions

APPENDIX F: DATA CONTROL BLOCK SYMBOLIC FIELD NAMES
The following describes data control block fields that contain information which defines
the data characteristics and device requirements for a data set. Each of the fields
described shows the values that result from specifying various options in the DCB
macro instruction. These fields can be referred to by the problem program through the
use of a DCBD macro instruction which creates a dummy control section (DSECT) for
the data control block. Fields that contain addresses are 4 bytes long and are aligned
on a fullword boundary. If the problem program inserts an address into a field, ~he
address must be inserted into the low-order 3 bytes of the field without changing the
high-order byte.
The contents of some fields in the data control block depend on the device and access
method being used. A separate description is provided when the contents of the field
are not common to all device types and access methods.

Data Control Block Offset

Common Fields
Bytes and
Alignment

26(IA)

Field
Name

Description

DCBDSORG

Data set organization.

1...
.1..
.. 1.

Code
IS
PS
DA

... x

xx ..
.. 1.

... 1

Indexed sequential.
Physical sequential.
Direct organization .
Reserved bits .
Partitioned organization.
Unmovable - the data set contains
location-dependent informat ion.

40(28)

DCBDDNAM

Eight byte name of the data definition
statement that defines the data set associated
with this DCB.

42(2A)

DCBMACRF
(After
OPEN)

This field may only be referenced after OPEN.
It is common to all uses of the DCB and is
created by moving the DCBMACR field into this
area.

DCBOFLGS
. , .1
1...

Flags used by Open routine.
OPEN has completed successfully .
Set to I by problem program to indicate
concatenation of unlike attributes.
Set to 0 by an I/O support function when that
function takes a user exit. It is set to 0 to
inhibit other I/O support functions from
processing this DCB.
Set to I on return from the user exit to the
I/O support function that took the exit.

48(30)

.. 0.

.. 1.
50(32)

.. 2

DCBMACR
(Before
OPEN)

Macro instruction reference before OPEN.
Major macro instructions and various options
associated with them. Used by the Open
routine to determine access method. Used by
the access method executors in conjunction
with other parameters to determine which load
modules are required. This field is moved to

Appendix F: Data Control Block Symbolic Field Names 227

Offset

Bytes and
Alignment

Field
Name

Description
overlay part of DCBDDNAM at Open time and
becomes the DCBMACRF field.
This field is common to all uses of the DCB,
but each access method must be referenced for
its meaning.

Data Control Block Offset

SAM, BPAM
Bytes and
Alignment

20(14)

Field
Name

Description

DCBBUFNO

Number of buffers required for this data set.
May range from 0 to a maximum of 255.

2 t( 15)

DCBBUFCB

Address of buffer pool control block.

24(18)

DCBBUFL

Length of buffer. May range from 0 to a
maximum of 32,760.

32(20)

DCBBFALN
.. xx
.. 10
.. 01

D
F

DCBBFTEK
.xxx
. 1.0
.0.1
.110

S
E
A

.010

....

36(24)

Buffering technique:
Simple buffering .
Exchange buffering .
QSAM locate mode processing of spanned
records: OPEN is to construct a record
area if it automatically constructs
buffers.
BSAM create BDAM processing of unblocked spanned records: Software track
overflow. OPEN forms a segment work
area pool and stores the address of the
segment work area control block in
DCBECBW.However, WRITE uses a
segment work area to write a record as
one or more segments.
BSAM input processing of unblocked
spanned records with keys: Record offset
processing. READ reads one record
segment into the record area. The first
segment of a record is preceded in the
record area by the key. Subsequent
segments are at an offset equal to the key
length.
Reserved bit.

x...
33(21 )

Buffer alignment:
Doubleword boundary.
Fullword not a doubleword boundary,
coded in the DCB macro instruction.

DCBEODAD

End-of-data address. Address of a userprovided routine to handle end-of-data
conditions.

DCBRECFM

Record format.
Code

.. 1.

10 ..
01..

228 OS/VS Data Management Macro Instructions

D
F
V

Format-D record .
Fixed record length.
Variable record length.

Offset

Bytes and
Alignment

Field
Name

Description

11..
.. 1.
... 1

U
T
B
1. ..

.10.
.01.
.00.
••. 1

Undefined record length.
Track overflow .
Blocked records . May not occur with
undefined (U).
S
Fixed length record format: Standard
blocks. (No truncated blocks or unfilled
tracks are embedded in the data set.)
Variable length record format: Spanned
records.
A
ANSI control character.
M
Machine control character.
No control character.
Key length (KEYLEN) was specified in the
DCB macro instruction. This bit is inspected
by the Open routine to prevent overriding a
specification of KEYLEN =0 by a nonzero
specification in the JFCB or data set label.

37(25)

DCBEXLST

Exit list. Address of a user-provided exit
list control block.

42(2A)

DCBMACRF

Macro instruction reference after OPEN.
Contents and meaning are the same as those of
the DCBMACR field in the foundation segment
before OPEN.

50(32)

.. 2

DCBMACR
(Before
OPEN)

Major macro instructions and various options
associated with them. Used by the Open
routine to determine access method. Used by
the access method executors in conjunction
with other parameters to determine which load
modules are required.
Code

Byte 1
00 ..
.. 1.
... x x .. x
. 1..
.. 1.
51(33)

Byte 2
00 ..
.. 1.
1. ..
. 1..
.. 1.
... 1

50(32)

Byte 1
0 ...
.1..
.. 0.
••• 1
1...
. 1..

R
P
C

W
L
P
C

G
M
L
T

BSAM - Input
Always zero for BSAM.
READ
Reserved bits .
POiNT (which implies NOTE) .
CNTRL
BSAM - Output
Always zero for BSAM.
WRITE
Load mode BSAM (create BDAM data
set).
POINT (which implies NOTE) .
CNTRL
BSAM create BDAM processing of
unblocked spanned records, with
BFTEK=R specified: The user's program
has provided a segment work area pool
and stored the address of the segment
work area control block in DCBEOBW.
QSAM - Input
Always zero for QSAM.
GET
Always zero for QSAM .
Move mode .
Locate mode.
Substitute mode .

Appendix F: Data Control Block Symbolic Field Names 229

Offset

Bytes and
Alignment

Field
Name

Description
.. 1.
... 1

Byte 2
0 ...
.1..
.. 0.
... 1

51(33)

1...
.1..
.. 1.
... 1
50(32)

Byte 1
00 ..
.. 1.

... x
51(33)

.1..
x.xx

Byte 2
00 ..
.. 1.

... x

C
D

. 1..
x.xx

M
L
T
C
D

R
P

A
W
P

CNTRL
Data mode.
QSAM - Output
Always zero for QSAM.
PUT
Always zero for QSAM .
Move mode .
Locate mode.
Substitute mode.
CNTRL
Data mode.
BPAM - Input
Always zero for BPAM.
READ
POINT (which implies NOTE).
Reserved bits.
BPAM - Output
Always zero for BPAM.
WRITE
POINT (which implies NOTE) .
Reserved bits.

Direct-Access Storage Devices Interface
Field
Name

Description

16(10)

DCBKEYLE

Key length of the data set.

17(11)

DCBDEVT

Device type.

0010 1000
0010 0111
0010 1001

2314 Disk Storage Facility
2305-2 DiSk Storage Facility, Model 2
3330 Disk Storage

Field
Name

Description

DCBTRTCH

Tape recording technique for 7-track tape.

0010
0011
0001
0010

E
T

Offset

Bytes and
Alignment

Magnetic Tape Interface
Offset

Bytes and
Alignment

16(10)

Code

17(11)

18(2)

.. 1

0011
1011
0011
1011

C
ET

Even parity.
BCD/EBCDIC translation.
Data conversion.
Even parity and translation.

DCBDEVT

Device type.

1000 0001

2400 series magnetic tape unit (7-track or
9-track).

DCBDEN

Tape density Code

7-tracks

0000
0100
1000
1100

200 BPI
556 BPI
SOO BPI

0011
0011
0011
0011

230 OS/VS Data Management Macro Instructions

1
2
3

2400 series magnetic tape units.

9-tracks

SOO BPI
1600 BPI

Page of GC26-3793-1
Revised December 15, 1972
By TNL GN26-0748

Paper Tape Interface
Offset

Bytes and
Alignment

16(10)

Field
Name

Description

DCBCODE

1000
0100
0010
0001
0000
0000
0000
17(11)

0000
0000
0000
0000
1000
0100
0010

Paper tape code being used. The appropriate
translate table is made available.
Code
N

I
F
B
C
A
T

No conversion
IBM BCD
Friden
Burroughs
National Cash Register
ASCII (8-track)
Teletype 1

DCBDEVT

Device type.

0101 0000

2671 Paper Tape Reader.

Card Reader, Card Punch Interface
Offset

Bytes and
Alignment

16(10)

Field
Name

Description

DCBMODE,DCBSTACK
Code

xxxx
1000
0100

xxxx
0001
0010
17(11)

1
2

Mode of operation for 1442 Card Read
Punch.
Column binary mode.
EBCDIC mode.
Stacker selection.
Stacker 1.
Stacker 2.

DCBDEVT

Device type.

0100
0100
0100
0100
0100
0000

0011
0001
0010
0100
0101
0110
0000 1100

1442 Card Read Punch
2540 Card Reader
2540 Card Punch
2501 Card Reader
2520 Card Read Punch
3505 Card Reader
3525 Card Punch

Field
Name

Description

DCBPRTSP

Number indicating normal printer spacing.

0000
0000
0001
0001

Printer Interface
Offset

Bytes and
Alignment

16(10)

Code

17(11)

0001
1001
0001
1001

1
2

No spacing.
Space one line.
Space two lines.
Space three lines.

DCBDEVT

Device type.

Byte
0100
0100
0100

1403 Printer
3211 Printer
1443 Printer

1
1000
1001
1010

Trademark of Teletype Corporation.

Appendix F: Data Control Block Symbolic Field Names 231

Bytes and
Offset Alignment

Field
Name Description
Test-for-printer-overflow mask (PRTOV
mask). If printer overflow is to be
tested for, the PRTOV macro instruction
sets the mask as follows:
Byte 2
0010 0000
0001 0000

Code
9
12

Field
Name

Description

DCBOPTCD

Option codes.

1. ..
.1 ..

Code
W
U

.. 1.

Test for channel 9 overflow.
Test for channel 12 overflow.

Access Method Interlace
BSAM, BPAM Interface
Offset

Bytes and
Alignment

52(34)

... x
.1..

.. 1.
1...

T
Q

... x
52(34)

Write-validity check (DASD).
Allow a data check caused by an invalid
character. (1403 printer with UCS
feature.)
Chained scheduling using the Program
Controlled Interruption.
Reserved bit .
Magnetic tape devices: Use reduced
error recovery procedure.
BSAM only: user totaling .
An ASCII data set is to be processed.
Same as DCBOPTQ. BSAM only.
Reserved bit.

DCBOPTQ
1. ..

ASCII indication.
An ASCII data set is to be processed. Same
as DCBOPTCD, Code=Q. BSAM only.

57(39)

DCBSYNAD

Address of user's synchronous error routine to
be entered when a permanent error occurs.

62(3E)

.. 2

DCBBLKSI

Maximum blocksize. Maximum value: 32,760.
For fixed-length blocked record format, it
must be a multiple of the length given in
DCBLRECL. For variable-length records, this
must include the 4 byte block length field.

72(48)

DCBNCP

Number of chained programs. Number of
READ or WRITE requests which may
be issued prior to a CHECK. Maximum
number: 99.

80(50)

DCBUSASI!
DCBLBP

ASCII tape.
Block prefix.

.1 ..

Block prefix is a four-byte field containing
the block length.

81(51)

DCBBUFOF

Block prefix length.

82(52)

.. 2

DCBLRECL

Logical record length. For fixed-length blocked
record format, the presence of DCBLRECL
allows BSAM to read truncated records. For
undefined records, this field contains blocksize.

232 OS!VS Data Management Macro Instructions

QSAM Interface
Offset

Bytes and
Alignment

52(34)

Field
Name

Description

DCBOPTCD

Option codes.
Code

1.•.

1...
.1..

W
U

.. 1.

... x

52(34)

.1..

.. 1.

DCBOPTQ
1...

An ASCII data set is to be processed.
Same as DCBOPTQ. BSAM only.
Write-validity check (DASD)'
Allow a data check for an invalid
character (1403 with UCS).
Chained scheduling using the Program
Controlled Interruption.
Reserved bit.
Magnetic tape devices. Use reduced
error recovery procedure.
User totaling .

ASCII indication.
An ASCII data set is to be processed. Same
as DCBOPTCD, Code=Q. BSAM only.

57(39)

DCBSYNAD

Address of the user's synchronous error routine
to be entered when a permanent error occurs.

62(3E)

.. 2

DCBBLKSI

Maximum blocksize. Maximum value: 32,760.
For fixed-length blocked record format, it must
be a multiple of DCBRECL. For variablelength records this must include the 4-byte
block length field provided by the access method.

DCBUSASI!
DCBLBP

ASCII tape.
Block prefix.

.1..

Block prefix is a four-byte field containing
the block length.

80(50)

81(51)

DCBBUFOF

Block prefix length.

82(52)

.. 2

DCBLRECL

Format-F records: Record length.
Format-U records: Blocksize.
Format-V recordsUnspanned record format GET: PUTX; record length.
PUT: Actual or maximum record length.
Spanned record format Locate mode - GET: Segment length.
- PUT: Actual or minimum segment
length.
Logical record interface - Before OPEN: Maximum logical record
length.
- After GET: Record length.
- Before PUT: Actual or maximum record
length.
Move mode- GET: Record length.
- PUT: Actual or maximum record length.
Data mode, GETData records up to 32,752 bytes: Data
length.

Appendix F: Data Control Block Symbolic Field Names 233

Bytes and
Offset Alignment

Field
Name Description
Data records exceeding 32,752 bytes:
- Before OPEN: X'8000'
-After OPEN: Data length.
Output mode, PUTX (output data set):
Segment length.

84(54)

Data Control Block Offset

Error option. Disposition of permanent errors
if the user returns from a synchronous error
exit (DCBSYNAD), or if the user has no
synchronous error exit.

1...
. 1..
.. 1.

ACC: Accept.
SKP: Skip .
ABE: Abnormal end of task .

Field
Name

Description

DCBKEYLE

Key length.

DCBDEVT

Device type.

0010 1000
0010 0111
0010 1001

2314 Disk Storage Facility.
2305-2 Disk Storage Facility, Model 2.
3330 Disk Storage.

DCBBUFNO

Number of buffers required for this data set:
0-255.

ISAM
Bytes and
Alignment

16(10)
17(11)

DCBEROPT

20(14)
21(15)

DCBBUFCB

Address of buffer pool control block .

24(18)

DCBBUFL

Length of buffer: 0- 32,760.

32(20)

DCBBFALN
Code

33(21)
36(24)

... xx
.. 10
.. 01

D
F

.. 11

Buffer alignment:
Doubleword boundary .
Fullword not a doubleword boundary,
coded in the DCB macro instruction.
Fullword not a doubleword boundary,
coded in the DD statement.

DCBEODAD

Address of a user-provided routine to handle
end-of-data conditions.

DCBRECFM

Record format.
Code
F

10..
10 ..
11..
.. 1.
... 1

U
T
B

1...

'.10.
. 01.
.00.
... 1

A
M

234 OS/VS Data Management Macro Instructions

Fixed length records.
Variable length records.
Undefined length records.
Track overflow.
Blocked records. May not occur with
undefined (U).
Standard records. No truncated blocks or
unfilled tracks are embedded in the
data set.
ANSI control character.
Machine control character .
No control character.
Key length (KEYLEN) was specified in

Bytes and
Offset Alignment

Field
Name Description
the DCB macro instruction; this bit is
inspected by the Open routine to prevent
overriding a specification of KEYLEN=O by
a nonzero specification in the JFCB or
data set label.

37(25)

DCBEXLST

Exit list. Address of a user-provided list.

42(2A)

.. 2

DCBMACRF

Macro instruction reference after OPEN:
Contents and meaning are the same as those
of the DCBMACR field before OPEN.

50(32)

.. 2

DCBMACR

Byte 1
00.0 0 ...
.. 1.
.1..
.. 1.
... x

50(32)

Macro instruction reference before OPEN:
specifies the major macro instructions and
various options associated with them. Used
by the Open routine to determine access method.
Used by the access method executors in
conjunction with other parameters to determine
which load modules are required.
Code
BISAM

R
S
C

Byte 2
00.0 0000

51(33)

Byte 1
0.0. .0..
.1..
... 1
1...
.. xx

50(32)

Byte 2
1...
.1..
.. 0.
... 1

51(33)

Always zero for BISAM.
WRITE
QISAM

G
M
L

Always zero for QISAM.
GET
Move mode of GET .
Locate mode for GET.
Reserved bits .
QISAM

S
P

1...
.1..
.. 1.
... 1

52(34)

BISAM

.. 1.

Always zero for BISAM.
READ
Dynamic buffering.
CHECK
Reserved bit.

M
L
U
K

SETL
PUT or PUTX.
Always zero for QISAM .
Move mode of PUT.
Locate mode of PUT.
Update in place (PUTX).
SETL by key.
SETL by ID .

DCBOPTCD

Option codes:

1...
.1..
.. 1.
... 1

W
U
M

Code

1. ..
.. 1.
... 1
.x ..

53(35)

DCBMAC

Y
L
R

Write-validity check.
Full-track index write.
Master indexes .
Independent overflow area .
Cylinder overflow area.
Delete option.
Reorganization criteria.
Reserved bit.

Extension of the DCBMACRF field for ISAM.

Appendix F: Data Control Block Symbolic Field Names 235

Bytes and
Offset Alignment

Field
Name Description
Code

xxxx ... x
1. ..
.1..
.. 1.

U
U
A

Reserved bits.
Update for read.
Update type of write.
Add type of write .

54(36)

.. 1

DCBNTM

Number of tracks that determines the
development of a master index.
Maximum permissible value: 99.

55(37)

... 1

DCBCYLOF

The number of tracks to be reserved on each
prime data cylinder for records that overflow
from other tracks on that cylinder. Refer to
the" section on allocating space for an ISAM
data set in OS/VS Data Management Services
Guide to determine how to calculate the
maximum number.

56(38)

DCBSYNAD

Address of user's synchronous error routine
to be entered when uncorrectable errors are
detected in processing data records.

60(3C)

DCBRKP

Relative position of the first byte of the key
within each logical record. Maximum permissible
value: logical record length minus key length.

62(3E)

.. 2

DCBBLKSI

Blocksize.

64(40)

DCBMSWA

Address of the storage work area reserved for
use by the control program when new records
are being added to an existing data set.

68(44)

DCBSMSI

Number of bytes in area reserved to hold the
highest level index.

70(46)

DCBSMSW

Number of bytes in work area used by control
program when new records are being added to
the data set.

DCBNCP

Number of copies of the READ-WRITE (type K)
channel programs that are to be established
for this data control block (99 maximum).

DCBMSHI

Address of the storage area holding the
highest level index.

DCBEXCDI

First byte in which exceptional conditions
detected in processing data records are
reported to the user.

1...
.1..

Lower key limit not found.
Invalid device address for lower limit.
Space not found .
Invalid request.
Uncorrectable input error.
Uncorrectable output error .
Block could not be reached (input) .
Block could not be reached (update) .

72(48)

73(49)

80(50)

.. 1.

... 1
1...
. 1..
.. 1.
•.• 1

81(51)

DCBEXCD2

Second byte in which exceptional conditions
detected in processing data records are
reported to the user.

1...
. 1..
.. 1.
... 1

Sequence check.
Duplicate record .
DCB closed when error was detected .
Overflow record .

236 OS/VS Data Management Macro Instructions

Bytes and
Offset Alignment

Field
Name D,escription
1...
.xxx

PUT: length field of record larger than
length indicated in DCBLRECL.
Reserved bits.

82(52)

.. 2

DCBLRECL

Logical record length for fixed-length record
formats. Variable-length record formats:
maximum logical record length or an actual
logical record length changed dynamically
by the user when creating the data set.

197(C5)

DCBOVDEV

Device type for independent overflow.

0010 1000
0010 0111
0010 1001

2314 Disk Storage Facility.
2305-2 Disk Storage Facility, Model 2.
3330 Disk Storage.

Field
Name

Description

DCBKEYLE

Key length.

DCBREL

Number'of relative tracks or blocks in this
data set.

DCBBUFNO

Number of buffers required for this data set.
May range from 0 to 255.

Data Control Block -

BDAM

Offset

Bytes and
Alignment

16(10)
17(11)

20(14)
21 (15)

DCBBUFCB

Address of buffer pool control block or of
dynamic buffer pool control block.

24(18)

DCBBUFL

Length of buffer. May range from 0 to 32,760.

32(20)

DCBBFALN
.. xx
.. 10
.. 01
.. 11
.x.x

32(20)

x...

Buffer alignment:
Doubleword boundary .
Futlword nota doubleword boundary, coded in
the DCB macro instruction .
Fullword not a doubleword boundary, coded in
the DD statement.
Reserved bits .

DCBBFTEK
.. x.

36(24)

Buffering technique .
Unblocked spanned records:
Software track overflow. OPEN forms a
segment work area pool. The number of
segment work areas is determined by
DCBBUFNO (OPEN stores the address of
the segment work area control block
in DCBDYNB) if dynamic buffering is not
used or in the dynamic buffer pool
control block (see DCBBUFCB) if
dynamic buffering is used. WRITE uses
a segment work area to write a record
as one or more segments. READ uses a
segment work area to read a record that
was written as one or more segments.

.. 1.

DCBRECFM

Record format.

Appendix F: Data Control Block Symbolic Field Names 237

Bytes and
Offset Alignment

Field
Name Description
to..

Code
F

01..
11..
.. 1.

U
T

••. 1

1...
.00.
... 1

Fixed record length.
Variable record length.
Undefined record length.
Track overflow .
Blocked (allowed only with V) .
Spanned (allowed only with V).
Always zeros .
Key length (KEYLEN) was specified in
the DCB macro instruction. This bit
is inspected by the Open routine to
prevent overriding a specification of
KEYLEN=O by a nonzero specification
in the JFCB or data set label.

37(25)

DCBEXLST

Exit list. Address of a user-provided exit
list control block.

42(2A)

.. 2

DCBMACRF

Macro instruction reference after OPEN .
Contents and meaning are the same as
DCBMACR before OPEN.

50(32)

.. 2

DCBMACR

Macro instruction reference before OPEN:
major macro instructions and various options
associated with them that will be used.
Code

50(32)

51(33)

Byte. 1
00 ..
.. 1.
... 1

1...
.1..

K
I
S

.. 1.
... 1

X
C

Byte 2
00 ..
.. 1.
... 1

Code
W

K
1...
.x ..
.. 1.
... 1

52(34)

Always zero for BDAM.
READ
Key segment with READ .
ID argument with READ.
System provides area for READ (dynamic
buffering).
Read exclusive .
CHECK macro instruction .

DCBOPTCD

I
A

Option codes:
Code
W

1. ..
. 1..
.. 1.
. .. 1

E
F
1...
. 1..
.. 1.
.•. 1

238 OS/VSData Management Macro Instructions

Always zero for BDAM.
WRITE
Key segment with WRITE .
ID argument with WRITE.
Reserved bit.
Add type of WRITE .
Unblocked spanned records, with
BFTEK=R specified and no dynamic
buffering: The user's program
has provided a segment work area
pool and stored the address of
the segment work area control
block in DCBDYNB.

Write-validity check.
Track overflow .
Extended search .
Feedback .
Actual addressi ng.
Dynamic buffering .
Read exclusive .
Relative block addressing .

Bytes and
Offset Alignment

Field
Name Description

56(38)

DCBSYNAD

Address of SYNAD (synchronous error)
routine.

62(3E)

.. 2

DCBBLKSI

Maximum blocksize .

81(51)

DCBLIMCT

Number of tracks or number of relative blocks
to be searched (extended search option).

Appendix F: Data Control Block Symbolic Field Names 239

APPENDIX G: EVENT CONTROL BLOCK
The event control block is used for communications between the various components of
the system and between problem programs and the system. An event control block is
the subject of WAIT and POST macro instructions. The following illustration shows
the format of the event control block; a description of its fields follows the illustration.
+1

WICI
Offset

I
Bytes and
Alignment.

Bit
Code

Hex.
Dig.

lOxx

xxxx

01xx

xxxx

Description
W - Waiting for completion of an
event.
C - The event has completed.
One of the following completion codes
will appear at the completion of a
channel program:
Access Methods Other Than BTAM

0111

1111

Channel program has terminated without
error. (CSW contents useful.)

0100

0001

Channel program has terminated with
permanent error. (CSW contents useful.)

0100

0010

Channel program has terminated because
a direct access extent address has been
violated. (CSW contents do not apply.)

0100

Channel program has been intercepted
because of permanent error associated
with device end for previous request.
You may reissue the intercepted
request. (CSW contents do not apply.)

0100

1000

Request element for channel program
has been made available after it has
been purged. (CSW contents do no apply.)

0100

1111

Error recovery routines have been
entered because of direct access error
but are unable to read home addresses
or record O. (CSW contents do not apply.)

0111
0100
0100

1111

Completed normally.
Completed with an I/O error.
Enable command halted, or I/O
operation purged.

BTAM

1(1)

0001

1000

While awaiting completion of an event,
the request block address appears in
these 3 bytes. After completion of
the event, zeros, or the remainder
of the completion code, appear in
the last 3 bytes of the ECB.

Appendix G: Event Control Block 241

INDEX
Indexes for reference manuals are consolidated in OS/VS Master Index, GC28-0602. For additional
information about any subject listed below, refer to other publications listed for the same subject in the
Master Index.

A-type address constant defined 4
ABEND exit, DCB macro
BDAM 49
BISAM 55
BPAM 62
BSAM 77
list format 223-224
QISAM 86
QSAM 104
absexp defined 4
absolute expression defined 4
access methods
DCBD options 109-110
general description
BDAM 45
BISAM 53
BPAM 59
BSAM 67
QISAM 83
QSAM 93
macro instructions used with 219
SYNADAF options 183
actual device addressing (BDAM) 45,51
adding data to a data set
BDAM 191,50
BISAM 195,55
BPAM 179,197
BSAM 199
QISAM 145
QSAM 147
address constant, A-type
defined 4
address feedback
current block position 151,193
next block position 152,200
address of buffers
obtained from a pool 127
returned to a pool 117
addressing, types of (BDAM) 45-47
aids, coding 1-2
alias names in a directory 179-180
alignment of buffers
BDAM 46
BISAM 53-54
BPAM 60
BSAM 67-68
QISAM 84
QSAM 93

allocating space for a data set
BPAM 157
ISAM 83
American National Standards Institute
(ANSI) control characters
BPAM 64
BSAM 81
defined 226
QSAM 107
analysis of I/O errors
BDAM 52,209-217
BISAM 57,209-217
BPAM 64,209-217
BSAM 82,209-217
QISAM 90,209-217
QSAM 108,209-217
SYNADAF 183,209-217
ANSI·
(see American National Standards Institute)
argument, search
BDAM 51
QISAM 87
ASCII data sets
block prefix
BSAM 70
QSAM 96
restriction 96
blocksize
BSAM 73
QSAM 99
buffer length
BSAM 69
QSAM 96
on paper tape
BSAM 81
QSAM 107
restriction on record format
BSAM 81
QSAM 108
ASCII translation
Check routine 23
DeB option
BSAM 80-81
QSAM 106
Get routine 125
Put routine 147
Write routine 197
XLA TE macro instruction 207
associated data sets
closing 33
opening 133
types of
BSAM 74-75
QSAM 100-101

Index 243

automatic buffer pool construction
BDAM 45
BISAM 54
BPAM 61
BSAM 70
QISAM 85
QSAM 96
automatic checkpoint restart 25
automatic volume switching (FEOV macro) 113

backspacing
BSP macro 13
CNTRL macro 41
backward read
open option 134
Read operation 157
base registers for
dummy sections 109
macro instructions 4
BCD 8-track paper tape code
BSAM 73
QSAM 99
BDAM (basic direct access method)
general description 45
macro instructions used with 219
BFALN operand (DCB macro)
BDAM 46
BISAM 53-54
BPAM 60
BSAM 67-68
QISAM 84
QSAM 93-94
BFTEK operand (DCB macro)
BDAM 46
BSAM 68
QSAM 94
BISAM (basic indexed sequential access method)
general description 53
macro instructions used with 219
BLDL macro instruction
description 9
used with FIND 115
BLKSIZE operand (DCB macro)
BDAM 46-47
BPAM 60-61
BSAM 68-69
QISAM 84
QSAM 94-95
block
backspacing by 13
count.exit
BSAM 77
list format 223
QSAM 104
data control 45-108
data event control 209
descriptor word
(seeBLKSIZE operand)

244 OS/VS Data Management Macro Instructions

event control 209
position feedback 151-153,192
positioning with POINT 141
preftx
(see also BUFOFF operand)
effect on buffer length 67,96
effect on data alignment 67,93
reading 151-163
size
(see BLKSIZE operand)
writing 191-205
blocking
data checks (UCS printer) 172
records
BDAM 45,52
BPAM 59,64
BSAM 67,81
QISAM 90,145
QSAM 107-108,147
blocksize for SYSOUT data sets
(see also BLKSIZE operand)
BSAM 68
QSAM 94-95
BOLD type, meaning of 2
boundary alignment
(see BF ALN operand)
BPAM (basic partitioned access method)
general description 59
macro instructions used with 219
BSAM (basic sequential access method)
general description 67
macro instructions used with 219
BSP macro instruction 13
BUFCB operand (DCB macro)
BDAM 47
BISAM 54
BPAM 61
BSAM 69
QISAM 85
QSAM 95
relationship to
BUILD macro 15
BUILDRCD macro 17
GETBUF macro 127
GETPOOL macro 129
buffer
alignment
(see BFALN operand)
control
automatic 145-147,123-126
dynamic 119,196
using FREEBUF macro 117
using FREEDBUF macro 119
using GETBUF macro 127
using RELSE macro 167
forms control
using SETPRT macro 171
length
(see also BUFL operand)
BUILD macro 16
BUILDRCD macro 18
GETPOOL macro 129

checkpoint records, embedded (DOS) (Continued)
POINT macro 141
QSAM 107
CHKPT macro instruction 25
execute form 31
list.form 29
return codes 27-28
CLOSE macro instruction
execute form 39'
I/O error while executing
BDAM 52
BISAM 57
BPAM 64-65
BSAM 82
QISAM 90
QSAM 108
list form 37
relationship to
CNTRL macro 41
FREEPOOL macro 33
GETPOOL macro 129
PUT macro 145,148
SETL macro 169
standard form 33
TYPE=T (BSAM) 33-35
CNTRL macro instruction
description 41
restriction on use 41
specified in MACRF operand (DCB macro)
BSAM 79
QSAM 105
code
card
BSAM 74
QSAM 100
completion
(see code, return)
control character
(see control characters)
conversion
ASCII to EBCDIC 23,125
EBCDIC to ASCII 197
paper tape 73,101
XLATE macro 207
exception 209-217
return
BLDL macro 11
BSP macro 13
CHKPT macro 29-30
FIND macro 116
RELEX macro· 165
SETPRT macro 173
STOW macro 181
SYNADAF macro 184
SYNADRLS macro 187
WRITE macro 201
CODE operand (DCB macro)
BSAM 73
QSAM 99
coding
aids 1-2
macro instructions 2-5
registers as operands 3
restrictions for CLOSE options 134

246 OS/VS Data Management Macro Instructions

variable-length parameter lists 37,131,137
column, binary
(see card image mode)
eliminate mode, read
BSAM 74,76
QSAM 100
completion code
(see code, return)
completion testing of I/O operations 23
concatenation
input data sets (BPAM) 59
number 10
condition, exception 33,209-217
construct
a data control block
(see DCB macro instruction)
a DECB (data event control block) 203
a buffer pool
(see buffer pool construction)
contents of registers on entry to
exit list 223
SYNAD 219
control
I/O device 41-43
page format 143
releasing
buffer (FREEBUF macro) 117
buffer pool (FREEPOOL macro) 121
data block 165
dynamically acquired buffer 119,191-196
QSAM buffer (RELSE macro) 167
requesting
buffer (GETBUF macro) 127
buffer pool (GETPOOL macro) 129
data block 151
control block
buffer pool
(see BUFCB operand)
data
(see DCB macro instruction)
data event 209
control characters
ANSI 226
CNTRL macro 41
machine 226
PRTOV macro 143
control section (CSECT)
(see DCB macro instruction)
count exit, block
BSAM 77
format list 223
QSAM 104
cylinder
index 88
overflow area 89
CYLOFL (cylinder overflow area)
operand 85-86
option 89

D-format records
BSAM 81

buffer (Continued)
for card image mode 69,96
for ASCII data sets 69,96
message format (SYNADAF macro) 185
pool construction
(see also BUFCB operand)
automatic
(see BUFNO operand)
using BUILD macro 15
using BUILDRCD macro 17
using GETPOOL macro 129
releasing of
using FREEBUF macro 117
using FREEDBUF macro 119
using FREEPOOL macro 121
using RELSE macro 167
using SYNADRLS macro 187
buffering, types of
automatic 145-147,123-126
dynamic 119
exchange 94
problem erogram controlled
BDAM 48
BISAM 54
BPAM 61
BSAM 70
simple 94
variable-length spanned record
BDAM 48
QSAM 94
using BUILDRCD macro 17
BUFL operand (DCB macro)
BDAM 47
BISAM 54
BPAM 61
BSAM 69
QISAM 85
QSAM 96
BUFNO operand (DCB macro)
BDAM 48
BISAM 54
BPAM 61
BSAM 70
QISAM 85
QSAM 96
relationship to NCP operand 56
BUFOFF operand (DCB macro)
BSAM 70
QSAM 96
BUILD macro instruction
description 15
relationship to
buffer length
(see BUFL operand)
buffer pool control block
(see BUFCB operand)
number of buffers
(see BUFNO operand)
BUILDRCD macro instruction
description
execute form 21
list form 19
standard form 17
relationship to

buffer length
(see BUFL operand)
GET macro 126
number of buffers
(see BUFNO operand)
PUT macro 148
Burroughs 7-track paper tape code
BSAM 73
QSAM 99

II
card
code
BSAM 74
QSAM 100
image mode
defined 74,100
buffer length required 69,96
punch 74,100
reader 74,100
carriage
control channel
CNTRL macro 41
PRTOV macro 143
control characters
ANSI 226
CNTRL macro 41
machine 226
PRTOV macro 143
changing partitioned data set member name 179
chained scheduling option
BPAM63
BSAM 80
CHKPT macro 26
QSAM 106
channel
carriage control
(see carriage control channel)
overflow 143
programs, number of
BISAM 56
BPAM 63
BSAM 79
CHECK macro instruction
description 23
relationship to
end of data (EODAD) 62,77
number of Read and Write operations (NCP) 56,63
return of exception codes 209
with READ macro 151-163
with WRITE macro 191-205
checking, write-validity
BDAM 51
BPAM 63
BSAM 80
QISAM 89
QSAM 106
checkpoint data set 25
checkpoint records, embedded (DOS)
BSAM 80
CNTRL macro 41

Index 245

,11
" / i'
(

, I,'

device capacities 221-222
device types in a dummy section 110
direct data set
(see BDAM)
direct search option
BSAM 80
QSAM 106
directory, partitioned data set
creation 59
obtaining contents with BLDL 9
operations performed by STOW macro 179
search by FIND macro 115
disposition option
CLOSE macro 34
OPEN macro 134
requirement for extending an ISAM data set 145
DISP option
(see disposition option)
DOS embedded checkpoint records
BSAM 80
CNTRL macro 41
POINT macro 141
QSAM 107
doubleword alignment
(see BFALN operand)
DSECT for
DCB symbolic names 109
testing for open data set 134
DSORG operand (DCB macro)
BDAM 48
BISAM 55
BPAM 62
BSAM 77
DCBD macro 109
QISAM 86
QSAM 103
dummy data block (BDAM) 191-193
dummy section
(see DSECT)
dynamic buffering
effect on buffer length 47,54
effect on number of channel programs 56
requesting in READ macro 152,155
requesting in WRITE macro 196
returning buffer to the pool 119,191

EBCDIC
(see extended binary coded decimal interchange code)
ECB
(see event control block)
eliminate mode, read column
BSAM 74,76
QSAM 100
embedded checkpoint records (DOS)
BSAM 80
CNTRL macro 41
POINT macro 141
QSAM 107
end of data
(see EODAD operand)
end of file on magnetic tape, ignoring
BSAM 80
QSAM 107

248 OS!VS Data Management Macro Instructions

end of volume
forced 113
exit
BSAM 77
QSAM 104
end of sequential retrieval 111
entry to
exit routine 223
SYNAD routine 215-217
EODAD operand (DCB macro)
BPAM 62
BSAM 77
QISAM 86
QSAM 103
EROPT operand (DCB macro) 103
ERP (error recovery procedure)
BSAM 81
QSAM 106
error analysis, I/O
BDAM 52,209-217
BISAM 57,.209-217
BPAM 64,209-217
BSAM 82,209-217
QISAM 90,209-217
QSAM 108,209-217
SYNADAF macro 183,209-217
error codes
(see return codes)
error conditions while opening a data set 135
error exits
GET macro 126
PUT macro 146,148
PUTX macro 149
error option operand (QSAM) 103
error recovery procedure
(see ERP)
error tape, reading
(see ERP)
ESETL macro instruction 111
event control block 209
exception code 209-215
exchange buffering
buffer alignment for 94
restrictions
record format 94
track overflow feature 108,94
variable-length spanned records 108
specified in DCB 94
exclusive control of data block (BDAM)
requesting of 151
releasing of 165
specified in DCB 51
execute form instructions
BUILDRCD macro 21
CHKPT macro 31
CLOSE macro 39
OPEN macro 139
READ macro 163
SETPRT macro 177
WRITE macro 205
exit
(see also EXLST operand)
block count 77,104
data control block
(see EXLST operand)

(

)

D-format records (Continued)
QSAM 107
data block
exclusive con trol of 151
locating with POINT macro 141
release of exclusive control 165
retrieval 151-159,123-126
writing 191-201,145-149
data checks
blocking and unblocking 80-106
restriction with CNTRL macro 41
data control block
completing 133
construction
(see DCB macro instruction)
DCBBLKCT field 42
DCBEXCD 1 field 209
DCBEXCD2 field 209
DCBNCRHI field 56
DCBOFLGS field 135
DCBPRECL field 148
description
(see DCB macro instruction)
dummy section for 109
exception codes 209
exit list
(see EXLST operand)
restoring 133
special options with BLDL macro 9
symbolic references to 109
data, end of
(see EODAD operand)
data definition statement
(see DD statement)
data event control block
checking for I/O errors 23
construction 151-161,191-203
description 209
exception code 209
extended search option 50
modifying with execute form 163,205
requirement with CHECK macro 23
requirement with FREEDBUF macro 119
data management parameter list 39,139
data mode
GET macro 125-126
PUT macro 147-148
data protection image (DPI) 74,101
data set
blocksize for SYSOUT 68,95
closing 33
connecting to 133
disconnecting from 33
disposition at close 34
labels 33,133
opening 133
organization
(see DSORG operand)
temporary closing 33
types
(see access methods)
data translation
(see code conversion)

data transmittal modes
data 125-126,147-148
locate 123-126,145-148
move 145-148,123-126
specified in DCB 87,105
substitute 125-126,147-148
DCB ABEND exit
BDAM 49
BISAM 55
BPAM 62
BSAM 77
list format 223
QISAM 86
QSAM 104
DCB macro instruction
BDAM 45-52
BISAM53-58
BPAM 59-66
BSAM 67-82
QISAM 83-91
QSAM 93-108
DCB operands
description
(see DCB macro instruction)
symbolic names for 109
DCBD macro instruction
description 109
used to test for open data set 134
DDNAME operand (DCB macro)
BDAM 48
BISAM 54
BPAM 61
BSAM 70
QISAM 86
QSAM 97
DD statement, relationship to
data control block
(see DDNAME operand)
NOTE macro 131
OPEN macro 133
POINT macro 141
DEB validity checking 133
deblocking records
BDAM 45,52
BPAM 59,64
BSAM 67,81
QISAM 90,145
QSAM 107-108,147
DECB
(see data event control block)
deferred checkpoint restart 25
delete option
description 89
effect on sequential retrieval 169
density, recording (see DEN operand)
DEN operand (DCB macro)
BSAM 72
QSAM 98
DEVD operand (DCB macro)
BSAM 71-77
DCBD macro 110
QSAM 107-108,147
device addressing, types of (BDAM) 50

Index 247

exit (Continued)
end of data
(see EODAD operand)
end of volume 77,104
error analysis
(see error analysis, I/O)
FCB image 77,104
list format 223
user labeling 77,104
user totaling 77,104
EXLST operand (DCB macro)
BDAM 49
BISAM 55
BPAM 62
BSAM 77
list format 223
QISAM 86
QSAM 104
expression
absolute (absexp) 4
relocatable (relexp) 4
extended binary coded decimal interchange code
ASCII translation
Check routine 23
DCB option 80,106
Get routine 125
Put routine 147
Write routine 197
XLATE macro 207
paper tape translation
ISAM 73
QSAM 99
extended search option
LIMCT operand 49
OPTCD operand 51

F-format records
(see RECFM operand)
FCB image (SETPRT macro) 172
exit 77,104
list format 223
operand (SETPRT macro) 172
feedback
block position 151,193
next address 150,200
FEOV macro instruction 113
file, end of
(see end of file)
final volume positioning 33,133
FIND macro instruction 115
fixed-length records
(see BLKSIZE operand; RECFM operand)
format
exit list 223
page 143
record
BDAM 52
BPAM 64
BSAM 81
QISAM 90
QSAM 107
forms alignment 172

forms control buffer
description 172
exit 223
image. 172
forward space 43,41
FREEBUF macro instruction
description 117
relationship to GETBUF macro 127
FREEDBUF macro instruction
description 119
used with BDAM 191
used with BISAM 55
FREEPOOL macro instruction
description 121
relationship to CLOSE macro 33
relationship to GETPOOL macro 129
restriction on buffer alignment 121
Friden 8-track paper tape code
BSAM 73
QSAM 99
full-track-index write operation 89
fullword boundary alignment
(see BFALN operand)
FUNC operand (DCB macro)
BSAM 74,76
QSAM 100

GET macro instruction
ASCII translation 125
data mode (QSAM) 105,125
locate mode
QISAM 83,123
QSAM 105,125
used with PUTX macro 147
move mode
QISAM 83,123
QSAM 105,125
restriction when using CNTRL macro 41
restriction when using paper tape 105
relationship to
EODAD
(see EODAD operand)
RELSE 167,105
SETL 169
specified in DCB macro
QISAM 83
QSAM 105
substitute mode (QSAM) 105,126
Get routine exits 125
GETBUF macro instruction
description 127
relationship to
BUILD macro 15
BUILDRCD macro 17
FREEBUF macro 117
GETPOOL macro instruction
description 129
relationship to
BUFCB
(see BUFCB operand)

Index 249

GETPOOL macro instruction (Continued)
BUFL (see BUFL operand)
BUFNO (see BUFNO operand)
FREEPOOL macro 121

a
IEBPTPCH utility program 1
IHADCB dummy section 109
image
FCB (forms control buffer) 172
UCS (universal character set) 172
image, data protection
BSAM 74
QSAM 100
image mode, card
BSAM 74
QSAM 100
independent overflow area 89
index
cylinder 89
highest level
address of 56
size of 56
master
number of tracks per level 89
specified in MACRF operand (DCB macro) 89
space allocation for 83
indicators, status 209-217
INOUT open option 134
INPUT open option 134
input data sets
basic access methods
BDAM 151
BISAM 155
BPAM 157
BSAM (read a direct data set) 159
BSAM (read a sequential data set) 157
closing 133
opening 33
queued access methods
QISAM 123
QSAM 125
READ or GET specified in DCB
BDAM 50
BISAM 55
BPAM 63
BSAM 79
QISAM 87
QSAM 105
testing completion of I/O operations 23
input/output devices
2540 card punch 96
card reader and card punch 41
control of 41
magnetic tape 41
printer
CNTRL macro 41
PRTOV macro 143
input/output error analysis
BDAM 52,209-217
BISAM 57,209-217

250 OS!VS Data Management Macro Instructions

BPAM 64,209-217
BSAM 81,209-217
QISAM 90,209-217
QSAM 108,209-217
SYNADAF macro 183,209-217
input/output operation
completion of 23
status indicators 209-217
synchronizing I/O 23
interface, logical record
invoked by BUILDRCD macro
specified in DCB macro
BDAM 46
BSAM 68
QSAM 94
used with GET macro 126
used with PUT macro 147

II
job control language
DD statement, relationship to DCB
data control block
(see DDNAME operand)
NOTE macro 131
OPEN macro 133
POINT macro 141
DISP parameter for extending ISAM 145
LABEL parameter to request ASCII translation 23
SP ACE parameter for ISAM 83
job step checkpoint restart 25

II
key, dummy (BDAM)
search for 191
specified in DCB macro 51
writing 199
key length
(see KEYLEN operand)
key position, relative (RKP) 90
key, record
PUT macro 145
READ macro 151-159
RKP operand (DCB macro) 90
SETL macro 169
WRITE macro 191-201
KEYLEN operand (DCB macro)
BDAM 49
BPAM 62
BSAM 78
QISAM 87

II
label
(see also EXLST operand)
exit list format 223

label (Continued)
input data set 133,113
output data set
CLOSE macro 33
FEOV macro 113
OPEN macro 133
LABEL parameter in DD statement 23
LEAVE option
CLOSE macro 33
FEOV macro 113
OPEN macro 133
length
buffer
(see BUFL operand)
record
(see LRECL operand)
levels of master index (ISAM) 88
LIMCT operand (DCB macro) 49
line spacing, printer
CNTRL macro 41
PRTSP operand (DCB macro)
BSAM 73
QSAM 99
list
directory contents (BLDL macro) 9
relative address (FIND macro) 115
variable-length parameter 37,13 7
list address, data management 39,139
list format, exit 223
list form instructions
BUILDRCD macro 19
CHKPT macro 29
CLOSE macro 37
OPEN macro 137
READ macro 161
SETPRT macro 175
WRITE macro 203
load mode (QISAM) 83
loading
universal character set buffer (UCS) 172
forms control buffer (FCB) 172
locate mode
GET macro
QISAM 123
QSAM 125
PUT macro
QISAM 145
QSAM 147
specified in DCB macro
QISAM 87-88
QSAM 105
logical record length for
(see also LRECL operand)
GET macro 123,125
PUT macro 145,147
PUTX macro 149
lower limit of sequential retrieval (SETL macro) 169
LRECL operand (DCB macro)
BPAM 62
BSAM 78
QISAM 87
QSAM 104

II
machine control characters
BPAM 63
BSAM 80
description 225
QSAM 107
MACRF operand (DCB macro)
BDAM 50-51
BISAM 55
BPAM 63
BSAM 79
QISAM 87
QSAM 105
macro
definition 1
expansion 1,4
library 1
macro instruction coding 2
magnetic tape
backspace
BSP macro 13
CNTRL macro 42
density 72,98
end-of-file, ignored 81,107
final volume positioning (FEOV macro) 113
forward space 42
read backward 157
recording technique 72,98
restriction when using NOTE macro 131
restriction when using POINT macro 141
short error recovery procedure 80,106
master index
number of tracks per level 89
option specified in DCB 89
highest level in storage
address of storage area 56
size of storage area 57
member, partitioned data set
complete a list with BLDL macro 9
locate beginning with FIND macro 115
update directory with STOW macro 179
mode
(see also MACRF operand)
card image
BSAM 74
QSAM 100
data (QSAM) 125,147
load (QISAM) 83
locate
QISAM 123,145
QSAM 125,147
move
QISAM 123,145
QSAM 125,147
optical mark read
BSAM 76
QSAM 101
read column eliminate
BSAM 74,76
QSAM 100

Index 251

mode (Continued)
scan (QISAM) 83,123
substitute (QSAM) 125,147
MODE operand (DCB macro)
BSAM 74
QSAM 100
modifying a parameter list
BUILDRCD macro 19
CLOSE macro 37
OPEN macro 137
READ macro 161
SETPRT macro 175
WRITE macro 203
move mode
QISAM 123,145
QSAM 125,147
MSHI operand (DCB macro) 56
MSW A operand (DCB macro) 56
multiline print option
BSAM 75
QSAM 101

•

National Cash Register 8-track paper tape code
BSAM 73
QSAM 99
NCP operand (DCB macro)
BISAM 56
BPAM 63
BSAM 79
next address feedback
BDAM (creating) 200
RDAM- (existing) 153
non sequential processing of sequential data 67
NOTE macro instruction
description 131
restriction when using BSP macro 13
specified in DCB for BSAM 79
used with BPAM 63
NTM operand (DCB macro) 88
number of channel programs
(see NCP operand)
number of tracks per index level
(see NTM operand)

online printer
control 4143
skipping 143,225
spacing 143,225
open operation, testing 135
open options 133-134
OPEN macro instruction
execute form 139
list form 137
relationship to
CLOSE, TYPE=T 33-35
FEOV macro 113

252 OSNS Data Management Macro Instructions

GETPOOL macro 129
NOTE macro 131
POINT macro 141
standard form 133
operand, substitution for 24
OPTCD operand (DCB macro)
BDAM 51
BPAM 63
BSAM 80
QISAM 89
QSAM 106
SETPRT macro 172
optical mark read mode
BSAM 76
QSAM 101
option codes
(see OPTCD operand)
organization, data set
(see access methods)
OUTIN open option 134
output data sets
basic access methods
BDAM (creating with BSAM) 199
BDAM (existing) 191
BPAM 197
BSAM 197
closing 133
opening 33
queued access methods
QISAM 145
QSAM 147
WRITE or PUT specified in DCB macro
BDAM 50
BPAM 63
BSAM 79
QISAM 88
QSAM 105
writing an input record in an output data set using PUTX 147
output header labels
BSAM 77
exit list format 223
QSAM 104
OUTPUT open option 134
output trailer labels
BSAM 77
exit list format 223
QSAM 104
overflow
area
cylinder 85,89
independent 88
channel 143
exit address (PRTOV macro) 143
printer carriage 143
records
(see overflow area)
overflow feature, track
BDAM 52
BPAM 64
BSAM 82
QSAM 108
overprinting 143

II
paper tape codes
BSAM 73
QSAM 99
parameter list construction
BUILD RCD macro 19
CHKPT macro 29
CLOSE macro 37
OPEN macro 137
READ macro 161
SETPRT macro 175
WRITE macro 203
parameter list, modification
BUILDRCD macro 21
CHKPT macro 31
CLOSE macro 39
OPEN macro 139
READ macro 163
SETPRT macro 177
WRITE macro 205
partitioned data set
general description 59
macro instructions used with 219
relationship to
BLDL macro 10
FIND macro 115
STOW macro 179
POINT macro instruction
description 141
relationship to
BSP macro 13
BPAM 63
BSAM 67
position, relative key (RKP) 90
position feedback
current block 151,193
next block 152,200
positioning volumes
using CLOSE macro 33
using FEOV macro 113
using OPEN macro 133
prefix, block
BSAM 70
QSAM 96
relationship to
buffer length 69,96
data alignment 67,93
printer options (3525)
BSAM 74
QSAM 100
printer
carriage control 41,225
character set buffer loading 172
control characters 225
control tape 143
forms control buffer loading 172
skipping 41,225
spacing 41,225
program, channel
BISAM 56
BPAM 63
BSAM 79

protect option, data
BSAM 74
QSAM 101
PRTOV macro instruction 143
PRTSP operand (DCB macro)
BSAM 73
QSAM 99
punch, card 74,100
PUT macro instruction
data mode (QSAM) 148
locate mode
QISAM 145
QSAM 148
move mode
QISAM 146
QSAM 148
specified in DCB macro
QISAM 88
QSAM 105
substitute mode 146
PUTX macro instruction 88,149

QISAM (queued indexed sequential access method)
general description 83
macro instructions used with 219
QSAM (queued sequential access method)
general description 93
macro instructions used with 219
queued access technique
(see QISAM and QSAM)

II
RDBACK open option 134
readbackward, magnetic tape 157
read column eliminate mode
BSAM 74-76
QSAM 100
READ macro instruction
execute form 163
list form 161
relationship to
CHECK macro 23
EODAD operand 62,77
FIND macro 115
FREEDBUF macro 119
LIMCT operand 49
NCP operand
BISAM 56
BPAM 63
BSAM 79
POINT macro 141
RELEX macro 165
specified in DCB macro
BDAM 50
BISAM 55
BPAM 63
BSAM 79

Index 253

READ macro instruction (Continued)
standard form
BDAM 151
BISAM 155
BPAM 157
BSAM (read direct data set) 159
BSAM (read sequential data set) 157
RECFM operand (DCB macro)
BDAM 52
BPAM 64
BSAM 81
QISAM 90
QSAM 107
record
area
construction 17,94-95
use of 90-91
deletion option (ISAM) 89
descriptor word
(see LRECL operand)
format
(see RECFM operand)
length
(see LRECL operand)
logical
GET 123,145
PUT ]45,147
physical
(see BLKSIZE operand)
retrieval 123,145
segment 145,147
variable-length, spanned 17,94
writing 145,147
recording density, magnetic tape
BSAM 72
QSAM 98
recording technique, magnetic tape
BSAM 72
QSAM 98
recovery procedUre, error
(see ERP)
register
contents on entry to
DCB exit routine 223
overflow exit routine 143
SYNAD routine 215-216
DCBD base 109
usage rules 4
relative addressing
BDAM 51,45
BLDL macro 10
FIND macro 115
POINT macro 141
relative key position 90
release
buffer 117
buffer pool 121
dynamically acquired buffer 119
exclusive control 165
QSAM buffer 167
RELEX macro instruction 165
relexp defined 4
relocatable expression defined 4
RELSE macro instruction 167
reorganization statistics (lSAM) 89,83

254 OS/VS Data Management Macro Instructions

REREAD option
CLOSE macro 33
FEOV macro 113
OPEN macro 134
restart job from a checkpoint
automatic 25
deferred 25
restore data control block 33
return codes
BLDL macro 11
BSP macro 13
CHKPT macro 27-28
FIND macro 116
RELEX macro 165
SETPRT macro 173
STOW macro 181
SYNADAF macro 184
SYNADRLS macro 187
WRITE macro 201
return from error analysis rou tine
BDAM 52
BISAM 57
BPAM 64
BSAM 82
QISAM 90
QSAM 108
REWIND close option 33
RKP operand (DCB macro 90

save area
general register requirements 4
SYNADAF requirement 183
SYNADRLS macro 187
search
partitioned data set directory
BLDL macro 9
FIND macro 115
type of
BDAM 191
QISAM 87
search argument
BDAM 51
QISAM 87
search direct option 80,106
search option, ex tended 51,49
segment
descriptor word 159,147
interface 159
work area 48
sequential access methods
(see access methods)
services, optional
BDAM 51
BPAM 63
BSAM 80
QISAM 89
QSAM 106
SETPRT macro 172
SETL macro instruction
description ] 69
ESETL macro III

SETL macro instruction (Continued)
GET macro 123
SETPRT macro instruction
execute form 177
list form 175
standard form 171
simple buffering 94
skipping, printer
(see also spacing, printer)
CNTRL macro 41
control characters 225
SMSI operand (DCB macro) 56
SMSW operand (DCB macro) 53
space allocation, data set
BPAM 59
QISAM 83
space, magnetic tape
backward 13,41
forward 41
spacing, printer
(see also skipping, printer)
CNTRL macro 41
control characters 225
specified in DCB macro
BSAM 73
QSAM 99
STACK operand (DCB macro)
BSAM 74
QSAM 100
stacker selection
CNTRL macro 41
control characters 225
specified in DCB macro
BSAM 74
QSAM 100
statistics reorganization (lSAM) 89
status
following an I/O operation 209-217
indicators 217
STOW macro instruction 179
substitute mode
GET macro 125
PUT macro 147
specified in DCB macro 105
switching volumes
CLOSE macro 33
FEOV macro 113
symbol defined 3
SYNAD operand (DCB macro)
(see also error analysis, I/O)
BDAM 52
BISAM 57
BPAM 64
BSAM 82
QISAM 90
QSAM 108
SYNADAF macro instruction 183
SYNADRLS macro instruction 187
synchronizing I/O operations 23
synchronous error exit
(see SYNAD operand)
SYSIN restrictions
CNTRL macro 41

DEVD operand (DCB macro)
BSAM 71
QSAM 97

•

tape codes, paper
BSAM 73
QSAM 99
tape density, magnetic
BSAM 72
QSAM 96
tape error recovery procedure
BSAM 80
QSAM 106
tape recording technique
BSAM 72
QSAM 96
Teletype 5-track paper tape code
BSAM 73
QSAM 99
temporary close of data set 33
termination, abnormal
Check routine 23
end of data
(see EODAD operand)
uncorrectable I/O error
(see SYNAD operand)
testing completion of I/O 23
testing for open data set 135
totaling exit, user
BSAM 77
list format 223
QSAM 104
track addressing, relative
BDAM 51,45
BLDL macro 10
FIND macro 115
POINT macro 141
track index write, full 89
track overflow feature
BDAM 52
BPAM 64
BSAM 82
QSAM 108
restrictions
chained scheduling 64,108
exchange buffering 94,108
ISAM 83
variable-length, spanned records 108
translation
ASCII to EBCDIC
CHECK macro 23
GET macro 125
XLATE macro 207
EBCDIC to ASCII
PUT macro 147
WRITE macro 197
XLATE macro 207
paper tape code 73,99
transmittal modes
(see also MACRF operand)

Index 255

transmittal modes (Continued)
data 125,147
locate 123-125,145-147
move 123-125,145-147
substitute 125-147
TR TCH operand (DCB macro)
BSAM 72
QSAM 98
TRUNC macro instruction 189
truncating a block 189
TYPE=T (BSAM CLOSE macro) 33-35

II
U-format records
BDAM 52
BPAM 64
BSAM 82
QSAM 108
UCS operand (SETPRT macro) 172
unblocking data checks
BSAM 80
QSAM 106
SETPR T macro 172
uncorrectable I/O errors
(see SYNAD operand)
undefined length records
(see U-format records)
universal character set
(see UCS operand)
unmovable data sets
(see DSORG operand)
UPDA T open option 134
updating partitioned data set directory 179
user
data in partitioned data set directory
BLDL macro 10
STOW macro 179
label exit
BSAM 77
list format 223
QSAM 104
totaling exit
BSAM 77
list format 223
QSAM 104
USING statement requirement
DCBD macro 109
macro expansions 4

II
V-format records
BDAM 52
BPAM 64

256 OS/VS Data Management Macro Instructions

BSAM 82
QISAM 90
QSAM 108
validity checking, write
BDAM 51
BPAM 63
BSAM 81
QISAM 89
QSAM 106
variable-length parameter list 37,13 7
variable-length records
(see V-format records)
variable-length, spanned records
BDAM 46,199
BSAM 68,199
QSAM 94,147
volume, forcing end of 113
volume positioning
CLOSE macro 33
FEOV macro 113
OPEN macro 123
POINT macro 141

II
work area for BISAM
address of 56
size of 56
WRITE macro instruction
execute form 205
list form 203
relationship to
CHECK macro 23
NCP operand
BISAM 56
BPAM 63
BSAM 79
RELEX macro 165
specified in DCB macro
BDAM 50
BlSAM 56
BPAM 63
BSAM 79
standard form
BDAM (create with BSAM) 199
BDAM (existing) 191
BISAM 195
BPAM 197
BSAM 197
testing for completion 23

II
XLATE macro instruction 297

READER'S COMMENT FORM
OSNS Data Management Macro Instructions

GC26-3793-1

Your comments about this publication will help us to produce better publications for your use. If
you wish to comment, please use the space provided below, giving specific page and paragraph
references.
Please do not use this form to ask technical questions about the system or equipment or to make
requests for copies of publications. Instead, make such inquiries or requests to your IBM representative or to the IBM Branch Office serving your locality.

Reply requested
Yes
No

D
D

Name
Job Title
Address
_ _ _ _ _ _ _ _ _ _ _ _ _ _ Zip _ _ _ _ _ _ _ _ _ _ _ __

No postage necessary if mailed in the USA

GC26-3793-1

YOUR COMMENTS, PLEASE . ..
This publication is one of a series which serves as a reference source for systems analysts,
programmers, and operators of IBM systems. Your answers to the questions on the back of
this form, together with your comments, will help us produce better publications for your
use. Each reply will be carefully reviewed by the persons responsible for writing and
publishing this material. All comments and suggestions become the property of IBM.
Please note: Requests for copies of publications and for assistance in utilizing your IBM
system should be directed to your IBM representative or to the IBM sales office serving
your locality.

fold

FIRST CLASS
PERMIT NO. 2078
SAN JOSE, CALIF.

BUSINESS REPLY MAIL
NO POSTAGE STAMP NECESSARY IF MAILED IN U. S. A.,

POSTAGE WILL BE PAID BY . .

IBM Corporation
Monterey & Cottle Rds.
San Jose, California
95114

Attention: Programming Publications, Dept. D78

fold

Intematlonal Bualne.. Machlnea Corporation
Data Proce..lng Dlvlalon
1133 Weatcheater Avenue, White Plalna, New York 10604
(U.S.A. only)
IBM World Trade Corporation
821 United Natlona Plaza, New York, New York 10017
(lnternatlonaQ

fold

GC26-3793-1

International Business Machines Corporation
Data Proce..lng Division
1133 Westchester Avenue, White Plains, New York 10604
(U.s.A. only)
IBM World Trade Corporation
821 United Nations Plaza, New York, New York 10017
(International)

Technical Newsletter
Base Publication Number

GC26-3793-1

This Newsletter Number

GN26-0748

December 15, 1972

Date

Previous Newsletter Number (s) None

OS/VS DATA MANAGEMENT MACRO INSTRUCTIONS

(£)

IBM Corp. 1972

This technical newsletter, a part of Release 2 of OS/VS 1, provides replacement pages for the subject
publication. These pages remain in effect for subsequent releases unless they are specifically altered.
Pages to be inserted and removed are:
cover-2
27,28
33,34
41-46
53,54

59-62.1 (62.1 added)
67-86
93-108 (104.1 added)
113
133,134

143,144
157,158
211,212
221,222
231,232

Each technical change is marked by a vertical line to the left of the change.

Summary of Changes
Changes to the system are summarized under "OS/VSl Summary of Changes" following the Preface.
VSl Release 2 supports four new devices and one new function.
The 3505 Card Reader and the 3525 Card Punch are now supported by VS1; the macro instructions
affected by this change are CLOSE, CNTRL, DCB (BSAM and QSAM), OPEN, and PRTOV.
The 2305-1 Drum Storage and the new 3333 Disk Storage are also supported by VS1; capacity data for
these devices has been added to the tables in Appendix C.
DEB validity checking, a data protection feature formerly supported only by VS2, is now supported by
VS1; this change affects the OPEN macro instruction.
In addition to these major changes, miscellaneous other changes were made to:
• Describe register contents upon entry to an EO DAD routine (DCB macro instruction for BPAM, BSAM,
QISAM, and QSAM).
• Restrict use of the temporary close (TYPE=T) option in a SYNAD routine (CLOSE macro
instruction) .
• Expand the description of the LEAVE option (FEOV macro instruction for BSAM and QSAM).
• Define a new return code for the CHKPT macro instruction.
.
• Delete tape labels as a source of buffer alignment (BF ALN) data (DCB macro instruction for all
access methods).

Note: Please file this cover letter at the back of the publication to provide a record of changes.
IBM Corporation, Programming Center-Publishing, Monterey and Cottle Roads, San Jose, California 95114
PRINTED IN USA

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Create Date                     : 2013:03:12 12:56:16-08:00
Modify Date                     : 2013:03:12 16:58:03-08:00
Metadata Date                   : 2013:03:12 16:58:03-08:00
Producer                        : Adobe Acrobat 9.52 Paper Capture Plug-in
Format                          : application/pdf
Document ID                     : uuid:1e79e1ff-0c7f-42ac-8de2-785b0cabe69c
Instance ID                     : uuid:c8e54988-4339-43a8-adef-518cea49cf8f
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 280

EXIF Metadata provided by EXIF.tools

GC26 3793 1_OS_VS_Data_Management_Macro_Instructions_Sep72 1 OS VS Data Management Macro Instructions Sep72

Navigation menu

Versions of this User Manual:

Views

Navigation