Digital PDFs

AA-5057B-TK

August 1981

521 pages

Original

17MB

Document:	COBOL-68 Language Manual Aug81
Order Number:	AA-5057B-TK
Revision:	0
Pages:	521
Original Filename:	AA-5057B-TK_COBOL-68_Language_Manual_Aug81.pdf

OCR Text

TOPS-10/TOPS-20
COBOL-68
Language Manual
AA-SOS7B-TK

August 1981

This manual reflects the software of Version 12B of the
COBOl-68 compiler, Version 12B of LlBOl, and Version 4C
of SORT.
This manual replaces the document of the order numbers
AA-505? A-TK, AD-505? A-T1, and AD-5057 A-T2
OPERATING SYSTEM:

TOPS-10, Version 7.01
TOPS-20, Version 4

SOFTWARE VERSION:

COBOl-68, Version 12B
LlBOl, Version 12B

Software and manuals should be ordered by title and order number. In the United States, send orders to the nearest
distribution center. Outside the United States, orders should be directed to the nearest DIGITAL Field Sales Office
or representative.
NORTHEAST/MID-ATLANTIC REGION

CENTRAL REGION

WESTERN REGION

Technical Documentation Center
Cotton Road
Nashua, N H 03060
Telephone: (800) 258-1710
New Hampshire residents: (603) 884-6660

Technical Documentation Center
1050 East Remington Road
Schaumburg, Illinois 60195
Telephone: (312) 640-5612

Technical Documentation Center
2525 Augustine Drive
Santa Clara, California 95051
Telephone: (408) 984-0200

digital equipment corporation • marlboro, massachusetts

First Printing, August 1969
Updated, May 1979
January 1980
Revised, August 1981

The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this dopument is furnished under a license
and may only be used or copied in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

~, 1969, 1979, 1980, 1981, Digital Equipment Corporation.
All Rig~ts Reserved.

The postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in
preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DECUS
Digital Logo
PDP
UNIBUS
VAX

DECnet
DECsystem-10
DECSYSTEM-20
DECwriter
DIBOL
EduSystem

lAS
MASSBUS
PDT
RSTS
RSX
VMS
VT

CONTENTS

Page
1

INTRODUCTION TO COBOL-68 LANGUAGE

1-1

1.1
1.1.1
1.1.2
1.2
1.2.1
1.2.2
1.2.3
1.2.3.1
1.2.3.2
1.2.4
1.2.4.1
1.2.4.2
1.2.5
1.3
1.3.1
1.3.2
1.3.2.1
1.3.2.2
1.4
1.4.1

SYMBOLS AND TERMS
Symbols
COBOL Terms
ELEMENTS OF COBOL LANGUAGE
Program Structure
Character Set
Words
COBOL Reserved Words
User-Created Words
Literals
Numeric Literals
Alphanumeric Literals
Punctuation
SOURCE PROGRAM FORMAT
Card-Type Format
Terminal-Type Format
With Line Numbers
without Line Numbers
THE COBOL LIBRARY FACILITY
The COPY Statement

1-1
1-1
1-2
1-3
1-3
1-3
1-4
1-4
1-6
1-7
1-7
1-8
1-8
1-9
1-10
1-11
1-11
1-12
1-15
1-15

CHAPTER

THE IDENTIFICATION DIVISION

2-1

CHAPTER

THE ENVIRONMENT DIVISION

3-1

3.1
3.1.1
3.1.2
3.1.3
3.2
3.2.1
3.2.1.1
3.2.1.2
3.2.1.3
3.2.1.4
3.2.1.5
3.2.1.6
3.2.1.7
3.2.1.8
3.2.1.9
3.2.1.10
3.2.2

CONFIGURATION SECTION
SOURCE-COrvIPUTER
OBJECT-COMPUTER
SPECIAL-NAMES
INPUT-OUTPUT SECTION
FILE-CONTROL
SELECT
FOR MULTIPLE
RESERVE
FILE-LIMIT
ACCESS MODE
PROCESSING MODE
ACTUAL KEY
SYMBOLIC KEY
RECORDING MODE/DENSITY/PARITY
FILE STATUS
I-O-CONTROL

3-2
3-3
3-4
3-6
3-9
3-10
3-12
3-14
3-15
3-16
3-18
3-20
3-21
3-22
3-23
3-27
3-35

THE DATA DIVISION

4-1

4.1
4.2

FILE SECTION
SCHEMA SECTION

4-2
4-2

CHAPTER

iii

CONTENTS (CONT.)

Page
COMMUNICATION SECTION
WORKING-STORAGE SECTION
LINKAGE SECTION
REPORT SECTION
DATA DESCRIPTIONS
Elementary Items and Group Items
Level Numbers
Records and Files
QUALIFICATION
SUBSCRIPTING AND INDEXING
FILE DESCRIPTION (FD)
BLOCK CONTAINS
DATA RECORD
FD file-name
LABEL RECORD
RECORD CONTAINS
REPORT
SD file-name
VALUE OF
IDENTIFICATION/DATE-WRITTEN/USER-NUMBER
4.11
RECORD DESCRIPTIONS
4.11.1
Record Concepts
4.11.2
DATA DESCRIPTION ENTRY
4.11.2.1
BLANK WHEN ZERO
4.11.2.2
Condition-name (level-88)
4.11.2.3
data-name/FILLER
JUSTIFIED
4.11.2.4
4.11.2.5
level-number
OCCURS
4.11.2.6
4.11.2.7
PICTURE
REDEFINES
4.11.2.8
RENAMES (level-66)
4.11.2.9
4.11.2.10
SYNCHRONIZED
USAGE
4.11.2.11
VALUE
4.11.2.12
4.12
REPORT SECTION
4.12.1
Report Description (RD)
4.12.1.1
CODE
4.12.1.2
CONTROL(S)
4.12.1.3
PAGE LIMIT
4.12.2
Report Group Description
4.12.2.1
COLUMN
4.12.2.2
GROUP INDICATE
4.12.2.3
LINE NUMBER
4.12.2.4
NEXT GROUP
4.12.2.5
RESET
4.12.2.6
SOURCE
4.12.2.7
SUM
4.12.2.8
TYPE

4-3
4-3
4-3
4-4
4-5
4-5
4-5
4-6
4-6
4-7
4-11
4-13
4-14
4-15
4-16
4-18
4-19
4-20

THE PROCEDURE DIVISION

5-1

5.1

SYNTACTIC FORMAT OF THE PROCEDURE
DIVISION
Statements and Sentences
Sentences

5-2
5-2
5-3

4.3
4.4
4.5
4.6
4.7
4.7.1
4.7.2
4.7.3
4.8
4.9
4.10
4.10.1
4.10.2
4.10.3
4.10.4
4.10.5
4.10.6
4.10.7
4.10.8

CHAPTER

5.1.1
5.1.2

4-21
4-24
4-24
4-25
4-27
4-28
4-30
4-31
4-33
4-34
4-36
4-49
4-51
4-53
4-55
4-62
4-64
4-66
4-68
4-69
4-70
4-72
4-75
4-76
4-77
4-79
4-80
4-81
4-82
4-83

CONTENTS (CONT.)

Page
5.1.3
5.1.4
5.2
5.3
5.4
5.4.1
5.4.2
5.5
5.5.1
5.5.1.1
5.5.1.2
5.5.1.3
5.5.1.4
5.5.2
5.5.2.1
5.5.2.2
5.5.2.3
5.5.2.4
5.5.3
5.5.3.1
5.5.4
5.5.4.1
5.5.5
5.5.5.1
5.5.6
5.5.7
5.5.8
5.6
5.6.1
5.7
5.8
5.9
5.9.1
5.9.2
5.9.3
5.9.4
5.9.5
5.9.6
5.9.7
5.9.8
5.9.9
5.9.10
5.9.11
5.9.12
5.9.13
5.9.14
5.9.15
5.9.16
5.9.17
5.9.18
5.9.19
5.9.20
5.9.21

Paragraphs
Sections
SEQUENCE OF EXECUTION
SEGMENTATION AND SECTION-NAME PRIORITY
NUMBERS
ARITHMETIC EXPRESSIONS
Arithmetic Operators
Formation and Evaluation Rules
CONDITIONAL EXPRESSIONS
Relation Condition
Format of a Relation-Condition
Relational Operators
Comparison of Numeric Items
Comparison of Alphanumeric Items
Class Condition
Format of a Class Condition
Restrictions
The ALPHABETIC Test
The NUMERIC Test
Condition-Name Condition
Format of a Condition-Name
Switch-status Condition
Format of a Switch-Status Condition
Sign Condition
Format of a Sign Condition
Logical Operators
Formation and Evaluation Rules
Abbreviations in Relation Conditions
COMMON OPTIONS ASSOCIATED WITH THE
ARITHMETIC VERBS
The ON SIZE ERROR Option
THE CORRESPONDING OPTION
DETERMINATION OF USAGE IN ARITHMETIC
COMPUTATIONS
PROCEDURE DIVISION VERB FORMATS
ACCEPT
ADD
ALTER
CALL
CANCEL
CLOSE
COMPUTE
DELETE
DISPLAY
DIVIDE
ENTER
ENTRY
EXAMINE
EXIT
EXIT PROGRAM
FREE
GENERATE
GO TO
GOBACK
IF
INITIATE

5-4
5-4
5-5
5-5
5-6
5-6
5-6
5-7
5-7
5-8
5-8
5-8
5-9
5-9
5-10
5-10
5-10
5-10
5-10
5-10
5-11
5-11
5-11
5-12
5-12
5-12
5-15
5-16
5-16
5-17
5-17
5-19
5-20
5-22
5-24
5-25
5-27
5-28
5-31
5-32
5-33
5-34
5-36
5-37
5-38
5-40
5-41
5-42
5-45
5-47
5-48
5-49
5-51

CONTENTS (CONT • )

Page
5.9.22
5.9.23
5.9.24
5.9.25
5.9.26
5.9.27
5.9.28
5.9.29
5.9.30
5.9.31
5.9.32
5.9.33
5.9.34
5.9.35
5.9.36
5.9.37
5.9.38
5.9.39
5.9.40
5.9.41
5.9.42
5.9.43
5.9.44
5.9.45

MERGE
MOVE
MULTIPLY
NOTE
OPEN
PERFORM
READ
RELEASE
RETAIN
RETURN
REWRITE
SEARCH
SEEK
SET
SORT
STOP
STRING
SUBTRACT
SUPPRESS
TERMINATE
TRACE
UNSTRING
USE
WRITE

5-52
5-54
5-56
5-58
5-59
5-64
5-69
5-71
5-72
5-78
5-79
5-80
5-83
5-84
5-85
5-88
5-89
5-94
5-96
5-97
5-98
5-100
5-109
5-113

CHAPTER

COMPILING COBOL-68 PROGRAMS

6-1

CHAPTER

COBOL UTILITY PROGRAMS

7-1

7.1

ISAM - INDEXED-SEQUENTIAL FILE
MAINTENANCE PROGRAM
Building An Indexed-Sequential File
Maintaining An Indexed-Sequential File
Packing An Indexed-Sequential File
Ignoring Errors
Reading And Writing Magnetic Tape
Labels
Renaming An Indexed-Sequential File
Checking An Indexed-Sequential File
Producing Blocking Data With ISAM
Indirect Commands
using Indexed-Sequential Files
LIBARY - PROGRAM TO CREATE AND MAINTAIN
SOURCE LIBRARIES
Library File Format
Invoking The Library utility
Command String Defaults
LIBARY Switches
Running LIBARY
LIBARY Commands
Group Mode Commands
LIBRARY-Directing Commands
Example of Command Usage
COBDDT - PROGRAM FOR DEBUGGING COBOL
PROGRAMS
Loading And Starting COBDDT

7.1.1
7.1.2
7.1.3
7 .1. 4
7.1.5
7.1.6
7.1.7
7 .1. 8
7.1.9
7.1.10
7.2
7.2.1
7.2.2
7.2.3
7.2.4
7.2.5
7.2.6
7.2.6.1
7.2.6.2
7.2.6.3
7.3
7.3.1

7-2
7-3
7-8
7-11
7-12
7-13
7-15
7-16
7-17
7-18
7-19
7-21
7-21
7-21
7-23
7-24
7-25
7-25
7-25
7-26
7-27
7-28
7-28

CONTENTS (CONT.)

Page
7.3.2
7.3.3

7-30

7.4.1
7.4.2

coaDDT Commands
Obtaining Histograms Of Program
Behavior
Initializing the Histogram Table
Starting the Histogram
Stopping the Histogram
Obtaining the Histogram Listing
Using the Histogram Feature
RERUN - PROGRAM TO RESTART COBOL
PROGRAMS
Operating RERUN
Examples Of Using RERUN

FILE FORMATS

8-1

8.1
8.1.1
8.1.2
8.1.3
8.1.4
8.2
8.2.1
8.2.2
8.2.3
8.2.4
8.2.5
8.2.6
8.2.6.1
8.2.6.2
8.2.6.3
8.3
8.4
8.5
8.5.1
8.5.2
8.6
8.6.1
8.6.2

RECORDING MODES
ASCII Recording Mode
SIXBIT Recording Mode
EBCDIC Recording Mode
BINARY Recording Mode
FILE FORMATS
Fixed-Length ASCII
Variable-Length ASCII
Fixed-Length SIXBIT .
Variable-Len~th SIXBIT
EBCDIC File Formats
BINARY File Formats
COBOL ASCII Mixed-Mode Binary
COBOL SIXBIT Mixed-Mode Binary
COBOL EBCDIC Mixed-Mode Binary
FILE ORGANIZATION AND ACCESS
SEQUENTIAL FILES
RANDOM FILES
Sequential Access Of Random Files
Random Access Of Random Files
INDEXED-SEQUENTIAL FILES
Indexed Data File
Index File

8-1
8-1
8-2
8-2
8-3
8-3
8-4
8-5
8-8
8-10
8-12
8-21
8-22
8-24
8-25
8-27
8-27
8-27
8-28
8-29
8-30
8-31
8-32

SIMULTANEOUS UPDATE

9-1

9.1
9.1.1
9.1.2
9.1.3
9.1.4
9.1.4.1
9.1.4.2
9.1.4.3
9.1.4.4
9.1.5
9.1.6

PROGRAMMING CONSIDERATIONS
The OPEN Statement
The RETAIN Statement
The FREE Statement
Accessing Sequential Files
Basic Reading
Basic writing
Basic Updating
Access to Sequential File Strategies
Accessing Random Files
Accessing Indexed-Sequential Files

9-3
9-4
9-7
9-10
9-11
9-11
9-12
9-12
9-12
9-15
9-16

CHAPTER

REPORT WRITER

10-1

CHAPTER

PROGRAM SEGMENTS, SUBPROGRAMS, AND
OVERLAYS

11-1

7.3.3.1
7.3.3.2
7.3.3.3
7.3.3.4
7.3.3.5
7.4

CHAPTER

vii

7-38
7-38
7-39
7-39
7-40
7-42
7-42
7-43
7-44

CONTENTS (CONT.)

Page

CHAPTER

11.1
11.1.1
11.1.2
11.2
11.2.1
11.2.1.1
11.2.1.2
11.2.2
11.2.3
11.2.4
11.3
11.3.1
11.3.2
11.3.3
11.3.4
11.3.5
11.3.6

PROGRAM SEGMENTS
Section-Names And Segment Numbers
Examples
SUBPROGRAMS
Inter-Program Communication
The Calling Program
The Called Subprogram
Loading A Subprogram Structure
Object Libraries And Searches
Examples
OVERLAYS
When To Use Overlays
Over1ayab1e COBOL Programs
Defining Overlays
The /SPACE Switch To LINK
The CANCEL Statement
Examples

11-1
11-1
11-2
11-3
11-4
11-4
11-5
11-6
11-6
11-7
11-8
11-8
11-9
11-9
11-11
11-14
11-14

CALLING NON-COBOL SUBPROGRAMS

12-1

12.1
12.2

CALLING FORTRAN SUBPROGRAMS
CALLING MACRO SUBPROGRAMS

12-2
12-3

IMPROVING PERFORMANCE OF COBOL-68
PROGRAMS

13-1

HOW TO PROCEED WITH PROGRAM OPTIMIZATION
Where To Begin
What Tools Are Available
What Method Or Procedure To Use
Evaluating Performance
Documentation
LISTING THE TOOLS
COBDDT
The ENTRIES Column
The CPU Column
ELAPSED Column
OVERHEAD
USING THE CORRECT DATA TYPE
DISPLAY Data Types
EBCDIC
ASCII
SIXBIT
COMPUTATIONAL
DATA EFFICIENCIES
Counter, Indexes, Subscripts
File Storage
Blocking Data
EFFICIENT CODING CONVENTIONS
Alignment
Use Of Subscripts
Incrementing Counters
The PERFORM Statement
Use Of The EXAMINE Statement
Data Movement

13-3
13-3
13-3
13-4
13-5
13-5
13-6
13-6
13-7
13-7
13-8
13-8
13-8
13-8
13-8
13-9
13-10
13-10
13-10
13-11
13-11
13-11
13-12
13-12
13-12
13-13
13-13
13-14
13-14

13.1
13.1.1
13.1.2
13.1.3
13.1.4
13.1.5
13.2
13.2.1
13.2.1.1
13.2.1.2
13.2.1.3
13.2.1.4
13.3
13.3.1
13.3.2
13.3.3
13.3.4
13.3.5
13.4
13.4.1
13.4.2
13.4.3
13.5
13.5.1
13.5.2
13.5.3
13.5.4
13.5.5
13.5.6

viii

CONTENTS (CONT.)

Page
13.5.7
13.5.8

Ordering Statements
Asking The Correct Question

13-15
13-15

APPENDIX A

COBOL RESERVED WORDS

A-I

APPENDIX B

COLLATING SEQUENCES AND CONVERSION
TABLES

8-1

APPENDIX C

DEFINING LOGICAL NAMES UNDER TOPS-20

C-l

APPENDIX D

ALTERNATE NUMERIC TEST

D-l

APPENDIX E

TAPE HANDLING

E-l

DIRECTIONS AND DEFINITIONS
Definitions
Finding The Right Instructions
Symbols Used In The Text
FACTORS TO CONSIDER WHEN USING TAPES
General Defaults And Restrictions
Converting Tapes Between Labeled And
Unlabeled
USING SYSTEM-UNLABELED TAPES
Tape Has No Labels
Tape Drive Is Available To The User
Tape Drive Is Owned By The System
Tape Has Labels
USING SYSTEM-LABELED TAPES
Tape Has ANSI Labels
Transportable Tapes - F, D, And S
Formats
Undefined-Format Tapes - U-Format
Tape Has EBCDIC Labels

E-l
E-l
E-2
E-4
E-4
E-4

E.l
E.l.l
E.l.2
E.l.3
E.2
E.2.l
E.2.4
E.3
E.3.l
E.3.l.l
E.3.l.2
E.3.2
E.4
E.4.l
E.4.l.l
E.4.l.2
E.4.2
GLOSSARY

E-6
E-6
E-7
E-7
E-7
E-8
E-8
E-8

E-9
E-IO

E-ll
Glossary-l

INDEX

Index-l
FIGURES

FIGURE

1-1 (a)

l-2(a)
l-3(a)
4-1

4-2
4-3
7-1
8-1
8-2
8-3

8-4
8-5
8-6
8-7
8-8
8-9

Card-Type Format
Terminal-Type Format with Line Numbers
Terminal-Type Format without Line Numbers
Direct Subscripting/Indexing
Relative Subscripting/Indexing
Qualified Direct Subscripting/Indexing
COBOL ISAM File Environment
ASCII Recording Mode
SIXBIT Recording Mode
EBCDIC Recording Mode
EBCDIC Recording Mode - Industry-Compatible
Binary Recording Mode
Fixed-Length ASCII
COBOL Fixed-Length ASCII
Variable-Length
COBOL Variable-Length ASCII

1-10
1-11
1-12

4-9
4-9
4-10
7-3
8-1
8-2
8-2
8-2
8-3

8-4
8-5
8-6

8-8

FIGURES (Cont.)
8-10
8-11
8-12
8-13
8-14
8-15
8-16
8-17
8-18
8-19
8-20
8-21
8-22
8-23
8-24
8-25
8-26
8-27
9-1
9-2
9-3
9-4
9-5
9-6
9-7
11-1
13-1

8-8
Fixed-Length SIXBIT
8-9
COBOL Fixed-Length SIXBIT
8-10
Variable-Length SIXBIT
8-12
COBOL Variable-Length SIXBIT
8-13
Fixed-Length EBCDIC
8-13
COBOL Fixed-Length EBCDIC
8-14
Variable-Length EBCDIC
8-16
COBOL Variable-Length EBCDIC
COBOL Blocked Fixed-Length EBCDIC
8-18
B~ocked Variable-Length EBCDIC
8-19
COBOL Blocked Variable-Length EBCDIC
8-21
COBOL Standard Binary and
8-23
ASCII Mixed-Mode Binary
COBOL Standard Binary and
SIXBIT Mixed-Mode Binary
8-24
COBOL Standard Binary and
EBCDIC Mixed-Mode Binary
8-26
Statements Used to Sequentially
8-30
Access a Random File
ISAM Data File Structure
8-32
Locating a Record in an
Indexed-Sequential File
8-33
ISAM Index File Structure
8-34
The Problem of Buried Update
9-2
The Problem of Deadly Embrace
9-3
Declaring Resources For Simultaneous Update 9-4
The OPEN Statement
9-5
Competing For Program Access to Files
9-7
The RETAIN Statement
9-8
The FREE Statement
9-10
Example of an Overlay Structure
11-10
Sample COBDDT Histogram
13-6

TABLES
TABLE

3-1
3-2
3-3
4-1
5-1
5-2
5-3
6-1

B-1
B-2
B-3

Recording Modes
Monitor File Status Bits
Monitor Error Codes
Standard Label for Nonrandom-Access Media
Procedure Verb and Statement Categories
Types of Segments
CLOSE Options and File Types
COBOL Switch Summary
ASCII and SIXBIT Collating Sequence
and Conversion to EBCDIC
ASCII to SIXBIT Conversion
EBCDIC Collating Sequence and
Conversion to ASCII

3-26
3-31
3-32
4-17
5-2
5-5
5-30
6-3

B-1
B-3

8-5

FORWARD

This manual describes COBOL-68 as
implemented on both TOPS-IO and
TOPS-20.
This manual is a complete manual containing reference
material, user's guide material,
and . COBOL utilities.
Chapter 1
discusses language elements, conventions used in this manual, and the
structure of a COBOL-68 program.
Chapters 2 through 5 describe the
four
major divisions of a COBOL-68 program.
Chapters 6 through 13
provide the information necessary to use the COBOL-68
system,
including performance improvements,
utility programs, file formats,
report writing, and various other useful features of COBOL-68.
Several Appendixes, A through E, plus a Glossary of COBOL terms are
included in this manual.
Appendix A contains the COBOL reserved
words, Appendix B contains the character collating sequence, Appendix
C describes how to define logical names under TOPS-20, Appendix D
describes an alternate form of numeric test, and Appendix E describes
Tape Handling.
It is assumed that the reader has a knowledge of the COBOL-68
language.
This manual is intended primarily for reference and is not
a tutorial guide for beginning COBOL programmers.
Those wishing to
learn the COBOL-68 language are referred to the following books:
Farina, Mario V., COBOL Simplified, New
Inc., 1968.

Jersey,

McCameron, Fritz A.,
COBOL Logic and
Irwin, Inc., 1966.
Illinois, Richard D.

Programming,

Prentice

Hall,

Homewood,

McCracken, Daniel D.
and Garbassi, Umberto,
A Guide to COBOL
Programming, Second Edition, New York, John Wiley and Sons, Inc.,
1970.

TOPS-IO users should read and be familiar with the following manuals:

• TOPS-IO OpeLating System Commands Manual

• TECO Programmer's Reference Manual
• TOPS-IO Monitor Calls Manual

• TOPS-IO Hardware Reference Manual
• TOPS-IO LINK Reference Manual
• TOPS-IO SORT/MERGE User's Guide
TOPS-20 user's should read and be familiar with the following manuals:
•

TOPS-20 Commands Reference Manual

• TOPS-20 TV Reference Manual
• TOPS-20 EDIT Reference Manual
• TOPS-20 Monitor Calls Manual
• TOPS-20 Hardware Reference Manual

• TOPS-20 LINK Reference Manual
• TOPS-20 SORT/MERGE User's Guide

xii

ACKNOWLEDGMENT

COBOL is an industry language and is not the property of any company
or
group
of
companies, or of any organization or group of
organizations.
No warranty, expressed or implied, is made by any contributor or by
the CODASYL Programming Language Committee as to the accuracy and
functioning of the programming system and language.
Moreover, no
responsibility is assumed by any contributor, or by the committee, in
connection therewith.
The authors and copyright holders of
herein

the

copyrighted

material

used

•

FLOW-MATIC
(trademark
of
Sperry
Rand
Corporation) ,
Programming for the Univac
(R) I and II, Data Automation
Systems copyrighted 1958, 1959, by Sperry Rand Corporation;

•

IBM Commercial Translator Form No.
1959 by IBM;

•

FACT,
DSI
27a5260-2760,
Minneapolis-Honeywell.

28-8013,

copyrighted

copyrighted
1960

have specifically authorized the user of this material, in whole or in
part, in the COBOL specifications. Such authorization extends to the
reproduction and use of COBOL specifications in programming manuals or
similar publications.

xiii

CHAPTER 1
INTRODUCTION TO COBOL-68 LANGUAGE

This chapter describes the conventions,
special terms, language
elements,
and formats acceptable to COBOL-68.
The source language
statements are discussed in subsequent chapters.
NOTE
For the purposes of this document,
terms
COBOL
and
COBOL-68
interchangeable.

1.1

the
are

SYMBOLS AND TERMS

The symbols and terms used in the following chapters of this manual
are necessary to describe the language or-are commonly used COBOL
terms.
The single exception of this statement
is
the
term
BIS-compiler.
This term refers to compiler
implementations that
compile COBOL-68 using the Business Instruction Set (BIS).
All
users
of TOPS-20 get BIS code.
Users of TOPS-IO who have a KS or KL central
processing unit get BIS code as the default, but the compiler can be
installed without the BIS option.
TOPS-IO users who have a KI central
processor will usually not get the BIS option on their compilers.
The
KI processor will not execute the BIS instructions;
however, the KI
will run the compiler which produces BIS code should there be a need
for
it.
(For more
information,
see the COBOL-68 Installation
Procedures.) You can tell if your compiler is producing BIS code by
checking a
listing of a compiled program.
If your compiler is
producing the BIS instructions,
the letters BIS will
follow the
version and edit numbers on top of the page.

1.1.1

Symbols

The symbology used in this manual
to illustrate the various COBOL
statement formats is essentially the same as that used in other COBOL
language manuals and is based on the CODASYL COBOL reference document.
Symbology

Meaning

Lower-case characters

Represent information that
must
supplied by the programmer,
such
values, names, and other parameters.
1-1

be
as

INTRODUCTION TO COBOL-68 LANGUAGE
Symbology

Meaning

Upper-case characters,
Underscored

Key words in the COBOL lexicon that must
be used when the formats of which they
are a part are used.

Upper-case characters,
not underscored

Other words in the COBOL lexicon that
serve only to make the COBOL statement
more readable.
Their use is optional
and has no effect on the meaning of the
formats of which they are a part.

B~aces

Indicate that a choice must be made from
the two or more lines enclosed.

Brackets

Indicate an optional
feature.
The
contents
of
the brackets are used
according to the rules above if the
feature is desired.

Ellipsis .•.

Indicate that the information contained
within the preceding pair of braces or
brackets can
be
repeated
at
the
programmer's option.

1.1.2

COBOL Terms

The terms block, record, and item have special meanings when used in a
COBOL program.
Term

Meaning

Block

Signifies a logical grouping of records.
This term
commonly refers to a logical block of records on some
storage medium.

Record

Signifies a logical unit of information.
In relation
to a data file, a record is the largest unit of logical
information that can be accessed and processed at a
time. Records can be subdivided into fields or items.

Item

Signifies a logical field or group of fields within a
record.
A group item is one that is further broken
down into subitems (for example, a group item called
TAX might be broken down into subitems called FED-TAX
and STATE-TAX). Subitems can be further broken down
into other subitems. An item that has no subitems is
called an elementary item.

1-2

INTRODUCTION TO COBOL-68 LANGUAGE
1.2

ELEMENTS OF COBOL LANGUAGE

1.2.1

Program Structure

A COBOL program consists of four divisions.
Within each division
the program statements;
some are required, others are optional.
Division

are

Meaning

IDENTIFICATION DIVISION

Identifies the source program.

ENVIRONMENT DIVISION

Describes the computer on which the
source program is to be compiled,
the computer on which the object
program is to run,
and certain
relationships
between
program
elements and hardware devices.

DATA DIVISION

Describes the data to be
by the object program.

PROCEDURE DIVISION

Describes
the
actions
performed on the data.

processed
to

NOTE
There is no limit to the number of
source lines
the compiler can handle.
However, the largest source line number
that the compiler can generate is 8184.
Beyond that number, the compiler begins
again
with
0001.
This can cause
confusion when
error
messages
are
issued.

1.2.2

Character Set

within a source program statement,
except:

all

ASCII

characters

are

valid

Null, delete, and carriage return (which are ignored);

Line feed, vertical tab, form feed, and the printer control
characters
(20(8)
through 24(8)), which mark the end of a
source line;

Control-Z, which marks the end-of-file.

The lower case ASCII characters are translated to upper
characters except when they appear in nonnumeric literals.

case

Of this character set, 37 characters (the digits 0 through 9,
the 26
letters of the alphabet, and the hyphen) can be used by the programmer
to form COBOL words,
such as data-names,
procedure-names,
and
identifiers.

1-3

INTRODUCTION TO COBOL-68 LANGUAGE
Punctuation characters include:
(spac-e)

(quotation mark)

(comma)

(left parenthesis)

(semicolon)

(right parenthesis)

(period)

(horizontal tab)

Special editing characters include:

(plus sign)

. (check protection symbol)

(minus sign)

(zero suppression)

(dollar sign)

(blank insertion)

(comma)

(zero insertion)

(decimal point)

(credit)

(debit)

Special characters used in arithmetic expressions include:
+

(addition)

(division)

(subtraction)

(exponentiation)

(multiplication)

(exponentiation)

Special characters used in conditional ( IF) statements include:
(equal)

1.2.3

(greater than)

(less than)

Words

A COBOL word is composed of not more than 30 characters chosen from
the 37 characters A through Z, 0 through 9, and hyphen. A word is
terminated by a space, period, right parenthesis, comma, semi-colon,
or horizontal tab.
A hyphen can not be used as the first or last
character of a word. If the terminator is not a space or horizontal
tab, at least one space or tab must follow the terminator.
Words used in writing COBOL source programs are of two
reserved words and user-created words.

types:

COBOL

1.2.3.1 COBOL Reserved Words - COBOL reserved words are those words
that constitute the COBOL lexicon and have a special meaning to the
compiler (for example, DIVISION, PROCEDURE, ADD) ;
these words are
listed in Appendix A. They include all the COBOL division, section,
and paragraph names, descriptive clauses, procedure verbs, certain
prepositions, figurative constants, and special registers. Reserved
words must be spelled and used exactly as shown in the formats given
in this manual.

1-4

INTRODUCTION TO COBOL-68 LANGUAGE
Figurative Constants - Figurative constants are reserved words that
specify certain fixed values.
When these reserved words are to be
used as figurative constants, they must not be enclosed in quotation
marks;
otherwise they are treated by the compiler as alphanumeric
literals.
The figurative constants are given below.
Except for
ALL constant),
singulai and plural forms are given;
equivalent and can be used interchangeably.
Figurative
Constant

one case
(the
these forms are

Use

ZERO
ZEROS
ZEROES

Represents the value zero or one or more of
the character 0 depending on context.

SPACE
SPACES

Represents one or more blanks or spaces.

HIGH-VALUE
HIGH-VALUES

For DISPLAY-6, DISPLAY-7, and DISPLAY-9 items
this represents the highest value in the
collating sequence.
For COMP and COMP-l
items, this represents the largest number
that can be placed in the machine word(s)
containing the item.
For COMP-3 items,
this
represents all
9s with the nonprinting plus
sign.

LOW-VALUE
LOW-VALUES

For DISPLAY-6, DISPLAY-7, and DISPLAY-9 items
this represents the lowest value in the
collating sequence.
For COMP and COMP-l
items, this represents the smallest number
(most negative)
that can be placed in the
machine word(s)
containing the item.
For
unsigned COMP-3 items,
this represents all
zeros with the nonprinting plus sign;
for
signed COMP-3 items, this represents all 9s
with a minus sign.

QUOTE
QUOTES

Represents one or more quotation marks
(").
It can be used anywhere that the quotation
mark
character
(")
is valid,
except to
delimit alphanumeric literals
(see Section
1.2.4.2, Alphanumeric Literals).
QUOTE(S) is
frequently used where an actual quotation
mark character would erroneously appear to
delimit
an
alphanumeric
literal.
For
example,
if you wanted your program to type
out the exact character string
MOUNT TAPE LABELLED "MASTER" ON DRIVE 3
you could use the procedure statement
DISPLAY "MOUNT TAPE LABELLED" QUOTE
"MASTER" QUOTE "ON DRIVE 3".

ALL any-literal

Represents repetitions of the string
of
characters
that
constitute
either
an
alphanumeric literal or a figurative constant
(other
than
ALL
any-literal) .
If
a
figurative constant is used,
the ALL is
redundant;
thus,
ZEROS and ALL ZEROS are
equivalent.

1-5

INTRODUCTION TO COBOL-68 LANGUAGE
Figurative constants generate a string of characters whose length is
determined, based on context, by the compiler.
For example, if
TOTAL-AMOUNT is a five-character field, the procedure statement MOVE
ALL ZEROS TO TOTAL-AMOUNT moves a string of five zeros to the field
TOTAL-AMOUNT;
MOVE ALL "AB" TO TOTAL-AMOUNT moves "ABABA"
to
TOTAL-AMOUNT. If the length cannot be determined by context, a single
character (or a single-character sequence, in the case of ALL)
is
generated.
For example, the procedure statement DISPLAY ALL QUOTES
results in the output of a single quotation mark (") to your terminal.
Examples of Use of Figurative Constants:
02"AMOUNT PICTURE IS 9999.99
IS ZERO.
04 MESSAGE PICTURE IS A(lO)
IS SPACES.

DATA DIVISION Usage:

PROCEDURE DIVISION Usage:

VALUE
VALUE

MOVE ZEROS TO AMOUNT.
MOVE SPACES TO MESSAGE.
IF TOTAL IS EQUAL TO ZERO ....
EXAMINE FLD-A
TALLYING
LEADING
ZEROS.

COBOL

Special Registers - In addition to figurative
constants,
recognizes two other special reserved-words: TALLY and TODAY.

TALLY is the name of a fixed five-digit signed COMPUTATIONAL field.
It is used primarily to hold information produced by the EXAMINE verb.
However, the programmer can use TALLY in any situation where a signed
numeric field is valid (for example, temporary storage of any integer
value of five or fewer digits).
TODAY is a l2-character alphanumeric DISPLAY field that
current date and time. Its format is:

contains

the

yymmddhhmmss
where

yy is the year (last two digits)

hh is the hour

mm is the month

mm is the minute

dd is the day

ss is the second

1.2.3.2 User-Created Words - User-created words are labels for the
various parts of your data (files, records, and fields) and your
procedure (sections and paragraphs).
They can contain only the
symbols 0 through 9, A through Z, and the hyphen. With the exception
of procedure names, they cannot be all digits.
A user-created word
can neither begin nor end with a hyphen. The maximum number of
user-created words allowed in the program is 4681.
User-created words can be further subdivided into several categories.
To understand the remainder of this manual, you should be familiar
with the following types of words.
data-name

The user-created name assigned
(field) within a record.

item

file-name

The user-created
file.

data

1-6

name

assigned

INTRODUCTION TO COBOL-68 LANGUAGE

1.2.4

record-name

The user-created name
record within a file.

procedure-name

The user-created name assigned to a paragraph
or section in the PROCEDURE DIVISION.
When
assigned to a section, it is referred to as a
section-name;
and
when
assigned to a
paragraph,
it
is
referred
to
as
a
paragraph-name.

identifier

A user-created name
used
in
PROCEDURE
DIVISION statement formats
to indicate a
data-name followed,
as required,
by
the
syntactically
correct
combination
of
qualifiers, and/or subscripts, and/or indexes
necessary to make reference to a unique item
of data.

mnemonic-name

A user-created name assigned
device or a report code.

condition-name

A user-created name assigned to a value or
range of values of the associated data item.
Condition-name can also be
assigned
to
console switch settings.

index-name

A user-created name defined using the INDEXED
BY clause
(see OCCURS
in Chapter 4).
Its
function is identical to that of an
index
data-name (see below).

index data-name

A user-created name defined with USAGE INDEX.
Its function
is identical to that of an
index-name.

assigned

data

hardware

Literals

A literal is a string of characters, the value of which
is identical
to the characters that compose the literal.
Literals are of two
types:
numeric and nonnumeric.

1.2.4.1 Numeric Literals - A numeric literal is a string of 1 to 18
numeric characters
(0
through 9).
It cannot contain any alphabetic
characters.
It can be preceded by a plus sign (+)
or a minus sign
(-);
if no sign is used, the literal is assumed to be positive.
A
decimal point can appear anywhere in the literal except to the left of
the sign or as the rightmost character.
If no decimal point is used,
the literal is assumed to be an
integer.
A numeric literal
is
considered to be of the numeric class;
that is, it can be used
legitimately as a value in arithmetic expressions.
Examples of Numeric Literals:
123
-123
-.123456789

+123
1.23456
1234567890.12345678

1-7

.123456789
-1234567890.12345678

INTRODUCTION TO COBOL-68 LANGUAGE
1.2.4.2 Alphanumeric Literals - Alphanumeric literals are character
strings containing from 1 to 120 characters enclosed in single or
double quotation marks. The value of the literal is equal to the
characters, including any spaces, enclosed by the quotation marks.
Note that the compiler accepts either single or double quotation marks
to enclose a literal;
however, the opening and closing quotation
marks must be the same type, either single or double.
Any ASCII
character except the quotation mark, null, delete, carriage return,
and printer control can appear within a literal.
Alphanumeric literals cannot be used as values
in
arithmetic
operations, and numeric editing cannot be performed on them. If a
literal conforms to the rules for formation of a numeric literal, but
is enclosed in quotation marks, it is considered to be an alphanumeric
literal. That is, "120.45" is not equivalent to 120.45.
Examples of Nonnumeric Literals:
A"
'THIS ACCOUNT HAS A CREDIT BALANCE'
IRE'rURN"
"-125.50"
'DEDUCT 10% IF PAID BEFORE JAN.3lST'
II

1.2.5

Punctuation

The punctuation that can be used in
space, comma, semicolon, and period.

source

programs

includes

the

The space is used to separate words, phrases and clauses.
The comma
and semicolon can be used interchangeably within a program to improve
the appearance of the program.
However, both the comma and the
semicolon are treated as spaces by the compiler; they can be used any
place in the program where a space is expected.
The period is used to terminate a division name, a section name, and a
paragraph name.
It is also used in the PROCEDURE DIVISION to
terminate sentences. Paragraphs and sections are terminated by the
period ending the last sentence of the paragraph or section. In the
DATA DIVISION, a period must be placed after the description of a data
item. Examples of the use of periods are:
PROCEDURE DIVISION.
INPUT SECrION.
READ INFIL AT END GO TO ENDER.
DATA DIVISION.
FILE SECTION.

01 MYDATA PICTURE IS X(lO).

1-8

INTRODUCTION TO COBOL-68 LANGUAGE
1.3

SOURCE PROGRAM FORMAT

There are two basic types of source program formats in which you can
write your COBOL-68 programs. These two types arise from the methods
of entering the source program into the system.
The first is
conventional card-type format. You should use this type if you wish
your COBOL-68 program to be compatible with other compilers.
The
second is the standard DEC format which is designed for easy use on
terminals. This format is the one to use for those programs that are
to be entered into the system through a terminal using a text editor.
The compiler assumes that the source program
is
written
in
terminal-type format unless the /S switch is included in the command
string to the compiler (refer to Chapter 6).
Certain margins which begin the areas used for writing COBOL-68
statements are standard for source programs. The standard names for
these margins are Margins L, A, B, and R.
As you might expect,
Margins Land R are the left and right margins of the line,
respectively. Margins A and B mark the beginning of two areas, Areas
A
and B.
Area A is where all division-names, section-names,
paragraph-names, and FD (File Description) entries must begin.
All
other entries must begin in Area B. Although the actual character
position which marks each of these margins changes from format to
format, the function of each area is the same; in other words, you
must begin your division-names at Margin A no matter what format you
use, no matter where Margin A happens to be placed in that format.
NOTE
These rules agree with the 1968 ANSI
standard for source program formats.
Programs written according to the rules
are more readable and transportable.
The COBOL-68 compiler, however, does not
do complete syntax checking to determine
if you have followed all rules, and does
not always issue an error message if you
violate them. Thus, you are encouraged
to
conform
to the rules to avoid
unpredictable results.
Some of the rules for using source program formats remain constant
regardless of which format you use. These rules are given below.
Refer to them for all types of formats.
1.

Continuation Area - If you wish to split a word or literal
across two lines, you must use this area to indicate your
wish to the compiler. To do this, write the first line up to
the point at which you wish to split it, then place a hyphen
(-) in the continuation area of the next line and continue
the second line beginning at or after Margin A. If you are
splitting a word or numeric literal you can leave spaces
between the last character in the first line and the end of
the source statement area.
(This area
ends
at
the
identification area, when it exists; otherwise it ends at
Margin R.) However, if you wish to split an alphanumeric
literal you must not leave spaces after the last character of
the first line, since the compiler assumes that those spaces
are part of the literal.
If you wish only to continue a
sentence on the next line without splitting any words, you
can simply write the first line, then continue on the next
line; do not use the continuation column for this purpose.
1-9

INTRODUCTION TO COBOL-68 LANGUAGE
2.

Comment Lines - You can insert comment lines into your
COBOL-68 program by using the continuation area. If the
compiler finds an asterisk (*) in that area it lists the
remainder of the line as a comment on the next line. If
there is a slash (/) instead of an asterisk a new page is
started and the comment is listed at the top of the new page.

NOTE
All formats can be used with any input
medium.
The· names of the types of
formats refer to their origins, not
their uses.

1.3.1

Card-Type Format

You should use card-type format if you wish to compile your program
under an operating system other than TOPS-IO or TOPS-20. Your program
can be punched on an off-line card punch or created with an on-line
text editor.
This format uses card sequence numbers which must be
created by you. The layout of a line in this format is shown in
Figure 1-1 (a) .
The numbers refer to card columns or character
positions.

CARD-TYPE

FORMAT

6 7

t
L

~J
r
B

......,....
I

."
MR-S-965-81

Figure l-l(a) Card-Type Format
In this format, Margin L is to the left of position 1 and Margin R is
to the right of position 80. Margin A is betw~en positions 7 and 8
and begins the area labeled A in the figure.
Margin B is between
positions 11 and 12 and begins the area labeled B.
The following rules pertain to the use of this source format:
1.

Line Numbers - These are placed in area L (positions 1
through 6) by you when creating the file on a terminal or a
card punch.

Identification Area - This area is marked I in the figure
(positions 73 through 80). These eight character positions
can hold identifying information which can be composed of any
eight characters. This information is printed on the source
listing, and can be used to identify the card deck (if the
source code is in fact on cards).

1-10

INTRODUCTION TO COBOL-68 LANGUAGE

NOTE
The card sequence numbers are not the
same as the line numbers created by a
line editor. The numbers supplied by an
editor are not acceptable to COBOL-68
when you specify card-type format.
The example in Figure 1-1 (b) illustrate these rules.
The first two
lines are simple statements, with a line number in area L, COBOL-68
statements in areas A and B, and the identification area containing
the name of the program. The third line shows how the continuation
column is used to split a word across two lines. Note that the word
can be written right up to the end of area B.

1.3.2

Terminal-Type Format

If you are writing your program using a text editor and a terminal to
input the source code, terminal-type format is your best choice.
There are two types of terminal-oriented formats,one with line
numbers and one without. Layouts and examples of each type are shown
in the figures which follow.

1.3.2.1 with Line Numbers - This format is suitable if you use a
line-oriented editor such as EDIT or 50S. The format is shown in
Figure 1-2 (a) •

TERMINAL·TYPE

FORMAT . WITH

LINE

NUMBERS

122

6
7
8
12
~------------r-~-.----------~------------~/

~--~I~I~--~--~/i~1______~
L

Figure 1-2(a) Terminal-Type Format with Line Numbers
In this format, margin L is to the left of position 1 and margin R is
to the right of position 122. Margin A is between positions 7 and 8
and begins the area labeled A. Margin B is between positions 11 and
12 and begins the area labeled B.
Therefore, areas A and B can
contain a maximum of 114 characters.

1-11

INTRODUCTION TO COBOL-68 LANGUAGE
The following rules pertain to the use of this source format:
1.

Line Numbers - These are placed in area L (positions 1
through 5) either by the line editor or by you. If you are
using an editor which supplies line numbers you must not add
numbers yourself - one set is enough.

position 6 - This position (marked Z in the figure)
remains
blank.
The editor can insert a tab here for purposes of
making your text more readable:
if so, the compiler reads
the tab as a space.

Continuation Area - To use the continuation area, type -, *,
, or / as the first character of the line. However, if you
do not wish to use the continuation area, you can ignore it
altogether - you do not need to type a space at the beginning
of the line. If you do type a space as the first character
of a line, the compiler assumes that you meant the space to
be part of the line.

The example in Figure l-2(b) illustrate the use of this format.
The
first two lines are simple COBOL-68 statements with the five-character
line number in area L and areas Z and C blank. The third line shows
how a word is split across two lines. Note that you can leave spaces
between the last letter of the word and margin R without confusing the
compiler.

1.3.2.2 without Line Numbers - If you 'decide to use a terminal to
enter your program but your editor
(such as TECO or TV) does not
supply line numbers (or you requested that the editor remove them when
you finished editing), this is the simplest format to use. The format
is shown in Figure l-3(a).

TERMINAL-TYPE

FORMAT - NO

LINE

NUMBERS

5
~~--------~~--------------~I

122
,~(----------------~

Figure l-3(a) Terminal-Type Format without Line Numbers
In this format, margin L is to the left of position 0, if it exists,
or position 1, if position 0 does not exist. Margin R is to the right
of position 122. Margin A is to the left of position 1 and begins the
area labeled A. Margin B is between positions 4 and 5 and begins the
area labeled B. Therefore, areas A and B can contain a maximum of 114
characters.

1-12

INTRODUCTION TO COBOL-68 LANGUAGE
The following rule pertains to the use of this source format:
Continuation Area - If you wish to use the continuation area,
type the character you wish to enter (-, *, /) as the first
character of the continued line. If the compiler finds one
of these characters at the beginning of a line it assumes
that the line has a position 0
in other words, a
continuation area. Otherwise, each line starts in position 1
and there is no position o.
The example in Figure 1-3{b) show this format's simplicity. The first
two lines are the same simple COBOL-68 sentences as above. Note that
the paragraph-name starts in the very first character position.
The
third line shows how to tell the compiler that the line you enter is a
continuation (or a comment) line. The first half of the line is
entered beginning in the first position of Area B, while the second
half begins with a hyphen and continues from the second position.

1-13

00 1 0 20
00 1 0 30
00 1 0 40-

Till XA C~ T~
Till XA CC TG

00 1 0 00 PR OC ES S- TA X.
00 1 0 1 0
IMO VE TH IS -P ER 10 OS -T AX TO 1A X- p~ 10.

Till XA CC TG
ST RI NG f'J0 Sl -R EC EN IT - MO N1 H, SP AC E ,
, SP PC E, MO SiT -R EC EN T- OA Y,
IllR
, SP IA CE , t10 ST -IR EC EN T- YE
SP lAC E ,
DE LI MI TE ~Y S I ZE IN TO 01 SP LT ~X AC CTG
lAY -0 AT E.
II _

II _

MR-S-968-81

Figure 1-1 (b)
H

t-3
~

o
c

(')

t-3
H

plR OC ES <;- IliA Ix.
IMn ~E TH IS -p IE RI'" IDle; -11 Alx 1110 11 P X- PiA Ie.

t-3

(')

II _

Sl RI NG I~ 0S -R EC EI~ 1- tJlc Nil H, ISlp Ale E ,
, SP Alc E, Mlc Sil -B EC EN 1 - OA Y, SP ACE
1- RE clE I~ T-I~ EA R DIE 11 tJ I TIE [ Islv SI Iz E IN TO Ie I SP IL Jl Iv - CP TE.
II

II _ II

slF ACE tJOS

o
OJ
o

MR-S-969-81

0"1

t"i
I

Figure 1-2 (b)

00 10P
00 110
00 120
00 1 3Q -

PR ~C ES S- TA X.
MO VE TH IS -P ER 10 O~ -T AX ~~ ~A X- pll\ 10.
, S PIA CE ,M OS T- RL- CE NT r--O ~~ ,~ PA CE ,
ST RI NG IMO ST -R EC EN T- MO Nrr ,S PA CE ,
S
I ZE IN TO 01 SP AY -0 ~IT r-r- •
1M
BY
DE
IT
ED
YE
E,
EC
EN
IAR
AC MO SiT -R
TII

,SP

MR-S-970-81

Figure 1-3 (b)

INTRODUCTION TO COBOL-68 LANGUAGE
1.4

THE COBOL LIBRARY FACILITY

You can use the COBOL Library Facility to copy part of your program
from a COBOL source library at compile time. This can be useful if,
for example, you need to describe a complex file to be used in several
different programs, and you wish to write the file description only
once. You can insert the file description into the library (for
directions and further description see the COBOL-68 Usage Material,
Part 3 of this manual), and whenever the description is needed you can
simply copy it from the library into the program you are writing. The
following statement is used to accomplish this.
NOTE
The COpy facility for COBOL-68 is the
enhanced
version
from
the ANSI-74
standard, and not the original one from
the ANSI-68 standard.

1.4.1

The COPY Statement

Function
The COpy statement incorporates text from a COBOL library into a COBOL
source program.
(For a complete description of COBOL libraries, see
the COBOL-68 Usage Material, Part 3 of this manual.) The COpy
statement can also be used to replace specified text in the source
text being copied.
General Format

COpy text-name [I~l library-name]

REPLACING
.;. ;.;:;;;.;. . ;;.;. .;. .;;. ;;. .;.;;.;;;;.

{I ~~~~~~~~;~:~t-l== IBY j ~~~~m~~;:~t-2== I}
llteral-l
word-l

- ) literal-2
~ word-2

.•. -

MR-S-971-81

Technical Notes

NOTE
In the technical notes which follow, the
term string-l is used to denote the
character string which is used in place
of
the
following:
pseudo-text-l,
identifier-I, literal-I, or word-I. The
term string-2 is similarly used.

1-15

INTRODUCTION TO COBOL-68 LANGUAGE
1.

If more than one COBOL library
is
available
during
compilation, text-name must be qualified by the library-name
identifying the COBOL library in which the text associated
with text-name resides.
Within one COBOL library, each text-name must be unique.

The COpy statement must be preceded by a space and terminated
by the separator period. The entire statement, including the
period, is removed when the text is copied from the library.

String-l must not be null, nor can it.consist solely of the
character space(s), nor can it consist solely of comment
lines.

String-2 can be null.

Character-strings within string-l and string-2
can
be
continued.
However,
both characters of a pseudo-text
delimiter must be on the same line.

A COpy statement can occur in the source program anywhere a
character-st~ing
or a separator can occur except that a COpy
statement must not occur within another COpy statement.

The effect of processing a COpy statement is that the library
text associated with text-name is copied into the source
program, logically replacing the entire COpy statement,
beginning with the reserved word COpy and ending with the
punctuation character period, inclusive. The compilation of
a source program containing COpy statements is logically
equivalent to processing all COpy statements prior to the
processing of the resulting source program. For clarity, use
the double equal sign (==) around string-l and string-2 to
designate clearly the string that is being replaced and the
string that is replacing that text.
See Note 10 for an
example of the use of the double equal sign.

If the REPLACING phrase is not specified, the library text is
copied unchanged. If the REPLACING ~hrase is specified, the
library text is copied and each properly matched occurrence
of
string-l
in the library text is replaced by the
corresponding string-2.

The comparison operation to determine text replacement occurs
as follows:
a.

Any separator comma, semicolon, and/or space(s) preceding
the leftmost library text-word is copied into the source
program. Starting with the leftmost library text-word
and
the first string-l that was specified in the
REPLACING phrase, the entire REPLACING phrase operand
that precedes the reserved word BY is compared to an
equivalent number of contiguous library text-words.

String-l matches the library text if, and only if, the
ordered sequence of text-words that forms -string-l is
equal, character for character, to the ordered sequence
of library text-words.
For purposes of matching, each
occurrence of a separator comma or semicolon in string-l
or in the library text is considered to be a single space
except when string-l consists solely of
either
a
separator
comma
or
semicolon,
in which case it
participates in the match as a text-word. Each sequence
1-16

INTRODUCTION TO COBOL-68 LANGUAGE
of one or more
single space.

10.

space separators is considered to be a

If no match occurs, the comparison is repeated with each
next successive string-I, if any, in the REPLACING phrase
until either a match is found or
there
is no next
successive REPLACING operand.

When all the REPLACING phrase operands have been compared
and no match has occurred, the leftmost library text-word
is copied into the source program.
The next successive
library text-word is then considered as the leftmost
library text-word, and the comparison cycle starts again
with the first string-l specified in the REPLACING
phrase.

Whenever a match occurs between string-l and the library
text,
the corresponding string-2
is placed into the
source program.
The library
text-word
immediately
following
the rightmost text-word that participated in
the match is then considered as the leftmost library
text-word.
The comparison cycle starts again with the
first string-l specified in the REPLACING phrase.

The comparison operation continues until
the rightmost
text-word 'in the library text has either participated in
a match or been considered as a
leftmost
library
text-word and participated in a complete comparison
cycle.

When you use the REPLACING phrase, you must treat any picture
strings in the library text as complete pieces of text.
That
is, if you wish to replace XIS in the picture string
EXAMPLE-ITEM PICTURE IS XXX.
with 9's, you must replace the entire PICTURE
just the three XIS, with the form shown below:
COpy EXAMPLE-TEXT FROM LIBARY REPLACING
XXX== BY ==PICTURE IS 999==.

clause,

not

==PICTURE IS

11.

For purposes of matching, a comment line which occurs in the
library text and string-l is interpreted as a single space.
Comment lines which appear in string-2 and library text are
copied into the source program unchanged.

12.

The text produced as a result of the complete processing of a
COPY statement must not contain a COpy statement.

13.

The syntactic correctness of the library text cannot be
independently determined.
The syntactic correctness of the
entire COBOL source program cannot be determined until all
COPY statements have been completely processed.

14.

Library text must conform to the rules for
COBOL source
program format.
(See Section 1.3.) You can copy text from a
library without worrying about what format your program is
in, however.

15.

For purposes of compilation, text-words after replacement are
placed in the source program according
to the rules for
source program format.
1-17

CHAPTER 2
THE IDENTIFICATION DIVISION

The IDENTIFICATION DIVISION is required in every source program and
identifies the source program and the output from compilation. In
addition, you can include other documentary information such as the
name of the program's author, the name of the installation, the dates
on which the program was written and compiled, any special security
restrictions, and any miscellaneous remarks.
General Structure

{t£ EN TI FI CAT ION} DI VISION.
[PROGRAM-ID. [program-name] [comment paragraph] ..!... ]
[AUTHOR.

comment

paragraph

..!... ]

[ INSTALLATION.

comment

paragraph

..!... ]

[ DATE-WRITTEN.

comment

paragraph

..!... ]

[ DATE-COMPILED.

comment

paragraph

[ SECURITY.

comment

paragraph

[ REMARKS.

comment

paragraph

..!...

..!... ]

..!...

]

MR-S-972-81

Technical Notes
1.

The Identification Division must begin with the reserved
words IDENTIFICATION DIVISION (or ID DIVISION) followed by a
period and a space. ID is the equivalent to IDENTIFICATION.

2-1

THE IDENTIFICATION DIVISION
2.

The PROGRAM-ID paragraph contains the name
identifying
the
program.
The program-name can have up to six characters, and
must contain only letters, digits, and the hyphen.
It can be
enclosed in quotation marks.
The program-name cannot be a
reserved word and must be unique.
It cannot be the same as a
section, paragraph,
file,
data or subprogram name.
This
paragraph is optional.
If it is not present, the name MAIN
is assigned to the program.

The remaining paragraphs are optional and,
if used,
can
appear
in any combination and in any order.
A comment
paragraph consists of any combination of characters from the
COBOL character
set organized to conform to COBOL sentence
and paragraph format.
All text appears as written on the
output listing except the DATE-COMPILED paragraph.
The first
line in this paragraph is deleted and replaced by the current
date.
Any remaining text in the DATE-COMPILED paragraph is
treated as comments.
Reserved words can be used
in any
comment paragraph.

2-2

CHAPTER 3
THE ENVIRONMENT DIVISION

The Environment Division allows you to describe the particular
computer configurations to be used for program compilation and
execution. In this division you also specify the files and devices
you will use for input and output. The Environment Division consists
of the division header (ENVIRONMENT DIVISION.) followed by one or more
of the following sections:
CONFIGURATION SECTION.

(See Section 3.1)

INPUT-OUTPUT SECTION.

(See Section 3.2)

3-1

THE ENVIRONMENT DIVISION

CONFIGURATION SECTION
3.1

CONFIGURATION SECTION

The CONFIGURATION SECTION allows you to describe the computers used
for program compilation and execution, and to assign mnemonlc-names
for input/output devices. The Configuration Section consists of the
section name
(CONFIGURATION SECTION.) followed by one or more of the
following paragraphs.
SOURCE-COMPUTER.

(See Section 3.1.1)

OBJECT-COMPUTER.

(See Section 3.1.2)

SPECIAL-NAMES.

(See Section 3.1.3)

Technical Notes
1.

This section is optional.

All commas and semicolons are optional.
A period must
terminate the entire entry in each of the three paragraphs.

3-2

THE ENVIRONMENT DIVISION

SOURCE-COMPUTER

3.1.1

SOURCE-COMPUTER

Function
The SOURCE-COMPUTER paragraph describes
program is to be compiled.

the

computer

which

the

General Format

[ SOURCE-COMPUTER.

computer-name.J
MR·S·973·81

Technical Notes
1.

This paragraph is optional.

You must use one of the following terms for computer-name:
DECsystem-IO
PDP-IO
DECSYSTEM-20
DECsystem-IOnn
where nn is a 2-digit integer in the range from 00 to 99.

•
Example
SOURCE-COMPUTER.

DECSYSTEM-I055.

3-3

THE ENVIRONMENT DIVISION

OBJECT-COMPUTER

3.1.2

OBJECT-COMPUTER

Function
The OBJECT-COMPUTER paragraph describes
program is to be executed.

the

computer

which

the

General Format

OBJECT-COMPUTER
[ MEMORY SIZE

{computer- name}
CHARACTE RS } ]
j WORDS

i nteger-l

t MODULES

[SEGMENT-LIMIT IS integer-2]
DISPLAY- 6
DISPLAY IS { DISPLAY-7
DISPLAY-9

1
MR-S-974-81

Technical Notes
1.

This paragraph is optional.

You must use one of the following terms for computer-name:
DECsystem-lO
PDP-IO
DECSYSTEM-20
DECsystem-lOnn
where nn is a 2-digit integer in the range 00 to 99.

The MEMORY SIZE clause is optional.
If it is omitted,
262,144 WORDS are assumed.
If it appears, the following
ranges are applicable.
CHARACTERS

Up to 1,572,864 (262,144 words x 6
characters/word)

WORDS

Up to 262,144

MODULES

Up to 256 (1 module equals 1024
words)

3-4

THE ENVIRONMENT DIVISION

OBJECT-COMPUTER (Cont.)
COBOL-68 ignores the MEMORY SIZE clause.
SORT uses its
default algorithms to determine the amount of memory needed
to execute a sort.
(Refer to the TOPS-IO and the TOPS-20
SORT User's Guides for more information.)
4.

If the SEGMENT-LIMIT clause is -given, only those segments
having segment numbers from 0 up to, but not including, the
value of integer-2 are considered as resident segments of the
program. Integer-2 must be a positive integer in the range 1
to 49.
If the SEGMENT-LIMIT clause is omitted, segments having
segment numbers from 0 through 49 are considered as resident
segments of the program (that is, SEGMENT-LIMIT IS 50 is
assumed). More on segmentation can be found in Chapter 5.

The DISPLAY IS clause is optional. If you specify DISPLAY
IS, then all data-items described as DISPLAY defaults to the
specified DISPLAY type. Using the DISPLAY IS clause also
causes the recording mode for external files to default to
the specified DISPLAY type.

Example
OBJECT-COMPUTER. DECSYSTEM-l077
MEMORY 50000 WORDS.

3-5

THE ENVIRONMENT DIVISION

SPECIAL-NAMES
3.1.3

SPECIAL-NAMES

Function
THE SPECIAL-NAMES paragraph provides a
names to input/output devices.

means

assigning

mnemonic

General Format

SPECIAL-NAMES.

[CONSOLE

[ CHANNEL

IS mnemonic-name-l ]

IS mnemonic-name-2 ]

(m)

[ CHANNEL

(n)

IS mnemonic-name-3

IS mnemonic-name-4

SWITCH

... ]

[ON

STATUS

[OFF

STATUS

IS condition-name-l

[OFF

STATUS

IS condition-name-2

IS condition-name-l ]

IS cond it i on-name-2 ]

(m)

OFF

[ON

[SWITCH

(n)

... ]

STATUS

IS mnemonic-name-5 ]

[CURRENCY

SIGN

[DECIMAL-POINT

condition-name-2 ]

IS condition-name-lJ

...

[literal-l

literal-2 ]

IS COMMA ] . .:.
MR-S-975-B1

3-6

THE ENVIRONMENT DIVISION

SPECIAL-NAMES (Cont.)
Technical Notes
1.

This paragraph is optional.

The reserved word CONSOLE refers to your terminal.
The
assigned mnemonic-name can be used with the ACCEPT and
DISPLAY verbs in the PROCEDURE DIVISION to input data from
and output data to the terminal.

The name CHANNEL refers to a channel on the line-printer
control tape. m and n represent any integer from 1 to 8 and
refer to anyone of the eight channels on the tape.
Control
tape channels can be referred to in the ADVANCING clause of
the WRITE verb in the PROCEDURE DIVISION to advance the paper
form to the desired channel position.
(Refer to the Hardware
Reference Manual for a description of printer
control
tapes.) For example, if the entry
CHANNEL (1) IS TOP-OF-PAGE
is included in this
statement prints the
next page.

paragraph, the following procedure
line and then skip to the top of the

IF LINE-COUNT IS GREATER THAN
BEFORE ADVANCING TOP-OF-PAGE.
4.

WRITE

PRINT-RECORD

The reserved word SWITCH is provided for compatibility with
other manufacturers' COBOL compilers. The use of the SWITCH
feature is discouraged in a time-sharing environment.
If
provided, the name SWITCH refers to the hardware switches on
the KA-10 or KI-10 console. The letters m and n in the
general format represent any integer from 0 to 35 and refer
to the corresponding console switches.
The mnemonic-name can be used in conditional expressions
the PROCEDURE DIVISION. For example, if the entry

SWITCH (4) IS INPUT-l
is included in this paragraph, the following
considered to be true if switch (4) is on.

condition

IF INPUT-l IS ON .•.•
If a condition-name is specified for the ON or OFF STATUS of
a switch, that condition-name can be used in a conditional
expression. For example, if the entry
SWITCH (4) IS INPUT-Ii

OFF STATUS IS NO-INPUT

is included in this paragraph, the
statements are functionally equivalent.
IF INPUT-l IS OFF ••..
IF NO-INPUT •.••

3-7

following

procedure

THE ENVIRONMENT DIVISION

SPECIAL-NAMES (Cent.)
5.

The clause literal-l IS mnemonic-name-5 specifies the CODE
value for a particular report (refer to the CODE clause in
Chapter 4). Literal-l must be a nonnumeric literal enclosed
in quotation marks, and can be from 1 through 120 characters
in length.

If you use the CURRENCY SIGN clause in the SPECIAL NAMES
paragraph, then the literal you specify replaces the standard
$ character
functions for PICTURE clauses in. the DATA
DIVISION.
This literal is limited to a single printable
must not be one of the following characters:

character

and

digits 0 through 9
alphabetic characters A, B, C, D, P, R, S, V, X, Z
special characters
7.

* + - , . ,

(

)

If you use the DECIMAL-POINT IS COMMA clause then the
functions of the comma and period are interchanged for all
PICTURE clauses and numeric literals.

Example
SPECIAL-NAMES. CONSOLE IS MYTERM
CHANNEL (1) IS TOP-OF-PAGE
SWITCH (10) IS LOOPER.

3-8

THE ENVIRONMENT DIVISION

INPUT-OUTPUT SECTION
3.2

INPUT-OUTPUT SECTION

The INPUT-OUTPUT SECTION names the files and external media required
by
the
object
program and provides information required for
transmission and handling of data during execution of the object
program.
This section consists of the section header (INPUT-OUTPUT
SECTION.) followed by one or more of the following paragraphs:
FILE-CONTROL

(See Section 3.2.1)

I-O-CONTROL

(See Section 3.2.2)

Technical Notes
1.

This section is optional.

All semicolons and commas are optional.
Each
SELECT
statement in the FILE-CONTROL paragraph must end with a
period. The entire entry in the I-O-CONTROL paragraph must
end with a period.

3-9

THE ENVIRONMENT DIVISION

FILE-CONTROL

3.2.1

FILE-CONTROL

Function
The FILE-CONTROL paragraph names each file,
identifies
medium, and allows logical hardware assignments.

the

General Format

FILE-CONTROL.SELECT

OPTIONAL

ASSIGN TO device-name-l

[FOR MULTIPLE

[RESERVE

[,device-name-2]

{~~i~ lJ

{~~tege r-l l

)
( FILE LIMIT IS
) FILE-LIMIT IS
(
[ ) FILE-L IMITS ARE,
{ FILE LI MITS ARE J

file-name

AL TERNATE

[{ data-name-ll
literal-l
(

data-name-3}
{ "literal-3

THRU

[ AREA
AREAS

THRU]

data-name-4 l]
{ literal-4 (

JJ
d a t a - n ame - 2 }
{ literal-2

---J

SEQUENTIAL [WITH CHECKPOINT OUTPUT [EVERY integer-l RECORDS]
RJI,NDm~
ACCESS MODE IS
--

{

INDEXED

IwITH{CHECKPOINT OUTPUT [EVERY
L
DEFERRED OUTPUT

i nteger-l RECORDS]]

PROCESSING MODE IS SEQUENTIAL
ACTUAL KEY IS data-name-5
MR-S-976-81

3-10

file

THE ENVIRONMENT DIVISION

FILE-CONTROL (Cont.)
IC}
[ { SYMBOL
NOMI NAL

KEY IS data-name-6

RECORD KEY IS data-n ame-7 ]
' -.:.=..;::::...::..:....=.

ASCII

SfXBfT
BINARY
RECORDING

MODE IS

£.
.'::L.
STANDARD-ASCI I
STANDARD ASCII

FILE-STATUS
[ FILE STATUS

IS data-name-8

[,data-name-9

[,data-name-ll

[,data-name-12

[, data-name-14

[ ,data-name-15] ] ] ] ] ] ] ]

[,data-name-lO

[,data-name-13

[SELECT •••• J ...
MR-S-977-81

Technical Notes
1.

This paragraph is optional.

All semicolons and commas are optional.
must end with a period.

The SELECT and ASSIGN clauses must appear before any other
clause shown,
and the SELECT clause must precede the ASSIGN
clause.
Every file described in the Data Division must be
named in a SELECT clause in the Environment Division.
Therefore, a SELECT filename ASSIGN TO device-name clause
must be specified for every file.
The other clauses can be
in any order.

The individual clauses are described on the
in the order shown above.

3-11

Each

SELECT

following

clause

pages

THE ENVIRONMENT DIVISION

SELECT

3.2.1.1

SELECT

Function
The SELECT statement names each file that is to be described
DATA DIVISION, and assigns each file to a particular device.

the

General Format

SELECT

[ OPTIONAL]

file-name ~ TO

}
1i te ra 1-1
{ device-name-l

,literal-2
[ , dev i ce - name- 2

MR-S~9;8~81

Technical Notes
1.

Each file described in the DATA DIVISION must be named once
and
only once as a file-name
in a SELECT, statement.
Conversely, each file named in a SELECT statement must have a
File Description entry in the DATA DIVISION.
Each file-name
must be unique within a program.

The key word OPTIONAL is required for input files
that are
not necessarily present each time the object program is run.
When an OPEN statement is executed for a file that has been
declared OPTIONAL,
the question IS file-name PRESENT? is
typed and the operator responds with YES or NO.
If the
response is YES,
the file
is processed normally;
if the
response is NO, the first READ statement executed for
that
file
immediately takes the AT END or INVALID KEY path.
ISAM
files can not be optional. They must be present at program
start-up, even if only as dummies.

for
a
file.
The ASSIGN clause specifies the device
Device-names can be either physical device-names or logical
device-names.
Physical device-names are fixed mnemonic-names that are
associated with specific peripheral devices.
When specified
in an ASSIGN clause, a physical device-name assigns the
associated file to that device.
Physical device-names are
described in the Operating System Commands manual.
Logical device-names are names created by the programmer.
They can contain up to six characters, consisting of any
combination of letters and digits.
At object execution time,
each logical device-name must be assigned to a physical
device by means of the TOPS-IO ASSIGN command or the TOPS-20
DEFINE command.

3-12

THE ENVIRONMENT DIVISION

SELECT (Cont.)
4.

The use of literals with the ASSIGN clause allows you to use
COBOL reserved words as legal device names. The literal name
must follow the same conventions as
the
device-name:
literals can contain up to six characters, consisting of any
combination of letters and digits. At object execution time,
each literal must be assigned to a physical device by means
of the TOPS-IO/TOPS-20 ASSIGN command or the TOPS-20 DEFINE
command.

More·than one device can' be assigned to a file to avoid delay
when switching from one reel or unit to the next. When more
than one
device
is
specified,
the
object
program
automatically uses the next device, in a cyclic manner, when
an end-of-reel condition is detected, or when a CLOSE REEL
statement is executed. This automatic switching occurs only
for tapes, SORT, and ISAM files.
It is unconditional for
tapes. For SORT/MERGE, you can assign any number of devices.
If the devices are all generic disk (i.e.
DSK), SORT/MERGE
uses its internal optimal algorithm to determine which
physical devices to use. For any other devices, all devices
specified are used in a round-robin fashion. You can assign
only two devices when you use ISAM.

If the access mode is INDEXED, and two devices are assigned,
the first device is assumed to contain the index portion of
the file and the second to contain the data portion of the
file.
If one device is specified, it is assumed to contain
both the index portion and the data portion of the file.

For ISAM and random files, the devices must be random-access.

Examples
SELECT INFIL ASSIGN TO DTAI.
SELECT SRTFIL ASSIGN TO DSK, DSK, DSK.

3-13

THE ENVIRONMENT DIVISION

FOR MULTIPLE

3.2.1.2

FOR MULTIPLE

Function
THE FOR MULTIPLE clause specifies that a tape-file occupies more reels
than the number of devices assigned.
The FOR MULTIPLE clause does
nothing when your program is compiled.
It is merely used for
documentation purposes only.
General Format

[ FOR

MULTIPLE

{~m} ]
MR·S·979·B1

Example
SELECT OUTFIL ASSIGN TO MTA
FOR MULTIPLE REEL.

3 .... 14

THE ENVIRONMENT DIVISION

RESERVE

3.2.1.3

RESERVE

Function
The RESERVE clause allows y-ou to specify an addi tional number of
input/output buffer areas to be allocated by the compiler to this
file.
General Format

[ RESERVE

I~~teger-l

}

ALTERNATE

]]
[ AREA
AREAS
MR-S-980-81

Technical Notes
1.

If the access mode is RANDOM or INDEXED, this
ignored and only one buffer area is assigned.

If the NO option is used, only one buffer area is allocated.

If the integer-l option is used, the integer specifies the
number of buffer areas to be assigned in addition to the two
areas always assigned by the compiler. If integer-l is less
than 0, only one buffer area is assigned.

You can specify a maximum of 62 areas for integer-l.
However, the optimal number of areas you can specify is
between 5 and 10. If you specify the number of areas to be
greater than 62, a warning message is generated. If you
specify a large (but legal) number of areas, you might run
out of available memory. Specifying a large number of areas
might also cause your program to run more slowly, since your
program is that much bigger.

Example
SELECT INFIL ASSIGN TO DSK
RESERVE 1 ALTERNATE AREA.

3-15

clause

THE ENVIRONMENT DIVISION

FILE-LIMIT

3.2.1.4

FILE-LIMIT

Function
The FILE-LIMIT clause is used to define the logical limits of
whose access mode is RANDOM.

file

General Format

data-name-l
THRU ]
} -literal-l

{d~ta-name-2}
llteral-2

}]
[. {m:~~~~~-3} THRU { data-name-4
literal-4
]

MRS,",,,

Technical Notes
1.

The FILE-LIMIT clause is required only for files whose access
mode is RANDOM;
it is optional for files with SEQUENTIAL
access mode residing on mass-storage devices.
It is ignored
in all other cases.

The words FILE and LIMIT (or LIMITS) can
the space or hyphen.

Every data-name used in this clause must be defined as USAGE
COMP or INDEX and must be an integer of 10 digits or less.

Each pair of operands represents a logical portion of the
is not
file.
If the first operand of the first pair
specified, it is assumed to be 1.

The operands represent logical record numbers relative to the
beginning of the file.
The first record is considered to be
1.

The logical beginning and end of a random-access file are the
records
specified
by
the
first
and last operands,
respectively, of the FILE-LIMIT clause.

The values of data items specified in this clause are used by
the object-time system only when the file is opened by an
OPEN statement.

tf a file whose access mode is RANDOM
is
processed
sequentially,
the FILE-LIMIT clause is ignored.
Thus, you
can create records with keys higher
than
the
upper
FILE-LIMIT.

3-16

separated

with

THE ENVIRONMENT DIVISION

FILE-LIMIT (Cont.)
;Example
SELECT INFIL ASSIGN TO DSK
F~LE LIMIT IS 3000.

3-17

THE ENVIRONMENT DIVISION

ACCESS MODE

3.2.1.5

ACCESS MODE

Function
The ACCESS MODE clause specifies the way in which a file is accessed.
General Format

SEQUENTIAL [WITH CHECKPOINT OUTPUT [EVERY integer-l RECORDS]
Rp.NDm1
ACCESS MODE IS
{ INDEXED

~ITH{CHECKPOINT OUTPUT [EVERY integer-l RECORDS]]
L
DEFERRED OUTPUT
MR-S-982-81

Technical Notes
1.

The ACCESS MODE clause is
indexed-sequential files.
files.

If ACCESS MODE IS SEQUENTIAL and the file
is
on
a
random-access device, the random-access records are obtained
or placed sequentially.
That is, the next logical record is
made available from the file on a READ statement execution,
and an output record is placed into the next available area
on a WRITE statement execution.
Thus sequential access
processing on a random-access device is functionally similar
to the processing of a magnetic tape file.

If ACCESS MODE IS RANDOM,
the contents of the data item
associated with the ACTUAL KEY specifies which record,
relative to the beginning of the file, is made available by a
READ statement,
or where the record is to be placed by a
WRITE statement.

If ACCESS MODE IS INDEXED, the contents of the data item
associated with the SYMBOLIC KEY specifies which record is
made available by a READ statement, or where the record is to
be placed by a WRITE statement, or which, record is to be
deleted by a DELETE statement, or which record is replaced by
a REWRITE statement.

The DEFERRED OUTPUT option of the INDEXED ACCESS MODE causes
the object-time system to output a block of an indexed
sequential file only when another block must be brought into
core.
Normally, to ensure security for the file, a block is
output every time a record is written, even if records are
written successively in the same block.
When a file is
opened for simultaneous update, the DEFERRED OUTPUT clause is
ignored.
Refer to the OPEN statement in Chapter 5.

3-18

required for
random-access and
It is ignored for
sequential

THE ENVIRONMENT DIVISION

ACCESS MODE (Cont.)

If you are using ISAM files sequentially, DEFERRED OUTPUT
provides the advantage of running faster.
However, it is
also more easily damaged if the system crashes.
Thus,
its
use is advantageous if file integrity is not important.

Specifying the CHECKPOINT OUTPUT phrase causes a checkpoint
FILOP. UUO
to occur after every physical output.
For
sequential files, every output may not coincide with each
WRITE.
For ISAM files,
the CHECKPOINT OUTPUT causes the
FILOP. UUO to occur after every output.
For ISAM files,
every output coincides with each WRITE.
Using the CHECKPOINT OUTPUT phrase has the same effect as if
you were to use a CLOSE followed by an OPEN.
However, the
CHECKPOINT OUTPUT phrase performs the action much faster than
the OPEN and CLOSE verbs.
Using the CHECKPOINT OUTPUT phrase
increases the reliability of your ISAM files,
but it slows
down the overall performance of your program.

If integer-l is zero, or if you do not specify the EVERY
integer-l RECORDS clause,
the checkpointing actions occurs
after every physical write.

Example
SELECT INFIL ASSIGN TO DSK, DSK
ACCESS MODE IS INDEXED WITH DEFERRED OUTPUT.

3-19

THE ENVIRONMENT DIVISION

PROCESSING MODE

3.2.1.6

PROCESSING MODE

Function
The PROCESSING MODE clause specifies that the file is to be
sequentially.

processed

General Format

[PROCESSING MODE

IS SEQUENTIAL]
MR-S-983-81

Technical Notes
This clause is for documentation only;
records
processed in the order in which they are accessed.
Example
SELECT INFIL ASSIGN TO MTAl
ACCESS MODE IS SEQUENTIAL
PROCESSING MODE IS SEQUENTIAL.

3-20

are

always

THE ENVIRONMENT DIVISION

ACTUAL KEY

3.2.1.7

ACTUAL KEY

Function
The ACTUAL KEY clause specifies which record is read or written
random-access file.

General Format

[ACTUAL KEY

IS data-name]
MR-S-984-81

Technical Notes
1.

The ACTUAL KEY clause is valid only for files whose access
mode is RANDOM;
it must be specified for those files.
This
clause cannot be used for files whose access modes are
INDEXED or SEQUENTIAL.

The
as
can
for

ACTUAL KEY data-name must be defined in the DATA DIVISION
a COMPUTATIONAL item of ten or fewer digits. The PICTURE
contain only the characters 8 and 9 or their equivalent,
example 89(10).

Example
SELECT INFIL ASSIGN TO D8K
ACCESS MODE IS RANDOM
ACTUAL KEY IS RKEY.

3-21

THE ENVIRONMENT DIVISION

SYMBOLIC KEY

3.2.1.8

SYMBOLIC KEY

Function
The SYMBOLIC KEY clause specifies the record in an indexed-sequential
file that is to be read, written, deleted or rewritten.
General Format

SYMBOLIC
NOMINAL

KEY

d'ata-name-l,

RECORD

KEY

data-name-2']
MR-S-985-81

Technical Notes
1.

NOMINAL KEY is completely equivalent to SYMBOLIC KEY.

The SYMBOLIC KEY clause is valid only for files whose access
mode is INDEXED;
it must be specified for those files (refer
to the READ statement in Chapter 5).

The SYMBOLIC KEY data-item must be defined in the DATA
DIVISION,
and must not appear in the record area of the file
to which it pertains.
It must agree with the description of
the RECORD KEY data item in class, usage, size, and number of
decimal places.

The RECORD KEY data-item must be defined as an item in the
record area of the file to which it pertains. Though the
RECORD KEY is described in only one of the records,
it is
assumed to occupy the same position in all records for that
file.

The RECORD KEY is required to describe the location in the
record area of the key for the file.
The contents of the
RECORD KEY data-item must be unique for each record in the
file,
and cannot be equal to LOW-VALUES (refer to the READ,
WRITE, REWRITE, and DELETE statements in Chapter 5).

Example
SELECT INFIL ASSIGN TO DSK, DSK
ACCESS MODE IS INDEXED
SYMBOLIC KEY IS SYMKEY, RECORD KEY IS RECKEY.

3-22

THE ENVIRONMENT DIVISION

RECORDING MODE/DENSITY/PARITY

3.2.1.9

RECORDING MODE/DENSITY/PARITY

Function
The RECORDING MODE clause specifies the r-ecording mode, tape
and parity for a magnetic tape file.

density,

General Format

RECORDING

~ODE

S I XB IT

BINARY

A.S..W

IS [BYTE MODE]

}]

{ fTANDARD-ASCII

STANDARD ASCII

[ DENSITY IS

tm}1[URill

(~~~N lJ
MR-S-986-81

Technical Notes
1.

The RECORDING MODE clause allows you to record data on
device in a format other than that used in memory.
following recording modes are acceptable.
ASCII

the
The

five
- The file is read/written as ASCII records,
Bit 35 (the
7-bit characters per
36-bit word.
rightmost bit) is ignored.

six
SIXBIT - The file is read/written as SIXBIT records,
6-bit
characters
per 36-bit word with record
headers.
BINARY - The file is read/written as binary records, 36
per word.
F

bits

The file
is read/written as fixed-length EBCDIC
records,
four
9-bit characters per 36-bit word for
everything but industry-compatible magnetic tape.
For industry-compatible magnetic tape (9-track, with
800, 1600, and 6250 bpi density),
the file
is
read/written with four 8-bit characters per 36-bit
word.
If more than one record description is given
in the FD entry, the record length must be the same
for all records in the entry.

3-23

THE ENVIRONMENT DIVISION

RECORDING MODE/DENSITY/PARITY (Cent.)
V

- The file is read/written as variable-length EBCDIC
records, four 9-bit characters per 36-bit word with
record
and
block
headers.
However,
for
industry-compatible magnetic tape
(9-track, with
800, 1600, or 6250 bpi density), the file is
read/written with four 8-bit characters per 36-bit
word. If a file whose recording mode is V is open
for INPUT-OUTPUT and you overwrite a record, the
record being written must be the same size as the
overwritten record. A file whose recording mode is
V cannot be opened for simultaneous update.

STANDARD-ASCII (STANDARD ASCII)
The five 7-bit bytes in each word in core are
transferred to five 8-bit bytes on the tape and bit
35 is stored in bit 0 of the fifth byte on tape.
The character set and the character encodings are
the same as those of ASCII recording mode.
This
enables interchanges with other manufacturers' ASCII
data files.
The format of records for each recording
Section 4.11.2.11.
2.

mode

given

The recording mode of a file is determined by a number of
factors besides the recording mode specified in the RECORDING
MODE clause. These factors are:
a.

If the device can only accept ASCII data (For example,
Line Printer), the object-time system always uses ASCII
as the recording mode no matter what recording mode is
specified.

If the ADVANCING or POSITIONING clause is included in the
WRITE statement, the object-time system always uses ASCII
as the recording mode no matter what recording mode is
specified.

If the file descriptor (FD) has a REPORT clause, the
object-time system always uses ASCII as the recording
mode no matter what recording mode is specified.

The recording mode specified in the RECORDING MODE clause
is compared to the USAGE clause for the record. The
recording mode is determined in the following sequence:
1.

The recording mode that is specified is used.

If the recording mode is not specified, the default
recording mode depends on the usage mode that is
specified.

If neither the recording mode nor the usage mode is
specified, the default recording mode depends on the
display mode.

3-24

THE ENVIRONMENT DIVISION

RECORDING MODE/PARITY/DENSITY (Cont.)
4.

If none of the above has been specified, the default
recording mode is SIXBIT,
unless the /X switch is
included in the command string to the compiler or the
DISPLAY is DISPLAY-6/7/9.
If the /X switch is
included, the default recording mode is F.
If the
DISPLAY is DISPLAY-6/7/9, then the default recording
mode is SIXBIT/ASCII/F.

When the recording mode is not declared, it is inferred from
the usage mode for the record according to the rules given
above.
However, the reverse is not true.
That is, when the
recording mode is declared and no usage mode is given for a
record, the presence of the- RECORDING MODE clause serves only
to specify the recording mode of the file.
The usage mode of
the records in the file can default to another character set,
with undesirable results (see the USAGE clause in Chapter 4).
Table 3-1 shows the resulting recording mode when the
recording mode declared in, the RECORDING MODE clause is
compared to the usage mode declared in the USAGE clause.
3.

The DENSITY and PARITY clauses are valid only for
magnetic
tape,
and are ignored for all other devices.
If the DENSITY
clause is hot present, tapes are recorded in the density
standard for the installation.
The density for a job can be
modified by the SET DENSITY command, which is described in
the TOPS-IO Operating Systems Manual and the TOPS-20 User's
Guide. A density of 1600 or 6250 bpi can be specified only
for
tapes being read/written to or from magnetic tape drives
that can use that density.
If the PARITY clause is omitted,
ODD is assumed.
Care must be taken when using even parity.
If nulls are written into a file that is recorded in even
parity,
the file cannot be read properly.
Nulls can be
written into a file without you being aware of them;
that
is, when SYNCHRONIZED data items appear in an item, the word
preceding the word in which the item is synchronized could
contain nulls.

If BYTE MODE is used, the exact number of bytes is written on
the tape.
BYTE MODE truncates;
it does not round up to word
boundary.
This occurs only on magnetic tape.
BYTE MODE
applies only to users of TOPS-IO and only to sequential
files.
Its purpose is to enable interchanges with other
manufacturers' equipment.

Example
SELECT INFIL ASSIGN TO MTAI
RECORDING MODE IS V
DENSITY IS 800
PARITY IS ODD.

3-25

THE ENVIRONMENT DIVISION

RECORDING MODE/DENSITY/PARITY (Cont.)
Table 3-1
Recording Modes

USAGE Clause

Recording Mode
actually used

none

DISPLAY-6

SIXBIT

none

DISPLAY-7

ASCII

none

DISPLAY-9

EBCDIC

none

SIXBIT (no IX)
or DISPLAY-6

none

EBCDIC (IX)
or DISPLAY-9

none

ASCII (DISPLAY-7)

SIXBIT

DISPLAY-6

SIXBIT

DISPLAY-7

SIXBIT

DISPLAY-9

SIXBIT

ASCII

DISPLAY-6

ASCII

DISPLAY-7

ASCII

DISPLAY-9

ASCII

F or V

DISPLAY-6

EBCDIC

F or V

DISPLAY-7

EBCDIC

F or V

DISPLAY-9

EBCDIC

BINARY

DISPLAY-6

BINARY

DISPLAY-7

BINARY

DISPLAY-9

BINARY

RECORDING MODE
Clause

NOTE
Conversions necessary
to
make
the
recording mode conform to the usage mode
of the records are made automatically by
the
object-time
system.
(These
conversions can cause your program to
run more slowly.)

3-26

THE ENVIRONMENT DIVISION

FILE STATUS

3.2.1.10

FILE STATUS

Function
The FILE STATUS clause specifies data-items into which LIBOL places
values when an I/O error or warning message occurs on the file
specified by the SELECT clause. A user-written USE procedure can then
examine and alter these values as part of a recovery process.
General Format

FILE-STATUS}
STATUS IS data-name-l [ ,data-name-2 [,data-name-3 [,data-name-4
{ FILE

[, data- name- 5 [, data- name-6 [, data-n ame-7 [, dat a-name-8] ] ] ] ]

MR-S-987-81

Technical Notes
1.

Data-name-l is required if this clause is specified;
but
data-name-2 through data-name-8 are optional.
If fewer than
eight data-names are specified, the compiler assumes that the
data-names
are specified starting with data-name-l and
continuing in order. Therefore, if data-name-8 is specified,
data-name-l through data-name-7 must also be specified.

3-27

THE ENVIRONMENT DIVISION

FILE STATUS (Cont.)
2.

The data-names must be defined in the WORKING STORAGE SECTION
of the DATA DIVISION in the following form:
data-name-l
data-name-2
data-name-3
data-name-4
data-name-5
data-name-6
data-name-7
data-name-8

PIC 9(2).
PIC 9 (10) .
USAGE INDEX.
PIC X(9).
USAGE INDEX.
USAGE INDEX.
PIC X(30).
USAGE INDEX.

After a fatal I/O error, the FILE STATUS
following values:
data-name-l
data-name-2
data-name-3
data-name-4
data-name-5
data-name-6
data-name-7
data-name-8

contains
contains
contains
contains
contains
contains
contains
contains

items

contain

the file status.
a ten digit error number.
the action code, which is set to zero.
the VALUE OF ID.
the current block number.
the current record number.
the file name.
the file-table pointer.

The file status, which is stored in data-name-l, is set to one of
following 2-character codes.
00
10
22
23
24
30
34

the

The I/O was successful.
No next logical record;
that is, there is no next record
in the file.
The AT END path is taken.
Duplicate key;
that is, an attempt was made to write a
record
into a record position that is already occupied.
The INVALID KEY path is taken.
No record found on READ, REWRITE, DELETE;
that is,
when.
an indexed sequential file was accessed, an empty record
position was found.
The INVALID KEY path is taken.
Boundary violation, that is, the random file's actual key
violated the file limits.
The INVALID KEY path is taken.
Permanent error;
that is,
a
successful
hardware
operation cannot be done without a hardware error signal.
Permanent error; . that is, more space on the media cannot
be obtained to extend the file for output operations.

The 10-character error number stored in data-name-2 has the form:
ABCDEFGHIJ
where the code has the meanings shown below.
AB contains a value indicating the COBOL verb that caused the error.

1
2
3
4
5
6
7

No COBOL verb error
OPEN
CLOSE
WRITE
REWRITE
DELETE
READ
RETAIN

3-28

THE ENVIRONMENT DIVISION

FILE STATUS (Cont.)
CD contains a value indicating the monitor call
error.

o
1
2
3
4
5
6
7
8

the

I
being

accessed

when

None of the following
ISAM index file
ISAM data file
A sequential file
A random file

G contains a value indicating the
accessed when the error occurred.
1
2
3
4

that caused

No UUO error
INPUT
OUTPUT
LOOKUP
ENTER
RENAME
INIT
FILOP
TAPOP

EF contains a value indicating the type of file
the error occurred.
1
2
3
4

(UUO)

ISAM

block

type

that

was

being

None of the following
ISAM statistics block
ISAM SAT block
ISAM index block
ISAM data block

HIJ contains a value indicating an error number on INPUT or OUTPUT.
If CD is set to 0, HIJ contains an error number.
The numbers and
their meanings are listed below.
Note that these are the same as the
messages issued by LIBOL after an error or warning occurs.

o
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

None of the following.
SYMBOLIC-KEY must not equal low-values.
No more index levels available.
Insufficient core while attempting to split the top
index
block.
Version number discrepancy.
Allocation failure - all blocks are in use.
The maximum record size may not be exceeded.
Cannot expand core while SORT is in progress.
Insufficient core for buffer requirements.
Blocking-factor differs between index file and file-table.
File cannot be opened, already open.
Locked file cannot be opened.
File cannot be opened shares buffer area with opened file.
File cannot be opened device is not available to this job.
File cannot be opened device is assigned to another file.
File cannot be opened device cannot input/output.
File cannot be opened device cannot input.
File cannot be opened device cannot output.
File cannot be opened device is not a device.
File cannot be opened directory device must have standard
labels.
File cannot be closed because it is not open.
3-29

THE ENVIRONMENT DIVISION

FILE STATUS (Cont.)
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
52
53
54
55
56

File cannot be closed.
The CLOSE "REEL" option
may
not
be
used
with
a
multi-file-tape.
File is not open for output.
Zero length records are illegal.
File cannot do output.
"AT END" path has been taken.
File cannot do input.
Encountered an "EOF" in the middle of a record.
File cannot do input.
RECORD-SEQUENCE-NUMBER n should be m.
File cannot do input.
file-name on device-name should be reorganized, the top index
block was just split.
Not used.
Either the ISAM file does not exist or the VALUE OF ID
changed during the program.
Attempt to do I/O fro~ a subroutine called by a non resident
subroutine.
File cannot be opened.
I/O cannot be done from an overlay.
File cannot be opened.
Read an "EOF" instead of a label.
CLOSE REEL is legal only for magnetic tape.
File is not open for input.
Not enough free core between .JBFF and overlay area.
Not enough free core between .JBFF and overlay area.
Insufficient core while attempting to split the top index
block.
Standard ASCII recording mode and density of 1600 BPI require
the device to be a TU70.
TAPOP.
Failed - Unable to set STANDARD-ASCII mode.
Got an EOF in middle of BLOCK/RECORD descriptor word.
Block descriptor word byte count is less than five.
ERROR - Got another buffer instead of "EOF".
ERROR - Record extends beyond the end of the logical block.
It is illegal to change the record size of an EBCDIC 10
record.
The two low order bytes of RDW/BDW must be zero,
spanned
EBCDIC not supported.
TAPOP.
failed - Unable to set HARDWARE DATA MODE.
Unable to get mag tape status information.
Cannot set requested density.
TAPOP.
failed - unable to get/set label type/information.
Improper tape label format for indicated recording mode.
Improper default hardware data mode for ASCII system-labeled
tape.
ANSI-labeled "S" and "D" mag tape not supported.
Program can not have OPEN I/O and OPEN EXTEND for
same file
FD.
TAPOP.
failed, unable to switch mag tape reels.

If CD is set to 1 or 2, HIJ contains the number of an I/O error status
bit.
The I/O error status bits, their mnemonics, and their meanings,
are shown in Table 3-2.

3-30

THE ENVIRONMENT DIVISION

FILE STATUS (Cont.)

Table 3-2
Monitor File .Status Bits
Bit

Mnemonic

Meaning

IO.IMP

Improper Mode. Attempt to write on a
write-locked
file structure, or a
redundancy failure occurred.
This
usually set by the monitor. You cannot
bit.

IO.DER

Hardware
error,
However,
disk is
set this

IO.DTE

Hard data error. The data read or written has
incorrect parity as detected by the hardware.
Your data is probably unrecoverable even after
the device has been fixed. This bit is usually
not set by you.

IO.BKT

Block too large. A disk data block is too large
to fit into the buffer; or a block number is
too large for the disk unit; or DSK has been
filled; or your quota on the file structure has
been exceeded. This bit is usually not set by
you.
This error is also returned when you try
to close a file that has open locks associated
with it (using Enqueue/Dequeue).

IO.EOF

End-of-file. Your program has requested data
beyond the last block of the file with an IN or
INPUT call; or USETI has specified a block
beyond the last data block of the file. When
IO.EOF is set, no data has been read into the
buffer.

IO.ACT

I/O Active. The disk is actively transmitting
or receiving data.
This bit is always set by
the monitor.

IO.WHD

write disk pack headers.
This is used in
conjunction with the SUSET.
monitor call to
format a disk pack.

IO.SYN

Synchronous mode I/O.
stop
buffer is read or written.

IO.UWC

User word count, supplied by you in each buffer.

32-35

IO.MOD

Data mode of the device.

software
software
bit
is
set this

devife error.
The disk unit is in
rather than the data on the disk.
data read into core or written on the
probably incorrect. You do not usually
bit.

3-31

disk

after

every

THE ENVIRONMENT DIVISION

FILE STATUS (Cont.)
For the file status for
Manual.

each

device,

refer

the

Monitor

Calls

If CD is set to 3, 4, 5, or 7, HIJ contains the error code for LOOKUP,
ENTER, RENAME, or FILOP errors. Table 3-3 gives these codes and their
meanings.
Table 3-3
Monitor Error Codes
Explanation

Code

File not
found,
illegal
filename
(0,*),
filenames do not match, or RENAME after a LOOKUP
failed.

UFD does not exist.on specified file structures.
(Incorrect project-programmer number.)

Protection failure or directory full on DTA.

File being modified.

Already existing filename (RENAME) or different
filename (ENTER after LOOKUP) or supersede (on a
non-superseding ENTER) ..

Illegal sequence of UUOs (RENAME with neither
LOOKUP nor ENTER, or LOOKUP after ENTER).

1.
2.
3.

Transmission, device, or data error.
Hardware-detected device or
data
error
detected while reading the UFD RIB or UFD
data block.
Software-detected data inconsistency error
detected while reading the UFD RIB or file
RIB.

Not a saved file.

Not enough core.

Device not available.

No such device.

No 2-register relocation capability.

No room on this file structure or quota exceeded
(overdrawn quota not considered).

write-lock
structure.

Not enough table space in free core of monitor.

error.

3-32

Cannot

write

file

THE ENVIRONMENT DIVISION

FILE STATUS (Cont.)

Table 3-3 (Cont.)
Monitor Error Codes
Code

Explanation

Partial allocation only.

Block not free on allocated position.

Cannot supersede an existing directory.

Cannot delete a non-empty directory.

Sub-directory not found
(some
specified path was not found).

Search list empty (LOOKUP or ENTER was performed
on generic device DSK and the search list is
empty) .

Cannot create a SFD nested deeper
maximum allowed level of nesting.

No file structure in the job's search list has
both the no-create bit and the write-lock bit
equal to zero and has the UFD or SFD specified
by the default or explicit path
(ENTER on
generic device DSK only).

GETSEG from a locked low segment to a high
segment which is not a dormant, active, or idle
segment.
(Segment not on the swapping space.)

Cannot update file.

Low segment overlaps high segment.

Not logged in.

SFD

than

the

The FILE STATUS items are the communications paths between
LIBOL and a USE procedure.
A USE procedure specifies a
recovery process executed when an error or warning occurs
during an I/O operation.
A USE procedure determines the
error or warning type from the error-number placed into
data-name-2 by LIBOL.
Control returns to LIBOL at the
conclusion of the USE procedure.
The contents of the
action-code placed into data-name-3 by the USE procedure and
the error-number determine the subsequent LIBOL action.
If
the action-code
is set to 1, LIBOL ignores the error and
continues the run.
If the action-code is left set to 0,
LIBOL issues an error message and terminates the run.
If the
error-number is 17, LIBOL continues the run independent of
the action-code setting.
If the action-code is not 0 or 1,
the LIBOL action is undefined.

3-33

THE ENVIRONMENT DIVISION

FILE STATUS (Cant.)
When the program comes to a normal termination and you
requested that errors be ignored, LIBOL issues the following
message:
%n ERRORS IGNORED
5.

Refer to the USE statement
writing USE procedures.

Chapter

If the FILE STATUS statement is not specified,
I/O error
recovery processing cannot be performed.
If the FILE STATUS
statement is specified with only data-name-l included, you
can examine the status of the file, but you cannot specify
that LIBOL ignore the error because you cannot set the action
code (data-name-3).
You also cannot examine the error number
(data-name-2) .

Example

SELECT INFIL ASSIGN DSK, DSK
ACCESS MODE IS INDEXED
SYMBOLIC KEY IS SYMKEY, RECORD KEY IS RECKEY
RECORDING MODE IS ASCII
FILE STATUS IS FILSTAT, ERRNUM, ACTCODE, VID,
BLKNUM, RECNUM, FILNAM, FILPNTR.

DATA DIVISION.

WORKING-STORAGE SECTION.
77 SYMKEY
PIC X(lO).
77 FILSTAT PIC 9(2).
77 ERRNUM
PIC 9(10).
77 ACT CODE INDEX.
77 VID
PIC X(9).
77 BLKNUM
INDEX.
77 RECNUM
INDEX.
PIC X(30).
77 FILNAM
77 FILPNTR INDEX.

3-34

for

details

THE ENVIRONM~NT DIVISION

I-O-CONTROL
3.2.2

I-O-CONTROL

Function
The I-O-CONTROL paragraph specifies the points at which a rerun dump
is to be performed, the memory area that is to be shared by different
files, and the location of files on a multiple-file reel.
General Format

I-O-CONTROL.

EVERY.END OF
lnteger-l

~6~~RD J
[MULTIPLE

FILE

[ ,fil e-name-6

TAPE

I~ I

AREA

UNIT.
RECORDS

FOR

CONTAINS

[POS ITI ON

file-narne-l

fi 1e- name- 2, f i 1e- name-3

[ ,f i 1e - narne - 4 ]

file-name-5

integer-2 ]

i nteger- 3 ] ]

... ]

[POSITION

...

... J

-'.
MR-S-988-81

Technical Notes
1.

This paragraph is optional.

The RERUN clause
performed.

specifies

when

rerun

dump

The dump is always written onto a disk file,
using the
program's low segment name as the filename, and an extension
of CKP.
If the program has no filename because it was never
SAVEd, the program name (from the PROGRAM-ID paragraph in the
IDENTIFICATION DIVISION) is used as a filename,
with the
extension CKP.
If the END OF UNIT option is used, a rerun dump is taken at
the end of each input or output reel of the specified REEL
file.

3-35

THE ENVIRONMENT DIVISION

I-O-CONTROL (Cont.)
If the integer-l RECORDS option is used, a rerun dump is
taken whenever a number of logical records equal to a
multiple of integer-l is either read or written for the file.
A rerun dump is not taken if any file is open on a device
other than magnetic tape, disk, or terminal. Also, RERUN
cannot be used if overlays are used or if files are open for
simultaneous update.
Do not attempt to have a rerun dump
taken while a sort is in progress.
3.

The SAME AREA clause specifies that two or more files are to
use the same area during processing;
this includes all
buffer areas and the record area. However, unless the RECORD
option is used, only one of the named files can be open at
one time.
If the RECORD option is specified, the files share only the
record area (that is, the area in which the current logical
record is processed). If files sharing a record area are
open at the same time but their records do not have the same
usage mode, no conversion automatically takes place.
The SORT option is used for sort files. However, this option
need not be specified because all sort files always use the
same sort area.

The MULTIPLE FILE clause is required when more than one file
shares the same physical reel of tape.
This clause is
invalid for media other than magnetic tape.
Regardless of the number of files on a single reel, only
those files defined in the program can be listed. If all
files residing on the tape are listed in consecutive order,
the POSITION option need not be given. If any file on the
tape is not listed, the POSITION option must be included;
integer-2, integer-3, and so forth, specify position of the
file relative to the beginning of the tape. All files on the
same reel of tape must be ASSIGNed to the same device in the
FILE-CONTROL paragraph.
Not more than one file on the same reel of tape can
at one time.

Example
I-O-CONTROL.
RERUN EVERY 300 RECORDS OF INFIL
SAME RECORD AREA FOR INFIL, OUTFIL
MULTIPLE FILE TAPE CONTAINS INFIL POSITION 4.

3-36

open

CHAPTER 4
THE DATA DIVISION

The Data Division, required in every COBOL program,
describes
the
characteristics of the data to be processed by the object program.
This data can be divided into six major types:

Data contained in files, both input and output.

Data contained in a database and accessed
Base Management System (DBMS).

Data to be sent to
System (MCS).

Data initially stored as part of the program, as variables or
constants.
This can include constant data such as messages,
tables of fixed values,
and
the like,
or data developed
during processing, that is, intermediate information such as
partial arithmetic results.

Data in a subprogram that is passed from the program
it.

calling

Data to be printed in a report, and the format used to
such data.

To handle these types of data,
following sections:

received

the

Data

from

the

Division

through

the

Message

consists

Data

Control

the

The FILE SECTION, which describes the characteristics and the
data formats for each file processed by the object program.

The SCHEMA SECTION, which names the sub-schema and schema
that link a program or subprogram to the Data Base Management
System (DBMS).

The COMMUNICATION SECTION, which defines the special data
items that link a program or
subprogram to the Message
Control System (MCS).

The WORKING-STORAGE SECTION, which contains any fixed values
and the working areas in which
intermediate data can be
stored.

The LINKAGE SECTION, which describes the data in a subprogram
that is available from the calling program.

The REPORT SECTION, which describes the data and format of
report.

4-1

THE DATA DIVISION
However,

Unused sections of the Data Division can be omitted.
sections included must be in the following order:

the

FILE SECTION.
SCHEMA SECTION.
COMMUNICATION SECTION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
REPORT SECTION.

4.1

FILE SECTION

In the File Section, the characteristics of each file to be
are described by two types of entries.

processed

The first type of entry, the file description, describes the
aspects of the file. These aspects include:

physical

How the logical data records of the file
grouped into blocks on the file medium.

are

The maximum length of a logical record, which
4095 characters.

cannot

Whether or not the file contains header and trailer labels
and, if so, whether the format of these labels is standard or
nonstandard.

The names of the records contained in the file.

The names of any reports in the file.

The second type of entry, the data description,
formats of the logical records in the files.

exceed

the

data

The File Section begins with the section-header FILE SECTION.
present, it must be the first section in the DATA DIVISION.

4.2

describes

physically

SCHEMA SECTION

In the Schema Section, the names of the sub-schema and schema to be
processed are specified by either an INVOKE statement or an ACCESS
statement.
The Schema Section begins with the section-header
and must follow the File Section, if present.

(SCHEMA

SECTION.)

If the installation does not include DBMS, the Schema
be used.

Section

A description of the contents of the Schema Section can
the Data Base System Programmer's Procedures Manual.

4-2

cannot

found

THE DATA DIVISION
4.3

COMMUNICATION SECTION

In
the
Communication
Section,
input
communication-description entries are defined.

and

output

CD entries define records, called CD records,
that contain special
data items used to link the program to the Message Control System
(MCS-lO) •
The Communication Section begins with the section-header COMMUNICATION
SECTION.
and must fol19w the File Section and precede the Report
Section. The Communication Section must also follow the Schema
Section if both are present.
If the installation does not include MCS,
cannot be used.

the

Communication

Details of the Communication Section entries can be
Message Control System Programmer's Procedures Manual.

4.4

found

Section
in

the

WORKING-STORAGE SECTION

The Working-Storage Section defines (1) data that is stored when the
object program is loaded, and (2) areas used for intermediate results.
The Working-Storage Section is similar to the File Section, except
that the Working-Storage Section can contain level-77 items and cannot
contain FD, SD, or RD entries.
The
Working-Storage
Section
WORKING-STORAGE SECTION.
The ma*imum size
characters.

4.5

data

begins
item

with
WORKING

the

section-header

STORAGE

262,143

LINKAGE SECTION

The Linkage Section describes data available from a calling program
and can appear only in a subprogram.
The structure is the same as
that of the Working-Storage Section with the following restrictions:
1.

The VALUE clauses can only be used in condition-name entries.

The data-names used in the VALUE OF IDENTIFICATION
(or
ID),
the VALUE OF DATE-WRITTEN,
and the VALUE OF USER' NUMBER
cannot appear in this section.

The OCCURS clause with the DEPENDING phrase cannot be defined
in this section.

The SYMBOLIC KEY and ACTUAL KEY data items cannot be
in this section.

The data items in the FILE-LIMITS clause cannot be defined in
this section.

defined

Data described in the Linkage Section of a subprogram is not allocated
storage space.
Instead, at link-time, the link program sequentially
equates the Linkage Section identifiers (listed in the USING clause of
the ENTRY statement within the subprogram or in the USING clause of
the PROCEDURE DIVISION header within the subprogram)
to the calling
4-3

THE DATA DIVISION
program identifiers (listed in the USING clause of the CALL statement
within the calling program). Thus, when the Procedure Division of a
subprogram executes, references to the Linkage Section data refer
instead to the calling program data.
Thus:
CALLING PROGRAM

CALLED PROGRAM

DATA DIVISION.
FILE SECTION.
FD ...
01 MAIN .•.
02 MAINl •.•
02 MAIN2 ...

DATA DIVISION.
FILE SECTION.
LINKAGE SECTION
01 SUB .. .
02 SUBl .. .
02 SUB2 .. .

PROCEDURE DIVISION.

PROCEDURE DIVISION.
ENTRY ENTRPT USING SUB.

CALL ENTRPT USING MAIN.
EXIT PROGRAM.

The identifier MAIN is defined in the File Section of the calling
program;
the identifier SUB is defined in the Linkage Section of the
called program. When the Procedure Division of the called program
executes, references to SUB refer instead to MAIN. See the COBOL-68
User's Guide for more information about subprograms.
Each 01- or 77-level item in the Linkage Section must have a unique
name because it cannot be qualified. Also, each 01- and 77-level item
must correspond to a word-aligned item of the same size or larger in
the calling program. Word-aligned items start at the beginning of a
computer word. All 01- and 77-level items fulfill this requirement;
items that do not, can be made to do so by the SYNCHRONIZED LEFT
statement.

4.6

REPORT SECTION

The Report Section defines reports by describing the
physical
appearance of the particular format and data rather than by specifying
the procedure used to produce the report.
The data for a report can be read from a file or another part of the
program or can be summed within the Report Section. The format of the
report is given in the record description and report group entries in
the Report Section.
The Report Section begins with the section-header REPORT SECTION., and
must follow the File Section, the Working-Storage Section and the
Linkage Section.

4-4

THE DATA DIVISION

4.7
4.7.1

DATA DESCRIPTIONS
Elementary Items and Group Items

The basic user-defined datum in a COBOL program is called an
elementary item;
it can be referenced directly only as a unit.
An
elementary item can be associated with contiguous elementary items to
form sets of data items called group items.
Group items can be
associated with other group items and/or elementary items to form more
inclusive group items.
Thus,
an elementary item can be contained
within one or more group items, and a group item can contain more than
one elementary item.

4.7.2

Level Numbers

Level numbers indicate a hierarchy in which data items are ranged.
The highest level
is 01, which signifies that the data item is a
record within a file named in an FD clause (or is a contiguous area in
the WORKING-STORAGE SECTION).
Level numbers of 02 through 49 indicate
items that are subordinate to a Ol-level data item.
For example,
an
employee record can be described in the following manner.
01 EMPLOYEE-RECORD.
02 NAME.
03 FIRST-NAME PICTURE IS A(6).
03 MIDDLE-INITIA~ PICTURE IS A.
03 LAST-NAME PICTURE IS A(20) .
02 BADGE-NUMBER PICTURE IS X(5).
02 SALARY-CLASS PICTURE IS X(2).
Within a record description, the level numbers indicate which items
are contained within higher-level
items.
That is,
in the above
example, the items that have a 03 level are subordinate to NAME, which
has a 02 level, which is in turn subordinate to EMPLOYEE-RECORD, which
has a 01 level.
The example also shows elementary items
(those that
contain PICTURE clauses)
contained within group items.
In this
example, EMPLOYEE-RECORD is a group item,
NAME is a group item
contained within a group item, and FIRST-NAME is an elementary item
contained within the group item NAME.
An item at a 01 level can be an
elementary item as well as a group item as long as it is referenced as
a unit.
For example:
01 EMPLOYEE-RECORD PICTURE IS A(34) .
shows the same record as above, but in this case the record is
operated on as a single entity.
Three other level numbers are available to the COBOL programmer:
66, and 88.

always
77,

Items with a level number of 77 are noncontiguous elementary items
that are written only in the WORKING-STORAGE SECTION to define
constant values and to store intermediate results.
Level-66 data items are those items that contain an explicitly
specified portion of a record, or even the whole record.
A data item
at a level of 66 is used in a RENAMES clause to regroup items within a
4-5

THE DATA DIVISION
record.
After
a
record
is described,
a level-66 item RENAMES a
portion of that record.
The level-66 data item can be a regrouping of
the whole record, a group within the record, or a combination of group
and elementary items.
For example:
01 EMPLOYEE-RECORD
02 NAME
03 FIRST-NAME ...
03 MIDDLE-INITIAL ...
03 LAST-NAME ...
02 BADGE-NO ...
02 SALARY-CLASS ...
66 PERSONNEL-REC RENAMES NAME THRU BADGE-NO.
66 PAY-REC RENAMES LAST-NAME THRU SALARY-CLASS.
When the level-66 item PAY-REC is referenced,
the
items LAST-NAME,
BADGE-NO.,
and SALARY-CLASS are referenced as a unit.
The programmer
can thus regroup portions of a record for differing purposes.
Level-88 items are condition-names that cause a value or a
range of
values to be associated with a data item.
The condition-name can then
be used in place of the relation condition in conditional expressions
in the PROCEDURE DIVISION.
For example:
03 BADGE-NO ...
88 FIRST-BADGE VALUE IS "AOOOl".
88 LAST-BADGE VALUE IS "Z9999".
In a comparison, the following statements would then be equivalent:
Conditional Variable

Condition-Name

IF BADGE-NO IS EQUAL TO "AOOOl" .. .
IF BADGE-NO IS EQUAL TO "Z9999" .. .

4.7.3

IF FIRST-BADGE ...
IF LAST-BADGE •..

Records and Files

Records can be divided into two categories;
those associated with a
file and those not associated with a file.
A file is the highest
level of data organization in COBOL;
it represents a collection of
data records held on some external medium, that is, not wholly in real
or virtual memory.
Records not associated with a
file are those
values stored in the WORKING-STORAGE and LINKAGE SECTIONS or sum
counters in the REPORT SECTION.

4.8

QUALIFICATION

Any data item that is to be referenced must be uniquely
identified.
This unique
identification can be achieved by the assignment of a
unique name to each item.
However,
in many applications this
is
tedious and
inconvenient
(1)
because of the large number of names
required,
and
(2)
because items containing the same
type
of
information
in
different
records would have different names.
Therefore, qualification is introduced to allow similar
items and
certain records to have identical names.

4-6

THE DATA DIVISION
Qualification means giving enough information about the
item to
specify it uniquely.
In COBOL, this information is the name of the
group items containing it, in order of increasing inclusiveness.
It
is not necessary to name each group containing it, but only enough
groups so that no other item with the same name as the original
item
could be identically qualified.
It is also unnecessary to name each
successively higher group containing the item until
a
unique
qualification is made.
Any set of names that uniquely describe the
item can be used.
Example:

01
02

RECORD-I.
01
RECORD-2.
ITEM-I.
02
ITEM-2.
03
SUB-ITEM.
03
SUB-ITEM.
FIELD PIC X.
04
04
FIELD PIC X.

FIELD in the left-hand example can be referenced uniquely
the following ways:
FIELD OF
FIELD OF
FIELD OF
FIELD IN
FIELD IN
FIELD IN

any

SUB-ITEM OF ITEM-l IN RECORD-I.
SUB-ITEM OF ITEM-I.
SUB-ITEM IN RECORD-I.
ITEM-l OF RECORD-I.
RECORD-I.
ITEM-I.

The connectives
interchangeably.

and

are

equivalent

and

can

used

The only data items which need have unique names are level-77
items
and records not associated with files, since they are not contained in
any higher level data structure.
Records associated with files can be
qualified by the file
name,
as can any item contained within the
record.
File names must be unique.
Level-66 items can be qualified only (1) by the name of the record
with which they are associated and (2) by the name of any file with
which that record is associated.

4.9

SUBSCRIPTING AND INDEXING

It can sometimes be more convenient for you to specify a set of data
values as a table rather than assigning a name to each element of the
set.
A table (or array) is a set of homogeneous items stored together
in memory for
use by the program.
You define the table elements in
the program by specifying an OCCURS clause in the description of a
data
item.
The data item thus defined represents not one item but a
set of items having the identical format.
Subscripting and
indexing
are used to refer
to one of the elements of the set.
In DIGITAL
COBOL-68, subscripting and indexing are identical in'use and can be
used interchangeably.
However, the manner in which they are defined
differs.

4-7

THE DATA DIVISION

Subscripting is defined simply by the fact that an item has an
clause in its description. For example,
01

OCCURS

RATE-TABLE.
02 VOLUME OCCURS 25 TIMES.

describes VOLUME as 25 elements of RATE-TABLE. If you wish to refer
to one of the elements of this set, you must qualify the data-name
with a subscript.
Thus, VOLUME(lO)
is the tenth element
(or
occurrence) of VOLUME.
A subscript can be either an integer or a
data-name to which an integer value has been assigned.
Thus, when
DIST has been assigned to value 10, VOLUME (DIST) is the same as
VOLUME (10) .
To specify indexing you must add the INDEXED BY option to
clause. Thus,
01

the

OCCURS

RATE-TABLE.
02 VOLUME OCCURS 25 TIMES INDEXED BY IND.

defines VOLUME as 25 elements of the table and defines IND as the
index by which each element of the table can be indexed; that is,
VOLUME (IND) is an element in the table.
The index-name IND is
treated
exactly
like the data-name DIST because the compiler
recognizes an index-name as being exactly the same as a data-name. An
item defined as an index in an OCCURS clause has an implicit usage of
INDEX, and is equivalent to a data item that is declared USAGE INDEX.
However, this usage is included in DIGITAL COBOL for compatibility
with other compilers because an item whose usage is INDEX (implicit or
explicit)
is treated as if its usage were COMPUTATIONAL. In fact, a
data-name that is used as a subscript can be explicitly declared as
USAGE INDEX;
it can be treated as a COMPUTATIONAL data item by the
compiler.
COBOL-68 tables can be one, two, or three dimensions. The number of
dimensions is defined by the number of subscripts or indexes required
to refer to an individual item. For example:
C(1,3)
represents the item located in the first row and third column of
2-dimensional table which is defined by the DATA DIVISION entries:

01 TABLEA.
02 ROW OCCURS 20 TIMES.
03 COLUMN OCCURS 5 TIMES.
The subscript/index must be enclosed in parentheses and must appear in
the PROCEDURE DIVISION statement where the subscripted/indexed data
name is used. The subscript/index must appear after the data-name. A
space between the data-name and the parentheses is optional. Multiple
subscripts/indexes are separated by a comma or by a space. No spaces
can appear immediately following the left parenthesis or immediately
preceding the right parenthesis.
When referring to elements in
multi-dimensional tables, subscript/indexes are written from left to
right in the order of major (subscript/index varying least rapidly),
intermediate, and minor (subscript/index varying most rapidly). The
major index corresponds to the item written with the smallest
level-number, that is, the most inclusive item.

4-8

THE DATA DIVISION

As an illustration, consider a table having a major element occurring
ten times, an intermediate element occurring five times within each
occurrence of the major element, and a minor element occurring three
times within each intermediate element. The last major element of the
table has a subscript of (10,1,1), while the final element of the
table has a subscr ipt of (10,5,3).
There are two forms of subscripting/indexing:
direct and relative.
Direct subscripting/indexing means that the subscript/index refers
directly to the desired element. Relative subscripting/indexing means
that the element of the table is referred to indirectly. by a
subscript/index to a data name to which an integer is added or
subtracted. The form for direct subscript/indexing is shown in Figure
4-1.

data-name

~ubscript ~ [{ ,~ubscript }]
( { lndex
I
,lndex

. ..

)

MR-S-581-80

Figure 4-1 Direct Subscripting/Indexing
In relative subscripting/indexing, the subscript/index is followed by
the operator plus (+) or minus (-) followed by an unsigned integer
numeric literal. The operator plus (+) or minus (-) must be delimited
by spaces. The subscript/index, the operator, and the numeric literal
must follow the data-name and must be enclosed in parentheses.
The
form for relative subscripting/indexing is shown in Figure 4-2.

data-name

J+}
({ ~UbScriPt}
wdex
\-

integer

J,sUbscriPt}
[ I , index

J+}
\-

integer]

. ..

)

MR-S-582-80

Figure 4-2 Relative Subscripting/Indexing
When you use relative subscripting/indexing, the element of the table
that you refer to is not the one to which the subscript/index refers,
but the element to which the subscript/index plus or minus the integer
refers. That is, if the item
VOLUME (IND + 2)
is specified, and IND is set at 3, the fifth occurrence of VOLUME is
referred to, not the third. However, the value of the subscript/index
is not changed by relative subscripting/indexing; the value of IND
remains 3.
You can also combine direct subscripting/indexing and
relative
subscripting in the same statement. For example, if you specify the
following statement
TABLE(IND, VOL + 3)
the first subscript value is the value of IND
value is the value of VOL + 3.
4-9

an~

the second subscript

THE DATA DIVISION

When you need to qualify a table element for uniqueness, you should
use the format for direct subscripting/indexing shown in Figure 4-3.

data-name

[{

~~ }

~ubscr;Pt} [{ t~ubscr;pt

dat a-n ame-l ]

( { lndex

,lndex

...

)

MR·S·583·80

Figure 4-3 Qualified Direct Subscripting/Indexing
For example, to refer to ANAME in the following example:
01 ARECI.
02 AGROUPI OCCURS 5.
03 ASUBGROUPI OCCURS 10.
04 ANAME PIC X(5) OCCURS 20.
you could specify the following:
ANAME (I, J , 4)

NOTE
Subscripts can not be subscripted.

4-10

THE DATA DIVISION

FILE DESCRIPTION (FD)
4.10

FILE DESCRIPTION (FD)

Function
The File Description (FD) furnishes information concerning
the
physical structure, identification, and record names pertaining to a
given file.
General Format
FD

fi le-name

[BLOCK

CONTAINS

[ i nteger-l

i nteger-2

JRECORD(S)
\ CHARACTERS

[ RECORO

CONTAINS

[integer-3

TO]

integer-4

CHARACTERS

[ LABEL

STANDARD
RECORD IS
OMITTED
RECORDS ARE 1 {
record-n ame-l

J REPORT IS
[ \ REPORTS ARE

[VALUE

[ DATA

report-name-l

[DATE-WRITTEN

[USER-NUMBER

f\ RECORDs
RECORD IS
ARE

J
...

[, record-name-21

}]

[,report-name-2 ... ]]

tllENTIFICATION

fda t a- name - 2
\ literal-l

Im:~~~~~-21 ]
f data-n ame- 3

\ literal-3,literal-4

1 record-name-3

1] ]

[,record-name-4]

]

MR-S-989-81

4-11

THE DATA DIVISION

FILE DESCRIPTION (FD) (Cont.)

MODE IS

RECORDING

ASCII
SIXBIT
BINARY
£
V

STANDARD-ASCII
STANDARD ASCII
MR-S-l000-81

The clauses shown in the General Format appear in
on the following pages.

alphabetical

order

Technical Notes
1.

An FD entry must be present for each file-name selected
the FILE-CONTROL paragraph of the Environment Division.

All semicolon and commas are optional.
must terminate with a period.

The clauses can appear
Description entry.

The ability to place the RECORDING MODE clause in the FD has
been provided for compatibility with other manufacturers. If
you place the RECORDING MODE clause for a file in the FD, you
cannot also place it in the FILE-CONTROL paragraph for that
file in the ENVIRONMENT DIVISION. Also, if you wish to use
the RECORDING DENSITY and RECORDING PARITY clauses, you must
put them in the FILE-CONTROL paragraph in the ENVIRONMENT
DIVISION, even if the RECORDING MODE clause is in the FD.
The description of the RECORDING MODE clause can be found in
Chapter 3 with the full description of the ENVIRONMENT
DIVISION.

The maximum number of files that can be open at one

any

The entire

order

within

entry

the

File

time

16.

NOTE
ISAM files count as two files:
and one data (.IDA) file.

4-12

one index (.IDX) file

THE DATA DIVISION

BLOCK CONTAINS
4.10.1

BLOCK CONTAINS

Function
The BLOCK CONTAINS clause specifies the size of a logical block.
General Format

[ BLOCK CONTAINS

[integer-l

TO]

integer-2

RECOR 0( S)
CHARACTERS

MR-S-1001-81

Technical Notes
1.

You must specify the BLOCK CONTAINS clause if you want
the
file
to be organized into logical blocks.
If you do not
specify this clause, or if you specify integer-2
to be
0,
then all
records are packed in the file with no empty space
between the records.
The file
is then considered
to be
"unblocked" or "blocked zero".
However, if you use magnetic
tape and have used the RECORDING MODE clause to specify that
the recording mode as V or F, or standard ASCII, the default
is a blocked file with a blocking factor of one.

If the CHARACTERS option is used, the logical block size
is
specified
in terms of the number of character positions
required to contain the record.
If the recording mode
is
ASCII
(that
is,
all
records
for
the file are described,
explicitly or implicitly, as USAGE DISPLAY-7), it is assumed
that
the size is specified in terms of DISPLAY-7 characters.
If the recording mode is SIXBIT (that is, the records for the
file
are
all described,
explicitly or
implicitly,
as
DISPLAY-6) it is assumed that the size is specified in
terms
of SIXBIT characters.
If the recording mode is F or V (that
is, the data is recorded on the medium as EBCDIC characters),
it
is assumed that the size is specified in terms of EBCDIC
characters,
either
fixedor
variable-length.
When
variable-length EBCDIC records are used (i.e., the recording
mode is V),
the number of records
in a
block
is also
variable.
If the blocking factor is not zero, the number of
records in a block is determined by dividing the block size
in characters by the number of characters in the longest
record as specified by the FD statement.
For example, if the
FD statement specifies a maximum record length of
248
characters and the BLOCK CONTAINS 2400 CHARACTERS clause
is
used, the number of records in a block are 9.

Integer-l and integer-2 must be positive integers.
If only
integer-2
is specified, it represents the exact size of the
logical' block.
If both integer-l and
integer-2 are given,
integer-l
is
ignored and integer-2 is used as the blocking
factor.

Files whose access modes are RANDOM or INDEXED must have a
is
nonzero
blocking
factor.
Files whose access mode
sequential and opened for I/O should have a nonzero blocking
factor.
If not, the compiler will calculate one.
4-13

THE DATA DIVISIO~

DATA RECORD
4.10.2

DATA RECORD

Function
The DATA RECORD clause
associated file.

cross

references

the

record-name

with

its

General Format

RECORD ISARE } record-name-l [ srecord-name-2 ] ...
DATA { RECORDs
MR-S-1002-81

Technical Notes
1.

This clause is optional because all records not associated
with a LABEL RECORDS clause are assumed to be data records.

Both record-name-l and record-name-2 must be the names given
in Ol-level data entries subordinate to this FD.
The
presence of more than one such record-name indicates that the
file contains more than one type of data record. These
records can have different descriptions. The order in which
they are listed is not significant.

All records within a file share the same area.

4-14

THE DATA DIVISION

FD file-name
4.10.3

FD file-name

Function
The FD file-name clause identifies the file to which this
description entry and the subsequent record descriptions relate.

file

General Format
FD file-name

Technical Notes
1.

This entry must begin each file description.

The file-name must appear in a SELECT statement
FILE-CONTROL paragraph of the ENVIRONMENT DIVISION.

4-15

the

THE DATA DIVISION

LABEL RECORD
4.10.4

LABEL RECORD

Function
The LABEL RECORD clause specifies whether or not labels are present on
the file and, if so, identifies the format of the labels.
General Format

RECORD IS
LABEL { RfCoRos ARE
[

OMITTED
STANDARD
record-narne-l

}{

[,record-name-Z]

...

}]

MR-S-1003-81

Technical Notes
1.

If the clause is
assumed.

omitted,

LABEL· RECORDS

ARE

The OMITTED option is used when the file
trailer labels.

The STANDARD option is used when the file has header and
trailer labels that conform to the DECsystem-lO standard
format.
If this clause is used for files on disk or DECtape,
LABEL RECORDS ARE STANDARD must be specified. See the VALUE
OF IDENTIFICATION clause for
the association between the
label and the filename on disk or DECtape.

has

STANDARD

header

The standard label for DECtape and random-access devices
is
the directory block used by the monitor.
For magnetic tape,
if the file is recorded in SIXBIT, the standard label is 78
SIXBIT characters in length and is written in a separate
physical record from the data, with the same recording mode
as the data.
If the recording mode is ASCII, the label
contains 78 ASCII characters, plus carriage return and line
feed,
for a total of 80 characters. Table 4-1 shows the
contents of each character
in a
standard
label
for
nonrandom-access devices.
Magnetic tapes are the only devices with ending labels.
Each
ending label is preceded by and followed by an end-of-file
mark.
4.

The record-name option is used when the file labels do not
conform to the system standard format.
The record-names must
appear as the names of record
description
(level-Ol)
subordinate to this FD;
the record-names must not appear in
a DATA RECORDS clause. When a file is opened, the beginning
non-standard label is read (as input) or written (as output)
automatically by the 1-0 routines.
If the file
is being
opened for output, the data for the record must be supplied
by a USE procedure in the DECLARATIVES (see Chapter 5).
If
the file is being opened for input, no checks are made by the
1-0 routines to determine the validity of the label;
you can
program any checks in a USE procedure.
4-16

THE DATA DIVISION

LABEL RECORD (Cont.)
The presense of TOPS-IO or TOPS-20 system labels on a
magnetic
tape causes the system to handle tape volume
processing normally done by.LIBOL and overrides the COBOL
labeling described above.
Thus,
a magnetic tape only has
TOPS-IO or TOPS-20 system labels or LIBOL created labels, but
never both.
5.

Files whose recording mod~ is F or V (fixed- or variablelength EBCDIC), must have LABELS RECORDS ARE OMITTED if they
are on magnetic tape.
If they are on disk or DECtape,
they
are assumed to have DECsystem-10 standard labels.
The
record-name option cannot be used for EBCDIC files.

•

Table 4-1
Standard Label for Nonrandom-Access Media
Contents

Characters

= Beginning File.
= Ending file.
= Ending reel.

1-4

HDRl
EOFI
EOVI

5-13

Value of identification.

14-21

Always spaces.

22-27

Not used.

28-31

Reel number.

32-41

Not used.

42-47

Creation date;
two characters each
year, month, and day, respectively.

48-78

Not used.

79-80

Carriage-return/line-feed if file
is
ASCII.
(Note that this is on the label only;
it is not
kept internally.)

The first reel is always 0001.

4-17

for

the

THE DATA DIVISION

RECORD CONTAINS
4.10.5

RECORD CONTAINS

Function
The RECORD CONTAINS clause specifies the size of the data
this file.

records

General Format

[RECORD CONTAINS [integer-l TO] integer-2 CHARACTERS]
MR·S·1004·81

Technical Notes

Because the size of each data record is completely defined by
its record description entry, this clause is never required.
However, if you use it, it replaces the record description
entry in setting the size of the record, and the following
rules must be observed.

Integer-l and integer-2 must be positive integers. Integer-2
can not be less than the size of the largest record but
cannot exceed 4095, which is the limit on the size of a
record.

The data record size is specified in terms of the number
character positions required to contain the record.

The maximum size of a record in an FD is 4095 characters.

This clause is ignored if the FD contains a REPORT clause and
there is no data record description.
In this case, the
record size defaults to 132 characters.

4-18

THE DATA DIVISION

REPORT
4.10.6

REPORT

Function
The REPORT clause specifies the name of each report that is associated
with the file.
General Format

REPORT IS
REPORTS ARE

report-name-l

[ ,report-name-2 ]

... ]
MA·S·1005·B1

Technical Notes
1.

This clause is optional; it is used only when Report-Writer
statements cause output to be written on the file.

Repor~-name-l and report-name-2 must be the names
Descriptor items in the REPORT SECTION.

If this clause is used, the data record description can be
omitted because the name of the data record is not referred
to directly in the PROCEDURE DIVISION. When the data record
description is omitted, the compiler automatically assumes a
132-character record.

4-19

Report

THE DATA DIVISION

SO file-name
4.10.7

SO file-name

Function
The SO file-name clause identifies the sort to which this
description entry and the subsequent record description relate.

file

General Format
.
[
{ RECORD
SD f,le-name
DATA
RECORDS IS}
ARE record-name-l [ ,record-name-2 ]

[RECORD CONTAINS

... ]

[integer-~ TO] integer-2 CHARACTERS ] ~-S-1006-81

Technical Notes
1.

The SO entry must begin each sort file description.

The file-name must appear
in a SELECT statement
FILE-CONTROL paragraph of the ENVIRONMENT DIVISION.

The DATA RECORD and RECORD CONTAINS
descriptive clauses allowed.

4-20

•

clauses

are

the

only

THE DATA DIVISION

VALUE OF IDENTIFICATION
4.10.8

VALUE OF IDENfIFICATION/DATE-WRITTEN/USER-NUMBER

Function
The VALUE OF IDENTIFICATION clause provides specific data for an
within the label records associated with a file.

item

General Format

[VALUE OF [{t.gENTI FI CATION} IS
[

Hn:~~f~~-l}]

DATA-WRITTEN IS {d?ta-name-2}]
11 tera 1- 2

[USER-NUMBER IS

{~~i:;~t~~iiteral-4}]]
MR·S-1007-81

Technical Notes
1.

The VALUE OF IDENTIFICATION clause is required only if label
records are standard;
it is ignored in all other cases. The
VALUE OF DATE-WRITTEN and the VALUE OF USER-NUMBER are always
optional.

The three clauses can be written in any order, but
of each can be specified for a file.

IDENTIFICATION represents the file-name and extension of a
file with standard labels.
If a data-name is specified, it
must be associated with a DISPLAY-6, DISPLAY-7, or DISPLAY-9
data item nine characters in length.
If a literal is
specified, it must be a alphanumeric literal nine characters
in length.
The first six characters are taken as the
file-name,
and last three characters are taken as the
extension. The programmer must provide spaces as required to
conform to this convention.
The literal cannot consist
exclusively of spaces.
The period which the system prints
between the file-name and the extension must not be included
in the VALUE OF IDENTIFICATION clause.
Examples:
a.

VALUE OF IDENTIFICATION IS "COST

VALUE OF IDENTIFICATION IS FILE-I-NAME
(WORKING-STORAGE SECTION.)
77 FILE-I-NAME PICTURE IS X(9).
4-21

TST"

only

one

THE DATA DIVISION

VALUE OF IDENTIFICATION (Cent.)
4.

DATE-WRITTEN represents the date that a magnetic tape file
(with STANDARD labels)
was written.
If a data-name is
specified, it must be associated with a DISPLAY-6,
DISPLAY-7
or DISPLAY-9 data item six characters in length.
If a
literal is specified, it must be a alphanumeric literal six
characters in length. The first two characters are taken as
year, the next two as month, and the last two as day.
The
DATE-WRITTEN clause is ignored when the file is OPENed for
output;
instead, the current date is used.
Examples:
a.

VALUE OF IDENTIFICATION IS "RANDOMXYZ",
760112

DATE-WRITTEN

VALUE OF IDENTIFICATION IS "DATA
FILE-I-DATE

DATE-WRITTEN

(WORKING-STORAGE SECTION.)
77 FILE-I-DATE PICTURE IS 9(6).
5.

USER-NUMBER represents the project-programmer number of the
owner of a disk file;
it is ignored for all other devices.
Data-name-3 must be a COMPUTATIONAL item of 10 or fewer
digits
in which the project-programmer number is stored.
Literal-3 and literal-4 are numeric literals of six or
fewer
digits that are treated as octal.
Literal-3 is the project
number and literal-4 is the programmer number.

For input files the VALUEs specified are checked against the
file when it is opened.
ISAM files are checked as soon as
your program is run.
For output files,
the VALUE OF
IDENTIFICATION is written when the file is opened.
If the
specified values do not match a file on the selected medium,
a run-time error message is issued.

If the access mode is INDEXED and data-name-l is used in the
VALUE OF IDENTIFICATION clause, data-name-l must contain the
filename and extension of the index-file for
the
indexed
sequential
file
being
referenced.
The
contents of
data-name-l can not be altered during program execution.
You
need not specify the identification for the data file of an
indexed sequential file because this identification is stored
in the index file.

If data-name-3 is used to represent the project-programmer
number,
you must be aware that the value of data-name-3 is
treated as decimal, even though the project-programmer number
is octal.
The data-name-3 value is translated from decimal
to binary by the COBOL conversion routine.
Thus,
the
project-programmer
is not accurate unless you provide a
conversion routine in your program to convert your octal
project-programme~
number
to its decimal equivalent so that
it is converted to the correct binary number.
The following
example is a suggested method for performing the conversion.

4-22

THE DATA DIVISION

VALUE OF IDENTIFICATION (Cont.)
77
77
77
77
01

ERR-FLAG
PIC 9,
USAGE COMP.
HALF-NUM,
PIC S9 (7) ,
USAGE COMP.
OCTAL-PPN,
PIC S9 (10) ,
USAGE COMP.
DIGIT,
PIC 9.
PP-NUMBER.
02 PROJ-NUMBER,
PIC 9 (6) .
02 PROG-NUMBER,
PIC 9 ( 6) ..
02 EITHER-NUM,
PIC 9(6).
02 X REDEFINES EITHER-NUM.
03 PP-DIGIT,
PIC 9, OCCURS 6 TIMES, INDEXED BY I.

ACCEPT PROJ-NUMBER, PROG-NUMBER.
SET ERR-FLAG TO ZERO.
MOVE PROJ-NUMBER TO EITHER-NUM.
MOVE ZERO TO HALF-NUM.
PERFORM CONVERT VARYING I FROM 1 BY 1 UNTIL 1>6.
IF ERR-FLAG IS NOT = 0 GO TO OCTAL-ERROR.
COMPUTE OCTAL-PPN = HALF-NUM * 262144.
MOVE PROG-NUMBER-TO EITHER-NUM.
MOVE ZERO TO HALF-NUM.
PERFORM CONVERT VARYING I FROM 1 BY 1 UNTIL 1>6.
IF ERR-FLAG IS NOT = 0 GO TO OCTAL-ERROR.
COMPUTE OCTAL-PPN = OCTAL-PPN + HALF-NUM.

CONVERT.
IF PP-DIGIT (I) = 8 OR 9, SET ERR-FLAG UP BY 1.
COMPUTE HALF-NUM = 8 *HALF-NUM + PP-DIGIT (I).
*

THIS ROUTINE INVALID FOR PROJECT NUMBERS LARGER THAN
77777.

If the access mode is INDEXED and data-name-3 is used to
represent the project-programmer number, the following rules
must be observed:

Data-name-3 must have a value that is the decimal
equivalent of an octal project-programmer number, and
that project-programmer number must contain a file with
the name used in the VALUE OF IDENTIFICATION clause.

Data-name-3 can be altered during program execution
if all files referenced have identical parameters.

If several files are read through the
same
File
Description, data-name-3 should point to the file with
the largest number of levels of index
(this is usually
the largest file).

only

None of the data-names in the VALUE clauses can appear in the
LINKAGE SECTION.

4-23

THE DATA DIVISION

RECORD DESCRIPTIONS
4.11

RECORD DESCRIPTIONS

Following the FD for a file, a record description is given for each
different record format in the file. A record description begins with
a level-Ol entry:
01

data-name

A complete record description can be as simple as
01

data-name PICTURE picture-string.

or it can be more complex, where the aI-level is followed by a long
series of data description entries of varying hierarchies that
describe various portions and subportions of the record.
A aI-level
data-name in the File Section cannot be explicitly redefined (using
the REDEFINES clause). However, because a file has only one record
area, if more than one data-name is specified, they implicitly
redefine the first data-name. Also, if the additional data-names have
usages different from that of the first data-name, the last usage
given is used as the usage in determining the usage mode of the file
if it is necessary to use a default.

4.11.1

Record Concepts

A record description consists of a set of data description entries
which describe a particular logical record. Each data description
entry consists of a level-number followed by a data-name (or FILLER)
which is followed, as required, by a series of descriptive clauses.
The general format of a data description entry follows.

4-24

THE DATA DIVISION

DATA DESCRIPTION ENTRY
4.11.2

DATA DESCRIPTION ENTRY

Function
A data description entry describes a particular item of data.

General Format

1eve 1-number {~:~~E~ame-l} [REDEFINES data-name-2J [tm.TURE} IS pi cture-string ]

COMPUTATIONAL

CQM£
COMPUTATIONAL-l
~

COMPUTATIONAL-3
~

DISPLAY
pISPLAY-6
PISPLAV-7
DISPLAY-9
INDEX
DATABASE-KEY
DBKEY

[OCCURS [integer-l TO

SYNCHRONIZED} {LEFT }]
[{ SYNC
RIGHT

J integer-2 TIMES [DEPENDING ON data-name-l J

[gm~~mG} KEY IS data-name-2 [,data-name-3J ... ] ...
[INDEXED BY index-name-l [, i ndex-name-2 ] .

i.J ]_.

66 data-name-l RENAMES data-name-2 [THRU data-name-3J ....!....
88 condition-name {~SI~RE} literal-l [THRU literal-2 ]

[ ,litera 1- 3 [I!:!Rl.! 1i tera 1-4

J] .:~s'oo:"
4-25

THE DATA DIVISION

DATA DESCRIPTION ENTRY (Cont.)

The clauses shown in the General Format appear in
on the following pages.

alphabetical

order

Technical Notes
1.

Each data description entry must be terminated by
All semicolons and commas are optional.

The clauses can appear in any order, with one exception:
the
REDEFINES clause, when used, must immediately follow the
data-name being redefined.

The VALUE clause must not appear in a data description entry
which also contains an OCCURS clause, or in an entry which is
subordinate to an entry containing an OCCURS clause.
The
latter part of this rule does not apply to condition-name
(level-88) entries.

The PICTURE clause must be specified for every elementary
item, except a USAGE INDEX, COMP-l, DATABASE-KEY, or DBKEY.

The clauses SYNCHRONIZED, PICTURE, JUSTIFIED, and BLANK
ZERO can be specified only at the elementary level.

4-26

period.

WHEN

THE DATA DIVISION

BLANK WHEN ZERO

4.11.2.1

BLANK WHEN ZERO

Function
The BLANK WHEN ZERO clause causes the blanking of
value is zero.

item

when

its

General Format
[BLANK

WHEN

ZERO ]
MR-S-1009-81

Technical Notes
1.

When the BLANK WHEN ZERO option is used and the item is zero,
the item is set to blanks.

BLANK WHEN ZERO can be specified only at the elementary level
and only for numeric or numeric-edited items whose usage is
DISPLAY-6, DISPLAY-7, or DISPLAY-9.

More comprehensive editing features are available in the
PICTURE clause. For example, if a PICTURE clause appears in
the same data description entry and contains the zero
suppression symbol * (zero suppress and replace with *), the
field is replaced with * when the item is given a zero value
(see Section 4.11.2.7, PICTURE).
The only exception is
fields containing a decimal point, in which case the decimal
point is not replaced.

4-27

THE DATA DIVISION

Condition-name (Ievel-SS)

4.11.2.2

Condition-name (level-88)

Function
To assign a name to a value or range of values of the associated
item.

data

General Format

f VALUE

condition-name

1VAUJEs ARE

[ ,literal-3

[THRU

)

literal-l

[THRU

literal-2 ]

literal-4] ]
MR-S-1010-81

Technical Notes
1.

Each condition-name requires a separate level-88 entry.
This
entry contains the name assigned to the condition, and the
value
or
values
associated
with
that
condition.
Condition-name entries must immediately follow the data
description entry with which the condition-name is to be
associated.

A condition-name entry can be associated with
or group item except:

another condition-name entry, or

a level-66 item.

elementary

Some examples of possible level-88 entries are given below:
a.

B-FIELD PICTURE IS 99.
88 Bl VALUE IS 3.
88 B2 VALUES ARE 50 THRU 69.
88 B3 VALUES ARE 20, 25, 28, 31 THRU 37.
88 B4 VALUES ARE 70 THRU 75, 80 THRU 85, 90 THRU 95.

C-FIELD PICTURE IS xxx.
88 C-YES VALUE IS "YES".
88 C-NO VALUE IS "NO ".

The data item with which the condition~name is associated is
called a conditional variable. A conditional variable can be
used to qualify any of its condition-names.
If references to
a conditional variable require indexing, subscripting, or
qualification,
then
reference
to
its
associated
condition-names
also
require
the same combination of
indexing, subcripting, or qualification.

4-28

THE DATA DIVISION

,Condition-name (Ievel-SS) (Cont.)

A condition-name is used in conditional expressions as an
abbreviation for
the related condition. Thus, if the above
DATA DIVISION entries (NOTE c) are used,
the statements in
each pair below are functionally equivalent.

Relational Expression

Condition-Name

IF B-FIELD IS EQUAL TO 3 ••••

IF Bl .•••

IF B-FIELD IS GREATER THAN
49 AND LESS THAN 70 •.•.

IF B-FIELD IS EQUAL TO 20 OR
EQUAL TO 25 OR EQUAL TO 28
OR GREATER THAN 30 AND
LESS THAN 38 .•..

IF B3 ....

IF B-FIELD IS GREATER THAN 69
AND LESS THAN 76 OR GREATER
THAN 79 AND LESS THAN 86 OR
GREATER THAN 89 AND LESS
THAN 96 •.••

IF B4 ..•.

IF C-FIELD IS EQUAL TO "YES" ••

IF C-YES

B2 ....

Literal-l must always be less than literal-2, and literal-3
less than literal-4. The values given must always be within
the range allowed by the format given for
the conditional
variable.
For example, any condition-name values given for a
conditional variable with a PICTURE of PP999 must be in the
range of
.00000 to
.00999.
(See Note 10 under PICTURE in
this chapter for the meaning of P in a picture-string.)

4-29

THE DATA DIVISION

data-name/FILLER

4.11.2.3

data-name/FILLER

Function
A data-name specifies the name of the data being described.
The
FILLER specifies an unreferenced portion of the logical record.

word

General Format

leve l-number

data-name

I FILLER

MR-S-1011-81

Technical Notes
1.

A data-name or the word FILLER must immediately
level-number in each data description entry.

A data-name must be composed of a combination of the
characters A through Z, 0 through 9, and the hyphen.
It must
contain at least 1 alphabetic character and must not exceed
30 characters
in length.
It must not duplicate a COBOL
reserved word.
Refer to Section 1.2.3.2, User-Created Words,
for further information.

The key word FILLER is used to name an unreferenced item in a
record
(that is,
an item to which the programmer has no
reason for assigning a unique name).
A FILLER item cannot,
under
any
circumstances,
be referenced directly in a
PROCEDURE DIVISION statement.
However, it can be indirectly
referenced by referring to a group-level item of which the
FILLER item is a part.
FILLER can be used at any level,
including the 01 level.

4-30

the

THE DATA DIVISION

JUSTIFIED

4.11.2.4

JUSTIFIED

Function
The JUSTIFIED clause specifies nonstandard positioning of data
a receiving data item.

within

General Format

JUSTIFIED)
JUST

RIGHT) ]
LEFT
MR-S-1012-81

Technical Notes
1.

The JUSTIFIED clause cannot be specified at a group level
for numeric edited items.

If neither RIGHT nor LEFT is specified, RIGHT is assumed.

An item subordinate to one containing a VALUE
be JUSTIFIED.

DISPLAY-6, DISPLAY-7 and DISPLAY-9 items can be JUSTIFIED.

The standard rules for positioning data within an
data item are as follows:
a.

clause

cannot

elementary

Receiving
data
item
described
as
numeric
or
numeric-edited
(see definition in Notes 6 and 9 under
PICTURE in this chapter). A numeric or numeric-edited
item is justified according to the following rules, thus
the JUSTIFIED clause cannot be used.
The data is aligned by decimal point and is moved to the
receiving
character
positions
with
zero fill
or
truncation on either end as required.
If an assumed decimal point is not explicitly specified,
the data item is treated as if it had an assumed decimal
point immediately following its rightmost character,
and
the sending data is aligned according to this decimal
point.

Receiving data item described as alphanumeric (other than
numeric edited) or alphabetic (see definition in Notes 5
and 7 under PICTURE in this chapter).
The data is moved to the receiving character positions
and aligned at the leftmost character position with space
fill or truncation at the right end as required.

4-31

THE DATA DIVISION

JUSTIFIED (Cont.)
6.

When a receiving item is described
positioning occurs as in 4a above.

JUSTIFIED

LEFT,

When a receiving data item is described with the JUSTIFIED
RIGHT clause and is larger than the sending data item, the
data is aligned at the rightmost character position in the
receiving item with space fill at the left end.
When a receiving data item is described with the JUSTIFIED
RIGHT clause and is smaller than the sending data item, the
data is aligned at the right most character position in the
receiving item with truncation at the left end.

Examples are given below:
03

ITEM-A PICTURE IS
X(8) VALUE IS IIABCDEFGHII.

ITEM-B PICTURE IS
X(4) VALUE IS IIWXYZIl.

ITEM-C PICTURE IS X(6).

ITEM-D PICTURE IS X(6).
JUSTIFIED RIGHT.
Contents of Receiving Field

MOVE ITEM-A TO ITEM-C.

ABC D E F

MOVE ITEM-A TO ITEM-D.

C D E F G H

MOVE ITEM-B TO ITEM-C.

wX Y Z

MOVE ITEM-B TO ITEM-D.

WX Y Z

4-32

THE DATA DIVISION

level-number

4.11.2.5

level-number

Function
The level-number shows the hierarchy of data within a logical record.
In addition, special level-numbers are used for condition-names
(level-SS), noncontiguous WORKING-STORAGE items (level-77), and the
RENAMES clause (level-66).
General Format

level-number

J data-name )
\ FILLER

MR-S-1013-81

Technical Notes
1.

A level-number is required as the first element in each
description entry.

Level-numbers can be ~laced anywhere on the source
or after margin A.

Level-number
88
is
desc~ibed
under
"condition-name
(level-88)", and level-number 66 is described under "RENAMES
(level-66)", both in this section.

A further description of level-numbers and data hierarchy can
be found in the introduction to this chapter.

4-33

line,

data
at

THE DATA DIVISION

OCCURS

4.11.2.6

OCCURS

Function
The OCCURS clause eliminates the need for
separate entries
for
repeated data,
and supplies information required for the application
of subscripts and indexes.
General Format

i nteger-l
{ integer-3
ASCENDING}
[ { DES CEN Dr NG
[ INDEXED BY

KEY

integer-2

TIMES

DEPENDING ON data-name-l}

TIMES

index-name-I

data-name-2

[,data-name-3]

[, index -name- 2 ]

. .• ] ]

..•

]

M"S"""

Technical Notes
1.

This clause cannot be specif~ed in a data description entry
that has a 66 or 88 level-number, or in one that contains a
VALUE clause.

The OCCURS clause
is used
homogeneous sets of repeated
used, the associated data-name
must always be subscripted
PROCEDURE DIVISION statements.

All clauses given in a data description that
includes
OCCURS clause apply to each repetition of the item.

The integers must be positive.
If integer-l is specified, it
must have a value less
than integer-2.
No value of a
subscript can exceed integer-2;
in addition,
if
the
DEPENDING option is specified, no subscript can exceed the
value of data-name-l at the time of subscripting.

The value of data-name-l
is the count of the number of
occurrences of the item described by the OCCURS clause;
its
value must not exceed integer-2.

If the DEPENDING option is specified,
the
integer-l TO
integer-2 phrase must be included.
Data-name-l must be USAGE
INDEX or USAGE COMP of 10 digits or less with no scaling or
decimal places.
It cannot be subscripted or appear in the
LINKAGE SECTION.
4-34

to define tables or
other
data.
Whenever this clause is
and any subordinate data-names
or
indexed when used in all
an

THE DATA DIVISION

OCCURS (Cont.)
7.

The KEY IS option indicates that the repeated data has been
sorted by you into either ascending or descending order
according to the values
associated
with
data-name-2,
data-name-3, and so forth.
The data-names are listed in
order of decreasing significance.

Data-name-2 must be either the name of the entry containing
the OCCURS clause, or the name of an entry subordinate to the
entry containing the OCCURS clause. Data-name-3, etc., must
be the name of an entry subordinate to the group item that is
the subject of this entry.

An index-name defined in a OCCURS clause must not be defined
elsewhere;
its appearance in the INDEXED option is its only
definition. There can be no items of the same name defined
elsewhere.
The USAGE of each index-name is assumed to be
INDEX.

10.

Subscripting and indexing are described in
to this chapter.

11.

The maximum number of
32,767.

OCCURS

4-35

for

the

single

introduction
data

item

THE DATA DIVISION

PICTURE

4.11.2.7

PICTURE

Function
The PICTURE clause describes the general characteristics
requirements of an elementary item.

and

editing

General Format

[ (

~TURE

pi cture-s tr i ng ]
MR-S-1015-81

Technical Notes
1.

A PICTURE clause can be used only at the elementary level.
It . can not be used with an item described as USAGE INDEX or
CaMP-I.

A picture-string consists of certain allowable combinations
of characters in the COBOL character set used as symbols.
These symbols are as follows:
a.

Symbols representing data characters
9 represents a numeric character (0 through 9)
and
A represents an alphabetic character (A through Z,
the space)
X represents an alphanumeric character
(any allowable
character)

Symbols representing arithmetic signs and assumed decimal
point positioning
V represents the position of the assumed decimal point
P represents an assumed decimal point scaling position
S represents the presence of an arithmetic sign

Symbols representing zero suppression operations
Z represents standard zero suppression
(replacement of
leading zeros by spaces)
* represents check protection (replacement of leading
zeros by asterisks)

4-36

THE DATA DIVISION

PICTURE (Cant.)
d.

Symbols representing insertion characters
$ represents a dollar sign (this sign floats

from left
to right and replaces the rightmost leading zero when
more than one $ apears) 1
, represents an insertion comma 2
• represents an actual decimal point 2
B represents an insertion blank
o represents an insertion zero
e. Symbols representing editing sign-control symbols

+ represents an editing plus sign
- represents an editing minus sign
CR represents an editing Credit symbol
DB represents an editing Debit symbol
The plus and minus signs (+ and -) float when more than
one appear, and replace the rightmost leading zeroes.
f. Consecutive repetitions of a picture-symbol can
be
abbreviated to the symbol followed by (n), where n
indicates the number of occurrences.
3.

A maximum number of
30
symbols
can
appear
in
a
picture-string.
Note that the number of symbols in a
picture-string and size of the item represented are not
necessar ily the same.
There are 'two reasons for this
discrepancy. First, the abbreviated form for indicating
consecutive repetitions of a symbol can result in fewer
symbols in the picture-string than character positions in the
item being described.
For example, a data item having 40
alphanumeric character positions can be described by a
picture-string of only 5 symbols:
PICTURE IS X(40).
The second reason is that some symbols are not counted when
calculating the size of the data item being described. These
symbols include the V (assumed decimal point), P (decimal
point scaling position), and S (arithmetic sign); these
symbols do not represent actual physical character positions
within the data item. For example, the character-string
S999V99
represents a 5-position data item.
Other size restrictions for numeric and numeric edited
are given under the appropriate headings below.

items

If the CURRENCY SIGN IS clause appears in the SPECIAL-NAMES
paragraph, the symbol specified by the literal must be used in all
instances in place of the $.
2
If the DECIMAL-POINT IS COMMA clause appears in the SPECIAL-NAMES
paragraph, the functions of the comma and decimal point are reversed.

4-37

THE DATA DIVISION

PICTURE (Cont.)
4.

There are five categories of data that can be described with
a
PICTURE
clause:
alphabetic, numeric, alphanumeric,
alphanumeric edited, and numeric edited.
A description of
each category is given in the notes below.

Definition of an Alphabetic Item

Its picture-string can contain only the symbol A.

It can contain only the 26 letters of
the space.

alphabet

and

Its picture-string can contain only the symbols 9, P,
and V.
It must contain at least one 9.

Definition of a Numeric Item
a.

7•

the

The picture-string
positions.

must

have

from

It can contain only
operational sign.

the

digits

through

digit
and

Definition of an Alphanumeric Item
a.

Its picture-string can consist of all
Xs,
or
a
combination of the symbols A, X, and 9 (except all 9s or
all As). The item is treated as if the character-string
contained all xs.

Its contents can be any combination of characters
the complete character set (see Section 1.2.2.2).

from

Definition of an Alphanumeric Edited Item
a.

Its picture-string can consist of any combination of As,
Xs, or 9s (it must contain at least one A or one X), plus
at least one of the symbols B or O.

Its contents can be any combination
the complete character set.

characters

from

Definition of a Numeric Edited Item
a.

Its picture-string must contain
following editing symbols:

, . * + -

least

one

the

0 B CR DB $

It can also contain the symbols 9, V, or P.
The allowable sequences are determined by certain editing
rules for each symbol and can be found in Note 10.
The picture-string
positions.
b.

must

from

The contents can be any combination
through 9 and the editing characters.

the

digits

4-38

have

digit
0

THE DATA DIVISION

PICTURE (Cont.)
10.

The symbols used to define the category of an elementary item
and their functions are as follows.
A

Each A in the pict~re-string represents a character
position which can contain only a letter of the alphabet
or a space.

Each B in the picture-string represents a character
position into which a space character is inserted during
editing.

Examples:

(A-FLD contains the value 092469)
B-FLD picture-string

Result

MOVE A-FLD TO B-FLD

99B99B99

10191612141616191

MOVE A-FLD TO B-FLD

9999BBBB

10191214161616161

Also see Note 14, "Simple Insertion Editing".
PEach P in the picture-string indicates an assumed decimal
point scaling position and is used to specify the
location of an assumed decimal point when the point is
outside the positions defined for the item.
Ps are not
counted in the size of the data item. They are counted
in determining the maximum number of digit positions (18)
allowed in numeric edited items or numeric items.
Ps can
appear only to the left or right of the picture-string
and must appear together.
The assumed decimal point is
assumed to be to the lett of the string of Ps it the Ps
are at the left end of the picture-string and to the
right of the string of Ps if the Ps are at the right end
of the picture-string.
If the V symbol is used in this
case, it must appear in either of those positions;
it is
redundant.
Examples:
PPP9999 (or VPPP9999) defines a data item of four
character
positions whose contents is treated as
.000nnnn during any
decimal point alignment operation (such as in a MOVE or ADD).
9PPP
(or
9PPPV)
defines a data item of one character position
whose contents is treated as nOOO during any decimal point
alignment operation.

An S in a picture-string indicates that the item has an
operational sign and retains the sign of any data stored
in it.
The S must be written as the leftmost character
in the picture-string.
If S is not included, all data is
stored in the item as an absolute value and is treated as
positive in all operations.
The S symbol is not counted
in the size of the data item.

4-39

THE OATA OIVISION

PICTURE (Cont.)
V

A V in a picture-string indicates the location of the
assumed decimal point and can appear only once in a
picture-string.
The V does not represent a physical
character position and is not counted in the size of the
data item.
If the assumed decimal point position is at
the right of the rightmost character position of the
item, the V is redundant (that is, 9999
is functionally
equivalent to 9999V).

Each X in a picture-string represents a
character
position which can contain any allowable character from
the complete character set.

Each
Z in a picture-string represents the leftmost
leading numeric character positions in which leading
zeros are to be replaced by spaces.
Each Z is counted in
the size of the item.

Each * in a picture-string represents the leftmost
leading numeric character positions in which leading
zeros are to be replaced by *.
Each * is counted in the
size of the item.

Examples:

(A-FLO contains the value

00305)

B-FLO picture-string
MOVE A-FLO TO B-FLO

999999

MOVE A-FLO TO B-FLO

ZZ9999

MOVE A-FLO TO B-FLO

ZZZZZZ

MOVE A-FLO TO B-FLO

ZZZZ.ZZ

Result

10101013 01 5
16 16 10 3 01 5
6 6 6 3 01 5
1
1 1 1
6 3 0 5
0I
1 1 1 1 1. 01
1

Also see Note 18, "Zero Suppression Editing".
9

Each 9 in a picture-string represents a
character
position which can contain a digit.
Each 9 is counted in
the size of the item.

Each 0 in a picture-string represents a
character
position into which a zero is inserted.
It is counted in
the size of the item.
The 0 symbol works
in the same
manner as the B symbol.
Each
,
in a picture-string represents
position into which a comma is inserted.

Examples:

(A-FLO contains

character

362577)

B-FLO picture-string
MOVE A-FLO TO B-FLO

9,999,999

MOVE A-FLO TO B-FLO

Z,ZZZ,ZZZ
4-40

Result

13 16 12·1 ' 15 171 7 I

THE DATA DIVISION

PICTURE (Cont.)
Also see Note 14, "Simple Insertion Editing".
A • (dot or period) in a picture-string is an editing
symbol that represents an actual decimal point. It is
used for decimal point alignment and also indicates where
a point (.) is to be inserted. This symbol is counted in
the size of the item.
Only one
can lappear in a
picture-string.
Examples:

(A-FLO contains

3S2~9)1

B-FLO picture-string

Result

MOVE A-FLO TO B-FLO

99,999.99

MOVE A-FLO TO B-BLO

zz,zzz.zz

MOVE A-FLO TO B-FLO

99999.9999

10131,1512161.19191
16131 ' 1512161 .1 919I
10131s12161·19191 ol~

See Note 4 under MOVE in Chapter S for
rule governing the third example.

clarification

the

Also see Note IS, "Special Insertion Editing".
+

CR
OB

Each of these symbols is used as an editing sign-control
symbol. When used,
they
represent
the
character
position(s)
into which the editing sign-control symbol
is placed. Only one of these symbols can appear in a
character-string.

The + and - symbols can appear either at the beginning or at the
end of a picture-string. The CR and OB symbols can appear only
at the end of a picture-string.
+

The character position containing this symbol contains a
+ if the sending field either was unsigned (absolute) or
had a positive operational sign; it contains a - if the
sending field had a negative operational sign.
The character position containing this symbol contains a
space if the sending field either was unsigned (absolute)
or had a positive operational sign; it contains a
if
the sending field had a negative operational sign.

CR} Each of these symbols requires two character positions.
these
OB The character positions containing either of
symbols contains spaces if the sending field either was
unsigned (absolute) or had a positive operational sign;
they contain the symbol specified if the sending field
had a negative operational sign.

1
The caret (~) symbol is
assumed decimal point.

used

4-41

indicate

the

location

the

THE DATA DIVISION

PICTURE (Cont.)
Examples:

345~5,

(A-FLD contains

B-FLD contains

-345~5) 1

C-FLD picture-string

Result

MOVE A-FLD TO C-FLD

9999.99BCR

31 4 51 6 1.1 2 51~1~1~1

MOVE B-FLD TO C-FLD

9999.99BCR

31 4 51 6 1.1 2 51~1 CIR

MOVE A-FLD TO C-FLD

+9999.99

1+ 31 4 5161· 2 51

MOVE B-FLD TO C-FLD

+9999.99

1- 3 4 5 6

MOVE A-FLD TO C-FLD

-9999.99

1~13 4 5 6 · 2 51

MOVE B-FLO TO C-FLO

-9999.99

1-13 4 5 6

MOVE A-FLO TO C-FLD

9999.990B

MOVE B-FLO TO C-FLO

9999.990B

MOVE B-FLO TO C-FLD

$9999.99+

· 2151~1~1
3 4 5 6 · 2151 0 lBI
1$1 3 4 5 6 · 21 5 1-\

· 2 51

· 2151

13 4 5 6
1

Also see Note 16, IIFixed Inserting Editingll.
The + and - can also be used to perform floating insertion
editing, a combination of zero suppression and symbol insertion.
Floating insertion editing is indicated by the occurrence of two
or more consecutive + or
symbols at the beginning of the
picture-string. The total number of significant positions in the
editing field must be at least one greater than the number of
significant digits in the data to be edited. The floating + or moves from left to right through any high-order zeros until a
decimal point or the picture character 9 is encountered.
Examples:

(A-FLO contains

005~5i

B-FLO contains

-005~5)

C-FLO picture-string

Result

MOVE A-FLO TO C-FLO

++999.99

MOVE B-FLO TO C-FLD

++++9.99

1~1+1015161·12151
1~1~1-15161·12151

MOVE ZERO TO C-FLD

++999.99

MOVE ZERO TO C-FLO

+++++.++

1
The caret (A) symbol is
assumed decimal point.

used

4-42

indicate

I~I +1 01 0 10 1.1 0 10 I
I~I~I~I~I~I~I~I~I

the

location

the

THE DATA DIVISION

PICTURE (Cont.)
(In order for floating to go past decimal point, all numeric
positions of item must be represented by the floating insertion
symbol)
MOVE A-FLO TO C-FLO

--999.99

MOVE B-FLD TO C-FLD

--999.99

MOVE ZERO TO C-FLD

---99.99

MOVE ZERO TO C-FLD

-------

I~I~I 01 5 16 1.1 2 15 1
I~ I-I 01 5 16 1.1 2 15 1
I~ I~ I~ I0 I0 I· I0 I0 I
I~I~I~I~I~I~I~I~I

Also see Note 15, "Floating Insertion Editing".
Note that the + and
symbols are distinct from the
S
(operational sign)
symbol.
Normally,
the + and - symbols are
used to describe display items that are to appear on some printed
report;
they provide visual sign indication and cannot be used
with items appearing as operands in arithmetic statements.
$

A $ (or the symbol specified by the CURRENCY SIGN clause
in the SPECIAL-NAMES paragraph) represents the character
position into which a $ (or the currency symbol) is to be
placed. This symbol is counted in the size of the item.

Example:

(A-FLO contains

345~5)

Result

B-FLO character-string
MOVE A-FLO TO B-FLD

$9,999.99

1$131,1415161.17151

MOVE A-FLO TO B-FLD

$999,999.99

1$1010131,1415161.17151

Also see Note 16, "Fixed Insertion Editing".
The $ symbol can also be used to perform floating insertion
editing.
Floating
insertion editing is indicated by the
occurrence of two or more consecutive $ symbols at the beginning
of the character string.
The total number of significant
positions in the editing field must be at least one greater than
the number of significant digits in the data to be'edited. The
floating $ symbol floats from left to right through
any
high-order zeros until a decimal point or the picture character 9
is encountered.
Examples:

(A-FLO contains

005~5)

B-FLO picture-string

Result

MOVE A-FLO TO B-FLO

$$9,999.99

I~ 1$1 0 I, 10 15 16 1·J2bJ

MOVE A-FLO TO B-FLO

$$$,$$$.99

MOVE ZERO TO B-FLO

$$$,999.99

MOVE ZERO TO B-FLO

$$$,$$$.$$
4-43

I~ I~ I~I~I $1 5 16 1.1 2 151
I~ I~ I~I $1 0 10 10 I· 10 10 1
1~1~1~161~1~1~1~1~1~1

THE DATA DIVISION

PICTURE (Cant.)
Also see Note 17, "Floating Insertion Editing".
11.

There are two general methods of performing
PICTURE clause:
a.

insertion, or

suppression and replacement.

editing

the

There are four types of insertion editing available:
a.

Simple insertion

Special insertion

Fixed insertion

Floating insertion

There are two types of suppression and replacement editing:

12.

Zero suppression and replacement with spaces

Zero suppression and replacement with asterisks

The type of editing that can be performed upon
depends on the category to which the item belongs.

item

Type of Editing Allowed

Category
Alphabetic

None

Numeric

None

Alphanumeric

None

Alphanumeric edited

Simple insertion:

Numeric Edited

All (except for the restriction given in
Note 13 )

0 and B

13.

Floating insertion editing and zero suppression/replacement
editing are mutually exclusive in a PICTURE clause.
Only one
type of replacement can be used with zero suppression in a
PICTURE clause.

14.

Simple Insertion Editing

(, B 0)

The , (comma), B (space),
and 0
(zero)
constitute those
editing symbols used in simple insertion editing.
These
insertion characters represent the character position in the
item into which the character is inserted. These symbols are
counted in the size of the item ..

4-44

THE DATA DIVISION

PICTURE (Cent.)
15.

Special Insertion Editing (.)
The • (decimal point) symbol is used in special insertion
editing.
In addition to its use as an insertion character,
it also represents the position of the decimal point for
decimal point alignment. This symbol is counted in the size
of the item. The symbols . and V (assumed decimal point) are
mutually exclusive in a PICTURE clause. If the . is the last
symbol in the character-string, it must be immediately
followed by one of the punctuation characters (semicolon or
period).
.

16.

Fixed Insertion Editing ($ + - CR DB)
The currency symbol
($)
and the editing sign
control
characters (+
CR DB) constitute the characters used in
fixed insertion editing. Only one $ and one of the editing
sign
control
characters
can
be
used in a PICTURE
character-string. When the symbols CR or DB are used, they
represent two character positions in determining the size of
the item. The symbols + or - when used must be the leftmost
or rightmost character positions to be counted in the size of
the item. The $ when used must be the leftmost character
position to be counted in the size of the item, except that
it can be preceded by a + or· - symbol.
A fixed insertion
editing character appears in the same character position in
the
edited
item
as
it
occupied
in
the
PICTURE
character-string.
When the $ is used as a floiting insertion editing character,
the picture string must contain at least one $ more than the
maximum number of significant digits in the item to be
edited.
If you use a comma and the $ simultaneously for
editing, there must always be at least two $ to the left of
the comma because one $ is always printed; there is no place
for a significant digit to the left of the comma if you have
used only one $.
(If the i tern has a picture of $, $$$ then no
digit ever appears to the left of the comma; a $ is always
there.) A comma is omitted only when what appears to its
left consists only of zeroes.
(With the picture string $,$$$
the comma is never omitted.)
Editing sign control symbols produce the following
depending on the value of the data being edited.
Editing Symbol in
PICTURE character-string

results

Result
Data positive
Data Negative

space

2 spaces

4-45

THE DATA DIVISION

PICTURE (Cont.)
17.

Floating Insertion Editing ($$ ++ --)
The $ and the editing sign control symbols + and
floating
insertion editing characters and are
exclusive in a given PICTURE string.

are the
mutually

Floating insertion editing is indicated in
a
PICTURE
character-string by using a string of at least two of the
allowable insertion characters to represent the leftmost
numeric
character
positions
into which the insertion
characters can be floated.
Any of the simple insertion
characters embedded in the string of floating insertion
characters or to the immediate right of this string are part
of the floating string.
In a PICTURE character-string, there are
representing floating insertion editing.

only

two

ways

Represent any two or more of the leading
numeric
character positions on the left of the decimal point by
the insertion character. The result is that a single
insertion character is placed in the character position
immediately preceding the leftmost nonzero digit of the
data
being
edited
or
in the character position
immediately preceding the decimal point, or in the
character position represented by the rightmost insertion
character, whichever is encountered first.

Represent all numeric character
positions
in
the
character-string by the insertion character.
If the
value is not zero, the result is the same as when the
insertion character appears only to the left of the
decimal point. If the value is zero, the entire item is
set to spaces.
A picture-string containing floating insertion characters
must
contain at least one more floating insertion
character than the maximum number of significant digits
in the item to be edited. For example, a data field
containing five significant digit positions requires an
editing field of at least six significant positions.
All floating insertion characters are counted in the size
of the item.

18.

Zero suppression Editing (Z *)
The suppression of leading zeros and commas in a data field
is indicated by the use of the Z or the * symbol in a
picture-string. These symbols are mutually exclusive in a
given picture-string. Each suppression symbol is counted in
the size of the item.
If a Z is used, the replacement
character is a space.
If an * is used, the replacement
character is an *.
Zero suppression and replacement is
indicated by a string of one or more Zs or *s to represent
the leading numeric-character positions which are to be
replaced when the associated character position in the data
contains a leading zero.
Any of the simple insertion
characters embedded in this string of zero suppression
symbols or to the immediate right of this string are part of
the string.
4-46

THE DATA DIVISION

PICTURE (Cont.)
If the zero suppression symbols appear only to the left of
the decimal point, any leading zero in the data that
corresponds to a zero suppression symbol in the string is
replaced by the replacement character.
Suppression terminates at the first nonzero digit in the data
represented by the suppression symbol in the string or at the
decimal point, whichever is encountered first.
If all numeric character positions in the picture-string are
represented by the suppression symbol and the value of the
data is not zero, the result is the same as if the
suppression characters were only to the left of the decimal
point. If the value is zero, the entire item (including any
sign) is set to the replacement character (with the exception
of the decimal point if the suppresson symbol is an *).
When the * is used and the clause BLANK WHEN ZERO appears in
the same entry and zeros are moved to the field, all
character positions with the exception of the decimal point
are replaced by *
19.

The symbols + - * Z and $ when used as floating replacement
a
given
characters
are
mutually
exclusive
within
picture-string.

20.

The following chart shows the order of precedence of the
various picture-string symbols.
Each "y" on the chart
indicates that the symbol in the top row directly above can
precede the symbol at the left of the row in which the "y"
appears.
{}

indicate that the symbols are mutually exclusive.

The P and the fixed insertion + and - appear twice.
P9, +9, and -9 represent the case where these symbols
to the left of any numeric positions in the string.

appear

9P, 9+, and 9- represent the case where these symbols
to the right of any numeric positions in the string.

appear

The Z, *, and the floating ++, --, and $$ also appear twice.
Z., *., $$., and --. represent the case where these
appear before the decimal point position .

symbols

. Z, . *, . $$, . ++, and . -- represent the case where
symbols appear following the decimal point position.

these

4-47

THE DATA DIVISION

PICTURE (Cont.)

OTHER

FIXED INSERTION

z
oj::
Z

a
UJ

+9)
-9

x 19~}
9-

P9 9P

0:::

{;,} [;} 9 f++.}
--. I:~~} $$. .$$

A
X

(+~ ~'
9~ {~:} $

~~ Y

$
A
X

P9
9P

Y
Y

~;:J

[;} y

t~) y

t~ y

$$.

.$$

0:::
UJ

:r:
t-

y
y
Y

y
y

MR-S-1016-81

4-48

· THE DATA DIVISION

REDEFINES

4.11.2.8

REDEFINES

Function
The REDEFINES clause allows the same memory area to
two or more data items.

allocated

General Format
level-number

data-name-l

REDEFINES data-name-2

Technical Notes
1.

The REDEFINES clause,
data-name-l.

when

immediately

The level-numbers of the data-name-l and data-name-2
must be identical.

entries

This clause must not be used for level-number 66 or 88 items.
Also,
it must not be used for level-Ol entries in the FILE
SECTION;
implicit redefinition is provided by specifying
more than one data-name in the DATA RECORDS ARE clause in the
FD.

When the level-number of the data-names is other than
level-aI, the storage area for data-name-2 should be of the
same size or shorter than data-name-l. FILLER items can be
used to comply with this rule.

The REDEFINES entry must
describing data-name-2 •.

The REDEFINES entry cannot. be a
clause.

The redefinition entries cannot contain VALUE clauses.

Data-name-2 must not be qualified.

4-49

used,

must

immediately

subordinate

the

entries

the

OCCURS

THE DATA DIVISION

REDEFINES (Cont.)

The following example illustrates the use of the REDEFINES
entry.
The entries shown cause AREA-A and AREA-B to occupy
the same area in memory.
03

AREA-A USAGE DISPLAY-6.
04 FIELD-l PICTURE IS X(7).
04 FIELD-2 PICTURE IS A(13) .
04 FIELD-3.
05 SUBFIELD-l PICTURE IS
S999V99 USAGE IS CaMP.
05 SUBFIELD-2 PICTURE IS
S999V99 USAGE IS CaMP.
AREA-B REDEFINES AREA-A USAGE DISPLAY-6.
04 FIELD-A PICTURE IS X(22).
04 FIELD-B PICTURE IS X(5).
04 FILLER PICTURE IS X(9).

Note how the length of each area is calculated so that AREA-B
can be defined so that its size is equal to that of AREA-A.
AREA-A:

FIELD-l

FIELD-2

13
4

SUBFIELD-l

Total 6-bit characters

AREA-B:

FIELD-A

FIELD-B

FILLER

Total 6-bit characters

4-50

6-bit characters
(DISPLAY-6
assumed)
6-bit characters
(DISPLAY-6
assumed)
6-bit characters
used
(not
because CaMP items must start
at a new word boundary)
6-bit characters
(CaMP items
occupy one word, or six 6-bit
character positions)
6-bit characters
(CaMP items
occupy one word, or six 6-bit
character positions)
(DISPLAY-6
6-bit characters
assumed)
(DISPLAY-6
6-bit characters
assumed)
6-bit characters
(needed to
make
AREA-B size equal to
AREA-A)

THE DATA DIVISION

RENAMES (level-66)

4.11.2.9

RENAMES (level-66)

Function
The RENAMES clause permits alternate, possible overlapping,
of elementary items.

groupings

General Format
66

data-name-l RENAMES data-name-2

[THRU data-name-3]

Technical Notes
1.

All RENAMES entries associated with items in a given record
must immediately follow the last data description entry for
that record.
01

data-name-a
(data description entries)

(level-66 entries associated with this logical record)
data-name-b.

and can be
Data-name-l cannot be used as a qualifier,
qualified only by the names of the level-Ol or FD entries
associated with it.

Data-name-2 and data-name-3 must be the names of items in the
assoicated logical record and cannot be the same data-name.
Neither data-name-2 nor data-name-3 can have a level-number
of 01,
66, 77, or 88. Neither of these data-names can have
an OCCURS clause in its data description entry,
nor be
subordinate to an item that has an OCCURS clause in its data
description entry.
Data-name-2 must
precede
data-name-3
in
the
record
description,
and
data-name-3 cannot be subordinate to
data-name-2.
If there is any
associated
redefinition
(REDEFINES),
the ending point of data-name-3 must logically
follow the beginning point of data-name-2. When data-name-3
is specified, data-name-l is a group item that includes all
elementary items starting with data-name-2 (if data-name-2 is
an
elementary
item)
or the first elementary item in
data-name-2 (if data-name-2 is a group item)
and concluding
with
data-name-3
(or
the
last
elementary
item in
data-name-3) •

4-51

THE DATA DIVISION

RENAMES (level-66) (Cont.)
If data-name-3 is not specified, data-name-2 can be either a
group or elementary item.
I f i t is a group item, data-name-l
is treated as a group item and includes all elementary items
in data-name-2;
if data-name-2 is an elementary item,
data-name-l is treated as an elementary item with the same
descriptive clauses.
4.

The following examples illustrate
entry.
01

the

use

the

RECORD-NAME.
02 FIRST-PART.
03 PART-A.
04 FIELD-l PICTURE IS
04 FIELD-2 PICTURE IS
04 FIELD-3 PICTURE IS
03 PART-B.
04 FIELD-4 PICTURE IS
04 FIELD-S.
05 FIELD-SA PICTURE IS
05 FIELD-SB PICTURE IS
03 SECOND-PART.
03 PART-C.
04 FIELD-6 PICTURE IS .. .
04 FIELD-7 PICTURE IS .. .
66 SUBPART RENAMES PART-B THRU PART-C.
66 SUBPARTI RENAMES FIELD-3 THRU SECOND-PART.
66 SUBPART2 RENAMES FIELD-SB THRU FIELD-7.
66 AMOUNT RENAMES FIELD-7.

4-52

RENAMES

THE DATA DIVISION

SYNCHRONIZED

4.11.2.10

SYNCHRONIZED

Function
The SYNCHRONIZED clause specifies the positioning
item within a computer word (or words).

elementary

General Format

J SYNCHRONIZED
[ \ SYNC

)

J LEFT
\ RIGHT

MR-S-1017-81

Technical Notes
1.

This clause can appear only in the
elementary item.

This clause specifies that the item being defined
is to be
placed in an integral number of computer words and that it is
to begin or end at a computer word boundary.
No other
adjacent fields are to occupy these words.
The unused
positions, however, must be counted when calculating:

group

data

which

description

this

elementary

The size of any
belongs, and

item

The computer memory allocation when the item appears as
the object of a REDEFINES clause.
However,
when a
SYNCHRONIZED item is referenced, the original size of the
item
(as indicated by the PICTURE clause) is used in
determining such things as truncation, justification, and
overflow.

SYNCHRONIZED LEFT or SYNC LEFT specifies that the item is to
be positioned in such a way that it begins at the left
boundary of a computer word.
SYNCHRONIZED RIGHT or SYNC RIGHT specifies that the item is
to be positioned in such a way that it terminates at the
right boundary of a computer word.

When the SYNCHRONIZED clause is specified for an item within
the scope of an OCCURS clause, each occurrence of the item is
SYNCHRONIZED.

Any FILLER required to position the item as specified is
automatically generated by the compiler. The content of this
FILLER is indeterminate.

4-53

THE DATA DIVISION

SYNCHRONIZED (Cont.)
6.

COMP(UTATIONAL), COMP(UTATIONAL)-l, and INDEX items
are
always implicitly SYNCHRONIZEU RIGHT, and therefore cannot be
SYNCHRONIZED LEFT.

An item subordinate to one containing a VALUE
be SYNCHRONIZED.

Only DISPLAY-6, DISPLAY-7, DISPLAY-9, or COMP-3 items can
SYNCHRONIZED.

4-54

clause

cannot
be

THE DATA DIVISION

USAGE

4.11.2.11

USAGE

Function
The USAGE clause specifies the format
storage.

data

item

computer

General Format

COMPUTATIONAL
COMP
COMPUTATIONAL-l

[ USAGE IS ]

COMPUTATIONAL-3
COMP-3
DISPLAY
DISPLAY-6
pISPLAY-7
DISPLAY-9
INDEX
DATABASE-KEY
DBKEY
MR-S-1018-81

Technical Notes
1.

The USAGE clause can be written at any level.
If it is
written at a group level, it applies to each elementary item
in the group.
The USAGE clause of an elementary item cannot
contradict the USAGE clause of a group to which the item
belongs.
Note that the recording mode of a
file determines how the
data is recorded on the external medium.
The recording mode
can be inferred from the usage m~de of the data records,
but
the reverse
is never
true.
The usage of a data record is
never inferred from the declared recording mode of the file.
The implied USAGE of a group item is DISPLAY-7 if the first
elementary item subordinate to it is declared as DISPLAY-7,
or DISPLAY-9 if the first elementary item subordinate to
it
is declared as either DISPLAY-9 or COMP-3;
otherwise, its
USAGE is DISPLAY-6.
Howevei~ if the /X switch is included in
the compiler command string, the default USAGE is DISPLAY-9.
USAGES of DISPLAY-6, DISPLAY-7, and DISPLAY-9/COMP-3 cannot
be mixed.
However, USAGES of COMP, COMP-l and INDEX can be
mixed with the aforementioned USAGES.

This clause specifies the manner in
represented within computer memory.

4-55

which

data

item

THE DATA DIVISION

USAGE (Cont.)
3.

COMPUTATIONAL (COMP)
a.

COMP is equivalent to COMPUTATIONAL.

A COMPUTATIONAL item represents a value to be used in
computations and must be numeric. Its picture-string can
contain only the symbols:
9 S V P.
Its value is
represented as a binary number with an assumed decimal
point.

If a group item is described as COMPUTATIONAL, the
elementary
items
in
the group are COMPUTATIONAL.
However, the group itself is not COMPUTATIONAL and cannot
be used as an operand in arithmetic computations.

COMPUTATIONAL items of 10 or fewer decimal positions are
SYNCHRONIZED RIGHT in one computer word. Computational
items of more than 10 decimal positions are SYNCHRONIZED
RIGHT in two full computer words.

The following illustrations
COMPUTATIONAL item.

give

format

sign

I0 I
I

I-WORD COMPUTATIONAL ITEM

sign

I0 I
I

~
0

the

35
nol uscu

2-WORD COMPUTATIONAL ITEM

4-56

35
MR·S·l019·Bl

THE DATA DIVISION

USAGE (Cont.)
4.

COMPUTATIONAL-I (COMP-I)
a.

COMP-I is equivalent to COMPUTATIONAL-I.

A COMPUTATIONAL-I item can contain a value,
in floating
point format,
to be used in computations.
It must be
numeric. A COMP-I item must not have a PICTURE.

If a group item is described as COMPUTATIONAL-I,
the
elementary items within the group are COMPUTATIONAL-I.
However, the group item itself is not COMPUTATIONAL-I and
cannot be used as an operand in ar i thmetic comput-ations.

COMPUTATIONAL-I
computer word.

The ,following illustration
COMPUTATIONAL-I item.

sign

hinary
exponent

items

are

SYNCHRONIZED

gives

format

the

one

full
of

Illallt issa

MR-S-1020-81

4-57

THE DATA DIVISION

USAGE (Cont.)
5.

COMPUTATIONAL-3 (COMP-3)
a.

COMP-3 is equivalent to COMPUTATIONAL-3.

A COMP-3 item's picture string can contain only the
symbols 9 S V P. Its value is represented as a packed
decimal number with an assumed decimal point.

If a group item is declared as COMP-3 the elementary
items in the group are COMP-3. However, the group item
itself is not COMP-3 and cannot be used as an operand in
arithmetic computations.

The maximum size of a COMP-3 item is 18 decimal digits.

The following illustration gives the format of a COMP-3
item. Note that bits 0, 9, 18 and 27 of the word are not
used.

I
0

17 18

SYNCHRONIZED

2627

")")

LEFT

35
MR-S-1021-81

COMP-3 items can be
RIGHT.

COMP-3 items can share a computer word with other COMP-3
items or with DISPLAY-9 items. However, COMP-3 items
always begin at one of the following bit positions in a
word: 1, 10, 19, 28.

The actual size of a COMP-3 item in memory is at least
four bits larger and can be nine bits larger than the
number of character positions because the sign is stored
in the last four bits of the item and the item is stored
right justified on a nine-bit byte boundary.

The octal values 12, 14, and 16 represent plus signs and
the octal values 13 and 15 represent minus signs. The
octal value 17 represents the non-printing plus sign.
Although octal 12, 14 and 16 rep~esent plus signs, the
sign given to the positive result of any arithmetic
operation is 14. Similarly, the minus sign given to the
negative result of any arithmetic operation is 15.

SYNCHRONIZED

The non-printing plus sign is actually an absolute value
indicator.
Any positive or negative number which is
moved into an item with this sign receives this sign. In
arithmetic computations and numeric editing operations,
items containing the nonprinting plus sign are treated as
positive.

4-58

THE DATA DIVISION

USAGE (Cont.)
6.

DISPLAY-6
DISPLAY is equivalent to DISPLAY-6 when the
not given in the compiler command string.

A DISPLAY-6 item represents a string of 6-bit characters.
Its picture-string can contain any picture symbols.
Refer to App~ndix B for the-8IXBIT collating sequence.

DISPLAY-6 items can be SYNCHRONIZED LEFT or SYNCHRONIZED
RIGHT, as desired. Otherwise, they can share a computer
word with other DISPLAY-6 items.

The illustration below given the format
word.

DISPLAY-6

MR-S-1022-81

If the USAGE clause is omitted for an elementary item,
its USAGE is assumed to be DISPLAY-6 if the Ix switch has
not been included in the compiler command string.

DISPLAY-7
a.

A DISPLAY-7 item represents a string of 7-bit ASCII
characters.
Its picture-string can contain any picture
symbols.

DISPLAY-7 items can be SYNCHRONIZED LEFT or SYNCHRONIZED
RIGHT, as desired; otherwise, they can share a computer
word with other items.
If the item is SYNCHRONIZED
RIGHT, the last character of the item ends in bit 34 of a
computer word.

The illustration below gives the format
word.

o
8.

IX switch

DISPLAY-7

35
MR-S-1023-81

DISPLAY-9
a.

DISPLAY is equivalent to DISPLAY-9 when the IX switch
included in the command string to the compiler.

A DISPLAY-9
characters.
symbol.

item represents
a
string
of
EBCDIC
Its picture string can contain any picture

4-59

THE DATA DIVISION

USAGE (Cont.)
c.

DISPLAY-9 items can be SYNCHRONIZED LEFT or SYNCHRONIZED
RIGHT as desired;
otherwise, they can share a computer
word with other DISPLAY-9 OR COMP-3 items.
If the item
is SYNCHRONIZED RIGHT,
the last character of the item
ends in bit 35 of a computer word.

The maximum
characters.

The illustration below gives the format of a DISPLAY-9
item. Note that bits 0, 9, 18, and 27 are not used.

10.

I
f.

length

DISPLAY-9

item

17 18

4,096

2627

MR-S-1024-B1

If the USAGE clause is omitted for
an elementary item,
its USAGE is assumed to be DISPLAY-9 if the Ix switch has
been included in the computer command string.

INDEX
a.

An elementary item described as USAGE INDEX is called an
index data-item.
It is treated as a COMP item with
PICTURE S9(5) and can be used as a COMP item.

An index data-item must not have a PICTURE.

If a group item is described as INDEX,
the elementary
items within the group are treated as INDEX.
However,
the group item itself is not INDEX and cannot be used as
an operand in arithmetic statements.

Index data items and index-names (defined in the
clause by the INDEXED BY option) are equivalent.

If an index-name is defined
cannot be defined elsewhere.

OCCURS

clause,

DATABASE-KEY
a.

DATABASE-KEY
and
interchangeable.

DBKEY

An item described as USAGE DATABASE-KEY is treated as a
COMP item with PICTURE S9(10) and can be used as a COMP
item.

4-60

are

equivalent

and

THE DATA DIVISION

USAGE (Cont.)
c.

The item with USAGE DATABASE-KEY must not have a PICTURE.

An item with USAGE DATABASE-KEY is primarily used in
programs accessing data bases through the Data Base
Management System (DBMS). This item can be used to store
the value of a data base key. All data base keys are
assigned by DBMS and cannot be changed by you.
Refer to
the
DBMS
Programmer's
Procedures Manual for more
information about DBMS.

4-61

THE DATA DIVISION

VALUE

4.11.2.12

VALUE

Function
The VALUE clause defines the initial value of WORKING-STORAGE
and the values associated with condition-names (level-88).

items,

General Format
Format 1:
[VALUE

literal]

Format 2:

VALUE

VArnEs

IS
)
ARE

[,literal-3

literal-1

[THRU

[ THRU

literal-2 ]

literal-4] ] ...

MR·S·1025·81

Technical Notes
1.

Format 2 can be specified only for level-88 items.

In the FILE SECTION, the VALUE clause can be used only with
level-88 items.
In the WORKING-STORAGE SECTION, it can be
used at all levels, except level-66. It must not be stated
in a data description entry that contains an OCCURS clause or
that is subordinate to an entry containing an OCCURS clause.
Also, it must not be stated in an entry that contains a
REDEFINES clause or that is subordinate to an entry that
contains a REDEFINES clause.

If the VALUE clause is used at a group level, the literal
must be a figurative constant or a nonnumeric literal. The
group item is initialized to this value without consideration
for the individual elementary or group items contained within
this group. No VALUE clauses can appear at subordinate
levels within the group.

If no VALUE clause appears for a WORKING-STORAGE
initial value of the item is unpredictable.

4-62

item,

the

THE DATA DIVISION

VALUE (Cont.)
5.

More information concerning Format 2 can be
"condition-name (Level-88)" in this chapter.

The VALUE clause must not conflict with other clauses in the
data description entry or in the data description entries
within the hierarchy of th~ item. The following rules apply:

found

under

If the category of an item is numeric, all literals in
the VALUE clause must be numeric. All literals in a
VALUE clause must have a value within the range of values
indicated by the PICTURE clause; for example, an item
with PICTURE PPP9 can have only the values in the range
.0000 through .0009.

If the category of
the
item
is
alphabetic
or
alphanumeric, all literals in the VALUE clause must be
alphanumeric literals. The literal is aligned according
to the normal alignment rules (see "JUSTIFIED") except
that the number of characters in the literal must not
exceed the size of the item.

If the category of an item is
numeric-edited
or
alphanumeric-edited, no editing of the value is performed
in the VALUE clause.

The USAGE of the literal agrees with the USAGE of the
item. Thus, if the item has USAGE DISPLAY-6, the literal
also has USAGE DISPLAY-6 and its value must contain legal
SIXBIT characters.

The figurative constants SPACE(S), ZERO(E) (S), QUOTE(S),
LOW-VALUE(S), and HIGH-VALUE(S) can be substituted for a
literal.
If the item
is
numeric,
only
ZERO(E) (S),
LOW-VALUE(S), and HIGH-VALUE(S) are allowed.

4-63

THE DATA DIVISION

REPORT SECTION
4.12

REPORT SECTION

The REPORT SECTION contains the descriptions of one
and the report groups that make up each report.

reports

Report groups are the basic elements of a report. Each report group
is divided into report lines, which are in turn divided into fields.
The report groups that can appear in a report are:
REPORT HEADING

Printed once at the beginning

REPORT FOOTING

Printed once at the end

PAGE HEADING

Printed at the beginning of each page

PAGE FOOTING

Printed at the end of each page

DETAIL

Printed for each set of report data

CONTROL HEADING

Printed at the beginning of each detail
report group when a control break occurs

CONTROL FOOTING

Printed at the end of each detail
group when a control break occurs

report

The detail report groups contain the data items that constitute the
report.
Data items within a detail group can be designated by the
programmer as controls. These control items are in descending order
of rank from FINAL, through major, intermediate, to minor. Each time
a control item changes, a control break is said to occur; the control
footings for the detail group are printed, and control headings for
the next detail group are printed before the next detail group is
printed.
A FINAL control break occurs twice during the generation of
a report, before the first detail line is printed and after the last
detail line is printed. The most major control breaks least often and
the most minor control breaks most often. If the most minor control
field breaks, the control footing for that control field is generated,
and the control heading for the next detail group for that control is
generated. If a more major control field breaks, the control footings
for all fields more minor than that which broke are gen~rated,
starting with the most minor and continuing up to the control footing
for the control that broke. The control headings are then printed
starting with the control field that broke and continuing through the
most minor control field. An example of a skeleton report follows.
REPORT HEADING
PAGE HEADING
CONTROL HEADING (FINAL)
CONTROL HEADING (MAJOR)
CONTROL HEADING (MINOR)
DETAIL GROUP

CONTROL FOOTING (MINOR)
CONTROL HEADING (MINOR)
DETAIL GROUP

(control break occurred)

4-64

THE DATA DIVISION

REPORT SECTION (Cont.)
CONTROL FOOTING
CONTROL FOOTING
CONTROL HEADING
CONTROL HEADING
DETAIL GROUP

(MINOR)
(MAJOR)
(MAJOR)
(MINOR)

CONTROL FOOTING (MINOR)
CONTROL FOOTING (MAJOR)
CONTROL FOOTING (FINAL)
PAGE FOOTING
REPORT FOOTING

(control break occurred)

within a report file, more than one report can be written.
If more
than one report is written in a file, the names of all the reports
must be specified in the REPORTS clause of the file description entry,
and a unique code must be specified for each report by means of the
CODE clause in the Report Description fo each report.
The code must
also be identified in the SPECIAL-NAMES section of the ENVIRONMENT
DIVISION.
To print one of the reports within a
report file,
you enter
the
filename and the code of the desired report into the queue for the
line-printer spooler, LPTSPL.
LPTSPL copies the report lines with the
designated code to the line printer, but does not erase the lines from
the file.
The file is entered into the line-printer queue by means of
the PRINT monitor command.
The code is specified by the /REPORT
switch in the Queue command string.
PRINT filespec/REPORT:code
Only the first 12 characters of the code are
command string.

accepted

the

Included in the description of a report are the number of lines on a
report page, where headings should begin on the page, where footings
should end, the column on the page where each item in a
report group
is to be placed, and the number of lines that are left between report
groups.
To cause a report to be printed, in addition to specifying its format
and data in the DATA DIVISION, you must include certain verbs in the
PROCEDURE DIVISION. These verbs are:
INITIATE, which initializes the
report and sets sum counters to zero;
GENERATE, which causes report
groups to be generated on specified control breaks;
and TERMINATE,
which ends the report.
An additional statement, USE BEFORE REPORTING,
causes a programmer-specified procedure to be performed before a
report group is produced.

4-65

THE DATA DIVISION

REPORT DESCRIPTION (RD)
4.12.1

Report Description (RD)

Function
The Report Description furnishes information concerning
structure for a report.

the

physical

General Format
RD report-name
[CODE mnemonic-name J
jCONTROL IS } {identifier-l ,identifier-2 ...
}]
FINAL [,identifier-l [,identifier-2] ... J
[ lCONTROLS ARE

LIMIT IS l ·
{LINES}
[ PAGE { LIMITS AREJ lnteger-l LINES
[ HEADING inte ger-2J [FIRST DETAIL integer-3 J

[LAST DETAIL integer-4] [FOOTING integer-5 ]] -'MR-S-1026-81

Technical Notes
appearance

the

optional

clauses

The order of
immaterial.

A fixed data-name PAGE-COUNTER is automatically generated for
each RD entry.
Its function is to contain the current page number of a
report.
It is a COMPUTATIONAL item; its size is equal to
the size of the largest field that refers to it in a SOURCE
clause. The contents of the PAGE-COUNTER are set to 1 by the
INITIATE statement.

The fixed data-name LINE-COUNTER is automatically generated
for each RD entry. Its function is to contain the current
line number within a report page.
It is a COMPUTATIONAL
item;
its size is based on the number of lines specified in
the PAGE-LIMIT clause.

4-66

THE DATA DIVISION

REPORT DESCRIPTION (RD) (Cont.)
4.

PAGE-COUNTER or LINE-COUNTER can be referenced as if it were
any data-name.
It must be qualified by the report-name if
more than one RD entry is present in the program.

Each of the above clauses

appea~s

4-67

on the following pages.

THE DATA DIVISION

CODE

4.12.1.1

CODE

Function
The CODE clause defines a unique string of one or more characters that
is affixed to each line of the report.
General Format
CODE mnemonic-name
Technical Notes
1.

This clause is necessary only if more than one report
be written in a single file.

Mnemonic-name is defined in the
the ENVIRONMENT DIVISION.

The character string represented by mnemonic-name is affixed
to the beginning of each report line, and is used to uniquely
define the lines of separate reports written in one file.

The number of characters represented by mnemonic-name must be
the same for the codes of all reports in the same file.

4-68

SPECIAL-NAMES

paragraph

THE DATA DIVISION

CONTROL(S)

4.12.1.2

CONTROL(S)

Function
The CONTROL clause indicates the identifiers that control the printing
of totals in the report.
General Format

~~~~~i~ier-~ . [,identifier-2]
}
1J ~~~i~~ts I~RE ) { FINAL,ldentlfler-l
[,identifier-2] ...
MR-S-1027-81

Technical Notes
1.

The CONTROL clause is required when CONTROL
CONTROL FOOTING report groups are specified.

The identifiers specify the control hierarchy for this
report. They are listed in order from major to minor; FINAL
is the highest level of control, identifier-l is the major
control, identifier-2 is the intermediate control, etc. The
last identifier specified is the minor control.

Identifiers must not be defined in the Report Section.
Identifiers can be qualified, but they cannot be subscripted
or indexed.

4-69

HEADING

THE DATA DIVISION

PAGE LIMIT

4.12.1.3

PAGE LIMIT

Function
The PAGE LIMIT clause indicates the specific line
maintained within the presentation of a report page.

control

must

General Format

[HEADING inte ger-2] [FIRST DETAIL integer-3]
[LAST DETAIL integer-4] [FOOTING integer-s]
MR-S-l028-81

Technical Notes
1.

The PAGE LIMIT clause is required when page
controlled by the Report Writer.

All integers must have a positive value less than
Integer-2
through
integer-5 must not be greater
integer-I.

If absolute line spacing is indicated for all report groups
(see the LINE NUMBER and NEXT GROUP clauses Sections 4.12.2.3
and 4.12.2.4 respectively), integer-2 through integer-5 need
not be specified.

The integers specify line numbers relative to
of a page.

The HEADING clause specifies the first line of a page
used;
no line precedes integer-2.

The FIRST DETAIL clause specifies the first line of the first
DETAIL or CONTROL print group;
no DETAIL or CONTROL group
precedes integer-3.

The LAST DETAIL clause specifies the last line of a DETAIL or
CONTROL HEADING report group;
no such group extends beyond
integer-4.

The FOOTING clause specifies the last line number of the last
CONTROL FOOTING report group;
no CONTROL FOOTING group
extends beyond integer-5.

4-70

format

the

512.
than

beginning
to

THE DATA DIVISION

PAGE LIMIT (Cont.)
9.

If any optional clause is omitted, a value is assumed for its
integer. The default values are:
integer-2:

Default is 1

integer-3:

Default is the value of integer-2

integer-4:

Default is the value
of
integer-5
if
specified; if integer-5 is also omitted, the
default is the value of integer-l

integer-5:

Default is the value
of
integer-4
specified;
if integer-4 is omitted,
default is the value of integer-I.

4-71

if
the

THE DATA DIVISION

Report Group Description (RD)
4.12.2

Report Group Description

Function
The Report Group Description entry specifies the
format of a particular report group.
General Format
Opt ion 1:
01 [ data-narne-l]
integer-l

}]

integer-3

}]

LINE NUMBER IS { PLUS integer-2
[
NEXT PAGE

NEXT GROUP IS { PLUS integer-4
[
NEXT PAGE
REPORT HEADING
RH
PAGE HEADING

PH ,CONTROL HEADING} {identifier-I}
- lCH
FINAL
TYPE IS DETAIL
DE {CONTROL FOOTING} {identifier-2}
CF
FINAL
PAGE FOOTING
PF
REPORT FOOTING
RF

USAGE
[[ - IS]

I~~~~t~~-6Il

MR-S-1029-81

pISPLAY-ZDISPLAV-9

4-72

characteristics

and

THE DATA DIVISION

Report Group Description (RD) (Cont.)
Option 2:
level-number [data-name-I]
[ BLANK WHEN ZERO]
[ COLUMN NUMBER IS integer-I]
[ GROUP INDICATE]

integer-2
}]
LINE NUMBER IS { PLUS integer-3
[
NEXT PAGE

[llliTURE I IS character-string]
RESET ON { identifier-I}]
[FINAL
SOURCE IS identifier-2
}
SUM
identifier-3
[,identifier-4]
...
[UPON
data-name-~
{ VALUE IS literal-I

[ [ USAGE IS]

!
1
I
DISPLAY
DISPLAY-6
DISPLAY-7
DISPLAY-9

...!....

MR-S-1030-81

4-73

THE DATA DIVISION

Report Group Description (RD) (Cont.)
Technical Notes
1.

Except for the data-name, which when present must immediately
follow the level-number, the clauses can be written in any
order.

In order for a report group to be referred to by a
DIVISION statement, it must have a data-name.

All elementary items must have a PICTURE clause
the clauses SOURCE, SUM, or VALUE.

For a detailed description of the BLANK WHEN ZERO, JUSTIFIED,
PICTURE, VALUE, and USAGE clauses, see the pages following
the Data Description Entry.

The data-name need not appear in an entry unless it is
referred to by a GENERATE or USE statement, or reference is
made to the SUM counter.

If the Ol-level item is elementary, the clauses in Format
can be used in addition to the clauses in Format 1.

The remaining clauses
following pages.

are

4-74

described

and

detail

PROCEDURE
one

2
the

THE DATA DIVISION

COLUMN

4.12.2.1

COLUMN

Function
The COLUMN NUMBER clause indicates the column on the printed page
which the high-order (leftmost) character of an item is printed.

General Format
COLUMN NUMBER IS integer
Technical Notes
1.

Integer must have a positive value less than 512.

This clause is valid only for an elementary item.

Within a report group and a
particular
LINE
NUMBER
specification, COLUMN NUMBER entries must be indicated from
left to right.

If the COLUMN NUMBER clause is omitted, the elementary item,
though included in the description, is suppressed when the
report group is produced at object time.

4-75

THE DATA DIVISION

GROUP INDICATE

4.12.2.2

GROUP INDICATE

Function
The GROUP INDICATE clause indicates that this elementary item is to be
produced only on the first occurrence of the item after any CONTROL or
PAGE breaks.
General Format
GROUP INDICATE
Technical Notes
1.

This clause can only be used at the elementary level within a
TYPE DETAIL report group.

A GROUP INDICATEd item is presented in the first detail line
of a report after any control breaks and after any page
breaks; it is suppressed at all other times.

4-76

THE DATA DIVISION

LINE NUMBER

4.12.2.3

LINE NUMBER

Function
The LINE NUMBER clause indicates the absolute or relative line
entry in reference to the page or the previous entry.

number

General Format

LINE

NUMBER

integer-l
}
PLUS integer-2

N'EXf PAGE

MR-S-1031-81

Technical Notes
1.

Integer-l and integer-2 must be positive integers with values
less than 512.
Integer-l must be within the range specified
by the PAGE LIMITS clause in the RD entry.

The LINE NUMBER clause must be given for each report line of
a report group, and must be specified at or before the first
elementary item that contains a COLUMN clause of each report
line.
If an item does not contain a COLUMN clause and the
LINE NUMBER clause is specified for it, no printing is done,
but the - LINE NUMBER clause causes vertical spacing to be
done.

If a LINE NUMBER clause is specified for an item, all entries
following that item,
up to but not including the next item
with a LINE NUMBER clause, are presented on the same line.

A LINE NUMBER at a subordinate level
LINE NUMBER at a group level.

Integer-l indicates that the current line is to be
at that line number.

PLUS integer-2 indicates that the LINE-COUNTER is to be
incremented by the value of integer-2, and that the current
line is to be presented on the line specified by the new
value of the LINE-COUNTER.

NEXT PAGE is used to indicate an automatic skip to the next
page before the current line is presented.
If there is no
PAGE-LIMIT clause, there is only a skip to the top of the
next page.
However, if there is a PAGE-LIMIT clause, after
skipping to the next page,
the Report writer spaces as
follows:

4-77

can

not

contradict

presented

THE DATA DIVISION

Type of Line

Space To

Detail, control heading,
control footing

First detail line

Report heading, report
footing, page heading

Heading line

Page footing

Footing line

4-78

THE DATA DIVISION

NEXT GROUP

4 • 12 . 2 • 4

N.EXT GROUP

Function
The NEXT GROUP clause specifies the spacing
last line of the report group.

condition

following

the

General Format

integer-l
}
PLUS i nteger- 2
NEXT PAGE

GROUP

MR·S·1032·81

Technical Notes
1.

The NEXT GROUP clause can appear only at the 01
report group.

Integer-l and integer-2 must be positive integers with values
less than 512.
Integer-l cannot exceed the number of lines
specified by the PAGE LIMIT clause.

Integer-l specifies a line number to which
is set after the group is presented.

PLUS integer-2 specifies a
relative line
number
that
increments the LINE-COUNTER by the value of integer-2 after
the group is presented.
Integer-2 is the number of lines
skipped following the last line of the report group.

NEXT PAGE indicates an automatic skip to the next page
the group is presented.

4-79

the

level

LINE-COUNTER

after

THE DATA DIVISION

RESET

4.12.2.5

RESET

Function
The RESET clause indicates the CONTROL data-item that causes
counter to be reset to zero on a control break.

the

SUM

associated

with

General Format
RESET ON {identifier-l}
-FINAL
MR-S-1033-61

Technical Notes
1.

Identifier-l must be one of the identifiers
the CONTROL clause in the RD entry.

The RESET clause can be used only in conjunction with
clause at a CONTROL FOOTING elementary level.

Identifier-l must be a higher level (more major) control
identifier than the control identifier associated with this
report group.

After a TYPE CONTROL FOOTING report group is presented, the
sum counters associated with that group are automatically set
to zero, unless an explicit RESET clause directs that the
counter be cleared at a higher level.

4-80

SUM

THE DATA DIVISION

SOURCE

4.12.2.6

SOURCE

Function
The SOURCE clause indicates the source of the data for a report item.
General Format
SOURCE IS identifier
Technical Notes
1.

The SOURCE clause can only be given at the elementary level.

Identifier must indicate an item that appears in the FILE
WORKING-STORAGE SECTION.

When the report group is presented, the contents of
report item are replaced by the contents of identifier.

this

4-81

•

THE DATA DIVISION

SUM

4.12.2.7

SUM

Function
The SUM clause indicates the items to be summed to produce the
of data for a report item.

source

General Format

SUM identifier-l [,identifier-2]

[ UPON data-name-l]
MR-S-1034-81

Technical Notes
1.

A SUM clause can appear only in a TYPE CONTROL FOOTING report
group.

Each identifier must indicate a SOURCE item in a TYPE DETAIL
report group,
or a
SUM counter in a TYPE CONTROL FOOTING
report group.

If the SUM counter is referred to by a PROCEDURE DIVISION or
REPORT SECTION statement, a data-name must be specified for
the
item.
The data-name then represents the summation
counter automatically generated by the Report Writer;
that
data-name does not represent the report group item itself.

A summation counter
is
incremented
just
before
the
presentation of the
identifiers.
Any editing of the SUM
counters is done only when the sum item is presented;
at all
other times it is treated as a numeric item.

If higher-level report groups are indicated in the control
hierarchy,
each lower level that is figured into the sum is
summed into the higher
level before each lower level
is
reset,
that
is,
counters are rolled forward prior to the
reset operation.

The UPON option is required to obtain selective summation for
a particular data item that is named as a SOURCE item in two
or more TYPE DETAIL report groups.
Identifier-l
and
identifier-2 must be SOURCE data items in data-name-l;
data-name-l must be the name of a TYPE DETAIL report group.

When the UPON option is used, summation occurs only when a
GENERATE statement references data-name-l.
It does not occur
during summary reporting (refer to the GENERATE statement in
the PROCEDURE DIVISION).

The identifiers cannot be subscripted or indexed.

4-82

THE DATA DIVISION

TYPE

4.12.2.8

TYPE

Function
The TYPE clause specifi~s the particula~ type of report group that is
described by this entry and
indicates when the
report group is
generated.
General Format

REPORT HEADING
RH
PAGE HEADING

E!i {~~NTROL HEADING} {~f~~Ci fier-n }
TYPE IS

DETAIL
DE
-

{CONTROL FOOTING} {identifier-n}
CF
FINAL

PAGE FOOTING
PF
REPORT FOOTING
RF
MR-S-1035-81

Technical Notes

RH
PH
CH
DE
CF
PF
RF

If the report group is described as TYPE DETAIL, the GENERATE
statement in the PROCEDURE DIVISION directs the Report Writer
to produce the named report group.

The REPORT HEADING entry indicates a
report group that
is
produced only once at the beginning of a report, during the
execution of the first GENERATE statement.
There can be only
one report group of this type in a report.

The PAGE HEADING entry
indicates a
report group that is
automatically produced at the beginning of each page of the
report.
There can be only one report group of this type in a
report.

The CONTROL HEADING entry indicates a report group that is
produced at the beginning of a control group for a designated
identifier.
In the case of FINAL, it is produced once before
the first control group during the execution of the first
GENERATE statement.
There can be only one report group of
this type for each identifier and for FINAL.

is
is
is
is
is
is
is

an
an
an
an
an
an
an

abbreviation
abbreviation
abbreviation
abbreviation
abbreviation
abbreviation
abbreviation

for
for
for
for
for
for
for

REPORT HEADING;
PAGE HEADING;
CONTROL HEADING;
DETAIL;
CONTROL FOOTING;
PAGE FOOTING;
REPORT FOOTING.

4-83

THE DATA DIVISION

TYPE (Cont.)
6.

The CONTROL FOOTING entry indicates a report group that is
produced at the end of a control group for a designated
identifier, or that is produced only once at the termination
of a report in the case of FINAL. There can be only one
report group of this type for each identifier and for FINAL.
In order to produce any CONTROL FOOTING report groups, a
control break must occur.

The PAGE FOOTING entry indicates a report group that is
automatically produced at the bottom of each page of the
report. There can be only one report group of this type in a
report.

The REPORT FOOTING entry indicates a report group that is
produced only once, at the termination of a report. There
can be only one report group of this type in a report.

Each identifier, as well as
identifiers associated with
entry.

4-84

FINAL, must
the CONTROL

be one of the
clause in the RD

CHAPTER 5
THE PROCEDURE DIVISION

The Procedure Division specifies the processing to be performed on the
files and the file data described in the Environment and Data
Divisions.
The Procedure Division contains a series of
COBOL
procedure statements which describe the processing to be done.
Statements, sentences, paragraphs, and sections are described in
Section 5.1. Sections are optional and permit a group of consecutive
paragraphs to be referenced by a single procedure-name. Sections can
also
be
used
for
segmentation
purposes
(see Section 5.3,
Segmentation). If any section appears in the Procedure Division, then
all paragraphs must appear within a section.
The first entry in the Procedure Division of a source program must be
the division-header.
The next en~ry must be either the DECLARATIVES
header (see the USE statement, Section 5.9.42), or a paragraph-name or
section-name.

PROCEDURE DIVISION

~SING data-name-J

~ a t a - na me - 2

[DE CLARA n VES.
{ section-name SECTION

~aragraPh-name.

[segment-number~

[sentence]

... ]

declarative-sentence

.. , }

END DECLARATIVES~
{ sect ion-name SECn ON

~egment- numbe rJ

[!aragraPh-name. [sentence]

Only in a subprogram
DIVISION header.

can

... ]

USING

clauses

appear

the

PROCEDURE

When a program-name is specified in a CALL statement in a calling
program, control is transferred to the beginning of the executable
code in the subprogram (that is, the Procedure Division).
The identifiers in the USING clause indicate those data items in the
called program that can reference data items in the calling program.
The order of identifiers in the CALL statement of the calling program
and in the PROCEDURE DIVISION header of the called program is
critical. The items in the USING clauses are related by their
corresponding positions, not by name. Corresponding identifiers refer
to a single set of data that is available to both the calling and
called programs.

5-1

THE PROCEDURE DIVISION
The number of identifiers in the USING clause in the PROCEDURE
DIVISION header must be less than or equal to the number of
identifiers in the USING clause in the CALL statement in the calling
program.

5.1

SYNTACTIC FORMAT OF THE PROCEDURE DIVISION

The PROCEDURE DIVISION consists of a series of procedure statements
grouped into sentences, paragraphs, and sections. By grouping the
statements in this manner, reference can be made to them by a
procedure-name (that is, a paragraph-name or a section-name). The
order in which procedure-statements are executed can be controlled by
using the sequence-control verbs ALTER, GO TO, and PERFORM.

5.1.1

Statements and Sentences

Statements fall into three categories: imperative, conditional, and
compiler-directing, depending upon the verb used. Verbs, in turn, are
also classified into certain categories. These categories and their
relationship to the three statement categories are given in Table 5-1.
'rable 5-1
Procedure Verb and Statement Categories
Verb

Verb Category

Statement Category

ADD
COMPUTE
DIVIDE
MULTIPLY
SUBTRACT

ARITHMETIC

IMPERATIVE

ALTER
CALL
ENTER
ENTRY
EXIT PROGRAM
GOBACK
GO TO
PERFORM
STOP

SEQUENCE-CONTROL

IMPERATIVE

EXAMINE
MOVE
SET
STRING
UNSTRING

DATA MOVEMENT

IMPERATIVE

5-2

THE PROCEDURE DIVISION
Table 5-1 (Cont.)
Procedure Verb and Statement Categories

5.1.2

Verb

Verb Category

CANCEL
EXAMINE
FREE
MERGE
RELEASE
RETAIN
RETURN
SEARCH
SORT
TRACE

MISCELLANEOUS

IMPERATIVE

GENERATE
INITIATE
SUPPRESS
TERMINATE

REPORT

IMPERATIVE

ACCEPT
CLOSE
DELETE
DISPLAY
OPEN
READ
REWRITE
SEEK
WRITE

I-O

IMPERATIVE

CONDITIONAL

COpy
EXIT
NOTE
USE

COMPILER-DIRECTING

Statement Category

Sentences

A statement or sequence of statements terminated by a period forms
a
sentence.
Sentences are classified into the same three categories as
statements.
An imperative sentence consists solely of one or more
imperative
statements.
Except for
imperative sentences containing one of the
sequence-control verbs, control passes to the next procedural sentence
following execution of the imperative sentence.
If a GO TO or STOP
RUN statement is present in an imperative sentence,
it must be the
last statement in the sentence.

5-3

THE PROCEDURE DIVISION
A conditional sentence performs some test and, on the basis of the
results of that test, determines whether a true or a false path should
be taken. A conditional sentence is one that contains the conditional
verb
(IF) or one of the option clauses ON SIZE ERROR (used with
arithmetic verbs), AT END (used with the READ verb), or INVALID KEY
(used with the READ verb for mass storage devices).
A compiler-directing sentence consists of a single compiler-directing
statement.
Compiler-directing sentences are used to indicate the end
point of a PERFORM loop (EXIT), insert comments in the PROCEDURE
DIVISION (NOTE), copy library entries (COPY) and specify procedures
for input-output errors and label handling
(USE) .
Generally,
compiler-directing sentences generate no object program code.

5.1.3

Paragraphs

A single sentence or a group of sequential sentences can be assigned a
paragraph-name for reference. The paragraph-name must begin in Area A
(see Chapter 1) and terminate with a period. The first sentence of
the paragraph can begin after the space following this period or it
can begin on the next line, beginning in Area B.
A paragraph-name must be unique within its section, but need not be
unique within the program.
A non-unique paragraph-name must be
qualified by its section-name except when it is referenced from within
its own section.

5.1.4

Sections

A single paragraph or a group of sequential paragraphs can be assigned
a section-name for reference. The section-name must begin in Area A,
be followed by the word SECTION, and optionally, followed by a
priority number, and terminated by a period.
section-name SECTION nne
If the section-name is in the DECLARATIVES portion, it can not have a
priority number. A USE statement can appear following the terminating
space after the period.
The section-name applies to all paragraphs following it until
section-header is encountered.

another

All section-names must be unique within a program.
Sections are
optional within the PROCEDURE DIVISION, but if a DECLARATIVES portion
is used there must be a named section immediately following the END
DECLARATIVES statement.
When a section-name is referenced, the word SECTION is not allowed
the reference.

5-4

THE PROCEDURE DIVISION
5.2

SEQUENCE OF EXECUTION

In the absence of sequence-control verbs, sentences are executed
consecutively within paragraphs, paragraphs are executed consecutively
within sections, and sections are executed consecutively within the
PROCEDURE
DIVISION (with the exception of sections within the
DECLARATIVES portion, which are executed individually when the related
condition occurs).

5.3

SEGMENTATION AND SECTION-NAME PRIORITY NUMBERS

COBOL source programs can be written to enable certain portions of the
PROCEDURE DIVISION code to share the same memory area at object run
time, thus decreasing the amount of memory required to run the object
program, though not the time.
The method used to achieve this
reduction is called segmentation.
Segmentation consists of dividing the PROCEDURE DIVISION sections into
logically related groupings called segments. The programmer defines a
segment by assigning the same priority-number
(a priority-number
follows the word SECTION in the section-header, and can be in the
range 00 through 99) to all the sections to be included in that
segment;
these sections need not appear consecutively in the source
program.
Segments are classified into three groups, depending upon their
priority-number. These three groups are described in Table 5-2.
Table 5-2
Types of Segments
Priority Number

Type

None, or 00 up to
SEGMENT-LIMIT
minus I

Resident
Segment

This segment is always resident in memory and is never
overlaid.

SEGMENT-LIMIT
up to 49

Nonresident;
ALTERed GO
TOs retained

segments are
nonThese
resident
and are brought
into memory when
needed.
Any ALTERed GO TOs retain
their most
recently
set
values.

50 through 99

Nonresident;
ALTERed GO
TOs reset

These segments are also nonresident and
are brought
into memory when
needed.
Any ALTERed GO TOs do not
retain their latest values,
reset to their
but
are
original setting each time
the segment is entered from
another segment.

Description

5-5

THE PROCEDURE DIVISION
In addition to the resident segment, all data areas described in the
DATA DIVISION are resident at all times. Thus, memory can be thought
of as being divided into two parts:
1.

A resident area, in which
resident segment, and

reside

all

data

areas

and

the

A nonresident area, equal to the size of the largest
nonresident segment, into which each nonresident segment is
read when needed. Since each nonresident segment reads into
the same memory area, any previous nonresident segment in
that area is overlaid and must be brought in again when it is
to be executed again.

'rhe resident segment should consist of those sections that constitute
the main portion of the processing. Infrequently-used sections can be
allocated to the nonresident segments.
NOTE
Non-resident
shareable.

5.4

code

can

never

ARITHMETIC EXPRESSIONS

An arithmetic expression is an identifier of a numeric elementary
item, or a numeric literal, or such identifiers and literals separated
by arithmetic operators.
Algebraic negation can be indicated by a unary minus symbol.

5.4.1

Arithmetic Operators

There are five arithmetic operators that can be used in arithmetic
expressions.
They are represented by specific character symbols that
must be preceded by a space and followed by a space.
Arithmetic Operator
+

5.4.2

Meaning
Addition or unary plus
Subtraction or unary minus
Multiplication
Division
Exponentiation
Exponentiation

Formation and Evaluation Rules

The following rules for information and evaluation apply to arithmetic
expressions.

5-6

THE PROCEDURE DIVISION
1.

Parentheses specify the order in which elements within an
arithmetic expression are to be evaluated.
Expressions
within parentheses are evaluated first.
within a nest of
parentheses, the evaluation proceeds from the elements within
the innermost pair of parentheses to the outermost pair of
parentheses. When parentheses are not used, or parenthesized
expressions are at the same level of inclusiveness, the
following hierarchal order of operations is implied:
First:
then
then
and then

unary +, unary -

** and
* and /

(exponentiation)
(multiplication and division)
(addition and subtraction)

+ and -

When the order of a sequence of operations on the same
hierarchal level
(for example, a sequence of + and
operations)
is not
completely
specified
by
use
of
parentheses, the order of operations is from left to right.

An arithmetic expression can begin with one of the following:

(- + variable
and can end only with one of the following:
) variable
4.

5.5

There must be a one-to-one correspondence between left and
right parentheses in an arithmetic expression; each left
parenthesis must precede its corresponding right parenthesis.

CONDITIONAL EXPRESSIONS

A conditional expression causes the object program to select between
alternate paths (called the true and false paths) of control depending
upon the truth value of a test. Conditional expressions can be used
in conditional
(IF)
statements and in PERFORM statements (options 3
and 4). A conditional expression can be one of the following types:
Relation condition
Class condition
Condition-name condition
Switch-status condition
Sign condition

(greater than, equal to, less than)
(numeric or alphabetic)
(level-SS conaition-names)
(SPECIAL-NAMES paragraph)
(positive, negative, zero)

Each of these types is discussed below.

5.5.1

Relation Condition

A relation condition causes a comparison of two operands, each of
which can be an identifier, a literal, a figurative constant, or an
arithmetic expression.
Comparison of two numeric
operands
is
permitted regardless of their formats as described by their respective
USAGE clauses. Comparison of two operands is permitted if each is
DISPLAY-6, DISPLAY-7, or DISPLAy-g.

5-7

THE PROCEDURE DIVISION
A numeric-edited operand can not be compared to a numeric operand. An
alphanumeric operand can not be compared to a numeric operand unless
the alphanumeric operand contains no characters other than numeric
digits. For example, the statement:
IF NUH < "2".
is permissible but the statement:
IF NUM < "2.0".
is not.

5.5.1.1 Format of a Relation-Condition - The
relation condition is
identifier-l
li~eral-~

.
arlthmetlc-expresslon-l
figurative-constant-l

relational-o erator
p

general

identifier-2
li~eral-~

.
arlthmetlc-expresslon-2
figurative-constant-2

format

for

}

MR-S-1037-81

The first operand is called the subject of the condition; the second
operand is called the object of the condition. Either the subject or
the object must be an identifier or an arithmetic expression.

5.5.1.2 Relational Operators - Relational operators specify the type
of comparison to be made in the relation condition. Relational
operators must be preceded by a space and followed by a space.
Relational Operator

Meaning

IS [NOT] GREATER THAN
IS [NOT] > THAN

Greater than, not greater than

IS [NOT] LESS THAN
IS [NOT] < THAN

Less than, not less than

IS [NOT] EQUAL (EQUALS) TO
IS [NOT] = TO

Equal to, not equal to

5.5.1.3 Comparison of Numeric Items - A
comparison
between
two
numeric items determines that the algebraic value of one item is less
than, equal to, or greater than the algebraic value of the other item.
The length of the operands is not significant. Zero is considered a
unique value; +0 and -0 are equal. Unsigned operands are considered
positive. Blanks and tabs are ignored when a numeric item is compared
to zero. Since blanks and tabs make an item alphanumeric, a true zero
condition can be established by an alphanumeric test followed by a
comparison with zero.

5-8

THE PROCEDURE DIVISION
5.5.1.4 Comparison of Alphanumeric Items - For
operands
whose
category is alphanumeric (or where one operand is numeric and the
other is alphanumeric), a comparison results in the determination that
one of the operands is less than, equal to, or greater than the other
operand with respect to a specified collating sequence of characters
(see Appendix B).
The size of an operand is the total number of
characters in the operand. Blanks and tabs are not ignored when an
alphanumeric item is compared to ZERO. The presence of either blanks,
tabs, or both in the operand causes the test result to be NOT EQUAL.
There are three cases to consider: operands of equal length, operands
of unequal length, and operands with differing justification.
1.

Operands of equal length - If the operands are of equal
length, characters in corresponding character positions of
the two operands are compared, starting at the higher-order
(leftmost) end and continuing through the low-order end. If
all pairs of characters compare equally through the last
pair, 'the operands are considered to be equal. If they do
not all compare equally, the first pair of unequal characters
encountered is compared to determine their relative position
in the collating sequence.
The operand containing the
character that is positioned higher in the collating sequence
is considered to be the greater operand.

Operands of unequal length - If the operands are of unequal
length, the comparison of characters proceeds from the
high-order end to the low-order end until either
a.

A pair of unequal characters is encountered, or

One of the operands has no more characters to compare.

encountered,
If a pair of unequal characters is
comparison
is
determined in the manner described
equal-sized operands.

the
for

If the end of one of the operands is encountered before
unequal characters are encountered, this shorter operand is
considered to be less than the longer operand unless the
remaining characters in the longer operand are spaces, in
which case the two operands are considered equal.
3.

5.5.2

If one operand is right-justified and
the
other
is
left-justified, they are compared just as they appear in the
record. That is, PICTURE XXX, VALUE IIBII and PICTURE XXX,
VALUE IIBII, JUSTIFIED RIGHT are not equal because the first
appears in the record as B
and the second as
B.

Class Condition

The class condition tests the contents of an
alphabetic or wholly numeric.

5-9

item

for

being' wholly

THE PROCEDURE DIVISION
5.5.2.1

Format of a Class Condition -

i denti fi er

IS [NOT] { ALPHABETI C}
NUMERIC
MR·S·1038·81

5.5.2.2 Restrictions - The item named
by
identifier
must
be
described, implicitly or explicitly, as DISPLAY, DISPLAY-6, DISPLAY-7,
or DISPLAY-9. The NUMERIC test cannot be applied to an item described
as alphabetic.
The ALPHABETIC test cannot be applied to an item
described as numeric. A compiler diagnostic results if either of the
two previousl~ mentioned tests are attempted.

5.5.2.3 The ALPHABETIC Test - The ALPHABETIC test result is TRUE when
the item consists of characters from the alphabet (A through Z) and
the space or tab.

5.5.2.4 The NUMERIC Test - The NUMERIC test result is TRUE under
following conditions:

th~

For alphanumeric and unsigned numeric items, each character
must be a digit (0 through 9). No signs are permitted.
Spaces and tabs cause the test result to be FALSE.

For signed numeric items, the sign can have only one of the
three following representations: a leading graphic sign ("+"
or "_"), a trailing graphic sign, or a trailing embedded
sign.
All other characters must be digits. Spaces or tabs
cause the test result to be FALSE.
NOTE
An alternative form of NUMERIC test can
be selected by a switch setting during
system
installation,
which
causes
leading and trailing blanks and tabs to
be ignored. This alternative form is
described in Appendix D.

5.5.3

Condition-Name Condition

In a condition-name condition, a conditional variable is tested to
determine whether or not its value is equal to one of the values
associated with a condition-name (level-88).

5.5.3.1 Format of a Condition-Name - The
condition-name is

general

format

for

[NQT] condition-name

If the condition-name is associated with a range of values, then the
conditional variable is tested to determine whether or not its value
5-10

THE PROCEDURE DIVISION
falls within this range, including the end values.
The rules for comparing a conditional variable with a condition-name
value are the same as those specified for relation conditions.
The result of the test is true if one of the values associated with
the condition-name equals the value of its associated conditional
variable.

5.5.4

Switch-status Condition

A switch-status condition
hardware switch.

determines

the

off

status

5.5.4.1 Format of a Switch-Status Condition - The general formats for
a switch-status condition are

Format 1:
[NOT]

condition-name

Format 2:
mnemoni c-name

[NOT] {~~F }

Format 3:
SWITCH (integer) IS

[NOT] {~~F }
MR-S-1039-81

In format 1, condition-name is associated with a SWITCH IS ON or OFF
STATUS clause in the SPECIAL-NAMES paragraph of the ENVIRONMENT
DIVISION.
In format 2, mnemonic-name is associated with a SWITCH (not an ON or
OFF
STATUS)
in the SPECIAL-NAMES paragraph of the ENVIRONMENT
DIVISION.
In format 3, integer must be in the range from 0 through 35.
In format 1, the result of the test is true if the switch is [NOT) set
to the position associated with the condition-name.
In formats 2 and 3, the result of the test is true if
[NOT] set to the position specified in the condition.

switch

The sign condition determines whether or not the algebraic value of
numeric operand is less than, greater than, or equal to zero.

5.5.5

the

Sign Condition

5-11

THE PROCEDURE DIVISION
5.5.5.1 Format of a Sign Condition - The general format
condition is:

identifier
} IS
{ arithmetic-expression

for

sign

POSITIVE}

[HQI] { NEGATIVE

z.E.EQ
MR·S·1040-81

The POSITIVE
test
result
is
TRUE
if
the
identifier
or
arithmetic-expression
is
algebraically greater than zero.
The
NEGATIVE
test
result
is
TRUE
if
the
identifier
or
arithmetic-expression is algebraically less than zero. The ZERO test
result is TRUE if the identifier or arithmetic-expression is equal to
zero or contains all spaces, all tabs, or a combination of spaces and
tabs. However, any spaces or tabs makes an item alphanumeric.

5.5.6

Logical Operators

The interpretation of any of the above conditions is reversed by
preceding the condition with the logical operator NOT. Any of the
above types of conditions can be combined by either of two logical
operators.
A logical operator must be preceded by a space and
followed by a space.

5.5.7

Logical Operator

Meaning

Entire condition is true if either
or both of the simple conditions
are true.

AND

Entire condition is true if both of
the simple conditions are true.

Formation and Evaluation Rules

A conditional expression can be composed of either a simple-condition
or a compound-condition.
A simple-condition is one that performs a
single test. A compound-condition is one that contains a string of
simple-conditions connected by the logical operators AND, OR. A
compound-condition can contain any combination of types of conditional
expressions (relational, class, condition-name, switch-status, and
sign) •
The evaluation rules for conditions are analogous to those given for
arithmetic expressions, except that the following hierarchy applies:
arithmetic-expressions
all relational operators
NOT
AND
OR
Parentheses can be used either to improve readability or to override
the hierarchy given above. Each set of conditions within a pair of
parentheses is reduced to a single condition.
When
this
is
accomplished, reductions which cross parentheses are done.

5-12

THE PROCEDURE DIVISION
You can use" parentheses in arithmetic expressions to specify the order
in which elements are to be evaluated. Expressions within parentheses
are evaluated first; within nested parentheses, evaluation proceeds
from the least inclusive set to the most inclusive set. In the
absence of parentheses or when parenthesized expressions are at the
same level of inclusiveness, the following hierarchical order of
execution is implied:
1st 2nd 3rd 4th -

Unary plus and minus
Exponentiation
Multiplication and division
Addition and subtraction
NOTE
The precedence of unary minus
over
exponentiation
is
different
from
algebraic notation, and from some other
programming
languages.
If
the
data-names A and B have the values 3 and
2 respectively, then the COBOL statement
COMPUTE C = - A ** B
yields C as 9 (not -9 as in algebra).

Examples:
1.

Using parentheses for ease of reading.
The following expression
A = B OR C > D AND F < G AND H IS
NEGATIVE
can be parenthesized for
effect as shown below:

readability

ALPHABETIC
without

changing

(A = B) OR (C > D AND F < G AND H IS ALPHABETIC)
IS NEGATIVE)

IS
its
(I

If all the conditions within any of the three sets of
parentheses are true, then the entire conditional expression
is true.
The diagram below illustrates the effect
and the order of evaluation.

5-13

this

statement

THE PROCEDURE DIVISION

; > - - - - - - - - - - - - - - - - - - - - - 1 " ' 1 ~~~~

True

Using parentheses to override normal order of evaluation.

To illustrate this usage, a compound-conditional is shown in three
forms, each accompanied by a flow diagram showing the result of each.
Fl = F2 AND F3 = F4 OR F5 = F6 AND F7 = Fa

5-14

THE PROCEDURE DIVISION
F1 = F2 AND (F3 = F4 OR F5 = F6 AND F7 = FB)

> - - - - - - - - r - - - - - - - - - , - - , . . r False
Path

False

True

F1=F2 AND ((F3 = F4 OR F5 = F6) AND F7 = FB)

~----------__.______.__+f ~:~~e

False

MR·S·1043·B1

5.5.8

Abbreviations in Relation Conditions

When· a string of consecutive relation conditions appears in a
statement, abbreviations can be used, in certain cases, for any
relation condition other than the first. The subject, or the subject
and relational operator, or the subject, relational operator and
logical connective can be omitted. In each of these cases, the effect
of the abbreviated relation condition is as if the omitted parts were
the same as those in the nearest preceding complete relation condition
within the same sentence. There are two valid forms of abbreviation.
1.

Abbreviation 1
If the subject is identical in a series of
conditions,
it
can be omitted in all the
conditions except the first.
Example: A = B OR A < C AND A = D OR A = E
can be abbreviated to
A = B OR < C AND = D OR = E

5-15

relational
relational

THE PROCEDURE DIVISION
2.

5.6

Abbreviation 2
If subjects and relational operators are identical in a
series of relational conditions, they can be omitted in all
the relational conditions except the first.
Example: A = B OR A = C AND A = D OR A = E
can be abbreviated to
A = B OR C AND D OR E

COMMON OPTIONS ASSOCIATED WITH THE ARITHMETIC VERBS

Associated with the five arithmetic verbs (ADD, COMPUTE, DIVIDE,
MULTIPLY, and SUBTRACT) are two options: the ROUNDED option, and the
ON SIZE ERROR option. These two options are described here to avoid
the necessity of including their descriptions with each of the
arithmetic verbs.
If the ROUNDED option is specified, the absolute value of the item is
increased by 1 if the leftmost truncated digit is greater than or
equal to 5.
Example:

value:
resultant-identifier picture:
stored result without
ROUNDED option:
stored result with
ROUNDED option:

567.8756
999V~9

567.87
567.88

When the low-order positions in a resultant-identifier are represented
by
the
symbol
P
in
the
PICTURE
associated
with
the
resultant-identifier, rounding or truncation occurs relative to the
rightmost integer position for which storage is allocated.
Example:

5.6.1

value:
resultant-identifier picture:
stored result without
ROUNDED option:
stored result with
ROUNDED option:

5388
99PP

53
54

The ON SIZE ERROR Option

If, after decimal point alignment, the number of significant digits in
the result of an arithmetic operation is greater than the number of
integer positions provided in the result-identifier, a size error
condition occurs.
Division by zero always causes a size error
condition. The size error condition applies to both the intermediate
results and the final result of an arithmetic operation. If the
ROUNDED option is specified, rounding takes place before checking for
size error. When such a size error does occur, the subsequent action
depends upon whether or not the ON SIZE ERROR option is specified.
If the ON SIZE ERROR is not specified and a size error condition
occurs, the value of the resultant-identifier is unpredictable, and no
additional action is taken.

5-16

THE PROCEDU~E DIVISION
If ON SIZE ERROR is specified, and a size error condition occurs, then
the values of the resultant-identifier(s) affected by the size errors
are not altered. Values for resultant-identifier(s) for which no size
error condition occurs are unaffected by size errors that occur for
other resultant-identifier(s). After completion of the execution of
the arithmetic operation, the statement(s) after ON SIZE ERROR is
executed.
Example:

5.7

ADD A TO B ON SIZE ERROR GO TO OVERFLW
A:
954
PICTURE IS 999; VALUE 954.
B:
Result:
The contents of B are left unchanged and
control is transferred to the paragraph
or section named OVERFLW

THE CORRESPONDING OPTION

The CORRESPONDING option is
arithmetic verbs (ADD and
verb.

used in the formats of two of the
SUBTRACT) and in the format of the MOVE

For the purpose of this discussion, d(l)
and
d(2)
represent
identifiers that refer to group items. A pair of data items, one from
d(l) and one from d(2), correspond if the following conditions exist:
1.

All possible qualifiers for d(l)
up to but not including
d(l), must be identical to all possible qualifiers for d(2),
up to but not including d(2).

Both of the data items are elementary numeric data
the
case
of
an ADD or SUBTRACT statement
CORRESPONDING option.

Neither d(l) nor d(2) can be data items with level-number 66,
77, or 88.

Each data item subordinate to d(l) or d(2)
that contains a
RENAMES,
a REDEFINES or an OCCURS clause is ignored.
However, d(l) and d(2) can have REDEFINES or OCCURS clauses
or be subordinate to data items with REDEFINES or OCCURS
clauses.

items in
with the

See ADD, MOVE, and SUBTRACT;
Sections 5.9.2, 5.9.23, and 5.9.39
respectively for information on the specific formats and results of
the use of the CORRESPONDING option.

5.8

DETERMINATION OF USAGE IN ARITHMETIC COMPUTATIONS
\

If a programmer describes a numeric field as having USAGE DISPLAY-6,
DISPLAY-7, DISPLAY-9, or COMP-3, the compiler converts this data to
fixed-point binary when performing arithmetic computations with it.
If the field contains 10 or fewer digits, it is converted to
single-precision fixed-point binary. Conversion to double-precision
fixed-point binary is performed if the field contains more than 10
digits. A field described as COMPUTATIONAL (or INDEX) is fixed-point
binary; single-precision for 10 or fewer digits, double-precision for
more than 10 digits. A field described as COMPUTATIONAL-l is single
precision floating-point binary.

5-17

THE PROCEDURE DIVISION
When any arithmetic computation is performed, the arithmetic usage
(single-precision
fixed-point,
double-precision
fixed-point, or
floating-point) used for each operation is determined from the usages
of the two operands of the computation.
If either operand is
floating-point, the operation
is
performed
in
floating-point
arithmetic.
If neither operand is floating-point, but one operand is
double-precision fixed-point,
the
operation
is
performed
in
double-precision fixed-point arithmetic. Otherwise, the operation is
performed in single-precision fixed-point arithmetic.
If
both
operands are constants, the operation is performed in single- or
double-precision fixed-point arithmetic, as appropriate.
On KL or KS hardware, ADD, SUBTRACT, MULTIPLY, or DIVIDE is done in
four-word fixed point arithmetic, if the size of the intermediate
result exceeds 18 digits.
In the COMPUTE verb, double-precision
floating-point arithmetic is used if division or exponentiation is
performed or if the intermediate result exceeds 18 digits.
If any alphanumeric characters appear in the DISPLAY-6, DISPLAY-7, or
DISPLAY-9 field that is to be converted, the compiler attempts to
convert them to binary; however, in many cases, undefined results can
occur.
When DISPLAY-6, DISPLAY-7, and DISPLAY-9 characters are
converted to binary, the following rules apply.

o through 9

are converted to 0 through 9.

A through I

are converted to 1 through 9.

? , [ ,{

are converted to

through R

are converted to 1 through 9, and the field
is made negative if it is found in the
low-order digit, unless an explicit sign is
present.

:,!,],}

are converted to 0, and the field is made
negative if it is found in the low-order
digit unless an explicit sign is present.

Nulls

are ignored.

Leading spaces
and tabs

are ignored.

+ and -

are treated as sign characters.

Scanning of a field proceeds from left to right, it stops when one
the following conditions is met:
1.

The entire field has been scanned.

A trailing space, tab, plus, or minus is seen.

If both leading and trailing signs appear in the field,
sign is ignored.

5-18

the

trailing

THE PROCEDURE DIVISION
5.9

PROCEDURE DIVISION VERB FORMATS

The format of each PROCEDURE DIVISION verb is given on
pages. The verbs are presented in alphabetical order.

the

following

The word "identifier" is a data-name followed,
as required, by
qualification, subscripts, and/or indexes necessary to make
data-name unique.

5-19

any
the

THE PROtEDURE DIVISION

ACCEPT
5.9.1

Function
Option 1 of the ACCEPT statement causes low-volume
from the terminal.

data

read

Option 2 of the ACCEPT statement causes the MESSAGE COUNT field to be
updated to include the number of messages in a queue or sub-queue
maintained by MCS-IO, DIGITAL'S Message Control System for TOPS-IO.
General Format

Option 1.
ACCEPT

identifier-l

[, i dent; fi er-2]

[FROM mnemonic-name]

Option 2.
ACCEPT

cd-name

MESSAGE Cill.lli.l

MR-S-1044-81

Technical Notes
1.

The ACCEPT statement causes the next set of data available
from the terminal to replace the contents of the items named
by identifier-I, identifier-2, . . • .

If the FROM
appear
in
paragraph.

When the data to be read for one or more ACCEPT statements is
numeric, a comma (,), space, or tab is used as a delimiter
separating the data items.

When the data to be read for one or more ACCEPT statements is
alphanumeric, each data item is delimited by a line-feed,
altmode, form-feed, or vertical tab.

The ACCEPT statement reads from left to right a maximum of
1023 characters into each identifier. If the identifier is
1023 or less characters in size, then depending upon how many
characters are input from the terminal, the following occurs:

option is specified, the mnemonic-name must
the CONSOLE IS clause of the SPECIAL-NAMES

Less than the identifier
the identifier
justified and the rest is filled with spaces.

Exactly the size of the identifier - the
filled.

More than the identifier
the identifier
justified and the rest is truncated.

5-20

identifier
is

left
is
left

THE PROCEDURE DIVISION

ACCEPT (Cont.)
If the identifier is greater than 1023 characters in size,
then the above holds true for the first 1023 characters of
the identifier. The remaining characters of the identifier
are not changed, no mattei how many characters are typed on
the terminal.
6.

Upon execution of the ACCEPT MESSAGE COUNT statement, the
contents of the area specified by a communication description
entry must contain at least the name of the symbolic queue to
be tested. Testing the condition causes the contents of the
data items replaced by data-name-ID (status
key)
and
data-name-2 (MESSAGE COUNT) of the areas associated with the
communications entry to be appropriately updated.

5-21

THE PROCEDURE DIVISION

ADD
5.9.2

ADD

Function
The ADD statement computes the sum of two more
stores the result.

numeric

operands

and

General Format
Option 1:

ADD

identifier-1 }
{ 1itera 1-1

identifier-2 }]
[ , { 1iteral-2

[ • i dent ifi er-n

[ROUNDED] ]

[ON

SIZE

ERROR

statement-l

identifier-m

[, s tatement-2 ] ...

[ROUNDED]

Option 2:

ADD

identifier-I}
{ 1itera1-1

identifier-2 }
{ 1iteral-2

GIVING

[ROUNDED] [ • identifier-n

[ON

identifier-m

SIZE

ERROR

identifier-3 }]
{ 1 i tera 1- 3

...

[ROUNDED] ]

statement-l

[,statement-2 ] ...

identifier-l

~ ]

Option 3:

ADD

CORRESPONDING
{ CORR

[ ROUNDED ] [ON

SIZE

ERROR

identifier-2

s tatement-l

[, s tatement- 2 ] ...

~ ]

MR-S-1045-B1

5-22

THE PROCEDURE DIVISION

ADD (Cont.)
Technical Notes
1.

Each ADD statement must contain at least two operands (that
is, an addend and an augend).
In options 1 and 2, each
identifier must refer to an elementary numeric item, except
that identifiers appearing to the right of the word GIVING
can refer to numeric edited items.
In option 3, each
identifier must refer to a group item.
Each literal must be a numeric
constant ZERO is permitted.

literal;

the

figurative

The composite of all opera"nds (i.e., the data item resulting
from the superimposition of all operands aligned by decimal
point) must not contain more than 19 decimal digits for the
non-BIS
compiler
and not more than 36 digits for a
BIS-compiler. In either case, a maximum of 18 digits can be
stored in the receiving field.
NOTE
The BIS-compiler is standard on the DECSYSTEM-20 and
DECsystem-lO.
For KI based hardware, the non-BIS
compiler is optional on the DECsystem-lO.
(See the
COBOL-68 Installation Procedures.)

Option 1 causes the values of the operands preceding the word
TO to be algebraically summed. The resultant sum is then
added to the current value of identifier-m and this result
replaces
the current value in identifier-me
If other
identifiers follow, the same process is repeated for each of
them.

Option 2 causes the values of the operands preceding the word
GIVING to be algebraically summed. The resultant sum then
replaces the current contents of identifier-me
If other
identifiers follow, their contents are also replaced by this
resultant sum.
The
current
values
of
identifier-m,
identifier-n,...
do
not
enter
into
the arithmetic
computation.

Option 3 causes the data items in the group item associated
with identifier-l to be added to the current value of the
corresponding data items associated with identifier-2, and
each
result
replaces
the value of the corresponding
data-items associated with identifier-2. The criteria used
to
determine
whether two items are corresponding are
described in Section 5.7, The CORRESPONDING Option.

The ROUNDED and ON SIZE ERROR options are described in
Section 5.6 Common Options Associated with Arithmetic Verbs.

5-23

THE PROCEDURE DIVISION

ALTER
5.9.3

ALTER

Function
The ALTER statement
statements.

changes

the

object

one

General Format

ALTER procedure-name-l TO PROCEED TO procedure-name-2
[,procedure-name-3 TO PROCEED TO procedure-name-l]
MR-S-1046-81

Technical Notes
1.

During execution of the object program, the ALTER statement
modifies
the
GO TO statement in the paragraph named
procedure-name-l, procedure-name-3, ... replacing the object
of the GO TO by procedure-name-2, procedure-name-4, •.. ,
respectively.

Each procedure-name-l, procedure-name-3, .... must be the name
of a paragraph that contains only a single GO TO statement
without the DEPENDING option.

Each procedure-name-2, procedure-name-4, ... must be the name
of a paragraph or section within the PROCEDURE DIVISION.

A GO TO statement in a section whose priority is greater than
or equal to 50 must not be referred to by an ALTER statement
in a section with a different priority.

An ALTER statement in a procedure not in the DECLARATIVES
portion of the program can not reference a procedure name
within the DECLARATIVESi
conversely,
an ALTER statement
within the DECLARATIVES can not reference a procedure-name
not in the DECLARATIVES.

Restrictions similar to those in Note 5 also apply to the
INPUT PROCEDUREs and to the OUTPUT PROCEDUREs associated with
SORT and MERGE verbs.

For program segments with priorities of 50 and greater,
the
changes made by ALTER statements are lost when segments are
overlaid.

5-24

THE PROCEDURE DIVISION

CALL
5.9.4

CALL

Function
The CALL statement is used

transfer control to a subprogram.

General Format

CALL {program-name} [USING
entry-name

identifier-l

, identifier-2

... ]

[ON OVERFLOW imperative-statement-l] ~
MR-S-1047-81

Technical Notes
1.

Program-name is a l-to-6 character name (PROGRAM-ID) of the
subprogram to be called. Errtry-name is a l-to-6 character
name of an entry point in the subprogram. Either name can be
enclosed in quotation marks, but can contain only letters and
digits.

If the program-name is used, the entry point is
beginriing of the executable code in the subprogram.

Called programs can call other subprograms, but a called
program cannot call, either directly or indirectly, any part
of itself or the program that called it.

The number of operands in the USING clause of the CALL
statement must be greater than or equal to the number of
operands in the ENTRY statement or PROCEDURE DIVISION header
in the subprogram.

Each of the operands in the USING clause can be any item
defined in the FILE, WORKING-STORAGE, or LINKAGE SECTION of
the calling program.
However,
these
items
must
be
word-aligned;
that is, they must begin on a word boundary.
01- and 77-level items are always word-aligned.
Any other
item can be word-aligned by means of the SYNCHRONIZED LEFT
clause.

The identifiers in the USING clause indicate those data items
in the calling program that can be referenced (or whose
subordinate parts can be referenced) in the called program.
The order of the identifiers in the CALL statement in the
calling program and in the PROCEDURE DIVISION header or ENTRY
statement of the calling program is critical. The items in
the USING clause are related
by
their
corresponding
positions, not by name. Cor~esponding identifiers refer to a
single set of data that is available to both the calling and
called programs.

5-25

the

THE PROCEDURE DIVISION

CALL (Cont.)
7.

The first time a called program is entered, its state is that
of a fresh copy. Subsequently, if the subprogram is not in a
LINK overlay, its state when entered is exactly as it was
left after the last exit from it. That is, all internal
variables, altered GO TO's, and the like are exactly as they
were left.
However, external data (that is, data described
in the LINKAGE SECTION) may have been changed since the last
exit.
If the subprogram is in a LINK overlay and it is entered
again, its state is exactly as it was left after the last
exit from it provided that the subprogram has not been
cancelled by you or overlaid. If the subprogram has been
cancelled or overlaid, its state is that of a fresh copy.

The ON OVERFLOW condition cannot happen if it is encountered
within the CALL statement. It is merely shown here for ANSI
compatability. If ON OVERFLOW is used, it is ignored and
your CALL statement exits normally.

Refer to Chapter 11 of this manual for
subprograms.

5-26

information

THE PROCEDURE DIVISION

CANCEL
5.9.5

CANCEL

Function
The CANCEL statement causes a subprogram to be logically disassociated
from the main program and,' if possible, causes the return of the
memory used by the subprogram to the system.
General Format
CANCEL subprogram-l [,subprogram-2]
Technical Notes
1.

The CANCEL statement can only be used to cancel a subprogram
that has been loaded into an overlay link by LINK. Refer to
Chapter 11 of this manual for information on specifying LINK
overlays and on subprograms.

After a subprogram has been cancelled, a subsequent call
the subprogram caus'es a freshly-initialized copy to
brought into memory.

Cancellation of a subprogram causes the entire link in
it resides and all lower level -links to be cancelled.

A subprogram in the root link or higher in the current
overlay structure cannot be cancelled. If an attempt is made
to do so, the CANCEL statement is ignored and a warning
message issued at runtime.

A subprogram cannot cancel itself or any subprogram that
resides in an overlay link with it. An attempt to do either
results in the CANCEL statement being ignored and a warning
message issued at runtime.

Cancellation of a subprogram higher in the current calling
sequence
is
also an illegal operation.
But, if the
subprogram being cancelled is in a lower-level link and
higher in the calling sequence, it could be cancelled without
being detected as an error. This would cause the return from
the program to be an undefined location.

Example
CANCEL SUBA,SUBC.

5-27

to
be

which

THE PROCEDURE DIVISION

CLOSE
5.9.6

Function
The CLOSE statement terminates the
files, reels, or units.

processing

input

and

output

General Format

NO REWIND}]
CLOSE file-name [{~~~~}J WITH { LOCK
DELETE

[. file-name-l [{ ~m }] [WITH {~:;IND}]]
MR-S-1048-81

Technical Notes
1.

Each filename must appear as the subject of an
the FILE SECTION of the DATA DIVISION.

entry

The REEL, UNIT, and NO REWIND options apply only to
tape files.
UNIT is synonymous with REEL.

The DELETE option applies only to disk and DEC tape files.
If
this option is included, the file is deleted from the device.

For the purpose of showing the effect of various CLOSE
options as applied to the various storage media, all input,
output, and input-output files are divided into the following
three mutually exclusive categories:

magnetic

a. NON-REEL

A file whose device is such that the concepts
of REWIND, REEL, or UNIT have no meaning.
This category includes files residing on
disk,
punched
cards,
paper tape,
line
printer, and terminal.

b. SINGLE REEL

A file that is entirely contained on one reel
or unit.

c. MULTI-REEL

A file that can be contained on more than one
reel or unit.

The results of each CLOSE option for each of the above types
of files are summarized in Table 5-3. The definitions for
the s¥mbols used in this table are given below.
Where the
defin1tion depends upon whether the file
is an input or
output file, alternate definitions are given; otherwise, the
single definition given applies to both input and output
files.

5-28

THE PROCEPURE DIVISION

CLOSE (Cont.)
Codes Qsed in Table 5-3
A = Any subsequent reels of this file are not processed.
B

The current reel is not rewound.

Standard CLOSE File

P~ocedure

INPUT and 1-0 Files (see "OPEN")
If the file is positioned at its end, your ENDING FILE
LABEL PROCEDUREs are performed, if you have specified
any by a USE statement. An input file is considered to
be at the end-of-file if the imperative-statement in the
AT END clause of a READ for the file has been executed,
and no CLOSE statement for the file has been executed.
OUTPUT Files
If LABEL RECORDS are STANDARD, an ending label is
created and written on the output medium. Then, your
ENDING FILE LABEL PROCEDUREs are performed.
D

The current reel is rewound and unloaded.
If you are using TOPS-20, the tape drive must be made
unavailable to MOUNTR and ASSIGNed to your job in order
for the reel to be unloaded.

Any attempt to subsequently OPEN this file results in an
error message being typed and the run terminated.

F = Standard CLOSE REEL Procedure
INPUT Files
1.

If the file is assigned to more than one device, the
next device specified in the ASSIGN clause becomes
the current device.
If no
other
device
is
specified, the first device mentioned becomes the
current device.

The standard beginning reel label procedure and your
BEGINNING REEL LABEL PROCEDURE (specified in a USE
statement) are performed for the new reel.

OUTPUT and, 1-0 Files

The standard ending reel label procedure and
ENDING REEL LABEL PROCEDURE are performed.

If the file is assigned to more than one device, the
devices are swapped. A halt occurs to allow you to
mount an available reel.

The standard beg~nning reel label procedure and your
BEGINNING REEL LABEL PROCEDURE (specified in a USE
statement) are performed.

The tape is rewound.
5-29

your

THE PROCEDURE DIVISION

CLOSE (Cont.)
Codes Used in Table 5-3
H

The file is deleted from the device.
However,
if the
file
is a sequential file on disk that is open for
output in supersede mode,
the original file
remains
intact (that is, the original file is not superseded nor
deleted) .

Illegal.
This is an illegal
option and a file type.

combination

If the file has been specified with an OPTIONAL clause in the
FILE-CONTROL paragraph of the ENVIRONMENT DIVISION and the
file was not present for this run, the CLOSE has no effect.

If a CLOSE statement without the REEL or UNIT option has been
executed for
a
file, a READ, WRITE, or CLOSE statement for
that file must not be executed until another OPEN for
that
file has been executed.

SINGLE
REEL/UNIT

t-lUL'rI - REEL

C,G

C,G,A

CLOSE
WITH LOCK

C,E

C,G,E

C,G,E,A

CLOSE WITH
NO REWIND

C,B

C,B,A

0-1
0

CLOSE REEL

F,G

CLOSE REEL
WITH LOCK

F,D

CLOSE REEL
WI'rH NO
REWIND

F,B

CLOSE WITH
DELETE

CfH

•.-1

RUN
Any
are

NON-REEL

If a file is OPENed but not CLOSEd before the STOP
statement is executed, the file is automatically CLOSEd.
records still
retained
by
a
RETAIN
statement
automatically freed by a CLOSE statement.

File Type

Table 5-3
CLOSE Options and File Types

s::

5-30

THE PROCEDURE DIVISION

COMPUTE
5.9.7

COMPUTE

Function
The COMPUTE statement assigns to a data item the value
data item, literal, or arithmetic expression.

numeric

General Format

EQUALS } {identifier-2
}
COMPUTE identifier-l [ROUNDED] { EQUAL TO li~eral-~
.
=
arlthmetlc-expresslon
[ON SIZE ERROR [statement-l

,statement-2]

... ~J
MR-S-1049-81

Technical Notes
1.

The COMPUTE statement allows you to combine arithmetic
operations without the restrictions on the composite of
operands and/or receiving data items
imposed
by
the
arithmetic statements ADD, SUBTRACT, MULTIPLY, and DIVIDE.
Division
and
exponentiation
are
always
done
using
double-precision
floating-point internal representations.
This can cause problems for you if your result has seventeen
or eighteen digits of precision; your answers could be low
by a very small amount. If this is causing a problem for
you, you should use the ROUNDED option.
Exponentiation
statement.

can

only

done

using

COMPUTE

the

Identifier-l must be an elementary numeric or numeric
item.

Identifier-2 must be an elementary numeric
must be a numeric literal.

item.

edited

Literal-2

The identifier-2 and literal-l options provide a method for
setting the value of identifier-l equal to identifier-2 or
literal-I.
4.

The rules for forming arithmetic expressions and the order of
evaluation
are
given
earlier
in this chapter under
"Arithmetic Expressions".

The ROUNDED and SIZE ERROR options are described earlier in
this chapter under "Common Options Associated with the
Arithmetic Verbs".

5-31

THE PROCEDURE DIVISION

DELETE
5.9.8

DELETE

Function
The DELETE statement removes a specified
access mode is INDEXED.

record

from

file

whose

General Format
DELETE record-name INVALID KEY statement-l [, statement-2] ...

Technical Notes
1.

Record-name must be a record associated
access mode is INDEXED.

When the DELETE statement is executed, the record in the file
that has a key equal in value to the SYMBOLIC KEY for the
file is removed from the file. If no such record exists, the
statement(s) associated with the INVALID KEY clause is
executed.

At the time that the DELETE statement is executed,
must be open for OUTPUT or INPUT-OUTPUT.

5-32

with

file

the

whose

file

THE PROCEDURE DIVISION

DISPLAY
5.9.9

DISPLAY

Function
The DISPLAY statement causes low-volume data to
terminal.

written

your

General Format

DISPLAY

{~iter~l:l
} [{literal-2
}]
ldentlfler-l
identifier-2
...
t

[UPON mnemonic-name] [WITH NO ADVANCING]
MR·S-1050-81

Technical Notes
1.

The contents of each operand are written on your terminal
the order listed.

Each of the literals can be numeric or alphanumeric, or one
of the figurative constants.
If a figurative constant is
specified as one of the operands, only a single occurrence of
that constant is written on the device.

The mnemonic-name must appear in the CONSOLE clause
SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISION.

If WITH NO ADVANCING is specified, the terminal does not
advance to the next line.
Thus, printing or type-in can
continue on the same line.

If the identifier being displayed is numeric, commas are
inserted automatically from the right. for example, if you
code DISPLAY NUM-ONE and NUM-ONE contains 1234567890, then
this appears on your terminal as 1,234,567,890.

5-33

the

THE PROCEDURE DIVISION

DIVIDE
5.9.10

DIVIDE

Function
The DIVIDE statement divides one numeric item into
the value of a data item equal to the result.

another

and

General Format

Option 1:
DIVIDE {i?entifier-1} INTO identifier-2 [ROUNDED] [REMAINDER identifier-4]
- - llteral-1
[ON SIZE ERROR statement-1 [,statement-2] ... ~]

Option 2:
DIVIDE
BY identifier-1 [ROUNDED] [REMAINDER identifier-4]
- {i?entifier-2}
llteral-2
[ON SIZE ERROR statement-1 [,statement-2] ... ~]

Option 3:
DIVIDE {identifier-1} INTO {identifier-2} GIVING identifier-3
literal-1
- - literal-2
[ROUNDED] [REMAINDER identifier-4]
[ON SIZE ERROR statement-1 [,statement-2] ... ___
.]
MR-S-1051-81

5-34

sets

THE PROCEDURE DIVISION

DIVIDE (Cont.)
Opt ion 4:

DIVIDE {identifier-2} BY {i~entifier-l} GIVING identifier-3
literal-2
llteral-l
[ROUNDED] [REMAINDER identifier-4]
[ON SIZE ERROR statement-l [,statement-2 ] ... ] _
MR·S·1052·81

Technical Notes
1.

The value of identifier-lor literal-l is divided into the
value of identifier-2 or literal-2.
In option 1,
the
resulting quotient replaces the value of identifier-2.
In
option 2,
the resulting quotient replaces the value of
identifier-I.
In options 3 and 4,
the resulting quotient
replaces the value of identifier-3.

Each DIVIDE statement must contain two operands (that is,
a
dividend
and
a
divisor} •
Both
of
these operands
(identifier-l and identifier-2)
must refer
to elementary
numeric items.
Identifier-3 can be an elementary numeric or
numeric edited item.
Each literal-lor literal-2 must be a
numeric literal.
Identifier-4 can be an elementary numeric
or numeric edited item.

The ROUNDED and SIZE ERROR options are described earlier
in
this chapter under "Common Options Associated with Arithmetic
Verbs" .

If the REMAINDER clause is used,
the
replaces the value of identifier-4.

The data item resulting from the divide operation (i.e.,
the
sum of the digits in the dividend and the digits in the
fractional part of the divisor) must not contain more than 20
decimal digits for the non-BIS compiler and not more than 36
digits for the BIS compiler.
In either case, a maximum of 18
digits can be stored in the receiving field.

resulting

remainder

NOTE
The BIS compiler is standard for the DECSYSTEM-20 and
DECsystem-lO.
For KI based hardware, the non-BIS
compiler is optional on the DECsystem-lO.
(See the
COBOL-68 Installation Procedures.)

The remainder is checked for a size error after the quotient
is checked, whether or not the quotient has a size error.
If
either the quotient or the remainder has a size error,
LIBOL
follows
the
procedure described under
"Common Options
Associated with Arithmetic Verbs".

The ROUNDED option does not apply
remainder is always truncated.
5-35

the

remainder;

the

THE PROCEDURE DIVISION

ENTER
5.9.11

ENTER

Function
The ENTER statement allows the execution of MACRO
subroutines in conjunction with the COBOL program.

and

FORTRAN

General Format

MACRO }
ENTER { FORTRAN program-name
COBOL
identifier-l

} [{identifier-2
}]
, literal-2
..
procedure-name-l
procedure-name-2

[USING { literal-l

[ON OVERFLOW imperative-statement-l] ~
MR-S-1053-81

Technical Notes
1.

MACRO refers to MACRO assembly language and FORTRAN refers to
the FORTRAN language.

The program-name can be enclosed in quotation marks.

The ENTER statement generates a subroutine call followed by
the address in which the items associated with the USING
clause are located.
(Refer to Chapter
12
for
more
information on the ENTER statement.)

The ON OVERFLOW condition cannot happen if it is encountered
within the ENTER statement.
It is merely shown here for ANSI
compatability.
If ON OVERFLOW is used,
it is ignored and
your ENTER statement exits normally.

ENTER COBOL is equivalent to CALL.

5-36

THE PROCEDURE DIVISION

ENTRY
5.9.12

ENTRY

Function
The ENTRY statement establishes an entry point in a subprogram.
General Format
ENTRY entry-name [USING identifier-l [,identifier-2] •.. ~
Technical Notes
1.

The ENTRY statement can only be used in a subprogram.

Control is passed to the entry point by a CALL statement in a
calling program.

Entry-name is a I-to-6 character name that can contain only
letters
and digits.
It can, however, be enclosed in
quotation marks. This name must not be the same as any other
entry-name or PROGRAM-ID in any program with which the
subprogram containing it is loaded.

The identifiers listed in the USING clause must be defined as
01or 77-level items in the LINKAGE SECTION of the
subprogram containing the ENTRY statement.

The number of operands in the USING clause of an ENTRY
statement must be less than or equal to the number of
operands in any CALL statement referencing that
ENTRY
statement.

The identifiers in the USING clause indicate those data items
in the called program that can reference data items in the
calling program.
The order of identifiers in the CALL
statement in the calling program and in the ENTRY statement
in the called program is critical. The items in the USING
clauses are related by their corresponding positions, not by
name. Corresponding identifiers refer to a single set of
data that is available to both the calling and called
programs.

At run-time, additional ENTRY statements are ignored unless
there are specific calls made to them. for example, if a
subprogram has three ENTRY statements and a call is made to
the first ENTRY statement, the remaining two ENTRY statements
are ignored.

Refer to Chapter 11 of this manual for
subprograms.

5-37

information

THE PROCEDURE DIVISION

EXAMINE
5.9.13

EXAMINE

Function
The EXAMINE atatement replaces or counts the number of occurrences
a given character in a data item.

General Format

EXAMINE identifier
TALLYING

{t~~DING

} literal-l [REPLACING BY literal-2]

UNTIL FIRST

REPLACING

{~~~DING

} literal-l JrL

literal-2

[UNTIL] FI RST
MR·S·l054·81

Technical Notes
1.

The USAGE of identifier must be DISPLAY-6,
DISPLAY-9, implicitly or explicitly.

DISPLAY-7,

Each literal must consist of a single character belonging to
a class consistent with that of the identifier.
A literal
can be any figurative constant.

Examination starts at the leftmost
identifier and proceeds to the right.

When the TALLYING option is used, a count is kept of:

character

Occurrences of literal-l when the ALL option is used.

Occurrences of literal-l prior to a character other
literal-l when the LEADING option is used.

Characters prior to the first occurrence
when the UNTIL FIRST option is used.

the

than

literal-l

This count replaces the contents of the special register
called TALLY (see "Special Registers", Chapter 1).
TALLY has
a PICTURE of S9(5), and can be referenced
in any statement
where an identifier referring to an elementary numeric data
item is valid.
If the REPLACING BY clause is used with the TALLYING option,
replacement is performed according to the rules below.

5-38

THE PROCEDURE DIVISION

EXAMINE (Cont.)
5.

When either of the REPLACING BY options are used, replacement
rules are
a.

If the ALL option is used, literal-2 is
each occurrence of literal-I.

substituted

for

If the LEADING option is used,
the substitution of
literal-2 for literal-l terminates as soon as a character
other than literal-l is encountered.

If the UNTIL FIRST option is used,
substituted
for each .character prior
occurrence of literal-I.

If the FIRST option is used, literal-2 is substituted for
only the first occurrence of literal-I.

literal-2
is
to the first

If the identifier is classified as numeric, it must consist
solely of numeric characters.
It can possess an operational
sign, but this sign is ignored by the EXAMINE process.

5-39

THE PROCEDURE DIVISION

EXIT
5.9.14

EXIT

Function
The EXIT statement provides a common end point
routines executed by a PERFORM or USE statement.

for

series

Only

NOTE

General Format
paragraph-name.

EXIT.

Technical Notes
1.

EXIT must be the first sentence in a
can follow.

paragraph.

The EXIT statement can be used to provide an end point for
a
series of paragraphs th~t are PERFORMed, or at the end of a
section in the DECLARATIVES.
By using EXIT at the end of the
range of a PERFORM or USE,
a variety of exits from the
performed procedure can be accomplished by making each point
at which an exit is required a transfer to the EXIT
paragraph.
However, unless EXIT is specified as the end of
the range of a PERFORM or USE or is placed as the last
paragraph in the range of a PERFORM or USE, it is ignored.
Example:
PERFORM TAX-ROUTINE THROUGH EXIT-RTE.

TAX-ROUTINE.
IF TOTAL-TAX IS EQUAL TO OR GREATER THAN TAX-LIMIT
GO TO EXIT-RTE.
MULTIPLy .•.•.
DEDUCTION-RTE.
IF NO-OF-DEPENDENTS IS EQUAL TO ZERO
GO TO EXIT-RTE.
MULTIPLY NO-OF-DEPENDENTS BY DEP-DEDUCT ••••

EXIT-RTE. EXIT.
3.

If control reaches an EXIT statement and no associated
PERFORM or USE statement is active or if EXIT is not the last
paragraph in the range of a PERFORM or USE statement even if
the PERFORM or USE statement is active, control passes
through the EXIT paragraph to the first statement of the next
paragraph.

5-40

THE PROCEDURE DIVISION

EXIT PROGRAM
5.9.15

EXIT PROGRAM

Function
The EXIT PROGRAM statement is used to return control from a subprogram
to its calling program.
General Format
EXIT PROGRAM.
Technical Notes
1.

EXIT PROGRAM can only appear in a subprogram.

When an EXIT PROGRAM statement is executed, control is
returned to the calling program at the statement immediately
following the CALL statement.

If an EXIT PROGRAM statement is encountered in a subprogram
that is operating as a main program, it is ignored.

Refer to Chapter 11 of this manual for
subprograms.

5-41

information

THE PROCEDURE DIVISION

FREE
5.9.16

FREE

Function
The FREE statement explicitly frees records that have been retained in
a RETAIN statement.
General Format

fi le-n ame-l

RECORD [KEY
{i?entifier-l}]
llteral-l

IEVERY RECORD

[ I
t

f 1Ol e-n ame- 2

RECORD [KEY
-

{illteral-2
?entifier-2}]

EVERY RECORD

EVERY RECORD
[NOT RETAINED statement-l [, statement-2]

... ] _
MR-S-1055-B1

Technical Notes
1.

Filename-I, filename-2 ...
are the names of files containing
records that have been retained.
Thus, they are files that
have been opened for simultaneous update.

Identifier-I, identifier-2...
and literal-I,
literal-2 .••
specify the value of a key.
This key refers to the record to
be freed in the file.

Statement-I, statement-2 ...

The FREE statement is needed to explicitly free records that
have not been implicitly freed by an I/O statement. This
could occur when the RETAIN statement contains the UNTIL
FREED phrase, when an I/O statement is not issued after the
RETAIN statement, or when the FOR clause of the RETAIN
statement specifies ANY VERB.
Refer to the RETAIN statement
in this chapter for a description of its function and syntax.

The EVERY RECORD phrase is used to free all records
or to free all records retained in a specific file.

5-::42

are any valid COBOL statements.

retained

THE PROCEDURE DIVISION

FREE (Cont.)
6.

The NOT RETAINED phrase.specifies the COBOL statements to be
executed when one or more records to be freed are not
currently retained.
If the NOT RETAINED phrase is not
included and the records to be freed are not currently
retained, the program proceeds and you are not notified of
the possible error.
.

When an EVERY RECORD phrase is used, the statements in the
NOT RETAINED phrase are executed only if no records are
currently retained or only if no records are currently
retained in the specified file.

If the FREE statement includes a file that was not opened for
simultaneous update, the NOT RETAINED statements, if present,
are executed.
Otherwise, the program continues and you are
not notified of the error.

You can mix records from sequential,
random,
sequential files in the same FREE statement.

10.

All records of a file are freed automatically when the file
is closed including those records that were retained with an
UNTIL FREED clause in the RETAIN statement.

11.

The record to be freed, whether or not the KEY phrase is
specified,
depends on the access mode of the file.
Each
access mode is described separately below.
a.

and

indexed

SEQUENTIAL ACCESS FILES
If the KEY phrase is specified, its value refers to the
record with that value in the RETAIN statement.
That is,
a KEY value of 6 in the FREE statement frees
the record
defined with a KEY value 'of 6 in the RETAIN statement.
If the KEY phrase is not specified, the record freed
is
that record defined with a KEY value of 0 in the RETAIN
statement.
The value of a key can be specified by any identifier,
which can be subscripted and/or qualified, provided that
its USAGE is COMPUTATIONAL or INDEX.
The value of the
key can also be specified by a positive integer numeric
literal containing ten or fewer digits.

RANDOM ACCESS FILES
If the KEY phrase is specified, its value refers to the
record with that value in the RETAIN statement.
That is,
a KEY value of 0 in the FREE statement frees
the record
defined with a KEY value of 0 in the RETAIN statement.
If the KEY phrase is not specified, the record freed
that record defined by the ACTUAL KEY of the file.

The value of a key can be specified by any identifier,
which can be subscripted and/or qualified, provided that
its USAGE is COMPUTATIONAL or INDEX.
The value of a
key
can also be specified by a positive integer numeric
literal containing ten or fewer digits.
5-43

THE PROCEDURE DIVISION

FREE (Cont.)
c.

INDEXED SEQUENTIAL FILES
If the KEY phrase is specified, its value refers to the
record with that value in the RETAIN statement.
That is,
a key identified with a value of
"ABC"
in the FREE
statement frees the record
identified as "ABC" in the
RETAIN statement.
If LOW-VALUES is used as the value of
the key,
it refers to the next record after the current
record, which is not necessarily the record identified by
LOW-VALUES in the RETAIN statement.
This is because the
current record
is changed by an I/O statement and
LOW-VALUES always refers to the record following the
current record.
The value specified in the KEY phrase must normally be an
identifier
that specifies a field that agrees with the
RECORD KEY defined for the file in size,
class,
usage,
and number of decimal places.
However, if the RECORD KEY
of the file is USAGE COMPUTATIONAL or INDEX,
a positive
integer numeric literal of ten or fewer digits can be
used as the value in the KEY phrase.
If the KEY phrase is not specified, the record freed
is
that record defined by the SYMBOLIC KEY of the file.
If
the SYMBOLIC KEY contains LOW-VALUES, it refers to the
next record after
the .current record, which
is not
necessarily the record specified by LOW-VALUES in the
RETAIN statement. This is because the current record is
changed by an I/O statement and LOW-VALUES refers to the
record following the current record.

Examples
Sequential File
RETAIN HISTORY KEY 0 FOR READ-WRITE UNTIL FREED,
HISTORY KEY 1 FOR READ-WRITE UNTIL FREED,
HISTORY KEY 2 FOR READ-WRITE.
READ HISTORY, AT END STOP RUN.
FREE HISTORY EVERY RECORD.
Random Access File
RETAIN PART KEY 0 FOR ANY VERB.
READ PART, INVALID KEY GO TO ERR.
WRITE PARTREC.
FREE PART KEY O.
Indexed Sequential File
MOVE "B" TO SYMBOLIC-KEY.
RETAIN LETTERS FOR READ.
FREE LETTERS.

5-44

THE PRdcEDURE DIVISION

GENERATE
5.9.17

GENERATE

Function
The GENERATE statement causes the Report-Writer to execute all
automatic report operations,
and,
if required, produce one or more
report groups.
General Format
GENERATE identifier
Technical Notes
1.

If identifier is the name of a TYPE DETAIL report group,
the
GENERATE
statement
performs
all the automatic report
operations, and produces an output detail report group on the
output file.
This is called detailed reporting.

If the identifier is the name of an RD entry,
the GENERATE
statement performs all the automatic report operations, but
do~s not produce an output
detail report group.
This is
called summary reporting.

A GENERATE
operations:

statement

performs

the

following

automatic

Steps and tests the LINE-COUNTER and/or PAGE-COUNTER to
produce,
if necessary, any PAGE FOOTING and PAGE HEADING
report groups.

Recognizes any specified control breaks to
produce
appropriate CONTROL FOOTING and CONTROL HEADING report
groups, and resets appropriate summation counters.

Accumulates into the
identifiers.

Executes any routines defined by a USE statement.

If this is detailed
report group.

summation

reporting,

counters

produces

all

the

specified

detailed

During the execution of the first GENERATE statement for
report, the following groups, if specified, are produced:
a.

Report Heading

Page Heading

All Control Headings, in the order major to minor.

The detail report group, if this is detailed reporting.

5-45

THE PROCEDURE DIVISION

GENERATE (Cont.)
5.

Data is moved to the data item in the Report
Group
Description Entry according to the same rules for movement
described for the MOVE statement see Section 5.9.23.

A GENERATE statement for a particular report can not be
executed until an INITIATE statement has been executed for
that report. In addition, if a TERMINATE statement has been
executed for that report, a GENERATE statement can not be
executed until an intervening INITIATE statement is executed
for the report.

5-46

THE PROCEDURE DIVISION

GO TO
5.9.18

GO TO

Function
The GO TO statement causes control to
the PROCEDURE DIVISION to another.

transferred from one part

General Format

Option 1:
GO

TO [procedure-name-1 ]

Option 2:
GO

procedure-name-1,procedure-name-2

DEPENDING ON

[,procedure-name-3 ]

identifier
MR-S-1056-81

Technical Notes
1.

Each procedure-name is the name of a paragraph or section
the PROCEDURE DIVISION of the program.

Option 1 causes transfer of control to the
specified
procedure-name, or to some other procedure-name if the GO TO
has been previously ALTERed.
In order to be alterable, Option 1 must appear as
sentence in a paragraph; only NOTE can follow.

the

first

If procedure-name-l is not specified,
the GO TO must be
alterable and an associated ALTER statement must be executed
prior to executing this GO TO.
When this form of GO TO appears in an imperative sentence, it
must appear as the last or only statement in the sentence,
except for NOTE.
3.

Option 2 causes transfer of control
to procedure-name-l,
procedure-name-2,...
or
procedure-name-n
depending on
whether the value of the identifier
is 1,
2,
or n,
respectively.
The identifier must refer to an elementary numeric item
having no positions to the right of the decimal point. The
item can not be USAGE COMPUTATIONAL-I.
If the value of the identifier is other
than the positive
integers 1, 2, •..
or n, the GO TO statement is by-passed.
5-47

THE PROCEDURE DIVISION

GOBACK
5.9,.19

GOBACK

Function
The GOBACK statement is used in a subprogram to return control to
calling program.

the

General Format
GOBACK.
Technical Notes

•

The GOBACK statement can only be used in subprograms.

When control reaches a GOBACK statement, control is returned
to the calling program at the statement immediately following
the CALL statement.

If a GOBACK statement is encountered in a subprogram that is
operating as a main program, it is treated as a STOP RUN
statement.

Refer to Chapter 11 of this manual for
subprograms.

5-48

information

THE PROCEDURE DIVISION

IF
5.9.20

Function
The IF statement causes a conditional expression to be evaluated and
the subsequent operations to be performed to be determined as a result
of this evaluation.
General Format

!f conditional-expression
statement-l [,statement-2]
} [ELSE {statement-3 [tstatement-4]
{ NEXT SENTENCE
•••
-NEXT SENTENCE

... }] - '
MR-S-1057-B1

Technical Notes
1.

Conditional expressions are discussed in Section 5.5 in
chapter.

this

The subsequent action of the program is determined by whether
the conditional expression is true or false.
a.

If the conditional expression, is true and statement-l and
any following statements are given, statement-l and any
following statements are executed and, provided that they
do not contain a GO TO or STOP RUN, control passes to the
next sentence. If the conditional expression is true and
NEXT SENTENCE is given, control passes to the next
sentence.

If the conditional expression is false and statement-3
and any following statements are given, statement-3 and
any following statements are executed and, provided that
they do not contain a GO TO or STOP RUN, control passes
to the next sentence.
If the conditional expression is false and either ELSE
NEXT SENTENCE is given or the entire ELSE clause is
omitted, control passes to the next sentence.

The length of compared data-items in
the
conditional
expression of an IF statement is limited to 2047 characters.

Statement-I, statement-2, statement-3, and statement-4 can
include any statement or sequence of statements, including
other IF statements. IF statements included within other IF
statements are nested.
Nested IF statements are paired IF
and ELSE combinations and can continue up to 12 levels deep.
Each ELSE encountered is paired with the nearest preceding IF
not already paired with an ELSE. The pairing process begins
with the innermost IF ••• ELSE pair and proceeds outwards.

5-49

THE PROCEDURE DIVISION

IF (Cent.)
Example:

(c=condition;s=statement)

MR·S·1058·81

5-50

THE PROCEDURE DIVISION

INITIATE
5.9.21

INITIATE

Function
The INITIATE statement is used to initialize
report is produced.

all

counters

before

General Format
INITIATE repor t-name-l [, repor t-name-2]

••.

Technical Notes
1.

Each report-name must be defined by an RD entry in the REPORT
SECTION of the DATA DIVISION.

The INITIATE statement resets all data-name
contain SUM clauses associated with a report.

The PAGE-COUNTER is set to 1 during the execution of an
INITIATE statement.
If a different starting value for the
PAGE-COUNTER is desired,
it can be reset following the
INITIATE statement before the execution of the first GENERATE
statement.

The LINE-COUNTER is set to 0 during execution of the INITIATE
statement.

The INITIATE statement does not open the file with which the
report is associated.
An OPEN statement must be executed
prior to the execution of the INITIATE statement.

A second INITIATE statement for a particular report-name can
not
be executed until a TERMINATE statement for
that
report-name is executed.

5-51

entries

that

THE PROCEDURE DIVISION

MERGE
5.9.22

MERGE

Function
The MERGE statement combines two or more identically sequenced files
on a set of specified keys.
During the MERGE process records are made
available, in merged order, to an output procedure or to an output
file.
General Format

CEND I NG } KEY data-name-l [ data-name-2 ] ...
.
{ AS
MERGE [ WITH SEQUENCE CHECK ] flle-name-ION
DESCENDING
ASCENDING}
[
[ ON { DESCENDING KEY data-name-3 data-name-4

J]
..... .

USING file-name-2, file-name-3 [,file-name-4] ...
.
[{ THRU
THROUGH} section-name-2]
OUTPUT PROCEDURE IS sectlon-name-l

IGIVING file-name-5

MR-S-1059-81

Technical Notes
1.

File-name-l must be described in an SD file description entry
in the DATA DIVISION.
Each data-name must represent data
items described in records associated with file-name-l.

File-name-2, file-name-3, file-name-4, and file-name-5 must
be described in an FD file description,
not an SD file
description.
All records associated
with
file-name-2,
file-name-3,
and file-name-4 must be large enough to contain
all the KEY data-names.

The data-names following the word KEY are listed in order of
decreasing significance without regard to how they are
divided into KEY clauses.

The data-names can be qualified but not subscripted.

MERGE statements can appear anywhere in the
PROCEDURE
DIVISION except in the DECLARATIVES portion or in an INPUT or
OUTPUT PROCEDURE associated with a SORT, or an OUTPUT
PROCEDURE associated with another MERGE.

When the ASCENDING clause is used, the input files must be in
sequence from the lowest values to the highest values; when
the DESCENDING clause is used, the input files must be in
sequence from the highest values to the lowest values.

The OUTPUT PROCEDURE, if present, must consist of one or more
sections or paragraphs that appear contiguously in the source
program and do not form a part of any INPUT PROCEDURE.
The
OUTPUT PROCEDURE must contain at least one RETURN statement
in order to make MERGEd records available for processing.
5-52

THE PROCEDURE DIVISION

MERGE (Cont.)
8.

ALTER, GO, and PERFORM statements in the OUTPUT PROCEDURE can
not refer to procedure-names outside the OUTPUT PROCEDURE in
which they appear.

If you specify an OUTPUT PROCEDURE, it is PERFORMed by the
MERGE statement. You must. observe all rules relating to the
range of a PERFORM.

10.

If WITH SEQUENCE CHECK is present then the input files are
checked to make sure that the records are in sequence with
respect to the merge keys
(that is,
that the files were
presorted. ) A warning message is given for each record out
of order.

11.

If you specify the GIVING option, all the merged records in
file-name-l are automatically transferred to file-name-5.
File-name-5 must not be open when the MERGE statement is
executed. Any USE PROCEDURES associated with file-name-5 are
executed as appropriate. The GIVING option is equivalent to
the following OUTPUT PROCEDURE:
L4.
L5.

L6.

OPEN OUTPUT file-name-5.
RETURN sort-file INTO record-name-5;
L6.
WRITE record-name-5 ..
GO TO L5.
CLOSE file-name-5.

5-53

AT END GO

THE PROCEDURE DIVISION

MOVE
5.9.23

MOVE

Function
The MOVE statement transfers data in accordance with
editing, from one data area to one or more data areas.

the

rules

General Format

Option 1:
MOVE {i~entifier-1} TO identifier-2 [ identifier-3] ...
- - llteral-1
,
Opti on 2:
MOVE {CORRESPONDING} identifier-1 TO identifier-2
CORR
MR-S-1060-81
Technical Notes

Identifier-l (or literal-I) represents the data to be moved
and is called the sending item.
Identifier-2, identifier-3,
represent the receiving data items.

In option 1, the data contained in identifier-lor literal-l
is moved first to identifier-2, then identifier-3, etc.
In option 2, data items within the group item associated with
identifier-l are moved to corresponding data items within the
group item associated with identifier-2. The results are the
same as
if you had referred to each pair of corresponding
identifiers in separate MOVE statements. The criteria used
to
determine
whether two items are corresponding are
described under "The CORRESPONDING Option" at the beginning
of this chapter.

The following rules apply to both group and elementary items;
a group item is treated as a single field.
a.

A numeric edited, alphanumeric edited, or alphabetic data
item must not be moved to a numeric or numeric edited
data item.

A numeric or numeric edited item must not be moved to
alphabetic data item.

5-54

THE PROCEDURE DIVISION

MOVE (Cont.)
c.

A numeric item whose implicit decimal point is not
immediately to the right of the least significant digit
must not be moved to an alphanumeric or alphanumeric
edited item.
All other moves are

The following rules apply to legal moves.
a.

l~gal.

When an alphanumeric, alphanumeric edited, or
item is the receiving item,

alphabetic

If the size of the sending field is greater than the
size of the receiving field, the least significant
(rightmost) characters are truncated if the receiving
field
is not described by a JUSTIFIED RIGHT clause;
the most significant
(leftmost)
characters
are
truncated if the receiving field
is described as
JUSTIFIED RIGHT.

If the size of the sending field
is less than the
size of the receiving field, spaces are placed in the
remaining rightmost characters of the receiving field
if
the receiving field
is not described by a
JUSTIFIED RIGHT clause;
spaces are placed in the
remaining leftmost characters of the receiving field
if the receiving field is described by a JUSTIFIED
RIGHT clause.

If the sizes of the sending and receiving field are
equal,
no truncation or filling with spaces takes
place.

When a numeric or numeric edited item is the receiving
item,
the sending and receiving fields are aligned by
decimal point.
If the sending field is not numeric,
the
decimal point is assumed to be on the right.
Any
necessary zero filling takes place before editing.
If
the receiving item has no operational sign, the absolute
value of the sending item is stored.
If the receiving
item has fewer digits to the left or right of the decimal
point than does the sending item, the excess digits are
truncated.
If the sending item contains any nonnumeric
characters, the result is unpredictable.

Any necessary conversion of data from one form of
internal
representation
to
another
is
performed
automatically during the move,
along with any editing
specified by the PICTURE of the receiving item.

Any move that is not an elementary move (that is,
both the
sending and receiving
items are not elementary items) is
called a group move. A group move is treated as if it were
an alphanumeric to alphanumeric elementary move, except that
there is no conversion of data from one form of internal
representation to another.
In other words, the individual
data descriptions of the items within the sending group item
and the receiving group item are completely ignored and both
items are treated as though they were described by a PICTURE
IS X(n) clause, where n is the number of character positions
in the particular item.
5-55

THE PROCEDURE DIVISION

MULTIPLY
5.9.24

MULTIPLY

Function
The MULTIPLY statement causes one data item to be multiplied by
another data item and the resulting product to be stored in a data
item.
General Format

Option 1:
MULTIPLY {i ~ent i fier-1} BY i dent i fier-2 [ROUNDED]
11 tera1-1
-[ON SIZE ERROR statement-1 [,:tatement-2] ...

__
. ]

Option 2:
MULTIPLY {i~entifier-1} BY {i~entifier-2} GIVING identifier-3
l1tera1-1
-- l1teral-2
[ROUNDED] [ON SIZE ERROR statement-1 [,statement-2] ... _._]
MR-S-1061-81

Technical Notes
1.

Each MULTIPLY statement must contain at least two operands (a
multiplicand and a multiplier). Each identifier must refer
to an elementary numeric item, except that identifier-3 can
refer to either a numeric or a numeric edited item. Each
literal must be a numeric literal; the figurative constants
ZERO and TALLY are permitted.

Option 1 causes the value of identifier-lor literal-l to be
multiplied by the value of identifier-2.
The resultant
product replaces the value of identifier-2.

Option 2 causes the value of identifier-lor literal-l to be
multiplied by the value of identifier-2 or literal-2. The
resultant product replaces the value of identifier-3.

5-56

THE PROCEDURE DIVISION

MULTIPLY (Cont.)
4.

The ROUNDED and SIZE ERROR options are described earlier
in
this chapter under "Common Options Associated with Arithmetic
Verbs".

The data item resulting from the multiply operation (that is,
the sum of all digits in both operands) must not contain more
than 20 decimal digits for the non-BIS compiler and not more
than 36 digits for
the BIS compiler.
In either case, a
maximum of 18 digits can be stored in the receiving field.
NOTE
The BIS compiler is standard on the DECSYSTEM-20 and
DECsystem-lO.
For KI based hardware, the non-BIS
compiler is optional on the DECsystem-IO
(See the
COBOL-68 Installation Procedures.)

5-57

THE PROCEDURE DIVISION

NOTE
5.9.25

NOTE

Function
The NOTE statement allows the programmer to
PROCEDURE DIVISION.

insert

comments

the

character

set

General Format
NOTE

character-string~

Technical Notes
1.

Any combination of characters from the ASCII
can be included in the character-string.

If the NOTE sentence appears as the first sentence in a
paragraph, the entire paragraph is considered to be part of
the character-string. The paragraph is ended when a new
paragraph is begun.
A new paragraph has its first word
starting in Area A.

If the NOTE statement appears as other than the first
sentence in a paragraph, the character-string ends at the
first period followed by a space or carriage return.

The contents of the
character-string
compilation listing, but are not compiled.

5-58

appear

the

THE PROCEDURE DIVISION

OPEN
5.9.26

OPEN

Function
The OPEN statement initiates th~ processing of files and, where
necessary, performs the checking and writing of labels.
It also
specifies your covenants for opening a file for simultaneous update.
General Format
{ 6~~~0T}

fi le-name-l [WITH NO REWI NO ] [, file-n ame-2 [WITH NO REWIND

{~UT-OUTPUT}

file-name-3

I~~~~~TE I:!~~~TE
I~~~~ITE I J
[ I~~C~ITE t I~~C~ITE
Iilih Iilih .Jl
FOR

DELETE
ANY VERB

ALLOWING OTHERS

[

OPEN
,file-name-4

JJ ...

EQR

WBlII

DELETE
ANY VERB

QElill
ANY VERB

l ] ...

WRITE
ltND
DELETE
8l1Y VERB

WRlI&

DELETE
ANY VERB

[

DELETE
~ VERB

...

ALLOWING OTHERS

WRITE
!ITE
lJ ...
DELETE
.8.!iY VERB

ltND

DELETE
ANY VERB

l]·

IIU
I

[EXTEND] fi le-name-5 [fi le-name-6 ] ...
[UNAVAILABLE statement-l [,statement-2] ...

J~
MR·S·1062·B1

5-59

THE PROCEDURE DIVISION

OPEN (Cant.)
Technical Notes

The OPEN statement must be executed for a file prior
to the
execution of any SEEK, READ, WRITE, REWRITE, DELETE, or CLOSE
for that file.

A second OPEN statement for a file cannot be executed
to the execution of a CLOSE statement for that file.

prior

When your program executes an OPEN verb, the record area
that file is cleared.

for

An OPEN statement does not obtain or release the first record
of a
file.
A READ statement must be executed to obtain the
first record (or
a WRITE statement must be executed to
release the first record).

The maximum number of files that can be opened at a
time
is
16.
When indexed sequential files
are being used, each
indexed sequential file is treated as two files:
the
index
file and the data file.
If the program is segmented, one
less file can be open;
similarly, if the RERUN option is
being used,
one less file can be open.
The key word INPUT,
OUTPUT, INPUT-OUTPUT, or 1-0 applies to each subsequent
filename
until another such key word is encountered or until
the end of the OPEN statement is reached.

When you OPEN an indexed sequential file, the OPEN statement
initializes the keys to LOW-VALUES.
Thus, you cannot load a
key with a value prior to opening the ISAM file and expect
the key to have the value you specify.

The NO REWIND option has meaning only for magtape files and
is ignored for all other devices.
If the NO REWIND clause is
not specified for a tape file, the tape
is rewound to the
beginning of tape.

If labels exist, the label is read into the record area to
make
it available to the USE routines.
The record area is
then filled with spaces.
If a file has been described as
LABEL RECORDS ARE STANDARD, standard label checking or label
writing is performed; your BEGINNING LABEL
(USE)
routines
are executed if provided.
If a file has been described as
LABEL RECORDS ARE data-name-l, your
BEGINNING LABEL
(USE)
routines are executed.
If a file has been described as LABEL
RECORDS ARE OMITTED,
no label checking or writing
is
performed.

is described as
OPTIONAL
(in
the
If an INPUT file
the object-time system types the
FILE-CONTROL paragraph),
message
IS file-name PRESENT?
and wait for you to type "YES" or "NO".
If you type "NO" ,
the
first
READ
statement
for
this file causes the
imperative-statement at the AT END or INVALID KEY clause to
be executed.

5-60

THE PROCEDURE DIVISION

OPEN (Cont.)
10.

The 1-0 or INPUT-OUTPUT options permit the opening of a file
on
a
random-access device for
both input and output
processing. When the 1-0 option is specified, the execution
of the OPEN statement causes the standard beginning label
procedures and your BEGINNING LABEL routines, if specified by
a USE statement, to be executed.
If the file does not exist
when it is opened for INPUT-OUTPUT, an empty file is created.

11.

A file is opened for simultaneous update if the ALLOWING
OTHERS clause is present in the OPEN statement.
It must be
opened in 1-0 mode and cannot have a recording mode of V
(variable-length EBCDIC).

12.

If the first user of a fi~e opens it for simultaneous update,
all subsequent users of' the file must also open it for
simultaneous update or for
input only.
If the file
1S
currently open for simultaneous update, any subsequent users
attempting to open the file for output or 1-0 are denied
access to the file.
If the first user of a file opens it for
output or 1-0 only and subsequent users attempt to open that
file for
simultaneous update, the simultaneous update users
are denied access to the file until the first user closes it.

13.

After the keyword FOR, you can give one or more verbs that
you intend to execute while you have the file ope~.
You can
only execute those verbs that you have specified.
Following
the keywords ALLOWING OTHERS, you give one or more verbs that
you allow other users to execute when they open the file.
You can also specify that others not be allowed to execute
any verbs when they open the file.
Specification of ANY VERB
means that all verbs legal for the file are permissible.
If
the ALLOWING OTHERS clause is not present, the file
is not
opened for simultaneous update.

14.

Once you have opened at least one file for
simultaneous
update,
you cannot open any other files for simultaneous
update until all files you previously opened for simultaneous
update are closed.
Thus, all files
that must be open
concurrently for simultaneous update must be opened in the
same OPEN statement.
However,
files that are not to be
opened for simultaneous update can be opened at any time.

15.

Files can be opened for INPUT, OUPUT, and
just INPUT-OUTPUT
(that is,
not for simultaneous update)
in the same OPEN
statement as files opened for simultaneous update.

5-61

THE PROCEDURE DIVISION

OPEN (Cont.)
16.

When more than one file is to be opened in one OPEN statement
and
at least one of the files
is to be opened for
simultaneous update, no files are opened if the simultaneous
update file cannot be opened.
Simultaneous update files
cannot be opened if they are not available in the modes
specified by both the FOR and ALLOWING clauses.
If the files
cannot be opened for this reason, your program is suspended
until all files are available, unless the UNAVAILABLE clause
is specified.
If the UNAVAILABLE clause is specified and one
or more simultaneous update files are unavailable, control
passes to the UNAVAILABLE clause. Note that the availability
of the simultaneous update files is always checked before any
files are opened.
After the simultaneous update files are
checked for
availability the files are opened. A failure
during the actual opening process on any of the files does
not cause the UNAVAILABLE path to be taken, but an error to
be returned.
You can choose to ignore the error by using the
FILE STATUS clause in the ENVIRONMENT DIVISION (see FILE
STATUS in Chapter 3 of this manual).

17.

Any valid COBOL statements (including OPEN) can
the UNAVAILABLE clause.

18.

If you wish to open a file in your program for
simultaneous
update and the file is not available to it, the open request
is queued for the file on a first-come/first-served basis.
However,
if your program wishes to open more than one file
for simultaneous update and at least one of the files is not
available,
the program is queued for those files that are
available as well as the ones that are not available.
This
is because the program cannot open one file without opening
all files in the same OPEN request.
The requests for
files
remain in the queue for the files until all of the files are
available to you.

19.

If your program violates its simultaneous update covenants,
it is aborted.
That is, if the program opens a file for READ
and then issues a WRITE statement for that file, the program
is aborted.

20.

Once a file is open for simultaneous update, you must issue a
RETAIN statement before you execute any I/O on that file.
Refer to the RETAIN statement, described further
ahead in
this chapter.

21.

When you specify the EXTEND phrase,
the OPEN statement
positions the file
immediately following the last logical
record of that file.
Subsequent WRITE statements referencing
the file add records to the file as though the file had been
opened with the OUTPUT phrase.

22.

If you wish to open a file using the EXTEND option, you
cannot open the same file for
input-output in the same
program.
You can, however, supply two FD's for
the same
file.
This allows you to open the file for input-output
using the file name supplied with one FD, and at a different
time you can open the file using the EXTEND option and the
file name supplied in the other FD.

5-62

used

THE PROCEDURE DIVISION

OPEN (Cont.)
23.

You cannot use the EXTEND option with system-labeled tapes.

24.

When you specify the EXTEND phrase and the LABEL RECORDS
clause indicates label records are present, the execution of
the OPEN statement includes the following steps:
a.

The beginning file labels are processed only in the
of a single reel file.

The beginning reel labels on the last existing reel are
processed as though the file was being opened with the
INPUT phrase.

The existing ending file labels are processed as though
the file
is being opened with the INPUT phrase. These
labels are then deleted.

Processing then proceeds as though
opened with the OUTPUT phrase.

the

Examples
OPEN INPUT INFIL.
OPEN 1-0 TRANSACTION FOR READ AND WRITE,
ALLOWING OTHERS READ AND WRITE.
OPEN OUTPUT LOG, LIST,
INPUT-OUTPUT MASTER FOR READ AND REWRITE,
OTHERS ANY
DET FOR READ,
OTHERS READ AND WRITE,
ACCOUNT FOR ANY
OTHERS NONE,
INPUT DAILY WITH NO REWIND,
1-0 SKILLS
NAMES FOR WRITE.

5-63

file

had

case

been

THE PROCEDURE DIVISION

PERFORM
5.9.27

PERFORM

Function
The PERFORM statement is used to depart from the normal sequence of
execution to execute one or more procedures and then return control to
the normal sequence.
General Format

Option 1:
PERFORM procedure-name-1 [THRU procedure-name-2]
Option 2:
PERFORM procedure-name-1 [THRU procedure-name-2] {~dentifier-1}
TIMES
lnteger-1
Option 3:
PERFORM procedure-name-l [THRU procedure-name-2] UNTIL condition-l
Option 4:
PERFORM procedure-name-1 [THRU procedure-name-2]
VARYING identifier-l FROM {~~!~~~ii!r-2}
BY {liter~1:2
l UNTIL condition-1
i dent 1 f 1 er- 3 f
MR.S.l063.81

5-64

THE PROCEDURE DIVISION

PERFORM (Cont.)

[

AFTER

VARYING

identifier-4

J\ identifier-6
literal-4

[AFTER VARYING

UNTIL

FROM

J\ identifier-5
literal-3

condition-2

identifier-7 FROM

J\ identifier-9
literal-6
I' UNTIL

J literal-5
\ identifier-8

condition-3 ] ]
MR-S-1064-81

Technical Notes
1.

Each procedure-name is the name of a section or paragraph in
the PROCEDURE DIVISION.
Each identifier must refer to a
numeric elementary item described in the DATA DIVISION.
Each
literal must be a numeric literal or the figurative constants
ZERO and TALLY.

When the PERFORM statement
is
executed,
control
is
transferred to the first statement of procedure-name-l. An
automatic return to the statement following the PERFORM
statement is established as follows.
The procedures executed
constitute the range of the PERFORM.

If
procedure-name-l
is
a
paragraph-name
and
procedure-name-2 is not specified, the return is after
the last statement of procedure-name-l.

If
procedure-name-l
is
a
section-name
and
procedure-name-2 is not specified, the return is after
the
last
statement
in
the
last
paragraph
in
procedure-name-l.

If procedure-name-2 is a paragraph-name,
the
after the last statement in that paragraph.

If procedure-name-2 is a section-name,
the return is
after the last statement in the last paragraph of that
section.

return

There is no relationship between
procedure-name-l
and
procedure-name-2, except that the sequence of operations
beginning at procedure-name-l must eventually end with the
execution of procedure-name-2 in order to effect the return
at the end of procedure-name-2. Any number of GO TO and/or
PERFORM statements can occur between procedure-name-l and
procedure-name-2.

5-65

THE PROCEDURE DIVISION

PERFORM (Cont.)
4.

If control passes to these procedures by means other
than a
PERFORM statement, control passes through the return point to
the following statement as though no return mechanism were
present.

PERFORM
No PERFORM statement can terminate until
all
statements that it has executed have terminated.
A PERFORM
statement can be executed which terminates at the same
procedure-name as another active PERFORM.

Option I causes the PERFORM range to be executed once,
followed by a return to the statement immediately following
the PERFORM.

Option 2 causes the PERFORM range to be executed the number
of times specified by identifier-lor integer-I.
The value
of identifier-lor integer-l must not be negative;
it can be
zero.
Once the PERFORM statement has been initialized, any
modification to the contents of identifier-l has no effect on
the number of times the range is executed.

Option 3 causes the PERFORM range to be executed until
the
condition specified in the UNTIL clause is true.
If this
condition is true at the time the PERFORM statement is
initialized,
the range is not executed.
Conditions are
explained under "Conditional Expressions" earlier
in this
chapter.

Option 4 is used to augment the value of one or more
identifiers during the execution of a PERFORM statement.
In option 4, when only one identifier is varied, identifier-l
is set equal to identifier-2 or literal-2 when the PERFORM
statement is initialized.
If the condition specified is
determined to be false at this point, the PERFORM range is
executed once. Then the value of identifier-l is augmented
by identifier-3 or literal-3 and the rest of the condition is
done again.
This cycle continues until condition-l is true;
at this point, control passes to the statement following the
PERFORM statement.
If condition-l is true at the beginning
of the execution of the PERFORM, control immediately passes
to the statement following the PERFORM.

5-66

THE PROCEDURE DIVISION

PERFORM (Cont.)
The flow chart below illustrates the logic
cycle when two identifiers are varied.

the

PERFORM

ENTRANCE

+
Set identifier-2 and identifier-5
to current F ROM values

•

True

Condition-1

Exit

False

True

Condition-2

+ False

Execute procedure-name-1
TH R U procedure-name-2

Set identifier-5 to its
current F ROM value

•

Augment identifier-5 with
current BY value

Augment identifier-2 with
current BY value

MR-S-1065-81

The following flow chart illustrates the logic of the PERFORM
cycle when three identifiers are varied.
ENTRANCE

+
Set
identifier-2, identifier-5, identifier-8
to current FROM values

+
Condition-1

+ False

True

Exit

True

Condition-2

False

Condition-3

•

False

Execute
procedure-name-1
TH R U procedurename-2

Set
identifier-8
to its current
FROM value

Augment
identifier-8
with current
BY value

Augment
identifier-5
with current
BY value

""----

True

5-67

Set
identifier-5
to its current
FROM value

Augment
identifier-2
with current
BY value
MR-S-1066-81

THE PROCEDURE DIVISION

PERFORM (Cont.)
10.

When a procedure-na~e in a segment with a priority number
greater than 49 1S referred to by a PERFORM statement
contained in a segment with a different priority number, the
segment referred to is made available in its initial state
(that is, with all ALTERable GO TOs set to their initial
setting) for each execution of the PERFORM statement.

11.

A PERFORM statement in a section not in the DECLARATIVES can
have as its range, procedures wholly contained within the
DECLARATIVESi however, a PERFORM statement in a section
within the DECLARATIVES can not have any non-DECLARATIVE
procedures within its range.

12.

A PERFORM statement within an INPUT or OUTPUT PROCEDURE
associated with a SORT or MERGE verb can not have within its
range any procedures outside of that INPUT or
OUTPUT
procedure.

5-68

THE PROCEDURE DIVISION

READ

Function
The READ statement makes available a logical record from an input file
and allows performance of a specified imperative statement when
end-of-file or invalid key is detected.
General Format

READ file-name RECORD
[INTO identifier]

{:~V~D KEY} statement-l [,statement-2]

_e_
MR·S·1067·81

Technical Notes
1.

An OPEN INPUT or OPEN 1-0 statement must be executed for the
file prior to execution of the first READ statement for that
file.

The AT END clause is valid only for those files whose
mode is SEQUENTIAL (explicitly or implicitly).

access

The AT END clause should be used if there is the possibility
that your program will encounter "End-of-Data", in order to
avoid program failure.
The INVALID KEY clause is valid only for
access mode is RANDOM or INDEXED.

those

files

whose

If an end-of-file condition is encountered during
the
execution of a READ statement for a sequential file, the
statement(s) specified in the AT END clause is executed, and
no logical record is made available.
The logical end-of-file depends upon the type of device
which the file resides (see the Monitor Calls manual).

After execution of the imperative-statement(s) in the AT END
clause, no further READ statements can be executed for that
file without first executing a CLOSE statement followed by an
OPEN statement for the file.
If, during the execution of a READ statement for a file whose
access mode is RANDOM, the ACTUAL KEY is found to contain a
value not within the range specified by the FILE-LIMITS
clause for that file or a value for a record that has not
been written (that
is,
a
zero-length
record) ,
the
statement(s) specified in the INVALID KEY clause is executed
and no logical record is made available.

5-69

THE PROCEDURE DIVISION

READ (Cont.)
When a READ statement is executed for
a file whose access
mode is RANDOM and the ACTUAL KEY contains a value of 0, the
first nonzero-length record having a key higher than the last
record processed
(by a READ or WRITE statement) is made
available.
If no such record exists (that is,
end-of-file),
the INVALID KEY statement(s}
is executed and no record is
made available.
If the file has been opened but no READ or
WRITE statement has been executed, the first nonzero-length
record is made available.
You can use this method to
sequentially read a file whose access mode is RANDOM.
When a READ statement is executed for
a file whose access
mode
is INDEXED and the SYMBOLIC KEY contains a value other
than LOW-VALUES, a search of the file is made to find
the
record that has a key equal to the contents of the SYMBOLIC
KEY associated with the file.
If that record is found, it is
moved to the record area for the file;
if it is not found,
the statement(s) associated with the INVALID KEY clause is
executed,
and no record is made available. When a READ
statement is executed for a file whose access mode is INDEXED
and the SYMBOLIC KEY contains a value of LOW-VALUES, the
first logical record having a key higher than the last record
processed (by a READ, WRITE, REWRITE, or DELETE statement) is
made available.
The next higher key is used regardless of
whether or not the previous I/O operation caused the INVALID
KEY path to be taken.
If no such record exists
(i.e.,
end-of-file),
the INVALID KEY statement(s} is executed, and
no record is made available.
If the file has been opened but
no READ, WRITE,
REWRITE,
or DELETE statement has been
executed, the first record of the file is made available.
3.

If a file described by an OPTIONAL clause is not present, the
imperative-statement(s}
in the AT END or INVALID KEY clause
is executed on the first READ for that file.
Any specified
USE procedures are not performed.

If logical end-of-reel is recognized during execution of
READ statement, the following operations are carried out.

The reel is rewound and your ENoDING REEL LABEL PROCEDUREs
are executed, if specified in a USE statement.

If the file is assigned to more than one device,
the
devices are advanced.
The previous reel is rewound and
the next reel is initialized.

The standard beginning label procedure and your BEGINNING
REEL LABEL PROCEDURE are executed, if specified in a USE
statement.

The first data record on the new reel is made available.

If a file consists of more than one type of logical
record,
these records automatically share the same storage area.
This is equivalent to an implied REDEFINE for
the record
area.
Only information in the current record is accessible.

If the INTO identifier option is specified,
the
READ
statement is then equivalent to a READ without the INTO
option, followed by a MOVE of the record area associated with
the filename to identifier.

5-70

THE PROCEDURE DIVISION

RELEASE
5.9.29

RELEASE

Function
The RELEASE statement transfers records to the initial
sort operation.

phase

the

General Format
RELEASE record-name [FROM identifier]
Technical Notes
1.

A RELEASE statement can be used only in an input procedure
associated with a SORT or MERGE statement for a file whose SD
description contains record-name.

If the FROM option is used, the contents of identifier are
moved to record-name,
then the contents of record-name are
released to the sort subroutines.

After the RELEASE statement is
record-name are not available.

Refer to the description
examples.

5-71

the

executed,
SORT

the

contents

MERGE

verb

of
for

THE PROCEDURE DIVISION

RETAIN
5.9.30

RETAIN

Function
The RETAIN statement specifies your
intent to access
records in files that are open for simultaneous update.

one

General Format

RETAIN

file-name-l

READ
REWRITE
READ-REWRITE
DELETE
WRITE

FOR

RECORD

AND

• file-nane-2

READ
REWRITE
READ-REWRITE
DELETE
WRITE

FOR

[KEY

AND

~WRITE

ANY VERB

[ UNAVAILABLE

READ
REWRITE
READ-REWRITE
DELETE
WRITE
ANY

VERB

RECORD

i dent i f i er-l }]
{ literal-l

[ UNT IL

FREED]

~WRITE

ANY

[KEY

statement-l

VERB

{ identifier-2}]
literal-2

READ
REWRITE
READ-REWRITE
DELETE
WRITE

[ UNTI L FREED]

~WRITE

ANY VERB

[,statement-2 ]

... ]

MR-S-1068-81

Technical Notes
1.

Filename-I, filename-2 ••• must be the
names
previously opened for simultaneous update.

5-72

files

THE PROCEDURE DIVISION

RETAIN (Cont.)
2.

Identifier-I,
identifier-2 ... and
literal-I,
literal-2 ... specify keys that refer to records in the file.

Statement-I, statement-2 •.•

The RETAIN statement must be given before any record
is
accessed in a file opened for simultaneous update.
If it is
given for a file not open for
simultaneous update,
the
program is terminated.

The RETAIN statement does not cause any change in the record
area or any change in the positioning in the file.
You must
explicitly issue I/O statements for
these changes to be
performed.
Thus,
the RETAIN statement does not cause an
end-of-file condition.

The actions performed by any I/O operation is logically the
same as if the file were not opened for simultaneous update.
That is,
a
sequential
file
is
always
read/written
sequentially;
the ACTUAL KEY is examined to determine the
record to be read/written in a random access file;
and the
SYMBOLIC KEY is examined to determine the record to be
read/written/rewritten/deleted in an indexed sequential file.
The only difference is that a check is made to ascertain that
the record has been retained.
Thus, retaining a record does
not cause that record to become the current record of the
file.
Only I/O operations can cause a record to become the
current record of the file.

You can retain nonexistent records in a file,
but you will
receive an error if you attempt to perform I/O, other than a
WRITE, on these nonexistent records.
You can perform a WRITE
operation on nonexistent records.

It is possible to mix requests for records from sequential,
random,
and indexed sequential files
in the same RETAIN
statement.

Using the RETAIN for WRITE, DELETE, or ANY VERB statement
with indexed-sequential files locks the entire file, not just
the record.

10.

When you retain a record for
READ, other
users are also
allowed to read that record, but cannot perform any other
form of I/O on that record (WRITE, REWRITE, or DELETE).
In
addition,
any other record in that logical-block, where a
logical-block is that set of records grouped in a block as
defined by the BLOCK CONTAINS clause or as calculated by the
compiler for sequential access files, cannot be accessed by
other users for
any form of I/O. When you retain a record
for any use other than READ,
all other users are banned
completely from accessing that record or block of records.

11.

The statement included in the FOR clause in the RETAIN
statement must agree with at least one statement in the FOR
clause in the OPEN statement for the file.
If ANY VERB is
specified in the FOR clause in the RETAIN statement, the file
must have been explicitly opened for ANY VERB.

5-73

are any valid COBOL statements.

THE PROCEDURE DIVISION

RETAIN (Cont.)
12.

The record or records named in the RETAIN statement are
automatically freed upon execution of the statement or
statements (except ANY VERB) in the FOR clause of the RETAIN
statement.
If you do not issue an I/O statement for the
record, or if the UNTIL FREED phrase is used, you must
explicitly free the record with the FREE statement.
If a
record is not freed, you cannot retain any more records in
any of your files open for simultaneous update.

13.

The UNTIL FREED phrase allows you to retain several logically
related records for processing ,without their being freed
automatically by the I/O statements.
Instead,
the records
are retained until they are explicitly freed by means of the
FREE statement.

14.

The KEY phrase allows you to specify a particular
to specify more than one record in a file.

15.

All records to be retained concurrently, whether
in one or
several files, must be retained in the same RETAIN statement.
Once records in any file have been retained, no other records
in any open file can be retained until the currently retained
records have all been freed.
This rule prevents a deadly
embrace situation.

record

NOTE
Deadly embrace occurs when two users make conflicting
demands upon a file resource and neither is willing
or able to yield to the other, with the result that
both programs hang or stall waiting for the resource
to become available.

16.

When attempting to retain records, the program is suspended
if anyone of the records is not available.
If you wish the
program to perform other processing,
rather
than
be
suspended, you can include an UNAVAILABLE phrase in the
RETAIN statement. Any valid COBOL ~tatement can be used in
the UNAVAILABLE phrase.

17.

Use of the RETAIN statement differs according to the access
mode of the file.
Each type of file is described separately
below.

18.

SEQUENTIAL ACCESS FILES
a.

Records in a sequential access file only can be retained
for READ, WRITE, READ-WRITE, or ANY VERB.
For sequential
access files, ANY VERB means READ, WRITE, and READ-WRITE.

5-74

THE PROCEDURE DIVISION

RETAIN (Cont.)
b.

When the KEY phrase is specified, KEY 0 refers to the
next record in the file.
The next record in the file
depends on the last I/O operation performed
(READ or
WRITE)
and the I/O operation for which the record is to
be retained.
If the last record was written,
the next
record to be retained for READ, WRITE, or READ-WRITE is
defined to be the one following the record just written.
Similarly,
if the last record was read, the next record
to be retained for READ is defined to be the one
following the on~ just read.
However, the next record to
be retained for WRITE is defined to be the record
just
read.

Subsequent KEY values (1,
2,
3 .•• ),
refer to records
relative to the record designated by a KEY value of O.

If the KEY phrase is not included, the record retained is
always the record designated by a KEY value of O.

The value of a key can be specified by any identifier,
which can be subscripted or qualified, or both, provided
that its USAGE is COMPUTATIONAL or INDEX.
The value of
the key can also be specified by a positive integer
numeric literal containing ten or fewer digits.

It is recommended that you, when performing simultaneous
updating on sequential access files,
retain several
records at a time so that the input/output overhead is
reduced.
If records are retained singly, each record
must be brought into memory from the device (even if it
is already in memory) so that you have the latest copy of
the record.
Also when you free a record
(either
implicitly or explicitly), after writing it, the record
must be written out to the device so that other users
have access to the latest copy of that record.

Example:
OPEN INPUT-OUTPUT HISTORY FOR READ AND WRITE
ALLOWING OTHERS READ AND WRITE

RETAIN HISTORY KEY 0 FOR READ-WRITE UNTIL FREED,
HISTORY KEY 1 FOR READ-WRITE UNTIL FREED,
HISTORY KEY 2 FOR READ-WRITE;
READ HISTORY, AT END STOP RUN.

19.

RANDOM ACCESS FILES
a.

Records in a random access file can only be retained for
READ, WRITE, READ-WRITE, or ANY VERB.
For random access
files, ANY VERB means READ, WRITE, and READ-WRITE.

5-75

THE PROCEDURE DIVISION

RETAIN (Cont.)
b.

When the KEY phrase is specified, the value of the key
designates a specific record in the file, just as the
ACTUAL KEY of the file does. Thus, record 1 is always
the first record in the file. If the value of the key is
0, however, the record retained is the next sequential
record in the file. The next record in the file depends
on the last I/O operation performed (READ or WRITE) and
the I/O operation for which the record is to be retained.
If the last record was written, the next record to be
retained for READ, WRITE, or READ-WRITE is defined to be
the one following the record just written. Similarly, if
the last record was read, the next record to be retained
for READ is defined to be the one following the record
just read.
However, the next record to be retained for
WRITE is defined to be the record just read.
Note that
the next record actually read or written depends on the
value of the ACTU~L KEY, not on the record specified in
the RETAIN statement.

If you wish to read/write the file sequentially, you
should set the KEY to 0 in the RETAIN statement and set
the ACTUAL KEY to 0 so that you are performing I/O on the
same records that you are retaining. If you wish to
read/write the file randomly, you should set the ACTUAL
KEY to the desired record and either use the same value
in the KEY in the RETAIN statement or use no KEY value in
the RETAIN statement.

If the KEY phrase is not specified, the value used for
the key is taken from the ACTUAL KEY specified for the
file.

The value of a key can be specified by any identifier,
which can be subscripted or qualified, or both, provided
that its USAGE is COMPUTATIONAL or INDEX. The value of
the key can also be specified by a positive integer
numeric literal containing ten or fewer digits.

Example:
OPEN 1-0 PART FOR READ AND WRITE ALLOWING OTHERS
NONE.
MOVE 64 TO PART-ACTUAL-KEY
RETAIN PART FOR READ.
READ PART, INVALID KEY GO TO ERR.

RETAIN PART KEY 0 FOR WRITE,
PART KEY 35 FOR READ AND WRITE.
WRITE PARTREC.
MOVE 35 TO PART-ACTUAL-KEY.
READ PART, INVALID KEY GO TO ERR.
WRITE PARTREC.

5-76

THE PROCEDURE DIVISION

RETAIN (Cont.)
20.

INDEXED SEQUENTIAL ACCESS FILES
a.

Records in an indexed sequential file can be retained for
READ, WRITE, REWRITE, DELETE, READ-REWRITE, and ANY VERB.
For indexed sequential files, ANY VERB means READ, WRITE,
Records in an indexed
REWRITE, DELETE, and READ-REWRITE.
sequential file cannot be retained for READ-WRITE.

When the KEY phrase is specified, the value of the key
refers to a specific record in the file, just as the
SYMBOLIC KEY does.

The value specified in the KEY phrase must normally be an
identifier that specifies a field that agrees with the
RECORD KEY defined for the file in size,
class,
usage,
and number of decimal places.
However, if the RECORD KEY
of the file is USAGE COMPUTATIONAL or INDEX,
a positive
numeric literal of ten or fewer digits can be used as the
value in the KEY phrase.

If the KEY phrase is not specified, the value used for
the key is taken from the current SYMBOLIC KEY for the
file.

If the value of the key is LOW-VALUES
(which must be
specified as the contents of an identifier or as the
SYMBOLIC KEY), the record retained is that following
the
last record referenced in the same RETAIN statement or by
a READ, WRITE, REWRITE, or DELETE statement.

If other users are allowed to write or delete records in
an indexed sequential file, LOW-VALUES cannot be used as
the value of the first key specified in the RETAIN
statement.
Similarly, the first I/O statement following
the RETAIN statement cannot reference a record specified
with
a
SYMBOLIC
KEY value of LOW-VALUES.
These
restrictions are applied because the next record
in the
file could be undefined because another user has written
or deleted that record.

Example:
OPEN 1-0 LETTERS FOR READ ALLOWING OTHERS READ AND
WRITE.
MOVE IIBII TO SYMBOLIC KEY.
RETAIN LETTERS FOR READ.
READ LETTERS INVALID KEY GO TO ERRS.

5-77

THE PROCEDURE DIVISION

RETURN
5.9.31

RETURN

Function
The RETURN statement obtains sorted records from the final phase of
SORT or MERGE operation.

General Format

RETURN file-name RECORD [INTO identifier] AT END statement-l [,statement-2]
Technical Notes
1.

File-name must be described by an SO file descriptor.

A RETURN statement can be used only in an output procedure
associated with a SORT or MERGE statement for file-name.

If .the INTO phrase is specified, the current record is moved
from the record area associated with file-name to identifier.

The AT END path is automatically taken when there are no more
records to be returned. After executing the statement(s) in
the AT END clause, no RETURN statements can be executed until
another SORT or MERGE is executed.

Refer to the description of
examples.

5-78

the

SORT

MERGE

verbs

for

THE PROCEDURE DIVISION

REWRITE
5.9.32

REWRITE

Function
The REWRITE statement replaces an already existing record
whose access mode is INDEXED.

file

General Format

REWRITE record-name [FROM identifier] INVALID KEY statement-l [,statement-2]
MR-S-1070-B1

Technical Notes
1.

Record-name must be a record associated
access mode is INDEXED.

with

When the REWRITE statement is executed, a record in the file
is located whose key value is equal to the contents of the
SYMBOLIC KEY associated with the file.
The contents of the
SYMBOLIC KEY item are moved to the RECORD KEY item and the
contents of the record are then replaced with the contents of
record-name.
If no such record exists in the file, the
statement(s)
associated with the INVALID KEY clause is
executed.

At the time the REWRITE statement is executed, the file
be open for OUTPUT or INPUT-OUTPUT.

If the FROM option is used, the statement is equivalent to:
MOVE identifier TO record-name
REWRITE record-name (without the FROM option)

5-79

file

whose

must

THE PROCEDURE DIVISION

SEARCH
5.9.33

Function
The SEARCH statement is used to
condition exists.

table

until

specified

General Format
Opti on 1:
SEARCH identifier-l [VARYING identifier-2][AT END imperative-statement-l [,imperative-statement-2] ...J
perative-statement-3 [,imperative-statement-4]
}
WHEN can d1't'10n -1 {im
__
NEXT SENTENCE
..•

imperati ve-statement-5 [, imperat ive-statement-6]
}]
WHEN can d1't'10n -2 { NEXT
SENTENCE
...
[ , __

Option 2:

SEARCH ALL identifier-l [AT END imperative-statement-l [,imperative-statement-2] ...
WHEN
dit· -1 {imperative':statement-3 [,imperative-statement-4]
- - can
lon
NEXT SENTENCE

. ..

}
MR.·s.107,.a,

Technical Notes
1.

If any of the optional clauses are present, they must
in the order shown.

Identifier-l must not be subscripted or indexed, but its
description must contain an OCCURS clause with an INDEXED BY
option.
In option 2, identifier-l must also contain a KEY
option in its OCCURS clause.

Identifier-2 must be an index, or an elementary numeric
with no places to the right of the decimal point.

item

In option 1, condition-I, condition-2,
condition described in Section 5.5.

any

5-80

etc.,

can

appear

THE PROCEDURE DIVISION

SEARCH (Cont.)
5.

In option 2, condition-l must consist of a relation condition
incorporating the EQUAL TO or equal sign, or a condition-name
condition where the VALUE clause contains only a single
literal, or a compound condition consisting of two or more
such simple conditions connected by AND.
A data-name that appears in the KEY clause of identifier-l
must appear as the subject or object of a test, or be the
name of the data-item with which the tested condition-name is
associated.
However, all preceding data-names in the KEY
clause must also be included within condition-I.

If the AT END clause is not present, AT END NEXT SENTENCE
assumed.

If the VARYING option is not specified,
the first
index
specified in the INDEXED BY option for identifier-l is used.
If the VARYING option is used, and identifier-2 is the name
of
an
item
specified in the INDEXED BY option for
identifier-I, then identifier-2 is used as the index.
If
identifier-2 is not specified in the INDEXED BY option for
identifier-I, the first index-name in the INDEXED BY option
is used as the index, and identifier-2 contains the value of
the index at each step of the search.

If option 1 of the SEARCH verb is used, a serial search takes
place, starting with the current index setting.
If, at the start of execution of the SEARCH statement,
the
index contains a value that is not positive or is greater
than allowed (greater than the number of occurrences or
greater than any DEPENDING item), the statement(s) specified
in the AT END statement is executed.
If, at the start of execution of the SEARCH statement,
the
index is within the allowed range of values,
the WHEN
conditions are evaluated one at a time.
If any condition is
true,
the associated statement(s)
is executed.
If no
condition is true, the index is incremented by 1, and the
search operation is executed again.
The contents of the index are always left as they were when
the search is terminated, either by a WHEN condition, or the
AT END condition.

If option 2 of the SEARCH verb is used, a binary search takes
place. All the keys in the table must be in order (ascending
or descending) and all the elements in the table must be
filled.
It is up to you to ensure that the keys associated
with the table are in order and the table filled.
If the
keys are not in order, or if there are empty elements in the
table being searched, the SEARCH can take the AT END path
even if the key being searched for is there.
If the table is
not going to be filled, using the DEPENDING ON clause with
OCCURS effectively shortens the table.
-

5-81

THE PROCEDURE DIVISION

SEARCH (Cont.)
The initial contents of the index are ignored;
instead,
the
table is examined until the WHEN condition is satisfied (in
which
case
imperative-statement-3
and
any
following
statements are executed)
or until the entire table is
examined (in which case the AT END statement(s) is executed).
When the search is terminated,
the contents of the index
reflect the occurrence number of the entry that satisfied the
WHEN condition if it was satisfied, or is arbitrary if it was
not satisfied.
Conditional statements (for example, IF) are not
the WHEN clause of a SEARCH verb.

allowed

10.

In either option, after any WHEN or AT END statement(s)
is
executed, control is transferred to NEXT SENTENCE unless that
statement contained a GO TO.

11.

If identifier-l is a data item subordinate to a data item
that
contains
an OCCURS clause
(that is,
this is a
multidimensional
table),
only the index associated with
identifier-l is modified during the search. To search an
entire multidimensional table, the SEARCH statement must be
executed several times.
Example
01

TABLE.
02 TABLI OCCURS 200 TIMES INDEXED BY I,
ASCENDING KEYS A, B.
03 A
PICTURE XXX.
03 FOO
PICTURE X(20).
03 B
PICTURE 9(4).
03 DES
PICTURE X(40).
03 AM
PICTURE S9(5)V99.

SEARCH ALL TABLl, AT END GO TO WHAT-HAPPENDEDi
WHEN A(I) = "XYZ" AND B(I) = 350 GO TO GO-ONE.

5-82

THE PROCEDURE DIVISION

SEEK
5.9.34

SEEK

Function
The SEEK statement initiates the accessing of a mass storage data
record in a random access file for subsequent reading or writing.
General Format
SEEK file-name RECORD
Technical Notes
1.

The SEEK statement uses the contents of the ACTUAL KEY item
to position the read-write arms on a mass storage device.
If
the key is invalid, no action is taken;
however,
if the
contents of ACTUAL KEY are not changed before the next READ
or WRITE statement is executed, that READ or WRITE statement
then takes the INVALID KEY path.

The file must be assigned to amass-storage device,
ACCESS MODE must be RANDOM.

The statement cannot be used for files whose access modes are
sequential or indexed.

Under timesharing, a SEEK to a public file structure is
generally a waste of time, because many users are competing
for positioning.

5-83

and

the

THE PROCEDURE DIVISION

SET
5.9.35

SET

Function
The SET statement allows a data-item to be
or set to a value.

incremented,

decremented,

General Format

SET identifier-l [ ,identifier-2 ] ... { lQ.
UP BY } {identifier-3}
literal-l
DOWN BY
MR-S-1072-B1
Technical Notes
1.

All identifiers must be numeric elementary items described
without any positions to the right of the assumed decimal
point.
All literals must be integers,
ZERO.

the

figurative

constant

The SET statement causes identifier-I,
identifier-2,...
to
be set
(TO),
incremented (UP BY), or decremented (DOWN BY)
the value of identifier-3 or literal-I.

5-84

THE PROCEDURE DIVISION

SORT
5.9.36

SORT

Function
The SORT statement creates a sort file containing the contents of one
or more files that have been ordered according to user-specified keys.
General Format

SORT file-name-l ON ~~~~~~~~~G KEY data-name-l
[ ,data-name-2 ] ... ON ASCENDING
DESCENDING KEY data-name-3

.
.
SORT flle-name-l
ON {ASCENDING}
DESCENDING KEY data-name-l
[. data-name-2] ••. [ON

gm~~6~~G} KEY data-name-3 [.data-name-4] ... ] ...

INPUT PROCEDURE IS procedure-name-l [THRU procedure-name-2]}
{ USING file-name-2 [,file-name-3] ...
OUTPUT PROCEDURE IS procedure-name-3 [THRU procedure-name-4]}
{ GIVING file-name-4
.
.

MR-S·1073-81

Technical Notes
1.

File-name-l must be described in an SD file description entry
in the Data Division.
Each data-name must represent data
items described in records associated with file-name-l.

File-name-2, file-name-3, and file-name-4 must be described
in an FD file description. All records associated with these
files must be large enough to contain all of the KEY
data-names.
If multiple files must be read, you can use an
input procedure that reads each file in turn.
If you use
SORT, you can use any number of input files with a SORT
statement.

The data-names following the word KEY are listed in order of
decreasing significance without regard to how they are
organized in the SD record description.

The data-names can be qualified but not subscripted.

5-85

THE PROCEDURE DIVISION

SORT (Cont.)
5.

with SORT, the maximum record size is 4095
ASCII, EBCDIC, and SIXBIT representations.

SORT statements can appear anywhere in the PROCEDURE DIVISION
except in the DECLARATIVES portion or in an input or output
procedure associated with a sort, or an output procedure
associated with a merge.

When the ASCENDING clause is used,
the sorted sequence is
from
the lowest value to the highest value;
when a
DESCENDING clause is used, the sorted sequence is from the
highest value to the lowest value.

The input procedure, if present, must consist of one or more
sections or paragraphs that appear contiguously in the
program and do not form a part of any output procedure.
The
input procedure must contain at least one RELEASE statement
to transfer records to the sort subroutine.

The output procedure, if present, must consist of one or more
sections or paragraphs that appear contiguously in a source
program and do not form a part of any input procedure.
The
output procedure must contain at least one RETURN statement
to make sorted records available for processing.

10.

ALTER, GO and PERFORM statements in the input procedure are
not permitted to refer to procedure-names outside the input
procedure;
similarly, ALTER, GO and PERFORM statements in
the
output
procedure
are not permitted to refer to
procedure-names outside the output procedure.

11.

If an input or output procedure is
specified,
those
procedures are PERFORMED by the SORT statement, and all rules
re,1ating to the range of a PEHFORM must be observed.

12.

If the USING option is specified, all rec6rds in file-name-2,
file-name-3, ... ,
are automatically transferred to the SORT
subroutine.
File-name-2, file-name-3, ... , must not be open
when the SORT statement is executed.
Any USE PROCEDUREs
associated with file-name-2, file-name-3, ... , are executed as
appropriate.
The USING option is equivalent to the following
INPUT PROCEDURE:
Ll.
L2.
L3.

OPEN INPUT file-name-2
READ file-name-2 INTO sort-record;
L3.
RELEASE sort-record.
GO TO L2.
CLOSE file-name-2.

5-86

characters

END

for

THE PROCEDURE DIVISION

SORT (Cant.)
13.

If the GIVING option is specified, all the sorted records in
file-name-l are automatically transferred to file-name-4.
File-name-4 must not be open when the SORT statement is
executed. Any USE PROCEDURES associated with file-name-4 are
executed as appropriate. The GIVING option is equivalent to
the following OUTPUT PROCEDURE:
L4.
L5.
L6.

14.

OPEN OUTPUT file-name-4.
RETURN sort-file INTO record-name-4;
WRITE record-name-4.
GO TO L5.
CLOSE file-name-4.

AT END GO TO L6.

An ISAM file can be sorted with INPUT and OUTPUT procedures.
ISAM files cannot be sorted with the USING and GIVING
options.
ISAM files are by definition a sorted set.
In designing the
file you should use the order in which the file is most often
accessed.
If you wish to access it in a different order,
write a program with an input procedure that reads the ISAM
file sequentially using LOW VALUES. The input procedure can
release records to the sort.
If you wish to use an ISAM file
as output, you must have an empty ISAM file for output,
return records from the sort and write them into the new ISAM
file.

5-87

THE PROCEDURE DIVISION

STOP
5.9.37

STOP

Function
The STOP statement halts the object ·program.
General Format
STOP

literall

RUN

Technical Notes
1.

If the literal option is used, the literal is displayed
your terminal, and the program waits for you to type

CONTINUE

Following receipt of this message, the program
execution at the statement following the STOP.

continues

The literal can be a figurative constant;
single character is displayed.

case,

this

If the RUN option is used, all files currently open
closed, and execution of the program is terminated.

5-88

a
are

THE PROCEDURE DIVISION

STRING
5.9.38

STRING

Function
The STRING statement is used to concatenate the partial
contents of several data items into a single data item.

complete

General Format

STRING

ide nt i fie r -1
{ literal-1

,identifier-2 ]
[ ,literal-2

[. I

i dent i fi er-4
literal-4

INTO

identifier-7

[WITH

,identifier-5 ]
,literal-5

POINTER

DELIMITED BY

identifier-3 }
literal-3
{ SIZE

DELIMITED BY

identifier-6 }]
literal-6
{ SIZE

identifier-8 ]

[;ON OVERFLOW statement-l ]
MR-S-1074-81

Technical Notes
1.

Source Items
a.

The
data
items
referenced
by
identifier-I,
identifier-2, •.• are called source data items.

A numeric source item is moved to an intermediate
unsigned numeric data item of the same size as the source
and whose USAGE is the same as that of identifier-7
according to the rules for numeric transfers, and then
treated as alphanumeric.

If subscripting or indexing is needed to identify a
source data item, the values of the required subscripts
and/or indexes and the depending items, if any, just
prior to the transfer of that pa~ticular source item are
used.

If a source item is defined in the Data Division using
the OCCURS ••• DEPENDING option, STRING deals with the
source item as if it were just long enough to contain the
existing characters.

Literal-I; literal-2 •••
Source
literals
must
alphanumeric figurative
modifier.

If a source literal is a figurative constant, it refers
to a single-character literal of the specified type.

5-89

are called source literals.
be alphanumeric literals or
constants
without
the
ALL

THE PROCEDURE DIVISION

STRING (Cont.)
2.

Delimiter Items
a.

Each series of source items specified in the STRING
statement must be followed by a DELIMITED BY phrase.
This phrase specifies the delimiter condition to be
associated with each source item in that series.

The
data
items
referenced
by
identifier-3
identifier-6 are called delimiter data items.

A numeric delimiter item is moved to an intermediate
unsigned numeric data item of the same size as the
delimiter and whose USAGE is the same as that of
identifier-7 according to the rules for numeric transfers
and then treated as alphanumeric.

If subscripting or indexing is needed to identify a
delimiter
data
item,
the values of the required
subscripts and/or indexes and the depending items, if
any, just prior to the transfer of the source item
corresponding to that particular delimiter item are used.

Literal-3 and literal-6 are called delimiter literals.
Delimiter literals must be alphanumeric literals or
alphanumeric figurative constants
without
the
ALL
modifier.

If a delimiter literal is a figurative constant, it
refers to a single-character literal of the specified
type.

If a delimiter data item or a delimiter literal is
specified, the content of the data item during the
execution of the STRING statement, or the value of the
literal is the delimiter string for each source item
corresponding to that delimiter item.

and

In this case, the delimiter condition for each of the
corresponding source items is the first occurrence in the
source item of a character string that matches the
delimiter string. If there is not such character string
in the source item, the delimiter condition is the
rightmost boundary of that source item.

Two character strings match if, and only if, they
are of equal length and each character of the
first string is equivalent, according to the
rules for code conversion, to the corresponding
character of the second string.
h.

If the DELIMITED BY SIZE phrase is specified, the only
delimiter condition for each of the corresponding source
items is the rightmost boundary of the source item.

5-90

THE PROCEDURE DIVISION

STRING (Cont.)
3.

Destination
a.

The data item referenced by identifier-7
is called the
destination.
The
destination must be an unedited
alphanumeric data item.
It cannot be justified (that is,
the JUSTIFIED clause cannot be used for this item).

If subscripting or indexing is needed to
identify the
destination, the values of the required subscripts and/or
indexes and the depending items, if any,
just prior
to
the execution of the STRING statement are used.

Pointer
a.

The data item referenced by identifier-8 is called the
pointer.
The pointer must be an unedited integer data
item of sufficient size to contain a value one greater
that the size of the destination.

The pointer
destination.

If subscripting or indexing is needed to
identify the
pointer,
the values of the required subscripts and/or
indexes and the depending items, if any,
prior
to the
execution of the STRING statement are used.

If the POINTER phrase is specified,
the pointer
is
directly available to you.
It must be initialized before
the execution of the STRING statement to a value greater
than
zero
and not greater
than the size of the
destination.

If the POINTER phrase is not specified,
the STRING
statement is always executed as if you have specified a
pointer and set the initial value to 1.
In this case,
the pointer is not directly available to you.

The STRING statement is executed as if the initial value
of the pointer were stored in a temporary location.
This
temporary location is used as the pointer during
the
execution of the STRING statement.
The value in this
temporary location is stored in the real pointer
item
before any subscripting is done and at the end of
execution of the STRING statement.

serves

character

index

for

the

Execution
a.

When the STRING statement is executed, each source
item
in turn,
starting with the first source item specified,
is transferred to the destination character-by-character,
beginning at the leftmost character position of the
source item and continuing to the right,
until
the
delimiter condition corresponding to that source item has
been encountered or the destination has been filled.

5-91

THE PROCEDURE DIVISION

STRING (Cont.)
b.

If a delimiter item was specified for a source item and a
string of characters is found in the source item matching
the delimiter string, all characters of the source item
preceding the matching string are used in the transfer to
the destination, but none of the characters that are
in
the matching string and no characters following it in the
source item are used in the transfer.

If no delimiter item was specified for a source item or
no string of characters is found
in the source item
matching the delimiter string,
all characters of the
source item are used in the transfer to the destination.

During the execution of the STRING statement,
characters
are transferred to the destination from the source items
as if the destination were a table of single character
data items indexed by the pointer, which is automatically
incremented after each character transfer.

The first character transferred is stored
in
the
character position of the destination indicated by the
initial value of the pointer.
The
nth
character
transferred is stored in the character position indicated
by the initial value of the pointer plus n-l.

The transfer of characters ends when one of the following
conditions occur.
These conditions are
order stated:

specifically

checked

for

the

The initial value of the pointer is not a positive
integer less than or equal to the size of the
destination.

All appropriate characters of all source
been transferred to the destination.

A character has been transferred to
the
last
character position of the destination, though not all
appropriate characters of all source items have been
transferred.

items

have

If the transfer of characters to the destination is
terminated because of condition 2 of note f, those
character positions of
the
destination
to
which
characters were not transferred,
if any,
retain the
values they contained before the execution of the STRING
statement.
That is, remaining character positions in the
destination are not space-filled.

After the transfer of characters to the destination has
ended, the pointer is set to a value one greater than the
ordinal number of the last character position of the
destination to which data was transferred.
If no data
was transferred to the destination,
the pointer
is
unchanged.

5-92

THE PROCEDURE DIVISION

STRING (Cont.)
6.

Overflow
a.

If the transfer of characters to the destination is
terminated because' of either condition 1 or condition 3
of note 5.f, the STRING statement is considered to have
caused an overflow.

IF THE ON OVERFLOW phrase is not specified,
after the
execution of the STRING statement, regardless of whether
or not there was an overflow, control passes to the point
in
the
program
immediately
following
the STRING
statement.

If the ON OVERFLOW phrase is specified,
after the
transfer of characters has ended and the pointer set to
the appropriate value,
the flow of program control
depends on whether or not there was an overflow.
1.

If an overflow did not occur, control passes to the
point in the program corresponding to the end of the
sentence containing the STRING statement
(following
all the statements in the ON OVERFLOW phrase) .

If an overflow did occur, control passes to the point
in the program corresponding to the beginning of
statement-I.

Example
DATA DIVISION.
Dl
INPUT-DATE.
D3 IN-MO PIC 99.
D3 IN-DA PIC 99.
D3 IN-YR PIC 99.
Dl
MONTH-TABLE.
D3 MON-TABLE PIC X(36) VALUE
"JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC".
D3 MON-ARRAY REDEFINES MON-TABLE.
D5 MO-NAME OCCURS 12 TIMES PIC xxx.
Dl
OUTPUT-DATE PIC X(12).
PROCEDURE DIVISION.
STRING IN-DA "-" MO-NAME (IN-MO) "-" IN-YR
DELIMITED BY SIZE INTO OUTPUT-DATE.
STOP RUN.
NOTE
The DELIMITED BY clause specifies a
character of data which is to serve as
the rightmost terminator of the input
field, unless SIZE is specified.

5-93

THE PROCEDURE DIVISION

SUBTRACT
5.9.39

SUBTRACT

Function
The SUBTRACT statement is used to subtract one, or the sum of two or
more,
numeric items from one or more numeric items and set the values
of one or more items to the result.
General Format
Option 1:

SUBTRACT

identifier-I}
{ literal-l

[

identifier-2 }]
{ literal-2

FROM

identifier-m

[ROUNDED] [ ,identifier-n

[ON

SIZE

statement-l

ERROR

[ROUNOED] ]

[,statement-2 ] ...

~ ]

Option 2:

SUBTRACT

FROM

identifier-I}
{ literal-l

identifier-m }
{ literal-m

[ i dent ifi er-p

[ON

SIZE

[, {

}]

GIVING

identifier-n

identifier-2
literal-2

...

[ROUNDED]

[ROUNDED] ]

ERROR

statement-l

[,statement-2 ]

]

MR-S-1075-81

5-94

THE PROCEDURE DIVISION

SUBTRACT (Cont.)
Option 3:

SUBTRACT

CORRESPONDING } identifier-l
{ CORR

[ ROUNDED] [ON SIZE

ERROR

FROM

s tatement-l

identifier-2

[, statement-2 ]

~ ]
MR-S-1076-81

Technical Notes
1.

Each SUBTRACT statement must contain at least two operands
(that is,
a subtrahend and a minuend).
In options 1 and 2,
each identifier must refer to an elementary numeric
item,
except that
identifiers to the right of the word GIVING can
refer to numeric edited items.
In option 3, each
identifier
must refer to a group item.
Each literal must be a
constant ZERO.

numeric

literal

the

figurative

the data item
The composite of all operands
(that is,
resulting from the superimposition of all operands aligned by
decimal point) must not contain more than 18 decimal digits
the BIS
the non-BIS compiler or more than 36 for
for
compiler.
In either case a maximum of 18 digits can be
stored in a receiving field.
NOTE
The BIS compiler is standard on the DECSYSTEM-20 and
DECsystem-lO.
For KI based hardware, the non-BIS
compiler is optional on the DECsystem-lO.
(See the
COBOL-68 Installation Procedures.)

Option 1 causes the values of the operands preceding the word
FROM to be added together, and this sum to be subtracted from
the values of identifier-m, identifier-n, and so forth.

Option 2 causes the values of the operands preceding the word
FROM
to
be
added together,
the sum subtracted from
identifier-m or literal-m, and the result stored as the new
values of identifier-n,
identifier-p,
and so forth.
The
current values of identifier-n, identifier-p, and so forth,
do not enter into the computation.

Option 3 causes the data items in the group item associated
with identifier-l to be subtracted from and stored into
corresponding data items in the group item associated with
identifier-2.
The criteria used to determine whether two
items
are
corresponding
are
described
under
"The
CORRESPONDING Option" at the beginning of this chapter.

The ROUNDED and SIZE ERROR options are described earlier
in
this chapter under "Common Options Associated with Arithmetic
Verbs".
5-95

THE PROCEDURE DIVISION

SUPPRESS
5.9.40

SUPPRESS

Function
The SUPPRESS statement inhibits the presentation of a report group.
General Format

SUPPRESS PRINTING
MR-S-1077-81
Technical Notes
1.

The SUPPRESS statement
REPORTING procedure.

can

appear

only

The SUPPRESS statement inhibits presentation of the report
group named in the USE BEFORE REPORTING statement only.

Each time you wish your program to inhibit presentation of a
report group you must make sure that your program executes
the SUPPRESS statement; you cannot execute it only once if
you wish the group to be suppressed all the time.

Execution of the SUPPRESS statement causes
report group functions to be inhibited:

the

USE

BEFORE

following

•
•
•

The presentation of the print lines of the group,

•

The adjustment of LINE-COUNTER.

The processing of all LINE clauses in the group,
The processing of the NEXT GROUP clause
and

5-96

the

group,

THE PROCEDURE DIVISION

TERMINATE
5.9.41

TERMINATE

Function
The TERMINATE statement ends the processing of a report.
General Format
TERMINATE report-name-l [, report-name-2]
Technical Notes
1.

Each report-name must be defined by an RD entry in the REPORT
SECTION of the DATA DIVISION.

All control footings associated with the report are produced
as if a control break had occurred at the highest level.
In
addition, the last PAGE FOOTING and any REPORT FOOTING report
groups are produced.

A second TERMINATE statement for a particular report can not
be executed until another INITIATE statement is executed for
that report.

The TERMINATE statement does not close the file associated
with the report;
a CLOSE statement must be executed after
the TERMINATE statement is executed.

5-97

THE PROCEDURE DIVISION

TRACE
5.9.42

TRACE

Function
The TRACE statement causes the compiler to generate calls to COBDDT.
This allows you to trace paragraphs or to stop tracing paragraphs at
run time.
When a paragraph is traced, its name,
enclosed in angle
brackets «», is typed each time that the paragraph is entered.
General Format
TRACE

~~F 1

{

MR-S-1078-81

Technical Notes
1.

You must load COBDDT with your program to be able to use
trace
facility.
(Refer
to Section 7.3.1,
Loading
Starting COBDDT, for more information.)

The compiler generates trace calls for each paragraph in the
program if the IP switch is not included in the command
string.
If the IP switch is included in the command string,
the trace calls are not generated.

Although the compiler generates trace calls when the IP
switch is not present, tracing is not performed unless you
include the TRACE ON statement in your program
(or specify
the TRACE ON statement to COBDDT).

The TRACE ON statement causes all ensuing paragraphs to be
traced;
that
is,
their names, enclosed in angle brackets
«», are typed each time they are entered.
Tracing
continues until either
the end of program is reached or a
TRACE OFF statement is encountered
(or
is specified to
COBDDT) .

The TRACE OFF statement stops tracing of all
ensuing
paragraphs until either
the end of program is reached or a
TRACE ON statement
is encountered
(or
is specified to
COBDDT} .

5-98

the
and

THE P~OCEDURE DIVISION

TRACE (Cont.)
6.

When compiling for a production run, you should include the
IP switch in the command string so that trace calls are not
generated and TRACE statements in the program are ignored.
The following example shows paragraphs with TRACE OFF and
TRACE ON statements included.
PROCEDURE DIVISION.
PARA.

TRACE ON.
PARB.

TRACE OFF.
PARCo

TRACE ON.
PARD.

Paragraphs PARB and PARD are traced. Paragraph PARC is not
traced
because
the
TRACE
OFF statement is included
immediately before it. If the IP switch is included in the
command string when this program is compiled, the TRACE
statements are ignored and trace calls are not generated.

5-99

THE PROCEDURE DIVISION

UNSTRING

5.9.43

UNSTRING

Function
The UNSTRING statement is used to split a single data item (for
example,
text string) into several parts, depending on the occurrence
of specified delimiters, and to store the parts into separate data
items where they can be more easily accessed by the COBOL program.
General Format
UNSTRING

identifier-l

INTO ,identifier-4

[,DELIMITER

i<ientifier-5J [,COUNT

i dent ifi er-8 ] [ • COUNT

identifier-6 ]

[ • i dent i fi er-7

[ . DELIMITER

[WITH

POINTER

identifier-lO

J[TALLYING IN identifier-ll ]

[,ON

OVERFLOW

statement-I]

i dent i fi er-9 ] ]

...

MR-S-1 079-8 1

Technical Notes
1.

Source Items
a.

The data item referenced by identifier-l is called the
source item.
The source item must be a DISPLAY-6,
DISPLAY-7, or DISPLAY-9 data item. A numeric source item
is moved to an intermediate unsigned numeric data item of
the same size according to the rules for
numeric
transfers and then treated as alphanumeric.

If subscripting or indexing is needed to identify the
source,
the values of the required subscripts and/or
indexes and the depending items, if any,
just prior to
the execution of the UNSTRING statement are used.

Destination Items
a.

The
data
items
referenced
by
identifier-4,
identifier-7, ••• ,
are
called
destination
items.
Destination items can be any kind of data items.

5-100

THE PROCEDURE DIVISION

UNSTRING (Cont.)
b.

If subscripting or indexing is needed to identify a
destination item, the values of the required subscripts
and/or indexes and the depending items, if any, just
prior to the transfer of data to that destination item
are used.

Delimiter Items
a.

The
data
items
referenced
by
identifier-2,
identifier-3, ••. , are called delimiter data items.

A numeric delimiter item is moved to an intermediate
unsigned numeric data item of the same size as the
delimiter and whose USAGE is the same as that of
identifier-l according to the rules for numeric transfers
and then treated as alphanumeric.

If subscripting or indexing is needed to identify a
delimiter
data
item,
the values of the required
subscripts and/or indexes and the depending items, if
any,
just prior to the transfer of data to each
successive destination item are used.

Literal-I, literal-2, •.. , are called delimiter literals.
Delimiter literals must be alphanumeric literals or
alphanumeric figurative constants
without
the
ALL
modifier.

If a delimiter literal is a figurative constant, it
refers to a single-character literal of the specified
type.

If a delimiter data item or a delimiter literal is
specified, the contents of the data item or the value of
the literal is a delimiter string for the source.

If more than one delimiter item is specified, the
delimiter items are separated by the connective OR. In
this case, the several delimiter strings are ordered by
the order in which the delimiter items specifying them
occur in the UNSTRING statement.

If the ALL phrase is specified with a delimiter item, the
delimiter string that that item specifies is considered
to consist of as many occurrences of that
simple
delimiter string as can be found contiguously stored in
the source.

A delimiter condition is an occurrence in the source of a
character string, not contained in the portion of the
source that has already been scanned, that matched one of
the delimiter strings, or the rightmost boundary of the
source.

5-101

THE PROCEDURE DIVISION

UNSTRING (Cont.)
4.

Delimiter Storage Items
a.

A DELIMITER IN phrase can be specified
DELIMITED BY phrase is specified.

the

The
data
items
referenced
by
identifier-5
identifier-8 are called delimiter storage items.

and

If subscripting or indexing is needed to identify a
delimiter storage item, the values of the required
subscripts and/or indexes and the depending items, if
any,
just
prior to the transfer of data to the
destination item corresponding to that delimiter storage
item are used.

only

Count Storage Items
a.

The
data
items
referenced
by
identifier-6
and
identifier-9 are called count storage items.
Count
storage items must be unedited integer data items of
sufficient length to contain a value equal to the length
of the source.

If subscripting or indexing is needed to identify a count
storage item, the values of the required subscripts
and/or indexes and the depending items,
if any,
just
prior to the transfer of data to the destination item
corresponding to that count storage item are used.

A count storage item is used to store the number of
characters of the source that were examined during the
execution of the UNSTRING statement and approved for
transfer to the destination corresponding to that count
storage item.

NOTE
This is not necessarily the same as the number of
characters
that
were
actually transferred,
because the destination can be too small to hold
all that were approved for transfer.

Pointer
a.

The data item referenced by identifier-IO is called the
pointer.
The pointer must be an unedited integer data
item of sufficient size to contain a value one greater
than the size of the source.

The pointer serves as a character index for the source.

If subscripting or indexing is needed to identify the
pointer, the values of the required subscripts and/or
indexes and the depending items, if any,
just prior to
the execution of the UNSTRING statement are used.

5-102

THE PROCEDURE DIVISION

UNSTRING (Cant.)

If the POINTER phrase is specified,
the pointer
is
directly available to you.
It must be initialized before
the execution of the UNSTRING statement to a value
greater
than zero and not greater than the size of the
source.

If the POINTER phrase is not specified,
the UNSTRING
statement is always executed as if you have specified a
pointer and set the initial value to 1.
In this case,
the pointer is not directly available to you.

Destination Counter
a.

The data item referenced by identifier-II is called the
destination counter.
The destination counter must be an
unedited integer data item of sufficient size to contain
a
value equal
to the number of destination items
specified in the UNSTRING statement.

The destination counter is used to store the number of
destination item~ to which data was transferred by the
execution of the UNSTRING statement.

If subscripting or indexing is needed to identify the
destination
counter,
the
values
of the required
subscripts and/or indexes and the depending
items,
if
any,
just prior
to the execution of the UNSTRING
statement are used:'

If the TALLYING phrase is specified,
the destination
counter
is directly available to you, and it must be
initialized before the execution
of
the
UNSTRING
statement.

If the TALLYING phrase is not specified,
the UNSTRING
statement is always executed as if you had specified a
destination counter and set the initial value to O.
In
this case,
the destination counter
is not directly
available to you.

Execution
a.

The execution of the UNSTRING statement is an iterative
process.
There is one iteration for each destination
item specified in the UNSTRING statement,
starting with
the first destination item specified and continuing in
order through the series of destination items.
However,
the iteration process is stopped after all the data in
the source has been used, even if not all destination
items have been used.
During execution of the UNSTRING
statement, the pointer and an increment to be added to
the destination counter are kept in temporary locations.
At the start of execution of the UNSTRING statement,
the
real pointer
is stored in the temporary pointer and the
temporary destination count is set to zero.
When it
becomes necessary to move these items to the real pointer
and real destination items, the internal pointer is moved
into the real pointer, the internal destination counter
is added to the real destination counter,
and the
internal destination counter is set to zero again.

5-103

THE PROCEDURE DIVISION

UNSTRING (Cent.)
b.

Each iteration of the process involved in the execution
of the UNSTRING statement consists of the following
steps:
1.

Select a set of characters from the source.

If the destination item, delimiter storage item, or
count storage item is subscripted, store the internal
pointer into the real pointer item and update the
real destination counter.

Move a representation of these characters
destination item for that iteration.

Move some characters to the delimiter storage item
corresponding to that destination item, if one is
specified.

Set the count storage item corresponding
destination item, if one is specified.

Advance the internal pointer
position in the source.

Increment the internal destination counter.

indicate

the

that
a

new

During the execution of the UNSTRING statement, the
source is treated as if it were a table of single
character data items indexed by the pointer.
The
character
position of the source indicated by the
pointer, during each iteration of the UNSTRING process,
is
called
the pointer-indicated position for that
interation. Only the pointer-indicated position for an
iteration and those source character positions to its
right are used during
that
iteration.
Character
positions to the left of that position are not involved
in that iteration in any way.

During each iteration of the UNSTRING process, a scan of
the source is done to determine which characters of the
source are selected as the character set to be moved to
the appropriate destination item. This scan begins at
the pointer-indicated position and continues to the right
in the source.

When the source is scanned, certain conditions are
detected depending on whether or not the DELIMITED BY
phrase is specified.
1.

If the DELIMITED BY phrase is specified, the scan
ends when either of the following conditions occurs:
a.

A string of contiguous characters in the source
that matches one of the delimiter strings is
found.

The rightmost boundary of the source is found.

5-104

THE PROCEDURE DIVISION

UNSTRING (Cont.)
2.

When the DELIMITED BY phrase is not specified,
the
scan ends when either of the following conditions
occurs:
a.

A number of characters sufficient
fill the destination is found.

completely

The rightmost boundary of the source is found.

When the scan ends, the set of characters to be moved
the destination item is known.

The source scan proceeds in one of two ways depending
whether or not the DELIMITED BY phrase is specified.

If the DELIMITED BY phrase
proceeds as follows:

specified,

the

scan

Each character position of the source, starting
at the pointer-indicated position and continuing
to the right, is first checked to see if any
source
character-string
beginning
at
that
position matches the delimiter-string specified
by the first delimiter
item in the UNSTRING
statement.
If such a string is found,
condition
a of Note el is satisfied.

If no such string is found,
the same character
position is then checked to see if any source
character-string beginning at
that
position
matches the second specified delimiter-string.
This process is repeated using each successive
delimiter-string until either condition a of Note
el is satisfied or all specified delimiters have
been tried.

If condition a of Note el is not satisfied for
the source character position under consideration
and one of the specified delimiter-strings,
that
character position is then selected as part of
the source to be moved to the current destination
item.

The above process continues until no more source
character positions remain (condition b of Note
el) .

If the DELIMITED BY phrase is not specified,
the
source scan proceeds until one of the following
conditions occurs:
a.

Enough successive character positions of the
source have been selected to entirely fill the
destination item (conditon a of Note e2).

No more source
character
(Condition b of Note e2).

5-105

positions

remain

THE PROCEDURE DIVISION

UNSTRING (Cont.)
g.

During each iteration of the UNSTRING process, the set of
contiguous source character positions selected by the
process described
in Note f
is considered to be a
complete
individual data item,
and
is moved to the
current destination item according to the rules for
the
MOVE statement,
including any class of usage conversion
that might be necessary.
You should note that truncation
or fill can occur during the execution of the MOVE.
This
data item might contain no character positions at all
if
the pointer-indicated position satisfied condition a of
Note el or it can contain as much as the entire source.

If a count storage item is specified with the destination
item for an iteration of the UNSTRING process, the number
of source characters that were examined during
the
execution of
the UNSTRING statement and approved for
transfer to the destination item is stored in that count
storage item.

If there is a delimiter storage
item specified for
particular iteration of the UNSTRING process, then:
1.

If the selection of source character
positions
described in Note f is terminated because condition a
of Note el, the string of contiguous source character
positions that contain the match for a delimiter
string is treated as a complete individual data
item
and
is moved to the delimiter storage item according
to the
rules for
the MOVE statement,
including
truncation if necessary.
If, in this case,
the delimiter
string that was
matched
is described with the ALL phrase, the set of
source character positions containing a match for the
simple
delimiter
string,
plus every immediately
succeeding set of
contiguous
source
character
positions containing a match for the same delimiter
string, are used in the data item that
is moved
to
the delimiter storage item.

If the selection of source character
positions
described
in
Note f
is terminated because of
condition b of Note el,
spaces are moved to
the
specified delimiter storage item.

In an
iteration of the UNSTRING process,
after
the
appropriate data has been stored in the destination item,
the delimiter storage item, and the count storage
item,
the pointer
is set to a value one more than the ordinal
number of
the last source character position
that
participated in the selection process.
This includes all
character positions that were selected as part of the
source to be moved to the destination item and, if a
DELIMITED BY phrase is specified, all character positions
that were used
in the successful match of a delimiter
string.

5-106

THE PROCEDURE DIVISION

UNSTRING (Cont.)
k.

At the conclusion of execution of the UNSTRING statement,
the
real destination counter is updated using the
internal destination ~ounter and the internal pointer is
stored into the real pointer.

Overflow
a.

If the initial value of the pointer is less than one or
greater than the size of the source, execution of the
UNSTRING statement is aborted before any
data
is
transferred,
the real pointer's value is unchanged, and
the UNSTRING statement is considered to have caused an
overflow.

If, during the execution of an UNSTRING statement, data
has been transferred to all of the destination items in
accordance with Note g, but the updated pointer still
contains a value less than or equal to the size of the
source
(that is,
not all of the source
character
positions have been used in the UNSTRING process), the
UNSTRING statement is considered to have caused an
overflow.

If the ON OVERFLOW phrase is not specified,
after
the
execution
of the UNSTRING statement,
regardless of
whether or not there was an overflow, control passes to
the point in the program immediately following
the
UNSTRING statement.

If the ON OVERFLOW phrase is specified,
after the
transfer of characters has ended and the pointer and
destination counter are set to the appropriate values,
the flow of Gontrol of the program depends on whether or
not there was an overflow.
1.

If an overflow did not occur, control passes to the
point in the program corresponding to the end of the
sentence containing the UNSTRING statement (following
all the statements in the ON OVERFLOW phrase) .

If an overflow did occur, control passes to the point
in the program corresponding to the beginning of
statement-I.

5-107

THE PROCEDURE DIVISION

UNSTRING (Cent.)
Example
DATA DIVISION.

01
01

INPUT-DATE PIC X(12).
DATE-FIELDS.
03 DAY
PIC XX.
03 MONTH PIC XXX.
03 YEAR PIC XX.

PROCEDURE DIVISION.

UNSTRING INPUT-DATE DELIMITED BY ALL "_"
INTO DAY MONTH YEAR.

STOP RUN.

This example assumes that the input date is in the form
"Ol-JAN-Sl".
If the day and year are to be used as
numerics, they have to be moved to fields which are
justified right.
Also, if the month is to be converted
to numeric, this must be done by means of a table search.

5-108

THE PROCEDURE DIVISION

USE
5.9.44

USE

Function
The USE statement specifies procedures for
error handling that are in addition to
provided.

input-output label and
the standard procedures

General Format

Format 1:

USE AFTER STANDARD ERROR PROCEDURE ON

fi 1e-name-l
INPUT
OTITPUT
{ 1-0
INPUT-OUTPUT

Format 2:

USE

BEFORE } STANDARD
{ AFTER

[{ BEGINNING}]
ENDING

LABEL

{~~ame-l ~

PROCEDURE ON

[{

~ic~
}]
UNIT

}

1-0

TNPUT-OUTPUT

Format 3:
USE

BEFORE REPORTING

identifier-l

MR-S-10BO-B1

Technical Notes
1.

USE statements can appear only in the DECLARATIVES portion of
the PROCEDURE DIVISION.
The DECLARATIVES portion follows
immediately after the PROCEDURE DIVISION header and begins in
A-margin with the word
DECLARATIVES.

5-109

THE PROCEDURE DIVISION

USE (Cont.)
The DECLARATIVES portion ends in A-margin with the words
END DECLARATIVES.
Following this must be a section-header as the first entry of
the main portion of the PROCEDURE DIVISION.
The DECLARATIVES portion itself consists of USE sections,
each consisting of a section-header,
followed by a USE
statement, followed by the associated procedure paragraphs.
The general format for
below:

the

DECLARATIVES

portion

given

PROCEDURE DIVISION.
DECLARATIVES.
section-name-l SECTioN. USE ..... .
paragraph-name-la. (statement)
[paragraph-name-lb. (statement)]
[section-name-2 SECTION. USE ...... ]

END DECLARATIVES.
section-name-m SECTION.
2.

The USE statement can follow on the same line as the
section-header and must be terminated by a period followed by
a space. The remainder of the section must consist of one or
more procedural paragraphs that define the procedures to be
used.

The USE statement itself is never executed, rather it defines
the
conditions
calling for
the execution of the USE
procedures.

The designated procedures are
time as follows:

executed

the

appropriate

Format 1 causes the designated procedures to be executed
after completing the standard input-output error routine.
This provides the ability to continue a program on an I/O
error
if it would have otherwise failed.
Refer to the
FILE-STATUS clause in Chapter 3 for details of specifying
a FILE-STATUS action code.

Format 2 causes the designated procedures to be executed
at one of the following times, depending upon the options
used.
1.

Before or after a beginning or
check procedure is executed.

Before a beginning ~r ending output label is created.

5-110

ending

input

label

THE

PROCEDU~E

DIVISION

USE (Cont.)

After a beginning or ending output label is
but before it is written on tape.

Before or after a beginning or ending
label check procedure is executed.

created,

input-output

Format 3 causes the designated procedures to be executed
just prior to the production of the named report group.

There must not be any reference to any non-DECLARATIVES
procedure within a USE procedure.
Conversely, there must be
no reference
to procedure-names that appear within the
DECLARATIVES portion in the non-DECLARATIVES portion, except
that PERFORM statements can refer to a USE section or
to a
procedure contained entirely within such a USE section.

No input/output can be performed, other than use of ACCEPT
and DISPLAY statements, during execution of a USE procedure.

Format I causes the associated procedures to be executed
after
the standard
input-output error
routine has been
executed.
If the INPUT option is used,
the procedures are
executed for all INPUT files;
if the OUTPUT option is used,
they are executed for all OUTPUT files;
if the 1-0 or
the
INPUT-OUTPUT option
is used,
they are executed for all
INPUT-OUTPUT files;
if the filename-l option is used,
they
are
executed
only for
that particular
file.
If the
filename-l option is used and any other option is used (i.e.,
INPUT,
OUTPUT,
INPUT-OUTPUT) ,
the file
named
in the
filename-l option cannot be opened in the
form that is
specified
in the other error procedure.
For example, if you
specify two error procedures, one for INPUT and the other for
filename-I, filename-l cannot be opened for INPUT;
it can be
opened for OUTPUT or INPUT-OUTPUT.
If the filename-l OPEN option is used,
the system performs
the associated procedures only if a "FILE BEING MODIFIED"
error occurs when an attempt is made to open an output file.
After performing
the procedure,
the system automatically
tries again to open the file, repeating
this process until
the file
is opened.
This option allows you to suspend your
job until
it can access a
file
that another
user
is
modifying.

Format 2 causes the associated procedures to be executed at
the appropriate
times, as indicated by the options selected
(see note 4).
If the words BEGINNING or
ENDING are not
included in Format 2, the designated procedures are executed
for both the beginning and ending labels.
If neither
UNIT,
REEL,
nor
FILE
is
included, the designated procedures are
executed for both REEL (or UNIT) labels and for FILE labels.
If the
INPUT,
OUTPUT,
INPUT-OUTPUT,
or
1-0 option
is
specified,
the label procedure applies to every file of that
type except files described as LABEL RECORDS ARE OMITTED.
If the file-name-l option is used, its file description
not contain a LABEL RECORDS ARE OMITTED clause.

5-111

must

THE PROCEDURE DIVISION

USE (Cont.)
9.

within a given format, a file~name must not be referred to,
either
implicitly
(that
is,
by
an
INPUT, OUTPUT,
(that is,
by a
INPUT-OUTPUT, or 1-0 option) or explicitly
file-name-l option), in more than one USE statement.

10.

Identifier-l in Format 3 represents a report group named
in
the REPORT SECTION of the DATA DIVISION. An identifier must
not appear in more than one USE statement. The report group
must not be TYPE DETAIL.

5-112

THE PROCEDURE DIVISION

WRITE
5.9.45

WRITE

Function
The WRITE statement transfers a logical record to an output file.
General Format

Format 1:
WRITE record-name-l [FROM ~igUr~t~ve-constant]
-- - ldentlfler-l
identifier-2 LINES!]
BEFORE} ADVANCING intege~-l LINES
{ AFTER
mnemonlc-name
PAGE

[

Format 2:
WRITE record-name-l [FROM ~igUr~t~ve-constant]
- - ldentlfler-l
AFTER POSITIONING {~dentifier-2} LINES
lnteger-l

Format 3:

~ record-name-l [ERQM ~igUr~t~ve-constant]
1 dent 1 f 1 e r-l
INVALID KEY statement-l [,statement-2]
MR-S-1081-81

Technical Notes
1.

An OPEN OUTPUT or OPEN I-O or OPEN INPUT-OUTPUT statement
must be executed for the file prior to the execution of the
WRITE statement.

After the WRITE is executed, the data in record-name-l is
longer be available.

Record-name-l must be the name of a logical record in a DATA
RECORDS clause of the FILE SECTION of the DATA DIVISION.

5-113

THE PROCEDURE DIVISION

WRITE (Cont.)
4.

Option 1 is valid for any file currently open for
output,
with ACCESS MODE IS SEQUENTIAL. The ADVANCING clause allows
control of the vertical positioning of the paper
form for
print files as follows:

If the ADVANCING clause is not
recording mode
is ASCII,
BEFORE
assumed.

If identifier-2 or
integer-l is specified,
it must
represent a positive integer or
zero.
The form is
advanced the number of lines equal to the value of
identifier-2 or integer-I.

If mnemonic-name is specified, the form is advanced until
the specified channel
is encountered on the paper-tape
format control loop.
Mnemonic-name must be defined by a
CHANNEL clause
in the SPECIAL-NAMES paragraph of the
ENVIRONMENT DIVISION.

If the BEFORE option is used,
before the form positioning.

If the AFTER option is used, the record is printed after
form positioning occurs,
and no form positioning takes
place after the printing.

the

specified
ADVANCING

record

and
the
1 LINE is

printed

If end-of-reel is encountered while writing on magtape,
WRITE statement performs the following operations.

the

Your ENDING LABEL PROCEDURE is executed, if specified
a USE statement.

A file mark is written, and the tape is rewound.

If the file was assigned to more than one tape unit,
units are advanced.

A label is written on the new tape,
if labels are not
OMITTED, and your BEGINNING LABEL PROCEDURE is executed.

Option 2 is valid for any file currently
with ACCESS MODE IS SEQUENTIAL.

open

for

the

output,

The POSITIONING clause allows control of the
vertical
positioning of the paper form for print files.
The record is
written after the printer page is advanced according
to the
following rules.

5-114

THE PROCEDURE DIVISION

WRITE (Cont.)
a.

If identifier-2 is specified, it must be described as a
I-character alphanumeric item;
that is, with PICTURE X.
The valid values that identifier-2 can contain and their
interpretations are as follows.
blank

+
1-8

Single-spacing
Double-spacing
Tr iple-spa"c ing
Suppress spacing
Skip to channels 1 through 8 respectively
on the paper-tape format control loop

Note that LIBOL interprets the values
in identifier-2,
substituting the proper positioning characters into the
ASCII file.
The character stored in the field named
identifier-2 is not stored in the output file.
b.

If integer-l is specified, it must be unsigned, and must
be one of the values 0, 1, 2, or 3.
The values have the
following meanings.

o
1
2
3

Skip to channell of next
control "eject")
Single-spacing
Double-spacing
Triple-spacing

page

(carriage

Either ADVANCING or POSITIONING can be specified for a file,
but not both.
Also, if either is specified, the recording
mode of the file is ASCII, regardless of the recording mode
specified in the RECORDING MODE clause.

Option 3 is valid only for random-access files whose access
mode is RANDOM or INDEXED.
The imperative-statement(s) in
the INVALID KEY clause of a RANDOM file is executed when an
attempt is made to execute a WRITE to a segment outside the
range of the FILE-LIMITS of the file.
When a WRITE statement is executed for a
file whose access
mode is RANDOM and the ACTUAL KEY contains a value of 0,
records are written sequentially in the file
(that is,
no
records are left null).
If the previous operation performed
on the file was by a READ statement, the previous record
is
replaced (that is, the record is updated).
When a WRITE statement is executed for a
file whose access
mode is INDEXED,
the contents of the SYMBOLIC KEY item are
moved to the RECORD KEY item and the record is written.
The statement(s) in the INVALID KEY clause is executed when
the SYMBOLIC KEY contains a value equal to the key of an
already existing record in an INDEXED file
(refer
to the
REWRITE statement).

5-115

THE PROCEDURE DIVISION

WRITE (Cont.)
8.

When executing a WRITE statement for a SEQUENTIAL file opened
for
1-0
(or
INPUT-OUTPUT), the logical record is placed on
the file as the next logical record,
if the previous
input-output operation was a WRITE,
or
it replaces the
previous record, if the previous input-output operation was a
READ.

If the FROM option is used, the statement is equivalent to:
MOVE identifier-l TO record-name-l
WRITE record-name-l (without the FROM option)

5-116

CHAPTER 6
COMPILING COBOL-68 PROGRAMS

Compiling COBOL-68 programs consists of running the COBOL-68 compiler
and typing the correct command string in response to the prompt. To
run COBOL and compile your program(s), type R COBOL in response to the
TOPS-IO prompt (.) or COBOL in response to the TOPS-20 prompt (@).
That is,
.R COBOL

for users of TOPS-IO

or
@COBOL

for users of TOPS-20

The general form of the compiler command string is as follows:
relfil,lstfil= libfil/L, srcl, libfil/L, src2, •.•
where:
relfil

is the file that is to hold the generated code.
If
no
generated code is desired, the file
description for relfil is replaced by a hyphen.
Example:

lstfil

-,lstfil=srcl,src2 ••.

is the file that is to hold the generated listing.
If no listing is desired, the file description for
lstfil is replaced by a hyphen.
Example:

relfil,-=srcl,src2, .••

libfil

is an optional library file referenced by COpy
verbs in the source files. For each source file
specified, only one library file opens at once.
Thus, you can specify more than one library for a
source file, but only the last-specified one is
used.

srcl,src2

are one or more source files required to form
complete input program.

one

Each file description has the following form:
device: file.ext [project,programmer] /switch/switch
where:
device

is the name of a physical or logical device.
The name is composed of 6 or fewer letters
and/or digits.
6-1

COMPILING COBOL-68 PROGRAMS
file

is the name of a file.
The name is
of 6 or fewer letters and/or digits.

composed

ext

is the filename extension.
It is composed
3 or fewer letters and/or digits.

project

is a user's project number.

programmer

is a user's programmer number.

switch

is any of the switches shown in Table 6-1.

Users of TOPS-20 who wish to specify a directory other than the
default can run the TRANSLATE program to determine the correct
project-programmer number.
(See the TOPS-20 User's
Guide
for
information on how to do this.) For an alternative which is generally
more useful, see Appendix C, Defining Logical Names under TOPS-20.
Certain default assignments are made by the compiler whenever
are omitted from the command strings or the file descriptions.

terms

If the device is omitted in any output file description, DSK
is assumed.
If the device is omitted in an input file
description, either the preceding device or DSK
(if no
preceding device is specified) is assumed.

If the filename for relfil and/or lstfil
filename of the first source file is used.

If the filename extension is omitted from relfil,
.REL is
assumed;
if it is omitted from lstfil, .LST is assumed.
If
the extension is omitted from the source file descriptor, the
compiler looks in the file area for the named file with the
extension .CBL.
If that file
is not found,
the compiler
looks for
the named file with the extension .COB.
If that
file is not found, the compiler looks for
the named file
without an extension.
If the extension is omitted from the
library file description, .LIB is assumed.

If the project-programmer option is omitted on any file, your
default path is used.
On TOPS-20, the connected directory is
used.

omitted,

the

Examples:
MTA1:RELOUT.A/W,LPT:=DSK:SRCIN.C [27,36]/M/S
The compiler compiles the program found in the file SRCIN.C in the
area reserved for project-programmer [27,36].
It treats columns 1-6
of the source as a sequence number
(/S).
The generated code is
written on MTAl, after
the tape is rewound
(/W). The listing,
including maps (/M) is put on the LPT.
=LIBl/L,PROG/A
The compiler compiles the program found in PROG.CBL
(CBL is assumed
because the filename extension is omitted from the source file
descriptor) on the disk, using LIBl.LIB whenever a COpy verb is seen
(/L) .
The generated code goes into the file DSK:PROG.REL, and the
listing onto the file DSK:PROG.LST.
The generated code is listed
(/A) •

6-2

COMPILING COBOL-68 PROGRAMS
-=LIBI/L,PROG/A
This is identical to the preceding example, with the exception that no
generated code is produced because the file descriptor for the file
has been replaced by a hyphen.
If you wish to produce the
.REL file
but not the .LST file, you should add a comma to the command string,
as follows:
,-=LIBI/L,PROG/A
The following table shows the switches that can be used
COBOL-68 programs.

compiling

Table 6-1
COBOL Switch Summary
Switch

Action by Compiler

List the MACRO reproduction
code in the lstfil.

Produce
a
cross-reference
user-defined symbols.

all

D:nnnnnn

Increment, in octal words, that is to be
to the object-time push down list size.

added

Check program for errors, but
code.

Type description of COBOL-68 command strings and
switches.

Suppress output of start address (program is
be used only by CALLs) .

Force output of start address in
presence of subprogram syntax.

the

Use the preceding source file as a library file
whenever a copy verb is encountered.
If the
first source file is not a /L file,
LIBARY.LIB
is used as the library file until the first /L
file is encountered.
(The default extension for
library files is .LIB.)

Include a map
lstfil.

Do not type compilation errors on your terminal.

Optimize the object code.

Production mode.
relfil.

Omit debugging

features

from

Quick mode.
Do not range check
turn on /0 and /P.

PERFORMs,

also

6-3

your

the
table

defined

not

spite

items

generated

generate

the

COMPILING COBOL-68 PROGRAMS
Table 6-1 (Cont.)
COBOL Switch Summary
Switch

Action by Compiler

Produce a two-segment object program. The high
segment contains the Procedure Division;
the
low segment all else.

The source file
is in "conventional" format
(with
sequence numbers in columns 1-6 and
comments starting in column 73).

Produce a one-segment object program.
the default for TOPS-ID.

Rewind the device before
(magnetic tape only).

Give a usage of DISPLAY-9 to items whose
is either omitted or declared as DISPLAY.

usage

Zero the directory of the device before
(DECtape only).

writing

6-4

reading

This
or

writing

CHAPTER 7
COBOL UTILITY PROGRAMS

COBOL provides several utility programs that allow you to perform
certain operations within your COBOL program. These utility programs
are:
•

ISAM

- Indexed-Sequential File Maintenance Program
ISAM provides you with the ability to create and
maintain indexed-sequential files (see section 7.1).

•

LIBARY - Source Library Maintenance Program
LIBARY provides you with the facility to create,
modify, and delete statements or groups of statements
in a library file (See Section 7.2).

•

COBDDT - Program For Debugging COBOL Programs
COBDDT provides you with the ability to:

•

RERUN

Look for areas of error by setting breakpoints

Trace the activity of procedures

Display and, if necessary, change the contents of
data-items

Determine time spent in sections of the program
by analyzing a histogram (see Section 7.3)

- Program to Restart COBOL Programs
RERUN provides you with the ability to restart a
COBOL program after an abnormal termination has
occurred (See Section 7.4).

7-1

COBOL UTILITY PROGRAMS

NOTE
Many of the examples in this chapter are
written for only one operating system that is, they have either
the TOPS-IO
prompt
(.)
or
the TOPS-20 prompt (@)
alone.
However,
unless you are told
otherwise,
the examples apply to both
TOPS-IO and TOPS-20.
Thus,
in this
chapter you can substitute
.R (program

name)~

for
@(program

name)~

and vice versa.

7.1

ISAM -

INDEXED-SEQUENTIAL FILE MAINTENANCE PROGRAM

Indexed-sequential files are created, maintained,
and compacted for
backup storage by means of the
ISAM program.
ISAM performs the
following functions:
1.

Builds an indexed-sequential file from a sequential file

Maintains an indexed-sequential file by reorganizing it

Packs an indexed-sequential file into a sequential
backup storage

ISAM has the following switches that you
functions:

I
I

use

for

perform

these

Advance between records according to the mode specified
switch can be used only with the P switch)

(this

Build an indexed file from a sequential one

Check an indexed file for errors

Ignore errors in packing a file
with the P switch)

Read or write standard tape labels (this switch
only with the B or P switches)

Maintain an indexed file by reorganizing it

Pack an indexed file for backup storage

Rename an indexed file

Provide statistics on blocking factors
used only with the B switch)

7-2

can

file

(this switch can be used

(this

can

switch

can

only
used

COBOL UTILITY PROGRAMS
Figure 7-1 shows the COBOL ISAM File Environment.
(INPUT SEQUENTIAL
DATA FILE)

R ISAM
(BUILD)

.-------,

R ISAM

RUN
MYPROG

(MAINTAIN)

(USER'S APPLICATION PROGRAM)

'ISAM

(PACK)

(OUTPUT SEQUENTIAL
BACKUP FILE)

Figure 7-1

7.1.1

COBOL ISAM File Environment

Building An Indexed-Sequential File

To build an indexed-sequential file you provide a sequential file
in
which the record keys are arranged in ascending order. The ISAM
program uses this file to create an indexed-sequential data file with
a user-specified number of empty records and blocks.
ISAM then
creates the index file according to the description of the data file.
To run the ISAM program and select the option
indexed-sequential file, type the following:

ISAM~

for

building

the

for users of TOPS-IO
or

@ISAM~

for users of TOPS-20

*devl:indfil.ext[ppnl] ,dev2:datfil.ext=dev3:seqfil.ext[ppn2]/B~
where:
devl, dev2, and dev3 are the devices for the index, data, and input
sequential file.
devl and dev2 must be disk.
The default for
devl, dev2, and dev3 is DSK.
indfil.ext is the name and extension of the
index file.
If the
filename
is not specified, the name of the input file is assumed.
If the extension is omitted, .IDX is assumed.

7-3

COBOL UTILITY PROGRAMS
datfil.ext is the name and extension of the indexed data file.
the filename is omitted, the name of the index file is assumed.
the extension is omitted, .IDA is assumed.

If
If

seqfil.ext is the name and extension of the input sequential file.
This filename must be specified, but the extension can be omitted.
If it is omitted, .SEQ is assumed.
[ppnl], [ppn2] specify directories for the index file and the input
file,
respectively.
If either is omitted, then the directory of
the logged-in user is assumed.
The data file must reside in the
same directory as the
index file.
Users of TOPS-20 who wish to
specify a directory other than the default can run the TRANSLATE
program to determine the correct project-programmer number.
(See
the TOPS-20 User's Guide for information on how to do this.) For an
alternative which
is generally more useful,
see Appendix C,
Defining Logical Names under TOPS-20.
j

/B is the switch signifying that ISAM is used to build an
indexed-sequential file.
If the switch is omitted from the command
string, /B is assumed.
The equal sign (=) can be omitted if the
specifications for the output files are omitted.
Users can build an indexed file without providing a sequential file to
the
ISAM program by specifying that the device on which the
(nonexistent) input sequential file
resides
is NUL:.
Thus,
the
following command produces an indexed file:
TSTFIL,TSTFIL=NUL:TSTFIL/B
After reading the command string, ISAM asks a series of questions,
which are described below.
Every question must be answered.
Mode of input file:
Reply with S, A, F, V, or ST according to the mode of the input file.
S means SIXBIT, A means ASCII, F means fixed-length EBCDIC, V means
variable-length EBCDIC, and ST means STANDARD-ASCII.
Mode of data file:
Specify S, A, F, or V according to the mode in which the ISAM data
file is to be recorded.
S means SIXBIT, A means ASCII, and both F and
V mean EBCDIC, as above.
If the mode of the input file differs from
that of the data file, characters are converted in the same manner as
they are converted in standard COBOL operations.
Maximum record size:
Specify the size of the largest record irt the input file
in bytes.
For ASCII records you should not count the carriage return and line
feed that are appended to each ASCII record.
Key descriptor:
Describe the key upon which the file
is to be indexed.
If your
records are of variable length, you must be sure that the key field
occurs in the fixed portion of the record, or that the key field
is
filled with characters,
in the case of an ASCII text file.
If you
fail to fill the key field in the ASCII file, your key field might be
loaded with a carriage return/line feed pair.

7-4

COBOL UTILITY PROGRAMS
In response to the message from ISAM, you describe the key field using
a code that has the form:
[s]

[x]m.n

where:
s

designates the sign of the key:
S -

the key is signed

U -

the key is unsigned

indicates the key type:

x - the key is nonnumeric
N -

the key is numeric display

C -

the key is COMPUTATIONAL

F -

the key is COMPUTATIONAL-l

P -

the key is COMPUTATIONAL-3

specifies the character position in the record where the
key
begins,
assuming
that the position of the first character in
the record is 1.

specifies the size of the key in characters for types X and N
or in digits for types C and P.
If n is less than or equal to
10 for type C, one word is used.
If n is greater than 10, two
words are used.
n is ignored for type F because it is always
one word long.

The following rules apply to the key descriptor:

The key type is optional;
if S or
U are
default is N.
Otherwise, the default is x.

The key sign is optional;
is not x.

the default is S if the

The sign designators S
conjunction with type x.

m and n must be specified.

cannot

specified,

the

key

type

specified

Records per input block:
Give the blocking factor of the input file.
If the file is
(that is, the file contains ASCII text), enter O.
Total records per data block:

(Recommended

unblocked

= n):

Give the total number of records to be contained in each block of the
indexed data file.
ISAM supplies .the blocking factor that is most
efficient in terms of disk utilization.
If you wish to optimize the
amount of core the object-time system requires to process the file,
you must calculate the blocking factors yourself.
Empty records per data block:

7-5

COBOL UTILITY PROGRAMS
Specify the number of records that are to be initially left
each block of the data file.
Total entries per index block:

(Recommended:

empty

= n):

Specify the total number of index entries to be contained in each
block of the index file.
ISAM supplies the blocking factor that is
most efficient in terms of disk utilization.
If you wish to optimize
the amount of core the object-time system requires to process the
file, you must calculate the blocking factors yourself.
Usually,
a
good blocking factor is a page (or less) of memory, since this allows
the internal swapping algorithms to operate most efficiently.
Empty entries per index block:
Specify the number of index entries that are to be
initially left
empty in each index block.
Note that at least two entries must be
available in each index block, so that the number of total entries
minus the number of empty entries equals or exceeds two.
Percentage of data file to leave empty:
Give a figure that corresponds to the amount of empty space you wish
ISAM to allocate.
This empty space corresponds to completely empty
data blocks, over and above the free space that is allocated on "live"
data blocks.
ISAM figures the total number of data blocks required
for the file, then add the number of blocks which equals the given
percentage of the required blocks.
This procedure helps to prevent
"DISK FULL" crashes.
Percentage of index file to leave empty:
Give a figure that corresponds to the amount of empty space you wish
ISAM to allocate.
ISAM figures
the total number of index blocks
required for the file, then add the number of blocks which equals the
given percentage of the required blocks.
As with the data file, this
procedure helps to prevent "DISK FULL" crashes.
Maximum number of records file can become:
Reply with the maximum number of records the file can contain before
it
is next maintained.
Note, however, that your number is used only
for documentation, since ISAM calculates its own number and uses that
number for allocating storage.
information on the
ISAM supplies you with some
At this point,
The form of the information is as
usage.
efficiency of your disk
follows:
[ISMLOV m Levels of index
[ISMNDR n Data records]
r% wasted space in the Data
words of q.
[ISMWSD wasted p.
file.]
physical disk blocks.]
[ISMLDE One logical Data block equals s.
words of u.
in the Index file.]
[ISMWSI Wasted t.
physical disk blocks.]
[ISMLIE One logical Index block equals v.
[ISMIBS LIBOL's I/O buffer will require w.
words (x.
pages)
of
core.]

7-6

COBOL UTILITY PROGRAMS
Example - Building an indexed-sequential file
.R ISAM
*TEST.IDX,TEST.IDA=TEST.SEQ/B
Mode of input file: SIXBIT
Mode of data file: SIXBIT
Maximum record size: 240
Key descriptor: X129.29
Records per input block: 10
Total records per Data block: (Recommended: 53): 25
Empty records per Data block:
Total entries per Index block: (Recommended: 18):
Empty entries per Index block:
Percentage of Data file to leave empty:
Percentage of Index file to leave empty:
Maximum number of records file can become: 10000
[ISMLOV 2 Levels of index]
[ISMNDR 500 Data records]
[ISMWSD Wasted 127. words of 1152. 11.0% wasted space in
the Data file.]
[ISMLDE One logical Data block equals 9. physical disk
blocks.]
[ISMWSI Wasted o. words of 128. in the Index file.]
[ISMLIE One logical Index block equals 1. physical disk
blocks.]
[ISMIBS LIBOL's I/O buffer will require 2816. words (6.
pages) of core.]

7-7

COBOL UTILITY PROGRAMS
7.1.2

Maintaining An Indexed-Sequential File

The ISAM program allows you to maintain an existing
ISAM file after
the file has become crowded.
More empty space can be added to the
file and the number of index levels can be decreased.
That is,
the
files are rearranged and indexes are streamlined.
The input is the
indexed-sequential file and the output is a
new indexed-sequential
data and index file.
The command string for the ISAM maintain option
is as follows:
.R

ISAM~

for users of TOPS-IO
or

@ISAM~

for users of TOPS-20

*devl:indfil.ext[ppnl] ,dev2:datfil.ext=infil.ext[ppn2]/M~
where:
devl, and dev2, are disk devices on which the files
If any of the devices is omitted, DSK is assumed.

are

stored.

indfil.ext is the name and extension of the new index file.
the name is omitted, the name of the input file is assumed.
the extension is omitted, .IDX is assumed.

If
If

datfil.ext is the name and extension of the new indexed data
file.
If the name is omitted, the name of the new index file is
assumed.
If the extension is omitted, .IDA is assumed.
infil.ext is the name and extension of the index file of the old
indexed-sequential file.
The name of the file must be specified,
but the extension can be omitted.
No extension is assumed if the
extension is omitted.
[ppnl], [ppn2] specify directories for the new index file and the
old
index file,
respectively.
If either
is omitted,
the
directory of the logged-in user is assumed.
The new data file
must reside in the same directory as the new index file.
Users
of TOPS-20 who wish to specify a directory other than the default
can
run
the
TRANSLATE program to determine the correct
project-programmer number.
(See the TOPS-20 User's Guide for
information on how' to do this.)
For an alternative that is
generally more useful, see Appendix C,
Defining Logical Names
under TOPS-20.
1M is the switch indicating that the maintain
requested.
The switch must be specified.
If the output file specifications are not
string, the equal sign (=) can be omitted.

included

option
in

the

being
command

After the command string has been scanned,
ISAM asks a series of
questions about values for the new indexed-sequential file.
The mode
of the file, the record size, and the key cannot be changed.
The
values from the old file are given in parentheses with the question.
If you wish to change a value, enter the new value;
if you do not
wish to change a value, press the RETURN key.
All questions refer to
the output file.

7-8

COBOL UTILITY PROGRAMS
Total records per data block (n):
Specify the total number of records to be contained in each
the data file.

block

Empty records per data block (n):
Give the number of data records that are to be initially left empty in
each data block.
Total entries per index block (n):
Give the total number of index entries to be contained in each block
of the index file.
Usually, a good blocking factor is a page (or
less) of memory, since this allows the internal swapping algorithms to
operate most efficiently.
Empty entries per index block (n):
Specify the number of index entries that
empty in each index block.

are

initially

left

Percentage of data file to leave empty (n):
Give, as a percentage of the total number of blocks, the number of
blocks to be initially left empty in the data file.
ISAM figures the
total number of data blocks required for the file, then add the number
of blocks which equals the given percentage fo the required blocks.
This procedure helps to prevent "DISK FULL" crashes.
Percentage of index file to leave empty (n):
Give, as a percentage of the total number of blocks, the number of
blocks to be initially left empty in the index file.
ISAM uses the
procedure described above to figure the amount of space to allocate,
thus, helping to prevent "DISK FULL" crashes.
Maximum number of record files can become (n):
Specify the maximum number of records that can be contained in the
file.
This number sets the upper limit on the size of the data file.
It is required because storage allocation tables must be set up when
the file is created, and ISAM must figure the number of index levels
required to handle the specified number of data records.
At this point, ISAM supplies you with some information on the
efficiency of your disk usage. The form of the information is the
same as that used in building an indexed-sequential file.

7-9

COBOL UTILITY PROGRAMS
Example - Maintaining an indexed-sequential file
@ISAM~

*=CALNDR/M
Total records per Data block (64):
Empty records per data block (4):
Total entries per Index block (159):
Empty entries per index block (10):
Percentage of Data file to leave empty (0):
Percentage of Index file to leave empty (0):
Maximum number of records file can become (1000):
[ISMLOV 1 Level of index]
[ISMNDR 1 Data record]
[ISMWSD Wasted O. words of 1408.
in the Data file.]
[ISMLDE One logical Data block equals 11. physical disk blocks.]
[ISMWSI Wasted 2. words of 640. 0.3% wasted space in the Index
file.]
[ISMLIE One logical Index block equals 5. physical disk blocks.]
[ISMIBS LIBOL's I/O buffer will require 3712. words (8. Pages) of
core.]

7-10

COBOL UTILITY PROGRAMS
7.1.3

Packing An Indexed-Sequential File

Packing an indexed-sequential file is the reverse,of building one. An
indexed-sequential file is copied into a sequential file in the order
specified by the index. This option is used primarily to compact an
indexed-sequential file
for
backup storage, although the resulting
sequential file can be treated as any other sequential file.
You
should always use ISAM to back up yo.ur indexed-sequential files.
You
can pack the files to tape, then rebuild on disk, or you can maintain
the file before packing and copying it to tape (or other backup
medium).
In either case, you have cleaned up the file you are saving
for
backup and streamlined the actual master file as well.
The
command string for the packing option of ISAM is as follows:

.R ISAM~

for users of TOPS-IO
or

@ISAM~

for users of TOPS-20

*devl:seqfil.ext[ppnl]=dev2:indfil.ext[ppn2]

Ip~

where:
devl and dev2 are the devices on which the sequential file is to
be stored and the index file resides, respectively.
The input
file must be on disk.
If neither device is specified, DSK is
assumed.
seqfil.ext is the name and extension of the output sequential
file.
If the name
is omitted, the name of the input file is
assumed.
If the extension is omitted, .SEQ is assumed.
indfil.ext is the name and extension of the index file of the
indexed-sequential file.
The name must be specified, but the
extension can be omitted.
If the extension is omitted,
no
extension is assumed.
[ppnl] [ppn2] are directories for the new sequential file and the
old
index file,
respectively.
If either
is omitted,
the
directory of the logged-in user is assumed.
Users of TOPS-20 who
wish to specify a directory other than the default can run the
TRANSLATE program to determine the correct project-programmer
number.
(See the TOPS-20- User's Guide for information on how to
do this.) For an alternative that is generally more useful,
see
Appendix C, Defining Logical Names under TOPS-20.

IP is the switch signifying that
requested.

the

packing

option

being

It must be included.

If the output file specification is omitted, the equal sign (=) can be
omitted.
After the command string has been processed, ISAM asks
questions.

the

following

Mode of output file:
Specify SIXBIT (or S), ASCII (or A), F, V, or ST according to the mode
in which the sequential file is to be recorded.
V is variable-length
EBCDIC, and F is fixed-length EBCDIC, and ST is STANDARD-ASCII.
Records per output block:

7-11

COBOL UTILITY PROGRAMS
Give the blocking factor that you want for the sequential file
(i.e.,
the number of records per logical block).
If the file is to be
unblocked, you answer O.
Example - Packing an indexed-sequential file
.R ISAM
*MTA2:TEST.SEQ=TEST.IDX/P
Mode of output file: SIXBIT
Records per output block: 0
If you are packing the data from the indexed file
into a sequential
ASCII file,
you can specify the advancing mode you want to be used
with the IA switch (lAD and IADV are also legal).
The format of the
command string to use with the IA switch is as follows:
sequential-file/A:mode=index-file/P
The arguments the IA switch takes are:
Mode

Meaning

6 [8]
7 [ 4]
A [FTER]
B[EFORE]

use
use
use
use

COBOL-68
COBOL-74
COBOL-74
COBOL-68

default (BEFORE)
default (AFTER)
default
default

If you do not specify the advancing mode when you pack an ASCII file,
your
file
is written using the COBOL-68 default, which is BEFORE
ADVANCING.

7.1.4

Ignoring Errors

When packing an indexed-sequential file into a sequential file,
you
can include the II switch in the command string to force ISAM to
ignore certain fatal errors.
This switch causes ISAM to try to
recover as much data as possible from a damaged indexed-sequential
file.
Including the II switch in the command string to ISAM causes the
program to make nonfatal those errors that concern duplicate keys or
keys out of order. The messages for these errors are preceded by a
percent sign
(%)
rather
than a question mark
(?)
so that ISAM
continues the packing operation. The II switch can be used only with
the Ip switch.
It cannot be used alone.
The command string to use with the II and Ip switches is as follows:
.R

ISAM~

for users of TOPS-IO
or

@ISAM~

for users of TOPS-20

*devl:seqfil.ext[ppnl]=dev2:indfil.ext[ppn2]/P/I~

where:
devl and dev2 are the devices on which the sequential and index
files reside, respectively.
The input file must be on disk.
If
neither device is specified, DSK is assumed.

7-12

COBOL UTILITY PROGRAMS
segfil.ext is the name and extension of the output sequential
file.
If the name is omitted, the name of the input file is
assumed. If the extension is o~itted, .SEQ is assumed.
indfil.ext is the name and extension of. the index file of the
indexed-sequential file.
The name must be specified, but the
extension can be omitted.
If the extension is omitted, no
extension is assumed.
[ppnIJ, [ppn2J are directories for the new sequential file and
the old index file,
respectively.
If either is omitted, the
directory of the logged-in user is assumed. Users of TOPS-20 who
wish to specify a directory other than the default can run the
TRANSLATE program to determine the correct project-programmer
number.
(See the TOPS-20 User's Guide for information on how to
do this.) For an alternative that is generally more useful, see
Appendix C, Defining L6gical Names under TOPS-20.

IP is the switch signifying that
requested.

the

packing

option

II is the switch signifying that some
ignored.

fatal errors are
It can be included only with the IP switch.

The equal sign (=)
can
specification is omitted.

7.1.5

being

It must be included.

omitted

the

output

be
file

Reading And Writing Magnetic Tape Labels

When you are building or packing an indexed-sequential file, you can
include the IL switch to cause ISAM to read or write labels on
magnetic tape. The IL switch, when used with the IB switch, causes
ISAM to read COBOL standard tape labels on the input magnetic tape.
When used with the IP switch, the IL switch causes ISAM to write
standard tape labels on the output magnetic tape. The IL switch can
only be used on magnetic tape files whose recording mode is not F or
V.
NOTE
The tape labels handled by ISAM are
COBOL tape labels, not ANSI labels.
COBOL labels are processed
by
the
object-time system, not the operating
system.
The command string when using the
follows:
.R

ISAM~

IL switch with the IB switch

for users of TOPS-IO
or

@ISAM~

for users of TOPS-20

*devl:indfil.ext[ppnJ ,dev2:datfil.ext=MTAn:seqfil.ext/B/L~

7-13

COBOL UTILITY PROGRAMS
where:
devl, dev2, and MTAn are the devices for
the index, data,
input sequential file.
devl and dev2 must be disk devices.
default disk for devl and dev2 is DSK.

and
The

indfil.ext is the name and extension of the index file.
If the
filename is not specified, the name of the input file is assumed.
If the extension is omitted, .IDX is assumed.
datfil.ext is the name and extension of the
indexed data file.
If the filename
is omitted,
the name of the index file is
assumed.
If the extension is omitted, .IDA is assumed.
seqfil.ext is the name and extension of the input sequential
file.
This filename must be specified, but the extension can be
omitted.
If it is omitted, .SEQ is assumed.
[ppn] specifies the directory for
the
index file.
If it is
omitted,
the directory of the logged-in user is assumed.
The
data file must reside in the same directory as the index file.
Users of TOPS-20 who wish to specify a directory other than the
default can run the TRANSLATE program to determine the correct
project-programmer number.
(See the TOPS-20 User's Guide for
information on how to do this.)
For an alternative that is
generally more useful,
see Appendix C, Defining Logical Names
under TOPS-20.

18 is the switch

signifying that ISAM is used to build an
indexed-sequential file.
If the switch is omitted from the
command string, 18 is assumed.

IL is the switch signifying that ISAM reads standard tape labels.
It must be included.
The equal sign (=) can be omitted if the file specifications
output files are also omitted.
The command string when using the
follows:
.R

ISAM~

IL switch with the IP switch

for users of TOPS-10
or

@ISAM~

for users of TOPS-20

*MTAn:seqfil.ext=devl:indfil.ext[ppn]/P/L~

7-14

for
is

the
as

COBOL UTILITY PROGRAMS
where:
MTAn:
and devl are the devices on which the sequential file
is
to be stored and the index file resides, respectively.
The input
file must be on disk.
If the name of devl is not specified,
DSK
is assumed.
seqfil.ext is the name and ext~nsion of the output sequential
file.
The name and extension can both be omitted because
filenames are not used on magnetic tape.
indfil.ext is the name and extension of the index file of the
indexed-sequential file.
The name must be specified, but the
extension can be omitted.
If the extension is omitted,
no
extension is assumed.
[ppn] is a directory for the old index file.
If it is omitted,
the directory of the logged-in user is assumed.
Users of TOPS-20
who wish to specify a directory other than the default can run
the TRANSLATE program to determine the correct project-programmer
number.
(See the TOPS-20 User's Guide for information on how to
do this.)
For an alternative that is generally more useful, see
Appendix C, Defining Logical Names under TOPS-20.

/p is the switch signifying that
requested.

/L is the switch signifying
labels.
It must be included.

7.1.6

the

packing

option

being

standard

tape

It must be included.
that

ISAM

writes

Renaming An Indexed-Sequential File

Since indexed-sequential files actually consist of two different
files,
you cannot rename a particular
ISAM file with a single
monitor-level command.
To allow you to rename ISAM files with greater
ease,
the ISAM program has the /R switch.
The form of the command
string you must supply to ISAM is as follows:
.R

ISAM~

for users of TOPS-IO
or

@ISAM~

for users of TOPS-20

*devl:indfil.ext[ppnl] ,dev2:datfil.ext=infil.ext[ppn2]/R~
where:
devl, and dev2, are disk devices on which the files
If any of the devices is omitted, DSK is assumed.

are

stored.

indfil.ext is the name and extension of the new index file.
the name is omitted, the name of the input file is assumed.
the extension is omitted, .IDX is assumed.

If
If

datfil.ext is the name and extension of the new indexed data
file.
If the name is omitted, the name of the new index file is
assumed.
If the extension is omitted, .IDA is assumed.

7-15

COBOL UTILITY PROGRAMS
infil.ext is the name and extension of the index file of the old
indexed-sequential file.
The name of the file must be specified,
but the extension can be omitted.
No extension is assumed if the
extension is omitted.
[ppnl], [ppn2] specify directories for the new index file and the
old
index file,
respectively.
If either
is omitted,
the
directory of the logged-in user is assumed.
The new data file
must reside in the same directory as the new index file.
Users
of TOPS-20 who wish to specify a directory other than the default
can
run
the
TRANSLATE program to determine the correct
project-programmer number.
(See the TOPS-20 User's Guide for
information on how to do this.)
For an alternative that is
generally more useful, see Appendix C,
Defining Logical Names
under TOPS-20.

IR is the switch indicating that the file is to be renamed.

The

switch must be specified.
The equal sign (=)
omitted.

can be omitted if the output file specification

Example - Renaming an indexed-sequential file
@DIRECTORY CALNDR
PS:<DUPREE)
CALNDR.IDA.l
.IDX.l
Total of 7 pages in 2 files
@ISAM
*CLDR=CALNDR/R
*C
@DIRECTORY CLDR
PS:<DUPREE)
CLDR.IDA.l
.IDX.l
Total of 7 pages in 2 files
@

7.1.7

Checking An Indexed-Sequential File

The ISAM program can check the format of an indexed-sequential file to
make sure there are no detectable errors. This includes duplicate
keys, bad key ordering,
version number discrepancies,
and record
length discrepancies.
When you use the IC switch, ISAM reads the entire file, printing error
messages when it encounters errors as it does when you use the II
switch. That is, the messages are printed as warnings rather than
fatal errors;
the prefix character for these messages is % instead of
?
Since ISAM does not produce an output file, you need not specify
an output file specification. The command string you should use to
get ISAM to check your indexed-sequential file is as follows:

7-16

COBOL UTILITY PROGRAMS
.R

ISAM~

for users of TOPS-IO
or

@ISAM~

for users of TOPS-20

*idxfil/C
Example
*CALNDR/C
%ISMKOO
keys are out .of order
00000009
is after
00000010
Data block 7. version number 21.

*
7.1.8

Producing Blocking Data With ISAM

The ISAM program can help you to build indexed-sequential files more
efficiently when you use the /S switch to produce blocking factors and
statistics.
ISAM cannot make the decision of the best blocking factor
for you, because you must balance the best blocking factor in terms of
disk space against the amount of main memory the file needs to be
processed.
But ISAM can help you by doing most of the simple
calculations. The statistics ISAM can calculate include:
•

Percentage of wasted space
factor

the

file

•

Number of physical blocks
blocking factor

each

logical

•

Size of logical block in core words for each blocking factor

Example - Producing Blocking Data
@ISAM
*=CALNDR/B/S
Mode of input file: A
Mode of data file: A
Maximum record size: 102
Key descriptor: 1.8
Records per input block: 0
Total records per Data block:
Records Disk
Wasted
/block
Blocks
space
5
1
14.1%
11
2
5.5%
17
3
2.6%
23
4
1.2%
29
5
0.3%
34
6
2.6%
40
7
1.8%
46
8
1.2%
52
9
0.7%
58
10
0.3%
64
11
0.0%

Core
(wds)
128
256
384
512
640
768
896
1024
1152
1280
1408

7-17

for

each
block

blocking
for

each

COBOL UTILITY PROGRAMS
(Recommended = 64):
Empty records per data block: 4
Total entries per Index block:
Records Disk
Wasted Core
/block
Blocks
space
(wds)
128
31
1
1.6%
63
2
0.8%
256
384
95
3
0.5%
127
4
0.4%
512
159
5
0.3%
640
(Recommended
159) :
Empty entries per index block: 10
Percentage of Data file to leave empty: 10
Percentage of Index file to leave empty: 10
Maximum number of records file can become: 1000
[ISMLOV
[ISMNDR

1 Level of index
4 Data records ]

wasted O. words of 1408.
in the Data file.]
[ISMWSD
One logical Data block equals 11. physical disk
[ISMLDE
blocks.]
[ISMWSI
Wasted 2. words of 640. 0.3% wasted space in the
Index file.]
[ISMLIE
One logical Index block equals 5. physical disk
blocks.]
[ISMIBS
LIBOL's I/O buffer will require 3712. words (8.
Pages) of core.]
*~C

7.1.9

Indirect Commands

The ISAM program accepts command strings and dialogue
indirect command files.

responses

from

The command string to direct ISAM to read an indirect command file is:
.R

ISAM~

for users of TOPS-IO
or

@ISAM~

for users of TOPS-20

*@dev:cmdfil.ext[ppn]~

where:
@ indicates that this is an indirect command file.
dev is the device on which the command file is stored.
omitted, DSK is assumed.

If it

cmdfil.ext is the name and extension of the command file.
The
name must be specified.
If you omit the extension, .CMD is
assumed.

7-18

COBOL UTILITY PROGRAMS
[ppn] is the directory in which the command file is stored.
If
it is omitted,
the directory of the logged-in user is assumed.
Users of TOPS-20 who wish to specify a directory other than the
default can run the TRANSLATE program to determine the correct
project-programmer number.
(See the TOPS-20 User's Guide for
information on how to do this.)
For an alternative that is
generally more useful, see Appendi~ C, Defining Logical Names
under TOPS-20.
After ISAM reads the c~mmand string, it reads the command file and
performs the processlng specified within it. The command file must
contain the complete command string and all dialogue responses for a
single ISAM operation exactly as they would be typed if you were
giving them directly to the ISAM program. Nothing else can be present
in the command file.

7.1.10

Using Indexed-Sequential Files

Indexed-sequential files can be read and written,
and individual
records within them can be rewritten or deleted.
You can perform any
actions on the records in an indexed-sequential file by specifying the
desired record key in the RECORD KEY field.
Remember that COBOL-68
supports single-key ISAM files only.
To use an indexed-sequential
file, the following statements are employed:

1.
2.
3.
4.

5.
6.
4.

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT ISAM-FILE ASSIGN TO DSK
ACCESS MODE IS INDEXED
SYMBOLIC KEY IS ISAM-SYM-KEY
RECORD KEY IS ISAM-RECORD-KEY.
DATA DIVISION.
FILE SECTION.
FD ISAM-FILE
BLOCK CONTAINS 13 RECORDS
VALUE OF IDENTIFICATION IS .. ISAMFLIDX" .
01 ISAM-RECORD.
02 FILLER PIC X(12).
02 ISAM-RECORD-KEY PIC X(3).
02 FILLER PIC X(75).
WORKING-STORAGE SECTION.
01 ISAM-SYM-KEY PIC S(3).
PROCEDURE DIVISION.
BEGIN.
OPEN INPUT-OUTPUT ISAM-FILE.

READ ISAM-FILE, INVALID KEY GO TO ERRPROC.

WRITE ISAM-RECORD, INVALID KEY GO TO ERRPROC.

DELETE ISAM-RECORD, INVALID KEY GO TO ERRPROC.

7-19

COBOL UTILITY PROGRAMS
10.

REWRITE ISAM-RECORD, INVALID KEY GO TO ERRPROC.

11.

MOVE LOW-VALUES TO ISAM-SYM-KEY.
READ ISAM-FILE, INVALID KEY GO TO ENDFILE.

The notes in the following list are keyed to the numbers to
of the lines in the preceding program.

the

left

The indexed-sequential file must reside on disk.

The ACCESS MODE clause is required if you wish to access the
file
in random fashion,
since the ACCESS MODE defaults to
sequential.

The SYMBOLIC KEY clause is required in the Environment
Division and the data item named must be defined in the
Working-Storage Section of the Data Division.
The SYMBOLIC
KEY and the RECORD KEY must have the same size and usage, but
they do not need to have the same level number, and the fact
that one of them is a group item does not mean that the other
must also be a group item.

The RECORD KEY clause is required in the
Environment
Division.
It refers to the data-item designated as the
record key which appears in the Data Division within the FD.

An indexed-sequential file must be blocked.

The VALUE OF IDENTIFICATION clause
is
required.
It
designates the filename and extension of the index file
rather than that of the data file.
The name of the related
data file
is stored within the index file.
The VALUE OF
IDENTIFICATION must be specified because the name of the file
must be present at initialization time so that the buffer and
storage space can be allocated.

The READ statement reads the indexed-sequential file to find
the record whose key as written on the file matches the
record key.
If no match is found, the INVALID KEY path is
taken.

The WRITE statement writes the record that has a key that
matches the record key.
If the record whose key matches the
record key is already in the file, the INVALID KEY path is
taken.

The DELETE statement causes a search to be made of the file
to find the record whose key matches the record key. When
the record is found, it is deleted.
If the record is not
found, the INVALID KEY path is taken.

10.

The REWRITE statement causes searching of the file to find
the record whose key matches the record key.
When the record
is found, it is replaced with the contents of the record
specified in the REWRITE statement.
If the record is not
found in the file, the INVALID KEY path is taken.

7-20

COBOL UTILITY PROGRAMS
11.

7.2

This shows the method used to read an indexed-sequential file
sequentially.
First, LOW-VALUES is moved to the SYMBOLIC
KEY.
Then a READ is issued, which causes the record
following the last record accessed to be read. Thus, if the
first I/O operation you execute is a READ with LOW-VALUES in
the SYMBOLIC KEY, you read the first record in the file. You
could then proceed to issue more READs and you would be
reading the indexed file sequentially. This procedure works
with all I/O verbs, not just with READ.

LI'BARY - PROGRAM TO CREATE AND MAINTAIN SOURCE LIBRARIES

LIBARY provides a facility for creating or maintaining COBOL library
files on disk or DECtape (TOPS-IO only). Library files contain COBOL
source-language text organized into statement groups.
Specifically,
the LIBARY program has the capability of adding source-language text
to the library file, replacing and/or deleting statement groups, and
providing a listing of the file. It allows you to specify those data
descriptions or procedures used in many programs and to place them in
a common file for use by the COBOL compiler. The statement groups in
the library file are included in a COBOL program through the use of
the COpy verb.
(See Section 1.4.1 for information on the COpy
statement. )

7.2.1

Library File Format

A library file is a collection of COBOL source-language statement
groups,
each
identified
by
a
unique
1to
8-character
library-entry-name. The library file must be on a directory device.
Each statement group is a set of ordinary COBOL language statements
conforming to the use of the COpy verb. The statement groups are kept
in alphabetic order according to their library names. The maximum
number of statement groups that can appear in a library is 3869.
The library file is in a
LIBARY and the COBOL
yourself with the format
them as ASCII text;
automatically.

7.2.2

binary format that is recognizable only by
compiler.
You, however, need not concern
of the actual entries in the file. You enter
LIBARY stores them in the appropriate format

Invoking The Library Utility

To invoke the library utility program, enter R LIBARY in response to
the TOPS-IO prompt (.) or LIBARY in response to the TOPS-20 prompt
(@). That is:
.R LIBARY~

for users of TOPS-IO

or
@LIBARY~

for users of TOPS-20

7-21

COBOL UTILITY PROGRAMS
When LIBARY is ready to process commands, it issues an asterisk
prompting character and waits for you to enter a file specification
command line. The file specification command line identifies the
library files being either created or used as input.
It also
identifies the listing file if a listing is required.
The file
specification command line has the following general format:
*output-library,listing=input-library~

where:
output-library

is the file specification for the
being generated.

listing

is the file specification for the file that is
to receive the output listing (See Figure 10-1,
Sample LIBARY listing.)

input-library

is the file specification for the
being used as input.

library

file

Each file specification has the following format:
dev:filename.ext[ppn]/sw
where:
dev:

is the logical device name for the unit on which
the
desired file is mounted.
The default
assignment is DSK:.

filename

is the name of the file consisting of from one
to six SIXBIT characters.
Filename must be
specified for at least one library file.

.ext

is the filename extension consisting of a period
followed by zero to three characters. It is
used to indicate the type of information in the
file.

[ppn]

is the directory area in which the file is
stored.
The directory specification, enclosed
in brackets, contains the project-programmer
number of the file's owner. Users of TOPS-20
who wish to specify a directory other than the
default
can
run the TRANSLATE program to
determine the correct project-programmer number.
(See the TOPS-20 User's Guide for information on
how to do this.) For an alternative which is
generally more useful, see Appendix C, Defining
Logical Names under TOPS-20.

/sw

is one ASCII character preceded
specifying a LIBARY switch option.
7.2.4, LIBARY Switches.)

7-22

by a slash
(See Section

COBOL UTILITY PROGRAMS
There are three main forms to the LIBARY command string.
One form
allows you to read an existing library and make changes, additions,
deletions, and extractions as you wish.
The second form simply
produces a listing of the contents of the exiting library. The third
allows you to create a new library by typing in the text with which
you wish to load it.
To make changes, additions, and so on, to your existing library, you
use the following command form (note that the listing file contains
only the changes to your existing library, not a listing of the entire
library) :
*output-library,listing-file=input-library~

If you wish to produce a listing of your input library but do not wish
to make any changes to the library, use the following form:
*listing-file=input-library/L~

To create a new library by typing in text, use the following
the command:

form

*output-library,listing-file=~

After you have invoked LIBARY and given it a file specification
command line,
it automatically creates a scratch file to contain the
output file generated by the LIBARY run.
When you are through working
on your library file and enter the END command (See Section 7.2.6.2,
LIBARY Directing Commands), LIBARY renames the scratch file with the
proper output name (after any necessary renaming of the input file).
If an error occurs causing the execution of LIBARY to be aborted,
the
input file,
if specified,
is unchanged and the scratch file is
deleted.
If the error occurred after the input file has been renamed,
the original input file has an extension of .BAK.

7.2.3

Command String Defaults

The following default values are assumed by LIBARY if any part of
file specification is omitted:

any

If any device is not specified, DSK is assumed.

If the file specification for the listing file is omitted, no
listing is produced.

If the name of the listing file is omitted, the name
input file is assumed.

the

If the extension of the listing
assumed.

.LST

If the file specification for the output file is omitted,
is assumed that there is no output file to be produced.

7-23

file

omitted,

COBOL UTILITY PROGRAMS

NOTE
If you are omitting the output file because you want
to run LIBARY to obtain a listing only, the listing
file specification, the input file specification, and
the /L switch must be specified.

If the name of the output file is omitted, the name of the
input file
is assumed.
In this case (as well as when you
specify that the output file is to be named the same as the
input file), the input file is written out with the extension
.BAK.

If the extension of the
assumed.

If the file specification of the input file is omitted, it is
assumed that there is no input file and that a library is
being created.
Thus, only commands for
insertion can be
used.

The filename for the input file cannot be omitted if the file
specification is present.

10.

If the extension of
assumed.

11.

If any project-programmer number is omitted, it is assumed to
be that of the logged-in user.
Users of TOPS-20 who wish to
specify a directory other than the default can run the
TRANSLATE program to determine the correct project-programmer
number.
(See the TOPS-20 User's Guide for information on how
to do this.)
For an alternative which is generally more
useful, see Appendix C, Defining Logical Names under TOPS-20.

12.

If the input and output files have the same name and
extension,
and are both on disk, the extension of the input
file is changed to .BAK at the completion of the operation.

7.2.4

output

the

file

input

file

omitted,

.LIB

LIBARY Switches

The following switches can
LIBARY:

included

the

command

string

List on your terminal all of the
contained on the input library file.

List on your terminal all of
LIBARY.

available

with

Create only a listing file of the entire input library.
output file specification must be omitted.

The

Put the input statement group into standard card format.

Rewind (for magnetic tape only).

7-24

the

library-entry-names

commands

COBOL UTILITY PROGRAMS
/Z

7.2.5

Clear an output directory (for DEC tape only).

Running LIBARY

Running LIBARY consists of specifying commands in response to the
LIBARY asterisk prompting character (*). LIBARY provides you with the
means to optionally create new library files and insert or delete
statement groups into an existing file. Each command causes LIBARY to
move forward in the file. Because LIBARY cannot move backward in the
file, you should plan your interaction with LIBARY so that you create
or modify your files in alphabetical order by statement group.
This
keeps you from having to restart LIBARY and reprocess your file.
Thus, if you have a library entry that is called CLDESC and another
called FLSTAT, you should be sure to deal with CLDESC first and do
everything you wish to accomplish at once, if possible, before going
on to FLSTAT.

7.2.6

LIBARY Commands

The following sections describe the commands available with
LIBARY commands are divided into two classes of commands:
•

Group mode

(See Section 7.2.6.1)

•

LIBARY directing

(See Section 7.2.6.2)

These commands can be abbreviated as
abbreviation.

long

you

supply

LIBARY.

unique

NOTE
For the remainder of this chapter, the
words "line number" refer to the line
numbers generated by a system standard
editor (such as SOS or EDIT); the words
"COBOL line number"
refer
to
the
conventional line numbers as described
in Section 1.3, Source Program Format.

7.2.6.1 Group Mode Commands - Group mode commands allow
you
insert, replace, extract, and delete entire statement groups.
group mode commands are:

to
The

DELETE library-entry-name
Delete the statement group identified by library-entry-name from
the library file. The library-entry-name itself is also deleted.
LIBARY moves forward through the input library file.
It copies
each statement it finds onto the output file until it encounters
the library entry specified
by
library-entry-name.
When
library-entry-name is reached, LIBARY positions itself at the
next sequential library entry and waits for another command.

7-25

COBOL UTILITY PROGRAMS
EXTRACT library-entry-narne,file-specification
Extract
the
complete
library
entry
specified
by
library-entry-name from the input library file and generate a new
file named filename. LIBARY searches the input library file for
the
library
entry
specified by library-entry-name.
When
library-entry-name is found, it creates a file or overwrites an
existing file with the attributes specified by filename and
copies the library entry onto it. The input library file remains
unchanged.
INSERT library-entry-narne,file-specification
Insert the statement group contained on the file specified by
filename into the output library file. The statement group is
inserted alphabetically according to the name specified by
library-entry-name.
The file specified by filename must be an
ASCII file. LIBARY assumes that the entire file is to be
inserted under library-entry-name.
If you want to insert many
entries, you must create a separate file for each and execute a
separate INSERT command for each. If there are line numbers in
the file, they are included when the file is merged.
If there
are no line numbers, LIBARY generates them starting with 10 and
incrementing by 10. If the library entry being inserted contains
COBOL line numbers, the /S swi tch must be specified.
(See
Section 7.2.4, LIBARY Switches.)
REPLACE Iibrary-entry-name, file-specification
Replace the library entry identified by library-entry-name with
the statement group contained on the file specified by filename.
The file specified by filename must be an ASCII file.
LIBARY
assumes that the entire file is to replace the statements
currently associated with library-entry-name.
If you want to
replace many library entries, you must create a separate file for
each, and execute a separate REPLACE command for each. If there
are line numbers in the file, they are included. If there are no
line numbers, LIBARY generates them starting with 10
and
incrementing by 10.
The /S switch must be specified for files
having COBOL line numbers.
(See Section 7.2.4, LIBARY Switches.)

7.2.6.2 LIBRARY-Directing Commands - LIBRARY-directing commands allow
you to end or restart library processing.
The LIBARY-directing
commands are:
END
Copy any remaining statement groups from the input to the output
file, close both the input and output files, and rename the input
file with the extension .BAK, if necessary.
NOTE
If you neglect to use the END command and attempt to
leave LIBARY by hitting CTRL/C, you abort your LIBARY
session, and your output library and listing file is not
written out.

7-26

COBOL UTILITY PROGRAMS
RESTART
Copy any remalnlng statement groups from the input to the output
files,
close both the inputl and output files, rename the input
file with the extension .BAK, 'and, reopen the output file as the
new input. Any changes made p~ior to issuing the RESTART command
are in the new input file.

7.2.6.3 Example of Command Usage - The following example shows the
use of LIBARY commands.
Suppose a library on disk contains the
routines PAYCOMP, FIND-MP, and MP-DESCR,
and you wish to do the
following:
1.

Insert a new routine called JOB-DESC

Correct MP-DESCR

Delete PAYCOMP

These ,tasks must be undertaken in this order because LIBARY deals with
code units in alphabetic order only.
The MP-DESCR routine contains
the following source statements:
000010
000020

LABEL RECORDS ARE OMITTED
DATA RECORD IS MP-RECORD.

The dialogue at the terminal might appear as follows:
.R LIBARY
*LIBARY.NEW=LIBARY.OLD
*INSERT JOB-DESC, JOBDES.TXT
*REPLACE MP-DESCR, MPDESC.TXT
*DELETE
PAYCOMP
*END
The file LIBARY.NEW now contains the following:
1.

FIND-MP

JOB-DESC

MP-DESCR

To insert one or more files in a library, you can issue the
commands to LIBARY •
. R LIBARY
*ALIB,ALIB=
*INSERT AFIL,AFIL
*INSERT BFIL,BFIL
*END

7-27

following

COBOL UTILITY PROGRAMS
The file ALIB.LIB contains two statement groups (AFIL
the file ALIB.LST contains the following information.
A F I L

B F I L

7.3

BFIL)

01-DEC-78

09:52

01-DEC-78

09:52

COBOL LIBRARY
DISPLAY "B".

COBDDT - PROGRAM FOR DEBUGGING COBOL PROGRAMS

COBDDT is an interactive program that is used to debug COBOL
at run-time. with COBDDT, you can:

7.3.1

and

DISPLAY "A".

000010

COBOL LIBRARY

and

Change the contents of a data-name

Set up to 20 breakpoints in a program

Continue from a breakpoint to any other breakpoint

Display the contents of a data-name

Trace paragraphs and sections

Obtain a histogram of paragraphs
behavior

Interrupt a running program

executed

show

programs

program

Loading And Starting COBDDT

To run COBDDT, you must first compile the source
load and start the compiled program with COBDDT.

program.

You

then

NOTE
Using the IP switch with the COMPILE
command suppresses your symbols that are
used by COBDDT. Therefore, you must not
use the IP switch when compiling your
program, if you wish to use COBDDT.
However,
it is possible to load some
programs compiled with the IP switch
with
some
compiled without the Ip
switch, though those compiled with the
IP switch cannot be debugged.
You can load the compiled source program with either the monitor
command LOAD or direct commands to LINK.
In both cases, LINK loads
your symbols along with the program.

7-28

COBOL UTILITY PROGRAMS
After loading the compiled source program,
you
issue the monitor
command START to start the program.
You can also issue the monitor
command DEBUG to load and start COB DDT with your
COBOL program.
If
you use the DEBUG command, you can specify the file to be debugged by
any of the following:
the name of the source file, the name of the
binary relocatable file,
or merely the name of the file without the
extension.
However, if the extension of the source file is something
other
than
.CBL, you must use the /COBOL switch with the DEBUG
command.
Otherwise the file is not recognized as a COBOL file.
When
you load COBDDT with your program,
only COBDDT is started;
the
program itself is not started.
The three methods of loading and starting are shown below.
Although
all
system prompts shown are for TOPS-IO, you can use the same syntax
on TOPS-20.
If you are using TOPS-20, you do not have to specify the
/"LOCALS" switch, as TOPS-20 loads local symbols by default.
1.

.LOAD %"LOCALS" file spec, SYS:COBDDT
. START

.DEBUG file spec [/COBOL]

.R LINK
*/LOCALS file spec, SYS:COBDDT /GO
• START

NOTE
On TOPS-20, you do not need
to
load
local symbols as
this
default mode.

specify
is the

When the program is started with the START command, COBDDT is entered.
This is shown by the message:
[Starting COBOL DDT]
COBDDT>
You can now issue any COBDDT command
(described below).
Users of
TOPS-20 can get a list of the available commands by typing a question
mark.
The TOPS-20 version of COBDDT also allows you to
use
recognition on the commands.
If you want to run your program at this
time, enter the PROCEED command.
This causes your program to run to
completion or until a
fatal
error is encountered.
If an error is
encountered that would normally cause abortion of execution, COBDDT is
entered automatically and the message:
?ENTERING COBDDT from:

<paragraph-name>

gives the name of the paragraph in which the error occurred.
COBDDT
can then be used to check data values at the time of the failure.
The
program cannot proceed after COBDDT has been entered due to an error.
If the COBOL program is in a loop and is not reaching a breakpoint,
you can enter COBDDT by typing CTRL/C two times followed by typing the
REENTER command.
For example:

"c"c
REENTER

7-29

COBOL UTILITY PROGRAMS
This causes COBDDT to display the following message:
Do you want to enter COBDDT (Y or N)
If you enter Y, the execution of the object program is resumed where
it was interrupted and COBDDT is entered at the next TRACE entry in
the program.
If you enter N, however, your COBOL program is reentered
at its original address.

7.3.2

COBOOT Commands

The commands to COBDDT are described below.
Other than for
the STOP
command,
you need only type the first letter of each command for
COBDDT to recognize the command.
For the STOP command,
however,
you
must type the entire command.
Data-names and section-names need not
be typed in full as long as each name or portion of the name is unique
in the program.
Paragraph-names can be qualified by section-names,
and data-names can be qualified by higher-level data-names
or
subscript values or both.
The subscripts for a qualified data-name
must appear immediately after the first data-name.
Subscripts must be
numeric integers.
Section-names and data-names cannot be qualified by
program-names because COBDDT uses the names in the program specified
in the MODULE command.
NOTE to TOPS-20 Users
COBDDT uses the COMND JSYS to do its
command parsing.
You must be aware that
if a command line ends with a " - "
(hyphen), the COMND JSYS deletes the "_"
from the command line and continues
parsing on the next line.
If you wish to include a "_" as the last
character on a cummand line, you should
type a space following
the
"_"
For
example,
COBDDT>DISPLAY FILE-<SPACE>~

ACCEPT
The ACCEPT command allows you to change the contents of a data
item.
The new contents of the data item are typed on the next
line.
The ACCEPT command has the format:
ACCEPT
ACCEPT data-name
If the data-name is not specified, the last name specified
DISPLAY or another ACCEPT command is assumed.
Example:

COBDDT>ACCEPT VARl
16.25
COBDDT>
7-30

COBOL UTILITY PROGRAMS
BREAK
The BREAK command sets a breakpoint (or pause) at the beginning
of the specified paragraph or section name. The BREAK command
has the format:
BREAK paragraph-name
BREAK section-name
Up to 20 breakpoints can be
UNPROTECT command is given.

set

program.

unless

the

Breakpoints can be set in nonresident COBOL segments, whether or
not the segment is in memory. If more than one module is in
memory, the name of the module in which the break occurred is
typed with the paragraph and section names.
You can set breakpoints in LINK overlays, but all breaks in the
overlay are cleared when the overlay is overlaid or cancelled.
To set breakpoints in LINK overlays, you must use the OVERLAY
command to specify OVERLAY ON. If you do not specify the OVERLAY
ON command, the program executes through the overlay before you
can set a breakpoint.
This is because you cannot set a
breakpoint in an overlay unless the overlay is in memory.
Example:
COBDDT)BREAK PARI

COBDDT)

CLEAR
The CLEAR
paragraph.

command removes the breakpoint
The CLEAR command has the format:

specified

CLEAR paragraph-name
CLEAR
If the paragraph-name is not specified, all breakpoints that have
been set in the program are removed.
Example:
COBDDT)CLEAR PARI

COBDDT)

7-31

COBOL UTILITY PROGRAMS
DDT
The COBDDT DDT command allows you to enter regular DDT,
the
assembly language debugger.
COBDDT can supply only certain types
of data;
the use of the DDT command enables you to look at the
data areas or procedure areas of the object program. This allows
you to change the compiled code or to put breakpoints in the
middle of a paragraph.
If COBDDT or LIBOL have been linked with
symbols, you can use the DDT command to look at these as well.
To use the assembly language debugger, you must first use the
LOCATE command or an assembly listing to obtain the addresses of
the areas that you want to look at.
Once you have these
addresses, you can use the DDT command to look at these areas.
The DDT command has the format:
DDT
COBDDT responds to the DDT command by telling you how to exit
from the assembly language debugger back to COBDDT. To get back
to COBDDT from the assembly language debugger,
you
type
POPJ 17,$X, where the "$" is an ESCape (~ ).
COBDDT tries to load DDT into memory if it is not already

there.

This example shows the use of the DDT command on TOPS-IO.
Although the system prompt differs on TOPS-20, the use of the
command is the same on both systems.
Example:
.RUN PRGRM
STARTING COBOL DDT
COBDDT)DDT
[Return from DDT by typing "POPJ 17,$X"]
DDT

DISPLAY
The DISPLAY command causes the contents of a data item to be
displayed on your terminal.
The DISPLAY command has the format:
DISPLAY
DISPLAY data-name
If no data-name is specified, COBDDT uses
specified in an ACCEPT or DISPLAY command.
Example:
COBDDT)DISPLAY ALPHA

COBDDT)

7-32

the

last

data-name

COBOL UTILITY PROGRAMS
GO
The GO command causes the program to resume execution of
specified procedure name. The GO command has the format:

the

GO procedure-name
The procedure name must be in a module that is currently loaded
into core.
Execution of the program begins at the designated
procedure name immediately after ihe command is typed.
The procedure name that you specify can be in another module, if
that module is in memory. However, the GO command does not set
up a return for the EXIT PROGRAM statement, nor does it provide
addresses for LINKAGE SECTION items.
The GO command also does not alter the existing stack of PERFORM
exits or subprogram exits.
If an error is detected in using
these return mechanisms following the GO command, control is
returned to COBDDT, but the PROCEED and GO commands are disabled.
Therefore further execution of the object program is
not
possible.
Example:

COBDDT>GO PARAl
BREAK AT «PARA4»
COBDDT>

LOCATE
The LOCATE command causes the object-time address of a procedure
name or a data item to be typed. The LOCATE command has the
format:
LOCATE procedure-name
LOCATE data-item
If the specified data-item does not start on a word boundary in
memory, the bit displacement of the data-item is also displayed.
Example:

COBDDT>LOCATE PARAl
401057

COBDDT>

MODULE
The MODULE command causes COBDDT to look for data names and
procedure names in the specified program. The MODULE command has
the format:
MODULE [program-name]

7-33

COBOL UTILITY PROGRAMS
If the name is omitted, COBODT types the name of the current
module followed by the names of all modules currently in memory.
Normally, within a run unit containing more than one program,
COBDDT searches for data names and procedure names in the current
program. The MODULE command changes the program in which the
search takes place. All subsequent searches for data names and
procedure names are within the specified program until another
MODULE command is issued.
If the current module is cancelled or
overlaid, the main program becomes the current module.
Example:

COBDDT>MODULE
CURRENT MODULE:

MYPROG

COBDDT>

NEXT
The NEXT command causes the contents of a data item to be
displayed on your terminal.
The NEXT command uses the variable
name and the subscript values given for the last ACCEPT, DISPLAY,
or NEXT command and adds the numeric value of the signed integer
to the rightmost subscript value in the subscript list. The NEXT
command has the format:
NEXT
NEXT signed integer
If the signed integer is omitted, a default of +1 is used.
A
signed integer can be any integer with plus, minus, or no leading
sign.
If you specify a subscript that is out of range, an error
message is displayed.
Example:

COBDDT>NEXT 3
33
COBDDT>

OVERLAY
The OVERLAY command either causes a break when un overlay is
The OVERLAY command has the
entered or clears the breakpoint.
format:
OVERLAY ON
OVERLAY OFF

7-34

COBOL UTILITY PROGRAMS
OVERLAY ON causes COBDDT to break the first
time
that a
LINK
overlay is entered each time
it is brought into memory.
The
break only occurs once for each time the overlay is brought
into
memory.
COBDDT types
the following message when the break
occurs:
BREAK UPON ENTRY TO name
where name is the name of the entry point.
Following the
message,
COBDDT types the name of the current module and a list
of the modules currently in memory.
OVERLAY OFF causes COBDDT not to break when a
LINK overlay is
entered and not to type the information described above.
OVERLAY
OFF is the initial default.

PROCEED
The PROCEED command causes the program either to be started or to
continue execution after
a breakpoint caused it to pause.
The
PROCEED command has the format:
PROCEED
PROCEED n
After a PROCEED command is executed, the program runs either
to
completion or until another breakpoint is reached.
If an integer
is included with the command, the program runs until
the n(th)
occurrence of the preceding" breakpoint has been reached.
Thus
PROCEED I is equivalent to PROCEED.
Example:
COBDDT>PROCEED 3
BREAK AT «PARA3»

COBDDT>

SHOW SYMBOLS
The SHOW SYMBOLS command prints on the terminal all symbols that
match
the given mask.
The mask consists of letters and the
special characters ?, %, and *.
The asterisk (*) stands for
any
number
of characters, including zero.
The question mark (?) for
TOPS-IO and the percent sign (%) for
TOPS-20
represent exactly
one character.
COBDDT>SHOW SYMBOLS *WRITE*
FIRST-WRITE-PARA
LAST-WRITE-PARA
REWRITE-RECORD
WRITE-RECORD
COBDDT>SHOW SYMBOLS %%WRITE*
REWRITE-RECORD
COBDDT>

7-35

COBOL UTILITY PROGRAMS
STEP
The STEP command causes your program to execute a specified
number of steps, each step being a procedure name, section name,
or a paragraph name. The default is a single step.
The STEP
command has the format:
STEP
STEP integer
If an integer is included with the command, the program runs
until the n(th) occurrence of a step has been reached. When the
STEP command has completed the specified number of steps, the
program is interrupted, and control is returned to COBDDT. The
following di~play then occurs:
STEP AT

!procedure-namel
lProgram-name

EXIT PROGRAM
Modules that have been compiled with the IP switch are invisible
to the STEP command. The entry point, the procedure names and
the exit programs are not counted as steps.
Example:

COBDDT>STEP 2
BREAK AT «PARA2»
COBDDT>

STOP
The STOP command is equivalent to the COBOL STOP RUN statement.
All files that are open are closed and program execution is
terminated. The STOP command has the format:
STOP
You must type the word STOP in Eull.
Typing only
letter, S, initiates execution of the STEP command.

the

first

Example:

COBDDT>STOP
EXIT

TRACE
The TRACE command starts tracing,
backwards, depending on the form
command has the format:

stops tracing, or traces
of the command. The TRACE

TRACE ON
TRACE OFF
TRACE BACK
TRACE ON causes tracing of all paragraphs and sections as they
are executed.
Whenever a paragraph or section is entered, its
name, enclosed in angle brackets «», is typed on your terminal.
7-36

COBOL UTILITY PROGRAMS
For each depth of subprogram, COBDDT types an exclamation poi'nt
(L)
before each paragraph or section name.
For each depth of a
PERFORM statement, COBDDT also types an asterisk (*) before each
paragraph or section name.
The maximum length of the string
printed is 35 characters.
Note that the exclamation point and
asterisk are printed for each depth of subprogram or PERFORM.
Example:

COBDDT)TRACE ON
!!*!**<PARA)
COBDDT)
When a LINK overlay is brought into memory,
COBDDT types the
names of any modules overlaid and the names of the modules in the
new overlay. When a LINK overlay is cancelled, COBDDT types the
names of the modules in that overlay.
TRACE OFF causes COBDDT to stop tracing procedures until either
execution is terminated or another TRACE ON command is executed.
Example:
COBDDT)TRACE OFF

COBDDT)
TRACE BACK causes COBDDT to show the sequence of paragraphs and
sections that were called to reach this program. When you
specify the TRACE BACK command,
the name of the currently
activated program is displayed,
followed by the sequence of
programs that were called to reach this program.
Example:
COBDDT)TRACE BACK
IN PROGRAM [SAMPLE]

COBDDT)

UNPROTECT

(TOPS-lO only)

The UNPROTECT command turns off write-protection for
the high
segment.
This command must be typed before you put breakpoints
(the BREAK command) in the high segment of the source code to be
compiled with the /R switch.

7-37

COBOL UTILITY PROGRAMS
WHERE
The WHERE command causes COBDDT to list the names of all
paragraphs at which breakpoints were set.
The WHERE command has
the format:
WHERE
If more than one module is in memory, the module name is included
with the paragraph name.
Example:
COBDDT>WHERE
PROGRAM STOPPED AT «PARAl»
BREAKPOINTS:
«PARAl»
«PARA2»
«PARA3»
17 UNUSED BREAKPOINTS
COBDDT>

7.3.3

Obtaining Histograms Of Program Behavior

The histogram facility in COBDDT allows you to obtain a report of the
number of times each section and paragraph in your COBOL program was
entered as well as the total amount of processor time and elapsed time
spent in each section and paragraph.
The commands for using this
feature are described in the following sections.
Both words of the histogram commands can be shortened to their unique
abbreviations.
None of the commands can be abbreviated to just H;
the first letter of the second word of the command must be present;
for example, H I, H B, and H E are legal.

7.3.3.1 Initializing the Histogram Table - The
HISTORY
INITIALIZE
command causes COBDDT to set up and initialize the histogram table in
which are stored the statistics for the histogram.
The form of this
command is:
HISTORY INITIALIZE [filespec] ['title']
The file specification is the device,
filename,
extension,
and
project-programmer
number
of
the
output
histogram
report
(dev:file.ext[p,pn]).
If the entire file specification is omitted,
your
terminal
is assumed.
If the device is omitted but the filename
is included, DSK is assumed.
If the extension is omitted,
.HIS is
assumed.
If the project-programmer number is omitted, that of the
logged-in user is assumed.
Users of TOPS-20 who wish to specify a
directory other than the default can run the TRANSLATE program to
determine the correct project-programmer number.
(See the TOPS-20
User's Guide for
information on how to do this.) For an alternative
that is generally more useful, see Appendix C, Defining Logical Names
under TOPS-20.

7-38

COBOL UTILITY PROGRAMS
The title is the one that is printed as the second line of the
histogram report.
It must be enclosed in single quotation marks and
can have a maximum length of 70 characters.
Once you specify a file specification and/or title,
it becomes
default for any subsequent reports until explicitly changed.

the

It is not necessary to use this command, but it is advisable to do so
if only a portion of the program's statistics are to be recorded.
The
table can also be reinitialized by means of the HISTORY INITIALIZE
command to begin a new histogram.

7.3.3.2 Starting the Histogram - The HISTORY BEGIN command causes
COBDDT to start gathering statistics for each section and paragraph
entered after this command is issued.
This command has the form:
HISTORY BEGIN [filespec] ['title']
The file specification is the device,
filename,
extension, and
project-programmer
number
of
the
output
histogram
report
(dev:file.ext[p,pn]).
If the entire file specification is omitted,
your
terminal is assumed.
If the device is omitted but the filename
is included, DSK is assumed.
If the extension is omitted,
.HIS is
assumed.
If the project-programmer number is omitted, that of the
logged-in user is assumed.
Users of TOPS-20 who wish to specify a
directory other than the default can run the TRANSLATE program to
determine the correct project-programmer number.
(See the TOPS-20
User's Guide for
information on how to do this.) For an alternative
that is generally more useful, see Appendix C, Defining Logical Names
under TOPS-20.
The title is the one that is printed as the second line of the
histogram report.
It must be enclosed in single quotation marks and
can have a maximum length of 70 characters.
Once you specify a file specification and/or title,
it becomes
default for any subsequent reports until explicitly changed.

the

The HISTORY BEGIN command implies a HISTORY INITIALIZE command if one
has not already been issued and if a histogram has not already been
started.
If a histogram already exists, HISTORY BEGIN adds data to
that histogram.
The statistics collected are:

•
•

The number of times each paragraph or section is entered

•

The elapsed time spent within each paragraph or section

•
•

The elapsed time and CPU time for overhead

The CPU time spent within each paragraph or section

The unaccounted elapsed time and CPU time

7.3.3.3 Stopping the Histogram - The HISTORY END
command
causes
COBDDT to stop gathering statistics for the histogram. This command
has the form:
HISTORY END

7-39

COBOL UTILITY PROGRAMS
If you wish to gather statistics throughout the entire execution of
the program, you need not use the HISTORY END command. However, if
you wish to stop gathering statistics for the histogram before the
p~ogram
finishes, you must set a breakpoint at the appropriate
paragraph and, when the break occurs, use the HISTORY END command.

7.3.3.4 Obtaining the Histogram Listing - The HISTORY REPORT command
causes COBDDT to list the available statistics in a report. This
command has the form:
HISTORY REPORT [file specification] ['title']
The file specification is the device, filename, extension, and
project-programmer
number
o f , the
output
histogram
report
(dev:file.ext[p,pn]). If the entire file specification is omitted,
your terminal is assumed. If the device is omitted but the name is
included, DSK is assumed.
If the extension is omitted,
.HIS is
assumed.
If the project-programmer number is omitted, that of the
logged-in user is assumed. Users of TOPS-20 who wish to specify a
directory other than the default can run the TRANSLATE program to
determine the correct project-programmer number.
(See the TOPS-20
User's Guide for information on how to do this.) For an alternative
that is generally more useful, see Appendix C, Defining Logical Names
under TOPS-20.
The title is the one that is printed as the second line of the
histogram report.
It must be enclosed in single quotation marks and
can have a maximum length of 70 characters.
Once you specify a file specification and/or title, it becomes
default for any subsequent reports until explicitly changed.

the

The format for the histogram report is shown below.
The heading
printed for each module that is in memory at the time the report
printed, even if the module was never entered.
If the report
printed while a module for which statistics were gathered is not
memory, the statistics for that module are not printed.

is
is
is
in

COBDDT HISTOGRAM FOR module-name
title
PROCEDURE
-section-nameparagraph-name
OVERHEAD:
UNACCOUNTED:

ENTRIES
integer-2
integer-3
ELAPSED:time-5
ELAPSED:time-7

7-40

REPORT: integer-l

CPU
time-l
time-3
CPU:time-6
CPU:time-8

ELAPSED
time-2
time-4

COBOL UTILITY PROGRAMS
module-name

is the" name of the
PROGRAM ID ·clause.

integer-l

is the report number. It starts at 1 and is
incremented by 1 for each report produced in
a run.

title

is the title that you specified in one of the
HISTORY commands.

section-name

is the name of a section into which control
was transferred or passed. Each paragraph in
the section to which control was passed is
given with the section.

integer-2

is the number of times control
directly to the section.

time-l

is the amount
section.

time

spent

the

time-2

is the amount of elapsed time
section.

spent

the

paragraph-name

is the name of a paragraph to
was transferred or passed.

which

control

integer-3

is the number of times control was passed
this paragraph.

time-3

is the amount
paragraph.

spent

this

time-4

is the amount of elapsed time spent
paragraph.

this

time-5

is the elapsed time spent entering
and
exiting
from
subprograms
and
PERFORM
statements. If this time is 0, the line is
not printed.

time-6

is the CPU time spent entering and exiting
from subroutines and PERFORM statements.

time-7

is the elapsed time that could not be charged
to any section or paragraph. If this time is
0, the line is not printed.

time-8

is the CPU time that could not be charged to
any section or paragraph. For example, when
a subprogram is entered, the time accrued
until the first paragraph or section is seen
is charged to unaccounted.

module,

CPU

time

taken

from

was

the

passed

If control is never passed to a particular section or paragraph,
nothing is printed for that section or paragrap,h. When a PERFORM
statement or subprogram is entered, the current paragraph or section
is saved on a stack so that COBDDT can continue to charge time to the
correct section or paragraph when the return is done. The size of the
stack is 20 locations.
After a depth of twenty calls or PERFORM
statements is reached, time is charged to unaccountable.

7-41

COBOL UTILITY PROGRAMS
A sample histogram report is shown below.
COBDDT HISTOGRAM FOR CASHX
PROCEDURE

REPORT:

ENTRIES

CPU

ELAPSED

0
721
1
721
1
1
721
721
721
721

1.360
0.008
0.000
0.385
0.016
0.000
0.400
0.167
0.178
0.206

21.707
2.641
0.000
5.616
0.233
0.017
5.575
2.146
2.086
3.393

-GENERATED-SECTION-NAMESTART
ST-l
START-2
INITIAL-SETUP
END-INITIAL-SETUP
CONVERT-RECORDS
END-CONVERT-RECORDS
RATE-IT
END-RATE-IT

7.3.3.5 Using the Histogram Feature - To use the histogram feature,
issue the following commands upon entering COBDDT for the first time.
HISTORY INITIALIZE
HISTORY BEGIN
At any time when you are stopped at a breakpoint, you can stop
gathering statistics for
the histogram by issuing the HISTORY END
command.
If you issue a HISTORY BEGIN command after a HISTORY END
command,
the histogram continues from the point where the HISTORY
BEGIN command was issued.
However, if after a HISTORY END command you
issue a HISTORY INITIALIZE and a HISTORY BEGIN command, the previous
statistics are lost and a new histogram begun.
To get the previous
histogram,
issue
a HISTORY REPORT command before the HISTORY
INITIALIZE command.
If a histogram file already exists with the same file specification as
the one given, the histogram report is appended to the existing file.
If the file specification is different, COBDDT starts a new histogram
file.

7.4

RERUN - PROGRAM TO RESTART COBOL PROGRAMS

The RERUN program is used to restart a COBOL program that has been
terminated abnormally due to a system failure, a device error, o( an
exceeded disk quota.
RERUN uses checkpoint files, which are similar
to memory-image dump files.
Checkpoint files are created in one of
two ways:
•

By including RERUN statement(s)

•

By typing CTRL/C twice
execution

followed

in the COBOL program itself
by

REENTER

during

program

The COBOL system creates a checkpoint file by writing a memory-image
dump file of the program onto disk and adding some other information
to allow a later restart of the program. At the same time, the COBOL
system closes and reopens all disk and magnetic tape output files.
The dump is not performed if a sort is in progress.
Each time the
checkpoint file
is written, the COBOL system types the message DUMP
COMPLETED on your terminal.

7-42

COBOL UTILITY PROGRAMS
If the COBOL program is interrupted during execution, you can restart
the program by means of the RERUN program. The RERUN program reads
the dump file back into memory, restores the files to their state at
the time the checkpoint file was written, and then passes control to
the COBOL program so that it can continue processing to completion.
RERUN assumes that the operating environment at the time the COBOL
program was interrupted is the same as the environment at the time the
checkpoint file was written. Thus, the files must be associated with
the same types of devices, and devices must have the same logical
names.

7.4.1

Operating RERUN

To restart a COBOL program from the last checkpoint file written
before execution stopped,
type R RERUN in response to the operating
system prompt (users of TOPS-20 can respond RERUN).
For example:
.R RERUN~

for users of TOPS-IO
or

@RERUN~

for users of TOPS-20

If you are running on TOPS-20, RERUN displays a prompt:
RERUN>
The first message you see from TOPS-IO RERUN is the second
message you see from TOPS-20 RERUN, and both are followed by
an asterisk prompt:
TYPE CHECKPOINT FILENAME

*
At this point you type the name of the checkpoint file
core-image dump is stored.

which

the

When a checkpoint dump is being written, the COBOL system uses the
filename of the program as the name of the checkpoint file and adds
the extension .CKP.
If the COBOL program does not have a filename
because it was not saved,
the COBOL system takes the checkpoint
filename from the PROGRAM-ID in the program and adds the extension
.CKP.
If the program has been divided into a 2-segment file, the
high-segment filename must be the same as the low-segment filename.
Thus, when you respond with the checkpoint filename you are in effect
telling RERUN the program name as well.
If TOPS-IO RERUN encounters a logical device name in the
types the following message:

program,

ASSIGN device-name
TYPE CONTINUE WHEN DONE
and exits to monitor command level.
If this happens, you should give
the appropriate ASSIGN command to assign the logical device to a
specific one, then a CONTINUE monitor command to restart RERUN.
The TOPS-20 RERUN works similarly.
prints the following:

If it finds

DEFINE logical-name:
(AS) device:
TYPE CONTINUE WHEN DONE
7-43

logical

name,

COBOL UTILITY PROGRAMS
TOPS-20 RERUN exits to the monitor.
You should then give the
appropriate DEFINE command followed by a CONTINUE command to restart
RERUN.

7.4.2

Examples Of Using RERUN

In the following example, you have a COBOL program that was terminated
by a system failure.
Checkpoints had been inserted in the program by
means of RERUN statements. The program has a filename of ACCNT;
thus,
the checkpoint filename is ACCNT.CKP.
Instead of running the
program again from the beginning, you employ the RERUN program to
restart your program from the last checkpoint written before the
program stopped.
You type:
.R

RERUN~

The RERUN> prompt is not printed above because the example is
on a TOPS-IO system.
RERUN responds:

running

TYPE CHECKPOINT FILENAME

*
You type:
ACCNT.CKP

RERUN loads the che~kpoint file into memory, reopens and repositions
the magnetic tape and disk files, and passes control to the COBOL
program so that it can continue processing to completion.
In the example below, you are running a COBOL program that is notified
the system is going down.
You do not have any RERUN statements in
your program, yet you wish to create a checkpoint file so that the
processing done by your COBOL program up to that point is not wasted.
You create the checkpoint file by typing CTRL/C twice and then typing
REENTER. The checkpoint file is written by the COBOL system onto disk
with a filename of PROGl3 (taken from the PROGRAM-ID) and an extension
of .CKP. After the system is restored, you can restart the program by
running the RERUN program.
The dialogue is as follows:

@RERUN ~
RERUN>
TYPE CHECKPOINT FILENAME

PROGl3.CKP

The program PROGl3 is loaded into memory, its files are reopened,
it continues running to completion.

7-44

and

CHAPTER 8
FILE FORMATS

8.1

RECORDING MODES

The recording mode specifies the byte size of the data and, except for
binary mode, also specifies the character set used.
The four
recording modes and their respective byte sizes are:
RECORDING MODE

BYTE SIZE

ASCII
SIXBI'r
EBCDIC
Binary

7 bits
6 bits

8 bits
36 bits (1 word)

The following sections describe the recording modes in more detail.

8.1.1

ASCII Recording Mode

An ASCII word consists of 5 characters left-justified
Each character is represented by a 7-bit byte:

the

word.

BIT NU M B E R _ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
BINAR Y
REPRE SENTATION
DATA

-- .
.

o • o • •

• •

•

• •

•

• • x

C
MR-S-030-79

BYTES: 5

• = on bit
o = off bit
X = unused bit

Figure 8-1 ASCII Recording Mode
NOTE
A variant form of ASCII, line-sequence
ASCII, sets bit 35 of the line-sequence
word to 1.

8-1

FILE FORMATS
8.1.2

SIXBIT Recording Mode

SIXBIT is a compressed form of ASCII in which lowercase letters and a
few special characters are not used. A SIXBIT word consists of 6
characters per word, with each character represented by a 6-bit byte:

BIT N U M B E R - O

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

BINAR Y
~
REPR ESENTATION
•

o •

• •

DATA

•

• •

•

• •

3
MR-S-031-79

BYTES: 6
•
o

on bit
off bit

Figure 8-2 SIXBIT Recording Mode

8.1.3

EBCDIC Recording Mode

An EBCDIC word consists of 4 characters per word.
Each byte is 9 bits
long, but the first bit in each byte is unused. Each character is
represented by 8 bits:
BIT NU M B E R - 0

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

BINAR Y
REPRE SENTATION - - X

DATA

o • X •

• • •

• x • • •

•

• • • •

•

MR-S-032-79

BYTES: 4
• ~ on bit
o ~ off bit
X ~ unused bit

Figure 8-3 EBCDIC Recording Mode
A variant form, used only for magnetic tape,
is industry-compatible
EBCDIC.
In this form of EBCDIC, there are 4 characters per word,
left-justified within the word.
Each character is represented by an
8-bit byte. The last 4 bits in the word are unused:

BIT NU MBER----- 0
BINAR Y
REPRE SENTATION
DATA

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

--. • • •

••• • •

• • • •

•

• • • •

•

X X

2
MR-S-033-79

BYTES: 4
•

= on bit

= off bit

Figure 8-4 EBCDIC Recording Mode - Industry-Compatible

8-2

FILE FORMATS
8.1.4

BINARY Recording Mode

Unlike the recording modes previously mentioned, binary mode does not
specify a character set for
the data.
In binary mode, the entire
36-bit word is interpreted as a single byte of binary data:

BIT N U M B E R - O 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
__ 0
BINAR Y
REPR ESENTATION

000

•

DATA

• • •

•

• • • •

2,739,136
MR-S-034-79

BYTES: 1
• = on bit
o = off bit

Figure 8-5 Binary Recording Mode

8.2

FILE FORMATS

The file format specifies the structure of the record used to store
the data.
The following
sections describe all major file formats.
Each section includes a diagram of the file format and a COBOL code
segment that generates the file format.
The following conventions are used in the diagrams:
1.

Alphanumeric or numeric-character data in a word is shown
with each individual character enclosed in a box. The box
represents 1 byte. Thus, a word of ASCII data would be shown
as follows:

Binary data in a word (fixed- and floating-point numbers)
shown by a number in the word:

132156.1°1
3.

EBCDIC packed-decimal values are shown as two decimal digits
per
EBCDIC byte.
The right half of the rightmost byte
contains the sign.
Neither the digits nor
the sign are
EBCDIC characters.

COBOL signed numeric data, such as produced by PIC S9(n),
is
shown
with the over-punched character
if the sign is
negative.
For example, -12345 is shown as 1234N, with the N
representing
both the negative sign and the value 5.
DIGITAL's COBOL does not use over-punched characters for
positive sign representation, so diagrams depicting positive,
signed numeric data do not show a sign.

Italicized characters in a diagram do not depict data;
label or clarify parts of the diagram:

ROW 30

MR-S-034A-81

8-3

they

FILE FORMATS
6.

Heavy vertical lines are used to
within a record:

delimit

individual

fields

Padding, the use of blanks or nulls to force the next record
to begin on some boundary (for example, a word or disk-block
boundary), is shown by white space in the word:

You cannot consider padding as part of a record field, nor can you use
padding as part of a key field. However, the length of any padding
must be taken into account when calculating record length and key
starting position.

8.2.1

Fixed-Length ASCII

A fixed-length ASCII file consists of records containing
five
characters per 36-bit word, with each group of five characters
left-justified within the word. Fixed-length ASCII records must end
wi th a car riage return/l ine feed. The following diagr aem ill ustrates
the format of fixed-length ASCII records:
WORD

RECORD

I
4

GD
~

CARRIAGE RETURN

(ill

LINE FEED

MR-S-035-79

Figure 8-6 Fixed-Length ASCII

8-4

FILE FORMATS
CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS ASCII.
DATA DIVISION.
FILE SECTION.
FD filename
01 record-l
02 field-l
02 field-2
02 field-3
02 field-4
02 field-5

VALUE OF ID "DATA
DISPLAY-7.
PIC X{6}.
PIC A(3).
PIC 9{4}.
PIC S9(6).
PIC S9(6)V9999.

FIL".

PROCEDURE DIVISION.
LOAD-PARAGRAPH. '
MOVE "AB12EF" TO field-I.
MOVE "GHI" TO field-2.
MOVE 3249 TO field-3.
MOVE -481253 TO field-4.
MOVE 31458.5012 TO field-5.
WRITE record-I.

Figure 8-7 illustrates the record produced by the code
above:

segment

shown

WORD

GO
MR-S-036-79

Figure 8-7

8.2.2

COBOL Fixed-Length ASCII

Variable-Length ASCII

Variable-length ASCII consists of records containing five characters
per
36-bit word, with each group of five characters left-justified
within the word. Variable-length ASCII records must end with some
combination of the following control characters:
1.

Carriage return

8-5

FILE FORMATS
2.

Line feed

Vertical tab

Form feed

The following diagram illustrates the format of variable-length
records:
A

G!!)

G!)

C!Q

CK)

= CARRIAGE RETURN

= VERTICAL TAB

CK) = FORM FEED

= LINE FEED

MR-S-037-79

Figure 8-8 Variable-Length ASCII

8-6

ASCII

FILE FORMATS
CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS ASCII.
DATA DIVISION.
FILE SECTION.
FO filename
01 record-1
02 fie1d-1
02 field-2
02 field-3
02 field-4

VALUE OF IO "DATA
OISPLAY-7.
PIC X(7).
PIC S9(7)V99.
PIC A(3).
PIC 9(4).

01 record-2
02 field-l
02 field-2
02 field-3
02 field-4

DISPLAY-7.
PIC X(7).
PIC S9(7)V99.
PIC A(3).
PIC 9(7).

FIL".

PROCEDURE DIVISION.
LOAD-PARAGRAPH-l.
MOVE "AB13521" TO field-l OF record-I.
MOVE -3269.02 TO field-2 OF record-I.
MOVE "ILM" TO field-3 OF record-I.
MOVE 1359 TO field-4 OF record-I.
WRITE record-I.
LOAD-PARAGRAPH-2.
MOVE "EFGHI95" TO field-l OF record-2.
MOVE 42553.40 TO field-2 OF record-2.
MOVE "LMN" TO field-3 OF record-2.
MOVE 3712536 TO field-4 OF record-2.
WRITE record-2.

Figure 8-9 illustrates the record produced by the code
above:

8-7

segment

shown

FILE FORMATS
WORD
A

1
1

MR-S-038-79

Figure 8-9 COBOL Variable-Length ASCII

8.2.3

Fixed-Length SIXBIT

In a SIXBIT file, characters are stored six per 36-bit word, and a
SIXBIT record must start and end on a word boundary. The left half of
the first word in the record contains one of the following:
1.

The record sequence number of COBOL magnetic tape records

Data specific to COBOL ISAM records

Binary zeros

The right half of the first word contains the number of characters in
the record.
To ensure that the record ends on a word boundary, the
last word in the record is padded with blanks, if necessary.
When
determining the size of the record for memory considerations, you must
take into account the first word of the record {containing file-access
information and a character count} and the possible existence of
padding characters {blanks} to enable the record to end on a word
boundary.
The following diagram illustrates the format of fixed-length SIXBIT
records. Note that the character count is the same for each record:
WORD

RECORD

FAD
2

'-'

FAD

'-'

FAD = FILE ACCESS DATA

E
'-'

'-'
MR-S-039-79

= CHARACTER COUNT

'-'

= BLANK (USED AS PADDING CHARACTER)

Figure 8-10 Fixed-Length SIXBIT

8-8

FILE FORMATS
CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS SIXBIT.
DATA DIVISION.
FILE SECTION.
FD filename
01 record-l
02 field-l
02 field-2
02 field-3
02 field-4
02 field-5
02 field-6
02 field-7
02 field-8

VALUE OF ID "DATA
DISPLAY-6.
PIC X(4).
PIC A(5).
PIC 9(10) COMPo
PIC X(2).
PIC 9(11) COMPo
PIC 9(4).
COMP-l.
PIC 9(11} COMPo

FIL".

PROCEDURE DIVISION.
LOAD-PARAGRAPH.
MOVE "A13B" TO field-I.
MOVE "CDEFG" TO field-2.
MOVE 9654839218 TO field-3.
MOVE "HI" TO field-4.
MOVE 34567982314 TO field-5.
MOVE 1289 TO field-6.
MOVE 123.45 TO field-7.
MOVE 12398756983 TO field-8.
WRITE record-I.

Figure 8-11 illustrates the record produced by the code segment
above:
WORD

FAD

I D

9654839218

3
H

ILl

5
34567982314

r-6
1

123.45

8
9

r---

12398756983

FAD
CC
L.....I

MR-S-040-79
FILE ACCESS DATA
= CHARACTER COUNT
= BLANK (USED AS PADDING CHARACTER)
=

Figure 8-11

COBOL Fixed-Length SIXBIT
8-9

shown

FILE FORMATS
8.2.4

S~XBIT

Variable-Length

This format is the same as fixed-length SIXBIT, except that the
character count can vary from record to record. The following diagram
illustrates the format of variable-length SIXBIT records:
WORD

FAD
2

'-'

FAD

'-'

MR-S-041-79

FAD: FILE ACCESS DATA
CC

= CHARACTER COUNT

'-'

= BLANK (USED AS PADDING CHARACTER)

Figure 8-12 Variable-Length SIXBIT

8-10

VALUE OF 10 "DATA
OISPLAY-6.
COMP-l.
PIC X(3).
PIC A(3).
PIC 9(3).
PIC 9(10) COMPo
PIC 9 (11) COMPo
PIC X(2).
PIC 9(5) COMPo

01 record-2
02 field-l
02 field-2
02 field-3
02 field-4
02 field-5
02 field-6
02 field-7
02 field-8

DISPLAY-6.
COMP-l.
PIC X(3).
PIC A(3).
PIC 9(3).
PIC 9(10) COMPo
PIC 9(11) COMPo
PIC X(2).
PIC 9(11) COMPo

FIL".

PROCEDURE DIVISION.
LOAD-PARAGRAPH-l.
MOVE 123.4567 TO field-l OF record-I.
MOVE "A3C" TO field-2 OF record-I.
MOVE "DEF" TO field-3 OF record-I.
MOVE -55 TO field-4 OF record-I.
MOVE 1234567809 TO field-5 OF record-I.
MOVE 98765432108 TO field-6 OF record-I.
MOVE "A2" TO field-7 OF record-I.
MOVE 32571 TO field-8 OF record-I.
WRITE record-I.
LOAD-PARAGRAPH-2.
MOVE 1395.678 TO field-l OF record-2.
MOVE "B5L" TO field-2 OF record-2.
MOVE "LMN" TO field-3 OF record-2.
MOVE 79 TO field-4 OF record-2.
MOVE 8176596821 TO field-5 OF record-2.
MOVE 18976532150 TO field-6 OF record-2.
MOVE "M5" TO field-7 OF record-2.
MOVE 12357986183 TO field-8 OF record-2.
WRITE record-2.

Figure 8-13 illustrates the record produced by the code segment
above:

8-11

shown

FILE FORMATS
WORD

FAD

123.4567
A

1234567809

98765432108

6
A

32571

FAD

1395,678

8176596821

18976532150

L-

6
M

12357986183

MR-S-042-79

Figure 8-13

8.2.5

COBOL Variable-Length SIXBIT

EBCDIC File Formats

On disk and in memory, the characters in an EBCDIC file are
represented by 8 bits right-justified in 9-bit bytes. On tape, the
characters in an EBCDIC file are represented by 8-bit bytes, and 4
bytes occur per 36-bit word.
Within a given file, records can be
either fixed or variable length, and can be either blocked or
unblocked. Thus, there are four types of EBCDIC files:
1.

Fixed-length

Variable-length

Blocked fixed-length

Blocked variable-length

In a file written in fixed-length EBCDIC, records all have the same
record length and the records need not begin or end on a word
boundary.
The following
diagram
illustrates
the
format
of
fixed-length EBCDIC records in an unblocked file:

8-12

FILE FORMATS
WORD

RECORD

I
3

MR-S-043-79

Figure 8-14 Fixed-Length EBCDIC
CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS F.
DATA DIVISION.
FILE SECTION.
FD filename
01 record-l
02 field-l
02 field-2
02 field-3
02 field-4
02 field-5

VALUE OF ID "DATA
DISPLAY-9.
PIC 9(3).
PIC X(5).
PIC A(2).
PIC 9(9) COMP-3.
PIC S9(6) COMP-3.

FIL".

PROCEDURE DIVISION.
LOAD-PARAGRAPH.
MOVE 123 TO field-I.
MOVE "ABCDE" TO field-2.
MOVE "LM" TO field-3.
MOVE 137958795 TO field-4.
MOVE -351235 TO field-5.
WRITE record-I.

Figure 8-15 illustrates the record produced by the code segment
above:

I
2

3
4

7 :9

1 :3

7 :9

5:+

5 :1

2:3

5 :MR-S-044-79

Figure 8-15

COBOL Fixed-Length EBCDIC

8-13

shown

FILE FORMATS
In a file written in variable-length EBCDIC format, the record lengths
can vary from record to record. Each record contains a 4-byte Record
Descriptor Word (RDW) at the head of the record. The left half-word
of the RDW specifies a value equal to the number of bytes in the
record plus 4 (to allow for the length of the RDW itself).
The
rightmost 2 bytes of the RDW must be zero; if they are nonzero, they
indicate spanned records, which are unsupported.
The following
diagram illustrates the format of variable-length EBCDIC records in an
unblocked file:
WORD

RECORD

I ROW

ROW

3
4

ROW ~ RECORD DESCRIPTOR WORD
MR-S-045-79

Figure 8-16 Variable-Length EBCDIC

8-14

VALUE OF ID "DATA
DISPLAY-9.
PIC S9(7) COMP-3.
PIC S9(8) COMP-3.
PIC 9 ( 3) •
PIC A(2).
PIC X(5}.

01 record-2
02 field-l
02 field-2
02 field-3
02 field-4
02 field-5

DISPLAY-9.
PIC S9(7} COMP-3.
PIC S9(8) COMP-3.
PIC 9(3}.
PIC A(2}.
PIC X(8).

FIL".

PROCEDURE DIVISION.
LOAD-PARAGRAPH-l.
MOVE -1398569 TO field-l OF record-I.
MOVE 57635937 TO f{eld-2 OF record-I.
MOVE 596 TO field-3 OF record-I.
MOVE "AB" TO field-4 OF record-I.
MOVE "AI3DE" TO field-5 OF record-I.
WRITE record-I.
LOAD-PARAGRAPH-2.
MOVE 5369787 TO field-l OF record-2.
MOVE -53896156 TO field-2 OF record-2.
MOVE 593 TO field-3 OF record-2.
MOVE "MN" TO field-4 OF record-2.
MOVE "ILH5MLXY" TO field-5 OF record-2.
WRITE record-2.

Figure 8-17 illustrates the record produced by the code segment
above:

8-15

shown

FILE FORMATS
WORD
ROW

1 :3
I

9:8

5 :6
I

:5
I

7 :6

3 :5

9 :3

7 :+

ROW

5 13
1

7 1+

26
1,2

6 19
I

7 :8
I

2,3

3 18
I

9 :6

1 :5

6:-

3,4

4,5

5,6

MR-S-046-79

Figure 8-17

COBOL Variable-Length EBCDIC

Fixed-length EBCDIC records can also be blocked.
In this file format,
fixed-length EBCDIC records are written in groups (or blocks). Each
For tapes, each block
new block begins on a disk-block boundary.
starts a new physical magnetic-tape record.

8-16

FILE FORMATS
CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS F.
DATA DIVISION.
FILE SECTION.
VALUE OF ID "DATA
FD filename
BLOCK CONTAINS 1 RECORD.
DISPLAY-9.
01 record-l
02 field-l
PIC 9{3}.
PIC X(5).
02 field-2
PIC A(2).
02 field-3
PIC S9(5) COMP-3.
02 field-4
PIC S9(4) COMP-3.
02 field-5
01 record-2
02 field-l
02 field-2
02 field-3
02 field-4
·02 field-5

FIL"

DISPLAY-9.
PIC X(3).
PIC X(5).
PIC A(2).
PIC S9(5) COMP-3.
PIC S9(4) COMP-3.

PROCEDURE DIVISION.
LOAD-PARAGRAPH-l.
MOVE 194 TO field-l OF record-I.
MOVE "BDEFG" TO field-2 OF record-I.
MOVE "MN" TO field-3 OF record-I.
MOVE 13796 TO field-4 OF record-I.
MOVE 1985 TO field-5 OF record-I.
WRITE record-I.
LOAD-PARAGRAPH-2.
MOVE "762" TO field-l OF record-2.
MOVE "LANBH" TO field-2 OF record-2.
MOVE "AB" TO field-3 OF record-2.
MOVE 76543 TO field-4 OF record-2.
MOVE -9764 TO field-5 OF record-2.
WRITE record-2.

Figure 8-18 illustrates the record produced by the code segment
above:

8-17

shown

FILE FORMATS
WORD

BLOCK

BLOCK'
9
D

918
1

6:+
1

1: 3

7:9
1
1

5'+
1

7:6

5:4

3I+
'1

..........

:9
I
1

7:6

4 : -I
I

MR-S-047-79

Figure 8-18

COBOL Blocked Fixed-Length EBCDrC

Variable-length EBCDIC records can be blocked as well.
In this file
format, the record length can vary from record to record. Each record
contains a I-word Record Descriptor Word (RDW)
at the head of the
record.
This word contains (in the left half-word) a count of all
bytes in the record and in the RDW itself. The right half of the RDW
must be zero.
The records are read and written in groups called
blocks. The actual number of records in a block depends on the
blocking factor specified when the file was created. Each block of
records contain a I-word Block Descriptor Word (BDW) which contains a
count (in the left half-word) of the bytes in the block. That is, the
bytes of data and the bytes of the RDW for each record in the block
and the 4 bytes of the BDW itself are incLuded in the block count.
The following illustrates the format of blocked variable-length EBCDIC
records:

8-18

FILE FORMATS
WORD

RECORD

BOW

ROW

201

BOW

202

ROW

203

ROW

BLOCK

204
205
206
207

0
C

BOW = BLOCK DESCRIPTOR WORD
ROW = RECORD DESCRIPTOR WORD
MR-S-048-79

Figure 8-19 Blocked Variable-Length EBCDIC

8-19

FILE FORMATS
CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS V.
DATA DIVISION.
FILE SECTION.
FD filename
VALUE OF 10 "DATA
BLOCK CONTAINS 1 RECORD.
DISPLAY-9.
01 record-l
PIC S9(7) COMP-3.
02 field-l
02 field-2
PIC S9(7) COMP-3.
PIC X(3).
02 field-3
02 field-4
PIC A(2).
PIC S9(9) COMP-3.
02 field-5
PIC X(6).
02 field-6
01 record-2
02 field-l
02 field-2
02 field-3
02 field-4
02 field-5
02 field-6

FILII

DISPLAY-9.
PIC S9(7) COMP-3.
PIC S9(7) COMP-3.
PIC X(3).
PIC A(2).
PIC 9(9) COMP-3.
PIC X(9).

PROCEDURE DIVISION.
LOAD-PARAGRAPH-l.
MOVE +9356127 TO field-l OF record-I.
MOVE 3987156 TO field-2 OF record-I.
MOVE 11198 11 TO field-3 OF record-I.
MOVE IIMN II TO field-4 OF record-I.
MOVE -569138279 TO field-5 OF record-I.
MOVE IIABCDEF II TO field-6 OF record-I.
WRITE record-I.
LOAD-PARAGRAPH-2.
MOVE -3295865 TO field-l OF record-2.
MOVE 9378518 TO field-2 OF record-2.
MOVE 11196" TO field-3 OF record-2.
MOVE IIAL" TO field-4 OF record-2.
MOVE 569138279 TO field-5 OF record-2.
MOVE IIABCDEFGHI" TO field-6 OF record-2.
WRITE record-2.

Figure 8-20 illustrates the record produced by the code segment
above:

8-20

shown

FILE FORMATS

BOW

ROW

0
0
I

9:3

5:6

1 12

I
I

3i 9

8: 7
1

1 5

6:+
1

5:6

9 :1

3: 8

I
I

2:7

9: -

E
~

BOW

7; +

..".r

.A.

'""'-V

ROW

31
I

3:2

9; 5

8:6

0
1
51
I

I
I

9:3

7:8

81+
A

5: 1
1

5:6
1

!
I

3:8

91+

2: 7
I

~~~--<

MR-S-049-79

Figure 8-20

8.2.6

COBOL Blocked Variable-Length EBCDIC

BINARY File Formats

Binary records consist of contiguous 36-bit words.
Each record starts
and ends on a word boundary.
Binary is the only recording mode which
does not have a character set associated with it, and standard binary
records can only be
interpreted as COMPUTATIONAL and COMP-l binary
numbers.
However, it is possible to associate a character set with
binary records by writing mixed-mode
records.
COBOL programs are
capable of writing three mixed-mode binary formats.
Each format
is
shown below:

8-21

FILE FORMATS
8.2.6.1

COBOL ASCII Mixed-Mode Binary -

CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS BINARY.
DATA DIVISION.
FILE SECTION.
FD filename
01 binary-rec
02 field-l
02 field-2
02 field-3
02 field-4
02 field-5
02 field-6
02 field-7

VALUE OF ID "DATA
DISPLAY-7.
PIC S9(10) COMPo
COMP-l.
PIC X(7).
PIC 9(11) COMPo
PIC X(3).
PIC 9(14) COMPo
PIC A(2).

FIL".

PROCEDURE DIVISION.
LOAD-PARAGRAPH.
MOVE 1234568910 TO field-I.
MOVE 1246.5978 TO field-2.
MOVE "ABCDE12" TO field-3.
MOVE 12345678954 TO field-4.
MOVE "532" TO field-50
MOVE 12345678954967 TO field-6.
MOVE "LM" TO field-7.
WRITE binary-rec.

Figure 8-21 illustrates the record produced by the code segment
above:

8-22

shown

FILE FORMATS

1234568910
2

1246.597892

I D I

L
5

12345678954

8
'--

12345678954967

9
10

M
MR-S-050-79

Figure 8-21

COBOL Standard Binary and ASCII Mixed-Mode Binary

8-23

FILE FORMATS
8.2.6.2

COBOL SIXBIT Mixed-Mode Binary -

CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS BINARY.
DATA DIVISION.
FILE SECTION.
VALUE OF ID "DATA
DISPLAY-6.
PIC S9(10) COMPo
COMP-l.
PIC X(7).
PIC 9(11) COMPo
PIC X(3).
PIC 9(14) COMPo
PIC A(2).

FD filename
01 binary-ree
02 field-l
02 field-2
02 field-3
02 field-4
02 field-5
02 field-6
02 field-7

FIL".

PROCEDURE DIVISION.
LOAD-PARAGRAPH.
MOVE 1234567891 TO field-I.
MOVE 1234.5921 TO field-2.
MOVE IABCDE12" TO field-3.
MOVE 12345678954 TO field-4.
MOVE "532" TO field-5.
MOVE 12345678954967 TO field-6.
MOVE "LM" TO field-7.
WRITE binary-ree.

Figure 8-22 illustrates the record produced by the code segment
above:

shown

WORD

12345678910
1234.592175

I c I DIE I 1

L
5

12345678954

I 2 I

8
12345678954967

'--

9
10

l
MR-S-051-79

Figure 8-22

COBOL Standard Binary and SIXBIT Mixed-Mode Binary

8-24

FILE FORMATS
8.2.6.3

COBOL EBCDIC Mixed-Mode Binary -

VALUE OF ID "DATA
DISPLAY-9.
PIC S9(lO) COMPo
COMP-l.
PIC X(7).
PIC 9(11) COMPo
PIC 9(3).
PIC 9 (14) COMPo
PIC A(2).
PIC S9(5) COMP-3.
PIC 9(8) COMP-3.

FIL".

PROCEDURE DIVISION.
LOAD-PARAGRAPH.
MOVE 1234567891 TO field-I.
MOVE 1246.5978 TO field-2.
MOVE "ABCDE12" TO field-3.
MOVE 12345678954 TO field-4.
MOVE "532" TO field-5.
MOVE 12345678954967 TO field-6.
MOVE "LM" TO field-7.
MOVE -72539 TO field-8.
MOVE 36193586 TO field-9.
WRITE binary-rec.

Figure 8-23 illustrates the record produced by the code segment
above:

8-25

shown

FILE FORMATS

12345678910
1246.597861

12345678954

8
12345678954967

9
10

7:2

9 :-

6: 1

5 :8

J
5 :3
I

I
I

9 :3

:+
MR-S-052-79

Figure 8-23

COBOL Standard Binary and EBCDIC Mixed-Mode Binary

8-26

FILE FORMATS
8.3

FILE ORGANIZATION AND ACCESS

File organization refers to the manner
in which the records are
arranged in a file.
File access refers to the method by which records
in the file are read and written.
COBOL-68 supports three types of
file organization:
sequential, random, and indexed-sequential.
Each
type of file organization has a corresponding method of access.
Sequential files are accessed sequentially only, that is, in the order
in which they are recorded.
Random and indexed-sequential files can
be accessed either sequentially or randomly.
You use the ACCESS MODE clause in the Environment Division to specify
the method of access which you wish to use.
The chart below shows the
types of COBOL-68 files and the methods by which they can be accessed.
File Organization

Method of Access

ACCESS MODE

Sequential

SEQUENTIAL

Random

Sequential
Random

SEQUENTIAL
RANDOM

Indexed

Sequential
Random

SEQUENTIAL
INDEXED

In the following sections, file types are described in greater detail,
along with the methods by which they can be accessed and the manner in
which these methods are specified.

8.4

SEQUENTIAL FILES

Sequential files are those files that can only be read or written
sequentially,
that is,
starting at the first record in the file and
continuing with each subsequent record until
the end of the file.
Sequential files can reside on any file medium:
cards, paper tape,
DEC tape (DECsystem-lO only), magnetic tape, and disk.
If the file
contains a
large amount of data that is read and written frequently,
it should be stored on magnetic tape or disk.
Since tape storage is
normally less expensive than disk storage, magnetic tape is often used
for such files.
However, if it is necessary to have rapid access to
the data, disk storage can be preferable to tape storage.
Sequential
files on disk or DEC tape should not be blocked unless they are to be
open for
input/output.
When the files are stored on magnetic tape,
they should be blocked to reduce wasted space caused by inter-record
gaps.
A sequential file can be open for input/output (updating), but it must
be blocked for this purpose and must reside on disk.
If a sequential
file is open for input/output, a write to the file causes writing of
either
the last record read (if the last operation was a READ) or the
record after the last record written (if the last operation was a
WRITE) .

8.5

RANDOM FILES

Random files are arranged like sequential files,
but differ
from
sequential files
in the method by which they are accessed and in the
devices on which they must be stored.
The following requirements must
be fulfilled for a random file:

8-27

FILE FORMATS
1.

It must be on a random-access device.

It must be blocked.

Random files can be accessed sequentially by declaring ACCESS MODE IS
SEQUENTIAL in the SELECT statement of the FILE-CONTROL paragraph.
This declaration allows you to treat your random file exactly like a
sequential one.
If you declare this, you must deal with the records
in the order in which they are recorded - you can not access records
by their relative position in the file.
Random files can be accessed randomly by declaring ACCESS MODE IS
RANDOM in the SELECT statement.
This declaration allows you to
process records in any order you choose.
You must specify the
data-name of the
item which holds the relative record number of the
record you wish to access in the random file.
This item is called the
ACTUAL
KEY,
and
is specified in the SELECT statement in the
Environment Division.
You must also specify the maximum range of
relative record numbers in the FILE-LIMIT clause, which is also in the
SELECT statement.
The data-name specified by the ACTUAL KEY must be described
in the
Working-Storage section of the Environment Division as a COMPUTATIONAL
item of 10 or fewer digits.
Its picture can only contain the
characters Sand 9 (or their equivalent, such as S9(4)).
The ACTUAL
KEY specifies to the object-time system the location of a
record
relative to the beginning of the file.
That is, the ACTUAL KEY of the
first record in the file is 1, that of the second is 2,
and that of
the last is n where n is the number of records in the file.
Some records in a random file can be zero-length;
that
is,
they do
not have anything written in them because the file was created
randomly.
These records have ACTUAL KEYs and can be written but
cannot be read until information is placed into them.
If an attempt
is made to read zero-length records, the INVALID KEY path is taken.
You can create a random file by declaring its ACCESS MODE to be RANDOM
and writing out records to the file.
You can write the records either
randomly or sequentially.
To create a file
randomly
(that is,
by
writing
into scattered or random records), you must open the file for
output, move an integer value into the ACTUAL KEY for each record to
be
written,
and write each record.
To create a
random file
sequentjally, simply open the file
for
output and begin writing
records.
The ACTUAL KEY defaults to the next record in the file, and
the records are entered sequentially. No zero-length records are in
the file if it is written sequentially.

8.5.1

Sequential Access Of Random Files

A random file can be accessed sequentially if you specify ACCESS MODE
IS SEQUENTIAL in the FILE-CONTROL paragraph of the Environment
Division.
Read operations on such a
file
retrieves succeeding
records,
starting with the first non-zero-length record on the file,
and continuing with each successive non-zero-length record.
Any
zero-length records are skipped by the sequential read operation. A
successful sequential READ or WRITE updates the file's ACTUAL KEY
value to indicate the current record position.

8-28

FILE FORMATS
The AT END or INVALID KEY condition occurs if:
1.

A READ is made to a non-existent record
End-of-File

A WRITE is made to a
record

8.5.2

lo~ation

containing

this
a

logical

non-zero-length

Random Access Of Random Files

A random file can be accessed at scattered locations
if you specify
the clause ACCESS MODE IS RANDOM in the FILE-CONTROL paragraph of the
Environment Division.
In this case the record accessed is the one
indicated by the current value of the ACTUAL KEY.
The first record on
the file is assigned the key of 1, with succeeding records numbered
2, 3, 4, ....
Therefore,
before you execute a random I/O operation,
you must specify the record by moving the value you desire
into the
ACTUAL KEY for
the file.
Non-zero-length records can be updated by
the use of the WRITE clause, assuming that the file is open for
I/O
and that the previous I/O operation was a successful READ of the
record in question.
The INVALID KEY condition occurs if:
1.

A READ is made to a zero-length record

A WRITE is made to a non-zero-length record

A random file can be treated as a sequential file
by declaring
its
ACCESS MODE to be SEQUENTIAL, but the file cannot be read or written
randomly when this declaration has been made.
However, if you declare
that the ACCESS MODE IS RANDOM, you can access the records randomly or
sequentially.
You can access the records sequentially by moving
zero
to the ACTUAL KEY and acting as if the ACCESS MODE were SEQUENTIAL.
The following example shows the statements used to update a
random
file sequentially when the ACCESS MODE has been declared to be RANDOM.

8-29

FILE FORMATS
ID DIVISION.
PROGRAM-ID. RNDTST.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT RNDOUT ASSIGN TO DSK
ACCESS MODE IS RANDOM
FILE LIMIT IS 100
ACTUAL KEY IS RNDKEY.
DATA DIVISION.
FILE SECTION.
FD RNDOUT
BLOCK CONTAINS 1 RECORD
RECORDING MODE IS ASCII
VALUE OF ID IS "FOO
FIL".
01 RNDREC.
03 BEGIN-REC
PIC S999 USAGE COMPo
03 MID-REC
PIC 9(4).
03 FILLER
PIC X(50).
WORKING-STORAGE SECTION.
77 RNDKEY PIC 9(10) VALUE ZERO USAGE COMPo
PROCEDURE DIVISION.
START.
OPEN INPUT-OUTPUT RNDOUT.
READ-AND-UPDATE-PARA.
READ RNDOUT, INVALID KEY GO TO FINISH.
PERFORM UPDATE-ROUTINE.
WRITE RNDREC, INVALID KEY GO TO ERROR-ROUTINE.
GO TO READ-AND-UPDATE-PARA.
FINISH.
CLOSE RNDOUT, STOP RUN.
UPDATE-ROUTINE.

ERROR-ROUTINE.
DISPLAY "ERROR REPLACING RECORD", DISPLAY "RNDKEY ="RNDKEY.
GO TO FINISH.
Figure 8-24

8.6

Statements Used to Sequentially Access a Random File

INDEXED-SEQUENTIAL FILES

Indexed-sequential
files
(also
called
ISAM
files,
for
indexed-sequential access method)
are files
in which records are
accessed through a hierarchy of indexes according to a key within each
data record.
This file organization is commonly used for applications
in which the programmer wishes to identify and access records by the
contents of a data field (the key) rather than the relative location
of the record within the file.
Some examples of applications for
which this file organization is commonly used are:
• Payroll
•

(key is employee number)

Inventory control

(key is part number)

• Production control (key is job or batch number)
8-30

FILE FORMATS
An indexed-sequential file consists of two files:
the indexed data
file containing the actual data and the index file containing pointers
to record keys within the indexed data file.
The location of the
record key within each record is specified when the file is built.
To
build an indexed-sequential file, you must provide a sequential file
and some necessary information to the ISAM program.
(See Section 7.1,
ISAM, Indexed-Sequential File Maintenance Program.)
ISAM then copies
the data from the sequential file and creates an indexed data file and
an index file to reference the indexed data file.
All reading and writing of the index file
is performed by the
object-time system;
you need not be concerned with this function.
When using indexed-sequential files,
you need only specify which
record is to -be read, written, rewritten, or deleted.
The object-time
system performs all searching, insertion, deletion,
and updating of
both the index and indexed data files.
Indexed-sequential files must be accessed from disk.
Also,
because
each indexed-sequential file is actually two files, two software I/O
channels are required - one for the indexed data file and one for
the
index file.

8.6.1

Indexed Data File

The indexed data file can be recorded in EBCDIC, SIXBIT or ASCII;
in
any
mode,
the
file
must
be
blocked.
When
building an
indexed-sequential file (by means of the ISAM utility program),
you
must provide a sequential file that contains record keys in the same
relative location in each record.
You are advised to sort the file in
advance to insure that the most efficient index is built.
Each record
must have a unique key and the keys must be arranged
in ascending
order (numeric, alphabetic, or alphanumeric).
You can indicate to the
ISAM program that some records in each block are to be left empty and
some empty blocks should be added to the file.
The empty records and
blocks are to allow for insertion or addition of new records in the
file.
When a program processes the indexed-sequential file,
insertions and
additions are made by the object-time system.
Records are inserted in
a block in ascending order.
When there are no empty record slots in
the block, the block is split into two more-or-less-equal blocks, and
the record is added to the appropriate block.
New blocks created by
insertions or additions are placed in the empty blocks that were
allocated when the file was built.
If empty records and blocks were
not provided when the file was built, the object-time system requests
additional blocks from the monitor as needed.
If the monitor cannot
allocate additional blocks
(that is, because your quota on the file
structure is exceeded or the system's limit was reached),
an error
message is issued.
The format of the indexed data file is similar to that of
sequential files, with the following exceptions:

random

and

The right half of the header word contains the size of the
record ln bytes;
the left half contains a version number.
Only the version number of the first record of a block has
any meaning;
it pertains to all records for that block.
All
records (ASCII, SIXBIT, and EBCDIC) have a header word.

All records are line-blocked;
they occupy an integral number
of words.
ASCII
records always end with a single carriage
return/line feed pair.
8-31

FILE FORMATS
3.

For ASCII records, the left half of the header word contains
a version number, bits 18 through 34 contain the size of the
record in bytes, and bit 35 is always 1.

Figure 8-25 shows the structure of an ISAM data file.

.IDA

DATA

BLOCK STRUCTURE

RECORD

HEADER

DATA

FILE

STRUCTURE

WORD

WORDS

BLOCK

NO. OF CHARACTERS
(SIXBIT OR ASCII)

NUMBER

SIXBIT OR ASCII DATA (NOTE ON PADDING CHARACTERS
ZEROES FOR ASCII, AND SPACES FOR SIXBIT)
MR-S-053-79

Figure 8-25 ISAM Data File Structure

8.6.2

Index File

The index file is created by the ISAM program from the description of
the
input sequential data file and your parameters.
It contains to
ten levels of indexes, the lowest of which contains pointers to the
record
keys in the data file.
Each successive level of index points
to all blocks containing the next lower-level
index.
The highest
level
index is contained in one block and points to the blocks
containing the next lower-level index.
Index levels are provided so
that the entire index need not be searched each time that a record key
is accessed.
When a record key is accessed,
the object-time system
reads the highest-level index to find which lower-level index contains
a pointer to the approximate location of that key.
The block of the
next lower-level
index that contains the approximate location of the
key is then searched.
If this is the lowest-level index, it points to
the first record of the data block in which the record is stored.
The
data block is then searched for the appropriate record key,
and the
record
is made available.
If this is not the lowest-level index, the
next lower level is searched until
the lowest level
is reached.
Figure 8-26 illustrates the search.

8-32

FILE FORMATS

POINTERS
TO DATA

KEYS

r------r-~.L,

1 •

2 D

POINTERS
TO NEXT
USERS

LEV
IEL

:~~~~~T!ITH
KEY~

3 G

POINTERS
TO NEXT

KEYS

DATA BLOCK 2

INDEX BLOCK 1

r----r--'--1--r---L-,.

:~~:~::---1R-I*

I------I-I

NDEX

.:oC I-01-----'

: : \

'NDEX .LOCK 6

,NDEX

INDEX LEVEL 2
(HIGHEST)

.LOC~

I
I
I

DATA BLOCK 1

BLICKS

DATA BLOCK 3

I I

R
8 V

9 Y

INDEX BLOCK 5

INDEX LEVEL 1
(INTERMEDIATE)

INDEX BLOCK 3
INDEX LEVEL 0

DATA BLOCK 4

(LOWEST)

*=LOW VALUES

INDEX FILE

DATA FILE
MR-S-054-79

Figure 8-26

Locating a Record in an Indexed-Sequential File

The format of the index file is more complex than that of the indexed
data file.
Figure 8-27 shows an overview of the structure of the
index file.

8-33

FILE FORMATS

IN .IDX FILE

./OX BLOCK STRUCTURE

HEADER WORD 1

INDEX LEVEL

NO. OF CHARS IN BLOCK
(AS IF SIXBIT)

I VERSION NO. OF THIS BLOCK

HEADER WORD 2

INDEX ENTRIES

AS SPECIFIED IN ISAM DIALOG

INDEX ENTRY STRUCTURE

IPOINTER TO NEXT LOWER LEVEL OF INDEX OR DATA
I VERSION NO. OF BLOCK POINTED TO

WORD 1
WORD 2
WORDS 3·11

VALUE OF KEY

COMPUTATIONAL IF NUMERIC
OR SIXBIT CHARACTERS
MR-S-055-79

Figure 8-27 ISAM Index File Structure
Each index block in an indexed-sequential file is written as
were a block of a SIXBIT file.
The format of the block is:

header word 1:

is the header word.
The right half contains
the size of the index block in characters, as
if it were SIXBIT (that is,
six characters
per word).
The left half contains a number
representing the level of the
index
(the
lowest level is 0).

header word 2:

contains the version
number.
This
is
initially set to 0 by the ISAM program, and
is incremented by 1 whenever
this block is
divided due to the insertion of an entry when
a WRITE is executed.

Following word 2 are the index entries.

Each entry has the format:

word 1:

contains the pointer to a data block (if this
is index level
0) or a pointer to the next
lower-level index block
(if this
is index
level 1 or higher).

word 2:

contains the version number of the
index or
data block to which the index entry points.

8-34

FILE FORMATS
words 3-11:

contain the value of a key.
If the key is
nonnumeric,
it extends over as many words as
are necessary.
If the key is numeric, it is
kept
in COMPUTATIONAL form
(even if the
record key for the file is DISPLAY).
It is
one word· if 10 or fewer digits are in the
key;
it is two words if 11 or more digits
are
in
the
key.
If
the
key
is
COMPUTATIONAL-l (floating point), it is one
word.
NOTE

Take special care to describe your
key
fields
in exactly the same way in both
the ISAM program and your COBOL program.
For example,
if you describe your key
field as S9(10)
DISPLAY to
ISAM,
you
should describe it the same way in your
COBOL program.
By using
the
same
descriptions you ensure that appropriate
key matches are made, and that the same
amount of storage is generated in both
the ISAM file and its record area in
memory.
within the index file, in addition to the index blocks, are two other
blocks:
the statistics block and the storage allocation table.
The
statistics block is a header containing all the necessary information
about the
index file and the indexed data file.
Included in these
statistics are:
the name and extension of the data file,
the number
of levels in the index, the blocking factor, and a description of the
record key.
The storage allocation table is a bit table that shows
which data blocks are in use and which are free.
There are as many
blocks of this table as are necessary to contain this information.
In constructing an ISAM file you must consider not only optimizing
disk block usage,
but also the number of levels of indexes in the
index file.
An indexed-sequential file should be constructed so that
it does not require more than three levels of index, because the more
levels of index there are, the slower the access of the data will
be.
Indeed,
it is usually a simple matter to restrict a file of moderate
size to two levels of index.
For example, if the maximum file
is to
be 200,000 records, the blocking of the indexed data file could be 20
records per block and that of the index file 100 entries per block.
Since
100*100*20

= 200,000

the file
never needs more than two levels
occasionally maintained using the ISAM program.

8-35

of
index
if
it
(See Section 7.1)

CHAPTER 9
SIMULTANEOUS UPDATE

The COBOL-68 simultaneous update facility allows sequential,
random,
or
indexed-sequential data files to be updated concurrently by two or
more running
jobs.
That is,
it is possible for
several
truly
independent jobs to modify,
insert, and delete records in the same
data files without loss
of
information
or
file
integrity.
Simultaneous update,
under the control of COBOL-68, allows multiple
users to share resources at the file level while having exclusive
control of a portion of that resource at the record level.
You should also refer to Part 2 of this manual,
COBOL-68 Language
Reference Material, for the simultaneous update features of the OPEN,
RETAIN, and FREE statements.
To declare in your program that a file
is
being
processed concurrently with other programs,
use the
appropriate syntax available with the OPEN statements.
(See Section
9.1.1, The OPEN Statement.)
The OPEN statement identifies the file as
being open for
simultaneous update and excludes most users from
accessing it until you are ready to release it.
However, users who
attempt to open a file for READ access only, can open the file even if
you already have it open under simultaneous access.
The file is not
released until you expressly close it by issuing a CLOSE statement.
To gain exclusive control of individual records within the file,
use
the
RETAIN
statement.
(See
Section
9.1.2,
The
RETAIN
Statement.)
This statement inhibits any other user from accessing the
retained records until you have finished processing them.
Records 'can
be released either:
•

Explicitly, by issuing a FREE statement
The FREE Statement)

(see

Section

9.1.3,

•

Implicitly, by exhausting the verb selection specified on
preceding RETAIN statement

the

You are advised to make careful use of the RETAIN statement in order
to
avoid
the two most common problems that can occur using
simultaneous update.
The first, buried update, occurs when two users
are updating the same record concurrently and one user's update is
overlaid by the other's.
(See Figure 9-1, The Problem of Buried
Update.)
The second is deadly embrace.
It occurs when two users make
conflicting demands upon the file resources and neither is willing or
able to yield to the other. This results in both users being stalled
waiting for the other to relinquish control.
(See Figure 9-2, The
Problem of Deadly Embrace.) Both of these problems can be avoided by
carefully declaring the resources needed with a RETAIN statement prior
to performing any I/O operations on a shared file.

9-1

SIMULTANEOUS UPDATE

. FILE RESOURCE IS AVAILABLE TO ALL USERS INDISCRIMINANTLY

PROGRAM A
ACCEPT KEY·A
READ FILE-A

PROGRAM B
ACCEPT KEY-A
READ FILE-A

3_
PROGRAM A
REWRITE RECORD-A

4.
PROGRAM B
REWRITE RECORD-A

NOTE: PROGRAM A'S UPDATE IS NOW LOST.

MR-S-056-79

Figure 9-1

The Problem of Buried Update

9-2

SIMULTANEOUS UPDATE

INDIVIDUAL FILE RESOURCES ARE AVAILABLE TO ONLY ONE USER AT
ONE TIME.

1.
PROGRAM A
ACCEPT KEY-A
READ FILE-A WITH LOCK

2.
PROGRAM B
ACCEPT KEY-B
READ FILE-B WITH LOCK

PROGRAM A
ACCEPT KEY-B
READ FILE-B WITH LOCK

(PROGRAM A IS DENIED ACCESS TO KEY-B OF FILE-BI

4.
PROGRAM B
ACCEPT KEY-A
READ FILE-A WITH LOCK

(PROGRAM B IS DENIED ACCESS TO KEY-A OF FILE-AI

NOTE: PROGRAMS A AND B ARE NOW STALLED, AS EACH HAS A LOCK ON A
RESOURCE THAT THE OTHER WANTS, AND NEITHER CAN GIVE UP THE
RESOURCE THAT THEY ALREADY HAVE A LOCK ON.

MR-S-057-79

Figure 9-2

9.1

The Problem of Deadly Embrace

PROGRAMMING CONSIDERATIONS

Simultaneous update allows you to declare the usage you want at both
the file and record level.
It also allows you to declare the usage
you are allowing others to have while you have control of the file. A
central clearing house in the COBOL-68 object-time system correlates
these projections and takes one of three actions with respect to the
intent of each user:
•

Allows the process to proceed

•

Suspends the process until the required resource is available

•

Returns with a message to the effect that the
proceed at this time

process

cannot

You declare file usage by specifying which
of
the
COBOL-68
input/output verbs you execute during your tenure of the file or
record and which you allow others to execute.
Once allowed to
proceed, you are bound by the object-time system to act within the
scope of your projections and are stopped if you attempt to do
otherwise.
For example, if you open a file for a read operation and
then issue a write you are stopped from doing so.
See Figure 9-3 for
an outline of how resources can be declared for simultaneous update.

9-3

SIMULTANEOUS UPDATE
PROCEDURE DIVISION.
BEGIN-PARAGRAPH.
OPEN 1-0 FILE-NAME-l FOR [verb selection]
ALLOWING OTHERS [verb selection]

(File-wide specification'of
resources)

UNAVAILABLE [Object statements].
LOOP-PARAGRAPH.
[Generate key values for records to be
retained]
RETAIN FILE-NAME-l RECORD KEY .••
FOR [verb selection]
UNTIL FREED

(Specification
of record resources to be
retained and
manipulated
within the
context of a
user-defined
transaction)

UNAVAILABLE [Object statement].
1-0 verb selection as appropriate.
Including READ, WRITE, DELETE,
REWRITE.
FREE [appropriate file records].
GO TO LOOP-PARAGRAPH.
END-OF-JOB.
CLOSE FILE-NAME-l .•.

Figure 9-3

9.1.1

(Release of
file-wide
resource)

Declaring Resources For Simultaneous Update

The OPEN Statement

The OPEN statement is the vehicle by which you declare a file is being
used for simultaneous update.
It allows you to specify:
•

Your projected usage of the
operations you wish to perform

file

terms

•

The projected usage you are willing to allow others
of the I/O operations they are allowed to perform

Figure 9-4 shows the general format of the OPEN statement.

9-4

the
in

I/O
terms

SIMULTANEOUS UPDATE

{5~~~~T}

file-name-I

{~UT -OUTPUT}

[WITH NO REWIND] [,file-name-2[WITH NO REWIND]]. ••

fi le-name-3

FOR
!

[

REWRITE
READ
AND ! WRITE

QU.lli

..•

ANY VERB

~~~~ITE I ~~C~ITE IJ . J

ALLOWING OTHERS!
---WRITE
DELETE
ANY VERB

tND
- - ! WRITE
DELETE
ANY VERB

~~~~~TE I 1~~~~~TE I] . .

OPEN
, fi le-name-4

REWRITE
READ
WRITE
DELETE
ANY VERB

[EQR! DELETE

t.8.!:ill

ANY VERB

ALLOWING OTHERS!

DELETE
ANY VERB

~TE ItND ~TE I]· .JlIUI
!

DELETE
.8NY VERB

[

DELETE
llli1. VERB

[EXTEND] fi le-name-5 [ fi le-name-6 ] .••
[UNAVAILABLE statement-I. [,statement-2] ••• ]

Figure 9-4

-=-

The OPEN Statement

The following rules apply to the use of an OPEN
being processed under simultaneous update:

statement

for

files

To open a file under simultaneous update, the ALLOWING OTHERS
clause must be specified.

Every user, that is, every program expecting to process the
file
concurrently,
must
open
the file either under
simultaneous update or for input only.
Other users are
denied access.
NOTE
File access is determined on a first come first
served basis.
Therefore, if the first user opens a
file for simultaneous update, all
others
must
likewise open it under simultaneous update - unless
the user who is not under simultaneous update wishes
to open the file for READ access only. Conversely,
if a file is open for normal processing, users
attempting to open it under simultaneous update are
denied access. See Figure 9-5, Competing For Program
Access to Files.
9-5

SIMULTANEOUS UPDATE
3.

The file must be OPEN in I/O mode.

The COBOL-68 I/O verbs you intend to execute must be
following the key word FOR.

The COBOL-68 I/O verbs you are willing to allow others to
execute must be entered following
the key words ALLOWING
OTHERS.

All files to be opened for simultaneous update must be opened
in the same OPEN statement.
Multiple OPEN statements for
simultaneous update are not allowed.
Therefore,
before
another
file can be opened for
simultaneous update, the
previously opened files must be closed.
This prevents deadly
embrace at the file level.

You can use the same OPEN statement to open files
simultaneous update as well as for normal processing.

A maximum of sixteen (16) files can be opened by a single
OPEN statement.
In fact, a maximum of sixteen files can be
open at once, regardless of the number of OPEN statements
involved in opening them.

If one or more of the files being opened for
simultaneous
update
is not available in the mode specified, the program
requesting the OPEN is suspended until the requested file
is
available.
Those files, if any, that were opened during the
process remain open~
Control is not returned to the program
until
all
!of the requested files are open.
If the
UNAVAILABLE clause is specified,
no file
is opened,
even
though available,
until all of the requested files are
available.
In this case,
the statements following
the
UNAVAILABLE clause are executed.

10.

The I/O verbs specified in the OPEN statement are the only
verbs that can be used to process the file.
Likewise, the
I/O verbs you allow others to use are the only ones available
to them.
Any attempt to use verbs other than the ones
specified causes the object-time system to abort the program.

Example 9-1
OPEN I/O FILE-A FOR READ AND WRITE,
ALLOWING OTH&RS READ AND WRITE.
Example 9-2
OPEN OUTPUT FILE-A, LIST,
INPUT-OUTPUT FILE-B FOR READ AND REWRITE,
OTHERS ANY
FILE-C FOR READ,
OTHERS READ AND REWRITE,
FILE-D FOR ANY,
OTHERS NONE,
INPUT FILE-E WITH NO REWIND,
1-0 FILE-F, FILE-G FOR WRITE.

9-6

entered

for

SIMULTANEOUS UPDATE
Example 9-3
OPEN I-O FILE-A FOR READ AND WRITE,
OTHERS ANY,
UNAVAILABLE OPEN I-O FILE-A FOR READ,
OTHERS ANY,
UNAVAILABLE STOP RUN .

. WITH AND WITHOUT SIMULTANEOUS UPDATE

1.
PROGRAM A
OPEN FI LE·A FOR
SIMUL TANEOUS UPDATE

PROGRAM B
OPEN FILE·A FOR
INPUT ONL Y

PROGRAM C
OPEN FILE·A WITHOUT
SIMULTANEOUS UPDATE

~
/

FILE·A

()

FI LE.A

()

1.
PROGRAM C
~

OPEN FILE·A WITHOUT
SI M U
r--_ __ _ L_T_A_NE_O_U_S_U_PD_A_T_E--.

..---1'.

PROGRAM A

- .

OPEN FILE·A UNDER
SIMULTANEOUS UPDATE

MR-S-058-79

Figure 9-5

9.1.2

Competing For Program Access to Files

The RETAIN Statement

The RETAIN statement allows you to gain exclusive control
of
individual records within a file that was previously opened for
simultaneous update. Figure 9-6 shows the general format of the
RETAIN statement.

9-7

SIMULTANEOUS UPDATE

RETAIN

file-name-l

FOR

READ
REWRITE
READ-REWR ITE
DELETE
WRITE
READ-WRITE
ANY VERB

•fi le-name-2

FOR

RECORD

READ
REWRITE
READ-REWRITE
DELETE
WRITE
READ-WRITE
ANY VERB

[UNAVAILABLE

RECORD

[KEY

identifier-I}]
{ literal-I

AND

READ
REWRITE
READ-REWRITE
DELETE
WRITE
READ-WRITE
ANY VERB

[KEY

{ identifier-2}]
literal-2

AND

READ
REWRITE
READ-REWRITE
DELETE
WRITE
READ-WRITE
ANY VERB

statement-l

[ UNT IL

FREED]

[ UNTI L FREED]

[,staternent-2 ]

Figure 9-6

The RETAIN Statement

'rhe following general rules apply to the use of the RETAIN statement.
For
a description of how the RETAIN statement is used for the
individual file types - sequential, random, indexed-sequential
see
Sections 9.1.4, 9.1.5, and 9.1.6 respectively.
(See also the COBOL-68
Language Reference Material, Part 2 of this manual.)
1.

The file(s) named
in a RETAIN statement must have been
If not, the
previously opened under
simUltaneous update.
object-time system aborts the program.

A RETAIN statement must be given before any record on a
opened for simUltaneous update can be accessed.

You can use the same RETAIN statement to reserve records on
sequential,
random,
or
indexed-sequential files.
The I/O
verbs selected, however, must conform to those allowed for
the file.

All records to be retained concurrently must be retained with
the same RETAIN statement.
Once records have been retained,
no other records can be retained until the currently retained
records are freed.

9-8

file

SIMULTANEOUS UPDATE
5.

The retention of records is purely a logical operation and
does not involve any actual I/O.
You can, in fact, retain
nonexistent records.
Obvious~y,
any attempt to read or
rewrite any of these records could result in an I/O error
that could cause your program to be terminated.
(See note
6.)

A RETAIN statement, consistent with note 5, does not cause an
AT END condition.
This can only be caused by a READ
statement.
The RETAIN statement in this case merely retains
a nonexistent record after the last one in the file.

If you retain a record for a READ operation, other users are
allowed concurrent access to that record for READ.
If you
retain a recbrd for any other type of I/O, all other users
are denied access until you have freed it.

The I/O usage you specify in a RETAIN statement must agree
with the usage you specified in the OPEN statement for the
file.
For example, if you want to retain a
record for a
WRITE operation, you must have specified WRITE in the OPEN
statement for the file.
This holds true as well for the ANY
VERB option. The key words ANY VERB must appear in the OPEN
statement if you want to use them in a RETAIN statement.

The records named in the RETAIN statement are automatically
freed upon execution of the I/O verbs specified in the FOR
clause. The only exceptions are:
a.

If the ANY VERB option is specified in the FOR clause,
FREE statement must be issued to release a record.

If the UNTIL FREED option is specified, a FREE
must be issued to release a record.

statement

NOTE
The UNTIL FREED option allows you to
retain
several
logically related
records for processing without their
being automatically freed by the I/O
verbs.
c.

If an I/O verb is specified in a RETAIN statement but
that verb is not executed, the record is not freed until
a FREE statement is issued.

10.

The KEY phrase allows you to specify a particular
more than one record in a file.

11.

The value of the key can be specified by any identifier that
can be subscripted, qualified, or both.
Its usage, however,
must be COMPUTATIONAL.
For example:
RETAIN FILE-A RECORD
KEY PAY-REC OF RECORD-KEYS
FOR READ-REWRITE.

9-9

record

SIMULTANEOUS UPDATE
It can also be a positive numeric literal containing
to 10 digits.
You can, for example, enter:

from

RETAIN FILE-A-RECORD
KEY 123
FOR READ-REWRITE.
12.

The optional word RECORD can be used as a reminder
are retaining records, not files.
For example:

that

you

RETAIN FILE-A RECORD FOR READ.
retains the next record in FILE-A.
Be aware, though, that in
most cases the RETAIN statement actually locks up the block
in which the requested record resides.
The only time this is
not true
is in the case of an indexed-sequential file which
is open for WRITE access;
if you retain a
record
in this
file,
the entire file is locked until the record is freed.
This is because all the index blocks must be locked until any
new record is placed into the file.

9.1.3

The FREE Statement

The FREE statement explicitly frees records that have been retained
for
simultaneous update.
Figure 9-7 shows the general format of the
FREE statement.

RECORD [KEY
{i?entifier-l}]
llteral-l

f i 1e- n arne - 1

EVERY RECORD

[ ,fil e-name-2

RECORD [KEY
{i?entifier-2}]
llteral-2

EVERY RECORD

EVERY RECORD
[NOT RETAINED statement-l [,statement-2]

... ] _
MR-S-1055-81

Figure 9-7

The FREE Statement

The following general rules apply to the use of the FREE statement.
For a description of how the FREE statement is used with the
individual file types - sequential, random, and
indexed-sequential
see Sections 9.1.4,
9.1.5,
and 9.1.6 respectively.
(See also the
COBOL-68 Language Reference Material, Part 2 of this manual.)

9-10

SIMULTANEOUS UPDATE
1.

9.1.4

The FREE statement is required to explicitly release records
that have not been implicitly released by an I/O statement.
This could occur when:
a.

The RETAIN statement contains the UNTIL FREED phrase

An I/O statement is not issued after the RETAIN statemeht

The FOR clause of the RETAIN statement specifies ANY VERB

The EVERY RECORD phrase allows you to free all of the records
retained or
just those of a particular file.
It saves you
from having to issue a separate FREE statement for every
record that was retained.

When the EVERY RECORD phrase is used,
the NOT RETAINED
condition occurs only if no records are currently retained or
if no records in a specific file are retained.

The NOT RETAINED phrase specifies the COBOL statements to be
executed in the event that one or more of the record(s) you
are attempting to free have not been retained.
If this
phrase is not specified, the program continues and you are
not notified of any possible error.

A FREE statement issued to a file that was not opened for
simultaneous update causes the statements following the NOT
RETAINED phrase, if present~ to be executed.
If the NOT
RETAINED phrase was not specified in this case, the program
continues and you are not notified of a possible error
condition.

A single FREE statement can be used to free records
from all open files, regardless of file type.

All records,
regardless of how they were
automatically freed when the file is closed.

retained

retained,

are

Accessing Sequential Files

The following sections describe how to use the
statements to access records in a sequential file.

RETAIN

and

FREE

9.1.4.1 Basic Reading - The simplest way to read a sequential file
opened for simultaneous update is to execute pairs of statements like
this:
RETAIN FILE-A FOR READ.
READ FILE-A AT END GO TO EOJ.
The RETAIN statement declares your intent to read the next record of
FILE-A.
The READ statement delivers the next record to the file's
record area in memory, and automatically frees it for
use by other
users.

9-11

SIMULTANEOUS UPDATE
9.1.4.2 Basic Writing - Basic writing of a sequential file opened for
simultaneous update is analogous to basic reading.
For example, you
could use code that looks like this:
RETAIN FILE-A FOR WRITE.
(process record)
WRITE FILE-A-RECORD.
In this case, FILE-A-RECORD is written out to FILE-A and automatically
freed for access by other users.

9.1.4.3 Basic Updating - To update the next record in a file open for
simultaneous upate, you can use statements that look like this:
RETAIN FILE-A FOR READ-REWRITE.
READ FILE-A AT END GO TO EOJ.

REWRITE FILE-A-RECORD.
FILE-A-RECORD is automatically released upon execution of the REWRITE
statement because both verbs named in the RETAIN statement have been
executed.
If only one or none of the verbs were executed, the record
would not have been freed and any attempt to RETAIN any other records
would fail.
If, however, your application is such that you can or can not want to
update a record once it has been read, code of this nature could be
used:
RETAIN FILE-A FOR READ-REWRITE.
READ FILE-A AT END GO TO EOJ.

IF CHANGED REWRITE FILE-A-RECORD
ELSE FREE FILE-A.

9.1.4.4 Access to Sequential File Strategies - There are two reasons
why the basic reading, writing, and updating of sequential files as
outlined in Sections 9.1.4.1, 9.1.4.2, and 9.1.4.3 are not sufficient
for some applications:
1.

Performance

Logically related records

Each time you retain a record and that record happens to be already in
your buffer,
it is necessary to refill that buffer from mass storage
to make sure that you have the very latest copy.
Similarly, each time
a record that you have written or rewritten is implicitly or
explicitly freed, you must be certain that it is the very latest copy,
9-12

SIMULTANEOUS UPDATE
and that no other user has updated that record in the interim.
These
considerations have little effect on the performance of random or
indexed-sequential
files
accessed randomly,
but the effect on
sequentially processed files is profound.
Processing a
file with a
blocking factor of ten, as suggested in Sections 9.1.4.1, 9.1.4.2, or
9.1.4.3, would require an order of magnitude more input/output
overhead than it would if you were not using simultaneous update mode.
This is the performance reason for
using more sophisticated coding
techniques.
Sometimes,
several records in a file are logically
related and must be updated together.
For example,
a header
record
and subsequent trailer
records might be logically related in such a
way that the trailer records cannot be changed unless the header
record remains static.
But with the basic techniques outlined in
Sections 9.1.4.1, 9.1.4.2, and 9.1.4.3, only a single record can be
retained at a time.
This is the logically-related-records reason for
more sophisticated coding techniques.
The first step in providing for more sophisticated code
is the
introduction of a notation for addressing the records of a sequential
file.
The notation is this:
record 0 is defined as the next record
to be read or written.
Records 1,
2,
3, through n are defined
relative to record O.
NOTE
If you have just written a record,
the
next record to be written is the one
following it.
If you have just read a
record,
however,. the next record to be
written
is
the
one
just
read.
Therefore,
if you have
just read a
record and then you retain record 0 for
WRITE,
you have in effect retained the
record just read.
If, however, you have
just read a record and then you retain
record 0 for
READ-WRITE,
you
have
effectively retained the next record in
the file.
Sequential file users should code for performance by retaining several
Performance is optimal if the number of records
records at a time.
retained is a multiple of the blocking factor and the execution of the
A
RETAIN statement is synchronized with logical block boundaries.
RETAIN statement for a file whose b19cking factor is 5 might look like
this:
RETAIN FILE-A KEY 0 FOR READ,
FILE-A KEY 1 FOR READ,
FILE-A KEY 2 FOR READ,
FILE-A KEY 3 FOR READ,
FILE-A KEY 4 FOR READ.

9-13

SIMULTANEOUS UPDATE
This would then be followed by READ and/or FREE statements until all
records have been freed.
Subsequent FREE statements use the same
notation for freeing records as was used for retaining them.
Thus:
RETAIN FILE-A KEY 0 FOR READ,
FILE-A KEY 1 FOR READ.
READ FILE-A AT END GO TO EOJ.

FREE FILE-A KEY 1.
causes the second record of the pair to be freed, not the next one
the file.

Providing a notation for referencing several records of a sequential
file
is not enough for
updating several logically related records
together.
It is also necessary to retain a record,
even though you
are through with it,
until all of the related records have been
processed.
The UNTIL FREED phrase is provided for this purpose.
It
allows you to bypass the automatic freeing of records and retain them
until you are ready to expressly free them.
Also, to facilitate the
freeing of multiple records, the EVERY RECORD phrase is provided.
It
allows you to free every record retained or every record
in a
particular file.
Thus, to update three logically related records in a
particular file, you can code:
RETAIN FILE-A KEY 0 FOR READ-WRITE
UNTIL FREED,
FILE-A KEY 1 FOR READ-WRITE
UNTIL FREED
FILE-A KEY 2 FOR READ-WRITE.
READ FILE-A AT END GO TO EOJ.

WRITE FILE-A-RECORD.
READ FILE-A AT END GO TO EOJ.

WRITE FILE-A-RECORD.
FREE FILE-A EVERY RECORD.
You could also use the ANY VERB phrase to accomplish the same results.
For example:
RETAIN FILE-A KEY 0 FOR ANY VERB
results in your having to expressly free
finished with it.

9-14

the

record

when

you

have

SIMULTANEOUS UPDATE
When retaining records, the program is normally suspended if any of
the requested files or records are unavailable.
You are not notified
of this suspension unless you have provided the UNAVAILABLE phrase as
part of the RETAIN statement. The UNAVAILABLE phrase allows you to
specify a procedure to be followed in the event a record or file
is
unavailable at the time your program attempts to access it.
For
example:
RETAIN FILE-A KEY 0 FOR ANY VERB
UNAVAILABLE PERFORM UNAVAIL-RTN.
This instruc~s the object-time system to execute the statement
following
the word UNAVAILABLE in the event that the file (FILE-A) or
the next record in the file is unavailable at the time the RETAIN
statement is executed.
Similarly, if you execute a FREE statement for a record or
records
that are not currently retained -by your program, the object-time
system proceeds to the next instruction in your program as though the
condition did not exist.
If you wish to be informed of this
condition, you must provide the NOT RETAINED phrase in the FREE
statement.
The NOT RETAINED phrase causes the object-time system to
execute the procedures immediately following the words NOT RETAINED.
A FREE statement of this kind might look like this:
FREE FILE-A KEY 0 NOT RETAINED
GO TO ERROR-RTN.

9.1.5

Accessing Random Files

Accessing records in a random file is similar to the accessing of
There are, however,
sequential file
records.
(See Section 9.1.4.)
these differences:
1.

If a key is not specified, the ACTUAL KEY specified in the FD
for the file is used.

positive keys, whether specified directly or with ACTUAL KEY,
designate fixed (absolute) records of the file (as opposed to
designating records relative to the current record).
Thus,
record 1 is always the first record of the file, not the next
record.
A zero key, on the other hand, is interpreted in the
same way as for sequential files:
record 0 is defined as the
next record to be read or written.

A RETAIN statement, by virtue of its not performing
actual I/O, cannot generate an INVALID KEY condition.

Example 9-4 demonstrates reading a random file sequentially.
Example 9-4
A.

MOVE ZERO TO FILE-A-KEY.
RETAIN FILE-A FOR READ.
READ FILE-A RECORD;

INVALID KEY GO TO ERROR-RTN.

GO TO A.
9-15

any

SIMULTANEOUS UPDATE
Example 9-5 shows how a file can be processed randomly. Note that the
UNTIL FREED clause is used to insure that no one can access the record
until it is written.
Example 9-5
A.

PERFORM RANDOM-KEY-GENERATION.
RETAIN FILE-A KEY GENERATED-KEY
FOR READ-WRITE UNTIL FREED.
READ FILE-A INVALID KEY GO TO ERR-RTN.

WRITE FILE-A-RRCORD.
FREE FILE-A RECORD.
GO TO A.
Example 9-6 shows how to use a field within a record as the ACTUAL KEY
for processing a chain of related records in a random file.
Procedure
A initializes processing with record number 64.
Procedure B insures
that record 64 is stable, that is, that it has not been changed by
some other user after you read it and that it is not changed while you
are processing it.
Example 9-6
A.

MOVE 64 TO FILE-A-REL-KEY.
RETAIN FILE-A FOR READ.
READ FILE-A INVALID KEY GO TO ERR-RTN.

RETAIN FILE-A FOR READ-REWRITE
FILE-A KEY NUMBER OF FILE-A-RECORD
FOR READ-REWRITE.
READ FILE-A INVALID KEY GO TO ERR-RTN.
IF (record not stable)

9.1.6

FREE FILE-A EVERY RECORD.
GO TO B.

(process record 64 and record pointed to by NUMBER)

Accessing Indexed-Sequential Files

Accessing records in an indexed-sequential file is similar to the
accessing of sequential file records.
(See Section 9.1.4.)
There
are, however, these differences:
1.

You can retain records for REWRITE, DELETE, and READ-REWRITE,
in addition to READ, WRITE, and ANY VERB. You can not retain
a record for READ-WRITE.

If no key is specified, the RECORD KEY defined in the
statement for the fiLe is used.

9-16

SELECT

SIMULTANEOUS UPDATE
3.

If a key is supplied, it must be specified with an identifier
that agrees with the file's RECORD KEY in size, class, usage,
and number of decimal places. The only exception is a key
whose usage is COMP;
in th,is case, a positive numeric
literal of ten or fewer digits can be used.

Retaining or freeing records does not affect the "remembered"
key of the file;
that is, the record which would be read by
a READ NEXT statement would be the same before and after a
RETAIN or a FREE statement.

Example 9-7 demonstrates
processed sequentially.

how

indexed-sequential

file

can

Example 9-7
A.

RETAIN FILE-A KEY FILE-A-KEY
FOR READ.
READ FILE-A NEXT RECORD;

INVALID KEY GO TO ERR-RTN.

GO TO A.
Example 9-8 shows the random processing of an indexed file.
Note how
the UNTIL FREED statement is used to insure the stability of the
record.
Example 9-8
A.

ACCEPT DATA-KEY.
RETAIN FILE-A KEY DATA-KEY
FOR READ-REWRITE UNTIL FREED.
READ FILE-A INVALID KEY GO TO ERR-RTN.
DISPLAY FILE-A-RECORD.

(process and update record if you wish)

FREE FILE-A-RECORD.
GO TO A.

9-17

CHAPTER 10
REPORT WRITER

The COBOL compiler offers a report writing facility,
REPORT WRITER.
Using this facility can make it easy to format printed reports.
The example program on the following pages shows how to use the major
features of REPORT WRITER.
The full formats and available options for
each statement are discussed in detail
in the COBOL-68 Language
Reference Material, Chapter 4 of this manual.

10-1

REPORT WRITER
PRO G RAM
REP1.CBL
0001
0002
0003
0004

OOOS

0006
0007
0008
0009
0010
0011
0012
0013
0014
001S
0016
0017
0018
0019
0020
0021
0022
0023
0024
002S
0026
0027
0028
0029
0030
0031
0032
0033
0034
0035
0036
0037
0038
0039
0040
0041
0042

REP E X M
lS-JAN-81
lS-JAN-81 lS:20

lS:19

COBOL-68 12B(lllS) BIS
PAGE 1

ID DIVISION.
PROGRAM-ID. REPEXM.

* **************************************************************

*
*
*
*
*
*
*
*
*
*
*

This program is an example of the use of REPORT WRITER.
The program generates two reports: one is a list of
customers by city and statei the other is a list of
totals for each state.

*
*
*
*

*
*
The two reports are generated at one time and into one
*
file.
The line printer spooler can separate them at the
*
time they are to be printed.
*
*
* **************************************************************
*

ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.

* **************************************************************

*
*
*
*
*
*
*

*
*
*
*
*

*
*
The following entry in the SPECIAL-NAMES paragraph of the
**
CONFIGURATION SECTION defines the codes 'A' and 'B' for
*
the two reports we are going to generate. The line printer *
spooler can separate them when we use the /REPORT switch
*
with the system QUEUE command.
For example, to print
*
both reports, we would use
*
*
Q LL:=CUSTMR.LPT/REPORT:A,CUSTMR.LPT/REPORT:B
*
*
Report Codes (Line 37)

* **************************************************************
'A' IS BY-CITY-CODEi'B' IS STATE-TOTALS-CODE.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT CUSTOMER-FILEi ASSIGN TO DSKi
RECORDING MODE IS ASCII.

10-2

REPORT WRITER
0043

PRO G RAM

REPl.CBL
0044
0045
0046
0047
0048
0049
0050
0051
0052
0053
0054
0055
0056
0057
0058
0059
0060
0061
0062
0063
0064
0065
0066
0067
0068
0069
0070
0071
0072
0073
0074
0075
0076
0077
0078
0079
0080

15-JAN-81

REP E X M
15-JAN-81 15:19
15:20

COBOL-68 12B(1115) BIS
PAGE 2

* **************************************************************

**
*
*
*
*
*

*
*
*
Like any file, the file for the report must be SELECTed and *
ASSIGNed. Here we're using a disk file, but any device is *
legal.
*
Report file SELECTion and ASSIGNment (Line 55)

*
* **************************************************************
SELECT PRINTER-FILEi ASSIGN TO DSKi
RECORDING MODE IS ASCII.
SELECT SORT-FILEi ASSIGN TO DSK,DSK,DSKi
RECORDING MODE IS ASCII.
DATA DIVISION.
FILE SECTION.
SD
01

FD
01

SORT-FILE.
SORT-RECORD.
02 SORT-NAME
02 SORT-CITY
02 SORT-STATE
02 SORT-STREET
02 SORT-SALES

PIC
PIC
PIC
PIC
PIC

X(24) USAGE DISPLAY-7.
X(20) USAGE DISPLAY-7.
XX USAGE DISPLAY-7.
X(20) USAGE DISPLAY-7.
S9(10) USAGE COMPo

CUSTOMER-FILE
VALUE OF IDENTIFICATION IS 'CUSTMRDAT'.
GUSTMR-RECORD.
02 CUSTMR-NAME
PIC X(24) USAGE DISPLAY-7.
02 CUSTMR-STREET
PIC X(20) USAGE DISPLAY-7.
02 CUSTMR-CITY
PIC X(20) USAGE DISPLAY-7.
02 CUSTMR-STATE
PIC XX USAGE DISPLAY-7.
02 CUSTMR-SALES
PIC S9(10)V99.
02 FILLER
PIC X(302) .

10-3

REPORT WRITER
OOSl

PRO G RAM

REPl.CBL
00S2
00S3
00S4
00S5
00S6
00S7
OOSS
00S9
0090
0091
0092
0093
0094
0095
0096
0097
009S
0099
0100
0101
0102
0103
0104
0105
0106
0107
010S
0109
0110
0111
0112
0113
0114
0115
0116
0117
OIlS
0119
0120
0121
0122
0123
0124
0125
0126
0127

15-JAN-Sl

REP E X M
15-JAN-Sl 15:19
15:20

COBOL-68 12B(1115) BIS
PAGE 3

* **************************************************************

The FD for the Report File (Lines 100 - 103)

*
*

Here we give the file for the report the name CUSTMR.LPT.

*
*
*

The REPORTS ARE clause names the RD entries that weIll
define in the REPORT SECTION and names the reports to be
written in the file.

*
*
*

*
*
*
*
*
*
*

The record named in the 01-level entry must be large enough *
to contain the largest line written (including a l-character*
code.
In our example, we never refer to PRINTER-RECORD in *
the PROCEDURE DIVISION, so we could omit this; the default *
size for PRINTER-RECORD is 132 characters.
*

*
*

* **************************************************************
FD
01

PRINTER-FILE;
REPORTS ARE STATE-TOTALS-ONLY,BY-CITY
VALUE OF IDENTIFICATION IS ICUSTMRLPT I .
PRINTER-RECORD
PIC X(70) USAGE DISPLAY-7.

WORKING-STORAGE SECTION.
01
01

THIS-DATE
TO-REDEFINED
02 TO-MONTH
02 TD-HYF-l
02 TO-DAY
02 TD-HYF-2
02 TO-YEAR

PIC X(S).
REDEFINES THIS-DATE.
PIC Z9.
PIC X.
PIC 99.
PIC X.
PIC 99.

UNEDITED-DATE.
02 UE-YEAR
02 UE-MONTH
02 UE-DAY
02 FILLER

PIC
PIC
PIC
PIC

99.
99.
99.
X(6).

77
77
77

TEMP PIC S999 USAGE COMP.
NR-OF-CITIES PIC S999 USAGE COMP.
NR-OF-STATES PIC S999 USAGE COMP.

77
77
77

ONE-COUNT
PIC S9 USAGE COMP VALUE -I.
CURRENT-STATE
PIC XX.
CURRENT-CITY PIC X(20) USAGE DISPLAY-7.

10-4

REPORT WRITER
0128

PRO G RAM

REPl.CBL
0129
0130
0131
0132
0133
0134
0135
0136
0137
0138
0139
0140
0141
0142
0143
0144
0145
0146
0147
0148
0149
0150
0151
0152
0153
0154
0155
0156
0157
0158
0159
0160
0161
0162

15-JAN-81

REP E X M
15-JAN-Sl
15:20

15:19

COBOL-68 12B(1115) BIS
PAGE 4

* **************************************************************

*
*
*

*
*

*
*
*
The REPORT SECTION is in the DATA DIVISION.
It must be the *
last section of the division.
In the REPORT SECTION, we
*
define the formats for the reports.
*
*
The REPORT SECTION Statement (Line 139)

* **************************************************************
REPORT SECTION.

* **************************************************************

*
*
*
*
*
*

*
*
*
The RD is the report description for each report.
We need *
an RD for each report; one is here and the other is below.
*
*
The CODE clause of the RD gives the mnemonic-name of the
*
* code
assigned to the report.
This is the same code given
*
*
* by the literal in the SPECIAL-NAMES paragraph of the
*
*
* ENVIRONMENT DIVISION above.
*
*
* The CONTROL clause specifies the break fields in order from *
* most important to least important. FINAL is a special case *
*
* in which a control break occurs at the end of the
*
* report.
*
*
The RD for a Report (Lines 160 - 453)

* **************************************************************
RD

STATE-TOTALS-ONLY
CODE STATE-TOTALS-CODE
CONTROLS ARE FINAL, SORT-STATE.

10-5

REPORT WRITER
0163

PRO G RAM

REPl.CBL
0164
0165
0166
0167
0168
0169
0170
0171
0172
0173
0174
0175
0176
0177
0178
0179
0180
0181
0182
0183
0184
0185
0186
0187
0188
0189
0190
0191
0192
0193
0194
0195
0196
0197
0198
0199
0200
0201
0202
0203
0204
0205
0206
0207
0208
0209
0210
0211
0212
0213
0214

15-JAN-81

REP E X M
15-JAN-81 15:19
15:20

COBOL-68 12B(ll15) BIS
PAGE 5

* **************************************************************

*
*
*
*

*
*

*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*

*
*

*
*
*
*
*
*
*

The TYPE Statement (Line 266 and throughout the RDs)
The TYPE statement defines the type of each record and
where it appears in the report. The record need not be
named unless it is referenced in the PROCEDURE DIVISION.
There are seven types of records:
REPORT HEADING (or RH) is a heading that appears at
the beginning of the report.
REPORT FOOTING (or RF) is a footing that appears at
the end of the report.
PAGE HEADING (or PH) is a page heading that appears
at the top of each page of the report.
PAGE FOOTING (or PF) is a page footing that appears
at the bottom of each page.
CONTROL HEADING (or CH) is a heading that appears
immediately before any detail lines whenever a
control break occurs, and after the page heading of
the first page. The name of the control break is
specified in the CONTROL clause, and tells REPORT
WRITER which field to test for a control break.
CONTROL FOOTING (or CF) is a footing that appears
immediately after the last detail line before a
control break.
DETAIL (or DE) is a detail line that is printed each
time a GENERATE statement is executed in the
PROCEDURE DIVISION.

*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*

*
*
*
*
*
*
*
*
*
*
*
*
*

* **************************************************************
* **************************************************************

*
*
*
*
*
*

*
*

*
*
*
The NEXT GROUP clause given the line-number of the line for *
the beginning of the next group written. The argument for
*
NEXT GROUP can be a number; for example, NEXT GROUP IS 15
*
places the next group on line 15 of the page. The argument *
can also be relative; for example, NEXT GROUP IS PLUS 2
*
The NEXT GROUP Clause (Lines 266 and 424)

places the next line two lines below the current line.

* **************************************************************

10-6

REPORT WRITER
0215

PRO G RAM

REPl.CBL
0216
0217
0218
0219
0220
0221
0222
0223
0224
0225
0226
0227
0228
0229
0230
0231
0232
0233
0234
0235
0236
0237
0238
0239
0240
0241
0242
0243
0244
0245
0246
0247
0248
0249
0250
0251
0252
0253

l5-JAN-8l

REP E X M
l5-JAN-8l
15:20

15:19

COBOL-68 12B(1115) BIS
PAGE 6

* **************************************************************

*
*

The LINE Clause (Line 267 and throughout the RDs)

*
*

LINE NUMBER IS clause (which can be abbreviated to LINE)*
* The
tells on which line of the page a report entry should be
*
* written.
The
LINE
clause
applies
to
the
item
containing
it
*
* and continues to apply until the end-of-record or until
*
* another
LINE
clause
is
found.
*
*
* The LINE clause can take three kinds of arguments:
*
*
*
*
*
1. An integer that specifies the line number.
*
*
For example, LINE NUMBER IS 25 specifies line 25.
*
*
If the number is smaller than the current line, a
*
*
new page is begun.
*
*
*
*
2.
PLUS with an integer that specifies how, many lines
*
*
below the current line to print the current entry.
*
*
For example, LINE PLUS 3 means to skip two lines
*
*
before printing the current entry.
*
*
*
*
3. NEXT PAGE, which specifies the next page.
If the
*
*
record
is
a
page
header,
it
is
printed
on
*
*
line 1; otherwise it is printed on line 2.
*
*
** ***************************************************************
* **************************************************************

*
*
*
*

The COLUMN Clause (Line 267 and throughout the RDs)
The COLUMN NUMBER IS clause (we can omit NUMBER IS) tells
REPORT WRITER which column is the first for a record or
field.
If a record or field does not have a COLUMN entry,
it is not printed.

*
*
*
*
*
*
*
*

*******************************************~******************

10-7

REPORT WRITER
0254

PRO G RAM

REP1.CBL
0255
0256
0257
0258
0259
0260
0261
0262
0263
0264
0265
0266
0267
0268
0269
0270
0271
0272
0273
0274
0275
0276
0277
0278
0279
0280
0281
0282
0283
0284
0285
0286
0287
0288
0289
0290
0291
0292
0293
0294
0295
0296
0297
0298
0299
0300
0301
0302
0303
0304
0305

15-JAN-81

REP E X M
15-JAN-81 15:19
15:20

COBOL-68 12B(1115) BIS
PAGE 7

* **************************************************************

*
*
**
*
*
*
*

*
*
*
The SOURCE IS clause (we can omit IS) specifies the source *
for an item. The source item must have been defined in the *
The SOURCE Clause (Line 269 and throughout the RDs)

FILE or WORKING-STORAGE SECTION.
Its value is moved into
the report item before the item is written in the file.

*
*

* **************************************************************
01

TYPE PH NEXT GROUP PLUS 2.
02 LINE 1 COLUMN 22 PIC X(25) USAGE DISPLAY-7
VALUE 'State Totals of Customers'.
02 LINE 2 COLUMN 31 PIC X(8) SOURCE THIS-DATE.
02 LINE 5 COLUMN 1 PIC X(5) USAGE DISPLAY-7
VALUE 'State'.
02 LINE 5 COLUMN 10 PIC X(19) USAGE DISPLAY-7
VALUE 'Number of Customers'.
02 LINE 5 COLUMN 44 PIC X(5) USAGE DISPLAY-7
VALUE 'Sales'.

* **************************************************************

*
*

**
*
*
*
*
*
*
*
*

*
*
*
*
*
*
*
*
*
*
*
*

*
*
*

*
*
*
The SUM clause in the second following line specifies that *
the data-item is summed.
The data-item summed can be
*
either a SOURCE item from a TYPE DETAIL line (for example,
*
SORT-SALES in this program), or a summation counter (for
*
example, CITY-COUNT).
*
*
When either the SOURCE item or the summation counter is
*
used, the value of the item is added to a compiier*
generated accumulator and this accumulator is moved to the *
report item before writing. The summation counter need
*
not be named unless it is referenced directly in the
*
PROCEDURE DIVISION or in another REPORT SECTION statement.
*
*
A SUM clause can appear only in a TYPE CONTROL FOOTING
*
record. The accumulator is zeroed after being moved to the *
report item.
*
You can selectively sum portions of a data-item by using
**
the UPON option with the SUM clause.
In that case, summing *
occurs only when the item is referenced by a GENERATE
*
statement. The individual items to be summed must be
*
SOURCE items within a data-name specified as a TYPE DETAIL *
The SUM Clause (Line 309 and throughout the RDs)

report group.

* **************************************************************

10-8

REPORT WRITER
0306

PRO G RAM

REPl.CBL
0307
0308
0309
0310
0311
0312
0313
0314
0315
0316
0317
0318
0319
0320
0321
0322
0323
0324
0325
0326
0327
0328
0329
0330
0331
0332
0333
0334
0335
0336
0337
0338
0339
0340
0341
0342
0343
0344
0345
0346
0347
0348
0349
0350
0351
0352
0353

15-JAN-81

REP E X M
15-JAN-81 15:19
15:20

COBOL-68 12B(1115) BIS
PAGE 8

TYPE CF SORT-STATE LINE PLUS 1.
02 COLUMN 3
PIC XX SOURCE CURRENT-STATE.
02 COLUMN 15
PIC ZZ,ZZ9 SUM ONE-COUNT.
02 COLUMN 35
PIC ZZ,ZZZ,ZZZ,ZZ9 SUM SORT-SALES.

TYPE CF FINAL LINE PLUS
02 COLUMN 1
PIC
VALUE 'Total'.
02 COLUMN 15
PIC
02 COLUMN 35
PIC

2.
X(5) USAGE DISPLAY-7
ZZ,ZZ9 SUM ONE-COUNT.
$$,$$$,$$$,$$9 SUM SORT-SALES.

* **************************************************************

*
*
*
*

Missing COLUMN Clause (Lines 330 - 331)
The following lines illustrate the fact that a report
item is not written in the report (even if directly
specified in a GENERATE statement) unless the item has a
COLUMN NUMBER clause.

*
*
*
*
*
*
*
*

* *********************************~****************************
01

TYPE DETAIL.
02
02

PIC S9(5) SOURCE ONE-COUNT.
PIC S9(10) SOURCE SORT-SALES.

* **************************************************************

*
*
*

The PAGE LIMIT Clause (Line 351)

*
*
*

The PAGE LIMIT clause specifies the number of lines that
*
can be written on one page of the report.
If a line is
*
written that would exceed PAGE LIMIT, page footings are
*
written, a new page is begun, and page headings are written.*

*
*
*

'rhe PAGE LIMIT clause can contain additional options to
control placement of page headings and footings, and the
placement of first and last TYPE DETAIL lines.

*
*
*
*
*

* **************************************************************
RD

BY-CITY
CODE BY-CITY-CODE
CONTROLS ARE FINAL SORT-STATE,SORT-CITYi
PAGE LIMIT IS 58 LINES
HEADING 1, FOOTING 58, FIRST DETAIL 6,
LAST DETAIL 55.

10-9

REPORT WRITER
0354

PRO G RAM

REP1.CBL
0355
0356
0357
0358
0359
0360
0361
0362
0363
0364
0365
0366
0367
0368
0369
0370
0371
0372
0373
0374
0375
0376
0377
0378
0379
0380
0381
0382
0383
0384
0385
0386
0387
0388
0389
0390
0391
0392
0393
0394
0395
0396

15-JAN-81

REP E X M
15-JAN-81
15:20

15:19

COBOL-68 12B(1115) BIS
PAGE 9

REPORT-HEADER TYPE REPORT HEADING LINE 25.
02 COLUMN 27
PIC X(27) USAGE DISPLAY-7
VALUE 'Customers By City and State'.
02 LINE 29 COLUMN 36
PIC X(8) SOURCE THIS-DATE.

REPORT-FOOTER TYPE REPORT FOOTING LINE PLUS 2.
02 COLUMN 30
PIC X(19) USAGE DISPLAY-7
VALUE '** End of Report **'.

* **************************************************************

*
*
*
*

*
*
*
*
*
*
*

*
*

The PAGE-COUNTER (Line 384)
The compiler generates a data-item called PAGE-COUNTER for
each report descriptor (RD) item.
It is set to 1 by the
INITIATE statement, and incremented by 1 for each new page.

*
*

*
*
*
If you define more than one report in the same program, you *
must qualify a reference to PAGE-COUNTER'by using the name *
of the report.
*
*

* **************************************************************
01

PAGE-HEADING TYPE PAGE HEADING.
PIC X(33) USAGE DISPLAY-7
02 LINE 1 COLUMN 1
VALUE 'Customers By City and State'.
02 LINE 1 COLUMN 62
PIC X(4) USAGE DISPLAY-7
VALUE 'Page'.
02 LINE 1 COLUMN 66
PIC ZZZ9
SOURCE PAGE-COUNTER OF BY-CITY.
02 LINE 2 COLUMN 1
PIC X(8) SOURCE THIS-DATE.

STATE-HEADING TYPE CONTROL HEADING SORT-STATE
LINE PLUS 2.
02 COLUMN 1 PIC X(9) USAGE DISPLAY-7
VALUE 'Customer'.
02 COLUMN 30 PIC X(5) USAGE DISPLAY-7
VALUE 'State'.
02 COLUMN 36 PIC X(4) USAGE DISPLAY-7
VALUE 'City' .
02 COLUMN 65 PIC X(5) USAGE DISPLAY-7
VALUE 'Sales'.

10-10

REPORT WRITER
0397

PRO G RAM

REPl.CBL
0398
0399
0400
0401
0402
0403
0404
0405
0406
0407
0408
0409
0410
0411
0412
0413
0414
0415
0416
0417
0418
0419
0420
0421
0422
0423
0424
0425
0426
0427
0428
0429
0430
0431

15-JAN-81

REP E X M
15-JAN-81 15:19
15:20

COBOL-68 12B(1115) BIS
PAGE 10

DETAIL-LINE-l TYPE DETAIL LINE PLUS 2.
02 COLUMN 1 PIC X(24) USAGE DISPLAY-7
SOURCE SORT-NAME.
02 COLUMN 32 PIC X(2)
USAGE DISPLAY-7
SOURCE SORT-STATE.
02 COLUMN 36 PIC X(20) USAGE DISPLAY-7
SOURCE SORT-CITY.
02 COLUMN 56 PIC ZZ,ZZZ,ZZZ,ZZ9
SOURCE SORT-SALES.
02
PIC ZZ,ZZ9 SOURCE ONE-COUNT.

DETAIL-LINE-2 TYPE DETAIL LINE PLUS 1.
02 COLUMN 1 PIC X(20) USAGE DISPLAY-7
SOURCE SORT-STREET.

CITY-FOOTING TYPE CF SORT-CITY LINE PLUS 3.
02 CITY-COUNT COLUMN 4 PIC ZZ,ZZ9 USAGE DISPLAY-7
SUM ONE-COUNT.
02 COLUMN 11 PIC X(11) USAGE DISPLAY-7
VALUE 'customers in city'.
02 COLUMN 36 PIC X(20) USAGE DISPLAY-7
SOURCE SORT-CITY.
02 CITY-SALES COLUMN 56 PIC $$,$$$,$$$,$$9
SUM SORT-SALKS.

STATE-FOOTING TYPE CF SORT-STATE LINE PLUS 3
NEXT GROUP NEXT PAGE.
02 STATE-COUNT COLUMN 4 PIC ZZ,ZZ9 USAGE DISPLAY-7
SUM CITY-COUNT.
02 COLUMN 11 PIC X(18) USAGE DISPLAY-7
VALUE 'customers in state'.
02 COLUMN 32 PIC X(2) SOURCE SORT-STATE.
02 STATE-SALES COLUMN 56 PIC $$,$$$,$$$,$$9
SUM CITY-SALES.

10-11

REPORT WRITER
0432

PRO G RAM

REP1.CBL
0433
0434
0435
0436
0437
0438
0439
0440
0441
0442
0443
0444
0445
0446
0447
0448
0449
0450
0451
0452
0453

15-JAN-81
01

REP E X M
15-JAN-81
15:20

15:19

COBOL-68 128(1115) BIS
PAGE 11

FINAL-FOOTING TYPE CF FINAL LINE PLUS 1.
02 COLUMN 3 PIC X(5) USAGE DISPLAY-7
VALUE 'Total'.
02 COLUMN 15 PIC X(5) USAGE DISPLAY-7
VALUE 'Total'.
02 COLUMN 25 PIC X(5) USAGE DISPLAY-7
VALUE 'Total'.
02 COLUMN 45 PIC X(5) USAGE DISPLAY-7
VALUE 'Total'.
02 LINE PLUS 1 COLUMN 1 PIC X (9) USAGE DISPLAY-7
VALUE 'Customer s ' .
02 COLUMN 15 PIC X(6) USAGE DISPLAY-7
VALUE 'States'.
02 COLUMN 25 PIC X(6) USAGE DISPLAY-7
VALUE 'Cities'.
02 COLUMN 45 PIC X(5) USAGE DISPLAY-7
VALUE 'Sales'.
02 LINE PLUS 2 COLUMN 1 PIC ZZ,ZZ9 SUM STATE-COUNT.
02 COLUMN 16 PIC ZZ9 SOURCE NR-OF-STATES.
02 COLUMN 26 PIC ZZ9 SOURCE NR-OF-CITIES.
02 COLUMN 36 PIC $$,$$$,$$$,$$9 SUM STATE-SALES.

10-12

REPORT WRITER
0454

PRO G RAM

REP1.CBL
0455
0456
0457
0458
0459
0460
0461
0462
0463
0464
0465
0466
0467
0468
0469
0470
0471
0472
0473
0474
0475
0476
0477
0478
0479
0480
0481
0482
0483
0484
0485
0486
0487
0488
0489
0490
0491
0492
0493
0494
0495
0496
0497

15-JAN-81

REP E X M
15-JAN-81 15:19
15:20

COBOL-68 12B(1115) BIS
PAGE 12

PROCEDURE DIVISION.

* **************************************************************

*
*
*
*
*
*
*
*
*

The USE BEFORE REPORTING Verb

(Li~e

470)

You can include the USE BEFORE REPORTING verb in the
DECLARATIVES SECTION of the PROCEDURE DIVISION. A report
record is specified in the USE statement to indicate when
the USE procedure is to be performed.
It is performed
immediately before the report record is written.

*
*
*
*
*
*
*
*
*

* **************************************************************
DECLARATIVES.
EOR SECTION. USE BEFORE REPORTING REPORT-FOOTER.
EOR-A. DISPLAY 'END OF REPORTS'.
END DECLARATIVES.
MAIN SECTION.
START-PROC1.
SORT SORT-FILE ON ASCENDING KEY
SORT-STATE,SORT-CITY,SORT-NAME
INPUT PROCEDURE IS IN-PROCEDURE
OUTPUT PROCEDURE IS OUT-PROCEDURE.
STOP RUN.
IN-PROCEDURE SECTION.
START-PROC2.
OPEN INPUT CUSTOMER-FILE.
LOOP.
READ CUSTOMER-FILE AT END GO TO DONE-INPUT.
COMPUTE SORT-SALES ROUNDED = CUSTMR-SALES.
MOVE CUSTMR-NAME TO SORT-NAME.
MOVE CUSTMR-STATE TO SORT-STATE.
MOVE CUSTMR-STREET TO SORT-STREET.
MOVE CUSTMR-CITY TO SORT-CITY.
RELEASE SORT-RECORD.
GO TO LOOP.
DONE-INPUT. CLOSE CUSTOMER-FILE.

10-13

REPORT WRITER
0498

PRO G RAM

REPl.CBL
0499
0500
0501
0502
0503
0504
0505
0506
0507
0508
0509
0510
0511
0512
0513
0514
0515
0516
0517
0518
0519
0520
0521
0522
0523
0524
0525
0526
0527
0528
0529
0530
0531
0532

15-JAN-81

REP E X M
15-JAN-81
15:20

15:19

COBOL-68 12B(1115) BIS
PAGE 13

OUT-PROCEDURE SECTION.

* **************************************************************

**
*
*
*
*

OPEN the Report File (Line 511)

*
*

*
*
*
* **************************************************************
The report file must be OPENed before any records can be
written in it.

START-PROC3.
OPEN OUTPUT PRINTER-FILE.
MOVE TODAY TO UNEDITED-DATE.
MOVE UE-DAY TO TD-DAY; MOVE UE-MONTH TO TD-MONTH;
MOVE UE-YEAR TO TD-YEAR
MOVE I _ I TO TD-HYF-l,TD-HYF-2.

* **************************************************************

*
*

*
*
*
*
*
*
*
*

*
*
*
The INITIATE statement causes the counters and accumulators *
to be initialized. The summation counters are set to 0;
*
the PAGE-COUNTER is set to 1.
*
*
Each report written must be named in an INITIATE statement. *
The output file for the report must be OPENed before any
*
INITIATE statement is executed.
*
*
INITIATE the Reports (Lines 531 - 532)

* **************************************************************
INITIATE BY-CITY.
INITIATE STATE-TOTALS-ONLY.

10-14

REPORT WRITER
0533

PRO G RAM

REPl.CBL
0534
0535
0536
0537
0538
0539
0540
0541
0542
0543
0544
0545
0546
0547
0548
0549
0550
0551
0552
0553
0554
0555
0556
0557
0558
0559
0560
0561
0562
0563
0564
0565
0566
0567
0568
0569
0570
0571
0572
0573
0574
0575
0576
0577
0578
0579
0580
0581
0582

15-JAN-81

REP E X M
15-JAN-81
15:20

15:19

COBOL-68 12B(1115) BIS
PAGE 14

* **************************************************************

**
*
*
*
*
*

*
*
*
*

*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*

GENERATE Report Records (Lines 577 - 578)

*
*

The GENERATE statement causes testing of control fields and *
writes any required control headings and footings.
If the *
argument to the GENERATE statement is a TYPE DETAIL record, *
the record is written after any control breaks.
If the
*
argument is a report descriptor (RD) , the detail lines are *
set up but not printed, so that a summary report is written.*
In this program, both types of reports are generated. The
GENERATE DETAIL-LINE statement causes a detail report to be
written; the GENERATE STATE-TOTALS-ONLY statement causes a
summary report to be written.

**
*
*
*

*
*
1.
Increments and tests the PAGE-COUNTER and produces
*
any required page footings and headings.
*
*
2. Tests for any control breaks and produces any
*
required control footings and headings.
*
*
3. Adds all specified identifiers to summation counters. *
*
4.
Executes any routines defined by USE statements.
*
*
If the argument to the GENERATE statement is a TYPE- *
5.
DETAIL record, writes the detail report group.
*
*
During the first execution of a GENERATE statement, all
*

A GENERATE statement performs the following operations:

*
*

required report headings, page headings, control headings,
and detail report groups are written.

*
*
*

* **************************************************************
LOOP.
RETURN SORT-FILE; AT END GO TO DONE-REPORTS.
IF CURRENT-STATE NOT EQUAL SORT-STATE
ADD 1 TO NR-OF-STATES~
IF CURRENT-CITY NOT EQUAL SORT-CITY
ADD 1 TO NR-OF-CITIES.
GENERATE DETAIL-LINE-l.
GENERATE DETAIL-LINE-2.
GENERATE STATE-TOTALS-ONLY.
MOVE SORT-STATE TO CURRENT-STATE.
MOVE SORT-CITY TO CURRENT-CITY.
GO TO LOOP.

10-15

REPORT WRITER
0583

PRO G RAM

REPl.CBL
0584
0585
0586
0587
0588
0589
0590
0591
0592
0593
0594
0595
0596
0597
0598
0599
0600
0601
0602
0603
~604

0605
0606
0607
0608
0609
0610
0611

l5-JAN-8l

REP E X M
l5-JAN-8l
15:20

15:19

COBOL-68 l2B(1115) BIS
PAGE 15

* **************************************************************

*
*
**
*
*
*
*
*
*
*

TERMINATE the Reports (Line 609)
The TERMINATE statement completes the processing for a
report. When the TERMINATE statement is executed, breaks
occur for all control fields and all control footings are
written; all page footings and report footings are also
written.
If a program writes more than one report in the
same file, each report must be named in a TERMINATE
statement.

*
*
**
*
*
*
*
*
*
*

* **************************************************************

**
*
*
*
*

CLOSE the Report File (Line 610)
The CLOSE statement closes the report file.
All reports
written in the file must be TERMINATEd before the CLOSE
statement is executed.

*
*
*
*
*
*
*

* **************************************************************
DONE-REPORTS.
TERMINATE BY-CITY,STATE-TOTALS-ONLY.
CLOSE PRINTER-FILE.

NO ERRORS DETECTED

10-16

REPORT WRITER
The following pages show the reports
listed.

produced

the

Customers By City and State

2-12-81

10-17

program

just

REPORT WRITER
Page

Customers By City and State
2-12-81

State City

Customer
Other Side Of The Fence
1247 Main Street

1 customers in city

Sales

Darien

61,500

Darien

$61,500

The Lawn Man
174 Barrington Drive

Hartford

874,259

Turf World
8745 Asylum Street

Hartford

47,525

Hartford

$921,784

Hew Haven

83,247

Hew Haven

$83,247

2 customers in city
Bushwhackers, Inc.
2735 Skyline Drive

1 customers in city
4 customers in state

10-18

$1,066,531

REPORT WRITER

Page

Customers By City and State
2-12-81

State City

Customer

Sales

Boston Garden Shop
419 Beacon Street

Boston

15,389

Sodbusters
8941 Commonwealth Av

Boston

45,639

Boston

$61,028

Concord

7,649

Concord

$7,649

Worcester

9,042

Worcester

$9,042

2 customers in city
Joyce Kilmer Trees
453 Henry T Drive

1 customers in city
Mass Grass, Inc.
8789 Worcester Drive

1 customers in city
4 customers in state

10-19

$77,719

REPORT WRITER
Page

Customers By City and State
2-12-81

State City

Customer
Plastic Yards, Inc.
4772 Providence Blvd

1 customers in city
Astro Grass Company
666 Armageddon

1 customers in city
2 customers in state

Sales

Providence

7,747

Providence

$7,747

Woonsocket

6,489

Woonsocket

$6,489

10-20

$14,236

REPORT WRITER
Customers By City and State
2-12-81

Page

Total
Customers

Total
States

Total
Cities

Total
Sales

$1,158,486

** End of Report **

10-21

REPORT WRITER

State Totals of Customers
2-12-81
State

Number of Customers

Sales

CT
MA

4
4

1,066,531
77,719
14,236

Total

$1,158,486

** End of Report **

10-22

CHAPTER 11
PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS

Some tasks which are done by computers require them to execute
extraordinarily large amounts of code in order to solve the problem at
hand.
In rare cases, it can be difficult to fit the program into your
memory area.
In other, more numerous, cases, it can be desirable to
split up the task into subtasks in order to make debugging easier or
so that the subtasks can be given to different people to code.
There
are also cases where you wish to make some type of calculation which
is difficult or
impossible in COBOL.
For any of these reasons, you
can find it convenient to organize your program into parts to make the
programming task easier, to allow the program to run more efficiently,
or both.
A COBOL programming task can be organized into program
segments,
into subprograms, or into an overlay structure to allow the
breaking-up of the task.
These various methods for breaking the task
into smaller pieces must be carefully studied in order to determine
which method is most suitable for your particular use.
The methods
themselves differ widely in the techniques used and the results
obtained.

11.1

PROGRAM SEGMENTS

You can divide the Procedure Division of a COBOL program into parts
called program segments.
By doing this, you cause the system to run
your program with some segments in memory only when they are needed;
when they are not needed, they are on disk storage.
Thus, the amount
of memory required for execution is reduced.
You can define program segments in a main program or in a subprogram,
but only one segmented program is allowed in a single load.

11.1.1

Section-Names And Segment Numbers

A program segment is made up of one or more sections,
begins with a SECTION statement of the form

each

which

section-name SECTION nn.
where nn is a two-digit segment number in the range
00 to 99.
A
section extends from its SECTION statement to the next SECTION
statement, or to the end of the program,
whichever
is first.
All
sections having the same segment number are in the same segment.
A program segment is either resident or nonresident, and writable or
nonwritable, depending on its segment number, and on the setting of
the segment-limit.
(The SEGMENT-LIMIT IS nn statement in
the
Environment Division defines the segment limit, which is the smaller
of nn and 49;
if nn is omitted or nn is 0, the segment-limit is 49.)
11-1

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
A segment with a segment number of 50 or greater is nonresident and
nonwritable;
it is brought into memory only when it is needed for
execution.
Further, such a segment loses any changes made by ALTER
statements when it leaves memory.
It is in its original state each
time it enters memory.
A segment with a segment number in the range SEGMENT-LIMIT to 49 is
nonresident,
but
writable;
it retains changes made by ALTER
statements.
A segment with a segment number less than the SEGMENT-LIMIT
(or with
no segment number) is a resident and writable segment;
it is always
in memory during execution.
Nonresident segments are suitable for
routines that are executed
infrequently,
run for a long time once begun, and require large
amounts of memory.
For example, a program that has four main tasks
that are executed sequentially is an ideal application for nonresident
segmentation. Placing each task in a nonresident segment allows the
program to run with only one of the se~ments in memory at a time.
On the other hand, a frequently used routine should be placed in a
resident segment to avoid the overhead of bringing it into memory time
after time.

11.1.2

Examples

In the following sample program,
there are nine program SECTIONs
forming six program segments.
(Recall that sections having the same
segment numbers are in the same segment.)
PRO G RAM
S E G MN T
l5-JAN-8l 09:22

COBOL-68 l2B(1033) BIS
PAGE 1

SEGMNT.CBL
l5-JAN-8l 09:22
0001
IDENTIFICATION DIVISION.
0002
PROGRAM-ID. SEGMNT.
0003
0004
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
0005
OBJECT-COMPUTER. DECSYSTEM-20
0006
0007
SEGMENT-LIMIT IS 25.
0008
0009
DATA DIVISION.
0010
0011
PROCEDURE DIVISION.
0012
SECT 1 SECTION 20.
CALL A.
0013
0014
SECT2 SECTION 65.
CALL A.
0015
SECT3 SECTION 22.
0016
0017
CALL A.
0018
SECT4 SECTION 20.
0019
CALL A.
0020
SECTS SECTION 60.
CALL A.
0021
0022
SECT6 SECTION 30.
CALL A.
0023
0024
SECT7 SECTION 35.
0025
CALL A.
0026
SECT8 SECTION 35.
CALL A.
0027
11-2

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
0028
0029
0030

SECT9 SECTION 60.
CALL A.
STOP RUN.

NO ERRORS DETECTED
In the example above, the segments are as follows:

11.2

Segment 20 contains the sections SECTI and SECT4.
The
SEGMENT-LIMIT IS 25 statement causes this segment to be
resident and writable.

Segment 22
writable.

Segment 30 contains section SECT6.
Since its segment number
IS
above
the SEGMENT-LIMIT but less than 50,
it is
nonresident and writable;
changes made to the segment are
preserved even if it leaves and returns to memory.

Segment 35 contains sections
nonresident and writable.

Segment 60 contains sections SECTS and SECT9.
Since its
segment
number
is
above
50,
it is nonresident and
nonwritable;
changes made to the segment are lost when it
leaves and returns to memory.

Segment 65 contains section SECT2.
nonwritable.

contains

section

SECT3;

SECT7

and

resident

SECT8.

nonresident

and

SUBPROGRAMS

A COBOL subprogram is written and compiled as a separate program,
but
is meant to be executed together with other programs.
When several
programs are loaded and executed together,
the program in which
execution begins is called the main program;
the other programs are
called subprograms.
A large programming task can become more manageable if the program is
divided
into
subprograms.
Each subprogram can perform a
few
relatively simple tasks and each can be written and tested separately
by using "dummy" main programs.
Using subprograms also permits you to define an overlay structure
load time.
(See Section 11.3 for a discussion of overlays.)

A subprogram can open files, perform I/O for
them,
and close them;
but no COBOL subprogram can perform I/O for files in another program.
Any COBOL subprogram that performs I/O must be linked to the main
program.
That is,
there must be a link,
consisting of CALL
statements, or a series of CALL statements through a series of
subprograms,
from the main COBOL program to any COBOL subprogram that
wishes to do I/O.
The CALL statement does not have to be executed to
provide a
link
in fact, it can be in such a position that it is
never executed. This requirement is met by any group of subprograms
all of which are written in COBOL.
If, however, you wish to call a
non-COBOL subprogram, you must make sure that any COBOL routines which
are called by the non-COBOL subprogram have a link to the main COBOL
program if the COBOL routines wish to do any I/O.

11-3

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
The COBOL compiler recognizes a subprogram by its use of LINKAGE
SECTION,
ENTRY, GOBACK,
or
the presence of the USING clause in the
Procedure Division header.
If a program has none of these,
the
compiler treats it as a main program.
The compiler generates a start address for a main program, but not for
a subprogram.
This start address is the address of the beginning of
the Procedure Division,
that
is,
the address where the
first
executable instruction is generated.
This start address tells LINK
and, in turn, the system where to begin execution of the program.
You can force the compiler
to generate a start address for
a
subprogram by using the IJ switch.
You can prevent the compiler from
generating a start address for a main program by using the II switch.
NOTE
A subprogram can be treated as a main
program
(that is,
can contain a start
address) only if no statements
in the
Procedure Division refer to data in the
Linkage Section.
This is because in a
main
program
only
Data
Division
statements
can
allocate
memory
locations.
There is no space in memory
for data in the Linkage Section.

11.2.1

Inter-Program Communication

Main programs and subprograms communicate by transfering execution
control and by sharing data.
The shared data can be in files, but it
is often more useful for them to share data that is already in memory.

11.2.1.1 The Calling Program - In the calling
program,
a
CALL
statement transfers execution control to a subprogram and optionally
makes a list of data-items available to the called subprogram.
The
CALL statement has the form:
CALL {program- or entry-name}

[USING identifier-l [,identifier-2] ... ].

The program- or entry-name specifies the point to which execution
control
is to be passed in a subprogram.
If a program-name is given,
it is the PROGRAM-ID name
in the subprogram,
and control
is
transferred to the beginning of the subprogram's Procedure Division.
If an entry-name is given, it is the name given by an ENTRY statement
in the subprogram, and control is transferred to that statement.
Each program-name and entry-name must be unique among all those loaded
together.
The identifiers specified
in the CALL statement give a list of
data-items in the calling program.
The memory locations associated
with them are then available for use in the called subprogram.
If you
omit the USING clause, no memory locations in the calling program are
available to the called subprogram.
Each identifier must be defined in the File Section, Working-Storage
Section, or Linkage Section of the calling program.
Each data-item
must be word-aligned.
(Items at the 01 and 77 levels and COMP items
11-4

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
are already word-aligned;
SYNCHRONIZED LEFT clause.)

others

can

aligned

using

the

11.2.1.2 The Called Subprogram - A subprogram can begin execution at
any of its entry points.
The beginning of the Procedure Division is
always an entry point.
Its entry-name is the name given in the
subprogram's PROGRAM-ID statement.
You can name data-items to be available to the called program with a
USING clause in the PROCEDURE DIVISION statement.
This statement has
the form:
PROCEDURE DIVISION [USING identifier-l [,identifier-2] ••• ].
You can define additional entry
which has the form:

points

using

the

ENTRY

statement,

ENTRY entry-name [USING identifier-l [,identifier-2] ..• ].
use by CALL statements in
The specified entry-name is defined for
calling programs and must be unique among all entry-names and
program-names loaded together.
The USING clause of the calling program's CALL statement can have
defined data-items to be made available to the called subprogram.
If
so, the USING clause of the entry-point statement (PROCEDURE DIVISION
or
ENTRY)
can give identifiers to be used as local names for the
shared memory.
The identifiers in the called subprogram's USING clause are assigned
data-items in the shared memory from left to right.
The lengths of
the data-items in the called subprogram need not match those in the
calling program;
but the total length of the data-items in the called
program must not exceed that in the calling program.
in
the
The identifiers in the USING clause must be defined
subprogram's Linkage Section and they must be level-Ol or level-77
identifiers.
When a subprogram is called, execution proceeds as in any program.
Control leaves the subprogram at the first executed GOBACK, EXIT
PROGRAM, or STOP statement.
If the subprogram does any I/O there must be a
link to the main
program consisting of COBOL subprograms.
You can not have a COBOL
subprogram doing I/O that is called by a non-COBOL subprogram.
Execution of a GOBACK or
EXIT PROGRAM statement in a subprogram
returns control to the calling program.
Execution of the calling
program resumes at the statement immediately following
the CALL
statement that called the subprogram.
Any changes to the data-items
specified in USING clauses at the entry point are preserved on return
to the calling program.
The forms of the GOBACK and EXIT PROGRAM statements are:
GOBACK.
EXIT PROGRAM.

11-5

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
Execution of a STOP statement halts execution
program. The STOP statement has the form:

the

entire

loaded

STOP {RUN or literal}.
The STOP RUN statement ends program execution;
there is no return to
the calling program.
The STOP literal statement causes a pause in
program execution and the literal is typed on your terminal.
If you
then type CONTINUE, execution continues at the statement following the
STOP literal.

11.2.2

Loading A Subprogram Structure

There are two ways to load a subprogram structure:
1.

For simple loads, you can use the COMPILE-class commands.

For more complex loads, you must use LINK directly.

In either case,
the following special considerations for
loading
subprogram structures apply:
every entry point
(program-name or
entry-name) referenced in a CALL statement anywhere in the loaded
program must be satisfied by loading a program containing the
program-name or entry-name.
If some referenced entry points are
missing, a fatal LINK error occurs at load time.

11.2.3

Object Libraries And Searches

An object library is a file having one or more object modules;
when
LINK searches an object library, a module is loaded from the file only
if it satisfies an unresolved global reference.
(COBOL global
references are created by the CALL or ENTER statement in a program;
additional global references to routines in the object-time system are
created by the COBOL compiler.)
NOTE
Object libraries are very different from
source libraries. The source library is
built using the COBOL utility program
LIBARY and is accessed by the COpy
statement in a COBOL program.
The
object library is built using the system
program MAKLIB and is accessed by LINK
command
strings
or by COMPIL-class
system commands.
The /SEARCH and /NOSEARCH switches turn on and off LINK's library
search mode.
When the library search mode is off (the initial
default), LINK loads each input file you specify.
When the library
search mode is on,
LINK searches each specified input file as a
library.

11-6

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
If the /SEARCH switch is appended to a file
specification,
then
switch
is automatically turned Dff after that file is searched.
example:

the
For

MYCOBL/SEARCH, COB4
searches MYCOBL.REL, but loads all of COB4.REL.
If the /SEARCH switch is not appended to a
file
specification,
then
the switch remains on until end-of-line or until a /NOSEARCH switch is
found, whichever is earlier.
For example:
COBO,/SEARCH MYLIBl,MYLIB2,/NOSEARCH COBI
loads CaBO, searches MYLIBI and MYLIB2, and loads COBI.
The system library LIBOL.REL is searched automatically when LINK loads
programs compiled with COBOL.
If the program has LINK overlays, this
search occurs at the end of each overlay
(sometimes referred to as
nodes) •
You can change this normal search procedure by using LINK switches.
The /SYSLIB switch requires LINK to search specified system libraries
no matter what kind of modules are loaded.
The /NOSYSLIB switch
forbids
search of specified system libraries.
Using these two
switches, you can select the time for searching system libraries.
The /USERLIB switch specifies that for modules from a specified
translator,
a given user
library must be searched before the
corresponding system library.
For example,
using
the
switch
MYCOBL/USERLIB:COBOL
requlres
LINK to search MYCOBL.REL before
searching LIBOL.REL. The /NOUSERLIB switch can suspend the effect of
a /USERLIB swi tch. .
Using combinations of these search-related switches gives you precise
control of library searches.
All
LINK switches are described in
detail in the LINK Reference Manual.

11.2.4

Examples

Section 11.3.6 contains program listings of seven programs.
The first
of these
is called CBLO;
it is a main program.
The remaining six
programs are subprograms.
Each has a Linkage Section that defines
data items named in USING clauses of PROCEDURE DIVISION or ENTRY
statements.
The program CBL2 has two entry points defined by ENTRY
statements.
The following example shows how to load, save, and run these programs.
The LOAD system command loads the programs;
the SAVE command creates
a file (CBLO.EXE) for
the loaded program;
the RUN CBLO command
executes the program.
All text between the RUN and EXIT lines were
written by the executed program.
The example is shown with a TOPS-IO
system prompt character (.), but the TOPS-20 system prompt (@) could
be there instead. TOPS-20 responds the same way to the LOAD command.

11-7

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
.LOAD CBLO,CBLl,CBL2,CBL3,CBL4,CBLS,CBL6 ~
COBOL: CBLO
[CBLO.CBL]
COBOL: CBLI
[CBLl.CBL]
COBOL: CBL2
[CBL2.CBL]
COBOL: CBL3
[CBL3.CBL]
COBOL: CBL4
[CBL4.CBL]
COBOL: CBLS
[CBLS.CBL]
COBOL: CBL6
[CBL6.CBL]
LINK:
Loading
EXIT
.SAVE ~
CBLO.EXE.l saved
.RUN CBLO ~
We're at level 0 in program CBLO
calling CBL2A
CBLO
We're at level 1 in program CBL2
at CBL2A
calling CBLS
CBL2
We're at level 2 in program CBLS
CBLS doesn't call anything
Returned to CBL2
calling CBL6
CBL2
We're at level 2 in program CBL6
CBL6
calling CBL3
We're at level 3 in program CBL3
CBL3 doesn't call anything
Returned to CBL6
Returned to CBL2
Returned to CBLO
CBLO
calling CBL4
We're at level 1 in program CBL4
CBL4
calling CBLI
We're at level 2 in program CBLI
CBLI
calling CBL2B
We're at level 3 in program CBL2
CBL2B doesn't call anything
Returned to CBLI
Returned to CBL4
Returned to CBLO
Execution ends in CBLO

at CBL2B

EXIT

11.3

OVERLAYS

If your loaded program would be too large to execute in one piece, you
can define an overlay structure for it. This permits the system to
execute the program with only some parts in your memory space at one
time.
(See the chapter on overlays in the LINK Reference Manual.)

11.3.1

When To Use Overlays

You do not need an overlay structure unless your program is too large
for your memory area.
If the program can fit in your memory space,
you should not define an overlay structure for
it;
the monitor's
page-swapping facility is faster than overlay execution.
11-8

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
11.3.2

Overlayable COBOL Programs

A COBOL subprogram
following rules:

structure

overlayable

observes

the

If a subprogram contains I/O verbs other than ACCEPT and
DISPLAY,
it must be placed in the root link.
(The other I/O
verbs are CLOSE, DELETE, OPEN, READ,
REWRITE, START, and
WRITE.)
Further,
the subprogram that does I/O must have a
chain of calls from the main program entirely within the root
link;
the chain of calls cannot contain calls to subprograms
in other links.
Suppose, finally, that control could pass
from the main program to an overlaid subprogram and thence to
a root-node subprogr~m.
If the root-node subprogram wishes
to do any I/O (again, other than ACCEPT and DISPLAY), there
must be a call from the main program to the root-node
subprogram to establish the direct link.

The subprogram structure must not contain RERUN statements.

The subprogram structure must not contain reentrant code
(compiled with /R under TOPS-IQ or compiled without switches
under TOPS-20.) Thus, users of TOPS-20 must use the /U switch
and users of TOPS-IO need not use the /U switch, as it is the
default, to avoid reentrant code.

To insure proper execution of a COBOL overlay, observe
rules:

the

following

After bringing the overlay into memory (by a LOAD command),
run it using the RUN command (not the START command).

Be sure that enough free memory is in the root link
program to execute.
(See Section 11.3.4.)

A subprogram loaded into a nonroot link is not writable.
the link comes into memory, it is in its original state.

11.3.3

for

the

Each

time

Defining Overlays

A program overlay has a tree structure. The tree is made up of links,
each containing one or more program modules.
These links are
connected by paths.
Using LINK switches, you define each link and
each path.
At the top of the tree is the root link, which must contain the main
program.
First-level links are below the root link;
each first-level
link is connected to the root link by one path.
Second-level links are below the first-level links,
and each is
connected by a path to exactly one first-level link. A link at level
n is connected by a path to exactly one link at level n-l.
Notice that a link can have more than one downward path (to
links), but only one upward path (to ancestor links).

successor

Figure 11-1 shows a diagram of an overlay structure with 5 links.
root link is TEST;
the first-level links are LEFT and RIGHT;
second-level links are LEFTI and LEFT2.

11-9

The
the

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
Example of an Overlay Structure

Figure 11-1 Example of an Overlay Structure
Defining an overlay structure allows your program to execute in a
smaller space. This is because the code in a given link is allowed to
make reference to memory only in links along a direct upward or
downward path.
In the structure in Figure 11-1, the link LEFT can reference memory in
itself,
in the root link TEST, or in its successor links LEFTI and
LEFT2. More generally, a link can reference memory in any link that
is vertically connected to it.
Referencing memory in any other link is illegal;
for example, a
from LEFTI to LEFT2 is not a direct upward or downward path.

path

Because of this restriction on memory references, only one complete
vertical path
(at most)
is required in the memory area at anyone
time. The remaining links can be stored on disk while they are not
needed.
LINK has a family of overlay-related switches for defining overlays.
These switches are described in detail in the LINK Reference Manual.
The following example shows command strings for defining the overlay
diagrammed in Figure 11-1.
TEST/LOG/LOGLEVEL:2
/ERRORLEVEL:5
TEST/OVERLAY
TEST/MAP
LPT:TEST/PLOT
CBLO,CBLI/LINK:TEST
/NODE:TEST CBL2,CBL3/LINK:LEFT
/NODE:LEFT CBL5/LINK:LEFTI
/NODE:LEFT CBL6/LINK:LEFT2
/NODE:TEST CBL4/LINK:RIGHT
TEST/SAVE
/E/GO

;Define TEST.LOG
;Important messages
;Define TEST.OVL
;Define TEST.MAP
;Request diagram
;Root link
;Left branch
;Left-left branch
;Left-right branch
;Right branch
;Define TEST.EXE
;Execute now

The first command string above defines the .LOG file for the overlay.
TEST/LOG specifies that the file is named TEST. LOG. The /LOGLEVEL:2
switch directs that only LINK messages at level 2 or greater be
written in the .LOG file.

11-10

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
In the second command string, the /ERRORLEVEL:5 switch directs that
messages below the level of 5 be suppressed for terminal typeout. The
third command string, TEST/OVERLAY,
tells LINK that an overlay
structure is to be defined and that the file for the overlay is to be
TEST.OVL.
The fourth command string, TEST/MAP, defines
overlay symbol maps.

the

file

TEST.MAP

The next command string, LPT:TEST/PLOT directs that a diagram
overlay links be printed on the line printer.

for
the

The next command string, CBLO,CBLI/LINK:TEST, loads the files CBLO.REL
and CBLl.REL into the root link.
The /LINK:TEST switch tells LINK
that no more modules are to be in the root link and that the link name
is TEST.
Each of the next four lines defines one link
form:

with

string

the

/NODE:linkname filenames/LINK:linkname
where:
/NODE:/linkname

specifies the previously defined link
to
which the present link is an
immediate successor.

filenames/LINK:linkname

names the files in the current link
and specifies the name of the link.

The first of these four lines begins with /NODE:TEST, which tells LINK
that the link being defined is to be an immediate successor to TEST,
the
root
link.
Then
(on
the
same
line) ,
the
string
CBL2,CBL3/LINK:LEFT loads the files CBL2.REL and CBL3.REL, ends the
link, and names the link LEFT.
The next line, /NODE:LEFT CBL5/LINK:LEFTl, defines a link named LEFTI
containing the file CBL5.REL, and this link is an immediate successor
to the link LEFT.
The next line, /NODE:LEFT CBL6/LINK:LEFT2, defines another immediate
successor to LEFT, this time containing the file CBL6.REL and called
LEFT2.
The last link is defined in the next line, /NODE:TEST CBL4/LINK:RIGHT.
This string defines the link RIGHT, which is an immediate successor to
TEST and contains the file CBL4.REL.
The next-to-last line in the example, TEST/SAVE, directs LINK to
create the saved file TEST.EXE.
The last line, /E/GO, specifies that
the loaded program is to be executed and that all commands to LINK are
completed.

11.3.4

The /SPACE Switch To LINK

For a COBOL overlay structure to execute properly, it must
memory in its root link for the following uses:
1.

General-purpose I/O buffers

11-11

have

free

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
2.

I/O buffers and file tables for sorting

Label record area for multireel files

File index blocks for split index blocks of ISAM files

The /SPACE switch to LINK reserves free memory.

It has the form:

/SPACE:n
where n is the decimal number of words to be reserved.
The /SPACE switch is used in the root link.
For example, to allocate
5000 words of free memory in the overlay example above, you would
type:
CBLO,CBLI/SPACE:5000/LINK:TEST
There are two types of space needed in the root link of a
overlay:
space for buffers and space for dynamic allocation.
Use the following guidelines to compute the
buffers:
1.

free

memory

COBOL

needed

for

Two buffers are needed for each sequential file and one
additional buffer
is needed for each extra area used in the
program.
For an unblocked sequential file (on disk or magnetic tape),
each buffer
is 128 words.
For example, the buffer space
needed for one sequential file on disk with one alternate
area is 3*128 = 384 words.
For a blocked sequential file on magnetic tape,
the buffer
size
is the blocksize
(record-size*records/block).
For
example, the buffer space needed for one blocked sequential
file with 100 records per block and records of 100 words each
is 2*100*100 = 20000 words.

One buffer is needed for each random-access file and one for
each file that is open for
I/O.
The buffer size is the
number of l28-word blocks needed to hold the logical block,
plus seven words.
For example, a random-access file with logical blocks of 25
10-word records has a block size of 250 words.
The smallest
number of 1~8-word blocks containing 250 words is 2
(= 256
words). Therefore the buffer size is 256 + 7 = 263 words.

Indexed-sequential files require one buffer for
The buffer size is the sum of the following:

each

Enough 128-word blocks to contain
each level of the index file.

logical

block

for

Enough l28-word blocks to
data.

logical

block

A number of l28-word blocks equal to the number used in
an index block.
These are used for storage allocation
tables.

One l28-word block for the statistics block.

11-12

contain

a
a

file.

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
e.

One l28-wotd block for the index table.

A number of words equal to the
plus two words.

A number of words equal to the largest blocking factor of

largest

index

key-size,

all the indexed-sequential files
in the program.
For
example, if the largest blocking factor is 10, then 10
words are required in the buffer.
h.

Enough l28-word blocks to contain the largest of the data
or
index blocks
in all indexed-sequential files in the
program.
For example, to compute the buffer size for
an indexed
sequential file with four
levels, with l28-word index
blocks and 256-word data blocks, compute as follows:
512
256
128
128
128
256
2
4

Total

1414

Four l28-word index blocks
One 256-word data block
One l28-word storage allocation table
block
One l28-word statistics block
One l28-word index table block
Two l28-word blocks for
the largest of
all data or index blocks
Two words for the largest blocking factor
2-word index key plus two words
Buffer size (in words)

Use the following guidelines to compute the amount of
needed for dynamic allocation du~ing program execution:

free

memory

The size of the label-record area for a multireel file.
This
size is 16 words for
standard labels.
For nonstandard
labels, the size is the number of characters in the label
divided by 5.

The size of the index block of an indexed-sequential file
the top index block is split.

The size of the sort I/O buffers if sorting is used
in the
program.
This size
is calculated as the number of devices
assigned to the sort file in the SELECT clause times two (for
two buffers for each file) plus 26 words for each file table
for each device.

For example, for a sort file with
buffers as follows:

four

4 * 128 words *2 + (4 * 26 words)

assigned

devices,

1128 words

NOTE
This calculation reflects
only
the
requirements needed by COBOL.
See also
the
SORT
User's
Guide
for
sort
requirements.

11-13

calculate

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
If you do not allocate sufficient fre~ memory ~ith the /SPACE switch,
either your program does not begin execution or it fails during
execution.

11.3.5

The CANCEL Statement

You can use the CANCEL statement
structure to reduce memory size
statement has the form:

in a COBOL subprogram overlay
during program execution. This

CANCEL subprogram-l [,subprogram-2] •..•
where each named subprogram is in one of the overlay links.
The CANCEL statement creates a call to the REMOV. Overlay Handler
subroutine.
This directs removal from core of the links containing
the named subroutines, along with all their successor links.
The
Overlay Handler attempts to return the recovered memory.
A CANCEL statement cannot direct removal of its own link or of any
its ancestor links, including the root link.

In the overlay structure diagrammed in Figure 11-1, for example, a
subprogram loaded into the link LEFT can CANCEL subprograms in link
LEFTl, LEFT2, or both.
But it cannot CANCEL subprograms in its own
link, LEFT, or in the root link, TEST.

11.3.6

Examples

The following pages show terminal listings of
the example above. These pages show:

associated

with

COBOL listing files for the
(seven pages)

used

the

Terminal copy of the interactive use of LINK
execute the overlay (two pages)

define

The file TEST.MAP, generated by LINK, which shows symbol maps
for the overlay (eight pages) .

11-14

programs

files

overlay
and

PRO G RAM
C B L 0
CBLO.CBL
15-JAN-81 08:31

.....
.....
I
.....
Ul

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026

COBOL-68 12B(1033) BIS

10-SEP-80

08:45

ID DIVISION.
PROGRAM-ID. CBLO.CBL
DATA DIVISION.
WORKING-STORAGE SECTION.
INFO.
01
LEVMSG PIC X (15) USAGE IS DISPLAY-7 VALUE "We're at level "
02
VALUE O.
LEVEL
PIC 9V
02
PGMMSG PIC X (12) USAGE IS DISPLAY-7 VALUE " in program "
02
CALMSG PIC X (9)
USAGE IS DISPLAY-7 VALUE " calling "
02
02
RETMSG PIC X (12) USAGE IS DISPLAY-7 VALUE "Returned to "
PIC X(8)
02
B
VALUE "
"
PIC X(6) VALUE "CBLO".
01
PGMN~M
ENDMSG PIC X(18) USAGE IS DISPLAY-7 VALUE "Execution ends in "
01
PROCEDURE DIVISION.
DISPLAY LEVMSG,LEVEL,PGMMSG,PGMNAM.
DISPLAY PGMNAM,CALMSG,"CBL2A".
CALL CBL2A USING INFO.
DISPLAY RETMSG,PGMNAM .
DISPLAY PGMNAM,CALMSG,"CBL4".
CALL CBL4 USING INFO.
DISPLAY RETMSG,PGMNAM.
DISPLAY PGMNAM,CALMSG,"CBL2B".
CALL CBL2B USING INFO.
DISPLAY RETMSG,PGMNAM.
DISPLAY ENDMSG,PGMNAM.
STOP RUN.

NO ERRORS DETECTED

PAGE 1

SUB
C B L 1
CBLl.CBL
15-JAN-81

I-'
I-'
I
I-'

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019

COBOL-68 12B(1033) BIS
08:30

ID DIVISION.
PROGRAM-ID. CBLI.
DATA DIVISION.
WORKING-STORAGE SECTION.
PGMNAM PIC X(6) VALUE IICBLll1.
01
LINKAGE SECTION.
INFO.
01
02
LEVMSG PIC X (15) USAGE IS DISPLAY-7.
02
LEVEL
PIC 9V.
02
PGMMSG PIC X (12) USAGE IS DISPLAY-7.
02
CALMSG PIC X (9)
USAGE IS DISPLAY-7.
RETMSG PIC X(12) USAGE IS DISPLAY-7.
02
02
B
PIC X(8).
PROCEDURE DIVISION USING INFO.
ADD 1 TO LEVEL.
DISPLAY B,B,LEVMSG,LEVEL,PGMMSG,PGMNAM.
DISPLAY B,B,IICBLI doesn't call anything ll •
SUBTRACT 1 FROM LEVEL.
GOBACK.

NO ERRORS DETECTED

10-SEP-80

08:46

PAGE 1

SUB
C B L 2
CBL2.CBL
15-JAN-81
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026
0027
0028
0029
0030
0031
0032
0033
0034
0035

COBOL-68 12B(1033) BIS

ID DIVISION.
PROGRAM-ID. CBL2.
DATA DIVISION.
WORKING-STORAGE SECTION.
01
PGMNAM PIC X(6) VALUE "CBL2".
01
ENTNAM PIC X(6).
01
ENTMSG PIC X(4) USAGE IS DISPLAY-7 VALUE" at "
LINKAGE SECTION.
INFO.
01
02
LEVMSG PIC x (15) USAGE IS DISPLAY-7.
02
LEVEL
PIC 9V.
02
PGMMSG PIC X (12) USAGE IS DISPLAY-7.
02
CALMSG PIC X (9)
USAGE IS DISPLAY-7.
02
RETMSG PIC X(12) USAGE IS DISPLAY-7.
PIC X (8) •
02
B
PROCEDURE DIVISION.
ENTRY CBL2A USING INFO.
ADD 1 TO LEVEL.
MOVE "CBL2A" TO ENTNAM.
DISPLAY B,LEVMSG,LEVEL,PGMMSG,PGMNAM,ENTMSG,ENTNAM.
DISPLAY B,PGMNAM,CALMSG,"CBL5".
CALL CBL5 USING INFO.
DISPLAY B,RETMSG,PGMNAM.
DISPLAY B,PGMNAM,CALMSG,"CBL6".
CALL CBL6 USING INFO.
DISPLAY B,RETMSG,PGMNAM.
SUBTRACT 1 FROM LEVEL.
GOBACK.
ENTRY CBL2B USING INFO.
ADD 1 TO LEVEL.
MOVE "CBL2B" TO ENTNAM.
DISPLAY B,LEVMSG,LEVEL,PGMMSG,PGMNAM,ENTMSG,ENTNAM.
DISPLAY B,"CBL2B doesn't call anything".
SUBTRACT 1 FROM LEVEL.
GOBACK.

NO ERRORS DETECTED

10-SEP-80

08:40

08:46

PAGE 1

SUB
C B L 3
15-JAN-81
CBL3.CBL

I--'
I--'
I
I--'
ex>

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019

COBOL-68 12B(1033) BIS
08:51

ID DIVISION.
PROGRAM-ID. CBL3.
DATA DIVISION.
WORKING-STORAGE SECTION.
PGMNAM PIC X(6) VALUE ICBL3".
01
LINKAGE SECTION.
INFO.
01
LEVMSG PIC X (IS) USAGE IS DISPLAY-7.
02
LEVEL
02
PIC 9V.
02
PGMMSG PIC X (12) USAGE IS DISPLAY-7.
02
CALMSG PIC X (9)
USAGE IS DISPLAY-7.
02
RETMSG PIC X (12) USAGE IS DISPLAY-7.
02
B
PIC X (8) .
PROCEDURE DIVISION USING INFO.
ADD 1 TO LEVEL.
DISPLAY B,B,B,LEVMSG,LEVEL,PGMMSG,PGMNAM.
DISPLAY B,B,B,"CBL3 doesn't call anything".
SUBTRACT 1 FROM LEVEL.
GOBACK.

NO ERRORS DETECTED

10-SEP-80

08:46

PAGE 1

SUB
C B L 4
CBL4.CBL
15-JAN-81

I-'
I-'
I
I-'
\.0

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021

COBOL-68 12B(1033) BIS
09:05

ID DIVISION.
PROGRAM-ID. CBL4.
DATA DIVISION.
WORKING-STORAGE SECTION.
PGMNAM PIC X(6) VALUE IICBL411.
01
LINKAGE SECTION'.
INFO.
01
02
LEVMSG PIC X(15) USAGE IS DISPLAY-7.
02
LEVEL
PIC 9V.
02
PGMMSG PIC X (12) USAGE IS DISPLAY-7.
02
CALMSG PIC X (9)
USAGE IS DISPLAY-7.
02
RETMSG PIC X (12) USAGE IS DISPLAY-7.
02
B
PIC X (8) .
PROCEDURE DIVISION USING INFO.
ADD 1 TO LEVEL.
DISPLAY B,LEVMSG,LEVEL,PGMMSG,PGMNAM.
DISPLAY B,PGMNAM,CALMSG,IICBLl l1 •
CALL CBLI USING INFO.
DISPLAY B,RETMSG,PGMNAM.
SUBTRACT 1 FROM LEVEL.
GOBACK.

NO ERRORS DETECTED

10-SEP-80

08:46

PAGE 1

SUB
C B L S
1S-JAN-81
CBLS.CBL

.....

.....
I

0001
0002
0003
0004
OOOS
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019

COBOL-68 12B(1033) BIS

ID DIVISION.
PROGRAM-ID. CBLS.
DATA DIVISION.
WORKING-STORAGE SECTION.
PGMNAM PIC X(6) VALUE "CBLSII.
01
LINKAGE SECTION.
01
INFO.
02
LEVMSG PIC X (IS) USAGE IS DISPLAY-7.
02
LEVEL
PIC 9V.
PGMMSG PIC X (12) USAGE IS DISPLAY-7.
02
USAGE IS DISPLAY-7.
02
CALMSG PIC X {9}
02
RETMSG PIC X (12) USAGE IS DISPLAY-7.
B
PIC X (8) •
02
PROCEDURE DIVISION USING INFO.
ADD 1 TO LEVEL.
DISPLAY B,B,LEVMSG,LEVEL,PGMMSG,PGMNAM.
DISPLAY B,B,"CBLS doesn't call anything".
SUBTRACT 1 FROM LEVEL .
GOBACK.

NO ERRORS DETECTED

10-SEP-80

08:48

PAGE 1

09:05

. ...

SUB
C B L 6
15-JAN-81
CBL6.CBL

I-'
I-'
I
~

I-'

0001
0002
0003
0004
0005
0006
0007
0008
000'9
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021

COBOL-68 12B(1033) BIS
09:04

ID DIVISION.
PROGRAM-ID. CBL6.
DATA DIVISION.
WORKING-STORAGE SECTION.
PGMNAM PIC X(6) VALUE "CBL6".
01
LINKAGE SECTION.
INFO.
01
02
LEVMSG PIC X (15) USAGE IS DISPLAY-7.
PIC 9V.
LEVEL
02
PGMMSG PIC X(12) USAGE IS DISPLAY-7.
02
CALMSG PIC X (9) USAGE IS DISPLAY-7.
02
02
RETMSG PIC X(12) USAGE IS DISPLAY-7.
B
PIC X (8) •
02
PROCEDURE DIVISION USING INFO.
ADD 1 TO LEVEL.
DISPLAY B,B,LEVMSG,LEVEL,PGMMSG,PGMNAM.
DISPLAY B,B,PGMNAM,CALMSG,"CBL3".
CALL CBL3 USING INFO.
DISPLAY B,B,RETMSG,PGMNAM.
SUBTRACT 1 FROM LEVEL.
GOBACK.

NO ERRORS DETECTED

10-SEP-80

08:48

PAGE 1

.R LINK ~
*TEST/LOG/LOGLEVEL:S ~
jDefine TEST. LOG
*/ERRORLEVEL:S ~
jImportant messages
*TEST/OVERLAY ~
jDefine TEST.OVL
*TEST/MAP ~
jDefine TEST.MAP
*CBLO,CBLI/LINK:TEST ~
iRoot link
[LNKLMN Loading module CBLO]
[LNKLMN Loading module CBLl]
[LNKLMN Loading module OVRLAY]
[LNKLMN Loading module CON012]
[LNKLMN Loading module LILOWS]
[LNKLMN Loading module TRACED]
[LNKLMN Loading module USRDSL]
[LNKLMN Loading module DBSTP$]
[LNKELN End of link number 0 name TESTj
*
/NODE:TEST
CBL2,CBL3/LINK:LEFT ~
[LNKLMN Loading module CBL2]
[LNKLMN Loading module CBL3]
[LNKELN End of link number 1 name LEFT]
*
/NODE:LEFT
CBLS/LINK:LEFTI ~
[LNKLMN Loading module CBLS]
[LNKELN End of link number 2 name LEFTl]
*
. /NODE:LEFT
CBL6/LINK:LEFT2 ~
[LNKLMN Loading module CBL6]
[LNKELN End of link number 3 name LEFT2]
*
/NODE:TEST
CBL4/LINK:RIGHT ~
[LNKLMN Loading module CBL4]
[LNKELN End of link number 4 name RIGHT]
*TEST/SAVE ~
*/E/GO ~
[LNKXCT CBLO Execution]

jLeft branch

jLeft-left branch
iLeft-right branch
;Right branch

We're at level 0 in program CBLO
CBLO
calling CBL2A
We're at level I in program CBL2
at CBL2A
CBL2
calling CBL5
We're at level 2 in program CBL5
CBL5 doesn't call anything
Returned to CBL2
calling CBL6
CBL2
We're at level 2 in program CBL6
calling CBL3
CBL6
We're at level 3 in program CBL3
CBL3 doesn't call anything
Returned to CBL6
Returned to CBL2
Returned to CBLO
calling CBL4
CBLO
We're at level I in program CBL4
CBL4
calling CBLI
We're at level 2 in program CBLI
CBLI doesn't call anything
Returned to CBL4
Returned to CBLO
CBLO
calling CBL2B
We're at level I in program ,CBL2
at CBL2B
CBL2B doesn't call anything
Returned to CBLO
Execution ends in CBLO

l:O

3:
00
t%l

Gl
3:
t%l

1-3
00
00
C

tx:I

:::0
0

)01

EXIT

zt j
0

<:
t%l

:::0
t'1

)01

LINK SV~bol map ot
TEST
Produced by LINK version 4B(1272) on

version 128(1102)
at 9:05:27

paQe 1

18-~~r-R1

Overley no.
0
name
TE5T
Low seg~ent starts at
0 ends at
3144 length
3145.
4P
~lgh seg~ent starts at
0 ends at
3506 length
3507
4P
Control Block address is
31~5, length
30 (oct~l), 24. (decimal)
411 words free In Low S~9ment, 185 words free In hiah segment
366 Gl~bal ~ymbols loaded, therefore min. hash size is 407
Start- ad~ress Is 400010, located 1n program CaLO

•••••••••••••

0
G'l

JOBDAT-INITIAL-SYMBOLS
Zero lenQtn

•••••••••••••

til
tzl

LIBOL-STATIC-AREA
Low segment st8rts itt
.COf04M.

~o"ule

140

140 ends at
Coml!lon

1477 length

length

736.

1340 (octal),
.COMM.

G'l
3:
tzl

736. (dechal)
_140

Common

length

736.

••••••••• *.*.
f-'
f-'

CBLO

I
N
,j::.

til
C

DSK:C8LO.RELf4,206]
cre!lted by CQBOL-68 on 21-Jan-Bl !It 10121100
250 (octal),
1500 ends at
1747 length
168. (deCimal)
Low segment starts at
205 (octal) ,
High 5eq~~nt starts ~t 400011) ends at 400214 length
133. (dec!m"l)
fro~

CRLO

400022

Entry

"0
~

0
G'l

Relocatable

5;!

••••••••••• **
CSLl

til

created by COBOL-6B on 21-Jan-B1 at 10:21100
from DSK:CRL1.REL[4,206]
220 (o~tal),
1750 ends at
2167 length
144. (deCimal)
Low seqment starts at
224 (octal) ,
14~. (deCimal)
High seqment starts at 400215 ends at 400440 length
CBLl

400217

F.ntry

>
Z

Relocatable

•••••• *.***.*
OVRLAY

tzl
~

t'1

>
t<

created by ~ACRO on 15-May-BO at 16154100
from SYS:OVRLAY.REL[4,20J
504 (octal) ,
2673 length
2170 ends at
324. (deClIIal )
Low segment starts at
3046 (octal), 1574. (dec!mal )
Hlqh seqment starts at 400441 t'nds at 403506 length
BOUn
ERJ~P

GCVEC\
GJ,OLD
HlLTF%

JFNS\
JS\NAJ4
LOGI)V.
OF'%RD
OPE~F'

104000000051
320700000000
t04000000300
10(1)00000000
104000000170
104000000030
7000000000
402644
200000
104000000021

Z
t-3

til

GlObal
GlObal
GlObal
Global
GlObal
GlObal
GlObal
Entry
GlObal
GlOhal

Absolute
Absolute
Absolute
Suppressed
Absolute
Absolute
Ahsolute
suppressed
Absolute
Relocatable
Suppressed
Absolllte
Absolute

CLOSF,
ERSTR\
GETOV.
GTJFN,
INIOV.
JS'DI~

104000000022
104000000011
402056
104000000020
402045
70000000000

JS%PAF

OP'\~SZ

770000000000
100000
20000000000

OF\WR
Pl\F.X

GlObal
Glonel
Entrv
Globel
Entrv
GlObal
GlObal
GlObal
GlObal
Global

til

AbSolute
Absolute
Relocetable
Absolute
Relocatable
AbSolute
Suppressed
AbSolute
Suppressed
Absolute
SUPpressed
Absolute
Suppressed
Absolute
Sup Dressed

LINK symbol map of

T1!:Sr

200000000
104000000076
104000000061
402115
10400001)0027
104000000053
777773

suppressed
Absolute
Absolute
Absolute
Relocateble
Absolute
Absolute
Absolute
Suppressed
suppressed
Absolute
Relocatable
Relocatable

version 12B(1102)

paQe 2

OVRLAY
PA\PRV
psoun
R"'AP\

RUNnv.
S~PTR\

SOUT%
.FHJOB
.JSAOF'
.OVRL!.
.QVPLU

2171
402401

Global
Global
GlObal
Entry
Global
Global
GlObal
Global
Entry
Entry

PBOUT,
REMOV.
RPACS\
RUNTM\
SIN\
\OVRLA
.F'HSLF
."'ULIO
.OVRLO
.OVRWA

104000000074
402077
104000000057
104000000015
104000000051
402000052
400000
371777
2176
2175

Global
Entry
GlObal
GlObal
GlObal
GlObal
GlObal
GlObal
GlObal
GlObal

Absolute
Reloeatable
AbSolute
Absolute
Absolute
Absolute
Suppressed
AbSolute
SUPpressed
Absolute
SUPpressed
Reloeatable
Reloeatable

from SY~:~IROL.R~Lr4,20J
LOW segment starts at
GF-T\
GJ%SHT
JS\GEN
RF\LNr,

2f>74
104000000200
1001')000
70000000
4000(1)000000

.~FSFt.

CN.12

I
N
U1

created by MACRO on 30-Jan-81 at 17:52:00
2614 ends at
200 (octal),
3073 lenQth
128. (deCimal )
Entry
Global
Global
GlObal
Global
GlObal

Reloc'atable
AI'\solut ..
Absolut~

Suppressed

Absolute

Sup~ress@d

Ahsolut~

SUP ores sed
Suooressed

Absolute

COBST.
GJ\PHY
GT\ADR
JS\TYP
RFSTS%

2674
10000000
200000
700000000
104000000156

GlObal
GlObal
GlObal
GlObal
GlObal

3:
til

Relocatable
Absolute
Suppre . . ed
Absolute
Suppressed
Ab'olute
SUPpressed
Absolute

*** •• *.* •••• *

I--'
I--'

LILOWS

tZJ
G'l

3:
tZJ

til
til

from SYS:LIROL.REL[4,20]

created by MACRO on

30-Ja~-81

C
ll'

at 17:52100

"'CI

0
G'l

Zero tenQth module

** •• ***_.* •• *
LIDISP

0
G'l

••••••• **** ••
CDNOl2

I't:J

from SYS:LIBOL.REL[4,20]

til

created by MACRO on 30-Jan-Sl at 17:52:00

Zero 1 enqth lIIodllle

t::I

*.* ••• *.* •• **

TRACED

from SYS:LIBOL.REL[4,20J
Low seqm@nt st~rts at
STPAC.
(,'\OI)T.

HSRPT.
SJ:lPSG.
TRPO.

3077
3101
3077
3077
3100

created by MACRO on 30-Jan-81 at 17:52100
3074 ends at
3103 lenQth
10 (octal) ,
Entry
Entry
Entry
E!'Itry
Entry

Relocatable
R~locatable

Relocatable
Relocatable
Reloc8table

C.TRCE
CNTRC.
PTFLG.
SF'OV.
TRPOP.

3074
3077
3102
3077
3077

*.* •• *••• *•••
USROSL

from SYS:LIROL.REL[4,20]
Zero leoQth ",odule

•••••••••••••

created bv MACRO on 30-Jan-81 at 17:52,00

<
tZJ

8. (deCimal)
E~try
E~try

GlObal
Entry
E~try

Relor:atable
Relocatable
Relocatable
Relocatable
Relocatable

t"1

til

LINK
08STP,

sy~bol

map of

from SYSILIBOL.REL[4,20)
Low seQment starts at
DBSTPS

]t04

....•..".".*.

TEST

version 128(1102)

pa;e 3

created bv ~ACRO on lO-Jan-81 at 17152100
3104 ends at
3104 lenQth
1 (octal),
Entry

1. (decimal)

Index to LI"K symbol mao of

TEST

vl!!rslon 128(1102)

page 4

Nallle

Paqe

Nlllllle

P8Qe

Name

Pl!ge

Name

Page

('8LO

t
1
2

ORSTPS
LTDISP

LILnws
OVRLAY

TRACED
USROSL

2
2

CRLl
cnN012

LTN~

sy~bol

map of

TFST

version 128(1102)

paQe 5

Overlay no.
n~me
L~FT
Low s~Q~ent starts at
7145 en~s at
10704 length
1540
2P
Contrnl Blo~K a1~ress Is 106it, lenath
30 (oct~l), 24. (dec1mal)
Path 15 0
sq words free In Low seqrnent, 185 words free In hlQh seQment
74 r.lobal symbols loade~, therefore mtn. hash size 15 27

••••• ** ••• ***
CRL2

from I)SKICFH.2.REL[4,2061
Low seqment starts at
Hlnh seament st8rts at

created by COBOL-68 on 21-Jan-81 at 10.23100
7711 ends at
10160 l~ngth
250 (octal),
168. (deCimal)
714~ ends at
77tO lenqth
544 (octal),
356. (decl~al'

CAL2

7147

~ntry

C~L1B

74S0

Entrv

Relocatable
ReloCl'ltable

CBL2A

7165

Entry

***.*********
CBL]

from ~SK:CBLJ.RELr4,2061
created by COBOL-68 on 21-Jan-81 at 10:23100
10421 ends at
10640 lengt~
220 (octal),
144. (deCimal)
Low seome~t st~rts at
10161 pndS at
10420 lengt~
240 (octal),
160. (deCimal)
H1qh seqment starts at
CRLJ

10t63

************.

Entry

Relocatable

LINK

sy~bol

map Of

TEST

version 128(1102)

paoe 6

Overlay no.

2
n~me
LEFT1
starts at
10705 ~n~s at
11376 lenQth
472.
1P
26 (oct~l), 14. (decimal)
Control RInCk address is 11351, length
Path 15 Or 1
257 words free In ~ow seqment, 185 words free in high segment
t9 Global svmbols loaded, t~erefore min. hash size Is 22
LOW

seg~~nt

*************
CRL5

from DSK:CBLS.REL(4 r 1061
created bV COBOL-68 on 21-Jan-81 at 10124100
11131 ~nds at
11350 length
22n (octal),
144. (deCiMal)
Low segment starts at
10705
ends
at
11130 length
224 (octal),
148. (deCImal)
High seq~ent st~rts at
CRLI)

10707

*************

......
......
I
N
~

Entry

LINK

SY~bol

map Of

TEST

version 128(1102)

page 7

Overlay no.
3
name
LF.FT2
Low segment starts at
10705 ends at
11446 length
542.
1P
Control ~loCK a~dress 15 11421, length
16 (oct~l), 14. (decimal)
~~th 15 0, 1
217 words free In Lo~ segment, 185 words free In hlQh segment
20 Global Sy~bOls loade~, t~erefore min. has~ sIze 15 23

**,*.*.******
CBL6

from DSK:CBL6.RELr4,206J
created bv CO~OL-68 on 21-Jan-81 at 10:24:00
Low seQ~ent starts at
11177 en~s at
11420 lenat~
222 (octal),
146. (decl~al)
HIgh seqment starts at
'0705 ends at
1117~ length
272 (octal),
1A6. (deCimal)
CRL6

tQ7~7

***.** •• ** •• *

Entrv

TEST

verlion 128(1102)

paoe 8

nallle
RIGHT
Overlay no.
4
Low segment Itarts at
7145 ends at
7664 length
520.
IP
7617, length
16 (octal), 14. (deci.al)
Control BlOCk addrels Is
Path :Is 0
75 words free In Low seoment, 285 words free In hlg~ leg~ent
20 Global symbols loa1e1, therefore ~tn. hash size Is 21

*************
CRL4

fro~

DSKIC8L4.~F.L[4,206]

Low se~ment starts at
Hiah seQ~e~t starts at
CRL4

7147

*************

.....
.....
I

.....

created bV COBOL-68 on ,1-Jan-81 at 10123100
7415 ends at
7636 lenQt~
222 (octal),
146. (dec1Mal)
714~ ends at
7414 lenQt~
250 (octal),
168. (decl~.l)
Entrv

Index to overlay nU'IIbers of TE:ST
Overlay Pi'lge
lIO
It t

Overlay Page
1I2

"
Index to

version 128(1102)
Overlay
lI3

Po!lq~

paoe 9

Overlay Page
114

I')verlav names of TF.ST

version 128(1102)

rH!me

P"!ge

N'!me

Paqe

Name

Paae

Name

Paoe

',EF'T
LF:F'I'l

LI';F'T2

RIGHT

TEST

[~n'"

of LINK map of

TFST)

CHAPTER 12
CALLING NON-COBOL SUBPROGRAMS

Some programming tasks are more conveniently done in a language other
than COBOL.
You can write non-COBOL subprograms for these tasks, and
then call the subprograms from COBOL programs.
To call a non-COBOL subprogram, use the ENTER verb
Division. The call has the form:

the

Procedure

ENTER language entry-name [USING string-l [,string-2] .•. ].
where:
language

is the name of the
subprogram.

compiler

that

generated

the

entry-name

is the name of the entry point you want to call.

string

is an identifier, literal, or procedure-name. The
list of strings is usually called an argument list
or a parameter list.

The compilers that can generate COBOL-callable subprograms are COBOL,
FORTRAN,
and MACRO.
The phrase ENTER COBOL is equivalent to CALL and
is not discussed further here.
The entry point used in the ENTER statement must be an entry-name
symbol generated by the compiler for
the called program. COBOL
generates an entry-name for each ENTRY statement and program-name.
FORTRAN generates an entry-name for each SUBROUTINE, FUNCTION, and
ENTRY statement.
MACRO generates an entry-name for each ENTRY
statement.
NOTE
You can use the "weaker" MACRO statement
INTERN
instead
of
ENTRY
if
you
explicitly load the MACRO module.
ENTRY
is required only if the module must be
loaded in a library search.

In the USING clause, using an identifier passes the value of the
identifier to the called subprogram;
uSlng a literal passes the
literal to the subprogram;
using a procedure-name passes the address
of the beginning of the named procedure, which can be used for
alternate returns.
FORTRAN cannot
accept
DISPLAY-6
(SIXBIT) ,
DISPLAY-9 (EBCDIC), or COMP-3 (packed-decimal) data.

12-1

CALLING NON-COBOL SUBPROGRAMS
12.1

CALLING FORTRAN SOBPROGRAMS

When the COBOL compiler finds an ENTER FORTRAN statement, it generates
a call for
the named subprogram.
If the ENTER statement contains a
USING clause, the values indicated by the given identifiers, literals,
and procedure-names are passed to the subprogram.
FORTRAN programs called by COBOL programs should not use blank COMMON,
even among themselves.
Doing so can overwrite storage in the COBOL
program.
In the following example, the COBOL program CFSQRT calls the FORTRAN
subprogram FSQRT to perform a square-root operation. The following
list shows how values are passed from the main program to the
subprogram:
Use of
Value

COBOL
Identifier

FORTRAN
Variable

Input number

INPUT-NUMBER

INPUT

Answer

ANSWER

Error message location

ERROR-MESSAGE

ERRMSG

Exit message location

EXIT . . . MESSAGE

EXMSG

The following is the source file for the COBOL program CFSQRT:
ID DIVISION.
PROGRAM-ID. CFSQRT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 INPUT-NUMBER USAGE COMP-l.
01 ANSWER USAGE COMP-I.
PROCEDURE DIVISION.
LOOP.
DISPLAY 'Type a positive integer. '.
ACCEPT INPUT-NUMBER.
ENTER .FORTRAN FSQRT USING INPUT-NUMBER,ANSWER,
ERROR-MESSAGE,EXIT-MESSAGE.
DISPLAY ANSWER.
GO TO LOOP.
ERROR-MESSAGE.
DISPLAY 'No negative numbers, please.'.
GO TO LOOP.
EXIT-MESSAGE.
DISPLAY 'Thank you~'.
STOP RUN.
The following is the source file for the FORTRAN program FSQRT:
SUBROUTINE FSQRT(INPUT,ANSWER,*,*)
REAL INPUT
INTEGER ERRMSG,EXMSG
ERRMSG=l
EXMSG=2
IF(INPUT.LT.O) RETURN ERRMSG
IF(INPUT.EQ.O) RETURN EXMSG
ANSWER=SQRT(INPUT)
RETURN
END
12-2

CALLING NON-COBOL SUBPROGRAMS
In the following lines, these two source p~ograms are executed.
Each
positive integer input yields its square root; a negative number
yields an error message at an alternate return in the COBOL program;
o yields the exit message at another al±ernate return. Note that the
TOPS-IO system prompt could be replaced by the TOPS-20 prompt (@)
without altering the example - the programs run exactly the same way
under TOPS-20 •
• EX CFSQRT.CBL,FSQRT.FOR
FORTRAN: FSQRT
FSQRT
COBOL: CFSQRT [CFSQRT.CBL]
Loading
LINK:
[LNKXCT CFSQRT Execution]
Type a positive integer.
4

2.0EO
Type a positive integer.
3

1.7320508EO
Type a positive integer.
2

1.4142136EO
Type a positive integer.
1

1.OEO
Type a positive integer.
-1

No negative numbers, please.
Type a positive integer.

Thank you.
EXIT

12.2

CALLING MACRO SUBPROGRAMS

When the COBOL compiler finds an ENTER MACRO statement,
the standard calling sequence:

generates

MOVEI 16,arglist
PUSHJ 17,entry point
where arglist is the address of the first word of the
and entry point is an entry-name symbol.

argument

list,

If the ENTER statement contains a USING clause, the compiler creates
an argument list containing an entry for each identifier or literal in
the clause. The word immediately preceding the argument list is of
the form:
-length"O
where length is the number of arguments in the list.
If no USING
clause appears in the ENTER statement, the length of the list is 0
(but the length word still appears).

12-3

CALLING NON-COBOL SUBPROGRAMS
Each entry in the argument list is a 36-bit storage word of the form:

1=======================================================1
1
0
1 Code 1
Effective Address (E)
1
1=======================================================1
o

8 9

12 13

where code is a 4-bit code (described below), and bits 13-35
the effective address (E) of the first word of the argument.

contain

If the passed argument is a I-word COMP item, the code is 2 and
the location of the argument.

If the passed argument is a 2-word COMP item, the code is 11 (octal)
and E is the location of the first word of the argument; the second
word of the argument is at E+l.
If the passed argument is a COMP-l item, the code is 4 and
location of the argument.

the

If the passed argument is a DISPLAY-6, DISPLAY-7, DISPLAY-9, or COMP-3
item, or a figurative constant, the code is 15 (octal) and E is the
location of a 2-word descriptor for the argument. The first word of
the descriptor is a byte pointer word pointing to the argument. Its
byte size is 6 for DISPLAY-6 or TODAY, 7 for DISPLAY-7 or literals or
other figurative constants, and 9 for DISPLAY-9 and COMP-3 items.
The format of the second word is:
Bit 0

Reserved

Bit 1-4

Type code:
1= DISPLAY-6
2= DISPLAY-7
3= DISPLAY-9
4= COMP-3

Bit 5

Item is a literal

Bit 6

Item is a figurative constant (e. g.

Bit 7

Item is numeric

SPACES)

If bit 7 = 0:
Bit 8-11

Reserved

Bit 12-35

Size of item in bytes

If bit 7 = 1:
Bit 8

Item is signed

Bit 9

Item is scaled (i.e. PICTURE contains "P's"
left of implied decimal point, e.g. 999PP)

Bit 10

Item is numeric edited

If bit 9 = 0:
Bit 11-25

Reserved

Bit 26-30

Number of decimal places

12-4

CALLING NON-COBOL SUBPROGRAMS
Bit 31-35

Size of item in bytes

If bit 9 = 1:
Bit 11-25

Reserved

Bit 26-30

Scale factor

Bit 31-35

Size of item in bytes
999PP)

(e.g.

2 if picture was 999PP)
(e.g.

picture

was

The following are additional usage notes:
1.

A figurative constant is passed exactly as a one-character,
non-numeric DISPLAY-7 data item, except that bit 6 in the
second descriptor word is set~

The figurative constant TODAY is passed as
DISPLAY-6 data item, except that bit 6
descriptor word is set.

The figurative constant TALLY is passed as a I-word COMP data
item.

For an item with a picture that contains "PiS" on the right
side of the assumed decimal point (e.g.
PIC VPP999), bit 9
is not set. This case can be recognized because the number
of decimal places is greater than the total size of the item.

If the passed argument is a procedure-name (not allowed in a
call to a COBOL subprogram),
the code is 7 and E is the
location of the first word of the procedure.

a 12-character
in the second

In the following example, the COBOL program CMSQRT calls the MACRO
subprogram MSQRT to perform a square-root operation.
(The subprogram
uses the FORLIB routine SQRT to take the square root.)
The argument list
follows:

generated

-4,,0
ARGLST: Z 4,address
Z 4,address
Z 7,address
Z 7,address

the

ENTER

;-Arglength"O
;<4B12>+<Address
;<4B12>+<Address
;<7B12>+<Address
;<7B12>+<Address

12-5

MACRO

of
of
of
of

statement

1st COMP-l item>
2nd COMP-l item>
1st procedure>
2nd procedure>

CALLING NON-COBOL SUBPROGRAMS
The following is the source file for the COBOL program CMSQRT:
ID DIVISION.
PROGRAM-ID. CMSQRT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 INPUT-NUMBER USAGE COMP-l.
01 ANSWER USAGE COMP-l.
PROCEDURE DIVISION.
LOOP.
DISPLAY 'Type a positive integer.'.
ACCEPT INPUT-NUMBER.
ENTER MACRO MSQRT USING INPUT-NUMBER,ANSWER,
ERROR-MESSAGE,EXIT-MESSAGE.
DISPLAY ANSWER.
GO TO LOOP.
ERROR-MESSAGE.
DISPLAY 'No negative numbers, please.'.
GO TO LOOP.
EXIT-MESSAGE.
DISPLAY 'Thank you. '.
STOP RUN.
The following is the source file for the MACRO program MSQRT.
Notice
that the entry-name MSQRT must be declared ENTRY and that the FORLIB
routine SQRT, which is to be called, must be declared EXTERNAL.
Notice also that at NEG and ZERO, the return address in the stack is
replaced by a procedure-name
(address)
to set up the alternate
returns. At POS, the pointer to the argument list must be saved
before calling SQRT.

MSQRT:

POS:

TITLE
ENTRY
EXTERN
SKIPN
JRST
JUMPL

MSQRT
MSQRT
SQRT
1,@0(16)
ZERO
1,NEG

MOVEM
MOVEM
MOVEI

1,ARG
16,SAVPTR
16,1+[-1,,0
Z 4,ARG]
l7,SQRT
16,SAVPTR
0,@1(16)
17,
1,@3(16)
1,0(17)
17,
1,@2(16)
1,0(17)
17,

PUSHJ
MOVE
MOVEM
POPJ
ZERO:
MOVEI
MOVEM
POPJ
NEG:
MOVEI
MOVEM
POPJ
ARG:
BLOCK 1
SAVPTR: BLOCK 1
END

;Skip if not zero
;To zero routine
;To negative routine
;Fall into positive routine
;Save arg in reg 1
;Save return address
;Set up arg for SQRT
;FORLIB square root routine
;Restore return address
;Set up return arg
;Return
;Set up alternate return
; for zero arg
;Return
;Set up alternate return
;
for negative arg
;Return

In the following lines, these two source programs are executed. Since
neither program is a FORTRAN program, FORLIB must be explicitly
searched.

12-6

CALLING NON-COBOL SUBPROGRAMS
Each positive integer input yields its square root; a negative number
yields an error message at an alternate return in the COBOL program;
o yields the exit message at another alternate return. Note that the
execution of these programs yields the same output if run under
TOPS-IO.
@EXE CMSQRT.CBL,MSQRT.MAC,SYS:FORLIB.REL/SEARCH
COBOL: CMSQRT
[CMSQRT.CBL]
MACRO: MSQRT
LINK:
Loading
[LNKXCT CMSQRT Execution]
Type a positive integer.
4
2.0EO
Type a positive integer.
3

1.7320508EO
Type a positive integer.
2

1.4142136EO
Type a positive integer.
1

1.OEO
Type a positive integer.
-1

No negative numbers, please.
Type a positive integer.

Thank you.
EXIT
@

12-7

CHAPTER 13
IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS

Normally, the code generated by the COBOL-68 compiler is adequately
efficient.
However, since there are certain COBOL-68 constructions
for which efficient code is not g~nerated, it is possible to write
programs that perform poorly. If your programmed application performs
inefficiently, you are left with the following alternatives:
1.

Assume that a higher-performance
compiler solves the problem

version

Purchase new or faster hardware

Redesign the entire program

Rewrite only the bad portions of the program

the

COBOL-68

Assuming that you are unwilling to wait for an improved compiler or
purchase new or faster hardware, let us consider the remaining
alternatives.
Although redesigning the entire program or application is possible, it
is expensive and is generally not done. Like any system rewrite,
however, it does offer the opportunity to add new features and
eliminate old, out-of-date ones.
It is a good alternative, in the
long run.
The much cheaper solution is to determine why a program is performing
poorly and rewrite only the inefficient portions. This normally does
not require a large effort since most COBOL programs spend 90% of the
time executing only 10% of their code. The biggest task involves
determining why a program is inefficient.
Most programs lend themselves to some improvement.
There have been
many instances where a program used less than half the CPU time after
improvement than it did before. Most often, the gain is in the range
of 30%. Most significant is the fact that the reprogramming generally
involved only 20 lines or less.
Because some optimization techniques can be contrary to programming
standards, it is necessary to use discretion when choosing which
programs to improve and how much to improve them. It is, therefore,
not recommended that all programs be optimized. For example, little
is gained if a weekly application has its CPU time cut from 10 to 5
minutes.
A program that runs for 2 hours a day, on the other hand,
probably should be investigated.
Program optimization is usually done on an as-needed basis:
the
greater the resource consumption by a program, the greater the
priority for optimization. Therefore, your installation's programming
standards
should guide programmers towards efficient, partially
13-1

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
optimized programs.
Each computer system is different.
Therefore,
it is likely that
installation programming standards reflects, to some extent, practices
that promote efficient use of the presently installed system. On some
systems, for example, the size of a program, the number of files open,
and the type of devices used affects a program's performance.
On
other systems, emphasis is placed on data types, coding practices, and
data patterns.
It is normal for a programming standard to reflect
those practices that normally produce efficient results without
impairing reliability or maintainability.
The standard, therefore, could stipulate that all counters,
indexes,
and subscripts be described as COMPUTATIONAL.
It could also, as is
the case with most TOPS-IO and TOPS-20
installations,
standardize
around
DISPLAY-6 files because of file-space economy.
Another
standard practice is to request that an analysis of the data be made
and that the program be written to efficiently process it.
For
example, the following program statements make some decisions based on
the value of a particular item:
IF ABLE> BAKER GO TO CHARLIE.
IF ABLE < BAKER GO TO DOG.
IF ABLE
BAKER GO TO ECHO.
If the value of ABLE is normally equal to BAKER, the program should be
reordered with the following statement first:
IF ABLE

= BAKER GO TO ECHO.

Programming techniques of this type promotes efficiency
every system and should be encouraged.

virtually

Any programmer who can write COBOL programs can optimize them.
Most
of the programming tools currently available require minimal knowledge
of anything other than COBOL. The optimization tools and techniques
described in this chapter plus the techniques described in your
installation standard provide most of the information needed to
improve most COBOL programs.
It is easy to apply already known optimizations to a program.
It
becomes more difficult to make programs more efficient, however, when
the known optimization techniques are not applicable.
The person who
can be most successful is one who understands a little about the code
generated by the compiler and can read assembler code.
By using the
/A switch option to obtain a listing of the assembly language code
generated for the program, you can determine, from the code generated,
which alternatives produce the best results.
There are many ways to make a program more efficient.
The best
results come from good program design.
Minimizing disk access,
segmenting programs into small well-defined pieces, and keeping
irrelevant information out of records are some ways to gain more
efficiency.
Discussion of these techniques,
because
they
are
applications-specific, are beyond the scope of this chapter. They are
mentioned here in order that you take them into consideration when
designing your individual applications.
The remainder of this chapter
deals with program improvements.
It is a collection of techniques
that have been used to good advantage by various installations.

13-2

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
13.1

HOW TO PROCEED WITH PROGRAM OPTIMIZATION

The actual coding required to optimize a program is usually minimal
and not time-consuming.
The largest component of time is spent
learning the nature of the problem, that is, determining where and how
much time is being spent by the program. Therefore, once a program
has been selected for investigation, it is advisable to form a plan or
procedure to be followed.
This plan should consist of a series of
small steps each designed to improve a small portion of the program.
As one portion of the program is improved, begin on the next, and so
on until the entire program has been improved to your satisfaction.
NOTE
Do not attempt program
optimization
until the program has been debugged and
runs correctly!

13.1.1

Where To Begin

Begin by gathering together the following material and information:
1.

An understanding of the goal (lower elapsed time or CPU time)

Copies of the source program and supporting software

Enough data to make this program run long enough to measure,
and short enough to allow quick turn-around - 10 to 15
minutes is usually sufficient

Files for output verification

Access to the measurement tools (see Section l3.l.2)

A notebook to record all observations,
results (see Section l3.l.S)

13.1.2

measurements,

and

What Tools Are Available

There are some tools that are part of the system software;
you can
have others at your installation;
and some are available through
DECUS and other agencies. This chapter discusses those that are part
of the system software and are commonly used and understood. These
tools are:
For users of TOPS-10 and TOPS-20
7.3 and 13.2

•

COBDDT-

•

SET WATCH - For users of TOPS-10 only
see
Operating System Commands Manual

13-3

see

Sections

the

TOPS-10

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
13.1.3

What Method Or Procedure To Use

Once you have gathered all of the information and materials required,
and are familiar with the various tools at your disposal, it is time
to decide upon a course of action.
The following procedure is
provided as a guide. You can expand or shorten it as benefits your
application or installation.
1.

Generate a version of the program and its data that uses 10
to 15 minutes elapsed time. Remove anything from the program
(terminal interaction, logical names, etc.) that make it
difficult to run.

Schedule your machine time to coincide with periods when the
system is lightly loaded. This enables you to make better
use of the elapsed time statistics.

Run the unaltered (original)
following statistics:

program

and

determine

the

Amount of CPU time used

Elapsed time

Amount of idle time on the system

Amount of disk I/O, swapping, etc.

Use SET WATCH to observe the program
during
its
execution;
SET WATCH aids you in determining CPU time,
peripheral usage, etc.

Some of these statistics are not too meaningful on a system
with even a moderate work load. Only the person conducting
the test can determine to what extent the system work load
can bias the measurement.
However, even if the system is
loaded, CPU time is normally a good indication of how the
program performs.
If the program runs with idle time,
determine the reason for it (disk wait, tape wait, etc.).
Often, additional buffering can lower the elapsed time.
(See
Section 13.1.4, Evaluating Performanrie.)
4.

Run a COBDDT histogram to determine its runtime statistics.
The histogram aids you in spotting potential problem areas in
the program.

If other tools are available, use them.

Save the output from this first run for verification.

Analyze the results and make any changes you believe improves
the program.

Recompile, link, and execute the program using the tools
techniques mentioned above.

and

Compare the statistics from
previous or original run.

the

10.

Write down all observations,
Section 13.1.5, Documentation.)

13-4

this

run

with

those

facts,

and

hunches.

(See

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
11.

Repeat steps 7 through 10 until you are
results.

satisfied

with

the

The last step, repeat until satisfied, is very important. It is very
easy to get carried away with program optimization. Start with a
premise, for example, "I will be satisfied with a 30% improvement".
When you reach this level of performance, stop.

13.1.4

Evaluating Performance

Generally the best criterion for evaluating performance is the one
that led you to be suspicious of the program in the first place. Most
generally, CPU time is used. It is easy to measure and easy to
reproduce.
You simply observe the CPU time in the original program,
make changes as appropriate, rerun the program and observe it again.
If the CPU time decreases, the changes were effective.
NOTE
Because CPU time can vary with the load
on the system, 6nly changes in excess of
5% can be considered significant.
Another, more effective, way to determine performance is to measure
the amount of work done per second of CPU time. By counting the
number of records processed per second or minute, you have a good way
to document a program's performance. Thus, if a program can normally
process 100 records per CPU minute, and the volume increases by 1000
records per run, the effect is clearly an increase of about 10 CPU
minutes per run.

13.1.5

Documentation

It is a good practice to document everything you have done during
program optimization. You may want to improve other programs, and the
notes you take for the first attempt can aid you in saving time and
effort on each succeeding attempt. The documentation kept should be
simple and should include the following information:
1.

The name of the program, the time and date of
the name of the programmer

the

run,

The amount of data used by the test
1000 records for a 10-minute run

for

example,

The time (CPU and elapsed) used by the original program

The level of performance desired

The optimization techniques utilized

The results obtained, both positive and negative

COBDDT histogram

Any observations about system performance

13-5

program,

and

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
9.

Any other statistics collected, feelings, hunches, and
perceptions

other

The documentation need not be elegant.
It should, however, be
permanent.
You might even tape portions of the console log into your
notebook as a quick way of recording timings.

13.2

LISTING THE TOOLS

This section discusses the tools most commonly used by
COBOL
programmers for program optimization: COBDDT and SET WATCH. You are
advised to read Section 7.3, COBDDT, before reading this section. The
write-up on SET WATCH in the TOPS-IO Operating System Commands Manual
is also recommended for users of TOPS-IO.
This section does not
attempt to redo anything that has already been done.
It attempts only
to present information relevant to program optimization.

13.2.1

COBDDT

This section discusses COBDDT as used for
evaluating
program
performance. Therefore, only the histogram feature is described. The
COBDDT histogram provides you with the following information for each
procedure that was executed in your program (see Figure 13-1, Sample
COBDDT Histogram) :
•

Procedure name

•

The number of times the procedure was entered (ENTRIES)

•

The CPU time the procedure used (CPU)

•

The elapsed time the procedure used (ELAPSED)

COBDDT HISTOGRAM FOR XDDT04
XDDT4B.HIS
PROCEDURE

REPORT:

ENTRIES

CPU

ELAPSED

1
5
1
1
2
3
3
7
7
7
10
10

0.336
0.251
0.028
0.005
0.045
0.123
0.013
0.032
0.030
0.030
0.115
0.050

1.649
1.239
0.333
0.005
0.065
0.398
0.029
0.065
0.152
0.047
0.380
0.108

1ST
P12
PP3
PP4
PP5
2ND
2PO
2Pl
2P3
2PI0
3RD
3PO
XDDT4B.HIS
OVERHEAD:

ELAPSED:

0.002

Figure 13-1 Sample COBDDT Histogram

13-6

CPU:

0.002

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
13.2.1.1 The ENTRIES Column - The information listed in the ENTRIES
column of the histogram helps you to set your priorities for program
improvement. Very high counts relative to others establishes the
paragraph as one which needs further investigation.
For example:
1.

Why is it entered so often?

Is anything done there that could be
elsewhere?

Can it be rewritten to do less?
Coding Conventions.)

Often, the numbers guide you into
decision lists.
For example:

done

effectively

(See Section 13.5, Efficient

understanding

how

order

your

Suppose P-l was typically entered 1000 times, P-2 was entered 500
times, and these paragraphs are chosen by a decision list that
looks like this:
S-l.

IF A

" GO TO P-2.

S-2.

IF A

"00" GO TO P-l.

It is apparent, then, that the order of S-l
reversed because A is usually 00.

and

S-2

should

Also, based on the number of records processed, unexpected
ce~tain paragraphs should be accounted for.

counts

Do not be afraid to add new paragraph names to the program. Not only
does this technique allow you to break large paragraphs up into
smaller ones, it also enables you to better understand exactly where
the program spends its time.

13.2.1.2 The CPU Column - The histogram's CPU column lists the amount
of CPU time each paragraph used. Generally, if you can cut the CPU
time, the elapsed time also drops and the application performs more
efficiently.
By analyzing this column, you can easily identify the
big spenders - those procedures that eat up most of the CPU time. One
approach is to rank the paragraphs in terms of CPU time and to look
for paragraphs that spend more time per entry than others.
Then,
proceeding in rank order, determine what each paragraph is doing, if
it has to do it, and if a better coding technique is in order.
Usually only a few paragraphs need be examined.
NOTES
1.

CPU time for a
paragraph
also
includes time spent in'paragraphs
performed
or
routines
called.
Therefore, the sum of the CPU time
is greater than the total
time
actually
spent
within
this
paragraph.
(See Section 13.2.1.4.)

CPU time also includes time spent in
the object-time system, the monitor,
and for users of
TOPS-20,
the
compatability package.
13-7

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
If after examining the list of the most time-consuming paragraphs, you
determine that all can be explained, it is unlikely that changing any
particular thing improves performance. Either the program cannot be
improved any further, or other techniques are needed.

13.2.1.3 ELAPSED Column - In a lightly loaded system, the elapsed
time can be a guide to the .effective blocking of records. Some
experiences with programs that seemed I/O-bound indicated that they
were spending a great deal of time in the paragraphs that dealt with
random or ISAM reads and updates. Inspection of the blocking revealed
that while the files were blocked to conserve disk space, large
amounts of data were being transferred (1 block) when the desired
object was to update 1 record.
Therefore, if a disproportionate
amount of time is spent in some paragraphs, there could be a problem
in processing. These paragraphs should definitely be investigated.

13.2.1.4 OVERHEAD - This entry in the histogram,
(see Figure 13-1)
represents the time spent for PERFORM or CALL overhead. Look at this
entry to evaluate the cost of PERFORM-loop control mechanisms.
If
this figure is high, then some very short paragraph is being performed
a large number of times. If this is the case, a more 'efficient method
of loop control is probably in order.

13.3

USING THE CORRECT DATA TYPE

Understanding the various data types available is extremely important
because there are so many of them.
COBOL-68 offers you three
different DISPLAY types and several COMPUTATIONALS.
Each data type
offers some advantages and some disadvantages. It is necessary to
understand these in order to maximize the efficiency of a particular
application.

13.3.1

DISPLAY Data Types

There are 3 display data types used within COBOL.
EBCDIC
ASCII
SIXBIT
EBCDIC and ASCII are character codes that occupy 8 and 7 bits per
character respectively.
The representations for each character are
defined by industry standards. SIXBIT is a 6-bit BCD code which is
defined by DIGITAL.

13.3.2

EBCDIC

The 8-bit EBCDIC code allows 256 different characters.
It is
compatible with IBM and thus is a natural where data interchange with
360s and 370s is necessary. EBCDIC files can contain a mixture of
EBCDIC and COMPUTATIONAL-3 data. EBCDIC is packed into the computer's
memory, 4 characters per word.

13-8

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
EBCDIC processing is going to be somewhat slower than either ASCII or
SIXBIT because of the amount of space that each character takes up.
As an example, a l20-character record would occupy:
1.

30 words in EBCDIC

24 words in ASCII

20 words in SIXBIT

Since movement of data is roughly linear with volume (it takes twice
as long to move twice as much), it can be seen that SIXBIT and ASCII
are 33% and 20% more efficient than EBCDIC, respectively.
The amount of file storage is also proportional to the byte size.
For
example,
five ASCII records or 6 SIXBIT records can be stored in the
same space taken by only 4 EBCDIC records.
Thus the use of EBCDIC should be restricted to those cases where:
1.

The ASCII and SIXBIT character set is too small (128 and
characters respectively compared with 256 for EBCDIC).

The transmittal of data to and from EBCDIC systems is a major
part of the application.

The application depends on the collating
after alphabetics).

The existence of many redefined records with mixtures
EBCDIC and COMP-3 make reprogramming unthinkable.

sequence

(numerics
of

In summary, it suffices to say that EBCDIC is a useful data type
available to the COBOL user.
For whatever its benefit, you must
realize that it is slower and that a 33% increase on throughput could
be realized by going to SIXBIT.

13.3.3

ASCII

Seven-bit ASCII is the coding sequence utilized by the unit record
peripherals and terminals. Any other data type (EBCDIC or SIXBIT) has
to be converted to ASCII if it is to be sent to one of these devices.
In memory, the use of ASCII makes the movement of data proceed faster
than EBCDIC but slower than SIXBIT because of the number of characters
per word.
On the disk, all ASCII records are variable length as
defined by industry standards, the end of an ASCII record is defined
by the existence of a "vertical form" (normally a line feed) character
(or several such characters).
Thus, it is necessary to read ASCII
files a character at a time in order to find
the end-of-record
character. This implies that ASCII records can be variable length and
efficiently stored on the disk.
It also implies that moving such
records to or from memory is more costly than the other data types
that can be moved by the block transfer instruction.
ASCII is the standard data type for "text files".
Files created by
editors
that
contain
arbitrary length records can be stored
economically and processed easily using the ASCII data type.
Cards
from a reader can be "trailing blank suppressed" so that they can be
stored economically and are easily manipulated using ASCII.
However,
unless the full character set capabilities of ASCII
(128 with
lowercase plus line control) are necessary or the data is coming from
13-9

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
or going to an ASCII
probably preferable.

13.3.4

peripheral,

conversion

SIXBIT files is

SIXBIT

By far the most efficient DISPLAY code is SIXBIT. Six characters can
be packed per word. Each record on disk or tape is preceded by a word
with a character count allowing for block transfers of data. And the
transmission time for moving the data around memory is less than any
other data type.
The only problem with SIXBIT is the number of characters possible
within the 6-bit code.
The 64 characters allow for uppercase,
numerics, and punctuation. It does not allow for lowercase, device
control characters, or special graphics.
Most installations put the bulk of their files into SIXBIT due to the
storage economy and the processing efficiency. Use if SIXBIT files is
highly recommended wherever possible.

13.3.5

COMPUTATIONAL

There are several flavors of computational data types available to the
COBOL programmer including:
1.

COMPUTATIONAL-3, the four-bit complement of EBCDIC

COMPUTATIONAL, internal binary {35 bits plus sign}

Double-word COMPUTATIONAL, automatically invoked when the
number of digits desired is greater than 10 {70 bits plus
sign}

COMPUTATIONAL-I, floating point {the
hardware
supports
double-precision floating point, but COBOL does not}

Aside from the use of COMP-3 as an adjunct to EBCDIC, the most useful
data type is COMPUTATIONAL.
This is normally used for indexes,
counters, and subscripts. If other data types are used for these
purposes, there is continual conversion taking place since all
arithmetic is done in binary.
You can read arbitrary files by defining them as BINARY mode and
use the data as desired.

13.4

then

DATA EFFICIENCIES

Programming standards should insist on using the correct data types
for certain operations. Using COMPUTATIONAL for counters works better
on almost any machine.

13-10

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
13.4.1

Counter, Indexes, Subscripts

In DIGITAL COBOL indexes and subscripts are not different (this is not
the case with some systems).
They are,
in fact,
the same as
COMPUTATIONAL. A data item that is used as a counter or subscript
should be declared:
77 THE-NAME

PICTURE S9(10) COMPUTATIONAL.

COMPUTATIONAL items are always word-aligned no matter at what level
they are defined and thus are equally efficient.
However, there are
some things which must be observed.
1.

If the number of digits is greater than 10, the item becomes
double-word computational.
If you have the BIS compiler on
TOPS-IO or you are using TOPS-20, all arithmetic is done
in-line using double-precision instructions. Otherwise, all
arithmetic is done with calls to the object-time system.
However, it is still faster and more efficient than DISPLAY.

It is important that the variable be signed.
If it is not,
much less efficient code is generated in order to insure that
it is never negative.

13.4.2

File Storage

SIXBIT files are the best for file storage and data manipulation
efficiencies.
Not only do they requlre less space than ASCII or
EBCDIC, but they are efficient to move about.
Each SIXBIT record is
preceded by a "length descriptor"
that provides the information
necessary to do block transfers of data in memory rather than
character by character.
Also, since SIXBIT records are always word
aligned, they can be transferred with block transfer instructions.
ASCII is good for text which is of variable length (for example those
created by EDIT) and for line control.
It suffers from the necessity
to process each character to determine the end of the record.
EBCDIC is necessary if more than 128 characters are needed and if data
transfer to systems using EBCDIC is necessary.
It is also necessary
to read files character by character since EBCDIC records
(fixed
length) need not necessarily be word aligned.
It can be somewhat more
efficiently processed than ASCII, however, since a specified number of
characters is always transferred rather than an arbitrary number.

13.4.3

Blocking Data

Processing data from disk is more efficient if it is not blocked.
This allows the system to pack information as tightly as possible on
the disk with no slack bytes between blocks. Blocks always start on
one
of
the disk's l28-word sector boundaries.
Thus blocking
inefficiently could waste considerable space.
If you block disk records, remember to count the length descriptor
words on SIXBIT and variable-length EBCDIC records.
Records for these
two data types are also word aligned.

13-11

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
13.5

EFFICIENT CODING CONVENTIONS

This section contains a listing of some practical coding practices
that have proven efficient. You can show these to be beneficial by
writing short programs that execute these sequences a large number of
times.
It is also possible- to look at the MACRO expansion of the
program to see what is different about the compiled code.

13.5.1

Alignment

When the addresses of the data items are known at compile time, the
compiler can generate efficient in-line code. This code can include
the use of the block transfer instruction where the two data items are
aligned and of the same type. When they are not aligned, or when
conversion is necessary, an object-time system routine can be called.
The simplest way to insure that data is aligned is to define it at
ei ther the "77" level or at the "01" level. It is possible by
counting characters or by using the COBOL data map to also determine
alignment.
Alignment simply means that the first byte of each item begins in the
same position in the beginning word, that the items are the same
length, and that they are of the same type.

13.5.2

Use Of Subscripts

Avoid the use of subscripts whenever possible.
Subscripts are
recomputed every time they are used, they are never remembered. If
you use a subscripted item more than once, it is more efficient to
move it into a simple variable and then use that. For example:
01 THE-TABLE OCCURS 200 TIMES
02 THE-COUNT PIC S9(10) COMPo
02 THE-DATA PIC XXXXXXXX.
77 THE-TABLE-COUNT PIC S9(10) COMPo
The sequence:
MOVE THE-COUNT (IDX) TO THE-TABLE-COUNT.
IF THE-TABLE-COUNT
3 GO TO P-l.
IF THE-TABLE-COUNT = 4 GO TO P-2.
is more efficient if it is likely that the count is not
following:
IF THE-COUNT(IDX)
IF THE-COUNT(IDX)

= 3 GO TO P-l.
= 4 GO TO P-l.

13-12

than

the

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
It is usually advantageous to move the whole entry from a table into
some Ol-level structure which contains similar items rather than to
process the data from the table with subscripts. For example:
01 THE-TABLE OCCURS 20 TIMES.
02 THE-CNT PIC S9(10) COMP.
02 THE-DATA PIC XXXXXXX.
01 THE-TABLE-ENTRY.
02 THE-TABLE-CNT PIC S9(10) COMP.
02 THE-TABLE-DATA XXXXXXX.
MOVE THE-TABLE(IDX) TO THE-TABLE-ENTRY.
IF THE-TABLE-CNT = 5 DISPLAY THE-TABLE-DATA.
In this example, only one subscript had to be calculated, and one
unsubscripted move performed. Savings in often-referenced paragraphs
(in a loop) can be quite large..
Simply remember that there is
additional overhead involved in subscripting and it pays to eliminate
it.

13.5.3

Incrementing Counters

COBOL-68 provides three ways of incrementing counters.
the same function in different ways.
For example:

Each

performs

77 COUNTER PIC S9(10) COMP.
This counter can be modified in the following ways:
SET COUNTER UP BY 1.
ADD 1 TO COUNTER.
COMPUTE COUNTER = COUNTER +1.
The first two examples are equivalent, the third is much
therefore, not recommended.

slower

and,

Keep in mind that computational counters should always be signed even
when they logically never become negative.
If they are not signed,
the compiler must generate additional instructions to make sure they
do not become negative.

13.5.4

The PERFORM Statement

The PERFORM statement provides an essential element of structured
programming.
It provides implicit loop control and it makes listings
easy to follow. The power of the statement is not provided without
some cost, however.
Every entrance to a routine requires that some
information be posted, and every exit from a routine requires that
some information be cleared.
Because of the complexity of these
operations, COBOL-68 uses the concept of level.
Each time a PERFORM
statement is encountered, the level counter is incremented by 1. Each
time a performed routine exits, it is decremented by 1.
The level
counter must have the same value at exit time as it has at entry or
else there is an error in the program.
Here are a few known ways to improve the efficiency of
use PERFORMs.
13-13

programs

that

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
Example 13-1
SET IDX TO 0
PARle

PERFORM PARl 100 TIMES.

SET IDX UP BY 1.
IF TABLE(IDX) = ABLE MOVE 6 TO FOO.

Example 13-1 is more efficient than:
PERFORM PAR2 VARYING IDX FROM 2 BY 1
UNTIL IDX > 100.
When a loop or PERFORM is done repeatedly, the loop should do
everything possible on each iteration. This minimizes the expense of
the loop control mechanism. Thus:
PERFORM F-l 1000 TIMES.
PERFORM F-2 1000 TIMES.
should be rewritten so that both functions of F-l and F-2 can be
accomplished by a single PERFORM. This is most meaningful when the
amount of work being accomplished by each paragraph is small.

13.5.5

Use Of The EXAMINE Statement

Use of the EXAMINE statement is preferable to doing the same process
in other ways.
You should understand all the options (including
REPLACING) so that the power of the statement can be applied.
For
information on the EXAMINE statement see Part 2, COBOL Language
Reference Material.

13.5.6

Data Movement

If you are moving data from one record to another and the records
differ in their usages, the object-time system has to convert the data
from one character-set to another. In this case, it is more efficient
to change all fields in a record with one MOVE statement than to move
the data field by field. If, on the other hand, the usages are the
same for the two records, the compiler recognizes that data conversion
is not necessary. If the records are also aligned, then efficient
in-line code can be generated. Due to the method of moving data used
by TOPS-IO and TOPS-20, however, the fixed cost to move any number of
characters is higher than on some systems. You should therefore try
to avoid loops where small numbers of characters are continually being
transferred.
If it is impossible to avoid such situations, then make
sure that the data is aligned.

13-14

IMPROVING PERFORMANCE OF COBOL-68 PROGRAMS
13.5.7

Ordering Statements

All programs should be written so that they avoid executing large
numbers of useless instructions.
Thus classic decision lists like:
IF AB
IF CD
IF EF

" " GO TO FOO.
"I" GO TO FOO-l
"2" GO TO FOO-2.

IF GH = "3" GO TO FOO-3
should be ordered by expected frequency.
The following type of coding
should be avoided if it is in a highly used spot:
IF AB
" " MOVE Z TO DQD.
IF AB = "1" MOVE Z TO FFF.
IF AB
"2" MOVE Z TO GGG.
In this type of code the conditional clauses of all statements get
executed each time,
even though only one actually does anything
useful.

13.5.8

Asking The Correct Question

Some small efficiencies can be gained by asking the correct questions.
Thus the following example is inefficient.
LOOP.

SET X TO 1.
MOVE B(X) TO C(X).
SET X UP BY 1.
IF X > 1000 GO TO ZIP.
GO TO LOOP.

While this is not bad coding, the program only goes to ZIP one time in
a 1000.
Some better code is developed if the statement were
rewritten:
IF X < 1001 GO TO LOOP ELSE GO TO ZIP.
The first option is the one that happens the most often.

13-15

APPENDIX A
COBOL RESERVED WORDS

In the listing below, words not preceded by symbols are reserved in
both ANSI-68 Standard COBOL and in COBOL-68. Words preceded by '*'
are reserved in ANSI-68 Standard COBOL but not reserved in COBOL-68.
Words preceded by
'**' are reserved in COBOL-68 but not reserved in
ANSI-68 Standard COBOL.
Reserved words can not
be
used
as
user-created names.
A

ACCESS

ACTUAL

ADD

*ADDRESS

ADVANCING

AFTER

ALL

ALPHABETIC

ALTER

AND

**ALLOWING
ALTERNATE

**ANY

ARE

AREA

AREAS

ASCENDING

**ASCII

ASSIGN

AUTHOR
B

BEFORE

BEGINNING

BLANK

BLOCK

**CALL

**CANCEL

**CD

**BINARY

**BYTE
C

**CHECK

CHARACTERS

**CHECKPOINT

**CLASS

*CLOCK-UNITS

COBOL

CODE

COLUMN

COMMA

COMP

**COMP-l

**COMMUNICATION

A-I

COBOL RESERVED WORDS
**COMP-3

**COMPILE

COMPUTATIONAL

**COMPUTATIONAL-l

**COMPUTATIONAL-3

COMPUTE

**CONSOLE

CONTAINS

CONFIGURATION
CONTROL

CONTROLS

CORR

CORRSPONDING

CURRENCY

COPY
**COUNT

**CURRENT

D
DATA
**DATE-COMPILED

**DATABASE-KEY

**DATE

DATE-WRITTEN

**DBKEY
DECIMAL-POINT

**DEC

DECLARATIVES

**DECSYSTEM-IO

**DECSYSTEM-20

**DECSYSTEMIO

**DEFERRED

**DELETE

**DELIMITED

**DELIMITER

**DENSITY

DEPENDING

DESCENDING

**DEPTH

**DESTINATION

DETAIL

**DISABLE

DISPLAY

**DISPLAY-6

**DISPLAY-7

**DISPLAY-9

DIVIDE

DIVISION

DOWN

**DUP

**DUPLICATE

E
**EGI

ELSE

**EMI

**EMPTY

**ENABLE

END

ENDING

ENTER

**ENTRY

ENVIRONMENT

EQUAL

**EPI

**EQUALS

ERROR

**ESI

**EVEN

EVERY

**EXCL

**EXCLUSIVE

EXAMINE
EXIT

**EXTEND
F
FD

FILE

FILE-CONTROL

FILE-LIMIT

FILE-LIMITS

**FILE-STATUS

FILLER

FINAL

**FIND
A-2

COBOL RESERVED WORDS
FIRST
**FORTRAN-IV
FREED

FOOTING

FOR

**FORTRAN

**FREE

FROM

G
GENERATE

**GET

GIVING

**GOBACK

GREATER

GROUP
H
HEADING

HIGH-VALUE

HIGH-VALUES

I
1-0

1-0 CONTROL

IDENTIFICATION

INDEX

INDEXED

INDICATE

**INITIAL

INITIATE

INPUT

INPUT-OUTPUT
INTO

**INSERT

**ID

INSTALLATION

INVALID

**INVOKE

IS
J
**JOURNAL

JUST

JUSTIFIED

K
KEY

KEYS

L
LABEL

LAST

LEADING

LEFT

*LENGTH

LESS

LIMIT

LIMITS

LINE

*LINE-COUNTER

LINES

**LINKAGE

LOCK

LOW-VALUE

LOW-VALUES

**MACRO

**MEMBER

**MEMBERS
A-3

COBOL RESERVED WORDS
MEMORY

**MERGE

**MESSAGE

MODE

**MODIFY

MODULES

MULTIPLE

MULTIPLY

NEGATIVE

**NOMINAL

**NONE

NOT

MOVE
N

NOTE

NUMERIC

NUMBER

OBJECT-COMPUTER

OCCURS

OFF

**ONLY

**OPT

**ODD
OMITTED
OPEN

OPTIONAL

OUTPUT

**OVERFLOW

**PARITY

**PDP-IO

PERFORM

PIC

PICTURE

PLUS

**POINTER

POSITION

OTHERS
**OWNER
P
*PAGE-COUNTER

POSITIVE
PROCEDURE
* * PROGRAM

**PRIOR

**POSITIONING
**PRIVACY

PROCEED
PROGRAM-ID

PROCESSING
**PROT

**PROTECTED
Q
**QUEUE

QUOTE

QUOTES

READ

R
RANDOM
**READ-REWRITE
RECORD
REDEFINES

**READ-WRITE

**RECEIVE

**RECORDING

RECORDS

REEL

**RELATIVE
A-4

COBOL RESERVED WORDS
RELEASE
**REMOVE

**REMAINDER

REMARKS

RENAl~ES

REPLACING

REPORT

REPORTING

REPORTS

RERUN

RESERVE

RESET

**RETAIN

**RETAINED

**RETR

**RETRIEVAL

RET RUN

REWIND

**REWRITE

REVERSED

RIGHT

RUN

**RUN-UNIT

RF
ROUNDED

S
SAME

**SCHEMA

SECTION

SEEK

**SEGMENT

SELECT

**SELECTIVE

SENTENCE

**SEQUENCE

SEQUENTIAL

SET

**SETS

SIGN

**SIXBIT

SIZE

SORT

SOURCE

SOURCE-COMPUTER

SPACE

SPACES

SPECIAL-NAMES

STANDARD

STATUS

STOP

**STANDARD-ASCII

SECURITY
SEGMENT-LIMIT
**SEND

**STORE

**STRING

**SUB-QUEUE-l

**SUB-QUEUE-2

**SUB-QUEUE-3

**SUB-SCHEMA

SUBTRACT
**SWITCH

**SUPPRESS

SUM
**SYMBOLIC

SYNC

SYNCHRONIZED
T
**TABLE

TALLY

TALLYING

TAPEL

**TERMINAL

TERMINATE

**TEXT

THAN

THROUGH

THRU

**TIME

TIMES

TODAY

**TRACE

A-5

COBOL RESERVED WORDS
**TRANSACTION

TYPE

U
**UNAVAILABLE

UNIT

**UNSTRING

UNTIL

**UPDATE

**UPDATES

UPON

USAGE

**USAGE-MODE

USE

**USER-NUMBER

USING
V
VALUE
**VERB

VALUES

VARYING

**VIA

W
WHEN

WITH

WORDS

WORKING-STORAGE

WRITE

ZEROES

ZEROS

**WITHIN

Z
ZERO

A-6

APPENDIX B
COLLATING SEQUENCES AND CONVERSION TABLES

Table B-1 shows the ASCII and SIXBIT collating sequence and the
conversions from ASCII to EBCDIC, SIXBIT to ASCII, and SIXBIT to
EBCDIC.
If the ASCII character does not convert to the same character
in EBCDIC,
the EBCDIC character is shown in parentheses next to the
EBCDIC code. Note that the first and last 32 characters do not exist
in SIXBIT.
Also, the characters in the first column (NUL, SOH, STX,
and so forth) are control characters, which are nonprinting.
Table B-1
ASCII and SIXBIT Collating Sequence and Conversion to EBCDIC

Character

ASCII
7-bit

EBCDIC
9-bit

NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR
SO
SI
DLE
DCl
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESC
FS
GS
RS
US

000
001
002
003
004
005
006
007
010
011
012
013
014
015
016
017
020
021
022
023
024
025
026
027
030
031
032
033
034
035
036
037

000
001*
002*
003*
067
055*
056*
057*
026
005
045
013*
014*
025* (NL)
006* (LC)
066* (UC)
044* (BYP)
024*(RES)
064*(PN)
065*(RS)
004*(PF)
075*
027* (IL)
046* (EOB)
052* (CM)
031*
032*(CC)
047*(PRE)
023*(TM)
041*(SOS)
040*(DS)
042*(FS)

Character

SIXBIT

ASCII
7-bit

EBCDIC
9-bit

Space

00
01
02
03
04
05
06
07
10
11
12
13
14
15
16
17
20
21
22
23
24
25
26
27
30
31
32
33
34
35
36
37

040
041
042
043
044
045
046
047
050
051
052
053
054
055
056
057
060
061
062
063
064
065
066
067
070
071
072
073
074
075
076
077

100
132
177
173
133
154
120
175
115
135
134
116
153
140
113
141
360
361
362
363
364
365
366
367
370
371
172
136
114
176
156
157

#
$
%
&
I

(

)

,
-

0
1
2
3
4
5
6
7
8

9
:
;

>
?

B-1

COLLATING SEQUENCES AND CONVERSION TABLES
Table B-1 (Cont.)
ASCII and SIXBIT Collating Sequence and Conversion to EBCDIC

Character

SIXBIT

40
41
42
43
44
45
46
47
50
51
52
53
54
55
56
57
60
61
62
63
64
65
66
67
70
71
72
73
74
75
76
77

A
B
C
D
E
F

G
H

I
J
K

L
M

N
0
p

Q
R
S
T
U
V
W

X
y

[

ASCII
7-bit

EBCDIC
9-bit

100
101
102
103
104
105
106
107
110

174
301
302
303
304
305
306
307
310
311
321
322
323
324
325
326
327
330
331
342
343
344
345
346
347
350
351
255"'1
340
275
137
155

III

112
113
114
115
116
117'
120
121
122
123
124
125
126
127
130
131
132
133
134
135
136
137

Character

a
b
c
d
e
f
g
h
i
j

k
1
m
n
0

P
q
r
s
t
u
v
w
x
Y

{

}

Delete

ASCII
7-bit

EBCDIC
9-bit

140
141
142
143
144
145
146
147
150
151
152
153
154
155
156
157
160
161
162
163
164
165
166
167
170
171
172
173
174
175
176
177

171
201
202
203
204
205
206
207
210
211
221
222
223
224
225
226
227
230
231
242
243
244
245
246
247
250
251
300"'1
117
320
241
007

1. These EBCDIC codes either have no equivalent in the ASCII or
SIXBIT character sets, or are referred to by different names.
They are converted to the indicated ASCII characters to preserve
their uniqueness if the ASCII character is converted back to
EBCDIC.

B-2

COLLATING'SEQUENCES AND CONVERSION TABLES
Table B-2 shows the conversion of ASCII code to SIXBIT code.
The
table does not show ASCII codes 000 through 037 because they all
convert to SIXBIT 74 (\), except 11 (TAB) which converts to SIXBIT 00
(space) •
Table B-2
ASCII to SIXBIT Conversion
ASCII
7-bit

SIXBIT

Character

040
041
042
043
044
045
046
047

00
01
02
03
04
05
06
07

A
B
C
D
E

050
051
052
053
054
055
056
057

10
11
12
13
14
15
16
17

0
1
2
3
4
5
6
7

060
061
062
063
064
065
066
067

20
21
22
23
24
25
26
27

070
071
072
073
074
075
076
077

30
31
32
33
34
35
36
37

Character
Space
!

#
$
%
&
I

(
)

,
-

:
;

ASCII
7-bit

SIXBIT

100
101
102
103
104
105
106
107

40
41
42
43
44
45
46
47

110

III

112
113
114
115
116
117

50
51
52
53
54
55
56
57

120
121
122
123
124
125
126
127

60
61
62
63
64
65
66
67

130
131
132
133
134
135
136
137

70
71
72
73
74
75
76
77

K
L
M
N

0
p
Q

R
S
T
U
V
W

X
y
Z

[

1
-

B-3

COLLATING SEQUENCES AND CONVERSION TABLES
Table B-2 (Cont.)
ASCII to SIXBIT Conversion
ASCII
code

ASCII
character

SIXBIT
code

. 140
141
142
143
144
145
146
147

74
41
42
43
44
45
46
47

150
151
152
153
154
155
156
157
160
161
162
163
164
165
166
167
170
171
172
173
174
175
, 176
177

c
d
e
f
9

50
51
52
53
54
55
56
57

h
i
j
k

1
m

n
0

60
61
62
63
64
65
66
67

P
q

r
s
t
u

v
w

70
71
72
73
74
75
74
74

z
{

I
}

delete

B-4

SIXBIT'
character

A
B
C
0
E

F
G

I
J
K
L
M
N
0
P
Q

R
S
T
U

V
W

Z
[

]

\
\

COLLATING SEQUENCES AND CONVERSION TABLES
Table B-3 shows the EBCDIC collating sequence and the conversion from
EBCDIC to ASCII. When conver9ion is from EBCDIC to SIXBIT, it is as
if the code was converted to ASCII and then from ASCII to SIXBIT.
Table B-3
EBCDIC Collating Sequence and Conversion to ASCII
EBCDIC
code

EBCDIC
character

ASCII
code

ASCII
character

000
001
002
003
004
005
006
007

NUL
SOH
STX
ETX
PF
HT
LC
Delete

000
001
002
003
024
011
016
177

NUL
SOH
STX
ETX
DC4
HT
SO
Delete

050
051
052
053
054
055
056
057

010
011
012
013
014
015
016
017

SMM
VT
FF
CR
SO
SI

134
134
134
013
014
134
134
134

\
\
\

060
061
-62
063
064
065
066
067

020
021
022
023
024
025
026
027

DLE
DC1
DC2
TM
RES
NL
BS
IL

134
134
134
034
021
015
010
026

030
031
032
033
034
035
036
037

CAN
EM
CC
CUI
IFS
IGS
IRS
IUS

134
031
032
134
134
134
134
134

040
041
042
043
044
045
046
047

DS
SOS
FS

036
035
037
134
020
012
027
033

RS
GS
US

BYP
LF
ETB
ESC

VT
FF

\
\
\

EBCDIC
code

070
071
072
073
074
075
076
077

\
\

FS
DC1
CR
BS
SYN

100
101
102
103
104
105
106
107

EM
SUB

\
\

\
\
\

110
III
112
113
114
115
116
117

DLE
LF
ETB
ESC

B-5

EBCDIC
character

ASCII
code

ASCII
character

\
\

ENQ
ACK
BEL

134
134
030
134
134
005
006
007

PN
RS
UC
EaT

134
134
134
134
022
023
017
004

CU3
DC4
NAK
SUB

134
134
134
134
134
025
134
134

\
\
\
\
\

SM
CUZ

Space

CENT

<
(

040
134
134
134
134
134
134
134
134
134
134
056
074
050
053
174

CAN

\
\

ENQ
ACK
BEL

DC2
DC3
SI
EaT

NAK

\
Space

\
\
\
\
\
\

\
\
\

<
(

COLLATING SEQUENCES AND CONVERSION TABLES
Table B-3 (Cont.)
EBCDIC Collating Sequence and Conversion to ASCII
EBCDIC

EBCDIC

ASCII

EBCDIC

ASCII

code

character

code

character

code

character

c::ode

character

046
134
134
134
134
134
134
134

\
\
\
\
\
\
\

170
171
172
173
174
175
176
177

120
121
122
123
124
125
126
127
130
131
132
133
134
135
136
137
140
141
142
143
144
145
146
147
150
151
152
153
154
155
156
157
160
161
162
163
164
165
166
167

,
%

->
?

134
134
041
044
052
051
073
137

1
\

055
057
134
134
134
134
134
134

134
134
134
054
045
137
076
077

\
\
\

134
134
134
134
134
134
134
134

200
201
202
203
204
205
206
207

\
\

210
211
212
213
214
215
216
217

/
\
\
\
\
\
\

220
221
222
223
224
225
226
227

\
\
\
\
\
\
\
\

230
231
232
233
234
235
236
237

B-6

#
@

a
b

c
d
e
f
9

h
i

j
k

1
m

n
0

P
q

134
140
072
043
100
47
075
042

\
\

134
141
142
143
144
145
146
147

150
151
134
134
134
134
134
134

#
@

c
d
e
f
9
h
i

\
\
\
\
\
\

134
152
153
154
155
156
157
160

161
162
134
134
134
134
134
134

j
k

1
m

n
0

\
\
\
\
\
\

COLLATING SEQUENCES AND CONVERSION TABLES
Table B-3 (Cont.)
EBCDIC Collating Sequence and Conversion to ASCII
EBCDIC

EBCDIC

ASCII

EBCDIC

ASCII

code

character

code

character

code

character

code

character

134
176
163
164
165
166
167
170

310
311
312
313
314
315
316
317

110
110
134
134
134
134
134
134

240
241
242
243
244
245
246
247
250
251
252
253
254
255
256
257

t
u
v
w

x
y
z

[

171
172
134
134
134
133
134
134

260
261
262
263
264
265
266
267

175
134
134
134
134
134
134
134

270
271
272
273
274
275
276
277

134
134
134
134
134
135
134
134

300
301
302
303
304
305
306
307
360
361
362
363
364
365
366
367

]

A
B
C
D
E
F

G
0-

1
2
3
4
5
6
7

173
101
102
103
104
105
106
107
060
061
062
063
064
065
066
067

t
u
v
w

320
321
322
323
324
325
326
327

Y
z

\
\

\
[

\
\

330
331
332
333
334
335
336
337

\
\
\

340
341
342
343
344
345
346
347

\
\
\
\
\

]

\
\

J
K
L
1'1
N

0
P

Q
R

S
T
U
V

W
X
y

350
351
352
353
354
355
356
357

1
1
2
3
4
5
6
7

370
371
372
373
374
375
376
377

8
9

A
B
C
D
E
F

B-7

175
112
113
114
115
116
117
120
121
122
134
134
134
134
134
134

\
\
\
\
\
\
J
K
L
M
N

0
P
Q

\
\

134
134
123
124
125
126
127
130

131
132
134
134
134
134
134
134

070
071
134
134
134
134
134
134

S
T
U
V

W
X

\
\
\
\
\
\
8
9

\
\
\
\
\
\

APPENDIX C
DEFINING LOGICAL NAMES UNDER TOPS-20

Most of the file specifications for
the COBOL compiler and the
utilities associated with COBOL~68 use project-programmer numbers to
identify areas on the disk.
Users of TOPS-20 do not normally deal
with project-programmer numbers;
named directories are used instead.
However, the compiler and the utilities often do not accept named
directories in the command strings. There are two ways for TOPS-20
users to specify a directory to be searched. One is to use the TRANSL
command to translate a named directory to a project-programmer number.
This way is perfectly functional, but usually inconvenient. The other
way is to define a logical name and use it in the command string in
place of the device name and the project-programmer number.
The
TRANSL and DEFINE commands are described in the TOPS-20 User's Guide.
Refer to that manual for more information on these two commands.
A
short description of the DEFINE command has been included here for
convenience.
The DEFINE command has the following format:
@DEFINE (LOGICAL NAME) logname:

(AS)

filespecs

where:
logname:

is the logical name being defined.
It consists of up
to
6 alphanumeric characters
(A-Z and 0-9 only)
followed by a colon.

filespecs

is a list of file specifications (separated by commas)
that define the logical name. A file specification can
contain any combination of a structure name, device
name, directory,
file name,
file type, generation
number, and wildcards.
If you wish to remove a logical
name, you should leave the filespecs entry blank.

The following characteristics of the DEFINE command should be noted:
1.

The DEFINE command is used at TOPS-20 monitor level (or in a
batch or command file).
The command does not alter any
program and leaves you at monitor level.

Some programs can expect certain logical names to be defined
certain ways.
You should exercise caution in deciding on a
character string to use as a logical name.
See
the
INFORMATION command in the TOPS-20 User's Guide for a
description of how to determine what logical names are
already defined.

C-l

DEFINING LOGICAL NAMES UNDER TOPS-20
Example:
DEFINE PR:
allows you
compiler:

type

the

following

command

the

COBOL-68

PR:FEDTAX=TESTFT.CBL
This command string takes a file in your connected directory
named TESTFT.CBL and compile it, writing the .REL file in the
directory <PAYROLL>. As written, the command string would also
write the .LST file to your connected directory. If you wish to
have it in the <PAYROLL> directory you must use the following
command:
PR:FEDTAX,PR:FEDTAX=TESTFT.CBL

C-2

APPENDIX D
ALTERNATE NUMERIC TEST

LIBOL as normally assembled includes the ANSI standard NUMERIC test.
However,
an
assembly
switch has been provided to allow the
installation manager to replace this with the ALTERNATE NUMERIC test
at installatiqn time.
The ALTERNATE
conditions:

NUMERIC

test

result

TRUE

under

the

following

For alphanumeric and unsigned numeric items, each character
must be a digit (0 through 9). Leading and tiailing spaces
and leading and trailing tabs are ignored.
No signs are
permitted.

For signed numeric items, the sign can have only one
three following representations:
1.

A leading graphic sign ("+" or "-"),

A trailing graphic sign, or

A trailing embedded sign.

the

Leading and trailing spaces and leading and trailing tabs are
ignored. All other characters must be digits.

D-1

TAPE HANDLING
In this case, you do not want to use a STANDARD-ASCII tape, so you do
not use the SET TAPE FORMAT command. If your COBOL program is running
on a TOPS-IO system, you can use the simplest TOPS-IO MOUNT command:
MOUNT tapnam: •..••
If your program is running on a TOPS-20 system, you must use a logical
name in the MOUNT command to allow you to set the attribute iFORMAT
(with the DEFINE command). You must set this attribute to avoid
confusion with the case where you wish to write an ASCII U-format
tape. On TOPS-20, you can write both F-format and D-format tapes, so
you can use either iFORMAT:F or iFORMAT:D with the DEFINE command. It
is also a good idea to declare the record and block size in the DEFINE
command.
The format is shown below (here x stands for one of the
letters F and D, and nn and mm for a decimal number of bytes).
MOUNT TAPE tapnam: ....•
DEFINE taplnm: tapnam: iFORMAT:x ;RECORD:nn iBLOCK:mm

E.4.1.2 Undefined-Format Tapes - U-Format - Undefined-format
tapes
include all tapes written in EBCDIC, SIXBIT, and binary recording
modes, as well as tapes written in other recording modes if the label
type
is
set
to
U.
U-format tapes cannot be written with
STANDARD-ASCII or ASCII recording modes on TOPS-IO.
EBCDIC for TOPS-IO
If you want to use EBCDIC recording mode on an ANSI-labeled tape,
simply declare in your COBOL program-that:

you

RECORDING MODE IS EBCDIC
Then you mount the tape using the simple form of the MOUNT command:
MOUNT TAPE tapnam
The tape-labeling software recognizes the recording mode
that it must write a U-format tape.

and

realize

EBCDIC and ASCII for TOPS-20
If you wish to use EBCDIC or ASCII recording modes on a U-format tape,
you should include in your COBOL program an explicit declaration of
the recording mode you want to use.
You should also include a
statement of the form:
SELECT filnam ASSIGN TO taplnm
When you mount the tape, use some name that is different from
thus:

taplnm,

MOUNT TAPE tapnam
Finally, use the DEFINE command to set the label type:
DEFINE taplnm: tapnam: iFORMAT:U
Another way for users of TOPS-20 to handle ASCII data on an
undefined-format tape is to use the SET TAPE FORMAT monitor command.
E-IO

APPENDIX E
TAPE HANDLING

E.l

DIRECTIONS AND DEFINITIONS

This appendix describes in detail the methods you use to handle tapes
with COBOL programs.
The appendix does not describe the use of the
MOUNT command;
for this information, see the TOPS-IO Operating System
Commands Manual or the TOPS-20 Commands Reference Manual. This
appendix also does not describe the piocedures used by the operating
system in handling tapes and tape drives.
For more information on
this subject, consult the TOPS-IO or TOPS-20 Tape Processing Manual.

E.l.l

Definitions

Several terms used in this appendix require explicit definition.
COBOL Labels
Labels written by a COBOL program that includes the LABEL
(see
RECORDS
clause.
COBOL labels and system labels
definition below) are mutually exclusive.
You cannot write
COBOL labels onto a system-labeled tape;
nor can you write
system labels onto a tape that has COBOL labels,
since you
must initialize a tape to write a system label on it.
Label Type
A field in the system label that defines the structure 9 f
records on the tape.
There are four
label types:
F,
meaning fixed-length records, D, indicating variable-length
records, U,
signifying that an undefined format has been
used to write the records, and S, meaning spanned records.
Object-Time System
The object-time system consists of LIBOL.REL and LIB012.EXE.
System Labels
These are labels written by the TOPS-IO or TOPS-20 operating
system.
Labels are written on a tape by the aPR program
when it initializes the tape.
You must therefore ask the
operator to initialize your tape if you do not have the
privileges required to run OPR.
COBOL labels and system
labels are mutually exclusive.

E-l

TAPE HANDLING
Volume
A single magnetic tape;

a reel.

Volume Number
A number signifying the position of the reel in
set.

the

volume

single

Volume Set
A group of magnetic tapes that
unit.

E.l.2

are

accessed

Finding The Right Instructions

This appendix presents a number of specific methods of labeled-tape
handling that are recommended ways to use the tape-handling software.
Many situations can be devised that do not fit exactly into one of the
cases listed here. If you attempt to use the tape-labeling software
in one of these ways, the results are not predictable. Therefore, you
are advised to set up a system of handling tapes at your site that is
consistent with the methods discussed in this appendix.
The flowchart below helps to guide you to the section
the type of tape handling you are doing.

E-2

that

describes

TAPE HANDLING

Yes

See
Section
E.3.1.1

See
Section
E.3.1.2

See
Section
E.3.2

See
Section
E.4.2

Yes

See
Section
E.4.1.1

See
Section
E.4.1.2

(1) See definition of system labels in Section E.1.2.
(2) A tape drive is either assigned by the system tape-handling software or assigned by you.
(3) Tapes with F-format, S-format, and D-format ANSI labels are transportable to other systems,
and must be written in either ASCII or STANDARD-ASCII recording mode.
MR-S-1377-B1

E-3

TAPE HANDLING
E.l.3

Symbols Used In The Text

The sample ASSIGN clauses and MOUNT commands that follow contain text
strings that represent user-supplied information.
The strings, and
the information they represent, are shown belqw.
String

Represents

Where used

tapnam

Name of tape

ASSIGN clause, MOUNT command

taplnm

Logical name

ASSIGN clause, MOUNT command

filnam

Name of file

ASSIGN clause

xxx

Any legal switch

MOUNT command

idN
Volume 10
(N=O,1,2, ••• )

E.2

MOUNT command

FACTORS TO CONSIDER WHEN USING TAPES

Several new situations have been introduced into the COBOL environment
by the addition of software to TOPS-IO and TOPS-20 for handling
labeled tapes. This section presents some factors you should consider
when deciding what type of tape labeling to use.

E.2.1

General Defaults And Restrictions

The following defaults and restrictions apply to tape handling on both
TOPS-IO and TOPS-20.
1.

If you are using system labels, no COBOL labels are read or
written on your tape.
The object-time system can tell
whether the system tape-handling software found labels on
your tape;
if system labels were found, the object-time
system does not write or read COBOL labels.

All STANDARD-ASCII tapes (explicit or default)
are written
without carriage return/line feed pairs unless you introduce
the carriage return/line feeds by using the ADVANCING clause.

COBOL-68 USE procedures for END-OF-REEL no longer work if you
use system labeled tapes. This is because the EaT (End Of
Tape) condition is never seen by the COBOL object-time
system;
the system tape-handling software intervenes when
EaT is reached and requests the ne~t tape from the operator.
The only time a USE procedure far END-OF-REEL is executed is
when the program contains a CLOSE REEL statement. When this
statement is executed, the USE procedure is performed.

E-4

TAPE HANDLING
4.

If you have multiple devi~es in the ASSIGN statement in your
COBOL program,
your system labeled tapes use only the first
device in the list.
The only exception to this is when you
use
the CLOSE REEL syntax to end one tape and start another.
This syntax causes the system tape-handling software to see
one volume set being closed,
rather than one reel.
This
allows COBOL to switch to the next device
in the ASSIGN
statement while the system tape-handling software switches to
the next volume set, as specified in the next MOUNT command
you gave.

You cannot write an unblocked tape with an F-format or
D-format label • . If your COBOL program declares the blocking
factor to be zero, or if you omit the BLOCK CONTAINS clause,
the object-time system acts as
if you had declared BLOCK
CONTAINS 1 RECORD.

The COBOL compiler and object-time system do not always
enforce the description of your file glven in the FD when you
are writing tapes.
In
particular,
you
could
write
variable-length records to an F-format ANSI-labeled tape
without receiving any errors.
The data on the tape would be
padded with nulls to the specified maximum record size.

E.2.2

Defaults And Restrictions Specific To TOPS-20 Systems

The following defaults and restrictions
TOPS-20 only.

apply

tape

handling

The default recording mode for TOPS-20 systems is determined
by a fairly simple algorithm.
If you use the RECORDING MODE
IS STANDARD-ASCII clause in your program, and you set no tape
attributes
(using
the DEFINE command),
your tape becomes
D-format.
If your RECORDING MODE IS ASCII, and you give the
SET TAPE FORMAT ANSI-ASCII command at monitor level, your
tape again becomes D-format.
You can also get aD-format
tape by omitting the RECORDING MODE clause from your program
and giving the SET TAPE FORMAT ANSI-ASCII command.
In all
other default cases, TOPS-20 writes a U-format tape.
TOPS-20
never defaults to F-format.
(This does not mean that you
cannot write an F-format tape if you specify that you wish to
do so.)

Users of TOPS-20 who wish to write compatible tapes should
set record and block length attributes (using the DEFINE
command - see examples below)
to make explicit the exact
sizes of the record and block.
Setting attributes
is
advisable because the tape-handling software allows several
attributes to default to values that can conflict with the
declarations in your program. When you are determining
the
size of any record, you must count all the characters in the
record, including explicit and implicit advancing characters
and header characters (see the TOPS-20 Tape Processing Manual
for more information on the format of record headers).

The TOPS-20 user-set attributes (set with the DEFINE command)
are
the
overriding
factor
in determining
the label
information when you are writing a labeled tape.
When you
are reading a
labeled tape,
the overriding factor is the
information written in the tape's label.
E-5

TAPE HANDLING
4.

You can write STANDARD-ASCII tapes
(both
labeled
and
unlabeled)
by
declaring
the
recording
mode
to be
STANDARD-ASCII, as you would expect.
You can also write
STANDARD-ASCII tapes by using the SET TAPE FORMAT ANSI-ASCII
command at monitor level and ~eclaring the recording mode to
be ASCII or allowing the reco¢ding mode to default to SIXBIT.

TOPS-20 cannot write EBCDIC labels, but it can read them.

E.2.3

Defaults And Restrictions Specific To TOPS-IO Systems

The following defaults and restrictions
TOPS-IO only.

E.2.4

apply

tape

handling

TOPS-IO

COBOL

object-time

Both the TOPS-IO monitor and the
system use F-format by default.

TOPS-IO can both read and write EBCDIC labels.

The COBOL object-time system running under TOPS-IO
read or write S-format or D-format labeled tapes.

TOPS-IO cannot write a U-format tape in STANDARD-ASCII or
ASCII recording modes.
The object-time system causes all
such tapes to be written with F-format labels.

cannot

Converting Tapes Between Labeled And Unlabeled

System-labeled tapes can only be created with the OPR program (both
TOPS-IO and TOPS-20).
Since OPR writes a system label on a tape by
initializing the tape, you cannot convert an unlabeled tape to a
system-labeled one simply by writing a system label on it. The
simplest way to create a system-labeled tape with the same data as a
given unlabeled tape is to write a short COBOL program to copy the
data.
This COBOL program should read every record on the unlabeled
tape and copy it to a tape that has been initialized and mounted as a
system-labeled tape.
If there are several files on a tape, the COBOL
program must deal with end-of-file conditions. Once all the data on
the unlabeled tape has been copied, the system-labeled version of the
tape has been created;
no further steps are necessary.
You can
create an unlabeled version of a system-labeled tape by reversing this
process.

E.3

USING SYSTEM-UNLABELED TAPES

This section describes the use of tapes that the system considers to
be unlabeled. This includes tapes that actually have system labels if
you have told the system tape-handling :software that labels are to be
bypassed.
The section is divided intd procedures for tapes that have
no system labels and procedures for tapes whose labels are bypassed.

E-6

TAPE HANDLING
E.3.l

Tape Has No Labels

If you wish to use tapes that actually have no system labels, as
opposed to tapes whose system labels are bypassed, the method you
should use depends on whether the tape drive can be assigned by you.

E.3.l.l Tape Drive Is Available To The User - If you wish to use a
tape that actually has no system labels (as opposed to bypassing
labels that are on the tape), and the tape drive is available for you
to assign, you can assign it and proceed with your processing exactly
as you have always done. The introduction of system label processing
does not interfere with this style of tape usage.

E.3.l.2 Tape Drive Is Owned By The System - This
section
contains
instructions for using unlabeled tapes on tape drives assigned by the
system tape-handling software.
The instructions are in two parts:
one part for single-reel volume sets, and one part for multiple-reel
volume sets.
SINGLE-REEL VOLUME SET
To use a single tape, put the
program:

following

statement

into

your

COBOL

SELECT filnam ASSIGN TO tapnam
At run time, use the following command to mount the tape:
MOUNT TAPE tapnam: /LABEL-TYPE:UNLABELED /xxx
MULTIPLE-REEL VOLUME SET
There are three methods you can use to deal with multiple-reel volume
sets.
The most convenient way to use the multiple tapes is to put the
following statement into your COBOL program:
SELECT filnam ASSIGN TO tapnam
This allows you to mount the tapes at
command:

run

time

with

the

following

MOUNT TAPE tapnam /LABEL-TYPE:UNLABELED /VOLIDS:fdl, ... ,idN /xxx
where N is the number of tapes in the volume set,
and
idN is the
volume
ID of the tape that corresponds to tapnamN (the name of tape
N) •

It is also possible to deal with a multiple-volume set by mounting the
first volume and notifying the operator of the names and volume
numbers of the remaining tapes.
The tape-labeling software recognizes
the end of a volume and requests the operator to mount the next tape
in the volume set. The MOUNT command is of the form:
MOUNT TAPE tapnam /LABEL-TYPE:UNLABELED /xxx
Finally, you can use in your COBOL program an ASSIGN statement of
form:

E-7

the

TAEE HANDLING
SELECT filnam ASSIGN TO tapnaml, ... ,tapnamN
where N is the number of tapes in the volume set.
If you use this
form of the ASSIGN clause, you must use N MOUNT commands (which
requires you to have N tape drives).
Each MOUNT command is of the
simplest form:
MOUNT TAPE tapnaml /LABEL-TYPE:UNLABELED /xxx

MOUNT TAPE tapnamN /LABEL-TYPE:UNLABELED /xxx

E.3.2

Tape Has Labels

If you wish to bypass the system labels on a tape and use the tape as
if it had no labels, you can use the instructions above for unlabeled
tapes. However, you should note the following exceptions:
1.

You must have privileges to bypass the labels on a tape.

You must tell the system to bypass the system labels
tape. The MOUNT command for doing this is:

the

MOUNT TAPE tapnam /LABEL-TYPE:BYPASS /xxx

E.4

If you want to look at the system label in your
program, simply read it as the first file on the tape.

If you want to skip the system label,
SKIP 1 commands at monitor level.

give

the

REWIND

COBOL
and

USING SYSTEM-LABELED TAPES

This section describes the use of tapes that the system considers to
be labeled. This does not include tapes whose system labels are being
bypassed.
(For information on using this kind of tape,
see Section
E.3.2 above.)
There are two types of system labels: ANSI labels and
EBCDIC labels.

E.4.1

Tape Has ANSI Labels

Methods for using ANSI-labeled tapes can be separated into those used
with transportable tapes and those used with undefined-format tapes.
The first section that follows deals with transportable tapes, which
have F-format, D-format, or S-format labels and must be written in
STANDARD-ASCII or ASCII recording modes. The next section presents
information on using U-format tapes. U-format tapes include all those
recorded in EBCDIC, SIXBIT, and binary, and it is possible to write
U-format tapes in ASCII and STANDARD-ASCII as well.

E-8

TAPE HANDLING
E.4.1.1 Transportable Tapes - F, D, And S Formats
- You can write
transportable tapes in two styles of ASCII.
One kind, STANDARD-ASCII,
does not contain any carriage ~eturn/line feed pairs unless your COBOL
program explicitly introduces them (using the ADVANCING clause).
The
other kind, ASCII, does include carriage return/line feed pairs
in
each
record unless they are specifically excluded (using, once again,
the ADVANCING clause).
This sec~ion presents two methods for
writing
STANDARD-ASCII transportable tapes that do not have implicit carriage
return/line feed pairs, and another for
writing ASCII
transportable
tapes that do have implicit carriage return/line feed pairs.
STANDARD-ASCII
There are two ways to write a
tape in STANDARD-ASCII.
The first
method requires your COBOL program to include the following statement:
RECORDING MODE IS STANDARD-ASCII
This allows the MOUNT command to be in its simplest form:
MOUNT TAPE tapnam
The second method, usable only on TOPS-20, requires your COBOL'program
to include the following statement:
RECORDING MODE IS ASCII
However, the data on the tape is (or can be, depending on whether you
are
reading or writing
the tape)
recorded as
if you had said
STANDARD-ASCII. Therefore, you must tell the object-time system to
read (or write) a STANDARD-ASCII tape.
To do this, type the following
command at monitor level before you run your COBOL program:
SET TAPE FORMAT ANSI-ASCII
This command must be given at monitor level, but it does not matter
whether you type it before or after you mount the tape with the MOUNT
command.
The MOUNT command you should use is the simplest form:
MOUNT TAPE tapnam
You can produce the same kind of tape by omitting the RECORDING MODE
clause from your COBOL program altogether, assuming that you have not
changed the default recording mode (with the /X compiler switch or the
DISPLAY IS clause).
In this case, your recording mode defaults to
STANDARD-ASCII, despite the fact that the usual default recording mode
is SIXBIT.
If you omit the clause, you must set the default tape
format as shown in the previous case, and you can use the simple MOUNT
command format shown for the previous case as well.
ASCII
If you wish to write a transportable tape and you also want carriage
return/line feed pairs
in each record,
you can use regular ASCII
recording mode.
To do this, you must include in your COBOL program a
statement of the following type:
SELECT filnam ASSIGN TO taplnm
This must be followed by the statement:
RECORDING MODE IS ASCII
E-9

TAPE HANDLING
You can avoid the use of the logical name by giving the command:
SET TAPE FORMAT CORE-DUMP
This command, along with the declaration of ASCII
recording mode in
your COBOL program, allows you to read or write an ASCII U-format tape
with carriage return/line feed pairs included.
You could also
read/write an ASCII U-format tape, omitting carriage return/line
feeds, by including in your COBOL program the statement:
RECORDING MODE IS STANDARD-ASCII
Omitting the RECORDING MODE clause
same effect.

fr~m

the

program

would

have

the

SIXBIT and Binary
If you want to deal with SIXBIT or binary data on a labeled tape, you
must declare the recording mode in your COBOL program.
You cannot
allow the recording mode to default to SIXBIT;
if you did, you would
get STANDARD-ASCII data on your tape (assuming the default hardware
data mode to be ANSI-ASCII;
see the section on EBCDIC and ASCII tapes
above) .
You must also make sure that the default tape format is not
INDUSTRY-COMPATIBLE or ANSI-ASCII, so that you are sure to get a
U-format tape (INDUSTRY-COMPATIBLE and ANSI-ASCII formats indicate an
F-format or D-format tape).
Users of TOPS-20 can make sure of this by
giving the moni tor command- show'n below:
SET TAPE FORMAT CORE-DUMP
Users of TOPS-IO cannot use this command;
the default tape format
is
set for
the site and cannot be changed by individual users.
If you
have trouble handling SIXBIT or binary tapes, check with your system
administrator
to make sure the default tape format is not set to
INDUSTRY-COMPATIBLE or ANSI-ASCII.

E.4.2

Tape Has EBCDIC Labels

If your tape has EBCDIC labels, you can read it on both TOPS-IO and
TOPS-20 by using the simple forms of the ASSIGN clause and the MOUNT
command:
SELECT filnam ASSIGN TO tapnam
MOUNT TAPE tapnam /LABEL-TYPE:EBCDIC /xxx
You can write EBCDIC-labeled tapes on TOPS-IO using the same ASSIGN
clause and MOUNT command.
However, TOPS-20 systems cannot write to
EBCDIC labeled tapes.
The COBOL object-time system running under TOPS-IO writes F-format
tapes if you declare the recording mode to be F in your COBOL program;
the same software writes D-format tapes if you declare the recording
mode to be V.
If the recording mode is something other than EBCDIC F
or V, the TOPS-IO COBOL object-time system writes a U-format tape.

E-II.

TAPE HANDLING
TOPS-lO does not read S-format tapes (S-format tapes contain spanned
records) •
F-format, D-format, and U-format tapes can be read on a
TOPS-lO system.
To read F-format tapes, you must declare the
recording mode to be F in your COBOL program. To read D-format tapes,
you must declare the recording mode to be V in your COBOL program. If
you wish to read a U-format tape, you can read the data in any fashion
you wish; no checking is done on the recording mode.
TOPS-20, as mentioned above, does not write EBCDIC-labeled tapes.
However, you can read EBCDIC-labeled tapes on TOPS-20. The TOPS-20
monitor processes the data coming from the tape; it knows how big a
logical record is, and it hands the COBOL program one logical record.
If you are expecting to receive the data in the format in which it was
actually recorded, you get the right data when you read a record. If,
however, your idea of the data format of the tape is not accurate,
your results are unpredictable.

E-l2

GLOSSARY

The terms in this glossary are defined in accordance with COBOL as
used in this document. Therefore, these terms may not have the same
meanings in other languages.
These definitions are also intended to serve either as reference
material or as introductory material to be reviewed before reading the
detailed language specifications. For this reason, these definitions
are, in most instances, brief and do not include detailed syntactical
rules.
Abbreviated Combined Relation Condition
The combined condition that results from the explicit omission of
a common subject, or a common subject and common relational
operator, in a consecutive sequence of relation conditions.
Access Mode
The manner in which records are to
file.

operated

upon

within

Actual Decimal Point
The physical representation {decimal point characters period
or comma (,)) of the decimal point position in a data item.

(.)

Actual Key
A key whose contents identify a logical record in a random file.
Alphabetic Character
A character that belongs to the following

set

letters:

B, C, D, E, F, G, H, I, J, K, L, M, N, 0, P, Q, R, S, T, U,

V, W, X, Y, Z, and Space.
Alphanumeric Character
Any character in the computer's character set.
Arithmetic Expression
An arithmetic expression can be an identifier or a numeric
elementary item, a numeric literal, such identifiers and literals
separated by arithmetic operators, two arithmetic expressions
separated by an arithmetic operator, or an arithmetic expression
enclosed in parentheses.

Glossary-l

Arithmetic Operator
A single character, or a fixed
belongs to the following set:

2-character

Character

Meaning

addition
subtraction
multiplication
division
exponentiation

*
**

combination

that

Ascending Key
A key upon the values of which data is ordered starting with the
lowest value of key up to the highest value of key in accordance
with the rules for comparing data~items.
Assumed Decimal Point
A decimal point position that does not involve the existence of
an actual character in a data item. The assumed decimal point
has logical meaning but no physical representation.
At End Condition
A condition caused:
1.

During the execution of a READ statement for
accessed file.

sequentially

During the execution of a RETURN statement, when no next
logical record exists for the associated sort or merge file.

During the execution of a SEARCH statement, when the search
operation
terminates
without
satisfying the condition
specified in any of the associated WHEN phrases.

Block
A physical unit of data that is normally composed of one or more
logical records.
For mass storage files, a block can contain a
portion of a logical record. The size of a block has no direct
relationship to the size of the file within which the block is
contained, or to the size of the logical record(s) that are
either continued within the block or that overlap the block. The
term is synonymous with physical record.
Body Group
Generic name for a report group of TYPE DETAIL, CONTROL
or CONTROL FOOTING.

HEADING,

Called Program
A program that is the object of a CALL statement combined
object time with the calling program to produce a run unit.
Calling Program
A program that executes a CALL to another program.

Glossary-2

Cd-Name
A user-defined word that names an MCS interface area described in
a
communication descrip~ion entry within the Communication
section of the Data Division.
Character
The basic indivisible unit of the language.
Character position
A character position is the amount of physical storage required
to store a single standard data format character described as
usage is DISPLAY.
Further characteristics of the physical
storage are defined by the implementor.
Character-String
A sequence of contiguous characters that form a COBOL word,
literal, a PICTURE character-string, or a comment-entry.

Class Condition
The proposition, for which a truth value can be determined, that
the content of an item is wholly alphabetic or is wholly numeric.
Clause
A clause is an ordered set of consecutive COBOL character-strings
whose purpose is to specify an attribute of an entry.
COBOL lCharacter Set
The complete COBOL character set consists of
listed below:

the

Character

Meaning

0,1, ••. ,9

digit
letter
space (blank)
plus sign
minus sign (hyphen)
asterisk
stroke (virgule, slash)
equal sign
currency sign
comma (decimal point)
semicolon
period (decimal point)
quotation mark
left parenthesis
right parenthesis
greater than symbol
less than symbol

A,B, •.. ,Z
+

(
)

>
<

characters

COBOL Word
(See Word.)
Collating Sequence
The sequence in which the characters that
computer are ordered for purposes of
comparing.

Glossary-3

are acceptable in a
sorting, merging, and

Column
A character position within a print line.
numbered from 1, by 1, starting at the
position of the print line and extending
position of the print line.

The columns are
leftmost character
to the rightmost

Combined Condition
A condition that is the result of connecting two
conditions with the 'AND' or the 'OR' logical operator.

An entry in the Identification Division that can be
combination of characters from the computer character set.

any

Comment-Entry

Comment Line
A source program line represented by an asterisk in the indicator
area of the line and any characters from the computer's character
set in area A and area B of that line. The comment line serves
only \s documentation in a program. A special form of comment
line represented by a stroke (/) in the indicator area of the
line, and any characters from the computer's character set in
area A and area B of that line, causes page ejection prior to
printing the comment.
Communication Description Entry
An entry in the Communication Section of the Data Division that
is composed of the level indicator CD, followed by a cd-name, and
then followed by a set of clauses as required. It describes the
interface between the Message Control System (MCS) and the COBOL
program.
Communication Device
A mechanism (hardware or hardware/software) capable of sending
data to a queue and/or recelvlng data from a queue. This
mechanism can be a computer or a peripheral device. One or more
programs
containing
communication
description entries and
residing within the same computer define one or more of these
mechanisms.
Communication Section
The section of the Data Division that describes the interface
areas between the MCS and the program. This section is composed
of one or more CD description entries.
Compile Time
The time at which a COBOL source program is translated by a COBOL
compiler to a COBOL object program.
Compiler Directing Statement
A statement beginning with a compiler-directing verb that causes
the compiler to take a specific action during compilation.
Complex Condition
A condition in which one or more logical operators act upon one
or more conditions.
(See Negated Simple Condition, Combined
Condition, Negated Combined Condition.)

Glossary-4

Computer-Name
A system-name that identifies the computer upon which the program
is to be compiled or run.
Condition
A status of a program at execution time for which a truth value
can be determined.
Where the term 'condition' (condition-I,
condition-2, •.• ) appears in these language specifications in or
in reference to 'condition' (condition-I, condition-2, .•. ) of a
general format, it is a conditional expression consisting of
either a simple condition optionally parenthesized, or a combined
condition consisting of the syntactically correct combination of
simple conditions, logical operators, and parentheses, for which
a truth value can be determined.
Condition-Name
A user-defined word assigned to a specific value, set of values,
or range of values, within the complete set of values that a
conditional variable can possess;
or the user-defined word
assigned to a status of an implementor-defined switch or device.
Condition-Name Condition
The proposition, for which a truth value can be determined, that
the value of a conditional variable is a member of the set of
values att~ibuted to a condition-name associated with
the
conditional variable.
Conditional Expression
A simple condition or a complex condition specified in an IF,
PERFORM, or SEARCH statement.
(See Simple Condition and Complex
Condition.)
Conditional Statement
A conditional statement specifies that the truth value of a
condition is to be determined, and that the subsequent action of
the object program is dependent on this truth value.
Conditional Variable
A data item of which one or
assigned to it.

values

has

condition-name

Configuration Section
A section of the Environment Division that describes
specifications of source and object computers.

overall

Connective
A reserved word that is used to:
1.

Associate a data-name, paragr~ph-name,
text-name with its qualifier.

Link two or more operands written in a series.

Form conditions
Operator.)

(logical

condition-name,

connectives) •

Glossary-5

(See

Logical

Contiguous Items
Items that are described by consecutive entries in the Data
Division, and ,that bear a definite hierarchical relationship to
each other.
Control Break
A change in the value of a data item that is referenced in the
CONTROL clause. More generally, a change in the value of a data
item that is used to control the hierarchical structure of a
report.
Control Break Level
The relative position within a control
most major control break occurred.

hierarchy

which

the

Control Data Item
A data item, in whose contents a change
break.

can

produce

control

clause

and

refers

Control Data-Name
A data-name that appears in a CONTROL
control data item.

Control Footing
A report group that is presented at the end of the control
of which it is a member.

group

Control Group
A set of body groups that is presented for a given value of a
control data item or of FINAL. Each control group can begin with
a CONTROL HEADING, end with a CONTROL FOOTING, and contain DETAIL
report groups.
Control Heading
A report group that is presented at the beginning of the
group of which it is a member.

control

Control Hierarchy
A designated sequence
positional order of
clause.

of report subdivisions defined by the
FINAL and the data-names within a CONTROL

Counter
A data item used for storing numbers or number representations in
a manner that permits these numbers to be increased or decreased
by the value of another number, or to be changed or reset to zero
or to an arbitrary positive or negative value.
Currency Sign
The character '$' of the COBOL character set.

Glossary-6

Currency Symbol
The character defined by- the CURRENCY SIGN clause in the
SPECIAL-NAMES paragraph.
If no CURRENCY SIGN clause is present
in a COBOL source program, the currency symbol is identical to
the currency sign.
Current Record
The record that is available in the record area
the file.

associated

with

Current Record Pointer
A conceptual entity that is used in the
record.

selection

the

Data Clause
A clause that appears in a data description entry in the Data
Division and that provides information describing a particular
attribute of a data item.
Data Description Entry
An entry in the Data Division that is composed of a level-number
followed by a data-name, if required, and then followed by a set
of data clauses, as required.
Data Item
A character or a set of
either case, literals)
program.

contiguous characters (excluding, in
defined as a unit of data by the COBOL

Data-Name
A user-defined word that names a data item described in a data
description entry in the Data Division. When used in the general
formats,
'data-name' represents
a
word
that
cannot
be
subscripted, indexed, or qualified unless specifically permitted
by the rules for that format.
Declaratives
A set of one or more special-purpose sections, written at the
beginning of the Procedure Division, the first of which is
preceded by the key word DECLARATIVES, and the last of which is
followed by the key words END DECLARATIVES. A declarative is
composed
of
a
section
header,
followed
by
a
USE
compiler-directing sentence, followed by a set of zero, one, or
more associated paragraphs.
Declarative-Sentence
A compiler-directing sentence consisting of
statement terminated by the separator period.

single

USE

Delimiter
A character or a sequence of contiguous characters that identify
the end of a string of characters and separate that string of
characters from the following string of characters. A delimiter
is not part of the string of characters that it delimits.

Glossary-7

Descending Key
A key upon the values of which data is ordered starting with the
highest value of key. down to the lowest value of key, in
accordance with the rules for comparing data items.
Destination
The symbolic identification of the
from a queue.

receiver

transmission

Digit position
A digit position is the amount of physical storage required to
store a single digit.
This amount can vary depending on the
usage of the data item describing the digit position.
Further
characteristics of the physical storage are defined by the
implementor.
Division
A set of zero, one, or more sections of paragraphs, called the
division body, that are formed and combined in accordance with a
specific set of rules. There are four divisions in a COBOL
program: Identification, Environment, Data, and Procedure.
Division Header
A combination of words followed by a period and a space that
indicates that beginning of a division. 'The division headers
are:
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
DATA DIVISION.
PROCEDURE DIVISION [USING data-name-l [data-name-2] •.•

] •

Edi ting Char,acter
A single character or a fixed 2-character
to the following set:

combination

Character

Meaning

space
zero
plus
minus
credit
debit
zero suppress
check protect
currency sign
comma (decimal point)
period (decimal point)

CR
DB
Z

belonging

Elementary Item
A data item that is described
subdivided.

not

being

further

logically

End of Procedure Division
The physical position in a COBOL source program
further procedures appear.

Glossary-8

after

which

Entry
Any descriptive set of con~edutiye clauses terminated by a period
and written in the Identification Division, Environment Division,
or Data Division of a COBOL source program.
Environment Clause
A clause that appears as part of an Environment Division entry.
Execution Time
(See Object Time.)
Extend Mode
The state of a file after execution of an OPEN statement with the
EXTEND phrase specified for that file, and before the execution
of a CLOSE statement for that file.
Figurative Constant
A compiler-generated value referenced through the use of
reserved words.

certain

File
A collection of records.
File Clause
A clause that appears as
Division entries:

part

any

the .following

Data

File description (FD)
Sort-merge file description (SD)
Communication description (CD)
FILE-CONTROL
The name of an Environment Division paragraph in which
files for a given source program are declared.

the

data

File Description Entry
An entry in the File Section of the Data Division that is
composed of the level indicator FD, followed by a file-name, and
then followed by a set of file clauses as required.
File-Name
A user-defined word that names a file described in a file
description entry or a sort-merge file description entry within
the File Section of the Data Division.
File Organization
The permanent logical file structure established at the time that
a file is created.
File Section
The section of the Data Division that contains file description
entries and sort-merge file description entries together with
their associated record descriptions.

Glossary-9

Format
A specific arrangement of a set of data.
Group Item
A named contiguous set of elementary or group items.
High Order End
The leftmost character of a string of characters.
I-O-CONTROL
The name of an Environment Division paragraph in which object
program requirements for specific input-output techniques, rerun
points, sharing of same areas by several data files, and multiple
file storage on a single input-output device are specified.
1-0 Mode
The state of a file after execution of an OPEN statement, with
the input-output phrase specified, for that file and before the
execution of a CLOSE statement for that file.
Identifier
A data-name followed as required by the syntactically correct
combination of qualifiers, subscripts, and indexes necessary to
make unique reference to a data item.
Imperative Statement
A statement that begins with an imperative verb and specifies an
unconditional action to be taken. An imperative statement can
consist of a sequence of imperative statements.
Implementor-Name
A system-name that refers to a particular
that implementor's computing system.

feature

available

Index
A computer storage position or register, the contents of which
represent the identification of a particular element in a table.
Index Data Item
A data item in which the value associated with an index-name
be stored in a form specified by the implementor.

can

Index-Name
A user-defined word
specific table.

that

names

index

associated

with

An identifier that is composed of a data-name followed by one
more index-names enclosed in parentheses.

Indexed Data-Name

Indexed File
A file with indexed organization.

Glossary-IO

Indexed Organization
The permanent logical file structure in which each record is
identified by the value of one or more keys within that record.
Input File
A file that is opened in the input mode.
Input Mode
The state of a file after execution of an OPEN statement with the
INPUT phrase specified for that file, and before the execution of
a CLOSE statement for that file.
Input-Output File
A file that is opened in the input-output mode.

Input-Output Section
The section of the Environment Division that names the files and
the external media required by an object program, and that
provides information required for transmission and handling of
data during execution of the object program.
Input Procedure
A set of statements that is
released to the sort file.

executed

each

time

record

Integer
A nonnegative numeric literal or a numeric data item that does
not include any character positions to the right of the assumed
decimal point. Where the term 'integer' appears in general
formats, integer must not be a numeric data item, and must not be
signed or zero, unless explicitly allowed by the rules of that
format.

Invalid Key Condition
A condition at object time caused when a specific value of the
key associated with an indexed or relative file is determined to
be invalid.

Key
A data item that identifies the location of a record, or a set of

data items that serve to identify the ordering of data.
Key Word
A reserved word whose presence is required when the
which the word appears is used in a source program.

format

Language-Name
A

system-name that specifies a particular programming language.

Level Indicator
Two alphabetic characters that identify a specific type
or a position in hierarchy.

Glossary-II

file

Level-Number
A user-defined word that indicates the position of a data item in
the hierarchical structure of a logical record or that indicates
special properties of a data description entry.
A level-number
is expressed as a 1- or 2-digit number. Level-numbers in the
range 1 through 49 indicate the position of a data item in the
hierarchical structure of a logical record. Level-numbers in the
range 1 through 9 can be written either as a single digit or as a
zero followed by a significant digit. Level-numbers 66, 77, and
88 identify special properties of a data description entry.
Library-Name
A user-defined word that names a COBOL library that is to be used
by the compiler for a given source program compilation.
Library Text
A sequence of character-strings
library.

and/or

separators

COBOL

Line
(See Report Line.)
Line Number
An integer that denotes the vertical position of a report line on
a page.
Linkage Section
The section in the Data Division of the called program that
describes data items available from the calling program. These
data items can be referred to by both the calling and called
program.
Literal
A character-string whose value is implied by the ordered
characters constituting the string.

set

Logical Operator
One of the reserved words AND, OR, or NOT. In the formation of a
condition, both or either of AND and OR can be used as logical
connectives. NOT can be used for logical negation.
Logical Record
The most inclusive data item. The level-number for a
01.
(See Repor t Wr iter Log ical Record.)

record

A storage medium on which data can be oganized and maintained
both a sequential and nonsequential manner.

Low Order End
The rightmost character of a string of characters.
Mass Storage

Mass Storage Control System (MSCS)
An input-output control system that
processing of mass storage files.
G1ossary-12

directs

controls

the

Mass Storage File
A collection of records
medium.

that

assigned

mass

storage

MCS
(See Message Control System.)
Merge File
A collection of records to be merged by a MERGE statement.
The
merge file is created and can-be used only by the merge function.
Message
Data associated with an end of message indicator
group indicator.
(See Message Indicators.)

end

processing

exist

the

Message Control System (MCS)
A communication control system that supports
messages.

the

Message Count
The count of the number of complete messages that
designated queue of messages.

Message Indicators
EGI (end of group indicator), EMI (end of message indicator), and
ESI
(end of segment indicator) are conceptual indications that
notify the MCS that a specific condition exists
(end of group,
end of message, end of segment).
Within the
equivalent
equivalent
terminated
terminated

hierarchy of EGI, EMI, and ESI, an EGI is conceptually
to an ESI, an EMI, and an EGI. An EMI is conceptually
to an ESI and an EMI.
Thus,
a segment can be
by an ESI, an EMI, or an EGI. A message can be
by an EMI or an EGI.

Message Segment
Data that forms a logical subdivision of a message normally
{See Message
associated with an end of segment indicator.
Indicators.)
Mnemonic-Name
A user-defined word that is associated
Division with a specified implementor-name.

the

Environment

MSCS
(See Mass Storage Control System.)
Negated Combined Condition
The
'NOT'
logical
operator
immediately
parenthesized combined condition.

followed

Negated Simple Condition
The 'NOT' logical
condition.

operator

immediately

Glossary-13

followed

simple

Next Executable Sentence
The next sentence to which control is transferred after execution
of the current statement is complete.
Next Executable Statement
The next statement to which control is transferred
execution of the current statement is complete.

after

Next Record
The record that logically follows the current record of a file.
Noncontiguous Items
Elementary data items in the Working-Storage and Linkage Sections
that bear no hierarchical relationship to other data items.
Nonnumeric Item
A data item whose description permits its contents to be composed
of any combination of characters taken from the computer's
character set. Certain categories of nonnumeric items can be
formed from more restricted character sets.
Nonnumeric Literal
A character-string bounded by quotation marks.
The string of
characters can include any character in the computer's character
set. To represent a single quotation mark character within a
nonnumeric literal, two contiguous quotation marks must be used.
Numeric Character
A character that belongs to the following set of digits:

2, 3, 4, 5, 6, 7, 8, 9.

Numeric Item
A data item whose description restricts its contents to a value
represented by characters chosen from the digits '0' through '9';
if signed, the item can also contain a '+',
I_I
or other
representation of an operational sign.
Numeric Literal
A literal composed of one or more numeric characters that also
contain either a decimal point, or an algebraic sign, or
both. The decimal point must not be the rightmost character.
The algebraic sign, if present, must the leftmost character.

~an

OBJECT-COMPUTER
The name of an Environment Division paragraph in which the
computer
environment,
within which the object program is
executed, is described.
Object of Entry
A set of operands and reserved words within a Data Division entry
that immediately follows the subject of the entry.

Glossary-14

Object Program
A set or group of executable machine language instructions and
other material designed to interact with data to provide problem
solutions. In this context, an object program 1S generally the
machine language result of the operation of a COBOL compiler on a
source program. Where there is no danger of ambiguity, the word
'program' alone can be used in place of the phrase 'object
program.'
Object Time
The time at which an object program is executed.
Open Mode
The state of a file after execution of an OPEN statement for that
file, and before the execution of a CLOSE statement for that
file.
The particular open mode is specified in the OPEN
statement as either INPUT, OUTPUT, 1-0, or EXTEND.
Operand
Whereas the general definition of operand is 'that component that
is operated upon,' for the purposes of this publication any
lowercase word (or words) that appears in a statement or entry
format can be considered to be an operand and, as such, is an
implied reference to the data indicated by the operand.
Operational Sign
An algebraic sign associated with a numeric data item or a
numeric literal, which indicates whether its value is positive or
negative.
Optional Word
A reserved word that is included in a specific format only to
improve the readability of the language and whose presence is
optional to you when the format in which the word appears is used
in a source program.
Output File
A file that is opened in either the output
mode.

mode

the

extend

Output Mode
The state of a file after execution of an OPEN statement, with
the OUTPUT or EXTEND phrase specified for that file, and before
the execution of a CLOSE statement for that file.
Output Procedure
A set of statements to which control is given during execution of
a SORT statement after the sort function is completed, or during
execution of a MERGE statement after the merge function has
selected the next record in merged order.
Page
A vertical division of a report representing
a
physical
separation of report data, the separation being based on internal
reporting requirements and/or external characteristics of the
reporting medium.

Glossary-IS

Page Body
That part of the logical page
and/or spaced.

which

lines

can

written

Page Footing
A report group that is presented at the end of a report
determined by the Report writer Control System.

page

Page Heading
A report group that is presented at the beginning of a
page and determined by the Report Writer Control System.

report

Paragraph
In the Procedure Division, a paragraph-name followed by a
and a space, and by zero, one, or more sentences.
Identification and Environment Divisions, a paragraph
followed by zero, one, or more entries.

period
In the
header

Paragraph Header
A reserved word followed by a period and a space that indicates
the
beginning
of
a paragraph in the Identification and
Environment Divisions. The permissible paragraph headers are:
In the Identification Division:
PROGRAM-ID.
AUTHOR.
INSTALLATION.
DATE-WRITTEN.
DATE-COMPILED.
SECURITY.
REMARKS.
In the Environment Division:
SOURCE-COMPUTER.
OBJECT-COMPUTER.
SPECIAL-NAMES.
FILE-CONTROL.
I-a-CONTROL.
Paragraph-Name
A user-defined word that identifies and begins a paragraph in the
Procedure Division.
Phrase
A phrase is an ordered set of one or more
character-strings that form a portion of
statement or of a COBOL clause.

consecutive COBOL
a COBOL procedural

Physical Record
(See Block.)
Prime Record Key
A key whose contents uniquely identify a record within an indexed
file.

Glossary-16

Printable Group
A report group that contains at

lea~t

one print line.

Printable Item
A data item, the extent and contents of which are specified by an
elementary report entry.
This elementary report entry contains a
COLUMN NUMBRR clause, a PICTURE clause, and a SOURCE, SUM, or
VALUE clause.
Procedure
A paragraph or group of logically successive paragraphs, or a
section or group of logically successive sections, within the
Procedure Division.
Procedure-Name
A user-defined word that is used to name a paragraph or section
in the Procedure Division.
It consists of a paragraph-name
(which can be qualified) or a section-name.
program-Name
A user-defined word that identifies a COBOL source program.
Pseudo-Text
A sequence of character-strings and/or separators bounded by, but
not including, pseudo-text delimiters.
Pseudo-Text Delimiter
Two contiguous
pseudo-text.

equal

sign

(=1

characters

used

delimit

Punctuation Character
A character that belongs to the following set:
Character

(
)

Meaning
comma
semicolon
period
quotation mark
left parenthesis
right parenthesis
space
equal sign

Qualified Data-Name
An identifier that is composed of a data-name followed by one or
more sets of either of the connectives OF and IN followed by a
data-name qualifier.

Glossary-l7

Qualifier
1.

A data-name that is used in a reference together with another
data-name at a lower level in the same hierarchy.

A section-name that is used in a reference
paragraph-name specified in that section.

together

with

A library-name that is used in a reference
text-name associated with that library.

together

with

Queue
A logical collection
processing.

messages

awaiting

transmission

Queue Name
A symbolic name that indicates to the MCS the logical path by
which a message or a portion of a completed message can be
accessible in a queue.
Random Access
An access mode in which the program-specified value of a key data
item identifies the logical record that is obtained from, deleted
from, or placed into a relative or indexed file.
Random File
A file with random organization.
Random Organization
The permanent logical file structure in which each record is
uniquely identified by an integer value greater than zero, which
specifies the record's logical position in the file.
Record
(See Logical Record.)
Record Area
A storage area allocated for processing the record described in a
record description entry in the File Section.
Record Description
(See Record Description Entry.)
Record Description Entry
The total set of data
particular record.

description

entries

associated

with

Record Key
A key whose contents identify a record within an indexed file.
Record-Name
A user-defined word that names a record
description entry in the Data Division.

Glossary-18

described

record

Reference Format
A format that provides a standard
source programs.

method

for

describing

COBOL

Relation
(See Relational Operator.)
Relation Character
A character that belongs to the following set:
Character

Meaning

greater than
less than
equal to

=
Relation Condition

The proposition for which a truth value can be determined that
the value of an arithmetic expression or data item has a specific
relationship to the value of another arithmetic expression or
data item.
(See Relational Operator.)
Relational Operator
A reserved word, a relation character,
a group of consecutive
reserved words,
or a group of consecutive reserved words and
relation characters used in the construction of a
relation
condition. The permissible operators and their meanings are:
Relational Operator

Meaning

IS [NOT] GREATER THAN
Greater than or not greater than
IS [NOT]

IS [NOT]

LESS THAN

IS [NOT]

EQUAL TO

Less than or not less than

Equal to or not equal to
IS [NOT]
Report Clause
A clause in the Report Section of the Data Division that appears
in a
report description entry or a report group description
entry.
Report Description Entry
An entry in the Report Section of the Data Division that is
composed of the level
indicator RD followed by a report name,
followed by a set of report clauses, as required.
Report File
An output file whose file description entry contains a REPORT
clause.
The contents of a report file consist of records that
are written under control of the Report Writer Control System.

Glossary-19

Report Footing
A report group that is presented only at the end of a report.
Report Group
In the Report Section of the Data Division,
entry and its subordinate entries.

level-number

Report Group Description Entry
An entry in the Report Section of the Data Division that is
composed of the level-number 01, the optional data-name, a TYPE
clause, and an optional set of report clauses.
Report Heading
A report group that is presented
report.

only

the

beginning

Report Line
A division of a page representing one row of horizontal character
positions.
Each character position of a report line is aligned
vertically beneath the corresponding character position of the
report line above it. Report lines are numbered from 1, by 1,
starting at the top of the page.
Report-Name
A user-defined word that names a report described in a report
description entry within the Report Section of the Data Division.
Report Section
The section of the Data Division that contains one or more report
description entries and their associated report group description
entries.
Report Writer Control System (RWCS)
An object-time control system provided by
constructs reports.

the

implementor

that

Report writer Logical Record
A record that consists of the Report writer print line and
associated control information necessary for its selection and
vertical positioning.
Reserved Word
A COBOL word specified in the list of words that can be used in
COBOL source programs, but that must not appear in the programs
as user-defined words or system-names.
Routine-Name
A user-defined word that identifies
language other than COBOL.

procedure

written

Run Unit
A set of one or more object programs that function at object time
as a unit to provide problem solutions.

Glossary-20

RWCS
(See Report Writer Control System.)
Section
A set of zero, one, or more paragraphs or entries,
called a
section body, the first of which is preceded by a section header.
Each section consists of the section header and the related
section body.
Section Header
A combination of words followed by a period and a space that
indicates the beginning of a section in the Environment, Data,
and Procedure Division.
In the Environment and Data Divisions, a section header
is
composed of reserved words followed by a period and a space. The
permissible section headers are:
In the Environment Division:
CONFIGURATION SECTION.
INPUT-OUTPUT SECTION.
In the Data Division:
FILE SECTION.
SCHEMA SECTION.
WORKING-STORAGE SECTION.
COMMUNICATION SECTION.
LINKAGE SECTION.
REPORT SECTION.
In the Procedure Division, a section header
is composed of a
section-name followed by the reserved word SECTION, followed by a
segment-number (optional), followed by a period and a space.
Section-Name
A user-defined
Division.

word

that

names

section

the

Procedure

Segment-Number
A user-defined word that classifies sections in the Procedure
Division for purposes of segmentation.
Segment-numbers can
contain only the characters '0', '1', •. , '9'. A segment-number
can be expressed either as a 1- or 2-digit number.
Sentence
A sequence of one or more statements,
the
terminated by a period followed by a space.

last

which

Separator
A punctuation character used to delimit character-strings.
Sequential Access
An access mode in which logical records are obtained from or
placed into a file
in a consecutive predecessor-to-successor
logical record sequence determined by the order of records in the
file.

Glossary-21

Sequential File
A file with sequential organization.
Sequential Organization
The permanent logical file structure in which a record is
identified by a predecessor-successor relationship established
when the record is placed into the file.
Sign Condition
The proposition, for which a truth value can be determined, that
the algebraic value of a data item or an arithmetic expression is
either less than, greater than, or equal to zero.
Simple Condition
Any single condition chosen from the set:
relation condition
class condition
condtion-name condition
switch-status condition
sign condition
(simple-condition)
Sort File
A collection of records to be sorted by a SORT statement.
The
sort file is created and can be used by the sort function only.
Sort-Merge File Description Entry
An entry in the File Section of the Data Division that is
composed of the level indicator SD, followed by a file-name, and
then followed by a set of file clauses, as required.
Source
The symbolic identification of the originator of
to a queue.

transmission

SOURCE-COMPUTER
The name of an Environment Division paragraph in which the
computer
environment,
within which the source program is
compiled, is described.
Source Item
An identifier designated by a SOURCE
value of a printable item.

clause

that

provides

the

Source Program
Although it is recognized that a source program
can
be
represented by other forms and symbols, in this document it
always refers to a syntactically correct set of COBOL statements
beginning with an Identification Division and ending with the end
of the Procedure Division. In contexts where there is no danger
of ambiguity, the word 'program' alone can be used in place of
the phrase 'source program.'

Glossary-22

Special Character
A character that belongs to the following set:
Character

Meaning

plus sign
minus sign
asterisk
stroke (virgule, slash)
equal sign
currency sign
comma (decimal point)
semicolon
period (decimal point)
quotation mark
left parenthesis
right parenthesis
greater than symbol
less than symbol

"
(
)

>
<
Special-Character Word
A reserved word that is an
character.

arithmetic

operator

relation

SPECIAL-NAMES
The name of an Environment Division
paragraph
in
which
implementor-names are related to user-specified mnemonic-names.
Special Registers
Compiler-generated storage areas whose primary use is to store
information produced in conjunction with the user of specific
COBOL features.
Standard Data Format
The concept used in describing the characteristics of data in a
COBOL Data Division under which the characteristics or properties
of the data are expressed in a form oriented to the appearance of
the data on a printed page of infinite length and breadth, rather
than a form oriented to the manner in which the data is stored
internally in the computer, or on a particular external medium.
statement
A syntactically valid combination of words and symbols written in
the Procedure Division and beginning with a verb.
Sub-Queue
A logical hierarchical division of a queue.
Subject of Entry
An operand or reserved word that appears immediately following
the level indicator or the level-number in a Data Division entry.
Subprogram
(See Called Program.)

Glossary-23

Subscript
An integer whose value
table.

identifies

particular

element

An identifier that is composed of a data-name followed by one
more subscripts enclosed in parentheses.

Subscripted Data-Name

Sum Counter
A signed numeric data item established by a SUM clause in the
Report Section of the Data Division. The sum counter is used by
the Report writer Control System to contaiQ the result of
designated summing operations that take place during production
of a report.
Switch-Status Condition
The proposition, for which a truth value can be determined, that
an implementor-defined switch, capable of being set to an 'on' or
'off' status, has been set to a specific status.
System-Name
A COBOL word that is
environment.

used

communicate

with

the

operating

Table
A set of logically consecutive items of data that are defined
the Data Division by means of the OCCURS clause.

Table Element
A data item that belongs to the set of repeated items
a table.

comprising

Terminal
The originator of a transmission to a queue, or the receiver of a
transmission from a queue.
Text-Name
A user-defined word that identifies library text.
Text-Word
Any character-string or separator,
library or in pseudo-text.

except

space,

COBOL

Truth Value
The representation of the result of the evaluation of a condition
in terms of one of two values:
true
false
Unary Operator
A plus (+) or a minus (-) sign that precedes a variable or a left
parenthesis in an arithmetic expression, and that has the effect
of multiplying the expression by +1 or -1, respectively.

Glossary-24

unit
A module of mass storage the dimensions of which
by each implementor.

are

determined

User-Defined Word
A COBOL word that must be supplied by you to satisfy
of a clause or statement.

the

format

variable
A data item whose value can be changed by execution of the object
program.
A variable used in an arithmetic expression must be a
numeric elementary item.
Verb
A word that expresses an action to be taken by a
or object program.

COBOL

compiler

Word
A character-string of not more than 30 characters that
user-defined word, a system-name, or a reserved word.

forms

Working-Storage Section
The section of the Data Division that describes working storage
data items, which is composed either of noncontiguous items or of
working storage records or of both.
77-Level-Description-Entry
A data description entry that describes a noncontiguous data item
with the level-number 77.

Glossary-25

INDEX

36-bit storage word, 12-4

ASCII conversion,
EBCDIC to, B-5
ASCII data types, 13-9
ASCII mixed-mode binary,
8-22
ASCII recording mode, 3-23,
8-1
ASCII tape writing, E-9
ASCII to EBCDIC conversion,

Abbreviations in relation
condition, 5-15
ACCEPT, 5-20
ACCEPT command,
COBDDT, 7-30
Access,
file, 8-27
ACCESS MODE, 3-18
Accessing
indexed-sequential file,
9-16
Accessing random file, 9-15
Accessing sequential file,
9-11
ACTUAL KEY, 3-21, 5-70,
5-73
ADD, 5-22
ADVANCING, 5-114
AFTER, 5-114
Alignment, 13-12
ALL, 5-39, 5-101
ALLOWING OTHERS, 5-61
Alphabetic item definition,
4-38
Alphanumeric edited item
definition, 4-38
Alphanumeric item
definition, 4-38
Alphanumeric items,
comparison of, 5-9
Alphanumeric literals, 1-8
ALTER, 5-24
Alternate numeric test, 0-1
ANSI labeled tape, E-8
Area,
continuation, 1-9
Argument list,
entries in, 12-4
Arithmetic computations,
usage in, 5-17
Arithmetic expressions, 1-4,
5-6
Arithmetic operators, 5-6
Arithmetic signs,
symbols representing,
4-36
Arithmetic verbs,
common options in, 5-16
ASCENDING, 5-52, 5-86
ASCII,
fixed-length, 8-4
variable-length, 8-5

8-1

ASCII to SIXBIT conversion,
B-3
ASSIGN, 3-11, 3-12
AT END, 5-69, 5-81

Basic reading, 9-11
Basic updating, 9-12
Basic writing, 9-12
BEFORE, 5-114
BEGINNING, 5-111
Binary,
ASCII mixed-mode, 8-22
EBCDIC mixed-mode, 8-25
SIXBIT mixed-mode, 8-24
BINARY recording mode, 3-23,
8-3
Bits,
monitor file status, 3-31
BLANK wHEN ZERO, 4-27
Block, 1-2
'
BLOCK CONTAINS, 4-13
Blocked fixed-length EBCDIC,
8-18
Blocked variable-length
EBCDIC, 8-21
Blocking data, 13-11
Blocking data with ISAM,
_p rod u c in g, 7 -1 7
Braces, 1-2
Brackets, 1-2
BREAK command,
COBDDT, 7-31
Building indexed-sequential
, file, 7-3
Buried update, 9-2
BYTE MODE, 3-25

CALL, 5-25
Called subprogram, 11-5
Calling FORTRAN subprograms,
12-2

Index-l

INDEX (CONT.)

Calling MACRO subprograms,
12-3
Calling program, 11-4
Calling subprograms, 12-1
CANCEL, 5-27, 11-14
Card-type format, 1-10
Categories,
statement, 5-3
CHANNEL, 3-7
Character set, 1-3
Characters,
edi ting, 1-4
floating replacement,
4-47
lower-case, 1-1
punctuation, 1-4
special, 1-4
upper-case, 1-2
Checking indexed-sequential
file, 7-16
CHECKPOINT OUTPUT, 3-19
Class condition, 5-9
Class condition format,
5-10
Class condition
restrictions, 5-10
CLEAR command,
COBDDT, 7-31
CLOSE, 5-28, 5-30
CLOSE REEL procedure, 5-29
COBDDT,
loading, 7-28
starting, 7-28
COBDDT ACCEPT command, 7-30
COBDDT BREAK command, 7-31
C08DDT CLEAR command, 7-31
COBDDT commands, 7-30
C08DDT DDT command, 7-32
COBDDT DISPLAY command,
7-32
C08DDT GO command, 7-33
C08DDT histogram, 13-6
COBDDT LOCATE command, 7-33
COBDDT MODULE command, 7-33
COBDDT NEXT command, 7-34
COBDDT OVERLAY command,
7-34
COBDDT PROCEED command,
7-35
C08DDT SHOW SYMBOLS command,
7-35
C08DDT STEP command, 7-36
COBDDT STOP command, 7-36
COBDDT TRACE command, 7-36
COBDDT UNPROTECT command,
7-37
COBDDT utility, 7-1, 7-28,
13-6
COBDDT WHERE command, 7-38

COBOL,
elements of, 1-3
COBOL compile switches, 6-3
C080L labels, E-l
COBOL library facility,
1-15
COBOL programs,
debugging, 7-28
overlayable, 11-9
restarting, 7-42
COBOL reserved words, 1-4,
A-I
COBOL symbols, 1-1
COBOL terms, 1-1, 1-2
COBOL utility programs, 7-1
COBOL-68 language,
introduction to, 1-1
COBOL-68 performance,
improving, 13-1
COBOL-68 programs,
compiling, 6-1
CODE, 4-68
Codes,
file status, 3-28, 3-29,
3-30
monitor error, 3-32, 3-33
Coding conventions, 13-12
Collating sequences, B-1
COLUMN, 4-75
Column,
histogram CPU, 13-7
histogram ELAPSED, 13-8
histogram ENTRIES, 13-7
histogram OVERHEAD, 13-8
Command,
C08DDT ACCEPT, 7-30
COBDDT BREAK, 7-31
C08DDT CLEAR, 7-31
COBDDT DDT, 7-32
COBDDT DISPLAY, 7-32
COBDDT GO, 7-33
COBDDT LOCATE" 7-33
C08DDT MODULE, 7-33
COBDDT NEXT, 7-34
COBDDT OVERLAY, 7-34
COBDDT PROCEED, 7-35
COB DDT SHOW SYMBOLS, 7-35
COB DDT STEP, 7-36
COBDDT STOP, 7-36
COBDDT TRACE, 7-36
C08DDT UNPROTECT, 7-37
COBDDT WHERE, 7-38
LIBARY DELETE, 7-25
LIBARY END, 7-26
LIBARY EXTRACT, 7-26
LI8ARY INSERT, 7-26
LIBARY REPLACE, 7-26
LIBARY RESTART, 7-27

Index-2

INDEX (CONT.)

Command defaults,
LIBARY, 7-23
Command usage,
LIBARY, 7-27
Commands,
COBDDT, 7-30
indirect, 7-18
LIBARY, 7-25
LIBARY directing, 7-26
LIBARY group mode, 7-25
Comment lines, 1-10
Common options in
arithmetic verbs, 5-16
Communication,
inter-program, 11-4
COMMUNICATION SECTION, 4-3
Comparison of alphanumeric
items, 5-9
Comparison of numeric items,
5-8
Compile switches,
COBOL, 6-3
Compiling COBOL-68 programs,
6-1
COMPUTATIONAL, 4-56
Computational data types,
13-10
COMPUTATIONAL-I, 4-57
COMPUTATIONAL-3, 4-58
COMPUTE, 5-31
Concepts,
record, 4-24
Condition,
class, 5-9
relation, 5-7
Condition-name, 4-28
Condition-name condition
format, 5-10
Conditional expressions,
5-7
Conditional statements, 1-4
CONFIGURATION SECTION, 3-2
CONSOLE, 3-7
Constants,
Figurative, 1-5
Continuation area, 1-9
CONTROL FOOTING, 4-69
CONTROL HEADING, 4-69
CONTROL{S), 4-69
Conventions,
coding, 13-12
Conversion,
ASCII to EBCDIC, B-1
ASCII to SIXBIT, B-3
EBCDIC to ASCII, B-5
SIXBIT to EBCDIC, B-1
Conversion table,
data type, B-1
Converting tapes, E-6

COPY, 1-15
CORRESPONDING, 5-17
Count storage items,
UNSTRING, 5-102
Counter, 13-11
Counters,
incrementing, 13-13
CPU column,
histogram, 13-7
Creating source libraries,
7-21
CURRENCY SIGN, 3-8
CURRENCY SIGN IS, 4-37

D-format, E-9
Data,
blocking, 13-11
Data characters,
symbols representing,
4-36
Data description entry,
4-25
Data descriptions, 4-5
DATA DIVISION, 4-1
Data efficiencies, 13-10
Data file,
indexed, 8-31
Data item qualification,
4-6
Data movement, 13-14
DATA RECORD, 4-14
Data type,
using correct, 13-8
'Data type conversion table,
B-1
Data types,
ASCII, 13-9
computational, 13-10
DISPLAY, 13-8
EBCDIC, 13-8
SIXBIT, 13-10
Data-name, 4-30
DATABASE-KEY, 4-60
DATE-COMPILED paragraph,
2-2
DATE-WRITTEN, 4-22
DDT command,
COBDDT, 7-32
Deadly embrace, 9-3
Debugging COBOL programs,
7-28
DECIMAL-POINT IS COMMA,
4-37
DECLARATIVES, 5-109
Defaults,
tape handling, E-4
TOPS-IO tape handling,

Index-3

INDEX (CONT.)

DISPLAY-9, 4-59
DIVIDE, 5-34
DIVISION,
DATA, 4-1
ENVIRONMENT, 3-1
ID, 2-1
IDENTIFICATION, 2-1
PROCEDURE, 5-1
Documentation, 13-5
DOWN BY, 5-84

Defaults (Cont.)
E-6
TOPS-20 tape handling,
E-5
DEFERRED OUTPUT, 3-18
Defining logical names, C-l
Defining overlays, 11-9
Definition,
alphabetic item, 4-38
alphanumeric edited item,
4-38
alphanumeric item, 4-38
elementary item, 4-39
histogram listing, 7-41
numeric edited item, 4-38
numeric item, 4-38
picture-string, 4-39,
4-40
Definitions,
PICTURE, 4-36
tape handling, E-l
DELETE, 5-28, 5-32
DELETE command,
LIBARY, 7-25
DELIMITED BY, 5-102
DELIMITED BY SIZE, 5-90
DELIMITER IN, 5-102
Delimiter items,
STRING, 5-90
UNSTRING, 5-101
Delimiter storage items,
UNSTRING, 5-102
DENSITY, 3-23
DEPENDING, 5-24
DESCENDING, 5-52, 5-86
Description entry,
data, 4-25
Description (FD),
file, 4-11
Descriptions,
data, 4-5
record, 4-24
Destination,
STRING, 5-91
Destination counter,
UNSTRING, 5-103
Destination items,
UNSTRING, 5-100
Direct indexing, 4-9
Direct subscripting, 4-9
Directing commands,
LIBARY, 7-26
DISPLAY, 5-33
DISPLAY command,
COBDDT, 7-32
DISPLAY data types, 13-8
DISPLAY IS, 3-5
DISPLAY-6, 4-59
DISPLAY-7, 4-59

EBCDIC,
blocked fixed-length,
8-18
blocked variable-length,
8-21
fixed-length, 8-13
variable-length, 8-14
EBCDIC conversion,
ASCII to, B-1
SIXBIT to, B-1
EBCDIC data types, 13-8
EBCDIC file formats, 8-12
EBCDIC labeled tapes, E-ll
EBCDIC mixed-mode binary,
8-25
EBCDIC recording mode, 8-2
EBCDIC to ASCII conversion,
B-5
Editing,
fixed insertion, 4-45
floating insertion, 4-44,
4-46
simple insertion, 4-44
special insertion, 4-45
symbols representing,
4-37
zero suppression, 4-46
Editing characters, 1-4
Editing in PICTURE, 4-44
ELAPSED column,
histogram, 13-8
Elementary item definition,
4-39
Elementary items, 4-5
Elements of COBOL, 1-3
Ellipsis, 1-2
ELSE, 5-49
Embrace,
deadly, 9-3
END command,
LIBARY, 7-26
END DECLARATIVES, 5-110
END OF UNIT, 3-35
ENDING, 5-111
ENTER, 5-36

Index-4

INDEX (CONT.)

ENTRIES column,
histogram, 13-7
Entries in argument list,
12-4
ENTRY, 5-37
Entry,
data description, 4-25
level-66, 4-51
RD, 4-66
report group description,
4-72
ENVIRONMENT DIVISION, 3-1
Error codes,
monitor, 3-32, 3-33
Errors,
Ignoring ISAM, 7-12
Evaluating performance,
13-5
Evaluation rules, 5-12
EVERY RECORD, 5-42
EXAMINE, 5-38, 13-14
Execution,
sequence of, 5-5
STRING, 5-91
UNSTRING, 5-103
EXIT, 5-40
EXIT PROGRAM, 5-41
Expressions,
arithmetic, 1-4, 5-6
conditional, 5-7
EXTEND, 5-62
EXTRACT command,
LIBARY, 7-26

File (Cont.)
indexed-sequential, 8-30
maintaining
indexed-sequential, 7-8
packing
indexed-sequential,
7-11
random, 8-27
renaming
indexed-sequential,
7-15
sequential, 8-27
using indexed-sequential,
7-19
File access, 8-27
File description (FD), 4-11
File format,
library, 7-21
File formats, 8-1, 8-3
File formats,
EBCDIC, 8-12
File organization, 8-27
FILE SECTION, 4-2
FILE STATUS, 3-27
File status bits,
monitor, 3-31
File status codes, 3-28,
3-29, 3-30
File storage, 13-11
File strategies,
sequential, 9-12
File types, 5-30
FILE-CONTROL paragraph,
3-10
FILE-LIMIT, 3-16
Files, 4-6
FILLER, 4-30
FIRST, 5-39
FIRST DETAIL, 4-70
Fixed length recording mode,
3-23
Fixed-length ASCII, 8-4
Fixed-length EBCDIC, 8-13
blocked, 8-18
Fixed-length SIXBIT, 8-8
FOR, 5-61
FOR MULTIPLE, 3-14
Format,
card-type, 1-10
class condition, 5-10
condition-name condition,
5-10
library file, 7-21
relation condition, 5-8
sign condition, 5-12
source program, 1-9
switch-status condition,
5-11
terminal-type, 1-11, 1-12

F-format, E-9
Facility,
COBOL library, 1-15
FD file-name, 4-15
(FD) ,
file description, 4-11
Features,
using histogram, 7-42
Figurative constants, 1-5
File,
accessing
indexed-sequential,
9-16
accessing random, 9-15
accessing sequential,
9-11
building
indexed-sequential, 7-3
checking
indexed-sequential,
7-16
index, 8-32
indexed data, 8-31

Index-5

INDEX (CONT.)

IDENTIFICATION DIVISION,
2-1
IF, 5-49
Ignoring ISAM errors, 7-12
Improving COBOL-68
performance, 13-1
Incrementing counters,
13-13
INDEX, 4-60
Index file, 8-32
INDEXED BY, 5-80
Indexed data file, 8-31
Indexed-sequential file,
8-30
accessing, 9-16
building, 7-3
checking, 7-16
maintaining, 7-8
packing, 7-11
renaming, 7-15
using, 7-19
Indexed-sequential file
maintenance program,
7-2
Indexes, 13-11
Indexing, 4-7
direct, 4-9
qualified direct, 4-10
relative, 4-9
Indirect commands, 7-18
Initializing histogram
table, 7-38
INITIATE, 5-51
INPUT, 5-60, 5-111
INPUT PROCEDURE, 5-52
INPUT-OUTPUT, 5-111
INPUT-OUTPUT SECTION, 3-9
INSERT command,
LIBARY, 7-26
Insertion,
symbols representing,
4-37
Inter-program communication,
11-4
INTO, 5-70, 5-78
Introduction to COBOL-68
language, 1-1
INVALID KEY, 5-32, 5-69
Invoking library utility,
7-21
ISAM,
producing blocking data
with, 7-17
ISAM errors,
Ignoring, 7-12
ISAM utility, 7-1
Item, 1-2
Items,
elementary, 4-5

Format of PROCEDURE
DIVISION, 5-2
Formation rules, 5-12
Formats,
EBCDIC file, 8-12
file, 8-1, 8-3
PROCEDURE DIVISION verb,
5-19
FORTRAN subprograms,
calling, 12-2
FREE, 5-42, 9-10
FROM, 5-71, 5-79, 5-116

GENERATE, 5-45
GIVING, 5-23, 5-87, 5-95
GO command,
COBDDT, 7-33
GO TO, 5-24, 5-47
GOBACK, 5-48
GROUP INDICATE, 4-76
Group items, 4-5
Group mode commands,
LIBARY, 7-25

Handling,
tape, E-l
Histogram,
COBDDT, 13-6
starting, 7-39
stopping, 7-39
Histogram CPU column, 13-7
Histogram ELAPSED column,
13-8
Histogram ENTRIES column,
13-7
Histogram features,
using, 7-42
Histogram listing,
obtaining, 7-40
Histogram listing
definition, 7-41
Histogram OVERHEAD column,
13-8
Histogram table,
initializing, 7-38
Histograms,
obtaining, 7-38
Histograms of program
behavior, 7-38

1-0, 5-60, 5-111
I-O-CONTROL paragraph, 3-35
ID DIVISION, 2-1

Index-6

INDEX (CONT.)

Items (Cont.)
group, 4-5

LIBARY RESTART command,
7-27
LIBARY switches, 7-24
LIBARY utility, 7-1
Libraries,
creating source, 7-21
maintaining source, 7-21
object, 11-6
Library facility,
COBOL, 1-15
Library file format, 7-21
Library utility,
invoking, 7-21
LINE NUMBER, 4-77
Line numbers, 1-11
LINE-COUNTER, 4-66
Lines,
comment, 1-10
LINK /SPACE switch, 11-11
LINKAGE SECTION, 4-3
Literals, 1-7
alphanumeric, 1-8
numeric, 1-7
Loading COBDDT, 7-28
Loading subprogram
structure, 11-6
LOCATE -command,
COBDDT, 7-33
Logical names,
defining, C-l
Logical operators, 5-12
Lower-case characters, 1-1

JUSTIFIED, 4-31

KEY, 5-44, 5-74, 5-85

Label,
standard, 4-17
LABEL RECORD, 4-16
Label type, E-l
Labeled tape,
ANSI, E-8
Labeled tapes, E-6, E-8
Labeled tapes,
EBCDIC, E-ll
Labels,
COBOL, E-l
Reading magnetic tape,
7-13
system, E-l
writing magnetic tape,
7-13
Language,
introduction to COBOL-68,
1-1
LAST DETAIL, 4-70
LEADING, 5-39
Level numbers, 4-5
Level-66, 4-33
Level-66 entry, 4-51
Level-77, 4-33
Level-88, 4-28, 4-33, 4-62
Level-number, 4-33
LIBARY,
running, 7-25
LIBARY command defaults,
7-23
LIBARY command usage, 7-27
LIBARY commands, 7-25
LIBARY DELETE command, 7-25
LIBARY directing commands,
7-26
LIBARY END command, 7-26
LIBARY EXTRACT command,
7-26
LIBARY group mode commands,
7-25
LIBARY INSERT command, 7-26
LIBARY program, 7~21
LIBARY REPLACE command,
7-26

MACRO subprograms,
calling, 12-3
Magnetic tape labels,
Reading, 7-13
writing, 7-13
Maintaining
indexed-sequential file,
7-8
Maintaining source
libraries, 7-21
Maintenance program,
indexed-sequential file,
7-2
Media,
nonrandom-access, 4-17
MEMORY-SIZE, 3-4
MERGE, 5-52
MESSAGE COUNT, 5-20
Methods,
programming, 13-4
Mixed-mode binary,
ASCII, 8-22
EBCDIC, 8-25

Index-7

INDEX (CONT.)

Mixed-mode binary (Cont.)
SIXBIT, 8-24
Mode,
ASCII recording, 3-23,
8-1
BINARY recording, 3-23,
8-3
EBCDIC recording, 8-2
fixed length recording,
3-23
SIXBIT recording, 3-23,
8-2
STANDARD-ASCII recording,
3-24
variable length recording,
3-24
Mode table,
recording, 3-26
Modes,
recording, 8-1
MODULE command,
COBDDT, 7-33
Monitor error codes, 3-32,
3-33
Monitor file status bits,
3-31
MOVE, 5-54
Movement,
data, 13-14
MULTIPLE FILE, 3-36
Multiple-reel volume set,
E-7
MULTIPLY, 5-56

Numeric item definition,
4-38
Numeric items,
comparison of, 5-8
Numeric literals, 1-7
NUMERIC test, 5-10
Numeric test,
alternate, D-l

Object libraries, 11-6
OBJECT-COMPUTER paragraph,
3-4
Object-time system, E-l
Obtaining histogram listing,
7-40
Obtaining histograms, 7-38
OCCURS, 4-7, 4-34, 5-80
OFF, 5-98
OMITTED, 4-16
ON, 5-98
ON OVERFLOW, 5-26, 5-36,
5-93
ON SIZE ERROR, 5-16, 5-23
OPEN, 5-59, 9-4
Operating RERUN, 7-43
Operators,
arithmetic, 5-6
logical, 5-12
relational, 5-8
Optimization,
program, 13-3
OPTIONAL, 3-12
Ordering statements, 13-15
Organization,
file, 8-27
OUTPUT, 5-60, 5-111
OUTPUT PROCEDURE, 5-52
Overflow,
STRING, 5-93
UNSTRING, 5-107
OVERHEAD column,
histogram, 13-8
OVERLAY command,
COBDDT, 7-34
Overlayable COBOL programs,
11-9
Overlays, 11-1, 11-8
Overlays,
defining, 11-9
using, 11-8

NEXT command,
COBDDT, 7-34
NEXT GROUP, 4-79
NEXT SENTENCE, 5-49, 5-82
NO REWIND, 5-28
NOMINAL KEY, 3-22
Nonrandom-access media,
4-17
NOT RETAINED, 5-43
NOTE, 5-58
Number,
volume, E-2
Numbers,
level, 4-5
line, 1-11
section-name priority,
5-5
segment, 11-1
segmentation priority,
5-5
Numeric edited item
definition, 4-38

Packing indexed-sequential
file, 7-11
PAGE LIMIT, 4-70

Index-8

INDEX (CONT.)

PAGE-COUNTER, 4-66
Paragraph,
DATE-COMPILED, 2-2
FILE-CONTROL, 3-10
I-O-CONTROL, 3-35
OBJECT-COMPUTER, 3-4
PROGRAM-ID, 2-2
SOURCE-COMPUTER, 3-3
SPECIAL-NAMES, 3-6
Paragraphs,
procedure, 5-4
Parentheses,
using, 5-13
PARITY, 3-23
PERFORM, 5-64, 13-13
Performance,
evaluating, 13-5
improving COBOL-68, 13-1
PICTURE, 4-36
editing in, 4-44
PICTURE definitions, 4-36
Picture-string definition,
4-39, 4-40
Picture-string symbols,
4-47, 4-48
POINTER, 5-103
Pointer,
STRING, 5-91
Pointer items,
UNSTRING, 5-102
POSITIONING, 5-114
Priority numbers,
section-name, 5-5
segmentation, 5-5
Procedure,
CLOSE REEL, 5-29
PROCEDURE DIVISION, 5-1
format of, 5-2
PROCEDURE DIVISION verb
formats, 5-19
Procedure paragraphs, 5-4
Procedure sections, 5-4
Procedure sentences, 5-2
Procedure statements, 5-2
Procedure verbs, 5-3
PROCEED command,
COBDDT, 7-35
PROCESSING MODE, 3-20
Producing blocking data
with ISAM, 7-17
Program,
calling, 11-4
indexed-sequential file
maintenance, 7-2
LIBARY, 7-21
Program behavior,
histograms of, 7-38
Program format,
source, 1-9

Program optimization, 13-3
Program segments, 11-1
Program structure, 1-3
PROGRAM-ID paragraph, 2-2
Programming methods, 13-4
Programming tools, 13-3,
13-6
Programs,
. COBOL utility, 7-1
compiling COBOL-68, 6-1
debugging COBOL, 7-28
overlayable COBOL, 11-9
restarting COBOL, 7-42
Punctuation, 1-8
Punctuation characters, 1-4

Qualification,
data item, 4-6
Qualified direct indexing,
4-10
Qualified direct
subscripting, 4-10

Random access of random
file, 8-29
Random file, 8-27
accessing, 9-15
random access of, 8-29
sequential access of,
8-28
RD entry, 4-66
READ, 5-69
Reading magnetic tape
labels, 7-13
Record, 1-2
RECORD, 3-36
Record concepts, 4-24
RECORD CONTAINS, 4-18
Record descriptions, 4-24
RECORD KEY, 3-22, 5-79
RECORDING MODE, 3-23
Recording mode,
ASCII, 3-23, 8-1
BINARY, 3-23, 8-3
EBCDIC, 8-2
fixed length, 3-23
SIXBIT, 3-23, 8-2
STANDARD-ASCII, 3-24
variable length, 3-24
Recording mode table, 3-26
Recording modes, 8-1
Records, 4-6
REDEFINES, 4-49
REEL, 5-28

Index-9

INDEX (CONT.)

Registers,
special, 1-6
Relation condition, 5-7
abbreviations in, 5-15
Relation condition format,
5-8
Relational operators, 5-8
Relative indexing, 4-9
Relative subscripting, 4-9
RELEASE, 5-71
REMAINDER, 5-35
RENAMES, 4-51
Renaming indexed-sequential
file, 7-15
REPLACE command,
LIBARY, 7-26
REPLACING BY, 5-39
REPORT, 4-19
Report description, 4-66
Report group description
entry, 4-72
REPORT SECTION, 4-4, 4-64
Report writer, 10-1
RERUN, 3-35, 5-60
RERUN,
operating, 7-43
using, 7-44
RERUN utility, 7-1, 7-42
RESERVE, 3-15
Reserved words,
COBOL, 1-4, A-I
RESET, 4-80
RESTART command,
LIBARY, 7-27
Restarting COBOL programs,
7-42
Restrictions,
class condition, 5-10
tape handling, E-4
TOPS-IO tape handling,
E-6
TOPS-20 tape handling,
E-5
RETAIN, 5-72, 9-7
RETURN, 5-78
REWRITE, 5-79
ROUNDED, 5-23, 5-31, 5-35,
5-57
Rules,
evaluation, 5-12
formation, 5-12
RUN, 5-88
Running LIBARY, 7-25

SD file-name, 4-20
SEARCH, 5-80
Searches, 11-6
SECTION,
COMMUNICATION, 4-3
CONFIGURATION, 3-2
FILE, 4-2
INPUT-OUTPUT, 3-9
LINKAGE, 4-3
REPORT, 4-4
SCHEMA, 4-2
WORKING-STORAGE, 4-3
Section-name priority
numbers, 5-5
Section-names, 11-1
Sections,
procedure, 5-4
SEEK, 5-83
Segment numbers, 11-1
SEGMENT-LIMIT, 3-5
Segmentation priority
numbers, 5-5
Segments,
program, 11-1
types of, 5-5
SELECT, 3-il, 3-12
Sentences,
procedure, 5-2
Sequence of execution, 5-5
Sequences,
collating, B-1
Sequential access of random
file, 8-28
Sequential file, 8-27
accessing, 9-11
Sequential file strategies,
9-12
SET, 5-84
Set,
character, 1-3
volume, E-2
SHOW SYMBOLS command,
COBDDT, 7-35
Sign condition, 5-11
Sign condition format, 5-12
Sign-control symbols, 4-37
Simultaneous update, 9-1
Simultaneous update
considerations, 9-3
Single-reel volume set, E-7
SIXBIT,
fixed-length, 8-8
variable-length, 8-10
SIXBIT conversion,
ASCII to, B-3
SIXBIT data types, 13-10
SIXBIT mixed-mode binary,
8-24

S-format, E-9
SAME AREA, 3- 3 6
SCHEMA SECTION, 4-2

Index-IO

INDEX (CONT.)

SIXBIT recording mode, 3-23,
8-2
SIXBIT to EBCDIC conversion,
B-1
SIZE ERROR, 5-31, 5-35,
5-57
SORT, 3-36, 5-85
SOURCE, 4-81
Source items,
STRING, 5-89
UNSTRING, 5-100
Source libraries,
creating, 7-21
maintaining, 7-21
Source program format, 1-9
SOURCE-COMPUTER paragraph,
3-3
/SPACE switch,
LINK, 11-11
Special characters, 1-4
Special registers, 1-6
SPECIAL-NAMES paragraph,
3-6
STANDARD, 4-16
Standard label, 4-17
STANDARD-ASCII recording
mode, 3-24
STANDARD-ASCII tape writing,
E-9
Starting COBDDT, 7-28
Starting histogram, 7-39
Statement categories, 5-3
Statements,
conditional, 1-4
ordering, 13-15
procedure, 5-2
STEP command,
COBDDT, 7-36
STOP, 5-88
STOP command,
COBDDT, 7-36
STOP RUN, 5-88
Stopping histogram, 7-39
Storage,
file, 13-11
Storage word,
36-bit, 12-4
STRING, 5-89
STRING delimiter items,
5-90
STRING destination, 5-91
STRING execution, 5-91
STRING overflow, 5-93
STRING pointer, 5-91
STRING source items, 5-89
Structure,
program, 1-3
Subprogram,
called, 11-5

Index-II

Subprogram structure,
loading, 11-6
Subprogram transfer, 5-25
Subprograms, 11-1, 11-3
Subprograms,
Calling, 12-1
calling FORTRAN, 12-2
calling MACRO, 12-3
Subscripting, 4-7
direct, 4-9
qualified direct, 4-10
relative, 4-9
Subscripts, 13-11
use of, 13-12
SUBTRACT, 5-94
SUM, 4-82
SUPPRESS, 5-96
SWITCH, 3-7
Switch,
LINK /SPACE, 11-11
Switch-status condition
format, 5-11
Switches,
COBOL compile, 6-3
LIBARY, 7-24
SYMBOLIC KEY, 3-22, 5-32,
5-70, 5-73, 5-79
Symbols,
COBOL, 1-1
picture-string, 4-47,
4-48
sign-control, 4-37
Symbols representing
arithmetic signs, 4-36
Symbols representing data
characters, 4-36
Symbols representing
editing, 4-37
Symbols representing
insertion, 4-37
Symbols representing zero
suppression, 4-36
SYNC LEFT, 4-53
SYNC RIGHT, 4-53
SYNCHRONIZED, 4-53
System,
object-time, E-l
System labels, E-l
System-labeled tapes,
using, E-8
System-unlabeled tapes,
using, E-6

TALLYING, 5-38, 5-103
Tape,
ANSI labeled, E-8
Tape handling, E-l

INDEX (CONT.)

UNPROTECT command,
COBDDT, 7-37
UNSTRING, 5-100
UNSTRING count storage
items, 5-102
UNSTRING delimiter items,
5-101
UNSTRING delimiter storage
items, 5-102
UNSTRING destination
counter, 5-103
UNSTRING destination items,
5-100
UNSTRING execution, 5-103
UNSTRING overflow, 5-107
UNSTRING pointer items,
5-102
UNSTRING source items,
5-100
UNTIL FIRST, 5-39
UNTIL FREED, 5-43, 5-74
UP BY, 5-84
Update,
buried, 9-2
simultaneous, 9-1
Update considerations,
simultaneous, 9-3
Upper-case characters, 1-2
USAGE, 4-55
Usage,
LIBARY command, 7-27
Usage in arithmetic
computations, 5-17
USE, 5-109
Use of subscripts, 13-12
User-created words, 1-6
USER-NUMBER, 4-22
USING, 5-25, 5-37, 5-86
Using correct data type,
13-8
Using histogram features,
7-42
Using indexed-sequential
file, 7-19
Using overlays, 11-8
using parentheses, 5-13
Using RERUN, 7-44
Using system-labeled tapes,
E-8
Using system-unlabeled
tapes, E-6
Using tapes, E-4
Utility,
COBDDT, 7-1, 7-28, 13-6
invoking library, 7-21
ISAM, 7-1
LIBARY, 7-1
RERUN, 7-1, 7-42

Tape handling defaults, E-4
TOPS-lO, E-6
TOPS-20, E-5
Tape handling definitions,
E-l
Tape handling restrictions,
E-4
TOPS-lO, E-6
TOPS-20, E-5
Tape writing,
ASCII, E-9
STANDARD-ASCII, E-9
Tapes,
converting, E-6
EBCDIC labeled, E-ll
labeled, E-6, E-8
transportable, E-9
undefined-format, E-IO
unlabeled, E-6, E-7
using, E-4
using system-labeled, E-8
using system-unlabeled,
E-6
Terminal-type format, 1-11,
1-12
TERMINATE, 5-97
Terms,
COBOL, 1-1, 1-2
Test,
NUMERIC, 5-10
Tools,
programming, 13-3, 13-6
TOPS-IO tape handling
defaults, E-6
TOPS-IO tape handling
restrictions, E-6
TOPS-20 tape handling
defaults, E-5
TOPS-20 tape handling
restrictions, E-5
TRACE, 5-98
TRACE command,
COBDDT, 7-36
Transfer,
subprogram, 5-25
Transportable tapes, E-9
TYPE, 4-83
Types,
file, 5-30
Types of segments, 5-5

U-format, E-IO
UNAVAILABLE, 5-62, 5-74
Undefined-format tapes,
E-IO
UNIT, 5-28
Unlabeled tapes, E-6, E-7

Index-12

INDEX (CONT.)

Utility programs,
COBOL, 7-1

WHERE command,
COBDDT, 7-38
WITH SEQUENCE CHECK, 5-53
Word,
36-bit storage, 12-4
Words, 1-4
COBOL reserved, 1-4, A-I
user-created, 1-6
WORKING-STORAGE SECTION,
4-3
WRITE, 5-113
writer,
report, 10-1
Writing,
ASCII tape, E-9
STANDARD-ASCII tape, E-9
writing magnetic tape
labels, 7-13

VALUE, 4-62
VALUE OF IDENTIFICATION,
4-21
Variable length recording
mode, 3-24
Variable-length ASCII, 8-5
Variable-length EBCDIC,
8-14
blocked, 8-21
Variable-length SIXBIT,
8-10
VARYING, 5-81
Verbs,
procedure, 5-3
Volume, E-2
Volume number, E-2
Volume set, E-2
multiple-reel, E-7
single-reel, E-7

Zero suppression,
symbols representing,
4-36

Index-13

TOPS-IO/TOPS-20
COBOL--68
Language Manual
AA-SOS7B-TK

READER'S COMMENTS
NOTE:

This form is for document comments only. DIGITAL will use comments submitted on this form at the company's discretion. If you require a written reply
and are eligible to receive one under Software Performance Report (SPR) service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well-organized? Please make
suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of reader that you most nearly represent.

o Assembly language programmer
o Higher-level language programmer
o Occasional programmer (experienced)
o User with little programming experience
o Student programmer
o Other (please speci~)~~~~~~~~~~~~~~~~~~~~~~~
Name~

__________________________________

Date~

____________________

Organization ~____________________________ Telephone ~~~~~~~~~_
Street~

___________________________________________________________

City~~~~~~~~~~~~~~~~~~--

State _____ Zip Code ~_ __
or Country

Not ear id
----~---aDO Ta FOa HeIre and Tape----------------------ffl-Ill--------::~o~~g~---t

.
•

I
I
I
I
I

Necessary
if Mailed in the
United States

. •

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

SOFTWARE PUBLICATIONS
200 FOREST STREET MR1-2/E37
MARLBOROUGH, MASSACHUSETTS 01752

Do Not Tear -Fold Here and Tape --------------------------------------------,
I

,I,
I
I
I
I
I
I