Digital PDFs

AD-5059B-T1

May 1985

570 pages

Original

20MB

Document:	AA-5059B-TK COBOL-74 Language Manual Oct85
Order Number:	AD-5059B-T1
Revision:	0
Pages:	570
Original Filename:	AA-5059B-TK_COBOL-74_Language_Manual_Oct85.pdf

OCR Text

TOP5-10/TOP5-20
COBOL-74 Language Manual
AA-50598-TK,AD-50598-T1

October 1985
This manual reflects the software of Version 12C of the
COBOL-74 compiler (CBL74) and the object-time system
(C740TS), and Version 4C of SORT.
This manual updates the TOPS-10ITOPS-20 COBOL-74
Language Manual, order number AA-50598-TK.
OPERATING SYSTEM:
SOFTWARE:

TOPS-10 V7.01
TOPS-20 V4.1

COBOL-74 V12C
C740TS V12C

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

Digital Equipment Corporation
PO Box CS2008
Nashua. New Hampshire 03061
Telephone :(603)884-6660

Digital Equipment Corporation
Digital Equipment Corporation
Accessories and Supplies Center Accessories and Supplies Center
1050 East Remington Road
632 Caribbean Drive
Sunnyvale. California 94086
Schaumburg. Illinois 60195
Telephone:(312)64o-5612
Telephone:(408)734-4915

Western Region

digital equipment corporation. marlboro massachusetts

First Printing, January 1979
Updated, January 1980
Revised, August 1981
Updated, October 1985
© Digital Equipment Corporation 1979, 1981, 1985. All Rights Reserved.

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 document 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.
The following are trademarks of Digital Equipment Corporation:

~D~DDmDTM
DEC
DECmate
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter
DIBOL

MASSBUS
PDP

P/OS
Professional
Q-BUS
Rainbow
RSTS

RSX
RT
UNIBUS
VAX
VMS

VT
Work Processor

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.

CONTENTS
PREFACE
CHAPTER 1

INTRODUCTION TO COBOL-74 LANGUAGE

1.1
SYMBOLS AND TERMS
1.1.1
Symbols
• •
1.1.1.1
Underline
• • •
1.1.1.2
Brackets and Braces
1.1.1.3
The Ellipsis • • • •
1.1.2
COBOL Terms • • • • •
1.2
ELEMENTS OF COBOL LANGUAGE
1.2.1
Program Structure
1.2.2
COBOL-74 Character Set •
1.2.3
Words
• •
1.2.3.1
Reserved Words • •
1.2.3.2
User-Defined Words •
1.2.4
Literals • • • • • • • •
1.2.4.1
Numeric Literal
1.2.4.2
Alphanumeric Literals
1.2.S
Separators • • •
1.3
SOURCE PROGRAM FORMAT
1.3.1
Card-Type Format • • •
1.3.2
Terminal-Type Format
1.3.2.1
With Line Numbers
1.3.2.2
Without Line Numbers.
1.4
THE COBOL LIBRARY FACILITY
1.4.1
The COpy Statement • • •
CHAPTER 2

THE IDENTIFICATION DIVISION

CHAPTER 3

THE ENVIRONMENT DIVISION

3.1
3.1.1
3.1.2
3.1.3
3.1.4
3.1.S
3.1.6
3.1.7
3.1.8
3.1.9
3.1.10
3.1.11
3.1.12
3.1.13
3.1.14
3.1.1S
3.1.16
CHAPTER 4
4.1
4.1.1
4.1.2
4.1.3
4.2

• • ••
1-1
• •
• • 1-1
• •
• • 1-2
• • • • • • • • • • • 1-2
• • • • • 1-2
• • • • •
• 1-3
•
• • 1-3
• 1-3
• 1-4
• • • ••
• • • • • l-S
• l-S
• • • • • • • • • • • 1-9
• • • ••
• • • • 1-10
• • • • • ••
1-10
• • • • • • • • 1-11
• • • •
1-12
• • • •
1-13
• • • • 1-14
• • • • • • • • • • • 1-15
1-16
• • • • 1-17
• • • • • 1-19
••••
1-19

ENVIRONMENT DIVISION CLAUSE FORMATS
Configuration Section • • • •
SOURCE-COMPUTER • • • •
OBJECT-COMPUTER
• • • • •
SPECIAL-NAMES
• • • • • •
Input-Output Section • • • •
• • • •
FILE-CONTROL •
SELECT • • • •
RESERVE
ORGANIZATION • •
ACCESS MODE
RECORD KEY • •
ALTERNATE RECORD KEY
RELATIVE KEY • • •
RECORDING MODE/DENSITY/PARITY
FILE STATUS • • • •
I-O-CONTROL • • • • • • • • • • •

......

3-2
3-2
• 3-3
• 3-4
• 3-6
• 3-9
3-10
3-14
3-16
3-17
3-19
3-20
3-21
3-22
3-23
3-27
3-37

THE DATA DIVISION
FILE SECTION • • • • • • • •
Record Descriptions
Elementary Items and Group Items •
Level Numbers
SCHEMA SECTION • •
iii

• • •
• • • • • •
•
•

4-2
4-2
4-3
4-3
4-4

October 1985

4.3
4.4
4.5
4.6
4.6.1
4.7
4.8
4.9
4.9.1
4.9.2
4.9.3
4.9.4
4.9.5
4.9.6
4.9.7
4.9.8
4.9.9
4.9.19
4.9.11
4.9.12
4.9.13
4.9.14
4.9.15
4.9.16
4.9.17
4.9.18
4.9.19
4.9.29
4.9.21
4.9.22
4.9.23
4.9.24
4.9.25
4.9.26
4.9.27
4.9.28
4.9.29
4.9.39
4.9.31
4.9.32
4.9.33
4.9.34
4.9.35
4.9.36
4.9.37
4.9.38
CHAPTER 5

COMMUNICATION SECTION
WORKING-STORAGE SECTION
LINKAGE SECTION
REPORT SECTION •
Format of Report Section •
QUALIFICATION
SUBSCRIPTING AND INDEXING
DATA DIVIS LON CLAUSES
File Description (FD)
BLOCK CONTAINS •
CODE-SET •
DATA RECORD
FD File-Name •
LABEL RECORD •
LINAGE •
RECORD CONTAINS
REPORT •
SO File-Name
VALUE OF
IDENTIFICATION/DATE-WRITTEN/USER-NUMBER
DATA DESCRIPTION ENTRY •
BLANK WHEN ZERO
Condition-Name (level-88)
Data-Name/FILLER •
JUSTIFIED
Level-Number •
OCCURS •
PICTURE
REDEFINES
RENAMES (level-66)
SIGN •
SYNCHRONIZED •
USAGE
VALUE
Report Description (RD)
CODE •
CONTROL
PAGE LIMIT •
Report Group Description •
COLUMN NUMBER
GROUP INDICATE •
LINE NUMBER
NEXT GROUP •
RESET
SOURCE •
SUM
TYPE •

4-5
4-5
4-5
4-6
4-7
4-9
4-19
4-12
4-13
4-15
4-17
4-18
4-19
4-29
4-22
4-24
4-25
4-26
4-27
4-31
4-33
4-34
4-36
4-37
4-39
4-49
4-42
4-56
4-58
4-69
4-62
4-64
4-79
4-72
4-74
4-75
4-76
4-78
4-81
4-82
4-83
4-85
4-86
4-87
4-88
.4-88.1

THE PROCEDURE DIVISION

5.1
SYNTACTIC FORMAT OF THE PROCEDURE DIVISION •
5.1.1
Statements •
5.1.2
Sentences
5.1.3
Paragraphs •
5.1.4
Sections •
5.2
SEQUENCE OF EXECUTION
5.3
SEGMENTATION AND SECTION-NAME PRIORITY NUMBERS •
5.4
ARITHMETIC EXPRESSIONS •
5.4.1
Arithmetic Operators •
5.4.2
Formation and Evaluation Rules •
5.5
CONDITIONAL EXPRESSIONS
5.5.1
Relation Condition •
5.5.1.1
Formation of a Relation-Condition
iv

5-2
5-2
5-2
5-4
5-4
5-4
5-4
5-6
5-6
5-6
5-7
5-7
5-8

October 1985

5.5.1.2
Relational Operators
5-8
Comparison of Numeric Items
5.5.1.3
5-8
5.5.1.4
Comparison of Nonnumeric Items
5-8
5.5.2
Class Condition
5-9
5.5.2.1
Format of a" Class Condition
5-9
5.5.2.2
Restrictions
5-9
5.5.2.3
The ALPHABETIC Test
5-10
5.5.2.4
The NUMERIC Test
5-10
5.5.3
Condition-Name Condition
5-10
5.5.3.1
Format of a Condition-Name Condition
5-10
5.5.4
Sign Condition •
5-11
5.5.4.1
Format of a Sign Condition
5-11
5.5.5
Logical Operators
5-11
5.5.6
Formation and Evaluation Rules
5-11
5.5.7
Combined and Negated Combined Conditions
5-15
5.5.8
Abbreviated Combined Relation Conditions •
5-16
5.6
COMMON OPTIONS ASSOCIATED WITH THE ARITHMETIC
VERBS
5-17
5.6.1
The ROUNDED Option
5-17
5.6.2
The SIZE ERROR Option
5-17
5.7
THE CORRESPONDING OPTION •
5-18
5.8
DETERMINATION OF USAGE IN ARITHMETIC COMPUTATIONS 5-18
5.9
PROCEDURE DIVISION VERB FORMATS
5-19
5.9.1
ACCEPT •
5-20
ADD
5.9.2
5-22
ALTER
5.9.3
5-24
CALL •
5.9.4
5-25
5.9.5
CANCEL •
5-27
5.9.6
CLOSE
5-28
COMPUTE
5.9.7
5-32
5.9.8
DELETE
5-33
5.9.9
DISPLAY
5-34
5.9.10
DIVIDE
5-35
5.9.11
ENTER
5-37
5.9.12
ENTRY
5-38
5.9.13
EXIT •
5-39
5.9.14
EXIT PROGRAM •
5-40
FREE
5.9.15
5-41
5.9.16
GENERATE
5-44
GO TO
5.9.17
5-46
5.9.18
IF
5-47
5.9.19
INITIATE
5-49
5.9.20
INSPECT
5-50
MERGE
5.9.21
5-55
MOVE
5.9.22
5-57
MULTIPLY •
5.9.23
5-59
OPEN
5.9.24
5-60
PERFORM
5.9.25
5-65
5.9.26
READ •
5-69
RELEASE
5.9.27
5-72
5.9.28
RETAIN
5-73
RETURN
5.9.29
5-79
5.9.30
REWRITE
5-80
SEARCH •
5.9.31
5-82
SET
5.9.32
5-85
SORT •
5.9.33
5-86
START
5.9.34
5-89
STOP •
5.9.35
5-91
5.9.36
STRING
5-92
SUBTRACT •
5-98
5.9.37
SUPPRESS
5.9.38
5-100
5.9.39
TERMINATE
5-101
5.9.40
TRACE
5-102
UNSTRING
5.9.41
5-104
v

October 1985

5.9.42
5.9.43
CHAPTER 6
6.1
6.2
6.3
CHAPTER 7

USE
WRITE

..........

• 5-113
• • • 5-116

COMPILING AND LOADING COBOL-74 PROGRAMS
• • • 6-1
COBOL-74 COMPILER COMMAND STRING •
• 6-4
LOADING COBOL-74 PROGRAMS
• • • •
. • • • . • 6-4
RUNNING COBOL-74 PROGRAMS
COBOL UTILITY PROGRAMS

7.1
ISAM
INDEXED-SEQUENTIAL FILE MAINTENANCE PROGRAM 7-2
Building an Indexed-Sequential File
• 7-4
7.1.1
7.1.2
Maintaining an Indexed-Sequential File • •
• 7-9
7.1.3
Packing an Indexed-Sequential File • • • •
7-12
7.1.4
Ignoring Errors • • • • • • • • • • • • •
7-13
Reading and Writing Magnetic Tape Labels •
7-14
7.1.5
7.1.6
Renaming an Indexed-Sequential File
7-16
7.1.7
Checking an Indexed-Sequential File
7-17
7.1.8
Producing Blocking Data with ISAM • • • • • • 7-18
Indirect Commands • • • • • • • • • • • • • • 7-19
7.1.9
7.1.19
Using Indexed-Sequential Files • • • • •
7-29
LIBARY
SOURCE LIBRARY MAINTENANCE PROGRAM
7-22
7.2
7.2.1
Library File Format • • • •
7-22
7.2.2
Invoking the Library Utility.
• • • • • 7-22
7.2.3
Command String Defaults
• • • • 7-23
7.2.4
LIBARY Switches • • • •
7-24
7.2.5
Running LIBARY • • • • • • • • • • • •
7-25
7.2.6
LIBARY Commands • • • • • •
• • • • • • 7-25
7.2.6.1
Group Mode Commands
• • • •
7-25
LIBRARY-Directing Commands
• • • • • 7-26
7.2.6.2
7.2.6.3
Example of Command Usage •
7-27
7.3
COBDDT
PROGRAM FOR DEBUGGING COBOL PROGRAMS
7-29
7.4
LOADING AND STARTING COBDDT • • • •
7-29
7.5
COB DDT COMMANDS • • • • • • •
• • • •
7-39
7.5.1
Obtaining Histograms of Program Behavior •
7-39
7.5.1.1
Initializing the Histogram Table • • • • • • 7-39
7.5.1.2
Starting the Histogram • • •
• • • • 7-49
7.5.1.3
Stopping the Histogram • • •
• • • • 7-49
7.5.1.4
Obtaining Histogram Listing
7-41
7.5.1.5
Using the Histogram Feature
• • • •
7-43
7.6
RERUN
PROGRAM TO RESTART COBOL PROGRAMS
7-44
7.6.1
Operating RERUN • • • • • • • • • • • • • • • 7-44
7.6.2
Examples of Using RERUN
• • • • • •
7-45
CHAPTER 8

FILE FORMATS

8.1
RECORDING MODES • • • •
8.1.1
ASCII Recording Mode • • • • • •
8.1.2
SIXBIT Recording Mode
• •
8.1.3
EBCDIC Recording Mode
•
8.1.4
BINARY Recording Mode
• • •
8.2
FILE FORMATS • • • • • • • • • • •
8.2.1
Fixed-Length ASCII • • • • • • •
8.2.2
Variable-Length ASCII
• • •
8.2.3
Fixed-Length SIXBIT • • • • •
8.2.4
Variable-Length SIXBIT • • • • •
8.2.5
EBCDIC File Formats • • • • •
8.2.6
BINARY File Formats • • • • •
8.2.6.1
COBOL ASCII Mixed-Mode Binary
8.2.6.2
COBOL SIXSIT Mixed-Mode Binary
vi

• • • • • • • • 8-1
• • • 8-1
• •
• • 8-2
• • • • • • • • 8-2
• • •
8-3
• • • • •
8-3
•
• 8-4
• •
• • • 8-6
• • • 8-8.1
•
8-19
••• •
8-12
• • • • 8-19
•••••
8-29
8-21
October 19"5

COBOL EBCDIC Mixed-Mode Binary
8.2.6.3
FILE ORGANIZATION AND ACCESS • • •
8.3
8.4
SEQUENTIAL FILES • • • • • • • • •
RELATIVE FILES • • • • • • • • • •
8.5
Sequential Access of Relative Files
8.5.1
Random Access of Relative Files • • • • • • •
8.5.2
8.5.3
Dynamic Access of Relative Files
INDEXED-SEQUENTIAL FILES
8.6
8.6.1
Data File
••••••
Index File
• • • •
8.6.2
CHAPTER 9

SIMULTANEOUS UPDATE

PROGRAMMING CONSIDERATIONS •
9.1
The OPEN Statement •
9.1.1
The RETAIN Statement
••••
9.1.2
The FREE Statement •
•
9.1.3
Accessing Sequential Files
9.1.4
Basic Reading
9.1.4.1
Basic Writing
9.1.4.2
Basic Updating • •
• • • • • •
9.1.4.3
Access to Sequential File Strategies ••
9.1.4.4
Accessing Relative Files • •
• • • •
9.1.5
Accessing Indexed-Sequential Files • • •
9.1.6
CHAPTER 10

REPORT WRITER

CHAPTER 11

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS

11.1
PROGRAM SEGMENTS • • • • • • • • • •
11.1.1
Section-Names and Segment Numbers
11.1.2
Examples • • • • • • • • • •
11.2
SUBPROGRAMS •• • • • • • • •
11.2.1
Inter-Program Communication
11.2.1.1
The Calling Program • • • •
The Called Subprogram • • •
11.2.1.2
11.2.2
Loading a Subprogram Structure
11.2.3
Object Libraries and Searches
11.2.4
Examples • • • • • • • • •
11.3
OVERLAYS • • • • • • • • • • • •
11.3.1
When to Use Overlays • • • •
11.3.2
Overlayable COBOL Programs •
11.3.3
Defining Overlays • • • • •
11.3.4
The /SPACE Switch to LINK
11.3.5
The CANCEL Statement • •
11.3.6
Examples • • • • • •

.....

CHAPTER 12
12.1
12.2
CHAPTER 13
13.1
13.1.1
13.1.2
13.1.3
13.1.4

8-22
8-23
8-23
8-24
8-24
8-25
8-25
8-27
8-27
8-28

• 9-3
• • 9-4
• 9-8
9-11
9-12
9-12
9-13
9-13
9-13
9-16
9-18

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

• •
••••

CALLING NON-COBOL SUBPROGRAMS
CALLING FORTRAN SUBPROGRAMS
CALLING MACRO SUBPROGRAMS

12-1
12-3

IMPROVING PERFORMANCE OF COBOL-74 PROGRAMS
HOW TO PROCEED WITH PROGRAM OPTIMIZATION •
Where to Begin • • • • • • • • •
What Tools Are Available • • • •
What Method or Procedure to Use
Evaluating Performance • • • • •
vii

13-3
13-3
13-3
13-4
13-5
October 1985

13.1.5
Documentation
13-5
13.2
LISTING THE TOOLS
13-6
13.2.1
COBDDT • • • • • • • • • • ~ • • • • • • •
13-6
13.2.1.1
The ENTRIES Column. •
• • • • • • • • • 13-7
13.2.1.2
The CPU Column. •
• • • • • 13-7
13.2.1.3
ELAPSED Column • • • • • ~.
• • • • • • 13-8
13.2.1.4
OVERHEAD.....
13-8
13.3
USING THE CORRECT DATA TYPE ~ • • • • • • •
13-8
13.3.1
DISPLAY Data Types
••••••••••
13-8
13.3.2
EBCDIC....
• •• ~
• • • •
13-8
13.3.3 , ASCII • • • • •
• • • •
13-9
13.3.4
SIXBIT................
• • 13-10
13.3.5
COMPUTATIONAL
• • • • • • • • • • • • 13-10
13.4
DATA EFFICIENCIES • • • • • ~ • • • • • • • • • 13-11
13.4.1
Counter, Indexes, Subscripts
• 13-11
13.4.2
File Storage • • • • • • • ~ •
13-11
13.4.3
Blocking Data • • • • • • • • • • • • •
• 13-11
13.4.4
DATA DIVISION Space Restrictions • • • • • • • 13-12
11.5
EFFICIENT CODING CONVENTIONS. •
• • • • 13-12.1
13.5.1
Alignment.......
• • • • • • • • 13-12.1
13.5.2
Usage of Subscripts
13-12.1
13.5.3
Incrementing Counters
• • • • • • • 13-13
13.5.4
The PERFORM Statement
• • • • • 13-13
13.5.5
Use of the INSPECT Statement.
• • 13-14
13.5.6
Data Movement • • • • • • ~
• • 13-14
13.5.7
Ordering Statements • • • ~ • • • • • • • • • 13-15
13.5.8
Asking the Correct Question
• • • • • • • 13-15
APPENDIX A

DIFFERENCES BETWEEN COBOL-68 AND COBOL-74

APPENDIX B

COBOL RESERVED WORDS

APPENDIX C

COLLATING SEQUENCES AND CONVERSION TABLES

APPENDIX 0

ALTERNATE NUMERIC TEST

APPENDIX E

DEFINING LOGICAL NAMES UNDER TOPS-20

APPENDIX F

TAPE HANDLING

F.1
F.1.1
F.1.2
F.1.3
F.2
F.2.1
F.2.2

DIRECTIONS AND DEFINITIONS • • • •
• •
Definitions • • • • • • • • • • • • • • • • • •
Finding the Right Instructions
•••••
Symbols Used in the Text • • • • • • • • • • • •
FACTORS TO CONSIDER WHEN USING TAPES •
• •
General Defaults and Restrictions • • • • • • •
Defaults and Restrictions Specific to TOPS-20
Systems • • • • • • • • • • • • • • • • • • • •
F.2.3
Defaults and Restrictions Specific to TOPS-10
Systems • • • • • • • • • • • • • • • • • • • •
F.2.4
Converting Tapes Between Labeled and Unlabeled •
F.3
USING SYSTEM-UNLABELED TAPES •
••••
• •
F.3.1
Tape Has No Labels • • • • •
•
F.3.1.1
Tape Drive Is Available to the User • • • • •
F.3.1.2
Tape Drive Is Owned by the System
• • •
F.3.2
Tape Has Labels • • • •
•••••• • • • •
F.4
USING SYSTEM-LABELED TAPES •
• • • •
F.4.1
Tape Has ANSI Labels
• • • • • •
viii

F-1
F-1
F-2
F-4
F-4
F-4
F-5
F-6
F-6
F-6
F-7
F-7
F-7
F-8
F-8
F-8

October 1985

F.4.l.l
F.4.l.2
F.4.2

Transportable Tapes - F, 0, and S Formats • • F-9
Undefined-Format Tapes - U-Format
F-10
Tape Has EBCDIC Labels • • • • • • • • • • • • F-ll

APPENDIX G

FIPS FLAGGER

APPENDIX H

DEBUG MODULE

H.l
USING THE COBOL-74 DEBUG MODULE
• • • • • •
H.2
SPECIAL REGISTER DEBUG~ITEM
• • • •
• •
H.2.l
Format of DEBUG-ITEM • • • • •
H.2.2
Execution of Debugging Sections • • • • • • • •
H.2.2.l
Debugging on Cd-name • • • •
• • • • • • •
H.2.2.2
Debugging on Identifier
•••••••
H.2.2.3
Debugging on File-name • • • • •
H.2.2.4
Debugging on Procedure Name
H.2.3
Data in DEBUG-ITEM • • • • • • • • • • • • • • •
H.3
LOADING PROGRAMS WITH THE DEBUG MODULE • • • • • •
APPENDIX I

8-1
H-l
H-l
H-3
8-3
H-4
H-4
H-4
8-5
H-7

USING RMS INDEXED FILES

1.1
1.2
1.2.1
1.2.2
1.2.3
1.2.4
1.3
1.4
1.5
1.6
1.7
1.8

DEFINING RMS INDEXED FILES • • • • • •
• • • I-I
PROCESSING RMS INDEXED FILES •
1-3
Opening RMS Indexed Files
• • • • • • • • 1-3
Reading RMS Indexed Files
• • • • 1-3
Writing RMS Indexed Files
• • • • • • • 1-4
Deleting RMS Indexed Records
• • • • • • 1-4
HANDLING ERRORS FROM RMS INDEXED FILES
• • • • 1-4
RUNNING A PROGRAM THAT USES RMS INDEXED FILES • • 1-6
RESTRICTIONS ON THE USE OF RMS INDEXED FILES • • • 1-7
COBOL-74/RMS INDEXED FILE EXAMPLE • • • • • • • • 1-8
USING RMSUTL • • • • • • • • • • • • •
1-20
RMS COMPATIBILITIES WITH BASIC+2 • • • • • • • • 1-22

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

Card-Type Format • • • • • • • • • • • • • •
1-14
Terminal-Type Format with Line Numbers • •
1-16
Terminal-Type Format without Line Numbers
1-17
4-11
Direct Subscripting/Indexing • • • • • • •
Relative Subscripting/Indexing • • • • • • •
4-11
Qualified Direct Subscripting/Indexing • • •
4-12
Picture String Character Chart • • • • • • • • • 4-55
Order of Evaluation of a Conditional Expression
5-13
Order of Evaluation of a Compound-conditional
Expression • • • • .' • • • • • • • • • • • • • •
5-14
PERFORM Cycle Logic - Two Variables
• • ••
5-67
PERFORM Cycle Logic - Three Variables
5-68
COBOL ISAM File Environment
• 7-3
ASCII Recording Mode • • • • • • • • • • • • • • • 8-1
SIXBIT Recording Mode • • • • • • • • • • • • • • 8-2
EBCDIC Recording Mode • • • • • • • •
8-2
EBCDIC Recording Mode - Industry-Compatible • • • 8-2
Binary Recording Mode
• • • • • • • 8-3
Fixed-Length ASCII • • • • • • • • • • •
• • • 8-4

GLOSSARY
INDEX
FIGURES

5-3
5-4
7-1
8-1
8-2
8-3
8-4
8-5
8-6

October 1985

COBOL Fixed-Length ASCII with BEFORE ADVANCING • • 8-5
COBOL Fixed-Length ASCII with AFTER ADVANCING
8-5
Variable-Length ASCII
• • • • • • • • • • • • • • 8-6
COBOL Variable-Length ASCII with BEFORE ADVANCING 8-7
COBOL Variable-Length ASCII with AFTER ADVANCING • 8-8
8-H~ (c) Fixed-Length SIXBIT
• • • • •
• • • • • 8-8.1
COBOL Fixed-Length SIXBIT • •
••• •
• 8-9
8-11
Variable-Length SIXBIT • • • •
• • • • • • • 8-le
8-12
COBOL Variable-Length SIXBIT • •
8-12
8-13
Fixed-Length EBCDIC • • • •
8-13
8-14
COBOL Fixed-Length EBCDIC
8-13
8-15
Variable-Length EBCDIC
• • • • • •
8-14
8-16
COBOL Variable-Length EBCDIC • • •
• • • • 8-15
8-17
8-18
COBOL Blocked Fixed-Length EBCDIC
• • • • 8-16
Blocked Variable-Length EBCDIC
••
• • • • 8-17
8-19
COBOL Blocked Variable-Length EBCDIC • • • • • • 8-19
8-20
8-21
COBOL Standard Binary and ASCII Mixed-Mode Binary 8-20
8-22
COBOL Standard Binary and SIXBIT Mixed-Mode
Binary • • • • • • • • • • • • • • • • • • • • • 8-21
8-23
COBOL Standard Binary and EBCDIC Mixed-Mode
Binary • • • • • • • • • • • • • • • • • • • • • 8-22
Statements Used to Sequentially Access a Relative
8-24
File • • • • • • • • • • • • • • • • • • •
8-26
8-25
ISAM Data File Structure • • • • • • • • •
8-28
8-26
Locating a Record in an Indexed-Sequential File
8-29
8-27
ISAM Index File Structure • • • • • • • •
8-30
9-1
The Problem of Buried Update • • • • • • • • • • • 9-2
The Problem of Deadly Embrace • • • • • • • • • • 9-3
9-2
9-3
Projecting Resources for Simultaneous Update • • • 9-4
9-4
The OPEN Statement • • • • • • • • • • •
• 9-5
9-5
Competing for Program Access to Files
• 9-8
9-6
The RETAIN Statement •
• • 9-9
9-7
The FREE Statement • • • • • • • • • •
9-11
10-1
Report A Format • • • • • • • • • • • •
10-2
10-2
Report B Format • • • • • • • • • • • • • • • •
1e-3
10-3
Input Data File for Report Writer Program
10-4
11-1
Example of an Overlay Structure
11-9
Sample COBOOT Histogram • • • • • • • • • • • • 13-6
13-1
Sample of FIPS Flagging • • • •
G-5
G-1

8-7
8-8
8-9
8-10(a)
8-10 (b)

October 1985

TABLES
3-1
3-2
3-3
4-1
5-1
5-2
5-3
5-4
6-1
C-1
C-2
C-3

Reco rd ing Modes • • • •
3-26
Monitor File Status Bits •
• • • • •
3-33
Moni tor Error Codes
• • • •
3-34
Standard Label for Magtapes • • • • •
4-21
Procedure Verb and Statement Categories
• • 5-3
Types of Segments • • • • • •
• • • • • 5-5
Conditions, Logical Operators, and Parentheses
Combinations • • • • • • • • •
• • • • • • • 5-15
CLOSE Options and File Types •
• • • • • • • 5-31
COBOL Switch Summary. • •
• • • • • • • • 6-3
ASCII and SIXBIT"Collating Sequence and Conversion
to EBCDIC • • • • • • • • • • • • • • • • • • • • C-1
ASCII to SIxaIT Conversion • • • • • • • • • • • • C-3
EBCDIC Collating Sequence and Conversion to ASCII C-5

October 1985

INTRODUCTION TO THE COBOL-74 SYSTEM
AND THE STRUCTURE OF THE MANUAL

The typical COBOL program follows a fairly simple series of steps from
the
human-readable
format
in
which
it
is written to the
machine~readable format in which it is executed.
The following flow
chart shows the basic steps which all programs take.

Introduction-l

Library File (.L1B)
created by LIBARV

COBOL·74
COMPILER

Relocatable (.REL)
Object Module

LINKER

USER PROGRAM

C740TS

Simultaneous
Update

Report
Writer

MA·S'()17·79

The program first sees the light of day as a source file which is
either created with a text editor or entered into the system by some
other means (for example, it could be punched into cards and loaded
through a card reader). This file is usua~ly given a filename whose
extension is .CBL, and it is identified in the flow chart by this
extension.
The COBOL-74 compiler then translates the source file into
a
relocatable object module.
In order to do this, the compiler may
sometimes copy text from user libraries which contain often-used
pieces of code.
These libraries, identified in the chart by the
extension of .LIB, are created by the LIBARY utility. The output from
the compiler, the relocatable object module, is usually given an

Introduction-2

extension of .REL, and is identified by this extension in the flow
chart.
The compiler can optionally produce a file which contains the
compilation listing of the source program. This file is identified by
its extension, ~LST.
At this point the program is given to the system linker, which
produces the executable version with the extension .EXE.
(This manual
does not contain any information on the system linker.
Users of
TOPS-IO should refer to the LINK Reference Manual and the LOAD command
in the Operating System Commands Manual for more information about
LINK.
Users of TOPS-20 should refer to the the LINK Reference Manual
and the LOAD command in the DECSYSTEM-20 user's Guide.)
The .EXE version of the program runs in conjunction with the
object-time system, C740TS.
Among other things,
the object-time
system handles I/O and calls routines from the COBOL-74 library to be
used at runtime.
The user program is now in a format which can be
executed, but there is no guarantee that it will produce the correct
results.
Most programs must still be debugged after they compile
error-free.
The COBOL-74 system provides an on-line
debugging
facility called COBDDT to assist the programmmer in finding out what
the program is really doing. COBDDT runs along with the user program
and the object-time system, and allows the steps which the program
executes to be monitored by the programmer.
Many COBOL programs use indexed files during their execution.
These
files are convenient for many applications.
The COBOL-74 system
provides a program, called ISAM, to create and maintain indexed files.
There are times when the user program is running and the system
operator has to shut down the system unexpectedly. Some programs are
written to be restartable, but many are not.
The RERUN utility is
provided with COBOL-74 to help in this situation. RERUN can save
enough information to allow the program to be restarted after the
system is brought back up, even though no provision was made in the
program for the restart.
Thus, the COBOL-74 system, in conjunction with the operating system,
provides complete facilities for the creation and execution of a COBOL
program. The rules regarding the creation of a COBOL-74 program, and
the syntax to be used in the program,· are described in Part 2,
COBOL-74 Language Reference Material. The individual units of the
COBOL-74 system are enumerated below.
1.

The Compiler The compiler copies text from user libraries and translates
the COBOL-74 program into a relocatable object module.
Running the COBOL-74 compiler is described in Part 3, Chapter
6.

The OTS The object-time system runs the COBOL-74 program and allows
the program to use such facilities as simultaneous update and
Report writer.
Information on the file formats which the OTS
accepts may be found in Part 3, Chapter 8. The simu~taneous
update facility is described in Part 3, Chapter 9, and Report
Writer in Part 3, Chapter 10. Subprograms, segmentation and
overlaying are covered in Part 3, Chapter 11. Chapter 12 of
Part 3 contains information on calling non-COBOL subprograms.

Introduction-3

The utilities The COBOL-74 utilities - LIBARY, COBDDT, RERUN and ISAM - are
described in Part 3, Chapter 7.
Information on the use of
COBDDT in improving the performance of COBOL-74 programs may
be found in Part 3, Chapter L3.

Part 4 of this manual contains appended material which may be of
interest to some users of COBOL-74.
Appendix A presents a list of
differences between DIGITAL's COBOL-68 and
DIGITAL's
COBOL-74.
Appendix B is the list of COBOL-74 reserved words. Appendix C
provides ASCII, SIXBIT, and EBCDIC collating sequences, along with
conversion charts for
these three codes. An alternate to the usual
numeric test, which may be elected at the time of installation of
COBOL-74,
is described in Appendix D.
Finally, Appendix E contains a
short description of the process of defining a logical name for
TOPS-20 users of the COBOL-74 utilities.

Introduction-4

CHAPTER 1
INTRODUCTION TO COBOL-74 LANGUAGE

This chapter describes the symbols, special terms, language elements,
and source program formats acceptable to COBOL-74.
The source
language statements are discussed in subsequent chapters.

NOTE
In this manual the word COBOL
refers
to
COBOL-74.
Any
documentation
concernlng
DECtapes can be ignored if your
system does not have them.

1.1

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 CQBOL
terms.
The single exception to this statement
is
the
term
BIS-compiler.
This term refers to compiler implementations that
compile COBOL-74 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 may 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-74 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. Its basis is the system of symbols used in the
American National Standard and developed by CODASYL.

1-1

INTRODUCTION TO COBOL-74 LANGUAGE
1.1.1.1 underline - The underline is used to denote reserved key
words.
Key words (uppercase underlined words) are required when you
use a function of which they are a part. The absence of an underline
in an uppercase word denotes that the word is optional; you may use
or omit the word at your discretion.
NOTE
Uppercase words, whether underlined
not, must be spelled correctly.

1.1.1.2 Brackets and Braces - When brackets, [], enclose a portion of
a general format, they denote an optional portion that may be included
or omitted as needed. When braces, {}, enclose a portion of a general
format, you must select one of the options within the braces.
Consider the following figure.

[

MEMORY

SIZE

integer

Il ~~=~iCTERS
1J J
MODULES

The brackets indicate that the entire clause is optional. The braces
indicate that a choice of one of the words vertically stacked within
the braces must be specified.
Wherever a choice is required,
stacked either within brackets
example.

the possibilities are vertically
or braces. Consider the following

[LEFT] ]
[{ SYNCHRONIZED}
SYNC
RLGHT
The outside brackets indicate that the entire clause is optional. Th~
braces indicate that if the clause is used, a choice of a word
vertically stacked wi thin the braces must be made. . The inside
brackets indicate that you may optionally select a vertically stacked
word within.
NOTE
When
possibilities
are
vertically
stacked between brackets, you have the
option
of
overriding
a
default
condition.
The default condition is
described in the general rules for the
clause.

1.1.1.3 The Ellipsis - The ellipsis ( ... ) indicates that you may
repeat the item preceding it. The preceding item is usually enclosed
either by brackets or braces to remove any ambiguity as to which item
may be repeated. Consider the following example.
[SAME [RECORD] AREA FOR file-name-l [file-name-2] ••. ] .••
The final ellipsis indicates that the entire clause, if used, may be
repeated.
The initial ellipsis indicates ~hat the item file-name-2
may also be repeated within the clause.

1-2

INTRODUCTION TO COBOL-74 LANGUAGE
1.1.2

COBOL Terms

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

used

Meaning

Block

Signifies a logical grouping of records.
This term
commonly refers to a logical block of records on some
storage medium.
NOTE
The term "block" as defined here does not refer
to a "disk block", which is 128 words of
storage space on a disk.

1.2

1.2.1

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.

ELEMENTS OF COBOL LANGUAGE

program Structure

A COBOL program consists of four divisions. Each division is made up
of source language statements. Some statements are required in every
program; most of them are optional.
Division

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.
1-3

processed
to

INTRODUCTION TO COBOL-74 LANGUAGE

NOTE
The COBOL-74 compiler will recognize
source line numbers up to and including
8184.
If
your
program
(including
library routines) exceeds this maximum,
the compiler will start numbering again
at 0001. Since this causes two or more
lines to have a single line number, you
should exercise caution when debugging
your
program.
The
cross-reference
listing may be confusing. However, the
compiler will generate correct
code
regardless of how many lines are in the
program or how they are numbered in the
cross-reference listing.

1.2.2

COBOL-74 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

CTRL/Z (32(8)), which marks the end-of-file

The compiler translates the lowercase ASCII characters to
characters except when they appear in nonnumeric literals.

uppercase

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 user-defined words, such as data-names, procedure-names,
and identifiers.
The remaining ASCII characters which are acceptable
compiler ar~ listed below.

the

Punctuation characters include:
~

(space)

" or

(quotation mark)

(comma)

(left parenthesis)

(semicolon)

(right parenthesis)

(period)

(horizontal tab)

1-4

COBOL-74

INTRODUCTION TO COBOL-74 LANGUAGE
Special editing characters include:

(plus sign)

(check protection symbol)

(minus sign)

(zero suppression)

(dollar sign)

(blank insertion)

(comma)

(zero insertion)

(decimal point)

(credi t)

(slash)

(debit)

Special characters used in arithmetic expressions include:
+

(addition)

(division)

(subtraction)

(exponentiation)

(multiplication)

(exponentiation)

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

(equal)

(greater than)

(less than)

NOTE
These special
characters
will
not
necessarily
be underlined when they
appear in formats.
For example, an
underlined minus sign might easily be
confused with an equal slgn.
However,
they are usually required items. You
may not omit them, unless you
are
specifically told otherwise.

1.2.3

Words

A COBOL word is a character string which has not more than 30
characters and is either a user-defined word or a reserved word. For
COBOL-74, as for most COBOL compilers, a word may be
either
user-defined or reserved, but not both.

1.2.3.1 Reserved Words - A reserved word is a COBOL word that is one
of a specific list that may be used in COBOL source programs as
specified in the general formats. y'ou cannot use a reserved word as a
user-defined word;
the two types are mutually exclusive.
(See
Appendix B for a complete list of COBOL reserved words).

1-5

INTRODUCTION TO COBOL-74 LANGUAGE
There are six types of reserved words:
1.

Key words
A key word is required when the format in which the word
appea~s IS used in a source program.
within each format, key
words are uppercase and underlined. Consider the following
example.
COMPUTE identifier-l [ROUNDED]

[

identifier-2 [ROUNDED]]

.••

=arithmetic-expression [ ON SIZE ERROR imperative-statement]
In this case, the words COMPUTE, ROUNDED, SIZE, and ERROR are
key words.
2.

Optional Words
Within each format, uppercase words that are not underlined
are optional words included for readability. You may use or
omit these words indiscriminately. The presence or absence
of an optional word does not alter the semantics of the COBOL
program in which it appears. Consider the following example.
LINAGE IS integer-l LINES [WITH FOOTING AT integer-2]
[LINES AT TOP integer-3]
In this case, the words IS, LINES, WITH, and AT are
words.

optional

Connectives
There are three types of connectives:
a.

Qualifier connectives that associate a data-name, a
condition-name, or a text-name with its qualifiers: OF,
IN (See Section 4.7, Qualification.) An example of this
type is
COpy ACTREC OF COBLIB.

Series connectives that link
operands:
separator comma,
example is

two or more consecutive
separator semicolon.
An

GO TO PARTl, PART2 8 PART3 DEPENDING ON COUNTERI.
c.

Logical connectives that are used in the formation of the
following conditions:
AND, OR, AND NOT, OR NOT. An
example is
IF HOURS-WORKED IS GREATER THAN
DEDUCTION-TIME PERFORM PRINT-CHECK.

ZERO

AND

NOT

Figurative Constants
A few specific constant values are used frequently and in
enough different ways to make it useful to hav& names for
them.
The names given to them are called
Figurative
Constants.
These names are reserved words and are listed
below.

1-6

INTRODUCTION TO COBOL-74 LANGUAGE
The values represented by figurative constants are generated
by the compiler and referenced through the use of the
reserved words given, below. These words must not be bounded
by quotation marks when used as figurative constants. The
singular and plural forms of figurative constants
are
equivalent and can be used interchangeably to increase
readability.
The values which the compiler generates for you,
reserved words that name them, are as follows:

and

the

ZERO
ZEROS
ZEROES

Represent the value ~, or one or more of the
character ~, depending on context.

SPACE
SPACES

Represent one or more of the character
"space".

HIGH-VALUE
HIGH-VALUES

Represent one or more of the character that
has the highest ordinal position
in
the
character set's collating sequence (in ASCII
code, this is octal 177).

LOW-VALUE
LOW-VALUES

Represent one or more of the character that
has the lowest ordinal
position
in
the
character set's collating sequence (in ASCII
this is octal ~~0).

QUOTE
QUOTES

Represent
one
or more occurrences of the
quote character, usually'"' (double quote).

ALL literal

Represents one or more repetitions of the
string of characters that compose the literal.
The literal must be either an alphanumeric
literal or a figurative constant other than
ALL. The ALL literal cannot be associated with
a numeric or numeric edited item.
When a
figurative constant is used, the word ALL is
redundant and is optional. You can use it for
readability if you wish.

Frequently a figurative constant represents a string of
characters whose length is not explicitly stated. When this
happens, the compiler determines ·the length of the string
from context. The figurative constant can be associated with
another data item by the context, as in the following
statements:
MOVE SPACES TO WORK-RECORD
IF AMOUNT-OWED EQUALS ZERO PERFORM CLOSE-ACCOUNT
Alternatively, the figurative constant can
with no relation to any data item, as in:

stand

itself

DISPLAY "BALANCE IS" ZERO
STRING DAY-CODE, SPACE, "_H, SPACE, MONTH-CODE
DELIMITED BY SIZE INTO DSPLY-DATE

1-7

October 1985

INTRODUCTION TO COBOL-74 LANGUAGE
In cases where the figurative constant is associated with a
data item, the compiler assumes that the string of characters
represented by the figurative constant has the same number of
characters as the associated data-item. In the case of (the
figurative constant) ALL literal, the literal is repeated
from left to right and truncated on the right, if necessary.
Thus, if WORK-RECORD in the above example contains 128
characters, the figurative constant SPACES represents a
string of 128 spaces. If AMOUNT-OWED is an eight-character
numeric field with two decimal places, ZERO represents the
value 000000.00. In the following example:
MOVE ALL "ABC" TO HOLD-AREA
If HOLD-AREA is a ten-character
contents after the MOVE is:
ABC

ABC

alphanumeric

field,

its

If you associate a JUSTIFIED clause with the data item, the
character repetition and truncation takes place before any
justification.
When the figurative constant is not associated with a data
item, as in the second set of examples above, the length of
the character string is the length of the literal, or one
occurrence of the literal in the case of ALL literal. This
is true even if you use the plural form instead of the
singular. That is, all of the following statements cause the
.;ame display:

DISPLAY ZERO.
DISPLAY ZEROS.
DISPLAY ALL ZEROS.
In each case, one zero is displayed.
A figurative constant can be used whenever a literal appears
in a format.
However, if the literal is restricted to
numeric characters, the only figurative constants permitted
are
ZERO
(ZEROS, ZEROES), LOW-VALUE (LOW-VALUES), and
HIGH-VALUE (HIGH-VALUES).
Each reserved word that is used to reference a figurative
constant value is a distinct character string with the
exception of the construction ALL literal, which is composed
of two distinct character strings.
5.

Special Registers
COBOL-74 recognizes four reserved words as special registers:
DAY, DATE, TIME, and LINAGE-COUNTER. All special registers
have implied data descriptions of
unsigned
elementary
integers.
The lengths of DAY, DATE, and TIME are fixed; the
length of LINAGE-COUNTER depends upon the file description
statement that generates the register.
DAY is five digits long. Its value represents the number
the current day of the year. Its format is:

YYDDD
where

YY is the year of the century, and
DDD is the number of the day of the year.
1-8

October 1985

INTRODUCTION TO COBOL-74 LANGUAGE
DATE is six digits long.
date. Its format is:

Its value

represents

the

current

YYMMDD
where

YY is the year of the century,
MM is the number of the month, and
DD is the number of the day.

TIME is eight digits long. Its value represents the current
elapsed time since midnight on a twenty-four-hour basis.
Its
format is:
HHMMSShh
where

HH is the hours,
MM is the minutes,
SS is the seconds, and
hh is the 1/100ths of a second.

DAY, DATE, and TIME may be accessed by ACCEPT statements in
the Procedure Division.
See Section 5.9.1 for the correct
format to use with the ACCEPT verb.
The LINAGE-COUNTER special register is generated whenever the
file description of a sequential file includes the LINAGE
clause. The contents of a LINAGE-COUNTER represent the
current line number within the current page of output. The
contents of a LINAGE-COUNTER are updated automatically by
WRITE statements referring to the associated sequential file.
The LINAGE clause and LINAGE-COUNTER are fully explained in
Section 4.9.31.
6.

Special-Character Words
The arithmetic operators +, -, *, I, **, A, and the relation
characters <,), and = are special-character reserved words.

1.2.3.2 User-Defined Words - A user-defined word is a COBOL word
which is supplied by the user to satisfy the format of a clause or
statement. The characters which may be used to form user-defined
words are the letters of the alphabet, the digits 0 through 9, and the
hyphen. The hyphen may not be used as the first or last character in
the user-defined word.
There are 17 types of user-defined words:
1.

alphabet-name

cd-name

condition-name

data-name

1-9

INTRODUCTION TO COBOL-74 LANGUAGE
5.

file-name

index-name

level-number

library-name

mnemonic-name

10.

paragraph-name

11.

program-name

12.

record-name

13.

report-name

14.

routine-name

15.

section-name

16.

segment-number

17.

text-name

Each of these user-defined word types is
which appears at the end of this manual.

1.2.4

described

the

Glossary

Literals

A literal is a character string whose value is determined by the
ordered set of characters of which it is composed. You can also use a
figurative constant as a literal. There are two types of literals:
numeric and alphanumeric.

1.2.4.1 Numeric Literal - A numeric lit~ral is a character string of
from 1 to 20 characters selected from the digits 0 through 9, the plus
sign, the minus sign, and the decimal point.
The rules for the
formation of numeric literals are as follows:
1.

A literal must contain at least 1 digit and no more
digits.

than

A literal must not contain more than one sign character.

A literal must not contain more than one decimal point.
The
decimal point is treated as an assumed decimal point, and may
appear anywhere within the literal except as the rightmost
character.
If the literal contains no decimal point, the
literal is considered an integer~

If
a sign is used, it must appear as the leftmost character of
the literal. If the literal is unsigned, it is considered
positive.

NOTE
The word integer, appearing in a
represents a nonnegative numeric
decimal point.
1-10

general
literal

format,
with no

INTRODUCTION TO COBOL-74 LANGUAGE
If a literal conforms to the rules for the formation of
numeric literals but is enclosed in quotation marks, it is
considered an alphanumeric literal and is treated as such by
the compiler.
4.

The value of a numeric literal is the algebraic quantity
represented by the characters in the numeric literal. Every
numeric literal is category numeric.
(See Section 4.10.16,
The PICTURE Clause.) The size of a numeric literal is equal
to the number of digits specified by the user, including
leading zeros, if any.

1.2.4.2 Alphanumeric Literals - An
alphanumeric
literal
is
a
character string representing from 1 to 120 characters, delimited on
both ends by quotation marks and consisting of any allowable character
in the computer's character set. An opening quotation mark must be
immediately preceded by a space or left parenthesis.
A closing
quotation mark must be immediately followed by one of the separators
(space, comma, semicolon, or right parenthesis) or by the terminator,
period.

NOTE
You may use either the single quote
character (') or the double quote (").
Whichever one you use, you must be sure
to pair them correctly - do not try to
pair a single quote with a double quote
or vice versa.
To represent one quotation-mark character within an alphanumeric
literal, two contiguous quotation marks must be used. The value of an
alphanumeric literal in the object program is the string of characters
itself, except that:
1.

The delimiting quotation marks are excluded, and

Each embedded pair of contiguous quotation marks represents a
single quotation mark character.

All other punctuation
alphanumeric literal,
category alphanumeric.

characters are part of the value of the
not separators. All alphanumeric literals are
(See Section 4.9.18, The PICTURE Clause.)

Separators

1.2.5

A separator is a string of one or more
rules for forming separators are:
1.

punctuation

characters.

The

Space
a.

Anywhere a space is used as a separator,
space may be used.

A space may immediately precede all separators except the
closing quotation mark.
Here the space is considered
part of an alphanumeric literal, hot a separator.
1-11

than

one

INTRODUCTION TO COBOL-74 LANGUAGE
c.

A space may immediately follow any separator except the
open quotation mark. In this case, a following space is
considered part of an alphanumeric literal, not
a
separator.

Comma and Semicolon
The punctuation characters, the comma and semicolon, are
separators.
You may insert these separators only where
explicitly permitted by the general formats, by format
punctuation rules, by statement and sentence definitions, or
by source program format rules.

Right Parenthesis and Left Parenthesis
Right parenthesis and left parenthesis are separators only
when used in balanced pairs to delimit subscripts or indexes.

Quotation Marks
Quotation marks may be used only in balanced pairs to delimit
alphanumeric literals or in adjacent pairs to pass one
quotation mark in an alphanumeric literal.
(See
note
concerning quotation marks in Section 1.2.4.2, Alphanumeric
Literals.)

Horizontal Tab
The horizontal tab character is governed by the same rules
that govern the space character.
It is normally used to
vertically align statements or clauses on successive lines of
the source program listing. The compiler, upon encountering
a tab character, generates one or more space characters
consistent with the tab character position in the source
line.

Pseudo-text Delimiter
Pseudo-text delimiters set off textual matter in the COpy
statement from the rest of the sentence. Each delimiter
consists of two contiguous equal signs (==).
The opening
pseudo-text delimiter must be immediately preceded by a
space; the closing delimiter must be immediately followed by
one of the separators space, comma, semicolon, or period.
These delimiters may appear only in balanced pairs delimiting
pseudo-text.

NOTE
There are certain rules for writing
source programs which supersede these
general rules.
For a discussion of
source program formats see Section 1.3.

1-12

INTRODUCTION TO COBOL-74 LANGUAGE
1.3

SOURCE PROGRAM FORMAT

There are two basic types of source program formats in which you may
write your COBOL-74 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-74 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 erograms which are
to be entered into the system through a terminal uSlng a text editor.
The compiler will assume 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 Appendix C).
Certain margins which begin the areas used for writing COBOL-74
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 marglns 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 1974 ANSI
standard for source program formats.
Programs written according to the rules
will be more readable and transportable.
The COBOL-74 compiler, however, does not
do complete syntax checking to determine
if you have followed all rules, and will
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 may 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 will assume 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
may simply write the first line, then continue on the next
line; do not use the continuation column for this purpose.
1-13

INTRODUCTION TO COBOL-74 LANGUAGE
2.

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

NOTE
All formats may 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
may 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 the user. The layout of a line in this format is shown in
Figure 1-1. The numbers refer to card columns or character positions.

CARD·TYPE FORMAT
6 7

z;
L

~
B

V
I

~
MR·S.o18·79

Figure 1-1 (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 between 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 the user who creates the file on a terminal or
a card punch.

Debug Lines - You may insert debug lines into your program by
putting a "0" in the continuation area (column 7). The
compiler will recognize it and print it on the source listing
with the spacing similar to a comment line.

1-14

INTRODUCTION TO COBOL-74 LANGUAGE
In this format, Margin L is to the left of position 1 and Margin R is
to the right of position 8~. Margin A is between 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 you create the file on a terminal or a
card punch.

Continuation Area - If you wish to use the continuation area,
type one of the following characters as the first character
of the continued line:
•

Hyphen (-) - Specifies that this is a continuation of the
previous line.

•

Asterisk (*) - Specifies that the line is a comment.
compiler ignores the line.

•

Slash (I) - Specifies a page change in the listing file.
The page change is numbered as a sub-page and is
incremented by 1.

The

Debug Lines - You can insert debug lines into your program by
putting a "0" in the continuation area (column 7). The
compiler recognizes it and prints it on the source listing
with the spacing similar to a comment line. However, with
the terminal-type format (Section 1.3.2), it is not possible
to determine if the "0" is in the continuation area or in
column 7. Therefore, the "\0" can be used instead.

Identification Area - This area is marked I in the figure
(positions 73 through 8~). These eight character positions
can hold identifying information that 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).
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-74
when you specify card-type format.

The examples in Figure I-I (b) illustrate these rules. The first two
lines are simple statements, with a line number in area L, COBOL-74
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-15

October 1985

INTRODUCTION TO COBOL-74 LANGUAGE
1.3.2.1 With Line Numbers - This format is suitable if you use a
line-oriented editor such as EDIT or SOS. The format is shown in
Figure 1-2(a). format is shown in Figure 1-2(a).
TERMINAL-TYPE

FORMAT
6

- WITH
8

LINE

NUMBERS

122

==========I==I=============~====:I~~(------------~

"--......---...v,.------/ -.--v-~"---------y--------MR-_S-_9-66--;:
Z

Figure l-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.
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 - If you wish to use the continuation area,
type one of the following characters as the first character
of the continued line:
•

Hyphen (-) - Specifies that this a
previous line.

continuation

the

•

Asterisk (*) - Specifies that the line is a comment.
compiler ignores the line.

The

•

Slash (I) - Specifies a page change in the listing file.
The page change is numbered as a sub-page and is
incremented by 1.

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.
4.

Debug Lines - Debug lines can be inserted in your program
with this format if you type "\0" (backslash D) as the first
two characters on the line. If you use "D" as in card-type
format, the compiler reads the "D" as the first character of
a word beginning in area A.

The
The examples in figure 1-2(b) illustrate the use of this format.
first two lines are simple COBOL-74 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-16
October 1985

INTRODUCTION TO COBOL-74 LANGUAGE
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_ _ _ _ _ _ _ _ _ _ _ _ _ _

,~J

. .--------....'V.-. . .------. . .

______________

--~~

I~c

__________________

C A R

Figure 1-3(a):

122

________________

MR-S-967-81

Terminal-Type Format without Line Numbers

In this format, margin L is to the left of position ~, if it exists,
or position 1, if position ~ 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.
The following rules pertains to the use of this source format:
1.

Continuation Area - If you wish to use the continuation area,
type one of the following characters as the first character
of the continued line:
•

Hyphen (-) - Specifies that this is a continuation of the
previous line.

•

Asterisk (*) - Specifies that the line is a comment.
compiler ignores the line.

The

(I) - Specifies a page change in the listing file.
• Slash
The page change is numbered as a sub-page and is
incremented by 1.
If the compiler finds one of these characters at the
beginning of a line it assumes that the line has a position ~
- in other words, a continuation area. Otherwise, each line
starts in position 1 and there Is no position ~.
2.

Debug Lines - Debug lines can be inserted into the program.
To do this type a
"\D"
(backslash D)
as the first two
characters on the line.

The examples in Figure l-3(b)
show this format's simplicity.
The
first two lines are the same simple COBOL-74 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-17

October 1985

II _

TA XA er- TG
TA XA ee TG

00 10 00 PR OC ES S- TA X.
00 10 10
MO VE iTH IS -P ER 10 OS -T AX TO TA X- PA 10.

, SP PC E, T-10 S!T -R EC EN T- OA Y,
TA XA CC TG
ST RI NG 1f'J0 ST -R EC EN T- M NT H, SP AC E ,
, SP lAic E, IMO ST -IR EC EN T- YE AIR DE LI tJ I ITE BY SI ZE IN TO 01 SP LT AX AC eTG
SP AC E,
AY -0 AT E.

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

II _

MR-S-1494-81

Figure 1-1 (b)
H

1-3

o
c

()

00 lPP
00 llb
.....
I

.....

ex>

00 120
00 1 3o ~.~

1-3

PR pC E~ S~ TA X.
MO VE TH IS -P ER 10 O~ -T AX ~

TA X PA 10.

1-3

ST RI NG IMO ST -R EC EN IT - MO Nrr ,S PA CE, - ,S PA CE ,M O~ T- R. . eE NT -0 ~~ ,S PA CE ,
AC E, MO SIT -R EC EN T- YE IAR DE 1M IT ED BY S I ZE IN TO 01 SP AY -0 Arr '"" .
II

,S P

M R-S-1495-81

Figure 1-2 (b)

II _

SP Alc E ~.~ 0S
MR-S-1496-81

Figure 1-3 (b)

I
~

PB oe ES Is - TIA 'X .
Ir~ IvlE ITH IS - ~ IE R110 ID 1-11 IA X ITlo ITIA x- PiA Ilc.
II

otJj

~~".-

~Ie_.

,S PiA IC E,M Ie SIT - RE CE N1 -0 AY ,S PA CE
SiT ~ I NIG I~ 0S[1 -R EIC EI~ -M 10 N iH ,S piP CE ,
[1- RE lelE I~ T-I~ EA R DIE LI rn TEe BY S I LE IN TO Ie I SP IL AI~ - Dip TE.

()

INTRODUCTION TO COBOL-74 LANGUAGE
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-74 Usage Material, Part 3 of this manual.)
The COpy
statement may also be used to replace specified text in the source
text being copied.
General Format

COpy text-name

[{~~} library-name]
==pseUdo-text-l==j

REPLACING

i~entifier-l

==pseUdo_text_2==j}
identifier-2
literal-2
...
word-2

llteral-l
word-l

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.

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.

1-19

INTRODUCTION TO

COB~L-74

LANGUAGE

The COPY statement must be p~eceded by a space and terminated
by the separator period.
Th~ entire statement, including the
per iod, will be removed when: the text is copied from the
library.

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

String-2 may be nUll.

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

A COPY statement may occur in the source program anywhere a
character-string or a separator may 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 replaci~g the entire COPY statement,
beginning with the reserv~d word COpy and ending with the
punctuation character periodl, inclusive.
The compilation of
a source program containipg COpy statements is logically
equivalent to processing all' COpy statements prior to the
processing of the resulting ~ource program.
For clarity, use
the double equal sign (==) a~ound string-l and string-2 to
designate clearly the stri~g 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 npt specified, the library text is
copied unchanged.
If the R~PLACING phrase is specified, the
library text is copied and ebch properly matched occurrence
of
string-l
in the lib~ary text is replaced by the
corresponding string-2.
'

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

Any separator comma, sem~colon, and/or space(s) preceding
the leftmost library te~t-word is copied into the source
program.
Starting with ~he leftmost library text-word
and
the first string~l that was specified in the
REPLACING phrase, the ertire REPLACING phrase operand
that precedes the res~rved word BY is compared to an
equivalent number of con~iguous library text-words.

String-l matches the lib~ary text if, and only if,
the
ordered sequence of t~xt-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 i~ considered to be a single space
except when string-l ~onsists solely of
either
a
separ a tor
comma
or : semicolon,
in wh ich case it
participates in the matc~ as a text-word.
Each sequence
of one or more space: separators is considered to be a
single space.

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.
1-20

January 1980

INTRODUCTION TO COBOL-74 LANGUAGE

19.

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
of one or more space separators is considered to be a
single space.

If no match occurs, the comparison is repeated with each
next successive string-l, 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 replace entire
data names.
You cannot replace parts of data-names. For
example, to replace REPORT-ACCT-NO with OUTPUT-ACC-NO, you
must specify:
REPLACING ==REPORT-ACCT-NO== BY ==OUTPUT-ACCT-NO==.
Thus, replacing REPORT- by OUTPUT- produces an error message.

11.

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

1-21

October 1985

INTRODUCTION TO COBOL-74 LANGUAGE
12.

Debugging lines are permitted within library text
and
string-2. Debugging lines are not permitted within string-I;
text-words within a debugging line participate in
the
matching rules as if the '0' did not appear in the indicator
area. If a COpy statement is specified on a debugging line,
then the text that is the result of the processing of the
COPY statement also appears as though it were specified on
debugging lines with the following exception: comment lines
in library text appear as comment lines in the resultant
source program.

13.

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

14.

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.

15.

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.

16.

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

1-22

CHAPTER 2
THE IDENTIFICATION DIVISION

The Identification Division is required in every source program.
It
identifies the source program and the output from compilation.
In
addition, it may contain 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

{ ffiENT! Fl CATION} DI VISION.

program-name.]

[PROGRAM-ID.

comment-entry

[ AUTHOR.

...

[INSTALLATION.

comment-entry

...J

[DATE-WRITTEN.

comment-entry

..]

~DATE-COMPILED.

comment-entry

...J

[SECURITY.

corrrnent-entry

...]

Technical Notes
1.

The Identification Division must begin with the reserved
words IDENTIFICATION DIVISION followed by a period and a
space. Note that in COBOL-74 the reserved word 10 may be
substituted for IDENTIFICATION in the division header.

The PROGRAM-ID paragraph contains the name identifying the
program. The program-name may 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.

2-1

THE IDENTIFICATION DIVISION
3.

The remaining paragraphs are optional and, if used, may
appear 1n any combination and 1n 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 which will
be replaced by the current date. Reserved words can be used
in any comment paragraph.

2-2

THE IDENTIFICATION DIVISION
GENERAL FORMAT FOR IDENTIFICATION DIVISION
ID
t
{ IDENTI FI CA TI ON " D1 VI S I ON.

pro gram- name

[ PROGRAM- I D.
[AUTHOR.

comment-entry

.J
..

~INSTALLAT10N.

comment-entry

~DATE-WRITTEN.

comment-entry

.. .J
.. ]

~DATE-COMPILED.

comment-entry

...]

[SECURITY.

corrment-entry

'.J

2-3

CHAPTER 3
THE ENVIRONMENT DIVISION

The Environment Division allows you to describe the particular
computer configurations you wish to use for program compilation and
execution. In this division you also specify the files and devices
you will use for input and output. The clauses used to do these
things are presented on the following pages.

3-1

THE ENVIRONMENT DIVISION

CONFIGURATION SECTION
3.1

ENVIRONMENT DIVISION CLAUSE FORMATS

3.1.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.2)

OBJECT-COMPUTER.

(See Section 3.1.3)

SPECIAL-NAMES.

(See Section 3.1.4)

Technical Notes
1.

This section is optional.

All commas and semicolons
terminate the entire entry.

3-2

are

optional.

period

must

THE ENVIRONMENT DIVISION

SOURCE-COMPUTER
3.1.2

SOURCE-COMPUTER

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

the

computer

which

the

General Format
SOURCE-COMPUTER.

computer-name [WITH DEBUGGING MODE]

Technical Notes
1.

This paragraph is optional.

Computer-name must be one of
the
DECSYSTEM-20, PDP-lO, or PDP-integer-l.
the range 1000 to 1099.

If the WITH DEBUGGING MODE clause is specified, all debugging
lines are compiled.
If it is not specified all debugging
lines are treated as if they were comment lines.
In either
case all USE FOR DEBUGGING statements are compiled as if they
were comments. This is because COBDDT accomplishes what is
otherwise done with debugging statements.

list
DECsystem-lO,
Integer-l must be in

Examples
SOURCE-COMPUTER. DECSYSTEM-l055.
SOURCE-COMPUTER. DECSYSTEM-20 WITH DEBUGGING MODE.

3-3

THE ENVIRONMENT' DIVISION

OBJECT -COMPUTER

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

the

computer

which

the

General Format

OBJECT-COMPUTER.

computer-name
WORDS
CHARACTERS }]
{ MODULES

[MEMORY SIZE integer

[PROGRAM COLLATING SEQUENCE IS alphabet-name]
[SEGMENT-LIMIT ~ segment-numbe~

i}] .

[ 0 I S PLAY I S DIS PLAY -{

Technical Notes
1.

This paragraph is optional.

Computer-name must be one of the
following:
PDP-lO,
PDP-integer-l, DECsystem-lO, or DECSYSTEM-20.
Integer-l must
be a number in the range 1000 through 1099.
The number
specified is for documentary purposes only and has no direct
bearing on the object code generated by the compiler.
If the
compiler was installed to take advantage of the KL central
processing unit's Business Instruction Set
(BIS),
the
BIS-code will be generated automatically.
(See the COBOL-74
Installation Procedures.)

The optional MEMORY SIZE clause specifies the maximum memory
size of SORT's work area during a SORT operation.
If the
MEMORY SIZE clause 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)

COBOL-74 presently ignores the MEMORY SIZE clause.
SORT will
use its default algorithms to determine the amount of memory
needed to execute a sort.
(Refer to the SORT User's Guide
for more information.)
version 12A

3-4

January 1980

THE ENVIRONMENT DIVISION

OBJECT-COMPUTER (Cont.)
4.

The PROGRAM COLLATING SEQUENCE clause specifies a collating
sequence for a program. When you use the PROGRAM COLLATING
SEQUENCE clause the collating sequence is the one associated
with
alphabet-name.
When you do not use the PROGRAM
COLLATING SEQUENCE clause the collating sequence is ASCII.
The program collating sequence determines:
1.

The
results
of
explicit
comparisons
relation-conditions and in condition-name conditions

The results of implicit comparisons in CONTROL clauses of
report description entries

MERGE
The order of records processed by SORT and
statements
which
do not specify another collating
sequence with the COLLATING SEQUENCE phrase

The values of the
LOW-VALUE

figurative

constants

HIGH-VALUE

and

(See the alphabet-name IS clause in the
SPECIAL-NAMES
paragraph for
information on how to associate a collating
sequence with alphabet-name.)
5.

If you use the SEGMENT-LIMIT clause, only those segments
having segment numbers from 0 up to but not including the
value of integer-3 are treated as resident segments of the
program.
Integer-3 must be a positive integer in the range 1
to 49.
If you omit the SEGMENT-LIMIT clause, 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 Sections 5.3 and 11.1.

The DISPLAY clause is optional.
If you include it in your
program,
the compiler uses the DISPLAY type you specify as
the default in determining the recording mode for external
files and for
items described in the Data Division as
DISPLAY. This allows you to change the default usage inside
the program without using compiler switches. The effect of
specifying DISPLAY IS DISPLAY-9 is the same as that of
including a IX switch in the command string to the compiler.
However, the IX switch always overrides the DISPLAY clause.
For example,
if you include in your program the following
statement
DISPLAY IS DISPLAY-7
all items described in the Data Division as USAGE IS
are considered DISPLAY-7 items.

Example
OBJECT-COMPUTER. DECSYSTEM-I077
MEMORY 50000 WORDS
PROGRAM COLLATING SEQUENCE IS NATIVE
SEGMENT-LIMIT IS 35
DISPLAY IS DISPLAY-7.
3-5

DISPLAY

THE ENVIRONMENT DIVISION

SPECIAL-NAMES
3.1.4

SPECIAL-NAMES

Function
The SPECIAL-NAMES paragraph provides a means of assigning mnemonic
names to input/output devices, code sets, and collating sequences.
This paragraph can also define the character used as a currency sign,
and can specify the interchange of decimal point and comma functions
in the program.
General Format
[SPECIAL NAMES.
[CHANNEL

[CONSOLE IS mnemonic-name-l]
(m)

[CHANNEL

mnemonic-name-2]

(n)

mnemonic-name-3

IS mnemonic-name-4

[ON

••• ]

STATUS IS condition-name-l]

[Q££ STATUS IS condition-name-2]
ON

STATUS IS condition-name-l

SWITCH(m)
[OFF
OFF

STATUS IS condi tion-name-2]

STATUS IS condition-name-2
[ON

STATUS IS condition-name-l]

STANDARD-l
NATIVE
ASCII
EBCDIC
literal-l [

{i~:~UGH} literal-2

ALSQ literal-3 [~ literal-4] •••

alphabet-name IS

[

literal-S [{r}"literal-6
ALSO l1teral~7 [.8J....SQ 1iteral-8] ...

Oiteral-9 IS mnemonic-name-4]
[CURRENCY SIGN IS literal-lO]
[DECIMAL POINT IS COMMA]

.!.]

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.
3-6

October 1985

THE ENVIRONMENT DIVISION

SPECIAL-NAMES (Cont.)
3.

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 skips to the top of the

IF LINE-COUNT IS GREATER THAN 50 WRITE PRINT-RECORD
BEFORE ADVANCING TOP-OF-PAGE.
4.

The alphabet-name IS clause associates a user-specified name
with a sequence of characters that can be used as a character
code set, a collating sequence, or both.
This character
sequence can be either one of the two sequences provided by
the compiler or a sequence specified by you.
A character
code
set
is
specified
by
referencing
alphabet-name in the CODE-SET clause of a file description.
When defining a character code set, the alphabet-name IS
clause is restricted to STANDARD-l, NATIVE, ASCII, or EBCDIC.
A
collating
sequence
is
specified
by
referencing
alphabet-name either in the PROGRAM COLLATING SEQUENCE clause
of the OBJECT-COMPUTER paragraph or in the COLLATING SEQUENCE
phrase of a SORT or MERGE statement.
When STANDARD-lor ASCII appears in an alphabet-name IS
clause,
the character code set and collating sequence
specified is ASCII. When EBCDIC appears in an alphabet-name
IS clause, the character code set and collating sequence
specified is EBCDIC.
When NATIVE appears, the character code set is ASCII.
However, if the DISPLAY mode specified is DISPLAY-9, the
character code set is EBCDIC.
When a literal phrase appears in an alphabet-name IS clause,
the literals define an ascending collating sequence in the
order of their appearance in the phrase.
Numeric literals
represent the ordinal number of the character within the
ASCII character set and must be in the range from 1 through
128.
Nonnumeric literals in an alphabet-name IS clause
represent themselves.
The ordinal number of an
ASCII
character is 1 greater than its ASCII value. If the literal
contains multiple characters, they are assigned successive
ascending positions within the collating sequence, starting
with the leftmost ·character. Characters whose positions are
not explicitly defined by the literal phrase are assigned
positions higher than the specified characters and in their
normal ASCII sequence.

3-7

THE ENVIRONMENT DIVISION

SPECIAL-NAMES (Cont.)
When you specify the THROUGH phrase, the set of contiguous
ASCII characters beginning with the character specified by
literal-l and ending with the character
specified
by
literal-2' are assigned successive ascending positions in the
collating sequence. The characters specified by a THROUGH
phrase can be in either ascending or descending order.
When you specify the ALSO phrase, the characters specified by
literal-I, literal-3, literal-4, ••• , are all assigned to the
same position in the collating sequence.

The character that has the highest ordinal position in the
program collating sequence is associated with the figurative
constant HIGH-VALUE for the character code set that you
specify.
For example,
in SIXBIT, the underscore ( ) is
equivalent to HIGH-VALUES.
If more than one character- has
the highest position in the program collating sequence, the
last character specified is associated with the figurative
constant HIGH-VALUE.

The character that has the lowest ordinal position in the
program collating sequence specified is associated with the
figurative constant LOW-VALUE for the character code set that
you specify. For example, in SIXBIT, the space is equivalent
to LOW-VALUES.
If more than one character has the lowest
position
in the program collating sequence, the first
character specified is associated with
the
figurative
constant LOW-VALUE.
5.

The clause literal-9 IS mnemonic-name-4 specifies the CODE
value for a particular report (refer to the CODE clause in
Section 4.9.26). Literal-l must be an alphanumeric 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, you must use the literal you specify (instead of
the $ character) in PICTURE clauses in the Data Division.
For instance,
if you wish to insert a currency sign at the
front of a field which is to be printed on your report, you
must use the literal you specified - not the $ character - as
the editing symbol.
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, 0, L, 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.

3-8

October 1985

THE ENVIRONMENT DIVISION

INPUT-OUTPUT SECTION
3.1.5

INPUT-OUTPUT SECTION

The Input-Output Section names the files and external media required
by
the
object
program and provides
information required
for
transmitting and handling 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.1.6)

I-O-CONTROL.

(See Section 3.1.15)

Technical Notes
1.

This section is optional.

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

3-9

THE ENVIRONMENT DIVISION

FILE-CONTROL

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

the

file

General Format

FORMAT 1:
SELECT

[OPTIONAL]

fi le-name

ASSIGN TO device-name-1
[RE SER VE i nteger-l

[device-name-2]

[~~~~sJ]

[ORGANIZATION IS SEQUENTIAL [CHECKPOINT OUTPUT]
[ACCESS MODE IS

SEQUENTIA~

ASCII

SfXi3IT
RECORDING

MODE IS [arrr MQDiJ

BINARY

'i.
STANDARD-ASCII
STANDARD ASCII

[DENSITY IS

(gill}]

[PARITY IS

FILE-STATUS)
STATUS IS data-name-1 [ data-name-2 [ data-name-3 [ data-name-4
[( FILE

[data-name-5 [data-name-6 [data-name-7 [data-name-s]]JJJJJ]

Version l2A

3-10

January 1980

~HE

ENVIRONMENT DIVISION

FILE-CONTROL (Cont.)

FORMAT 2:
SELECT file-name
ASSIGN TO device-name-l [device-name-2]

[AREA
.
AREAS
[ RESERVE lnteger-l

ORGANIZATION IS RELATIVE [WITH CHECKPOINT OUTPUT [EVERY integer-l RECORDS]]

SEQUENTIAL RELATIVE KEY IS data-name-1IJ
ACCESS MODE IS {RANDOM }
DYNAMIC
RELATIVE KEY IS data-name-l

ASCII }
SIXBfT
~INARY

RECORDING MODE IS
{

•
fFILE-STATUSj
[ \FILE STATUS

IS data-name-l [data-name-2 [data-name-3 [data-name-4

[dat a- n ame- 5 [d at a- name - 6 [d at a- name- 7 [d at a- name- 8]]]]]]]J
MR-S-12S4-81

3-11

THE ENVIRONMENT DIVISION

FILE-CONTROL (Cont.)

FORMAT 3:
SELECT fi le-name
ASSIGN TO device-name-l [device-name-2]
[AREA
.
[ RESERVE lnteger-l AREAS

L l

ORGANIZATION IS [RMS] INDEXED fWITH 'CHECKPOINT OUTPUT [EVERY integer-l RECORDS]t"l
DEFERRED OUTPUT

SEQUENTIAL
ACCESS MODE IS { RANDOM
DYNAMIC

RECORD KEY IS data-name-l

[ALTERNATE RECORD KEY IS data-name-l [WITH DUPLICATES]] ...
SiXiITT }
'{ASCII

RECORDING MODE IS fNARY

F I LE- STAT US
[{ FILE STATUS

IS data-name-l [data-name-2 [data-name-3 [data-name-4

[data-name-5 [data-name-6 [data-name-7 [data-name-s]]]]J]]]

3-12

October 1985

THE ENVIRONMENT DIVISION

FILE-CONTROL (Cont.)
Technical Notes
1.

This section is optional.

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

The SELECT and ASSIGN statements must appear before any other
clause shown, and the SELECT statement must precede the
ASSIGN statement.
Every file described in the Data Division
must be named in a SELECT clause in the Environment Division.
Thus, the following clause must be specified for
every such
file:
SELECT file-name ASSIGN TO device-name.

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

3-13

Each

SELECT

following

clause

pages

THE ENVIRONMENT DIVISION

SELECT

3.1.7 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 file-name

ASSIGN TO

Jliteral-l
}
\device-name-l

,literal-2
]
[ ,device-name-2

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 your program tries to open a file which you have
declared to be OPTIONAL, the question IS file-name PRESENT?
is typed on the operator's console 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 will immediately take the AT
END or INVALID KEY path.
NOTE
ISAM files may not be optional. They must be present
at program start-up, even if only as dummy files.
(Refer to the COBOL-74 Usage Material, Part 3 of this
manual, for more information on ISAM.)

The ASSIGN clause specifies the device
for
a
file.
Device-names can be either physical device-names or logical
device-names.
Physical device-names are fixed mnemonic-names that refer to
specific peripheral devices.
When specified in an ASSIGN
clause, a physical devi~e-name assigns the associated file to
that device.
Physical device-names are described in the
TOPS-IO Operating System Commands Manual and the TOPS-20
User's Guide.

Version 12A

3-14

January 1980

THE ENVIRONMENT DIVISION

SELECT (Cont.)
Logical device-names are names created by the programmer.
They can contain up to six characters, and can consist 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 a monitor command (refer to the COBOL-74
Usage Material, Part 3 of this manual, for an explanation of
the commands).
4.

Using a literal with the ASSIGN clause enables you to use
COBOL reserved words as legal device names. The literal name
must follow the same conventions as the device-name.
The
literal name can contain up to six characters, and can
consist of any combination of letters and digits. At object
execution time, each name must be assigned to a physical
device by means of a monitor command (refer to the COBOL-74
Usage Material, Part 3 of this manual, for an explanation of
the commands).

You may assign more than one device to a file to avoid delay
when switching from one reel or unit to the next. When you
specify more than one device the object program automatically
uses the next device, in a cyclic manner, when an end-of-reel
condition is detected. This applies only to tape devices and
SORT and ISAM files, and it is unconditional for tapes. For
SORT/MERGE, any number of devices may be assigned.
If the
disks are specified generically, SORT/MERGE will use its
internal algorithm to determine which physical devices to
use.
Otherwise, all devices specified will be used in a
round-robin fashion.
For ISAM files you may assign not more
than two devices.

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 MTAI.
SELECT SRTFIL ASSIGN TO DSK, DSK, DSK.

Version 12A

3-15

January 1980

THE ENVIRONMENT DIVISION

RESERVE

3.1.8 RESERVE
Function
The RESERVE clause allows you to specify the actual number of
input/output buffer areas for the compiler to allocate to this file.
General Format

~ESERVE integer-l [ AREAJll
AREAS U
Technical Notes
1.

If you specified the organization for this file as RELATIVE
or INDEXED, this clause is ignored and only one buffer area
is assigned.

If you did not specify RELATIVE or INDEXED organization, the
integer specifies the number of buffer areas for the compiler
to assign.

If you omit this clause for a sequential file, two areas will
be assigned.

You can specify a maximum of 62 areas for integer-I.
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 will be that much bigger.

Example
SELECT INFIL ASSIGN TO DSK
RESERVE 1 AREA.

3-16

January 1980

THE ENVIRONMENT DIVISION

ORGANIZATION

3.1.9 ORGANIZATION
Function
The ORGANIZATION clause specifies the way in
accessed.

which

file

will

General Format

J]
INDEXED [{~~~~~~6~NT} OUTPUT]

SEQ UENT I AL
[ RELATIVE
ORGANIZATION IS

[C HECKPOI NT

Technical Notes

The ORGANIZATION clause
indexed-sequential files.
files.

is
It

required for
is
ignored

relative
and
for
sequential

If ORGANIZATION IS SEQUENTIAL and the file
is
on
a
random-access
device,
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 ORGANIZATION IS RELATIVE, the contents of the data
item
associated with the RELATIVE 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, or which record is to be deleted by a DELETE
statement, or which record will be replaced by a REWRITE
statement.

If ORGANIZATION IS INDEXED, the contents of the data
item
associated with the RECORD 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 will be replaced by a
REWRITE statement.

The DEFERRED OUTPUT option of the ORGANIZATION IS INDEXED
clause causes the object-time system to output a block of an
indexed-sequential file only when another block must be
brought into memory.
Normally, to ensure integrity 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, Section
5.9.25.
3-17

January 1980

THE ENVIRONMENT DIVISION

ORGANIZATION (Cont.)

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

If you use the ORGANIZATION IS INDEXED clause, you may also
specify the CHECKPOINT OUTPUT option (instead of DEFERRED
OUTPUT).
If you specify this option, the object-time system
will force
the buffers to be written out, and all pointers
internal to the file to be updated, after every WRITE
statement.
This will naturally make your program run much
more slowly.
However,
it will also safeguard your file
against system crashes, since the file will have been updated
after the last WRITE before the crash.

Example
SELECT INFIL ASSIGN TO DSK, DSK
ORGANIZATION IS INDEXED DEFERRED OUTPUT.

3-18

THE ENVIRONMENT DIVISION

ACCESS MODE

3.1.10

ACCESS MODE

Function
The ACCESS MODE clause specifies the method used to access the file in
question.
General Format

[ACCESS MODE IS

SEQUENTIAL} ]
{ RAN DOM
DYNAMIC
MR-S-1259-81

Technical Notes
1.

If you do not specify the ACCESS MODE clause, ACCESS MODE IS
SEQUENTIAL is assumed regardless of the organization of the
file.

If you specify ACCESS MODE IS DYNAMIC you can access the file
either sequentially or randomly.

When you specify ACCESS MODE IS SEQUENTIAL,
the records in
your file are accessed in the sequence dictated by the file
organization. Sequential files are accessed in the same
order they are added to the file.
Relative files are
accessed in ascending relative record number order.
Indexed
files are accessed in ascending record key order.

If you specify ACCESS MODE IS RANDOM, the RELATIVE KEY
(for
relative files)
or the RECORD KEY
(for indexed files)
indicates the record to be accessed.

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 INFILE ASSIGN TO DSK
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS RECKEY.

3-19

THE ENVIRONMENT DIVISION

RECORD KEY

3.1.11

RECORD KEY

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

RECORD KEY IS data-name-l
MR-S-1260-81

Technical Notes
1.

The RECORD KEY clause is valid only for files
whose
organization is INDEXED; it must be specified for those files
(refer to the READ statement: Section 5.9.27).

You must define the RECORD KEY data-name 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.

If the file for which you are specifying the RECORD KEY
is to be accessed through RMS (that is, if the file is
a multi-key ISAM file), the RECORD KEY data item cannot be
longer than 255 characters. The data item must also be in
some DISPLAY format; DISPLAY-6, DISPLAY-7, or DISPLAY-9 are
legal, but no COMPUTATIONAL formats are legal.
c~ause

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.
However, when the
RECORD KEY is equal to LOW-VALUES, the results of a READ,
WRITE, REWRITE, and DELETE are unpredictable.

Example
SELECT INFIL ASSIGN TO DSK, DSK
ORGANIZATION IS INDEXED
RECORD KEY IS RECKEY.

October 1985

THE ENVIRONMENT DIVISION

ALTERNATE RECORD KEY
3.1.12

ALTERNATE RECORD KEY

Function
The ALTERNATE RECORD KEY clause specifies secondary keys that can be
used with multi-key indexed files.
These files are accessed through
RMS. See Appendix I, Using RMS Indexed Files, for more information on
RMS files.
General Format

[ALTERNATE RECORD KEY IS data-name-l [WITH DUPLICATES]]

Technical Notes
1.

The ALTERNATE RECORD KEY clause
is
valid
only
indexed-sequential files that are accessed through RMS.

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

No key specified with the ALTERNATE RECORD KEY clause can
larger than 255 characters.

All alternate key data items must be in one of the DISPLAY
formats.
DISPLAY-6, DISPLAY-7, and DISPLAY-9 are legal, but
no COMPUTATIONAL formats are legal.

You can specify up to 255 different ALTERNATE RECORD KEYs for
each file.
If more than one alternate key is to be used, an
additional ALTERNATE RECORD KEY clause must be specified for
each alternate key.

Keys specified with the ALTERNATE RECORD KEY syntax must have
the same data format (as defined in the USAGE clause) as the
record of which they are a part.
However, variable-length
keys are not allowed.

Files with ALTERNATE
simultaneous update.

A KL or KS CPU is required for the use of RMS files.

RECORD

3-21

KEYs

can

not

opened

for

October 1985

I
I

THE ENVIRONMENT DIVISION

RELATIVE KEY
3.1.13

RELATIVE KEY

Function
The RELATIVE KEY clause specifies which record is read or written in a
relative file.
General Format

RELATIVE KEY IS data-name-l
MR·S·1262·81

Technical Notes
1.

The RELATIVE KEY clause is valid only for a file whose
organization is RELATIVE; it must be specified for this type
of file. This clause cannot be used for a file whose
organization is INDEXED or SEQUENTIAL.

The RELATIVE KEY data-name must be defined in the Data
Division as a COMPUTATIONAL item of ten or fewer digits. The
PICTURE can contain only the character 9 or its equivalent,
for example 9(10).

Example
SELECT INFIL ASSIGN TO DSK
ORGANIZATION IS RELATIVE
ACCESS MODE IS RANDOM
RELATIVE KEY IS RKEY.

3-22

THE ENVIRONMENT DIVISION

RECORDING MODE/DENSITY/PARITY

3.1.14

RECORDING MODE/DENSITY/PARITY

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

density,

General Format

RECORDING

MODE IS [BYTE MODE]

.82ill
SIXBIT
BINARY
F

STANDARD-ASCII
STANDARD ASCII

[DENSITY IS

(lilll]

[PARITY IS

6250

Technical Notes
1.

MR·S-1263-81

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

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

SIXSIT - The file is read/written as SIXBIT records, six
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.
However, for industry-compatible
magnetic
tape
(9-track, with at least 800 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 of them.

3-23

THE ENVIRONMENT DIVISION

RECORDING MODE/DENSITY/PARITY (Cont.)
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 at
least 8~~ 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 memory are
transferred to five 8-bit bytes on the tape and bit
35 is stored in bit ~ 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.
This recording mode is valid for
magnetic tape only.
The format of records for each recording
Sections 8.1 and 8.2 of this manual.
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, a
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 uses the
recording mode specified.
If no recording mode is
specified, ASCII is the default.

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

October 1985

THE ENVIRONMENT DIVISION

RECORDING MODE/DENSITY/PARITY (Cont.)

Table 3-1
Recording Modes
RECORDING MODE
Clause

USAGE
Clause

RECORDING MODE
Actually Used

none

DISPLAY-6

SIXBIT

none

DISPLAY-7

ASCII

none

DISPLAY-9

EBCDIC

none

SIXBIT (no IX)

none

EBCDIC (IX)

SIXBIT

D:!SPLAY-6

SIXBIT

DISPLAY-7

SIXBIT

DISPLAY-9

SIXBIT

ASCII

DISPLAY-6

ASCII

DISPLAY-7

ASCII

DISPLAY-9

ASCII

or V

DISPLAY-6

EBCDIC

or V

DISPLAY-7

EBCDIC

or V

DISPLAY-9

EBCDIC

BINARY

DISPLAY-6

BINARY

DISPLAY-7

BINARY

DISPLAY-9

BINARY

NOTE
The object-time system
automatically
makes the conversions necessary to have
.the recording mode conform to the usage
mode of the records.
(These conversions
may cause your program to run more
slowly. )

3-25

THE ENVIRONMENT DIVISION

FILE STATUS
3.1.14

FILE STATUS

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

FI LE-STATUS}
{ FILE STATUS

data-name-l

data-name-2

data-name-3

[:ata-name_4

~ata-name-5 ~ata-name-6 ~ata-name-7 [data-name-8=!J~
Technical Notes
1.

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

3-26

THE ENVIRONMENT DIVISION

FILE STATUS
3.1.15

FILE STATUS

Function
The FILE STATUS clause specifies data-items into which the object-time
system 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

lJFIFI LE-STATUS}
LE STATUS

Cata-name-s

data-name-l

data-name-2

~ata-name-6

Gata- n ame-7

data-name-3

~ata-name_4

[data-name-8J~:J
MR-S-1264-81

Technical Notes
1.

3-27

THE ENVIRONMENT DIVISION

FILE STATUS (Cont.)
2.

You must define the data-names 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(1~).
USAGE INDEX.
PIC X(9).
USAGE INDEX.
USAGE INDEX.
PIC X(3~).
USAGE INDEX.

After a fatal I/O error, the FILE STATUS
following values.

items

contain

the

data-name-l contains the file status.
data-name-2 contains a l~-digit error number.
data-name-3 contains the action code, which is set to zero.
data-name-4 contains the VALUE OF 10.
data-name-5 contains the current block number.
data-name-6 contains the current record number.
data-name-7 contains the file name.
data-name-8 contains the file-table pointer.
The file status, which is stored in data-name-l, is set to one of
following 2-character codes.
~~
l~

21
22
23
24
3~

34
The

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.
Sequence error, primary key has changed; the prime record key
value has been changed by the program.
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.

l~-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.

o
1
2
3
4
5

6
7
8

No COBOL verb error
OPEN
CLOSE
WRITE
REWRITE
DELETE
READ
RETAIN
OPEN EXTEND
3-28

October 1985

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

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 FROM 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 MEMORY BETWEEN .JBFF AND OVERLAX AREA
INSUFFICIENT MEMORY 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 I/O
RECORD
THE TWO LOW-ORDER BYTES OF A BLOCK/RECORD DESCRIPTOR WORD
MUST BE ZERO

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-29

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
software write-locked file structure, or a
software redundancy failure occurred. This
bit is usually set by the monitor.
The
user cannot set this bit.

IO.DER

Hardware device error.
The disk unit is in
error,
rather than the data on the disk.
However, data read into memory or written
on the disk
is probably incorrect. The
user does not usually set this bit.

IO.DTE

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

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 the user's quota
on the file structure has been exceeded.
This bit is usually not set by the user.
This error is also returned when the user
tries to close a file that has open locks
associated with it (via Enqueue/Dequeue).

IO.EOF

End-of-file.
The
user
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.
This
bit is usually not set by the user.

IO.ACT

I/O
Active.
The
disk
is
transmitting or
receiving data.
is always set by the monitor for
use.

IO.WHD

Write disk-pack headers.
This is used in
conjunction with the SUSET. monitor call to
format a disk pack.
(Not used in COBOL)

IO.SYN

Synchronous mode I/O.
Stop disk after
every buffer is read or written.
(Not used
in COBOL)

IO.UWC

User word count, supplied by
each buffer.

32-35

IO.MOD

Data mode of the
3-30

d~vice.

the

actively
This bit
its own

user

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.

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

Protection failure or directory full on OTA.

File being modified.

Filename already exists (RENAME) or filename is
(ENTER after LOOKUP) or requested
supersede (on a non-superseding ENTER).

differen~

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 UFO RIB or UFO
data block.
Software-detected data inconsistency error
detected while reading the UFO RIB or file
RIB.

Not a saved file.

Not enough memory.

Oevice not available.

No such device.

No 2-register relocation
expected to occur)

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

Write-lock
structure.

error.

Not enough
monitor.

table

3-31

(Not expected to occur)

capability.

Cannot
space

(Not

write

file

free

memory

THE ENVIRONMENT DIVISION

FILE STATUS (Cont.)

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

Code

Partial allocation only.

Block not free on allocated position.

Cannot supersede an existing directory.

Cannot delete a nonempty
expected to occur)

Subdirectory not found (some
specified path was not found).

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

Cannot create a SFO nested deeper than the
maximum allowed level of nesting.
(Not expected
to occur)

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 UFO or SFO specified
by the default or explicit path (ENTER on
generic device OSK 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)
(Not expected to occur)

Cannot update file.

Low segment overlaps
expected to occur)

Not logged in.

high

(Not

directory.
SFO

segment.

the

(Not

(Not expected to occur)

The FILE STATUS items are the paths of communications between
the object-time system 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 the object-time system. Control
returns to the object-time system at the conclusion of the
USE procedure.
The object-time system action is determined
by the error number and by the contents of the action-code
placed into data-name-3 by the USE procedure.
If the
action-code is set to 1, the object-time system ignores the
error and continues the run. If the action-code is left set
3-32

THE ENVIRONMENT DIVISION

FILE STATUS (Cont.)
to 0, the object-time system issues an error message
terminates . the
run.
If the error-number is 17,
object-time system continues the run independent of
action-code setting.
If the action-code is not 0 or 1,
object-time system action is undefined.

and
the
the
the

When the program comes to a normal termination and, you have
requested (by loading a ~l" into the action-code) that errors
be ignored, the object-time system issues the following
message:
%n ERRORS IGNORED
5.

Refer to the USE statement in Section 5.9.42 for
writing USE procedures.

If you did not specify the FILE STATUS statement, I/O error
recovery processing cannot be performed.
If you specify the
FILE STATUS statement with only data-name-l included, you can
examine the status of the file, but you cannot specify that
the object-time syste,m 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
ORGANIZATION IS INDEXED
ACCESS MODE IS RANDOM
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 FILSTAT PIC 9(2).
77 ERRNUM
PIC 9(10).
77 ACTCODE INDEX.
77 VIP
PIC X(9).
77 BLKNUM
INDEX.
77 RECNUM
INDEX.
77 FILNAM
PIC X(30).
77 FILPNTR INDEX.

3-33

details

THE ENVIRONMENT DIVISION

I-O-CONTROL
3.1.15

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 - 0- CONTROL.

[RERUN EVERY

f END OF {~~ii }

t integer-l RECORDS

RECORD
SORT
[AME [ SO"RT-MERGE

OF fil e-name-l ]

AREA FOR file-name-2

{ file-name-3 }

~UL TJ PLE FILE TAPE CONTAINS fi 1e-name-4 [POSITION integer- 3J
[file-name-s

[POSITION integer-£i]

...

J. JJ

Technical Notes
1.

This paragraph is optional.

The RERUN clause
performed.

specifies

when

rerun

dump

THE ENVIRONMENT DIVISION

I-O-CONTROL (Cont.)
A rerun dump is not taken if any files are open for
input/output
(updating), or if any file is open on a device
other than magnetic tape, disk, line printer, or terminal, or
if an indexed-sequential (ISAM) file is open. Therefore, do
not attempt to have a rerun dump taken while a sort is in
progress. Also, RERUN cannot be used if overlays are used or
if files are open for simultaneous update.
3.

The SAME AREA clause specifies that two or more files are to
use the same area during processing;
this overlapping
applies to 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 you specify the RECORD option, the files share only the
record area
(that is, the area in which the current logical
record is processed). All of the files mentioned in the SAME
RECORD AREA clause may be open at the same time. A logical
record in the SAME RECORD AREA is considered to be a logical
record of each opened output file whose name appears in the
SAME RECORD AREA clause, as well as the most recently read
input file whose name is specified.
Since the various
DISPLAY usages are represented differently in memory, you
must keep track of the usage of the record in the SAME RECORD
AREA. You may use the record in any way you would otherwise
use it. However, you must be sure that you have a record of
the expected usage in the SAME RECORD AREA.
If, for example,
you plan to use a DISPLAY~7 record in your processing, you
must have a DISPLAY-7 record in the SAME RECORD AREA, not a
DISPLAY-6 record.
You will not get an error message if you
attempt to use a DISPLAY-6 record as if it were DISPLAY-7.
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 several files share
the same physical reel of tape. This clause is invalid for
media other than magnetic tape.
Regardless of the numbe~ of files on a single reel, only
those files defined in the program may 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 the 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.
No more than one file on the same reel of tape can be open 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-35

THIS PAGE INTENTIONALLY LEFT BLANK.

THE ENVIRONMENT DIVISION

I-O-CONTROL
3.1.16

I-O-CONTROL

[I - 0- CONTROL.

[RERUN EVERY

~AME

~) END OF {REEL'}
~
UNIT· OF fil e-name-l ]
\ integer-l RECORDS

RECORD
SORT
[ SORT-MERGE

AREA FOR file-name-2

GULTIPLE FILE TAPE CONTAINS file-name-4

{ file-name-3 }

[POSITION integer-3]

~ile-name-5 ~POSITION integer-~~

...

Technical Notes
1.

This paragraph is optional.

The RERUN clause
performed.

specifies

]]
MR-S-1265-81

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 you use the END OF UNIT option, a rerun dump is taken at
the end of each input or output reel of the specified REEL
file.
If you use the integer-l RECORDS option, 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 files are open for
input/output (updating), or if any file is open on a device
other than magnetic tape, disk, line printer, or terminal.
Therefore, do not attempt to have a rerun dump taken while a
sort is in progress. Also, RERUN cannot be used if overlays
are used or if files are open for simultaneous update.
3-37

THE ENVIRONMENT DIVISION

I-O-CONTROL (Cont.)
3.

The SAME AREA clause specifies that two or more files are to
use the same area during processing; this overlapping applies
to 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 you specify the RECORD opt(on, the files share only the
record area
(that is, the area in which the current logical
record is processed). All of the files mentioned in the SAME
RECORD AREA clause can be open at the same time. A logical
record in the SAME RECORD AREA is considered to be a logical
record of each opened output file whose name appears in the
SAME RECORD AREA clause, as well as the most recently read
input file whose name is specified.
Since the various
DISPLAY usages are represented differently in memory, you
must keep track of the usage of the record in the SAME RECORD
AREA. You can use the record in any way you would otherwise
use it. However, you must be sure that you have a record of
the expected usage in t'he SAME RECORD AREA.
If, for example,
you plan to use a DISPLAY-7 record in your processing, you
must have a DISPLAY-7 record in the SAME RECORD AREA, not a
DISPLAY-6 record.
You do not get an error message if you
attempt to use a DISPLAY-6 record as if it were DISPLAY-7.
The SORT and SORT-MERGE options are used for sort and merge
files.
However, these options need not be specified because
all sort and merge files always use the same area.

The MULTIPLE FILE clause is required when several files share
the same physical reel of tape with a uniform labeling
convention. This clause is invalid for media other than
magnetic tape, and cannot be specified for a sort or merge
fil~.
In addition, this clause is invalid for monitor tape
labeling (with ANSI) and does not work for COBOL labels.
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 the 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.
Each file in a series of files sharing the same physical reel
of tape, must be created with a uniform labeling convention.

Files used for SORT or MERGE
MULTIPLE FILE TAPE clause.

cannot

specified

the

No more than one file on the same reel of tape can be open at
one time.
Example
I-"-CONTROL.
RERUN EVERY 3"" RECORDS OF INFIL
SAME RECORD AREA FOR INFIL, OUTFIL
MULTIPLE FILE TAPE CONTAINS INFIL POSITION 4.

3-38

October 1985

THE ENVIRONMENT DIVISION

3-39

THE ENVIRONMENT DIVISION
GENERAL FORMAT FOR ENVIRONMENT DIVISION
ENV1RONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.

computer-name [WITH DEBUGGING MODE] •

OBJECT-COMPUTER.

computer-name

fMEMORY SIZE integer If =CTERS
I]
L
MODULES f
[PROGRAM COLLATING SEQUENCE IS alphabet-name]
[SEGMENT-LIMIT IS Segment-nunber]
SPECIAL-NAMES. [CONSOLE IS mnemonic-name-I]
[CHANNEL (m)

IS mnemonic-name-2]

[CHANNEL

(n) IS mnemonic-name-3 ..• ]

IS mnemonic-name-4
[OFF
ON

[ON

STATUS IS condition-name-l]

STATUS IS condition-name-2]

STATUS IS condition-name-l

SWITCH(m)

[OFF
OFF

STATUS IS condition-name-2]

STATUS IS condition-name-2

[ill! STATUS IS condition-name-lJ
STANDARD-l
alphabet-name IS NATIVE
ASCII
EBCDIC
literal-I

titeral-S

{THROUGH~ literal-2
~

[ ALSO literal-3 [ALSO literal-4]

J
...

[:'~:::a:::e(:~~: literal-B) oJ]

000

[literal-9 IS mnemonic-name-4]
[CURRENCY SIGN ~ literal-IO]
[DECIMAL-POINT 12. COMMA] • ]

3-40

October 1985

THE ENVIRONMENT DIVISION

GENERAL FORMAT FOR FILE CONTROL STATEMENT
FORMAT 2:

SELECT [OPTIONAL] file-name
ASSIGN TO device-name-l [device-name-2]

[AREA
.
AREAS
[ RESERVE lnteger-l

ORGANIZATION IS RELATIVE [WITH CHECKPOINT OUTPUT [EVERY integer-l RECORDS]]

[SEQUENTIAL
ACCESS MODE IS

f-RAN DOM
[ LDYNAMI C

RECORDING

]

[RELATIVE KEY IS data-name-l]]
RELATIVE KEY IS data-name-l]

ASCII
SiXBfT
MODE IS iINARY
{

•
FILE-STATUS)
[( FILE STATUS

IS data-name-l [data-name-2 [data-name-3 [data-name-4

JJJJJJ]]

[dat a- n ame- 5 [dat a- name -6 [d at a- n ame- 7 [dat a- n ame- 8

MR-S-1269-81

3-43

THE ENVIRONMENT DIVISION

GENERAL FORMAT FOR FILE CONTROL STATEMENT
FORMAT 3:
SELECT file-name
ASSIGN TO device-name-l
[RESERVE ;nteger-l

[~~~~sJ]

[device-name-2]

ORGANIZATION IS [RMS] INDEXED [WITH {CHECKPOINT OUTPUT [EVERY integer-l RECORDS]}]
DEFERRED OUTPUT

SEQUENTIAL}]
ACCESS MODE IS RANDOM
{ DYNAMIC

RECORD KEY IS data-name-l

[ALTERNATE RECORD KEY IS data-name-l [WITH DUPLICATES]] ...

ASCII }]
STXBiT
RECORDING MODE IS ilNARV
{

FI LE- STAT US
[{ FILE STATUS

IS data-name-l [data-name-2 [data-name-3 [data-name-4

[da t a- n ame- 5 [dat a- n ame-6 [dat a-name-7 [data-name-S]]]]]]J]

3-44

October 1985

CHAPTER 4
THE DATA DIVISION

The Data Division, which is 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:
1.

Data contained in files, both input and output

Data contained in a database.and accessed
Base Management System

Data to be sent to or receiv~d from the Message
System or the Transactional Processing System

Data which is used by the program in the process of executing
(This data can be constant or variable, and may be stored as
part of the program or computed by the program during its
operation.)

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:

the

Data

Division

through

consists

the

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

The Communication Section, which defines the special data
items that link a program or subprogram to the Message
Control System (M~S-lO) or the Transactional Processing
System (TPS-20)

The Working-Storage Section, which contains any fixed values
and the working areas in which intermediate data can be
stored

The Linkage Section, which des~ribes the data in a subprogram
that is available from a calling program

The Report Section, which describes the data and format of
report

4-1

THE DATA DIVISION
Unused sections of the Data Division may be omitted.
However,
sections which are 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

The File Section begins with the section-header FILE SECTION.
If
present, it must be the first section in the Data Division. In the
File Section, the characteristics of each file to be processed are
described by two types of entries, the file description and the record
description.
The first type of entry, the file description, describes the
aspects of the file. These aspects include:
file

are

physical

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

The maximum length of a logical record, which
4095 characters

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

cannot

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

4.1.1

physically

the

exceed

data

Record Descriptions

Following the FD file-name entry for a file, or the SD file-name entry
for a sort file, a record description is given for each different
recoyd format in the file. 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
can be found in Section 4.9.11.
A record description begins with a level-Ol entry:
01

data-name

A complete record description may be as simple as
01

data-name PICTURE picture-string.

or it may be more complex, where the Ol-level is followed by a long
series of data description entries of varying hierarchies that
describe various portions and subportions of the record.
A Ol-lev~l
4-2

THE DATA DIVISION
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.-

4.1.2

Elementary Items and Group Items

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

4.1.3

Level Numbers

Level numbers indicate a hierarchy of data items. 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-INITIAL 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. 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 01 level is not required to be a
group item; it may be an elementary item as long as it is referenced
as a unit. For example:
01 EMPLOYEE-RECORD PICTURE IS X(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 data
items that are defined only in the Working-Storage Section to define
constant values or to store intermediate results. Defining a level-77
item is the equivalent of defining a level-Ol elementary item.
Level-66 data items are
specified portion of a

those items that contain an explicitly
record already defined, or even the whole
4-3

THE DATA DIVISION
record. A data item with a level number of 66 is used in a RBNAMES
clause to regroup items within a 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 may 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 AOOOI.
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.2

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

SCHEMA SECTION

In the Schema Section, either an INVOKE statement or an ACCESS
statement specifies the names of the sub-schema and schema to be
processed.
The Schema Section begins with the section-header SCHEMA
must follow the File Section, if present.
If the installation does not include DBMS, the Schema
be used.

SECTION

Section

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

4.3

and

cannot

found

COMMUNICATION SECTION

The Communication Section contains the definitions of input and output
communication-description entries.
CD entries define records called CD records which contain special data
items used to link the program to the Message Control System for users
of TOPS-IO or the Transactional Processing System for users of
TOPS-20.
4-4

THE DATA DIVISION
4.3

COMMUNICATION SECTION

The Communication Section contains the definitions of input and output
communication-description entries.
CD entries define records called CD records that contain special data
items used to link the program to the Message Control System (MCS) for
TOPS-l~ users.
The Communication Section begins with the section-header COMMUNICATION
SECTION and must follow the File Section and Schema Section and
precede the Report Section.
If your TOPS-l~ installation does not include MCS,
Section cannot be used.

the

Details of the Communication Section entries can
Message Control System pro~rammer's Procedures
users.

be found
in the
Manual for TOPS-10

4.4

Communication

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, SO, RD, CD, or SCHEMA entries.
The
Working-Storage
Section
WORKING-STORAGE SECTION.

begins

with

the

section-header

The maximum size of a record in Working Storage is 262,143 characters.
However, the maximum size of a record to be read or written can only
be 4,~95 characters.

4.5

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 10),
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 RECORD KEY and RELATIVE KEY data items cannot be
in this section.

4-5

defined

October 1985

THE DATA DIVISION
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
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 DIVIS~ON.
ENTRY ENTRPT USING SUB,
SUBl, SUB2.

CALL ENTRPT USING MAIN,
MAINl, MAIN2.
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, references to SUBI
refer to MAINl, and so on through the list. See the COBOL-74 Usage
Material,
Part
3 of this manual,
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;
any items that do not can be made to do so by means of 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.

4-6

THE DATA DIVISION
4.6.1

Format Of 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 break happens least
often and the most minor control break happens 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 generated, 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.

4-7

THE DATA DIVISION
REPORT HEADING
PAGE HEADING
CONTROL HEADING (FINAL)
CONTROL HEADING (MAJOR)
CONTROL HEADING (MINOR)
DETAIL GROUP

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

CONTROL FOOTING
CONTROL FOOTING
CONTROL HEADING
CONTROL HEADING
DETAIL GROUP

(control break occurred)

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

(control break occurred)

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 of 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 print queue using
the PRINT command and specifying the code with the REPORT switch, as
follows:
PRINT file-specifier/REPORT:code
Only the first 12 characters of the code will be accepted in the PRINT
command string.
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
should be placed, and the number of lines which should be 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 programmer-specified procedure to be performed before a report
group is produced.
.

4-8

THE DATA DIVISION
4.7

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
(I)
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.
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 is sufficient.
Example:
01
02

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

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

any

FIELD OF SUB-ITEM OF ITEM-l OF RECORD-I.
FIELD OF SUB-ITEM OF ITEM-I.
FIELD OF SUB-ITEM IN RECORD-I.
FIELD IN ITEM-l OF RECORD-I.
FIELD IN RECORD-I.
FIELD IN ITEM-I.
The connectives
interchangeably.

and

are

equivalent

and

may

used

The only data items which need to 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 may be
qualified by the file name, as may any item contained within the
record.
File names must be unique.
Level-66 items may 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.8

SUBSCRIPTING AND INDEXING

It may sometimes be more convenient for you to specify a set of data
values as a table rather than assign 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-74, subscripting and indexing are identical in use and can be
4-9

THE DATA DIVISION
used interchangeably. However, the manner in which they are defined
differs.
Subscripting is defined simply by the fact that an item has
an OCCURS clause in its description.
For example,
01

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 (10) 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 will be treated as a COMPUTATIONAL data item by the
compiler.
COBOL-74 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
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. As an illustration, consider a table having a major element
occurring 10 times, an intermediate element occurring 5 times within
each occurrence of the major element, and a minor element occurring 3
times within each intermediate element.
The last major element of the
table is referred to by the subscript form (10,1,1), while the final
element of the table is referred to by (10,5,3).

4-10

January 1980

THE DATA DIVISION
NOTE

DATA DIVISION entries are limited to 468~ data items
as you define them. Refer to Section 13.4.4, for a
description of this restriction.
The subscript/index must be enclosed in parentheses and 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. As an illustration, consider a tabl~ having a major element
occurring l~ times, an intermediate element occurring 5 times within
each occurrence of the major element, and a minor element occurring 3
times within each intermediate element. The last major element of the
table is referred to by the subscript form (l~,l,l), while the final
element of the table is referred to by (1~,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 which an integer is added or subtracted. The form
for direct subscript/indexing is shown in Figure 4-1 •

. data-name

(

[{ ,~UbscriPt}J
{ ~ubscriPtl
... )
wdex
(
,wdex
MR-S-58l-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

(

1~~~~~ri pt } 1~ } integer

[ { :~~~~~riPt}

{~ }

integer]

... )
MR-S-582-80

Figure 4-2:

Relative Subscripting/Indexing

4-11

October 1985

THE DATA DIVISION
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 and relative subscripting/indexing in the
same statement. For example, if you specify the following data item:
TABLE (IND, VOL + 3)
the first subscript value is the value of IND and the second subscript
value is the value of VOL + 3.
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

OF t
[{ IN!

J ~UbscriPt} [{ ,~ubscript
,lndex!
( , lndex

data-name-l]

...

)

MR-S-583-80

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

4.9

DATA DIVISION CLAUSES

The clauses that make up the Data Division are presented in the
following pages. The function, syntax, and details of each clause are
described, and the general format of the clause is included.
The
clauses are presented in the order in which they appear in the general
formats at the end of this chapter, that is, in the order in which
they occur in the Data Division. The formats of some clauses contain
other clauses. When this is the case each clause that is subordinate
is described separately on succeeding pages.

4-12

THE DATA DIVISION

FILE DESCRIPTION (FD)
4.9.1

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
DATA DIVISION.
[FILE SECTION.
[FD fil e-name
GLOCK CONTAINS

[i nteger-l TqJ

i nteger-2

~RECORD CONTAINS

Qnteger-3 TO]

integer-4

LABEL

j RECORD(S)
l CHARACTERS

CHARACTER~ .

RECORD IS } jSTANOARO(
{ RECORDS ARE lOMITTEO

IvALUE OF rJ IDENTIFICATION} IS j d?ta-name-l}~
L-Uill
t llteral-l ~

j d?ta-name-2 }fllusER-NUMBER IS {
integer-5, integer-6f~
lrDATE-WRITTEN IS lllteral-2
UL
data-name-3

IrL!ATA {RECORD
IS }
RECORDS ARE
data-name-4

l--

ILINAGE IS {?ata-name-6}
lnteger-7

LINES

[data-name-5J

[WITH FOOTING AT

... ]

?ata-name-7
{ 1 nteger-8

r
U

ILINES AT TOP {?ata-name-8}] I LINES AT BOTTOM . {~ata-name-9 nl
L
- lnteger-9
L
lnteger-IO UJ

[CODE-SET IS al phabet-name ]

[

REPORT IS }
report-name-l
{ REPORTS ARE

[!eport-name-~

4-13

.. .]

October 1985

THE DATA DIVISION

FILE DESCRIPTION (FD) (Cont.)

RECORDING

MODE IS [BYTE MODE]

Ailil
SIXBIT
BINARY
F

STANDARD-ASCII
STANDARD ASCII

I
MR-S-1272-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 semicolons 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 specify the RECORDING MODE clause for a file in the FD,
you cannot also specify 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 Section 3.1.13.

The maximum number of files that can be open at one time is
16.
ISAM files count as two files: one index (.IDX) file
and one data (.IDA) file. However, RMS files (multi-key ISAM
files that are accessed through RMS) do not count towards
this total of 16.

4-14

any

order

The entire FD
within

the

entry
File

THE DATA,DIVISION

BLOCK CONTAINS
4.9.2

BLOCK CONTAINS

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

~LOCK CONTAINS [i nteger-l Tq]

i nteger-2

j RECORD(S) II

l CHARACTERS fJ

MA-S-1273-81

Technical Notes
1.

This clause is ignored for RMS files (multi-key indexed files
that are accessed through RMS).

If you do not include this clause, or if you specify that
integer-2 is zero, the file is not organized into logical
blocks when it is written. Rather, all records are placed in
the file with no empty space. The file is then considered to
be "unblocked" or "blocked zero" and is the most efficient
form of a sequential file on disk.

If you use the RECORDS clause, the block size can be any
multiple of the RECORD CONTAINS clause, or zero (for variable
or fixed length records).

If you use the CHARACTERS option, you specify the logical
block size 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), the compiler
assumes that the size is specified in terms of ASCII
characters. If the recording mode is SIXBIT (that is, the
records for the file are all described, explicitly or
implicitly, as DISPLAY-6), the compiler assumes 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) , the compiler assumes that the size is
specified in terms of EBCDIC characters, either fixed- or
variable-length.
When variable-length EBCDIC records are
used (that is, the recording mode is V), the number of
records in a block is arso 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.

4-15

October 1985

THE DATA DIVISION

BLOCK CONTAINS (Cont.)
5.

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

Files whose organizations are RELATIVE or INDEXED must have a
nonzero blocking factor.

4-16

October 1985

THE DATA DIVISION

CODE-SET

4.9.3

CODE-SET

FUNCTION
The CODE-SET clause specifies the character code set used to"represent
data on the external media.
General Format
[CODE-SET IS al phabet-name

Technical Notes
1.

When you specify the CODE-SET clause for a file, you must
describe all data in that file ,as USAGE IS DISPLAY. You must
also describe any signed numeric data with the SIGN IS
SEPARATE clause.

The alphabet-name clause referenced by
must not specify the literal phrase.

the

CODE-SET

You may specify the CODE-SET clause
residing on mass storage media.

only

for

The CODE-SET clause is included only for compatability, since
ASCII is the only alphabet-name allowed, and ASCII is also
the default.

If you include the CODE-SET clause, alphabet-name specifies
the character code convention used to represent data on the
external media.
It also specifies the
algorithm
for
converting the character codes on the external media from or
to the native character codes. This code conversion occurs
during the execution of an input or output operation.

If you omit the CODE-SET clause, the ASCII character
assumed for data on the external media.

4-17

clause

files

set

not

THE DATA DIVISION

DATA RECORD
4.9.4

DATA RECORD

Function
The DATA RECORD clause
associated file.

cross-references

the

record-name

with

its

entry

General Format

Ir~ATA {RECORD
IS } data-name-4
RECORDS ARE

[data-name-5J

... ]

Technical Notes
1.

This clause is optional because all records in the
are assumed to be data records.

All records within a file share the same area.

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

4-18

THE DATA DIVISION

FD File-name

4.9.5

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

[Jfo f;le-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-19

the

THE DATA DIVISION

LABEL RECORD

4.9.6

LABEL RECORD

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

RECORD IS
}
STANDARD
) OMITTED
{ RECORDS ARE

\ record-name-l

Technical Notes
1.

If you omit
assumed.

the

clause,

LABEL

RECORDS

ARE

STANDARD

You should use the OMITTED option when the file has no header
or trailer labels.

You should use the STANDARD option when the file has header
and trailer labels that conform to the standard format. If
the file you are describing is on disk or DECtape, you must
either specify LABEL RECORDS ARE STANDARD, or omit the clause
altogether allowing the default to take over. See the VALUE
OF IDENTIFICATION clause for the association between the
label and the filename on disk or DECtape.
The standard label for DECtape and disk is the directory
block used by the monitor. For magnetic tape, if the file is
recorded in SIXBIT, the standard label 1S
78
SIXBIT
characters in length and is written in a separate physical
record from 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.

Files whose recording mode 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-lO standard labels.

4-20

THE DATA DIVISION

LABEL RECORD (Cont.)
Table 4-1
Standard Label for Magtapes
Characters

Contents

1-4

HDRl = Beginning File
EOFl = Ending file
EOVl = Ending reel

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-21

for

the

THE DATA DIVISION

LINAGE
4.9.7

LINAGE

Function
The LINAGE cLause specifies the size of a logical page in terms of
number of lines. It can also spe~ify the size of the top and bottom
margins on the logical page and the line number, within the page body,
at which the footing area begins •.
General Format

[LINAGE IS

LINES

[ WITH FOOT! NG AT

J ~a t a - name - 21 ]
\lnteger-2

11~i!~~~~~-3IJ

LINES AT BOTTOM

\lnteger-4

J d at a - n am e - 11

\integer-I

[LINES AT TOP

J~ata-narne-4IJ
MR-S-1278-81

Technical Notes

LINAGE is valid only for sequential files.
However, the
LINAGE clause cannot be specified for sequential files OPENed
in the EXTEND mode.

The logical page size is the sum of the values referenced by
each
phrase except the FOOTING phrase.
(There is no
necessary relationship between the size of the logical page
and the size of a physical page.) If the LINES AT TOP or
LINES AT BOTTOM phrases are not specified, the values for
these functions are zero.

Data-name-l, data-name-2, data-name-3 and data-name-4 must
reference elementary unsigned numeric integer data items.
The value of integer-l must be greater than zero; the value
of integer-2 must not be greater than integer-l; the value of
integer-3 and integer-4 can be zero.

The number of lines on the logical page is equal to the value
of integer-lor the data item referenced by data-name-l. The
page body is that part of the logical page in which lines can
be written and/or spaced.

The line number within the page body at which the footing
area begins is equal to the value of integer-2 or the data
item referenced by data-name-2.
The value must not be
greater than the value of integer-l, or the data item
referenced by data-name-l. The footing area is the area of
the logical page between the line represented by the value of
integer-2 (or the data item referenced by data-name-2) and
the line represented by the value of integer-l (or the data
item referenced by data-name-l) inclusive.

4-22

October 1985

THE DATA DIVISION

REPORT

4.9.8

REPORT

Function
The REPORT clause specifies the
with the file.

nam~

of each report that is associated

General Format

[

f report-name-l

REPORT 1St
{ REPORTS ARE

[:eport-name-~

Technical Notes

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

Report-name-l and report-name-2 must be the names
Descriptor items in the Report Section.

If you use this clause, you may omit the data record
description 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 l32-character record.

4-23

Report

THE DATA DIVISION

SD File-name
4.9.9

SD File-name

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

file

General Format

[so

fi 1e-name
[RE CORD CONTAI NS

[i nteger-l TOJ i nteger-2 CHARACTER~

RECORD IS }
[ DATA { RECORDS ARE

[reeord-deseri ption-entry I

~ata-name-2J

data-name-l

00']

oJ 00 oJ

Technical Notes
1.

The SD 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-24

clauses

are

the

only

THE DATA DIVISION

REPORT
4.9.9

REPORT

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

[:eport-name-~

.J
MR-S-12BO-B1

Technical Notes
1.

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

A file described with a REPORT clause cannot be referenced by
any
input-output statements except the OPEN and CLOSE
statements.

Report-name-l and report-name-2 must be the names
Descriptor items in the Report Section.

If you use this clause, you can omit the data record
description 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-25

Report

October 1985

THE DATA DIVISION

SO File-name
4.9.10

SD File-Name

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

file

General Format
[SD

fi 1e-name

[RECORD CONTAINS

[integer-l TO]

~
{RECORD IS }
~PATA
RECORDS ARE
data-name-l
[reeord-deseri ption-entry I

integer-2 CHARACTER~

~ata-name-2J

00']

oJ 00 oJ
MR-S-1281-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-26

clauses

are

the

only

THE DATA DIVISION

VALUE OF IDENTIFICATION/DATE-WRITTEN
/USER-NUMBER
4.9.11

VALUE OF IDENTIFICATION/DATE-WRITTEN/USER-NUMBER

Function
The VALUE OF IDENTIFICATION clause provides specific data for an item
within the label records associated with a file.
The VALUE OF
DATE-WRITTEN clause specifies a date which the file label must contain
to be processed by the program.
The VALUE OF USER-NUMBER clause
provides a project-programmer number to be checked against the file
label before processing.
General Format

tlJ

t} data-name-3
integer-I, integer-2 ~~

Technical Notes
1.

ID can be substituted for IDENTIFICATION.

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, DISPLAY-6, DISPLAY-7, or
DISPLAY-9 data item nine characters in length. If a literal
is specified, it must be a nonnumeric 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.

4-27

only

one

October 1985

THE DATA DIVISION

VALUE OF IDENTIFICATION/DATE-WRITTEN
/USER-NUMBER (Cont.)
Examples:
a.

VALUE OF IDENTIFICATION IS "COST

TST"

VALUE OF IDENTIFICATION IS FILE-l-NAME

(WORKING-STORAGE SECTION.)
77-FILE-l-NAME PICTURE IS X(9).
5.

DATE-WRITTEN represents the date that a mag tape file
(with
STANDARD labels)
was written. If a data-name is specified,
it must be associated with a DISPLAY, DISPLAY-6, DISPLAY-7 or
DISPLAY-9 data item six characters in length. If a literal
is specified, it must be a nonnumeric 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" ,
810112

DATE-WRITTEN

VALUE OF IDENTIFICATION IS "DATA
FILE-l-DATE

DATE-WRITTEN

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

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 l~ or fewer
digits in which the project-programmer number is stored.
Integer-l and integer-2 are numeric literals of six or fewer
digits that are treated as octal. Integer-l is the project
number and integer-2 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.

8. '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.

4-28

October 1985

THE DATA DIVISION

DATA DESCRIPTION ENTRY

4.9.11

DATA DESCRIPTION ENTRY

Function
A data description entry describes a particular item of data.
General Format
FORMAT 1:

level-number

{data-name-l}
FILLER

[REDEFINES data-name-2 ]

[{

~URE } IS character-string]
COMPUTATIONAL
cor~P

B5M'PUTATIONAl-l
COMP-l
COMPTI'TATI ONAl - 3
COMP-3
DISPLAY
DISPlAY-6
DISPlAY-7
DISPlAY-9
INDEX
DAfABASE-KEY
DBKEY

USAGE IS

'OCCURS {~nteger-l TO integer-2 TIMES DEPENDING ON data-name-3 }
L--·nteger-2 TIMES
1

[{

~~~~~~~~~G} KEY IS data-name-4 [data-name-u

[INDEXED BY index-name-l
SYNCHRONIZED}
[{ SYNC

[index-name-2]

Jil

[lEFT
RIGHT ~

RIGHT}~

JUSTI FlED} {
[{ JUST
lEFT

U
4-29

. J]

THE DATA DIVISION

DATA DESCRIPTION ENTRY (Cont.)
FORMAT 2:

66 data-name-l RENAMES data-name-2

~{ ~UGH} data-name-3~

FORMAT 3:

VALUE IS }
{ VALUES ARE

88 condition-name

[iteral-3 a

=UGH}

1 1. t era 1-1

I!{
LJ THROUGH}
THRU

literal-4J]

The clauses shown in the General Format appear in alphabetical order
along with the other Data Division clauses on the following pages.
Technical Notes
1.

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

The clauses may 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-SS) entries.

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

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

4-30

period.

WHEN

THE DATA DIVISION

BLANK WHEN ZERO
4.9.12

BLANK WHEN ZERO

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

item

when

its

General Format
[1LANK WHEN ZERO]

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.

An asterisk used as a zero suppression symbol in a PICTURE
clause may not appear in the same entry with the BLANK WHEN
ZERO clause.
More comprehensive editing
features
are
available in the PICTURE clause.

When the BLANK WHEN ZERO clause is used for an elementary
item whose PICTURE is numeric, the category of the item is
considered to be numeric-edited.

4-31

THE DATA DIVISION

Condition-name (level-88)
4.9.13

Condition-name (level-88)

Function
The condition-name (level-88) entry assigns a name to a value or range
of values of the associated data item.
General Format

88 condition-name

VALUE IS
{ VALUES ARE)

l 1"t era 1-1

fJ{
t iteral-2]
LJ THROUGH
THRU
, 1

[iteral-3 a=UGH} 1iteral-4]
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 any
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 may 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-32

THE DATA DIVISION

Condition-name (Ievel-88) (Cont.)
5.

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 B2 ....

IF B-FIELD IS EQUAL TO 20 OR
EQUAL TO 25 OR EQUAL TO 28
OR GREATER THAN 30 AND 1
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 84 ....

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

IF C-YES

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 999 must be in the
range of 000 to 999.

4-33

THE DATA DIVISION

Data-name/RLLER
4.9.14

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
1 evel-number

data-name-l }
{ FI LLER

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 one 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-Defined 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 may 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-34

the

THE DATA DIVISION

JUSTIFIED
4.9.15

JUSTIFIED

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

within

General Format

JJUSTI FI ED} { RI GHT .}~
LEFT
[ t JUST

Technical Notes
1.

The JUSTIFIED clause cannot be specified at a group level, or
for numeric or edited items. If neither RIGHT nor LEFT is
specified, RIGHT is assumed.

An item subordinate to one containing a VALUE
be JUSTIFIED.

clause

cannot

DISPLAY, DISPLAY-6, DISPLAY-7
JUSTIFIED.

items

can

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

and

DISPLAY-9

elementary

The receiving data item is described as numeric or
numeric-edited (see definition in Notes 7 and 10 under
the PICTURE clause, Section 4.9.18.)
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.

The receiving data item is described as alphanumeric or
alphabetic (see definition in Notes 6 and 8 under the
PICTURE clause, Section 4.9.18).
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-35

THE DATA DIVISION

JUSTIFIED (Cont.)
5.

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 rightmost 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 "ABCDEFGH".

ITEM-B PICTURE IS
X(4) VALUE IS "WXYZ".

ITEM-C PICTURE IS X(6).

ITEM-D PICTURE IS X(6).
JUSTIFIED RIGHT.

Procedure Division statement

Contents of Receiving Field

MOVE ITEM-A TO ITEM-C.

I AI B C 0 ElF

MOVE ITEM-A TO ITEM-D.

I c\ 0 E F GIH

MOVE ITEM-B TO ITEM-C.

I wi X Y Z 6\6

MOVE ITEM-B TO ITEM-D.

4-36

6 1 6 W X YIZ

THE DATA DIVISION

Level-number

4.9.16

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-88), noncontiguous working-Storage items (level-77), and the
RENAMES clause (level-66).
General Format
level-number

da t a - na me - 1}
{ FILLER

Technical Notes
1.

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

Level-numbers may be placed anywhere on the source
or after margin A.

Level-number
88
is
described
under
"condition-name
(level-88)", Section 4.9.13, and level-number 66 is described
under "RENAMES (level-66)", Section 4.9.20.

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

4-37

line,

data
at

THE DATA DIVISION

OCCURS
4.9.17 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

[ OCCURS

[{

Jinteger-l
linteger-3

~~mm~G

TO integer-2
TIMES

TIMES DEPENDING ON data-name-11

KEY IS data-name-2

[INDEXED BY index-name-l

[da.ta-name-3]

[index-name-2]

000] 000

oJ]

Technical Notes
1.

This clause cannot be specified 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 or integer-3;
in addition, if
the DEPENDING option is specified, no subscript can exceed
the value of data-name-l at the time of subscripting.

If the DEPENDING option is specified, the integer-l TO phrase
must be included.
The DEPENDING option must immediately
follow TIMES.
Data-name-l must be a positive integer,
and
for efficiency should be either USAGE INDEX or USAGE COMP.
It cannot be subscripted, and if the clause appears
in the
Linkage Section, data-name-l must be either USAGE INDEX or
USAGE COMP.

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 or integer-3.

4-38

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

January 1980

THE DATA DIVISION

Level-Number
4.9.17

Level-Number

Function
The level-number shows the hiera~chy of data within a logical record.
In addition, special level-numbers are used for condition-names
(level-88), noncontiguous Working-Storage items
(level-77), and the
RENAMES clause (level-66).
General Format

level-number

data-name-l}
{ FILLER
MR-S-1287-81

Technical Notes
1.

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

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

Level~number

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

line,

data
at

88
is
described
under
"condition-name
(level-88)", Section 4.9.14, and level-number 66 is described
under "RENAMES (level-66)", Section 4.9.21.

4-39

THE DATA DIVISION

OCCURS
4.9.18

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

[OCCURS

integer-l
( integer-3

ASCENDING )
[( DESCENDING

TO integer-2

TIMES

TIMES DEPENDING ON data-name-l)

KEY IS data-name-2

[INDEXED BY index-name-l

[ d a t a - n a me - 3]

[index-name-2]

]

... ...

... J]
MR·S·12BB·B 1

Technical Notes

This clause cannot be specified 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 to define tables or
other
homogeneous sets of repeated data. Whenever this clause is
used, the associated data-name and any subordinate data-names
must always be subscripted or indexed when used in all
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 or integer-3; in addition,· if
the DEPENDING option is specified, no subscript can exceed
the value of data-name-l at the time of subscripting.

When a receiving item is a variable length data item and
contains the object of the DEPENDING ON clause, the maximum
length of the item is used, not the actual length of the
item.

If the DEPENDING option is specified, the integer-l TO phrase
must be included.
The DEPENDING option must immediately
follow TIMES. Data-name-l must be a positive integer, and
for efficiency should be either USAGE INDEX or USAGE COMP.
It cannot be subscripted, and if the clause appears in the
Linkage Section, data-name-l must be either USAGE INDEX or
USAGE COMP.

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 or integer-3.
4-40

October 1985

THE DATA DIVISION

PICTURE (Cont.)
, represents
. represents
B represents
o represents
/ represents
e.

an insertion comma l
an actual decimal pointl
an insertion blank
an insertion zero
an insertion slash

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) I where n
indicates the number of occurrences.
However, some
editing symbols may not be used more than once in a data
item: "S", "V", ".;1, ItCR" , and "DB".

A maximum number of 30 symbols can appear in a picture
string.
Note that the' number of symbols in a picture string
and the size of the item represented are not necessarily the
same.
There are two reasons for this discrepancy. First,
the abbreviated form for indicating consecutive repetitions
of a symbol may 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, with one exception, do not represent actual physical
character positions within the data item. The exception
involves the use of the SIGN IS SEPARATE clause, which causes
the S (arithmetic sign) to take up a character position. If
the clause is omitted, the character-string
S999V99
represents a 5-position data item. However, if tne SIGN IS
SEPARATE clause is included, the character-string would
represent a 6-position item.
Other size restrictions for numeric and numeric-edited
are given under the appropriate headings below.

items

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.

1
If the DECIMAL-POINT IS COMMA clause appears in the SPECIAL-NAMES
paragraph, the function of the comma and decimal point is reversed.

4-41

THE DATA DIVISION

PICTURE (Cont.)
6.

Definition of an Alphabetic Item
a.

Its picture string may contain only the symbol A or B.

It may contain only the 26 letters of
the space.

alphabet

and

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

Definition of a Numeric Item
a.

string

must

have

from

It may contain only
operational sign.

the

digits

through

The picture
positions.
b.
S.

10.

the

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.

It,s contents can be any combination of characters
the complete character set (see Section 1.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, 0 or /.

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 may also contain the symbols 9, V, or P. If you use
the CURRENCY SIGN IS clause f the new currency sign you
specify replaces the $ in the above list.
The allowable sequences are determined by certain editing
rules for each symbol and can be found in Note 11.
The picture
positions.
b.

string

must

from

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

the

digits

4-42

have

digit
0

THE DATA DIVISION

PICTURE (Cont.)
, represents an insertion comma 1
• represents an actual decimal point 1
B represents an insertion blank
~ represents an insertion zero
/ represents an insertion slash
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
However,
the
indicates the number of occurrences.
following editing symbols can not be used more than once
in a data item: "SO, "V", " " , OCR", and "DB".

A maximum number of 3~ symbols can appear in a picture
string.
Note that the number of symbols in a picture string
and the size of the item represented are not necessarily the
same.
There are two reasons for this discrepancy. First,
the abbreviated form eor 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 4~ alphanumeric character
positions can be described by a picture string of only 5
symbols:
PICTURE IS X(4~).
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, with one exception, do not represent actual physical
character positions within the data item. The exception
involves the use of the SIGN IS SEPARATE clause, which causes
the S (arithmetic sign) to take up a character position. If
the clause is omitted, the character-string
S999V99
represents a 5-position data item. However, if the 'SIGN IS
SEPARATE clause is included, the character-string would
represent a 6-position item.
The total picture character-strings
cannot exceed 262,143 characters.

for

data

item

Other size restrictions for numeric and numeric-edited
are given under the appropriate headings below.

items

There are five categories of data that can be described with
a
PICTURE
clause: alphabetic,
numeric,
alphanumeric,

If the DECIMAL-POINT IS COMMA clause appears in the SPECIAL-NAMES
paragraph, the function of the comma and decimal point is reversed.
4-43

October 1985

THE DATA DIVISION

PICTURE (Cont.)
alphanumeric-edited, and numeric-edited.
A
each category is given in the notes below.
6.

Its picture string can contain only the symbol A or B.

It can contain only the 26 letters of
the space.

However, no check is made at runtime to prevent a move
from
an alphanumeric item storing a non-alphabetic
character.

10.

the

alphabet

and

Definition of a Numeric Item
Its picture string can contain only the symbols 9, P,
and V.
It must contain at least one 9.
string

must

have

from

It can contain only
operational sign.

the

digits

through

The picture
positions.

Definition of an Alphabetic Item

description

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).

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, 0 or I.

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, and P.
If you use
the CURRENCY SIGN IS clause, the new currency sign you
specify replaces the $ in the above list.
The allowable sequences are determined by certain editing
rules for each symbol and can be found in Note 11.
The picture
positions.
b.

string

must

from

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

the

digits

4-44

have

digit
0

October 1985

THE DATA DIVISION

PICTURE (Cont.)
11.

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

Each A in the picture str~ng represents a character
position which can contain only a letter of the alphabet
or a space.

Each 8 in the picture string represents a character
position into which a space character is inserted during
editing.
Examples:

(A-FLD contains the value (92469)
Result

8-FLD picture string
MOVE A-FLD TO B-FLD

99899B99

MOVE A-FLD TO B-FLD

99998888

~12141~16191
IOI912141~1~1~1~1
I 0 19 1

Also see Note 15, 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.
Digit positions specified by P will contain zeros when
referenced as a numeric item, as when the data-item is
moved to a numeric or numeric edited item, or as when
compared to a numeric item.
piS can appear only to the left or right of
the picture
string and must appear together. The P character symbol
cannot appear in a data-item that defines a relative key.
The assumed decimal point is assumed to be to the left of
the string of Ps if 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; in either case, it
is
redundant.

Examples:
PPP9999 (or VPPP9999) defines a data item of four
character
positions
whose contents are 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 are
treated as n000 during a~y decimal point alignment
operation.
The P character symbol cannot appear in a data-item
defines a relative key.
S

that

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
4-45

October 1985

THE DATA DIVISION

PICTURE (Cont.)
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 unless the SIGN IS SEPARATE
clause is included, in which case it occupies one
character position.
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

Result

MOVE A-FLO TO B-FLO

999999

10 I0 0 3 01 5

MOVE A-FLO TO B-FLO

ZZ9999

I~IA 0 3 015

MOVE A-FLO TO B-FLO

ZZZZZZ

IAIA A 3 015

MOVE A-FLO TO B-FLO

ZZZZ.ZZ

1~131o 5 . 01 0

Also see Note 19, 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.
counted in the size of the item.

a character
The comma is

Each /
in a pi6ture string represents
position into which the slash is inserted.
counted in the size of the item.

a character
The slash is

4-46

October 1985

THE DATA DIVISION

PICTURE (Cont.)
Examples:

-0056",25)

(A .... FLO

cOl1tains

0056",25 ;

B-FLO

contains

C-FLO picture string

Result

++999.99
++++9.99
++999.99
+++++.++

I~\+\o 5 6\ .\2\51

MOVE A-FLO TO C-FLO
MOVE B-FLO TO C-FLO
MOVE ZERO TO C-FLO
MOVE ZERO TO C-FLO

1L11~\- 56\.\2\51

1~1+lo 0 01.10101

1~161~ ~ ~161~161

1~1~loI5 61.12\51

MOVE ZERO TO C-FLO

--999.99
,..-999.99
---99.99

MOVE ZERO TO C-FLD

---,...----

1~1~1~16 ~I~I~\

MOVE A-FLO TO C-FLD
MOVE B-FLO TO C-FLO

1~1-loI5 61.12\51

1~1~1~10 01·10\0\

Also see Note 18, Floating Insertion Editing.
Note that the + and - symbols are distinct from the S
(operational ~dg.n) 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

3456}5)

B-FLO character-string
MOVE A-FLO TO a-FLD
MOVE A-FLO TO a-FLO
Also see Note

Result

$9,999.99
1$1 3\' 1 41 5\6\.\ 71 5\
$ 999 , 9:9 9. 9 9 1$1010131,1415161.17151

17, 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.

4-47

THE DATA DIVISION

PICTURE (Cont.)
Examples:

(A-FLO contains 005625)
Result

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

,$$9,999.99

MOVE A-FLO TO B-FLO

$$$,$$$.99

MOVE ZERO TO B-FLO

$$$,999.99

MOVE ZERO TO B-FLO

$$$,$$$.$$

161 $1 0 I, 0 5 61.1 2151
6 6 6 6 '$ 5 61.1 2 1 5 1
1 1 1 1
1616161$ 0 0 o 1.1 0 101
[61 6\61 6 6 6 61 61 61 61

Also see Note 18, Floating Insertion Editing.
12.

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:

13.

Zero suppression and replacement with spaces

Zero suppression and replacement with asterisks

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

Type of Editing Allowed

Alphabetic

Simple lnsertion:

Numeric

None

Alphanumeric

None

Alphanumeric-edited Simp,; e insertion:
\v

Numeric-edited

item

B only

0, Band /

All (except for the restriction given in
Note 14 )

4-48

THE DATA DIVISION

PICTURE (Cont.)
14.

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.

15.

Simple Insertion Editing (, B 0 /)
The, (comma), B (space), 0 (zero), and / (slash or- stroke)
constitute those editing symbols used in simple insertion
editing. These insertion characters represent the character
position in the item into which the character will be
inserted. These symbols are counted in the size of the item.

16.

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. Since the • cannot
be the last symbol in the character-string, it must be
immediately followed by one of the line-ending characters,
either space or carriage return.

17.

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 floating 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 $ will always be printed; there is no
place for a significant digit to the left of the comma if you
have used only one $.
(If the item has a picture of $, $$$
then no digit will ever appear to the left of the comma; a $
will always be 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.)

4-49

THE DATA DIVISION

PICTURE (Cont.)
Editing sign control symbols produce the following
depending on the value of the data being edited.

Result
Data Negative
Data positive

Editing Symbol in
PICTURE
character-string

18.

results

space

spaces

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
numeri~
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

Representing 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 will be 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.

Representing 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.

4-50

THE DATA DIVISION·

PICTURE (Cont.)

19.

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 ~n a pic~ure
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.
tf 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) will be set to the replacement character (with the
exception of the decimal point if the suppresson symbol is an
*) •

The * and the clause BLANK WHEN ZERO may not
same entry.

4-51

appear

the

THE DATA DIVISION

PICTURE (Cont.)
Example:
(A-FLD contains 023456, B--FLD contains 001200)
R-FLD
PICTURE
String

Result
of. MOVE

MOVE A-FLD TO R-FLD

**** **

*234.56

MOVE B-FLD TO R-FLD

xxxx.xx

**12.00 (1)

MOVE A-FLD TO R-FLD

ZZZZ.Zz

234.56 (1)

MOVE B-FLD TO R-FLD

zzzz.zz

12.00

MOVE ZERO TO R-FLD

**** **

****.** (2)

MOVE ZERO TO R-FLD

ZZZZ.ZZ

/::,./::,./::,./::,./::,./::,./::,.

MOVE ZERO TO R-FLD

+****.**

***** ** (4 )

MOVE ZERO TO R-FLD

+ZZZZ.ZZ

/::,./::,./::,./::,./::,./::,./::,./::,.

(3)

(5 )

(1) Zero supression does not take place to the right of
the decimal point.
(2) Decimal point is not suppressed.
(3) Decimal point is replaced by a space.
(4) Plus sign ( + ) is replaced by a space.
(5) Both sign and decimal point are replaced by space.
20.

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

21.

Figure 4-4 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-52

THE DATA DIVISION

PICTURE (Cont.)
FIXED INSERTION

z
a

OTHER

(+~ (~;[
$
9-) (g:)

$$. .$$
{:.} {::} 9 u++.}
~--. :::}

i=
0::

W
V1

Z /'+9}
-9

w
X

u::

f9~
9-

P9 9P

~~ y

$
A
X

{:~ y

$$.

.$$

9P
S

::J
.....
o t:}
0::
W

:I:

r-++}

c-.

y
y

y
MR·S·024·79

Figure 4-4 Picture String Character Chart

4-53

THE DATA DIVISION

REDEFINES

4.9.19

REDEFINES

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

allocated

General Format
[REDEFINES data-name-2 ]

Technical Notes
1.

The REDEFINES clause,
data-name-l.

The level-numbe~s of the data-name-l and data-name-2 must
identical.

This clause must not be used for level-number GG 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. However, the REDEFINES clause may be used to redefine an
item whose picture contains the OCCURS clause.

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

The REDEFINES entry must
describing data-name-2.

The redefinition entries cannot contain VALUE clauses.

Data-name-2 must not be qualified.

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

when

used,

must

immediately

AREA-A USAGE DISPLAY-G.
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 COMPo
05 SUBFIELD-2 PICTURE IS
S999V99 USAGE IS COMPo
AREA-B REDEFINES AREA-A USAGE DISPLAY-G.
04 FIELD-A PICTURE IS X(22).
04 FIELD-B PICTURE IS X(5).
04 FILLER PICTURE IS X(9).

4-54

the

follow
be

entries

THE DATA DIVISION

REDEFINES (Cont.)
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

FIELD-3

SUBFIELO-l

SUBFIELD-l

Total 6-bit characters

AREA-B:

FIELD-A

FIELD-B

FILLER

Total 6-bit characters

4-55

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

THE DATA DIVISION

RENAMES (level-66)

4.9.20

RENAMES (level-66)

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

groupings

General Format

THROUGH}
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.

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

The words THRU and THROUGH are equivalent.

Data-name-2 and data-name-3 must be the names of items in the
associated 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-56

THE DATA DIVISION

RENAMES (level-66) (Cont.)
If data-name-3 is not specified, data-name-2 can be either a
group item or an elementary item.
If it 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.
5.

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-57

RENAMES

THE DATA DIVISION

SIGN
4.9.21

SIGN

Function
The SIGN clause specifies the position and the mode of
of the operational sign.

representation

General Format

[TSIGN IS] {

~~~~t~~G } [SEPARATE CHARACTER]]

Technical Notes
1.

The optional SIGN clause, if present, specifies the position
and the mode of representation of the operational sign for
the numeric data description entry to which it applies, or
for each numeric data description entry subordinate to the
group to which it applies. The SIGN clause applies only to
numeric data description entries whose PICTURE contains the
character S; the S indicates the presence of an' operational
sign.
However,
it does not indicate the representation or
the position of the sign.

The numeric data description entries to which the SIGN clause
applies must be described as USAGE IS DISPLAY.

At most one SIGN clause may apply to any given
description entry.

If the CODE-SET clause is specified, any signed numeric data
description entries associated with that file description
entry must be described with the SIGN IS SEPARATE clause.

A numeric data description entry whose PICTURE contains the
character S, but to which no optional SIGN clause applies,
has an operational sign which is associated with the trailing
digit position of the elementary item.

If the optional SEPARATE CHARACTER phrase is not present, the
following rules apply:

numeric

data

The operational sign will be presumed to be
with the trailing digit position of the
numeric data item.

The letter S in a PICTURE character-string is not counted
in determining the size of the item (in terms of standard
data format characters).

4-58

associated
elementary

THE DATA DIVISION

SIGN (Cont.)
7.

If the optional SEPARATE CHARACTER
following rules apply:

phrase

present,

the

There is no default condition for the operational sign in
this case. You may specify the SEPARATE CHARACTER phrase
only when either LEADING or TRAILING is also specified.

The letter S in a PICTURE character-string is counted in
determining the size of the item (in terms of standard
data format characters).

The operational signs for positive and negative are the
standard data format characters + and -, respectively.

The various possiblities for the SIGN and SEPARATE
CHARACTER clauses are illustrated below:
(value is -111)
Options

SIXBIT
Representation

none
SIGN LEADING
SIGN TRAILING
SIGN LEADING SEPARATE
SIGN TRAILING SEPARATE

OOOOOOllJ
]00000111

OOOOOOllJ
-000000111
000000111-

Every numeric data description entry whose PICTURE contains
the character S is a signed numeric data description entry.
If a SIGN clause applies to such an entry and conversion is
necessary
for
purposes of computation or comparisons,
conversion takes place automatically.

4-59

THE DATA DIVISION

SYNCHRONIZED
4.9.22

SYNCHRONIZED

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

elementary

General Format

SYNCHRONIZED}
[{ SYNC

LEFT
[ RIGHT ~

Technical Notes
1.

This clause can appear only in the
elementary item.

data

description

This clause is optional.
SYNCHRONIZED LEFT.

omit

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

you

which

this

the

default

the size of any
belongs, and

elementary

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 will begin 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 will terminate 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 will be
automatically generated by the compiler. The content of this
FILLER is indeterminate.

4-60

THE DATA DIVISION

SIGN (Cont.)
7.

If the optional SEPARATE CHARACTER
following rules apply:

phrase

present,

the

There is no default condition for the operational sign in
this case. You can specify the SEPARATE CHARACTER phrase
only when either LEADING or TRAILING is also specified.

The letter S in. a PICTURE character-string is counted in
determining the size of the item (in terms of standard
data format characters).

The operational signs for positive and negative are the
standard data format characters + and -, respectively.

The various possiblities for the SIGN and SEPARATE
CHARACTER clauses are illustrated below:
(value is -111)
Options

SIXBIT
Representation

none
SIGN LEADING
SIGN TRAILING
SIGN LEADING SEPARATE
SIGN TRAILING SEPARATE

OOOOOOllJ
]00000111

OOOOOOllJ
-000000111
000000111-

4-61

THE DATA DIVISION

SYNCHRONIZED
4.9.23

SYNCHRONIZED

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

elementary

General Format

J11lJ

SYNCHRONIZED}
[{ SYNC

LEFT
[ RI GHT

MR-S-1293-81

Technical Notes
1.

This clause can appear only in the
elementary item.

data

description

This clause is optional.
SYNCHRONIZED LEFT.

omit

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

you

which

this

the

default

the size of any
belongs, and

elementary

item

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. For example,
01

RECORD-A.
02 FIELD-A
02 FIELD-B

PIC XX SYNC LEFT.
PIC X.

MOVE "ABM TO FIELD-A.
MOVE Me" TO FIELD-B.

4-62

October 1985

THE DATA DIVISION

SYNCHRONIZED (Cont.)
is ~tored as (in SIXBIT) :
A

c
5.

I I I I I I
I I I I LI
B

(FIELD-A)
(FIELD-B)

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. For example,
RECORD-A.
02 FIELD-A
02 FIELD-B

PIC X.
PIC XX SYNC RIGHT.

MOVE nAn TO FIELD-A.
MOVE "BC n TO FIELD-B.
is stored as (in SIXBIT):
A

I I I I

(FIELD-A)
(FIELD-B)

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

4-62.1

October 1985

THE DATA DIVISION

(THIS PAGE INTENTIONALLY LEFT BLANK.)

4-62.2

THE DATA DIVISION

USAGE (Cont.)
4.

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. See
Note 3 above.

COMPUTATIONAL items of 10 or fewer decimal positions will
be
SYNCHRONIZED
RIGHT
in
one
computer
word.
Computational items of more than 10 decimal positions
will be SYNCHRONIZED RIGHT in two full computer words.
The maximum size of a COMP item is 18 digits.

The following illustrations
COMPUTATIONAL item.

give

the

format

tr---- sign

Io I
I

I·WORD COMPUTATIONAL ITEM

tr--- sign

Io II

Eno'usc~
o

2·WORD COMPUTATIONAL ITEM

COMPUTATIONAL-l (COMP-l)
a.

COMP-l is equivalent to COMPUTATIONAL-I.

A COMPUTATIONAL-l item can contain a value,
in floating
point format,
to be used in computations.
It must be
numeric. A COMP-l 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-l and
cannot be used as an operand in arithmetic computations.
See Note 3 above.

COMPUTATIONAL-l items will be SYNCHRONIZED
computer word.

4-63

one

full

THE DATA DIVISION

USAGE (Cont.)
e.

The following illustration
COMPUTATIONAL-l item.

gives

the

format

tr--- SI,l!11

hillal y
L' \ P( 111cll t

o 1

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. See Note 3 above.

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.

~
0

17 18

SYNCHRONIZED

2627

LEFT

SYNCHRONIZED

COMP-3 items may be
RIGHT.

COMP-3 items may share a computer word with other COMP-3
items or with DISPLAY-9 items. However, COMP-3 items
will 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 may 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.

4-64

THE DATA DIVISION

USAGE (Cont.)
The nonprinting plus sign is actually an absolute value
indicator.
Any positive or negative number which is
moved into an item with this sign will receive this sign.
In
arithmetic
computations
and
numeric
editing
operations, items containing the nonprinting plus sign
are treated as positive.
7.

DISPLAY
a.

DISPLAY-6
a.

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

A DISPLAY-6 item represents a string of 6-bit characters.
Its picture string may contain any picture symbols.
Refer to Appendix C for the SIXBIT collating sequence.

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

The illustration below given the format
word.

DISPLAY is equivalent to DISPLAY-6.
However, you may
change DISPLAY to be DISPLAY-7 or 9 with the DISPLAY IS
clause. You may also cause the compiler to consider all
DISPLAY items to be DISPLAY-9 by using the IX switch when
compiling your program.

DlSPLAY-6

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

DISPLAY-7
a.

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

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

Bit 35 of a word represented
used.

The maximum
characters.

DISPLAY-7

length

4-65

this

format

never

item

4,096

THE DATA DIVISION

USAGE (Cont.)
e.

The illustration below gives the format
word.

10.

DISPLAY-7

DISPLAY-9
a.

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

DISPLAY-9 items may be SYNCHRONIZED LEFT or SYNCHRONIZED
RIGHT as desired; otherwise, they may share a computer
word with ather DISPLAY-9 or COMP-3 items.
If the item
is SYNCHRONIZED RIGHT,
the last character of the item
will end 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.

DISPLAY-9
characters.
symbol.

11.

·14

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

length

DISPLAY-9

item

i 7 18

4,096

2627

If the USAGE clause is omitted for an elementary item and
the IX switch has been included in the compiler command
string, its USAGE is assumed to be DISPLAY-9 •

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.
4-66

OCCURS

clause,

THE DATA DIVISION

USAGE (Cont.)
i.

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 nonprinting plus sign.
Although octal 12, 14 and 16 represent 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.
The nonprinting plus sign is actually an absolute value
indicator. Any positive or negative number that 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.

DISPLAY
a.

DISPLAY is equivalent to DISPLAY-6.
However, you can
change DISPLAY to be DISPLAY-7 or 9 with the DISPLAY IS
clause. You can also cause the compiler to consider all
DISPLAY items to be DISPLAY-9 by using the IX switch when
compiling your program.

The maximum size of any group item in the FILE SECTION is
4095 characters
(7777).
The maximum size of any group
item in the WORKING-STORAGE SECTION is 262,143 characters
(777777).
These maximum sizes apply to DISPLAY-6,
DISPLAY-7, and DISPLAY-9 usage.

DISPLAY-6
a.

DISPLAY is equivalent to DISPLAY-6 when the IX switch is
not given in the compiler command string, or the DISPLAY
IS clause is not present.

A DISPLAY-6 item represents a string of 6-bit characters.
Its picture string can contain any picture symbols.
Refer to Appendix C for the SIxaIT 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

35
MR-S-1022-81

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

DISPLAY-7
a.

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

October 1985

THE DATA DIVISION

USAGE (Cont.)
b.

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.
Bit 35 of a word represented in this format is never
used.

The maximum
characters.

length

DrSPLAY-7

item

DISPLAY is equivalent to DISPLAY-7 when
DISPLAY-7 clause is present.

the

The illustration below gives the format
word.

4,095

DISPLAY
a

DISPLAY-7

35
MR-S-1023-81

DISPLAY-9
a.

DISPLAY is equivalent to DISPLAY-9 when the IX switch is
included in the command string to the compiler, or
DISPLAY IS DISPLAY~9 clause is present.

A DISPLAY-9
characters.
symbol.

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.

I
f.

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

length

11.

10.

17 18

DISPLAY-9

item

2627

4,095

MR-S-1024-81

If the USAGE clause is omitted for an elementary item and
the IX switch has been included in the compiler command
string, its USAGE is assumed to be DISPLAY-9 •

INDEX
a.

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

An index data-item must not have a PICTURE.

4-68

October 1985

THE DATA DIVISION

VALUE (Cont.)
7.

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

If the category of an item is numeric, all literals in
the VALUE clause must be numerlC. 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 may hav~ 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
nonnumeric literals.
The literal will
be
aligned
according
to
the normal alignment rules (see the
JUSTIFIED clause, Section 4.9.15) 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 (8), ZERO(E) (S), QUOTE (S) ,
LOW-VALUE(S), and HIGH-VA~UE(S) ma~ be 5uQ$tituted for a
literal.
If the item
1S
numerlC,
only
ZERO(E) (S),
LOW-VALUE(S), and HIGH-VALVE(S) are allowed.

4-69

THE DATA DIVISION

Report Description (RD)

4.9.25

Report Description (RD)

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

the

physical

General Format
RD

report-name

[CODE

mnemonic-name ]

CONTROL IS
CONTROLS ARE

[

PAGE

FINAL
identifier-l [identifier-2]
FINAL identifier-l [identifier-2]

}{

LIMIT IS
LIMITS ARE

[ HE.L\DING

[ LAST DETAIL

}]

LI NE }
LINES

i nteger-l

integer-2J [FIRST

...

DETAIL

integer-4] [FOOTING

integer-3 ]

inte ger-5]]

..:.

Technical Notes
1.

The order of
immaterial.

appearance

the

A fixed data-name PAGE-COUNTER is automatically generated for
each RD entry.

optional

clauses

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.
3.

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-70

THE DATA DIVISION

VALUE (Cont.)
7.

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

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
nonnumeric literals. The literal is aligned according to
the normal alignment rules (see the JUSTIFIED clause,
Section 4.9.16) except that the number of characters in
the literal must not exceed the size of the item.

Initialization takes place independent of any BLANK
ZERO or JUSTIFIED clause that may be specified.

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.

WHEN

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-71

THE DATA DIVISION

Report Description (RD)
4.9.26

Report Description (RD)

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

the

physical

General Format

RD report-name
[CODE mnemonic-name]

FINAL
CONTROL IS
-.
-. .
•
.•
{CONTROLS ARE} { ldentlfler-l [ldentlfler-2] ...
FINAL identifier-l ~dentifier-2J

.J]

fLIMIT IS }.
fLINES}
[ PAGE lLIMITS ARE lnteger-l lLINES
[HEADING inte ger-2] [FIRST DETAIL inte ger-3]

[ LAST DETAIL lnteger-4] [FOOTING integer-5 ] ] -'MR-S-1296-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 baspd on the number of lines specified in
the PAGE-LIMIT clause. You cannot change the value of the
LINE-COUNTER.

4-72

October 1985

THE DATA DIVISION

Report Description (RD) (Cont.)
4.

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

Each of the above clauses appears in this chapter separately,
in alphabetical order.

4-73

October 1985

THE DATA DIVISION

CODE
4.9.27

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~
MR-S-1297-81

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 SPECIAL-NAMES paragraph
the Environment Division, described in Section 3.1.4.

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-74

THE DATA DIVISION

CONTROL
4.9.28

CONTROL

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

If{
CONTROL IS}
~ CONTROLS ARE

FI NAL
identifier-l
[identifier-2] '"
{
FINAL i denti fi er-l
[i denti fi er-2]

...

}]

MR-S-1298-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.
Each
identifier in the CONTROL clause must identify a different
data item. Identifiers can be qualified, but they cannot be
subscripted or indexed.

4-75

HEADING

October 1985

THE DATA DIVISION

PAGE LIMIT
4.9.29

PAGE LIMIT

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

control

must

General Format

LIMIT IS l·
{LINE l
PAGE {LIMITS AREf lnteger-l LINESf
[HEADING integer-2] [FIRST DETAIL integer-3]
[LAST DETAIL integer-4] [FOOTING integer-s]
MR·S·1028·81

Technical Notes
1.

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

format

All integers must have a positive value less than
Integer-2
through
integer-S 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.9.32
and 4.9.33 respectively), integer-2 through integer-S 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-S.

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

the

integer-2:

Default is I

integer-3:

Default is the value of integer-2
4-76

S12.
than

beginning
to

October 1985

THE DATA DIVISION

PAGE LIMIT (Cont.)
integer-4:

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

integer-S:

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

4-77

if
the

October 1985

THE DATA DIVISION

REPORT GROUP DESCRIPTIONS
4.9.38

Report Group Description

Function
The Report Group Description entry specifies the
format of a particular report group.

characteristics

and

General Format

Format 1:
01 [ data-narne-1 ]
integer-1
}]
LINE NUMBER IS { PLUS integer-2
[
NEXT PAGE

[

integer-3}]
NEXT GROUP IS { PLUS
integer-4
NEXT PAGE
REPORT HEADING
RH
PAGE HEADING
PH {CONTROL HEADING} {identifier-I}
CH
FINAL
TYPE IS DETAIL
DE {CONTROL FOOTING} {identifier-2 l
CF
FINAL
i
PAGE FOOTING
PF
REPORT FOOTING
RF

I]
[ I
USAGE IS]
[-

DISPLAY
DISPLAY-6
DISPLAY-Z-·
DISPLAV-9
MR-S-1029-81

4-78

October 1985

THE DATA DI~ISION

REPORT GROUP DESCRIPTIONS (Cont.)

Format 2

le've l-nulTber [data-name-I]
[ BLANK WHEN ZERO]
[ COLUMN NUMBER IS i nteger-I ]
[ GROUP INDI CATE ]

integer-2}]

LINE NUMBER IS { PLUS integer-3
NEXT PAGE
[

[I ;J2 URE I. IS character-string]
RESET ON {identifier-It]
[-FINAL
f
SOURCE IS i dent i fier-2
SUM identifier-3 [,identifier-4]
{ VALUE IS literal-I

[ [USAGE IS]

}
••• [UPON data-name-~

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

MR·S·1030·Sl

4-79

October 1985

THE DATA DIVISION

REPORT GROUP DESCRIPTIONS (Cont.)
Technical Notes

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

A report group must have a data-name if it is referred to
a Procedure Division statement.

Up to three hierarchical levels are
group description.

All elementary items must have both a PICTURE clause and
of 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, which is Section 4.9.12.

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 level-~l item is elementary, the clauses in Format
can be used in addition to the clauses in Format 1.

The remalnlng clauses
following pages.

are

4-8~

permitted

described

detail

report

one

2
the

October 1985

THE DATA DIVISION

COLUMN NUMBER
4.9.31

COLUMN NUMBER

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

~OLUMN NUMBER IS

integer-l~
MR-S-1299-Bl

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.

An entry that contains a COLUMN NUMBER clause but no LINE
NUMBER clause must be subordinate to an entry that contains a
LINE NUMBER clause.

4-81

October 1985

THE DATA DIVISION

GROUP INDICATE
4.9.32

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

INDI CATEJ
MR-S-1300-81

Technical Notes

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.

The GROUP INDICATE clause can only appear in a DETAIL report
entry defining a printable item.
(A printable item is a data
item that contains a COLUMN and PICTURE clause.)

4-82

October 1985

THE DATA DIVISION

LINE NUMBER
4.9.33

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

GINE NUMBER IS

{

i nteger-l
PLUS i nteger-2

NEXT
PAGE
- MR-S-1301-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 does cause 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.
The LINE NUMBER clause is the
only way for you to change the current value of LINE-COUNTER.

A relative LINE NUMBER clause cannot be the first LINE NUMBER
clause in a PAGE FOOTING group.

4-83

can

not

contradict

presented

October 1985

THE DATA DIVISION

LINE NUMBER (Cont.)
8.

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 then spaces as
follows.
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-84

October 1985

THE DATA DIVISION

NEXT GROUP
4.9.34

NEXT GROUP

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

condition

following

the

General Format

GROUP

integer-l
}
PLUS ; nteger-2
NfXf PAGE
MR-S-1302-81

Technical Notes

The NEXT GROUP clause can appear only at the ~l-level of a
report group.
However, the NEXT GROUP clause cannot be
specified in a REPORT FOOTING 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 indicates a line number to which
is set after the group is presented.

PLUS integer-2 indicates 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.

The NEXT PAGE clause cannot be specified in
report group.

4-85

the

LINE-COUNTER

PAGE

after
FOOTING

October 1985

THE DATA DIVISION

RESET
4.9.35

RESET

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

the

SUM

General Format
RESET ON { i dent i fi er-ll

FINAL

MR-S-1033-81

Technical Notes
1.

Identifier must be one of the identifiers associated with 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 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-86

SUM

October 1985

THE DATA DIVISION

SOURCE
4.9.36

SOURCE

Function
The SOURCE clause indicates the source of the data for a report item.
General Format
SOURCE

identifier
MR-S-1303-81

Technical Notes
1.

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

Identifier must reference an item that appears in the File or
Working-Storage Section.

The identifier can be subscripted or indexed (see the
clause, Section 4.9.18).

OCCURS

When the report group is presented, the contents of
report item are replaced by the contents of identifier.

this

4-87

October 1985

THE DATA DIVISION

SUM
4.9.37

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-2J ••. [ UPON da~a-name-l ]
MR-S-1304-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,
Section 5.9.16.)

The identifiers cannot be subscripted or indexed.

4-88

October 1985

THE DATA DIVISION

TYPE
4.9.38

TYPE

Function
The TYPE clause specifies the particular type of report group that is
described by this entry and indicates the time when the report group
is generated.
General Format
REPORT HEADING
RH
PAGE HEADING

.E!! {EaNTROL HEADING} {~~~~C i fier-n }
TYPE IS

DETAIL
DE
-

{CONTROL FOOTING} {identifier-n}
CF
FINAL

PAGE FOOTING
PF
REPORT FOOTING
RF
MR-S-1035-81

Technical Notes
1.

RH is an abbreviation for REPORT HEADING.
PH is an abbreviation for PAGE HEADING.
CH is an abbreviation for CONTROL HEADING.
DE is an abbreviation for DETAIL.
CF is an abbreviation for CONTROL FOOTING.
PF is an abbreviation for PAGE FOOTING.
RF is an abbreviation for REPORT FOOTING.

If the report group is described as T~PE 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.
4-88.1

October 1985

THE DATA DIVISION

TYPE (Cont.)

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.
In the event that a CONTROL
FOOTING occurs after a control break and is the first line
printed on the next page, change one or more
values
(integer-I, integer-4, and integer-5) of the PAGE LIMIT
clause.

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-88.2

FINAL, must
the CONTROL

be one of the
clause in the RD

October 1985

THE DATA DIVISION

GENERAL FORMAT FOR DATA DIVISION
DATA DIVISION.
[rILE SECTION.
[ED fil e-name

GLOCK CONTAINS

[i nteger-l Tq]

i nteger-2

RECORD(S) }~
tj CHARACTERS
iJ

~RECORD CONTAINS

Qnteger-3 TOJ

i nteger-4

CHARACTER~

LABEL
--

STANDARD}
f tSOMITTED

{RECORD IS t
RECORDS ARE

rJ ill
L-- U
IVALUE OF

I DENTI FI CATI ON tIS

{d~ta-name-l tl
llteral-l

tlJ

IS
t~ data-name-3
i nteger-5, i nteger-6 fJ
l'DATE-WRITTEN IS 'd~ta-name-2}fllusER_NUMBER
tllteral-2 UL

IrLATA {RECORDs
RECORD IS l
data-name-4
ARE f

l--

ILINAGE IS

[data-name-5J

... ]

LINES !WIT.H FOOTING AT
flnteger-8
U
tj ~ata-name-6l
lnteger-7 f
L

J ?ata-name-7 fl

ILINES AT TOP '~ata-name-8
I LINES AT BOTTOM
L
- f lnteger-9 f L

data-name-9
{ lnteger-IO

nl
UJ

[CODE-SET IS al phabet-name ]

[

t report-name-l

REPORT IS
{ ~S AREf

[!eport-name-~

ASCII
SIXBIT
BINARY
RECORDING

STANDARD-ASCI I
STANDARD ASCII

4-89

October 1985

THE DATA DIVISION

GENERAL FORMAT FOR DATA DIVISION

[so fi 1e-name
~RECORD CONTAINS

integer-2 CHARACTER~

C=integer-l TO:]

~ata-name-2J

"~PATA {RECORD
RECORDS ISARE } data-name-l

ITrecord-descri ption-entry}

.. .]

J ...J

...

C:WORKING-STORAGE SECTION.

77-1 evel-descri pti on-entry] ...
[ record-description-entry

C:LINKAGE SECTION.
f]7-1eve1-descri Ption-entry ]

~ecord-descriPtion-entry

]
...

~OMMUNICATION SECTION.

J ...J

[Sommunication-description-entry
[!ecord-description-entry:J ...

4-90

MR-S-1306-81

THE DATA DIVISION
GENERAL FORMAT FOR ,DATA DIVISION
REPORT SECTION.

report-name

[CODE

[I
[

mnemonic-name ]

CONTROL IS
CONTROLS ARE

PAGE

){

LIMIT IS
LH1ITS ARE

[ HEADING

F I ~JAL
identifier-l [identifier-2] ...
FINAL identifier-l [ identifier-2]

lnteger-l

integer-2J [FIRST

[ LAST DETAIL

{record-description-entry}

LINE
LINES )

DETAIL

i nteger-4 ] [FOOT HiG

...J . J

4-91

integer-3 ]

i nteger-5

J] -'-

}]

THE DATA DIVISION
GENERAL FORMAT FOR DATA DESCRIPTION ENTRY
FORMAT 1:

level-number

data-name-l }
{ FILLER

[REDEFINES data-name-2 ]

[ {

~TURE } IS character-string]

USAGE IS

COMPUTATIONAL
CQt.1P
COOUTATIONAL-l
COMP-l
CQMi5'TI'fATI 0NAL - 3
COMP-3
DISPLAY
DISPLAY-6
DISPLAY-7
DISPLAY-9
INDEX
iJAfA'BASE-KEY
DBKEY

'OCCURS {~nteger-l TO i nteger-2 TIMES DEPENDING ON data-name-3 }
L-nteger-2 TIMES
1

ASCENDI NG }
[ { DESCENDING

KEY IS data-name-4

[data-name-~

~INDEXED BY index-name-l [i ndex-name-2]

[{ ~H RON IZE D} [~i ~~TJJ

[{ ~IFIED }{~~~T}]
[]LANK WHEN ZERO]

~ALUE IS litera~

4-92

...

THE DATA DIVISION
GENERALtFORMAT FOR DATA DESCRIPTION ENTRY
FORMAT 2:

66 data-name-l RENAMES data-name-2

~{ ~UGH} data-name-3~

FORMAT 3:

J VALUE IS }
l VALUES ARE

88 condition-name

[iter a

l-3 0

::UGH}

1iter a

1 i tera 1-1

l-4]

4-93

1 i tera 1-2J
LJrJ{ THROUGH}
THRU

THE DATA DIVISION
GENERAL FORMAT FOR REPORT GROUP DESCRIPTION ENTRY
Format 1

[ d at a- n arne - 1 ]

LI NE

NU~1BER

integer-l
}]
PLUS i nteger- 2
{ NEXT PAGE

GROUP

integer-3
PLUS i nteger-4
{ NEXT PAGE

[

REPORT

}]

HEADING

RH
PAGE

HEADING

PH f CONTROL HEADING} { identifier-I}
-1CH
FINAL
TYPE

DETAIL
DE

f CONTROL

- 1CF

FOOTING}

PAGE FOOTING
PF
REP OR T FOOT I NG
RF

DISPLAY

DISP[AY-6

DISPLAY-7
DISPLAY-9

I] ~

f identifier-2 }

1FINAL

THE DATA DIVISION
GENERAL FORMAT FOR REPORT GROUP DESCRIPTION ENTRY
Format 2

level-number

[data-name-l ]

[~ WHEN llliQ ]

[COLUMN

NUMBER

[GROUP

INDICATE]

[

J JUSTIFIED

\ JUST

LINE

NUMBER

[

integer-I]

RIGHT]

IS {

~~G~,ge~~ieger-3
}]
PAGE

Nrn

[ 1~:~TURE I IS character-string ]
[RESET
_ ON

identifier-l
FINAL

SOURCE IS identifier-2
SUM identifier-3 [identifier-4]
{ VALUE IS literal-l

I]
[ I
[USAGE

IS ]

DISPLAY
DISPLAY-6
DISPLAY-7
DISPLAY-9

..:,.

4-95

[J!.!:.Q!i data-name-2)}

CHAPTER 5
THE PROCEDURE DIVISION

The Procedure Division specifies the processing to be performed on the
files and 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 entry must be either the DECLARATIVES
header (see the USE statement, Section 5.9.42), or a para9raph-name or
section-name.

PROCEDURE DIVISION

~SING data-name-l

~ata-name-2~

~DECLARATIVES.
{ section-name SECTION

~segment-number~

~aragraPh-name. C=sentenc~

. .. ~

declarative-sentence

... ~ ... }

END DECLARATIVES~
{ section-name SECTION

~egment-number~

~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 may 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 the
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 via 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

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.

5-2

THE PROCEDURE DIVISION
Table 5-1
Procedure Verb and Statement Categories
Verb Category

Statement Category

ADD
COMPUTE
DIVIDE
MULTIPLY
SUBTRACT
INSPECT

ARITHMETIC

IMPERATIVE

ALTER
CALL
ENTER
ENTRY
EXIT PROGRAM
GOBACK
GO TO
PERFORM
STOP

SEQUENCE-CONTROL

IMPERATIVE

ACCEPT
INSPECT
MOVE
SET
STRING
UNSTRING

DATA MOVEMENT

IMPERATIVE

CANCEL
FREE
INSPECT
MERGE
RELEASE
RETAIN
RETURN
SEARCH
SORT
TRACE

MISCELLANEOUS

IMPERATIVE

GENERATE
INITIATE
TERMINATE

REPORT

IM~ERATIVE

ACCEPT
CLOSE
DELETE
DISPLAY
OPEN
READ
REWRITE
WRITE

1-0

IMPERATIVE

CONDITIONAL

COpy
ENTER
USE

COMPILER-DIRECTING

Verb

5-3

THE PROCEDURE DIVISION
5.1.2

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.
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 (u~ed with the READ verb for mass storage devices).
A compiler-directing sentence consists of a single compiler-directing
statement.
Compiler-directing sentences are usee to indicate the end
point of a PERFORM loop (EXIT), to copy library entries (COPY), and to
specify
procedures
for
input-output errors (USE).
Generally,
compiler-directing sentences generate no object-program coding.

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 Section 1.3, Source Program Format) 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
and be followed by the word SECTION followed by a priority number, if
desired, followed by a terminating period.
section-name SECTION nne
If the section-name is in the Declaratives portion, it may not have a
priority number. A USE statement may 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.
5-4

THE PROCEDURE DIVISION
When a section-name is referenced, the word SECTION is not allowed
the reference.

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 sect(ons 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.
The method used to achieve this reduction is called
segmentation.
Segmentation consists of dividing the Procedure Division sections into
logically related groupings called segments. You can define 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 you wish 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 ~egment is always resident in memory and is never
overlaid.

SEGMENT-LIMIT
up to 49

Nonresident;
ALTERed GO
TOs retained

These
segments are
nonresident
and are brought
into memory when
needed.
Any ALTERed GO TOs retain
their most
recently
set
values.

50 through 99

Nonresldent;
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,
but
are
reset to their
original setting each time
the segment is reloaded into
memory_

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.

The 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.

5.4

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 may 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 fqllowing rules for information and evaluation apply to arithmetic
expressions.
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:

5-6

THE PROCEDURE DIVISION
First:
then
then
and then

unary +, unary -

** and

and /
+ and k

(exponentiation)
(multiplication and division)
(addition and subtraction)

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 may begin with one of the following:
(- + variable

and may end only with one of the following:
) variable
4.

5.5

There must be a one-to-one correspondence between left and
right parentheses ln 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 path and the false path) of control
depending upon the truth value of a test. Conditional expressions can
be used in conditional (IF) statements and in PERFORM statements
(formate 3 and 4).
A conditional expression can be one of the
following types:
Relation condition
Class condition
Condition-name condition
Sign condition

(greater than, equal to, less than)
(numeric or alphabetic)
(level-SS condition-names)
(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 may be an identifier, a literal, a figurati~e constant, or an
arithmetic expression.
Comparison of two numerlC
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-9.
A numeric-edited operand may not be compared to a numeric operand. An
alphanumeric operand may not be compared to a numeric operand unless
the alphanumeric operand contains no characters other than numeric
digits. For example, the statement:
IF NUM < "2".
is permissible but the statement:
IF NUM < "2.0".
is not.
5-7

THE PROCEDURE DIVISION

5.5.1.1 Format of a Relation-Condition - The
relation condition is
identifier-I)
li~eral-~
.
arlthmetlc-expresslon-l
{ figurative-constant-l

Jl relational-o perator

general

i~entifier-2
ll~eral-?

.
arlthmetlc-expresslon-2
figurative-constant-2

format

for

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.
Meaning

Relational Operator
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 nonnumeric, a true zero
condition may be established by a nonnumeric test followed by a
comparison with zero.

5.5.1.4 Comparison of Nonnumeric Items - For operands whose category
is nonnumeric (or where one operand is numeric and the other is
nonnumeric), 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 C). The size of an operand is the total number of characters
in the operand. Blanks and tabs are not ignored when a nonnumeric
item is compared to ZERO. The presence of either blanks, tabs, or
both in the operand will cause the test result to be NOT EQUAL.
There are three cases to consider: operands of equal size,
of unequal size, and operands with differing justification.

5-8

operands

THE PROCEDURE DIVISION
1.

Operands of equal size - If the operands are of equal size,
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 size - If the operands are of unequal
size,
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 "B" and PICTURE XXX,
VALUE "B", 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.5.2.1

Format of a Class Condition

identifier

[NOT]

ALPHABETIC
NUMERIC

item

for

being

wholly

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 will result if either of
the two previously mentioned tests are attempted.

5-9

THE PROCEDURE DIVISION
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:

the

For nonnumeric 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 must have one of the four
following representations:
a leading graphic sign ("+" or
"-"), a trailing graphic sign, a leading embedded 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,
which causes leading and trailing blanks
and tabs to be ,ignored, may be selected
by
a
switch setting during system
installation. 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 Condition - The general format for
a condition-name is

r=NOT]

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
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-10

THE PROCEDURE DIVISION
5.5.4

Sign Condition

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.1 Format of a Sign Condition - The general format
condition follows.

{ identifier
arithmetic-expression

IS [N~]

POSITIVE
NEGATIVE
ZERO

{

for

sign

}

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 will make an item nonnumeric.

5.5.5

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.6

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.

NOT

Entire condition is true
simple condition is false.

the

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 and/or OR. A
compound-condition can contain any combination of types of conditional
expressions (relational, class, condition-name, and sign).

5-11

THE PROCEDURE DIVISION
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 may be used either to improve readability or to override
the effects of 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.
You may 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
NEGATIV~

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.
Figure 5-1 illustrates the effect of this statement
order of evaluation.
5-12

and

the

THE PROCEDURE DIVISION

True

MA-S.Q25-79

Figure 5-1 Order of Evaluation of a Conditional Expression
2.

Using parentheses to override normal order of evaluation
To illustrate this usage, a compound-conditional is shown in
three forms in Figure 5-2, each accompanied by a flow diagram
showing the result of each.

5-13

THE PROCEDURE DIVISION
F1 = F2 AND F3 '-' F4 OR F5 = F6 AND F7 = Fa

F1 = F2 AND (F3 = F4 OR F5 = F6 AND F7 = Fa)

>----------y---------.-..-t Path
False
False

True

F1=F2 AND ((F3 =; F4 OR F5 = F6) AND F7 = Fa)

Figure 5-2 Order of Evaluation of a Compound-conditional Expression

5-14

THE PROCEDURE DIVISION
5.5.7

Combined and Negated Combined Conditions

A combined condition results from connecting conditions with one of
the logical operators 'AND' or 'OR'. The general format of a combined
condition follows:
condition { {

~~D}

condition}

"Condition" may be one of the following:
1.

A simple condition

A negated simple condition

A combined condition

A negated combined condition: that is, the 'NOT' logical
operator followed by a combined condition enclosed within
parentheses.

Combinations of the above, specified according to the rules
summarized in Table 5-3 Combinations of Conditions, Logical
Operators, and Parentheses.

Although parentheses need never be used when either 'AND' or 'OR' (but
not both) is used exclusively in a combined condition, parentheses may
be used to effect a final truth value when a mixture of 'AND',
'OR'
and 'NOT' is used.
(See Table 5-3 Combinations of Conditions, Logical
Operators, and Parentheses.)
Table 5-3 indicates the ways in which conditions and logical operators
may be combined and parenthesized.
There must be a one-to-one
correspondence between left and right parentheses so that each left
parenthesis occurs to the left of its corresponding right parenthesis.
Table 5-3
Conditions, Logical Operators, and Parentheses Combinations
In a left-to-right sequence of elements:
Given the
following
element

Location in
conditional
expression
First Last

Element, when not
first, may be
immediately preceded by only:

Element, when not
last, may be
immediately followed by only:

simplecondition

Yes

OR, NOT, AND,

OR, AND,

OR or AND

simple-condition,

NOT

Yes

OR, AND,

(

Yes

OR, NOT" AND,

)

Yes

simple-condition,

(

)

------.
)

simple-condition,

(

5-15

simple-condition,
NOT, (

(

)

OR, AND,

)

(

THE PROCEDURE DIVISION
Thus, the element pair 'OR NOT' is permissible while the pair 'NOT OR'
is not permissible i
'NOT' is permissible while 'NOT NOT' is not
permissible.

5.5.8

Abbreviated Combined Relation Conditions

Simple or negated simple relation conditions can be combined with
logical connectives in a consecutive sequence. When a succeeding
relation condition contains a subject or subject and. relational
operator that is common with the preceding relation condition, and no
parentheses are used within such a consecutive sequence, then any
relation condition except the first may be abbreviated by one of the
following:
1.

The omission of the subject of the relation condition

The omission of the subject and relational
relation condition

operator

the

The format for an abbreviated combined relation condition follows:

relation-condition

{{~~D} [NOl] ~elational-operato~

object }

Within a sequence of relation conditions both of the above forms of
abbreviation may be used. The effect of using such abbreviations is
as if the last preceding stated subject were inserted in place of the
omitted subject, and the last stated relational operator were inserted
in place of the omitted relational operator.
The result of such
implied
insertion
must
comply with the rules of Table 5-3,
Combinations of Conditions, Logical Operators, and Parentheses.
This
insertion of an omitted subject and/or relational operator terminates
once a complete simple condition is encountered within a complex
condition.
The interpretation ~pplied to the use of the word
abbreviated combined relation condition is as follows:

'NOT'

If the word immediately following 'NOT' is 'GREATER', '>',
'LESS', '<I, 'EQUAL', or '=', then the 'NOT' participates as
part of the relational operator: otherwise

The 'NOT' is interpreted as a logical
operator
and,
therefore, the implied insertion of subject or relational
operator results in a negated relation condition.

Some examples of abbreviated combined and negated
conditions and expanded equivalents follow.
Abbreviated Combined
Relation Condition

combined

relation

Expanded Equivalent

a > b AND NOT < c OR d

«a > b) AND (a NOT < c) ) OR (a
NOT < d)

a NOT EQUAL b OR c

(a NOT EQUAL b) OR (a NOT EQUAL
c)

NOT a

= b OR c

(NOT (a = b) ) OR (a
5-16

THE PROCEDURE DIVISION
NOT (a GREATER b OR < c)

NOT ((a GREATER b) OR (a < c»

NOT (a NOT > bAND c AND NOT d)

NOT ((((a NOT> b) AND (a NOT>
c»
AND (NOT (a NOT> d»»

5.6

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
SIZE ERROR option. These two options are described here to avoid the
necessity of including their descriptions with each of the arithmetic
verbs.

5.6.1

The ROUNDED Option

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:

567A8756
999V99
567A87
567A88

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:
resultant-identifier picture:
stored result without
ROUNDED option:
stored result with
ROUNDED option:

5.6.2

value:
99PP

5388

53
54

The SIZE ERROR Option

If, after decimal point alignment, the number of signitlcant 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 SIZE ERROR option is specified.
If the SIZE ERROR is not specified and a size error condition
the value of the resultant-identifier is unpredictable,
additional action is taken.

occurs,
and no

If SIZE ERROR is specified, and a size error condition occurs, then
the values of the resultant-identifier(s) affected by the size errors
5-17

THE PROCEDURE DIVISION
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 SIZE ERROR is
executed.
Example ADD A TO B ON SIZE ERROR GO TO OVERFLW
A:
954
PICTURE IS 999; VALUE 954.
B:
The contents of B are left unchanged and
Result:
control is transferred to the paragraph
or section named OVERFLW

5.7

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, del)
and
d(2)
represent
identifiers that refer to group items. A pair of data items, one from
del) and one from d(2), correspond if the following conditions exist:
1.

A data item in del) and a data item in d(2)
have the same
data-name
and
the same qualification up to, but not
including, del) and d(2).

Both of the data items are elementary numeric data
the
case
of
an ADD or SUBTRACT statement
CORRESPONDING option.

Neither del) nor d(2) may be data items with level-number 66,
77, or 88.

Each data item subordinate to del) or d(2)
that contains a
RENAMES,
a REDEFINES or an OCCURS clause is ignored.
However, del) and d(2) may have REDEFINES or OCCURS clauses
or be subordinate to data items with REDEFINES or OCCURS
clauses.

items in
with the

See the sections ADD, MOVE, and SUBTRACT 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, and 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.
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
5-18

THE PROCEDURE DIVISION
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.
If any nonnumeric 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

need no conversion.

A through I

are converted to 1 through 9.

?, [, {

are converted to O.

J through R

are converted to 1 through 9, and the field
is made negative if they are found in the
high-order or 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 high-order or
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, stopping 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 will be ignored.

5.9

the

trailing

the

following

PROCEDURE DIVISION VERB FORMATS

The format of each Procedure Division verb is given on
pages. The verbs are presented in alphabetical order.

The word lIidentifierll is a data-name followed, as required, by
qualification, subscripts, and/or indexes necessary to make
data-name unique.

5-19

any
the

THE PROCEDURE DIVISION

5.9.1 ACCEPT
Function
Formats 1 and 2 of the ACCEPT statement cause low-volume
read from the user's terminal.

data

Format 3 of the ACCEPT statement, the ACCEPT COUNT 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.
This is valid
only for users of TOPS-IO.
General Format

Format 1:
ACCEPT identifier-1
Format 2:
ACCEPT identifier FROM

identifier-2

[FROM mneumonic-name]

{ ~}
TIME

Format 3:
ACCEPT cd-name MESSAGE COUNT
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 will read from left to right into each
identifier a maximum of 1023 characters that have been typed
in. Two characteristics determine how the characters are
read into the identifier.
These characteristics are the size
of the data item and the number of characters that are
typed
in.
If the data item contains fewer than 1023 characters,
two situations can occur:
a.

option is specified,
the mnemonic-name must
the CONSOLE IS clause of the SPECIAL-NAMES

If the user types in fewer characters than are allowed by
the data item, the characters are left justified and the
remaining area is filled with spaces.
5-20

January 1980

THE PROCEDURE DIVISION

ACCEPT (Cont.)
b.

If the user types in more characters than are allowed by
the data item, the characters are left justified and
truncated.

Likewise, if the data item contains
characters, two situations can occur:

than

1023

If the user types in 'fewer than 1023 characters, the
characters are left justified and the remaining area is
filled with spaces.

If the user types in more than 1023 characters, only the
first
1023 characters are left justified, and the
remaining area specified by the data item is filled with
spaces.

When the ACCEPT MESSAGE COUNT statement is executed, the
contents
of
the
area specified by the communication
description entry must contain the name of the symbolic queue
to be tested. Testing the condition updates 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
communication description entry.

5-20.1

January 1980

THE PROCEDURE DIVISION

ADD

5.9.2

Function
The ADD statement computes the sum of two or more numeric operands and
stores the result.
General Format
i dent i fi er-2]
[ 1i teral-2

-ADD t}identifier-l
1i tera 1-1

[i dentifi er-n [ROUNDE:g]

.••

TO i denti fi er-m [ROUNDEoJ

[ON SI ZE ERROR imperati ve-statemen9

ADD }identifier-lt
tliteral-l

[identifier-3]
f {identifier-2}
literal-2
literal .. 3

GI VING i dentifi er-m [ROUNDEIj]

~ denti fi er-n [}OUNDED,]

[ON SIZE ERROR imperative-statement]

-ADD- t} CORRESPONDING
CORR
ft identifier-l TO identifier-2 rROUNDEDJ
L.:
[ON SI ZE ERROR i mperati ve-s tatementJ

Technical Notes
1.

Each ADD statement must contain at least two operands (that
is, an addend and an augend).
In formats 1 and 2, each
identifier must refer to an elementary numeric item, except
that identifiers appe~ring to the right of the word GIVING
may refer to numeric-edited items.
In format 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 operands (that is, the data item
resulting from the superimposition of all operands aligned by
decimal point) must not contain more than 19 decimal digits
for the standa~d compiler and not more than 36 digits for the
BIS-compiler. In either case, a maximum Qf 18 digits can be
stored in the receiving field.
(See Section 1.1 for a
definition of the BIS-compiler.)

5-21

THE PROCEDURE DIVISION

ADD (Cont.)
3.

Format 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.

Format 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.

Format 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
descr ibed in Section ,5. 7, The CORRESPONDING Option.

The ROUNDED and SIZE ERROR options are described in Section
5.6, .Common ,Options Associated with Arithmetic Verbs.

;

5-22

THE PROCEDURE DIVISION

ALTER
5.9.3

ALTER

Function
The ALTER statement
statements.

changes

the

object

one

General Format

ALTER procedure-name-l TO

~ROCEED TO]

procedure-name-2

~procedure-name-3 TO ~ROCEED TO~ procedure-name-4 ~
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 nothing but 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 Divisioq.

A GO TO statement in a section whose priority is greater than
)r equal to 50 must not be refer~ed 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 may not reference a procedure name
within the DECLARATIVESi
conversely, an ALTER statement
within the DECLARATIVES may 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 will be lost when segments
are overlaid.

5-23

THE PROCEDURE DIVISION

CALL
5.9.4

CALL

Function
The CALL statement is used to transfer control to a subprogram.
General Format

CALL

identifier-l
program-name
entry-name

l r-USING data-name-l
JL:-

[data-name-2]

~ON OVERFLOW imperative-statement~

Technical Notes
1.

Program-name is a one to six character name
(PROGRAM-ID)
of
the subprogram to be called.
Entry-name is a one to six
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 will be
beginning 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 may 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 may be referenced (or whose
subordinate parts may 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. Corresponding identifiers refer to a
single set of data that is available to both the calling and
called programs.

5-24

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 TOs, 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 or overlaid. If the subprogram has been cancelled
or overlaid, its state is that of a fresh copy.

The CALL identifier clause
conditions are met:

works

only

when

the

following

There is only one subprogram per overlay.

Each subprogram has only one entry point.

The overlay name is the same as the subprogram name.

Refer to the COBOL-74 Usage Material, Part 3 of this
for more information on subprograms.

5-25

manual,

THE PROCEDURE DIVISION

CANCEL
5.9.5

CANCEL

Function
The CANCEL statement releases
programs named in the clause.

the

memory

areas

occupied

the

General Format
CANCEL {identifier-I}
subprogram-l

i denti fi er-2]
[ subprogram-2

Technical Notes
1.

The CANCEL statement can be used either to reload a segment
of a segmented COBOL program or to cancel a subprogram that
has been loaded into an overlay link by LINK.
(Refer to the
COBOL-74
Usage
Material, Part 3 of this manual, for
information on specifying LINK overlays and on subprograms.)
Note 2 describes the first case while the remaining notes
describe the second.

When you cancel a segment of a program you cause the
object-time system to read your .EXE file and copy an
initialized version of the segment into memory.

After a subprogram has been cancelled, a subsequent call to
the subprogram will cause a freshly initialized copy to be
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 will be 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
will result 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 reach an undefined location.

5-26

which

THE PROCEDURE DIVISION

CLOSE
5.9.6

Function
The CLOSE statement terminates the
files, reels, or units.

processing

input

and

output

General Format

CLOSE fil e-name-l

o~~~~ B{WITH rO~}}
LOCK
DELETE

FOR

fil e-name-2

G~m~ { WITH
FOR

CLOSE file-Mme-l

REMOVAL

LOCKREWIND}}
DELETE
REMOVAL

~ITH LOCK] ~i1e-name-2

[WITH LOCK1]

Technical Notes
1.

Each filename must appear as the subject of an
the File Section of the Data Division.

The DELETE option applies only to disk and DECtape files.
If
this option is included, the file will be deleted from the
device.

The REEL, UNIT, and NO REWIND options apply only to
tape files; UNIT is synonymous with REEL.

The FOR REMOVAL option unloads magnetic tape.
The file
cannot be re-open~d without intervention by the operator.

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:
a. NON-REEL

entry

magnetic

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.
5-27

THE PROCEDURE DIVISION

CLOSE (Cont.)
b. SINGLE REEL

A file that is entirely contained on one reel
or unit.

c. MULTI-REEL

A file that may 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-4. The definitions for
the symbols used in this table are given below.
Where the
definition 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.
Codes Used in Table 5-4
A

Any subsequent reels of this file will not be processed.

The current reel is not rewound.

Standard CLOSE File Procedure is followed:
INPUT and 1-0 Files
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
created and written on the output medium.

label

The current reel is rewound and unloaded.

Any attempt to subsequently OPEN this file will result
in an error message being typed and the run terminated.

Standard CLOSE REEL Procedure is followed:
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
curr"ent device.

The standard beginning reel
performed for the new reel.

label

procedure

OUTPUT and I-O Files
1.

The standard
performed.

ending

5-28

reel

label

THE PROCEDURE DIVISION

CLOSE (Cont.)
2.

If the file is assigned to more than one device, the
devices are swapped.
A halt occurs to allow the
operator to mount an available reel.

The standard
performed.

beginning

reel

label

procedure

The tape is rewound.

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 will remain
intact
(that
is, the originaL file will not be
superseded nor deleted).

Illegal. This is an illegal
option and a file type.

combination

If a file is OPENed but not CLOSEd before the STOP RUN
statement is executed, the file will be automatically CLOSEd.
Any records still retained by a RETAIN statement will
automatically be freed by a CLOSE statement.

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.

5-29

THE PROCEDURE DIVISION

CLOSE (Cont.)

Table 5-4
CLOSE Options and File Types
File Type

CLOSE
Options

NON-REEL

SINGLE
REEL/UNIT

MULTI-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

CLOSE REEL

F,G

CLOSE REEL
WITH LOCK

F,D

F,D,G

CLOSE REEL
WITH NO
REWIND

F,B

CLOSE WITH
DELETE

C,H

CLOSE REEL
FOR REMOVAL

5-30

THE PROCEDURE DIVISION

COMPUTE
5.9.7

COMPUTE

Function
The COMPUTE statement assigns to a data item the value of a
data item, literal, or arithmetic expression.

numeric

General Format

COMPUTE identifier-l [ROUNDED]

n{LJ ~1;~~!f; ~r-2

. } [JOUNDED]l
arlthmetlc-expresslon
~

IS EQUAL TO l
Ij :QUALS
f arithmetic-expression [ON SIZE ERROR imperative-statement]

Technical Notes
1.

The COMPUTE statement allows you to combine arithmetic
operations without the restrictions on the composite of
operands and/or recelvlng data items imposed· by
the
arithmetic statements ADD, SUBTRACT, MULTIPLY, and DIVIDE.
If the composite operand exceeds 19 decimal digits,
the
composite is converted to COMP-l format.
This will lead,
however, to a loss of precision.

Identifier-l
must
numeric-edited item.

Identifier-2 must be an elementary numeric item.
must be a numeric literal.

elementary

numeric

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 in Section 5.4, Arithmetic
Expressions.

The ROUNDED and SIZE ERROR options are described in Section
5.6, Common Options Associated with the Arithmetic Verbs.

5-31

THE PROCEDURE DIVISION

DELETE
5.9.8

DELETE

Function
The DELETE statement removes a specified record frow
organization is RELATIVE or INDEXED.

file

whose

Record-name must be a record associated with a
organization is RELATIVE or INDEXED.

file

whose

When the DELETE statement is executed, the object-time
system removes from the file the record which has a key
equal in value to the RELATIVE KEY (for relative files)
or
the RECORD KEY (for indexed files).
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, the file
must be open for OUTPUT or INPUT-OUTPUT.

The INVALID KEY clause must not be specified for a DELETE
statement
that
references
a
file
that
is
in
sequential-access mode.
It must be specified for a DELETE
statement
that
references
a
file that is not in
sequential-access mode, and for which no USE procedure is
specified.

For files in the sequential-access
mode,
the
last
input-output statement executed for file-name prior to the
execution of the DELETE statement must have been
a
successfully executed READ statement. The OTS logically
removes from the file the record that was accessed by that
READ statement.

The execution of a DELETE statement does not affect the
current reco'rd pointer or the contents of the record area
associated with file-name. The execution of the DELETE
statement causes updating of the value of any specified
FILE STATUS data item associated with file-name.

General Format

DELETE file-name RECORD

[:INVALID KEY imperative-statement]

Technical Notes

5-32

THE PROCEDURE DIVISION

DELETE
5.9.8

DELETE

Function
The DELETE statement removes a specified record from
organization is RELATIVE or INDEXED.

file

whose

Record-name must be a record associated with a
organization is RELATIVE or INDEXED.

file

whose

Alternate keys cannot be used with this verb.

When the DELETE statement is executed, the object-time
system removes from the file the record which has a key
equal in value to the RELATIVE KEY (for relative files) or
the RECORD KEY (for indexed files). 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, the file
must be open for OUTPUT or INPUT-OUTPUT.

The INVALID KEY clause must not be specified for a DELETE
statement
that
references
a
file
that
is
in
sequential-access mode. It must be specified for a DELETE
statement
that
references
a
file that is not in
sequential-access mode, and for which no USE procedure is
specified.

The execution of a DELETE statement does not affect the
current record pointer or the contents of the record area
associated with file-name. The execution of the DELETE
statement causes updating of the value of any specified
FILE STATUS data item associated with file-name.

General Format

DELETE file-name RECORD

[INVALID KEY imperative-statement]
MR-S-1322-81

Technical Notes

5-33

THE PROCEDURE DIVISION

DISPLAY
5.9.9

DISPLAY

Function
The DISPLAY statement causes low-volume data to be written
terminal.

your

General Format

literal 1 } [ {identifier-2}]
DISPLAY {identifier-l
literal-2
...
[UPON mnemonic-name] [WITH NO ADVANCING]
MR-S-1050-81

Technical Notes

The contents of each operand are written on
in the order listed.

Each of the literals can be numeric, nonnumeric, 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 figurative
constants SPACE, SPACES, or ALL SPACES, or a literal
defined as spaces will not DISPLAY as they are considered
as trailing spaces on the line and the optimized OTS does
not print trailing spaces.

The mnemonic-name must appear in the CONSOLE clause in
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 you do not specify the WITH
NO ADVANCING clause, the terminal advances to the next line
after printing the text of the DISPLAY statement.

5-34

your

terminal

the

October 1985

THE PROCEDURE DIVISION

DIVIDE (Cont.)
2.

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 may be an elementary numeric or
numeric-edited item. Each literal-lor literal-2 must be a
numeric literal.
Identifier-4 may be an elementary numeric
or numeric-edited item.

The ROUNDED and SIZE ERROR options are described in Section
5.6, 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 (that is,
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 e~ther case, a maximum of 18
digits can be stored in the receiving field.
(See Section
1.1 for a definition of the BIS-compiler.)

The remainder is checked for a size error after th~ quotient
is checked, whether or not the quotient has a size error. If
either the quotient or the remainder has a size error, the
object-time system follows the procedure described in Section
5.6, Common Options Associated with Arithmetic Verbs.

The ROUNDED option does not apply
remainder is always truncated.

5-35

resulting

the

remainder

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 (
l COBOL ~

~SING l

~ identifier-l
literal-l
(
procedure-name-l ,

identifier-2
1 i tera 1-2
procedure-name-2 )

Technical Notes
1.

MACRO refers to MACRO-IO or MACRO-20 assembly language
FORTRAN to the TOPS-IO or the TOPS-20 FORTRAN language.

The program-name can be enclosed in quotation marks.

The ENTER statement generates a subroutine call and specifies
the address where the items associated with the USING clause
are located.
(Refer to the COBOL-74 Usage Material, Part 3
of this manual, for more information on the ENTER statement.)

ENTER COBOL is equivalent to CALL.

5-36

and

THE PROCEDURE DIVISION

ENTRY
5.9.12

ENTRY

Function
The ENTRY statement establishes an entry point in a

subprogr~m.

General Format
ENTRY entry-name [USING i denti fi er-1

[} dentHi er-:[]

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 one to six 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
ENTRY
operands in any CALL statement referencing that
statement.

The identifiers in the USING clause indicate those data items
in the called program that may 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 runtime, ENTRY statements are
specific calls to them.

Refer to the COBOL-74 Usage Material, Part 3 of this
for more information on subprograms.

5-37

ignored

unless

there

are

manual,

THE PROCEDURE DIVISION

EXIT
5.9.13

EXIT

Function
The EXIT statement provides a common end point
routines executed by a PERFORM or USE statement.

for

series

General Format

paragraph-name. EXIT.

Technical Notes
1.

EXIT must be the only sentence in the paragraph.

The EXIT statement may be used at the end of a section in the
Declaratives, or to provide an end point for a series of
paragraphs that are performed. When you use EXIT at the end
of the range of a PERFORM or USE, you can provide a variety
of exits from the performed procedure 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.

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-38

THE P~OCEDURE DIVISION

EXIT PROGRAM

5.9.14

EXIT PROGRAM

Function
The EXIT PROGRAM statement is used to return control from a subprogram
to its calling program.

General Format

Technical Notes

EXIT PROGRAM can only appear in a subprogram.

When an EXI~ PROGRAM statement is executed, control is
returned to the calling program at the statement immediately
following the CALL statement.

If an EXIT PROGRAM et~tement is encountered in a subprogram
that is operating as a main program, it is ignored.

Refer to the COBOL-74 Usage Material, Part 3 of this
for more information on subprograms.

5-39

manual,

THE PROCEDURE DIVISION

FREE
5.9.15

FREE

Function
The FREE statement explicitly frees records that have been retained in
a RETAIN statement.
General Format

RECORD [ KEY
fi le-name-l {

identifier-l
1itera1-1

EVERY RECORD

FREE
RECORD [_KEY
[

file-name-2 {

identifier-2
1i tera 1-2

EVERY RECORD

}J}]

EVERY RECORD

[NOT RETAINED statement-l

[statement-2]

]

.:..

Technical Notes
1.

Fi1ename-l, 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-l, 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,
Section 5.9.29, for a description of its function and syntax.

5-40

are any valid COBOL statements.

THE PROCEDURE DIVISION

FREE (Cont.)
5.

The EVERY RECORD phrase is used to free all records
or to free all records retained in a specific file.

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,
relative,
indexed-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 organization of the file. Each
organization is described separately below.
a.

retained

and

Sequential Files
If the KEY phrase is specified, the value of the key
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 Files
If the KEY phrase is specified, the value of the key
refers to the record with that value in the RETAIN
statement. For example, 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.

5-41

THE PROCEDURE DIVISION

FREE (Cont.)
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.
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 IIABC II in the FREE
statement frees the record identified as IIABC II 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 RECORD KEY of the file.
If
the RECORD 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 File
RETAIN PART KEY 0 FOR ANY VERa.
READ PART, INVALID KEY GO TO ERR.
WRITE l>ARTREC.
FREE PARK KEY O.
Indexed-Sequential File
MOVE IIBII TO RECORD-KEY.
RETAIN LETTERS FOR READ.
FREE LETTERS.

5-42

THE PROCE~URE DIVISION

GENERATE
5.9.16

GENERATE

Function
The GENERATE statement causes the Report-Writer to execute all
automatic report operations, and, if required, to produce one or more
report groups.
General Format
GENERATE

data -name }
{ report-name

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
does not produce an output detail report group.
This is
called summary reporting.

A GENERATE
operations:

statement

performs

the

following

automatic

It steps and tests the LINE-COUNTER and/or PAGE-COUNTER
to produce,
if necessary, any PAGE FOOTING and PAGE
HEADING report groups.

It recognizes any specified control breaks to produce
appropriate CONTROL FOOTING and CONTROL HEADING report
groups, and resets appropriate summation counters.

It accumulates into the summation counters all
identifiers.

It executes any routines defined by a USE statement.

In detailed reporting, it produces
group.

the

specified

detailed

report

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, in detailed reporting

5-43

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.

A GENERATE statement for a particular report may 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 may not be
executed until an intervening INITIATE statement is executed
for the report.

5-44

THE PROCEDURE DIVISION

GO TO

5.9.17

GO TO

Function
The GO TO statement causes control to be transferred from one part
the Procedure Division to another.

General Format

[procedure-name-l]

GO TO procedure- name-l

[ procedure -name- 2]

procedure-name-n

DEPENDING ON identifier

Technical Notes
1.

Each procedure-name is the name of a paragraph or section
the Procedure Division of the program.

Format 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, format 1 must appear as
sentence in a paragrapho

the

first

If procedure-name-l is not specified, the GO TO must be
alterable and an associated ALTER statement must pe ex~cuted
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.
3.

Format 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 may 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-45

THE PROCEDURE DIVISION

GOBACK

5.9.18

GOBACK

Function
The GOBACK statement is used in a subprogram to return control to
calling program.

the

General Format

GOBACK.

Technical Notes
1.

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 the COBOL-74 Usage Material, Part 3 of this
for more information on subprograms.

5-46

manual,

THE PROCEDURE DIVISION

5.9.19

Function
The IF statement causes a conditional expression to be evaluated and
subsequent operations to be determined as a result of this evaluation.
General Format

statement-l }
!£ condition {NEXT
SENTENCE

[ELSE

s tatement-2 }]
{NEXT SENTENCE

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 may
include any statement or sequence of statements, including
other IF statements.
IF statements included within other IF
statements are hested.
Nested IF statements are paired IF
and ELSE combinations and may 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-47

THE PROCEDURE DIVISION

IF (Coot.)

Example:

(c=condition;s=statement)

.-l1

IF (-I IF l'-~ s-~ LLSr: IF (-3 s-3 FLsr s4 LLSE s-5.

MR·S'()27-79

5-48

THE PROCEDURE DIVISION

INITIATE
5.9.20

INITIATE

Function
The INITIATE statement is used to initialize
report is produced.

all

counters

before

General Format

INITIATE report-name-l

[re po rt - 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 I during the execution of an
INITIATE statement.
If a different starting value for the
PAGE-COUNTER is desired, it may 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 may
not
be executed until a TERMINATE statement for that
report-name is executed.

5-49

entries

that

THE PROCEDURE DIVISION

INSPECT
5.9.21

INSPECT

Function
The INSPECT statement counts, replaces, or counts and replaces the
number of occurrences of a given character or groups of characters in
a data item.
General Format
INSPECT identifier-! TALLYING

INSPECT identifier-! REPLACING
CHARACTERS BY {i~entifier-6} fjBEFORE}
llteral-4
L'AFTER

---~'--'-'-.;.;.. -

INITIAL

{i~entifier-7}J
llteral-5

BY {i~entifier-6} rJBEFORE} INITIAL {identifier-7}]1
{! ~~~DING}!{i~entifier-5}
FIRST
llteral-3
-- llteral-4
literal-5
"""
O~

Il
"""Jf

INSPECT identifier-! TALLYING

identifier-4}J} ...
{literal-2

. ..

REPLACING

CHARACTERS BY
.;....--- -

l!{

{i~entifier-6}
llteral-4

~~~DING}
~{i~entifier-5}
~ ( llteral-3

[{~g~~E}
BY
--

INITIAL

{~1~~;!f~,~r-7}]

{identifier-6} [{BEFORE}
literal-4
AFTER

INITIAL

{i~entifier-7}]l
llteral-5
j ...

J
...

Technical Notes
The Lollowing rules apply to Formats 1, 2 and 3:
1.

Each literal must be nonnumeric and
constant except ALL.

The usage of all identifiers must be DISPLAY, implicitly or
explicitly.
Identifier-l must reference either a group item
or any category of
elementary
item.
Identifier-3 .••
identifier-n must reference either an elementary, alphabetic,
alphanumeric or numeric item.

5-50

may

any

figurative

THE PROCEDURE DIVISION

INSPECT (Cont.)
2.

The usage of all identifiers must be DISPLAY, implicitly or
explicitly.
Identifier-l must reference either a group
item or any category of elementary item.
Identifier-3 •••
identifier-n
must
reference
either
an
elementary,
alphabetic, alphanumeric or numeric item.

If there is more than one TALLYING and/or REPLACING to be
made in the same INSPECT statement, it is not the same as
two or more separate INSPECT statements, each with only one
of the comparisons.
In this case, the following rules
apply:
a.

The identifiers and literals for TALLYING
and/or
REPLACING are accepted in the order they are specified
in the INSPECT statement from left to right. The first
literal-I, literal-3 is compared to an equal number of
contiguous characters, starting with the
leftmost
character
position
in
identifier-I.
Literal-I,
literal-3, and that portion of the
contents
of
identifier-l match if they are equal, character for
character.

If no match occurs in the comparison of the first
literal-I, literal-3, the comparison is repeated with
each successive literal-I, literal-3, until a match is
found.
When a successive literal-I, literal-3 do not
exist,
the
character
position
in
identifier-l
immediately to the right of the leftmost character
position is considered the leftmost character position,
and
the
comparison begins again with the first
literal-I, literal-3.

When a match occurs, TALLYING and/or REPLACING takes
place as described in notes 6 and 11 below. The
character position in identifier-l immediately to the
right of the of the rightmost character position that
matched is now the leftmost character position of
identifier-l and the comparison begins again with the
first literal-I, literal-3.

The comparison continues until the rightmost character
position of identifier-l has matched or has already
been considered as the leftmost character position.
When this occurs, the INSPECT statement is terminated.

If CHARACTERS is specified, an implied one character
participates in the cycle as described in notes 3a and
3b above, except no comparison to the contents of
identifier-l
takes place.
This one character is
considered to match the leftmost character of the
contents of identifier-l occurring in the current
comparison.

The following rules apply to Format 1:
4.

Identifier-2 must reference an elementary numeric data
name.
It should be defined as a I-word COMP field with a
PICTURE of 9(10) to avoid any possible truncation warning
messages. If either literal-l or literal-2 is a figurative
constant, the figurative constant refers to an implicit
one-character data item.
5-51

October 1985

THE PROCEDURE DIVISION

INSPECT (Cont.)
S.

The contents of the data item referenced by identifier-2 is
not initialized by the execution of the INSPECT statement.

The rules for tallying are as follows:
a.

If the ALL phrase is specified, the contents of the data
item referenced by identifier-2 is incremented by one (1)
for each occurrence of literal-l matched within the
contents of the data item referenced by identifier-I.

If the LEADING phrase is specified, the contents of the
data item referenced by identifier-2 is incremented by
one (1) for each contiguous occurrence of literal-l
matched within the contents of the data item referenced
by identifier-I, provided that
the
leftmost
such
occurrence is at the point where comparison began in the
first comparison cycle in which literal-l was eligible to
participate.

If the CHARACTERS phrase is specified, the contents of
the data item referenced by identifier-2 is incremented
by one (1) for each character matched, within the
contents of the data item referenced by identifier-I.

The following rules apply to Format 2:
7.

The size of the data referenced by literal-4 or identifier-6
must be equal to the si~e of the data referenced by literal-3
or identifier-S. When a figurative constant is used as
literal-4, the size of the figurative constant is equal to
the size of literal-3 or the size of the data item referenced
by identifier-S.

When the CHARACTERS phrase is used, literal-4, literal-S, or
the size of the data item referenced by identifier-6 or
identifier-7 must be one character in length.

When a figurative constant is used as literal-3, the data
referenced by literal-4 or identifier-6 must be one character
in length.

10.

The required words ALL, LEADING and FIRST are adjectives that
apply to each succeeding BY phrase until the next adjective
appears.

11.

The following rules for replacement are as follows:
a.

When the CHARACTERS phrase is specified, each character
matched in the contents of the data item referenced by
identifier-l is replaced by literal-4.

When the adjective ALL is specified, each occurrence of
literal-3 matched in the contents of the data item
referenced by identifier-l is replaced by literal-4.

S-S2

THE PROCEDURE DIVISION

INSPECT (Cont.)
c.

When the adjective
LEADING
is
specified,
each
contiguous occurrence of literal-3 matched in the
contents of the data item referenced by identifier-l is
replaced by literal-4, provided that the leftmost
occurrence is at the point where comparison began in
the first comparison cycle in which literal-3 was
eligible to participate.

When the adjective FIRST is specified, the leftmost
occurrence of literal-3 matched within the contents of
the data item referenced by identifier-l is replaced by
literal-4.

The following rules apply to Format 3:
12.

Identifier-2 must reference an elementary numeric data
item.
It should be defined as a I-word COMP field with a
PICTURE of 9(10) to avoid any possible truncation warning
messages.

13.

If either literal-lor literal-2 is a figurative constant,
the figurative constant refers to an implicit one-character
data item.

14.

The size of the data
referenced
by
literal-4
or
identifier-6 must be equal to the Slze of the data
referenced by literal-3 or identifier-5. When a figurative
constant "is used as literal-4, the size of the figurative
constant is equal to the size of literal-3 or the size of
the data item referenced by identifier-5.

15.

When the CHARACTERS phrase is used, literal-4, literal-5,
or the size of the data item referenced by identifier-6 or
identifier-7 must be one character in length.

16.

When a figurative constant is used as literal-3, the data
referenced
by literal-4 or identifier-6 must be one
character in length.

17.

A Format 3 INSPECT statement is interpreted and executed as
though two successive INSPECT statements specifying the
same identifier-l had been written with one statement being
a Format 1 statement with TALLYING phrases identical to
those specified in the Format 3 statement, and the other
statement being a Format 2 statement with REPLACING phrases
identical to those specified in the Format 3 statement.
The general rules given for matching and counting apply to
the Format 1 statement and the general rules given for
matching and replacing apply to the Format 2 statement.

5-53

October 1985

THE PROCEDURE DIVISION

INSPECT (Cont.)
Examples
The field TXT-FLD contains "PSYCHOANALYSIS".
INSPECT TXT-FLD
INITIAL "A".

TALLYING

CQUNTER-l

FOR

CHARACTERS

BEFORE

COUNTER-l contains 6
INSPECT TXT-FLD REPLACING "A" BY "X" BEFORE INITIAL "N".
TXT-FLD ends with "PSYCHOXNALYSIS"
INSPECT TXT-FLD TALLYING COUNTER-l FOR
INITIAL "S", REPLACING ALL "S" BY HZ".
TXT-FLD ends with "PZYCHOANALYZIZ"
COUNTER-l contains 12

5-54

CHARACTERS

AFTER

THE PROCEDURE DIVISION

MERGE (Cont.)
5.

MERGE statements may 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.

ALTER, GO, and PERFORM statements in the OUTPUT PROCEDURE may
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 glven 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
will be executed as appropriate.
The GIVING option is
equivalent to the following OUTPUT PROCEDURE:
L4. OPEN OUTPUT file-name-5.
L5. RETURN sort-file INTO record-name-5;
WRITE record-name-5.
GO TO L5.
L6. CLOSE file-name-5.

AT END GO TO L6.

Refer to the SORT/MERGE User's Guide for more information
MERGE.

5-55

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

MOVE

{identifier-I}

r~OVE

{CORRESPON Dr NG}
CaRR

literal

TO i denti fi er-2

[

identifier-3]

i dent; fi er-l TO i denti fi er-2

Technical Notes
1.

CORR may be interchanged with CORRESPONDING.

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 format 1, the data contained in identifier-lor literal-l
is moved first to identifier-2, then to identifier-3, etc.
In format 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 in Section 5.7, The CORRESPONDING Option.

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.

A numeric item whose implicit decimal point is not
immediately to the ~ight of the least significant digit
must
not
be
moved
to
an
alphanumeric
or
alphanumeric-edited item.

All other moves are legal.

5-56

THE PROCEDURE DIVISION

MOVE (Cont.)
5.

The following rules apply to all legal moves.
a.

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 Q
JUSTIFIED RIGHT clause; spaces are placed in the
remalnlng leftmost characters of the receiving field
if the receiving field is described by a JUSTIFIED
RIGHT clause.

If the sizes of the sending and recelvlng 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, neither the
sending or receiving items are 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-57

THE PROCEDURE DIVISION

MULTIPLY

5.9.24

MULTIPLY

Function
The MULTIPLY statement causes numeric data items to be multiplied
sets the values of data items equal to the results.

and

General Format

MULTIPLY

)i~entifier-I} --BY identifier-2 [ROUNDED]

tllteral-I

[identi fier-3 [ROUNDED]]

MULTIPLY

{identifier-I} BY
literal-I
--

[ON SIZE ERROR imperative-statement]

)identif-ier-2}
t1iter.al-2

[identifier-4 [ROUNDED]] ...

GIVING identifier-3 [ROUNDED]

[ON SIZE ERROR imperative-statement]

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 in
format 2 may refer to either a numeric or a numeric-edited
item.
Each literal must be a numeric
literal;
the
figurative constant ZERO is permitted.

Format 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. The same process
happens again, with identifier-3 replacing identifier-2, then
identifier-4 replacing identifier-3, until all multipliers
have been used.

Format 2 causes the value of identifier-lor literal-l to be
multiplied by the value of identifier-2 or literal-2. The
resultant product is stored in identifier-3, identifier-4,
and so on.

The ROUNDED and SIZE ERROR options are described in Section
5.6, Commor! Options Associated with Arithmetic Verbs.

Despite the possiblity of sequential multiplication taking
place, there can never be more than two operands in use at
one time. The total number of digits in both opera~ds must
not be more than 18 decimal digits for the st~ndard 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.
(See Section 1.1
for
a
definition
of
the
BIS-compiler.)

5-58

THE PROCEDURE DIVISION

OPEN
5.9.25

OPEN

Function
The OPEN statement initiates the 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

.
[ REVERSED
flle-name-l
WITH NO REWIND

[.
flle-name-2

(READ
) REWRITE

{ ~UT -OUTPUT} fi 1 e-name-3

FOR
[

l[ }

READ
REWRITE

't WRITE
') AND t WRITE
DELETE
DELETE
ANYVI RB

[

[ REVERSED
WITH NO REWIND

~~~~ITE

ALLOWING OTHERS I WRITE
llANO
DELETE
ANY VE RB

)( READ
REWRITE (
WRITE
)
DELETE
(
ANYVERB

[filename-6 ]

[ UNAVAILABLE statement-l

[

READ
NONE
REWRITE
WRITE
DELETE
I ANVVfRB

...

statement-2 ]

...

~~C~ITE J]

]
WRITE
DELETE
ANYVERB

•••

(READ
)[
) REWRITE (
.EQR
WRITE
) AND
DELETE
[
ii.NYVfRB

[ ALLOWING OTHERS

[EXTEND Jfilename-5

.ii.NYVERB

OPEN

[ file-name-4

J..:..

5-59

...

READ
AND INONE
REWRITE
WRITE
DELETE
ANYVfRB

I] 1
•••

THE PROCEDURE DIVISION

OPEN (Cont.)
Technical Notes
1.

The OPEN statement must be executed for a file prior to the
execution of any I/O verbs, such as READ, WRITE, DELETE,
REWRITE, SEEK, or CLOSE.

A second OPEN statement for a file cannot be executed
to the execution of a CLOSE statement for that file.

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.

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 the tape.

If a file has been described with LABEL RECORDS ARE STANDARD,
standard label checking or label writing is performed.
If a
file has been described as LABEL RECORDS ARE OMITTED, no
label checking or writinq is performed.

If an INPUT file is described as
OPTIONAL
(in
the
FILE-CONTROL paragraph), the object-time system will type the
message

prior

IS file-name PRESENT?
and wait for the operator to type YES or NO.
If he types NO,
the
first
READ
statement
for this file causes the
imperative-statement at the AT END or INVALID KEY clause to
be executed.
8.

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 to be executed.
If the file does not exist when
it is opened for INPUT-OUTPUT, an empty file is created.

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).

5-60

THE PROCEDURE DIVISION

OPEN (Cont.)
Technical Notes
1.

The OPEN statement must be executed for a file prior to the
execution of any I/O verbs, such as READ, WRITE, DELETE,
REWRITE, or CLOSE.

The compiler calculates a blocking factor for any unblocked
file that is opened for I/O. Therefore, files opened for I/O
should have explicit blocking factors.
When an OPEN 1-0 statement is executed, the file
indicator is set to the first record in the file.

position

When an OPEN 1-0 statement specifies a nonexisting file,
the
file is created. However, ISAM files must exist for an OPEN
1-0 statement.
3.

When your program executes an OPEN verb, the record area
that file is cleared.

for

A second OPEN statement for a file cannot be executed
to the execution of a CLOSE statement for that file.

prior

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.

If a file has been described with LABEL RECORDS ARE STANDARD,
standard label checking or label writing is performed.
If a
file has been des6ribed as LABEL RECORDS ARE OMITTED, no
label checking or writing is performed.

l~.

If an INPUT file is described as
OPTIONAL
(in
the
FILE-CONTROL paragraph),
the object-time system types the
message
IS file-name PRESENT?
and wait for the operator to type YES or NO.
If he types NO,
the
first
READ
statement
for this file causes the
imperative-statement at the AT END or INVALID KEY clause to
be executed.
5-61
October 1985

THE PROCEDURE DIVISION

OPEN (Cont.)

11.

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 to be executed. The file must exist when it is
opened for INPUT-OUTPUT.

12.

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).

13.

RMS indexed files cannot be opened for simultaneous updates.
Therefore, the ALLOWING OTHERS clause cannot be used.

14.

If you open a file for simultaneous update,
all subsequent
users of the file must also open it for simultaneous update
or for input only.
If the file
is 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
you open the file 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
you close it.

15.

After the keyword FOR, you must give one or more verbs that
you intend t6 execute while you have your file open.
You can
only execute those verbs that you have specified.
Following
the keywords ALLOWING OTHERS, you must give one or more verbs
that you are allowing 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.

16.

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.

17.

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-62

THE PROCEDURE DIVISION

OPEN (Cont.)
21.

The REVERSED option may be used only on TU45 and TU70 tape
drives.
If you specify this option for a file, the file will
be opened and the tape positioned at the end of the file.
A
READ statement will ~ause the final block of the file to be
read by the monitor.
The record which is actually made
available to you is the first record of the last block, which
might not be the last record.
For example,
if you have
specified a
blocking factor of 2, the record made available
by the READ statement will be the next to last record in the
file,
not the last· one.
To be sure that you are actually
reading the last record in the file,
you should specify a
blocking factor of 1.

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.

5-63

January 1980

THE PROCEDURE DIVISION

PERFORM

5.9.26

PERFORM

Function
The PERFORM statement is used to depart from the normal sequence of
execution in order to execute one or more procedures and then return
control to the normal sequence.
General Format

PERFORM procedure-name-l [ { ~~~~UGH

} procedure-name-2 ]
denti fier-l
PE RFORM proced ure-name-l [ { THROUGH
} procedure-name-2 ] {ii nteger-l
} TIMES
THRU
PERFORM procedure-name-l [{ ~~~~UGH

} procedure-name-2 ] UNTIL condition-l
PERFORM procedure-name-l [ {THROUGH
THRU
} procedure-name-2 ]
VARYING

{i dent ifi er-2} FROM
index-name-l

dent ifi er- 3}
index-name-2
1itera1-1

tdenti fier-4}
1iteral-3

UNTIL condition-l

[ AFTER

tdentifier-s}
index-name-3

FROM

{i dent i fi er- 7}
1itera 1-4

UNTI L condition-2

[AFTER

{i denti fier-s}
index-name-5

FROM

{identi fier-lo}
1iteral-6

UNTI L condition-3

rdentifier-6}
index-name-4
1iteral-3

identifier-9
index-name-6
1iteral-5

5-64

THE PROCEDURE DIVISION

PERFORM (Cont.)
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 either a numeric literal or the figurative
constant ZERO.

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 may occur between procedure-name-l and
procedure-name-2.

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.

No PERFORM statement may terminate until
all
PERFORM
statements that it has executed have terminated. A PERFORM
statement may be executed which terminates at the same
procedure-name as another active PERFORM.

Format I causes the PERFORM range to be executed once,
followed by a return to the statement immediately following
the PERFORM.

5-65

THE PROCEDURE DIVISION

PERFORM(Cont.)
7.

Format 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 may 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.

Format 3 causes the PERFORM range to be executed until the
condition specified in the UNTIL clause is true.
If ~his
condition is true at the time the PERFORM statement is
initialized, the range is not executed.
Conditions are
explained in Section 5.5, Conditional Expressions.

Format 4 is used to augment the value of one or more
identifiers during the execution of a PERFORM statement.
In
format 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.
The flow chart in Figure 5-3 illustrates the logic
PERFORM cycle when two identifiers are varied.

ENTRANCE

Set identifier-2 and identifier-5
to current F ROM val ues

True

Condition-'

Exit

False
True

Condition-2
False
Execute procedure-name-'
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.Q28-79

Figure 5-3 PERFORM Cycle Logic - Two Variables

5-66

the

THE PROCEDURE DIVISION

PERFORM (Cont.)
The flow chart in Figure 5-4 illustrates the logic of the PERFORM
cycle when three identifiers are varied.
ENTRANCE

+
Set
identifier-2. identifier-5. identifier·8
to current FROM value$

+
Condition-l

True

False

Set
identifier-8
to its current
FROM value

Set
identifier-5
to its current
FROM value

Augment
identifier-8
with current
BY value

Augment
identifier-5
with current
BY value

Augment
identifier-2
with current
BY value

Execute
procedure-name-l
TH RU procedurename-2

-.....

True

False

Condition-3

Exit

False

Condition-2

True

J
MR·S'()69·79

Figure 5-4 PERFORM Cycle Logic - Three Variables
10.

When a procedure-name in a segment with a priority number
greater than 49 is 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 may
have as its range procedures wholly contained within the
DECLARATIVESi however, a PERFORM statement in a section
within the DECLARATIVES may 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 may not have within its
range any procedures outside of that INPUT or
OUTPUT
PROCEDURE.

5-67

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 fi 1e-name

[NEXT] RECORD

[INTO i denti fi erJ

[AT END imperative-statement]
READ file-name RECORD [INTO identifier] [INVALID KEY imperative-statement]
READ fil e-name RECORD [INTO i denti fi erJ
[KEY I S data-name]

~INVALID KEY imperative-statement]
Technical Notes
1.

An OPEN INPUT or OPEN I-O statement must be executed for the
file prior to execution of the first READ statement for that
file.

those

files

whose

For files whose organization is RELATIVE or INDEXED, the
INVALID KEY phrase or the AT END phrase must be specified if
no applicable USE procedure is specified for file-name.
If an end-of-file condition is encountered during
the
execution o£ a READ statement for a sequential file, any
statements specified in the AT END clause are executed, and
no logical record is made available.
The logical end-of-file depends upon the type of device on
which the file resides
(users of TOPS-IO should see the
Monitor Calls Manual, and users of TOPS-20 should see the
Monitor Calls Reference 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.

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 fil e-name

[NEXT] RECORD

[INTO i denti fi erJ

[AT END imperative-statement]
READ file-name RECORD [INTO identifier] ~INVALID KEY imperative-statement~
READ file-name RECORD [INTO identifier]
[KEY IS data-name]

~INVALID KEY imperative-statement]
MR-S-1338-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
organization is SEQUENTIAL (explicitly or implicitly). For
those files, the AT END phrase must be specified if no
applicable USE procedure is specified for file-name.
The READ statement can be executed after the AT END condition
occurs.
However, the AT END path is taken again and FILE
STATUS of 16 is set.
The INVALID KEY clause is valid only for
access mode is RANDOM or DYNAMIC.

those

files

whose

For files whose organization is RELATIVE or INDEXED, the
INVALID KEY phrase or the AT END phrase must be specified if
no applicable USE procedure is specified for file-name.
If an end-of-file condition is encountered during
the
execution of a READ statement for a sequential file, any
statements specified in the AT END clause are executed, and
no logical record is made available.
The logical end-of-file depends upon the type of device on
which the file resides
(users of TOPS-10 should see the
Monitor Calls Manual, and users of TOPS-20 should see the
Monitor Calls Reference Manual) •
5-69

October 1985

THE PROCEDURE DIVISION

READ (Cont.)
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.
When a READ statement is executed for a
file
whose
organization
is RELATIVE, the object-time system makes
available the record whose relative record number is equal to
the contents of the data item named in the RELATIVE KEY
phrase. If no such record exists, the INVALID KEY statements
are executed and no record is made available. For relative
files whose access mode is DYNAMIC, the NEXT phrase must be
specified if you wish to read the file sequentially. If you
specify the NEXT phrase the record made available is the next
logical record after the one most recently read, unless there
has not bean a READ statement since the last OPEN or START
statement. If this is the case, the record made available is
the first record, in the case of OPEN, or the record
specified in the START statement, depending upon whether the
EQUAL, GREATER THAN, or NOT LESS THAN option is used.
When a READ statement is executed for a
file
whose
organization is INDEXED, a search of the file is made to find
the record that has a key equal to the contents of the RECORD
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 statements associated with the INVALID KEY clause are
executed, and no record is made available.
When a READ NEXT statement is executed for a file whose
organization is INDEXED, the next record available on the
indicated key field logical path is made available.
The
logical key path is used regardless of intervening WRITES,
REWRITES, DELETES, or any previous I/O operation which caused
the INVALID KEY path to be taken. If a START statement was
the last reference to the file, the record made available is
the one specified in the START statement, or the first of the
specified range. That is, if your program contains the
following sentence:

START MYFILE KEY IS GREATER THAN MIN-KEY INVALID
TO DISPLAY-ERROR

KEY

the record made available to your program is the first
logical record with a key value greater than MIN-KEY. If no
such record exists (that is, you have reached end-of-file),
the INVALID KEY statements are executed, and no record is
made available. If the file has been opened but no READ,
WRITE, REWRITE, DELETE or START statement has been executed,
the first record of the file is made available.

The NEXT clause must be specified for files in dynamic access
mode, when records are to be retrieved sequentially. The
NEXT clause causes the next logical record to be retrieved
from the file.
A READ NEXT statement, following a WRITE statement execution
with a low key, causes access of the low numbered record.

5-70

October 1985

THE PROCEDURE DIVISION

READ (Cont.)
4.

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.

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 is executed.

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.

The INTO clause can be specified in the READ statement when:

all
records associated with the file and data-item
specified
in the INTO clause are group items, or
elementary alphanumeric items, or

only one record description is subordinate
description entry.

the

file

The KEY IS data-name clause can be specified to read ISAM or
RMS records.
With both record formats, the data-name must
previously be supplied a value before the read.
For ISAM the
data-name refers
to the RECORD KEY value.
For RMS, the
data-name refers to either the primary key value (RECORD KEY
IS)
or an alternate key value (ALTERNATE KEY IS).
Refer to
Appendix I for additional information on reading RMS indexed
files.
Example:
SELECT MASTER-FILE ASSIGN TO DSK
ORGANIZATION IS INDEXED
ACCESS IS DYNAMIC
RECORD KEY IS MASTER-NUMBER.

PROCEDURE DIVISION.

MOVE 99 TO MASTER-NUMBER.
READ MASTER-FILE KEY IS MASTER-NUMBER
INVALID KEY GO TO KEY-ERROR-ROUTINE.
5-71

October 1985

THE PROCEDURE DIVISION

RELEASE
5.9.27

RELEASE

Function
The RELEASE statement transfers records to the initial
sort operation.

phase

the

General Format
RELEASE record-name

[FROM i dent i fi erJ
MR-S-1339-B1

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 executed,
record-name can no longer be available.

5-72

the

contents

THE PROCEDURE DIVISION

RETAIN

5.9.28

RETAIN

Function
The RETAIN statement specifies your intent to access one or more
records in an indexed or relative file that is open for simultaneous
update.
General Format

RETAIN file-name-l

FOR

READ
REWRITE
READ-REWRITE
DELETE
WRITE

NEXT RECORD
RECORD [KEY {i?entifier-l}]
-

AND

~WRITE

ANY VERB

,fi le-n ame-2

FOR

llteral-l

READ
REWRITE
READ-REWRITE
DELETE
WRITE
""READ-WR ITE
ANY VERB

[UNTIL FREED]

NEXT RECORD.
..
RECORD [KEY {lgentlfler-l}] (

READ
REWRiTE
READ-REWRITE
DELETE
WRITE

. - llteral-l

AND

~WRITE

ANY VERB

[UNAVAILABLE statement-l

READ
REWRiTE
READ-REWRITE
DELETE
WRITE

[ UNTI L FREED]

~WRITE

ANY VERB

[.statement-2]

... ]

~
MR-S-1340-81

5-73

October 1985

THE PROCEDURE DIVISION

RETAIN (Cont.)
Technical Notes
files

Filename-I, filename-2 ••• must be the
names
previously opened for simultaneous update.

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 NEXT RECORD clause must be specified when you want to
retain the next record in the file. LOW-VALUES cannot be
moved to the RECORD KEY for a RETAIN of the next record.

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-fi1e condition.

The action performed by any I/O operation is logically the
same as if the file were not opened for simultaneous update.
For example, the RELATIVE KEY is examined to determine the
record to be read/written/rewritten/de1eted in a relative
file; and the RECORD KEY is examined to determine the record
to be read/written/rewritten/de1eted 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.
You can
perform a WRITE to a nonexistent record, but you will receive
an error if you attempt to perform any other I/O operation on
these nonexistent records.

It is possible to mix requests for records from random
indexed-sequential files in the same RETAIN statement.

10.

Using the RETAIN for WRITE, DELETE, or ANY VERB statements
with indexed-sequential files locks the entire file, not just
the record.

5-74

are any valid COBOL statements.

and

October 1985

THE PROCEDURE DIVISION

RETAIN (Cont.)
11.

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). When
you retain a record for any use other than READ, all other
users are banned completely from accessing that record.

12.

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 RgTAIN statement, the file
must have been explicitly opened for ANY VERB.

13.

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.

14.

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.

15.

The KEY phrase allows you to specify a particular
to specify more than one record in a file.

16.

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. The result is
that both programs hang or stall waiting
for the resource to become available.
17.

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 statement can be used
in
the UNAVAILABLE phrase.

5-75

THE PROCEDURE DIVISION

RETAIN (Cont.)
18.

Use of the RETAIN statement differs according to
the
organization of the file.
Each type of file is described
separately below.

5-76

October 1985

THE PROCEDURE DIVISION

RETAIN (Cont.)
19.

Relative files
a.

Records in a relative file can be retained only for READ,
WRITE, READ-REWRITE, REWRITE, DELETE, or ANY VERB. For
relative files, ANY VERB means READ, WRITE, READ-REWRITE,
DELETE, and REWRITE.

When the KEY phrase is specified, the value of the key
designates a specific record in the file, just as the
RELATIVE KEY of the file does. Thus, record 1 is always
the first record in the file. If you specify the NEXT
option, 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,
REWRITE, DELETE 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,
DELETE, or READ-REWRITE 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 or DELETE is defined to be the one following the
record just read.
However, the next record to be
retained for REWRITE is defined to be the record just
read. Note that the next record actually read or written
depends on the value of the RELATIVE KEY, not on the
record specified in the RETAIN statement.

If you wish to read/rewrite the file sequentially, you
should select the NEXT option in the RETAIN statement,
and use the READ NEXT syntax so that you are performing
I/O on the same records that you are retaining. If you
wish to read/rewrite the file randomly, you should set
the RELATIVE 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 RELATIVE KEY specified for the
file.

The value of a key can be specified by any identifier.
The identifier must be numeric, and can be subscripted or
qualified or both. For the sake of efficiency, its USAGE
should be COMPUTATIONAL or INDEX. The value of the key
can also be specified by a positive integer numeric
literal containing ten or fewer digits.

5-77

October 1985

THE PROCEDURE DIVISION

RETAIN (Cont.)
Example
OPEN I-O PART FOR READ AND REWRITE ALLOWING OTHERS
NONE.
MOVE 64 TO PART-ACTUAL-KEY
RETAIN PART FOR READ.
READ PART, INVALID KEY GO TO ERR.

RETAIN PART NEXT FOR REWRITE,
PART KEY 35 FOR READ AND REWRITE.
REWRITE PARTREC.
MOVE 35 TO PART-ACTUAL-KEY.
READ PART, INVALID KEY GO TO ERR.
REWRITE PARTREC.
2~.

Indexed-sequential 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,
REWRITE, and DELETE.

When RETAIN FOR DELETE, WRITE, or ANY VERB is specified
for an indexed-sequential file, the entire file, rather
than just the block, is locked for simultaneous update.

When the KEY phrase is specified, the value of the key
refers to a specific record
in the file, just as the
RECORD 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 numeric, a positive numeric literal of ten
or fewer digits can be used as the value in the KEY
phrase. For the sake of efficiency the key should be
USAGE COMPUTATIONAL or INDEX.

If the KEY phrase is not specified, the value used for
the key is taken from the current RECORD KEY for the
file.

If NEXT is specified, the record retained is that
following the last record referenced in the same RETAIN
statement or by a READ, WRITE,
REWRITE, or DELETE
statement.

Example
OPEN I-O LETTERS FOR READ ALLOWING OTHERS READ AND
REWRITE.
MOVE "B" TO RECORD KEY.
RETAIN LETTERS FOR READ.
READ LETTERS INVALID KEY GO TO ERRS.

5-78

October 1985

THE PROCEDURE DIVISION

REWRITE

5.9.31 REWRITE
Function
The REWRITE statement replaces an already existing record in a file.
General Format

REWRITE record-name

[FROM identifieC] [INVALID KEY imperative-statement]

Technical Notes
1.

Sequential files and files with sequential access
a.

The file must be open for INPUT-OUTPUT.

The last file operation must have been a successful READ.

The record that is replaced is the record that
read.

The INVALID KEY clause must not be specified.

Indexed and relative files

was

just

(dynamic or random access)

The file must be open for

INPUT-OUTPUT.

The record that is replaced is the
record
indicated by
the current value of
the record (indexed) or RELATIVE
(relative) KEY.

The INVALID KEY clause is required if
has been specified.

The INVALID KEY clause is executed if no
record exists
corresponding
to
the current value of the key or if the
current value of the RELATIVE KEY (for relative files) is
either zero or a negative number.

USE

procedure

If the FROM option is used, the statement is equivalent to:
MOVE identifier TO record-name
REWRITE record-name (without the FROM option)

The INVALID KEY phrase must not be specified for
a
REWRITE
statement that references a file in sequential mode.
This is
because a
REWRITE may only be done
on
a
file
in
sequential-access mode after a successful READ statement is
executed.

The INVALID KEY phrase must be specified
in the REWRITE
statement for files in the random- or dynamic-access mode for
which an appropriate USE procedure is not specified.
5-79

January 1980

THE PROCEDURE DIVISION

SEARCH
5.9.32

Function
The SEARCH statement is used to
condition exists.

table

until

specified

General Format

SEARCH i dent i fi er-l [ VARY! NG
WHEN condition-l
[ WHEN condition-2

imperative-statement-2
}
{ NEXT
SENTENCE
imperative-statement-3
}] ...
{ NEXT
SENTENCE

SEARCH ALL identifier-l

(

) data-name-l

WHEN

rAT END imperative-statement-l]
{ ~dentifier-2}l
lndex-name-l J L!

[AT END imperative-statement-l]

{IS EQUAL TO} {identifier-3
IS
literal-l
arithmetic-expression-l

condition-name-l

( data - name- 2

}

{i ~ EQUAL TO} {identifier-4
literal-2

}) ]
(
arithmetic-expression-2 ,

l can di t ion - name - 2
im perative-statement-2}
{ NEXT SENTENCE

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 format 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.

5-80

appear

item

THE PROCEDURE DIVISION

SEARCH (Cont.)
4.

In format 1, condition-I, condition-2,
condition described in Section 5.5.

etc.,

can

any

In format 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-l, the
first index-name in the INDEXED BY option is used as the
index, and identifier-2 will contain the value of the index
at each step of the search.

If format 1 of the SEARCH verb is used, a serial type of
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 DEP~NDING 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 format 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 may 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 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.
10.

In either format, 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-HAPPENDED;
WHEN A(I) = "XYZ" AND B(I) = 350 GO TO GO-ONE.

5-82

THE PROCEDURE DIVISION

SET

5.9.33

SET

Function
The SET statement allows a data-item to be
or set to a value.

incremented,

decremented,

General Format

SET {i dent i fi er-l
index-name-l

SET index-name-4

[ i denti fi er-2 ]
[i ndex-name-2 ]

[index-name-5]

} TO

identifier-3}
{ index-name-3
i nteger-l

UP BY
} {identifier-4}
{ DOWN BY
integer-2

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 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-83

the

figurative

constant

THE PROCEDURE DIVISION

SORT

5.9.34 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

ASCENDING}
{ DESCENDING

KEY data-name-l

[ data-name-2]

AS CEND I NG }
{ DES CEN 01 NG

KEY data-name-3

[data-name-4]

. J.

[COLLATING SEQUENCE IS alPhabet-name]

INPUT PROCEDURE IS section-name-l

{ USING file-name-2

THROUGH}
[{ THRU

section-name-2] }

[file-name-3]

,
1

OUTPUT PROCE DURE IS section-name-3 [{ THROUGH}
THRU

sect ion -name-4]

GIVING file-name-4

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.
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 may be qualified but not subscripted.

SORT statements may 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.

5-84

January 1980

THE PROCEDURE DIVISION

SORT (Cont.)

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
in order 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
in order to make sorted records available for processing.

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.

10.

If an input or output procedure
is
specified,
those
procedures are PERFORMED by the SORT statement, and all rules
relating to the range of a PERFORM must be observed.

11.

If the USING option is specified, all records 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, ••. ,
will
be
executed as appropriate.
The USING option is equivalent to
the following INPUT PROCEDURE:
Ll.
L2.
L3.

12.

OPEN INPUT file-name-2
READ file-name-2 INTO sort-record;
L3.
RELEASE sort-record.
GO TO L2.
CLOSE file-name-2.

END

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
will be executed as appropriate.
The GIVING option
is
equivalent to the following OUTPUT PROCEDURE:
L4.
L5.
L6.

OPEN OUTPUT file-name-4.
RETURN sort-file INTO record-name-4;
WRITE record-name-4.
GO TO L5.
CLOSE file-name-4.

5-85

AT END GO TO L6.

January 1980

THE PROCEDURE DIVISION

SORT (Cont.)
13.

An ISAM file cannot be sorted directly
standalone SORT.

using

the

non-COBOL

In designing
the
ISAM files are by definition a sorted set.
file you should use the order in which the file will be 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.
The input procedure can release records
to the
sort.
You can read the file in two ways - sequentially using
READ NEXT, or randomly by selecting the desired record and
inserting the key value in the RECORD KEY.
Usually, reading
the file sequentially and allowing SORT to order the
records
is much faster.
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.
14.

15.

The collating sequence used
to compare
the
specified
alphabetic data items is determined in the following order:
a.

SORT first looks at the collating sequence defined in the
COLLATING SEQUENCE phrase in the SORT statement.

If the COLLATING SEQUENCE phrase was not specified,
SORT
uses
the collating sequence defined
in the PROGRAM
COLLATING SEQUENCE of the OBJECT-COMPUTER paragraph.

If neither of the above two phrases have been specified,
SORT uses the normal collating sequence.
For example,
SORT would use ASCII for
ASCII
items and EBCDIC for
EBCDIC items.

Refer to the SORT User's Guide for more information on SORT.

5-86

January 1980

THE PROCEDURE DIVISION

START
5.9.35

START

Function
The START statement provides for logical positioning within a relative
or indexed file, for subsequent sequential retrieval of records.
General Format

START fil e-name

IS
EQUAL
}
IS - - TO
IS GREATER THAN
IS >
{ IS NOT LESS THAN
IS NOT -(-

data-name

[INVALID KEY imperative-statement]
Technical Rules
1.

File-name must be the name
dynamic access.

sequential

Data-name may be qualified.

The INVALID KEY phrase must be the data item specified if
applicable USE procedure is specified for file-name.

The file associated with file-name must be open in the INPUT
or I~O mode at the time the START statement is executed.

If you omit the KEY phrase, you imply the phrase IS EQUAL TO
data-name, where data-name refers to the RECORD KEY of an
indexed file or the RELATIVE KEY of a relative file.

If the file associated with file-name is a relative file, and
you include data-name, data-name must be the data item
specified in the RELATIVE KEY phrase of the file control
entry.
If the file is an indexed one and you include
data-name, data-name must be either the data item specified
as the record key, or an "approximate key". An "approximate
key" is a part of a key, whose leftmost character position is
the same position as the leftmost position of the RECORD KEY
but which is not the entire key. Suppose, for example, you
have an ISAM file whose key is of the form
YY-MM-DD-XX

5-87

file

with

THE PROCEDURE DIVISION

START (Cont.)
where YY is the year, MM the month, DO the day, and XX the
charge sequence number.
If you wished to begin processing
the file at the first record of July 1978, you could write
the following code:
SELECT CHARGE-FILE
ASSIGN TO DSK
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS CHG-REC-KEY.

MOVE "78-07-" TO CHG-REC-KEY.
START CHARGE-FILE KEY IS GREATER THAN CHG-REC-KEY,
INVALID KEY GO TO ERR-RTN.
The effect of this would be to find the first record in the
file whose key collates higher than 78-07- and then position
the record pointer in front of that record.
If you specified
NOT LESS THAN instead of GREATER THAN the pointer would be
positioned in front of the record whose key is 78-07-66666 if
such a record existed;
otherwise the pointer would be
positioned as in the actual example.
Note that only indexed
files may use the "approximate key", and that the leftmost
positions of the record key and the "approximate key" must be
the same character position in the record, not simply contain
the same character.
7.

If the comparison is not satisfied by any record in the file,
the INVALID KEY condition exists, the execution of the START
statement is unsuccessful, and your logical position in the
file
is
undefined.
When
this
is
the
case,
the
imperative-statements following the INVALID KEY phrase are
executed.

The execution of the START statement causes the value of the
FILE STATUS data item, if any, associated with file-name to
be updated.

5-88

THE PROCEDURE DIVISION

STOP

5.9.36

STOP

Function
The STOP statement halts the object program.
General Format
RUN
}
{ l1teral

Technical Notes
1.

The literal may be numeric or
figurative constant except ALL.

nonnumeric

may

any

If the literal is numeric, it must be an unsigned integer.

If the literal option is used, the literal is displayed on
the user's terminal.
The literal may be a figurative
constant; in this case, a single character is displayed.
The program waits for the operator to type
CONTINUE
Following receipt of this message, the program
execution at the statement following the STOP.

continues

If the RUN option is used, all files currently open
closed, and execution of the program is terminated.

5-89

are

THE PROCEDURE DIVISION

STRING
5.9.37

STRING

Function
The STRING statement is used to concatenate the partial
contents of several data items into a single data item.

complete

General Format

~ent

STRI NG {i
i fi er-l} [i dent i fi er-2J
llteral-l
literal-2

(identifier-3)
(
( SIZE
,

DELIMITED BY

~ 1i te ra 1 - 3

DELIMITED BY

~enti

~J ...

i
fi er-6
llteral-6
(

illS

INTO identifier-7 [WITH POINTER identifier-8]
[ON OVERFLOW imperative-statement]

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 (according to the rules
for
numeric transfers) to an intermediate unsigned
numeric data item of the same size as the source whose
USAGE is the same as that of identifier-7 , and then it
is treated as alphanumeric.

If subsccipting 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 particular source item are
used.

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-90

are called source literals.
be alphanumeric literals or
constants
without
the
ALL

THE PROCEDURE DIVISION

STRING (Con t.)
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 (according to the rules
for
numeric transfers) to an intermediate unsigned
numeric data item of the same size as the delimiter whose
USAGE is the same as that of identifier-7 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, either 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.
NOTE
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
condition for each of the corrsponding source
items is the rightmost boundary of the source item.

delimit~r

5-91

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-92

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 specifically
checked for in the order stated.
1.

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, will 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-93

January 1980

THE PROCEDURE DIVISION

STRING (Cont.)

Overflow
a.

The STRING statement is considered to have caused an
overflow if the transfer of characters to the destination
is terminated because of either of the conditions shown
below:
1.

The initial value of the pointer is not a positive
integer less than or equal to the size of the
destination.

A character has been transferred to
the
last
character position of the destination, though not all
appropriate cha~acters of all source items have been
transferred.

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 has been
set to the appropriate value, the flow of control 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 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.

5-94

January 1980

THE PROCEDURE DIVISION

SUBTRACT

5.9.38

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

SUBTRACT {identifier-I} [identifier-2]
literal-I

literal-2

[:identifier-n [ROUNDED]:]

SUBTRACT

[ON SIZE ERROR imperative-statement]

{i~entifier-I} [i~entifier-2l
llteral-I

llteral-2

FRor~ identifier-m [ROUNDED]

i dent i fi er-m}
{ literal-m

GIVING identifier-n [ROUNDEQ] [identifier-o [ROUNDED]] ...
r=ON SIZE error imperative-statement]

SUBTRACT

{~ESPONDING} identifier-l FROM identifier-2 [ROUNDEQ]

[ON SIZE ERROR imperative-statement]

Technical Notes
1.

Each SUBTRACT statement must contain at least two operands
(that is, a subtrahend and a minuend).
In formats 1 and 2,
each identifier must refer to an elementary numeric item,
except that identifiers to the right of the word GIVING may
refer to numeric edited items.
In format 3, each identifier
must refer to a group item.
Each literal must be a
constant ZERO.

numeric

literal

the

figurative

The composite of all operands
(that is, the data item
resulting from the superimposition of all operands aligned by
decimal point) must not contain more than 18 decimal digits
for the standard 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.
(See Section 1.1 for a
definition of the BIS-compiler.)

Format 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.

5-95

THE PROCEDURE DIVISION

SUBTRACT (Cont.)
4.

Format 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.

Format 3 causes the data items in the group ite~ 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 in Section 5.7, The
CORRESPONDING Option.

The ROUNDED and SIZE ERROR options are described in Section
5.6, Common Options Associated with Arithmetic Verbs.

5-96

THE PROCEDURE DIVISION

TERMINATE
5.9.39

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 may not
be executed until another INITIATE statement is executed for
that report.

The TERMINATE statement does not close the file associated
with the repo~t:
a CLOSE statement must be executed after
the TERMINATE statement is executed.

5-97

THE PROCEDURE DIVISION

TRACE
5.9.40 TRACE
Function

The TRACE statement causes COBDDT 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

Technical Notes
1.

The TRACE statement works with the COBDDT utility to help you
debug your COBOL-74 program.
COBDDT must be loaded with your
program for the program to be traced.
(See Section 7.3.1,
Loading and Starting COBDDT, for more information about using
COBDDT.) If COB DDT is not loaded,
the TRACE calls are
ignored.

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 the 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.

5 •. 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.

When compiling for a production run, you should include
the
IP switch in the command string so that trace calls wiLl not
be generated and TRACE statements
in the program will be
ignored.
The following example shows paragraphs with TRACE
OFF and TRACE ON statements included.

5-98

January 1980

THE PROCEDURE DIVISION

TRACE (Cont.)
PROCEDURE DlVISION.
PARA.

TRACE ON.
PARB.

TRACE OFF.
PARCo

TRAC~

ON.

PARD.

Paragraph PARB and PARD are traced. Paragraph PARC is not
traced
because
the
TRACE
OFF st~tement is included
immediately before it. If the IP switch is included in the
command stringwh~n this program is compiled, the TRACE
statements ~ill be ignored and trace calls will not be
generated.

5-99

THE PROCEDURE DIVISION

UNSTRING
5.9.41

UNSTRING

Function
The UNSTRING statement is used to split a single data item
(for
example,
a text string)
into several parts, depending on the
occurrence of specified delimiters, and to store the parts into
separate data items where they may be more easily accessed by the
COBOL program.
General Format
UNSTRING identifier-l

INTO identifier-4

t] ...J

t [ -OR [ALL]
{i?enti fier- 3
-l1teral-2
,

identifier-z
,
{literal-l

[DELIMITED BY

[OELHlITER IN identifier-5][COUNT IN identifier-6]

[identifier-7 [DEUt1ITER IN identifier-S] [COUNT IN identifier-gJ]

~WITH POINTER identifier-l~~TALLYING IN identifier-ll~
[ON OVERFLOW imperative-statement]

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 is 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.

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.

5-100

THE PROCEDURE DIVISION

UNSTRING (Cont.)

Delimiter Items
a.

The
data
items
referenced
by
identifier-2,
identifier-3, ••• , are called delimiter data items.

A numeric delimiter item is moved (according to the rules
for
numeric transfers)
to an intermediate unsigned
numeric data item of the same size as the delimiter whose
USAGE is the same as that of identifier-l and then is
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.

is a figurative constant,
it
If a delimiter literal
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 which 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.

Delimiter Storage Items
a.

A DELIMITER IN phrase may be specified
DELIMITED BY phrase is specified.

the

The
data
items
referenced
by
identifier-5
identifier-8 are called delimiter storage items.

and

5-101

only

January 1980

THE PROCEDURE DIVISION

UNSTRING (Cont.)

I
5.

•

If subscripting or indexing is needed to identify a
delimiter storage item, the values that are used are the
values of the required subscripts and/or indexes and the
values of the depending items which existed just prior to
the transfer
of
data
to
the
destination
item
corresponding to that delimiter storage item.

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 size to contain a value equal to the size of
the source.

If subscripting or indexing is needed to identify a count
storage item, the values that are used are the values of
the required subscripts and/or indexes and the values of
the depending items which existed just prior to the
transfer of data to the destination item corresponding to
that count storage item.

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
The number of characters of the source
that were examined is not necessarily
the same as the number of characters
that were actually transferred, because
the deEtination may 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.

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.

5-102

January 1980

THE PROCEDURE DIVISION

UNSTRING (Cont.)
e.

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,
however, 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
items 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 interactive
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 will be 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

January 1980

THE PROCEDURE DIVISION

UNSTRING (Cont.)

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 to
the
destination item for that iteration.

3.
4.

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

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
iteration.
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 will be 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

January 1980

THE PROCEDURE DIVISION

UNSTRING (Cont.)

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 then 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
e 1) •

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 (condition a of Note e2).

No more source
character
(Condition b of Note e2).

5-105

positions

remain

January 1980

THE PROCEDURE DIVISION

UNSTRING (Cont.)

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
may occur during
the execution of the MOVE
statement.
This data
item may contain no character
positions
at all
if
the pointer-indicated position
satisfied condition a of Note el or
it may 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 holds, the string of contiguous source
character positions
that contain the match for a
delimiter string is treated as a complete
indiyidual
data
item and is moved to the delimiter storage item
according
to
the
rules
for
the MOVE statement,
including truncation if necessary.
If 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

January 1980

THE PROCEDURE DIVISION

UNSTRING (Cont.)
k. When the UNSTRING statement has been executed,
the
real destination counter
is updated using the internal
destination counter 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.

the
If the ON OVERFLOW phrase is not specified,
after
execution
of the UNSTRING statement,
regardless of
whether or not there was an overflow, control passes to
the
the point in the program immediately following
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 control 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

January 1980

THE PROCEDURE DIVISION

USE
5.9.42

USE

Function
The USE statement specifies procedures for error handling that are in
addition to the standard procedures provided by the input-output
control system.
General Format

fi 1e-name-l

USE AFTER STANDARD

,EXCEPTIONl PROCEDURE ON
tERROR

OPEN

[fi 1 e-name- 2] OPEN

INPUT
OUTPUT

r:o-

EXTEN D

USE BEFORE REPORTING identifier.

Technical Notes
1.

USE statements may appear only in the Declaratives portion of
the Procedure Division.
The Declaratives portion follows
immediately after the PROCEDURE DIVISION header and begins
with the word
DECLARATIVES.
The Declaratives portion ends 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.

5-108

THE PROCEDURE DIVISION

USE (Cont.)
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 may 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.

Format 1 causes the designated procedures to be executed
after completing the standard input-output error routine.

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 may refer to a USE section or to a
procedure contained entirely within such a USE section.

No input/output can be performed other than ACCEPT
DISPLAY statements during execution of a USE procedure.

Format 1 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 will
be executed for
all
INPUT files;
if the OUTPUT option is
used, they will be executed for all OUTPUT files;
if the I-O
or the INPUT-OUTPUT option is used, they will be executed for
all INPUT-OUTPUT files;
if the filename-l format is used,
they will be executed only for that particular file.
If more
than one USE procedure could apply in a situation, only one
will actually be executed.
The procedure to be used will be
the one which is most restrictive, that is,
the one which
applies most closely to the situation in question.
For
example, suppose you specify the file-name-l option and the
OPEN option, and you get an error when you attempt to open
file-name-l.
The procedure you specified for the file-name-l
option will be executed,
but the procedure for the OPEN
option will not, because it is less restrictive.

5-109

and

THE PROCEDURE DIVISION

USE (Cont.)
If the filename-l OPEN format is used, the system performs
the associated procedutes 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.
8.

Identifier-l in Format 2 represents a report group named in
the Report Section of the Oata Division. An identifier must
not appear in more than one USE statement. The report group
must not be TYPE DETAIL.

5-110

THE PROCEDURE DIVISION

WRITE
5.9.43 WRITE
Function
The WRITE statement transfers a logical record to an output file.
General Format

WRITE record-name [FROM identifier-I]

[{

BEFORE( ADVANCING
AFTER ,
,

END-OF-PAGE}
{ EOP

Jl]

{
I

i dent i fi er-2 } [LI NE
integer
LINES
.
{mnemOnl c-name}

PAGE

imperative-statement]

WRITE record-name [FROM identifier] [INVALID KEY imperative-statement]

Technical Notes
1.

An OPEN OUTPUT, OPEN I-O, OPEN INPUT-OUTPUT or OPEN EXTEND
statement must be executed for the file prior to the
execution of the WRITE statement. SEQUENTIAL files and files
with SEQUENTIAL ACCESS must be OPEN OUTPUT or OPEN EXTEND.
OPEN EXTEND is valid only for ,SEQUENTIAL ORGANIZATION files.

After the WRITE is executed, the data in record-name-l may no
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.

Format 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:
a.

If the ADVANCING clause is not
recording mode is ASCII, BEFORE
assumed.

If identifier-2 or integer-l is specified,
it must
The form is
represent a positive integer or zero.
advanced the number of lines equal to the value of
identifier-2 or integer-I.

5-111

specified
ADVANCING

and
the
1 LINE is

January 1980

THE PROCEDURE DIVISION

WRITE (Cont.)
c.

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

record

printed

If end-of-reel is encountered while writing on magtape,
WRITE statement performs the following operations:

the

A file mark is written, and the tape is rewound.

If the file was assigned to more than one tape unit,
units are advanced.

the

If labels are not OMITTED, a label is written on the
tape.

new

If the END-OF-PAGE phrase is specified,
the
LINAGE clause
must be specified
in
the
file
description entry for the
associated
file.
The words
END-OF-PAGE
and
EOP
are
equivalent.

The ADVANCING mnemonic-name phrase cannot be specified when
writing a
record
to a
file whose file description entry
contains the LINAGE clause.

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:
a.

If identifier-2 is specified, it must be described as a
one
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
Triple spaclng
Suppress spacing
Skip to channels I through 8 respectively
on the paper-tape format control loop

5-112

January 1980

THE PROCEDURE DIVISION

WRITE (Cont.)
Note that the object-time system interprets the value
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 will be ASCII, regardless of the recording
mode specified in the RECORDING MODE clause.

The INVALID KEY clause is illegal for SEQUENTIAL FILES.

10.

The INVALID KEY clause is executed if either of the following
conditions exist:
a.

The RELATIVE
exists.

RECORD

KEY

indicates

record

For INDEXED files with SEQUENTIAL ACCESS,
the value of
the RECORD KEY is not greater
than the value of the
RECORD KEY for the previous record.
must

that

11.

INDEXED files that have SEQUENTIAL ACCESS
with RECORD KEYS in ascending order.

written

12.

If a RELATIVE KEY is specified for
a
SEQUENTIAL ACCESS,
the relative record
just written is placed into the RELATIVE
RELATIVE file with SEQUENTIAL ACCESS is
starting with record number 1.

13.

When executing a WRITE statement for a SEQUENTIAL file opened
for 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.

14.

The INVALID KEY phrase must be specified if an applicable USE
procedure is not specified for the associated file.

15.

If the FROM option is used, the statement is equivalent to:

RELATIVE file with
number of the record
KEY data
item.
A
written sequentially

MOVE identifier-l TO record-name-l
WRITE record-name-l (without the FROM option)
Note that identifier-l must be a data-name and
figurative
constant
(for example,
SPACES),
syntactically equivalent to a literal.

5-113

cannot be a
because it is

January 1980

THE PROCEDURE DIVISION
VERB FORMATS

THE PROCEDURE DIVISION
GENERAL FORMAT FOR PROCEDURE DIVISION
PROCEDURE DIVISION

~SING data-name-l

~ata-name-2~

. .J

[JECLARATI VES.
{ section-name SECTION

C=segment-number~

GaragraPh-name. [sentence]

... ]

declarative-sentence

... }

END OECLARATIVES~
{ sect ion-name SECTION

~egment-number]

[!aragraPh-name . [sentence]

... ]

}

5-114

THE PROCEDURE DIVISION
GENERAL FORMAT FOR VERBS

ACCEPT identifier-1

... [fROM mnemonic-name]

identifier-2

DATE
ACCEPT identifier FROM) DAy
\ TIME

i dent i fi er-2]
[ 1i teral-2

ADD {identifier-I
1 i tera 1-1

[i denti fi er-n [ROUNDEg:[] •• •

ADD {identifier-I}
1itera1-I

TO identifier-m QOUNDE~

[ON SI ZE ERROR imperati ve-statemen~

{identifier-2} [identifier-3]
1iteral-2
1iteral-3

GIVING identifier-m [ROUNDE'U

~dentifier-n [}OUNDED=1]

[ON SI ZE ERROR i mperati ve-s tatementJ

ADD {CORRESPONDING}
CORR
-

identifier-I TO identifier-2 rROUNDED]

L::

[ON SI ZE ERROR i mperati ve-statementJ

ALTER procedure-name-1 TO

~ROCEED TOJ

procedure-name-2

~procedure-name-3 TO ~ROCEED TO~ procedure-name-4 ]
CAL L

identifier-I ~
program- na me L~S I NG data -n ame-l
entry-name
.

[data-name-2]

~ON OVERFLOW imperative-statemen~

5-115

THE PROCEDURE DIVISION
GENERAL FORMAT FOR VERBS
i dent i fi er- 2J
[ s ubprogram-2

CANCEL ) i dent i fi er-l }
s ubpro gram-l

o~~i~ 8

{ LOCK
NO REWIND}}
DELETE

CLOSE file-name-l

ITH

REMOVAL

FOR

u~m~ {WITH

fi 1e··name-2

{ NO
LOCKREW I ND } }
DELETE
REMOVAL

FOR

I!ITH LOCK] ~i 1e-name-2

CLOSE fi 1e-name-l

COMPUTE identifier-l [ROUNDED]

...

~LJ arlthmetlc-expresslon
;~~~~!ii~r-2 .!, [fOUNDED]l~ ...

\ IS EQUAL TO
l :QUALS
\ arithmetic-expression

DELETE file-name RECORD

[WITH LOCK]]

[ON SIZE ERROR imperative-statement]

[jNVALID KEY imperative-statement]

~identifier-2 LJ···

identifier-:}
DISPLAY { literal-l
llliteral-2

5-116

.:lr7r
UPON mnemonlc-nam~~ITH NO ADVANCIN~

THE PROCEDURE DIVtSION
GENERAL FORMAT FOR VERBS
DIVIDE
-

t INTO identifier-2 rROUNDEDJ

identifier-I
{ literal-I
j

[identifier-3 [lOUNDEDJ]

01 VI DE

...

t INTO {i~entifier-2 t GIVING identifier-3 .IROUNDEDI

identifier-l
)
{ literal-l

~enti fi er-4 [ROUNDEi]]
DIVIDE

[ON SIZE ERROR imperative-statement]

identifier-I}
{ literal-l

REMAINDER identifier-4

i den t i fi e r-l }
{ literal-l
REMAINDER identifier-4

i denti fi er-2 }
{ literal-2

INTO
--

GIVING identifier-3

[JROUNDED~
II

{i~entifier-2}
llteral-2·

GIVING identifier-3 QOUNDEDI
U

[Jm SIZE ERROR imperative-statement]
BY
--

identifier-2}
{ literal-2

GIVING identifier-3 QOUNDEDl

:.J

C=ON SIZE ERROR imperative-statemen~

~~ING t
[us

~N SIZE ERROR imperative-statemen~

~ identifier-l

Y!ill ent ry- name

)

C=ON SIZE ERROR imperative-statemenf]

~entifier-4 [jOUNDEQ]
identifier-I}
{ literal-l

llteral-2

literal-l
(
procedure-name-l ,

I NG i dent ifi er-l

[J dent ifi e r- D

fill·

5-117

identifier-2
literal-2
procedure-name-2 J

TBE PROCEDURE DIVISION
GENERAL FORMAT FOR VERBS

RECORD [KI='Y
--~--

file-name-l

I i~entifier-l I] }
11teral-l

{ EVERY RECORD

FREE
[ ,fi le-name-2

{ RECORO [ KEY

identifier-2
1i tera 1-2

EVERY RECORD
EVERY RECORD

[NOT RETAINED statement-l
GENERATE

[,statement-2]

... ] ~

data -name }
{ report-name

GO TO procedure-name-l [procedure-name-2]

procedure-name-n

DEPENDING ON identifier

1£ condition

statement-l } ~
lELSE
{~ SENTENCE

INITIATE report-name-l

statement-2 }]
{tifll SENTENCE

[report-name-2]

5-118

I] }]

THE PROCEDURE DIVISION
GENERAL FORMAT FOR VERBS
INSPECT identifier-l TALLYING
INITIAL {i denti fi'er-4 11 }
fi denti fi er-2 FOR~ {{~~~DING} {~1~~~!f~ ~r-3}}BBEFORE}
)AFTER
1..:t1:eral-2
fJ ... 1
}

~ cHARACi'E RS

{

INSPECT identifier-l REPLACING
CHARACTERS BY {i~entifier-6} rJBEFORE}
llteral-4
\}AFTER

.:.:..;.:.;~:..:..=..:..:.;:. -

{

INITIAL

{i~entifier-7}1
llteral-5

{~~~DING}f{i~entifier.
-5} BY {i~entifier-6} ~{BEFORE} INITIAL {identifier-7\..]l
literal-5
f.)'"
{11teral-3
-- llteral-4
UAFTER

f
{FIRST

I }
...

INSPECT identifier-l TALLYING

identifier-2

{~1~~tira f~ tr - 3}}BBEFORE}
INITIAL {i dentifi er-411}
FOR~ {{~~~DING}
AFTER
literal-2
1] .,.
CHARACTERS
~

REPLACING
CHARACTERS BY {identifier-6} rJBEFORE}
literal-4
\}AFTER

INITIAL

{i~entifier-7}1
llteral-5

~{i
~enti fi er-5} -BY {i dentifi er-6} ~{BEFORE} INITIAL {identifier-7\..]l
literal-5
f.
{ ~~~DING}
FIRST
t llteral-3
literal.-4
UAFTER

{

MERGE

} KEY data-name-l
[WITH SEQUENCE CHECK] fil e-name-l ON {ASCENDING
DESCENDING

~...

[ON

{ASCENDING }
DESCENDING

KEY data-name-3

[
[

I}
. ..

data-name-2]

data-name-4]

. J.

~COLLATING SEQUENCE IS alPhabet-name~
USING fil e-name-2

fil e-name- 3

[fi 1e-name-4 ]
THROUGH
THRU

OUTPUT PROCEDURE IS section-name-l

section-name-2

GIVING file-name-5

'identifier-I}
MOV E (literal

MOVE

{CORRESPONDING}
CORR

TO 1°d en tOr
__
1 ler -2

[

identifier-3]

identifier-I TO identifier-2

5-119

January 1980

THE PROCEDURE DIVISION
GENERAL FORMAT FOR VERBS

MUL TIPL Y { ;

~~~;! i~ ~ r-l} .!l1 i dent ifi er- 2 [RO UN DE D]

[identifier-3 [ROUNDED]

MULTIPLY

{identifier-I} BY
literal-I
--

[ON SIZE ERROR imperative-statement]

[identifier-4 [ROUNDED]] •..

INPUT}
{.Q.UIPJlI

file-name-l

[ON SIZE ERROR imperative-statement]

REVERSED
[ with no rewind

{~UT-OUTPUT} file-name-3

GIVING identifier-3 [ROUNDED]

{identifier-2}
literal-2

.
[ fl1e-name-2

{!lli

[

EQR

[1lliJl {!illiTE
DELETE

DELETE }
ANY VERB

ALLOWING ~

REVERSED
[ WITH
NO REWIND

ANY VERB

READ
NONE
REWRITE
WRITE
DELETE
ANY VERB

1[ I I~
AriD

READ
NONE
REWRITE
WRITE
DELETE
ANY VERB

OPEN

[file_name_4

...EQR

[

REWRITE
REWRITE
BfAD.
} [ .8N.D. {READ
}] ...
WRITE
WRITE
QUill
{ DELETE
ANY VERB
ANY VERB

ALLOWING OTHERS

READ
.llilli.E.
~~~~~TE

...DlllIf..

1[ I I]
1lliJl

ANY VERB

file-name-5

[ fil e-name-6]

[ UNAVAILABLE statement-l

[statement-2]

[EXTEND]

...

READ

NONE
~~~~~TE

...

DELETE
ANY VERB

]

PERFORM procedure-name-I [ { ~~~~UGH

} procedure-name-2 ]

PERFORM pro cedure-name-I [ { i~ ~~UGH

} TIMES
} procedure-name-2 ] {identifier-I
integer-I

PERFORM procedure-narne-I [{ ~~~~UGH

} procedure-name-2 ] UNTIL condition-I
5-120

January 1980

THE PROCEDURE DIVISION
GENERAL FORMAT FOR VERBS

THROUGH } procedure-name-2 ]
PERFORM procedure-name-l [ { THRU

VARYING

[ AFTER

[AFTER

{~dentifier-2}
FROM
1 ndex-name-l
-identifier-4}
{1iteral-3

i dent i fi er- 3}
{ index-name-2
1itera1-1

UNTIL condition-l

fdenti fier-6}

index-name-3

dentifi er-5}

FROM

{i dentifi er-7}
1iteral-4

UNTIL

condition-2

tdentifier-s}
i ndex-name-5

FROM

i denti fi er-9
index-name-6
1iteral-5

{i dentifi er-lO}

UNTIL

COnditiOn-3]]

1iteral-6

READ fi 1 e-name

index-name-4
1 i tera 1- 3

[NEXT] RECORD

[INTO i denti fi erJ

[AT END imperative-statement]
READ file-name RECORD [INTO identifier] [INVALID KEY imperative-statement]
READ file-name RECORD [INTO identifier]
[KEY IS data-name]

~INVALID KEY imperative-statement]
RELEASE record-name [FROM i denti fi erJ

5-121

THE PROCEDURE DIVISION
GENERAL FORMAT FOR VERBS

RETAIN

FOR

file-name-l

RECORD

READ
REWRITE
READ-REWRITE
DELETE
WRITE

AND

ANY VERB

FOR

[ UNT IL FREED]

ANY VERB

RECORD

READ
REWRiTE
READ-REWRITE
DELETE
WRITE

[KEY

identifier-2}]
{ literal-2

AND

READ
REWRiTE
READ-REWRITE
DELETE
WRITE
REAi):"WRITE
ANY VERB

~WRITE

ANY VERB

[UNAVAILABLE

READ
REWRITE
READ-REWRITE
DELETE
WRITE

~WRITE

•fi le-name-2

identifier-I}]
{ literal-l

[KEY

statement-l

SEARCH identifier-l [ VARYING

[ UNTI L FREED]

[.statement-2]

· .• ] ..:.

identifier-2
~
{ index-name-l J LAT END lmperat~ve-statement-l

]

WHEN condition-l {im perative-statement-2 }
NEXT SENTENCE
perative-statement-3 }]
[ WHEN condition-2 {im
NEXT SENTENCE

SEARCH ALL identifier-l

[AT END imperative-statement-l]

{
{IS
EQUAL TO} {identifier-3
}}
Jdata-name-l
IS =
literal-l
WHEN )
arithmetic-expression-l
{ condition-name-l

[AND

data-name-2

{~~ :QUAL TO} {~1~~~!i~~r-4

1condition-name-2

}

arithmetic-expression-2

tJ
)

imperati ve-statement-2 }
{ NEXT SENTENCE
5-122

January 1980

THE PROCEDURE DIVISION
GENERAL FORMAT FOR VERBS

SET {~dentifier-l

[ i denti fi er-2 ]
[index-name-2 ]

lndex-name-l

i denti fi er-3 }
index-name-3.
{
integer-l

} TO
UP BY

} {identifier-4}

SET index-name-4

[index-name-S]

SORT file-name-l

{ASCENDING}
DESCENDING

KEY data-name-l

[ data-name-2]

[ON

{ASCEN 01 NG }
DESCENDING

KEY data-name-3

[ data-name-4]

{

•..

~BY

integer-2

. J.

[COLLATING SEQUENCE IS alPhabet-name]

NPUT PROCEDURE IS section-name-l

USING file-name-2

[{THROUGH}
THRU

secti on-name-2] }

[fi 1e-name- 3J

OUTPUT PROCEDURE IS section-name-3 [ rHROUGH}
THRU

section-name-4]

GIVING file-name-4

START fil e-name

{

l~ ~E:O

THAN}
IS >
IS NOT LESS THAN
IS NOT (

data-name

[INVALID KEY imperative-statement]
RUN
}
{ literal

STRING

{i~entifier-l}
[identifier-2l
llteral-l
literal-2 J

[{~~~~~!f~~r-4} [;1~~~!f~~r-5J

DELIMITED BY

{identifier- 3 l
1 i te r a1 - 3
(

'
l 51 ZE

~enti

i
fi er-6lJ
llteral-6
( ...

t SI ZE

)

INTO identifier-7 [WITH POINTER identifier-s]
[ON OVERFLOW imperative-statement]

5-123

January 1980

THE PROCEDURE DIVISION

GENERAL FORMAT FOR VERBS

SUBTRACT

{i~entifier-Il
llteral-I
f [i~entifier-2J
llteral-2

[:identifier-n [ROUNDED]:]

SUBTRACT

FROM identifier-m [ROUNDED]
- --

[ON SIZE ERROR imperative-statement]

{i~enti'fier-Il [i~entifier-21
llteral-I

000

llteral-2

i denti fi er-m}
{literal-m

GIVING identifier-n [ROUNDEI!] [i dentifier-o [ROUNDED

J] ...

r=ON SIZE error imperative-statement]

SUBTRACT

{~ESPONDING} identifier-l FROM identifier-2 [ROUNDED]

[ON SIZE ERROR imperative-statement]
TERMINATE report-name-I

[report-name-2]

UNSTRING identifier-l

[DELIMITED BY

[ ALL] {identifier-2}
1i teral-l

{i ~enti

OR [ALL]
f; er-3}]
llteral-2
[-

INTO identifier-4 [DELIMITER IN identifier-5][COUNT IN identifier-6]
[identifier-7 [DELIMITER IN identifier-a] [COUNT IN identifier-g]]

[WITH POINTER identifier-I~[TAL.J...YING IN identifier-II]
[ON OVERFLOW imperative-statement]

5-124

THE PROCEDURE DIVISION
GENERAL FORMAT FOR VERBS
file_name-I
INPUT
OUTPUT

1J,g,.8.E.ill STANDARD'~~~6~TIONt PROCEDURE ON

t--

OPE(fil e-name-2 ]OPEN ..

{ 1-0
EXTEND

USE BEFORE REPORTING identifier.

~ record-name [FROM identifier-I]

BEFOREl
AFTER j

ADVANCING

Jl]

i denti fi er-2 } [LINE
integer
LINES
{mnemOnic-name}
PAGE

~AT {~-OF-PAGE} imperative-statement:]
WRITE record-name [FROM; dent; f; erJ [INVALI D KEY i mperat i ve-s tatementJ

5-125

CHAPTER 6
COMPILER COMMAND STRINGS

The general form of the compiler command string is as follows:
relfil,lstfil= libfil/l, srcl,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 the optional library file
verbs in the source files.

referenced

COpy

srcl,src2

are one or more source files required to form
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.

file

is the name of a file.
The name
is
of 6 or fewer letters and/or digits.

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.

6-1

composed
of

COMPILER COMMAND STRINGS
Users of TOPS-20 who wish to specify a directory other than
the default may 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 E,
Defining
Logical Names under TOPS-20.
Certain default assignments are made by the compiler whenever
terms are omitted from the command strings or the file
descriptions.
1.

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 is omitted,
filename of the first source file is used.

If the filename extension is omitted from relfil, .REL is
assumed;
if it is omitted from Istfil, .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 .COB.
If that file is not
found,
the compiler looks for the named file with the
extension .CBL.
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,
the user's default path is used.
On TOPS-20, the
connected directory is used.

the

Examples:
MTAl: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).
-=LIBl/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.

6-2

COMPILER COMMAND STRINGS
Table 6-1
COBOL Switch Summary
Switch

Action by Compiler

~------------------+--------------------------------------------------------

List the machine code generated in the Istfil.

Generate code for all DEBUG lines (those with /D
in col.
7) which otherwise would be treated as
comments.

Produce
a
cross-reference
user-defined symbols.

D:nnnnnn

Increment, in octal words, to be
object time push down list size.

added

Check program for errors, but
code.

not

Type description of COBOL-74 command strings and
switches.

Suppress output of start address
be used only by CALL's).

(program is

Force output of start address in
presence of subprogram syntax.

spite

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 of the user defined items
lstfil.

Do not type compilation
terminal.

the

user's

Optimize the object code.

Production mode.
relfil.

Omit debugging

features

from

Quick mode.
Do .not range check
turn on /0 and /P.

PERFORMs,

also

Produce a two-segment object program.
The high
segment will contain the procedure division;
the low segment all else.

The source file
is in "conventional"
format
(with
sequence
numbers
in cols.
1-6 and
comments starting in col.
73).

Produce a one-segment object program.

6-3

table

errors

all

the

generate

the

COMPILER COMMAND STRINGS
Table 6-1 (Cont.)
COBOL Switch Summary
Switch

Action by Compiler

Rewind the device
(magtape only).

Give a usage of DISPLAY-9 to items whose
is either omitted or declared as DISPLAY.

Flag DIGITAL extensions to ANS-74 standard.

Zero the directory of the device before
(DECtape only).

6-4

before

reading

writing
usage

writing

CHAPTER 7
COBOL-74 UTILITY PROGRAMS

COBOL-74 provides several utility programs that allow you to perform
certain operations within your COBOL program. These utility programs
are:
•

lSAM

- 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
COBODT 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-74 Programs
RERUN provides you with the ability to restart a
COBOL-74 program after an abnormal termination has
occurted (See Section 7.4).

7-1

COBOL-74 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 may substitute
.R (program name) <RET>
for
@(program name) <RET>
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 ari indexed-sequential file by reorganizing it

Packs an indexed-sequential file into a sequential
backup storage

ISAM has the following switches which you may
functions:

use

file

for

perform

these

Build an indexed file from a sequential one

Ignore errors in packing a file (this switch may only be
with the P switch)

used

Read or write standard tape labels (this switch
used with the B or P switches)

may

M Maintain your indexed file by reorganizing it
P

Pack your indexed file for backup storage
Figure 7-1 shows the COBOL-74 ISAM File Environment.

7-2

only

COBOL-74 UTILITY PROGRAMS
(INPUT SEOUENTIAL
DATA FILE)

R ISAM

(BUILD)

R ISAM
RUN
MYPROG

(MAINTAIN)

(USER'S APPLICATIQN PROGRAM)

f:::\ _
~

"'SA"

(PACK)

(OUTPUT SEQUENTIAL
BACKUP FILE)
MR-S-029·79

Figure 7.... 1

COBOL-74 ISAM File Environment

7-3

COBOL-74 UTILITY PROGRAMS
Building an Indexed-Sequential File

7.1.1

To build an indexed-sequential file you must provide a sequential file
in which the record keys are arranged in ascending order. The ISAM
program will use 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:

for

building

the

.R ISAM<RET) for users of TOPS-IO
or
@ISAM~RET)

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.
datfil.ext is the name and extension of the 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.
[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 may 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 E, Defining Logical Names under TOPS-20.
/B is the switch signifying that ISAM will be 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.
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 Sf 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.

7-4

COBOL-74 UTILITY PROGRAMS
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 will be converted in the same manner
as they are converted in standard COBOL-74 operations.
MAXIMUM RECORD SIZE:
Specify the size of the largest record in 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
that has the form:

code

specifies the number of the character in the record where
key begins.

the

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.

[s]

indexed

using

[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

The following rules apply to the key descriptor:
1.

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.

7-5

cannot

specified

the

key

type

specified

COBOL-74 UTILITY PROGRAMS
RECORDS PER INPUT BLOCK:

Give the blocking factor of the input file.
o should be specified.

If the file is unblocked,

TOTAL RECORDS PER DATA BLOCK:

Give the total number of records to be contained in each block of
data file.

the

EMPTY RECORDS PER DATA BLOCK:

Specify the number of records that are to be initially left
each block of the data file.

empty

each

TOTAL ENTRIES PER INDEX BLOCK:

Specify the total number of index entries
block of the index file.

contained

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 must equal or exceed two.
PERCENTAGE OF DATA FILE TO LEAVE EMPTY:

Give, as a percentage of the total number of blocks,
blocks to be initially left empty in the data file.

the

number

the

number

PERCENTAGE OF INDEX FILE TO LEAVE EMPTY:

Give, as a percentage of the total number of blocks,
blocks to be initially left empty in the index file.
MAXIMUM NUMBER OF RECORDS FILE CAN BECOME:

Reply with the maximum number of records that the data file can
possess before the file is next maintained. This number sets the
upper limit of the size of the data file.
It is required because
storage allocation tables must be set up in the index when the file is
created. There is no harm in making this number excessively large
because the index data blocks are allocated in the storage allocation·
tables, but not actually assigned until needed.
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: 40
KEY DESCRIPTOR: SN37.4

(The key is signed numeric display; it begins in the
thirty-seventh byte; and it is four bytes long.)
RECORDS PER INPUT BLOCK: 3
TOTAL RECORDS PER DATA BLOCK: 2
EMPTY RECORDS PER DATA BLOCK: 1
TOTAL ENTRIES PER INDEX BLOCK: 3
EMPTY ENTRIES PER INDEX BLOCK: 1
PERCENTAGE OF DATA FILE TO LEAVE EMPTY: 60
PERCENTAGE OF INDEX FILE TO LEAVE EMPTY: 10
MAXIMUM NUMBER OF RECORDS FILE CAN BECOME: 12000
7-6

COBOL-74 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 may be added to the
file and the number of index levels may 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<RET> for users of TOPS-IO
or
@ISAM<RET> for users of TOPS-20
*devl:indfil.ext[ppnl] ,dev2:datfil.ext=infil.ext[ppn2]/M<RET>
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 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
may
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 E, Defining Logical Names
under TOPS-20.
/M 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-7

COBOL-74 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
of the index file.

each

block

initially

left

EMPTY ENTRIES PER INDEX BLOCK (n):
Specify the number of index entries that
empty in each index block.

are

PERCENTAGE OF DATA FILE TO LEAVE EMPTY (n):
Give, as a percentage of the total number of blocks,
blocks to be initially left empty in the data file.

the

number

the

number

PERCENTAGE OF INDEX FILE TO LEAVE EMPTY (n):
Give, as a percentage of the total number of blocks,
blocks to be initially left empty in the index file.
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.
Example - Maintaining an indexed-sequential file
.R ISAM(RET)
*test.idx, test.ida=test 1m
total records per data block (2):
empty records per data block (1):
total entries per index block (3): 32
empty entries per index block (1): 10
percentage of data file to leave empty (60): 50
percentage of index file to leave empty (10): 40
maximum number of records file can become (12000)

7-8

25000

COBOL-74 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.
The
command string for the packing -option of ISAM is as follows:
.R ISAM<RET> for users of TOPS-IO
or
@ISAM<RET> for users of TOPS-20
*devl:seqfil.ext[ppnl]=dev2:indfil.ext[ppn2] IP<RET>
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 may 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 E, 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, rSAM asks
questions.

the

following

MODE OF THE 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:
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, the user answers O.

7-9

COBOL-74 UTILITY PROGRAMS
Example - Packing an indexed-sequential file
.R ISAM
*MTA2:TEST.SEQ=TEST.IDX IP
MODE OF THE OUTPUT FILE: SIXBIT
RECORDS PER OUTPUT BLOCK: 0

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 (7) so that ISAM will
continue the packing operation. The II switch can be used only with
the IP switch. It cannot be used alone.
The command string when using the

II and IP switches is as follows:

.R ISAM<RET) for users of TOPS-IO
or
@ISAM<RET) for users of TOPS-20
*devl:seqfil.ext[ppnl]=dev2:indfil.ext[ppn2]/P/I<RET)
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.
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 may 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 E, Defining Logical Names under TOPS-20.

7-10

COBOL~74

UTILITY PROGRAMS

IP is the switch signifying that
requested.

the

packing

option

/1 is the switch signifying that some fatal errors are
ignored. It may be included only with the /P 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 building or packing an indexed-sequential file, you can include
the /L switch to cause ISAM to read or write labels on magnetic tape.
The /L switch, when used with the /B switch, causes ISAM to read
COBOL-74 standard tape labels on the input magnetic tape. When used
with the /P switch, the /L switch causes ISAM to write standard tape
labels on the output magnetic tape. The /L switch can only be used on
magnetic tape files whose recording mode is not F or V.
The command string when using the /L switch with the /B switch
follows:

.R lSAM<RET> for users of TOPS-IO
or
@ISAM<RET> for users of TOPS-20
*devl:indfil.ext[ppn] ,dev2:datfil.ext=MTAn:seqfil.ext/B/L<RET>
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, .lDX is assumed.
datfil.ext is the name and extension of the 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 spe~ified, 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 may 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 E, Defining Logical Names
under TOPS-20.
/B is the switch signifying that ISAM will be used to build an
indexed-sequential file.
If the switch is omitted from the
command string, /B is assumed.

7-11

COBOL-74 UTILITY PROGRAMS
/L is the switch signifying that ISAM
labels. It must be included.

will

read

standard

The equal sign (=) can be omitted if the file specifications
output files are also omitted.

tape

for

the

The command string when using the /L switch with the /P switch
follows:
.R ISAM<RET> for users of TOPS-IO
or
@ISAM<RET> for users of TOPS-20
*MTAn:seqfil.ext=devl:indfil.ext[ppn]/P/L<RET>
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 extension 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 may 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 E, Defining Logical Names under TOPS-20.
/P is the switch signifying that
requested. It must be included.

the

packing

being

write

standard

tape

The ISAM program accepts command strings and dialogue
indirect command files.

responses

from

/L is the switch signifying that ISAM will
labels. It must be included.

7.1.6

option

Indirect Commands

The command string to direct ISAM to read an indirect command file is:
.R ISAM<RET> for users of TOPS-IO
or
@TSAM<RET> for users of TOPS-20
*@dev:cmdfil.ext[ppn]<RET>

7-12

COBOL-74 UTILITY PROGRAMS
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.
[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 may 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 E,
Defining Logical Names
under TOPS-20.
After ISAM reads the command string, it reads the command file and
performs the processing 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.7

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.
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
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
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).

PROCEDURE DIVISION.
BEGIN.
OPEN INPUT-OUTPUT ISAM-FILE.

7-13

COBOL-74 UTILITY PROGRAMS
7.

READ ISAM-FILE, INVALID KEY GO TO ERRPROC.

WRITE ISAM-RECORD, INVALID KEY GO TO ERRPROC.

DELETE ISAM-RECORD, INVALID KEY GO TO ERRPROC.

10.
11.

REWRITE ISAM-RECORD, INVALID KEY GO TO ERRPROC.
READ ISAM-FILE NEXT RECORD, 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 ORGANIZATION clause is required.

The ACCESS MODE clause is required if you wish to access the
file in random fashion, since the ACCESS MODE defaults to
sequential. When DYNAMIC is specified, as here, either
random or sequential access may take place.

The RECORD KEY clause is required in the Environment Division
and refers to the data-item designated as the record key
which appears in the Data Division within the FD area record
description for the indexed-sequential file.

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-14

COBOL-74 UTILITY PROGRAMS
11.

7.2

This shows the method used to read an indexed-sequential file
sequentially.
When the READ statement is executed, the
record accessed is the first record whose record key has a
value higher than the last record processed by a READ, WRITE,
REWRITE or DELETE statement. If the file has been opened but
no
READ, WRITE, DELETE or REWRITE statement has been
executed, the first record of the file is read.

LIBARY - SOURCE LIBRARY MAINTENANCE PROGRAM

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 lines or whole
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 Part 2, Section 1.4, for
information on the COpy verb.)

7.2.1

Library File Format

A library file is a collection of COBOL source-language statement
groups, each identified by a unique 1- to 8-character library-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 binary format that is recognizable only by
LIBARY and the COBOL compiler.
You, however, need not concern
yourself with the format of the actual entries in the file. You enter
them as ASCII text;
LIBARY stores them in the appropriate format
automatically.

7.2.2

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<RET> for users of TOPS-IO
or
@LIBARY<RET> for users of TOPS-20

7-15

COBOL-74 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. Enter the file
specification command line according to the following format:
*output-library,listing=input-library<RET>
where:
output-library - is the file specification for the
being generated.

library

listing

- is the file specification for the file
to receive the output listing.

input-library

- is the file specification for the
being used as input.

that

library

file
is
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
may
run the TRANSLATE program to
determine the correct project-programmer numbere
(See the TOPS-20 User's Guide for information on
how to do this.) For an alternative which is
generally more useful, see Appendix E, Defining
Logical Names under TOPS-20.

/sw

- is one ASCII character preceded
specifying a LIBARY switch option.
7.2.4, LIBARY Switches.)

by a slash
(See Section

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.4,
LIBARY Directing Commands), LIBARY renames the scratch file with the
proper output name (after any necessary renaming of the input file).

7-16

COBOL-74 UTILITY PROGRAMS
If an error occurs causing the execution of LIBARY to be aborted,
the
input file, if specified, will be unchanged and the scratch file will
be 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 will be 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.

file

omitted,

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 IL switch must be specified.
6.

If the name of the output file is omitted, the
input file is assumed.

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 ~or 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 may 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 E, 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.

the

output

input

7-17

file

name

the

omitted,

.LIB

omitted,

.LIB

COBOL-74 UTILITY PROGRAMS
7.2.4

LIBARY Switches

The following switches can
LIBARY.

included

the

command

string

/D - List on the user terminal all of the library-names contained
on the input library file.
/H - List on the user terminal all of the commands available with
LIBARY.
/L - Create only a listing file of the entire input library.
output file specification must be omitted.

The

/S - Put the input statement group into conventional format.
/W - Rewind (for magnetic tape only).
/Z - Clear an output directory (for DECtape only).

7.2.5

Running LIBARY

Running LIBARY consists of specifying commands in response to the
LIBARY asterisk prompting character (*). 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 will keep you from having to restart LIBARY and reprocess your
file.
LIBARY is organized so that you can optionally create new library
files, insert or delete statement groups into an existing file, or
make line-by-line changes to an existing file.
It has, therefore, two
major modes of operation:
group mode or edit mode. Group mode
provides a means of inserting, replacing, extracting, and d~leting
entire statement groups; edit mode provides a means of inserting new
lines or deleting or modifying existing ones.
NOTE
Edit mode in LIBARY acts as a text
editor for the library. However, this
editor is not as powerful or as useful
as the text editors provided with the
operating system (such as TECO
and
EDIT) .
LIBARY edit mode is there for
historical reasons and its use is not
recommended.

7-18

COBOL-74 UTILITY PROGRAMS
7.2.6

LIBARY Commands

The following sections describe the commands available with
LIBARY commands are divided into three classes of commands:
•

Group mode

(See Section 7.2.6.1)

•

Edit mode

(See Section 7.2.6.2)

•

LIBARY-directing

(See Section 7.2.6.4)

These commands may be abbreviated as
abbreviation.

long

you

supply

LIBARY.

unique

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

NOTE
For the remainder of this chapter, the
words "line number" refer to the line
numbers generated by a system standard
editor;
the words "COBOL line number"
refer to the conventional line numbers
as described in Part 2, Section 1.3,
Source Program Format.
DELETE, library-name
Delete the statement group identified by library-name from the
library file.
The library-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-name.
When library-name is
reached, LIBARY positions itself at the next sequential library
entry and waits for another command.
EXTRACT, library-name, file-specification
Extract the complete library entry specified by library-name from
the input library file and generate a new file named file-name.
LIBARY searches the input library file for the library entry
specified by library-name.
When library-name is found, it
creates a file or overwrites an existing file with the attributes
specified by file-name and copies the library entry onto it. The
input library file remains unchanged.
INSERT, library-name, file-specification
Insert the statement group contained on the file specified by
file-name into the output library file. The statement group is
inserted alphabetically according to the name specified by
library-name.
The file specified by file-name must be an ASCII
file. LIBARY assumes that the entire file is to be inserted
under library-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

7-19

COBOL-74 UTILITY PROGRAMS
by 10. If the library entry being inserted contains COBOL line
numbers, the /S switch must be specified.
(See Section 7.2.4,
LIBARY Switches.)
REPLACE, library-name, file-specification
Replace the library entry identified by library-name with the
statement group contained on the file specified by file-name.
The file specified by file-name must be an ASCII file.
LIBARY
assumes that the entire file is to replace the statements
currently associated with library-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 Edit Mode Commands - Edit mode commands allow you to create a
library file or modify an existing one with line-by-line edits from
your terminal. To edit your file, you must first specify one of the
following commands to enter edit mode; after which, you can enter an
appropriate edit command to affect the actual editing you wish to
perform:
CORRECT, library-name
positions LIBARY to the group of statements specified
by
library-name and enters edit mode. Any of the commands described
in Section 7.2.6.3, Edit Commands, can be entered at this time.
If the /N switch is specified, LIBARY puts new line numbers on
the output (corrected) statements.
(See Section 7.2.4, LIBARY
Swi tches. )
INSERT, library-name
Positions LIBARY at the place in the library file that the
specified library-name will be inserted.
It then enters edit
mode and waits for you to enter statements that will compose the
module. The I command, described in Section 7.2.6.3, is used for
this purpose.
REPLACE, library-name
Positions LIBARY at the statement group specified by library-name
and deletes it.
It then enters edit mode and waits for you to
insert source lines by means of the I command.
(See Section
7.2.6.3, Edit Commands.)

7.2.6.3 Edit Commands - The commands given in this section allow you
to insert, delete, and replace individual source lines in a statement
group. Source lines should be edited in numeric order within a
statement group because LIBARY can only move forward in the file. The
following edit commands are provided:
Dnnnnnn
Delete the line specified by nnnnnn.
The line number can be
entered without leading zeros. That is, you need not enter six
characters unless there are that many characters actually in the
line number.
7-20

COBOL-74 UTILITY PROGRAMS
Innnnnn COBOL statement
Insert the COBOL statement into the statement group according to
the line number specified by nnnnnn. The line number can be
entered without leading zeroS. A space or tab must be included
between the line number and the COBOL statement; the space will
not be included in the statement, but the tab will.
Rnnnnnn COBOL-statement
Replace the source line identified by nnnnnn with the specified
COBOL-statement.
The line number can be entered without leading
zeros. A space or tab must be included between the line number
and the statement;
the space will not be included in the
statement, but the tab will.

7.2.6.4 LIBARY-Directing Commands - LIBARY-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.
RESTART
Copy any remalnlng statement groups from the input to the output
files,
close both the input and output files, rename the input
file with the extension .BAK, and reopen the output file as the
new input. Any changes made prior to issuing the RESTART command
are in the new input file.
NOTE
LIBARY maintains source
modules
in
ascending order.
Line numbers within
modules are also in ascending order.
If
you want to go back in processing to a
line previously passed, use the RESTART
command.

7.2.6.5 Example of Command Usage - A library on disk contains the
routines PAYCOMP, FIND-MP, and MP-DESCR. This example shows you how
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.
7-21

COBOL-74 UTILITY PROGRAMS
The dialogue at the terminal might appear as follows:
.R LIBARY
*LIBARY.NEW=LIBARY.OLD
*INSERT
JOB-DESC
*110
LABEL RECORDS ARE STANDARD;
*120
VALUE OF ID IS "JOBS DAT";
*130
DATA RECORD IS JOB-RECORD.
*CORRECT
MP-DESCR/N
*15
BLOCK CONTAINS 5 RECORDS
*DELETE
PAYCOMP
*END
The file LIBARY.NEW now contains the following:
1.

FIND-MP

JOB-DESC

MP-DESCR, altered to appear as follows:
000010
BLOCK CONTAINS 5 RECORDS
000020
LABEL RECORDS ARE OMITTED
000030
DATA RECORD IS MP-RECORD.

To insert one or more files in a library, you can issue the
commands to LIBARY .

following

. R LIBARY
*ALIB,ALIB=
*INSERT AFIL,AFIL
*INSERT BFIL,BFIL
*END

The file ALIB.LIB contains two statement groups (AFIL
the file ALIB.LST contains the following information.
A F I L
000010

B F I L
000010

7.3

COBOL LIBRARY

and

BFIL)

01-DEC-78

09:52

01-DEC-78

09:52

and

DISPLAY "A".

COBOL LIBRARY
DIS P LA Y " 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:
1.

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

7-22

programs

COBOL-74 UTILITY PROGRAMS
5.

Trace paragraphs and sections

Obtain a histogram of paragraphs
behavior

Interrupt a running program

executed

show

program

7.3.1 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 the user symbols that
are used by COBDDT.
Therefore, you must
not use
the IP switch when compiling
your program, if you wish to use COBDDT.
the monitor
You can load the compiled source program with either
In both cases, LINK loads
command LOAD or direct commands to LINK.
the user symbols along with the program.
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 COBDDT 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
extensiori.
However, if the extension of the source file is
something
other
than
.CBL,
you must use
the ICOBOL switch with the DEBUG
command.
Otherwise the file is not recognized as a COBOL file.
When
you load COBDDT with the user 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
I"LOCALS" switch, as TOPS-20 loads local symbols by default.
1.

.LOAD %"LOCALS" file spec, SYS:COBDDT
. START

.DEBUG file spec

.R LINK
*/LOCALS file spec, SYS:COBDDT IGO
. START

[/COBOL]

When the program is started with the START command, COBDDT is entered.
This is shown by the message:

STARTING COBOL DDT

Version 12A

7-23

January 1980

COBOL-74 UTILITY PROGRAMS
You can now issue any COBDDT command (described below).
If you want
to run your program at this time, enter the PROCEED command. This
will cause 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.
COB DDT
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:

This will cause 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 will be
reentered at its original address.

7.3.2 COBDDT Commands

The commands to COBnDT 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 may be qualified by section-names,
and data-names may 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 COBnDT uses the names in the program specified
in the MODULE command.

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.

Version 12A

7-24

January 1980

COBOL-74 UTILITY PROGRAMS
Example:

*ACCEPT VARI
16.25

*
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 set in a program. Breakpoints cannot
be set in the high segment of a reentrant program on TOPS-IO.
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:
*BREAK PARI

*
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:
*CLEAR PARI

Version 12A

7-25

January 1980

COBOL-74 UTILITY PROGRAMS
DDT
The DDT COBDDT command causes an entry to be made to DDT,
the
assembly language debugger.
COBDDT can supply only certain types
of data;
the use of the DDT COBDDT 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 COBDDT 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 COBDDT command to look at
these areas.
The DDT COBDDT 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 use the POPJ
17,
X statement.
The DDT COBDDT command does not cause the assembly language
debugger
to be loaded,
therefore you must load the assembry
language debugger before you begin the debugging session.
This example shows the use of the DDT COBDDT command on TOPS-IO.
Although
the system prompt differs on TOPS-20, the use of the
command is the same on both systems.
Example:
.GET PRGRM
.DDT
DDT

$G
STARTING COBOL DDT
*DDT
[Return from DDT by typing "POPJ 17,
DDT

DISPLAY
The DISPLAY command causes the contents of a data item to be
displayed on
the user's terminal.
The DISPLAY command has the
format:
DISPLAY
DISPLAY data-name
If no data-name is specified, COB DDT uses
specified in an ACCEPT or DISPLAY command.

version 12A

7-26

the

last

data-name

January 1980

COBOL-74 UTILITY PROGRAMS
Example:
*DISPLAY ALPHA

*
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 the 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.
not
Therefore further execution of the object program is
possible.
Example:
*GO PARAl
BREAK AT «PARA4»

*
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:
*LOCATE PARAl
401057

Version 12A

7-26.1

January 1980

C.OBOL-74 UTILITY PROGRAMS
MODULE
The MODULE command causes COBDDT to look for data names and
The MODULE command has
procedure names in the specified program.
the format:
MODULE [program-name]
If the name is omitted, COBDDT 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 will
take place. All subsequent searches for data names
and procedure names will be 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:
*MODULE
CURRENT MODULE:

MYPROG

*
NEXT
The NEXT command causes the contents of a data item to be
displayed on the user's 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 va~ue 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
slgn.
If you specify a subscript that is out of range, an error
message is displayed.
Example:
*NEXT 3
33

*
OVERLAY
The OVERLAY command either causes a break when an overlay is
entered or clears the breakpoint.
The OVERLAY command has the
format:
OVERLAY ON
OVERLAY OFF
Version 12A

7-26.2

January 1980

COBOL-74 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 COB DDT 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 1 is equivalent to PROCEED.
Example:
*PROCEED 3
BREAK AT «PARA3»

*
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 the preceding breakpoint 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 display then occurs:
STEP AT

procedure-name
program-name

EXIT PROGRAM

Version 12A

7-26.3

January 1980

COBOL-74 UTILITY PROGRAMr
Modules that have been compiled with the IP switch are invisible
to the STEP program. The entry point, the procedure names and
the exit programs are not counted as steps.
Example:
*STEP 2
BREAK AT «PARA2»

*
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 full.
Typing only
letter, S, initiates execution of the STEP command.

the

first

Example:
*STOP
EXIT

TRACE
The TRACE command starts tracing,
backwards, depending on the form
command has the format:

stops tracing, or
traces
The TRACE
of the command.

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 the user's
terminal.
For each depth of subprogram, COBDDT types an exclamation point
(!)
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:
*TRACE ON
!!*!**<PARA>

*
When a LINK overlay is brought into memory, COB DDT types the
names of any modules overlaid and the names of the modules in the
new overlay.
When a LINK overlay is cancelled, COB DDT types the
names of the modules in that overlay.
version 12A

7-26.4

January 1980

COBOL-74 UTILITY PROGRAMS
TRACE OFF causes COB DDT to stop tracing procedures until either
execution is terminated or another TRACE ON command is executed.
Example:
*TRACE OFF

*
TRACE BACK causes COB DDT 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:
*TRACE BACK
IN PROGRAM [SAMPLE]

*
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:
*WHERE
PROGRAM STOPPED AT «PARAl»
BREAKPOINTS:
«PARAl»
«PARA2»
«PARA3»
17 UNUSED BREAKPOINTS

*
7.3.3 Obtaining Histograms of Program Behavior
The histogram facility in COB DDT 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.
version l2A

7-27

January 1980

COBOL-74 UTILITY PROGRAMS
7.3.3.1 Initializing the Histogram Table - The
HISTORY
INITIALIZE
command causes COBDDT to set up and initialize the histogram table in
whi£h 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,
the user's 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 may 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 E, Defining Logical Names
under TOPS-2Q.
The title is the one that will be 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,
the user's 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 may 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 E, Defining Logical Names
under TOPS-20.
The title is the one that will be 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

7-28

COBOL-74 UTILITY PROGRAMS
started.
If a histogram already exists, HISTORY BEGIN will
to that histogram. The statistics collected are:

add

data

The number of times each paragraph or section is entered
The CPU time spent within each paragraph or section
The elapsed time spent within each paragraph or section
The elapsed time and CPU time for overhead
The elapsed time and CPU time that is unaccounted for
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
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
program 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 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
of
the
output
histogram
report
(dev:file.ext[p,pn]). If the entire file specification is omitted,
the user 1 s 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 may 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 E, Defining Logical Names
under TOPS-20.
The title is the one that will be 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-29

REPORT: integer-l

CPU
time-l
time-3
CPU:time-6
CPU:time-8

ELAPSED
time-2
time-4

COBOL-74 UTILITY PROGRAMS
module-name

is the name of the
PROGRAM ID clause.

integer-l

is the report number. It starts at I and is
incremented by I for each report produced in
a run.

title

is the. title that the user specified
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

one

passed

If control is never passed to a particular section or paragraph,
nothing is printed for that section or paragraph. When a PERFORM
statement or subprogram is entered, the current paragraph or section
is saved on a stack so that COSDDT 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-30

COBOL-74 UTILITY PROGRAMS
A sample histogram report is shown below.
REPORT:

COBDDT HISTOGRAM FOR CASHX
PROCEDURE

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 will continue 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 will be 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-74 PROGRAMS

The RERUN program is used to restart a COBOL program that has been
terminated abnormally due to a system failure, a device error, or an
exceeded disk quota.
RERUN uses checkpoint files, which are similar
to memory-image dump files.
They are created in one of two ways:
•

By including RERUN statement(s) in the COBOL program itself

•

By typing CTRL/C twice
execution

followed

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, however,
if any files are open for
input/output
(updating),
if an indexed-sequential file is open when
the dump is requested, or if a sort is in progress.
Each time the
checkpoint file is written, the COBOL system types the message DUMP
COMPLETED on the user's terminal.
7-31

COBOL-74 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 may respond RERUN). For example:
.R RERUN<RET> for users of TOPS-IO
or
@RERUN<RET> for users of TOPS-20
The program responds with the message:
TYPE CHECKPOINT FILENAME
Type the name of the checkpoint file in which the core-image
stored.

dump

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 a logical device name is encountered in the
the following message:

program,

RERUN

types

ASSIGN device name
TYPE CONTINUE WHEN DONE
and exits to monitor command level. The appropriate ASSIGN command
should be given to assign the logical device to a specific one. Then
a CONTINUE rrconitor command will reenter RERUN.

7-32

COBOL-74 UTILITY PROGRAMS
7.4.2

Examples of Using RERUN

In the following example, the user has 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,
the user employs the
RERUN program to restart his program from the last checkpoint written
before the program stopped.
He types:
.R RERUN<RET>
and RERUN responds:
TYPE CHECKPOINT FILENAME
The user types:
ACCNT.CKP<RET>
RERUN loads the checkpoint 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, a user running a COBOL program is notified that
the system is going down.
He does not have any RERUN statements in
his program, yet he wishes to create a checkpoint file so that the
processing done by his COBOL program up to that point is not wasted.
He creates 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 PROG13 (taken from the PROGRAM-ID) and an extension
of
.CKP.
After the system is restored, the user can restart the
program by running the RERUN program.
The dialogue is as follows:
@RERUN<RET>
TYPE CHECKPOINT FILENAME
PROG13.CKP<RET>
The program PROGl3 is loaded into memory, its files are reopened,
it continues running to completion.

7-33

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
SIXBIT
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.

ASCII RECORplNG MODE

BIT NUMBER

0 1 234 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

BINARY
•
REPRESENTATION- -

000

DATA

o • o • •

• •

•

• •

•

• • X

BYTES: 5
•

= on bit

o
X

= unused bit

= off bit
MR.S·030.79

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:
SIXBIT RECORDING MODE

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 - -

a a a a • a • a a a

DATA

• • a a a • a a • a a • a • a a a • • a • a a • •

BYTES: 6
•

on bit
off bit

MR 5·031 79

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:
EBCDIC RECORDING MODE

BIT NU MBER---- 0

1 234 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

a a a • X •

• • • a a a • X • • • a a a • a X • • • • a a • a

BYTES: 4
•

on bit

a = off bit
X = unused bit

MR·5032·79

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:
INDUSTRY·COMPATIBLE EBCDIC RECORDING MODE

BIT NU 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
REPRE SENTATION
DATA

-- . • •
.

a a a a ••
A

• • • a a a • • • • a a a • a • • • • a a •
B

BYTES: 4
•

= on bit

= off bit

MR·S.Q33·79

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:
BINARY RECORDING MODE

BIT NU M B E R - O 1 234 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

BYTES: 1

• = on bit

MR-S-034-79

o = off bit

Figure 8-5 Binary Recording Mode
This is the only wayan ASCII file can be read preserving nulls.

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:

MR-S-1364-81

Binary data in a word (fixed- and floating-point numbers)
shown by a number in the word:
132156. 10

MR-S-1365-81

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 l234N, 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:

8-3

they

FILE FORMATS

RDW301

MR-S-1366-B1

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:

MR-S-1367-B1

~ ~ I~ ,31 11
5 9

MR-S-136B-B1

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 5 characters
left-justified within the word. Fixed-length ASCII records must end
with a carriage-return/line feed.
Depending upon the method in which
the records are written to a file,
fixed-length ASCII records are
written as follows:
1.

With the BEFORE ADVANCING clause of the WRITE statement, a
carriage-return/line feed
is inserted at the end of each
record.

With the AFTER ADVANCING/AFTER POSITIONING clauses of the
WRITE statement, a carriage-return/line feed is inserted at
the beginning of each record, and a carriage-return is
inserted after the last record of the file.

The following diagram illustrates the
records:

format

WORD

ASCII

RECORD

·6

G!D

fixed-length

I
4

GO
G!D
GD

CARRIAGE RETURN
LINE FEED
MR-S-035-79

Figure 8-6:

Fixed-Length ASCII

8-4

October 1985

FILE FORMATS
CODg 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 FIL".
DISPLAY-7.
PIC X(6) VALUE "AB12EF".
PIC A(3) VALUE "GHI".
PIC 9(4) VALUE 3249.
PIC S9(6) VALUE -481253.
PIC S9(6)V9999 VALUE +31458.5012.

Figure 8-7 illustrates the record produced by the code
above:

segment

shown

WORD

C§)

GO
MR-S-036-79

Figure 8-7:

COBOL Fixed-Length ASCII with BEFORE ADVANCING

If the WRITE statement for record-l had the AFTER ADVANCING clause,
the record produced by the code segment shown above would appear as:
WORD

ru (IT)

4 I 4

ru
MR-S-3095-83

Figure 8-8:

COBOL Fixed-Length ASCII with AFTER ADVANCING

8-5

October 1985

FILE FORMATS
8.2.2

Variable-Length ASCII

Variable-length ASCII consists of records containing five characters
per 36-bit word, with each group of 5 characters left-justified within
the word. Depending upon the method in which the records are written
to a file, variable-length ASCII records are written as follows:
1.

With the BEFORE ADVANCING clause of the WRITE statement, a
carriage-return/line feed is inserted at the end of each
record.

The following diagram illustrates the format of variable-length
records:

GD GQ

C2Q

ASCII

GD GQ
GD = CARRIAGE RETURN

= VERTICAL TAB

G:)

= LINE FEED

C!D = FORM FEED

MR-S-037-79

Figure 8-9:

Variable-Length ASCII

8-6

October 1985

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

VALUE OF ID "DATA FIL".
DISPLAY-7.
PIC X(7) VALUE "AB1352l".
PIC S9(7)V99 VALUE -3269.02.
PIC A(3) VALUE "ILM".
PIC 9(4) VALUE 1359.

01 record-2
02 field-l
02 field-2
02 field-3
02 field-4

DISPLAY-7.
PIC X(7) VALUE "EFGHI95".
PIC S9(7)V99 VALUE 42553.40.
PIC A(3) VALUE "LMN".
PIC 9(7) VALUE 3712536.

PROCEDURE DIVISION.
WRITE record-l BEFORE ADVANCING.
WRITE record-2 BEFORE ADVANCING.

Figure 8-l0(a) illustrates the record produced
shown above:

G!D

GEO

the

code

segment

I
I

MR-S-038-79

Figure 8-l0(a):

COBOL Variable-Length ASCII with BEFORE ADVANCING

8-7

October 1985

FILE FORMATS
If the WRITE statements for record-l and record-2 had the AFTER
ADVANCING clause, the records produced by the code segment shown above
would appear as:
WORD

(ill

5
3

9
5

MR-S-3096-83

Figure 8-19(b):

COBOL Variable-Length ASCII with AFTER ADVANCING

8-8

October 1985

FILE FORMATS
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

FAD
2

'--'

FAD

'--'

F
'--'

FAD = FILE ACCESS DATA
CC

'--'

= BLANK (USED AS PADDING CHARACTER)

CHARACTER COUNT
MR-S-039-79

Figure 8-10(c):

Fixed-Length SIXBIT

8-8.1

October 1985

FILE FORMATS

(THIS PAGE INTENTIONALLY LEFT BLANK.)

8-8.2

FILE FORMATS
CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FIL.E-CONTROL.
SEL.ECT filename ASSIGN TO DSK
RECORDING MODE IS SIXBIT.
DATA I1IVISION.
FILE SECTION.
FII

fihmame VALUE OF ID 'DATA FIL..
record··. 1 DISPI...Ay····6.
02 field-1 PIC X(4) VALUE "A13I!" •
02 field-2 PIC A(5) VALUE "CDE::rD' •
02 field-3 PIC 9(10) COMP VAL.UE 96~.:i4n~~~~2:L D.
02 field-4 PIC X(2) VALUE "HI".
02 field· . ·5 PIC 9<11> COMP VAL.UE: 34~.:j6 ?9B~!:314 •
02 field'-6 PIC 9(4) VALUE 1289.
02 field-7 PIC 9(5) COMP""l VALUE 123.4~5.
02 field-8 PIC 9(11) COMP VALlIE 1239137::'i69f:1:.1.
I

Figure 8-11 illustrates the record produced by the code segment
above:
WORD

FA'D

3
4

9654839218

r--

34567982314

6
1

8
9

123.45

r--

12398756983

I
MR·S-040·79

Figure 8-11

COBOL Fixed-Length SIXBIT

8-9

shown

FILE FORMATS
8.2.4

Variable-Length SIXBIT

This format is the same as fixed-length SIXBIT, except that the
character count may vary from record to record. The following diagram
illustrates the format of variable-length SIXBIT records:
WORD

FAD

I
3

'-'

FAD

I
6

FAD = FILE ACCESS DATA
CC
= CHARACTER COUNT
'-' "BLANK (USED AS PADDING CHARACTER)
MR-S-041 79

Figure 8-12 Variable-Length SIXBIT

8-10

FILE FORMATS
CODE SEGMENT:

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS SIXBIT.
[lATA DIVISION.
FILE SECTION.
F[I
01

filename VALUE OF 1[1 'DATA FIL' •
record-1 DIS P LA'( ._. 6 •
02 field'-l PIC 9(7) COMp····1 VAL.UE 123.456"7.
02 field-2 PIC X(3) VALUE A3C ".
02 field-3 PIC A(3) VAL,UE "DEF".
02 field-4 PIC 9(3) VALUE .-. ~:;j~5 •
02 field"-5 PIC 9(10) COMP VAUIE 143456l009.
02 field--6 PIC 9 ( 11 ) COMP VALUE: 9a7654:'5~~ 1 0(1.
02 field-7 PIC X( ~.~) VAL.UE "A2".
02 field--8 PIC 9(5) COMP VALUP.: 32~?1.
I

record-2 DI SPLAY '-6.
02 field--l PIC 9(7) COMp····l VALUE 1395.67t;J.
02 field--2 PIC X(3) VALUE B5L.' •
02 field-3 PIC A(3) VALUE LMN ".
02 field--4 PIC 9(3) VALUE "79.
02 f ield-"5 PIC 9(10) COMP VALUE 81l6E)96f;J:!1.
02 field-6 PIC 9(11) COMP VAL.UE 18976~:j321 !':,o.
02 field-7 PIC X(2) VAL.lIE "M5".
02 field-8 PIC 9(11) COMF' VALUE:: t2~~5l9861 (13.
I

PROCEDURE DIVISION.
WRITE record-t.
WRITE record-·2.

8-11

FILE FORMATS
Fig~re 8-13 illust~ates the record produced by the code segment
on the previous page.

shown

WORD
CC

FAD

123.4567
2

1234567809

5
98765432108

6
A

32571

FAD

1395.678

1 I
M

8176596821

5
I--

18976532150

6
M

8
9

12357986183

I
MR·S.Q42·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 may be
either fixed or variable length, and may be either blocked or
unblocked. Thus, there are four types of EBCDIC files:
1.

Fixed-length

Variable-length

Blocked fixed-length

Blocked variable-length

8-12

FILE FORMATS
In a file written in fixed-length EBCDIC, reco~ds 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:
WORD

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
01

filename VALUE OF ID 'DATA FIL'.
record-l DISPLAY-9.
02 field-l PIC 9(3) VALUE 123.
02 field-2 PIC X(5) VALUE ·ABCDER.
02 field-3 PIC A(2) VALUE ·LM·.
02 field-4 PIC 9(9) COMP-3 VALUE 137958795.
02 field-5 PIC S9(6) COMP-3 VALUE -351235.

Figure 8-15 illustrates the record produced by the code segment
above:

I
2

3
4

5;8
5: 1

1 :3

5:+
5:-

2:3

shown

MR-S-04~-79

Figure 8-15

COBOL Fixed-Length EBCDIC

In a file written in variable-length EBCDIC format, the record lengths
may 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
8-13

FILE FORMATS

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:

RECORD

WORO

l ROW

ROW

ROW = RECORD DESCRIPTOR WORD
MA -5-045- 79

Figure 8-16 Variable-Length EBCDIC

8-14

FILE FORMATS
CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO [lSK
RECORDING MODE IS V.
IIATA DIVISION.
FILE SECTION.
FD
01

filename VALUE OF 1[1 '[tATA FH.' •
record-1 DISF'LAY-9.
02 field~'l PIC 89("7) COMP"'3 VAl..UF. ·.. t ~590~p9.
02 field-2 PIC S9(D) COMp···3 VALUE ~763r-5937 •
02 field-3 PIC 9(3) VALUE ~.:i96 •
02 field'-4 PIC A(2) VALUE 'AB'~
02 field-5 F'IC X(5) VALUE "A13DE".

record-2 DISPLAY-9.
02 field-1 PIC 59(7) COMP-3 VALUE 5~697a7,
02 field-2 PIC 99(8) COMP-3 VALUE -~3a96156.
02 field-3 PIC 9(3) VALUE 593.
02 field-4 PIC A(2) VALUE "MN·.
02 field-5 PIC X(S) VA~UE ·ILH5MLXY~ •.

PROCEDURE DIVISION.
WIUTE record-1.
WRITE record--2.

Figure 8-17 illustrates the record produced Oy the code se9m~nt
above:

ROW

5 :6

9 I-

7 :6

~ :5

9 :3

ROW

5"3

Is
I

1 I,

9:8

:5
3
4

26
1,2

6 19

:8
I

I
I

2,3

3 :8

9 :6

1 :5

6 I-

3,4

4,5

5,6

I
MR·S'()46·79

Figure 8-17

COBOL Variable-Length EBCDIC

8-15

shqwn

FILE FORMATS
Fixed-length EBCDIC records may also be blocked.
In this file format,
fixed-length EBCDIC records are written in groups (or blocks). Each
new block begins on a disk-block boundary.
For tapes, each block
starts a new physical magtape record.
CODE SEGMENT:
ENVIRON"ENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO DSK
RECORDING MODE IS F.
rlATA lIIVISION.
FILE SECTION.
FD
01

filename VALUE OF ID 'DATA FIL'
BLOCK CONTAINS 1 RECORDS.
record-l
DISPLAY-9.
02 field-l
PIC 9(3) VALUE "194".
02 field-2 PIC XeS) VALUE "BDEFG".
02 field-3 PIC A(2) VALUE "MN·.
02 field-4 PIC 9(5) COMP-3 VALUE 13796.
02 field-5 PIC 99(4) COMP-3 VALUE 1985.
record-2 DISF'LAY·-·9.
02 field-"l PIC 9(3) VALUE '762".
02 field-2 PIC X(5) VALUE LANBH'.
02 field-3 PIC A(2) VALUE "AB".
02 field-4 PIC Ii' (5) COMP--3 VALUE 76543.
02 field-.. 5 PIC 89(4) COMf"<~ VALUE ·-9764.
I

PROCEDURE DIVISION.
WRITE record-i.
WRITE recoJ'd-·2.

Figure 8-18 illustrates the record produced by the code segment
above:
WORD

BLOCK 1

6:+
1

7:9

918

5:+

1
1

BLOCK 2

7:6

5:4

7:6

4'I

I
I

3 I' +
I
I

--.

Figure 8-18

:9
I
I

------ -

MR·S.()47·79

COBOL Blocked Fixed-Length EBCDIC

8-16

shown

FILE FORMATS
Variable-length EBCDIC records may be blocked as well. In this file
form~t, the record length may vary from record to record.
Each record
contijins a I-word Record Descriptor Word (ROW) 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 ROW itself. The right half of the ROW
must be ~ero.
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 (BOW) 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 ROW for each record in the block
and the 4 bytes of the BOW itself are included in the block count.
The following illustrates the format of blocked variable-length EBCDIC
recorda:

BOW

ROW

201

BOW

202

ROW

203

ROW

204

205

206

I ROW

207

o
C

BOW ~ BLOCK DESCRIPTOR WORD
ROW = RECORD DESCRIPTOR WORD
MR-S-048-79

Figure 8-19 Blocked Variable-Length EBCDIC

8-17

FILE FORMATS
CODE SEGMENT:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO D8K
RECORDING MODE IS V.
DATA DIVISION.
FILE SECTION.
FD
01

filename VALUE OF ID 'DATA FIL'
BLOCK CONTAINS 1 RECORDS.
record-l
DISPLAY-9.
02 field-l
PIC S9(7) COMP-3 VALUE +9356127.
02 field-2 PIC 9(7) COMP-3 VALUE 3987156.
02 field-3 PIC 9(3) VALUE "198".
02 field-4 PIC A(2) VALUE "MN°,
02 field-5 PIC 89(9) COMP-3 VALUE -569138279.
02 field-6 PIC X(6) VALUE "ABCDEF".
record-2 [I I SPLAY ... 11.
02 field-l
PIC 89(7) COMP-3 VALUE ···3295B65.
02 field-2 PIC 9(7) COMp .... 3 VALUE 937D~;:J.8 •
02 field·"3 PIC 9(3) VALUE "196".
02 field-4 PIC A(2) VALUE "AL.. u
02 field-5 PIC 9(9) COMP . ··:~ VALLIE 569138279.
02 f ield'-6 PIC X(9) VALLIE "ABCDEFGHI".

PROCEDURE DIVISION.
WRITE record-I.
WRITE record-2.

8-18

FILE FORMATS
Figure 8-20 illustrates the record produced by the code segment
on the previous page.

BOW

ROW

shown

0
0
I

9:3

5:6

I
I

3:9
1

1 12
1

7;+
1,

8:7
1

1 :5
I

6:+
1

9 i1
1

3:8

,
N

5:6
I
I

2;7

9:1

v--.....--

....-..J'.. -"

BOW

ROW

;

3:2
,

9;5
1

1
511
!
81+
1

8:6

9:3
1

7:8
,

5; 1

9: 1

3:8

5:6
1
1
9:+
,

2:7
6

~4...--....-'"

....

~
MR·S.Q49-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 may only be interpreted as COMPUTATIONAL and COMPI 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 on the following pages.

8-19

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
01

filename VALUE OF 'DATA FIL'.
BINARY-REC DISPLAY-7.
02 field-l PIC 89(10) COMP VALUE 12345678910.
02 field-2 PIC 59(10) COMP-1 VALUE 1246.597092.
02 field-3 PIC XC]) VALUE -ABCDE12-.
02 field-4 PIC 9(11) COMP VALUE 12345678954.
02 field-5 PIC 9(3) VALUE -532-.
02 field-6 PIC 9(14) COMP VALUE 12345678954.
02 field-7 PIC A(2) VALUE -LN-.

Figure 8-21 illustrates the record produced by the code segment
above:

shown

~
1234568910
1246.597892

2
3

5
12345678954
6

8
12345678954967
9
10
MR·S.Q5(J.7~

Figure 8-21

COBOL Standard Binary and ASCII Mixed-Mode Binary

8-20

FILE FORMATS
8.2.6.2

COBOL SIXBIT Mixed-Mode Binary -

CODE SEGMENT:

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO D8K
RECORDING MODE IS BINARY.
DATA DIVISION.
FILE SECTION.
FD
01

fi lerlame VALUE OF 'DATA FIL' •
BINARY-REC DISPLAY-6.
02 field-1 PIC S9(10) COMP VALUE 1234567B910.
02 field-2 PIC S9(10) CDMP"-1 VALUE 1234. 59::.~ 1. 7~).
02 field-3 PIC X(7) VALUE "ABCDE12".
02 field-4 PIC 9(11) COMP VALUE 12345678954.
02 field-5 PIC 9(3) VALUE "532".
02 field-6 F're 9(14) COMP VALUE 1~~345678954967 •
02 field-7 PIC A(2) VALUE "LM".

Figure 8-22 illustrates the record produced by the code segment
above:

shown

12345678910
2

1234.692175

5
6

9
10

I c I DIE

L
5

12345678964

I I

12345678964967

I 1

1
MR·S'()51·79

Figure 8-22

COBOL Standard Binary and SIXBIT Mixed-Mode Binary

8-21

FILE FORMATS
8.2.6.3

COBOL EBCDIC 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
01

filename VALUE OF 'DATA FIL'.
BINARY-REC DISPLAY-9.
02 field-1
PIC 59(10) COMP VALUE 12345678910.
02 field-2 PIC 59(10) COMP-1 VALUE 1246.597861.
02 field-3 PIC X(7) VALUE "ABCDE12".
02 field-4 PIC 9(11) COMP VALUE 12345678954.
02 field-5 PIC 9(3) VALUE "532",
02 field-6 PIC 9(14) COMP VALUE 12345678954967.
02 field-7 PIC A(2) VALUE "LM".
02 field-8 PIC 59(5) COMP-3 VALUE -72539.
02 field-9 PIC 9(8) COMP-3 VALUE 36193586.

Figure 8-23 illustrates the record produced by the code segment
above:

shown

WORD
12345678910
1246.597861

12345678954

8
'--

12345678954967

7 2

5 :3

9 :-

6: 1

9 :3

5 !8

:+
~m

Figure 8-23

5-052 79

COBOL Standard Binary and EBCDIC Mixed-Mode Binary

8-22

FILE FORMATS
8.3

FILE ORGANIZATION AND ACCESS

File organization refers to the manner in which the records are
arranged in the file.
Three types of file organization are available
with COBOL-74:
sequential, relative, and indexed-sequential.
File
organization is specified in a COBOL program by means of the
ORGANIZATION clause~
COBOL-74 provides three methods by which files can be accessed:
File access refers to the way in
sequential,
random, and dynamic.
The method of
which records from a file are read and/or written.
access for a file is specified in a COBOL program by the ACCESS MODE
clause. The chart below shows file organizations and the methods by
which they can be accessed.
File Organization

Method of Access

ACCESS MODE

Sequential

SEQUENTIAL

Relative

Sequential
Random
Sequential and Random

SEQUENTIAL
RANDOM
DYNAMIC

Indexed

Sequential
Random
Sequential and Random

SEQUENTIAL
RANDOM
DYNAMIC

RMS Indexed

Sequential and Random

DYNAMIC

In the following sections, file organizations are described along with
the methods by which they can be accessed and the manner in which
these methods are specified.
For RMS Indexed file organization reference Appendix I and/or the
Reference Manual (RMSREF.MEM).

8.~

RMS

SEQUENTIAL FILES

Sequential files 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, DECtape (TOPS-10 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 DECtape
(TOPS-l0 only) 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 must be specified
with the REWRITE statement. This 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 REWRITE).

8-23

October 1985

FILE FORMATS
8.5

RELATIVE FILES

Relative files are arranged like sequential files, but differ from
sequential files in the method by which they are accessed and by the
devices on which they must be stored. The following requirements must
be fulfilled for a file to be relative:
1.

It must be on a random-access device.

It must be blocked.

You can use the ACCESS MODE clause in the SELECT
Environment Division to specify the access method.

statement

the

You must also specify the RELATIVE KEY in the Environment Division.
The data-name specified by the relative key must be described in the
Working-Storage section as a COMPUTATIONAL item of 10 or fewer
cha~acters.
Its picture can only contain the characters Sand 9 (or
their equivalent, such as S9(4)). The RELATIVE KEY specifies to the
object-time system the location of a record relative to the beginning
of the file. That is, the first record in the file is record 1 and
the last record in the file is l+n where n is the number of remaining
records in the file.
Some records can be zero-length, that is, they do not have anything
written in them because the file was created randomly. These records
have RELATIVE 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.
A relative file can be created in one of two ways
randomly or
sequentially.
To create a file randomly (that is, by writing into
scattered or random records), you need only open the file, move an
integer value into the RELATIVE KEY for each record to be written
randomly, and write each record.
To ~reate a
relative
file
sequentially, open the file for output and begin writing records. The
RELATIVE 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 Relative Files

A file with relative organization can still be accessed sequentially
if you specify ACCESS MODE IS SEQUENTIAL in the File Control
paragraph. 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-Iength record.
Any
zero-length records are skipped by the sequential read operation. A
file opened for input or I/O can be repositioned using the START
statement.
An existing record can be updated using the REWRITE
statement, assuming the file was opened for I/O and the immediately
preceding I/O operation was a READ.
A sequential READ or WRITE
updates the file's RELATIVE KEY value to indicate the current record
position.

8-24

FILE FORMATS
8.5.2

Random Access Of Relative Files

A relative file may be accessed at scattered locations by specifying
the clause ACCESS MODE IS RANDOM.
In this case the record accessed is
the one indicated by the current value of the RELATIVE KEY. The first
record on the file is assigned the relative 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 RELATIVE KEY for the file.
Non-zero-length records
may be updated by the use of the" REWRITE clause, assuming that the
file is open for I/O and that the previous I/O operation was a READ to
the file.
The INVALID KEY condition occurs if:

8.5.3

A READ is made to a zero-length record

A WRITE is made to a non-zero-length record

A REWRITE is made to a zero-length record, or the last I/O
operation before the REWRITE was not a valid READ to the file

Dynamic Access Of Relative Files

Often you will want to access a file both randomly and sequentially.
You may accomplish this by indicating that your file's ACCESS MODE IS
DYNAMIC.
If you specify this mode, you may read your relative file
randomly in the normal way, then issue a READ NEXT command and switch
to sequential access.. This READ statement acts just as it would in
sequential access mode, obtaining the next non-zero-length record. As
in sequential mode, the RELATIVE KEY will be reset to indicate the
relative location of the record just obtained. The first READ NEXT
you issue will use the current value of the RELATIVE KEY as its
starting point.
You may alter this by using the START verb to
position the record pointer in the file.
You may also update records
using the REWRITE verb, with the same considerations as before.
Figure 8-24 presents an example program which positions the file
pointer to a starting location and updates records sequentially
thereafter.

8-25

FILE FORMATS
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT RELOUT ASSIGN TO DSK
ORGANIZATION IS RELATIVE
ACCESS MODE IS DYNAMIC
RELATIVE KEY IS RELKEY.

DATA DIVISION.
FILE SECTION.
FD RELOUT BLOCK CONTAINS 8 RECORDS DATA RECORD IS RELREC
VALUE OF ID IS "RELFILDAT"
01 RELREC PIC X(80)

WORKING-STORAGE SECTION.
77 RELKEY PIC 9(10) VALUE IS 1.
PROCEDURE DIVISION.
START.
OPEN INPUT-OUTPUT RELOUT.

UPDATE.
MOVE 5 TO RELKEY.
START RELOUT, INVALID KEY GO TO STRT-ERR.
READ RELOUT NEXT, AT END GO TO FINISH.

REWRITE RELREC, INVALID KEY GO TO ERROR.
GO TO UPDATE.

FINISH.
CLOSE RELOUT, STOP RUN.
ERROR.
DISPLAY "ERROR REPLACING RECORD", DISPLAY RELREC.
GO TO FINISH.
STRT-ERR.
DISPLAY "ERROR IN START - KEY=", RELKEY.
GO TO FINISH.
Figure 8-24

Statements Used to Sequentially Access a Relative File

A relative file can be treated as a sequential file.
That is, you can
declare its ACCESS MODE as SEQUENTIAL and read or write the file
sequentially.
However, the file cannot be read or written randomly
when it has been declared as' ACCESS MODE SEQUENTIAL.
If you wish to
be allowed to access the file both randomly and sequentially you
should specify the ACCESS MODE IS DYNAMIC option.

8-26

FILE FORMATS
8.6

INDEXED-SEQUENTIAL FILES

Indexed-sequential files (also called ISAM files) 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:
o payroll (key is employee number)
o inventory control (key is part number)
o production control (key is job or batch number)
An indexed-sequential file consists of two files:
the data file
containing the actual data and the index file containing pointers to
record keys within the 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 5.9,
ISAM - Indexed-Sequential File Maintenance Program.) ISAM then copies
the data from the sequential file and creates a data file and an index
file to reference the 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 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 data file and one for the index
file.

8.6.1

Data File

The 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 will
request additional blocks from the monitor as needed. If the monitor
8-27

FILE FORMATS
cannot allocate additional blocks (that is, because the user's quota
on the file structure is exceeded or the system's limit was reached),
an error message is issued.
The format of the data file
is similar to that
sequential files, with the following exceptions.

relative

and

The right half of the header word contains the size of the
record in 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.

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.

IN .IDA FILE

.IDA BLOCK STRUCTURE

DATA RECORD STRUCTURE

HEADER WORD

DATA WORDS

NO. OF CHARACTERS
(SIXBIT OR ASCII)

BLOCK 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 data file and parameters specified by the user.
It contains
up 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 of the 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
8-28

FILE FORMATS

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.

A
B

C
POINTERS
TO DATA
BLOCKS

POINTERS
TO NEXT
LEVEL

POINTERS
TO NEXT
LEVEL
USERS
REQUESTS
RECORD WITH
KEY L

-----

-- r

KEYS

[KEYS

1 *

2 D

3 G

INDEX BLOCK 1

DATA BLOCK 2

.........,.........,
1

DATA BLOCK 1

*"'*'........----~

2 J ~----.t

~--~~

5 M

~--~~

5 R

6 P
INDEX BLOCK 4
INDEX BLOCK 2

INDEX BLOCK 6
INDEX LEVEL 2
(HIGHEST)
3 R

8 V

9 Y
INDEX BLOCK 5
INDEX LEVEL 1
(INTERMEDIATE)

*=LOW VALUES

INDEX BLOCK 3
INDEX LEVEL 0
(LOWEST)

INDEX FILE

DATA BLOCK 4

DATA FILE
MR·S-054·79

Figure 8-26

Locating a Record in an Indexed-Sequential File

8-29

FILE FORMATS
The format of the index file is more complex than that of
file. Figure 8-27 shows the structure of the index file.

the

data

IN .IDX FILE

STATS
BLOCK

.IDX BLOCK STRUCTURE

HEADER WORD 1

INDEX LEVEL

NO. OF CHARS IN BLOCK
(AS IF SIXBIT)

HEADER WORD 2

I VERSION NO. OF THIS BLOCK

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 whi~h the index entry points.

8-30

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 ~escribe your key
field as S9(10)
DISPLAY to )SAM,
you
should describe it the same way in your
COBOL program.
BY using
the
same
descriptions you will ensure 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 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 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 general, 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 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 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 will never need more than two levels
occasionally maintained using the ISAM program.

8-31

of index if
it
(See Section 7.1)

CHAPTER 9
SIMULTANEOUS UPDATE

The COBOL-74 simultaneous update facility allows sequential, relative,
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-74, 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-74 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
non-simultaneous-update users from accessing it until you are willing
to release it. 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

•

Implicitly, by exhaustion of the verb selection
the preceding RETAIN statement.

Section

9.1.3,

specified

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 AR.E AVAILABLE TO ONLY ONE USER ATN
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-B)

PROGRAM B
ACCEPT KEY-A
READ FILE-A WITH LOCK

(PROGRAM B IS DENIED ACCESS TO KEY-A OF FILE-A)

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.Q5779

Figure 9-2

9.1

The Problem of Deadly Embrace

PROGRAMMING CONSIDERATIONS

Simultaneous update allows you to project the usage you want at both
the file and record level.
It also allows you to project the usage
you will allow others to have while you have control of the file.
A
central clearing house in the COBOL-74 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 project file usage by specifying which
of
the
COBOL-74
input/output verbs you will execute during your tenure of the file or
record and which you will 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 will be stopped from doing so. See Figure 9-3
for an outline of how resources can be projected 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 se1ection]
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

(Release of
file-wide
resource)

Projecting Resources For Simultaneous Update

The OPEN Statement

9.1.1

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

,
[ REVERSED
flle-name-l
WITH NO REWIND

{ ~~~UT-OUTPUT} file-name-3
-

[,
[ REVt:RSED
.flle-name-2
WITH NO REWINDJ

[

READ '
NaNE
REWRITE
~
WRITE
PELETE
I ANY VERB

[
OPEN

.EQ.B.
[

..•

AN'YVfRB

AN'Y"VE RB

ALLOWING nTHI='R'

[ file-name-4

~~~~ITE
l) [AND '~t WRITE
~~~~ITE
'~t WRITE
DELETE
DELETE

FOR

READ
REWRITE }[
WRIT E
..8!iQ
{ DELETE
FiNvV"ERB

REWRITE
READ
WRITE,
{ DELETE
ii:N'Y'VfRB

AND
-

READ
INaNE
REWRITE
WRITE
DELETE
A Y VER

...

REAO
REWRITE
. AND
[ ALLOWING OTHERS WRITE
NONE
DELETE
I Aij'YVI RB

READ

If 1!iQ!if II

[ EXTEND] fil ename-5 [ f i l ename-6 ]
[ UNAVAILABLE statement-l

...

[,statement-2 ]

Figure 9-4

] ~

The OPEN Statement

9-5

WRITE
DELETE

'ANY"YfRB

•••

SIMULTANEOUS UPDATE
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
either
open the file under
simultaneous update or for input only. Other uses will be
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.
Conversely, if a file is open
for normal processing, users attempting
to open it under simUltaneous update
will be denied access. See Figure 9-5,
Competing For Program Access to Files.

The file must be OPEN in I/O mode.

The COBOL-74 I/O verbs you intend to execute must be
following the key word FOR.

The COBOL-74 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
OPEN statement.

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 qnly
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 will cause the object-time system to abort the
program.
9-6

opened

entered

for

single

S~MULTANEOUS

UPDATE

Example 9-1
OPEN I/O FILE-A FOR READ AND WRITE,
ALLOWING OTHERS 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.
Example 9-3
OPEN 1-0 FILE-A FOR READ AND WRITE,
OTHERS ANY,
UNAVAILABLE OPEN 1-0 FILE-A FOR READ,
OTHERS ANY,
UNAVAILABLE STOP RUN.

9-7

SIMULTANEOUS UPDATE

WITH AND WITHOUT SIMULTANEOUS UPDATE

PROGRAM A
~

OPEN FI LE·A FOR

"MULTANEOU' UPOATE

.----------.
3.

PROGRAMC

OPEN FILE·A WITHOUT
SIMULTANEOUS UPDATE

PROGRAM C
~

OPEN FILE·A WITHOUT
...---_S_IM_UL_T_AN_EO_U_S_UP_DA_T_E...,

2.
PROGRAM A

~(
~.

"L6A

T)
~

•

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 exclusiv~ 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-8

SIMULTANEOUS UPDATE

RETAIN

file-name-l

RECORD

[KEY

READ
REWRITE
READ-REWRITE
DELETE
WRITE

READ
REWRITE
READ-REWRITE
DELETE
WRITE
READ-WRITE
ANY VERB

~WRITE

ANY VERB

• fi le-name-2

FOR

RECORD

READ
REwRITE
READ-REWRITE
DELETE
WRITE
RfA[):"WRITE
ANY VERB

~WRITE

ANY VERB

statement-l

[UNTIL FREED]

identifier-2}]
{ literal-2

[KEY

READ
REWRITE
READ-REWRITE
DELETE
WRITE

[UNAVAILABLE

{ identifier-I}]
literal-I

[,staternent-2 ]

Figure 9-6

[UNTIL FREED]

... ] ~

MR-S-586-80

The RETAIN Statement

The 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, relative,
indexed-sequential)
see
Sections 9.1.4, 9.1.5, and 9.1.6 respectively.
(See also the COBOL-74
Language Reference Material, Part 2 of this manual.)
1.

The file(s) named in a RETAIN statement must have been
previously opened under simultaneous update.
If not, the
object-time system will abort 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,
relative, or indexed-sequential files.
The I/O
verbs selected, however, must conform to those allowed for
the file.

Using the RETAIN for, WRITE, DELETE, or ANY VERB statement
with an indexed-sequential file locks the entire file, not
just the record.

All records to be retained concurrently must be retained with
the same RETAIN statement.
Once records have been retained,
no other records may be retained until the currently retained
records are freed.

9-9

file

January 1980

SIMULTANEOUS UPDATE
6.

The retention of records is purely a logical operation and
does not involve any actual I/O. You may, in fact, retain
nonexistent records.
Obviously, 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, will 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 record 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.

10.

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 will not be freed
until a FREE statement is issued.

11.

Using the RETAIN for WRITE, DELETE8 or ANY
causes the program to look for an ISAM file.

VERB

statement

12.

The KEY phrase allows you to specify a particular record or
more than one record in a file.
If no key is provided, the
next record is assumed for sequential files and the current
value of the RELATIVE or RECORD KEY is used for indexed or
relative files.

13.

The value of the key may be specify by any identifier that
can be subscripted, qualified, or both. Its usage, however,
must be computational. For example:
RETAIN FILE-A RECORD
KEY PAY-FEC OF RECORD-KEYS
FOR READ-REWRITE.
9-10

January 1980

SIMULTANEOUS UPDATE
It may 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 RECORO may 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.

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.

identifier .. l
literal-l

RECORD
file-name-l
{ EVERY RECORD

[

file-na~-2

RECORD [KEY
{
~

J identifier-2
\ literal-2

RECORD

EVERY RECORD
[NOT RETAIN~D statement-!
Figure 9-7

statement-2]

. .. ]

.!..

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, relative, and indexed-sequential,
see Sections 9.1.4, 9.1.5, and 9.1.6 respectively.
(See also the
COBOL-74 Language Reference Material, Part 2 of this manual.)
1.

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 statement

The FOR clause of the RETAIN statement specifies ANY VERB
9-11

SIMULTANEOUS UPDATE

9.1.4

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 will occur 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 will cause 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 projects 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.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.
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-12

SIMULTANEOUS UPDATE
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 ve~bs were executed, the record
would not have been freed and any attempt to RETAIN any oth~r records
would fail.
If, however, your application is such that yo~ mayor may 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 Sophisticated Access to Sequential Files - 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 will not
be 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,
and that no other user has updated that record in the interim. These
considerations have little effect on the performance of relative 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,
9-13

SIMULTANEOUS UPDATE

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
records at a time. Performance is optimal if the number of records
retained is a multiple of the blocking factor and the execution of the
RETAIN statement is synchronized with logical block boundaries. A
RETAIN statement for 'a file whose blocking 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.
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.

9-14

SIMULTANEOUS UPDATE
Providing a notation for r~ferencing 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 ~ll of the related records have been
processed. The UNTIL FREED phrase is provided for this purpose.
It
allows you to defeat 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.

the

record

when

you

have

When retaining records, the program will normally be suspended if any
of the requested files or records are unavailable.
You will not be
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 instructs 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.

9-15

SIMULTANEOUS UPDATE
Similarly, if you execute a FREE statement for a record or records
that are not currently retained by your program, the object-time
system will proceed 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 Relative Files

Accessing records in a relative file is similar to the accessing of
sequential file records.
(See Section 9.1.4.) There are, however,
these differences:
1.

If a key is not specified, the RELATIVE KEY specified in
FD for the file is used.

the

Positive keys, whether specified directly or via RELATIVE
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: that
is, 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.

any

Example 9-4 demonstrates reading a relative file sequentially.
Example 9-4
A.

RETAIN FILE-A FOR READ.
READ FILE-A NEXT RECORD;

INVALID KEY GO TO ERROR-RTN.

GO TO A.
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.

9-16

SIMULTANEOUS UPDATE
Example 9-5
A.

PERFORM RELATIVE-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-RECORD.
FREE FILE-A RECORD.
GO TO A.
Example 9-6 shows how to use a field within a record as the RELATIVE
KEY for processing a chain of related records in a relative 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 will not be
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) FREE FILE-A EVERY RECORD.
GO TO B.

9.1.6

(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 may retain records for REWRITE, DELETE, and READ-REWRITE,
in addition to READ, WRITE, and ANY VERB. You may 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-17

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 this case, a positive numeric
literal of ten or fewer digits may 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.

DATA~KEY.

RETAIN FILE-A KEY DATA-KEY
FOR REAO-REWRITE UNTIL FREED.
READ FILE-A INVALID KEY GO TO ERR-RTN.
DISPLAY FILE-A-RECORD.
B.

(process and update record if the user wishes)

FREE FILE-A-RECORD.
GO TO A.

9-18

CHAPTER 19
REPORT WRITER

The COBOL-74 compiler offers a report writing facility, REPORT WRITER.
Using this facility can make it easy to format printed reports.
As a programmer, you have been asked to write a program to print two
reports from one input file.
The first report format is shown in
Figure 19-1, the second report format is shown in Figure 19-2.
The
input data file records are 89 characters in length. The data file's
input appears in Figure 19-3.
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-74 Language
Reference Material, Part 2 of this manual.
Immediately following the example program are the two reports as
would appear on the line printer.

19-1

they

October 1985

.-.
z

f~
"

,[to
I" [11

DEC 15-(649)-1001"'869

MR-s-3121-83

Figure 1"-1:

Report A Format

LINE PRINTER SPACING CHART

GL.UE

;:;:=;; ........ "'.ww_

figure 10-2:

NOTES

Report B Format

REPORT WRITER
John Adam
Herbert Abbott
Robert Archibald
Elliot Brown
Thomas Berger
Janet Blau
Jeanne P. Canale
James Carter
Peggy Doucet
Ruth Fong
Jack Frost
Jane Hoffman
Steve Ingersoll
Josef Jacquart
Stanley Kowalczyk
Ron Lusk
John Maslanka
Mary Miller
David Nixon
John Young
Peter Vatne
Figure 10-3:

12 Pleasant Street Marlboro
200 Meadow Lane
Westminster
Nashua
317 Narrows Road
Whitinsville
299 Swift Road
700 East State Road Princeton
29 E. Main Street
Marlboro
Medford
100 Miller Lane
400 High Street
London
200 Forest Street
Marlboro
Concorn
1533 State Street
7 Winter Street
White Plains
Bolton
15 Summer Street
13 Washington St.
Atlantic City
5 Jean Road
Walpole
P Cynthia Road
Canton
White Plains
57 Highview Drive
30 Taylor Street
Marlboro
8 Commerce Way
Woburn
10 Main Street
Sudbury
99 Oldham Road
Sudbury
137 Farm Road
Hudson

MA
MA
NH
MA
NJ
MA
MA
~TH

MA
NH
NY
MA
NJ
MA
MA
NY
MA
MA
MA
MA
MA

Ir,HHHHHJ

650000
960000
750000
1125000
357000
675000
350000
700000
625000
650000
350000
760000
275000
425000
555000
840000
500000
450000
800000
475000

Input Data File for Report Writer Program

10-4

October 1985

REPORT WRITER
COBOL-74 12C(1574) BIS
PAGE 1

PRO G RAM
REP E X M
27-Aug-85 10:43
REPEXM.C74
05-Aug-85 11:20
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0ftJ21
0022
0023
0024
0025
0026
0027
0028
0029
0030
0031
0032
0033
0034
0035
0036
0037
0038
0039
0040
0041
0042
0043
0044
0045

IDENTIFICATION DIVISION.
PROGRAM-ID.
REPEXM.

* **************************************************************
**
* This program is an example of the use of REPORT WRITER.
*
*
* The program generates two re90rts: one is a list of
* customers by city and state; the other is a list of
*
*
*
*
* totals for each state.
*
* The two reports ere 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.

* **************************************************************
*
* Report Codes (Lines 37 and 38):
*
*
* The following entry in the SPECIAL-NAMES paragraph of the *
*
*
SECTION defines the codes 'A' and 'B' for
*
* CONFIGURATION
the two reports you are going to generate. The line printer *
* spooler
can separate them when you use the /REPORT: switch *
* with
the
system QUEUE command. For example, to print both
*
*
* reports, you can type:
*
*
*
Q LL:=CUSTMR.LST/REPORT:A,CUSTMR.LST/REPORT:B
*
*
* ***************************************************************
*
'A'
'B'

IS BY-CITY-CODE
IS STATE-TOTALS-CODE.

INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT

CUSTOMEP-FILE
ASSIGN TO DSK
RECORDING MODE IS ASCII.

10-5

October 1985

REPORT WRITER
COBOL-74 l2C(1574) BIS
PAGE 2

PRO G RAM
REP E X M
27-Aug-85 1~:43
~5-Aug-85
11:2~
REPEXM.C74
~~46
~~47
~~48
~~49
0~5~

~05l

0052
0053
0054
0055
~056
0~57

0058
0059
0060
0061
0062
0063
0064
0065
0066
0067
0068
0069

* ********************************.*****************************
*
*
* Report file SELECTion and ASSIGNment (Line 57):
*
*
*
* Like any file, the file for the report must be SELECTed and *
* assigned. You can use a disk file (DSK) , but any device is *
*
* legal.
*
*
* **************************************************************
SELECT

ASSIGN TO DSK
PRINTER-FILE
RECORDING MODE IS ASCII.

SELECT

ASSIGN TO DSK DSK DSK
SORT-FILE
RECORDING MODE IS ASCII.

DATA DIVISION.
FILE SECTION.
SD
01

SORT-FILE.
SORT-RECORD
~2

007~

0071
0072
0073
0074
0075

~076

~2
~2
~2

0~79

0080
0081

0~83
~~84

SORT-NAME
SORT-CITY
SORT-STATE
SORT-STREET
SORT-SALES

PIC X(24) •
PIC X (20) •
PIC XX.
PIC X (20) •
PIC S9 (10) •

CUSTOMER-FILE
VALUE OF ID IS 'CUSTMRDAT'.
CUSTOMER-RECORD
USAGE DISPLAY-7.

0077
0078

~082

USAGE DISPLAY-7.

02
02
02

CUSTOMER-NAME
CUSTOMER-STREET
CUSTOMER-CITY
CUSTOMER-STATE
CUSTOMER-SALES
FILLER

10-6

PIC X (24) •
PIC X (20) •
PIC X (20) •
PIC XX.
PIC S9(1~)V99.
PIC XX.

October 1985

REPORT WRITER
COBOL-74 12C(1574) BIS
PAGE 3

PRO G RAM
REP E X M
27-Aug-85 1~:43
REPEXM.C74
05-Aug-85 11:2~
0085
~~86
~~87

0088
~~89

0090
0~91
0~92
0~93
~~94
~095
~~96
~~97
~~98
~099
~1~0
~1~1
~1~2
~103
~1~4
~105

* **************************************************************
*
*
* The FD for the Report File (Lines 1~5 - 1~9):
*
*
*
* You can give the file for the report the name CUSTMR.LST.
*
*
*
* The REPORTS ARE clause names the RD entries that you
*
* 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 one*
*
*
* character code. In this program, you never refer to
PRINTER-RECORD in the PROCEDURE DIVISION. Thus, you can
*
*
*
* omit PRINTER-RECORD. The default size for PRINTER-RECORD
is 132 characters.
*
*
*
*
* **************************************************************
FD

0106

PRINTER-FILE
REPORTS ARE

01~7

0108

VALUE OF ID IS
PRINTER-RECORD

01~9
~11~

0111
0112
0113

WORKING-STORAGE SECTION.

~114
~115

01
01

02
02

0116
0117
0118
k. .. 19

02
02

~120

0121
0122
0123
0124
0125
0126

THIS-DATE
TD-REDEFINED

STATE-TOTALS-ONLY
BY-CITY
'CUSTMRLST'.
PIC X(80)

PIC X(8).
REDEFINES

TD-MONTH
TD-HYF-1
TD-DAY
TD-HYF-2
TD-YEAR

PIC
PIC
PIC
PIC
PIC

USAGE DISPLAY-7.

THIS-DATE.
Z9.
X.
99.
X.
99.

UNEDITED-DATE.
UE-YEAR
UE-MONTH
UE-DAY

PIC 99.
PIC 99.
PIC 99.

77
77
77

TEMP
NUMBER-OF-CITIES
NUMBER-OF-STATES

PIC S999
PIC S999
PIC S999

USAGE COMP.
USAGE COMP.
USAGE COMP.

ONE-COUNT

PIC S9

USAGE COMP
VALUE 1.

77
77

CURRENT-STATE
CURRENT-CITY

PIC XX.
PIC X (20)

USAGE DISPLAY-7.

02
02
02

~127

0128
0129
~130

0131
0132
0133
0134
~135

0136

10-7

October 1985

REPORT WRITER
PRO G RAM
REP E X M
27-Aug-85 1~:43
REPEXM.C74
~5-Aug-85
11:2~
0137
0138
0139
0140
0141
~142

0143
0144
0145
0146
0147
0148
0149
015~

0151
0152
0153
0154
~155
~156

0157
0158
0159
0160
0161
0162
~163

0164
0165
~166

0167
0168
0169
0170
0171
0172
~173

0174
~175

0176
0177
0178
~179
~18~

COBOL-74 12C(1574) BIS
PAGE 4

* **************************************************************
*
* The REPORT SECTION statement (Line 148):
*
*
*
* The REPORT SECTION is coded within the DATA DIVISION. It
* must be the last section(s) of the division. In the REPORT *
*
*
*
* SECTION, you can define the formats for the reports.
*
*
* **************************************************************
REPORT SECTION.

* **************************************************************
*
* The RD for a Report (Lines 172 - 531):
*
*
* The RD entry is the report description for each report.
*
*
*
need an RD entry for each report produced by the
* You
*
program. The first RD entry is below, on line 172, for the *
* STATE-TOTALS-ONLY
report and the RD entry for the BY-CITY
* report is on line 384.
*
*
*
*
The CODE clause of the RD gives the mnemonic-name of the
**
* code
to the report. This is the same code given
*
* by theassigned
literal in the SPECIAL-NAMES paragraph in 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.
*
*
*
*
*

**************************************************************

STATE-TOTALS-ONLY
CODE
CONTROLS ARE FINAL
PAGE LIMIT IS

STATE-TOTALS-CODE
SORT-STATE
58 LINES
HEADING 1
FOOTING 58
FIRST DETAIL 6
LAST DETAIL 55.

October 1985

REPORT WRITER
COBOL-74 12C(1574) BIS
PAGE 5

PRO G RAM
REP E X M
27-Aug-85 10:43
REPEXM.C74
05-Aug-85 11:20
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
0215
0216
0217
0218
0219
0220
0221
0222
0223
0224
0225
0226
0227
0228
0229
0230
0231
0232
0233

* **************************************************************
*
*
* The TYPE Statement (Line 286 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 (Lines 286 and 485):
*
*
*
* The NEXT GROUP clause gives 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
*
*
*
* places the next line two lines below the current line.
*
* ***************************************************************

10-9

October 1985

REPORT WRITER
PRO G RAM
REP E X M
27-Aug-85 10:43
05-Aug-85 11:20
REPEXM.C74

COBOL-74 l2C(1574) BIS
PAGE 6

0234
~235

0236
0237
0238
0239
~240

0241
0242
0243
~244

0245
0246
0247
0248
~249

0250
0251
0252
0253
~254

~255
~256
~257
~258
~259
~260
~26l
~262

0263
0264
0265
~266

0267
0268
0269
027~

0271
~272

~273
~274

0275
0276
0277
~278

0279
0280
~28l
~282

0283

*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*

**************************************************************

*
*
*
*
*
*
*
*
*
*

**************************************************************

*
*
*
*
*
*
*
*
*
*

**************************************************************

*
*
*
The LINE NUMBER IS clause (which can be abbreviated to LINE)*

The LINE clause (Line 288 and throughout the ROs):

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:

*
*
*
*

*
*
*
*
*
*
*
*
*

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.

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.

*
*
*

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 NUMBER IS clause (you 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.
*
*
**************************************************************
The COLUMN clause (Line 288 and throughout the ROs):

*
*
*
The SOURCE IS clause (you can omit IS) specifies the source *
The SOURCE clause (Line 291 and throughout the ROs):

for an item. The source item must have been defined in the
FILE or WORKING-STORAGE SECTION.
Its value is moved into
the report item before the item is written in the file.

*
*
*

**************************************************************

~284

1~-10

October 1985

REPORT WRITER
PRO G RAM
REP E X M
27-Aug-S5 1~:43
REPEXM.C74
~5-Aug-S5
11:2~

COBOL-74 l2C(1574} BIS
PAGE 7

~2S5

~2S6
~2S7
~2SS
~2S9
~29~
~29l
~292
~293
~294
~295
~296
~297
~29S
~299
~3~~
~3~1
~3~2
~3~3
~3~4
~3f()5

f()3f()6
f()3f()7
f()3f()S
f()3f()9
f()3lf()
f()3ll
f()3l2
f()3l3
f()3l4
f()3l5
f()3l6
f()3l7
f()31S
f()3l9
f()32f()
f()32l
f()322
f()323
f()324
f()325
f()326
~327

~32S

USAGE DISPLAY-7.

TYPE

NEXT GROUP PLUS 2

f()2

LINE 1

LINE 2

LINE 5

f()2

LINE 5

COLUMN 22
PIC X(25)
VALUE 'STATE TOTALS OF CUSTOMERS'.
COLUMN 31
PIC X(S)
SOURCE THIS-DATE.
COLUMN 1
PIC X(5}
VALUE 'STATE'.
COLUMN If()
PIC X(19}
VALUE 'NUMBER OF CUSTOMERS'.
COLUMN 44
PIC X(5)
VALUE 'SALES'.

* **************************************************************
*
*
* The SUM clause (Line 335 and throughout the RDs):
*
*
*
* The SUM clause entry on line 337 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 compiler*
*
* 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 *
report group.
*
*
*
*
* **************************************************************

If()-ll

October 1985

REPORT WRITER
COBOL-74 12C(1574) BIS
PAGE 8

PRO G RAM
REP E X M
27-Aug-85 10:43
REPEXM.C74
05-Aug-85 11:20
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
0354
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

TYPE

SORT-STATE LINE PLUS 1.

COLUMN 3

COLUMN 15

COLUMN 35

TYPE

PIC XX
SOURCE CURRENT-STATE.
PIC ZZ,ZZ9
SUM ONE-COUNT.
PIC ZZ,ZZZ,ZZZ,ZZ9
SUM SORT-SALES.

FINAL LINE PLUS 2.

COLUMN 1

COLUMN 15

COLUMN 35

PIC X(5)
USAGE DISPLAY-7
VALUE 'TOTAL'.
PIC ZZ,ZZ9
SUM ONE-COUNT.
PIC ZZ,ZZZ,ZZZ,ZZ9
SUM SORT-SALES.

* **************************************************************
*
*
Missing COLUMN clause (Lines 362 and 364):
*
*
*
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

PIC S9(5)
SOURCE ONE-COUNT.
PIC S9(10)
SOURCE SORT-SALES.

* **************************************************************
*
**
The PAGE LIMIT clause (Lines 388 through 392):
*
*
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 pags headings are
*
*
written.
*
*
*
*
The 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.
*
*
*
*
**************************************************************
*

10-12

October 1985

REPORT WRITER
COBOL-74 12C(1574) BIS
PAGE 9

PRO G RAM
REP E X M
27-Aug-85 10:43
05-Aug-85 11:20
REPEXM.C74
0383
0384
0385
0386
0387
0388
0389
0390
0391
0392
0393
0394
0395
0396
0397
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
0432
0433

BY-CITY
CODE
CONTROLS ARE FINAL
PAGE LIMIT IS

BY-CITY-CODE
SORT-STATE
SORT-CITY
58 LINES
HEADING 1
FOOTING 58
FIRST DETAIL 6
LAST DETAIL 55.

REPORT-HEADER

TYPE REPORT HEADING.

COLUMN 27

02
01

LINE 25

PIC X(27)
USAGE DISPLAY-7
VALUE 'CUSTOMERS BY CITY AND STATE'.
LINE 29
COLUMN 36
PIC X(8)
SOURCE THIS-DATE.

REPORT-FOOTER

TYPE REPORT FOOTING LINE PLUS 2.

COLUMN 30
VALUE

'**

PIC X(19)
USAGE DISPLAY-7
END OF REPORT **'.

* **************************************************************
*
*
The PAGE-COUNTER (Line 430):
*
*
*
*
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 (SOURCE IS PAGE-COUNTER OF report). *
*
*
*
* **************************************************************
01

PAGE-HEADING
02

LINE 1

LINE 2

TYPE PAGE HEADING

USAGE DISPLAY-7.

COLUMN 1
PIC X (33)
VALUE 'CUSTOMERS BY CITY AND STATE'.
COLUMN 62
PIC X(4)
VALUE 'PAGE'.
COLUMN 66
PIC ZZZ9
SOURCE IS PAGE-COUNTER OF BY-CITY.
COLUMN 1
PIC X(8)
SOURCE THIS-DATE.

10-13

October 1985

REPORT WRITER
PRO G RAM
REP E X M
27-Aug-85 19:43
REPEXM.C74
95-Aug-85 11:29
9434
9435
9436
9437
9438
9439
9449
9441
9442
9443
9444
9445
9446
9447
9448
9449
9459
9451
9452
9453
9454
9455
9456
9457
9458
9459
9469
9461
9462
9463
9464
9465
9466
9467
9468
9469
9479
9471
9472
9473
9474
9475
9476
9477
9478
9479
9489
9481
9482

COBOL-74 12C(1574) BIS
PAGE 19

STATE-HEADING

TYPE CONTROL HEADING
SORT-STATE
LINE PLUS 2
USAGE DISPLAY-7.

COLUMN 1

COLUMN 39

COLUMN 36

COLUMN 65

DETAIL-LINE-1

TYPE DETAIL LINE PLUS 2.

COLUMN 1

COLUMN 32

COLUMN 36
COLUMN 56

92
91

DETAIL-LINE-2
92

PIC X(9)
VALUE 'CUSTOMER'.
PIC XeS)
VALUE 'STATE'.
PIC X(4)
VALUE 'CITY'.
PIC X(5)
VALUE 'SALES'.

PIC X(24)
USAGE DISPLAY-7
SOURCE SORT-NAME.
PIC XX
USAGE DISPLAY-7
SOURCE SORT-STATE.
PIC X(29)
USAGE DISPLAY-7
SOURCE SORT-CITY.
PIC zz,zzz,ZZZ,ZZ9
SOURCE SORT-SALES.
PIC ZZ,ZZ9
SOURCE ONE-COUNT.

TYPE DETAIL LINE PLUS 1.
COLUMN 1

PIC X(29)
USAGE DISPLAY-7
SOURCE SORT-STREET.

CITY-FOOTING

TYPE CF SORT-CITY LINE PLUS 3.

COLUMN 4

CITY-COUNT

PIC ZZ,ZZ9
USAGE DISPLAY-7
SUM ONE-COUNT.
COLUMN 11
PIC X(17)
USAGE DISPLAY-7
VALUE 'CUSTOMERS IN CITY'.
COLUMN 36
PIC X(29)
USAGE DISPLAY-7
SOURCE CURRENT-CITY.
COLUMN 56
PIC $$,$$$,$$$,$$9
SUM SORT... SALES.

92
92
92

CITY-SALES

19-14

October 1985

REPORT WRITER
PRO G RAM
REP E X M
27-Aug-8S 1B:43
REPEXM.C74
BS-Aug-8S 11:2B
B483
B484
B48S
B486
B487
B488
B489
B49B
B491
B492
B493
B494
B49S
B496
B497
B498
B499
BSBB
BSB1
BSB2
BSB3
BSB4
BSBS
BSB6
BSB7
BSB8
BSB9
BS1B
BS11
BS12
BS13
BS14
BS1S
BS16
BS17
BS18
BS19
0S2B
BS21
BS22
BS23
BS24
BS2S
0526
0527
BS28
0529
0S3B
BS31
BS32

STATE-FOOTING

TYPE CF SORT-STATE LINE' PLUS 3
NEXT GROUP NEXT PAGE.

COLUMN 4

STATE-COUNT

B2
B2
B2
B1

COSOL-74 12C(1S74) SIS
PAGE 11

STATE-SALES

PIC ZZ,ZZ9
USAGE DISPLAY-7
SUM CITY-COUNT.
COLUMN 11
PIC X(18)
USAGE DISPLAY-7
VALUE 'CUSTOMERS IN STATE'.
COLUMN 32
PIC XX
SOURCE CURRENT-STATE.
COLUMN 56
PIC $$,$$$,$$$,$$9
SUM CITY-SALES.

FINAL-FOOTING

TYPE CF FINAL.

COLUMN 3

LINE PLUS 1

B2
B2
B2
B2

LINE PLUS 1

B2
B2
B2
B2

B2
B2

LINE PLUS 2

PIC X(S)
USAGE DISPLAY-7
VALUE 'TOTAL'.
COLUMN 15
PIC X(S)
USAGE DISPLAY-7
VALUE 'TOTAL'.
COLUMN 25
PIC X(S)
USAGE DISPLAY-7
VALUE 'TOTAL'.
COLUMN 45
PIC X(S)
USAGE DISPLAY-7
VALUE 'TOTAL'.
COLUMN 1
PIC X(9)
USAGE DISPLAY-7
VALUE 'CUSTOMERS'.
COLUMN 15
PIC X(6)
USAGE DISPLAY-7
VALUE 'STATES'.
COLUMN 25
PIC X(6)
USAGE DISPLAY-7
VALUE 'CITIES'.
COLUMN 4,5
PIC X (5)
USAGE DISPLAY-7
VALUE 'SALES'.
COLUMN 1
PIC ZZ,ZZ9
SUM STATE-COUNT.
COLUMN 16
PIC ZZ9
SOURCE NUMBER-OF-STATES.
COLUMN 26
PIC ZZ9
SOURCE NUMBER-Of-CITIES.
PIC $$,$$$,$$$,$$9
COLUMN 36
SUM STATE-SALES.

October 1985

REPORT WRITER
COBOL-74 12C(1574) BIS
PAGE 12

PRO G RAM
REP E X M
27-Aug-85 10:43
REPEXM.C74
05-Aug-85 11:20
0533
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
0583

PROCEDURE DIVISION.

* **************************************************************
*
*
* The USE BEFORE REPORTING verb (Line 551):
*
*
*
* 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.
END-OF-REPORT SECTION.
USE BEFORE REPORTING REPORT-FOOTER.
END-OF-REPORT-A.
DISPLAY 'END OF REPORTS'.
END DECLARATIVES.
MAIN SECTION.
START-PROCEDURE-1.
SORT

STOP

SORT-FILE ON ASCENDING KEY
SORT-STATE SORT-CITY SORT-NAME
INPUT PROCEDURE IS IN-PROCEDURE
OUTPUT PROCEDURE IS OUT-PROCEDURE.
RUN.

IN-PROCEDURE SECTION.
START-PROCEDURE-2.
OPEN

INPUT

CUSTOMER-FILE.

INPUT-PROCESS.
READ

CUSTOMER-FILE
AT END GO TO INPUT-PROCESS-COMPLETE.
COMPUTE SORT-SALES
ROUNDED = CUSTOMER-SALES.
MOVE
CUSTOMER-NAME
TO SORT-NAME.
MOVE
CUSTOMER-STATE TO SORT-STATE.
MOVE
CUSTOMER-STREET TO SORT-STREET.
MOVE
CUSTOMER-CITY
TO SORT-CITY.
RELEASE SORT-RECORD.
GO TO
INPUT-PROCESS.

10-16

October 1985

REPORT WRITER
COBOL-74 12C(1574) BIS
PAGE 13

PRO G RAM
REP E X M
27-Aug-85 10:43
REPEXM.C74
05-Aug-85 11:20
0584
0585
0586
0587
0588
0589
0590
0591
0592
0593
0594
0595
0596
0597
0598
0599
0600
0601
0602
0603
0604
0605
0606
0607
0608
0609
0610
0611
0612
0613
0614
0615
0616
0617
0618
0619
0620
0621
0622
0623
0624
0625

INPUT-PROCESS-COMPLETE.
CLOSE

CUSTOMER-FILE.

OUT-PROCEDURE SECTION.

**************************************************************

*
**
* OPEN the Report File (Line 602):
*
**
* The report file must be opened before any records can be
*
* written in it.
*
* ***************************************************************
START-PROCEDURE-3.
OPEN
ACCEPT

OUTPUT PRINTER-FILE.
UNEDITED-DATE FROM 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-1 TD-HYF-2.

* **************************************************************
*
*
* INITIATE the Reports (Lines 623 and 624):
*
*
*
* 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
INITIATE

BY-CITY.
STATE-TOTALS-ONLY.

10-17

October 1985

REPORT WRITER
COBOL-74 12C(1574) BIS
PAGE 14

PRO G RAM
REP E X M
27-Aug-85 10:43
REPEXM.C74
05-Aug-85 11:20
0626
0627
0628
0629
0630
0631
0632
0633
0634
0635
0636
0637
0638
0639
0640
0641
0642
0643
0644
0645
0646
0647
0648
0649
0650
0651
0652
0653
0654
0655
0656
0657
0658
0659
0660
0661
0662
0663
0664
0665
0666
0667
0668
0669
0670
0671
0672
0673
0674
0675

* ***********.**************************************************
*
*
* GENERATE Report Records (Lines 677 through 679):
*
*
*
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.
*
*
*
A GENERATE statement performs the following operations:
**
*
*
*
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.
**
*
*
*
5. If the argument to the generate statement is a TYPE- *
*
DETAIL record, writes the detail report group.
*
*
*
During the first execution of a GENERATE statement, all
**
*
required report headings, page headings, control headings, *
*
and detail re~ort groups a~e written.
*
*
*
*
* **************************************************************
OUTPUT-PROCESS.
RETURN

SORT-FILE
AT END GO TO REPORTS-COMPLETED.

CURRENT-STATE NOT EQUAL SORT-STATE
ADD 1 TO NUMBER-OF-STATES.

CURRENT-CITY NOT EQUAL SORT-CITY
ADD 1 TO NUMBER-OF-CITIES.

10-18

October 1985

REPORT WRITER
PRO G RAM
REP E X M
27-Aug-85 10:43
REPEXM.C74
05-Aug-85 11:20
0676
0677
121678
0679
121680
121681
0682
0683
0684
0685
0686
0687
0688
0689
121690
0691
0692
0693
0694
0695
0696
0697
0698
0699
07121121
0701
0702
0703
0704
0705
071216
0707
071218
0709
0710
121711
0712
0713
0714

GENERATE
GENERATE
GENERATE
MOVE
MOVE
GO TO

COBOL-74 l2C(1574) SIS
PAGE 15

DETAIL-LINE-l.
DETAIL-LINE-2.
STATE-TOTALS-ONLY.
SORT-STATE TO CURRENT-STATE.
SORT-CITY TO CURRENT-CITY.
OUTPUT-PROCESS.

* **************************************************************
*
**
* TERMINATE the Reports (Lines 711 and 712):
*
**
* 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 714):
*
**
* The CLOSE statement closes the report file. All reports
*
* written in the file must be TERMINATEd before the CLOSE
*
* statement is executed.
*
*
* **************************************************************
REPORTS-COMPLETED.
TERMINATE
TERMINATE
CLOSE

BY-CITY.
STATE-TOTALS-ONLY.

PRINTER-FILE.

No Errors Detected

10-19

October 1985

REPORT WRITER

CUSTOMERS BY CITY AND STATE

8-27-85

10-2~

October 1985

REPORT WRITER
PAGE

CUSTOMERS BY CITY AND STATE

8-27-85

STATE CITY

CUSTOMER
Jane Hoffman
15 Summer Street

1 CUSTOMERS IN CITY

Stanley Kowalczyk

SALES

Bolton

3,500

Bol ton

$3,500

Canton

4,250

Canton

$4,250

Hudson

4,750

Hudson

$4,750

8 Cynthia Road

1 CUSTOMERS IN CITY

Peter vatne
137 Farm Road

1 CUSTOMERS IN CITY

Janet Blau
29 E. Main Street

Marlboro

3,570

John Adam
12 Pleasant Street

Marlboro

10,000

John Maslanka
30 Taylor Street

Marlboro

8,400

Peggy Doucet
200 Forest Street

Marlboro

7,000

Marlboro

$28,970

Medford

6,750

Medford

$6,750

4 CUSTOMERS IN CITY
Jeanne P. Canale
100 Miller Lane

1 CUSTOMERS IN CITY

David Nixon
10 Main Street

Sudbury

4,500

John,Young
99 Oldham Road

Sudbury

8,000

Sudbury

$12,5"0

CUSTOMERS IN CITY

10-21

October 1985

REPORT WRITER
CUSTOMERS BY CITY AND STATE
8-27-85

Josef Jacquart
5 Jean Road

PAGE

I CUSTOMERS IN CITY
Herbert Abbott
200 Meadow Lane

1 CUSTOMERS IN CITY
Elliot Brown
299 Swift Road

I CUSTOMERS IN CITY
Mary Miller
8 Commerce Way

1 CUSTOMERS IN CITY
14 CUSTOMERS IN STATE

Walpole

2,750

Walpole

$2,750

Westminster

6,500

Westminster

$6,500

Whitinsville

7,500

Whitinsville

$7,500

Woburn

5,000

Woburn

$5,000

10-22

$82,470

October 1985

REPORT WRITER
PAGE

CUSTOMERS BY CITY AND STATE
8-27-85

STATE CITY

CUSTOMER
Ruth Fong
1533 State Street

1 CUSTOMERS IN CITY
James Carter
400 High Street

1 CUSTOMERS IN CITY
Robert Archibald
317 Narrows Road

1 CUSTOMERS IN CITY
3 CUSTOMERS IN STATE

SALES

Concord

6,250

Concord

$6,250

London

3,500

London

$3,500

Nashua

9,600

Nashua

$9,600

10-23

$19,350

October 1985

REPORT WRITER
PAGE

CUSTOMERS BY CITY AND STATE
8-27-85

CUSTOMER

STATE CITY

Steve Ingersoll
13 Washington St.

1 CUSTOMERS IN CITY
Thomas Berger
700 East State Road

1 CUSTOMERS IN CITY
2 CUSTOMERS IN STATE

SALES

Atlantic City

7,600

Atlantic City

$7,600

Princeton

11,250

Princeton

$11,250

10-24

$18,850

October 1985

REPORT WRITER
CUSTOMERS BY CITY AND STATE
8-27-85

CUSTOMER

PAGE

STATE CITY

SALES

Jack Frost
7 Winter Street

White Plains

6,500

Ron Lusk
57 Highview Drive

White Plains

5,550

White Plains

$12,050

2 CUSTOMERS IN CITY
2 CUSTOMERS IN STATE

1"'-25

$12,050

October 1985

REPORT WRITER
CUSTOMERS BY CITY AND STATE
8-27-85

PAGE

TOTAL
CUSTOMERS

TOTAL
STATES

TOTAL
CITIES

TOTAL
SALES
$132,720

** END OF REPORT **

10-26

October 1985

REPORT WRITER

STATE TOTALS OF CUSTOMERS
8-27-85

STATE

NUMBER OF CUSTOMERS

SALES

MA
NH
NJ
NY

14
3
2
2

82,470
19,350
18,850
12,050

TOTAL

132,720

10-27

October 1985

CHAPTER 11
PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS

You may 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.

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 nne
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 writeable or
nonwriteable, 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.)
A segment with a segment number of 50 or greater is nonresident and
nonwriteable;
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 writeable;
it retains changes made by ALTER
statements.

11-1

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
A segment with a segment number less than the SEGMENT-LIMIT
(or with
no segment number) is a resident and writeable 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 maln 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 segments 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
SEGMNT.CBL
0001
0002
0003
0004

OOOS
0006
0007
0008
0009
0010
0011
0012
0013
0014

OOIS
0016
0017
0018
0019
0020
0021
0022
0023
0024
002S
0026
0027
0028
0029
0030

S E G MN T
24-0CT-78 09:22
24-0CT-78 09:22

IDENTIFICATION DIVISION.
PROGRAM-ID. SEGMNT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
OBJECT-COMPUTER. DECSYSTEM-20
SEGMENT-LIMIT IS 2S.
DATA DIVISION.
PROCEDURE DIVISION.
SECT 1 SECTION 20.
CALL A.
SECT2 SECTION 6S.
CALL A.
SECT3 SECTION 22.
CALL A.
SECT4 SECTION 20.
CALL A.
SECTS SECTION 60.
CALL A.
SECT6 SECTION 30.
CALL A.
SECT7 SECTION 3S.
CALL A.
SECT8 SECTION 3S.
CALL A.
SECT9 SECTION 60.
CALL A.
STOP RUN.

NO ERRORS DETECTED

11-2

COBOL-74 12(601) BIS
PAGE 1

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
In the example above, the segments are as follows:

11.2

The
Segment 20 contains the sections SECTI and SECT4.
SEGMENT-LIMIT IS 25 statement causes this segment to be
resident and writeable.

Segment 22
writeable.

Segment 30 contains section SECT6.
Since its segment number
is
above
the SEGMENT-LIMIT but less than 59,
it is
nonresident and writeable; changes made to the segment are
preserved even if it leaves and returns to memory.

Segment 35 contains sections
nonresident and writeable.

Segment 60 contains sections SECTS and SECT9.
Since its
segment
number
is
above
59,
it is nonresident and
nonwriteable; changes made to the segment are lost when it
leaves and returns to memory.

Segment 65 contains section SECT2.
nonwriteable.

contains

section

SECT3;

SECT7

and

resident

SECTS.

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; it has
to be present to allow the compiler to build a list of all subprogram
nahmies. ThUiS, it can be inbsuch a Positiofn that it is nelvler exheicuhted.
T s
requ rement i s met y any group 0
subprograms a
0 f w
care
written in COBOL.
If you wish to call a non-COBOL subprogram, you must make sure that
any COBOL routines that are called by the non-COBOL subprogram have a
link to the main COBOL program if the COBOL routines are to do any
I/O.
The COBOL compiler recognizes a subprogram by its use of LINKAGE
SECTION,
ENTRY, 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.
11-3

October 1985

I
.

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
NOTE
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
that are called by the non-COBOL subprogram have a
link to the main COBOL program if the COBOL routines
are to do any I/O.
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 /J switch. You can prevent the compiler from
generating a start address for a main program by using the /I 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-4

October 1985

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
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 must have the form:
CALL {program- or entry-name} (USING identifier-l (,identlfier-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 ~1 and 77 levels and COMP items
are
already word-aligned; others can be aligned by using the
SYNCHRONIZED LEFT clause.)

11-4.1

October 1985

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS

(THIS PAGE INTENTIONALLY LEFT BLANK.)

11-4.2

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
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
subpr'ogram'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
You can define additional entry
which has the form:

identifie~-l

points

[,identifier-2] ... ].

using

the

ENTRY

statement,

ENTRY entry-name [USING identifier-l [,identifier-2] •.. ].
The specified entry-name is defined for use by CALL statements in
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 may 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) may 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 in it 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 may not have a COBOL
subprogram doing I/O which 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.
Execution of a STOP statement halts execution
program. The STOP statement has the form:
STOP {RUN or literal}.

11-5

the

entire

loaded

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
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 the user
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.
If the /SEARCH switch is appended to a file specification,
then
switch is automatically turned off after that file is searched.
example:
MYCOBL/SEARCH, COB4
searches MYCOBL.REL, but loads all of COB4.REL.

11-6

the
For

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
If the /SEARCH switch is not appended toa 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 COBO, searches MYLIBI and MYLIB2, and loads COBI.
The system library C74LIB.REL is searched automatically when LINK
loads programs compiled with COBOL.
This search occurs at the end of
loading.
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 were 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
requires
LINK to search MYCOBL.REL before
searching C74LIB.REL. The /NOUSERLIB switch can suspend the effect of
a /USERLIB switch.
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 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 .
. LOAD CBLO,CBLl,CBL2,CBL3,CBL4,CBL5,CBL6
COBOL:
CBLO
[CBLO.CBL]
[CBLl.CBL]
COBOL:
CBLI
COBOL:
CBL2
[CBL2.CBL]
COBOL:
CBL3
[CBL3.CBL]
COBOL:
CBL4
[CBL4. CBL]
[CBL5.CBL]
COBOL:
CBL5
COBOL:
CBL6
[CBL6.CBL]
LINK:
Loading
EXIT
. SAVE
CBLO saved

11-7

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
.RUN CBLO
We're at level 0 in program CBLO
calling CBL2A
CBLO
We're at level 1 in program CBL2
at CBL2A
CBL2
calling CBL5
We're at level 2 in program CBL5
CBL5 doesn't call anything
Returned to CBL2
CBL2
calling CBL6
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
calling CBL2B
CBLI
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
EXIT

11.3

at CBL2B

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 virtual address 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 virtual address space.
If the program can fit in your
virtual space, you should not define an overlay structure for it; the
monitor's page-swapping facility is faster than overlay execution.

11.3.2
A COBOL

Overlayable COBOL Programs

subprogram
following rules:
1.

structure

overlayable

observes

the

If a subprogram contains I/O verbs other than ACCEPT and
DISPLAY 7 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.

11-8

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
2.

The subprogram structure must not contain RERUN statements.

The subprogram structure must not contain reentrant code
{compiled with /R under TOPS-IO or compiled without switches
under TOPS-20 - thus users of TOPS-20 must use the /U switch
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 writeable.
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.

TEST

Figure 11-1

Example of an Overlay Structure

11-9

The
the

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
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 illegali
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 virtual address space 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

iDefine TEST. LOG
iImportant messages
iDefine TEST.OVL
iDefine TEST.MAP
iRequest diagram
iRoot link
'
iLeft branch
iLeft-left branch
iLeft-right branch
iRight branch
iDefine 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.
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:
/NODE:linkname filenames/LINK:linkname

11-10

with

string

the

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
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:

have

General-purpose I/O buffers

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.

free

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.

11-11

COBOL

PROGRAM SEGMENTS, SUBp:ROGRAMS, AND OVERLAYS

Use the following guidelines to compute the
buffers:
1.

free

memory

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 l28-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 l28-word blocks to contain
each le~el 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.

One l28-word 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
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.

Enough l28-word blocks to contain the largest of the data
or index blocks in all indexed-sequential files in the
program.

11-12

contain

a
a

largest

index

file.

key-size,

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
For example, to compute th~ buffer size for an indexed
sequential file with four levels, with 128-word index
blocks and 256-word data blocks, compute as follows:
512
256
128
128
128
256
2
4
Total

1414

Four 128-word index blocks
One 256-word data block
One ~28-word storage allocation table
block
One 128-word statistics block
One 128-word index table block
Two 128-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 during program execution:

free

memory

The size of the label-record area for a multireel file. This
size is 16 words fo~ 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,

calculate

1128 words

NOTE
This calculation reflects
only
the
requirements needed by COBOL. See also
the
SORT
User's
Guide
for
sort
requirements.
If you do not allocate sufficient free memory with the /SPACE switch,
either your program will not begin execution or it will fail 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.
11-13

PROGRAM SEGMENTS, SUBPROGRAMS, AND OVERLAYS
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 are:

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

.TY SEGPRG.TTY
PRO G RAM
C B L 0
26-0CT-78 10:59
CBLO.CBL
22-NOV-77 19:00

I-'
I-'

I
I-'
lJ1

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-74 12(600) BIS
PAGE 1

ID DIVISION.
PROGRAM-ID. CBLO.
DATA DIVISION.
WORKING-STORAGE SECTION.
01
INFO.
02
LEVMSG PIC X(15) USAGE IS DISPLAY-7 VALUE "We're at level"
02
LEVEL PIC 9V VALUE O.
02
PGMMSG PIC X(12) USAGE IS DISPLAY-7 VALUE" in program"
02
CALMSG PIC X(9) USAGE IS DISPLAY-7 VALUE" calling ".
02
RETMSG PIC X(12) USAGE IS DISPLAY-7 VALUE "Returned to "
02
B PIC X(8) VALUE"
01
PGMNAM PIC X(6) VALUE "CBLO".
01
ENDMSG PIC X(18) USAGE IS DISPLAY-7 VALUE "Execution ends in
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

sua
caL 1
26-0CT-78 10:59
caL1.CBL
22-NOV-77
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019

COBOL-74 12(600) BIS
PAGE 1
19:00

ID DIVISION.
PROGRAM-ID. CBL1.
DATA DIVISION.
WORKING-STORAGE SECTION.
01
PGMNAM PIC X(6) VALUE "CBLl".
LINKAGE SECTION.
01
INFO.
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,B,LEVMSG,LEVEL,PGMMSG,PGMNAM.
DISPLAY B,B,nCBLl doesn't call anything"
SUBTRACT 1 FROM LEVEL.
GOBACK.

NO ERRORS DETECTED

SUB
C B L 2
26-0CT-78 10:59
22-NOV-77
CBL2.CBL

I-'
I-'

I
I-'
-J

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-74 12(600) BIS
PAGE 1
19:00

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.
01
INFO.
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.
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

SUB
C B L 3
26-0CT-78 11:00
CBL3.CBL
16-NOV-77
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019

10 DIVIS ION.
PROGRAM-ID. CBL3.
DATA DIVISION.
WORKING-STORAGE SECTION.
01
PGMNAM PIC X(6) VALUE "CBL3".
LINKAGE SECTION.
01
INFO.
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,B,B,LEVMSG,LEVEL,PGMMSG,PGMNAM.
DISPLAY B,B,B,"CBL3 doesn't call anything".
SUBTRACT 1 FROM LEVEL.
GOBACK.

NO ERRORS DETECTED

......

......
I

......
CO

COBOL-74 12(600) BIS
PAGE 1
19:00

SUB
C B L 4
26-0CT-78 11:00
CBL4.CBL
16-NOV-77
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021

........I
....
\0

COBOL-74 12(600) 8IS
PAGE 1
19:00

ID DIVISION.
PROGRAM-ID. CBL4.
DATA DIVISION.
WORKING-STORAGE SECTION.
01
PGMNAM PIC X (6) VALUE "CBL4".
LINKAGE SECTION.
01
INFO.
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(S).
PROCEDURE DIVISION USING INFO.
ADD I TO LEVEL.
DIS PLA Y B, LEVMSG, LEVEL ,.PGMMSG , PGMNAM.
DISPLAY B, PGMNAM,CALMSG, "CBLI".
CALL CBLI USING INFO.
DISPLAY B,RETMSG,PGMNAM.
SUBTRACT I FROM LEVEL.
GOBACK.

NO ERRORS DETECTED

SUB
C B L 5
26-0CT-78 11:00
16-NOV-77
CBLS.CBL
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019

I D DI VI S ION .
PROGRAM-ID. CBL5.
DATA DIVISION.
WORKING-STORAGE SECTION.
01
PGMNAM PIC X(6) VALUE "CBLS".
LINKAGE SECTION.
01
INFO.
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,B,LEVMSG,LEVEL,PGMMSG,PGMNAM.
DISPLAY B,B,HCBL5 doesn't call anything".
SUBTRACT 1 FROM LEVEL.
GOBACK.

NO ERRORS DETECTED
I--'
I--'

COBOL-74 12(600) BIS
PAGE 1
19:00

SUB
CBL6
26-0CT-78 11:00
CBL6.CBL
16-NOV-77
0001
On02
0003
0004
0005
0006
0007
0008
0009
0010
OOll
0012
0013
0014
0015
0016
0017
n018
0019
0020
0021

......

......
I
N

......

COBOL-74 12(600) BIS
PAGE 1
19:00

ID DIVISION.
PROGRAM-ID. CBL6.
DATA DIVISION.
WORKING-STORAGE SECTION.
PGMNAM PIC X(6) VALUE "CBL6".
01
LINKAGE SECTION.
01
INFO.
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,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

@R LINK
*TEST/LOG/LOGLEVEL:5
*/ERRORLEVEL:5
*TEST/OVERLAY
*TEST/MAP
*CBLO,CBLI/LINK:TEST
[LNKLMN Loading module CBLO]
[LNKLMN Loading module CBLI]
[LNKLMN Loading module OVRLAY]
[LNKLMN Loading module LILOWS]
[LNKLMN Loading module CONOI2]
{LNKLMN Loading module TRACED]
(LNKLMN Loading module USRDSL]
[LNKELN ~nd of link number 0, name TEST]
*
/NODE:TEST
CBL2,CBL3/LINK:LEFT
[LNKLMN Loading module CBL2]
[LNKLMN Loading module CBL31
[LNKELN End of link number 1, name LEFT]
/NODE:LEFT
CBL5/LINK:LEFTI
[LNKLMN Loading module CBL5]
[LNKELN End of link number 2, name LEFTI]
*
/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]

Define TEST. LOG
Important msgs
Define TEST.OVL
Define TEST.MAP
Root link

;Left branch

;Left-Ieft branch
;Left-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 CBLS
We're at level 2 in program CBLS
CBLS doesn't call anything
Returned to CBL2
CBL2
calling CBL6
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 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
EXIT
@

LINK symbol map of
TEST
version 12(600)
Produced by LINK version 4(765) on 6-Dec-7B at 13:31:10

page 1

Overlay no.
D
name
TEST
0 ends at
3106 length
3107 =
4P
Low segment starts at
High segment starts at
0 ends at
3462 length
3463 =
4P
Control Block address is
3047, length
30 (octal), 24. (decimal)
441 words free in Low segment, 211 words free in high segment
322 Global symbols loaded, therefore min. hash size is 358
Start address is 400010, located in program CBLO
*************
JOBDAT-INITIAL-SYMBOLS
Zero length module
*************
LIBOL-STATIC-AREA
Low segment starts at

140 ends at

1477 length

736.

(dec imal)

140

Common

16B.
133.

(dec imal)
(decimal)

144.
148.

(decimal)
(decimal)

from SYS:OVRLAY.REL[l,4]
created by MACRO on 28-Aug-78 at 14:38:00
Low segment starts at
2170 ends at
2671 length
502 (octal) ,
322.
High segment starts at 400441 ends at 403462 length
3022 (octal) ,
1554.

(dec imal)
(dec imal)

BOUT
ERJMP
GCVEC
GTJFN
INIOV.
LOGOV.
PBOUT
REMOV.
RPACS
RUNTM

Global
Global
Entry
Global
Global
Global
Global
Global
Entry
Global

.COMM.

140

Common

length

736.

1340 (octal),
.COMM.

length

*************

from DSK:CBLO.REL[4,70] created by COBOL-74 on 6-Dec-78 at 13:29:00
Low segment starts at
1500 ends at
1747 length
250 (octal) ,
High segment starts at 400010 ends at 400214 length
205 (octal) ,

"'"

CBLO

f-'
f-'

CBLO

400022

Entry

Relocatable

*************
CBLI

from DSK:CBL1.REL[4,70] created by COBOL-74 on 6-Dec-7B at 13:30:00
Low segment starts at
1750 ends at
2167 length
220 (octal) I
High segment starts at 400215 ends at 400440 length
224 (octal) ,
CBLl

400217

Entry

Relocatable

*************
OVRLAY

104000000051
320700000000
104000000300
104000000020
402016
402617
104000000074
402045
104000000057
104000000015

Global
Global
Global
Global
Entry
Entry
Global
Entry
Global
Global

Absolute
Absolute
Absolute
Absolute
Relocatable
Relocatable
Absolute
Relocatable
Absolute
Absolute

CLOSF
ERSTR
GETOV.
HALTF
JFNS
OPENF
PSOUT
RMAP
RUNOV.
SFPTR

104000000022
104000000011
402026
104000000170
104000000030
104000000021
104000000076
104000000061
402065
104000000027

Absolute
Absolute
Relocatable
Absolute
Absolute
Absolute
Absolute
Absolute
Relocatable
Absolute

736.

LINK symbol map of

TEST

version 12(600)

104000000052
104000000014
400000
2176
2175

Absolute
Absolute
Absolute
Suppressed
Relocatable
Relocatable

page 2

OVRLAY
SIN
TIME
.FHSLF
.OVRLO
.OVRWA

Global
Global
Global
Global
Global

SOUT
%OVRLA
.OVRLA
.OVRLU

104000000053
400000037
2171
402346

Global
Global
Entry
Entry

Absolute
Suppressed
Absolute
Relocatable
Relocatable

*************
LILOWS

from SYS:C74LIB.REL[l,4]

created by MACRO on 24-0ct-78 at

8:39:00
It!
~

Zero length module

G')

*************
CON012

from SYS:C74LIB.REL[l,4] created by MACRO on 24-0ct-78 at
Low segment starts at
3036 length
2672 ends at
CN.12
GJ%OLD
GT%ADR
JS%GEN
JS%PAF
PA%PRV

Entry
Global
Global
Global
Global
Global

Relocatable
Absolute
Absolute
Absolute
Absolute
Absolute

Suppressed
Suppressed
Suppressed
Suppressed
Suppressed

COBST.
GJ%SHT
JS%DIR
JS%NAM
JS%TYP

3:
10l.

(decimal)
Global
Global
Global
Global
Global

2672
1000000
70000000000
7000000000
700000000

til

Relocatable
Absolute
Absolute
Absolute
Absolute

TRACED

til

G')

Suppressed
Suppressed
Suppressed
Suppressed

3:
til

Z
8

til

c:::

*************

I-'
I-'
N
U1

2672
100000000000
200000
70000000
1
200000000

8:39:00
145 (octal) ,

from SYS:C74LIB.REL[l,4] created by MACRO on 24-0ct-78 at
3046 length
Low segment starts at
3037 ends at

tn
It!

8:39:00
10 (octal) ,

(decimal)

G')

BTRAC.
CBDDT.
HSRPT.
SBPSG.
TRPD.

3042
3044
3042
3042
3043

Entry
Entry
Entry
Entry
Entry

Relocatable
Relocatable
Relocatable
Relocatable
Reiocatable

C.TRCE
CNTRC.
PTFLG.
SFOV.
TRPOP.

from SYS:C74LIB.REL[l,4] created by MACRO on 24-0ct-78 at
Zero length module

*************

Entry
Entry
Global
Entry
Entry

Relocatable
Relocatable
Relocatable
Relocatable
Relocatable

til
)II

*************
USRDSL

3037
3042
3045
3042
3042

0
8:39:00

<
til
~

t-1

)II

til

Index to LINK symbol map of
Name
CBLO
CBLI

Page

TEST

version 12(600)

Name

Page

Name

Page

Name

Page

CON012
LILOWS

2
2

OVRLAY
TRACED

USRDSL

page 3

"'D
~

~
::c

til
Gl

::c
til

Z
8

......

......
I

I'V
0"1

m
c
tJJ

."
~

Z
0

<:
til
~

t'1

>
t<

LINK symbol map of

TEST

version 12 (600)

ltl

page 4

Overlay no.
name
LEFT
Low segment starts at
7107 ends at
7642 length
534 =
IP
High segment starts at
3463 ends at
4466 length
1004 =
2P
Control Block address is
7577, length
30 (octal), 24. (decimal)
Path is 0
93 words free in Low segment, 211 words free in high segment
23 Global symbols loaded, therefore min. hash size is 26

*************
CBL2

from DSK:CBL2.REL[4,70) created by COBOL-74 on 6-Dec-78 at 13:30:00
Low segment starts at
7107 ends at
7356 length
250 (octal),
High segment starts at 403463 ends at 404226 length
544 (octal),
CBL2
CBL2B

403465
403766

Entry
Entry

Relocatable
Relocatable

CBL2A

168.
356.

403503

(decimal)
(decimal)
Entry

*************
CBL3

from DSK:CBL3.REL[4,70) created by COBOL-74 on 6-Dec-78 at 13:30:00
Low segment starts at
7357 ends at
7576 length
220 (octal),
High segment starts at 404227 ends at 404466 length
240 (octal),
CBL3

404231

*************

Entry

Relocatable

144.
160.

(decimal)
(decimal)

Relocatable

LINK symbol map of

TEST

version 12{600)

page 5

Overlay no.
2
name
LEFTI
Low segment starts at
7643 ends at
IP
10110 length
246 =
4467 ends at
4712 length
lP
High segment starts at
224 =
Control Block address is 10063, length
16 (octal) , 14. (decimal)
Path is 0, 1
439 words free in Low segment, 211 words free in high segment
18 Global symbols loaded, therefore min. hash size is 21

*************
CBL5

from DSK:CBL5.REL[4,70] created by COBOL-74 on 6-Dec-78 at 13:30:~O
Low segment starts at
7643 ends at
10062 length
220 (octal),
High segment starts at 404467 ends at 404712 length
224 (octal),
C8L5

404471

*************

.......
.......
I
N

Entry

Relocatable

144.
148.

(decimal)
(decimal)

LINK symbol map of

TEST

version 12 (600)

page 6

LEFT2
Overlay no.
3
name
Low segment starts at
10112 length
7643 ends at
250 =
IP
High segment starts at
4467 ends at
5204 length
516 =
IP
Control Block address is 10065, length
16 (octal) , 14. (decimal)
Path is 0, 1
437 words free in Low segment, 211 words free in high segment
19 Global symbols loaded, therefore min. hash size is 22
*************

CBL6

from DSK:CBL6.REL[4,70] created by COBOL-74 on 6-Dec-78 at 13:30:00
Low segment starts at
7643 ends at
10064 length
222 (octal),
High segment starts at 404713 ends at 405204 length
272 (octal),
CBL6

404715
*************

Entry

Relocatable

146.
186.

(decimal)
(decimal)

LINK symbol map of

TEST

version 12(600)

page 7

RIGHT
Overlay no.
name
Low segment starts at
7107 ends at
7356 length
250 =
IP
2P
High segment starts at
3463 ends at
5454 length
1772 =
7331, length
16 (octal) , 14. (dec imal)
Control Block address is
Path is 0
273 words free in Low segment, 211 words free in high segment
19 Global symbols loaded, therefore min. hash size is 22
*************

CBL4

from DSK:CBL4.REL[4,70] created by COBOL-74 on
6-Dec-78 at 13:30:00
Low segment starts at
7107 ends at
7330 lE:ngth
222 (octal),
High segment starts at
405205 ends at
405454 length
250 (octal),
CI'lL4

405207
*************

.......

.......
I

Entry

Relocatable

146.
168.

(dec imal)
(dec imal)

Index to overlay numbers of TEST
Overlay Page

Overlay Page

3
4

Index to overlay names of TEST

w
I--'

page 8

Overlay Page

version 12(600)

Name

Page

Name

Page

Name

Page

Name

Page

LEFT
LEFTl

4
5

LEFT2

RIGHT

TEST

{End of LINK map of

I--'
I--'

version 12(600)

TEST]

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

entry-name

is the name of the entry point you want to call.

string

is one or
more
procedure-names.

identifiers,

generated

literals,

the

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 i£ 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 tQ the called subprogram;
using a literal passes the
literal to the subprogram; using ~ 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 FORTRAN SUBPROGRAMS

When the COBOL compiler finds an ENTER FORTRAN statement, it generates
a call for the named subprogram. If the ENTER statement contains a
12-1

October 1985

CALLING NON-COBOL SUBPROGRAMS
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.
NOTE
I/O operations can be performed only in subprograms
that are written in the same language as the main
program.
In addition, APR trap handling is performed
in a manner consistent with the language used in the
main prog ram.
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:
10 DIVISION.

PROGRAM-ID. CFSQRT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 INPUT-NUMBER USAGE COMP-1.
01 ANSWER USAGE COMP-l.
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-MESSAG E.
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=1
EXMSG=2
IF(INPUT.LT.0) RETURN ERRMSG
IF(INPUT.EQ.0) RETURN EXMSG
ANSWER=SQRT(INPUT)
RETURN
END
12-2

October 1985

CALLING NON-COBOL SUBPROGRAMS
In the following lines, these two source programs 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 alternate 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 Eexcution]
Type a positive integer.
4

2.0EO
Type a positive
3
1.7320508EO
Type a positive
2
1.4142136EO
Type a positive
1
1.OEO
Type a positive

integer.
integer.
integer.
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
0
1 Code 1
Effective Address (E)
/
1=======================================================1
o
8 9
12 13
35
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 CaMP 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 or DISPLAY-7 item, 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 7 for
DISPLAY-7.
The second word of the descriptor is of the form:
bit 0

numeric flag

bit 1

signed number flag

bit 2

figurative constant flag

bit 3

literal flag

bits 4-11

reserved

bit 12

flag for Ps preceding decimal point in PICTURE

bits 13-17

number of decimal places (if bit
number of Ps (if bit 12 is 1)

bits 18-35

number of bytes in the item

0),

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.
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

MACRO

;-Arglength"O
;<4B12>&<Address of
;<4B12>&<Address of
;<7B12>&<Address of
;<7B12>&<Address of

12-4

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
MSQRT
ENTRY
MSQRT
EXTERN SQRT
SKIPN 1,@O(16)
JRST ZERO
JUMPL 1,NEG

MOVEM 1,ARG
MOVEM 16,SAVPTR
MOVEI 16,1+[-1,,0
Z 4,ARG]
PUSHJ 17,SQRT
MOVE 16,SAVPTR
MOVEM 0, @1 (16)
POPJ 17,
ZERO:
MOVEI 1,@3(16)
MOVEM 1, 0 ( 17)
POPJ 17,
NEG:
MOVEI 1,@2(16)
MOVEM 1, 0 ( 17)
POPJ 17,
ARG:
BLOCK 1
SAVPTR: BLOCK 1
END

;Skip if not zero
iTo zero routine
iTo negative routine
iFall into positive routine
iSave arg in reg 1
iSave 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-5

CALLING ~ON-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 will yield the same output if run under
TOPS-10.
@EXE CMSQRT.CBL,MSQRT.MAC,SYS:FORLIB.REL/SEARCH
COBOL: CMSQRT [CMSQRT.CBL]
MACRO: MSQRT
LINK:
Loading
[LNKXCT CMSQRT Excution]
Type a positive integer.
4

2.0EO
Type a positive integer.
3

1.7320508EO
Type a positive integer.
2

1.4l42l36EO
Type a positive integer.
1

1.0EO
Type a positive integer.
-1

No negative numbers, please.
Type a positive integer.

Thank you.
EXIT
@

12-6

CHAPTER 13
IMPROVING PERFORMANCE OF COBOL-74 PROGRAMS

Normally, the code generated by the COBOL-74 compiler is adequately
efficient.
However, since there are certain COBOL-74 constructions
for which efficient code is not generated, it is possible to write
prosrams that perform poorly.
If your programmed application performs
inefficiently, you are left with the following alternatives:
1.

Assume that a higher-performance
compiler will solve the problem

version

Purchase new or faster

Redesign the entire program

Rewrite only the bad portions of the program

the

COBOL-74

hardw~re

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 may 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
optimized programs.
13-1

IMPROVING PERFORMANCE OF COBOL-74 PROGRANS
Each computer system is different.
Therefore, it is likely that
installation programming standards will reflect, to some extent,
practices which 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 will affect 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 economics. 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 will promote
virtually every system and should be encouraged.

efficiency

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 will be 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, he/she 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 will 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-74 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

Copies of the source program and supporting software

Enough data to make this program run long enough to measure,
and short enough to endure:
10 to 15 minutes is usually
sufficient.

Files for output verification

Access to the measurement tools

A notebook to record all observations,
results (see Section 13.1.5).

13.1.2

(lower elapsed or CPU time)

(see Section 13.1.2)
measurements,

and

What Tools are Available

There are some tools that are part of the system software;
you may
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:
•

COBDDT-

For users of TOPS-lO and TOPS-20
7.3 and 13.2

•

SET WATCH - For users of TOPS-IO only
see
Operating System Commands Manual

13-3

see

Sections

the

TOPS-lO

IMPROVING PERFORMANCE OF COBOL-74 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 will use
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 will enable you to make
better use of the elapsed time statistics.

(original)
Run the unaltered
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 will aid 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
may 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 Performance.)
4.

Run a COBDDT histogram to determine its runtime statistics.
The histogram will aid 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
improve the program.

believe

will

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 l3.i.5, Documentation.)

13-4

changes

this

you

run

with

those

facts,

and

hunches.

(See

IMPROVING PERFORMANCE OF COBOL-74 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 criteria 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, only changes in excess of
5% can be considered relevant.
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 easily predictable.

13.1.5

Documentation

It is a good practice to document everything you have done during
program optimization.
You will want to improve other programs, and
the notes you take for the first attempt will 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 la-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

COB DDT histogram

Any observations about system performance

13-5

program,

and

IMPROVING PERFORMANCE OF COBOL-74 PROGRAMS
9.

Any other statistics collected, feelings, hunches, and
perceptions

other

The documentation need not and should 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-lO Operating System Commands manual
is also recommended for users of TOPS-lO..
This section will not
attempt to redo anything that has already been done. It attempts only
to present information relevant to program optimization.

13.2.1

COB DDT

This section discusses COBDDT as used for
evaluating
program
performance. Therefore, only the histogram feature is described. The
COB DDT histogram provides you with the following information for each
procedure that was executed in your program (see Figure 13-1, Sample
COB DDT 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
2PlO
3RD
3PO
XDDT4B.HIS
OVERHEAD:

ELAPSED:
Figure 13-1

0.002

CPU:

Sample COBDDT Histogram

13-6

0.002

IMPROVING PERFORMANCE OF CQBOL-74 PROGRAMS
13.2.1.1 The ENTRIES Column - The information listed in the ENTRIES
column of the histogram helps you to set your prioritieQ 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.)

done

effectively

(See Section 13.5, Efficient

Often, the numbers will guide you into understanding how to order your
decision lists. For example:
Suppose P-l was entered 1000 times, P-2 was en~ered 500 times,
and these paragraphs are chosen via a decision list that looks
like this:
8-1.

IF A =

S-2.

IF A == "00" GO TO P-l.

" GO TO P-2.

It is apparent, then, that the order of S-1
reversed because A is usually 00.

and

S-2

sho~ld

Also, based on the number of records processed, unexpected
certain paragraphs should be accounted for.

counts

Do not be afraid to add new paragraph names to the prog~am. 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 up. Generally, if you can cut the ~PU
time, the elapsed time will also drop and the application will perform
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 ti~e &nd 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 and the
monitor.

13-7

IMPROVING PERFORMANCE OF COBOL-74 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 will improve performance. Either the program cannot
be improved any further, or other techniq~es are needed.

13.2.1.3 ELAPSED Column - In a lightly loaded system, the elapsed
time can be a guide to the ef(ec~ive 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
relative or ISAM reads and updates.
Inspection of the blocking
revealed that while the files were blocked to conserve disk space,
large amounts of data was being transferred (1 block) when the desired
object was to update I 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 ord~r.

13.3

USING THE CORRECT DATA TYPE

Understanding the various data types available is extremely important
because there are so many of them.
COBOL-74 offers you three
different DISPLAY types and several COMPUTATIONALS.
Each data type
will offer some advantages and some disadvantages. It is necessary to
understand these in order to maxi~ize 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 which 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 may 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-74 PROGRAMS
EBCDIC processing is going to be somewhat slower than either ASCII or
SIXBIT because each character takes more space. As an example, a
129-character record would occupy:
1.

39 words in EBCDIC

24 words in ASCII

29 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 29% more efficient than EBCDIC, respectively.
However, there is an anomaly caused by having full words of data.
This is generally moved at word speed which is much faster than byte
speed.
It is often worth while to fill a data item with extra
characters to make it a multiple of a full word. Also, moves that can
be done 2 characters at a time one faster than those moves that can be
done 1 character at a time.
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 usage 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 existance 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 usage 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 existance of a vertical form
(normally a line feed)
character
(or several such characters).
Thus, when reading ASCII
files, it is necessary to read them 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.
13-9

IMPROVING PERFORMANCE OF COBOL-74 PROGRAMS

ASCII is the standard data type for text files.
Files created by
editors
which
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.
In
addition, blank lines are ignored or skipped over, unless they contain
space characters. However, unless the full character set capabilities
of ASCII (128 with lowercase plus line control) are necessary or the
data is coming from or going to an ASCII peripheral, conversion to
SIXBIT files is probably preferable.

13.3.4

SIxaIT

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. Basically, 64 characters allows for uppercase,
numerics, and punctuation. It does not allow for lowercase, d~vice
control characters, or special graphics.
Most installations put the bulk of their files into SIXBIT due to the
storage
economy
and the processing efficiency.
It is highly
recommended whenever possible.

13.3.5

COMPUTATIONAL

There are several types of computational data types available
COBOL programmer including:

the

COMPUTATIONAL-3, the four bit relative of EBCDIC

COMPUTATIONAL, internal binary (35 bits plus sign)

Double-word COMPUTATIONAL, automatically invoked when the
number of digits desired is greater than l~ (7~ bits plus
sign)

COMPUTATIONAL-I, floating point (the hardware supports double
precision
floating
point, but COBOL does not, except
internally for the COMPUTE verb.)

Aside from the usage 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.

l3-l~

then

October 1985

IMPROVING PERFORMANCE OF COBOL-74 PROGRAMS
13.4

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.4.1

Counter, Indexes, Subscripts

In DIGITAL COBOL indexes and subscripts are identical (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 that must be observed:
1.

If the number of digits is greater than 10, it becomes
double-word computational, and all arithmetic is done with
double word instructions. 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 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 require 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 variable length text (for example those created by
TECO or TV) and for line control. It suffers from the necessity of
processing 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 128-word sector boundaries.
Thus blocking
inefficiently could waste considerable space.

13-11

IMPROVING PERFORMANCE OF COBOL-74 PROGRAMS
If you block disk records, remember to count the length descriptor
words on SIXBIT, variable length EBCDIC records, and carriage-return,
line-feed in ASCII.

13.4.4

DATA DIVISION Space Restrictions

Each DATA DIVISION item in the, program being created generates an
entry within an internal table (DATAB). The range of the table is
from ~~~~~ to 77777, or 32768 words. Each entry is seven words long.
Therefore, the maximum number of items in the DATA DIVISION is 32768
divided by 7, or 468~ items (one word is used as overhead).
This
includes all data items described in the FILE SECTION and the
WORKING-STORAGE SECTION.
Conditional items (level 88) are
not
included and are therefore, excluded. For example, the following data
description generates four entries in DATAB:
~1

ITEM-A.
02 ITEM-B.
~4
ITEM-C
~4
ITEM-D

PIC X.
PIC X.

However, the following data description generates only
DATAB:
01

ITEM-A

one

entry

PIC XX.

Both examples above encompass two bytes of data in the data area of
the program.
The first example requires four times as much space in
DATAB as the second example.
Therefore, the limits of the DATA
DIVISION are governed by how you describe the data items, not by how
much data you need to store.
Subscripted and indexed data items generate nine word entries in
DATAB.
An INDEXED BY clause in an indexed data item generates an
additional seven word DATAB entry. Each edited data item generates a
13 word entry in DATAB.
An item description that contains SEARCH keys generates a DATAB entry
of 14 words or more. For example, ITEM-A below generates a 15 word
entry:
~1

ITEM-A OCCURS l~ TIMES
ASCENDING KEY IS ITEM-B, ITEM-C.
~2
ITEM-B PIC X.
02 ITEM-C PIC X.

If your program exceeds the maximum number of data items in
DIVISION, you must either:

DATA

FILE

Rework the data
item
entries
WORKING-STORAGE SECTION, or

Remove some or all the arrays and set them up within
subprograms to be CALLed or ENTERed by your main program.

13-12

within

the

October 1985

IMPROVING PERFORMANCE OF COBOL-74 PROGRAMS
13.5

EFFICIENT CODING CONVENTIONS

This section contains a listing of some practical coding practices
that have proven efficient. You can demonstrate that these techniques
are more efficient with short programs that execute these sequences a
large number of times. You can also look at the MACRO expansion of
the program to see why things are different.

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 usage 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 may be called.
The simplest way to insure that data is aligned is to define it at
either 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

Usage 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} COMP.
02 THE-DATA PIC XXXXXXXX.
77 THE-TABLE-COUNT PIC S9(10} COMP.
The sequence
MOVE THE-COUNT(IDX} TO THE-TABLE COUNT.
IF THE-TABLE-COUNT
3 GO TO P-1.
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}
3 GO TO P-1.
IF THE-COUNT (IDX) = 4 GO TO P-l.

13-12.1

than

the

IMPROVING PERFORMANCE OF COBOL-74 PROGRAMS

(THIS PAGE INTENTIONALLY LEFT BLANK.)

13-12.2

IMPROVING PERFORMANCE OF COBOL-74 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 via subscripts. For example:
01 THE-TABLE OCCURS 20 TIMES.
02 THE-CNT PIC 89(10) COMPo
02 THE-DATA PIC XXXXXXX.
01 THE-TABLE-ENTRY.
02 THE-TABLE-CNT PIC 89(10) COMPo
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 here and it pays to eliminate it.

13.5.3

Incrementing Counters

COBOL-74 provides three ways of incrementing counters.
the same function in different ways. For example:

Each

performs

77 COUNTER PIC S9(10) COMPo
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 will never become negative. If they are not
signed, additional instructions will be generated 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.
However, it suffers from the fact that it requires some information to
be posted upon entry to a routine and cleared upon exit from that
routine. COBOL-74 is fussy about the nesting of PERFORMs so that
there is a 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 sa~e 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 programs
use PERFORMs.
13-13

which

IMPROVING PERFORMANCE OF COBOL-74 PROGRAMS
Example 13-1
SET IDX TO
PARI.

PERFORM PARI 100 TIMES.

SET IDX UP BY 1.
IF TABLE(IDX)
ABLE MOVE 6 TO FOO.

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
word being accomplished by each paragraph is small.

13.5.5

Use of the INSPECT Statement

Use of the INSPECT 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 INSPECT statement see Part 2, COBOL Language
Reference Material.

13.5.6

Data Movement

This is just an observation on data movement. On a character-oriented
machine, there is generally a machine instruction with a name
something like MVC (for move characters). On such a system, there is
a fixed cost for picking up the instruction, plus a variable cost
which is a function of the number of characters. TOPS-IO and TOPS-20
act similarly, but the fixed cost is higher.
Especially if data conversion is implied (ASCII to SIXBIT), then it is
more efficient to change all fields in a record with one move
statement than to move the data field by field.
If the compiler
recognizes that data conversion is not necessary, and that the records
are aligned, then efficient in-line code can be generated.
Because
the fixed cost to move any number of characters is higher on TOPS-IO
and TOPS-20 than on some systems, programmers should 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-74 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 ~ highly used spot:
IF AB
IF AB
IF AB

" " MOVE Z TO ODD.

"I" MOVE Z TO FFF.

= "2" MOVE Z TO GGG.

In this type of code all statements get executed
though only one actually does anything useful.

13.5.8

each

time,

even

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 > iooo GO TO ZIP.
GO TO LOOP.

While this is not bad coding, the program will only go 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
DIFFERENCES BETWEEN COBOL-68 AND COBOL-74

The terms COBOL-68 and COBOL-74, which are used in the following text,
refer
to DIGITAL's implementation of ANS-68 and ANS-74 COBOL,
respectively. Any references to ANS COBOL will be made clear by the
use of the initials "ANS".
COBOL-74 differs from COBOL-68 in the following ways:
1.

A stroke (slash, "/", virgule)
in the continuation area
(seventh character position) of a line causes page ejection
of the compilation listing.
(The line is treated as a
comment.) <lNUC (1) New feature to COBOL-74>

Two contiguous quotation marks may be used to represent a
single quotation mark character in a nonnumeric literal.
<lNUC (1 ) New feature.>

REMARKS paragraph is deleted.
replaced by the comment line.>

Continuation of Identification Division comment-entries must
not have a hyphen in the continuation indicator area. <lNUC

<lNUC

(2 )

Function

was

(2) >

PROGRAM COLLATING SEQUENCE clause
specifies
that
the
collating sequence associated with alphabet-name is used in
nonnumeric comparisons. <lNUC (1) New feature.>

SPECIAL-NAM~S

Alphabet-name clause relates a user-defined name to
a
specified collating sequence or character code set (ANSI,
native, or implementor-specified). <lNUC (1) New feature.>

Alphabet-name clause:
the literal phrase
specifies
user-defined collating sequence. <2NUC (1) New feature.>

All items which are immediately subordinate to a
must have the same level-number.
<lNUC (2»

10.

Object of a REDEFINES clause can be subordinate to an item
described with an OCCURS clause, but must not be referred to
in the REDEFINES clause with a subscript or an index.
<lNUC
(1) New feature.>

11.

An asterisk used as a zero suppression symbol in a PICTURE
clause and the BLANK WHEN ZERO clause may not appear in the
same entry. <lNUC (2»

paragraph:
IlL",
"/", and "=" may not be
specified 1n the CURRENCY SIGN clause.
<2NUC
(2) This
restriction did not exist in X3.23-l968.>

A-I

group

a
item

DIFFERENCES BETWEEN COBOL-68 AND COBOL-74
12.

Alphabetic PICTURE character-string may contain the character
B.
<lNUC (1) New feature.>

13.

Stroke (/) permitted as an editing character.
feature.>

<lNUC (1)

14.

SIGN clause allows the specification of
<lNUC (1) New feature.>

sign

15.

In the Procedure Division a section may contain zero or
paragraphs
and
a paragraph may contain zero or
sentences.
<lNUC (1) New feature.>

16.

In relation and sign conditions, arithmetic expressions must
contain at least one reference to a variable.
<lNUC (2»

17.

Comparison of nonnumeric operands:
If one of the operands is
described as numeric, it is treated as though it were moved
to an alphanumeric item of the same size and the contents of
this alphanumeric item were then compared to the nonnumeric
operand.
<lNUC (3»

18.

Abbreviated combined relation condition: When any portion is
enclosed in parentheses, all subjects and operators required
for the expansion of that portion must be included within the
same set of parentheses.
<2NUC
(2)
No such restriction
appeared in X3.23-l968.>

19.

Abbreviated combined relation
condition:
If
NOT
immediately
followed
by a
relational operator,
it
interpreted as part of the relational operator.
<2NUC (2)
X3.23-l968, NOT was a logical operator in such cases.>

20.

Class condition:
The numeric test cannot be used with a
group item composed of elementary items described as signed.
<lNUC (3) >

21.

In an arithmetic operation, the composite of operands must
not contain more than 18 decimal digits.
However, if your
COBOL-74 compiler makes use of the Business Instruction Set,
the maximum is 36 digits.
<lNUC (2) X3.23-l968 specified
limits only for ADD and SUBTRACT.>

22.

ACCEPT identifier FROM DATE/DAY/TIME allows the programmer to
access the date, day, and time.
<2NUC (1) New feature.>

23.

COMPUTE statement:
feature.>

24.

DISPLAY statement:
If the operand is a numeric
must be an unsigned integer.
<lNUC (2»

25.

DIVIDE statement:
the INTO identifier series and the
identifier series.
<lNUC (2»

26.

DIVIDE statement:
the remainder item can be
<2NUC (1) New feature.>

27.

GO TO statement:
the word TO is not
X3.23-l968 requires the word TO.>

28.

EXAMINE statement and the special register TALLY
were
deleted.
<lNUC
(2)
Function was replaced by the INSPECT
statement.>

the identifier

A-2

the

series.

New

position.

<2NUC

more
more

(1)

literal,

is
is
In

New
it

GIVING

numeric-edited.

required.

<lNUC

(1)

DIFFERENCES BETWEEN COBOL-68 AND COBOL-74
29.

INSPECT statement provides ability to count or replace
occurrences of single characters or groups of characters.
<lNUC (1) New feature.>

30.

MOVE statement: A scaled integer item (i.e., the rightmost
character of the PICTURE character-string is a P) may be
moved to an alphanumeric or alphanumeric~edited item.
<lNUC
. (1) New feature.>

31.

MULTIPLY statement: the BY identifier series and the
identifier series. <2NUC (1) New feature.>

32.

PERFORM statement: There is no logical difference to the
user between fixed and fixed overlayable segments. <lNUC (1)
X3.23-l968 did not permit fixed overlayable segments to be
treated the same as a fixed segment.>

33.

PERFORM statement: Control is passed only once for each
execution
of
a Format 2 PERFORM statement (i.e., an
independent segment referred to by such a PERFORM is made
available in its initial state only once for each execution
of that PERFORM statement). <fNUC,lSEG (3»

34.

STOP statement: If the operand is numeric literal,
be an unsigned integer. <lNUC (2»

35.

A data description entry with an OCCURS 'DEPENDING clause may
be followed within that record only by entries subordinate to
it. That is, only the last part of the record may have a
variable number of occurrences. <2TBL (2) This rule did not
appear in X3.23-l968.>

36.

When a group item, having subordinate to it an entry that
specifies Format 2 of the OCCURS clause, is referenced, only
that part of the table area that is defined by the value of
the operand of the DEPENDING phrase will be used in the
operation. That is, the actual si~~ of a variable length
item is used, not the maximum size. <2TSL (2»

37.

The subject of the condition in the WHEN phrase of the SEARCH
ALL statement must be a data item named in the KEY phrase of
the table; the object of this condition may not be a data
item named in the KEY phrase. <2TBL (2) X3.23-1968 specified
that either the subject or object could be a data item named
in the KEY phrase.>

38.

SORT statement:
COLLATING SEQUENCE phrase provides the
ability to override the program collating sequence. <2SRT
(1) New feature.>

39.

No more than one file-name from a multiple
appear in a SORT statement. <2SRT (2»

file

40.

Segment-numbers permitted in DECLARATIVES.

<lSEG (1»

41.

ACCESS MODE IS DYNAMIC clause: provides ability to access a
file
sequentially
or
randomly
in the same program.
<2REL,2INX (1) New feature.>

42.

ACTUAL KEY clause deleted.

43.

RELATIVE KEY clause added for relative
(1) New featue.>

A-3

GIVING

reel

must

can

«2»
organization.

<lREL

DIFFERENCES BETWEEN COBOL-68 AND COBOL-74
44.

FILE-LIMITS clause deleted.

«2»

45.

PROCESSING MODE clause deleted.

«2»

46.

ORGANIZATION IS RELATIVE clause.

47.

ORGANIZATION IS SEQUENTIAL clause.

48.

ORGANIZATION IS INDEXED clause.

49.

MULTIPLE REEL/UNIT clause deleted.

«2»

50.

RESERVE ... ALTERNATE AREAS deleted.

«2»

51.

RESERVE integer AREAS to allow the user to specify the exact
number
of areas to be used.
<lSEQ,lREL,lINX (1) New
feature.>

52.

The data-name option of the LABEL RECORDS clause was deleted.
<lSEQ,lREL,lINX (2) X3.23-l968 provided for user-defined
label records.>

53.

LINAGE clause permits programmer definition of
size. <2SEQ (1) New feature.>

54.

CLOSE ... FOR REMOVAL statement.

55.

DELETE statement.

56.

OPEN REVERSED positions the file at its end.

<2SEQ (2»

57.

OPEN EXTEND statement adds
<2SEQ (1) New feature.>

eKisting

58.

The OPEN REVERSED statement applies to all devices that claim
support for this function.
<2SEQ (1) X3.23-l968 restricted
the application of this phrase.>

59.

READ statement: AT END phrase required only if no applicable
USE
AFTER
ERROR/EXCEPTION
procedure
specified.
<lSEQ,lREL,lINX (1) New feature.>

60.

READ statement: INVALID KEY phrase required only if no
applicable USE AFTER ERROR/EXCEPTION procedure specified.
<lREL,lINX (1) New feature.>

61.

READ ... NEXT statement: used to retrieve the next logical
record from a file when the access mode is dynamic. <2REL,
2INX (1) New feature.>

62.

REWRITE statement.

63.

SEEK statement was deleted.

64.

START statement provides for logical positioning within a
relative or indexed file for sequential retrieval of records.
<2REL, 2INX (1) New feature.>

65.

USE statement: the label processing options were deleted.
<lSEQ,lREL,lINX (2) X3.23-l968 provided for the processing of
user-defined labels.>

logical

page

<2SEQ (I) New feature.>

records

file.

<lSEQ,lREL (1) New feature.>

A-4

«2»

DIFFERENCES BETWEEN COBOL-68 AND COBOL-74
66.

USE ... ERROR/EXCEPTION
feature.>

statement.

67.

Recursive
invocation
<lSEQ,lREL,lINX (2»

68.

WRITE statement: INVALID KEY phrase required only if no
applicable USE AFTER ERROR/EXCEPTION procedure specified.
<lREL,lINX (1»

69.

WRITE statement: BEFORE/AFTER PAGE phrase
to skip to top of a page. <lSEQ (1»

provides

70.

WRITE statement:
feature.>

<2SEQ

71.

CALL identifier statement.

USE

END-OF-PAGE

A-5

<lSEQ,lREL,lINX
procedures

phrase.

(1)

New

prohibited.

ability
(1 )

New

DIFFERENCES BETWEEN COBOL-68 AND COBOL-74
Note A.

(RELATIVE files)

The RANDOM file access method of COBOL-68 has been replaced by
the RELATIVE file organization in COBOL-74.
This means a number
of syntactic changes, but in addition it means some important
semantic changes as well.
In the Environment Division, the syntactic changes include the
substitution of an ORGANIZATION IS RELATIVE clause for the old
ACCESS IS RANDOM clause, and the substitution of the ACCESS IS
SEQUENTIAL / RANDOM / DYNAMIC
for
the
old
PROCESSING
IS
SEQUENTIAL clause.
The FILE LIMITS clause goes away.
The ACTUAL
KEY clause is replaced by the RELATIVE KEY clause, although the
meaning of the key value is identical to that in COBOL-68.
The Data Division is unchanged.
The Procedure Division verbs are changed considerably.
OPEN,
CLOSE and the USE ON ERROR procedures are unchanged.
The WRITE
statement is unchanged in syntax, but its meaning is restricted
to writing a record into an "empty" position in the file.
If the
record position in the file
into which the record is being
written is already "occupied",
the WRITE must not alter the
existing contents of the record position, but must instead take
the INVALID KEY path (or execute a USE procedure).
In order to
change the contents of an "occupied" record position one either
has to REWRITE it or DELETE and WRITE it. Attempting to DELETE
or REWRITE a record position which is already "empty" causes the
INVALID KEY path to be taken.
In other words, each record
position of the relative file must have an "occupied" state,
which can be recognized by the object time I/O routines.
There
is also a START verb which can be used to position at or beyond a
given record position.
Then sequential READs or WRITEs may be
done.
The sequential READ is done with a READ NEXT statement,
whereas the random READ is just a READ statement. The sequential
READ uses the AT END phrase (which is optional)
and the random
READ uses the INVALID KEY phrase (also optional).
Thus, there
are not only many syntactic changes in existing verbs,
but new
verbs, and a markedly different approach to the file's contents.
Note B.

(INDEXED files)

The INDEXED I/O module of COBOL-74 is 'fairly similar to that of
COBOL-68.
There are syntactic differences in the Environment
Division and in the Procedure Division.
COBOL-68 had a SYMBOLIC KEY clause to designate the key used in
READ,
WRITE,
REWRITE and DELETE statements. COBOL-74 does not
have a SYMBOLIC KEY clause.
The random READ statement has a "KEY
IS identifier"
phrase which supplies a key value.
The WRITE
statement uses key values from the record being written, and the
DELETE and REWRITE statements must follow a successfully executed
READ and use the "remembered" key fro~ that operation.
COBOL-74 includes a START statement in the Procedure Division
which positions the record pointer in the file specified.
Also,
the READ NEXT statement is used to do sequential reading through
the existing records of the file.
Note C.

(Segmentation and PERFORM rules)

In COBOL-74, sections in the Procedure Division can have segment
numbers
(called "priority numbers" in COBOL-68) that range from
00 to 99.
Segments with numbers 50 and above are called
A-6

DIFFERENCES BETWEEN COBOL-68 AND COBOL-74
"independent"
segments • . Also,
the programmer can specify a
SEGMENT LIMIT IS clause with a value between 00 and
49.
This
divides the segments with.numbers below 50 into two groups.
Thus
all segments fall into one of three groups:
1.

Below the segment limit, called "fixed permanent",
always resident.

that

is,

From the segment limit to
49,
called "fixed overlayable",
that
is, each segment number defines an overlay and the code
in such a segment is brought into memory only as needed.
Any
GO TOs which have been ALTERED will
retain their most
recently set values when they are brought into memory.

From 50 up,
called
"independent",
that
is,
each segment
number defines an overlay and the code is brought into memory
only as needed.
Any GO TOs which have been altered will
be
reset each time the segment is brought into memory.

The restrictions on the ALTER and PERFORM verbs have not
really
changed from ANS-68 COBOL to ANS-74 COBOL but they have become
more explicit.
COBOL-74 implements the restrictions on the ALTER
statement correctly
(by either standard)
but
implements the
restrictions on PERFORM in a manner different from either
standard.
COBOL-74 uses the segment-limit value as the dividing
line for the PERFORM restrictions, whereas the standards use
the
segment number 50 as the dividing line.
When you do not specify
a segment limit value the compiler supplies 50 as
the default,
making the restrictions the same for COBOL-74 and the standards.
However, when you do supply the segment limit value,
COBOL-74
applies
the
rules
in such a
way as to make all overlayable
segments behave the same.
(In the Journal of Development,
the ALTER statement has been
abolished and segment numbers are restricted to 00 to 49, hence
all these rules go away, but the JOD change occurred after
the
ANS-74 COBOL standard was frozen for publication.)
Note D.

(CALL and CANCEL rules)

There are many differences between COBOL-74's
CALL and CANCEL and the ANS-74 COBOL standard.

implementation

The syntax is different for both statements in that COBOL-74
interprets a
user-word as a
program-name with or without
quotes around it, whereas ANS-74 COBOL interprets a user-word
as a data-name in which is stored the program-name.

In ANS-74 COBOL there is an ON OVERFLOW
clause
for
handling
instances in which
there
is insufficient memory
space available to load the dalled subprogram.
This does not
exist in COBOL-74.

not
COBOL-74 allows alternate entry points to subprograms,
the
ENTER
allowed
in ANS-74 COBOL,
and COBOL-74 uses
user
to
call
(MACRO/FORTRAN)
statement to allow the
subprograms written in those languages.

The semantics are very different.
COBOL-74 uses LINK
to
construct a tree-structured overlay scheme from user-supplied
commands to LINK.
When a subprogram is CALLed, the branch of
the
tree up to that subprogram is loaded along with the
subprogram.
Likewise, when a subprogram is CANCELled,
the
entire tree beyond that subprogram is cancelled.
ANS-74
A-7

DIFFERENCES BETWEEN COBOL-68 AND COBOL-74
COBOL recognizes no such tree structure, and allows loading
and cancelling to occur strictly on a subprogram basis. In
addition, LINK allows more than one subprogram to be linked
into a single overlay, with the effect that a cancel of one
of the subprograms in the overlay results in a cancel of all
subprograms in that overlay.

Note E.

(COpy statement)

The double equal sign (==) is a syntactic element new to ANS-74
(but not new to users of COBOL-68 version 12) used to set
off pseudo-text. This notation is used to delimit pieces of text
which you wish to replace or insert with the COpy verb.
It is
not necessary to use the double equal sign if your text-string is
a literal or a data-name, but if you wish to replace complex
pieces of text the double equal sign will serve as a clear
delimiter, and you may include the notation any time you wish
without risk of confusing the compiler.
COBOL

APPENDIX B
COBOL RESERVED WORDS

In the listing below, words not preceded by symbols are reserved in
both ANSI-74 Standard COBOL and in DECsystem-lO and DECSYSTEM-20
COBOL.
Words preceded by '*' are reserved in ANSI-74 Standard COBOL
but not reserved in DECsystem-lO and DECSYSTEM-20 COBOL. Words
preceded by '**' are reserved in DECsystem-lO and DECSYSTEM-20 COBOL
but not reserved in ANSI-74 Standard COBOL.
Reserved words may not be
used as user-created names.
A

ACCESS

ACTUAL

ADD

*ADDRESS

ADVANCING

AFTER

ALL

**ALLOWING

ALPHABETIC

ALSO

ALTER

ALTERNATE

AND

ARE

AREA

AREAS

**ASCII

ASSIGN

ASCENDING
AT

**ANY

AUTHOR
B

BEFORE

BEGINNING

BLANK

BLOCK

BYTE

**BINARY
BOTTOM

**CALL

**CANCEL

**CHANNEL

CHARACTER

CHARACTERS

**CLASS

*CLOCK-UNITS

COBOL

CODE

CODE-SET

COLLATING

B-1

COBOL RESERVED WORDS
COLUMN

COMMA

COMP

**COMP-l

**COMMUNICATION
**COMP-3
**COMPUTATIONAL-l

**COMPILE

COMPUTATIONAL

**COMPUTATIONAL-3

COMPUTE

CONFIGURATION

**CONSOLE

CONTAINS

CONTROL

COpy

CORR

**COUNT

**CURRENCY

**DATABASE-KEY

**DATE

DATE-WRITTEN

**DBKEY

*DEBUG-CONTENTS

*DEBUG-ITEM

*DEBUG-LINE

*DEBUG-NAME

*DEBUG-SUB-l

*DEBUG-SUB-2

*DEBUG-SUB-3

DEBUGGING

DECIMAL-POINT

DECLARATIVES

**DECSYSTEM-1O

CONTROLS
CORRESPONDING
CURRENT
D
DATA
**DATE-COMPILED

**D~CSYSTEM-20

**DECSYSTEM1O

**DELETE

DELIMITED

**DENSITY

DEPENDING

.**DEFERRED
DELIMITER
**DEPTH

DESCENDING

DESTINATION

DISABLE

DISPLAY

**DISPLAY-6

**DISPLAY-7

**DISPLAY-9

DIVIDE

DIVISION
**DUPLICATE

DOWN

DETAIL

**DUP

DUPLICATES

DYNAMIC

**EBCDIC

EGI

ELSE

EMI

**EMPTY

ENABLE

END

END-OF-PAGE

ENDING

ENTER

**ENTRY

ENVIRONMENT

EOP

**EPI

EQUAL

**EQUALS

ERROR

ESI

**EVEN

EVERY

EXCEPTION

B-2

COBOL RESERVED WORDS
**EXCL

**EXCLUSIVE

EXIT

EXTEND
F
FD

FILE

FILE-CONTROL

FILE-STATUS

FILLER

FINAL

FIRST

FOOTING

**FIND
FOR

**FORTRAN-IV

**FORTRAN

**FREED

FROM

GENERATE

**GET

GIVING

**GOBACK

GREATER

**FREE
G

GROUP
H
HEADING

HIGH-VALUE

HIGH-VALUES

I
1-0

1-0 CONTROL

**ID

IDENTIFICATION

INDEX

INDEXED

INDICATE

INITIAL

INITIATE

INPUT

INPUT-OUTPUT

**INSERT

INSPECT

INSTALLATION

INTO

INVALID

**INVOKE

J
**JOURNAL

JUSTIFIED

JUST

K
KEY

KEYS

L
LABEL

LAST

LEADING

LEFT

LENGTH

LESS
B-3

COBOL RESERVED WORDS
LIMIT

LIMITS

LINAGE

LINAGE-COUNTER

LINE

LINE-COUNTER

LINES
LOW-VALUE

**LINKAGE

LOCK

LOW-VALUES

M
**MACRO

**MEMBER

**MEMBERS

MEMORY

MERGE

MESSAGE

MODE

**MODIFY

MODULES

MULTIPLE

MULTIPLY

NEGATIVE

**NOMINAL

**NONE

NOT

NUMBER ...

MOVE
N
NATIVE

NUMERIC

OBJECT-COMPUTER

OCCURS

OFF

**ONLY

**OPT

**ODD
OMITTED
OPEN

OPTIONAL

ORGANIZATION

**OTHERS

OVERFLOW

**OWNER

OR
OUTPUT

P
PAGE
**PDP .... IO

PAGE-COUNTER

**PARITY

PERFORM

PIC

PICTURE

PLUS

**P-oINTER

POSITION

POSITIVE

PRINTING

**PRIVACY

PROCEDURE

**POSITIONING
**PRIOR
PROCEED

PROCEDURES

**PROGRAM

PROGRAM-ID

**PROTECTED

B-4

PROCESSING
**PROT

COBOL RESERVED WORDS
Q
QUEUE

QUOTE

QUOTES

RANDOM

READ

*READ-REWRITE

*READ-WRITE

RECEIVE

RECORD

**RECORDING

RECORDS

REDEFINES

REEL

REFERENCES

RELATIVE

RELEASE

REMAINDER

REMARKS

REMOVAL

**REMOVE

RENAMES

REPLACING

REPORT

REPORTING

REPORTS

RERUN

RESERVE

RESET

**RETAIN

**RETAINED

**RETR

**RETRIEVAL

RETURN

REVERSED

REWIND

REWRITE

RIGHT

ROUNDED

RUN

**SCHEMA

**RUN-UNIT
S
SAME
SEARCH

SECTION

SECURITY

SEGMENT

SEGMENT-LIMIT

SELECT

**SELECTIVE

SEND

SENTENCE

SEPARATE

**SEQUENCE

SEQUENTIAL

SET

**SETS

SIGN

**SIXBIT

SIZE

SORT

SORT-MERGE

SOURCE

SOURCE-COMPUTER

SPACE

SPACES

SPECIAL-NAMES

STANDARD

STANDARD-l

START

STATUS

STOP

**STORE

STRING

SUB-QUEUE-l

**SUB-QUEUE-2

**SUB-QUEUE-3

B-5

**STANDARD-ASCII

**SUB-SCHEMA

COBOL RESERVED WORDS
SUBTRACT

**SUPPRESS

SUM
SYMBOLIC

SYNC

TABLE

TALLY

TALLYING

TAPE

TERMINAL

TERMINATE

TEXT

THAN

THROUGH

THRU

TIME

TIMES

TOP

**TRACE

**SWITCH
SYNCHRONIZED
T

TRAILING

**TRANSACTION

TYPE

U
**UNAVAILABLE

UNSTRING'

UNIT

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

8-6

APPENDIX C

ASCII, SIXbIT, AND EBCDIC COLLATING StOUENCtS AND CONVERSIONS

Table C-l 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 3~ 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 C-l
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
OLE
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

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

!
"

#
$
%
&

(
)

*
+

0
1
2
3
4
5
6
7
8

9
:
;

<
=

>
?

C... l

EBCDIC
9-bit
100
132
177
173
133
154
120
175
115
135
134
116
153
140
113
141
360
361
I
I 362
: 363
364
365
366
367
370
371
172
136
114
176
156
157

ASCII, SIXBIT, AND EBCDIC COLLATING SEQUENCES AND CONVERSIONS
Table C.... 1 (Cont.)
ASCII and SIXBIT Collating Sequence and Conversion to EBCDIC

Character

SIXBIT

r----------"j ASCI I
I
9-bit
I Character 7-bit

ASCII
7-bit

EBCDIC

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

-----I

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

-------"" ----"-

EBCDIC
9-bit

140
171
141
201
b
142
202
143
203
c
204
0
d
144
205
145
E
e
F
206
f
146
207
147
G
9
H
h
210
150
III
i
151
211
I
j
152
112
221
J
K
113
k
222
153
L
154
223
114
1
M
155
115
m
224
N
116
n
225
156
0
a
157
226
117
p
I
p
120
160
227
: 121
Q
q
161
230
R
r
122
162
231
163
S
s
123
242
124
T
t
164
243
u
244
U
125
165
V
126
v
166
245
W
w
127
167
246
X
130
170
247
; I
x
y
y
250
131
171
Z
z
172
251
132
[
133
173
300 1
{
134
174
117
I
\
]
175
135
320
i
{
136
176
241
I
137
!
Delete 177
007
~-----~---~------~
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.
@

A
B
C

C-2

ASCII, SIXBIT, AND EBCDIC COLLATING SEQUENCES AND CONVERSIONS
Table C-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 C-2
ASCII to SIXBIT Conversion
ASCII
7-bit

SIXBIT

040
041
042
043
044
045
046
047

00
01
02
03
04
05
06
07

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
!
II

#
$
%
&
I

(
)

*
,
-

9
:
;

<
=

>
?

Character
@

A
B
C
D

E
F

G
H

I
J
K

L
M

N
0
p

Q
R

S
T
U
V
W

y
Z
[

\
]
t

C-3

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

ASCII, SIXBIT, AND EBCDIC COLLATING SEQUENCES AND CONVERSIONS
Table C-2 (Cant.)
ASCII to SIXBIT Conversion
ASCII
code
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

ASCII
character

SIXBIT
code

...

74
41
42
43
44
45
46
47

a
b
c
d

e
f
9

50
51
52
53
54
55
56
57

i
j
k

1
m

n
0

60
61
62
63
64
65
66
67

r
s
t
u

v
w

70
71
72
73
74
75
74
74

x
y

{
I
}

,...,

delete

C-4

SIXBIT
character

\
A

B
C
D

E
F

H
I
J
K
L
M
N

P
Q
R

S
T
U
V

W
X
y

Z
[

]

\
\

ASCII, SlXBIT, AND EBCDIC COLLATING SEQUENCES AND CONVERSIONS
Table C-3 shows the EBCDIC collating sequence and the conversion from
EBCDIC to ASCII. When conversion is from EBCDIC to SIXBIT, it is as
if the code was converted to ASCII and then from ASCII to SIXBIT.
Table C-3
EBCDIC Collating Sequence and Conversion to ASCII
EBCDIC
code

EBCDIC
character

ASCII
code

000
001
002
003
004
005
006
007

NUL
SOH
STX
ETX
PF
HT
LC
Delete

000
001
002
003
024
all
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

OLE
DCl
DC2
TM
RES
NL
BS
IL

134
134
l34
034
021
015
010
026

030
031
032
033
034
035
036

CAN
EM
CC
CUI
IFS
IGS
IRS
IUS

134
031
032
134
134
134
134
134

OS
SOS
FS

036
035
037
134
020
012
027
033

ASCII
character

EBCDIC
code

EBCDIC
character

ASCII
code

ASCII
character

0~7

040
041
042
043
044
045
046
047

BYP
LF
ETB
ESC

VT
FF

\
\
\

070
071
072
073
074
075
076
077

\
\

FS
DC1
CR
BS
SYN

100
101
102
103
104
105
106
107

EM
SUB

\
\

\
\
\

RS
GS
US

ENQ
ACK
BEL

134
134
030
134
134
005
006
007

PN
RS
UC
EOT

134
134
134
134
022
023
017
004

\
\
\
\

CU3
DC4
NAK
SUB

134
134
134
134
134
025
134
134

\
\
\
\
\

cuz

Space

110
III

112
113
114
115
116
117

OLE
LF
ETB
ESC

C-s

<
(

040
134
134
134
134
134
134
134
134
134
134
056
074
050
053
174

\
CAN
\

ENQ
ACK
BEL

DC2
DC3
SI
EOT

NAK

\
\
Space

\
\
\
\
\
\
\
\
\
\

<
(

ASCII, SIXBIT, AND EBCDIC COLLATING SEQUENCES AND CONVERSIONS
Table C-3 (Cont.)
EBCDIC Collating Sequence and Conversion to ASCII
ASCII
code

EBCDIC EBCDIC
code character
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

046
134
134
134
134
134
134
134

134
134
041
044
052
051
073
137

*
)

!
i

,
%

>
?

055
057
134
134
134
134
134
134

ASCII
character

EBCDIC
code

170
171
172
173
174
175
176
177

\
\
\
\
\

\
\

200
201
202
203
204
205
206
207

\
!

*
)

210
211
212
213
214
215
216
217

I
\
\
\

\
\
\

134
134
134
054
045
137
076
077

\
\
\

134
134
134
134
134
134
134
134

\
\
\
\

220
221
222
223
224
225
226
227

>
?

230
231
232
233
234
235
236
237

\
\
\

C-6

EBCDIC
character

#
@
I

=
"
a
b

c
d
e
f
9

h
i

j
k

1
m
n
0

P
q

ASCII
code

ASCII
character

134
140
072
043
100
47
075
042

134
141
142
143
144
145
146
147

\
a

150
151
134
134
134
134
134
134
134
152
153
154
155
156
157
160
161
162
134
134
134
134
134
134

#
@
I

=
"

c
d
e
f
9

h
i

\
j

1
m
n
0

P
q
r

\
\
\

ASCII, SIXBIT, AND EBCDIC COLLATING SEQUENCES AND CONVERSIONS
Table C-3 (Cont.)
EBCDIC Collating Sequence and Conversion to ASCII
EBCDIC
code
240
241
242
243
244
245
246
247
250
251
252
253
254
255
256
257

EBCDIC
character

s
t
u
v
w

x
y

[

ASCII
code
134
176
163
164
165
166
167
170
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

F
G

173
101
102
103
104
105
106
107

360
361
362
363
364
365
366
367

0
1
2
3
4
5
6
7

060
061
062
063
064
065
066
067

A
B
C
D
E

ASCII
character

EBCDIC
code

EBCDIC
character

ASCII
code

310
311
312
313
314
315
316
317

110
110
134
134
134
134
134
134

.............

s
t
u
v
w

320
321
322
323
324
325
326
327

z
\
\

[

\
\

330
331
332
333
334
335
336
337

\
\

340
341
342
343
344
345
346
347

\
\
\
\
\
\

\
\
\

]

\
\

{

J
K

L
M
N

0
P
Q

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

C-7

175
112
113
114
115
116
117
120
121
122
134
134
134
134
134
134

ASCII
character
H

\
\
\
\
\
\

}
J
K

L
M
N
0

P
Q

\
\
\
\
\
\

134
134
123
124
125
126
127
130

\
\
S

131
132
134
134
I 134
134
134
134

070
071
134
134
134
134
134
134

T
U
V

W
X

z
\
\
\
\
\
\
8
9

\
\
\
\
\
\

APPENDIX D
ALTERNATE NUMERIC TEST

LIBOL as normally assembled will include the ANSI standard NUMERIC
test.
However, a switch has been provided to allow the installation
manager to replace this with the ALTERNATE
NUMERIC
test
at
installation 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 trailing spaces
and leading and trailing tabs are ignored.
No signs are
permitted.

For signed numeric items, the sign, may have only one of the
three following representatibns: a leading graphic sign ("+"
or "-"), a trailing graphic sign, or a trailing embedded
sign.
Leading and trailing spaces and leading and trailing
tabs are ignored. All other characters must be digits.

D-l

APPENDIX E
DEFINING LOGICAL NAMES UNDER TOPS~20

Most of the file specifications for the COBOL compiler and the
utilities associated with COBOL-74 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 will not accept named
directories in the command strings. There are two ways fo~ 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 DECSYSTEM-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 may
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 leaye 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 may 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 DECSYSTEM-20 User's Guide for a
description of how to determine what logical names are
already defined.

E-l

DEFINING LOGICAL NAMES-UNDER TOPS-20
Example:
DEFINE PR:

<PAYROLL)

will allow you to type the
compiler:

following

command

the

COBOL-74

PR:FEDTAX=TESTFT.CBL
This command string will take 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=TES~FT.CBL

E-2

GLOSSARY

The terms in this glossary are defineq 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 that follow. 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.

(.)

Alphabet-Name
A user-defined word in the SPECIAL-NAMES paragraph of the
Environment Division that assigns a name to a specific character
set and/or collating sequence.
Alphabetic Character
A character that belongs to the following set of letters:

C, 0, 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.
Alternate Record Key
A key, other than the prime record key, whose contents identify a
record within an indexed file.

Glossary-l

Arithmetic Expression
An arithmetic expression ca~ 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.
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 ~ata 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 may 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.
Glossary-2

Calling Program
A program that executes a CALL to another program.
Cd-Name
A user-defined word that names an MCS interface area described in
a
communication description 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 Character 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
+

(
)
)

Glossary-3

characters

COBOL Word
(See Word.)
Collating Sequence
The sequence in which the characters that
computer are ordered for purposes of
comparing.

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.

Comment-Entry
An entry in the Identification Division that may be
combination of characters from the computer character set.

any

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 as 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 may 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 ~ntries.
Compile Time
The time at which a COBOL source program is translated by a COBOL
compiler to a COBOL object program.
GlosSary-4

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.)
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 may 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 attributed 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.

Glossary-5

overall

connective
A reserved word that is used to:
1.

Associate a data-name, paragraph-name,
text-name with its qualifier.

Link two or more operands written in a series.

Form conditions
Operator. )

(logical

condition-name,

(See

connectives) .

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

Control Data Item
A data item, in whose contents a change
break.

may

produce

Control Data-Name
A data-name that appears in a CONTROL
control data item.

clause

and

which

the

control

refers

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 may 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 Hierarchy
A designated sequence
positional order of
clause.

control

of report subdivisions defined by the
FINAL and the data-names within a CONTROL

Glossary-6

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.
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.
Current Record Pointer
A conceptual entity that is used in the
record.

associated

selection

the

with

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.
Debugging Line
A debugging line is any line with 'D' in the
the line.
Debugging Section
A debugging section
DEBUGGING statement.

section

Glossary-7

that

indicator

contains

area

USE

FOR

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.
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 ldentification of the
from a queue.

receiver

transmission

Digit position
A digit po~ition is the amount of physical storage required to
store a single digit.
This amount may 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]
Dynamic Access
An access mode in which specific logical records can be obtained
from or placed into a mass storage file in a nonsequential manner
(see Random Access), and obtained from a file in a sequential
manner (see Sequential Access), during the scope of the same OPEN
statement.
Glossary-8

Editing Character
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)
stroke (virgule, slash)

+
CR

DB
Z

/
Elementary Item
A data item that is described
subdivided.

as, not

being

End of Procedure Division
The physical position in a COBOL source program
further procedures appear.

belonging

further

after

logically

which

Entry
Any descriptive set of consecutive 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.
File
A collection of records.

Glossary-9

certain

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.
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.

Glossary-IO

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 may
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.
Index-Name
A user-defined word
specific table.

that

names

index

associated

can

with

Indexed Data-Name
An identifier that is composed of a data-name followed by one
more index-names enclosed in parentheses.

Indexed File
A file with indexed organization.
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.
Glossary-ll

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 of Reference
The key, either prime or alternate, currently
access records within an indexed file.

being

Key Word
A reserved word whose presence is required when the
which the word appears is used in a source program.

used

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.

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 may 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.

Glossary-12

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
These
describes data items available from the calling program.
data items may 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 Report writer Logical Record.)

record

Mass Storage
A storage medium on which data may be oganized and maintained
both a sequential and nonsequential manner.

Mass Storage Control System (MSCS)
An input-output control system that
processing of mass storage files.

the

Low Order End
The rightmost character of a string of characters.

Mass Storage File
A collection of records
medium.

that

directs

assigned

controls

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.

Glossary-13

Message
Data associated with an end of message indicator
group indicator.
(See Message Indicators.)

end

Message Control System (MCS)
A communication control system that supports
messages.

processing

exist

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 ES1, 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 may be
by an ESI, an EMI, or an EG1. A message may be
by an EMI or an EG1.

Message Segment
Data that forms a logical subdivision of a message normally
associated with an end of segment indicator.
(See Message
Indicators.)
Mnemonic-Name
A user-defined word that is associated
Division with a specified implementor-name.

the

Environment

MSCS
(See Mass Storage Control System.)
Native Character Set
The implementor-defined character set associated
computer specified in the OBJECT-COMPUTER paragraph.

with

the

Native Collating Sequence
The implementor-defined collating sequence associated
computer specified in the OBJECT-COMPUTER paragraph.

with

the

Negated Combined Condition
The
'NOT'
logical
operator
immediately
parenthesized combined condition.
Negated Simple Condition
The 'NOT' logical operator
condition.

Immediately

Glossary-14

followed

simple

Next Executable Sentence
The next sentence to which control will be transferred
execution of the current statement is complete.

after

Next Executable Statement
The next statement to which control will be 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 may be
formed from more restricted character sets.
Nonnumeric Literal
A character-string bounded by quotation marks.
The string of
characters may 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 may also contain a '+',
'-'
or other
representation of an operational sign.
Numeric Literal
A literal composed of one or more numeric characters that also
may 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.
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-IS

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 may 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 may 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 the user 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.

Glossary-16

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.
Page Body
That part of the logical page
and/or spaced.

which

lines

can

Page Footing
A report group that is presented at the end of a report
determined by the Report Writer Control System.

written

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.o
In the Environment Division:
SOURCE-COMPUTER.
OBJECT-COMPUTER.
SPECIAL-NAMES.
FILE-CONTROL.
I-O-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.

Glossary-l7

consecutive COBOL
a COBOL procedural

Physical Record
(See Block.)
Prime Record Key
A key whose contents uniquely identify a record within an indexed
file.
Printable Group
A report group that contains at least 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 NUMBER 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 may be qualified) or a section-name.
Program-Name
A user-defined wo~d 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 equal
pseudo-text.

sign

(=)

characters

Punctuation Character
A character that belongs to the following set:
Character

(
)

Meaning
comma
semicolon
period
quotation mark
left parenthesis
right parenthesis
space
equal sign

Glossary-18

used

delimit

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.
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 Mes the logical path by
which a message or a portion of a completed message may 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.
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, either the prime record key or an alternate record
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-19

described

key,

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 Ope~ator
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] <
IS [NOT] EQUAL TO
IS [NOT]

Less than or not less than
Equal to or not equal to

Relative File
A file with relative organization.
Relative Key
A key whose contents identify a
file.

logical

record

relative

Relative Organization
The permanent logical file structure in which each record is
uniquely identified by an integer value grater than zero, which
specifies the record's logical ordinal position in the file.
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.
Glossary-20

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 repo~t file consist of records that
are written under control of the Report writer Control System.
Report Footing
A report group that is presented only at the end of a report.
Report Group
In the Report Section of the Data bivision,
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.

Glossary-21

Reserved Word
A COBOL word specified in the list of words that may 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.
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.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
COMMUNICATION SECTION.
REPORT S~CTION.
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 may
contain only the characters '0', 'I', ... , '9'. A segment-number
may be expressed either as a 1- or 2-digit number.
Glossary-22

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.
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.

Glossary-23

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
may
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 may be used in place of
the phrase 'source program.'
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.
Glossary-24

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.)
Subscript
An integer whose value
table.

identifies

particular

element

Subscripted Data-Name
An identifier that is composed of a d~ta-name followed by one
more subscripts enclosed in parenthe~es.

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 contain the result of
designated summing operations that take place during production
of a report.
Switch-Status Condition
The proposition, for which a truth value qao be dete~mined, 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

commun~cat~

with

the

operating

Table
A set of logically consecutive items of data that are Qefined
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.
Glossary-25

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.
Unit

A module of mass storage the dimensions of which
by each implementor.

User-Defined Word
A COBOL word that must be supplied by the
format of a clause or statement.

user

are

determined

satisfy

the

variable
A data item whose value may 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

compiier

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-26

INDEX

Abbreviated
combined relation condition,
5-16
ACCEPT
COBDDT command, 7-31
ACCEPT statement, 5-20
Access
file organization, 8-23
ACCESS MODE clause, 3-19
Access strategies
sequential file, 9-13
ADD statement, 5-22
ADVANCING clause
WRITE statement, 5-117
Advancing mode
packing ISAM file, 7-13
AFTER option
WRITE statement, 5-117
Alignment
coding conventions, 13-12.1
ALL literal
figurative constant, 1-7
ALL phrase
INSPECT statement, 5-52
UNSTRING statement, 5-105,
5-110
ALL PROCEDURES clause
USE statement, 5-115
ALLOWING OTHERS clause
OPEN statement, 5-62, 9-6
Alphabet-name IS clause, 3-7
Alphabetic item definition, 4-44
ALPHABETIC test
class condition, 5-10
Alphanumeric item definition,
4-44
Alphanumeric literal, 1-11
Alphanumeric-Edited item
definition, 4-44
ALTER statement, 5-24
Alternate
numeric test, 0-1
ALTERNATE RECORD KEY clause, 3-21
RMS indexed files, I-I
ANSI labeled tapes
tape handling, F-8
ANSI levels
FIPS flagger, G-1
ANY VERB clause, 5-62
ANY VERB option
RETAIN statement, 9-10
Argument list entry
36-bit storage, 12-4
Arithmetic computations
usage
determination, 5-18
Arithmetic expression, 5-7
Arithmetic verbs
options, 5-17

ASCENDING clause
MERGE statement, 5-56
SORT statement, 5-87
ASCII
fixed-length
file format, 8-4
recording mode, 3-23, 8-1
transportable tapes, F-9
variable-length
file format, 8-6
ASCII collating sequence
conversion to SIXBIT, C-3
ASCII conversion
from EBCDIC, C-5
ASCII data type, 13-9
ASCII mixed-mode binary
file format, 8-20
ASCII tape handling
TOPS-20, F-10
ASCII/SIXBIT collating sequence
conversion to EBCDIC, C-1
ASSIGN clause, 3-14
Assignment
report file
Report Writer, 10-6
AT END clause
READ statement, 5-69
SEARCH statement, 5-83
Available tape drive
tape handling, F-7
BEFORE option
WRITE statement, 5-117
BINARY'
file format, 8-19
recording mode, 3-23, 8-3
Binary
standard, 8-20
transportable tape handling,
F-11
BIS-compiler, 1-1
BLANK WHEN ZERO clause, 4-33
Block
definition, 1-3
BLOCK CONTAINS clause, 4-15
Blocking data
efficient data types, 13-11
ISAM program, 7-18
Braces
symbology, 1-2
Brackets
symbology, 1-2
BREAK
COBDDT command, 7-31
Buffer memory
compute allocation, 11-12
Buffer size
indexed-sequential files, 11-12
Buffer space, 11-11

Index-1

October 1985

BY keyword
DIVIDE statement, 5-35
BYTE MODE clause, 3-25
CALL statement, 5-25
COBOL-68/74 differences, A-7
inter-program communication,
11-4.1
subprograms, 11-4
Called subprogram
inter-program communication,
11-5
Calling non-COBOL subprograms,
12-1
ENTER statement, 12-1
Calling program
inter-program communication,
11-4.1
CANCEL statement, 5-27
COBOL-68/74 differences, A-7
overlays, 11-13
Card-type format
source program format, 1-14
CD entries, 4-5
CD-name
debugging, H-3
CHANNEL
SPECIAL-NAMES, 3-7
Character chart
PICTURE string, 4-55
Character collating sequences
with conversion tables, C-l
Character set
COBOL-74, 1-4
Character-string
PICTURE clause, 4-43
Characters
arithmetic expressions, 1-5
conditional IF, 1-5
punctuation, 1-5
special editing, 1-5
CHARACTERS option
BLOCK CONTAINS, 4-15
CHARACTERS phrase
INSPECT statement, 5-51
Checking
indexed-sequential file, 7-17
CHECKPOINT OUTPUT option, 3-18
Class condition
ALPHABETIC test, 5-10
conditional expression, 5-9
format, 5-9
NUMERIC test, 5-10
restrictions, 5-9
Clause
ACCESS MODE, 3-19
ADVANCING, 5-117
ALL PROCEDURES, 5-115
ALLOWING OTHERS, 5-62
simultaneous update, 9-6
alphabet-name IS, 3-7
ALTERNATE RECORD KEY, 3-21, I-I
ANY VERB, 5-62

Clause (Cont.)
ASCENDING, 5-56, 5-87
ASSIGN, 3-14
AT END, 5-69, 5-83
BLANK WHEN ZERO, 4-33
BLOCK CONTAINS, 4-15
BYTE MODE, 3-25
CODE, 4-74
CODE-SET, 3-7, 4-17
COLUMN NUMBER, 4-81
CONTROL, 4-75
CURRENCY SIGN, 3-8
DATA RECORD, 4-18
DATE-WRITTEN, 4-27
DECIMAL-POINT IS COMMA, 3-8
DENSITY, 3-25
DESCENDING, 5-56, 5-87
DISPLAY, 3-5
DOWN BY, 5-85
ELSE, 5-47
FD, 4-13
FD file-name, 4-19
File Description, 4-13
FILE STATUS, 3-27
FOR, 5-75
FROM, 5-98
GROUP INDICATE, 4-82
INVALID KEY, 5-33, 5-69, 5-80
JUSTIFIED, 4-37
KEY, 5-83
KEY IS data-name, 5-71
LABEL RECORD, 4-20
LINAGE, 4-22
LINE NUMBER, 4-83
literal IS mnemonic-name, 3-8
MEMORY SIZE, 3-4
MULTIPLE FILE, 3-38
NEXT GROUP, 4-85
NEXT RECORD, 5-74
OCCURS, 4-10, 4-40
ORGANIZATION, 3-17, I-I
PAGE LIMIT, 4-76
PARITY, 3-25
PICTURE, 4-42
POSITIONING, 5-118
PRINTING, 5-100
PROGRAM COLLATING SEQUENCE, 3-5
RECORD CONTAINS, 4-24
RECORD KEY, 3-20
RECORDING MODE, 3-23
RECORDS, 4-15
REDEFINES, 4-56
RELATIVE KEY, 3-22
REMAINDER, 5-36
RENAMES
level-66, 4-58
REPORT, 4-25
RERUN, 3-37
RESERVE, 3-16
RESET, 4-86
RMS, 3-18
SAME AREA, 3-38
SO file-name, 4-26

Index-2

October 1985

Clause (Cont.)
SEGMENT-LIMIT, 3-5
SELECT, 3-13, 1-2
SIGN, 4-60
SOURCE, 4-87
SUM, 4-88
SYNCHRONIZED, 4-62
TYPE, 4-88.1
UNAVAILABLE, 5-63
UNTIL, 5-67
UP BY, 5-85
USAGE, 4-64
USER-NUMBER, 4-27
USING, 5-1, 5-25, 5-38
VALUE, 4-70
VALUE OF IDENTIFICATION, 4-27
WITH DEBUGGING MODE, 3-3
WITH NO ADVANCING, 5-34
Clause format
ENVIRONMENT DIVISION, 3-2
Clause WITH DUPLICATES, 1-1
CLEAR
COBDDT command, 7-32
CLOSE options
with file types, 5-31
CLOSE statement, 5-28
Report Writer, 10-19
COBDDT
optimizing tool, 13-6
utility program, 7-1
COBDDT program
CPU column, 13-7
debugging programs, 7-29
ELAPSED column, 13-8
ENTRIES column, 13-7
histogram listing, 7-41
histogram table, 7-39
histograms, 7-39
loading and starting, 7-29
OVERHEAD entry, 13-8
starting the histogram, 7-40
stopping the histogram, 7-40
using histogram, 7-43
COBDDT program command
ACCEPT, 7-31
BREAK, 7-31
CLEAR, 7-32
DDT, 7-32
DISPLAY, 7-33
GO, 7-33
LOCATE, 7-34
MODULE, 7-34
NEXT, 7-34
OVERLAY, 7-35
PROCEED, 7-35
SHOW SYMBOLS, 7-36
STEP, 7-36
STOP, 7-37
TRACE, 7-37
UNPROTECT, 7-38
WHERE, 7-38
COBDDT program commands, 7-30

COBOL
language elements, 1-3
program structure, 1-3
COBOL keyword
ENTER statement, 5-37
COBOL labels
tape handling, F-l
COBOL-68
differences
COBOL-74, A-l
COBOL-74
arithmetic expression
characters, 1-5
calling non-COBOL subprograms,
12-1
character set, 1-4
COBOL-68 differences, A-l
compiler command string, 6-1
compiling and loading, 6-1
conditional IF characters, 1-5
COPY statement, 1-19
DATA DIVISION, 4-1
data types, 13-8
DEBUG module
use, H-l
differences
CALL statement, A-7
CANCEL statement, A-7
COpy statement, A-8
indexed files, A-6
PERFORM statement, A-7
relative files, A-6
segmentation, A-7
documentation
program technique, 13-5
ENVIRONMENT DIVISION, 3-1
rDENTIFICATION DIVISION, 2-1
improving performance, 13-1
introduction, 1-1
library facility, 1-19
literals, 1-10
loading, 6-4
overlay programs, 11-8
PROCEDURE DIVISION, 5-1
program optimization, 13-2
program segments, 11-1
programming techniques, 13-2
punctuation characters, 1-5
Report Writer, 10-1
reserved words, 1-5, B-1
RMS indexed files, 1-3
RMS program example, 1-8
running, 6-4
separators, 1-12
source program format, 1-13
special editing characters, 1-5
standards, 13-2
switches
compiler, 6-3
symbology, 1-1
symbols, 1-1
terms, 1-1, 1-3
utility programs, 7-1

Index-3

October 1985

COBOL-74 (Cont.)
word, 1-5
Code
BIS, 1-1
CODE clause, 4-74
Report Writer, 10-8
CODE-SET clause, 3-7, 4-17
Codes
FILE STATUS clause, 3-28
Coding conventions
alignment, 13-12.1
data movement, 13-14
efficient, 13-12.1
incrementing counters, 13-13
INSPECT statement, 13-14
PERFORM statement, 13-13
statement ordering, 13-15
subscript usage, 13-12.1
Collating sequence
SORT statement, 5-88
COLLATING SEQUENCE phrase, 5-88
Collating sequences
character, C-l
COLUMN clause
Report Writer, 10-10, 10-12
COLUMN NUMBER clause, 4-81
Combined condition, 5-15
Comma separator, 1-12
Command
DEFINE
translation, E-1
indirect
ISAM program r 7-19
MOUNT, F-7
Command string
compiler, 6-1
Command TRANSL, E-1
Command usage
LIBARY program, 7-27
Commands
COBDDT program, 7-30
LIBARY program, 7-25
LIBARY-directing, 7-26
Comment lines
program format, 1-14
Communication
inter-program, 11-4
COMMUNICATION SECTION
DATA DIVISION, 4-5
Communication Section
definition, 4-1
Compiler
format
COBOL-74, 6-1
Compound-conditional expression
order of evaluation, 5-14
Computational data type, 13-10
COMPUTATIONAL format
USAGE clause, 4-65
COMPUTATIONAL-l format
USAGE clause, 4-65
COMPUTATIONAL-3 format
USAGE clause, 4-66

Computations
arithmetic
usage, 5-18
COMPUTE statement, 5-32
Condition
class, 5-9
NOT RETAINED
simultaneous update, 9-12
ON OVERFLOW
CALL statement, 5-26
ENTER statement, 5-37
WHEN, 5-83
Condition types, 5-15
Condition-name
level-88
entry, 4-34
Condition-name condition
conditional expression, 5-10
format, 5-10
Conditional expression
abbreviated combined relation
condition, 5-16
combined conditions, 5-15
evaluation, 5-11
format, 5-11
negated combined condition,
5-15
order of evaluation, 5-13
relation condition, 5-7
Conditional expressions
condition-name condition, 5-10
logical operators, 5-11
sign condition, 5-11
Conditions
conditional expression
combinations, 5-15
CONFIGURATION SECTION
ENVIRONMENT DIVISION, 3-2
Connectives
reserved words, 1-6
CONSOLE
reserved word, 3-6
Continuation area
characters, 1-15
program format, 1-14
CONTROL clause, 4-75
Report Writer, 10-8
CONTROL FOOTING entry
TYPE clause, 4-88.2
CONTROL HEADING entry
TYPE clause, 4-88.1
CONTROL print group, 4-76
Conversion to ASCII
EBCDIC
collating sequence, C-5
Conversion to EBCDIC
ASCII/SIXBIT
collating sequence, C-1
Conversion to SIXBIT
ASCII
collating sequence, C-3
COpy statement
COBOL-68/74 differences, A-8

Index-4

October 1985

COpy stat~ment (Cont.)
definition, 1-19
CORRESPONDING option
ADD statement, 5-23
MOVE statement, 5-57
PROCEDURE DIVISION, 5-18
SUBTRACT statement, 5-99
Count storage items
UNSTRING statement, 5-106
Counter
efficient data types, 13-11
Counters
incrementing
coding conventions, 13-13
CPU column
COBDDT
optimizing, 13-7
CURRENCY SIGN clause, 3-8
D format
transportable tape handling,
F-9
Data description
entry, 4-31
DATA DIVISION
COMMUNICATION SECTION, 4-5
FILE SECTION, 4-2
LINKAGE SECTION, 4-5
qualification, 4-9
REPORT SECTION, 4-6
SCHEMA SECTION, 4-4
space restrictions, 13-12
structure, 1-4
WORKING-STORAGE SECTION, 4-5
DATA DIVISION clauses, 4-12
Data file
characteristics, 8-27
structure
ISAM, 8-28
Data item
PAGE-COUNTER, 10-13
Data movement
coding conventions, 13-14
DATA RECORD clause, 4-18
SD file-name clause, 4-26
Data types, 4-1
ASCII, 13-9
blocking data, 13-11
computational, 13-10
counter, 13-11
DISPLAY, 13-8
EBCDIC, 13-8
efficiency, 13-11
file storage, 13-11
indexes, 13-11
SIXBIT, 13-10
subscripts, 13-11
Data-name entry, 4-36
DATABASE-KEY format
USAGE clause, 4-69
DATE
special register, 1-9

DATE option
ACCEPT statement, 5-20
DATE-COMPILED paragraph, 2-2
DATE-WRITTEN clause, 4-27
DAY
special register, 1-8
DAY option
ACCEPT statement, 5-20
DDT
COBDDT command, 7-32
Debug lines, 1-15
Debug module
CD-name
debugging, H-3
COBOL-74
use, H-l
DEBUG-CONTENTS, H-2
DEBUG-ITEM data, H-5
DEBUG-LINE contents, H-5
DEBUG-NAME contents, H-5
debugging on identifier, H-4
debugging section execution,
H-3
example, H-7
example methods, H-9
features, H-l
file-name debugging, H-4
loading programs, H-7
procedure-name debugging, H-4
special register, H-l
USE FOR DEBUGGING
statement, H-3
DEBUG-CONTENTS
debug module, H-2
format, H-2
DEBUG-ITEM
format, H-l
special register
debug module, H-l
DEBUG-ITEM data, H-5
DEBUG-ITEM register
USE statement, 5-115
DEBUG-LINE
contents, H-5
DEBUG-NAME
contents, H-5
Debugging programs
COBDDT, 7-29
Debugging section
execution, H-3
DECIMAL-POINT IS COMMA clause,
3-8
DECLARATIVES
format, 5-114
USE statement, 5-113
DECLARATIVES header, 5-1
DECLARATIVES SECTION
Report Writer, 10-16
Defaults
LIBARY program command string,
7-23
DEFERRED OUTPUT option, 3-18

Index-5

October 1985

DEFINE command
directory translation, E-l
Definition
alphabetic item, 4-44
alphanumeric item, 4-44
alphanumeric-edited item, 4-44
identifier, 5-19
numeric item, 4-44
numeric-edited item, 4-44
DELETE
LIBARY command, 7-26
DELETE option
CLOSE statement, 5-28
DELETE statement, 5-33
DELIMITED BY phrase
STRING statement, 5-93
UNSTRING statement, 5-109
DELIMITED BY SIZE phrase
STRING statement, 5-94
DELIMITER IN phrase
UNSTRING statement, 5-106
Delimiter items
STRING statement, 5-93
UNSTRING statement, 5-105
Delimiter storage items
UNSTRING statement, 5-106
DENSITY clause, 3-25
DEPENDING ON option
GO TO statement, 5-46
DEPENDING option
OCCURS clause, 4-40
DESCENDING clause
MERGE statement, 5-56
SORT statement, 5-87
Description
ACCEPT statement, 5-20
ACCESS MODE clause, 3-19
ADD statement, 5-22
ALTER statement, 5-24
ALTERNATE RECORD KEY, 3-21
BLANK WHEN ZERO clause, 4-33
BLOCK CONTAINS clause, 4-15
CALL statement, 5-25
CANCEL statement, 5-27
clauses
DATA DIVISION, 4-12
CLOSE statement, 5-28
CODE clause, 4-74
CODE-SET clause, 4-17
COLUMN NUMBER clause, 4-81
COMMUNICATION SECTION, 4-5
COMPUTE statement, 5-32
condition-name entry, 4-34
CONFIGURATION SECTION, 3-2
CONTROL clause, 4-75
COpy statement, 1-19
data description entry, 4-32
DATA DIVISION, 4-1
DATA RECORD clause, 4-18
data-name entry, 4-36
DATE-WRITTEN clause, 4-27
DELETE statement, 5-33
DISPLAY statement, 5-34

Description .(Cont.)
DIVIDE statement, 5-35
ENTER statement, 5-37
ENTRY statement, 5-38
ENVIRONMENT DIVISION, 3-1
EXIT PROGRAM statement, 5-40
EXIT statement, 5-39
FD clause, 4-14
FD file-name clause, 4-19
File Description clause, 4-14
FILE SECTION, 4-2
FILE STATUS clause, 3-27
FILE-CONTROL paragraph, 3-13
FILLER word, 4-36
FREE statement, 5-41
GENERATE statement, 5-44
GO TO statement, 5-46
GROUP INDICATE clause, 4-82
I-O-CONTROL paragraph, 3-37
IDENTIFICATION DIVISION, 2-1
IF statement, 5-47
indexing, 4-10
INITIATE statement, 5-49
INPUT-OUTPUT SECTION, 3-9
INSPECT statement, 5-50
JUSTIFIED clause, 4-37
LABEL RECORD clause, 4-20
level-66
RENAMES clause, 4-58
level-88 entry, 4-34
level-number entry, 4-39
LINAGE clause, 4-22
LINE NUMBER clause, 4-83
LINKAGE SECTION, 4-5
MERGE statement, 5-55
MOVE statement, 5-57
MULTIPLY statement, 5-59
NEXT GROUP clause, 4-85
OBJECT-COMPUTER paragraph, 3-4
OCCURS clause, 4-40
OPEN statement, 5-61
ORGANIZATION clause, 3-17
PAGE LIMIT clause, 4-76
PERFORM statement, 5-66
PICTURE clause, 4-42
PROCEDURE DIVISION, 5-1
qualification, 4-9
READ statement, 5-69
RECORD CONTAINS clause, 4-24
RECORD KEY clause, 3-20
RECORDING MODE clause, 3-23
REDEFINES clause, 4-56
RELATIVE KEY clause, 3-22
RELEASE statement, 5-72
RENAMES clause, 4-58
REPORT clause, 4-25
report description entry, 4-72
report group description entry,
4-80
REPORT SECTION, 4-6
RESERVE clause, 3-16
RESET clause, 4-86
RETAIN statement, 5-74

Index-6

October 1985

Description (Cont.)
RETURN statement, 5-79
REWRITE statement, 5-80
SCHEMA SECTION, 4-4
SD file-name clause, 4-26
SEARCH, 5-82
SELECT statement, 3-14
SET statement, 5-85
SIGN clause, 4-60
SORT statement, 5-86
SOURCE clause, 4-87
SOURCE-COMPUTER paragraph, 3-3
SPECIAL-NAMES paragraph, 3-6
START statement, 5-89
STOP statement, 5-91
STRING statement, 5-92
subscripting, 4-10
SUBTRACT, 5-98
SUM clause, 4-88
SUPPRESS statement, 5-100
SYNCHRONIZED clause, 4-62
TERMINATE statement, 5-101
TRACE statement, 5-102
TYPE clause, 4-88.1
UNSTRING statement, 5-104
USAGE clause, 4-64
USE statement, 5-113
USER-NUMBER clause, 4-27
VALUE clause, 4-70
VALUE OF IDENTIFICATION clause,
4-27
WORKING-STORAGE SECTION, 4-5
WRITE statement, 5-116
Descriptions
record
FILE SECTION, 4-2
Destination counter
UNSTRING statement, 5-107
Destination item
STRING statement, 5-94
Destination items
UNSTRING statement, 5-104
DETAIL entry
TYPE clause, 4-88.1
Device-name
logical, 3-15
physical, 3-14
Direct subscripting/indexing,
4-11
qualified, 4-12
Directory
translation, E-l
Directory translation
TRANSL command, E-l
DISPLAY
COBDDT command, 7-33
DISPLAY clause, 3-5
DISPLAY data types, 13-8
DISPLAY format
USAGE clause, 4-67
DISPLAY statement, 5-34
figurative constants, 5-34

DISPLAY-6 format
USAGE clause, 4-67
DISPLAY-7 format
USAGE clause, 4-67
DISPLAY-9 format
USAGE clause, 4-68
DIVIDE statement, 5-35
operands, 5-36
Double-precision
fixed-point, 5-18
DOWN BY clause
SET statement, 5-85
Dynamic access
relative files, 8-25
Dynamic allocation space, 11-11
EBCDIC
file format, 8-12
fixed-length
file format, 8-13
recording mode, 8-2
variable-length
file format, 8-14
EBCDIC collating sequence
conversion to ASCII, C-5
EBCDIC data type, 13-8
EBCDIC labels
tape handling, F-ll
EBCDIC mixed-mode binary
file format, 8-22
EBCDIC tape handling
TOPS-10, F-10
TOPS-20, F-10
Editing
fixed insertion, 4-51
floating insertion, 4-51, 4-52
simple insertion, 4-51
zero suppression, 4-53
Editing types
PICTURE clause, 4-50
ELAPSED column
COBDDT
optimizing, 13-8
Elementary item
PICTURE string, 4-45
Elementary items
FILE SECTION, 4-3
Ellipsis
symbology, 1-2
ELSE clause
IF statement, 5-47
Embrace
deadly, 5-75
END
LIBARY command, 7-27
END OF UNIT option, 3-37
END-OF-PAGE phrase
WRITE statement, 5-118
ENTER statement, 5-37
calling non-COBOL subprograms,
12-1
entry point, 12-1

Index-7

October 1985

ENTRIES column
COHDDT
optimizing, 13-7
Entry
condition-name (level-88), 4-34
data description, 4-31
data-name, 4-36
level-number, 4-39
report description
RD, 4-72
report group description, 4-78
ENTRY statement, 5-38
inter-program communication,
11-5
ENVIRONMENT DIVISION
clause format, 3-2
CONFIGURATION SECTION, 3-2
INPUT-OUTPUT SECTION, 3-9
structure, 1-4
EOP phrase
WRITE statement, 5-118
Error codes
monitor
FILE STATUS clause, 3-34
Error message
FIPS flagger, G-2
Error number
FILE STATUS clause, 3-28
Error numbers
RMS, 1-4
Evaluation order
compound-conditional expression,
5-14
conditional expression, 5-13
Evaluation rules
conditional expression, 5-11
PROCEDURE DIVISION, 5-6
EVERY RECORD phrase
FREE statement, 5-42, 9-12
Execution
sequence of, 5-4
STRING statement, 5-94
UNSTRING statement, 5-107
EXIT PROGRAM statement, 5-40
inter-program communication,
11-5
EXIT statement, 5-39
Explicit record release
simultaneous update, 9-1
Explicit usage
index, 4-10
Expressions
arithmetic, 5-6
conditional, 5-7
EXTEND phrase
OPEN statement, 5-63
EXTRACT
LIBARY command, 7-26

F format
transportable tape handling,
F-9
FD
report file
Report Writer, 10-7
FD entry
RMS indexed files, 1-2
FD file-name clause, 4-19
Figurative constant
ALL literal, 1-7
HIGH-VALUE, 1-7
HIGH-VALUES, 1-7
LOW-VALUE, 1-7
LOW-VALUES, 1-7
QUOTE, 1-7
QUOTES, 1-7
SPACE, 1-7
SPACES, 1-7
ZERO, 1-7
ZEROES, 1-7
ZEROS, 1-7
Figurative constants
reserved, 1-6
File
building
indexed-sequential, 7-4
data, 8-27
index, 8-28
indexed-sequential
maintaining, 7-9
packing, 7-12
File Description (FD) clause,
4-13
File format
ASCII
mixed-mode binary, 8-20
BINARY, 8-19
EBCDIC, 8-12
mixed-mode binary, 8-22
fixed-length ASCII, 8-4
fixed-length EBCDIC, 8-13
blocked, 8-16
fixed-length SIXBIT, 8-8.1
SIXBIT
mixed-mode binary, 8-21
source library, 7-22
standard binary, 8-20
variable-length ASCII, 8-6
variable-length EBCDIC, 8-14
blocked, 8-17
variable-length SIXBIT, 8-10
File formats, 8-1, 8-3
File maintenance
ISAM program, 7-2
File organization
access, 8-23
FILE SECTION
DATA DIVISION, 4-2
level numbers, 4-3
File Section
definition, 4-1

recording mode, 3-23

Index-8

October 1985

File status bits
monitor
FILE STATUS clause, 3-33
FILE STATUS clause, 3-27
error codes, 3-34
file status bits, 3-33
File storage
efficient data types, 13-11
File structure
ISAM, 8-28
index, 8-30
File types
with CLOSE options, 5-31
FILE-CONTROL paragraph, 3-10
File-name
debugging, H-4
Files
indexed-sequential
characteristics, 8-27
maximum number, 4-14
relative
characteristics, 8-24
sequential
characteristics, 8-23
FILLER word, 4-36
FINAL entry
TYPE clause, 4-88.2
FIPS
ANSI levels, G-l
error messages, G-2
federal COBOL standard, G-l
FPM definition, G-l
use, G-2
FIPS flagger
compatibility checker, G-1
FIRST DETAIL clause
PAGE LIMIT clause, 4-76
FIRST phrase
INSPECT statement, 5-52
Fixed-length ASCII
file format, 8-4
Fixed-length EBCDIC
file format, 8-13
Fixed-length SIXBIT
file format, 8-8.1
Floating-point arithmetic
double-precision, 5-18
FOOTING clause
PAGE LIMIT clause, 4-76
FOOTING phrase
LINAGE clause, 4-22
FOOTING report group, 4-76
FOR clause
RETAIN statement, 5-75
FOR keyword
OPEN statement, 5-62
FOR REMOVAL option
CLOSE statement, 5-28
Form positioning, 5-117
Format
COMP, 4-65
COMP-1, 4-65
COMP-3, 4-66

Format (Cont.)
DATABASE-KEY, 4-69
DISPLAY, 4-67
DISPLAY-6, 4-67
DISPLAY-7, 4-67
DISPLAY-9, 4-68
INDEX, 4-68
Formation rules
PROCEDURE DIVISION, 5-6
Formats
file, 8-1, 8-3
FORTRAN keyword
ENTER statement, 5-37
FORTRAN subprograms
call ing, 12-1
FPM
FIPS flagger, G-I
Free memory
/SPACE switch, 11-11
FREE statement, 5-41
simultaneous update, 9-11
FROM option
ACCEPT statement, 5-20
RELEASE statement, 5-72
REWRITE statement, 5-80
WRITE statement, 5-119
FROM word
SUBTRACT statement, 5-98
GENERATE statement, 5-44
Report Writer, 10-18
GIVING option
ADO statement, 5-23
MERGE statement, 5-56
SORT statement, 5-87
SUBTRACT statement, 5-98
GO
COBDDT command, 7-33
GO TO statement, 5-46
GROUP INDICATE clause, 4-82
Group items
FILE SECTION, 4-3
Group mode commands
LIBARY program, 7-25
Handling errors
RMS indexed files, 1-4
HEADING clause
PAGE LIMIT clause, 4-76
HIGH-VALUE
figurative constant, 1-7
HIGH-VALUES
figurative constant, 1-7
Histogram
initializing the table, 7-39
obtaining a listing, 7-41
starting, 7-40
stopping, 7-40
using, 7-43
Histograms
program behavior
obtaining, 7-39
Horizontal tab separator, 1-12

Index-9

October 1985

1-0 option
OPEN statement, 5-62
I-O-CONTROL paragraph, 3-37
Identification area
source program format, 1-15
IDENTIFICATION DIVISION
structure, 1-4
Identifier
debugging, H-4
Identifier definition
PROCEDURE DIVISION, 5-19
IF statement, 5-47
Implicit record release
simultaneous update, 9-1
Implicit usage
index, 4-10
Index file
characteristics, 8-28
structure
ISAM, 8-30
INDEX format
USAGE clause, 4-68
Index-sequential file
maintaining a, 7-9
Index-sequential files
FREE statement, 5-43
Indexed files
COBOL-68/74 differences, A-6
RMS
using, I-I
INDEXED option
OCCURS clause, 4-41
Indexed-sequential
ISAM program, 7-2
Indexed-sequential file
building a, 7-4
building example, 7-8
checking, 7-17
locating a record, 8-29
packing a, 7-12
packing example, 7-13
renaming, 7-16
renaming example, 7-17
using, 7-20
Indexed-sequential files, 8-27
accessing
simultaneous update, 9-18
buffer size, 11-12
RETAIN statement, 5-78
Indexes
efficient data types, 13-11
Indexing
DATA DIVISION, 4-10
relative/direct, 4-11
Indexing forms, 4-11
Indirect commands
ISAM program, 7-19
INITIATE statement, 5-49
Report Writer, 10-17
Input
optional, 5-61
INPUT option
USE statement, 5-114

INPUT PROCEDURE phrase
MERGE statement, 5-56
INPUT-OUTPUT option
USE statement, 5-114
INPUT-OUTPUT SECTION
ENVIRONMENT DIVISION, 3-9
INSERT
LIBARY command, 7-26
INSPECT statement, 5-50
coding conventions, 13-14
Inter-program communication
CALL statement, 11-4.1
called subprogram, 11-5
calling program, 11-4.1
ENTRY statement, 11-5
EXIT PROGRAM statement, 11-5
PROCEDURE DIVISION statement,
11-5
STOP RUN statement, 11-6
subprograms, 11-4
USING clause, 11-5
INTO keyword
DIVIDE statement, 5-35
INTO option
READ statement, 5-71
INTO phrase
RETURN statement, 5-79
INVALID KEY clause
DELETE statement, 5-33
READ statement, 5-69
REWRITE statement, 5-80
INVALID KEY phrase
START statement, 5-89
WRITE statement, 5-119
ISAM
utility program, 7-1
ISAM program
blocking data, 7-18
file environment, 7-3
file maintenance, 7-2
function switches, 7-2
functions, 7-2
indirect commands, 7-19
key descriptor, 7-6
tape labels, 7-14
Item
definition, 1-3
FILLER, 4-36
Items
elementary, 4-3
group, 4-3
JUSTIFIED clause, 4-37
KEY clause
SEARCH statement, 5-83
Key descriptor
ISAM program, 7-6
~EY IS data-name clause
READ statement, 5-71
KEY phrase
RETAIN statement, 5-75

Index-10

October 1985

KEY word
MERGE statement, 5-55
Key word
OPTIONAL, 3-14
Key words
reserved, 1-6
Keyword
BY, 5-35
COBOL, 5-37
FOR, 5-62
FORTRAN, 5-37
INTO, 5-35
MACRO, 5-37
LABEL RECORD clause, 4-2~
Label type
tape handling, F-l
Labeled tapes
converting to unlabeled tapes,
F-6
tape handling, F-8
Labels
COBOL
tape handling, F-1
system
tape handling, F-1
LAST DETAIL clause
PAGE LIMIT clause, 4-76
LEADING phrase
INSPECT statement, 5-52
SIGN clause, 4-61
LEFT option
JUSTIFIED clause, 4-37
SYNCHRONIZED clause, 4-62
Level numbers
FILE SECTION, 4-3
Level-66
RENAMES clause, 4-58
Level-77 entry, 4-39
Level-number entry, 4-39
LIBARY
utility program, 7-1
LIBARY program
command string defaults, 7-23
command usage, 7-27
commands, 7-25
group mode, 7-25
invoking, 7-22
running, 7-25
source file format, 7-22
source library maintenance,
7-22
switches, 7-24
LIBARY program command
DELETE, 7-26
END, 7-27
EXTRACT, 7-26
INSERT, 7-26
REPLACE, 7-26
RESTART, 7-27
Library facility
COpy statement, 1-19

Library maintenance
LIBARY program, 7-22
LINAGE clause, 4-22
LINAGE-COUNTER, 4-23
LINAGE-COUNTER
LINAGE clause, 4-23
special register, 1-9
LINE clause
Report Writer, 10-10
LINE NUMBER clause, 4-83
NEXT PAGE option, 4-84
PLUS option, 4-83
Line numbers, 1-15
LINE-COUNTER
INITIATE statement, 5-49
RD entry, 4-72
LINES AT TOP/BOTTOM
LINAGE clause, 4-22
LINK switch
/NOSEARCH, 11-6
/NOSYSLIB, 11-7
/NOUSERLIB, 11-7
/SEARCH, 11-6
/SPACE, 11-11
/SYSLIB, 11-7
/USERLIB, 11-7
LINKAGE SECTION
DATA DIVISION, 4-5
Linkage Section
definition, 4-1
Literal IS mnemonic-name clause,
3-8
Literal option
STOP statement, 5-91
Literals
alphanumeric, 1-11
defined, 1-10
numeric, 1-10
Loading
COBDDT program, 7-29
Loading programs
with debug module, H-7
LOCATE
COBDDT command, 7-34
Logical device-names, 3-15
Logical names
defining
TOPS-20, E-l
Logi"cal operator
AND, 5-11
NOT, 5-11
OR, 5-11
Logical operators
conditional expression
combinations, 5-15
conditional expressions, 5-11
LOW-VALUE
figurative constant, 1-7
LOW-VALUES
figurative constant, 1-7
MACRO keyword
ENTER statement, 5-37

Index-II

October 1985

MACRO subprograms
argument list descriptors, 12-4
calling, 12-3
Magtapes
standard label for, 4-21
Maintaining
ignoring errors, 7-13
indexed-sequential file, 7-9
MEMORY SIZE clause, 3-4
MERGE statement, 5-55
MESSAGE COUNT
ACCEPT statement, 5-21
Mixed-mode binary
file format
ASCII, 8-20
EBCDIC, 8-22
S I XB IT, 8 - 21
Modes
recording, 8-1
MODULE
COBDDT command, 7-34
MOUNT command
tape handling, F-7
MOVE statement, 5-57
MULTI-REEL storage media, 5-29
Multi-reel volume set
tape handling, F-7
Multi-volume tapes
tape handling, F-5
MULTIPLE FILE clause, 3-38
MULTIPLY statement, 5-59
Negated combined condition, 5-15
NEGATIVE test
sign condition, 5-11
NEXT
COBDDT command, 7-34
NEXT GROUP clause, 4-85
NEXT PAGE option, 4-85
PLUS option, 4-85
Report Writer, 10-9
NEXT PAGE option
LINE NUMBER clause, 4-84
NEXT GROUP clause, 4-85
NEXT phrase
READ statement, 5-70
NEXT RECORD clause
RETAIN statement, 5-74
NEXT SENTENCE phrase
IF statement, 5-47
NO REWIND option
CLOSE statement, 5-28
OPEN statement, 5-61
Non-COBOL subprogram
subprograms, 11-3
NON-REEL storage media, 5-28
Nonnumeric
relation condition comparison,
5-8
Nonresident segments, 11-2
NOT RETAINED condition
FREE statement, 9-12

NOT RETAINED phrase
FREE statement, 5-42
Numeric
relation condition comparison,
5-8
Numeric item definition, 4-44
Numeric literal, 1-10
NUMERIC test
class condition, 5-10
Numeric test
alternate, D-l
Numeric-edited item definition,
4-44
Object libraries
subprograms, 11-6
OBJECT-COMPUTER paragraph, 3-4
Object-time system
tape handling, F-l
OCCURS clause, 4-10, 4-40
OMITTED option
LABEL RECORD clause, 4-20
ON OVERFLOW condition
CALL statement, 5-26
ENTER statement, 5-37
ON OVERFLOW phrase
STRING statement, 5-96
UNSTRING statement, 5-111
OPEN option
USE statement, 5-114
OPEN statement, 5-60
Report Writer, 10-17
simultaneous update, 5-63, 9-4
Operands
relation condition, 5-8
Operators
arithmetic, 5-6
Optimization
program, 13-1
Optimizing
available tools, 13-3
documentation, 13-5
getting started, 13-3
methods, 13-4
performance evaluation, 13-5
procedures, 13-4
programs, 13-3
Optimizing programs
tools available, 13-6
Optimizing tool
COBDDT, 13-6
Option
AFTER, 5-117
ANY VERB
simultaneous update, 9-10
BEFORE, 5-117
CHARACTERS, 4-15
CHECKPOINT OUTPUT, 3-18
CORRESPONDING, 5-18, 5-23, 5-57,
5-99
DATE, 5-20
DAY, 5-20
DEFERRED OUTPUT, 3-18

Index-12

October 1985

Option (Cont.)
DELETE, 5-28
DEPENDING, 4-40
DEPENDING ON, 5-46
END OF UNIT, 3-37
FOR REMOVAL, 5-28
FROM, 5-20, 5-72, 5-80, 5-119
GIVING, 5-23, 5-56, 5-87, 5-98
1-0, 5-62
INDEXED, 4-41
INPUT, 5-114
INPUT-OUTPUT, 5-62, 5-114
INTO, 5-71
LEFT, 4-37, 4-62
literal, 5-91
NEXT PAGE, 4-84, 4-85
NO REWIND, 5-28, 5-61
OMITTED, 4-20
OPEN, 5-114
OUTPUT, 5-114
PLUS, 4-83, 4-85
POSITION, 3-38
PROCEED TO, 5-24
RECORD, 3-38
REEL, 5-28
RERUN, 5-61
REVERSED, 5-64
RIGHT, 4-37, 4-62.1
ROUNDED, 5-17, 5-23, 5-32, 5-36,
5-59, 5-99
RUN, 5-91
SIZE ERROR, 5-17, 5-23, 5-32,
5-36, 5-~9, 5-99
SORT, 3-38
SORT-MERGE, 3-38
STANDARD, 4-20
TIME, 5-20
TO, 5-23
UNIT, 5-28
UNTIL FREED
simultaneous update, 9-10
UPON, 4-88
USING, 5-87
VARYING, 5-83
OPTIONAL
key word, 3-14
Optional
input file, 5-61
Optional words
reserved, 1-6
Organization
file, 8-23
ORGANIZATION clause, 3-17
RMS indexed files, I-I
OUTPUT option
USE statement, 5-114
OUTPUT PROCEDURE phrase
MERGE statement, 5-56
Overflow
STRING statement, 5-96
UNSTRING statement, 5-111
OVERHEAD entry
COB DDT

OVERHEAD entry
COBDDT (Cont.)
optimizing, 13-8
OVERLAY
COBDOT command, 7-35
Overlay structure
example, 11-9
Overlays, 11-8
CANCEL statement, 11-13
defining, 11-9
example of overlay structure,
11-9
examples, 11-14, 11-16, 11-17,
11-18, 11-19, 11-20, 11-21,
11-22, 11-23, 11-24, 11-25,
11-26, 11-27, 11-28
handler subroutine, 11-14
LINK related switches, 11-10
LINK switch /SPACE, 11-11
overlayable COBOL programs,
11-8
rules, 11-9
tree structure, 11-9
when to use, 11-8
Packing
ignoring errors, 7-13
indexed-sequential file, 7-12
Packing ISAM file
switch arguments, 7-13
PAGE FOOTING entry
TYPE clause, 4-88.2
PAGE HEADING entry
TYPE clause, 4-88.1
PAGE LIMIT clause, 4-76
FIRST DETAIL clause, 4-76
FOOTING clause, 4-76
HEADING clause, 4-76
LAST DETAIL clause, 4-76
Report Writer, 10-12
PAGE-COUNTER
INITIATE statement, 5-49
RD entry, 4-72
Report Writer, 10-13
Paragraph
DATE-COMPILED, 2-2
FILE-CONTROL, 3-10
I-O-CONTROL, 3-37
OBJECT-COMPUTER, 3-4
PROGRAM-ID, 2-1
SOURCE-COMPUTER, 3-3
SPECIAL-NAMES, 3-6
Paragraphs
PROCEDURE DIVISION, 5-4
Parentheses
conditional expression
combinations, 5-15
formation rules, 5-6
Parentheses separator, 1-12
PARITY clause, 3-25
PERFORM statement, 5-65
COBOL-68/74 differences, A-7
coding conventions, 13-13

Index-13

October 1985

PERFORM statement (Cont.)
cycle logic examples, 5-67
Phrase
ALL, 5-52, 5-1~5, 5-11~
ALSO
SPECIAL-NAMES, 3-8
CHARACTERS, 5-51
COLLATING SEQUENCE, 5-88
DELIMITED BY, 5-93, 5-1~9
DELIMITED BY SIZE, 5-94
DELIMITER IN, 5-196
END-OF-PAGE, 5-118
EOP, 5-118
EVERY RECORD, 5-42
simultaneous update, 9-12
EXTEND, 5-63
FIRST, 5-52
FOOTING, 4-22
INPUT PROCEDURE, 5-56
INTO, 5-79
INVALID KEY, 5-89, 5-119
KEY, 5-75
LEADING, 4-61, 5-52
LINES AT BOTTOM, 4-22
LINES AT TOP, 4-22
NEXT, 5-7~
NEXT SENTENCE, 5-47
NOT RETAINED, 5-42
ON OVERFLOW, 5-96, 5-111
OUTPUT PROCEDURE, 5-56
POINTER, 5-94, 5-197
REPLACING, 5-51
SEPARATE CHARACTER, 4-69
TALLYING, 5-51, 5-1~7
THROUGH
SPECIAL-NAMES, 3-8
TIMES, 4-49
TRAILING, 4-61
UNAVAILABLE, 5-75
UNTIL FREED, 5-75
WITH SEQUENCE CHECK, 5-56
Physical device-names, 3-14
PICTURE c1ause,4-42
editing methods, 4-59
symbols, 4-42
PICTURE string
character chart, 4-55
elementary item, 4-45
PLUS option
LINE NUMBER clause, 4-83
NEXT GROUP clause, 4-85
Pointer item
STRING statement, 5-94
UNSTRING statement, 5-196
POINTER phrase
STRING statement, 5-94
UNSTRING statement, 5-197
POSITION option
I-O-CONTROL paragraph, 3-38
POSITIONING clause
WRITE statement, 5-118
POSITIVE test
sign condition, 5-11

Print group
CONTROL, 4-76
PRINTING clause
SUPPRESS statement, 5-1~0
PROCEDURE DIVISION
execution, 5-4
paragraphs, 5-4
sections, 5-4
segmentation, 5-4
sentences, 5-2
statements, 5-2
structure, 1-4
syntactic format, 5-2
verb formats, 5-19
PROCEDURE DIVISION statement
inter-program communication,
11-5
Procedure verb
statement categories, 5-3
Procedure-name
debugging, H-4
PROCEED
COBDDT command, 7-35
PROCEED TO option
ALTER statement, 5-24
Program
LINK, 6-4
TRANSLATE, 6-2
Program access to files
competing, 9-8
Program behavior
obtain~ng histograms, 7-39
PROGRAM COLLATING SEQUENCE clause,
3-5
Program documentation, 13-5
Program example
RMS indexed file, 1-8
Program format
comment lines, 1-14
continuation area, 1-14
source, 1-13
card-type, 1-14
identification area, 1-15
terminal-type, 1-15
Program optimization
how to proceed, 13-3
methods and procedures, 13-4
Program segments, 11-1
ex am pI e s , 11- 2
nonresident segments, 11-2
section-names, 11-1
segment numbers, 11-1
PROGRAM-ID paragraph, 2-1
Programming considerations
simultaneous update, 9-3
Programs
. loading COBOL-74, 6-4
running COBOL-74, 6-4
utility, 7-1
Project-programmer number
translation, B-1
Pseudo-text delimiter separator,
1-12

Index-14

October 1985

Qualification
DATA DIVISION, 4-9
definition, 4-9
Quotation mark separator, 1-12
QUOTE
figurative constant, 1-7
QUOTES
figurative constant, 1-7
Random access
relative files, 8-25
Random files
FREE statement, 5-42
RD
report file
Report Writer, 10-8
RD entry
LINE-COUNTER, 4-72
PAGE-COUNTER, 4-72
report description, 4-72
READ statement, 5-69
Reading tape labels
ISAM program, 7-14
Record
definition, 1-3
RECORD CONTAINS clause, 4-24
SO file-name clause, 4-26
Record description
level numbers, 4-3
Record descriptions
FILE SECTION, 4-2
RECORD KEY clause, 3-20
RECORD option
I-O-CONTROL paragraph, 3-38
RECORDING MODE clause, 3-23
Recording modes
ASCII, 8-1
BINARY, 8-3
EBCDIC, 8-2
SIXBIT, 8-2
RECORDS clause
BLOCK CONTAINS, 4-15
REDEFINES clause, 4-56
REEL option
CLOSE statement, 5-28
Relation condition
abbreviated combined, 5-16
conditional expression, 5-7
format, 5-8
nonnumeric items
comparison, 5-8
numeric items
comparison, 5-8
operands, 5-8
operators, 5-8
Relative files, 8-24
accessing
simultaneous update, 9-16
COBOL-68/74 differences, A-6
dynamic access, 8-25
random access, 8-25
RETAIN statement, 5-77
sequential access, 8-24

RELATIVE KEY clause, 3-22
Relative subscripting/indexing,
4-11
RELEASE statement, 5-72
REMAINDER clause
DIVIDE statement, 5-36
RENAMES clause
level-66, 4-58
Renaming
indexed-sequential file, 7-16
REPLACE
LIBARY command, 7-26
REPLACING phrase
COpy statement, 1-21
INSPECT statement, 5-51
REPORT clause, 4-25
Report codes
Report Writer, 10-5
Report description entry
RD, 4-72
REPORT FOOTING entry
TYPE clause, 4-88.2
Report group
FOOTING, 4-76
Report group description entry,
4-78
Report groups, 4-7
detail, 4-7
REPORT HEADING entry
TYPE clause, 4-88.1
REPORT SECTION
DATA DIVISION, 4-6
Report Section
definition, 4-1
Report section format, 4-7
Report Writer
CLOSE statement, 10-19
CODE clause, 10-8
COLUMN clause, 10-10
missing, 10-12
CONTROL clause, 10-8
DECLARATIVES SECTION, 10-16
GENERATE statement, 10-18
INITIATE statement, 10-17
LINE clause, 10-10
NEXT GROUP clause, 10-9
OPEN statement, 10-17
PAGE LIMIT clause, 10-12
PAGE-COUNTER, 10-13
report codes, 10-5
report example, 10-2
report file assignment, 10-6
report file FD, 10-7
report file RD, 10-8
report file selection, 10-6
REPORT SECTION, 10-8
REPORTS ARE clause, 10-7
sample input data file, 10-4
SOURCE clause, 10-10
SUM clause, 10-11
TERMINATE statement, 10-19
TYPE statement, 10-9

Index-15

October 1985

Report Writer (Cont.)
USE BEFORE REPORTING statement,
1B-16
REPORTS ARE clause
Report Writer, 1B-7
RERUN
utility program, 7-1
RERUN clause, 3-37
RERUN option
OPEN statement, 5-61
RERUN program
examples, 7-45
operating, 7-44
restarting programs, 7-44
RESERVE clause, 3-16
Reserved word
CONSOLE, 3-6
Reserved words, 1-5
COBOL-74, B-1
connectives, 1-6
figurative constants, 1-6
key words, 1-6
optional words, 1-6
special registers, 1-8
special-character words, 1-9
RESET clause, 4-86
RESTART
LIBARY command, 7-27
Restarting programs
RERUN utility, 7-44
Restrictions
RMS indexed files, 1-7
RETAIN statement,· 5-73
indexed-sequential files, 5-78
relative files, 5-77
simultaneous update, 9-8
RETURN statement, 5-79
REVERSED option
OPEN statement, 5-64
REWRITE statement, 5-8B
RIGHT option
JUSTIFIED clause, 4-37
SYNCHRONIZED clause, 4-62.1
RMS clause, 3-18
RMS errors
RMS indexed files, 1-4
RMS indexed files
ALTERNATE RECORD KEY clause,
I-I
defining, I-I
deleting, 1-4
FD entry, 1-2
handling errors, 1-4
opening, 1-3
ORGANIZATION clause, I-I
processing, 1-3
program example, 1-8
reading, 1-3
restrictions, 1-7
SELECT clause, 1-2
START statement, I-3
using, I-6
WITH DUPLICATES clause, I-I

RMS indexed files (Cont.)
writing, I-4
RMS program
with RMS indexed files, I-6
ROUNDED option
ADD statement, 5-23
COMPUTE statement, 5-32
DIVIDE statement, 5-36
MULTIPLY statement, 5-59
PROCEDURE DIVISION, 5-17
SUBTRACT statement, 5-99
RUN option
STOP statement, 5-91
S format
transportable tape handling,
F-9
SAME AREA clause, 3-38
SCHEMA SECTION
DATA DIVISION, 4-4
Schema Section
definition, 4-1
SD file-name clause, 4-26
SEARCH statement, 5-82
Searches
subprograms, 11-6
Section
CONFIGURATION, 3-2
INPUT-OUTPUT, 3-9
SECTION statement
program segments, 11-1
SECTION word, 5-5
Section-name
priority numbers, 5-4
Section-names
program segments, 11-1
Sections
PROCEDURE DIVISION, 5-4
Segment numbers
program segments, 11-1
SEGMENT-LIMIT clause, 3-5
SEGMENT-LIMIT IS statement
program segments, 11-1
Segmentation
COBOL-68/74 differences, A-7
PROCEDURE DIVISION, 5-4
Segments types, 5-5
SELECT clause, 3-13
RMS indexed files, I-2
SELECT statement, 3-14
Selection
report file
Report Writer, IB-6
Semicolon separator, 1-12
·Sentences
PROCEDURE DIVISION, 5-2
SEPARATE CHARACTER phrase
SIGN clause, 4-6~
Separators
COBOL, 1-12
comma, 1-12
horizontal tah, 1-12
parentheses, 1-12

Index-16

October 1985

Separators (Cont.)
pseudo-text delimiter, 1-12
quotation marks, 1-12
semicolon, 1-12
space, 1-12
Sequence of operations, 5-7
Sequences
collating
character, C-1
Sequential access
relative files, 8-24
Sequential file
access strategies, 9-13
Sequential files, 8-23
accessing
simultaneous update, 9-12
basic reading, 9-12
basic updating, 9-13
basic writing, 9-13
FREE statement, 5-42
SET statement, 5-85
SHOW SYMBOLS
COBDDT command, 7-36
SIGN clause, 4-60
Sign condition
conditional expression, 5-11
format, 5-11
NEGATIVE test, 5-11
POSITIVE text, 5-11
ZERO test, 5-11
Simultaneous update, 9-1
accessing indexed-sequential
files, 9-18
accessing relative files, 9-16
buried update, 9-2
deadly embrace, 9-3
example, 9-7
methods, 9-1
OPEN statement, 5-63
program access
competing, 9-8
programming considerations, 9-3
projecting resources, 9-4
reading sequential files, 9-12
sequential files
accessing, 9-12
updating sequential files, 9-13
writing sequential files, 9-13
SINGLE REEL storage media, 5-29
Single-precision
fixed-point, 5-18
Single-reel volume set
tape handling, F-7
SI XB I'r
fixed-length
file format, 8-8.1
recording mode, 3-23, 8-2
transportable tape handling,
F-11
variable-length
file format, 8-10
SIXBIT conversion
from ASCII, C-3

SIXBIT data type, 13-10
SIXBIT mixed-mode binary
file format, 8-21
SIZE ERROR option
ADD statement, 5-23
COMPUTE statement, 5-32
DIVIDE statement, 5-36
MULTIPLY statement, 5-59
PROCEDURE DIVISION, 5-17
SUBTRACT statement, 5-99
SORT option
I-O-CONTROL paragraph, 3-38
SORT statement, 5-86
collating sequence, 5-88
SORT-MERGE option
I-O-CONTROL paragraph, 3-38
SOURCE clause, 4-87
Report Writer, 10-10
Source items
STRING statement, 5-92
UNSTRING statement, 5-104
Source library
file format, 7-22
maintenance
LIBARY, 7-22
Source library facility, 1-19
SOURCE-COMPUTER paragraph, 3-3
SPACE
figurative constant, 1-7
Space
LOW-VALUES equivalence, 3-8
Space restrictions
DATA DIVISION, 13-12
Space separator, 1-12
SPACES
figurative constant, 1-7
Special register
DATE, 1-9
DAY, 1-8
DEBUG-ITEM, 5-115, H-l
LINAGE-COUNTER, 1-9
TIME, 1-9
Special registers
rese rved, 1-8
Special-character words
reserved, 1-9
SPECIAL-NAMES paragraph, 3-6
Standard label
magtapes, 4-21
STANDARD option
LABEL RECORD clause, 4-20
STANDARD-ASCII
recording mode, 3-24
transportable tapes, F-9
STANDARD-ASCII tapes
tape handling, F-6
START statement, 5-89
RMS indexed files, 1-3
Starting
COBDDT program, 7-29
Statement
ACCEPT, 5-20
ADD, 5-22

Index-17

October 1985

Statement (Cont.)
ALTER, 5-24
CALL, 5-25
differences, A-7
CANCEL, 5-27
differences, A-7
CLOSE, 5-28
COMPUTE, 5-32
COpy
differences, A-8
DELETE, 5-33
DISPLAY, 5-34
DIVIDE, 5-35
ENTER, 5-37
ENTRY, 5-38, 11-5
EXIT, 5-39
EXIT PROGRAM, 5-4~
FREE, 5-41, 9-11
GENERATE, 5-44
GO TO, 5-46
IF, 5-47
INITIATE, 5-49
INSPECT, 5-5~
MERGE, 5-55
MOVE, 5-57
MULTIPLY, 5-59
OPEN, 5-6~, 9-4
PERFORM, 5-65
differences, A-7
PROCEDURE DIVISION, 11-5
READ, 5-69
RELEASE, 5-72
RETAIN, 5-73, 9-8
RETURN, 5-79
REWRITE, 5-8~
SEARCH, 5-82
SECTION, 11-1
SEGMENT-LIMIT IS, 11-1
SELECT, 3-13, 3-14
SET, 5-85
SORT, 5-86
STAR T , 5 - 8 9 , I - 3
STOP, 5-91
STRING, 5-92
SUBTRACT, 5-98
SUPPRESS, 5-1~~
TERMINATE, 5-1~1
TRACE, 5-1~2
TRACE OFF, 5-1~2
TRACE ON, 5-1~2
UNSTRING, 5-1~4
USE, 5-113
USE FOR DEBUGGING, 5-115, H-3
WRITE, 5-116
Statement categories
procedure verb, 5-3
Statement ordering
coding conventions, 13-15
Statements
PROCEDURE DIVISION, 5-2
STEP
COBDDT command, 7-36

STOP
COBDDT command, 7-37
STOP RUN statement
inter-program communication,
11-6
STOP statement, 5-91
Storage media
MULTI-REEL, 5-29
NON-REEL, 5-28
SINGLE REEL, 5-29
STRING statement, 5-92
delimiter items, 5-93
destination item, 5-94
execution, 5-94
overflow, 5-96
pointer item, 5-94
source items, 5-92
Structure
COBOL progra~, 1-3
Subprogram structure
loading, 11-6
Subprograms, 11-3
CALL statement, 11-4
ENTRY statement, 11-3
examples, 11-7
inter-program communication,
11-4
LINKAGE SECTION, 11-3
loading subprogram structure,
11-6
non-COBOL subprogram, 11-3
object libraries, 11-6
searches, 11-6
USING clause, 11-3
Subscript usage
coding conventions, 13-12.1
Subscripting
DATA DIVISION, 4-l~
relative/direct, 4-11
Subscripting forms, 4-11
Subscripts
efficient data types, 13-11
multiple, 4-11
SUBTRACT statement, 5-98
SUM clause, 4-88
Report Writer, 1~-11
UPON option, 4-88
SUPPRESS statement, 5-1~0
Switch

/A
file packing, 7-13
Switches
compiler, 6-3
LIBARY program, 7-24
Symbology
braces, 1-2
brackets, 1-2
ellipsis, 1-2
underline, 1-2
Symbols
COBOL, 1-1
PICTURE clause, 4-42
SYNCHRONIZED clause, 4-62

Index-18

October 1985

System
object-time
tape handling, F-l
System labels
tape handling, F-l
System-labeled tapes
tape handling, F-8
System-owned tape drive
tape handling, F-7
Tables
conversion
collating sequences, C-l
TALLYING phrase
INSPECT statement, 5-51
UNSTRING statement, 5-107
Tape handling
ANSI labeled tapes, F-8
ASCII for TOPS-20, F-10
ASCII transportable tapes, F-9
available tape drive, F-7
binary transportable tapes,
F-ll
COBOL labels, F-l
converting tape labels, F-6
defaults, F-4
definitions, F-l
directions, F-l
EBCDIC for TOPS-10, F-10
EBCDIC for TOPS-20, F-10
EBCDIC labels, F-ll
finding inst~uctions, F-2
label type, F-l
labeled tapes, F-8
MOUNT command, F-7
multi-reel volume set, F-7
multi-volume tapes, F-5
object-time system, F-l
restrictions, F-4
single-reel volume set, F-7
SIXBIT transportable tapes,
F-ll
STANDARD-ASCII
transportable tapes, F-9
STANDARD-ASCII tapes, F-6
symbols used in text, F-4
system labels, F-l
system-labeled tapes, F-8
system-owned tape drive, F-7
tape with no labels, F-7
TOPS-10 restrictions, F-6
TOPS-20 defaults, F-5
transportable tapes, F-9
undefined formatted tape, F-10
unlabeled tapes
using, F-6
use considerations, F-4
volume, F-2
volume number, F-2
volume set, F-2
Tape with no labels
tape handling, F-7

Tapes
transportable
formats, F-9
Term
block, 1-3
item, 1-3
record, 1-3
words, 1-5
Terminal-type
source program format, 1-15
Terminal-type format
with line numbers, 1-16
without line numbers, 1-17
TERMINATE statement, 5-101
Report Writer, 10-19
Terms
COBOL, 1-1, 1-3
TIME
special register, 1-9
TIME option
ACCEPT statement, 5-20
TIMES phrase
OCCURS clause, 4-40
TO option
ADD statement, 5-23
TOPS-10 defaults
tape handling, F-6
TOPS-20
defining logical names, E-l
TOPS-20 restrictions
tape handling, F-5
TRACE
COBDDT command, 7-37
TRACE statement, 5-102
TRAILING phrase
SIGN clause, 4-61
TRANSL command
directory translation, E-l
TRANSLATE program, 6-2
Transportable tapes
ASCII, F-10
binary, F-ll
EBCDIC, F-10
EBCDIC tape handling, F-10
SIXBIT, F-ll
tape handling, F-9
Tree structure
overlays, 11-9
TYPE clause, 4-88.1
CONTROL FOOTING entry, 4-88.2
CONTROL HEADING entry, 4-88.1
DETAIL entry, 4-88.1
FINAL entry, 4-88.2
PAGE FOOTING entry, 4-88.2
PAGE HEADING entry, 4-88.1
REPORT FOOTING entry, 4-88.2
REPORT HEADING entry, 4-88.1
TYPE statement
Report Writer, 10-9
U format
transportable tape handling,
F-10

Index-19

October 1985

UNAVAILABLE clause, 5-63
UNAVAILABLE phrase
RETAIN statement, 5-75
Underline
symbology, 1-2
Underscore
HIGH-VALUES equivalence, 3-8
UNIT option
CLOSE statement, 5-28
Unlabeled system tapes
tape handling, F-6
Unlabeled tapes
converting to labeled tapes,
F-6
UNPROTECT
COBDDT command, 7-38
UNSTRING statement, 5-104
count storage items, 5-106
delimiter items, 5-105
delimiter storage items, 5-106
destination counter, 5-107
destination items, 5-104
execution, 5-107
overflow, 5-111
pointer item, 5-106
source items, 5-104
UNTIL clause
PERFORM statement, 5-67
UNTIL FREED option
RETAIN statement, 9-10
UNTIL FREED phrase
RETAIN statement, 5-75
UP BY clause
SET statement, 5-85
Update
simultaneous, 9-1
UPON option
SUM clause, 4-88
Usage
explicit, 4-10
implicit, 4-10
USAGE clause, 4-64
COMPUTATIONAL format, 4-65
COMPUTATIONAL-l format, 4-65
COMPUTATIONAL-3 format, 4-66
DATABASE-KEY format, 4-69
DISPLAY format, 4-67
DISPLAY-6 format, 4-67
DISPLAY-7 format, 4-67
DISPLAY-9 format, 4-68
INDEX format, 4-68
USE BEFORE REPORTING
statement, 10-16
USE FOR DEBUGGING statement,
5-115
debug module, H-3
USE statement, 5-L13
DECLARATIVES, 5-113
Report Writer, 10-16
User-defined words, 1-9
USER-NUMBER clause, 4-27
Using
FIPS flagger, G-2

Using (Cont.)
indexed-sequential file, 7-20
USING clause
CALL statement, 5-25
ENTER statement, 12-1
ENTRY statement, 5-38
inter-program communication,
11-5
PROCEDURE DIVISION, 5-1, 5-2
USING option
SORT statement, 5-87
Using RERUN program
examples, 7-45
Utility
LIBARY program, 7-22
Utility program
COBDDT, 7-1
ISAM, 7-1
LIBARY, 7-1
RERUN, 7-1
Utility programs
COBOL-74, 7-1
V

recording mode, 3-24
VALUE clause, 4-70
VALUE OF IDENTIFICATION clause,
4-27
Variable-length ASCII
file format, 8-6
Variable-length EBCDIC
file format, 8-14
Variable-length SIXBIT
file format, 8-10
VARYING option
SEARCH statement, 5-83
Verb formats
PROCEDURE DIVISION statements,
5-19
Volume
tape handling, F-2
Volume number
tape handling, F-2
Volume set
mul t i-reel,' F-7
single-reel, F-7
tape handling, F-2
WHEN condition
SEARCH statement, 5-83
WHERE
COBDDT command, 7-38
WITH DEBUGGING MODE clause, 3-3
WITH DUPLICATES clause
RMS indexed files, I-I
WITH NO ADVANCING clause
DISPLAY statement, 5-34
WITH SEQUENCE CHECK phrase
MERGE statement, 5-56
Word
character string, 1-5
FILLER, 4-36
FROM, 5-98

Index-20

October 1985

Word (Cont.)
KEY, 5-55
PRINTING, 5-1gg
SECTION, 5-5
Word integer, 1-11
Words
user-defined, 1-9
WORKING-STORAGE SECTION
DATA DIVISION, 4-5
Working-Storage Section
definition, 4-1
WRITE statement, 5-116

Writing tape labels
ISAM program, 7-14
ZERO
figurative constant, 1-7
ZERO test
sign condition, 5-11
ZEROES
figurative constant, 1-7
ZEROS
figurative constant, 1-7

Index-21

October 1985

TOPS-10/TOP8-20
COBOL-74 Language Manual
AD-505gB-T1
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.

D Assembly language programmer
D Higher-level language programmer
D Occasional programmer (experienced)

D User with little programming experience
D Student programmer

D Other (please spec~y)~~~~~~~~~~~~~~~~~~~~~

Name~~

__~__~__~~~__~~~_____ Date~__~~~~_________

Organization
Telephone __~~_~~~~_
Street __________________________________________________________

City ___________________________________ State _______ Zip Code ~_~
or Country

--m-.-

-0

I
I
I
I

mN.oto
Tear t-

.'Oa

"Due and Tape - - - - - - - - - - - - - - - - - - - - - -

f~-111--------~~~~;:;~~ -__

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 MR01-2/L12

MARLBOROUGH, MA 01752

Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

I
I
I
I
I
I

UPDATE NOTICE
TOP5-10/TOP5-20
COBOL-74 Language Manual
AD-5059B-T1

October 1985

Insert this Update Notice in the TOPS-10ITOPS-20 COBOL-74
Language Manual to maintain an up-to-date record of changes
to the manual.
Changed Information
The changed pages contained in this update package reflect
the software of Version 12C of the COBOL-74 compiler
(CBL74), and Version 12C of the object-time system (C740TS),
and Version 4C of SORT.
The instructions for inserting this update start on the next page.

~D~DDmD

wore

INSTRUCTIONS
AD-50598-T1
The following list of page numbers specifies which pages are to be placed in the TOPS-10/TOPS-20
COBOL-74 Language Manual as replacements for, or additions to, current pages.
[Title page
Copyright page

[3-27
3-28

[4-43
4-46

[8-3
8-8.2

[Entire Table
of Contents

[3-37
3-40

[4-61
4-62.2

[8-23
8-24

[1-7
1-8

[3-43
3-44

[4-67
4-68

[Entire
Chapter 10

[1-15
1-18

[4-71
4-90

[11-3
11-4.2

[1-21
1-22

[4-11
4-16

[5-33
5-34

[12-1
12-2

[4-21
4-22

[5-51
5-54

[13-9
13-12.2

[3-11
3-12

[4-25
4-28

5-61
[5-62

[Entire
Index

[3-19
3-24

[4-39
4-40

[5-69
5-78

KEEP THIS UPDATE NOTICE IN YOUR MANUAL TO MAINTAIN AN UP-TO-DATE
RECORD OF CHANGES.
TYPE AND IDENTIFICATION OF DOCUMENTATION CHANGES.

Five types of changes are used to update documents contained in the TOPS-10/TOPS-20 software
manuals. Change symbols and notations are used to specify where, when, and why alterations were
mal.. ....' to each update page. The five types of update changes and the manner in which each is
identified are described in the following table.
The Following Symbols and/or Notations

Identify the Following Types of Update Changes

1. Change bar in outside margin; version number and change date printed at bottom of
page.

1. Changes were required by a new version of
the software being described.

2. Change bar in outside margin; change date
printed at bottom of page.

2. Changes were required to either clarify or
correct the existing material.

3. Change date printed at bottom of page.

3. Changes were made for editorial purposes
but use of the software is not affected.

4. Bullet (e) in outside margin; version number
and change date printed at bottom of page.

4. Data was deleted to comply with a new version of the software being described.

5. Bullet (e) in outside margin; change date
printed at bottom of page.

5. Data was deleted to either clarify or correct
the existing material.
October 1985

UPDATE NOTICE

TOP~1 O/TOP~20

COBOL-74
Language Manual

AD-5059A-T1

January 1980
Insert this update notice in the COBOL-74 Reference Manual to
maintain an up-to-date record of changes to this manual.
CHANGED INFORMATION
The change pages contained in this update package reflect
Version 12A of the COBOL-74 compiler, Version 12A of
C740TS, the object-time system, and Version 4B of SORT.

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
2625 Augustine Drive
Santa Clara, California 96061
Telephone: (408) 984·0200

INSTRUCTIONS
AA-5059A-T1
The following list of page numbers specifies which pages are to be placed in COBOL-74 Language
Manual as replacements for, or additions to, current pages.

[title page
copyright page

[4-37
4-40

[5-61
5-64

[5-101
5-108

[Vii
viii

[4-79
4-80

[5-71
5-80

[5-111
5-113

C-

19
1-20

[5-19
5-20.1

[5-83
5-86

[5-119
5-124

[3-37
3-40

[5-93
5-94

[7-23
7-28

[3-7
3-24

[4-9
4-12

[5-97
5-98

[9-9
9-10
entire index

KEEP THIS UPDATE NOTICE IN YOUR MANUAL TO MAINTAIN AN UP-TO-DATE RECORD OF
CHANGES.

TYPE AND IDENTIFICATION OF DOCUMENTATION CHANGES
Five types of changes are used to update documents contained in the TOPS-10ITOPS-20 software
manuals. Change symbols and notations are used to specify where, when, and why alterations were
made to each updated page. The five types of update changes and the manner in which each is
identified are described in the following table.

The following Symbols and/or Notations

Identify the Following Types of Update

Change bar in outside margin; version number
and change date printed at bottom of page.

Changes were required by a new version of
the software being described.

Change bar in outside margin; change date
printed at bottom of page.

Changes were required to either clarify or
correct the existing material.

Change date printed at the bottom of page.

Changes were made for editorial purposes,
but use of the software is not affected.

Bullet (e) in outside margin; version number
and change date printed at bottom of page.

Data was deleted to comply with a new
version of the software being described.

Bullet (e) in outside margin; change date
printed at bottom of page.

Data was deleted to either clarify or correct
the existing material.

January 1980