Digital PDFs

AA-D339A-TC

July 1978

370 pages

Original

15MB

Document:	TRAX COBOL User's Guide
Order Number:	AA-D339A-TC
Revision:	0
Pages:	370
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/trax/AA-D339A-TC_TRAX_V1.0_COBOL_Users_Guide_Jul78.pdf

OCR Text

July 1978

This document describes how to use the TRAX COBOL
compiler. It is a companion guide to the TRAX COBOL
Language Reference Manual.

TRAX
COBOL User's Guide
Order No. AA-D339A-TC

OPERATING SYSTEM AND VERSION:

TRAX Version 1.0

SOFTWARE VERSION:

TRAX COBOL V03.5

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation · maynard, massachusetts

First Printing, July 1978

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 postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DECUS
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-II

DECsystem-10
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8

7/78-14

MASSBUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-II
TMS-ll
ITPS-IO

CONTENTS

Page
PREFACE
CHAPTER

CHAPTER

xv
1

INTRODUCTION

1-1

1.1
1.1.1
1.1.2
1.1.3
1.1.4
1.2
1.2.1
1.2.2

THE COBOL SOURCE PROGRAM
The Identification Division
The Environment Division
The Data Division
The Procedure Division
THE COBOL UTILITY PROGRAMS
ODL MERGE
REFORMAT

1-5
1-5
1-5
1-5
1-6
1-7
1-7
1-7

USING TRAX COBOL

2-1

2.1
INTRODUCTION
2.2
CREATING TRAX COBOL PROGRAMS
2.2.1
Creating Source Language Statement Files
2.2.2
Compiling COBOL Programs
2.2.3
Linking the Task
2.2.4
Running Your Program
2.3
USING THE LIBRARY FACILITY (COPY)
2.3.1
Creating a COBOL Library File
The COpy Statement
2.3.2
The COpy REPLACING Statement
2.3.3
Examples of COpy REPLACING Statement
2.3.3.1
2.3.4
The Source Listing
2.3.4.1
Before the COpy Statement
2.3.4.2
After the COpy Statement
2.3.5
Common Errors in Using the Library Facility
2.4
COMPILER SWITCHES
2.5
SAMPLE TRAX COBOL OUTPUT
2.6
USING THE ODL MERGE UTILITY
2.6.1
Invoking the Merge utility
2.6.2
ODL Merge Utility Error Messages
2.7
REFORMAT
2.7.1
REFORMAT Command String
2.7.2
REFORMAT Error Messages

2-1
2-1
2-1
2-2
2-4
2-4
2-4
2-5
2-5
2-8
2-9
2-11
2-11
2-12
2-12
2-13
2-16
2-25
2-26
2-28
2-30
2-31
2-31

NON-NUMERIC CFARACTER HANDLING

3-1

3.1
3.2
3.2.1
3.2.2
3.3
3.4
3.4.1

INTRODUCTION
DATA ORGANIZATION
Group Items
Elementary Items
SPECIAL CHARACTERS
TESTING NON-NUMERIC FIELDS
Relation Tests

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

iii

CONTENTS (Con t. )

Page

CHAPTER

Classes of Data
3.4.1.1
The Comparison Operation
3.4.1.2
3.4.2
Class Tests
3.5
DATA MOVEMENT
3.6
THE MOVE STATEMENT
3.6.1
Group Moves
3.6.2
Elementary Moves
3.6.2.1
Edited Moves
3.6.2.2
Justified Moves
Multiple Receiving Fields
3.6.3
Subscripted Moves
3.6.4
Common Errors, MOVE Statement
3.6.5
Format 2 - MOVE CORRESPONDING
3.6.6
THE STRING STATEMENT
3.7
Multiple Sending Fields
3.7.1
3.7.2
The POINTER Phrase
The DELIMITED BY Phrase
3.7.3
The OVERFLOW Phrase
3.7.4
3.7.5
Subscripted Fields in STRING Statements
3.7.6
Common Errors, STRING Statement
THE UNSTRING STATEMENT
3.8
3.8.1
Multiple Receiving Fields
3.8.2
The DELIMITED BY Phrase
3.8.2.1
Multiple Delimiters
3.8.3
The COUNT Phrase
3.8.4
The DELIMITER Phrase
3.8.5
The POINTER Phrase
The TALLYING Phrase
3.8.6
3.8.7
The OVERFLOW Phrase
Subscripted Fields in UNSTRING Statements
3.8.8
3.8.9
Common Errors, UNSTRING Statement
3.9
THE INSPECT STATEMENT
The BEFORE/AFTER Phrase
3.9.1
3.9.2
Implicit Redefinition
3.9.3
The INSPECT Operation
3.9.3.1
Setting the Scanner
3.9.3.2
Active/Inactive Arguments
3.9.3.3
Finding an Argument Match
3.9.4
Subscripted Fields in INSPECT Statements
3.9.5
The TALLYING Phrase
3.9.5.1
The Tally Counter
3.9.5.2
The Tally Argument
3.9.5.3
The Tally Argument List
3.9.5.4
Interference in Tally Argument Lists
3.9.6
The REPLACING Phrase
3.9.6.1
The Search Argument
3.9.6.2
The Replacement Value
3.9.6.3
The Replacement Argument
3.9.6.4
The Replacement Argument List
Interference in Replacement Argument Lists
3.9.6.5
3.9.7
Common Errors, INSPECT Statement

3-5
3-6
3-6
3-7
3-8
3-8
3-8
3-10
3-10
3-11
3-11
3-12
3-12
3-13
3-13
3-14
3-15
3-17
3-18
3-20
3-21
3-21
3-23
3-27
3-28
3-29
3-30
3-32
3-33
3-34
3-36
3-36
3-37
3-38
3-40
3-41
3-41
3-42
3-43
3-43
3-44
3-44
3-45
3-47
3-51
3-51
3-52
3-52
3-53
3-54
3-55

NUMERIC CHARACTER HANDLING

4-1

4.1
4.2
4.2.1

INTRODUCTION
USAGES, DISPLAY/COMP
Sign Conventions

4-1
4-1
4-2

CONTENTS (Cont.)

Page
4.2.2
4.3
4.3.1
4.3.2
4.3.3
4.4
4.4.1
4.4.2
4.4.3
4.4.4
4.5
4.5.1
4.5.2
4.5.3
4.5.4
4.5.5

4-3
4-6
4-6
4-6
4-7
4-8
4-8
4-8
4-10
4-12
4-12
4-12
4-13
4-14
4-15

4.6.3

Illegal Values in Numeric Fields
TESTING NUMERIC FIELDS
Relation Tests
Sign Tests
Class Tests
THE MOVE STATEMENT
Group Moves
Elementary Numeric Moves
Elementary Numeric Edited Moves
Common Errors, Numeric MOVE Statements
THE ARITHMETIC STATEMENTS
Intermediate Results
The ROUNDED Phrase
The SIZE ERROR Phrase
The GIVING Phrase
Multiple Operands in ADD and SUBTRACT
Statements
The ADD Statement
The SUBTRACT Statement
The MULTIPLY Statement
The DIVIDE Statement
The COMPUTE Statement
Common Errors, Arithmetic Statements
ARITHMETIC EXPRESSION PROCESSING
Motivation for Intermediate Results
Intermediate Results for Arithmetic
Expressions
Example of Intermediate Result Fields

TABLE HANDLING

5-1

5.1
5.2
5.2.1
5.2.2
5.3
5.3.1
5.4
5.4.1
5.4.2
5.4.3
5.4.4
5.4.5
5.4.6

5-1
5-1
5-2
5-2
5-3
5-7
5-9
5-9
5-10
5-11
5-11
5-12

5.4.11
5.4.12
5.4.13
5.4.14

INTRODUCTION
DEFINING TABLES
The OCCURS Phrase - Format 1
The OCCURS Phrase - Format 2
MAPPING TABLE ELEMENTS
Initializing Tables
SUBSCRIPTING AND INDEXING
Subscripting with Literals
Operations Performed by the Software
Subscripting with Data-Names
Operations Performed by the OTS on Data Names
Subscripting with Indexes
Operations Performed by the OTS on the SET
Statement
Relative Indexing
Index Data Items
The SET Statement
Referencing a Variable Length Table Element
at OTS Time
Referencing a Dynamic Group at OTS Time
The SEARCH Verb
The SEARCH Verb - Format 1
The SEARCH Verb - Format 2

FILE HANDLING

6-1

6.1
6.1.1

SEQUENTIAL FILE ORGANIZATION
Record Size

6-3
6-4

4.5.6
4.5.7
4.5.8
4.5.9
4.5.10
4.5.11
4.6
4.6.1
4.6.2

CHAPTER

5.4.7
5.4.8
5.4.9
5.4.10

CHAPTER

4-15
4-16
4-16
4-17
4-17
4-18
4-18
4-19
4-19
4-22
4-26

5-12
5-13
5-14
5-14
5-15
5-15
5-16
5-16
5-17

CONTENTS (Cont.)

Page

6.1.2
RECORD CONTAINS Clause
6.1.3
SAME RECORD AREA Clause
6.1.4
Print-Controlled Records
6.1.5
Record Blocking
Buffering
6.1.6
Buffer Size
6.1.6.1
6.1.6.2
1-0 Buffer Areas
6.1.6.3
Buffer Space
6.1.6.4
Sharing Buffer Space Among Files
6.1.7
Sequential I/O Statements
6.1.7.1
Opening Sequential Files
6.1.7.2
Reading Sequential Files
6.1.7.3
Rewriting Records into Sequential Files
6.1.7.4
Writing Sequential Files
6.1.7.5
Closing Sequential Files
6.2
RELATIVE FILE ORGANIZATION
6.2.1
Record Size
6.2.2
RECORD CONTAINS Clause
6.2.3
SAME RECORD AREA Clause
6.2.4
Record Blocking
6.2.5
Buffering
6.2.5.1
Buffer Size
6.2.5.2
I/O Buffer Areas
6.2.5.3
Buffer Space
6.2.5.4
Sharing Buffer Space Among Files
6.2.6
Relative I/O Statements
6.2.6.1
Access Modes
6.2.6.2
Opening Relative Files
6.2.6.3
Reading Relative Files
6.2.6.4
Rewriting Records into a Relative File
6.2.6.5
Writing Records in a Relative File
6.2.6.6
Deleting Records from a Relative File
6.2.6.7
Specifying the Next Record to be Read
6.2.6.8
Closing Relative Files
6.3
INDEXED FILE ORGANIZATION
6.3.1
Record Size
6.3.2
RECORD CONTAINS Clause
6.3.3
SAME RECORD AREA Clause
6.3.4
Record Blocking
6. 3.5
Buffering
6.3.5.1
Buffer Size
6.3.5.2
I/O Buffer Areas
6.3.5.3
Buffer Space
6.3.5.4
Sharing Buffer Space Among Files
6.3.6
Indexed I/O Statements
6.3.6.1
Access Mode
6.3.6.2
Opening Indexed Files
6.3.6.3
Reading Indexed Files
6.3.6.4
Rewriting Records into an Indexed File
6.3.6.5
Deleting Records from an Indexed File
6.3.6.6
Specifying the Next Record to be READ
6.3.6.7
Closing Indexed Files
6.4
DEVICES
6.4.1
Disk
Magnetic Tape
6.4.2
6.4.3
Line Printer
6.5
FILES AND FILENAMES
Using Explicit Filenames (VALUE OF ID Clause)
6.5.1
vi

6-4
6-5
6-6
6-6
6-7
6-8
6-8
6-8
6-8
6-9
6-9
6-11
6-12
6-12
6-13
6-13
6-14
6-14
6-15
6-15
6-17
6-18
6-18
6-18
6-18
6-18
6-19
6-20
6-21
6-22
6-22
6-22
6-23
6-24
6-24
6-27
6-27
6-27
6-27
6-30
6-30
6-30
6-31
6-31
6-31
6-32
6-33
6-34
6-34
6-35
6-35
6-37
6-37
6-38
6-39
6-39
6-40
6-41

CONTENTS (Cont.)

Page
Switches
6.5.1w1
6.5.2
Device Assignment by ASSIGN Clause
Files and Logical Units
6.5.3
6.6
OPTIMIZATION
6.6.1
Speed Optimization
6.6.2
Space Optimization
6.7
COMMUNICATING WITH THE PROGRAM
6.7.1
Using the ACCEPT Statement
6.7.2
Using the DISPLAY Statement
6.8
FILE COMPATIBILITY WITH OTHER PROGRAMMING
LANGUAGES
6.8.1
Writing Files For Other Programming
Languages
6.8.2
Reading Files Written in Other Programming
Languages
6.8.3
Data File Transportability
6.9
PROCESSING I/O ERRORS - USE STATEMENT
CHAPTER

CHAPTER

6-42
6-44
6-44
6-45
6-45
6-47
6-48
6-48
6-49
6-50
6-50
6-51
6-51
6-52

GOOD PROGRAMMING PRACTICES

7-1

7.1
7.2
7.3
7.4
7.5
7.6
7.6.1
7.6.2
7.6.3
7.6.4
7.6.5
7.6.6

FORMATTING THE SOURCE PROGRAM
USE OF PUNCTUATION
USE OF THE ALTER STATEMENT
USE OF THE PERFORM STATEMENT
USE OF LEVEL 88 CONDITION-NAMES
USE OF QUALIFIED REFERENCES
Qualified Data References
Guideline 1 (Data Item Definition)
Guideline 2 (Reference Format)
Guideline 3 (Unique Referability)
Qualified Procedure References
Qualification and Compiler Performance

7-1
7-4
7-5
7-5
7-6
7-8
7-8
7-10
7-10
7-11
7-11
7-12

SEGMENTATION

8-1

8.1
8.1.1
8.2
8.3
8.4

USING THE TRAX COBOL SEGMENTATION FACILITY
Programming Considerations
SEGMENTATION AND THE PDP-II COBOL COMPILER
SEGMENTATION USING THE /OV SWITCH
USING THE /CSEG:nnnn SWITCH

8-1
8-2
8-2
8-2
8-3

INTER-PROGRAM COMMUNICATIONS

9-1

9.1
9.1.1

COBOL MAIN PROGRAMS VERSUS SUBPROGRAMS
Calling a COBOL Subprogram from a COBOL
Program
Returning from a COBOL Subprogram
UNIQUENESS OF PSECT NAMES
COBOL OTS - ERROR CHECKING
INCLUDING A MACRO OBJECT MODULE IN A COBOL
TASK

9-1
9-2
9-3
9-3
9-3

HAND-TAILORING ODL FILES

10-1

STANDARD ODL FILE
ODL FILE HEADER
ODL FILE BODY

10-1
10-1
10-2

9.1.2
9.2
9.3
9.4
CHAPTER 10
10.1
10.2
10.3

vii

9-4

CONTENTS (Cont.)

Page
10.4
10.4.1

COMPILER-GENERATED ODL FOR COBOL PSECTS
ODL Generated for Overlays Containing Only
One PSECT
ODL Generated for Overlays Containing More
Than One PSECT
ODL Generated for All Overlay able PSECTs
MERGING STANDARD ODL FILES
INCLUDING NON-COBOL PROGRAMS IN A TASK
Creating a Standard COBOL ODL File
REARRANGING A COMPILER-GENERATED ODL FILE
Modifying the Compiler-Generated ODL File
Specifying LINKER Options

10-3
10-3
10-5
10-5
10-5
10-6
10-6
10-8

ERROR MESSAGES

11-1

COMPILER SYSTEM ERRORS
DIAGNOSTIC ERROR MESSAGES
RUNTIME FILE I/O ERROR PROCEDURES
RUN-TIME ERROR MESSAGES
OTS Auxiliary Error Message Information

11-1
11-1
11-4
11-6
11-6

APPENDIX A

THE COBOL FORMATS

A-I

APPENDIX B

COBOL DATA CONVERSION SUBROUTINES

B-1

CNVT
CALL Statement
Details on Use of CNVT
STRNUM
CALL Statement

B-1
B-2
B-3
B-3
B-4

APPENDIX C

LOGICAL UNIT NUMBER (LUN) ASSIGNMENTS

C-l

APPENDIX D

TRAX COBOL COMPILER IMPLEMENTATION LIMITATIONS

D-1

APPENDIX E

COMPILER GENERATED PSECTS

E-1

PSECT NAMING CONVENTIONS

E-1

SORTING FILES IN A COBOL PROGRAM

F-1

CALL STATEMENTS REQUIRED
Initializing the SORT - CALL RSORT
Passing a Record to the Sort - CALL RELES
Merging the Scratch Files - CALL MERGE
Requesting an OUTPUT Record - CALL RETRN
Terminating the Sort - CALL ENDS
SETTING UP THE KEY
WORK AREA SIZE
TYPICAL USAGE SEQUENCE
LINKING SORT ROUTINES WITH A COBOL PROGRAM
COMPARISON WITH ANS COBOL SORT VERB
ERROR CODES

F-1
F-1
F-2
F-2
F-2
F-3
F-3
F-3
F-3
F-4
F-4
F-5

APPENDIX G

DIAGNOSTIC ERROR MESSAGES

G-1

APPENDIX H

RECORD MANAGEMENT SERVICES ERROR CODES

H-1

10.4.2
10.4.3
10.5
10.6
10.6.1
10.7
10.7.1
10.7.2
CHAPTER 11
11.1
11.2
11.3
11.4
11.4.1

B.1
B.l.1
B.1.2
B.2
B.2.1

E.1
APPENDIX F
F.l
F.l.1
F.1.2
F.1.3
F.1.4
F.l.5
F.2
F.3
F.4
F.5
F.6
F.7

viii

10-3
10-3

CONTENTS (Cont.)

Page
APPENDIX I

OBJECT TIME SYSTEM ERROR MESSAGES

INDEX

I-I
Index-l

FIGURES
FIGURE

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

Building a COBOL Task Image
Sample COBOL Procedural Coding
Merging a Library File
Merging a Library File Area B
Using the COpy Statement in a Data Description
Using the COpy Statement in a Procedural
Statement
Placing the Library Text Before the COpy
Statement
Placing the Library Text After the COpy
Statement
Sample Source Program Listing
File-to-Relative-LUN Assignment Table
Sample Data Map
Sample Procedure-Name Map
Sample Segmentation Map
Sample of Compiler-Generated PSECT Map
Sample Map of Referenced OTS Routines
Sample Data PSECT Map
Sample Map of External Subprogram References

1-4
1-6
2-7
2-7
2-8

MAP

2-24
2-24
2-25
2-25
2-26
2-28
3-2
3-3
3-4
3-4
3-5
3-6
3-10
3-11
3-11
3-13
3-13
3-14
3-14
3-14
3-15
3-15
3-16
3-16
3-17

Sample Compilation Error Count Listing
Sample Compiler-Generated ODL File Listing
Sample Output Using OBJ Switch
Merged vs. Abbreviated ODL File
Sample ODL File Merge Dialogue
Field Sizes
Redefining Special Characters
ASCII Code Chart
Relation Condition
The Meanings of the Relational Operators
Class Condition, General Format
Data Movement with Editing Symbols
Data Movement with No Editing
Subscripted MOVE Statements
Sample STRING Statement
Concatenation with the STRING Statement
Literals as Sending Fields
Indexed Sending Fields
Sample POINTER Phrase
Delimiting with the Word SIZE
SPACE as a Delimiter
Repeating the DELIMITED BY Phrase
Delimiting with More Than One Space Character
The ON OVERFLOW Phrase
Various STRING Statements Illustrating the
Overflow Condition
STRING Statement with Pointer

2-8
2-11
2-12
2-16
2-18
2-19
2-21
2-22
2-22
2-23
2-23

3-17
3-18

CONTENTS (Con t • )

Page
FIGURES (Cont.)
FIGURE

3-22
3-23
3-24
3-25
3-26
3-27
3-28
3-29
3-30
3-31
3-32
3-33
3-34
3-35
3-36
3-37
3-38
3-39
3-40
3-41
3-42
3-43
3-44
3-45
3-46
3-47
3-48
3-49
3-50
3-51
3-52
3-53
3-54
3-55
3-56
3-57
3-58
3-59
3-60
3-61
3-62
3-63

Subscripting with the Pointer
Subscripting the Delimiter
Sample UNSTRING Statement
Multiple Receiving Fields
Delimiting with a Space Character
Delimiting with Multiple Receiving Fields
Delimiting with an Identifier
Multiple Delimiters
The COUNT Phrase
The DELIMITER Phrase
The POINTER Phrase
Examining the Next Character By Using the
Pointer Data Item as a Subscript
Examining the Next Character By Placing It
Into a I-Character Field
The TALLYING Phrase
The POINTER and TALLYING Phrases Used Together
Subscripting the COUNT Phrase With the TALLYING
Data Item
Using the OVERFLOW Phrase
Sequence of Subscript Evaluation
Erroneously Repeating the Word INTO
Sample INSPECT .•. TALLYING Statement
Sample INSPECT ••• REPLACING Statement
Sample INSPECT ... BEFORE Statement
Matching the Delimiter Characters to the
Characters in a Field
Sample INSPECT Statement
Sample REPLACING Argument
Sample AFTER Delimiter Phrase
Where Arguments Become Active in a Field
Sample Subscripted Argument
Format of the Tally Argument
CHARACTERS Form of the Tally Argument
Results of Counting with the LEADING Condition
Argument List Adding Into One Tally Counter
Argument List Adding Into Separate Tally
Counters
Argument List (with Delimiters) Adding into
Separate Tally Counters
Results of the Scan in Figure 3-55
Two Tallying Arguments that Do Not Interfere
with Each Other
Two Tallying Arguments that Do Interfere with
Each Other
Two Tallying Arguments that, Because of their
Positioning, Only Partially Interfere with
Each Other
An Attempt to Tally the Character B with Two
Arguments
Tallying Asterisk Groupings
Placing the LEADING Condition in the Argument
List
Reversing the Argument List in Figure 3-62

3-19
3-19
3-21
3-21
3-23
3-24
3-27
3-27
3-28
3-29
3-30
3-31
3-31
3-32
3-32
3-33
3-34
3-35
3-36
3-37
3-37
3-37
3-38
3-40
3-40
3-41
3-42
3-43
3-44
3-44
3-45
3-45
3-46
3-46
3-46
3-47
3-47
3-47
3-48
3-48
3-49
3-49

CONTENTS (Cont.)

Page
FIGURES (Cont.)
FIGURE

3-64
3-65
3-66
3-67
3-68
3-69
3-70
3-71
3-72
3-73
4-1
4-2
4-3
4-4
4-5
4-6
4-7
4-8
4-9
4-10
4-11
5-1
5-2
5-3
5-4
5-5
5-6
5-7
5-8
5-9
5-10
5-11
5-12
5-13
5-14
5-15
5-16
5-17

An Argument List that Counts Words in a
Statement
3-49
Counting Leading Tab or Space Characters
3-50
Counting the Remaining Characters With the
CHARACTERS Argument
3-50
Format of the Search Argument
3-51
Format of the Replacement Value
3-52
The Replacement Argument
3-53
Replacement Argument List that is Active Over
the Entire Field
3-53
Replacement Argument List that "Swaps" Ones
for Zeroes and Zeroes for Ones
3-53
Replacement Argument List that Becomes
Inactive with the Occurrence of a Space
Character
3-54
Argument List with Three Arguments That
Become Inactive with the Occurrence of a
Space
3-54
Truncation Caused By Decimal Point Alignment
4-9
Zero Filling Caused By Decimal Point Alignment
4-9
Numeric Editing
4-11
Rounding Truncated Decimal Point Positions
4-13
Rounding Truncated Decimal Scaling positions
4-14
Explicit Programmer-Defined Temporary Work Area 4-20
Arithmetic Statement Intermediate Result Field
Attributes Determined from Composite of Operands 4-20
Arithmetic Expression Intermediate Result Field
Attributes Determined by Implementor-Defined
Rules
4-21
Procedure to Determine I(IR(x»
and D(IR(x»
for an Arithmetic Expression Result Field IR
4-23
Truncation Criterion and I(IR(x»
and D(IR(x»
Computation
4-25
Example of Intermediate Results
4-26
Defining a Table
5-2
Mapping a Table into Memory
5-3
Synchronized COMP Item in a Table
5-4
Adding a Field without Altering the Table Size
5-5
Adding One Byte which Adds Two Bytes to the
Element Length
5-5
Forcing an Odd Address By Adding a I-Byte
FILLER Item to the Head of the Table
5-6
The Effect of a SYNCHRONIZED RIGHT Clause
Instead of a FILLER Item as shown in Figure 5-6 5-6
Initializing Tables
5-7
Initializing Mixed Usage Fields
5-8
Initializing Alphanumeric Fields
5-8
Literal Subscripting
5-9
Subscripting a Multi-Dimensional Table
5-10
Subscripting Rules for a Multi-Dimensional Table 5-10
Subscripting with Data-Names
5-11
5-12
Index-Name Item
Subscripting With Index-name Items
5-12
5-14
Relative Indexing

CONTENTS (Cant.)

Page
FIGURES (Cant.)
FIGURE

5-18
5-19
5-20
6-1
6-2
6-3
6-4
6-5

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

Index Data Item
Legal Data Movement with the SET Statement
Example of Using SEARCH To Search a Table
Placement of End-of-File Mark
Placement of the End-of-Volume Label and
End-of-File Mark in a Multi-Volume File
Single Key Indexed File Organization
Multi-key Indexed File Organization
Use of ACCEPT and DISPLAY Statements With
TRAX Support Terminal
Assigning the Line Printer to Files
Unqualified Data Item Reference
Qualified Data Item Reference
General Format of a Qualified Data Reference
General Format of a Qualified Procedure
Reference
Segmentation Using the /OV Switch
Using the /CSEG:nnnn Switch
Sample LINKAGE SECTION and USING Phrase
Argument Address List
Merged ODL File Listing
Modified ODL File
Overlay Description Map Before and After
Modification
Sample Listing of Program Used in Example-l
Sample Listing of Program Used in Example-2

5-14
5-15
5-19
6-3
6-4
6-25
6-26

6-39
6-40
7-8
7-9
7-10
7-11
8-3
8-4
9-2
9-6
10-7
10-8
10-9
11-8
11-10

TABLES
TABLE

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

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

Successful and Unsuccessful Replacing Matches
2-9
2-13
COBOL Compiler Switches
/SYM:n Switch Values
2-16
Merge Error Messages
2-29
3-9
Legal Non-Numeric Elementary Moves
Results of the Preceding Sample Statements
3-18
Results of the Preceding Sample Statements
3-20
Values Moved Into the Receiving Fields Based
3-22
on the Value in the Sending Field
Handling a Sending Field that is Too Short
3-23
3-24
Results of Delimiting with an Asterisk
Results of Delimiting Multiple Receiving Fields 3-25
3-25
Results of Delimiting with Two Asterisks
3-26
Results of Delimiting with ALL Asterisks
Results of Delimiting with ALL Double Asterisks 3-26
Results of the Multiple Delimiters Shown in
3-28
Figure 3-29
Original, Altered, and Restored Values Resulting
3-39
from Implicit Redefinition
The Resulting ASCII Character From-a Sign and
4-3
Digit Sharing the Same Byte
Conversion Values
4-5

xii

CONTENTS (Cont.)

Page
TABLES (Cont.)
TABLE

4-3
6-1
6-2
6-3
6-4
6-5
6-6
6-7
6-8
6-9
6-10
6-11
11-1
11-2
B-1
E-l
E-2
H-l

I-I

The Sign Tests
COBOL File Types
I/O Statements
Sequential OPEN Modes
Bucket Sizes for Possible Record Lengths
Relative OPEN Modes
Bucket Size for Possible Record Lengths
Indexed OPEN Modes
Device Codes
Comparison of TRAX System Disk Devices
File Specifier Switches
Form Control Characters
Sequential I/O File Status Key Values (ASCII)
Relative And Indexed I/O File Status Key Value$
(ASCII)
Data Type Conversions Performed by CNVT
$KK PSECT Name Suffixes
PSECT Name Suffixes
RMS System Standard Error Codes
COBOL Object Time System Error Messages

xiii

4-7
6-2
6-2
6-9
6-16
6-19
6-28
6-32
6-37
6-38
6-43
6-50
11-5
11-6
B-2
E-2
E-3
H-l

I-I

PREFACE

The TRAX COBOL User's Guide is intended primarily for
reference use.
It is a companion guide to the TRAX COBOL Language Reference Manual.
Because it is not a tutorial guide for beginning programmers,
you
should have a working knowledge of the COBOL language.
This guide describes the COBOL file structures, data formats, some of
the features of the TRAX COBOL compiler, error messages generated by
the compiler and I/O devices available with the system. Some hints on
good programming practices,
some techniques for debugging source
programs, and a description of the TRAX COBOL utility programs ODL
MERGE and REFORMAT are also discussed.
Those wishing to learn the COBOL language should obtain the
tutorial manuals:

following

Farina, Mario V., COBOL Simplified,
New Jersey, Prentice Hall, Inc., 1968.
McCameron, Fritz A., COBOL Logic and Programming,
Homewood, Illinois, Richard D. Irwin, Inc., 1970
McCracken, Daniel D. and Garbassi, Umberto,
A Guide to COBOL Programming, Second Edition,
New York, John Wiley and Sons, Inc., 1970
NOTE
These publication dates are the latest
available.
They will all probably be
revised to reflect ANS-74 standards.
The TRAX COBOL compiler accepts COBOL language
true subset of ANS-74 COBOL.

elements

that

are

ACKNOWLEDGMENT

COBOL is an industry language and is not the property of any company
or
group
of
companies, or of any organization or group of
organizations.
No warranty, expressed or implied, is made by any contributor or by
the CODASYL Programming Language Committee as to the accuracy and
functioning of the programming system and language.
Moreover, no
responsibility is assumed by any contributor, or by the committee, in
connection therewith.
The authors and copyright holders of the copyrighted material used
herein are:
FLOW-MATIC
(trademark of Sperry Rand Corporation),
Programming for the UNIVAC (R)
I and II, Data Automation Systems
copyrighted 1958, 1959, by Sperry Rand Corporation;
IBM Commercial
Translator Form No. F28-80l3, copyrighted 1959 by IBM;
FACT, DSI
27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell.
They have specifically authorized the use of this material,
in whole
or in part, in the COBOL specifications. Such authorization extends
to the reproduction and use of COBOL specifications in programming
manuals or similar publications.
Procedures have been established for the maintenance of COBOL.
Inquiries concerning the procedures for proposing changes should be
directed to the Chairman of the CODASYL
Programming
Language
Committee, P.O. Box 124, Monroeville, Pa. 15146.

xvi

CHAPTER 1

INTRODUCTION

Before a program can be run on a computer, it must be translated from
the form that a person can understand (near-English) into a form that
a computer can understand (machine language).
This translation is
performed by COBOL compiler systems.
Because each manufacturer's
system has its own unique machirie language, each system has its own
COBOL compiler.
The COBOL compiler for the TRAX system is the TRAX
COBOL compiler.
The TRAX COBOL compiler translates ANS-74 COBOL source programs into
relocatable object modules. The compiler runs under the supervision
of TRAX and conforms to all TRAX conventions and restrictions.

NOTE
The purpose of this manual
is
to
instruct you in the preparation of COBOL
programs
in
the
TRAX
support
environment.
Detailed
information
pertinent to
preparation
of
COBOL
programs
(TST's)
in
the
TRAX
applications environment can be found in
the TRAX Application Programmer's Guide
(AA-D329A-TC) •
The compiler itself requires disk storage space for its work file
system and temporary files.
(The work file system requires a minimum
of 128 blocks to a maximum of 512 blocks.
The temporary file and
object program file requirements grow in proportion to the size of the
source program.)
To run a COBOL program, you follow a five-step process:

•

Prepare a source program

•

Compile a source program to produce object files

•

Merge or prepare an overlay description file (optional)

•
•

Link the object files to form an executable task
Execute the task

The TRAX COBOL compiler accepts COBOL source statements from source
input files.
This means that you must manually enter your source
statements into a TRAX support terminal prior to the compilation
process (Section 2.2).

1-1

INTRODUCTION

Once you have decided upon a format for your source
have created them, you compile the source program.

input

files

and

The TRAX COBOL compiler reads source statements from the source input
file,
translates them into object code modules consisting of program
sections (PSECTs), and produces the following files:
•

Listing (LST)

•

Object (OBJ)

•

Overlay Description Language (ODL)

The listing file (LST) contains a listing of source statements in the
order compiled, any diagnostic error messages,
and any optional
special format listings, such as cross-reference listings and data and
procedure maps.
You obtain special format listings by appending an
appropriate switch to the COBOL command line at compile-time,
(see
Section 2.4, Compiler Switches).
The object file (OBJ) contains a collection of program sections called
PSECTs which are not executable.
They must be linked into an
executable task image by an operating system task called TRAX Linker.
The ability to compile COBOL subprograms to produce linkable object
files independently, enables you to create modular programs.
The Overlay Description Language (ODL) file contains directives that
describe the overlay structure of the object module generated from the
COBOL source program. ODL directives are generated into the ODL file
for each overlayable object module program section.
The ODL file generated by the compiler is not a complete ODL file.
You must either hand-tailor the ODL file, build your own specialized
ve~sion, or specify the compiler-generated ODL file as
input to the
Merge utility to complete the file (see Section 2.6, Using the Merge
Utility;
and Chapter 10, Hand-Tailoring ODL Files).
The compiler can compile only one source program or subprogram per
command string execution.
Therefore, a program which consists of a
main program plus one or more subprograms requires multiple executions
of the compiler. Each compilation generates a separate listing, ODL,
and object file . . The ODL files, in this instance, must be merged
together into a single ODL file to be submitted as input to the TRAX
Linker.
To accomplish this, you use the
following functions:

Merge

utility,

which

performs

merges the ODL statements from one or more ODL files
single ODL file

analyzes
provides
required

inserts the missing but required ODL directives not
by the compiler

into

the
a

the I/O requirements for
the entire task and
directives to include only those I/O routines
provided

Whether you have a large segmented program, a main program plus
subroutines,
or a small stand-alone program, the ODL files generated
by the compiler require merging or modification. You are advised to
use the Merge Utility to perform this merging/modification, although
you can hand-tailor your own ODL file.

1-2

INTRODUCTION

NOTE
Do not attempt to hand-tailor your own
OOL
file
unless you have in-depth
knowledge of your operating system and
TRAX COBOL.
However, if you wish to
hand tailor OOL files,
the following
references will provide the required
information:
•

The TRAX Linker Reference Manual
No.

•

Standard OOL file Format
Chapter 10 of this manual

•

COBOL Segmentation
Chapter 8 of this manual

•

Code PSECT Naming Conventions
Appendix E of this manual

•

Interprogram Communications
Chapter 9 of this manual

OEC

When you have a single OOL file that contains all of the required
overlay descriptor language, you can execute the TRAX Linker.
The TRAX Linker provides you with a facility for linking separately
compiled object modules into an executable task image. You can,
depending on your knowledge of your operating system and TRAX COBOL,
link object modules created by another programming language into your
COBOL task image. The TRAX Linker also allows you to take full
advantage of the COBOL system library to selectively link into your
COBOL task only those runtime support routines actually needed to run
your task.
The TRAX Linker, using the OOL file as a guide, provides the facility
to build large amounts of code into a task by careful use of code
segments that overlay each other.
Careful use of segmentation or
calls to subprograms within your COBOL source program will allow you
to compile and execute large and complex COBOL programs.
If you add
some functionality to an existing COBOL program and find that, after
task-building, the resulting task will not fit in memory, you have an
alternative other than reprogramming: you can segment the program or
make subprograms out of some of the existing procedures,
replacing
these
procedures
with
CALL
statements to the newly created
subprograms. When the source program has been compiled, the OOL file
merged, and linking accomplished,
the task is ready to be executed
(Section 2.2.4).
Figure 1-1
execution:

shows

the

process

1-3

preparing

COBOL

program

for

INTRODUCTION

OBJECT
MODULE

COMPILER
(COBOL)

LISTING

ODL
MERGE
UTILITY

Figure 1-1

Building a COBOL Task Image

1-4

INTRODUCTION
1.1

THE COBOL SOURCE PROGRAM

A COBOL source program consists of four major
appear in the following order:
1.

IDENTIFICATION DIVISION.

ENVIRONMENT DIVISION.

DATA DIVISION.

PROCEDURE DIVISION.

divisions,

which

must

Each of the COBOL divisions is further divided into sections that may
be divided into paragraphs.
Paragraphs contain COBOL sentences.
Sentences contain COBOL statements. The following subsections
(1.1.1
through 1.1.4)
individually discuss each division and its major
sections.

1.1.1

The Identification Division

The Identification Division identifies the COBOL program and contains
such optional documentary information as the name of the programmer,
the name of the installation, and the date the program was written and
last compiled.

1.1.2

The Environment Division

The Environment Division identifies the hardware configuration of the
system that is compiling the program (SOURCE-COMPUTER)
and the
hardware configuration of the system that is running the program
(OBJECT-COMPUTER) .
The division is divided into the following two
major sections:
•

Configuration Section
This section is required
and
contains the names of the source and object computers and any
mnemonic names that are to be assigned to devices.

•

Input-Output Section -- This section is optional and contains
descriptions of all the external fi~es being manipulated by
the program. The section is required if there are external
files.

1.1.3

The Data Division

The Data Division contains complete descriptions of all data to be
processed by the program.
In this division, the programmer must
assign a data-name to and describe every data item referred to in the
Procedure Division.
The Data Division is composed of three optional major sections:
•

File Section -- Contains the descriptions of
output files and their records.

all

input

and

•

Working-Storage Section
Contains
temporary records and data items.

descriptions

1-5

the

INTRODUCTION
•

1.1.4

Linkage Section -- Describes the data that is available to a
called program and is referenced in both the calling and
called program.

The Procedure Division

The Procedure Division contains the program's procedural statements.
Within this division, the program specifies manipulation of the data
items described in the Data Division.
The Procedure Division may begin with the DECLARATIVES, which contain
USE procedure declarative sections for processing I/O errors (Section
11.3).
The programmer may divide the Procedure Division
paragraphs that each perform a function.

into

sections

and

The
Procedure
Division
makes
COBOL's
advantages
(excellent
documentation and programming simplicity) most apparent.
Figure 1-2
(sample Procedure Division coding)
illustrates the documentation
capabilities of COBOL programs:

PROCEDURE DIVISION.
BEGIN.
OPEN INPUT TRANSACTION-FILE.
OPEN OUTPUT MASTER-FILE.
READ-A-RECORD.
READ TRANSACTION-FILE NEXT RECORD
AT END GO TO CLOSE-ROUTINE.
READ MASTER-FILE NEXT RECORD
AT END GO TO CLOSE-ROUTINE.
PROCESS-A-RECORD.
IF TRANS-ACCT-NUMBER IS GREATER THAN MAST-ACCT-NUMBER
GO TO READ-MAS-RECORD.
IF TRANS-ACCT-NUMBER IS LESS THAN MAST-ACCT-NUMBER
GO TO ERROR-ROUTINE.

Figure 1-2

Sample COBOL Procedural Coding

1-6

INTRODUCTION
1.2

THE COBOL UTILITY PROGRAMS

TRAX COBOL provides two utility programs:
•

OOL MERGE -- Merges ODL files created by one or more COBOL
compilations into a single ODL file to be
submitted as input to the TRAX Linker.

•

REFORMAT -- Converts POP-II terminal format COBOL programs
into conventional format ANSI COBOL programs.

Both of these utilities are part of the TRAX/COBOL software package.
The following subsections
(1.2.1 and 1.2.2) describe these utility
programs.

1.2.1

ODL MERGE

The OOL Merge utility program merges OOL files generated by COBOL
This file is submitted as input
compilations into a single OOL file.
to the TRAX Linker, and describes the overlay structure of the
resulting task image.

1.2.2

REFORMAT

TRAX COBOL accepts source programs that are coded using the terminal
reference format.
The REFORMAT utility program reads source programs
that were coded in terminal format and converts them to 80-column
ANSI-compatible source programs.

1-7

CHAPTER 2

USING TRAX COBOL

2.1

INTRODUCTION

This chapter provides you with the specific information necessary to
develop, compile, link, and run COBOL programs in the TRAX support
environment. Additional information is included on the use of the
TRAX COBOL library, the use of the COBOL utilities ODL MERGE and
REFORMAT, and on the definition and use of compile-time switches.
This chapter also contains a summary of COBOL error messages and
sample source program listings for all COBOL divisions.
The reference format supported by TRAX COBOL for program development
is the terminal format. The TRAX COBOL compiler does process data in
the conventional aD-column punched card format. However, since TRAX
system configurations do not include card readers, conventionally
formatted data and programs must be input from another I/O device such
as magnetic tape drives capable of reading ANSI standard magnetic
tapes. The terminal format is the default for TRAX COBOL.
Both
terminal and conventional reference formats are detailed in the TRAX
COBOL Language Reference Manual.

2.2

CREATING TRAX COBOL PROGRAMS

Creating COBOL programs in the TRAX support environment involves
basic steps:
1.

Create a machine readable source statement file.

Compile source statements into an object module.
Debug and
recompile source module until program is syntactically valid.

Link compiled object modules and required system libraries to
form an executable task image file.

Run the completed program.

Each of these steps is described in
follow.

2.2.1

four

detail

the

paragraphs

that

Creating Source Language Statement Files

After you have defined your procedure and translated the definition
into COBOL source language statements, the next step is to enter the
source statements into the computer. In the TRAX Support Environment,
this is done from a support terminal using the DEC Editor. Consult
your system manager for the location of your installation's support

2-1

USING TRAX COBOL

terminals, and the procedure required to long into the TRAX support
environment. Note that in addition to the support terminal, the TRAX
COBOL compiler accepts input from the following I/O devices:
1.

ANSI standard magnetic tape drives

Disk drives

The DEC Editor is a utility program that allows you to create and
If you are
maintain text files from a video or hard-copy terminal.
unfamiliar with the Editor's operations, consult the DEC Editor
Reference Manual.
The Editor is entered by typing the command string:
)EDIT [file-specification]
When you are creating a new file, the file specification should be a
new file name, and source files should have a .CBL file type.
Supplying an existing file specification to the EDIT command results
in the highest numbered existing version of that file being supplied
so that you can modify, insert or delete source language statements in
the file.

2.2.2

Compiling COBOL Programs

After you have created source language input files with the help of
the DEC Editor, the next step is compilation. The TRAX COBOL compiler
is a system program which translates your high level source language
statements into object modules which consist of machine language
instructions coded as octal numbers. To invoke the COBOL compil~r you
enter the following command string:
)COBOL/LIST file-specification
This command string produces an object file and a listing file with
the name designated by the file specification. The extensions for
these files will be .OBJ for the object file and .LST for the listing
file. The listing file is spooled, then deleted after printout.
Some common errors you should avoid when entering
string are:

the

COBOL

•

omitting the /CVF switch for programs that
conventional format, and causing a system error

•

omitting version numbers from one or more of the file
specifications, causing the system to create a new version or
to compile the wrong version.

The COBOL command is described
Environment Programmer's Guide.

detail

the

are

command

TRAX

the

Support

The size of a COBOL object module created from a COBOL source file
depends on the amount of memory required for the following elements:
1.

data-items in the Working-Storage Section

number of files in the File Section

amount of code generated for the Procedure Division

2-2

USING TRAX COBOL

number and length of all unique numeric
literals used in the Procedure Division

and

non-numeric

total size of all runtime modules needed to support the
executing program (includes such code as arithmetic support,
I/O support, segmentation support, etc.)

push-down stack space required to support the executable code

directories for all referenced data-items and literals

The maximum size of a program task on the PDP-II is 64K bytes.
On
systems that support TRAX COBOL, the maximum task is 56K bytes, where
the remaining 8K bytes are reserved for sharable file system code to
support I/O. A COBOL program, therefore, cannot occupy more than 56K
bytes of memory.
Some programs may exceed the allowable storage byte limit.
In this
case, the Linker issues a diagnostic and does not link your task. You
may take either of two corrective measures:
1.

create program overlays by using
facility (Chapter 8, Segmentation)

the

COBOL

segmentation

break up your program into a main program and one or
subprograms (Chapter 9, Interprogram Communication).

The listing output from your compilation will indicate errors in your
source language text, and provide information regarding the cause of
the error.
In addition, the compiler generates an error message summary and
displays it at your terminal. This summary contains the number of
errors encountered during the current compilation. The error message
summary has the following format:
CBL

NNNNN ERROR(S), NNNNN FATAL

Where:
NNNNN is the number of errors encountered.
NOTE
If fataf errors are encountered, no
object
file
is
generated,
unless
specifically requested via the
/ACC
switch.
(See Section 2.4, Compiler
Switches) .
You then can use the DEC Editor to make the required corrections to
your source statements, and recompile.
Several iterations of the
compile and editing process are usually needed to obtain an error free
compilation.
Once the compiler has reported that your compilation is
error free, you can then proceed to the next program development step,
which is linking the object modules to form a task.

2-3

USING TRAX COBOL

Linking the Task

2.2.3

The Linker is a TRAX program that accepts object modules
library modules as input, and merges this information to
image file. The task image file can be copied into memory
the operating system.
Linking is the final step in
development process.

and system
form a task
and run by
the program

A TRAX COBOL program that has been entered and compiled can be
by issuing a command string having the following form:

linked

)LINK file specification
The LINK command specifies the name of the input object file
specification.
This command links the object file designated by file
specification and produces a task image having the same name as the
specified file,
but as an extension of .TSK. The task uses all the
default assumptions for qualifiers and options. Link command syntax
along with qualifiers and options is described in detail in the TRAX
Linker Reference Manual.

Running Your Program

2.2.4

After all steps of program development, editing, compiling and linking
have been successfully completed, you may run your program by entering
the run command followed by the file name of the task image file that
was created by the Linker. For example:
)RUN file specification
A number of RUN time qualifiers which are available to be used with
the RUN command are described in the TRAX Support Environment User's
Guide.

2.3

USING THE LIBRARY FACILITY (COPY)

The TRAX COBOL library facility provides you with a means of copying
COBOL source language text from a library of source material into a
COBOL program during compilation. One COpy statement can place large
amounts of library source text into a source program, thereby saving
repetitious coding. The compiler treats the copied material as though
it were part of the program being compiled. The copied material,
however, does not physically alter the source program file in any way.
The COBOL library facility provides two important benefits:
1.

Standardization of File and Coding Conventions
A typical data file is processed by more than one program,
and each processing program must describe the characteristics
of that file (file-name, blocking factor, field names, etc.).
Often the programs are written by one programmer, then
maintained and updated by another programmer, who has to try
to understand a program that was written by someone else.
Since this situation arises at most sites,
it is good
practice to design a standardized file description (keeping
in mind the programs that process that file) and place it in
the library.
Then a COpy statement in each processing
program can merge it into the program at compile-time.

2-4

USING TRAX COBOL
This technique applies as well to any procedure that is used
in many different applications.
For example, the library
could contain a standardized routine that converts calendar
dates to Julian dates to be merged into each source program
that uses this function.
2.

Time Savings for Initial Coding and Updating
Defining and coding file and record descriptions is a
time-consuming chore.
If the descriptions exist in the
library, a single COPY statement will save the time required
to code those entries into programs using them.
Changing a
file
format is another
time-consuming chore.
Typically, when a file format changes, you must change and
recompile all the programs that use that file.
If the file
description is in a library file,
the programmer has to
change only the library file.
The source programs,
of
course, still have to be recompiled but require no individual
coding changes.
Putting commonly used Procedure Division procedures
library file yields the same time-saving benefits.

2.3.1

Creating a COBOL Library File

Each line of a COBOL library file must be in a form such that, when it
is merged
into the source program, it forms a syntactically correct
COBOL clause, phrase, or sentence.
It can meet this condition either
by being syntactically correct itself, or by becoming so when it is
merged with the source program.
The library text must conform to the rules for
the COBOL terminal
reference format (Library Module in the TRAX COBOL Reference Manual).
When writing text for library files,
place at least four
space
characters or a tab character before any entry that normally begins in
Area B of the COBOL source program.
Left justify, without space
characters,
entries that normally begin in Area A or at character
position O.
In addition, the library file and the source programs it
IS merged
into must also be in the terminal format.
(A conventional
format library file cannot be merged properly into a terminal format
source program and vice-versa.)
Since each library file contains all the source language text to be
merged into a source program by one COpy statement, the COpy statement
text-name must refer to the library file-name.
To create the library file, enter it directly onto disk or DECtape
through the support terminal using the DEC editor. There is no method
for updating COBOL library files on magtape. The available medium for
these files is disk storage.

2.3.2

The COpy Statement

The COpy statement is a compile-time function
library file into a COBOL source program.

that

merges

COBOL

The statement must begin with the word COpy and end with a period.
The compiler logically replaces the COpy statement (including the
period) with the library file named by the statement.
However,
both

2-5

USING TRAX COBOL

the COpy statement and the library text material appear in the source
listing (Section 2.3.4, The Source Listing). The statement may appear
anywhere in a source program that a COBOL word is allowed. The
simplest form of the statement is:
COpy text-name.
Text-name must specify either a file-name or a alphanumeric literal.
If a file-name is specified, the compiler assumes standard file
specification defaults and copies the text from the latest version of
that file into the source program.
The format for the full file specification is:
device: [UIC]file-name.file-typeiversion-number
The specification defaults are:
device:

the standard system device or the
device specified in the batch JCL

[user-identification]

the UIC that you are logged in under

file-name

(no default)

.file-type

.LIB

iversion-number

the latest version.

For example, the following text-name entry copies a library file named
BILBOS.LIB from the system disk to the source program:
COpy BILBOS.
This text-name entry causes the compiler to search the system disk for
a file named BILBOS.LIB.
This search takes place in the user's
directory only.
If a alphanumeric literal is entered, it may specify the full file
specification for that file.
For example, the following entry copies
the library file BILBOS.LIB from DKI into the source program:
COpy "DKl:BILBOS.LIB".
This text-name entry causes the software to search DKI for
the file
named BILBOS.LIB, and merge that file with the file named BILBOS (see
Figure 2-1).
Only four situations require the use of the alphanumeric literal
option to indicate the full file specification for the COpy statement:
1.

when the library has a file type other than .LIB

when there is more than one device containing a library file

when the LIBRARY contains more than one version of the
and you want to copy a version other than the latest.

when the library file is in another directory

2-6

file

USING TRAX COBOL
The following examples use only the file-name option:
COBOL SOURCE PROGRAM

RESULTING SOURCE PROGRAM

IDENTIFICATION DIVISION.

PROGRAM-ID. SAMPLE.

PROGRAM-ID SAMPLE.

COpy BILBOS.

AUTHOR.

BILBO BAGINS.

DATE-COMPILED.

ENVIRONMENT DIVISION.

SECURITY.

TODAY.

NONE.

ENVIRONMENT DIVISION.

LIBRARY FILE (BILBOS.LIB)j
AUTHOR. BILBO BAGINS.
DATE-COMPILED. TODAY.
SECURITY. NONE.
Figure 2-1

Merging a Library File

The library file in Figure 2-2 is formatted (four spaces before each
entry)
so that when it is merged into the source program, each entry
begins in Area B.
If the four spaces are not there, the text is moved
into Area A and syntax errors result (Area A is reserved for headers
such as division headers and paragraph headers).
COBOL SOURCE PROGRAM

RESULTING SOURCE PROGRAM

PROCEDURE DIVISION.

BEGIN. COpy STARTUP.

BEGIN.
/OPEN INPUT FILE-A.

READ-PROCEDURE.
READ FILE-A.

LIBRARY FILE (STARTUP. LIB)

OPEN OUTPUT FILE-B.

MOVE ZERO TO
'ACCUMULATORS.
SET INDEX-l TO 1.

READ-PROCEDURE.

OPEN INPUT FILE-A.

READ FILE-A.

OPEN OUTPUT FILE-B.
MOVE ZERO TO
ACCUMULATORS.
SET INDEX-l TO 1.
Figure 2-2

Merging a Library File Area B

2-7

USING TRAX COBOL

Since the COpy statement may appear anywhere in a source program that
a COBOL word is allowed, it can be used in various ways to solve a
particular programming problem.
For example, if a library file named
DRACULA contains the single entry BLOOD-RATE, the entry could be used
in the Data Division as shown in Figure 2-3.
SOURCE COpy STATEMENT

RESULTING SOURCE STATEMENT

02 COPY DRACULA. PIC 99V99.
Figure 2-3

02 BLOOD-RATE PIC 99V99.

Using the COpy Statement in a Data Description

The entry could be used in the Procedure Division as shown
2-4.
SOURCE COPY STATEMENT

Figure

RESULTING SOURCE STATEMENT

MULTIPLY 40 BY COpy DRACULA.
GIVING PLASMA.
Figure 2-4

MULTIPLY 40 BY BLOOD-RATE
GIVING PLASMA.

Using the COpy Statement in a Procedural Statement

The periods terminating the COpy statements in Figures 2-3 and 2-4 are
replaced by the text file.
No periods appear in the resulting source
program unless they are in the text file (if a source statement needs
a period, the text file must have a period at the required place).
NOTE
The examples illustrated by Figures 2-3
and 2-4 are not recommended uses of the
COpy statement. This chapter includes
them only to illustrate the mechanics of
the TRAX COBOL library facility.

2.3.3

The COpy REPLACING Statement

Sometimes it may be necessary to tailor library text material for
use
in a particular program, for example, if a data description in the
library text has level numbers incremented by 1 -- 01,02, 03,
.,.,n.
and you want them incremented by four -- 01, 05, 06, .,.,n. The COpy
statement can replace, during the copying process, all occurrences of
a given literal or word with an alternate literal or word. A sample
COpy REPLACING statement is:
COpy WALDEN REPLACING 02 BY 05.
This sample statement causes the compiler to scan the library file
WALDEN searching for 02. Wherever it finds a 02, it replaces it with
a 05. A match occurs only if the compiler finds a 02 (not just a 0 or
just a 2). The REPLACING character string, which may be a literal or
a word, must compare equally, character for character, with the entire
character string in the library text. The following table shows some
successful (YES) and unsuccessful (NO) matches:

2-8

USING TRAX COBOL
Table 2-1
Successful and Unsuccessful Replacing Matches
GIVEN LITERAL
OR WORD

LIBRARY TEXT

MATCH?

"ABC"

"ABCD"

HRLY-RATE

YES

"2"

IS"

"15"

"012"

"12"

012

SUBTRACT

YES

"012"

YES

2.3.3.1 Examples of COpy REPLACING Statement - The following examples
of the COPY REPLACING statement all refer to the library file named
NEWSBOY:
NEWSBOY (library filename)
01 A.
02 B PIC 99.
02 C PIC 99 VALUE 2.
02 D PIC X(S} VALUE "ABCDE".
02 EPIC 99V99 VALUE 3.75.
02 F PIC 99 VALUE 02.

Bxample 1
COPY NEWSBOY REPLACING B BY X.
This ~tatement merges the entire file named NEWSBOY into the source
program and changes data-name B to X.
It does not change the
character B in the character string of data-name D because it is part
of a nonmatching character string. This statement causes the compiler
to merge the following text into the source program:
01 A.
02 X PIC 99.
02 C PIC 99 VALUE 2.
02 D PIC X(S} VALUE "ABCDE".

2-9

USING TRAX COBOL
Example 2
COPY NEWSBOY REPLACING 2 BY 6.
This statement merges the entire file named NEWSBOY into the source
program and changes the 2 in the entry for data-name C to a 6.
It
does not change the 02 in the literal entry for data-name F nor any of
the 02 level numbers because they contain a nonmatching character O.
This statement causes the compiler to merge the following text into
the source program:
01 A.
02 B PIC 99.
02 C PIC 99 VALUE 6.
02 0 PIC X (5) VALUE "ABCDE".
02 E PIC 99V99 VALUE 3.75.
02 F PIC 99 VALUE 02.

Example 3
COpy NEWSBOY REPLACING 02 BY 63.
This statement merges the entire file named NEWSBOY into the source
program and changes not only the 02 literal entry in data-name F, but
also all of the 02 level numbers to 63.
Since level number 63 is
illegal,
this causes the compiler to produce syntax errors. The
replacing process is not sensitive to the syntax of the text.
The
string of characters in the library may be literals, level-numbers,
data-names, etc.;
if they match the REPLACING string,
character for
character,
the compiler replaces them.
Consider the results of this
statement:
01 A.
63 B PIC 99.
63 C PIC 99 VALUE 2.

63 F PIC 99 VALUE 63.

Example 4
COpy NEWSBOY REPLACING B BY X,
"ABCDE" BY "HIJKL",
3.75 BY 4.23.
This statement shows how a single COpy statement can replace more than
one literal or word.
It causes the compiler to merge the following
text into the source program:

2-10

USING TRAX COBOL
01 A.
02 X PIC 99.
02 C PIC 99 VALUE 2.
02 D PIC X (5) VALUE "HIJKL".
02 E PIC 99V99 VALUE 4.23.
02 F PIC 99 VALUE 02.

2.3.4

The Source Listing

Depending on how the COpy statement is written, the TRAX COBOL
compiler lists library text material either before or after the COpy
statement (Figures 2-5 and 2-6).

2.3.4.1 Before the COPY Statement - If
other
source
material
(including spaces) follows the COpy statement on the same source line,
the compiler lists the library text before the COpy statement
(see
Figure 2-5).
SOURCE LINE

SOURCE LISTING

...

. ..

COpy CHANGES. ADD A TO B.

text-line-l

text-line-2
text-line-3
COpy CHANGES. ADD A TO B.
Figure 2-5· Placing the Library Text Before the COpy Statement
The compiler does not print a source line until it has scanned the
entire line.
Therefore, in Figure 2-5 (CHANGES), the compiler takes
the following steps, in order:
1.

scans the COpy statement

recognizes that the COPY statement
information on the same line

prints the library text

scans the rest of the line

prints the entire source line

followed

This results in a somewhat confusing listing and should be avoided.
When the library text follows the COpy statement, a much more readable
listing is produced.

2-11

USING TRAX COBOL
2.3.4.2 After the COpy Statement - If the COpy statement terminates
the source line, the compiler merges the library text after the COpy
statement, as shown in Figure 2-6.
SOURCE LINE

SOURCE LISTING

COPY CHANGES.

COpy CHANGES.

ADD A TO B.

text-line-l

text-line-2
text-line-3
ADD A TO B.
Figure 2-6

Placing the Library Text After the COPY Statement

Referring to Figure 2-6, the compiler takes the
the order shown:
1.

scans the COpy statement

prints the COpy statement

prints the library text

prints the next sequential statement

2.3.5

following

steps,

Common Errors in Using the Library Facility

Common errors to avoid when using the library facility are:
•

Failing to follow the rules for
when creating the library file

•

Writing the library file in one format (conventional
terminal) and the source program in the other

•

Forgetting to terminate the COPY statement with a period

•

Using data-names in the library file that also appear in
source program, thus causing duplicate names

the

•

Writing the library text so that when it is merged
source program, it becomes syntactically incorrect

into

the

•

Merging the wrong library file, either
versions exist or because of misspelling

multiple

•

Writing other source material on the same line following the
COPY statement, thus causing confusion in the source program
listing

•

Forgetting that numeric literals (such as 02, 77, etc.) used
in
the REPLACING option replace level-numbers, picture
descriptions, and paragraph or section names, when they find
matches.
2-12

terminal

reference

because

format
or

OSING TRAX COBOL

•

2.4

Forgetting that a period must appear in the text file if it
is
to appear in the source program (the period that
terminates the COpy statement is replaced by the text).

COMPILER SWITCHES

The TRAX COBOL compiler provides a series of compile-time switches.
Using these switches, you can tailor your compilation listing and
assign particular characteristics to the generated object modules.
Table 2-2 provides a list of the compiler switches and their meanings.
Table 2-2
COBOL Compiler Switches
Switch

Meaning

/ACC:n

Produce an object program only if the source
program contains diagnostics with severities
equal to or less than n. ~he range of n must be
0<n<2,
Where:

o = Informational diagnostics
1 = Warning diagnostics
2 = Fatal diagnostics

The default is /ACC:l.
/CREF

Include a cross-reference listing as part of the
listing file output. When /CREF is specified,
data-names, procedure-names, and source line
numbers are sorted into ascending order and
appended to the end of the compilation listing.
The symbol # is used to indicate the line in
which the referenced name is defined.
NOTE
The use of /CREF significantly slows
down the compilation of large programs.

/CSEG:nnnn

Allows you to
specify
the
maximum
size
procedural code PSECT to be produced by the
size
compiler where nnnn is
the
maximum
procedural code PSECT, in decimal bytes. The
minimum value of nnnn is 100.

2-13

USING TRAX COBOL

Table 2-2 (Cont.)
COBOL Compiler Switches
Switch

Meaning

/CVF

Indicates to the compiler that the
source
program
is
in
conventional format
(i.e.,
80-character images with Area A beginning in
character position 8).

/ERR:n

Suppress the printing
severity number less
must be 0<n<2.

of diagnostics with a
than n. The range of n

Where:

o = Informational diagnostics
1 = Warning diagnostics
2 = Fatal diagnostics
The switch cannot suppress severity 2 (fatal)
diagnostics.
(An entry of 2 suppresses the
printing of all severity numbers that are less
than 2.) The default is /ERR:O.
/HELP

Display on the user terminal information
how to use the compiler switches.

about

/KER:kk

Instruct the compiler to generate PSECT names
using the two-character kernel specified by kk
to make them unique to this compilation, where
kk is a two character string that may contain
the numbers 0 through 9 and the letters A
through z.
NOTE
The sample program listed in Figure 2-7
was compiled using the /KER:kk switch.
See Figure 2-10 which contains
the
Procedure
Map
generated
for
this
program.
Notice
that
the
PSECTs
generated all contain the two character
kernel xx.

/MAP

Produce the following special map listings:
•
•
•
•
•
•

/NL

Data Division (Figure 2-9)
Procedure Map (Figure 2-10)
External Subprograms Referenced
(Figure
2-15)
Data and Control PSECTs
(Figures 2-12
and 2-14)
OTS Routines Referenced (Figure 2-13)
Segmentation Map (Figure 2-11)

Instruct the compiler not to list the source
statements copied from a library file. The
resultant source listing contains only the COpy
statement.

2-14

USING TRAX COBOL

Table 2-2 (Cont.)
COBOL Compiler Switches
Switch

Meaning

IOBJ

Print the object location in which the code for
each verb of the program is located.
The
information is listed on the line preceding the
source statement it describes (Figure 2-15).

IODL

Instruct the compiler to generate an ODL file
(default condition).
To override the default
condition, enter /-ODL.

IOV

Instruct the compiler to make all procedural
PSECTs (segments) overlayable. Therefore, the
root or main program will contain no procedural
statements.

IPFM:nn

Allows you to define the maximum number of
nested PERFORM statements in the program being
compiled. If specified, the compiler generates
a nested PERFORM stack equal in depth to the
decimal number specified by nne
The default
nested perform size is 10.
It is to your
advantage to use this switch to adjust the
nested PERFORM stack size to the exact number
required. This assures maximum utilization of
memory in that only the exact amount of PERFORM
stack space is generated.

/PLT

Directs the COBOL compiler to automatically pool
literals to minimize the memory required to
store them (default condition).
Pooling of
literals, however, slows down compiler execution
speed. To bypass literal pooling for
increased
compiler-speed, enter /-PLT.

IRa

Directs the compiler to generate
read-only
PSECTs
for
the
Procedure Division object
modules. The default status is read/write.

/SYM:n

Allows you to obtain more symbol table space for
the compilation, where "n" (an integer in the
range of 1 through 4)
specifies the space
required for the maximum number of data-names
and procedure-names allowed in the compilation.
See Table 2-3 for the correspondence between the
integer specified by n, and the number of
data-names and procedure-names assigned.

2-15

OSING TRAX COBOL
Table 2-3
/SYM:n Switch Values

2.5

Maximum Data-Names

Maximum Procedure-Names

761

1021

1531

2039

(defaul t)

SAMPLE TRAX COBOL OUTPUT

The following Figures 2-7 through 2-18 show and describe sample output
produced by the COBOL compiler:
CMD:MAP,MAP/MAP=MAP/KER:XX
IDENT: 005160
00001
00002
00003
00004
00005
00006
00007
00008
00009
00010
00011
00012
00013
00014
00015
00016
00017
00018
00019
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032

IDENTIFICATION DIVISION.
PROGRAM-ID. MAP.

*
*

EXERCISE COMPILER MAP PROCESSORS.

* ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. PDP-II.
OBJECT-COMPUTER. PDP-II.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 DEC PIC 9(4).
77 BIN PIC 9(4) USAGE COMPo
77 CHR PIC X(4).
LINKAGE SECTION.
77 L1 PIC X.
77 L2 PIC X.
77 L3 PIC X.
77 L4 PIC X.
PROCEDURE DIVISION USING L1 L3 .
SO SECTION.
PO.
STOP RUN.
Pl.
DISPLAY L3.
DISPLAY "ABC".
Sl SECTION.
P2.
MOVE DEC TO DEC.
MOVE DEC TO BIN.
MOVE BIN TO BIN.
Figure 2-7

Sample Source Program Listing

2-16

OSING TRAX COBOL

MOVE BIN TO DEC.
MOVE CHR TO CHR.
MOVE ALL SPACES TO CHR.
MOVE DEC TO CHR.
ADD DEC TO DEC.
ADD DEC TO DEC ROUNDED.
SUBTRACT DEC FROM DEC.
SUBTRACT DEC FROM DEC ROUNDED.
SUBTRACT BIN FROM BIN.
SUBTRACT BIN FROM BIN ROUNDED.
MULTIPLY BIN BY BIN GIVING BIN.

00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00043
I 00043 0371

POSSIBLE HIGH ORDER RECEIVING FIELD TRUNCATION.

00044

MULTIPLY DEC BY DEC GIVING DEC.

I 00044 0371

POSSIBLE HIGH ORDER RECEIVING FIELD TRUNCATION.

00045
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
00058
00059
00060
00061
00062
00063
00064
00065

DIVIDE BIN BY BIN GIVING
DIVIDE DEC BY DEC GIVING
DIVIDE DEC BY DEC GIVING
DIVIDE BIN BY BIN GIVING

BIN.
DEC.
DEC ROUNDED.
BIN ROUNDED.

P4.
CALL
CALL
CALL
CALL
CALL
CALL
CALL
CALL
CALL
CALL
CALL
CALL
CALL
CALL
CALL
CALL

"A"
"AB".
"ABC".
"ABCOOO".
"ABCOOl".
"ABC002".
"ABC003".
"ABC004".
"ABC005".
"ABC006
"ABC007".
"ABC008".
"ABC009".
"ABCOI0".
"ABCOll".
"ABC012".

Figure 2-7 (Cont.)

•

Sample Source Program Listing

2-17

OSING ~RAX COBOL
FILE-TO-LUN ASSIGNMENT TABLE
NAME

SOURCE

RELATIVE

LINE

LUN

00019
00025
00033

00001.
00002.
00003.

SQ-FSl
IX-FSl
RL-FSl
where:

is a file-name that appears in the SELECT clause
in the Input-Output Section.
The file names
appear in the order in which they occur in the
Input-Output Section.

NAME

SOURCE
RELATIVE

LINE
LUN

Figure 2-8

is
the
appears.

line

which

is
the relative logical
assigned, beginning with 1.

the

File

unit

number

File-to-Relative-LUN Assignment Table

2-18

Definition
(LUN)

OSING TRAX COBOL

DATA MAP
LEVEL

NAME

SOURCE
LINE

DDIV
LOCN

DIR
LOC

USAGE CLASS OCC LEN

01
01
01
L 01
L
05
05
L
L
05
05
L
05
L
05
~
L 01
05
L
L
05
05
L
05
L
05
L
05
L
L 01
L
05
02
L
L
05
L
05
05
L
05
L

DEC
BIN
CHR
LS-ALPHA-DATA
LA1
LA2
LA3
LA4
LAS
LA6
LS-NUM-DISP-DATA
LN1
LN2
LN3
LN4
LN5
LN6
LS-COMP-DATA
LC1
LC2
LC3
LC4
LC5
LC6

00013
00014
00015
00036
00037
00038
00039
00040
00041
00042
00043
00044
00045
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056

00022"4
000230
000232
000000
000000
000006
000016
000030
000044
000062
000000
000000
000004
000011
000016
000020
000022
000000
000000
000002
000004
000010
000014
000U20

000000
000006
000014

DSP
CMP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
DSP
CMP
CMP
CMP
CMP
CMP
CMP

COLUMN
L

******

000000
000006
000014
000022
000030
000036

******
000044
000052
000060
000066
000074
000102

******
000110
000116
000124
000132
000140
000146

NUM
NUM
AN
AN
AN
AN
AN
AN
AN
AN
AN
NUM
NUM
NUM
NUM
NUM
NUM
AN
NUM
NUM
NUM
NUM
NUM
NUM

CONTENTS
Data-item is defined in linkage section

LEVEL

Level number of data-item

NAME

Data-item name

SOURCE
LINE

Source line number where data-item is defined

DDIV
LOCN

Octal byte offset of data-item in data
PSECT (program section).
NOTE:

storage

For Linkage Section items,
this
offset is always relative to the
01 entry.

For non-Linkage Section
items,
this offset 1S relative to data
PSECT $KKDAT (KK=kerne1).

Figure 2-9

Sample Data Map

2-19

0004
0002
0004
0066
0006
0008
0010
0012
0014
0016
0021
0004
0005
0005
0002
0002
0003
0020
0002
0002
0004
0004
UO 0004
00 0004
00
00
00
00
00
00
00
00
00
00
00
00
00
00
00
00
00
00
00
00
00
00

USING TRAX COBOL

CONTENTS

COLUMN
DIR
LOC

Octal byte offset of data-item's directory
directory PSECT.
NOTE:

USAGE

in a

For Linkage Section items,
this
offset is relative to data PSECT
$KKARG (KK=kernel).

For non-Linkage Section
items,
this offset is relative to data
PSECT $KKDDD (KK=kernel).

If data-item is not referenced, no
directory is allocated and ******
appears.

One of the following abbreviations:
DSP - Display
CMP - Computational
NDX - Index

CLASS

One of the following abbreviations:
ALPHA - Alphabetic
NUM - Numeric
AN - Alphanumeric
ANEDIT - Alphanumeric edited
NMEDIT - Numeric edited

OCC

The number
data-item.

subscripts

LEN

The length in bytes of data-item.

Figure 2-9 (Cont.)

2-20

associated

Sample Data Map

with

this

USING TRAX COBOL

PROCEDURE NAME MAP
NAME

SOURCE
LINE

PSECT

OFFSET SEG

00022
00023
00025
00028
00029
00049

$XXOOI
$XXOOI
$XXOOI
$XX002
$XX002
$XX002

000024
000024
000036
000024
000024
000312

PO
PI
Sl
P2
P4

Column

SECT

00
00
00
00
00
00

PARA

S
P
P
S
P
P

Contents

NAME

Procedure-name

SOURCE
LINE

Source line number where procedure appears

PSECT

Executable code PSECT name
which contains the procedure

OFFSET

Octal byte offset of procedure in its executable
code PSECT

SEG

The segment-number of the section containing the
procedure

SECT

If the procedure is a section, an S will
in this column

PARA

If the procedure is a paragraph, a P will appear
in this column
Figure 2-10

(program

Sample Procedure-Name Map

2-21

section)

appear

USING TRAX COBOL

SEGMENTATION MAP
SECTION NAME

so
Sl

SEGMENT NO.

NAME

00
00

$XXOOI
$XX002

SIZE
000116
000532

00039
00173

Contents

Column
SECTION NAME

The section-name.

SEGMENT NO.

The segment-number assigned to the section.

NAME

The name of the executable procedural PSECT
(program section) generated for this section.
If the executable code generated for a section
exceeds
the code segment limit
(see /CSEG
switch), more than one procedural PSECT is
generated for the section. If this happens, the
multiple PSECT names will appear in a vertical
column.

SIZE

The size of the procedural
followed by decimal words.
Figure 2-11

psect,

octal

bytes

Sample Segmentation Map

COMPILER GENERATED PSECTS
SIZE

NAME
$XXENT
$XX003

000036
000046

00015
00019
Contents

Column
NAME

The name of the compiler-generated psect.

SIZE

The size of the PSECT:
words.

octal bytes followed by decimal

NOTE: This map lists those executable PSECTs (program sections)
that
are generated by the compiler. These PSECTs are not the result of
anything in the Procedure Division, but are generated to provide for
runtime execution initialization.
Figure 2-12

Sample of Compiler-Generated PSECT Map

2-22

USING TRAX COBOL

REFERENCED OTS ROUTINES
$XMBB
$XSUBD
$XEDIS
$XINIT

$XMDD
$XSUBR
$XGO

$XMDB
$XMULB
$XENDP

$XMBD
$XSUBB
$XSTPR

$XMCC
$XSBBR
$XABRT

$XMAL
$XMULB
$XCALL

$XADDD
$XDIVB
$XEXIT

$XADDR
$XDIVR
$XSUBK

Contents
This map contains the names of all COBOL OTS
(Object Time System)
routines that are referenced by the code generated by the compiler.

Figure 2-13

Sample Map of Referenced

OTS Routines

DATA PSECT MAP
NAME

SIZE

$XXDAT
$XXDDD
$XXPDT
$XXARG
$XXWRK
$XXLIT
$XXLTD
$XXLST
$XXPFM
$XXSDT
$XXADT
$XXUSE
$CBIOT
$CBFAI
$CBXAI
$XXIOB
$CBIFI
$CBIRI
$CBKDl
$CBBDI
$CBKBI
$CBFDI
$CBSWT

000236
000022
000014
000006
000102
000006
000014
000002
000214
000040
000000
000030
000126
000000
000000
000000
000000
000000
000000
000000
000000
000000
000002

00079
00009
00006
00003
00033
00003
00006
00001
00070
00016
00000
00012
00043
00000
00000
00000
00000
00000
00000
00000
00000
00000
00001

Column

Contents

NAME

The name of the data PSECT generated by the compiler.

SIZE

The size of the data PSECT, in octal bytes, followed by
decimal words.

NOTE: This map lists the data (nonexecutable) PSECTs generated by the
compiler.
See Appendix D for a description of the Data PSECTs
generated for each compilation.

Figure 2-14

Sample Data PSECT Map

2-23

USING TRAX COBOL

EXTERNAL SUBPROGRAM REFERENCES
AB
ABCOIO

Pi.

ABC009

ABC
ABCOII

ABCOOO
ABCOl2

ABCOOI

ABC002

ABC003

ABC004

Contents
This map contains the names of all external subprograms referenced
CALL statements in the COBOL source program.

Figure 2-15

Sample Map of

SEVERITY

ERROR COUNT

W
F

External Subprogram References MAP

Column

Contents

SEVERITY

Contains the error severity code.
The following
list contains the possible severity codes:

ERROR COUNT
NOTE:

Information

warning

Fatal

Contains the number of errors encountered.

This listing is generated for every COBOL compilation.

Figure 2-16

Sample Compilation Error Count Listing

2-24

USING TRAX COBOL
CO~PILER

GENERATED ODL FILE

iCOBOL STANDARD ODL FILE GENERATED ON: 05-JAN-78
iCOBOBJ=MAP.OBJ
iCOBKER=XX
.NAME XX$050,GBL
.PSECT $XX003,GBL,I,RW,CON
XX050$: .FCTR *XX$050-$XX003
XXOVR$: .FCTR
XX050$

16:05:40

NOTE
This listing is generated
object file is generated.
Figure 2-17

whenever

Sample Compiler-Generated ODL File Listing

MOVE REPETITIONS (POWER) TO REPS.
001 000104
PERFORM TESTI REPS TIMES.
001 000122
MOVE TESTDELTA(TESTNUMBER) TO BASETIME(POWER) PEOPLE
001 000160
DISPLAY "10**" POWER" REPETITIONS TOOK "
PEOPLETIME " HUNDREDTHS OF SECONDS.".
001 000206
ADD 1 TO POWER.
001 000220
001 000254
IF POWER NOT> POWERLIMIT GO TO IS.
001 000264
GO TO 110.

00110
PERFORM
00111
MOVE
00112
DISPLAY
00113
00114
ADD
00115
IF
GO
00116
GO
00117

For each COBOL verb, a line of the following format appears
listing, preceding the source line that contains the verb:
VERB:

the

containing

the

PPP AAAAAA

where:
1.

VERB is the verb name

PPP is the decimal number of the code
object code generated for the verb.

AAAAAA is the octal byte offset within the PSECT at which the
object code is generated.
Figure 2-18

2.6

PSECT

Sample Output Using OBJ Switch

USING THE ODL MERGE UTILITY

To convert the ODL file generated by the compiler into a complete ODL
file,
or to merge ODL files from more than one compilation into a
single ODL file, you use the Merge Utility.

2-25

USING TRAX COBOL

2.6.1

Invoking the Merge Utility

To invoke the ODL Merge utility, type RUN $MRG in response to a system
prompt.
When the ODL Merge Utility is loaded and ready to accept
input specifications, it issues the following message:
PLEASE ENTER FILE SPECIFICATION FOR OUTPUT FILE
Enter the file specification for the
merged ODL file.
For example:

file

that

receive

the

PLEASE ENTER THE FILE SPECIFICATION FOR OUTPUT FILE
BILBO.ODL

When the output file specification is received, Merge
prompt:

issues

another

DO YOU WANT AN ABBREVIATED OR MERGED ODL FILE?
PLEASE ANSWER A (ABBREVIATED) OR M (MERGED)
If you enter M, the ODL Merge utility generates a file that is a
concatenation of all the input ODL files.
If you enter an A, an ODL
file containing indirect command file specifications for each input
ODL file is generated.
Input ODL Files

I Merged ODL

Abbreviated ODL

IBILBOl.ODLI

BILBOl.ODL

@BILBOl.ODL

I BILB02 .ODLI

BILB02.0DL

@BILB02.0DL

I BILB03 .ODL I

BILB03.0DL

@BILB03.0DL

Merge supplied
ODL statements

Figure 2-19

Merged vs. Abbreviated ODL File

For example, the following results in the generation of an abbreviated
file:
DO YOU WANT AN ABBREVIATED OR MERGED ODL FILE?
PLEASE ANSWER A (ABBREVIATED) OR M (MERGED) A

Following the A'or M specification, Merge make the following request:
DO YOU WANT TO OVERLAY I/O SUPPORT ROUTINES?
PLEASE ANSWER Y(ES) OR N(O)
Simply enter Y for yes and N for no, followed by a carriage return.
ODL Merge now requests that you enter the file specification for the
first or only ODL file to be merged. The following message is issued:
PLEASE ENTER FILE SPECIFICATION FOR INPUT ODL FILE
Enter the input ODL file specification in response to this message
follows:

2-26

USING TRAX COBOL

file-specification

For example:
PLEASE ENTER FILE SPECIFICATION FOR INPUT OOL FILE
BILBOl.ODL

When OOL Merge has completed processing this input file,
it requests
you to enter the device and directory under which the associated
object file is stored. The following message is issued:
OBJECT PROGRAM REFERENCED IN ODL FILE IS:
object-filename.ext
PLEASE ENTER OBJECT FILE DEVICE AND PPN IN
THE FORMAT:

DEV:[PROJECT,PROGRAMMER]

Enter the device code and PPN if different from the
assignment. Otherwise, enter a carriage return only.

system default
For example:

OBJECT PROGRAM REFERENCED IN OOL FILE IS:
BILBOl.OBJ
PLEASE ENTER OBJECT FILE DEVICE AND PPN IN
THE FORMAT:

OEV:[PROJECT,PROGRAMMER]

The processing of the input ODL
issues the following message:

file

complete.

OOL

Merge

now

ANY MORE INPUT ODL FILES?
PLEASE ANSWER Y(ES) OR N(O)
Enter Y for yes and N for no followed by a carriage return. If Y is
entered, Merge reissues the PLEASE ENTER FILE SPECIFICATION FOR INPUT
OOL FILE message, and the merging procedure is repeated.
If N is
entered, the output file is completed, and the following message is
issued:
ODL MERGE IS COMPLETE
MERGED OOL FILE IS file-specification

2-27

USING TRAX COBOL
Figure 2-20 shows a sample ODL file merge dialogue.
RUN $MRG

PLEASE ENTER FILE SPECIFICATION FOR OUTPUT FILE
DIVA.ODL

DO YOU WANT AN ABBREVIATED OR MERGED ODL FILE?
PLEASE ANSWER A{BBREVIATED} OR M(ERGED} M ~
DO YOU WANT TO OVERLAY I/O SUPPORT ROUTINES?
PLEASE ANSWER Y{ES) OR N(O} N

PLEASE ENTER FILE SPECIFICATION FOR INPUT ODL FILE
DIVBUG.ODL

OBJECT PROGRAM REFERENCED IN ODL FILE IS:
DIVBUG.OBJ
PLEASE ENTER OBJECT FILE DEVICE AND UIC IN THE FORMAT:
DEV:[GROUP,MEMBER]

ANY MORE INPUT ODL FILES?
PLEASE ANSWER Y (ES) OR N (O) N ~
ODL FILE MERGE COMPLETE
MERGED ODL FILE IS: DIVA.ODL
caL -- 15: STOP RUN
Figure 2-20

2.6.2

Sample ODL File Merge Dialogue

ODL Merge Utility Error Messages

Whenever the ODL Merge utility encounters an error in processing,
it
issues an error message to the user terminal. These error messages
are listed in Table 2-3.

2-28

OSING TRAX COBOL
Table 2-4
Merge Error Messages
BAD FORMAT PPN: [p,p]
Description

The PPN you specified does not conform to system
standard syntax.

User Action

Respecify the PPN using the correct syntax.

THIS ODL FILE CONTAINS A jCOBMAIN LINE
A jCOBMAIN LINE HAS ALREADY OCCURRED
THIS ODL FILE ~S IGNORED
Description

A i COBMAN line in an ODL file that identifies the
object program as a main program. This message
is telling you that Merge has already processed
an ODL file that contained a jCOBMAIN line.
Since a task image can only contain one main
program, this ODL file is ignored.

MULTIPLE jCOBKER HEADER LINE DETECTED
THIS ODL FILE IS IGNORED
Description

A iCOBKER line is an ODL file that specifies the 2
character kernel used to identify PSECTs foi the
object file corresponding to this ODL file.
Only one
jCOBKER line per ODL file is allowed.
This ODL file is ignored.

MULTIPLE jCOBOBJ HEADER LINE DETECTED
THIS ODL FILE IS IGNORED
Description

A iCOBOBJ line in an ODL file that identifies the
object
file
for
which the ODL file was
generated.
Only
one
such
object
file
specification is allowed in a compiler-generated
ODL file.
This ODL file is ignored.

NOT STANDARD COBOL ODL FILE
FILE IS IGNORED
Description

The ODL file contains nonstandard
See Chapter 11 for ODL file format.

ODL

lines.

OPEN UNSUCCESSFUL
Description

User Action

One of the following conditions exists:
1.
2.
3.
4.
5.

The
The
The
The
The

device is not on line
device is not mounted
hardware has failed
file does not exist
user is not allowed access to the file

1.
2.
3.

Determine which condition exists
Rectify the condition
Reenter the command

2-29

USING TRAX COBOL

Table 2-4 (Cont.)
Merge Error Messages
READ ERROR -- MUST ABORT
Description

An unrecoverable read error occurred when the
Merge Utility attempted to read the input ODL
file.
The input and output ODL files are
closed, and the Merge Utility terminates.
One of the following conditions exists:

User Action

1.
2.
3.
4.

The device is not on line
The device is not mounted
The hardware has failed
The volume is full

1.
2.

Determine which condition exists
Rectify the condition
Reenter the command

2.7

REFORMAT

COBOL, as implemented in the TRAX support environment, accepts source
programs coded in the terminal reference format.
Existing source
programs in either format can be compiled, however, new support
environment COBOL programs must be created in the terminal format.
The REFORMAT utility program reads source programs that were coded in
the terminal format and converts them to 80-column conventional format
source programs.
with REFORMAT you can write source programs in the terminal format;
then,
if compatibility is ever required for any of those programs, it
provides a simple method for conversion to the conventional format.
REFORMAT uses the following steps to expand each line of Terminal
format coding to the 80-character Conventional format coding:
•

It generates a 6-character line number of 000010, places that
number in the first six character positions of the line, and
increases it by 000010 for each subsequent line;

•

It places any continuation or comment symbols (-,*, or /)
character position 7;

into

places the coding from the Terminal format line into
• It
character
positions
8-72,
thereby creating a line of
Conventional format coding;
•

It replaces any horizontal tabs with the appropriate number of
space characters to simulate tab stops at character positions
5,13,21,29,37,45,53,61, and 66 of the Terminal format line:

•

It moves spaces into any character positions left between
last character of coding and character position 73;

•

It places either identification characters
(if they were
supplied at program initialization) or spaces into character
positions 73-80;

•

It right justifies (against margin R)

2-30

the

first

line

the

USING TRAX COBOL
continued non-numeric literal, thus guaranteeing that the
literal will remain the same length as it was in the default
format;

2.7.1

•

It right justifies (against margin R) the first
COBOL word that is split over two lines;

part

any

•

It creates a line containing a slash (I)
in position 7 and
space characters in positions 8 through 72 for every form-feed
character that it encounters.

REFORMAT Command String

Since REFORMAT is written in COBOL, it runs as a COBOL object program.
It has no logical switches. To run it, simply type in the following
sequence of responses
(prompting messages typed by REFORMAT are
underlined) :
RUN $RFM

RET

This causes REFORMAT to begin execution.
REFORMAT
immediately
requests the file specifications for the two files (input and output)
to be processed.
In response to its prompting messages, type in the
file specifications for your two files.
RFM-INPUT FILE SPEC:
RFM-QUTPUT FILE SPEC:
When the system has successfully opened both files, REFORMAT types the
following request for an identification entry in columns 73 through
80. If you desire an identification entry, type in from one to eight
characters.
REFORMAT places these characters,
left justified, in
columns 73 through 80 of each output line. If no entry is required,
type a carriage return.
RFM-COLS 73 TO 80:
Following this response, REFORMAT reads the input file and
as 80-character records, in Conventional reference format.

writes

When it has processed the last record in the file, REFORMAT displays
the following messages;
the first indicating th~ number (nnnnn) of
output records produced and the second requesting another input file.
RFM-nnnnn LINES PROCESSED.
RFM-INPUT FILE SPEC:
If there is another file to be reformatted, follow the same sequence
with the specifications for the next file.
If not, type Control Z to
terminate execution.

2.7.2

REFORMAT Error Messages

If any of the responses to the prompting messages contain detectable
errors, REFORMAT displays the following messages indicating the
problem.
RFM-ERROR IN OPENING INPUT FILE
RFM-TRY AGAIN
RFM-INPUT FILE SPEC:

2-31

USING TRAX COBOL

The system could not open the input file.
Either the file is not
present on the device specified (the default device is SY:) or the
file name is typed incorrectly. The usual I/O error messages precede
this message.
To continue processing that file, examine the input file spec and type
in a corrected version. To process another file, type in a new input
file specification. To terminate execution, type Control Z.
RFM-ERROR IN OPENING OUTPUT FILE
RFM-TRY AGAIN
RFM-OUTPUT FILE SPEC:
The system could not open the output file. An incorrectly typed file
specification usually causes this error.
(The default device is SY:.)
The usual I/O error messages precede this message.
To continue, examine the output file specification and type
corrected version. To terminate execution, type Control Z.

RFM-INPUT FILE IS EMPTY
RFM-INPUT FILE SPEC:
The system successfully opened the input file,
statement encountered the AT END condition.

but

the

first

READ

To continue, type in a new input file specification for another
To terminate execution, type Control Z.

file.

RFM-ERROR IN READING INPUT FILE
RFM-INPUT FILE SPEC:
The first attempt to read the input file was unsuccessful. This error
is usually caused by an input record length exceeding 86 characters.
(Although terminal format records should not exceed 66 characters in
length, REFORMAT provides a record area of' 86 characters and ignores
the right-most 20 characters.)
To continue, type in a new input file specification for another
To terminate execution, type Control Z.

file.

RFM-ERROR IN READING INPUT FILE
RFM-REFORMATTING ABORTED
RFM-nnnnn LINES PROCESSED
RFM-INPUT FILE SPEC:
While reading input records (other than the first record), REFORMAT
was unsuccessful in an attempt to read a record.
It terminates
execution and closes both files.
RFM-ERROR IN WRITING OUTPUT FILE
RFM-REFORMATTING ABORTED
RFM-nnnnn LINES PROCESSED
RFM-INPUT FILE SPEC:
REFORMAT was unsuccessful in an attempt to write an output record.
terminates execution and closes both files.

To process another file, type in a new input file specification and
continue with the prompting message sequence. To terminate execution,
type Control Z.

2-32

CHAPTER 3
NON-NUMERIC CHARACTER HANDLING

3.1

INTRODUCTION

COBOL programs hold their data in fields whose sizes are described in
their
source
programs.
These fields are thus "fixed" during
compilation to remain the same size throughout the lifespan of the
resulting object program.
The data descriptions of the fields in a COBOL program describe them
as belonging to any of three data classes -- alphanumeric, alphabetic,
or numeric class. Numeric class data
items contain only numeric
values,
alphabetic class only A-Z and space, but alphanumeric class
data items may contain values that are all alphabetic, all numeric, or
a mixture of alphabetic bytes,
numeric bytes,
or,
in fact, any
character from the ASCII character set.
Further, these three classes are subdivided into five categories:
alphabetic,
numeric,
numeric
edited,
alphanumeric edited,
and
alphanumeric.
Every elementary item except for
an index data item
belongs to one of the classes and further to one of the categories.
The class of a group item is treated at object time as alphanumeric
regardless of the classes of subordinate elementary items.
For alphabetic
synonymous.

and

numeric

(data

items)

An alphabetic field is a field declared
(A-Z and space) characters.

class
contain

and

category

only

An alphanumeric class field that is declared to contain
character is called an alphanumeric category field.

are

alphabetic
any

ASCII

If the data description of an alphanumeric class field specifies that
certain editing operations will be performed on any value that is
moved into it, that field is called an alphanumeric or numeric edited
category field.
When reading the following sections of this chapter, this distinction
between the class or category of a data item and the actual value that
the item contains should always be kept in mind.
Sometimes the text
refers
to
alphabetic,
alphanumeric,
and
alphanumeric edited data items as non-numeric data items. This is to
distinguish them from items that are specifically described as numeric
items.
Regardless of the class of an item, it is usually possible to store a
value 1n the item, at object time,
that is "illegal".
Thus,
non-numeric ASCII characters can be placed into a field described as
numeric class,
and an alphabetic class field may be loaded with
non-alphabetic characters.
3-1

NON-NUMERIC CSARACTER HANDLING
To increase readability, the following sections oc~asionally omit the
word "class" when describing an item: however, the reader should
regard the descriptive word, numeric, alphabetic, or alphanumeric, as
referring to the class of an item unless it applies specifically to
the value "in the item.
This chapter discusses non-numeric class data and the non-arithmetic,
non-input-output operations that manipulate this type of data.

3.2

DATA ORGANIZATION

Usually, the data areas in a COBOL program are orgai&ized into grou~
items with subordinate elementary items. A group item is a data item
that is followed by one or more data items
(elementary items) with
higher valued level numbers. An elementary item has no higher valued
subordinate level number.
All of the data areas used by COBOL programs
(except for certain
registers and switches) must be described in the Data Division of the
~ource program.
The compiler allocates memory space for these fields
and fixes them in size at compilation time.
The following sub-sections (3.2.1 and 3.2.2)
discuss, on a general
level, how the compiler handles group and elementary data items.

3.2.1

Group Items

The size of a group item is the total size of the data 3rea occupied
by its subordinate elementary items. The compiler considers group
items to be alphanumeric DISPLAY items.
Thus,
the
software
manipulates group items as if they had been described as PIC X()
items, and ignores the structure of the data contained within them.

3.2.2

Elementary Items

The size of an elementary item is determined by the number of
allowable symbols it contains that represent character positions. For
example, consider the following fields:
01 TRANREC.
03 FIELD-l PIC X(7).
03 FIELD-2 PIC S9(5)V99.
Figure 3-1
Field Sizes
Both fields consume seven bytes of memory:
however, FIELD-~ contains
seven alphanumeric bytes while FIELD-2 contains decimal digits and an
operational sign. Although certain verbs handle these two classes of
data differently, the data, in either case, occupies seven bytes of
TRAX memory.
COBOL operations on such fields are independent of the
mapping of the field into TRAX memory words (16-bit words that hold
two 8-bit bytes). Thus, a field may begin in the left or right-hand
byte of a word with no effect on the function of any operations that
may refer to that field.

3-2

NON-NUMERIC CHARACTER HANDLING
In effect, the compiler sees memory as a continuous array of bytes,
not words. This becomes particularly important when declaring a table
with the OCCURS clause (see Chapter 5, Table Handling).
Records (a 01 level entry and all of its subordinate entries) and data
item~
that have a level number of 77 and all literal values given in
the Procedure Division automatically begin on even byte addresses.
I/O verbs require that records be aligned on word boundaries because
TRAX COBOL file system reads and writes integral numbers of
words.

the

Non-input-output verbs do not require alignment of the data. However,
when two fields are aligned identically,
the processing verb can
sometimes increase its efficiency by processing them a word at a time
rather that a byte at a time.
In all cases, automatic word alignment of literals, records, and/or 77
items increase the opportunity for more efficient processing.

3.3

SPECIAL CHARACTERS

COBOL allows the user to manipulate any of the 128 characters of the
ASCII" character set as alphanumeric data even though many of the
characters are control characters, which usually control input/output
devices.
Generally, alphanumeric data manipulations are performed in
a manner that attaches no "meaning" to an 8-bit byte. Thus, the user
can move and compare these control characters in the same manner as
. Iphabetic and numeric characters.
Although the object program can manipulate all ASCII characters,
certain control characters cannot appear in non-numeric literals since
the compiler uses them to delimit the source text.
Further,
the
keyboards of the console and keypunch devices have no convenient input
key for many of the special characters, thus making it difficult to
place them into non-numeric literals.
Special characters may be placed into data fields of the object
program by placing the binary value of the special character into a
numeric COMP field and redefining that field as alphanumeric DISPLAY.
Consider the following example of r~definition.
(Keep in mind that
the even byte of a word corresponds to the low-order bits of a binary
word.)
01
01
01
01
01
01

LF-COMP PIC 999 COMP VALUE 10.
LF REDEFINES LF-COMP PIC X.
HT-COMP PIC 999 COMP VALUE 9.
TAB REDEFINES HT-COMP PIC X.
CR-COMP PIC 999 COMP VALUE 13.
CR REDEFINES CR-COMP PIC X.
Figure 3-2
Redefining Special Characters

The sample coding in Figure 3-2 introduces each character as a I-word
COMP item with a decimal value, then redefines it as a single byte.
(The second byte of the redefinition need not be described at the 01
level, since redefinition at this level does not require identically
sized fields.)

3-3

NON-NUMERIC CHARACTER HANDLING
The following ASCII code chart may be used to determine the decimal
value f~r any ASCII character. To use the chart, find the desired
character;
then add its row and column values together to determine
the decimal integer to be supplied as a VALUE for the computational
item •

.';;Fz
Value

040

048

056

064

072

OBO

088

096

104

space

(

8
9
:
(

&
apos

6
7

>
?

E
F
G

Q
R
S
T
U
V

X
Y
Z
[

H
I
J
K
L
M
N

)

0
1
2
3
4

..!

grave
a
b
c
d
e
f

h
i
j
k
I
m
n

000

008

016

024

032

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

112

120

Row
Value

0
1
2
3
4
5

6
7

*
+

;

A
B
C

\
J
(t)
(~,

r
s

u
v
w

(ESC'
DEL

I
I

Figure 3-3
ASCII Code Chart

3.4

3.4.1

TESTING NON-NUMERIC FIELDS

Relation Tests

An IF statement that contains a relation condition (greater-than,
less-than, equal-to, etc.) can compare the value in a non-numeric data
item with another value and use the result to alter the flow of
control in the program.
An IF statement with a relation condition compares two operands,
either of which may be an identifier or a literal, except that bot~
cannot be literals. If the relation exists between the two operands,
the relation condition has a truth value of true.
Figure 3-4 illustrates the general format of a relation condition.
(The relational characters ">," "<," and "=," although required, are
not underlined to avoid confusion with other symbols such
as
greater-than-or-equal-to.)
IS
'
1
IS
1'd ent1' f 1erIS
literal-l
IS
{arithmetic-expreSSion-l} { IS
IS

[NOT]
[NOT]
[NOT]
[NOT]
[NOT]
[NOT]

GREATER THAN}
LESS
{'d
EQUAL THAN
TO.
1,en t'f'
1 1er- 2
->- 11teral-2
__<
arithmetic-expression-2

Figure 3-4
Relation Condition

3-4

NON-NUMERIC CHARACTER HANDLING
When coding a relational operator, leave a space before and after each
reserved word.
When the reserved word NOT is present, the software
considers it and the next key word or relational character to be one
relational operator that defines the comparison. Figure 3-5 shows the
meanings of the relational operators.
OPERATOR

MEANING

IS [NOT] GREATER THAN
IS [NOT] >

The first operand is greater than
(or not greater than) the second operand.

IS [NOT] LESS THAN
IS [NOT] <

The first operand is less than
(or not less than) the second operand.

IS [NOT] EQUAL TO
IS [NOT] =

The first operand is equal to
(or not equal to) the second operand.

Figure 3-5
The Meanings of the Relational Operators

3.4.1.1 Classes of Data - COBOL allows comparison of both numeric
class operands and non-numeric class operands;
however, it handles
each class of data slightly differently.
For example,
it allows a
comparison of two numeric oper~nds regardless of the formats specified
in their respective USAGE clauses,
but requires that all other
comparisons
(including comparisons of any group items) be between
operands with the same usage.
It compares numeric class operands with
respect to their algebraic values and non-numeric (or a numeric and a
non-numeric) class operands with respect to a specified collating
sequence.
If only one of the operands is numeric, it must be an integer data
item or an integer literal and it must be DISPLAY usage;
further, the
manner in which the software handles numeric operands depends on the
non-numeric operand. Consider the following two types of non-numeric
operands:
1.

If the non-numeric operand is an elementary item or a
literal, the software treats the numeric operand as if it had
been moved into an alphanumeric data item (which is the same
size as the numeric operand) and then compared. This causes
any operational sign, whether carried as a separate character
or as an overpunch,
to be stripped from the numeric item;
thus, it appears to be an unsigned quantity.
In addition, if
the picture-string of the numeric item contains trailing P
characters indicating that there
are
assumed
integer
positions that are not actually present, these are filled
with zero digits during the operation of stripping any sign
that is present.
Thus,
an item with a picture-string of
S9999PPP is moved to a temporary location where it is
described with a picture-string of 9999999. If its value is
432J (-4321), the value in the temporary location will be
4321000.
The numeric digits,
stored as ASCII bytes, take
part in the comparison.

If the non-numeric operand is a ~roup item,
the software
treats the numeric operand as lf lt had been moved into a
group item (which is the same size as the numeric operand)
and then compared.
This is equivalent to a "group move".
The software ignores the description of the numeric field
(except for length) and, therefore, includes any operational
sign, whether carried as a separate character or as an
3-5

NON-NUMERIC CHARACTER HANDLING
overpunch,
in its length.
(Overpunched characters are never
ASCII numeric digits, but characters in the range of from A
through R, {, or }.) Thus, the sign and the digits, stored as
ASCII bytes, take part in the comparison, and zeroes are not
supplied for P characters in the picture-string.
The compiler will not accept a comparison between a non-integer
numeric operand and a non-numeric operand, and any attempt to compare
these two items will cause a diagnostic message at compile time.

3.4.1.2 The Comparison
Operation - If
the
two
operands
are
acceptable, the software compares them byte for byte starting at their
left-hand end.
It proceeds from left to right, comparing the
characters in corresponding character positions until it either
encounters a pair of unequal characters or reaches the right-hand end
of the longer operand.
If the software encounters a pair of unequal characters, it considers
their relative position in the collating sequence. The operand with
the character that is positioned higher in the collating sequence is
the greater operand.
If the operands have different lengths, the comparison proceeds as
though the shorter operand were extended on the right by sufficient
ASCII spaces (040) to make them both the same length.
If all of the pairs of characters compare equally,
equal.

3.4.2

the

operands

are

Class Tests

An IF statement that contains a class condition
(NUMERIC
or
ALPHABETIC)
can test the value in a non-numeric data item (USAGE
DISPLAY only) to determine if it contains numeric or alphabetic data
and use the result to alter the flow of control in the program.
Figure 3-6 illustrates the general format of a class condition.
If
the data item consists entirely of the ASCII characters 0123456789
with or without the operational sign, the class condition would
determine that it is NUMERIC.
If the item consists entirely of the
ASCII characters A through Z and space, the class condition would
determine that it is ALPHABETIC.

identifier IS [NOT] !NUMERIC
lALPHABETICf
Figure 3-6
Class Condition, General Format

3-6

NON-NUMERIC CHARACTER HANDLING
When the reserv~d word, ~OT, is present, the software considers it and
the next key word as one class condition that defines the class test
to be executed;
for example, NOT NUMERIC is a truth test for
determining if an operand contains at least one non-numeric byte.
If the item being tested was described as a numeric data item, it may
only be tested as NUMERIC or NOT NUMERIC.
(For further information on
using class conditions with numeric items, see Chapter 4.) The NUMERIC
test cannot examine an item that was described either as alphabetic or
as a group item containing elementary items whose data descriptions
indicate the presence of operational signs.

3.5

DATA MOVEMENT

COBOL provides three statements (MOVE, STRING, and UNSTRING)
that
perform
most
of
the
data
movement
operations required by
business-oriented programs. The MOVE statement simply moves data from
one field to another. The STRING statement concatenates a series of
sending fields into a single receiving field. The UNSTRING statement
disperses a single sending field into multiple receiving fields. Each
has its uses and its limitations.
This section discusses data
movement situations which take advantage of the versatility of these
statements.
The MOVE statement handles the majority of data movement operations on
character strings. However, the MOVE statement has limitations in its
ability to handle multiple fields;
for example, it cannot, by itself,
concatenate a series of sending fields into a single receiving field
or disperse a single sending field into several receiving fields.
Two MOVE statements will, however, bring the contents of two fields
together into a third (receiving) field if the receiving field has
been "subdivided" with subordinate elementary items that match the two
sending fields in size. If other fields are to be concatenated into
the third field and they differ in size from the first two fields,
then the receiving field will require additional subdivisions (through
redefinition).
Another method of concatenation with the MOVE statement is to
subdivide the receiving field into single character fields, creating a
"table" of a single character field that occurs as many times as there
are characters in the receiving field, and execute a data movement
loop which moves each sending field, a character at a time, using a
subscript that moves continuously across the receiving field.
Two MOVE statements can also be used to disperse the contents of one
sending field to several receiving fields. The first MOVE statement
can move the left-most end of the sending field to a receiving field;
then the second MOVE statement can move the right-most end of the
sending field to another receiving field.
(The second receiving field
must first be described with the JUSTIFIED clause.) Characters from
the middle of the sending field cannot easily be moved to any
rece1vlng field without extensive redefinitions of the sending field
or a character-by-char~cter movement loop (as with concatenation) •
The concatenation and dispersion limitations of the MOVE statement are
handled quite easily by the STRING and UNSTRING statements. The
following sections (3.6, 3.7, and 3.8) discuss these three statements
in detail.

3-7

NON-NUMERIC CHARACTER HANDLING
3.6

THE MOVE STATEMENT

The MOVE statement moves the contents of one field into another.
The
following illustration shows the two formats of the MOVE statement.
Format 1
MOVE FIELDl TO FIELD2
Format 2
MOVE CORRESPONDING FIELDl TO FIELD2
NOTE
Format 2 is discussed in Section 3.6.6.
FIELDl is the name of the sending field and FIELD2 is the name of the
rece1v1ng field.
The statement causes the softwa~e to move the
contents of FIELDl into FIELD2. The two fields need not-be the same
size, class, or usage;
and they may be either group or elementary
items.
If the two fields are not the same length, the software will
align them on one end or the other
and will truncate or pad (with
spaces) the other end. The movement of group items and non-numeric
elementary items is discussed below.
A point to remember when using the MOVE statement is that it will
alter the contents of every character position in the receiving field.

3.6.1

Group Moves

If either the sending or rece1v1ng field is a group item, the software
considers the move to be a group move. It treats both the sending and
receiving fields in a group move as if they were alphanumeric class
fields.
If the sending field is a group item and the receiving field
is an elementary item, the software ignores the receiving field
description
(except for the size description,
in bytes, and any
JUSTIFIED clause);
therefore, the software conducts no conversion or
editing on the receiving field.

3.6.2

Elementary Moves

If both fields of a MOVE statement are elementary items, their data
description clauses control their data movement.
(If the receiving
field was described as numeric or numeric edited,
the rules for
numeric moves -- see Chapter 4, Numeric Character Handling -- control
the data movement.)
The following table
elementary moves.

shows

the

legal

3-8

(and

illegal)

non-numeric

NON-NUMERIC CHARACTER HANDLING
Table 3-1
Legal Non-Numeric Elementary Moves
SENDING FIELD CATEGORY

RECEIVING FIELD CATEGORY
ALPHABETIC

ALPHANUMERIC
ALPHANUMERIC EDITED

ALPHABETIC

Legal

ALPHANUMERIC

Legal

ALPHANUMERIC EDITED

Legal

NUMERIC INTEGER
(DISPLAY ONLY)

Illegal

Legal

NUMERIC EDITED

Illegal

Legal

In all of the legal moves shown above, the software treats the sending
field as though it had been described as PIC XC). If the sending
field description contains a JUSTIFIED clause, the clause will have no
effect on the move.
If the sending field picture-string contains
editing characters, the software uses them only to determine the
field's size.
Numeric class data must be in DISPLAY (byte) format
integer.

and

must

If the description of the numeric data item indicates the presence of
an operational sign (either as a character or an overpunch) or if
there are P characters in the picture-string of the numeric data item,
the software first moves the item to a temporary location. During
this move, it removes the sign and fills out any P character positions
with zero digits.
It then uses the temporary value (which may be
shorter than the original if a separate sign were removed, or longer
if P character positions were filled in with zeroes) as the sending
field as if it had been described as PIC X(),
that is, as if its
category were alphanumeric.
If the sending item is an unsigned numeric class field with no P
characters in its picture-string, the software does not move the item
to a temporary location.
A numeric integer data item sending
justification of the receiving field.
shorter than the receiving field, the
field with spaces.

field has no effect on the
If the numeric sending field is
software fills the receiving

In legal, non-numeric elementary moves, the receIVIng field actually
controls the movement of data. All of the following items, in the
receiving field, affect the move:
(1) the size, (2) the presence of
editing characters in its description, and (3) the presence of the
JUSTIFIED RIGHT clause in its description. The JUSTIFIED clause and
editing characters are mutually exclusive;
therefore, the two classes
are discussed separately below.
When a field that contains no editing characters or JUSTIFIED clause
in its description is used as the receiving field of a non-numeric
elementary MOVE statement, the statement moves the characters by
starting at the left-hand end of the fields and scanning across,
character-by-character to the right.
If the sending item is shorter
3-9

NON-NUMERIC CHARACTER HANDLING
than the receiving item, the software fills the remaining character
positions with spaces.

3.6.2.1 Edited Moves - Alphabetic or alphanumeric fields may contain
editing
characters.
Consider
the following insertion editing
characters. Alphabetic fields will accept only the B character;
however, alphanumeric fields will accept all three characters.
B

blank insertion position

zero insertion position

slash insertiol1 position.

When a field that contains an insertion editing character in its
picture-str ing is; used as the receiving field of a non-numer ic
elementary MOVE statement, each receiving character position that
corresponds to an editing character receives the insertion byte value.
Figura 3-7 illustrates the use of such symbols with the statement,
MOVE FIELDI TO FIELD2.
(Assume that FIELDI was described as PIC
X(7).)
FIELD2
FIELDI

PICTURE-STRING

070476

XX/99/XX

07/04/76

04JUL76

99BAAAB99

04 JUL 76

2351212

XXXBXXXX/XX/

235 1212/

123456

OXBOXBOXBOX

01 02 03 04

CONTENTS AFTER MOVE

Figure 3-7
Data Movement with Editing Symbols
Data movement always begins at the left end of the sending field,
and
moves only to the byte positions described as A, 9, or X in the
receiving field picture-string. When the sending field is exhausted,
the software supplies space characters to fill any remaining character
positions (not insertion positions) in the receiving field.
If the
receiving field becomes exhausted before the last character is moved
from the sending field, the software ignores the remaining sending
field characters.

3.6.2.2 Justified Moves - A JUSTIFIED RIGHT clause in the data
description of the receiving field causes the software to reverse its
usual data movement conventions.
(It starts with the right-hand
characters of both fields and proceeds from right to left.) If the
sending field is shorter than the receiving field, the software fills
the remaining left-hand character positions with spaces. Figure 3-8
illustrates various data description situations for the statement,
MOVE FIELDI TO FIELD2, with no editing.

3-10

NON-NUMERIC CHARACTER HANDLING
FIELD2

FIELDI
PICTURE-STRING

CONTENTS

XXX

PICTURE-STRING
(AND JUST CLAUSE)

ABC

CONTENTS AFTER
MOVE

XXXXX

ABC

XX JUST

XXXXX JUST

ABC

Figure 3-8
Data Movement with No Editing

3.6.3

Mu1tiple Receiving Fields

If a MOVE statement is written with more than one receiving field,
it
moves the same sending field value to each of the receiving fields.
It has essentially the same effect as a series of separate MOVE
statements that all have the same sending field.
(For information on
subscripted fields, see section 3.6.4.)
The receiving fields need have no relationship to each other.
The
software checks the legality of each one independently, and performs
an independent move operation on each one.
Multiple receiving fields on MOVE statements provide a convenient way
to
set many fields equal to the same value,
such as during
initialization code at the beginning of a section of processing.
For
example:
MOVE SPACES TO LIST-LINE, EXCEPTION-LINE, NAME-FLO.
MOVE ZEROES TO EOL-FLAG, EXCEPT-FLAG, NAME-FLAG.
MOVE 1 TO COUNT-I, CHAR-PTR, CURSOR.

3.6.4

Subscripted Moves

Any field of a MOVE statement may be subscripted and the referenced
field may also be used to subscript another name in the same
statement.
When more than one receiving field
is named in the same MOVE
statement,
the order
in which the software evaluates the subscripts
affects the results of the move.
Consider the following
two
situations:
Situation 1

MOVE FIELDl(FIELD2} TO FIELD2 FIELD3.

Situation 2

MOVE FIELDI TO FIELD2 FIELD3(FIELD2}.
Figure 3-9
Subscripted MOVE Statements

3-11

NON-NUMERIC CHARACTER HANDLING
In situation 1, the software evaluates FIELDl(FIELD2)
only once,
before it moves any data to the receiving fields.
In effect it is as
if the statement were replaced with the following statements:
MOVE FIELDl(FIELD2) TO TEMP.
MOVE TEMP TO FIELD2.
MOVE TEMP TO FIELD3.
In situation 2, the software evaluates FIELD3(FIELD2)
immediately
before moving the data into it (but after moving the data from FIELDI
to FIELD2). Thus, it uses the newly stored value of FIELD2 as the
subscript value.
In effect, it is as if the statement were replaced
with the following statements:
MOVE FIELDI TO FIELD2.
MOVE FIELDl TO FIELD3(FIELD2).

3.6.5

Common Errors, MOVE Statement

A most important thing to remember when writing MOVE statements is
that the compiler considers any MOVE statement that contains a group
item to be a group move.
It is easy to forget this fact when moving a
group item to an elementary item, and the elementary item contains
editing characters, or a numeric integer.
These attributes of the
receiving field
(which would determine the action of an elementary
move) have no effect on the action of a group move.

3.6.6

Format 2 - MOVE CORRESPONDING

Format 2 of the MOVE statement allows the programmer to move multiple
elementary items from, one group item to another, by using a single
MOVE statement. When the corresponding phrase is used,
selected
elementary items in the sending field are moved to those elementary
items in the receiving field whose data-names are identical.
For
example:
01 A-GROUP

01 B-GROUP
02 FIELD2

02 FIELDl
03 A PIC x

03 A PIC x

03 B PIC 9

03 C PIC xx

03 E PIC xxx

03 0 PIC 99
03 E PIC xxx
MOVE CORRESPONDING A-GROUP TO B-GROUP
OR
MOVE CORRESPONDING FIELDI TO FIELD2

3-12

NON-NUMERIC CHARACTER HANDLING
The above examples are equivalent to
statements:

the

following

series

MOVE

MOVE A OF FIELDI TO A OF FIELD2
MOVE C OF FIELDI TO C OF FIELD 2
MOVE E OF FIELDI TO E OF FIELD2

3.7

THE STRING STATEMENT

The STRING statement concatenates the contents of two or more
fields into a single field.

sending

The statement has many forms;
the simplest is equivalent,
in
function,
to a non-numeric MOVE statement. Consider the following
illustration;
if the two fields are the same size, or if the sending
field
(FIELDl)
is larger,
the statement is equivalent to the
statement, MOVE FIELDI TO FIELD2.
STRINGI FIELDI DELIMITED BY SIZE INTO FIELD2.
Figure 3-10
Sample STRING Statement
If the sending field is shorter than the rece1v1ng field, an important
difference between the STRING and MOVE statements emerges:
the
software does not fill the receiving field with spaces.
Thus,
the
STRING statement may leave some portion of the receiving field
unchanged.
Additionally, the receiving field must be an elementary alphanumeric
field
with
no JUSTIFIED clause or editing characters in its
description. Thus, the data movement of the STRING statement always
fills
the
receiving field from left-to-right with no editing
insertions.

3.7.1

Multiple Sending Fields

An important characteristic of the STRING statement is its ability to
concatenate a series of sending fields into one receiving field.
Consider the following example of the STRING statement:
STRING FIELDIA FIELDIB FIELDIC DELIMITED BY SIZE
INTO FIELD2.
Figure 3-11
Concatenation with the STRING Statement
In this sample STRING statement, FIELDlA, FIELDlB, and FIELDIC are all
sending fields.
The software moves them to the receiving field
(FIELD2) in the order in which they appear in the statement, from left
to right, resulting in the concatenation of their values.

3-13

NON-NUMERIC CHARACTER HANDLING
If FIELD2 is not large enough to hold all three items,
the operation
stops when it is full.
If this occurs while moving one of the sending
fields, the software ignores the remaining characters of that field
and any other sending fields not yet processed. For example, if
FIELD2 became full while receiving FIELDlB, the software would ignore
the rest of FIELDIB and all of FIELDIC.
If the sending fields do not fill the receiving field,
the operation
stops with the movement of the last character of the last sending item
(FIELDIC in Figure 3-11). The software does not alter the conte~ts
nor space-fill the remaining character positions of the receiving
field.
The sending fields may be non-numeric literals and
figurative
constants
(except for ALL literal).
For example, the following
statement sets up an address label with the literal period and space
between the STATE and ZIP fields:
STRING CITY SPACE STATE".

"ZIP

DELIMITED BY SIZE INTO ADDRESS-LINE.
Figure 3-12
Literals as Sending Fields
Sending fields may also be subscripted.
For
statement uses subscripts to concatenate
(A-TABLE) into a single field (A-FOUR).
(I,
subscript or an index-name.)

example,
the following
the elements of a table
of course, must be a

STRING A-TABLE(I) A-TABLE (1+1) A-TABLE (1+2) A-TABLE (1+3)
DELIMITED BY SIZE INTO A-FOUR.
Figure 3-13
Indexed Sending Fields

3.7.2

The POINTER Phrase

Although the STRING statement normally starts at the left-hand end of
the receiving field, with the POINTER phrase it is possible to start
it scanning at another point within the field.
(The scanning,
however, remains left-to-right.)
MOVE 5 TO P.
STRING FIELDIA FIELDIB DELIMITED BY SIZE
INTO FIELD2 WITH POINTER P.
Figure 3-14
Sample POINTER Phrase
When the POINTER phrase is used,
the value of P determines the
starting character position in the receiving field.
In Figure 3-14,
the 5 in P causes the software to move the first character of FIELDIA
into character position 5 of FIELD2 (the left-most character position
of the receiving field is character position 1) and leave positions 1
through 4 unchanged.

3-14

NON-NUMERIC CHARACTER HANDLING
When the STRING operation is complete, the software leaves P pointing
to one character position beyond the last character replaced in the
receiving field.
If FIELD1A and FIELD1B in Figure 3-14 are both four
characters long, P will contain a value of 13 (5+4+4) when the
operation is complete (assuming that FIELD2 is at least 12 characters
long) •

3.7.3

The DELIMITED BY Phrase

Although the sending fields of the STRING statement are fixed in size
at compile time,
they frequently contain variable-length items that
are padded with spaces. For example, a 20-character city field may
contain only the word MAYNARD and 13 spaces. A valuable feature of
the STRING statement is that it may be used to move only the useful
data from the left-hand end of the sending field.
The DELIMITED BY
phrase, written with a data-name or literal, instead of the word SIZE,
performs this operation.
(The delimiter may be a literal, a data
item, a figurative constant, or the word SIZE.
It may not be ALL
literal since ALL literal has an indefinite length. When the phrase
contains the word SIZE, the software moves each sending field,
in
total, until it either exhausts the sending field, or fills the
receiving field.)
Consider the following example:
STRING CITY SPACE STATE"
"ZIP
DELIMITED BY SIZE INTO ADDRESS-LINE.
Figure 3-15
Delimiting with the Word SIZE
If CITY is a 20-character field, the result of the
shown in Figure 3-15 might look like the following:
AYER ______~------__ MA.

STRING

operation

01432

'\~_____ 16 spaces

A far more attractive printout can be produced by
operation produce the following:
AYER, MA.

having

the

STRING

01432

To accomplish this, use the figurative constant SPACE as
on the sending field;
thus,
MOVE 1 TO P.
STRING CITY DELIMITED BY SPACE
INTO ADDRESS-LINE WITH POINTER P.
STRING ", " STATE ". " ZIP
DELIMITED BY SIZE
INTO ADDRESS-LINE WITH POINTER P.
Figure 3-16
SPACE as a Delimiter

3-15

delimiter

NON-NUMERIC CHARACTER HANDLING
This sample coding uses the pointer's characteristic of pointing to
one character position beyond the last character replaced in the
receiving field to enable the second STRING statement to begin at a
position one character past where the first STRING statement stopped.
(The first STRING statement moves data characters until it encounters
a space ~haracter
a match of the delimiter SPACE. The second
STRING statement adds the literal,
the 2-character STATE field,
another literal, and the 5-character ZIP field.)
The delimiter can be varied for each field within a single STRING
statement by repeating the DELIMITED BY phrase after the sending field
names to which it applies. Thus, the following shorter statement has
the same effect as the preceding example.
(Placing the operands on
separate source lines, as shown in this example, has no effect on the
operation of the statement, but improves program readability and
simplifies debugging.)
STRING CITY DELIMITED BY SPACE
", " STATE ". "
ZIP DELIMITED BY SIZE
INTO ADDRESS-LINE.
Figure 3-17
Repeating the DELIMITED BY Phrase
The sample STRING statement in Figure 3-17 cannot handle 2-word city
names,
such as New York, since the software would consider the space
between the two words as a match for the delimiter SPACE.
A longer
delimiter, such as two or three spaces (non-numeric literal), can
solve this problem. Only when a sequence of characters matches the
delimiter will the movement stop for that data item. With a 2-byte
delimiter, the same statement can be rewritten in a simpler form:
STRING CITY", " STATE ". " ZIP
DELIMITED BY" "INTO ADDRESS-LINE.
Figure 3-18
Delimiting with More Than One Space Character
Since only the CITY field may contain two consecutive spaces
(the
entire STATE field is only two bytes long), the delimiter's search of
the other fields will always be unsuccessful and the effect is the
same as moving the full field (delimiting by SIZE).
Data movement under control of a data-name or literal is
slower in execution speed than movement delimited by SIZE.

generally

The example in Figure 3-18 illustrates a frequent source of error in
the use of STRING statements to concatenate fields. The remainder of
the receiving field is not space-filled as with a MOVE statement.
If
ADDRESS-LINE is to be printed on a mailing label, for example, the
STRING statement should be preceded by the statement, MOVE SPACES TO
ADDRESS-LINE.
This guarantees a space fill to the right of the
concatenated result. Alternatively, the last field concatenated by
the STRING statement can be a field previously set to SPACES.
(This
sending field must be moved under control of a delimiter other than
SPACE, of course.)

3-16

NON-NUMERIC CHARACTER HANDLING
3.7.4

The OVERFLOW Phrase

When the SIZE option of the DELIMITED BY phrase controls the STRING
operation and the pointer value is either known or the POINTER phrase
is not used, the programmer can tell,
by simple addition, if the
receiving field is large enough to hold the sending fields.
However,
if the DELIMITED BY phrase contains a literal or an identifier, or
if
the pointer value is not predictable, it may be difficult to tell
whether the size of the receiving field is adequate, and an overflow
may occur.
Overflow occurs when the receiving field is full and the software is
either about to move a character from a sending field or is
considering a new sending field.
Overflow may also occur
if, during
the initialization of the statement, the pointer contains a value that
is either less than 1 or greater than the length of the receiving
field.
In this case,
the software moves no data to the receiving
field and terminates the operation immediately.
The ON OVERFLOW phrase at the end of the STRING statement tests for an
overflow condition:
STRING FIELDIA FIELDIB DELIMITED BY "C"
INTO FIELD2 WITH POINTER PNTR
ON OVERFLOW GO TO PN57.
Figure 3-19
The ON OVERFLOW Phrase
The ON OVERFLOW phrase cannot distinguish the overflow caused by a bad
initial value in pointer PNTR from the overflow caused by a receiving
field that is too short. Only a separate test, preceding the STRING
statement, can distinguish between the two.
The following examples illustrate the overflow condition:
DATA DIVISION.
01 FIELDIA PIC XXX VALUE "ABC".
01 FIELD2 PIC XXXX.
PROCEDURE DIVISION.
1.
2.
3.
4.
5.
6.

STRING FIELDIA QUOTE DELIMITED BY SIZE INTO FIELD2.
STRING FIELDIA FIELDIA DELIMITED BY SIZE INTO FIELD2.
STRING FIELDIA FIELDIA DELIMITED BY "C" INTO FIELD2.
STRING FIELDIA FIELDIA FIELDIA FIELDlA
DELIMITED BY "B" INTO FIELD2.
STRING FIELDIA FIELDIA "C" DELIMITED BY "C"
INTO FIELD2.
MOVE 2 TO P.
STRING FIELDIA "AC" DELIMITED BY "e"
INTO FIEL02 WITH POINTER P.
Figure 3-20
Various STRING Statements
Illustrating the Overflow Condition

3-17

NON-NUMERIC CHARACTER HANDLING
The results of executing the numbered statements follow:
Table 3-2
Results of the
Preceding Sample Statements
Value of FIELD2 after
the STRING operation

3.7.5

Overflow?

ABC"

ABCA

YES

ABAB

AAAA

ABAB

YES

AABA

Subscripted Fields in STRING Statements

All data-names used in the STRING statement may
the pointer value may be used as a subscript.

subscripted,

and

Since the pointer value might be used as a subscript on one or more of
the fields
in the statement, it is important to understand the order
in which the software evaluates the subscripts and exactly when it
updates the pointer.
(The use of the pointer as a subscript is not
specified by ANS-74 COBOL.
Before using it, read the note at the end
of this subsection.)
The software updates the pointer after it moves the last character out
of each sending field.
Consider the following sample coding:
MOVE 1 TO P.
STRING "ABC"
SPACE
"DEF" DELIMITED BY SIZE
INTO R WITH POINTER P.
Figure 3-21
STRING Statement with Pointer
During the movement of "ABC" into the receiving field (R), the pointer
value remains at 1.
After the move,
the software increases the
pointer value by 3 (the size of the sending field literal "ABC")
and
it takes on the value 4.
The software then moves the figurative
constant SPACE and increases the pointer value by 1 and it takes on
the value 5.
"DEF" is then moved and, on completion of the move, the
software increases the pointer to its final value for this operation,
8.

3-18

NON-NUMERIC CHARACTER HANDLING
Now, consider the updating characteristics of the pointer when applied
to subscripting:
MOVE 1 TO P.
STRING CHAR{P)
CHAR{P)
CHAR{P)
CHAR{P) DELIMITED BY SIZE
INTO R WITH POINTER P.
Figure 3-22
Subscripting with the Pointer
If CHAR is a I-character field in a table, the pointer increases by
one after each field has been moved and the software will move them
into R as if they had been subscrjpted as CHAR{l), CHAR(2), CHAR(3),
and CHAR(4).
If CHAR is a 2-character field, the pointer increases by
two after each field has been moved and the fields will move into R as
if they had been subscripted as CHAR{l), CHAR(3), CHAR(5), and
CHAR(7) .
Thus, the software evaluates the subscript of a sending item
immediately before it considers the item as a sending item.

once,

The software evaluates the subscript of a receiving item only once, at
the start of the STRING operation. Therefore, if the pointer is used
as a subscript on the receiving field,
changes occurring to the
pointer during the execution of the STRING statement will not alter
the choice of which receiving string is altered.
Even the delimiter field can be subscripted, and it too can be
subscripted with the pointer. The software re-evaluates the delimiter
subscript once for each sending field, immediately before it compares
the delimiter to the field. Thus, by subscripting it with the pointer
value, the delimiter can be changed for each sending field. This has
the peculiar effect of choosing the next sending field's delimiter
based on the position, in the receiving field, into which its first
character will fall.
For example, consider the following sample
coding:
01 DTABLE.
03 D PIC X

)

MOVE 1
STRING

7 TIMES.

TO
"ABC"
"ABC"
"ABC" DELIMITED BY D{P)
INTO R WITH POINTER P.
Figure 3-23
Subscripting the Delimiter

3-19

NON-NUMERIC CHARACTER HANDLING
The following table shows the value that will arrive in the receiving
field
(R) from the three "ABC" literals if DTABLE contains the values
shown in the left-hand column:
Table 3-3
Results of the
Preceding Sample Statements
DTABLE Value

R Value

ABCDEFG

(Unchanged)

BCDEFGH

AABABC

CDEFGHI

ABABCABC

CCCCCCCC

ABABAB
NOTE

The rules in this section,
concerning
subscripts
in the STRING statement, are
rules that are not specified by 1974
American
National
Standard
COBOL.
Dependence on these rules,
particularly
those involving the use of the pointer
field as a subscript,
may
produce
programs that will not perform the same
way on other COBOL compilers.
If the pointer field is not used as a
subscript on any of the fields in the
statement,
the point at
which
the
software evaluates the subscripts
is
immaterial to the execution of
the
statement. Thus, by avoiding the use of
the pointer as a subscript,
uniform
results can be expected from all COBOL
compilers that adhere to 1974 ANS COBOL.

3.7.6

Common Errors, STRING Statement

The most common errors made when writing STRING statements are:
•

using the word "TO" instead of "INTO"

•

forgetting to write "DELIMITED BY SIZE":

•

forgetting to initialize the pointer;

•

initializing the pointer to 0 instead of 1;

•

forgetting to provide for space fill of the
when it is desirable.

3-20

receiving

field

NON-NUMERIC CHARACTER HANDLING
3.8

THE UNSTRING STATEMENT

The UNSTRING statement disperses the contents
field into multiple receiving fields.

single

sending

The statement has many forms:
the simplest is equivalent in function
to a non-numeric MOVE statement. Consider the following illustration:
the sample statement is equivalent to MOVE FIELDI TO
FIELD2,
regardless of the relative sizes of the two fields.
UNSTRING FIELDl INTO FIELD2.
Figure 3-24
Sample UNSTRING Statement
The sending field
(FIELDl)
may be either a group item or an
alphanumeric, or alphanumeric edited elementary item. The receiving
field (FIELD2) may be alphabetic, alphanumeric, or numeric,
but it
cannot specify any type of editing.
If the receiving field is numeric, it must be DISPLAY usage.
The
picture-string of a numeric receiving field may contain any of the
legal numeric description characters except for P and, of course,
the
editing characters. The UNSTRING statement moves the sending field to
numeric receiving fields as if the sending field had been described as
an unsigned integer:
further,
it automatically truncates or zero
fills as required.
If the receiving field is not numeric, the ~oftware follows the rules
for elementary non-numeric MOVE statements.
It left-justifies the
data in the receiving field, truncating or space-filling as required.
(If the data-description of the receiving field contains a JUSTIFIED
clause,
the software right-justifies the
data,
truncating
or
space-filling to the left as required.)

3.8.1

Multiple Receiving Fields

An important characteristic of the UNSTRING statement is its ability
to disperse one sending field into several receiving fields.
Consider
the following example of the UNSTRING statement written with multiple
receiving fields:
UNSTRING FIELDl INTO
FIELD2A FIELD2B FIELD2C.
Figure 3-25
Multiple Receiving Fields
In "this sample statement, FIELDl is the sending field.
The software
performs the UNSTRING operation by scanning across FIELDI from left to
right. When the number of characters scanned is equal to the number
of characters in the receiving field, the software moves the scanned
characters into the receiving field and begins scanning the next group
of characters for the next receiving field.

3-21

NON-NUMERIC CHARACTER HANDLING
Assume that each of the receiving fields in the preceding illustration
(FIELD2A, FIELD2B, and FIELD2C)
is five characters long, and that
FIELDI is 15. characters long. The size of FIELD2A determines the
number of characters for the first move. The software scans across
FIELDI until the number of characters scanned equals the size of
FIELD2A (5).
It then moves those first five characters to FIELD2A,
and sets the scanner to the next (sixth) character position in FIELDI.
The size of FIELD2B determines the size of the next move. The
software begins this move by scanning across FIELDI from character
position six, until the number of scanned characters equals the size
of FIELD2B (5). It then moves the sixth through the tenth characters
to FIELD2B, and sets the scanner to the next (eleventh) character
position in FIELDI. FIELD2C determines the size of the last move (for
this example)
and causes characters 11 through 15 of FIELDI to be
moved into FIELD2C, thus terminating this UNSTRING operation.
Each data moveme~t acts as an individual MOVE statement,
the sending
field of which is an alphanumeric field equal in size to the receiving
field.
If the receiving field is numeric, the move operation will
convert the data to the numeric form.
For example, consider what
would happen if the fields under discussion had the data descriptions
and were manipulating the values shown in the following. table:
Table 3-4
Values Moved Into the Receiving Fields
Based on the Value in the Sending Field
FIELDI
PIC X (15) .
VALUE IS:

FIELD2A
PIC X(5)

FIELD2B
PIC S9(5)
LEADING SEPARATE

ABCDE1234512345

ABCDE

+12345

3450

XXXXXOOOOIOO123

XXXXX

+00001

1230

FIELD2A is an alphanumeric field and, therefore, the
conducts
an
elementary
non-numeric move with
characters.

FIELD2C
PIC S999V99

software simply
the first five

FIELD2B, however, has a leading separate sign that is not included in
its size.
Thus, the software moves only five numeric characters and
generates a positive sign in the separate sign position.
FIELD2C has an implied decimal point with two character positions to
the right of it, plus an overpunched sign on the low-order digit. The
sending field should supply five numeric digits;
but,
since the
sending field is alphanumeric, the software treats it as an unsigned
integer;
it truncates the two high-order digits and supplies two zero
digits for the decimal positions. Further, it supplies a positive
overpunch sign, making the low-order digit a +0
(or the ASCII
character, {).
(There is no simple way to have UNSTRING recognize a
sign character or a decimal point in the sending field.)
If the sending field is shorter than the sum of the sizes of the
receiving fields, the software ignores the remaining receiving fields.
If it reaches the end of the sending field before it reaches the end
of one of the recelvlng fields,
the software moves the scanned
characters into that receiving field.
It left-justifies and fills the
remalnlng character positions with spaces for alphanumeric data, or
decimal point aligns and zero fills the remaining character positions
3-22

NON-NUMERIC CHARACTER HANDLING
for numeric data. Consider the following examples of a sending field
that is too short.
(The statement is UNSTRING FIELDI INTO FIELD2A
FIELD2B.
FIELD2A is a 3-character alphanumeric field, and receives
the first three characters of FIELDI
(ABC)
in every operation.
FIELD2B, however,
runs out of characters every time before filling.
Since FIELD2A always contains the characters ABC, it is not shown.)
Table 3-5
Handling a Sending Field that is Too Short
FIELDI
PIC X(6}
VALUE IS:

FIELD2B
PICTURE IS:

ABCDEF

XXXXX
S99999
S9V999
S9999
LEADING SEPARATE

ABC246

3.8.2

FIELD2B
Value after UNSTRING Operation

DEF
0024F
600
+0246

The DELIMITED BY Phrase

The size of the data to be moved can be controlled by a delimiter,
rather than by the size of the receiving field.
The DELIMITED BY
phrase supplies the delimiter characters.
UNSTRING delimiters are quite flexible;
they can be literals,
figurative
constants
(including
ALL
literal), or identifiers
{identifiers may even be subscripted data-names}.
This sub-section
discusses the use of these three types of delimiters. Subsequent
sections cover multiple delimiters,
the COUNT phrase, and
the
DELIMITER phrase. Subscripting delimiters is discussed at the end of
this section under Subscripted Fields in UNSTRING Statements.
Consider the following sample UNSTRING statement;
figurative constant, SPACE, as a delimiter:

uses

the

UNSTRING FIELDI DELIMITED BY SPACE INTO FIELD2.
Figure 3-26
Delimiting with a Space Character
In this example,
the software scans the sending field
{FIELDI},
searching for a space character.
If it encounters a space, it moves
all of the scanned {non-space} chdracters that precede that space to
the receiving field
(FIELD2).
If it finds no space character, it
moves the entire sending field.
When it has determined the size of
the sending field,
the software moves the contents of that field
following the rules for the MOVE Statement, truncating or zero filling
as required.
The following table shows the results of an UNSTRING operation that
delimits with a literal asterisk (UNSTRING FIELDI DELIMITED BY "*"
INTO FIELD2).

3-23

NON-NUMERIC CHARACTER HANDLING
Table 3-6
Results of Delimiting with an Asterisk
FIELDI
PIC X(6)
VALUE IS:

FIELD2
PICTURE IS:

FIELD2
VALUE AFTER
UNSTRING

XXX

ABC

X (7)

ABCDEF

XXX JUSTIFIED

DEF

******

XXX

tJ.tJ.tJ.

*ABCDE
A*****

XXX
XXX JUSTIFIED

tJ.tJ.tJ.

246***

S9999

024F

12345*

S9999 SEPARATE
TRAILING

2345+

2468**

S999V9 SEPARATE
LEADING

+4680

*246**

9999

0000

ABCDEF

tJ.tJ.A

If the delimiter matches the first character in the sending field, the
software considers the size of the sending field to be zero. The
movement operation still takes place, however, and fills the receiving
field with spaces or zeroes depending on its class.
A delimiter may also be applied to
multiple receiving fields:

UNSTRING

statement

that

has

UNSTRING FIELDI DELlMITED BY SPACE
INTO FIELD2A FIELD2B.
Figure 3-27
Delimiting with Multiple Receiving Fields
The sample instruction in Figure 3-27 causes the software to scan
FIELDI searching for a character that matches the delimiter.
If it
finds a match, it moves the scanned characters to FIELD2A and sets the
scanner to the next character position to the right of the character
that matched.
It then resumes scanning FIELDl for a character that
matches the delimiter.
If it finds a match, it moves all of the
characters that lie between the character that first matched the
delimiter and the character that matched on the second scan, and sets
the scanner to the next character position to the right of the
character that matched.
(The DELIMITED BY phrase could handle
additional receiving fields in the same manner as it handled FIELD2B.)
The following table shows the results of an UNSTRING operation that
applies a delimiter to multiple receiving fields (UNSTRING FIELDI
DELIMITED BY "*" INTO FIELD2A FIELD2B).

3-24

NON-NUMERIC CHARACTER HANDLING
Table 3-7
Results of Delimiting
Multiple Receiving Fields

I
I

FIELDl
PIC X (8)
VALUE IS:

FIELD2A
PIC X(3)

ABC*DEF*

ABC

DEF

ABCDE*FG

ABC

FGl:.

A*B*****

Al:.l:.

Bl:.l:.

*AB*CO**

l:.l:.l:.

ABl:.

**ABCDEF

l:.l:.l:.

A*BCDEFG

Al:.l:.

BCD

ABC**OEF

ABC

l:.l:.l:.

A******B

Al:.l:.

l:.l:.l:.

VALUES AFTER UNSTRING OPERATION
FIELD2B
PIC X(3)

The last two examples illustrate the limitations of a single character
delimiter.
Accordingly, the delimiter may be longer than one
character and it may be preceded by the word ALL.
The following table shows the results of an UNSTRING operation that
uses a 2-character delimiter (UNSTRING FIELDl DELIMITED BY "**" INTO
FIELD2A FIELD2B):
Table 3-8
Results of Delimiting
with Two Asterisks
FIELDl
PIC X(8)
VALUE IS:

VALUES AFTER UNSTRING OPERATION
FIELD2A
FIELD2B
PIC XXX
PIC XXX
JUSTIFIED

ABC**OEF

ABC

DEF

A*B*C*D*

A*B

l:.l:.l:.

AB***C*D

ABl:.

C*D

AB**C*D*

ABl:.

*0*

AB**CD**

ABl:.

l:.CD

AB***CD*

ABl:.

CD*

AB*****CD

ABl:.

l:.l:.l:.

3-25

NON-NUMERIC CHARACTER HANDLING
Unlike the STRING statement, the UNSTRING statement accepts the ALL
literal as a delimiter. When the word ALL precedes the delimiter, the
action of the UNSTRING statement remains essentially the same as with
one delimiter until the scanning operation finds a match. At this
point, the software scans farther, looking for additional consecutive
strings of characters that also match the delimiter item.
It
considers the "ALL delimiter" to be one, two, three, or more adjacent
repetitions of the delimiter item.
The following table illustrates the results of an UNSTRING operation
that uses an ALL delimiter (UNSTRING FIELDI DELIMITED BY ALL "*" INTO
FIELD2A FIELD2B).
Table 3-9
Results of Delimiting
with ALL Asterisks
FIELDl
PIC X(8)
VALUE IS:

VALUES AFTER UNSTRING OPERATION
FIELD2A
FIELD2B
PIC XXX
PIC XXX
JUSTIFIED

ABC*DEF*

ABC

DEF

ABC**DEF

ABC

DEF

A******F

A6.6.

f).tJ.F

A*F*****

Af).6.

f).tJ.F

A*CDEFG

A6.6.

EFG

The next table illustrates the results of an UNSTRING operation that
combines ALL with a 2-character delimiter (UNSTRING FIELDI DELIMITED
BY ALL "**" INTO FIELD2A FIELD2B).
Table 3-10
Results of Delimiting with
ALL Double Asterisks
FIELDI
PIC X(8)
VALUE IS:

VALUES AFTER UNSTRING OPERATION
PIC XXX
PIC XXX
JUSTIFIED

ABC**DEF

ABC

DEF

AB**DE**

ABtJ.

bDE

A***D***

AbtJ.

f).*D

A*******

Af).6.

btJ. *

3-26

NON-NUMERIC CHARACTER HANDLING
In addition to unchangeable delimiters, such as
literals
and
figurative constants, delimiters may be designated by identifiers.
Identifiers (which may even be subscripted data-names) permit variable
delimiting. Consider the following sample statement:
UNSTRING FIELDI DELIMITED BY DELI
INTO FIELD2A FIELD2B.
Figure 3-28
Delimiting with an Identifier
The data-name, DELI, must be alphanumeric.
It may be a group or
elementary item, and it may be edited.
(Since the delimiter is not a
receiving field, any editing characters will not effect its use, other
than contributing to the size of the item.)
If the delimiter contains a subscript, the subscript may be varied as
a side effect of the UNSTRING operation. The evaluation of subscripts
is discussed later in this section.

3.8.2.1 Multiple Delimiters - The UNSTRING statement has the ability
to scan a sending field,
searching for
a match from a list of
delimiters. This list may contain ALL delimiters and delimiters of
various sizes.
The only requirement of the list is that delimiters
must be connected by the word OR.
The following sample statement separates a sending field into three
receiving fields.
The sending field consists of three strings
separated by the following:
(1) any number of spaces, or (2) a comma
followed by a single space, or
(3)
a single comma, or (4) a tab
character, or (5) a carriage return character.
(The"
"must precede
the "," in the list if it is ever to be recognized.)
UNSTRING FIELDI DELIMITED BY
ALL SPACE OR
", " OR
"," OR
TAB OR
CR
INTO FIELD2A FIELD2B FIELD2C.
Figure 3-29
Multiple Delimiters
The following table illustrates the potential of this statement.
The
tab
(represented by the letter t) and carriage return (represented by
the letter r) characters represent single character fields containing
the ASCII horizontal tab and carriage return characters.

3-27

NON-NUMERIC CHARACTER HANDLING
Table 3-11
Results of the Multiple Delimiters
Shown in Figure 3-29
FIELDl
PIC X(12)

FIELD2A
PIC XXX

FIELD2B
PIC 9999

FIELD2C
PIC XXX

A, a ,C r

Al:::.15.

0000

CI5.l:::.

At456,I5.E

Al:::.15.

0456

El:::.l:::.

Al:::.l:::.l:::.

Al:::.l:::.

0003

9l:::.l:::.

AttBr

Al:::.15.

0000

Bl:::.l:::.

A, ,C

Al:::.15.

0000

Cl:::.l:::.

ABCD,l:::.432l,Z

ABC

4321

Zl:::.15.

3l:::.l:::.l:::.9

t--tab character, r--carriage return character

3.8.3

The COUNT Phrase

The COUNT phrase keeps track of the size of the
stores the length in a user-supplied data area.

sending

string

and

The length of a delimited sending field may vary widely (from zero to
the full length of the field) and some programs may require knowledge
of this length. For example, if it exceeds the size of the receiving
field
(which is fixed in size) some data may be truncated and the
program's logic may require this information.
To use the phrase, simply follow the receiving field name with the
words COUNT IN and an identifier.
Consider the following sample
statement:
UNSTRING FIELDl DELIMITED BY ALL "*"
INTO FIELD2A COUNT IN COUNT2A
FIELD2B COUNT IN COUNT2B
FIELD2C.
Figure 3-30
The COUNT Phrase
In this sample statement, the software will count the number of
characters between the left-hand end of FIELDl and the first asterisk
in FIELDl and place that value into COUNT2A; thus, COUNT2A contains
the size of the first sending string. The software does not include
the delimiter in the count (as it is not a part of the string).
The software then counts the number of characters
sending field and places that value into COUNT2B.

the

second

The phrase should be used only where needed;
in this example the
length of the string moved to FIELD2C is not needed, so no COUNT
phrase follows it.

3-28

NON-NUMERIC CHARACTER HANDLING
If the receIvIng field is shorter than the value placed in the count
field,
the software truncates the sending string.
(If the number of
integer positions in a numeric field is smaller than the value placed
into the count field, high-order numeric digits have been lost.)
If the software finds a delimiter match on the
examines, it places a zero in the count field.

first

character

The count field must be described as a numeric integer, either COMP or
DISPLAY usage, with no editing symbols nor the character P in its
picture-string. The software moves the count value into the count
field according to the rules for an elementary numeric MOVE statement
The COUNT phrase may be used only in conjunction with the DELIMITED BY
phrase.

3.8.4

The DELIMITER Phrase

The DELIMITER phrase causes the actual character or characters that
delimited the sending field to be stored in a user-supplied data area.
This phrase is most useful when:
(1)
the statement contains a
delimiter list,
(2)
anyone of the items in the list might have
delimited the field, and (3) program logic flow depends on which one
found a match.
In fact, the DELIMITER and COUNT phrases could be used
together and program logic flow could depend on both the size of the
sending string and the delimiter character that terminated it.
To use the DELIMITER phrase, simply follow the receIvIng field name
with the words DELIMITER IN and an identifier.
(The software places
the delimiter character in the area named by the identifier.) Consider
the following sample UNSTRING statement:
UNSTRING FIELDl DELIMITED BY"," OR TAB OR
ALL SPACE OR CR
INTO FIELD2A DELIMITER IN DELIMA
FIELD2B DELIMITER IN DELIMB
FIELD2C.
Figure 3-31
The DELIMITER Phrase
After moving the first sending string to FIELD2A, the software takes
the character (or characters) that delimited that string and places it
in DELIMA. DELIMA, then, contains a comma, or a tab, or a carriage
return, or any number of spaces. Since the delimiter string is moved
under the rules of the elementary non-numeric MOVE statement,
the
software truncates or space fills with left or right justification
(depending on its data description).
The software then moves the second sending
places its delimiting character into DELIMB.

string

FIELD2B

and

When a sending string is delimited by the end of the sending field
(rather than a match on a delimiter) the delimiter string is of zero
length. This causes the DELIMITER item to be space filled.
The
phrase should be used only where needed;
in this example, the
character that delimits the last sending string is not needed,
so no
DELIMITER phrase follows FIELD2C.

3-29

NON-NUMERIC CHARACTER HANDLING
The data item named in the DELIMITER phrase must be described as an
alphanumeric item. It may contain editing characters and it may even
be a group item.
When the DELIMITER and COUNT phrases are used together, they must
appear
in the correct order
(DELIMITER phrase preceding the COUNT
phrase). Both of the data items named in these phrases may be
subscripted or indexed. If they are subscripted, the subscript may be
varied as a side effect of the UNSTRING operation.
(The evaluation of
subscripts is discussed in section 3.8.8.)

3.8.5

The POINTER Phrase

Although the UNSTRING statement normally starts at the left-hand end
of the sending field, the POINTER phrase permits the user to select a
character position in the sending field for the software to begin
scanning.
(The scanning, however, remains left-to-right.)
When a sending field is to be dispersed into multiple rece1v1ng
fields,
it often happens that the choice of delimiters, the size of
subsequent receiving fields, etc. depend on the value in the first
sending string or the character that delimited that string. Thus, the
program may need to move the first field,
hold its place in the
sending field,
and examine the results of the operation to determine
how to handle the sending items that follow. This is done by using an
UNSTRING statement with a POINTER phrase that fills only the first
receiving field.
When the first string has been moved to a receiving
item, the software updates the pointer data item with a new position
(one character beyond the delimiter that caused the interruption)
to
begin the next scanning operation. The program may then examine the
new position, the receiving field, the delimiter value,
the sending
string size, and resume the scanning operation by executing another
UNSTRING statement with the same sending field and pointer data item.
Thus, the UNSTRING statement can move one sending string at a time,
with the form of each move being dependent on the context of the
preceding string of data.
The POINTER phrase must follow the last receiving item in the
statement.
Consider the following two UNSTRING statements with their
accompanying POINTER phrases and tests:
MOVE 1 TO P.
UNSTRING FIELDl DELIMITED BY
":" OR TAB OR CR OR ALL SPACE
INTO FIELD2A
DELIMITER IN DELIMA
COUNT IN LSIZEA
WITH POINTER PNTR.
IF LSIZEA = 0 GO TO NO-LABEL-PROCESS.
IF DELIMA = ":"
IF PNTR > 8 GO TO BIG-LABEL-PROCESS
ELSE GO TO LABEL-PROCESS.
IF DELIMA = TAB GO TO BAD-LABEL PROCESS.

UNSTRING FIELDl DELIMITED BY •••
Figure 3-32
The POINTER Phrase

3-30

WITH POINTER PNTR.

NON-NUMERIC CHARACTER HANDLING
PNTR contains the current position of the scanner in the sending
field.
The second UNSTRING statement uses PNTR to begin scanning the
additional sending strings in FIELDI.
Since the software considers the left-most character to be character
position one,
the value returned by PNTR may be used to examine the
next character. To do this, simply use PNTR as a subscript on the
sending field (providing that the sending field is also described as a
table of characters). For example, consider the following sample
coding:
01 FIELDI.
02 FIELDl-CHAR OCCURS 40 TIMES.

UNSTRING FIELDI
WITH POINTER PNTR.
IF FIELDl-CHAR(PNTR) = "X"
Figure 3-33
Examining the Next Character
By Using the Pointer Data
Item as a Subscript
Another way to examine the next character of the sending field is to
use the UNSTRING statement to move it to a I-character receiving
field. Consider the following sample coding:
UNSTRING FIELDI
WITH POINTER PNTR.
UNSTRING FIELDI INTO CHARI WITH POINTER PNTR.
SUBTRACT 1 FROM PNTR.
IF CHARI = "X" •.•
Figure 3-34
Examining the Next Character
By Placing It Into a I-Character Field
The program must decrement PNTR in order for this case to work like
the one illustrated in Figure 3-33, since the second UNSTRING
statement will increment the pointer value by 1.
The program must initialize the POINTER phrase data item before the
UNSTRING statement uses it. The software will terminate the UNSTRING
operation if the initial value of the pointer is less than one or
greater than the length of the sending field.
(A pointer value that
is less than one or greater than the length of the sending field
causes an overflow condition. Overflow conditions are discussed in
section 3.8.7.)
The POINTER and TALLYING phrases may be used together in the same
UNSTRING statement; but, when both are used, the POINTER phrase must
precede the TALLYING phrase.

3-31

NON-NUMERIC CHARACTER HANDLING
3.8.6

The TALLYING Phrase

The TALLYING phrase counts the number
received data from the sending field.

receiving

fields

that

When an UNSTRING statement contains several receiving fields,
the
possibility exists that there may not always be as many sending
strings as there are receiving fields.
The TALLYING phrase provides a
convenient method for
keeping a count of how many fields were acted
upon.
MOVE 0 TO RCOUNT.
UNSTRING FIELDI DELIMITED BY"," OR ALL SPACE
INTO FIELD2A
FIELD2B
FIELD2C
FIELD2D
FIELD2E
TALLYING IN RCOONT.
Figure 3-35
The TALLYING Phrase
If the software has moved only three sending strings when it reaches
the end of FIELDl,
it adds 3 to RCOUNT. The first three fields
(FIELD2A, FIELD2B, and FIELD2C) contain data from the operation, and
the last two (FIELD2D and FIELD2E) do not.
The TALLYING data item always contains the sum of its initial contents
plus the number of sending strings acted upon by the UNSTRING command
just executed. Thus, the programmer may want to initialize the tally
count before each use.
When used in the same statement with a POINTER phrase,
the TALLYING
phrase must follow the POINTER phrase and both phrases must follow all
of the field names, the DELIMITER and COUNT phrases. The data items
for both phrases must contain numeric integers, that is, be without
editing characters or the letter P in their picture-strings;
both
data items may ~~ either COMP or DISPLAY usage. They may be signed or
unsigned and, if they are DISPLAY usage, they may contain any desired
sign option.
The data items for both phrases may be subscripted or indexed, or they
may be used as subscripts on other fields in the statement.
(The
evaluation of subscripts is discussed in section 3.8.8.) A convenient
use of the TALLYING phrase data item is as a subscript of a receiving
field.
Consider the following sample coding, which causes program
control to execute the UNSTRING statement repeatedly until it exhausts
the sending field.
PARI.

MOVE 1 TO PNTR, TLY.
UNSTRING FIELDI DELIMITED BY " , " OR CR
INTO FIELD2(TLY)
DELIMITER IN DEL2
WITH POINTER PNTR
TALLYING IN TLY.
IF DEL2 = "," GO TO PARI.
Figure 3-36
The POINTER and TALLYING Phrases
Used Together

3-32

NON-NUMERIC CHARACTER HANDLING
This sample coding causes program control to loop through the UNSTRING
statement, using the pointer, PNTR,
to scan across FIELDI with
successive executions. Each comma isolates a sending string until
control reaches either a carriage return character or the end of
FIELDI.
If it reaches the end of the field without encountering a
carriage return character, the software places a space into the
delimiter field, DEL2, and control falls through the IF statement and
out of the loop.
Since the TALLYING data item, TLY, is increased by 1 after each data
movement,
it serves as a subscript on the receiving field.
In effect
this causes the software to unpack the value in FIELDI into an array
of fixed-size fields.
Further, an array of COUNT data items can be
supplied and loaded by the UNSTRING/TALLYING statement by adding the
following phrase to the coding in Figure 3-36:
COUNT IN C(TLY)
Figure 3-37
Subscripting the COUNT Phrase
with the TALLYING Data Item
The TALLYING data item, in the above example, is one greater than the
number of receiving fields acted upon by the UNSTRING operation. This
is because the data item must be initialized to a value of one in
order to be used as a subscript for the first receiving item.

3.8.7

The OVERFLOW Phrase

The OVERFLOW phrase detects the overflow condition and provides an
imperative statement to be executed when it detects the condition. An
overflow condition exists when either of the following two situations
occurs:

The UNSTRING statement is about to be executed and its
pointer data item. contains a value of less than one or
greater than the size of the sending field.
When it detects
this situation, the software executes the OVERFLOW phrase
before it moves any data. Thus, the values of all of the
receiving fields remain unchanged.

The UNSTRING statement has filled all of the rece1v1ng fields
and data still remains in the sending field that has not been
matched as a delimiter or included in a sending string. When
it detects this situation, the software executes the OVERFLOW
phrase after it has executed the UNSTRING statement.
Thus,
the values of all of the receiving fields are updated, but
some data has not been moved.

If the UNSTRING operation causes the scanner to move off the end of
the sending field (thus exhausting it), the software will not execute
the OVERFLOW phrase.
Consider the following set of instructions, which cause program
control to execute the UNSTRING statement repeatedly until it exhausts
the sending field. The TALLYING data item is a subscript indexing the
receiving field.
(Compare this loop with the one in Figure 3-36,
which accomplishes the same thing.)

3-33

NON-NUMERIC CHARACTER HANDLING

PARI.

MOVE 1 TO TLY PNTR.
UNSTRING FIELDI DELIMITED BY " , " OR CR
INTO FIELD2(TLY)
WITH POINTER PNTR
TALLYING IN TLY
ON OVERFLOW GO TO PARI.
Figure 3-38
Using the OVERFLOW Phrase
NOTE
The overflow condition also occurs if
the value of a pointer data item lies
outside the sending field at the start
of execution of the UNSTRING statement.
(The pointer value must not be less than
1, nor greater than the length of the
sending field.) This type of overflow is
not distinguishable from the overflow
condition described at the start of this
section,
except that this condition
causes
the
UNSTRING
statement
to
terminate before any data movement takes
place.
Then,
the
values
of
all
receiving fields remain unchanged.

3.8.8

Subscripted Fields in UNSTRING Statements

Since the flexibility of the UNSTRING statement is enhanced by
subscripting and indexing and particularly by subscripting with other
fields within the statement (such as subscripting the receiving field
with the TALLYING data item as discussed above), it is important to
understand how often and exactly when the software evaluates these
subscripts and indexes. This sub-section discusses the frequency and
times of subscript evaluation.
The software evaluates subscripts and indexes on the follo~ing items
only once, at the initiation of the UNSTRING statement;
thus, any
change in subscript values during the execution of the statement has
no effect on these fields:
1.

Sending field,

POINTER data item,

TALLYING data item.

The software evaluates subscripts and indexes on the following items
immediately before it moves data into the item.
It moves the data to
these items in the order in which they are listed in the statement
(which is the same order as below):
1.

Receiving field,

DELIMITER data item,

COUNT data item.

3-34

NON-NUMERIC CHARACTER HANDLING
The software evaluates any subscripts and indexes on the data-names in
the DELIMITED BY phrase (delimiters) immediately before it scans each
sending string looking for a delimiter match. Thus, it re-evaluates
these data-names once for each receiving field in the statement.
If any of the following items are used as subscripts on any receiving
fields, the programmer must be aware of the point at which these items
are updated:
•

POINTER data-item,

•

TALLYING data-item,

•

COUNT data-item,

•

Another receiving field.

Figure 3-39 illustrates, with a flow chart, the sequence of evaluation
operations:

EVALUATE
ALL
DELIMITER
SUBSCRIPTS

CONTINUE
SCANNING FOR
REPETITIVE
MATCHES

w
w
a:
c..
w

(/)

«
a:

EVALUATE
DELIMITER
RECEIVING
FIELD
SUBSCRIPT

IF
POINTER
PHRASE
PRESENT

STORE
SCANNER IN
POINTER
DATA ITEM

STORE
DELIMITER
STRING IN
RECEIVING
FIELD

IF
TALLYING
PHRASE
PRESENT

ADD 1 TO
TALLYING
DATA ITEM

:r
c..

a:
w

SCAN
SENDING
FIELD FOR
DELIMITER

I-

UPDATE
SCANNER

:::i

':!:

EVALUATE
RECEIVING
FIELD
SUBSCRIPT

EVALUATE
COUNT
FIELD
SUBSCRIPT

I-

(/)

w
a:
c..
w

(/)

«
a:

:r
c..
MOVE SENDING
STRING TO
RECEIVING
FIELD

I-

::>
u
0

STORE COUNT
VALUE IN
COUNT FIELD

':!:

Figure 3-39
Sequence of Subscript Evaluation

3-35

NON-NUMERIC CHARACTER HANDLING
NOTE
The rules in this section concerning the
exact
point
at which the software
evaluates
the
identifiers
in
the
DELIMITED BY phrase and the point at
which it updates
the
POINTER
and
TALLYING data items, are rules that are
specified by 1974 American
National
Standard COBOL, as opposed to the STRING
statement where these
are
not
so
specified.

3.8.9

Common Errors, UNSTRING Statement

The most common errors made when writing UNSTRING statements are:
•

Leaving the OR connector out of a delimiter list;

•

Misspelling
DELIMITER;

DELIMITED

and

•

writing the DELIMITER and COUNT phrases in the wrong
when both are present (DELIMITER must precede COUNT);

order

•

Leaving out the word INTO or writing it as TO;

•

Repeating the word INTO where it is not needed;

interchanging

the

words,

thus:

UNSTRING FIELDI DELIMITED BY SPACE OR TAB
INTO FIELD2A DELIMITER IN DELIMA
INTO FIELD2B DELIMITER IN DELIMB
INTO FIELD2C DELIMITER IN DELIMC.
Figure 3-40
Erroneously Repeating the Word INTO
•

3.9

writing the POINTER and TALLYING phrases in the
(POINTER must precede TALLYING) .

wrong

order

THE INSPECT STATEMENT

The INSPECT statement examines the character positions in a field and
counts or replaces certain characters (or groups of characters) in
that field.
Like the STRING and UNSTRING operations,
INSPECT operations scan
across the field from left to right;
further,
like those two
statements, the INSPECT statement features a phrase which allows it to
begin or terminate the scanning operation with a delimiter match.
(Thus, the operation can begin within the field instead of at the
left-hand end, or it may begin at the left-hand end and terminate
within the field.)
The TALLYING operation (which counts certain characters in the field)
and the REPLACING operation (which replaces certain characters in the
field) are quite versatile and may be applied to all of the characters
in the delimited area of the field being inspected, or they may be
applied only to those characters that match a given character string
3-36

NON-NUMERIC CHARACTER HANDLING
under stated conditions.
Consider the following sample statements,
which both cause a scan of the complete field:
INSPECT FIELDI TALLYING TLY FOR ALL "B".
Figure 3-41
Sample INSPECT ... TALLYING Statement
This statement scans FIELDI looking for the character B.
finds a B, it increments TLY by 1.

Each time it

INSPECT FIELDI REPLACING ALL SPACE BY ZERO.
Figure 3-42
Sample INSPECT ... REPLACING Statement
This statement scans FIELDI looking for space characters.
finds a space character, it replaces it with zero.

Wherever it

One INSPECT statement can contain both a TALLYING phrase and a
REPLACING phrase.
However, when used together, the TALLYING phrase
must precede the REPLACING phrase. An INSPECT statement with both
phrases is equivalent to two separate INSPECT statements and, in fact,
the software compiles such a statement into two distinct INSPECT
statements.
(To simplify debugging,
therefore,
it is best to
initially write the two phrases in separate INSPECT statements.)

3.9.1

The BEFORE/AFTER Phrase

The BEFORE/AFTER phrase acts as a delimiter and
the area of the field being inspected.
The following sample statement would count
precede the percent sign (%) in FIELDI.

(possibly)
only

the

restricts

zeroes

that

INSPECT FIELDI TALLYING TLY
FOR ALL ZEROES BEFORE "%".
Figure 3-43
Sample INSPECT ••. BEFORE Statement
The delimiter (the percent sign in the preceding sample statement) can
be a single character, a string of characters, or any figurative
constant. Further, it can be either an identifier or a literal.
•

If the delimiter is an identifier, it must be an elementary
data
item
of
DISPLAY usage.
It may be alphabetic,
alphanumeric, or numeric, and,
it may contain
editing
characters. The compiler always treats the item as if it had
been described as an alphanumeric string.
(It does this by
implicit redefinition of the item, as described in Section
3.9.2.)

•

If the delimiter is a literal, it must be non-numeric.

3-37

NON-NUMERIC CHARACTER HANDLING
The software repeatedly compares the delimiter characters against an
equal number of characters in the field being inspected. If none of
the characters matches the delimiter, or if insufficient characters
remain in the field for a full comparison (at the right-hand end), the
software considers the comparison to be unequal.
The examples of the INSPECT statement in Figure 3-44, illustrate the
way the delimiter character finds a match in the field being
inspected.
(The portion of the field the statement ignores as a
result of the BEFORE/AFTER phrase delimiters is crossed out with a
slash, and the portion it inspects is underlined.)
INSTRUCTION

FIELDl VALUE

INSPECT FIELDl ..• BEFORE "E".
INSPECT FIELDl ..• AFTER "E".

ABCDty~~t
tlt¢I1~FGHI

INSPECT FIELDl ..• BEFORE "K".
INSPECT FIELDl ... AFTER "K".

iiWi'lrtFtt

INSPECT FIELDl ... BEFORE "AB" .
INSPECT FIELDl ... AFTER "AB".

tltCDEFGHI

ABCDEFGHI

tlt¢l1t'l~Ftt

INSPECT FIELDl ••• BEFORE "HI".
INSPECT FIELDl ••• AFTER "HI".

ABCDEFGFtt

INSPECT FIELDl ..• BEFORE "Ifj,".
INSPECT FIELDl ..• AFTER I fj,

ABCDEFGHI

'II

II •

iti¢I1~VrtIl;Y

tlt¢I1~V~~;Y

The ellipsis represents the position of the TALLYING or REPLACING
phrase.
Figure 3-44
Matching the Delimiter Characters
to the Characters in a Field
The software scans the field for a delimiter match before it scans for
the inspection operation (TALLYING or REPLACING), thus establishing
the limits of the operation before beginning the actual inspection.
The importance of the separate scan is discussed further in Section
3.9.3.

3.9.2

Implicit Redefinition

The software requires that certain fields referred to by the INSPECT
statement be alphanumeric fields.
If one of these fields was
described as another data class, the compiler redefines that field so
the INSPECT statement can handle it as a simple alphanumeric string.
This implicit redefinition is conducted as follows:
•

If the field was described as alphabetic, alphanumeric
edited, or unsigned numeric, the compiler simply redefines it
as alphanumeric. This is a compile-time operation; no data
movement occurs at object-time.

•

If the field was described as signed numeric, the compiler
first removes the sign and then redefines the field as
alphanumeric. If the sign is a separate character, the
compiler ignores that character, essentially shortening the
3-38

NON-NUMERIC CHARACTER HANDLING
field,
and that character does not participate in the
implicit redefinition.
If the sign is an "overpunch" on the
leading or trailing digit, the compiler actually removes the
sign value and leaves the character with only the numeric
value that was stored in it. The compiler alters the digit
position containing the sign before beginning the INSPECT
operation and restores it to its former value after the
operation.
If the sign's digit position does not contain a
valid ASCII signed numeric digit,
the action
of
the
redefinition causes the value to change. Table 3-12 shows
these original, altered, and restored values.
The compiler never moves an implicitly redefined item from its storage
position. All redefinition occurs in place.
The position of an implied decimal point on
not affect implicit redefinition.

numeric

quantities

Table 3-12
Original, Altered, and Restored Values Resulting
from Implicit Redefinition
ORIGINAL VALUE

ALTERED VALUE

RESTORED VALUE

} (173)
A (101 )
B (102 )
C (103 )
D (104)

0
1
2
3
4

(60)
(61)
(62)
(63)
(64)

} (173)
A (101 )
B (102 )
C (103 )
D (104 )

(105 )
(106 )
G (107)
H (110 )
I (Ill)

5 (65)
6 (66)
7 (67)
8 (70)
9 (71)

E (105)
F (106)
G (107 )
H (110)
I (Ill)

{
J

(175)
(112 )
K (113)
L (114)
M (115 )

0
1
2
3
4

(116)
(117)
p (120)
Q (121)
R (122 )

5 (65 )
6 (66)
7 (67)
8 (70)
9 (71 )

(60)
(61)
(62)
(63)
(64)

0
1
2
3
4

(65)
(66)
(67)
(70)
(71)

5 (65 )
6 (66)
7 (67)
8 (70)
9 (71)

All other values

0 (60)

8
9

(175)
(112)
K (113 )
L (114 )
M (115 )
(116 )
(117)
P (120 )
Q (121)
R (122 )

(60)
(61)
(62 )
(63)
(64)

0
1
2
3
4
6
7

{
J

(60)
(61)
(62)
(63)
(64)

} (173)
A (101 )
B (102 )
C (103)
D (104 )
E

(105)

F (106 )
G (107)

3-39

H
I

(110 )
(Ill)

}

(173)

does

NON-NUMERIC CHARACTER HANDLING
3.9.3

The INSPECT Operation

Regardless of the type of inspection
(TALLYING or REPLACING),
the
INSPECT statement has only one method for inspecting the characters in
the field.
This section describes this method.
However, before discussing how the inspection operation is
letls analyze the INSPECT statement itself:

conducted,

INSPECT FIELDI TALLYING TLY FOR ALL "B" BEFORE "A".

being~

The field
inspected

The argument

The operation
phrase

The delimiter
phrase

Figure 3-45
Sample INSPECT Statement
The format of the INSPECT statement requires that a field be named
which is to be inspected
(FIELDI above);
the field name must be
followed by an operation phrase
(TALLYING TLY above);
and,
that
phrase must be followed by one or more identifiers or literals ("B"
above). These identifiers or literals comprise the "arguments" (items
to be compared to the field being inspected). More than one argument
makes up the "argument list".
•

TALLYING Arguments
Each argument in an argument list can have other
fields
associated with it.
Thus, each argument that is used in a
(TLY above)
TALLYING operation must have a tally counter
associated with it.
The software increments the tally
counter each time it matches the argument with a character or
group of characters in the field being inspected.

•

REPLACING Arguments
INSPECT FIELDI REPLACING ALL "0" BY "$".

replacing argument
Figure 3-46
Sample REPLACING Argument
Each argument in an argument list that is used in a REPLACING
operation must have a replacement item ($ above) associated
with it. The software uses the replacement item to replace
each string of characters in the field that matches the
argument.
Each argument in an argument list (that is used with either a TALLYING
or REPLACING operation)
may have a delimiter field (BEFORE/AFTER
phrase) associated with it.
If the delimiter field is not present,
the software applies the argument to the entire field.
If the
delimiter field is present, the software applies the argument only to
that portion of the field specified by the BEFORE/AFTER phrase.

3-40

NON-NUMERIC CHARACTER HANDLING
3.9.3.1 Setting the Scanner - The INSPECT operation begins by setting
the scanner to the leftmost character position of the field being
inspected. It remains on this character until an argument has been
matched with a character (or characters) or until all arguments have
failed to find a match at that position.

3.9.3.2 Active/Inactive
Arguments - When
an
argument
has
a
BEFORE/AFTER phrase associated with it, that argument has a delimiter
and may not be eligible to participate in a comparison at every
position of the scanner. Thus, each argument in the argument list has
an active/inactive status at any given setting of the scanner.
For example, an argument that has an AFTER phrase associated with it
starts the INSPECT operation in an inactive state. The delimiter of
the AFTER phrase must find a match before the argument can participate
in the comparison.
When the delimiter finds a match, the software
retains the character position beyond the matched character string;
then, when the scanner reaches or passes this position, the argument
becomes active.
INSPECT FIELDI TALLYING TLY
FOR ALL "B" AFTER "X".
Figure 3-47
Sample AFTER Delimiter Phrase
If FIELDI in Figure 3-47 has a value of "ABABXZBA" ,
the argument B
remains inactive until the scanner finds a match for the delimiter X.
Thus, argument B remains inactive while the software scans character
positions 1 through 5. At character position 5, the delimiter X finds
a match, and since the character position beyond the matched delimiter
character is the point at which the argument becomes active, argument
B is compared for the first time at character position 6.
It finds a
successful match at character position 7 and this causes TLY to be
incremented by 1.
The examples in Figure 3-4H illustrate other situations where the
arguments and/or the delimiters are longer than one charactei.
(Consider the sample statement to be an INSPECT .•. TALLYING statement
that is scanning FIELDl,
tallying in TLY,
and looking for the
arguments and delimiters in the left-hand column. Assume that TLY is
initialized to 0.)

3-41

NON-NUMERIC CHARACTER HANDLING
ARGUMENT AND
DELIMITER

FIELDI
VALUE

ARGUMENT
ACTIVE AT
POSITION

CONTENTS OF
TLY AFTER SCAN

"B" AFTER "XX"

BXBXXXXBB
XXXXXXXX
BXBXBBBBXX

6
3
never

2
0
0

"X" AFTER "XX"

BXBXXBXXB
XXXXXXXX
BBBBBBXX

6
3
never

6
0

"B" AFTER "XB"

BXYBXBXX
XBXBXBXB
BBBBBBXB

7
3
never

XXXXBXXXX
XXXXBBXXX
XXBXXXXBX

6
6
4

1
1

"BX" AFTER "XB"

0
3
0

Figure 3-4b
Where Arguments Become Active in a Field
When an argument
has
an
associated
BEFORE
delimiter,
the
inactive/active states reverse roles:
the argument is in an active
state when the scanning begins, and becomes inactive at the character
position that matches the delimiter. Additionally, regardless of the
presence of the BEFORE delimiter, an argument becomes inactive when
the scanner approaches the right-hand end of the field and the
remaining characters are fewer in number than the characters
in the
argument.
(In such a case, the argument cannot possibly find a match
in the field so it becomes inactive.)
Since the BEFORE/AFTER delimiters are found on a separate scan of the
field,
the software recognizes and sets up the delimiter boundaries
before it scans for an argument match;
therefore, the same characters
can be used as arguments and delimiters in the same phrase.

3.9.3.3 Finding an Argument Match - The software selects arguments
from the argument list in the order in which they appear in the list.
If the first one it selects is an active argument and the conditions
stated in the INSPECT statement allow a comparison, the software
compares it to the character at the position of the scanner.
If the
active argument does not find a match, the software takes the next
active argument from the list and compares that to the same character.
If none of the active arguments finds a match, the scanner moves one
position to the right and begins the inspection operation again with
the first active argument in the list. The inspection operation
terminates at the right-hand end of the field.
When an active argument does find a match, the software ignores any
remaining arguments in the list and conducts the TALLYING or REPLACING
operation on the character. The scanner moves to a new position and
the next inspection operation begins with the first argument in the
list.
(The INSPECT statement may contain additional conditions, which
are described later
in this section;
this discussion, however,
assumes that the argument match is allowed to take place and that
inspection is allowed to continue following the match.)

3-42

NON-NUMERIC CHARACTER HANDLING
The software updates the scanner by adding the size of the matching
argument to it. This moves the scanner to the next character beyond
the string of characters that matched the argument.
Thus,
once an
active argument matches a string of characters, the statement does not
inspect those character positions again unless program
control
executes the entire statement again.

3.9.4

Subscripted Fields in INSPECT Statements

Any identifier named in an INSPECT statement
indexed.

may

subscripted

The software evaluates all subscripts in an INSPECT statement once,
before the inspection begins;
therefore, if the action of the INSPECT
statement alters one of the subscripts, the new subscript value has no
effect on the selection of operands during that inspection operation.
For example, consider the following illustration:
MOVE I TO TLY.
INSPECT FIELDI TALLYING TLY
FOR ALL X(TLY).
Figure 3-49
Sample Subscripted Argument
In this sample statement, the software evaluates the address of X(TLY)
only once,
before it begins inspecting the field;
hence, it will
evaluate X(TLY) as X{l). The alteration of TLY by the action of
inspecting and tallying has no effect on the choice of the X operand.
(X(l) will be used throughout the operation.)
NOTE
When subscripting an INSPECT statement
that contains both a TALLYING and a
REPLACING phrase, keep in mind that the
statement will be compiled into two
separate INSPECT statements. Therefore,
any field that is altered by the action
of the INSPECT ... TALLYING statement will
be in its altered state if used as a
subscript by the
INSPECT ... REPLACING
statement.

3.9.5

The TALLYING Phrase

An INSPECT statement that contains a TALLYING phrase counts the
occurrence
of
various
character strings under certain stated
conditions.
It keeps the count in a user-designated field called,
here, a tally counter.

3-43

NON-NUMERIC CHARACTER HANDLING
3.9.5.1 The Tally Counter - The identifier that follows the word
TALLYING
designates the tally counter.
The identifier may be
subscripted or indexed. The data item must be a numeric integer with
no editing or P characters; it may be COMP or DISPLAY usage, and it
may be signed (separate or overpunched).

Each time the tally argument matches the delimited
inspected, the software adds 1 to the tally counter.

string

being

The programmer can initialize the tally counter to any numeric
(The INSPECT statement does not initialize it.)

value.

3.9.5.2 The Tally Argument - The
tally
argument
specifies
a
character-string and a condition under which that string should be
compared to the delimited string being inspected.
The following
figure shows the format of the tally argument:

i~entifier}}
{ l1teral

ALL
}
{ LEADING
{ CHARACTERS

Figure 3-S0
Format of the Tally Argument
The CHARACTERS form of the tally argument specifies that every
character in the delimited string being inspected should be considered
to match an imaginary character that serves as the tally argument.
This increments the tally counter by a value that equals the size of
the delimited string. For example, the statement in the following
illustration causes TLY to be incremented by the number of characters
that precede the first comma, regardless of what those characters
might be.
INSPECT FIELDI TALLYING TLY FOR
CHARACTERS BEFORE ",no
Figure 3-51
CHARACTERS Form of the Tally Argument
The ALL and LEADING forms of the tally argument specify a particular
character string, which may be represented by either a literal or an
identifier. The tally argument character string may be any length;
however, each character of the argument must match a character in the
delimited string before the software considers the argument matched.
•

•

An identifier must be an elementary item of DISPLAY usage.
It may be any data class.
However, if it is other than
alphanumeric, the software performs an implicit redefinition
of
the item.
(This redefinition is identical to the
BEFORE/AFTER delimiter redefinition discussed earlier in
Sect~on

3.9.1.)

3-44

NON-NUMERIC CHARACTER HANDLING
The words ALL and LEADING supply conditions that further
inspection operation.

delimit

the

•

The word ALL specifies that every match that the search
argument finds
in the delimited character string be counted
in the tally counter. When a literal follows the word ALL,
it does not have the same meaning as the figurative constant,
ALL literal.
(The ALL literal meaning of ALL "," is a string
of consecutive commas,
as many as the context of the
statement requires.) ALL "," used as a tally argument means,
"count each comma without regard to adjacent characters."

•

The word LEADING specifies that only adjacent matches of the
TALLY
argument at the left-hand end of the delimited
character string be counted. At the first failure
to match
the tally argument,
the software terminates counting and
causes the argument to become inactive.
Consider
the
examples in Figure 3-52.
(The sample statement is an
INSPECT .•. TALLYING statement, scanning FIELDl,
tallying in
TLY, and looking for
the arguments and delimiters in the
left-hand column. Assume that the program initializes TLY to

o• )

ARGUMENT AND
DELIMI'rER

FIELDl
VALUE

CONTENTS OF TLY
AFTER SCAN

F***O**F
F**OF**

2
0

F**F**O
O***F**

F**O**F***
F**FO***FF**

1
1

F**FO****F**
F**F**O*

2
0

LEADING "*" AFTER "0".
0

LEADING 11**" AFTER 110".

Figure 3-52
Results of Counting with the
LEADING Condition

3.9.5.3 The Tally Argument List - One INSPECT ••. TALLYING statement
can contain more than one tally argument, and each argument can have a
separate BEFORE/AFTER phrase and tally counter associated with it.
These tally arguments with their associated tally counters and
BEFORE/AFTER phrases form an argument list. The manner in which this
list is processed affects the action of any given tally argument.
The following sample statements show INSPECT statements with argument
lists.
The text following each one tells how that list will be
processed.
~-------------------------------------------------------------,

INSPECT FIELDl TALLYING T FOR
ALL ","
ALL " ..
ALL "i".
Figure 3-53
Argument List Adding Into
One Tally Counter
3-45

NON-NUMERIC CHARACTER HANDLING
These three tally arguments have the same tally counter, T,
and are
active over the entire field being inspected. Thus, this statement
adds the total number of commas, periods, and semicolons in FIELDI to
the initial value of T.
INSPECT FIELDI TALLYING
TI FOR ALL ","
T2 FOR ALL " "
T3 FOR ALL ":".
Figure 3-54
Argument List Adding Into
Separate Tally Counters
Each tally argument in this statement has its own tally counter, and
is active over the entire field being inspected. Thus, the action of
this statement is to add the total number of commas in FIELDl to the
initial value of TI, the total number of periods to the initial value
of T2, and the number of semicolons to T3.
INSPECT FIELDI TALLYING
TI FOR ALL "," AFTER "A"
T2 FOR ALL "." BEFORE "B"
T3 FOR ALL ":".
Figure 3-55
Argument List (with Delimiters) Adding
into Separate Tally Counters
Each tally argument in this statement has its own tally counter:
the
first two arguments have delimiter phrases, and the last one is active
over the entire field being inspected. Thus, the first argument is
initially
inactive
and becomes active only after the scanner
encounters an A:
the second argument begins the scan in the active
state but becomes inactive after a B has been encountered:
and the
third argument is active du~ing the entire scan of FIELDI.
Figure 3-56 shows various values of FIELDI and the contents of the
three tally counters after the scan. Assume that the counters are
initialized to 0 before the INSPECT statement.
CONTENTS OF TALLY COUNTERS AFTER SCAN
FIELDI
VALUE

A.CiD.E,F
A.B.C.D
A,B,C,D
A:BiC:D
*,B,C,D

I
0
3
0
0

2
I
0
0
0

I
0
0
3
0

Figure 3-~6
Results of the Scan in Figure 3-55
The BEFORE/AFTER phrase applies only to the argument that precedes it,
and delimits the field for
that argument only. Each BEFORE/AFTER
phrase causes a separate scan of the field to determine the limits of
the field for its corresponding argument.

3-46

NON-NUMERIC CHARACTER HANDLING
3.9.5.4 Interference in Tally Argument Lists - When several tally
arguments contain one or more identical characters that are active at
the same time, they may interfere with each other (i.e., when one of
the arguments finds a match, the scanner is stepped past the matching
character(s) which prevents those character(s} from being considered
for any other match).
The example in Figure 3-57 illustrates two identical tally arguments
that do not interfere with each other since they are not active at the
same time.
(The first A in FIELDI causes the first argument to become
inactive and the second argument to become active.)
MOVE U TO TI T2.
INSPECT FIELDI TALLYING
TI FOR ALL "," BEFORE "A"
T2 FOR ALL "," AFTER "A".
Figure 3-57
Two Tallying Arguments that
Do Not Interfere with Each Other
The two identical tally arguments in Figure 3-58 will interfere with
each other since both are active at the same time.
(For any given
position of the scanner, the arguments are applied to FIELDI in the
order in which they appear in the statement. When one of them finds a
match, the scanner moves to the next position and ignores the
remaining arguments in the argument list.) Each comma in FIELDI causes
TI to be incremented by I and the second argument to be ignored.
Thus, TI will always contain an accurate count of all of the commas in
FIELDI, and T2 will always be unchanged.
INSPECT FIELDI TALLYING
TI FOR ALL ","
T2 FOR ALL "," AFTER "A".
Figure 3-58
Two Tallying Arguments that
Do Interfere with Each Other
The following statement achieves the same results as the statement in
Figure 3-57.
The first argument does not become active until the
scanner encounters an A. The second argument tallies all commas that
precede the A. After the A, the first argument counts all commas and
causes the second argument to be ignored.
Thus, TI contains the
number of commas that precede the first A and T2 contains the number
of commas that follow the first A.
This statement works well as
written, but could be more confusing to debug than the one in Figure
3-57.
INSPECT FIELDI TALLYING
T2 FOR ALL "," AFTER "A"
TI FOR ALL ",H.
Figure 3-59
Two Tallying Arguments that,
Because of their Positioning,
Only Partially Interfere with
Each Other

3-47

NON-NUMERIC CHARACTER HANDLING
The preceding three examples show that one INSPECT statement cannot
count any character more than once.
Thus, when using the same
character in more than one argument of an argument list, consider the
nature of the interference and choose the order of the argu~ents very
carefully. The solution to the problem may require two or more
INSPECT statements. Consider the following problem:
INSPECT FIELDI TALLYING
Tl FOR ALL "AB"
T2 FOR ALL "BC".
Figure 3-60
An Attempt to Tally the Character B
with Two Arguments
If FIELDl contains "ABCABC", after the scan Tl will be incremented by
a 2 and T2 will be unaltered. The successful matching of the argument
includes each B in the field.
Each match resets the scanner to the
character position to the right of the B, and causes the second
argument to never be successfully matched. Reversing the order of the
arguments has no effect, the results remain the same. Only separate
INSPECT statements can develop the desired counts.
Sometimes the programmer can use the interference characteristics of
the INSPECT statement to good advantage.
Consider the following
sample argument list:
MOVE 0 TO T4 T3 T2 Tl.
INSPECT FIELDI TALLYING
T4 FOR ALL "****"
T3 FOR ALL "***"
T2 FOR ALL "**"
Tl FOR ALL "*"
Figure 3-61
Tallying Asterisk Groupings
The argument list in Figure 3-61 counts all of the asterisks in FIELDI
but in four different tally counters. T4 counts the number of times
that four asterisks occur together; T3 counts the number of times
three asterisks appear together; T2 counts double asterisks;
and Tl
counts singles.
If FIELDI contains a string of more than four consecutive asterisks,
the argument list breaks the string into groups of four, and counts
them in T4. It then counts the less-than-four remainder in T3, T2, or
Tl.
Reversing the order of the arguments in this list causes Tl to
all of the asterisks and T2, T3, and T4 to remain unchanged.

count

When the LEADING condition is used with an argument in the argument
list, that argument becomes inactive as soon as it fails to be matched
in the field being inspected. Therefore, when two arguments in an
argument list contain one or more identical characters and one of the
arguments bas a LEADING condition,
the argument with the LEADING
condition
should
appear first.
Consider the following sample
statement:

3-48

NON-NUMERIC CHARACTER HANDLING
MOVE 0 TO TI T2.
INSPECT FIELDI TALLYING
TI FOR LEADING "*"
T2 FOR ALL "*"
Figure 3-62
Placing the LEADING Condition
in the Argument List
The placement of the LEADING condition in this sample statement causes
TI to count only leading asterisks in FIELDI;
the occurrence of any
other character stops this counting and causes the first tally
argument to become inactive.
T2 keeps a count of any remaining
asterisks in FIELDI.
Reversing the order of the arguments in this statement results
argument list that can never increment TI.

INSPECT FIELDI TALLYING
T2 FOR ALL "*"
Tl FOR LEADING "*".
Figure 3-63
Reversing the Argument
List in Figure 3-62
If the first character in FIELDI is not an asterisk, neither argument
can match it and the second argument becomes inactive. If the first
character in FIELDI is an asterisk, the first argument matches and
causes the second argument to be ignored. The first non-asterisk
character in FIELDI will fail to match the first argument and the
second argument will become inactive.
(The second argument becomes
inactive because it has not found a match in all of the preceding
characters.)
An argument with both a LEADING condition and a BEFORE phrase
sometimes sucessfully "delimit" the field being inspected:

can

MOVE 0 TO TI T2.
INSPECT FIELDl TALLYING
TI FOR LEADING SPACES
T2 FOR ALL"
"BEFORE""
T2 FOR ALL" "BEFORE "."
T2 FOR ALL " " BEFORE " "
IF T2 > 0 ADD I TO T2.
Figure 3-64
An Argument List that Counts
Words in a Statement
The statements in Figure 3-64 count the number of "words" in the
English statement in FIELDI.
(This assumes that no more than three
spaces separate the words in the sentence and that the sentence ends
with a period.) When FIELDI has been scanned, T2 contains the number
of gaps between the words. Since a count of the gaps renders a number
that is one less than the number of words, the conditional statement
adds one to the count.

3-49

NON-NUMERIC CHARACTER HANDLING
The first argument removes any leading spaces, counting them in a
different tally counter.
This shortens FIELDI by preventing the
application of the second through the fourth arguments until the
scanner finds a non-space character. The BEFORE phrase on each of the
other arguments causes them to become inactive when the scanner
reaches the period at the end of the sentence. Thus, the BEFORE
phrases "shorten" FIELDI by making the second through the fourth
arguments inactive before the scanner reaches the right-hand end of
FIELDI. If the sentence in FIELDI is indented with tab characters
instead of spaces, a second LEADING argument can count the tab
characters.
The following
sample
statement
illustrates
this
technique:
INSPECT FIELDI TALLYING
Tl FOR LEADING SPACES
Tl FOR LEADING TAB
T2 FOR ALL"
"etc.
Figure 3-b5
Counting Leading Tab or Space Characters
When an argument list contains a CHARACTERS argument, it should be the
last argument in the list.
Since the CHARACTERS argument always
matches the field, it prevents the application of any of the following
arguments in the list. However, as the last argument in an argument
list, it can count the remaining characters in the field being
inspected. Consider the following illustration.
MOVE 0 TO Tl T2 T3 T4 TS.
INSPECT FIELDI TALLYING
Tl FOR LEADING SPACES
T2 FOR ALL" " BEFORE ","
T3 FOR ALL "+" BEFORE ","
T4 FOR ALL "-" BEFORE ","
TS FOR CHARACTERS BEFORE ",H.
Figure 3-66
Counting the Remaining Characters
with the CHARACTERS Argument
If FIELDI is known to contain a number in the form frequently used to
input data, it may contain a plus or minus sign, and a decimal point;
further, the number may possibly be preceded by spaces and terminated
by a comma.
If this statement were compiled and executed, it would
deliver the following results:
Tl

would contain the number of leading spaces,

would contain the number of periods,

would contain the number of plus signs,

would contain the number of minus signs,

would contain the number of remaining characters (assumed to
be numeric) , and

the sum of Tl through TS (plus 1) gives
occupied by the terminating comma.

3-50

the

character

position

NON-NUMERIC CHARACTER HANDLING
3.9.6

The REPLACING Phrase

When an INSPECT statement contains a REPLACING phrase, that statement
selectively replaces characters or groups of characters in the
designated field.
The REPLACING phrase names a search argument consisting of a character
string of one or more characters and a condition under which the
string may be applied to the field being inspected.
Associated with
the search argument is the replacement value, which must be the same
length as the search argument.
Each time the search argument finds a
match in the field being inspected, under the condition stated, the
replacement value replaces the matched characters.
A BEFORE/AFTER phrase may be used to delimit the area of the field
being inspected. A search argument applies only to the delimited area
of the field.

3.9.6.1 The Search Argument - The search argument of the REPLACING
phrase names a character string and a condition under which the
character string should be compared to the delimited string being
inspected. Figure 3-67 shows the format of the search argument:

ALL

identifier}

LEADING (
FIRST

{

literal

CHARACTERS
Figure 3-67
Format of the Search Argument
The CHARACTERS form of the search argument specifies that every
character in the delimited string being inspected should be considered
to match an imaginary character that serves as the search argument.
Thus, the replacement value replaces each character in the delimited
string.
(The replacement value, in this case, must be one character
long. )
The ALL, LEADING, and FIRST forms of the search argument specify a
particular character string, which may be represented by a literal or
an identifier. The search argument character string may be any
length.
However, each character of the argument must match a
character in the delimited string before the software considers the
argument matched.
•

A literal character string must be either non-numeric or a
figurative constant
(other than ALL literal). A figurative
constant, such as SPACE,
ZERO, etc.,
represents a single
character and can be written as " ", "0", etc. with the same
effect. Since a figurative constant represents a single
character, the replacement value must be one character long.

•

An identifier must represent an elementary item of DISPLAY
usage.
It may be any class. However, if it is other than
alphabetic, the software performs an implicit redefinition of
the
item.
(This
redefinition
is
identical to the
BEFORE/AFTER delimiter redefinition discussed in Section
3.9.1.)
3-51

NON-NUMERIC CHARACTER HANDLING
The words ALL, LEADING, and FIRST
delimit the inspection operation:

supply

conditions

which

further

•

The word ALL specifies that each match that the search
argument finds
in the delimited string is to be replaced by
the replacement value.
When a literal follows the word ALL,
it does not have the same meaning as the figurative constant,
ALL literal.
(The figurative constant meaning of ALL ","
is
a string of consecutive commas, as many as the context of the
statement requires.) ALL "," as a search argument of the
REPLACING phrase means, "replace each comma without regard to
adjacent characters."

•

The word LEADING specifies that only adjacent matches of the
search argument at the left-hand end of the delimited
character string be replaced.
At the first failure to match
the search argument, the software terminates the replacement
operation and causes the argument to become inactive.

•

The word FIRST specifies that only the leftmost character
string that matches the search argument is to be replaced.
After
the replacement operation,
the
search
argument
containing this condition becomes inactive.

3.9.6.2 The Replacement Value - Whenever the search argument finds a
match in the field being inspected,
the matched characters are
replaced by the replacement value.
The word BY followed by an
identifier or literal specifies the replacement value.

identifier}
{

literal

Figure 3-68
Format of the Replacement Value
The replacement value must always be the same size as
search argument.

its

associated

If the replacement value is a literal character string,
it must be
either a non-numeric literal or a figurative constant (other than ALL
literal). A figurative constant represents as many characters as the
length that the search argument requires.
If the replacement value is an identifier, it must be an elementary
item of DISPLAY usage.
It may be any class. However, if it is other
than alphanumeric, the software conducts an implicit redefinition of
the item.
(This redefinition is the same as the BEFORE/AFTER
redefinition discussed in Section 3.9.1.)

3.9.6.3 The Replacement Argument - The replacement argument consists
of the search argument (with its condition and character string), the
replacement value, and an optional BEFORE/AFTER phrase.

3-52

NON-NUMERIC CHARACTER HANDLING
_A_L-=L_".....:i_'_' BY SPAC E BEFORE "."

~ BEFORE/AFTER

search/
/
argument
replacement
value

phrase (optional)

Figure 3-69
The Replacement Argument

3.9.6.4 The Replacement Argument
List - One
INSPECT ••. REPLACING
statement can contain more than one replacement argument. Several
replacement arguments form an argument list, and the manner
in which
the list is processed affects the action of any given replacement
argument.
The following examples show INSPECT statements with replacement
argument lists. The text following each one tells how that list will
be processed.
INSPECT FIELDl REPLACING
ALL .. , .. BY SPACE
ALL .. .. BY SPACE
ALL ":" BY SPACE.
Figure 3-70
Replacement Argument List that is
Active Over the Entire Field
These three replacement arguments all have the same replacement value,
SPACE, and are active over the entire field being inspected.
Thus, this statement replaces all commas, periods, and semicolons with
space characters;
and leaves all other characters unchanged.
INSPECT FIELDI REPLACING
ALL .. 0" BY "1"
ALL "I" BY "0".
Figure 3-71
Replacement Argument List that
"Swaps" Ones for Zeroes and Zeroes for Ones
Each of these two replacement arguments has its own replacement value,
and is active over the entire field being inspected. This statement
exchanges zeros for ones and ones for zeroes,
and leaves all other
characters unchanged.
NOTE
When a search argument finds a match in
the field being inspected, the software
replaces that character string and scans
to the next position beyond the replaced
characters. It ignores the remaining
arguments and applies the first argument
in the list to the character string in
3-53

NON-NUMERIC CHARACTER HANDLING
the
new
position.
Thus,
it never
inspects the new value that was supplied
by the replacement operation.
Because
of this, the search arguments may have
the
same values as the replacement
arguments
with
no
chance
of
interference.
INSPECT FIELDI REPLACING
ALL "0" BY "1" BEFORE SPACE
ALL "1" BY "0" BEFORE SPACE.
Figure 3-72
Replacement Argument List that
Becomes Inactive with the
Occurrence of a Space Character
This sample statement is identical to the statement in Figure 3-71,
except that, here, the first occurrence of a space character in FIELDI
causes both arguments to become inactive.
INSPECT FIELDI REPLACING
ALL "0" BY "1" BEFORE SPACE
ALL "1" BY "0" BEFORE SPACE
CHARACTERS BY "*" BEFORE SPACE.
Figure 3-73
Argument List with Three Arguments
That Become Inactive with the
Occurrence of a Space
Just as in the argument list in Figure 3-72, the first space character
causes all of these replacement arguments to become inactive. This
argument list exchanges zeroes for ones, ones for
zeroes,
and
asterisks for all other characters that are in the delimited area.
If the BEFORE phrase is removed from the third argument, that argument
will remain active across all of FIELDI. Within the area delimited by
the first space character, the third argument replaces all characters
except ones and zeroes with asterisks.
Beyond this area, it replaces
all characters (including the space that delimited FIELDI for
the
first two arguments and any zeroes and ones) with asterisks.

3.9.6.5 Interference in Replacement Argument Lists - When several
search arguments that are active at the same time contain one or more
identical characters,
they may interfere with each other,
and
consequently have an effect on the replacement operation. This
interference of one search argument with the matching of other search
arguments is similar to the interference that occurs between tally
arguments.
The action of a search argument is never affected by the BEFORE/AFTER
delimiters of other arguments, since the software scans for delimiter
matches before it scans for replacement operations.
The action of a search argument is never affected by the characters of
any replacement value, since the scanner does not inspect the replaced
characters again during execution of the INSPECT statement.
3-54

NON-NUMERIC CHARACTER HANDLING
Interference between search arguments, therefore, depends on the order
of the arguments, the values of the arguments, and the active-inactive
status of the arguments.
(The discussion in
Section
3.9.5.4
Interference
in
Tally
Argument Lists, applies,
generally,
to
replacement arguments as well.)
The following rules will help
argument lists:

minimize

interference
FIRST

replacement

Place search arguments with LEADING or
the start of the list;

conditions

Place several arguments with the CHARACTERS condition at
end of the list;

the

Consider, very carefully, the order of
search
arguments
that
contaiI! one
characters.

appearance of any
or more identical

Common Errors, INSPECT Statement

3.9.7

The most common errors made when writing INSPECT statements are:
•

Leaving the FOR out of an INSPECT ... TALLYING statement.

•

Using the word
phrase.

•

Failing to initialize the tally counter.

•

Omitting the word "ALL" e.g.:

"WITH"

instead

"BY"

the

INSPECT FIELDI TALLYING TLY FOR SPACES.

3-55

REPLACING

CHAPTER 4
NUMERIC CHARACTER HANDLING

4.1

INTRODUCTION

This chapter discusses numeric class data and the COBOL operations
that may be performed on numeric class data. It is assumed that the
reader has read Chapter 3, and understands the concept of COBOL data
classes.

4.2

USAGES, DISPLAY/CaMP

The USAGE of a numeric class item specifies the form in which that
item's data is held in memory. COBOL has two basic formats for data
storage, DISPLAY and COMPUTATIONAL (DISPLAY, DISPLAY-6, and DISPLAY-7
are all equivalent):
•

ANS-74 COBOL standards prescribe DISPLAY usage to be a string
of characters or bytes in decimal radix, with an assumed
decimal point location and various sign conventions.

•

The same standards prescribe COMPUTATIONAL (CaMP) usage to be
a real number with the same range of values as a DISPLAY usage
number. However, with CaMP usage, the compiler implementor
has the liberty of specifying the form in which that number is
held in memory.

two,
TRAX COBOL stores CaMP usage fields as binary numbers in one,
three or four words with an assumed decimal scaling position.
Consider the following field description:
01 GEMINI PIC 99V99 CaMP.
If this field contains the value 12.34, TRAX COBOL stores it as a
I-word binary number.
The word contains the integer value 1234 and
another location contains the scaling factor.
In this example, the
scaling factor records the fact that this integer has two decimal
fractional positions associated with it. Thus, the COBOL OTS knows
that the stored binary integer is 100 times larger than the programmer
intends it to be.
If the compiler encounters the following statement:
ADD 1 TO GEMINI.
it generates instructions to add a 1 to the 1234 in GEMINI. The OTS,
however,
scales the literal 1 up by two decimal places and adds the
resultant literal, 100, to the number in GEMINI. Thus, after the ADD
operation, GEMINI contains the new value 1334 (which is actually 13.34
with the stored decimal scaling position).
4-1

NUMERIC CHARACTER HANDLING
Thus, the TRAX COBOL compiler and OTS manipulate the data in both
DISPLAY and CaMP usage items in much the same way. Both usages have
exactly the same accuracy and precision, and can be freely mixed in a
program.
If a DISPLAY usage number and a CaMP usage number are both
involved in the same arithmetic statement, the OTS converts them to a
common radix, with no loss of information. It also converts the
result (if necessary), before storing it,
with
no
loss
of
significance.
The only effect of specifying the CaMP usage is that
space required for most numbers and speeds up
arithmetic statements.

4.2.1

it reduces the
the execution of

Sign Conventions

DISPLAY or CaMP usage numeric items may be signed or unsigned.
Unsigned numbers may contain values that range from zero to the
largest positive value allowed by their declared precision.
Negative
values are not allowed. All TRAX COBOL arithmetic operations yield
signed results. When the OTS must store such a result, whether
positive or negative,
in an unsigned data item, it stores only the
absolute value of the result. Thus, unsigned items always contain
zero or positive values.
This guide does not recommend unsigned numbers for general use.
They
are usually a source of programming errors, and are handled less
efficiently than signed quantities by the OTS.
Signed quantities always contain a numeric value and an operational
sign.
The OTS stores the sign with the numeric value in a variety of
ways depending on the usage of the item and the presence of the SIGN
clause.
NOTE
If numeric data is read into a field
described using the picture character S,
must
include
an
then
that
data
operational
sign of the appropriate
format to pass the NUMERIC test.

TRAX
COBOL always stores signed CaMP items in two's complement
binary form. Thus, the high-order bit indicates the sign of the item.
TRAX
COBOL always stores signed DISPLAY items as a sequence of byte
positions containing numeric ASCII characters. It may include the
sign in the high-order byte, the low-ordec byte, or as a separate,
extra, byte on either the high-order or low-order end of the item.
When the OTS stores the sign as part of a byte that also contains a
numeric digit, the sign causes a value change in thqt byte and, hence,
changes the value of the numeric digit. Table 4-1 shows the actual
ASCII character that results when a numeric value and a sign share the
same byte.

4-2

NUMERIC CHARACTER HANDLING
Table 4-1
The Resulting ASCII Character From a
Sign and Digit Sharing the Same Byte
DIGIT VALUE

SIGN

{

}

A byte containing a +0 stores as an octal 173, which prints as
a
{or a [ depending on the printing device.

either

A byte containing a -0 stores as an octal 175, which prints as

either

} or a ] depending on the printing device.

When the OTS stores the sign as a
separate distinct character,
the
actual ASCII character that it stores is the graphic plus sign (octal
053) or the graphic minus sign (octal 055).

4.2.2

Illegal Values in Numeric Fields

All TRAX COBOL arithmetic operations store legal values
in their
result
fields.
However,
it is possible, by reading invalid data or
through redefinition and group moves, to store data in numeric fields
that do not obey the descriptions of those fields.
(For example, it
is possible to place signed values into unsigned fields, and to place
non-numeric or
improperly signed data into signed numeric DISPLAY
fields.)
TRAX COBOL handles this data in the following manner.
NOTE
The following four
compiler techniques
are
not
specified by ANS-74 COBOL
standards.
Dependence on them may yield
programs
that
are
not
compiler
independent.
1.

When a
quantity described as unsigned enters
into
an
arithmetic operation, the OTS treats it as a signed quantity.
If it contains no sign, the OTS either considers the sign to
be positive, or ignores the sign if the value of the field is
zero.
If the field does contain a legally constructed sign,
the OTS interprets the sign as if the item had been described
as a signed quantity.
Thus the OTS treats a negative value in an unsigned CaMP item
as a
negative value.
Likewise a negative sign, stored as J
through R, in the rightmost digit of an unsigned DISPLAY
item, causes the OTS to treat that value as a negative value.
When an arithmetic operation or
legal elementary
MOVE
statement places its result in an unsigned item, that item
receives the absolute value only
(no sign information is
encoded in the result).

4-3

NUMERIC CHARACTER HANDLING
For example the following coding results in an unsigned value
of 15 in field B:

02 A PIC S99 VALUE IS 5
02 C PIC XX VALUE IS "2 "
02 B REDEFINES C PIC 99.

ADD A TO B.
However, given the same original values in A and B,
the
following statement would result in a value of -15 in field
A.
(Field B remains at -20.)
ADD B TO A.
2.

When a signed quantity enters into an arithmetic
the OTS interprets the sign as follows:
a.

If the item is COMP usage, the OTS takes the value
two's complement number;

If the item is DISPLAY usage and the sign is encoded
within the leading or trailing digit position, the OTS
takes the sign as positive if that position contains
either a {
(octal 173) or any ASCII byte that collates
less than J. Thus, the OTS considers a space, 0 through
9, and A through I, to be positive.
Further,
it
considers any ASCII character that collates equal-to or
higher-than J
(except {--octal 173)
to be negative.
(The OTS conducts this sign determination separately from
the numeric value determination for the same byte.)

operation,

VALUE

SIGN DETERMINATION

OOOA
OOOJ

+0001
-0001

If the item is DISPLAY usage and the sign is encoded as a
separate leading or trailing byte, the OTS takes the sign
as negative only if that byte contains the
ASCII
character
(octal 055).
The OTS considers that all
other ASCII characters in the separate sign position
indicate a positive field.

A COMP usage item may receive a value that is larger than the
specified range.
For example,
the OTS stores a field
described as PIC S9999 COMP as a l6-bit binary number.
The
declared range is four decimal digits, but the field has the
capability of storing any value from -32,768 to +32,767
(decimal) .
The OTS stores the results of an arithmetic
operation on such a field as a value modulo the declared
decimal range.
Thus, any value that exceeds 9,999 stores a
modulo 10,000 value.
(The binary value of 10,000 stores as a
zero.)

4-4

NUMERIC CHARACTER HANDLING
When a COMP usage field enters an arithmetic operation,
however, the OTS uses the full binary number as the binary
value of the field. Thus, a value stored in a COMP field by
a group move may cause the field to contain a value that
exceeds the declared range. Arithmetic operations will use
that value as found.
4.

A DISPLAY usage item may contain a value in which some or all
of the numeric digit positions contain illegal values.
When a DISPLAY usage numeric item enters an arithmetic
operation, the OTS converts each character to a binary value
either before or during the operation. This conversion maps
certain ASCII characters into the numeric values 0 through 9,
and all other ASCII characters into the numeric value O.
Table 4-2 shows these conversion values:
Table 4-2
Conversion Values
ASCII CHARACTERS

BINARY VALUES

0001 (1)

0010 (2)

0011 (3)

0100 (4)

0101 (5)

0110 (6)

0111 (7)

1000 (8)

1001 (9)

ALL OTHERS

0000 (0)

All arithmetic operations (including the numeric elementary MOVE)
deliver the ASCII characters 1 through 9 and 0 into all digit
positions of a numeric DISPLAY field.
A digit position that also
contains a sign value receives a correctly coded sign value as shown
in Table 4-1.

4-5

NUMERIC CHARACTER HANDLING
4.3

TESTING NUMERIC FIELDS

COBOL provides the following
numeric fields:

three

kinds

tests

for

evaluating

Relation tests, that compare the field's contents to
numeric value;

another

Sign tests, that examine the field's sign to
positive or negative;
and,

see

Class tests, that inspect the
legal numeric values.

positions

for

field's

digit

The following sub-sections explain these tests in detail.

4.3.1

Relation Tests

A relation test compares two numeric quantities and determines if the
specified relation between them is true.
For example, the following
statement compares FIELDI to FIELD2 and determines if the numeric
value of FIELDI is greater than the numeric value of FIELD2. If so,
the relation condition is true and program control takes the True path
of the statement.
IF FIELDI > FIELD2 ...
Either field in a relation test may be a numeric literal or the
figurative constant, ZERO.
(The numeric literals 0, 00, 0.0, or ZERO
are all equivalent, both in meaning and in execution speed.)
The sizes of the fields in a numeric relation test do not have to be
the
same
(this includes the sizes of numeric literals).
The
comparison operation aligns both fields on their assumed decimal
positions (through actual scaling operations in temporary locations or
by accessing the individual digits) and supplies leading or trailing
(as required) zeroes to either or both fields.
The comparison operation always compares the signs of non-zero fields
and considers positive fields to be greater than negative fields.
However, since it does not compare them, positive zeroes and negative
zeroes are equal.
(A negative zero could arrive in a field through
redefinition of the field or a MOVE to a group item.)
Further, the
operation considers unsigned numeric fields to be positive.
The form of representation of the number (COMP or DISPLAY usage)
and
the various methods of storing DISPLAY usage signs have no effect on
numeric relation tests.
For comparison purposes, the operation converts any illegal characters
stored in DISPLAY usage fields to zeroes.
It does not, however, alter
the actual values in those fields.

4.3.2

Sign Tests

The sign test compares a numeric quantity to zero arid determines if it
is greater
(positive), less
(negative), or equal (zero). Both the
relation test and the sign test can perform this function.
For
example, consider the following relation test:
IF FIELDI > 0 ...

4-6

NUMERIC CHARACTER HANDLING
Now consider the following sign test:
IF FIELDI POSITIVE ...
Both of these tests accomplish the same thing and would always arrive
at the same result. The sign test, however, shortens the statement
and shows, at a glance, that it is testing the sign.
Table 4-3 shows the sign tests and their equivalent relation tests
applied to FIELDI.

Table 4-3
The Sign Tests
SIGN TEST
IF
IF
IF
IF
IF
IF

EQUIVALENT RELATION TEST

· .. ...
· ..
...

FIELDI POSITIVE
FIELDI NOT POSITIVE
FIELDI NEGATIVE
FIELDI NOT NEGATIVE
FIELDI ZERO
FIELDI NOT ZERO ·

...

IF
IF
IF
IF
IF
IF

FIELDI
FIELDI
FIELDI
FIELDI
FIELDI
FIELDI

· ..
· ..
< 0 · ..
> 0

NOT > 0
NOT < 0

· ..

= 0 · ..
NOT = 0 · ..

Sign tests have no execution speed advantage over relation tests. The
compiler actually substitutes the equivalent relation test for every
correctly written sign test.
(Sections 4.2.1 and 4.2.2 discuss the
acceptable sign values and the treatment of illegal sign values.)

4.3.3

Class Tests

The class test interrogates a numeric field to determine if it
contains numeric or alphabetic data, and uses the result to alter the
flow of control in a program. For example, the following statement
determines if FIELDI contains numeric data. If so, the test conditio·n
is true and program control takes the true path of the statement.
IF FIELDI IS NUMERIC
When reading in newly prepared data, it is often desirable to check
certain fields for valid values. Relation tests and sign tests can
only determine if the field's contents are within a certain range, and
these tests both treat illegal characters in DISPLAY usage items as
zeroes. Thus, some data preparation errors could pass both of these
tests.
The NUMERIC class test checks numeric (or alphanumeric) DISPLAY
fields for valid numeric digits.

usage

If the field being tested contains a sign (whether carried as an
overpunch or as a separate character), the test checks it for a valid
sign value.
If the character position carrying the sign contains an
illegal sign value,
the NUMERIC class test rejects the item and
program control takes the false path of the IF statement.
If the
character position contains a valid sign and all digit positions in
the field contain valid numeric digits, the NUMERIC class test passes
the item and program control takes the true path of the IF statement.

4-7

NUMERIC CHARACTER HANDLING
The ALPHABETIC class test checks alphabetic (or alphanumeric)
fields
for valid alphabetic characters and the space character.
If all of
the character positions of the field contain ASCII characters (A-Z or
space),
the item passes the ALPHABETIC class test and causes program
control to take the true path of the IF statement.
(For further
information concerning the ALPHABETIC class test,
see Chapter 3,
Section 3.3.2.)

4.4

THE MOVE STATEMENT

The MOVE statement moves the contents of one field into another.
The
following sample MOVE statement moves the contents of FIELDI into
FIELD2.
MOVE FIELDI TO FIELD2.
Section 3.5 discusses the basic MOVE statement.
This
section
considers MOVE statements as applied to numeric fields. These MOVE
statements can be grouped into the following three categories:
1.

Group moves,

Elementary moves with numeric receiving fields, and

Elementary moves with numeric edited receiving fields.

The following three sub-sections (4.4.1,
each of these categories separately.

4.4.1

4.4.2,

and

4.4.3)

discuss

Group Moves

The software considers a move to be a group move if either the sending
field or the receiving field is a group item.
It treats both fields
in a group move as alphanumeric class fields and performs the move as
an alphanumeric to alphanumeric elementary move.
If either field in a group move is a numeric elementary item, the OTS
treats the storage area occupied by that item as a field of
alphanumeric bytes;
thus, it ignores the USAGE,
sign,
and decimal
point location characteristics of the numeric item.
Only the item's allocated size, in bytes, affects the move operation.
The OTS considers a separate sign character to be part of the item and
moves it with the numeric digit positions.

4.4.2

Elementary Numeric Moves

If both fields of a MOVE statement are elementary items and the
rece~v~ng
field is numeric,
the OTS considers the move to be an
elementary numeric move.
(The sending field may be either numeric or
alphanumeric.)
The numeric receiving field may be either DISPLAY or
COMP usage. The elementary numeric move converts the data format of
the sending field to the data format of the receiving field.

4-8

NUMERIC CHARACTER HANDLING
An alphanumeric sending field may be either an elementary data item or
any alphanumeric literal other than the figurative constants SPACE,
QUOTE, LOW-VALUE,
HIGH-VALUE,
or ALL "literal".
The elementary
numeric move accepts the figurative constant ZERO and considers it to
be equivalent to the numeric literal O.
It treats alphanumeric
sending fields as unsigned integers of DISPLAY usage.
If necessary, the numeric move operation converts the sending field to
the data format of the receiving field and aligns the sending field's
decimal point on that of the rece1v1ng field.
It then moves the
sending field digits to their corresponding receiving field digits.
If the sending field has more digit positions than the receiving
field,
the decimal point alignment operation truncates the sending
field,
with the resultant loss of digits.
The end
truncated
(high-order or low-order)
depends upon the number of sending field
digit positions that find matches on each side of the receiving
field's decimal point.
If the receiving field has fewer digit
positions on both sides of the decimal point, the operation truncates
both ends of the sending field.
Thus, if a field described as PIC
999V999 is moved to a field described as PIC 99V99,
it loses one
digit from the left end and one from the right end.
Figure 4-1
illustrates this alignment operation (the carat
(~)
indicates the
stored decimal scaling position):
01 GANDALF PIC 99V99.

MOVE 123.321 TO GANDALF.
Before execution
After execution
Figure 4-1
Truncation Caused By Decimal Point Alignment
If the sending field has fewer digit positions than the receiving
field,
the move operation supplies zeroes for all unfilled digit
positions.
Figure 4-2 illustrates this alignment
(the carat
(~)
indicates the stored decimal scaling position):
01 RIVENDELL PIC 999V99.

MOVE 1 TO RIVENDELL.
Before execution
After execution
Figure 4-2
Zero Filling Caused By Decimal Point Alignment
The following statement produces the same results:
MOVE 001.00 TO RIVENDELL.
4-9

NUMERIC CHARACTER HANDLING
Consider the following two MOVE statements
truncating and zero-filling effects:
STATEMENT

and

their

resultant

RIVENDELL AFTER EXECUTION

MOVE 00100 TO RIVENDELL

100 00

MOVE "00100" TO RIVENDELL

100 00

Literals with leading or trailing zeroes have no significant advantage
in space or execution speed with TRAX COBOL, and the zeroes are
often lost by decimal point alignment.
The MOVE statement's receiving field dictates how the sign will be
moved.
A signed DISPLAY usage receiving field causes the sign to be
moved as a separate quantity. An unsigned DISPLAY usage receiving
field causes no sign movement. A COMP usage receiving field, whether
signed or unsigned, causes the sign to be moved:
however,
if the
receiving field is unsigned, the OTS sets its value to absolute.

4.4.3

Elementary Numeric Edited Moves

The TRAX
COBOL object time system considers an elementary numer ic
move to a receiving field of the numeric edited category to be an
elementary numeric edited move. The sending field of an elementary
numeric edited move may be either numeric or alphanumeric and, if
numeric, it can be either DISPLAY usage or COMP usage. The OTS treats
alphanumeric sending fields
in numeric edited moves as unsigned
DISPLAY usage integers.
The OTS considers the receiving field to be numeric edited category if
it is described with a BLANK WHEN ZERO clause, or a combination of the
following symbols:
B

Space insertion position:

Decimal scaling position:

Location of assumed decimal point;

Leading numeric character position to be replaced by a space
if the position contains a zero:

Zero insertion position:

Position contains a numeric character;

Slash insertion position:
Comma insertion position:
Decimal point insertion position;

Leading numeric character position to be
asterisk if the position contains a zero:

Positive editing sign control symbol:
Negative editing sign control symbol:

Credit editing sign control symbol;

4-10

replaced

NUMERIC CHARACTER HANDLING
DB

Debit editing sign control symbol;

Currency symbol ($) insertion position.

A numeric edited field may contain 9, V, and P,
those symbols without an editing character
numeric edited.

but combinations of
do not make the field

The numeric edited move operation first converts the sending field to
DISPLAY usage and aligns both fields on their decimal point locations,
truncating or padding (with zeroes) the sending field until it
contains the same number of digit positions on both sides of the
decimal point as the receiving field. It then moves the resulting
digit values to the receiving field digit positions following the
COBOL editing rules.
The COBOL editing rules allow the numeric edited
perform any of the following editing functions:

move

operation

•

Suppress leading zeroes with either spaces or asterisks;

•

Float a currency sign and a
suppressed zeroes, inserting
field;

•

Insert zeroes and spaces;

•

Insert commas and a decimal point.

plus or minus sign through
the sign at either end of the

Figure 4-3 illustrates several of these functions with the statement,
MOVE
FRODO TO RIVENDELL.
(Assume that FRODO is described as
S9999V99.)
FRODO
0023",00
0085",90
1234",00
0012,,34
0000",34
1234",00
0012",34
0012",34
0000",00
0012",3M
0012",34
0012,,34

PICTURE STRING

RIVENDELL
CONTENTS AFTER MOVE
~
~

$$$~,$$$.99

L\23.00
-85.96
1,234.00
L\ $12.34
L\ L\$0.34
$1,234.00
$0,012.34
~L\/j,L\ $12.34

$$$,$$$.$$
++++.99
$***,***.99
$***,***.99

-12.34
$**1,234.00
$*****12.34

ZZZZ.99
++++.99
Z,ZZZ.99
$,$$$.99
$,$$9.99
$$,$~$.99

$$9,999.99

~/j,L\~L\~L\~~~

Figure 4-3
Numeric Editing
The currency symbol ($) and the editing sign control symbols (+ -) are
the only floating symbols. To float them, enter a string of two or
more occurrences of the symbol.

4-11

NUMERIC CHARACTER HANDLING
4.4.4

Common Errors, Numeric MOVE Statements

The most common errors made when writing numeric MOVE statements are:
•
•
•
•

4.5

Placing an incorrect number of replacement characters in a
numeric edited item.
Moving non-numeric data into numeric fields with group moves.
Trying to float the $ or + insertion characters past the
decimal point to force zero values to appear as .00 instead of
spaces.
(Use $$.99 or ++.99.)
Forgetting that the $ or + insertion characters require an
additional position on the leftmost end that cannot be
replaced by a digit (unlike the * insertion character which
can be completely replaced).

THE ARITHMETIC STATEMENTS

The COBOL arithmetic statements, ADD, SUBTRACT, MULTIPLY, DIVIDE, and
COMPUTE allow COBOL programs to perform simple arithmetic operations
on numeric data.
This section covers the use of the COBOL arithmetic statements.
The
first five sub-sections
(4.5.1 through 4.5.5)
discuss the common
features of the statements and the last five
(4.5.6 through 4.5.10)
discuss the individual arithmetic statements themselves.

4.5.1' Intermediate Results
Most forms of the arithmetic statements perform their operations in
temporary work locations,
then move the results to the receiving
fields, aligning the decimal points and truncating or zero filling the
resultant values.
This temporary work field, called the intermediate result field, has a
maximum
size
of 18 numeric digits.
The actual size of the
intermediate result field varies for each statement, and .is determined
at compile time based on the sizes of the operands used by the
statement.
When the compiler determines that the size of the intermediate result
field exceeds 18 digits, it truncates the excess high-order digits.
Thus, a program that requests a multiplication operation between the
following two fields,
PIC 9(18) and PIC V99.
(which would otherwise cause
intermediate result field
intermediate result field

the

compiler to set up a 20-digit
actually causes the following

9(18)V99)

PIC 9(16)V99.
PDP-II COBOL truncates high-order digits or low-order digits to the
right of the decimal point, based on the assumption that most large
data declarations are larger than ever need be, so zeroes occupy most
of their high-order digit positions. Numeric data may be declared as
PIC 9(12) or PIC 9(15) but the values that are placed in these fields
will probably not exceed nine digits of range (1 billion) in most
applications.

4-12

NUMERIC CHARACTER HANDLING
When using large numbers (or numbers with many decimal places)
that
are close to 18 digits long, examine all of the arithmetic operations
that manipulate those numbers to determine if truncation will occur.
If truncation is a possibility, reduce the size of the number by
dividing it by a power of 10 prior to the arithmetic operation.
(This
scaling down operation causes the low-order end to lose digits,
but
these
are probably less critical.)
Then,
after the arithmetic
operation, multiply the result by the same power of 10.
To save the low-order digits in such an operation, move the field to a
temporary location before the scaling DIVIDE, perform separate,
identical arithmetic operations on both the original and the temporary
fields, then, after the scaling MULTIPLY, combine their results.

4.5.2

The ROUNDED Phrase

Rounding-off is an important tool with most arithmetic operations.
The ROUNDED phrase causes the OTS to round-off the results of COBOL
arithmetic operations.
The phrase may be used on
any
COBOL
arithmetic
statement.
Rounding-off takes place only when the ROUNDED phrase requests it, and
then only if the intermediate result has more low-order digits than
the result field.
TRAX
COBOL rounds-off by adding a 5 to the leftmost truncated digit
of the absolute value of the intermediate result before it stores that
result.
Consider the following illustration and assume an intermediate
of 54321.2468:

result

Coding:

01 BILBO PIC S9(5)V9999.
01 FRODO PIC S9(5)V99.

...

ADD BILBO TO FRODO ROUNDED.

Intermediate resul t field:

PIC S9(6)V9999.
The ROUNDED operation:

Truncated

Intermediate result field: 054321.24
(ADD)
ROUNDED:
FRODO's ROUNDED result:

.00
054321.25

~
68

digits
'LEFT-MOST
50 truncated
18
digit

Figure 4-4
Rounding Truncated Decimal Point positions
The following ROUNDING example rounds-off to the decimal scaling
position (P). Assume an intermediate result of 24680.
(Section 4.5.4
discusses the GIVING phrase in numeric operations.)

4-13

NUMERIC CHARACTER HANDLING
Coding:

01
01

GANDALF PIC 9999.
SARUMAN PIC 9999PP.

...

MULTIPLY GANDALF BY 10

...

GIVING SARUMAN ROUNDED .

Intermediate result field:
PIC 999999.

The ROUNDED operation:

Truncated
Intermediate result

field:

ROUNDED
SARUMAN's

0246

(ADD) :
ROUNDED result:

80.

digits

50.
0247

30.

Figure 4-5
Rounding Truncated Decimal Scaling positions

4.5.3

The SIZE ERROR Phrase

The SIZE ERROR phrase detects the loss of high-order
in the results of COBOL arithmetic operations.

non-zero

digits

The phrase may be used on any COBOL arithmetic statement.
When the execution of a statement with no SIZE ERROR phrase results in
a size error, the OTS truncates the high-order digits and stores the
result without notifying the user.
When the execution of a statement
with a SIZE ERROR phrase results in a size error, the OTS discards the
entire result (it does not alter the receiving fields in any way)
and
executes the SIZE-ERROR imperative phrase.
If the statement contains both ROUNDED and SIZE ERROR phrases, the OTS
rounds the result befote it checks for a size error.
The phrase cannot be used on numeric MOVE statements.
Thus,
if a
program moves a numeric quantity to a smaller numeric field, it may
inadvertently lose high-order digits.
For example, consider the
following MOVE of a field to a smaller field:
01 BIGFOOT PIC 9(8)V99.
01 LITTLEFOOT PIC 9(4)V99.

MOVE BIGFOOT TO LITTLEFOOT.
This MOVE operation always loses four of BIGFOOT's high-order digits.
Either of the following two statements could determine whether these
digits are zero or non-zero, and could be tailored to any size field:
4-14

NUMERIC CHARACTER HANDLING
1.

IF BIGFOOT NOT> 9999.99
MOVE BIGFOOT TO LITTLE FOOT
ELSE ••.

ADD ZERO TO BIGFOOT GIVING LITTLEFOOT
ON SIZE ERROR ...

Both of these alternatives allow the MOVE operation to occur only if
BIGFOOT loses no significant digits.
If the value in BIGFOOT is too
large, both alternatives avoid altering LITTLEFOOT and take the
alternative execution path~

4.5.4

The GIVING Phrase

The GIVING phrase moves the intermediate result field of an arithmetic
operation to a receiving field.
(The phrase acts exactly like a MOVE
statement with the intermediate result serving as a sending field and
the data item following the word GIVING (in the statement) serving as
a receiving field.)
The phrase may be used on the
statements.

ADD,

SUBTRACT,

MULTIPLY,

and

DIVIDE

If the data item following the word GIVING is a numeric edited field,
the OTS performs the editing the same way it does for MOVE statements.

4.5.5

Multiple Operands in ADD and SUBTRACT Statements

Both the ADD and SUBTRACT statements may contain a string of more than
one operand preceding the word TO, FROM, or GIVING.
Multiple operands in either of these statements cause the OTS to add
the string of operands together and use the intermediate result of
that operation as a single operand to be added to or subtracted from,
the receiving field.
The following three equivalent coding groups illustrate
software executes the multiple operand statements:
1.

how

Statement:

ADD ABC 0 TO E F G H.

Equivalent coding:

ADD A B, GIVING TEMP.
ADD TEMP, C, GIVING TEMP.
ADD TEMP, D, GIVING TEMP.
ADD TEMP, E, GIVING E.
ADD TEMP, F GIVING F.
ADD TEMP, G GIVING G.
ADD TEMP, H GIVING H.

Statement:

SUBTRACT A, B, C, FROM D.

Equivalent coding:

ADD A, B, GIVING TEMP.
ADD TEMP, C GIVING TEMP.
SUBTRACT TEMP FROM D GIVING D.

Statement:

ADD ABC D GIVING E.

Equivalent coding:

ADD A B GIVING TEMP.
ADD TEMP C GIVING TEMP.
ADD TEMP D GIVING E.
4-15

the

NUMERIC CHARACTER HANDLING
(Just as with all COBOL statements, any commas in these statements are
optional.)
Only statement 3 may have a numeric edited rece1v1ng field,
is the only statement containing a GIVING phrase.

4.5.6

since

stores

the

The ADD Statement

The ADD statement adds two or more operands together
result.

and

The statement may contain multiple operands
(with the exception of
Format 3)
and the ROUNDED and SIZE ERROR phrases.
It may be written
in one of the following formats:
Format 1.

ADD FIELDI ..• TO FIELD2 FIELD3 . • . .

Format 2.

ADD FIELDI FIELD2 .•. GIVING FIELD3 FIELD4

Format 3.

ADD CORRESPONDING FIELDI TO FIELD2.

In Format 1, the receiving fields
(FIELD2, FIELD3)
are one
addends.
These must not be in the numeric edited category.

the.

In Format 2, the receiving fields (FIELD3, FIELD4) are not one of the
addends.
They may either be numeric or numeric edited. When using
this format, omit the word TO.
In Format 3, the receiving field (FIELD2) is one of the addends.
Both
FIELDl and FIELD2 must be group items. The corresponding elements of
FIELDl are added to the corresponding elements of FIELD2.

4.5.7

The SUBTRACT Statement

The SUBTRACT statement subtracts one, or the sum of
operands from another operand and stores the result.

two

more,

The statement may contain multiple operands
(with the exception of
It may be written
Format 3)
and the ROUNDED and SIZE ERROR phrases.
in one of the following formats:
Format 1.

SUBTRACT FIELDI

Format 2.

SUBTRACT FIELDl
FROM FIELD2
GIVING FIELD3 FIELD4

Format 3.

SUBTRACT CORRESPONDING FIELDI FROM FIELD2.

FROM FIELD2 FIELD3

In Format 1, the rece1v1ng fields
(FIELD2, FIELD3)
are both the
subtrahend and the difference (the result). These must not be in the
numeric edited category.
In Format 2, the receiving fields (FIELD3, FIELD4) are used only
store the result. They may be either numeric or numeric edited.

In Format 3, the receiving field (FIELD2) is both the subtrahend and
the difference (results).
Both FIELDl and FIELD2 must be group items.
The corresponding elements of FIELD2.

4-16

NUMERIC CHARACTER HANDLING
4.5.8

The MULTIPLY Statement

The MULTIPLY statement multiplies one operand by
the result.

another

and

stores

The statement may contain the ROUNDED and SIZE ERROR phrases. It may
contain multiple receIvIng operands.
It may be written in either of
the following formats:
Format 1.

MULTIPLY FIELDI BY FIELD2, FIELD3 . . . .

Format 2.

MULTIPLY FIELDI BY FIELD2 GIVING FIELD3, FIELD4 . . . .

In Format 1,
multipliers.
In Format
multiplier
edited.

the receiving fields
(FIELD2, FIELD3)
are also
These must not be in the numeric edited category.
2, the receiving
nor multiplicand.

the

fields
(FIELD3, FIELD4)
are neither
These may be either numeric or numeric

COBOLls "near English" format could cause a problem with the MULTIPLY
statement,
since it is common to speak of multiplying a number
(multiplicand) by another number (multiplier)
and to think of the
result as a new value for the multiplicand;
thus:
MULTIPLY EARNINGS BY 0.24.
~

~ultiplier

Multiplicand
This statement is incorrect since the OTS stores the result in the
multiplier field,
and this multiplier is a literal. The compiler
could diagnose this error, but would not diagnose it if the multiplier
were a data item. Consider this multiplier written as a data item:
MULTIPLY EARNINGS BY TAX-RATE.
The compiler would not diagnose this statement1s error,
and would
store the result of the operation in TAX-RATE. A good practice when
using MULTIPLY statements is to always write them in Format 2.
This
ensures that the result is properly stored.
The following two
statements safely capture their results:
MULTIPLY EARNINGS BY 0.24 GIVING EARNINGS.
or
MULTIPLY EARNINGS BY TAX-RATE GIVING EARNINGS.

4.5.9

The DIVIDE Statement

The DIVIDE statement divides one operand into another and
result.

stores

the

The statement may contain the ROUNDED and SIZE ERROR phrases.
With
the exception of Formats 4 and 5,
it may not contain multiple
receiving operands. It may be written in any of the following
formats:

4-17

NUMERIC CHARACTER HANDLING
Format 1.

DIVIDE FIELDI INTO FIELD2 FIELD3

Format 2.

DIVIDE FIELDI INTO FIELD2 GIVING FIELD3 FIELD4 • • . .

Format 3.

DIVIDE FIELD2 BY FIELDI GIVING FIELD3 FIELD4 • . . .

Format 4.

DIVIDE FIELDI INTO FIELD2 GIVING FIELD3 REMAINDER
FIELD4.

Format 5.

DIVIDE FIELDI BY FIELD2 GIVING FIELD3 REMAINDER
FIELD4.

In Format 1,
the receiving fields
(FIELD2, FIELD3)
are also
dividends. These must not be in the numeric edited category.

the

In Formats 2 and 3, the receIvIng fields
(FIELD3, FIELD4
are
neither dividends nor divisor. These may be either numeric or numeric
edited.
In Formats 4 and 5, the receiving field (FIELD3) is neither a dividend
nor a divisor.
FIELD4 is the remainder. The receiving field and the
remainder may be either numeric or numeric edited.

4.5.10

The COMPUTE Statement

The COMPUTE statement computes the value of an
and stores the value in the result.

arithmetic

expression

The statement may contain the ROUNDED and SIZE ERROR phrases.
It may
contain multiple receiving operands. The COMPUTE statement has the
following format:
COMPUTE FIELDI FIELD2

arithmetic-expression.

The receiving fields (FIELDl, FIELD2) may be either numeric or numeric
edited.

4.5.11

Common Errors, Arithmetic Statements

The most common errors made when using arithmetic statements are:
•

Using an alphanumeric class field in an arithmetic statem~nt.
The MOVE statement allows data movement between alphanumeric
class fields and certain numeric class fields, but arithmetic
statements require that all fields be numeric.

•

Writing the ADD or SUBTRACT statements without the GIVING
phrase,
but attempting to put the result into a numeric
edited field.

•

Writing a Format 2 ADD
example:

statement

with

the

word

TO;

For

ADD A TO B GIVING C.
•

Subtracting a 1 from a numeric counter that was described as
an unsigned quantity,
and testing for a value of less than
zero.

4-18

NUMERIC CHARACTER HANDLING

4.6

4.6.1

•

Forgetting that the MULTIPLY statement, without the GIVING
phrase, stores the result back into the second operand
(multiplier) .

•

Performing a series of calculations in such a way as to
generate an intermediate result that is larger than 18 digits
when the final result will be fewer digits.
(The programmer
should
be
careful
to
intersperse
divisions
with
multiplications or to drop non-significant digits that result
from multiplying large numbers (or numbers with many decimal
places).

•

Performing an operation on a field that contains
greater than the precision of its data description.
happen only if the field was disarranged by a group
redefinition.

•

Forgetting that,
in an arithmetic
statment
containing
multiple
receiVIng fields,
the ROUNDED phrase must be
specified for each receiving field that is to be rounded.

•

Forgetting that,
in an arithmetic statement
containing
multiple receIving fields,
the ON SIZE ERROR phrase, if
specified, applies to all receiving fields.
Only those
receiving operands for which a size error condition is raised
are left unaltered. The ON SIZE ERROR imperative statement
is executed after all the receiving fields are processed by
the OTS.

a value
This can
move or

ARITHMETIC EXPRESSION PROCESSING

Motivation for Intermediate Results

COBOL provides language facilities for manipulating user-defined data
arithmetically.
In particular, the language provides the arithmetic
statements ADD, SUBTRACT, MULTIPLY, and DIVIDE and the facilities of
arithmetic expressions using the +, -, *, I, and ** operators. In
simple terms, a given arithmetic functionality may be expressed in one
of several ways.
For example, consider a COBOL application in which
the total yearly sales of a salesman are to be computed as the sum of
the four individual sales quarters.
Figure 4-6 illustrates one method
of expressing a solution to this problem in COBOL:

4-19

NUMr.RIC CHARACTER HANDLING

MOVE 0 TO TEMP.
ADD 1ST-SALES TO TEMP.
ADD 2ND-SALES TO TEMP.
ADD 3RD-SALES TO TEMP.
ADD 4TH-SALES TO TEMP GIVING TOTAL-SALES.

Figure 4-6

Explicit Programmer-Defined Temporary Work Area

In figure 4-6, the COBOL programmer chooses to use a series of single
ADD statements to develop the final value for TOTAL-SALES. In the
process of computing TOTAL-SALES, a COBOL data-name, called TEMP,
is
used to develop the partial sums (i.e., intermediate results). The
important point here is that the programmer explicitly defines and
declares the temporary work area TEMP in the data division of the
COBOL program. That is, the attributes (i.e., class, USAGE, number of
integer and decimal places to be maintained) are specified explicitly
by the COBOL programmer.
Figure 4-7 below illustrates another way of expressing a
the problem:

solution

ADD 1ST-SALES, 2ND-SALES, 3RD-SALES, 4TH-SALES
GIVING TOTAL-SALES.

Figure 4-7
Arithmetic Statement Intermediate Result Field Attributes
Determined from Composite of Operands

4-20

NUMERIC CHARACTER HANDLING
In this example, the programmer chooses to compute TOTAL-SALES with a
single
ADD
statement.
Analogous to the previous example, an
intermediate result. field is required to develop the partial sums of
the four quarterly sales quantities.
In Figures 4-6, the programmer
is cognizant of this requirement, but chose to define the intermediate
result area TEMP explicitly in the data division of his COBOL program.
However, for the example in Figure 4-7, the software defines the
intermediate result field in a manner transparent to the COBOL source
program. That is, the software allocates storage for and assigns
various attributes to this "transparent" intermediate result field
according to a well-defined set of rules defined by the COBOL language
specification.
In
particular,
the
attributes
of
number-of-integer-places, number-of-decimal-places, and USAGE assigned
by the software to the intermediate result field are a function of the
composite of source operands in the ADD statement.
(The reader should
read the TRAX COBOL Language Reference Manual for details concerning
the composite of operands for the arithmetic statements.) The important
point here is that the ANS-74 COBOL language standard prescribes rules
for determining the attributes of intermediate result fields for
the
arithmetic statements and the associated language processor (e.g.,
TRAX COBOL compiler) must implement those rules.
As a final example, consider the following solution to our problem:

COMPUTE TOTAL-SALES = 1ST-SALES + 2ND-SALES + 3RD-SALES
+ 4TH-SALES.

Figure 4-8
Arithmetic Expression Intermediate Result Field
Attributes Determined by Implementor-Defined Rules
In Figure 4-8, the programmer solves the problem by using a single
COMPUTE statement with an embedded arithmetic expression. Again, an
intermediate result field is required and, as in Figure 4-7,
is
defined by the software.
However,
in defining the attributes of
intermediate result fields for COBOL arithmetic expressions,
the
ANS-74 COBOL language standard is not as helpful to the user as it
could be.
In fact, the COBOL language standard gives almost complete
freedom
to the implementor in defining the attributes of the
arithmetic expression intermediate result fields.
The only rules
imposed by the ANS-74 COBOL language specifications are:
1.

Arithmetic operations are to be combined without restrictions
on the composite of operands and/or receiving fields.

Each implementor will indicate techniques
arithmetic expressions.

4-21

used

handling

NUMERIC CHARACTER HANDLING
Thus, the user can and should expect differences between various
implementations of ANS-74 COBOL. The purpose of the remainder of this
section is to specify the conceptual algorithms used by the software
to compute the attributes for the arithmetic expression intermediate
result
field;
i.e.,
the
number-of-integer-places
and
number-of-decimal-places to be maintained (for a given intermediate
result field) as a function of a particular arithmetic operator and
its associated operands.

4.6.2

Intermediate Results for Arithmetic Expressions

In the compile-time and object-time
processing
of
arithmetic
expressions, the software maintains a maximum precision of 18 decimal
digits for intermediate result fields. One of the major compile-time
functions in processing an arithmetic expression operator x is to
determine the following attributes for the associated object-time
intermediate result field IR(x):
1.

USAGE type,

number. of integer places, I(IR(x», to be maintained, and

number of decimal places, D(IR(x», to be maintained.

All arithmetic expression intermediate result fields are treated as
signed data.
The software must determine the USAGE type for an
intermediate result in order to determine the form of its internal
representation;
the number of integer places and decimal places are
determined to know how much object-time storage is required for the
intermediate result.
With the exception of the exponentiation operator
(**),
all infix
arithmetic operators yield an intermediate result field whose USAGE
type is determined as a function of the USAGE types of its two source
operands.
That is, if both source operands are DISPLAY, the USAGE
type for the intermediate result field is also DISPLAY. If one of the
operands
associated
with
an
infix operator has a USAGE IS
COMPUTATIONAL declaration, the USAGE type of the intermediate result
field
is also COMPUTATIONAL (i.e., the intermediate result is
represented as COMPUTATIONAL data at object-time). The USAGE type of
an intermediate result for the exponentiation operator is the same
USAGE type as its first operand. Moreover, the only unary operator
which requires an intermediate result field is the unary negate
operator. In this case, the USAGE type of its intermediate result is
the same as its singular operand.
The unary plus operator is
essentially a "no-op" operator and, thus, is ignored at compile-time
and has no impact at object-time.
The process of determining the final number of integer places I(IR(x»
and the final number of decimal places D(IR(x»
to be maintained for
an intermediate result field IR(x)
resulting from an arithmetic
expression operator x is conceptually the five step pr~cedure outlined
in Figure 4-9 below. In computing the final values for I(IR(x»
and
D(IR(x», remember that these values are subject to the following
criterion:
1<= I(IR(x»

+ D(IR(x»

<= 18.

That is, a maximum prec~s~on of 18 decimal digits is maintained for an
intermediate result field.

4-22

NUMERIC CHARACTER HANDLING
1.

Record the largest number of integer places, lMAX, declared
for any source operand in an entire COBOL expression.

Record the largest number of decimal places, DMAX, declared
for any source operand in an entire COBOL expression.

Compute the number of integer places, l(x), and number of
decimal places, D(x), for an arithmetic expression operator x
as a function of the operands associated with operator x.

Using IMAX, DMAX, I(x), and D(x) computed
following criterion and redefinition:

above,

If IMAX > I(x) then redefine I(x)

IMAX.

If DMAX > D(x) then redefine D(x)

DMAX.

apply

the

using the (possible redefined) values of I(x) and D(x) from
step 4, apply truncation criterion to determine the final
values I(lR(x» and D(IR(x).

Figure 4-9 Procedure to Determine I(IR(x» and D(IR(x»
for an Arithmetic Expression Result Field IR
Before pursuing the procedure outlined in Figure 4-9 in more depth,
the following notational conventions are adopted to facilitate the
subsequent discussion:
x

the

set

IR (x)

Intermediate result field obtained
from
execution of an arithmetic operation x.

the

OPl(x)

First operand in arithmetic operation x.

OP2(x)

Second operand in arithmetic operation x.

I(OPl(x)

Number of integer places
arithmetic operation x.

declared

for

OPl

D(OPl(x»

Number of decimal places
arithmetic operation x.

declared

for

OPl

I (OP2 (x) )

Number of integer places
arithmetic operation x.

declared

for

OP2

D(OP2(x»

Number of decimal places
arithmetic operation x.

declared

for

OP2

lMAX

Maximum of number of integer places for any source
operand
(except
for
exponents) in a COBOL
expression.

DMAX

Maximum number of decimal places for any source
operand
(except
for
exponents) in a COBOL
expression.

I (x)

Number of integer places for
an
arithmetic
expression operator x computed as a function of
the operator's source operands.

COBOL expression
operator
+,-,*,/,**, and unary -.

4-23

from

NUMERIC CHARACTER HANDLING
D (x)

Number of decimal places for
an
arithmetic
expression operator x computed as a function of
the operator's source operand(s).

I (IR(x»

Final number of integer places to be maintained
for an intermediate result IR obtained by the
execution of operator x.

D(IR(x) )

Final number of decimal places to be maintained
for an intermediate result IR obtained by the
execution of operator x.

To determine the values for IMAX and DMAX (i.e., steps I and 2, Figure
4-9), the compile-time software inspects the operands of arithmetic
operators and all data-name references which are compared to an
arithmetic expression in relation conditions.
In the process of
inspecting the operands of arithmetic expressions, the software
ignores OP2 of the exponentiate (**) operator. Moreover, since the
software essentially "forgets" the presence of an unary plus operator,
its singular operand has no role in the determination of IMAX and
DMAX. Having determined the values of IMAX and DMAX, the software
then iteratively applies steps 3 through 5 of the procedure to each
arithmetic operator in an arithmetic expression. The algorithms for
computing I(x) and D(x) are summarized below:
Unary Negate (x

"_H)

I (unary -) = I(OPI(unary -»
D(unary -) = D(OPl(unary -»
Addition (x = "+")
1(+)

MAX(I(OPI(+», I(OP2(+») + 1

D (+ )

MAX (D (OP 1 (+) ), D (OP 2 (+) ) )

Subtraction (x

= "_H)

I (-)

MAX (I (OPI (+) ), I (OPI (-) »

D (-)

MAX (D (OPI (-», D (OPI (-»)

Multiplication (x

+ 1

= "*")

1(*) = I(OPl(*»

+ I(OP2(*»

D ( * ) = D (OP I (*»

+ D (OP 2 ( *) )

Division (x = "I")
I (I) = I (OP 1 (I»
D (I)

+ D (OP 2 (I) )

MAX (D (OP I (I) ), D (OP 2 (I) »

4-24

+ 1

NUMERIC CHARACTER HANDLING
Exponentiation (x = "**")
Case 1:

OP2(**) is a data-name exponent:
I (* *) = I (OP 1 ( * *»
where:

I(OP2(**»

* F (I (OP 2 ( * *) ) )
F (I (OP2 (**»)

o OR 1

> 1

0(**) = DMAX
Case 2:

OP2(**) is a numeric integer literal exponent
I (**)

I(OPl(**»

* OP2(**)

0(**)

D(OPl(**»

* OP2(**)

with the values of I(x), D(x)
IMAX, and DMAX known, the software
applies step 4 of Figure 4-9 to possibly redefine the values of I(X)
and D(x) in light of the known values of IMAX and DMAX.
The purpose
of step 4 is to ensure that the object-time software will maintain
sufficient precision for intermediate field IR resulting from an
arithmetic operation in the context in which that arithmetic operation
occurs. Finally, step 5 applies the truncation criterion specified in
Figure 4-9 to determine the final values of I(IR(x» and D(IR(x».
I (x) + 0 (x)

o (x)

I (x) + DMAX

f-----<J!!.---

Any
Value

I (IR(x»
D(lR(x»

< DMAX

Any

l(IR(x) = 18 - D(x) [High order trunc]

Value

D(IR(x»

<18

I(IR(x) = I (x)

=18

D(lR(x»

= IB

>18

I(lR(x»

= 18 - DMAX [high order trunc]

D(lR(x»

= DMAX[Low order trunc]

=18

....

= I (x)
= o (x)

----= DMAX

>18

Compiler Action

>DMAX

---------

= D(x)

- l(x) [low order trunc]

Figure 4-10
Truncation Criterion and I(IR(x»and D(lR(x»

4-25

Computation

NUMERIC CHARACTER HANDLING
Example of Intermediate Result Fields

4.6.3

Figure 4-11 illustrates the application of the conceptual algorithms
for computing the attributes of intermediate result fields.

PIC

999V99

PIC

99V9

PIC

99V999

IF A + 2

* B

USAGE IS DISPLAY.
USAGE IS COMPUTATIONAL.
USAGE IS DISPLAY.

C GO TO TAG-I.

Figure 4-11
Example of Intermediate Results
The IF statement given in Figure 4-11 contains a
relation condition
which specifies the comparison of an arithmetic expression to a
data-name. The arithmetic expression "A + 2 * B" gives rise
to the
creation of the following intermediate result fields:
IR' (*)
IR" (+)

2 * B
+ IR (+)

where the "primes" indicate the order in which the intermediate result
fields
are created.
The major problem here is to determine the USAGE
types of IR' and IR", respectively, and to determine the values of
I(IR'(*», D(IR'(*», I(IR"(+», and D(IR"(+».
To begin the development of solution, we observe that the USAGE of
IR' (*)
is COMPUTATIONAL since OP2(*) = B has a COMPUTATIONAL USAGE.
Then, it follows that the USAGE of IR"(+)
is COMPUTATIONAL since
OP2(+)
= IR' (*) has a COMPUTATIONAL USAGE type. Now, before applying
the five step procedure in Figure 4-9, the following conditions are
obtained from the declarations of A,B,C, and the specification of the
IF statement in Figure 4-11:
I(OPl(*»

land D(OPl(*»

o for OPl(*) =2,

I (OP2 (*»

2 and D(OP2(*»

1 for OP2 (*) = B,

I(OPl(+»

3 and D(OPl(+)

= 2 for OPl(+) = A,

I(C) = 2 and C(C) = 3 for the C dataname reference.
4-26

NUMERIC CHARACTER HANDLING
It should be noted, that since OP2(+) = "2 * B" is not a data name or
literal reference, OP2(+) does not enter into the specification of the
initial conditions, and therefore into the computation of the values
for IMAX and DMAX. Further, we note the values of I(C) and D(C) for
the dataname C reference since the relation condition involves the
comparison of an arithmetic expression to a data name reference. The
values of I(C) and D(C) are needed for the subsequent calculation of
IMAX and DMAX for the COBOL expression "A + 2 * B = Cu.
Given these initial conditions, now apply step 1 and 2 of
to calculate the values of IMAX and DMAX:
I MAX

MAX (I (OP 1 (+) ), I (OP 1 (*) ), I (OP 2 (*) ), I (C) )

IMAX

MAX(3,1,2,2)

Figure

4-3

IMAX = 3
DMAX

MAX(D(OPl(+», D(OPl(*», D(OP2(*», D(C»

DMAX

MAX(2,O,1,3)

DMAX

Therefore, from the application of steps 1 and 2, IMAX = 3 and DMAX
3 for the COBOL expression "A + 2 * B = Cu. Next, iteratively apply
steps 3-5 to each arithmetic expression operator ( in the order in
which the expression is evaluated at run time) to determine the values
of I(IR'(*», D(IR'(*», I(IR"(+», and D(IR"(+».
Thus, applying
step 3 to OPl(*) and OP2(*), we determine the following values for
I ( * ) and D ( *) :
I (*)

I (OPI (*»

+ I (OP2 (*) )

1(*) = 1 + 2
I (*)

D(*)

D(OPl(*»

+ D(OP2(*»

D(*) = 0 + 1

D(*)

with 1(*)
3 and D(*) = 1 determined from step 3, now apply step 4 to
discover that 1(*) = 3 and D(*) is redefined to 3 since DMAX > D(*) =
1. Thus, step 4 yields the following values:
I (*)

D(*) = 3
Finally, apply step 5 to the values of 1(*) and D(*) to yield
I(IR'(*)} = 3
D(IR' (*)}

since
1(*) + D(*) < 18.
Thus, the object-time software will maintain three integer places and
three decimal places for IR' (*) resulting from the evaluation of "2 *
B".

4-27

NUMERIC CHARACTER HAND~ING
We wish to apply steps 3-5 to OPl(+)
and OP2(+)
to determine the
values for I(IR"(+»
and D(IR"(+».
Note that, sinceOP2(+)
IR' (*), we have the following values for I(OP2(+»
and D(OP2(+»:
I(OP2(+»
I(OP2(+»

I(IR'(*»
= 3

D(OP2(+»

D(IR'(*»

D(OP2(+»

3•

with I(+) = 4 and 0(+) = 3 determined from step 3 of Figure 4-9, now
apply step 4 to find that I(+) = 4 and 0(+) = 3 remain unchanged since
IMAX < 1(+) and DMAX = D(+).
Finally, apply step 5 to the values of
I(+) and 0(+) to yield:
I(IR"(+»

D(IR"(+»

I (+) + 0(+)

< 18.

since

Hence, the object-time software will maintain four integer places and
three decimal places for IR" (+) resulting from the evaluation of "A +
2 * B = C".

4-28

CHAPTER 5
TABLE HANDLING

5.1

INTRODUCTION

with COBOL, as with any other language, any data item to which the
program
refers
must
be
uniquely
identified.
This
unique
identification of data items is usually accomplished by assigning a
unique name to each item.
However,
in many applications this is
tedious and inconvenient;
often programs require too many names for
items that have different names but contain the same type of
information. Tables provide a simple solution to this problem.
TRAX
COBOL includes full table handling capabilities as outlined for
standard COBOL in the 1974 ANSI Standards.
A table is a
repetition of one item
(element)
in memory.
This
repetition is accomplished by the use of the OCCURS clause in the data
description entry. The literal value in the OCCURS clause causes the
software to duplicate the data description entry as many times as
indicated by that value, thus creating a matrix or table.
The elements may be initialized with the VALUE clause or with a
procedural
instruction.
They
may
contain
synchronized
or
unsynchronized data. They may be accessed only with subscripted
procedural instructions.
A subscript is a parenthesized integer or
data name (with an integer value). The integer value represents the
desired occurrence of the element.
This chapter discusses how to set up tables and access them accurately
and efficiently.
It attempts to cover any problems that may be
encountered while handling tables. Read it through carefully before
setting up tables with TRAX COBOL. Sections 4 and 5 of the TRAX COBOL
Lan~uage
Reference Manual contains reference information on the
ind1vidual table handling instructions (OCCURS, USAGE IS INDEX, SET,
and SEARCH) •

5.2

DEFINING TABLES

To define a table with TRAX COBOL, simply complete a standard data
description for one element of the table and follow it with an OCCURS
clause. The OCCURS clause contains an integer which dictates the
number of times that element will be repeated in memory, thus creating
a table.

5-1

TABLE HANDLING
The OCCURS phrase has two formats:
Format 1
OCCURS integer-2 TIMES
ASCENDING }
[{ DESCENDING

KEY ~S data-name-2

[INDEXED BY index-name-l

[, data-name-3]

[, index-name-2]

. ·.

]

... ]

Format 2
OCCURS integer-l TO integer-2 TIMES DEPENDING ON data-name-l
ASCENDING }
[{ DESCENDING

KEY IS data-name-2

[INDEXED BY index-name-l

[. data-name-3]

[, index-name-2]

••. ]

... ]

In either format, the system generates a buffer large enough to
accommodate integer-2 occurrences of the data description. Therefore,
the amount of storage allocated in either case is equal to the amount
of storage required to repeat the data entry integer-2 times.
The software will automatically map the elements into memory.
When
mapping a table into memory,
the software follows the rules for
mapping which depend on whether the element contains synchronized
items or not.
If they do not contain synchronized items, the software
maps them into adjacent memory locations and the size of the table can
be easily calculated by multiplying the size of the element times the
number of occurrences (5XlO for the table illustrated in Figure 5-1,
or 50 bytes of memory) .
01 A-TABLE
03 A-GROUP PIC X(5} OCCURS 10 TIMES.
Figure 5-1
Defining a Table

5.2.1

The OCCURS Phrase - Format 1

When Format 1 is used, a fixed length table is generated, whose length
(number of occurrences) is equal to the value specified by integer-2.
This format is useful for storing large amounts of frequently used
reference data whose size never changes. Tax tables, used in payroll
deduction programs, are an excellent example of where a Format 1
(fixed length) table might be used.

5.2.2

The OCCURS Phrase - Format 2

Format 2 is used to generate variable length tables.
When used,
a
table whose length
(number of occurrences)
is equal to the value
specified by data-name-l is generated.

5-2

TABLE HANDLING
NOTE
Data-name-l must always be a positive
integer whose value is equal to or
greater than integer-l but not greater
than integer-2.
Unlike format 1 tables, the number of occurrences of data items in
format 2 tab1es can be dynamically expanded or reduced to satisfy user
needs.
By generating a variable length table, the user is, in effect, saying;
"build me a table that can contain at least integer-l occurrences, but
no more than integer-2 occurrences, and set its number of occurrences
equal to the value specified by data-name-l".
Data-name-l always reflects the number of occurrences available for
user access. To expand the size (number of occurrences available for
use) of a table, the user need only increase the value of data-name-l
accordingly.
Likewise, reducing the value in data-name-l will reduce the number
occurrences available for user access.

5.3

MAPPING TABLE ELEMENTS

As mentioned in Section 5.2, when the software detects an OCCURS
clause in an unsynchronized item,
it maps the table elements into
adjacent locations in memory. Consider the following data description
of a simple table and the way it is mapped into memory:
Table Description:

01 A-TABLE.
03 A-GROUP PIC X(5) OCCURS 10 TIMES.

Memory Map:
words
bytes
A-GROUP
Figure 5-2
Mapping a Table into Memory
The data description in Figure 5-2 causes the software to set up ten
items of five bytes each
(elements)
and place them in adjacent
ascending memory locations for a total of 50 character positions, thus
creating a table.
Since the length of each A-GROUP element is odd
(5), the memory addresses of each subsequent element will alternate
between odd and even locations.
The SYNCHRONIZED clause causes the software to add a fill byte to
items that contain an odd number of bytes, thereby making the number
of bytes in that item even.
This ensures that each subsequent
occurrence of the element will not alternate between odd and even
addresses, but will map the same (odd or even) as the first repetition
of that element.

5-3

TABLE HANDLING
If the data description of A-GROUP contained a SYNCHRONIZED clause,
the software would map it quite differently.
If A-GROUP were
synchronized, it would expand its length to three words.
The item
will, by default, be synchronized to the left occupying the first five
characters of the three words.
The software supplies a padding
character to fill out the third word. This padding character is not a
part of the A-GROUP element and table instructions referring to
A-TABLE will not detect the presence or absence of the character.
The padding character does, however, affect the overall length of the
group item and,
hence, the table.
Without the SYNCHRONIZED clause,
A-TABLE required only 50 character positions;
now, with the clause,
it requires 60 character positions.
(This length includes the last
padding character -- following the tenth element in the table.)
Although the SYNCHRONIZED clause has little value when used with
alphanumeric fields,
an understanding of the concept is essential
before attempting to use COMP and INDEX data items in tables.
The
software automatically synchronizes all COMP and INDEX usage data
items, and will most probably alter the size of any table
(often
drastically)
that contains these data types. Consider the following
illustration of a synchronized data item being mapped by the software:
Table Description:

01 A-TABLE.
03 A-GROUP OCCURS 20 TIMES.
05 ITEMI PIC X.
05 ITEM2 PIC S999 COMPo

l--ITEMI
2--ITEM2
S--SLACK
BYTE

Memory Map:
words
bytes
A-GROUP

A-GROUP

Figure 5-3
Synchronized COMP Item in a Table
Since the software synchronizes the ITEM2 fields (COMP), these fields
each occupy a single word in memory;
thus, a slack byte follows each
occurrence of ITEMI. Each repetition of A-GROUP consumes four bytes
of memory -- one byte for ITEMl, one byte for the slack byte, and two
bytes for ITEM2. A-TABLE, then,
requires 80 bytes of memory
(20
elements of four bytes each).
Now, consider the effect of adding a I-byte field to A-TABLE.
If we
place the field between ITEMI and ITEM2,
it will take the space
formerly occupied by the slack byte. This has the effect of adding a
data byte but leaving the size of the table unchanged. Consider the
following illustration:

5-4

TABLE HANDLING
Table Description:

01 A-TABLE.
03 A-GROUP
05 ITEMI
05 ITEM3
05 ITEM2

OCCURS 20 TIMES.
PIC X.
PIC X.
PIC S999 COMP.
l--ITEMI
2--ITEM2
3--ITEM3

Memory Map:
words
bytes

~...
...
A-GROUP

A-GROUP

Figure 5-4
Adding a Field without Altering the Table Size

If, however, we place the I-byte field after ITEM2, it has the effect
of adding
its own length plus another slack byte. Now, each element
requires six full bytes and the complete table consumes 120 bytes of
memory
(6X20)!
This is due to the fact that the first repetition of
ITEMI falls on an even byte and, in order to keep the mapping of each
A-GROUP element the same,
the software allocates each successive
repetition of ITEMI to an even byte address. Thus, it assigns ITEM3
to the even byte of the third word and adds a slack byte to guarantee
that the next element begins on an even byte. Consider the
following
illustration:
Table Description:

01 A-TABLE.
03 A-GROUP OCCURS 20 TIMES.
05 ITEMI PIC X.
05 ITEM2 PIC S999 COMP.
05 ITEM3 PIC X.

l>'lemory Map:
Odd or Even
words
bytes

E 0 E 0 E 0 E 0 E 0 E 0 E 0 E 0 E 0

A-GROUP

Figure 5-5
Adding One Byte which Adds Two Bytes
to the Element Length
NOTE
The illustrations in this section show
each byte with an even address (E) as
the leftmost byte, and each byte with an
odd address
(0) as the rightmost byte.
(The two bytes,
odd and even,
are
reversed in actual memory.)

5-5

TABLE HANDLING
If, however, we use a FILLER byte to force the first allocation of
ITEM1 to occur on an odd byte, A-GROUP again requires only four bytes
and no slack bytes. Figure 5-6 illustrates this.
Since the FILLER
item occupies the even byte of the first word, ITEMI falls on an odd
byte. The software requires that each repetition of ITEMI must be an
even number of bytes in length in order to guarantee that the
synchronized item(s) will map onto word boundaries.
No slack bytes
are needed and A-GROUP elements are again only four bytes long, and
A-TABLE requires only 81 bytes.
Table Description:

01 A-TABLE.
03 FILLER PIC X.
03 A-GROUP OCCURS 20 TIMES.
05 ITEMI PIC X.
05 ITEM2 PIC S999 COMPo
05 ITEM3 PIC X.

Memory Map:
odd or even
words
bytes

E 0

F 1

2 2

3 1

2 2

3 1

2 2

...

J:lilllilllilllilihllliBf I .·.

FILLER

A-GROUP

..•

A-GROUP

Figure 5-6
Forcing an Odd Address By Adding a I-Byte FILLER
Item to the Head of the Table
If we try to force ITEMI onto an odd byte with a SYNCHRONIZED RIGHT
clause,
the software maps ITEMI into the odd byte, but prohibits all
repetitions of the element from using the even byte. Thus, the first
repetition of A-GROUP has a slack byte at its beginning and, so that
the next element can begin (with a slack byte)
at an even address,
another slack byte
(odd) following ITEM3. This expands the element
length to six bytes and the table length to 120 bytes.
Table Description:

01 A-TABLE.
03 A-GROUP OCCURS 20 TIMES.
05 ITEMI PIC X SYNCHRONIZED RIGHT.
05 ITEM2 PIC S999 COMPo
05 ITEM3 PIC X.

Memory Map:
- Odd or Even
words
bytes
A-GROUP

A-GROUP

Figure 5-7
The Effect of a SYNCHRONIZED RIGHT Clause Instead
of a FILLER Item as shown in Figure 5-6

5-6

TABLE HANDLING
To determine how the software
following two rules:

5.3.1

will

map

given

table,

apply

the

The software maps all items in the first repetition of a
table element into memory words as with any item properly
defined with a data description, obeying any implicit or
explicit synchronization requirements.

If the first repetition contains any elementary items with
implicit or explicit synchronization, the software maps each
successive repetition of the element into memory words in the
same way as the first repetition. It does this by adding one
slack byte, if necessary, to make the size of the element
even.

Initializing Tables

If a table contains only DISPLAY items, it can be set to any desired
initial value (initialized). To initialize a table, simply specify a
VALUE phrase on the record level preceding the item containing the
OCCURS clause.
The sample data definitions, below, will set up
initialized tables:
Table Description:

01 A-TABLE VALUE IS "JANFEBMARAPRMAY
JUNJULAUGSEPOCTNOVDEC".
03 MONTH-GROUP PIC XXX USAGE DISPLAY
OCCURS 12 TIMES.

Memory Map:
words
byte contents

~~~~~~~~~~=x~~~~~~~

MONTH-GROUP
MONTH-GROUP
MONTH-GROUP
MONTij-GROUP

MONTH-GROUP
MONTH-GROUP
MONTH-GROUP
MONTH-GROUP

Figure 5-8
Initializing Tables
Often a table is too long to initialize with a single literal, or it
contains items that cannot be initialized (numeric, alphanumeric, or
CaMP). These items can be individually initialized by redefining the
group level preceding the level that contains the OCCURS clause.
Consider the following sample table descriptions:

5-7

TABLE HANDLING
Table Description:

01 A-RECORD-ALT.
05 FILLER PIC
05 FILLER PIC
05 FILLER PIC
05 FILLER PIC

XX VALUE "AX".
99 COMP VALUE 1.
XX VALUE "BX".
99 COMP VALUE 2.

01 A-RECORD REDEFINES A-RECORD-ALT.
03 A-GROUP OCCURS 26 TIMES.
05 ITEMI PIC X.
05 ITEM2 PIC S99 COMPo

~BinarY2

Memory Map:
words
byte contents at
initialization time

I
II
A X

III IV

A-GROUP

..•
B X

Figure 5-9
Initializing Mixed Usage Fields
In the preceding example, the slack bytes in the
(ITEMl) are being initialized to X.
Table Description:

alphanumeric

fields

01 A-RECORD-ALT.
03 FILLER PIC X(30) VALUE IS
IIAAAAAAAAAABBBBBBBBBBCCCCCCCCCC".
03 FILLER PIC X(30) VALUE IS
."DDDDDDDDDDEEEEEEEEEEFFFFFFFFFF".
(e tc . )
01 A-RECORD REDEFINES A-RECORD-ALT.
03 ITEMI PIX X(lO) OCCURS 26 TIMES.

l'v'lemo r y Map:
word
byte
contents at
initialization
time

ITEMl

Figure 5-10
Initializing Alphanumeric Fields
In the preceding example, each FILLER item initializes
table elements.

three

lO-byte

When redefining or initializing table elements, allow space for
any
slack bytes that may be added due to synchronization (implicit or
explicit).
The slack bytes do not have to be initialized;
however,
they may be and, if initialized to an uncommon value, they may even
serve as a debugging aid for situations such as a statement referring
to the record level above the OCCURS clause or
another record
redefining that level.

5-8

TABLE HANDLING
Sometimes the length and format of table items are such that they
would best be initialized by statements in the Procedure Division.
This initialization coding could be executed once and then overlaid
(due to the automatic segmentation feature) if the entire Procedure
Division is too large to be held in memory at one time.
Once the OCCURS clauses have established the necessary tables, the
program
must be able to access the elements of those tables
individually. Subscripting and indexing are the two methods provided
by COBOL for accessing individual elements.

5.4

SUBSCRIPTING AND INDEXING

To refer to a particular element within a table, simply follow the
name of the desired element with a parenthesized subscript or index.
A subscript is an integer or a data-name that has an integer value;
the integer value represents the aesired occurrence of the element
an integer value of 3, for example, refers to the third occurrence of
the element.
An index is a data-name that has been named in an
INDEXED BY phrase in the OCCURS clause.

5.4.1

Subscripting with Literals

A literal subscript is simply a parenthesized integer whose value
represents the occurrence number of the desired element. In figure
S-ll, the literal subscript in the MOVE instruction (2) causes the
software to move the contents of the second element of the table,
A-TABLE, to I-RECORD.
01 A-TABLE.
03 A-GROUP PIC XeS)
OCCURS 10 TIMES.

Table Description
Procedural Instruction

MOVE A-GROUP(2) TO I-RECORD.

Figure S-ll
Literal Subscripting
If the table has more than one level (or dimension), follow the name
of the desired item with a list of subscripts, one for each OCCURS
clause to which the item is subordinate. The first subscript in the
list applies to the first OCCURS clause to which the item is
subordinate.
(This is the most encompassing level -- A-GROUP in the
following example.) The second subscript in the list applies to the
next most encompassing level, and the last subscript applies to the
lowest level OCCURS clause being accessed (or the desired occurrence
number of the item named in the procedural instruction -- ITEMS in the
following example).
Consider Figure S-12; the subscripts (2,11,3) in the MOVE instruction
cause the software to move the third repetition of ITEMS in the
eleventh repetition of ITEM3 in the second repetition of A-GROUP to
I-FIELDS.
(For illustration simplicity, I-FIELDS is not defined.)
(ITEMS(l,l,l) would refer to the first occurrence of ITEMS in the
table and ITEM5(5,20,4) would refer to the last occurrence of ITEMS.)

S-9

TABLE HANDLING
01 A-TABLE.
03 A-GROUP OCCURS 5 TIMES.
05 ITEMI PIC X.
05 ITEM2 PIC 99 COMP OCCURS 20
TIMES.
05 ITEM3 OCCURS 20 TIMES.
07 ITEM4 PIC X.
07 ITEMS PIC XX OCCURS 4 TIMES.

Table Description

Procedural Instruction

MOVE ITEMS(2, 11, 3) TO I-FIELDS.

Figure 5-12
Subscripting a Multi-Dimensional Table
NOTE
Since ITEMS is not subordinate to ITEM2,
an occurrence number for ITEM2 is not
permitted in the subscript list.
Figure 5-13 summarizes the subscripting rules for each
items and shows the size of each field in bytes.

the

NAME
OF
FIELD

NUMBER OF SUBSCRIPTS
REQUIRED TO REFER TO
THE NAMED FIELD

SIZE
OF
FIELD

A-TABLE
A-GROUP
ITEMl
ITEM2
ITEM3
ITEM4
ITEMS

NONE
ONE
ONE
TWO
TWO

1110
222
1*
2

'rwo

9
1

THREE

above

* Plus a slack byte
Figure 5-13
Subscripting Rules for a
Multi-Dimensional Table

5.4.2

Operations Performed by the Software

the
When a literal subscript is used to refer to an item in a table,
software performs the following steps to determine the exact address
of the item:
1.

The compiler converts the literal to a I-word binary value.

The compiler range checks the subscript value (the value must
not be less than 1 nor greater than the number of repetitions
specified by the OCCURS clause)
and prints a diagnostic
message if the value is out of range.

The compiler decrements the value of the subscript by 1 and
multiplies it by the size of the item that contains the
OCCURS clause corresponding to this subscript,
thus forming
an index value;
it then stores this value, plus the literal
subscript, in the object program.
5-10

TABLE HANDLING
4.

5.4.3

At object execution time for a fixed length table,
the run
time system adds the index value (from 3 above) to a base
address, thus determining the address of the desired item.
For a variable length table reference, the procedure for
fixed length tables is preceded by the procedure described in
Section 5.4.6.

Subscripting with Data-Names

As discussed earlier in this section, subscripts may also be specified
using data-names instead of literals.
To use a data-name as a
subscript, simply define it as a numeric integer
(COMP or DISPLAY).
It may be signed, but the sign must be positive at the time it is used
as a subscript.
The sample subscripts in figure 5-14
accessed in Figure 5-12, (2, 11, 3).
Data Descriptions
of Subscript data-names

Procedural Instructions

refer

the

same

element

01 KEYI PIC 99 USAGE DISPLAY.
01 KEY2 PIC 99 USAGE COMP.
01 KEY3 PIC S99.
MOVE 2 TO KEYI.
MOVE 11 TO KEY2.
MOVE 3 TO KEY3.
GO TO TABLERTN.
TABLERTN.
MOVE ITEM5(KEYI KEY2 KEY3) TO
I-FIELD5.

Figure 5-14
Subscripting with Data-Names

5.4.4

Operations Performed by the OTS on Data Names

When a data-name subscript is used to refer to an item in a table, the
OTS performs the following steps at object execution time:
1.

If the data-name1s data type is DISPLAY,
converts it to a I-word binary value.

For fixed length tables,
the software range checks the
subscript value
(the value must not be less than 1 nor
greater than the number of repetitions specified by the
OCCURS clause)
and terminates the object program (with a
diagnostic message) if it is out of range.
For variable
length tables,
the procedure described in Section 5.4.6 is
followed.

The software decrements the value of the subscript by 1 and
multiplies it by the size of the item that contains the
OCCURS clause corresponding to this subscript,
thus forming
an index value.

The software adds the index value (from 3 above)
to a base
address, thus determining the address of the desired item.

5-11

the

software

TABLE HANDLING
5.4.5

Subscripting with Indexes

The same rules apply for the specification
subscripts except that the index must
phrase of the OCCURS clause.

of indexes as apply to
be named in the INDEXED BY

An index-name item (an item named in the INDEXED BY phrase of the
OCCURS clause) has the ability to hold an index value.
(The index
value is the product formed in step 3 of the operations performed by
the software for literal or data-name subscripts -- the relative
location, within the table, of the desired item.)
The compiler allocates a 2-part data item for each name that follows
an INDEXED BY phrase. These index-name items cannot be accessed as
normal data items; they cannot be moved about, redefined, written to
a file, etc.
However, the SET verb can change their values and
relation tests can examine their values.
One part of the 2-part
index-name item contains a subscript value and the other part contains
an index value. Consider the following illustration:

SUBS~~~~; :~~~ ---:~E-----------j
Figure 5-15
Index-Name Item
Whenever a SET statement places a new value in the subscript part, the
software performs an index value computation and stores the result in
the index part. Only the subscript part of the item acts as a sending
or receiving field.
The index part is never altered by any other
operation and is never moved to another item. It is used only when
the index-name is used as an index referring to a table item. The
sample MOVE statement in Figure 5-16 would move the contents of the
third repetition of A-GROUP to I-FIELD.
(For illustration simplicity,
once again, I-FIELD is not defined.)
01 A-TABLE.
03 A-GROUP OCCURS 5 TIMES
INDEXED BY INO-NAME.

Table Description
Procedural Instructions

SET IND-NAME TO 3.
MOVE A-GROUP (IND-NAME) TO I-FIELD.

Figure 5-16
Subscripting with Index-name Items

5.4.6

Operations Performed by the OTS on the SET Statement

The OTS performs
statement:

the

following

steps

when

executes

the

SET

The OTS converts the contents of the sending field of the SET
statement to a I-word binary value.

The OTS range checks the value (the value must not be less
than 1 nor greater than the number of repetitions specified
in the OCCURS clause) and terminates the object program with
a diagnostic message if it is out of range.

5-12

TABLE HANDLING
3.

The OTS decrements the value by 1 and mUltiplies it by the
size of the item that contains the OCCURS clause, thus
forming an index value.

For fixed length tables, once the SET statement has been executed and
the software has encountered the index-name item as an index, it only
has to add the index value (from 3 above) to a base address to
determine the address of the desired item. Since this is the only
action performed, the execution speed of a procedural statement with
an indexed data-name is equivalent to a reference with a literal
subscript.
For a variable length table, when the index-name is encountered as an
index, the procedure described in Section 5.4.6 is invoked before
following the fixed length table logic. However, the SET statement
itself is not impacted by the fixed/variable characteristic of the
associated table.
TRAX
COBOL initializes the value of all index-name items to a
subscript value of 1 (index value of 0), hence an attempt to use an
index-name item as an index before it has been the receiving field of
a SET verb will not result in an out-of-range termination.
NOTE
Initialization of index-name items is an
extension to the ANSI COBOL standards.
Users concerned with writing TRAX COBOL
programs that adhere to standard COBOL
should not rely on this feature.

5.4.7

Relative Indexing

To perform relative indexing, when referring to a table item, simply
follow the index-name with a plus or minus sign and an integer
literal. Relative indexing, albeit easy to use, causes additional
overhead to be generated each time a table item is referenced in this
fashion. At compile time, the compiler has to compute the index value
corresponding to the specified literal; and transfer this index value
to the object file. At object run time, the index value for the
literal is added to (+) or subtracted from (-) the index value of the
index-name. The resulting index value is stored in a temporary
location. The OTS adds this temporary index value to the base address
of the table to determine the address of the desired table item.
At
this point, a range check is performed on the temporary index value to
insure that the resulting index is within the permissible range for
the table.
For fixed length tables, this index manipulation is relatively
straightforward.
The size of the table is known at compilation time,
and this size is passed along to the OTS in the object file. A simple
compare against this fixed value is all that is required to determine
if a given index value is within the permissable range for the table.
For a variable length table, however, the process is more involved.
The current number of occurrences (data-name-l) for the table must be
determined and range checked; the index value corresponding to the
current number of occurrences must be calculated; then the temporary
index value must be range checked using the current number of
occurrence's index value.

5-13

TABLE HANDLING
The object time overhead required for the relative indexing of
variable.length tables is significantly greater than that required for
fixed length tables.
In either case,
the index portion of the
index-name is not altered.
If any of the range checks reveals an
illegal
(out of range)
value,
execution is terminated with an
apropriate error message.
The sample MOVE instruction in Figure 5-17 moves the fourth repetition
of A-GROUP to I-FIELD if IND-NAME has not been altered with a SET
verb.
MOVE A-GROUP{IND-NAME + 3) TO I-FIELD.
Figure 5-17
Relative Indexing
The actual operation of accessing a table element is shorter at run
time since the compiler has calculated the index value of the literal
at compile time and has stored it in the object program ready for use.
Relative indexing, therefore, involves two additions and a range check
during object execution.
It leaves the index-name item unaltered.

5.4.8

Index Data Items

Often a program will require that the value of an index-name item be
stored outside of that item.
It is for this purpose that TRAX COBOL
provides the index data item.
I-word
binary
integers
with
implicit
Index data items are
synchronization.
(The I-word size corresponds to the subscript part
of the index-name item.) They must be declared with a USAGE IS INDEX
(explicitly)
only by the SET
phrase and they may be modified
statement.
Subscript part------~.~I____________~
Figure 5-18
Index Data Item
Since index data items are considered to contain only the subscript
part of an index-name item, when a SET statement "moves" an index-name
item to an index data item,
only the subscript part is moved.
Likewise,
when a SET statement "moves" an index data item to an
index-name item, a new index value is computed by the software.
This
is done to guarantee that an index-name item will always contain a
good index value.
The only advantage gained by using index data items over numeric, COMP
items
is that the data description is shorter, easier to write, and
more self-documenting.
Further, the restrictions placed on access to
index items may be useful in debugging the program.

5.4.9

The SET Statement

The SET statement alters the value of index-name items and copies
their value into other
items. When used without the UP BY/DOWN BY
clause, it functions like a MOVE statement.
Figure 5-19 illustrates
the legal data movements that the SET statement can perform.
5-14

TABLE HANDLING
INDEX-NAME ITEM
NUMERIC LITERAL

(INDEX PART)

INDEX DATA ITEM

~~~1§UBSCRIPT-PART)~--~~~~==~~~

~------------~

NUMERIC DATA NAME
(CaMP OR DISPLAY)

INDEX-NAME ITEM
_J~@~~~~~U

(SUBSCRIPT PAR~)
Figure 5-19
Legal Data Movement with the SET Statement
The SET statement may be used with the UP BY/DOWN BY clause to alter
the value of an index-name item arithmetically. The numeric literal
is added to (UP BY) or subtracted from (DOWN BY) the subscript part,
and the index part is recalculated by the software after the
appropriate range check against the number of repetitions for the
table.
The SET statement is not affected by whether the table is
fixed or variable length.

5.4.10

Referencing a Variable Length Table Element at OTS Time

At OTS time, when a procedural reference involves an element
variable length table, the following procedure is used:
1.

Determine the number of occurrences in the table (the
contained in data-name-l), and verify its legality.

value

(integer-l <= data-name-l <= integer-2)
2.

Verify that the subscript is within the legal range.
(subscript <= data-name-l)

If any of the above checks fails,
appropriate error message.

5.4.11

execution

terminated

with

Referencing a Dynamic Group at OTS Time

A dynamic group is defined as a group item that contains a subordinate
item that is a variable length table. At OTS time, when a dynamic
group is referenced, the following procedures are followed:
1.

The number of occurrences of the subordinate variable length
table
is determined, and checked for legality;
i.e.,
integer-l<=data-name-l<=integer-2.
If this check
fails,
execution terminates and the appropriate error message is
issued.

The size of the dynamic group is calculated. The number of
occurrences of the variable length table (data-name-l) is
multiplied by the size of one table entry.
The resulting
number is then added to the fixed size of the dynamic group.

5-15

TABLE HANDLING
NOTE
The fixed size of a dynamic group is the
size
of
the group up to but not
including the variable length table.

5.4.12

The SEARCH Verb

The SEARCH verb has two formats:
Format 1, which performs a
sequential search of the specified table beginning with the current
index setting:
and Format 2 which performs a selective
(binary)
search of the specified table, beginning with the middle of the table.
Both formats allow the programmer to specify imperative statements
within the SEARCH verb.
At OTS time, an imperative statement
contained within a search verb is executed only when one of the exit
paths (success or failure) is taken.
The failure path is defined either explicitly by the AT END statement,
in which case the imperative statement which follows it is executed;
or by default, in which case control is passed to the next procedural
sentence.
In either case (success or failure), after an imperative
statement is executed, control is passed to the next procedural
sentence.

5.4.13

The SEARCH Verb - Format 1

Format 1 directs the OTS to search the indicated table sequentially.
The OCCURS clause for the table being searched must contain the
INDEXED by phrase.
Unless otherwise specified in
the
SEARCH
statement, the first index is the controlling index for the table
search. The search begins with the current index setting, and
progresses through the table, augmenting the index by one as each
occurrence is interrogated.
If any of the specified conditions is
true
(success), the associated imperative statement is executed; the
search exits;
and the index remains at the current setting.
If the possible number of occurrences for the table is exhausted
before any of the specified conditions are met, the specified failure
exit path is taken.
That is,
either the AT END exit path (if
specified)
is taken, or control is passed to the next procedural
sentence.
Figure 5-20 contains an example of using the SEARCH verb to
table a serially.
Associated with Format 1 is the optional VARYING phrase.
can be specified by using any of the following methods:
1.

default - phrase omitted

VARYING index-name-n

VARYING identifier-2

VARYING index-name-2

5-16

This

phrase

TABLE HANDLING

NOTE
The following is true regardless
above methods is used.

which

the

An index name associated with the table
is methodically
augmented by one,
by the OTS,
for each cycle of the
serial search. This controlling index, when compared to
the allowable number of occurrences for
the table,
dictates the permissible range of search cycles at OTS
time.
When an exit occurs (success or failure), this
index remains at the current setting.

The OTS will not initialize the index when the search
begins.
It is the programmers responsibility to insure
that the initial index setting is the appropriate one.
The OTS will begin processing the table with the setting
it finds when the search is initiated.

When method 1 is used, the first index name (index-name-l)
associated
with the table is used as the controlling index. Only this index is
set to consecutive values by the OTS serial search processor.
See
Figure 5-20, Example 2, for an example of using method 1.
When method 2 is used, index-name-n is any index that is associated
.with the table being searched.
It becomes the controlling index for
the table.
It alone is set to consecutive values by the OTS search
processor. See Figure 5-20, Example 3, for an example of using method
2.
When method 3 is used, identifier-2 is augmented by one each time the
first
index
(controlling index)
for the table is augmented by one.
Identifier-2
is not a substitute index.
It merely allows the
programmer to maintain an additional pointer to elements within a
table.
See Figure 5-20, Example 4, for an example of method 3.
When method 4 is used, index-name-2 is an index that is associated
with a
table other than the one being searched.
Each time the
controlling index (1st index for the table) of the searched table is
augmented,
index-name-2
is also augmented.
See Figure 5-20, Example
5.

5.4.14

The SEARCH Verb - Format 2

Format 2 is used to direct the OTS to search the indicated table
selectively.
The selective
(binary)
search is predicated upon the
ASCENDING/DESCENDING KEY attributes of the table being searched.
Therefore,
an ASCENDING and/or DESCENDING KEY(s) must be specified in
the OCCURS clause that defines the table, to inform the OTS that the
keys are stored within the table in ascending or descending order.
The INDEXED BY phrase must also be specified. When the binary search
is executed, the OTS uses the first or only index associated with the
table as the controlling index for the search.

5-17

TABLE HANDLING
The selective (binary) search is implemented in the OTS as follows:
1.

The OTS examines the range of permissible values for the
index of the table being searched; selects the median value;
and assigns this median value to the index.

The OTS then proceeds to process the sequence of simple tests
for equality, beginning with the first, with the index set to
the median value.

If all of the tests for equality are true (success), the
search is terminated; the associated imperative statement is
executed; the search exits;
and the index retains its
current value.

If any of the tests for
results occur.

equality

false,

the

following

The OTS determines if all of the possible occurrences for
the table have been tested.
If the table has been
exhausted, the imperative statement which accompanies the
AT END statement (if specified) is executed. In either
case, control is passed to the next procedural statement.

The OTS will now determine which half of the table is to
be
eliminated
from
further
consideration.
This
determination is predicated on whether the key being
tested is in ascending or descending order, and whether
the test failed because of a greater than or less than
comparison.
For example, if the key values being tested
are stored in ascending order, and the median table
element being tested is greater than the value being
tested for equality, the OTS will assume that all key
elements following the one tested are also greater than
the value being tested for equality.
Therefore, the
lower half of the table, those items which follow the
current index setting, are no longer in contention.

Once the direction of search is determined, half of the
table is eliminated from further consideration. A new
range of permissible index values is computed from the
remaining half of the table.

Processing begins allover again from step 1.

See Figure 5-20, Example 6, for an example of searching a table
Format 2 of the SEARCH verb.

5-18

using

TABLE HANDLING

FEO-TAX-TABLES.
~2
ALLOWANCE-DATA.
A3 FILLER

PIC X(70) VALUE

"O~~laa~
"~20288~
"~3043?~
"~a05760

"~5~72~~
"~&086a~

"~71~08~
"AA1152~
"~q12qb~

"l~laa~~".
ALLO~ANCE-TA8LE REDEFINES
~3
FEO-ALLOWANC£S OCr.URS

ASCENDING KEY IS

ALLowANC~-NU~BER

INDEXED 8v IND-1.
04

ALLOWANCE-NU~BER

ALLOwANCE
SINGLES-DEOUCTION-DATA,
~3
FILLER
~4

ALLOWANCE-DATA.
1~ TIMES

PIC xx.
PIC QQQVqq.
PIC X(112) VALUE

"~'-5a00~700~0001b
"~6700115~00b7220
"115~A18!~~lb32~J
"183A~24~~03tQ&2t
"24~~~27q0043q32b
"27q~~34&~05a0730
"34&~0qqqqq74173b".

SINr,LES-OEDUCTION-TABLE REDEFINES SINGLES-DEDUCTION-DATA.
~l
SINGLES-TABLE OCCURS 7 TIMES
ASCENOING KEY IS S-~IN-RANGE 5-MAX-~ANGE
INnEXED 8Y INO-2, TEMP-INOEX.
04 S-MIN-RANGE
PIC qqqVqq,
A4
S-M4X-RANGE
PI~ qqqVqq.
~4
S-TAX
PIC qqVqq.
04 S-PERCENT
PIC vqq.
MARRIED-OEDUCTION-DATA.
~]
FILLER
PIC X(11Q) VALUE
"0~80~0~~0~~000~11
"0q~A01730~0~81&2~
"173002~400~235&17
"2ba003~60003q0325
"34&~0a330A05q5128
"4330~5~000~~3Aq32
"50000~qqqq105333b".

MARRIED-DEDUCTION-TABLE REDEFINES MARRIED-DEDUCT ION-DATA.
MARRIEO-TABLE OCCURS 7 TIMES
ASCENOING KEY IS M-MIN-~ANGE M-MAX-RANGE
INDEXE~ ~Y IND·~, INO-].
04 M-MIN-RANGE
PIC qqqvqq.
04 M-MAX-RANGE
PIC qqqVqq.
04 M-TAX
PIC QQqVQq.
~4
M-PERCENT
PIC Vqq.
TEMP-INDEX
USAGE INDEX,
02

Figure 5-20
Example of Using SEARCH
To Search a Table

5-19

TABLE HANDLING
Example 1

SINGLE,

IF TAXABLE-INCOME C 02Uqq
GO Tn END-FED-COMP.
SET INO-2 TO 1.
SEA~C~ SINGLES-TABLE VARYING IND-2 AT ENO
GO TO TARLE-2-ERROR
WHE~ TAXABLE-INCOME. S-MIN-RANGECINO-2)
MOVE S-TA~CIND-2) Tn FEO-TAX-O~OUCTIO~ OF
OUTPUT-~ASTER

GO TO STn~E-FED-TA~
WHEN TAXARlE-INCOME C S-~'X-RANGECINO-2)
SUBTRACT S-MIN-RANGECINO-2) FROM TAXABLE-INCO~E
MULTIPLY TAXABLE-INCOME BY S-PERCENTCINO-2) ROUNDED
ADO TA~ABLE-tNcnMF. TO FEn-TAX-OEnUCTlnN OF
OUTPUT-MASTER.
Example 2

SINGLE.
IF TAXABLE-INCOME C 02UQQ
GO TO

E~D-FED-COMp.

SET INO-2 TO 1.
SEARCH SINGLES-TABLE VA.RYI~G INO-2 AT ENO
r,0 Tn TABLE-2-ERROR
WHEN TAXABLE-INCOME • S-MIN-RANGECI~D.2)
MOVE S-TA~CIND-2) TO FED-TAX-DEDUCTION OF
OUTPUT-MASTER
GO TO STORE-FEC-TAX
wHEN TAXABLE-INCO~E C ~-MAX-RANGECINO-2)
SUBTRACT S-MIN_RANGECIND-21 FROM TAXABLE-INCOME
MULTIPLY TA~A~LE-INCOME BY S-PE~CENTCINO-2) ROUNOED
AD~ TA~A8LE-INCOMF. TO FEO-TAX-OEOUCTlnN OF
OUTPUT-MASTER.
Example 3

MARRIED.

IF TAXABLE-INCOM.E C 041Qq
MOVE ZEROS TO FED-TAX-DEDUCTION OF OUTPUT-~ASTER,
GO TO ENO-FEO-COMP.
SET IND-3 TO 1.
SEARCH MARRIEO-TABLE VA~YING IND-]
AT END GO TO TABLE-3-ERROR
WHEN TAXA~LE-I~COME • ~-MIN-RANGECl~D.3)
MOVE M-TAXCINO-]) TO FEO-TA~.OEDUCTlnN OF OUTPUT-MASTER,
GO TO STOQE-FEO-TAX,
wMEN TAXABLE-INCOME c ~.~AX-RANGECINO-3)
~OVE M-TAXCIND-]) TO FED-TAX-OEDUCTION OF OUTPUT-MASTER,
SUBTRACT M-MIN-RANGECINO-3) FROM TAXABLE-INCOME ~OUNOEO,
MULTIPLY T.~ABLE-INCOME BY ~-PERCENT(IND-3' ROUNDED,
ADO TAXABLE-INCOME Tn FEo-TAx-nEDUCTION
nF OUTPUT-MASTER ROUNDED,
GO TO STORE-FEO-TAX.

Figure 5-20 (Cont.)
Example of Using SEARCH
To Search a Table

5-20

TABLE HANDLING
Example 4

SINGLE.
IF

< 024QQ
Gn TO E~n-FED-COMP.
SET 1"10-2 TO 1.
~EA~CH SINGLfS-TABLE VARYING TE~P-I~DEX AT ENO
GO TO TAALE-?-ERRnR
~MEN TAXABLE-INCOME = S-~IN-RANGECINO-2)
~OVE S-TA~(IND-2) TO FED-T4X-QEDUCTION OF
aUTPUT- M4STER
GO TO STORE-FEO-TAX
wHE~ TAXABLE-INCOMt c S-MAX-R'NGE(IND-~)
SUBTRACT S-MIN-RANGECINO-2) FROM TAXABLE-INCOME
MULTIPLY TAX.SLE-INCOME By S-PERCENTCIND-2) ROUNDED
ADO TA~ABLE-INCOMF. TO FEO-TAX-OEDUCTION OF
OUTPUT-MASTER.
TAXA8LE-I~COME

Example 5

SINGLE.

c ~2UQq
GO TO ENn-FEO-COMP.
SET INO-2 TO 1.
StARCH SINGLES-TA9LE VARYING IND-~ AT END
GO TO TA8LE-2-ERROR
WHEN TAXABLE-INCOM~ = S-MIN-RANGECINO-2)
MOVE S-TAXCIND-2) TO FED-TAX-DEDUCTION OF
OUTPUT-MASTER
GO TO STnRE-FED-TAX
WHEN TAXABLE-INCOME C S-MAX-RANGECINO-2)
SUBTRACT S-MIN-RANGECINO-?) FROM TAXABLE-INCOME
MULTIPLY TAXA~LE-INCOME BY S-PERCENTCINO-2) ROU~DEO
ADO TAXABLE-INCOME TO FED-TAX-OEOUCTION OF
OUTPUT-MASTER.
TA~A~LE-INCOME

Example 6

FED-DEDUCT-COMPUTATION.
SET IND-l TO 1.
SEARCH ALL FEO-ALLO~ANCES AT END GO TO TASLE-1-ERROR
WHEN 'LLOwANCE-NU~eER(IND-t) = NR-DEPENDENTS OF
OUTPUT-MASTER,
SU8TRACT 4LLO~ANCECINO-t) FROM GROSS.~4GE OF OUTPUT-MASTER
GIVING TAXARLF.-INCOMF. ROUNDED.
IF MARRITAL-STATUS OF OUTPUT-MASTER a "~"
GO TO MARRIE".

Figure 5-20 (Cont.)
Example of Using SEARCH
To Search a Table

5-21

CHAPTER 6

FILE HANDLING

TRAX COBOL provides three ways to arrange the records in its files
(file
organization) :
sequential,
relative,
and indexed.
The
ORGANIZATION in the Environment Division clause specifies the file
organization for COBOL files.
TRAX COBOL provides three ways to process the records in its files
(file access):
sequential,
random,
and dynamic. The ACCESS MODE
clause specifies the file access mode for each file used by COBOL
programs.
The following chart shows the three file organizations and
the file access methods that apply to each of them:

FILE ORGANIZATION

FILE ACCESS

SEQUENTIAL

SEQUENTIAL
SEQUENTIAL
RANDOM

RELATIVE

DYNAMIC
SEQUENTIAL
RANDOM

INDEXED

DYNAMIC

Once a program creates a file, all other programs that access it must
describe it with the same file organization. For example, it is not
possible to create a sequential file in one program and read it as a
relative file with another program.
However, programs can use
different access methods to process records in the same file as long
as the organization of the file supports the access method.

6-1

FILE HANDLING
The following table compares the different
their file manipulation capabilities.

file

organizations

with

Table 6-1
COBOL File Types
Access

File Type (Organization)

Capabilities

Sequential

Relative

Indexed

Sequential

Yes

Random

Yes

Limited

Yes

Record
Addition (at end of file)

Yes

Record
Insertion

Limited

Yes

Record
Deletion

Yes

Record
Replacement

COBOL I/O statements allow COBOL progra@s to communicate with the
system devices. These statements differ for sequential, relative, and
indexed file organizations. Therefore, the COBOL I/O statements are
discussed separately by file organization.
Section 6.1 discusses
sequential organization, Section 6.2 discusses relative organization,
and Section 6.3 discusses indexed organization. All file processing
is performed by the COBOL object time system (OTS),
regardless of
organization.
Table 6-2 shows which
methods:

statements

apply

each

file

organization

Table 6-2
I/O Statements
Sequential I/O Statements

Relative and Indexed I/O Statements

OPEN

DELETE

READ

OPEN

REWRITE

READ

WRITE

REWRITE
START
WRITE

6-2

FILE HANDLING
6.1

SEQUENTIAL FILE ORGANIZATION

Sequential file organization arranges the records in a file serially:
each record
(except the first) has another record preceding it and
each record (except the last) has another record following
it.
The
records remain in the order in which they were written. Thus, COBOL
statements cannot delete records from the file,
insert new records
between existing records, or alter the order of the existing records
in any way. However, they can replace existing records (providing the
length of the replacement record is identical to the original) and add
new records onto the end of the file.
The opening operation for reading,
writing,
or updating sequential
files must begin with the first record in the file and proceed by the
prescribed order through the file.
For example, to read a particular
record in the file,
say the 15th record, the program must open the
file and successfully execute 14 READ statements before the 15th
execution can read the desired record. The program can read all of
the remaining records (from record 16 on), but it cannot read any
record prior to record 16 without opening the file again and beginning
with record 1.
Sequential files always contain an end-of-file mark that designates
the end of the file.
COBOL statements can write over the end-of-file
mark and, thus, extend the length of a file.
(The software inserts
another end-of-file mark after
the last record written.) Since the
end-of-file mark indicates the end of useful data,
TRAX
COBOL
provides no method for
reading beyond the end-of-file mark:
even
though the amount of space reserved for the file exceeds the amount
actually used. See Figure 6-1.
REC

REC IREC IRECIRECI

Figure 6-1

REC~ ~

Placement of End-of-File Mark

Occasionally a file with sequential organization is so large that it
requ1res more than one volume
(such as a multi-reel magnetic tape
file).
An end-of-volume label marks the end of recorded information
on each volume and signals the file system to switch to a new volume.
On multi-volume files, the end-of-file mark appears once, at the end
of the last record on the last volume. See Figure 6-2.

6-3

FILE HANDLING

VOL. 1

t REC

REC

REC ~ ~ REC

REC

End-of-Volume
~Label

VOL. 2

REC

}{ REC

REC

~Label

VOL. 3

{ REC

REC

?~ REC

End-of-Volume

End-of-File Mark

Figure 6-2 Placement of the End-of-Volume Label and
End-of-File Mark in a Multi-Volume File

6.1.1

Record Size

If there is only one record description for a file or if there are
more than one that describe the same length record, that file contains
fixed-length records.
If the data descriptions for a sequential file
consist of more than one record description, which describe several
different-sized records, that file contains variable-length records.
When a program creates a sequential file with variable-length records,
the software places a count field in front of each record it writes
into the file.
This count field contains the number of character
positions in the record.
When a COBOL statement requests the record,
the software releases a record whose length is that specified by the
count field. The OTS creates and uses the count field automatically.
COBOL statements cannot access it during input operations, and the 01
level record description entries must not describe it.

REC

6.1.2

REC

RECORD CONTAINS Clause

The RECORD CONTAINS clause, when specified without the "integer-l TO"
option,
is for documentation purposes only. The compiler determines
record size from the data descriptions.
When the "integer-l TO"
option is specified,
it forces the compiler to generate a variable
length record file, even if the data descriptions describe fixed
length records.
Conversely, if the data descriptions for a sequential file describe
variable-length records,
the software sets up variable sized records
automatically and ignores this clause.
Even though the software ignores the values in the "integer-l TO ... "
phrase,
the clause may be used in any program to document record
sizes.

6-4

FILE HANDLING
6.1.3

SAM~

RECORD AREA Clause

The file system reserves a record processing area in memory for each
file.
This area is the current record area. The system fixes the
location of the current record area when it opens the file.
It also
reserves a byte preceding and following each current record area for
possible print-control characters. The current record area always
begins on an even byte boundary.
Two or more files may share a
current record area if a SAME RECORD AREA clause contains their
file-names. This clause causes the system to begin the current record
area of each file listed at a common location.
(Thus, current record
areas that share space are aligned on their leftmost bytes.) The
records do not have to be the same size and the current record areas
need not have the same maximum size. The following sample statement
would cause FILEA and FILEB to share the same current record area:
I-Q-CONTROL.
SAME RECORD AREA FOR FILEA FILEB

Since the system places a file's current record area in a separate
location from its buffers, each READ, WRITE, and REWRITE operation
causes a record to move between the buffers and the current record
area.
When a program reads a record from a file, modifies it, and
writes it into another file, a SAME RECORD AREA clause, containing
both file-names, can save an entire move of the record. The following
illustration shows these record movements:
WITHOUT SHARING A CURRENT RECORD AREA
WRITE

READ
FILEA
Buffer
FILEA
Current
Record
Area

FILEB
Current
Record
Area

SHARING A CURRENT RECORD AREA
WRITE

READ
FILEA
Buffer
FILEA & FILEB
Current Record Area
Record Movement Caused by
Reading, Processing, and Writing
Records in Two Files

6-5

FILE HANDLING
6.1.4

Print-Controlled Records

If a sequential file is described in a LINAGE IS clause,
an APPLY
PRINT-CONTROL clause,
or is referenced in a WRITE statement with the
ADVANCING clause specified, and the file is not going directly to a
printing device (is going to be spooled), the software designates the
file as a print-controlled file.
Print-controlled files contain form
advancing information with each record.
Explicit forms control bytes
are placed directly into the file.
Therefore,
any COBOL program
trying to process a print-controlled file may have unpredictable
results.

6.1.5

Record Blocking

The manner in which the file system blocks the records of sequential
files depends on the device to which the file is assigned and the
presence and format of the BLOCK CONTAINS clause.
COBOL programs can assign sequential files to disk which requires
fixed-length virtual blocks,
and to magnetic tape, which allows
variable-length blocks.
The BLOCK CONTAINS clause of a COBOL program refers to a logical block
size.
For magnetic tape,
the logical block size and virtual block
size are the same.
For disk, however, the logical block size is equal
to one or more virtual blocks.
(A virtual block on disk is 512
bytes) .
For files assigned to disk,
the OTS
packs
records
together
(end-to-end)
until a
logical block is filled.
The logical block is
written to disk, and any portion of the previously processed record
that did not fit into the logical block is put into the next logical
block.
This process is called record spanning because
it allows
records to span virtual block boundaries.
Record spanning is prohibited for files assigned to magnetic tape.
For these files, only complete records (fixed or variable length) are
placed end-to-end in a logical block.
The OTS writes the logical
block out to the file when it determines that the block is full to the
extent that the next record will not fit into it.
There are three w~ys to specify block size in a COBOL program;
by
default;
by uSlng the BLOCK CONTAINS integer RECORDS clause;
or by
using the BLOCK CONTAINS integer CHARACTERS clause.
The default
philosophy is to make the logical block size as small as possible;
thus minimizing the memory buffer space required.
By using the BLOCK
CONTAINS
(integer RECORDS or
integer CHARACTERS)
clause, you can
increase the memory buffer space required.
Increasing the buffer
space,
allows for
faster I/O by decreasing the number of I/O
operations required to process a file.
Use the BLOCK CONTAINS clause
only if you can afford the price of additional memory buffer space for
the ability to process your files faster.
The following paragraphs
further define the three blocking methods:
Default
By default, the logical block size is made equal to the record
size (add four bytes for variable length records on magnetic tape
or two bytes for variable length records on disk).
For disk
files,
the logical block size is rounded up to the next even
multiple of 512 bytes to make the logical block size an integral
number of virtual blocks.
For example:
6-6

FILE HANDLING
If the maximum record size for a disk file is 510 bytes, and the
file contains variable length records, then the logical block
size is 1024 bytes.
(510 plus 4 for variable length records is
514,
and 514 rounded up to the next even multiple of 512 is
1024.)
BLOCK CONTAINS integer RECORDS
If this clause is used, the logical block size is equal to the
record size
(plus four
bytes for variable length records on
magnetic tape or two bytes for variable length records on disk)
times the number of
records per block.
For disk files, the
logical block size is rounded up to the next even multiple of 512
bytes to make the block size an integral number of virtual
blocks.
For example:
If the record size for a fixed-length disk file is 100 bytes and
the clause BLOCK CONTAINS 10 RECORDS is specified, the logical
block size is 1024 bytes.
(100 times 10 is 1000,
and 1000
rounded up to the next even multiple of 512 is 1024).
BLOCK CONTAINS integer CHARACTERS
If this clause is used, the logical block size is equal to the
number of characters given in the clause.
If the specified
number of characters is less than the actual record size
(plus
four
bytes for variable-length records on magnetic tape or two
bytes for variable length records on disk) the compiler generates
a block size that is equal to the actual record size.
For disk
files, the specified number of characters must equal an even
multiple of 512. If the number you specify is not correct, the
OTS will round the logical block size it finds to the next even
multiple of 512 bytes.
When a program assigns a file to magnetic tape,
all programs that
access the file must describe it the same way that the creating
program described it in order to guarantee an accurate allocation of
buffers.
Note:

The previous discussion has used the following format:

[BLOCK CONTAINS integer

RECORDS
}]
{ CHARACTERS

If the following format is used:

[BLOCK CONTAINS [integer-l TO]integer-2

RECORDS

}]

{ CHARACTERS

the compiler ignores integer-I, and integer-2 is used as the integer.

6.1.6

Buffering

When the system performs an input operation, it reads a block from the
medium into the buffer,
and moves a record from the buffer to the
current record area.
Each subsequent read operation moves a
record
from the buffer to the current record area.
When it has exhausted the
buffer (has read an entire block), the system reads another block into
the buffpr.

6-7

FILE HANDLING
When performing an output operation, each write operation moves a
record from the file's current record area into the file's buffer.
Each subsequent write operation moves a record from the current record
area into the buffer. The system writes the block to the medium when
it has filled the buffer.
The following subsections discuss the size of the buffers, the
of buffers, and the sharing of buffers.

number

6.1.6.1 Buffer Size Buffer size depends on the size of the largest
record in the file and on the blocking factor.
For files with
sequential organization, the buffer size will be at least 512 bytes.

6.1.6.2 1-0 Buffer Areas The RESERVE clause in the Environment
Division specifies the number of 1-0 buffer areas to be allocated for
each file.
Each 1-0 area represents the space for one logical block.
A minimum of one and a maximum of two are permitted for sequential
files. One is the default. Since two 1-0 areas do not increase the
speed of access and take additional memory space, it is recommended
that this clause not be used.

6.1.6.3 Buffer Space - To calculate the total amount of buffer space
required for each sequential file,
the following algorithm may be
used:
Buffer space
+ 234

record size + (logical blocksize

* no. of areas)

In addition there are 76 bytes of buffer space that are
all files.

shared

among

6.1.6.4 Sharing Buffer Space Among Files The SAME AREA clause
provides a simple method of sharing buffer space among several files.
Two or more files may share the same buffers if the SAME AREA clause
contains their file-names and only one of them is open at any time
during program execution.
Further, since only one file is open at a
time,
the files will also share the same current record area. The
size of the current record area is set to the size of the largest
record description specified in the group.
If only one of these files is open at a time,
the following sample
statement causes them all to share the same buffer and current record
area.
I/O-CONTROL.
SAME AREA FOR FILEA FILEB FILEC.

6-8

FILE HANDLING
6.1.7

Sequential I/O Statements

TRAX COBOL
files:
•
•
•
•
•

provides the

following

I/O

statements

for

sequential

CLOSE
OPEN
READ
REWRITE
WRITE

Before a COBOL program can access a file,
it must open the file:
then, when the program is finished with the file, it must close the
file.
A COBOL program may open a sequential file in one of four modes,
INPUT, OUTPUT, 1-0 (input/output), or EXTEND. In INPUT mode, records
may be read from the file:
in OUTPUT mode the file is created and
records can only be written to it:
in 1-0 mode, records can be read
from the file and updated;
in EXTEND mode, records may be added onto
the end of the file. Table 6-3 shows which statements apply to the
four different OPEN modes of sequential files.
(The table does not
include the OPEN and CLOSE statements since they apply to all modes.)
Table 6-3
Sequential OPEN Modes

Statement
READ

Input

Output

Open Mode
Input-Output

REWRITE
WRITE

Extend

6.1.7.1 Opening Sequential Files - The OPEN statement makes a file
available for processing by a COBOL program. A program must execute
an OPEN statement for a file before it executes any other I/O
statement
for
that file.
Consider the following sample OPEN
statement. It opens the file named THOREAU for
input/output.
The
program containing this statement could, after executing it, READ,
REWRITE, and CLOSE THOREAU.

6-9

FILE HANDLING
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT THOREAU
ASSIGN TO "DKI:".

DATA DIVISION.
FILE SECTION.
FD THOREAU

PROCEDURE DIVISION.

OPEN 1-0 THOREAU.

The OPEN statement must refer to the file by the file-name appearing
in both the SELECT clause in the Environment Division and the FD
paragraph in the Data Division.
When the OTS executes an OPEN statement,
it
actions for the file named in the statement:

performs

the

following

•

If the file is already open,
the OTS generates an error
message
and
performs
the
USE procedure section
(if
specified) .
(Section 6.9 discusses USE procedures
and
Section 12.3 discusses error messages.)

•

When opening an existing file, the attributes
(i.e.,
record
length,
block size, etc.) of the file are used for accessing
the file.
Those specified in the program are
ignored.
Be
sure that the attributes specified in the COBOL program agree
with the actual attributes of the file. .

•

If the SELECT clause of the File-Control paragraph declares
the file OPTIONAL, the OTS displays the following message:
"FILE nnn ... OPTIONAL FILE MOUNTED?

Y OR N?"

(nnn represents the file-name.)
If the file is available for processing, type a Y.
If not,
type an N.
If the file
is not available (N), the OTS
disables all I/O processing on the file except READ and
CLOSE;
a later READ statement causes program control to take
the AT END imperative path.
•

If a SAME AREA clause contains the name of the file and none
of the other files named in the clause is open, the OTS
allocates buffer space for the file.

•

When the file has passed all of the preceding checks and is
ready for opening,
the OTS instructs the Record Management
Services to open the file.
If the Record Management Services
fails
to open the file, the OTS reports an error condition
and performs any applicable USE procedure (if present).

6-10

FILE HANDLING
•

If the program is creating the file
(OPEN OUTPUT)
and the
file description specifies LINAGE or APPLY PRINT-CONTROL, the
OTS initializes the LINAGE counters.

•

Finally, depending on which statements apply to the open
mode, the OTS enables or disables all of the program's I/O
statements that refer to the file
(see Table 6-3).
For
example,
if the OPEN mode is INPUT, it enables all READ
statements for that file and disables all REWRITE and WRITE
statements for that file.

Since the EXTEND mode simply allows the WRITE statement to add records
onto the end of the file, files opened in this mode must already exist
on disk or tape (only the last file on magnetic tape can be extended).
If the file does not exist, the OPEN statement fails and the OTS
issues an error message.

6.1.7.2 Reading Sequential Files - The READ statement makes the next
logical record of an open sequential file available to the program.
If the preceding I/O operation was an OPEN, it makes the first record
of the file available to the program.
Consider the following example.
If the last I/O operation on the file
named THOREAU was an OPEN, this statement would provide the program
with the first record in the file THOREAU. Every time the statement
is executed, it provides the program with the next sequential record
in THOREAU. Program control transfers to the paragraph named LIBRARY
when an end-of-file mark is encountered during the READ.
BEGIN. OPEN THOREAU.
LOOP. READ THOREAU AT END GO TO LIBRARY.

GO TO LOOP.
If the file contains variable-length records,
the program must
determine the length of the record just read. No such information is
supplied to the user program.
If the file is open in the 1-0 mode, the successful execution of a
READ statement enables any following REWRITE of the record just read.
(For further information on the REWRITE statement, see the next
subsection -- 6.1.7.3.)

6-11

FILE HANDLING
If the file has more than one record description, the records
automatically share the same current record area. The OTS does not
clear this area before it executes the READ statement (no blank
filling, etc.).
Therefore,
if the record read by the latest READ
statement does not fill the entire current record area, the area not
overlaid by the incoming record remains unchanged. For example, if
the file's record area contains ten 3's, and a READ operation moves in
a 6-character record containing alII's, the current record area then
contains six lis followed by four 3's.
Consider the following
example:
Current Record Area with all 3's

133333333331

Next Record in the File

11111111

Current Record Area after READ

111111133331

6.1.7.3 Rewriting Records into Sequential Files The
REWRITE
statement places the record just read from an input-output file back
into its file on disk or magnetic tape.
(The WRITE statement cannot
access 1-0 files.) The following sample statement writes the record,
RECl, back into its file.
(RECl, of course, must be a record in the
file read by the preceding READ for that file.)
REWRITE RECI
Before the REWRITE statement can refer to a record, the
containing the statement must meet the following conditions:

program

•

The file containing the record must be open in the 1-0 mode;

•

The last I/O operation on the file containing the recora must
have been a successful READ;

•

The record length of the record to be rewritten must
same as the record last read from the file.

the

6.1.7.4 Writing Sequential Files - The WRITE statement releases a
logical record to an output file, thereby creating an entirely new
record in the file.
The following sample WRITE statement releases the record PRINT-LINE to
the device assigned to that record's file, then skips three lines.
When it reaches the end of a page (as specified by the LINAGE clause),
it causes program control to transfer to the subroutine, HEADER-RTN.
WRITE PRINT-LINE BEFORE ADVANCING 3 LINES
AT EOP GO TO HEADER-RTN.
Note that this produces two blank lines following every line printed.
The WRITE statement releases records to files that are open in either
the output or extend mode. The following text discusses the two modes
separately.
•

OUTPUT Mode - The WRITE statement can create
two kinds of files in the OUTPUT mode:

6-12

the

following

FILE HANDLING
1.

Print-files - A print-file produces a listing on
a
printing
device.
The
LINAGE
clause,
the APPLY
PRINT-CONTROL clause, or a WRITE statement with the
ADVANCING
option included, designates a file as a
print-file.
One
or
more
records
containing
carriage-control characters are written to perform line
spacing. The WRITE statement does not have to release
print-files directly to a printing device, but may also
release them to a storage medium such as disk for
printing at a later time.

storage files - A storage file remains on disk or tape
for future reference. All files that are not print-files
are storage files.
A sample storage file WRITE statement
follows;
this statement writes a record named WALDEN
into a file:
WRITE WALDEN

•

EXTEND Mode - A WRITE to a storage file opened in the EXTEND
mode simply adds new records logically in sequence after the
last record in the file. As the statement extends the file,
the Record Management Services automatically handles requests
for additional storage space.
(Print-files on disk should
only be opened for EXTEND if they are being opened as a
print-file.)

6.1.7.5 Closing Sequential Files - The CLOSE statement terminates
processing on the file referred to in the statement. The following
sample CLOSE statement terminates processing on the file named
THOREAU:
CLOSE THOREAU
When the CLOSE statement closes a file, no other I/O operation
access that file until another OPEN statement opens the file.

can

If the statement specifies the LOCK option, the program cannot open
the file again in this run. The CLOSE statement with the LOCK clause
is shown below:
CLOSE THOREAU WITH LOCK
The lock option has no effect on the physical
file.

containing

the

If a SAME AREA clause contains the name of the file just closed,
program may open one of the other files named in the clause.

the

6.2

device

RELATIVE FILE ORGANIZATION

Relative file organization arranges the records of the file
into
numbered record positions.
It assigns each record position a number
that identifies that position relative to the beginning of the file
(the first record position in the file has record number 1, the second
has record number 2, etc.).

6-13

FILE HANDLING
1

Record positions in a Relative File
When a program executes a
random DELETE,
REWRITE,
READ or WRITE
operation on a relative file, the value in the relative key is used to
select records from these numbered record positions in the same way
that a subscript selects an item in a table.
Thus, while sequential and relative files both arrange their
record
positions in a serial order, COBOL statements can address the record
positions of a relative file by their position numbers, and successive
accesses do not have to proceed through the file in a prescribed,
serial, order.
Another significant feature of relative file organization is that each
record position does not have to contain a valid record.
Although
each position actually occupies one record space, a byte preceding the
record on the storage medium indicates whether or not that space
contains a valid record. Thus, a file may have fewer records than it
has record positions, and the indicated empty record positions may be
anywhere in the file.
The numerical order of the record positions remains the same during
all operations on a relative file;
however, the accessing statements
can move a record from one position to another, delete a record from a
position, or insert new records into empty positions.

6.2.1

Record Size

A relative file may contain either
fixed-length or variable-length
records.
(Fixed-length records have one or more record descriptions
that describe the same size record.
Variable-length records have more
than one record description that describe seve~al different sized
records.) However, the COBOL compiler allocates a record area on the
I/O device,
equal to the largest record described plus one. This
extra byte is an existence byte.
It indicates whether the record area
contains a valid record.
For variable length records in a relative
file, the software adds a two byte count field.
On a write operation
the actual record is written out to the I/O device not the maximum
length record. The length of this record is placed in the two byte
count field.
On a read operation this two byte count field is used to
determine the length of the record to be read in.

6.2.2

RECORD CONTAINS Clause

The RECORD CONTAINS clause, when specified without the "integer-l TO"
option,
is for documentation purposes only.
The compiler determines
record size from the data descriptions.
When the "integer-l TO"
option is specified,
it forces the compiler to generate a variable
length record file, even if the data descriptions describe fixed
length records.
Conversely, if the data descriptions for a sequential file describe
variable-length records,
the software sets up variable sized records
automatically and ignores this clause.
Even though the software ignores the values in the "integer-l TO •.. "
phrase,
the clause may be used in any program to document record
sizes.
6-14

FILE HANDLING
6.2.3

SAME RECORD AREA Clause

The SAME RECORD AREA clause is identical for all
See Section 6.1.3.

6.2.4

file

organizations.

Record Blocking

The size of a file is expressed as an inte~ral number of virtual
blocks.
Virtual blocks are physical storage structures. That is,
each virtual block within a file is a unit of data whose size depends
on the physical medium on which the file resides.
Relative files may reside only on disk. The size
within files on disk devices is always 512 bytes.

virtual

blocks

Relative files use a logical storage structure known as a logical
block or bucket. A bucket consists of from 1 to 32 virtual blocks.
This distinction should be made clear.
A virtual block is a physical
entity which is fixed in size and cannot be changed. A bucket,
however, is a logical entity.
Its size is directly under your
control.
Records may span virtual block boundaries. They may never
span bucket boundaries.
Increasing the bucket size increases the speed
of
sequential
processing of a file because fewer I/O operations are needed to access
the smaller number of buckets in the file.
On the other hand,
a
larger bucket size means that more memory space is taken up by the I/O
buffers.
Increasing the bucket size may not increase the speed of
random processing of a relative file.
There are three ways that the bucket size may be specified in a COBOL
program;
by default,
by using the construct BLOCK CONTAINS integer
RECORDS, or by using the construct BLOCK CONTAINS integer CHARACTERS.
The default is to make the bucket size as small as possible,
to
minlmlze the memory buffer space required.
By using the BLOCK
CONTAINS integer (RECORDS of integer CHARACTERS)
clause, you can
increase the memory buffer space required.
Increasing the buffer
space allows for faster I/O by decreasing the number of operations
required to access a file.
The following paragraphs further define
the three blocking methods:
Default
The default philosophy is to make the bucket size as small as
possible to minlmlze the memory buffer space required. The
algorithms for calculating the bucket size follow:
Bnum= «1+Rlen}/5l2}+1

Fixed length record

Bnum= {{3+Rmax}/512}+1

Variable length record

Where:
Bnum

is the number of virtual
ranging from 1 to 9.

Rlen

is the fixed record length {in bytes}.

Rmax

is the maximum record length
record length is variable.
6-15

blocks

(in

per

bytes)

bucket,

the

FILE HANDLING
The number 1 is for the existence byte. The number 3 is for
existence byte plus 2 bytes for the record length.

the

Table 6-4 gives the bucket size for possible record lengths.
Table 6-4
Bucket Sizes for possible Record Lengths
Bnum

Rlen

Rmax

1-511
512-1023
1024-1535
1536-2047
2048-2559
2560-3071
3072-35H3
3584-4095

1-509
510-1021
1022-1533
1534-2045
2046-2557
255&-3069
3070-3581
3582-4093
4094-4095

2
3
4
5
6
7
8

BLOCK CONTAINS Rnum RECORDS
If the BLOCK CONTAINS Rnum RECORDS clause is used, where Rnum is
an integer,
then the following algorithms are used to calculate
the bucket size.
Bnum= (((Rlen+l)*Rnum)/512)+1

Fixed length record

or
Bnum= (((Rmax+3)*Rnum)/512)+1

Variable length record

Where:
Bnum

is the number of virtual
ranging from 1 to 32.

blocks

Rlen

is the fixed record length (in bytes).

Rmax

is the maximum record length
record length is variable.

Rnum

is the number of records per bucket
the BLOCK CONTAINS clause.

(in

per

bucket,

bytes)

the

given

BLOCK CONTAINS Cnum CHARACTERS
If the BLOCK CONTAINS Cnum CHARACTERS clause is used, where Cnum
is an integer, then Cnum is subject to the following constraints.
(1)

Cnum

for fixed length records

Rlen+l
or

Cnum
(2)

Rmax+3

Cnum mod 512

for variable length records
0

6-16

FILE HANDLING
Based on CNUM, the bucket size is calculated as follows:
Bnum=Cnum/5l2
where:
Cnum

is the number of characters per bucket as given in
the BLOCK CONTAINS clause.

Rlen

is the fixed record length (in bytes).

Rmax

is the maximum record length
record length is variable.

(in

Bnum

is the number of virtual
ranging from 1 to 32.

blocks

bytes)
per

the

bucket,

Violation of constraint
(1)
causes a warning error and the
default method is used to calculate the bucket size.
Constraint
(2) means that Cnum should be a multiple of 512.
If not,
a
warning error
is given and Cnum is increased to the next even
multiple of 512.
The bucket size must be the same when the file
is created and
each time the file is accessed. Therefore, the BLOCK CONTAINS
clause must never change for a particular file.
Note:

The previous discussion has used the following format:

[BLOCK CONTAINS integer

RECORDS
}]
{ CHARACTERS

If the following format is used:
[BLOCK CONTAINS[integer-l TO]integer-2
the compiler ignores integer-I, and
integer.

6.2.5

RECORDS
}]
{ CHARACTERS

integer-2

used

the

Buffering

When the system performs a sequential or random input operation,
it
reads a bucket from the medium into the buffer, and moves a record
from the buffer to the current record area. Any subsequent sequential
read operations move a record from the buffer to the current record
area.
When it has exhausted the buffer (has read an entire bucket),
the system reads another bucket into the buffer.
When performing a random read operation,
the appropriate bucket is
read
into a file's buffer. The record is thp.n moved from the buffer
to the current record area.
When performing a sequential output operation, each write operation
moves a
record from the file's current record area into the file's
buffer.
Each subsequent sequential write operation moves a record
from the current record area into the buffer. The system writes the
bucket to the medium when it has filled the buffer.

6-17

FILE HANDLING
When performing a random output operation, the appropriate bucket is
read and the record is moved from the file's current record area into
the appropriate position in the file's buffer.
The system writes the
bucket back out to the medium before reading any additional blocks.
The following subsections discuss the size of the buffers, the
of buffers, and the sharing of buffers.

number

6.2.5.1 Buffer Size Buffer size depends on the size of the largest
record in the file and on the blocking factor.
For relative files,
buffer size must be some multiple of 256 words (512 bytes).

6.2.5.2 I/O Buffer Areas The RESERVE clause in the Environment
Division specifies the number of I/O buffer areas to be allocated for
each file where an area represents the space for one bucket.
A
minimum of one and a maximum of two I/O areas are permitted for
relative files. One is the default.
It is recommended that this
clause not be used, because two I/O areas do not increase the speed of
access and take up additional space.

6.2.5.3 Buffer Space To calculate the total amount of buffer space
in bytes required for each Relative file, the following algorithm may
be used:
Buffer space

= record size + bucket size + 266

In addition, there are 76 bytes of buffer space that are shared
all files.

among

6.2.5.4 Sharing Buffer Space Among Files The SAME AREA clause
provides a simple method of sharing buffer space among several files.
This clause is identical for
all file organizations.
See Section
6.1.6.4.

6.2.6

Relative I/O Statements

The COBOL I/O statements, CLOSE, DELETE, OPEN, READ,
and START can refer to relative files.

WRITE,

REWRITE,

A COBOL program may open a relative file in one of three modes, INPUT,
OUTPUT, or I-a, and access an open relative file in one of three ways,
sequentially, randomly, or dynamically.
In INPUT mode, tecords may be
read from the file;
in OUTPUT mode, the file is created and records
may be written to the file;
in I-a mode, records may be read from the
file,
updated on the file, deleted from the file, or written to the
file.
The following table shows which statements and access methods
apply to the three different OPEN modes of relative files.

6-18

FILE HANDLING
Table 6-5
Relative OPEN Modes
FILE ACCESS
MODE

Sequential

Random

Dynamic

STATEMENT
DELETE
READ
REWRITE
START
WRITE
DELETE
READ
REWRITE
START
WRITE
DELETE
READ
READ NEXT
REWRITE
START
WRITE

INPUT

OPEN MODE
OUTPUT

I-a

x
X

X
X
X

X
X

X
X
X

X
X

X
X
X
X
X
X

X
X
X

NOTE
The term, current record pointer, used
in the following sections, refers to a
location in the operating system used to
determine the record number of the next
available record in a file.

6.2.6.1 Access Modes - The ACCESS MODE clause in the File-Control
paragraph dictates which of the three access modes may be used on that
file.
When the ACCESS MODE clause specifies SEQUENTIAL, the I/O statements
must refer to the records in the file sequentially, starting (after
opening)
with the first record and stepping through with each
reference to the end of the file. The I/O statements ignore record
positions that do not contain valid records.
When the ACCESS MODE clause specifies RANDOM, the I/O statements refer
to the records in the file by record position. Thus, the statements
may refer to record positions that do not contain valid records.
The
program must specify the desired record position number by placing a
value in the file's relative key.
If an I/O statement refers to a
record position with the relative key, and that record position does
not exist (either because the position does not contain a record or
because it is beyond the end of the file), the INVALID KEY imperative
statement may be executed depending on the particular I/O statement
used.
(The INVALID KEY imperative statement is explained with each of
the relative I/O statements in this section.)

6-19

FILE HANDLING
When the ACCESS MODE clause specifies DYNAMIC, the I/O statements may
refer to the records in the file either sequentially or randomly. The
OTS determines which access method to use from the OPEN mode
(INPUT,
OUTPUT, or 1-0)
and the form of the I/O statement. For example, if
the statement READ ... INVALID KEY is to access an open input file
dynamically,
the OTS uses the relative key for random access;
if the
statement READ NEXT ...
is to access an open input file dynamically,
the OTS sequentially accesses the next existing record.
The following sections (6.2.5.2 through 6.2.5.8)
on using the I/O
statements themselves contain additional information about access
modes.

6.2.6.2 Opening Relative Files - The OPEN statement for a relative
file makes an INPUT, OUTPUT, or 1-0 mode file available so the COBOL
program can access the records in the file sequentially, randomly,
or
dynamically.
The OPEN statement sets the current record pointer
zero.

for

the

file

For example, the following sample OPEN statement opens the file named
ARTICHOKE for
input,
and sets ARTICHOKE's current record pointer to
zero. The program cbntaining this statement could,
after executing
the statement, access ARTICHOKE with READ and START statements in the
sequential access mode, READ statements in the random access mode, or
READ, READ NEXT, and START statements in the dynamic access mode.
OPEN INPUT ARTICHOKE.
When the OTS executes an OPEN statement,
it
actions for the file named in the statement:

performs

the

following

•

If the file is already open,
the OTS generates an error
message
and
performs
the
USE procedure section
(if
specified).
(Section 6.9 discusses USE procedures
and
Section 12.3 discusses error messages.)

•

When opening an existing file, the attributes
(i.e.,
record
length,
block size, etc.) of the file are used for accessing
the file.
Those specified in the program are ignored.
Be
sure that the attributes specified in the COBOL program agree
with the actual attributes of the file.

•

If a SAME AREA clause contains the name of the file and none
of the other files named in the clause is open, the OTS
allocates buffers space for the file.

•

When the file has passed all of the preceding checks and is
ready for opening,
the OTS instructs the Record Management
Services to open the file.
If the Record Management Services
fails to open the file, the OTS reports an error condition
and performs any applicable USE procedure (if present).

•

Finally, depending on which statements apply to the open
mode, the OTS enables or disables all of the program's I/O
statements that refer to the file
(see Table 6-5).
For
example,
if the OPEN mode is INPUT, it enables all READ and
START statements for that file and disables all REWRITE,
DELETE and WRITE statements for that file.

6-20

FILE HANDLING
If the file is being accessed randomly or dynamically,
the program
must maintain a correct value in the relative key.
If the file· is
being accessed sequentially, the OTS ignores the value of the relative
key, but updates it to contain the position number of the record being
accessed.

6.2.6.3 Reading Relative Files When applied to a file being
accessed sequentially,
the READ statement makes the next logical
record of an open file available to the program.
When applied to a file being accessed randomly,
the READ statement
selects a specified record from an open file and makes it available to
the program. The value of the relative key for
the file
identifies
the specific record.
When applied to a file being accessed dynamically, the READ statement
has two formats so that it can either select the next logical record
(sequentially) or select a specified record
(randomly)
and make it
available to the program. The READ NEXT statement takes the number in
the current record pointer and finds the next present record.
The
following sample READ statement reads the file named ARTICHOKE
sequentially and, when it exhausts the file, causes program control to
transfer to the subroutine named FILEOUT:
READ ARTICHOKE NEXT RECORD
AT END GO TO FILEOUT.
For further information concerning the mechanics of the READ NEXT
statement, see Section 6.2.5.7, Specifying the Next Record to be Read.
The READ with key takes the value in the relative key, moves it to the
current record pointer,
and reads the record being pointed to. The
following READ (with key) statement reads the file named ARTICHOKE
randomly,
selecting records through the value in the file's relative
key.
If the relative key supplies a value that does not contain a
valid record, the statement causes program control to transfer to the
subroutine named NO-REC.
READ ARTICHOKE RECORD
INVALID KEY GO TO NO-REC.
If the file has more than one record description,
the records
automatically share the same current record area. The OTS does not
clear this area before it executes the READ statement
(no blank
filling,
etc.).
Therefore,
if the record read by the latest READ
statement does not fill the entire current record area, the area not
overlaid by the incoming record remains unchanged.
For example, if
the file's record area contains ten 3's, and a READ operation moves in
a 6-character record containing all lis, the current record area then
contains six lis followed by four
3's.
Consider the following
example:
Current Record Area with all 3's

133333333331

Next Record in the File

11111111

Current record Area after READ

111111133331

6-21

FILE HANDLING
6.2.6.4 Rewriting Records into a Relative File The
REWRITE
statement places a record back into its file on disk or magnetic tape.
The following sample statement writes the record, BREAKERS, back into
its file.
REWRITE BREAKERS.
If the file is open in the sequential access mode,
the statement
rewrites the record just successfully read.
If the file is open in
either the random or dynamic access mode, the statement rewrites the
record to the record position specified by the relative key.

6.2.6.5 writing Records in a Relative File The WRITE statement
The following sample WRITE
releases a logical record to a file.
statement releases the record BREAKERS to the device assigned to that
record's
file.
If the record already exists,
program control
transfers to the subroutine, WRITE-ERR.
WRITE BREAKERS
INVALID KEY GO TO WRITE-ERR.
The WRITE statement releases records to files that are open in either
the OUTPUT or I/O mode. The following text discusses the two modes
separately:
•

OUTPUT Mode - The WRITE statement's only function with output
files
is to place entirely new records into the file.
If
more space is required for new record positions,
the Record
Management Services automatically extends the file size,
regardless of the access mode being employed.

•

I/O Mode - The statement's function with input-output files
is to place records in record positions that already exist
and are empty.
The length of the records must not exceed the
the file when it was
maximum length record specified for
created.

The relative WRITE statement creates only storage files
since
print-files are sequential files.
The following SAMPLE statement
writes a record named BREAKERS into its file:
WRITE BREAKERS.

6.2.6.6 Deleting Records from a Relative File The DELETE statement
logically removes an existing record from a relative file. After a
that
DELETE statement has successfully removed a record from a file,
record can no longer be accessed.
If the file is open in the sequential access mode,
the statement
removes the record just successfully read.
For example, the following
sample statement removes the record just read from the file named
ARTICHOKE:
DELETE ARTICHOKE RECORD.

6-22

FILE HANDLING
If the file is open in either the random or dynamic access mode,
the
statement removes the record from the record position specified by the
relative key. For example, the following sample statement deletes the
record specified by the relative key from the file named ARTICHOKE;
if the relative key supplies a value that does not contain a valid
record,
the statement transfers control to the subroutine named
NO-REC.
DELETE ARTICHOKE RECORD
INVALID KEY GO TO NO-REC.

6.2.6.7 Specifying the Next Record to be Read - The START statement
specifies which record in a file will be the next one to be referenced
sequentially.
A READ NEXT statement should follow the START statement since the READ
NEXT statement reads the next record from the one being pointed to by
the current record pointer.
If the data area, SOMETHING, in the following example contains a 30
and position 33 in the file contains the next present record, the
START statement sets the current record pointer to one less than 33
(32) .
The READ NEXT statement would then find the next present
record, which we know is 33.
WORKING-STORAGE SECTION.
77 SOMETHING PIC S99 VALUE 30.
77 ARTKEY PIC 99.

RD-SET.

MOVE SOMETHING TO ARTKEY.
START ARTICHOKE
KEY IS GREATER THAN ARTKEY
INVALID KEY GO TO NEWKEY.

INI.

READ ARTICHOKE NEXT RECORD
AT END GO TO FILEOUT.

The value of the RELATIVE KEY data item specified in the statement
(ARTKEY in the preceding example) together with the conditional phrase
specified in the statement (IS GREATER THAN in the preceding example)
determines which record in the file will be accessed by the READ NEXT
statement.
The START statement uses the value in the RELATIVE KEY data item to
set the current record pointer.
If record positions 30 and 33 contain
valid records and ARTKEY contains 30, the START statement would set
the current record pointer and RELATIVE KEY data item as follows:
1.

If the conditional phrase specifies KEY IS GREATER THAN
ARTKEY, the statement sets the current record pointer to 32.

If the conditional phrase specifies KEY IS EQUAL TO ARTKEY or
NOT LESS THAN ARTKEY, the statement sets the current record
pointer to 29.

The READ NEXT statement takes the number in the current record pointer
and finds the next present record from that number.
(If the pointer
contains a 30 and the next present record is in position 33, it finds
record number 33).
The READ NEXT statement gets that record and
places its record position number (33) into the current record pointer
and the relative key.
6-23

FILE HANDLING
A subsequent READ NEXT takes the number in the current record pointer,
which is now 33 in our example, and finds the next present record.
It
fetches that record and places its record position number
in the
current record pointer and relative key.

6.2.6.8 Closing Relative Files The CLOSE statement terminates
processing on the file referred to in the statement. The following
sample CLOSE statement terminates processing on the file named
ARTICHOKE:
CLOSE ARTICHOKE.
When the statement closes a file, no other I/O operation
that file until another OPEN statement opens the file.

can

access

If the statement specifies the LOCK option, the
the file again in that run.

cannot

open

If a SAME AREA clause contains the name of the file just closed,
program may open one of the other files named in the clause.

the

6.3

program

INDEXED FILE ORGANIZATION

Unlike the physical ordering of records in a sequential file or the
relative positioning of records in a relative file, the location of
records in the indexed file organization is transparent to your
program.
The presence of keys in the records of the file governs the
placement of records in an indexed file.
A key is a character string present in every r~cord of an indexed
file.
The location and length of this charact~r string is identical
in all records. When creating an indexed file,
you decide which
character string in the file's records is to be a key.
By selecting
such a character string, the contents (i.e., key value) of that string
in any particular record written to the file can be used by a program
to identify that record for subsequent retrieval.
You must define at least one key for an indexed file. This mandatory
key is the primary key of the file.
Optionally, you can define up to
255 additional keys
(i.e.,
alternate keys).
Each alternate key
represents an additional character string in records of the file. The
key value in anyone of these additional strings can also be used as a
means of identifying the record for retrieval.
As programs write records into an indexed file, the values contained
in the primary and alternate keys are used to locate the record in the
file.
From the values in keys within records a tree-structured table
known as an index is built. An index consists of a series of entries.
Each entry contains a key value copied from a record that a program
wrote into the file.
with each key value is a pointer to the location
in the file of the record from which the value was copied. A separate
index is built and maintained for each key you define for the file.
Each index is stored in the file.
Thus, every indexed file contains

6-24

FILE HANDLING

at least one index, the primary key index.
When you define alternate
keys, an additional index is built and maintained for each alternate
key.
Figure 6-3 shows the general structure of an indexed file that
has been defined with only a single key.
Figure 6-4 depicts an
indexed file defined with two keys, a primary key and one alternate
key.

KEY DEFINITION

ABLE

JONES

SMITH

,--------------------------------DATARECORDS-------------------------------

Figure 6-3

Single Key Indexed File Organization

6-25

KEY DEFINITIONS

ALTERNATE INDEX

PRIMARY INDEX
(Employee Name)

I"Ij

t"1

t!l

0'\

~
o

/'/'

-. .- ?- ----, -//I('/'

0'\

------

t"1

(j)

ABLE

ELM AV

24379

JONES

I MAIN ST

19724

SMITH

I HOLT RD

DATA RECORDS

Figure 6-4

11733

Multi-key Indexed File Organization

FILE HANDLING
6.3.1

Record Size

A relative file may contain either fixed-length or variable-length
records.
(Fixed-length records have one or more record descriptions
that describe the same size record. Variable-length records have more
than one record description that describe several different sized
records.) For variable length records in an indexed file, the software
adds a two byte count field. On a write operation the actual record
is written out to the I/O device not the maximum length record.
The
length of this record is placed in the two byte count field. On a
read operation this two byte count field is used to determine the
length of the record to be read in.

6.3.2

RECORD CONTAINS Clause

The RECORD CONTAINS clause, when specified without the "integer-l TO"
option,
is for documentation purposes only. The compiler determines
record size from the data descriptions.
When the "integer-l TO"
option is specified,
it forces the compiler to generate a variable
length record file, even if the data descriptions describe fixed
length records.
Conversely, if the data descriptions for a sequential file describe
variable-length records,
the software sets up variable sized records
automatically and ignores this clause.
Even though the software ignores the values in the "integer-l TO ..• "
phrase,
the clause may be used in any program to document record
sizes.

6.3.3

SAME RECORD AREA Clause

The SAME RECORD AREA clause is identical for all
See Section 6.1.3.

6.3.4

file

organizations.

Record Blocking

The size of a file is expressed as an integral number of virtual
blocks.
Virtual blocks are physical storage structures. That is,
each virtual block within a file is a unit of data whose size depends
on the physical medium on which the file resides.
Indexed files may reside only on disk. The size
within ~iles on disk devices is always 512 bytes.

virtual

blocks

Indexed files, like relative files, use a logical storage structure
known as a logical block or bucket. A bucket consists of 1 to 32
virtual blocks. The user may specify the number of virtual blocks
contained within each bucket by using the BLOCK CONTAINS clause. This
distinction should be made clear.
A virtual block is a physical
entity which is fixed in size and cannot be changed by the user. A
bucket is a logical entity and its size is directly under user
control.
Records may span virtual block boundaries. They may never
span bucket boundaries.

6-27

FILE HANDLING
Increasing the bucket size increases the speed of processing of a file
because fewer
I/O operations are needed to access the smaller number
of buckets in the file.
On the other hand, a larger bucket size means
that more memory space is taken up by the I/O buffers.
There are three ways that the bucket size may be specified by the user
in a COBOL program:
by default, by using the construct BLOCK CONTAINS
integer RECORDS, or by using the construct BLOCK CONTAINS
integer
CHARACTERS.
The default is to make the bucket size as small as possible to
minImlze the memory buffer space required.
By using the BLOCK
CONTAINS (integer RECORD or
integer CHARACTERS)
clause, you can
increase the memory buffer space required.
Increasing the buffer
space allows faster I/O by decreasing the number of operations to
process a file.
The following paragraphs further define the three
blocking methods:
Default
The default philosophy is to make the bucket size as small as
possible to minimize the memory buffer space required. The
algorithms for calculating the bucket size follow:
Bnum= ((22+Rlen)/512)+1 Fixed length record
or
Bnum= ((24+Rmax)/512)+1 Variable length record
where:
Bnum

is the number of virtual
from 1 to 9.

blocks

per

Rlen

is the fixed record length (in bytes).

Rmax

is the maximum record length (in bytes)
length is variable.

bucket,

ranging

record

the

The number 22 comes from a bucket overhead of 15 bytes and a
fixed length record header of 7 bytes;
24 comes from a bucket
overhead of 15 bytes and a variable length record header of 9
bytes.
Table 6-6 gives the bucket size for possible record lengths.
Table 6-6
Bucket Size for possible Record Lengths
Bnum

Rlen

Rmax

1
2
3
4
5
6
7
8

1-490
490-1002
1003-1514
1515-2026
2027-2538
2539-3050
3051-3562
3563-4074
4075-4095

1-488
489-10UO
1001-1512
1513-2024
2025-2536
2537-3048
3049-3560
3561-4072
4073-4095

6-28

FILE HANDLING
BLOCK CONTAINS Rnum RECORDS
If the BLOCK CONTAINS num RECORDS clause is used, where num is an
integer,
then the following algorithms are used to calculate the
bucket size.
Bnum= «15+(Rlen+7)*Rnum)/5l2)+1

Fixed length record

or
Bnum= «15+(Rlen+9)*Rnum)/512)+1

Variable length record

where:
Bnum

is the number of virtual
from 1 to 32.

blocks

per

bucket,

ranging

Rlen

is the fixed record length (in bytes).

Rmax

is the maximum record length (in bytes)
length is variable.

record

Rnum

is the number of records per bucket
BLOCK CONTAINS clause.

given

the

The number 15 is bucket overhead, 7 is the fixed length
header and 9 is the variable length record header.

the

record

BLOCK CONTAINS Cnum CHARACTERS
If the BLOCK CONTAINS Cnum CHARACTERS clause is used, where Cnum
is an integer, then Cnum is subject to the following constraints.

(1)

Cnum ~Rlen+l

for fixed length records
or

Cn urn <Rmax+ 3
(2)

for variable length records

Cnum mod 512=0

Based on Cnum, the bucket size is calculated as follows:
Bnum=Cnum/5l2
where:
Cnum

is the number of characters per bucket as given in
BLOCK CONTAINS clause.

Rlen

is the fixed record length (in bytes).

Rmax

is the maximum record length (in bytes)
length is variable.

Bnum

is the number of virtual
from 1 to 32.

6-29

blocks

per

the

bucket,

the

record
ranging

FILE HANDLING
Violation of constraint (1) causes a
method is used to calculate the
means that Cnum should be a multiple
error is given and Cnum is increased
512.

fatal error and the default
bucket size. Constraint (2)
of 512. If not, a warning
to the next even multiple of

The bucket size must be the same when the file is created and
each time the file is accessed. Therefore, the BLOCK CONTAINS
clause must never change for a particular file.
Note:

The previous discussion has used the following format:
RECORDS
}]
{ CHARACTERS

[BLOCK CONTAINS integer
If the following format is used:
[BLOCK CONTAINS [integer-l TO]integer-2

RECORDS

}]

{ CHARACTERS

the compiler ignores integer-I, and integer-2 is used as the integer.

6.3.5

Buffering

When the system performs a sequential or random input operation, one
or more index buckets are read into the buffer area until the bucket
containing the specified record is located. The bucket containing the
record is then read into the buffer area. Any subsequent sequential
read operations will use the current index buffer to locate and read
subsequent records in the current or other record buckets. When it
has exhausted the current index buffer
(has read all the records
identified in the bucket), the system reads the next index bucket into
the buffer area.
When performing a sequential or random output operation, the system
moves a record from the files current record area into the files
buffer. Each subsequent write operation moves a record from the
current record area into the buffer. The system writes the bucket to
the medium when it has filled the buffer. Every output operation also
causes the appropriate index bucket to be read into the buffer area,
the indexes for each of the keys to be added to the appropriate
buckets, and the buckets to be rewritten to the storage medium.

6.3.5.1 Buffer Size - Buffer size depends on the size of the largest
record in the file and on the blocking factor. For indexed files,
buffer size must be some multiple of 256 words (512 bytes).

6.3.5.2 I/O Buffer Areas - The RESERVE clause in the Environment
Division specifies the number of I/O buffer areas to be allocated for
each file. Each I/O area represents the space for one bucket.
A
minimum of two is required for an Indexed file (this is the default).
Three areas will increase the speed of random access. Four areas will
increase the speed of random access if the file is being accessed on
two different keys. For each additional key, an additional area will
increase the speed of access. Therefore, to speed up random access
6-30

FILE HANDLING
time, the optimum number of buffer areas is equal to
keys by which the file is being accessed plus two.
area means that more memory space is being taken up.

the number of
Of course, each

6.3.5.3 Buffer Space To calculate the total amount of buffer space
required for each Indexed file, the following algorithm may be used:
Buffer Space = record size+«bucket size+20)*no.
+(48*no.

of areas)

of keys in file)+«MAXKSIZ*2+MAXNKEY+3)/4*4)

+272
where:
MAXKSIZ

is the maximum key size in the program.

MAXNKEY

is the maximum number of record keys for any file in
the program.

Note that in the division, the result is truncated to the next
integer.

lowest

In addition to the above, there are 76 bytes of buffer space that are
shared among all files and 44 times MAXNKEY bytes of buffer space that
are shared among all indexed files.

6.3.5.4 Sharing Butter Space Among Files The SAME AREA clause
provides a simple method of sharing buffer space among several files.
This clause is identical for all file organizations and is described
in Section 6.1.6.4.

6.3.6

Indexed I/O Statements

The COBOL I/O statements, CLOSE, DELETE, OPEN, READ,
and START can refer to indexed files.

WRITE,

REWRITE,

A COBOL program may open an indexed file in one of three modes, INPUT,
OUTPUT, or I-a, and access an open indexed file in one of three ways,
sequentially, randomly, or dynamically.
In INPUT mode, records may be
read from the file;
in OUTPUT mode, the file is created and records
may be written to the file;
in I-a mode, records may be read from the
file,
updated on the file, deleted from the file, or written to the
file. The following table shows which statements and access methods
apply to the three different OPEN modes of indexed files.

6-31

FILE HANDLING
Table 6-7
Indexed OPEN Modes
File Access
Mode

Sequential

Random

Dynamic

Statement
DELETE
READ
REWRITE
START
WRITE
DELETE
READ
REWRITE
START
WRITE
DELETE
READ
READ NEXT
REWRITE
START
WRITE

Input

Open Mode
Output

1-0

x
X
X

X
X
X

X
X

X
X
X

x
X

NOTE
The term, current record pointer,
used
in the following sections, refers to a
location in the operating system used to
store the record number of available
record in a file.

6.3.6.1 Access Mode The ACCESS MODE clause in the File-Control
paragraph indicates which of the three access modes may be used on
that file.
When the ACCESS MODE clause specifies SEQUENTIAL, the I/O
statements must refer to the records in the file sequentially,
starting (after opening) with the first record and stepping through
with each reference to the end of the file.
When the ACCESS MODE clause specifies RANDOM, the I/O statements refer
to the records in the file by the value of the key or keys. Usually
the prime key is used unless a specific alternate key is designated.
If an I/O statement refers to a record with a key, and that record
does not exist, the INVALID KEY imparative statement may be executed
depending on the particular I/O statement used.
(The INVALID KEY
imperative statement is explained with each of the indexed I/O
statements in this section.)
When the ACCESS MODE clause specifies DYNAMIC, the I/O statements may
refer to the records in the file either sequentially or randomly. The
OTS determines which access method to use from the OPEN mode
(INPUT,
OUTPUT, or 1-0)
and the form of the I/O statement.
For example, if
the statement READ .•. INVALID KEY is to access an open input file
dynamically,
the OTS uses the designated key for random access.
If
the statement READ NEXT
... is to access an open input
file
dynamically, the OTS sequentially accesses the next existing record.
6-32

FILE HANDLING
The following sections (6.3.6.2 through 6.3.6.8)
on using the I/O
statements themselves contain additional information about access
modes.

6.3.6.2 Opening Indexed Files - The OPEN statement for an indexed
file makes an INPUT, OUTPUT, or 1-0 mode file available so the COBOL
program can access the records in the file sequentially, randomly,
or
dynamically. Consider the following example:
Example
The following sample OPEN statement opens the file named ARTICHOKE for
input, and sets ARTICHOKE's current record pointer to the first record
in the file. The program containing this statement could, after
executing
the statement,
access ARTICHOKE with READ and START
statements in the sequential access mode, READ statements in the
random access mode, or READ, READ NEXT, and START statements in the
dynamic access mode.
OPEN INPUT ARTICHOKE.
When the OTS executes an OPEN statement,
it
actions for the file named in the statement:

performs

the

following

•

When opening an existing file, the attributes
(i.e.,
record
length,
block size, etc.) of the file are used for accessing
the file.
Those specified in the program are ignored.
Be
sure that the attributes specified in the COBOL program agree
with the actual attributes of the file.

•

If a SAME AREA clause contains the name of the file and none
of the other files named in the clause is open, thp OTS
allocates buffer space for the file.

•

When the file has passed all of the preceding checks and is
ready for opening,
the OTS instructs the Record Management
Services to open the file.
If the Record Management Services
fails to open the file, the OTS reports an error condition
and performs any applicable USE procedure (if present).

•

Finally, depending on which statements apply to the open
mode,
the OTS enables or disables all of the program's I/O
statements that refer to the file
(see Table 6-7).
For
example,
if the OPEN mode is INPUT, it enables all READ and
START statements for that file and disables all REWRITE,
DELETE and WRITE statements for that file.

The OPEN statement sets the current record pointer for the file to the
first existing record in the file as established by the prime record
key.
If the file is being accessed randomly or dynamically,
the
program should maintain correct values in the prime and aternate key
fields.

6-33

FILE HANDLING
6.3.6.3 Reading Indexed Files When applied to a file being
accessed sequentially,
the READ statement makes the next logical
record of an open file available to the program. The information made
available is based on positioning by the OPEN, START, or last READ
operation.
When applied to a file being accessed randomly,
the READ statement
selects a specified record from an open file and makes it available to
the program. The value of the specified key (prime key, if the no key
is specified) identifies the record.
When applied to a file being accessed dynamically, the READ statement
has two formats so that it can either select the next logical record
(sequentially) or select a specified record
(randomly)
and make it
available to the program. The READ NEXT statement takes the number in
the current pointer and finds the next present record. The following
sample READ statement reads the file named ARTICHOKE sequentially and,
when it exhausts the file, causes program control to transfer to the
subroutine named FILEOUT:
READ ARTICHOKE NEXT RECORD
AT END GO TO FILEOUT.
For more information concerning the mechanics of the READ NEXT
statement see Section 6.3.6.6, Specifying the Next Record To Be Read.
The READ with key takes the value in the specified key, moves it to
the current record pointer, and reads the record being pointed to.
The following READ (with key) statement reads the file named ARTICHOKE
randomly, selecting records through the value in the file's primary
key. If the designated key supplies a value that is not identified
with a valid record, the statement causes program control to transfer
to the subroutine named NO-REC.
READ ARTICHOKE RECORD
INVALID KEY GO TO NO-REC.
Note:
a random read repositions the current recprd pointer
effects further sequential reads.

and

thus

If the file has more than one record description, the records
automatically share the same current record area. The OTS does not
clear this area before it executes the READ statement
(no blank
filling,
etc.).
Therefore,
if the record read by the latest READ
statement does not fill the entire current record area, the area not
overlaid by the incoming record remains unchanged.
For example, if
the file's record area contains ten 3's, and a READ operation moves in
a 6-character record containing alII's, the current record area then
contains six lis followed by four 3's.
Consider the following
example:
Current Record Area with all 3's

3333333333

Next Record in the File

111111

Current Record Area after READ

1111113333

6.3.6.4 Rewriting Records into an
Indexed
File - The
REWRITE
statement releases a logical record to an output or input-output file.
In all of the access modes, the record is positioned based on the
prime key, any alternate keys are also processed properly, including
6-34

FILE HANDLING
duplicate keys.
If more space is required for new record positions,
the Record Management Services automatically extends the file size,
regardless of the access mode being employed.
If the file is open in sequential access mode and the records are not
written in ascending order of the prime key values, an INVALID KEY
condition exists. In any access mode an attempt to write an existing
record having the same prime key value or an alternate key value where
duplicates are not allowed, results in an INVALID KEY condition.
The following sample WRITE statement releases the record BREAKERS to
the indexed file.
If the record already exists, program control
transfers to WRITE-ERR.
WRITE BREAKERS
INVALID KEY GO TO WRITE-ERR.
The indexed WRITE statement creates
print-files are sequential files.

only

storage

files

because

6.3.6.5 Deleting Records from an Indexed File - The DELETE statment
logically removes an existing record from a file. After a DELETE
statement has successfully removed a record from a file,
that record
can no longer be accessed.
If the file is open in the sequential access mode, the statement
removes the record just successfully read. For example, the following
sample statement removes the record just read from the file named
ARTICHOKE:
DELETE ARTICHOKE RECORD.
If the file is open in either the random or dynamic access mode,
the
statement removes the record from the record specified bi the prime
key. For example, the following sample statment deletes the record
specified by the prime key from the file named ARTICHOKE. If the
prime key supplies a value that does not contain a valid record,
the
statement transfers control to NO-REC.
DELETE ARTICHOKE RECORD
INVALID KEY GO TO NO-REC.

6.3.6.6 Specifying the Next Record to be READ - The START statement
specifies which record will be the next record to be referenced
sequentially in a file opened for INPUT or 1-0 processing. The START
statement updates the current record pointer for future sequential
READs.
Suppose we have the following START statement:
START FILE-A KEY IS EQUAL TO SUB-KEY-A.
SUB-KEY-A must be alphanumeric.
In addition, SUB-KEY-A must be a
record key or alternate record key or subordinate to a record key or
alternate record key whose leftmost character position corresponded to
its own leftmost character position. For example, if the following
fields were defined in the record:

6-35

FILE HANDLING
02 KEY-A.
03 SUB-KEY-A.
04 SUB-KEY-Al PIC XXX.
04 SUB-KEY-A2 PIC XX.
03 SUB-KEY-B PIC XXX.
and if KEY-A was a record key or alternate
following would be legal START statements:

record

key,

then

the

not

START FILE-A KEY IS EQUAL TO KEY-A.
START FILE-A KEY IS EQUAL TO SUB-KEY-A.
START FILE-A KEY IS EQUAL TO SUB-KEY-Al.
The following START statements are illegal.
START FILE-A KEY IS EQUAL TO SUB-KEY-A2.
START FILE-A KEY IS EQUAL TO SUB-KEY-B.
The leftmost character positions of SUB-KEY-A2 and SUB-KEY-B
correspond to the leftmost character position of KEY-A.

The relational operator IS EQUAL TO (or IS =) means that the current
record pointer is set to point to the record associated with the first
key equal to SUB-KEY-A. If SUB-KEY-A is shorter than the record key
or alternate record key, then the record keys or alternate record keys
in the file are truncated on the right to the same length as SUB-KEY-A
for the purposes of the comparison.
If the following START statement is used:
START FILE-A KEY IS GREATER THAN SUB-KEY-A.
or
START FILE-A KEY IS > SUB-KEY-A.
then the current record pointer is set to point to the record
associated with the first key that is greater than SUB-KEY-A. Thus,
if the file had records with the following keys:
Record #
KEY-A

743
ABCDDZZX

629
ABCDEABC

015
ABCDEXYZ

891
ABCDEZZZ

233
ABCDGAAA

and SUB-KEY-A contained ABCDE, then the current record
be set to point to record number 233.

371
ABCDGZZX

pointer

would

If the following START statement is used:
START FILE-A KEY IS NOT LESS THAN SUB-KEY-A.
or
START FILE-A KEY IS NOT

< SUB-KEY-A.

then the current record pointer is set to point to the record
associated with the first key that is greater than or equal to
SUB-KEY-A. In the previous example that would be record number 629.

6-36

FILE HANDLING
If there is no record that satisfies the comparison, the
exit is taken. In our example the following statement:

invalid

key

START FILE-A KEY IS EQUAL TO SUB-KEY-A.
would take the invalid key exit if SUB-KEY-A contained ABCDF.
If the comparison is satisfied and the current record pointer is set,
then subsequent READs would update the current record pointer using
KEY-A as the key of reference.
If the key phrase is not specified, then the default key is the
record key and the default comparison is IS EQUAL TO.

prime

6.3.6.7 Closing Indexed Files - The CLOSE
statement
terminates
processing on the file referred to in the statement. The following
sample CLOSE statement terminates processing on the file named
ARTICHOKE:
CLOSE ARTICHOKE.
When the statement closes a file, no other I/O operation can access
that file until another OPEN statement opens the file.
If the
statement specifies the LOCK option, the program cannot open the file
again in that run.
If a SAME AREA clause contains the name of the
file just closed, the program may open one of the other files named in
the clause.

6.4

DEVICES

The TRAX COBOL object time system supports any devices supported by
the Record Management Services. Table 6-8 contains a partial list of
these devices:
Table 6-8
Device Codes
Device Code

Device
Disk
Disk (RM02/03)

Disk (RKO 7)

Disk (RP04/05/06)

Line Printer

Magnetic Tape ( TE 16 ITU 4 5 )

6-37

FILE HANDLING
Some devices are better suited to certain uses than others.
For
example, since TRAX COBOL is a disk-oriented system,
the
disk
provides COBOL files with the best performance and reliability.
On
the other hand, COBOL files on magnetic tape are limited to sequential
organization.
The following subsections discuss the devices that are
how to use them to best advantage.

6.4.1

available

and

Disk

The primary means for storage and processing TRAX COBOL files
is
a disk. Several disk units are supported, including RK05, RFll,
RPll/RP03, RP04 and RS04. Each device has its own file
handling
characteristics, and differs with respect to capacity, speed, and
portability. The following table compares these characteristics.
Table 6-9
Comparison of TRAX System Disk Devices
Device

RP05/06

RM02/03

RK07

CAPACITY

VERY HIGH
(80,000
BLOCKS)

VERY HIGH
(65,000 130,000
BLOCKS)

HIGH
(54,000
BLOCKS)

SPEED

HIGH

PORTABILITY

HIGH (EASY)

6-38

FILE HANDLING
6.4.2

Magnetic Tape

TRAX systems support magnetic tape files; all COBOL operations
concerned with magnetic tape are fully supported by the compiler,
including the MULTIPLE-FILE TAPE clause and the CLOSE REEL
[WITH NO
REWIND] clause.

6.4.3

Line Printer

COBOL programs can use both a support terminal and
I/O devices.

line

printeras

The default device for the ACCEPT and DISPLAY statements is the
support terminal. For example, consider the following coding:

TRAX

PROCEDURE DIVISION.

ACCEPT INREC.

DISPLAY OUTREC.

Figure 6-5

Use of ACCEPT and DISPLAY Statements
With TRAX Support Terminal

If filenames have been assigned to these devices in the SELECT clause
of the File-Control paragraph, the READ and WRITE statements can
access them for I/O files.
For example, consider the
following
coding:

6-39

FILE HANDLING

FILE CONTROL.
SELECT OUTFILE ASSIGN TO "LP:".

FD OUTFILE
DATA RECORD IS OUTREC.

PROCEDURE DIVISION.

OPEN OUTPUT OUTFILE.

WRITE OUTREC.

Figure 6-6

6.5

Assigning the Line Printer
to Files

FILES AND FILENAMES

The OTS and the operating system use the device codes described in
Section 6.4 to communicate with the devices. Further, the COBOL OTS
uses the operating system's file specification and interfaces for all
file manipulation with file storage devices (disk and magtape). The
VALUE OF 10 clause (discussed in the following subsection) in the FO
entry describes the file specification to the OTS. The format for the
full file specification follows:
dev: [uic] filename.tYPiversion/switches
where:
dev:

- device code

[uic]

- user's identification code or the code of the user
for whom the file was created - the user directory
10.
(The brackets [ ] are required.)

filename

- an alphanumeric field containing
characters that identifies the file.

nine

typ

- an alphanumeric field containing up
characters that qualify the filename.

three

version

- a numeric field containing up to five octal digits
that give the version number of the file.
By
specifying version numbers, the user can maintain
several versions of the same file on a directory
device.

switches

- identifies certain actions for the operating system
to
perform for the file.
(Subsection 6.5.1.1
discusses these switches.)

6-40

FILE HANDLING
These entries default as follows:
dev:

- the device code of the disk containing the operating
system.

[uic]

- the user identification code of the
using the system.

filename

- null

typ

- null

version

user

currently

• input files - the highest numbered version of
file (thus selecting the latest version);

the

• output files
one greater than that of the
highest
numbered
verSlon of the file
(thus
creating the latest version).
switches

- null

For example, the following sample file specification causes the file
system to process version 3 of a file on disk named ARIES. The user
has an identification code of 140,222.
DB: [1 4

6.5.1

°,2 2 2 ] AR I ES ; 3

Using Explicit Filenames (VALUE OF 10 Clause)

The VALUE OF ID clause,
in the FO entry, describes the file
specification to the COBOL OTS. The VALUE OF 10 clause is optional;
however, the system requires it whenever the program refers to an
explicit file unless a sufficient file description is provided in the
ASSIGN clause. The clause accepts either a literal entry or an
identifier entry.
Consider the following sample literal form of the
clause:
VALUE OF 10 IS "DB: [140,222]ARIES;3"
Elements of the file specification appearing in the VALUE OF 10 clause
supersede their counterparts specified in the ASSIGN clause for the
file.
(Subsection 6.5.2 discusses the ASSIGN clause.)
When written in the literal form, the literal may be a
specification or a part of a file specification.

complete

file

When written in the identifier form, the value of the
be a complete or partial file specification.

identifier

may

The identifier form of this clause is especially useful when different
runs of a program process different files.
If a program must process
different files in the same way on different runs, an ACCEPT statement
in the Procedure Division can request a file specification from the
user at the user's console or from a batch input stream.

6-41

FILE HANDLING
The following example illustrates how a COBOL program could request
file specification from an interactive terminal:

DATA DIVISION.

FD FILEIN
VALUE OF 10 IS INFILE.

WORKING-STORAGE SECTION.
77 INFILE PIC X(20).
PROCEDURE DIVISION.

DISPLAY "TYPE IN INPUT FILE SPEC".
ACCEPT INFILE.

OPEN INPUT FILEIN.
This sample coding causes the following
interaction between the
program
and the user
(the message printed by· the program is
underlined) :
TYPE IN INPUT FILE SPEC
DBI : THOREAU ~
Following this interaction, the sample OPEN statement will
input) the file, THOREAU on DBI.

open

(for

6.5.1.1 Switches - There are four optional switches which may qualify
the
file
specification.
These switches modify the processing
performed by the COBOL OTS when it opens the file.
Table 6-10 contains a list of the file switches and their meanings
the OTS.

6-42

FILE HANDLING
Table 6-10
File Specifier Switches
SWITCH
/CL:n

MEANING
Allocate disk space in clusters of n virtual blocks
whenever the file needs additional storage space during
output operations.
(n may be any number from 1 to 256
in powers of 2.)
If the number is followed by a
decimal point, the software considers the number to be
decimal:
if it do~s not have a decimal point, it is
considered to be octal).
This switch would be used only when very large files
are to be created and the output device can hold the
entire file (i.e., an RM02/03 disk). The effect of this
switch is to make file accessing faster when the file
is being processed sequentially.

/CO:n

Allocate a contiguous file of n disk blocks to the file
when it is opened.
This switch ensures that n blocks
are available for the file prior to actual processing.
(When"many users are sharing the same disk, you can use
this switch to ensure that your entire file will fit on
the disk.)
It applies only to output files
being
created.
If a decimal point follows the number, the
system considers it to be decimal: otherwise,
octal.}

ISH

This file is shared for output or I/O mode, available
for writing or altering by other tasks
(or jobs)
running concurrently with the COBOL program.
The ISH
switch must not be specified for sequential files.
For
all other files, the following rules apply.
• The ISH switch should be used consistently among
concurrently executing tasks. That is, if the ISH is
specified for one task sharing the file,
all tasks
sharing the file should have it specified,
and
vice-versa.
• If a file is being opened for OUTPUT or I/O with the
ISH switch specified, all other tasks currently using
the file must also have the ISH switch specified.
• If a file is being opened for input without the ISH
switch set, no other task can be using the file for
output or I/O.
• If a file is being opened for INPUT and no ISH switch
is specified,
all other tasks currently using the
file should not have the ISH switch specified.
If access is denied when the file is opened because of
one of the above reasons, a file status code of 91 is
stored in the FILE-STATUS data-item associated with the
file if one is specified.

/AL:n

Same as the /CO:n switch with the following exception.
The /CO:n specifies that all blocks be contiguous, and
the /AL:n switch specifies that all blocks need not be
contiguous.

6-43

FILE HANDLING
6.5.2

Device Assignment by ASSIGN Clause

If the VALUE OF IO clause does not specify a complete
file
specification, the ASSIGN clause in the File-Control paragraph can
assign a defalt to those components not specified. The ASSIGN clause
must be written as part of the SELECT statement as shown below:
SELECT THOREAU ASSIGN TO "OBI:"
This example assigns a default device code "OBI:" for the location of
the file THOREAU. Another device code specification in the VALUE OF
IO clause could override it later in the source program.

6.5.3

Files and Logical Units

Each file in an executable task must have a unique Logical Unit Number
(LUN) assigned to it. The COBOL compiler can only generate a relative
LUN assignment for each file in a COBOL program, because there may be
multiple COBOL programs in a task.
(See Figure 2-8 which contains a
sample file-to-relative-LUN assignment table.) Actual LUN assignments
are made by the COBOL Object Time System (OTS) at task execution time.
The number of LUNs needed by a task is equal to l+n, where n is the
total number of individual files included in each program comprising
the task.
For example, if a task consists of three programs, each
program requiring three files, then the number of LUNs required is 10.
(The first LUN is
reserved
for
ACCEPT/DISPLAY
and
message
processing.)
If more than six LUNs are required for an executable
task, the UNITS option must be specified at link time, because the
TRAX Linker default is 6.
Each LUN must have a physical device associated with it before the
associated file can be opened. You can assign a physical device to
the file by specifying the VALUE OF IO or ASSIGN clause in your COBOL
program, or you can specify the ASG option at task-build time.
NOTE
The default LUN assignments generated by
the Task Builder do not always equate to
the system device.
(Refer to the TRAX Linker Reference Manual for your
particular
operating system for more information concerning link options.)
As previously stated, each COBOL program receives relative LUN
assignments for
its files by the compiler. At task-execution time,
the OTS converts these relative LUN assignments to actual assignments
according to the following rules:
1.

If the task consists of only one COBOL program, the OTS adds
1 to each of the relative LUN assignments yielding the actual
assignments. Therefore, a file receiving a relative LUN
assignment of 2 by the compiler would receive an actual LUN
assignment of 3 at execution time.

If the task consists of more than one COBOL program having
files assigned to it, simply adding 1 to the relative LUN
assignments would obviously yield duplicate actual
LUN
assignments. The OTS, in the case of multiple program tasks,
utilizes the relative assignment +1 formula for the first
6-44

FILE HANDLING
program in the task.
For each subsequent program, it takes
the highest actual LUN assignment for
the previous program
and adds 1 to it to arrive at the first LUN assignment.
It
then applies the +1 formula to this first LUN assignment to
arrive
at each subsequent assignment for
the program.
Consider the following example:
Example
A task consists of three programs (PROGA, PROGS, and PROGC).
Each program has three files with relative LUN assignments of
1, 2, and 3. At execution time, assuming that the programs
were presented to the Linker or to the Merge utility in the
order PROGA, PROGS, and PROGC, the OTS would assign actual
LUNs as follows:
Program

LUN assignment
1 (reserved for ACCEPT/DISPLAY and message
processing)

PROGA
2
3
4

1st. File
2nd. File
3rd. File

FROGS
6
7

1st. File
2nd. File
3rd. File

8
9
10

1st. File
2nd. File
3rd. File

PROGC

6.6

OPTIMIZATION

At times a user may wish to optimize his program with regards to space
or time.
Often,
there is a trade-off between the two. The default
philosophy of the COSOL compiler has been to
optimize
space
allocation. A discussion of the two types of optimization follows.

6.6.1

Speed Optimization

The following COSOL clauses
execution speed.

and

phrases

6-45

may

used

increase

FILE HANDLING
SAME RECORD AREA Phrase
Default

- No Same Record Area

Optimal

- Use SAME RECORD AREA phrase

Effect

- May save compute time.
If records
are being copied from one file to
another and if both files
share the
same
Record
Area,
then no move
statement is needed to move
the
records from one record area to the
other.

Use more space?

- No, uses less space

Other potential drawbacks - Records from both files will not be
available simultaneously (unless one
is moved so it can be saved), because
one record will wipe out the other.

BLOCK CONTAINS Clause
Default

- Bucket or logical block consists of
smallest number of virtual blocks.

Optimal

- Make bucket or logical block as large
as possible.

Effect

- Speeds sequential access by
amount of I/O to disk.

Use more space?

- Yes

reducing

Other potential drawbacks - None
For indexed files, the following clauses and phrases may
further increase execution speed.

used

RESERVE Clause Default

2 AREAS

Optimal

- Make the number of areas equal to the
number of keys of access + 2.

Effect

- Speeds up random access.

Use more space?

- Yes

Other potential drawbacks - None

WITH DUPLICATES Phrase Default

- Duplicates not allowed

Optimal

- Allow duplicates by using this phrase
6-46

FILE HANDLING
Effect

- Speeds up WRITE and REWRITE time. If
this phrase is not used, then the
program must check each alternate
record key on a write or rewrite, to
check that it doesn't already exist
on the file.

Use more space?

- No

Other potential drawbacks - Duplicate keys are allowed and this
may not be wanted. For example, if
the social security number is a key,
duplicate social security numbers may
be illegal.

6.6.2

Space Optimization

The default philosophy is
following COBOL clauses
space requirements.

to optimize
and phrases

space usage.
However, the
may be used to further reduce

SAME RECORD AREA
Default

- No Same Record Area

Optimal

- Use SAME RECORD AREA phrase
many files as possible.

Effect

- Instead of having a record area for
each file, all the files use the same
record area.

Slows execution time

- No

for

Other potential drawbacks - Records from both files will not be
available simultaneously (unless one
is moved in order to save
it) ,
because one record will wipe out the
other.

SAME AREA
Default

- No Same Area

Optimal

- Use SAME AREA phrase
files as possible.

Effect

- The buffer areas for all the files in
the SAME AREA phrase are shared.
Saves much more space than
SAME
RECORD AREA.

Slows execution time

- No

for

many

Other potential drawbacks - Not more than one of the files listed
in the SAME AREA phrase may be open
at any time.

6-47

FILE HANDLING
6.7

COMMUNICATING WITH THE PROGRAM

The ACCEPT and DISPLAY statements allow low-volume,
terminal-oriented
interaction between a COBOL program and the user of the program.
While these statements are intended for use with keyboard devices,
TRAX COBOL allows the ACCEPT statement to accept data from
a
TRAX
support terminal, and the DISPLAY statement to display data on a line
printer or at a TRAX support terminal.
The following two
Sections
(6.7.1 and 6.7.2) discuss these capabilities in greater detail.

6.7.1

Using the ACCEPT Statement

The ACCEPT statement makes small amounts
specified data item.

data

available

the

Consider the following example;
it causes data to be transferred from
the device identified by the mnemonic-name, OPERATOR, to the area
represented by the identifier, COMM-AREA.
ACCEPT COMM-AREA FROM OPERATOR.
OPERATOR must be a mnemonic-name specified for a device in the
Special-Names paragraph (in this example, possibly the console). The
area represented by the identifier COMM-AREA receives the data
requested without any editing.
The ACCEPT statement causes the transfer of a stream of bytes from the
device specified in the FROM phrase, if it is present (OPERATOR in the
previous example).
If the FROM phrase is not present,
the data is
transferred from the user's console.
Enough bytes are transferred to fill the identifier's area. The size
of COMM-AREA in this example dictates the number of bytes being
transferred.
If the device contains more data than there are
the data is truncated.

bytes

COMM-AREA,

•

If the length of the identifier exceeds 80 bytes,
the OTS
performs one or more additional transfers of data until it
either fills the identifier or transfers less than 80 bytes.

•

If the length of the identifier is less than or equal to 80
bytes and the length of the data is less than the identifier
on a teletype or cards, the OTS pads the identifier with
blank characters.

The ACCEPT statement has a second format that allows it to retrieve
the current DAY, DATE, or TIME from the system and store it in the
specified identifier.
(DAY, DATE, and TIME are reserved words that
the user does not define. The user must define identifiers into which
to accept the values in DAY, DATE, or TIME.)
The following sample
statement places the current date in the identifier, GREENWICH:
ACCEPT GREENWICH FROM DATE.

6-48

FILE HANDLING
DAY and DATE are treated as equivalent. A facility for specifying the
day of the year is currently not provided. The date, however, is
provided as follows (YY is the year; MM is the month;
DD is the
day):
DATE -- YYMMDO
If the date were July 4, 1976, the
with the number 760704.

systems

would

provide

GREENWICH

The systems provide the time as follows (HH is the hour;
MM is
minutes;
SS is the seconds; CC is the hundredths of a second):

the

TIME -- HHMMSSCC
If the time were 20 seconds after 5:15 PM, the systems (which have a
24-hour clock) would provide the numbers 17152000.
(Since the PDP-II
clock has no hundredths of a second capability,
the systems place
zeroes in the last two positions.)
The identifier receives the data according to the rules for the MOVE
statement.
Chapters 3 and 4 discuss the MOVE statement as applied to
non-numeric fields (Chapter 3) and numeric fields (Chapter 4).

6.7.2

Using the DISPLAY Statement

The DISPLAY statement transfers small amounts of data
specified data item or literal to the specified device.

from

Consider the following example;
it causes the transfer of data from
the area represented by the identifier, COMM-AREA, to the device with
the mnemonic-name, OPERATOR:
DISPLAY COMM-AREA UPON OPERATOR.
OPERATOR must be a mnemonic-name specified for a device in the
Special-Names paragraph
(possibly the console in this example). The
area represented by the identifier, COMM-AREA, contains the data being
transferred.
The DISPLAY statement causes the transfer of a stream of bytes to the
device specified in the UPON phrase if it is present (OPERATOR in the
preceding example). If the UPON phrase is not present,
the OTS
transfers the data to the user's console.
All of the bytes in all of the identifiers or literals in the DISPLAY
statement are transferred first.
The size of COMM-AREA, in this
example, dictates the number of bytes being transferred.
The system does not convert COMP items from binary
simply transfers them as they exist in storage.

ASCII;

If a single DISPLAY statement must transfer large amounts of data,
that data must contain appropriate vertical and horizontal form
control characters.
If the data being transferred does not contain
form control characters and the length of the data stream exceeds the
device's single line capacity, the excess characters will all print in
the last position (overprinting each other).
Table 6-11 contains several of the terminal form control characters:

6-49

FILE HANDLING
Table 6-11
Form Control Characters
Octal
Code

Control
Character

007
011
012
013
014
015

BEL
HT
LF
VT
FF
CR

(CTRL G)
(CTRL I)
(CTRL J)
(CTRL K)
(CTRL L)
(CTRL M)

Function
Bell ringer
Horizontal tab
Line feed or line space (new line)
Vertical tab
Form feed to head of form
Carriage return

When it has transferred all of the data from all of the items listed
in the statement, a carriage return and linefeed character are
automatically appended onto the data. The WITH NO ADVANCING phrase
suppresses this appending operation.
NOTE
The WITH NO ADVANCING phrase is
extension to the ANS-74 standard.

6.8

FILE COMPATIBILITY WITH OTHER PROGRAMMING LANGUAGES

All files generated by other programming languages are compatible with
COBOL provided that they were generated using Record Management
Services. Files generated by other file systems must conform to
Record Management Services formats.

6.8.1

Writing Files For Other Programming Languages

TRAX COBOL writes files that can be read only by languages using the
Record Management Services system interface for user program I/O.
When creating a file that is to be read by a language, that does not
use the Record Management Services interface
(i.e., BASIC-PLUS),
adhere to the following restrictions:
•

Ensure that the file has sequential file organization.

•

Ensure that the file is not a COBOL print-file (no LINAGE or
APPLY PRINT-CONTROL clauses are applicable to the file).
Printer control is handled differently by each
PDP-II
programming language.

•

Do not use the ADVANCING
creating the file.

option

statements

when

The file may contain fixed-length or variable-length records, and
records should only contain only printable ASCII character data.

the

6-50

WRITE

FILE HANDLING
6.8.2

Reading Files written in Other Programming Languages

TRAX COBOL reads files that were written only by languages using the
Record Management Services (RMS) system interface for user program I/O.
Before reading a file that was written by another language that does
not use the Record Management Services interface, be certain that the
file meets the following restrictions:
•

Ensure that the file is an ASCII file.

•

Ensure that the file does not have a carriage control
attribute (the FORTRAN carriage control file attribute must
not be set).

FORTRAN meets these restrictions when it writes ASCII
(not binary)
data with formatted WRITE statements. However, the user must disable
the carriage control attributes in the OPEN statement for the file.
CALL OPEN (UNIT=n, CARRIAGE CONTROL="NONE"

WRITE (n,lOO) list
FORMAT ( .••.. )
BASIC+2 is capable of reading and
Services files.
Therefore, files
compatible with COBOL.

writing
written

all Record Management
by BASIC+2 programs are

BASIC-PLUS meets all of these restrictions when it writes a formatted
ASCII
(sometimes
called sequential) file as described in the
BASIC-PLUS Language Manual.
TRAX
COBOL cannot read BASIC-PLUS
Virtual Array files.

6.8.3

Data File Transportability

The user who wishes to transport data files from one language
processor to another or from a TRAX system to some other RMS supported
system should be careful to write such files using the Record
Management Services. Record Management Services is the only file
interface used by TRAX COBOL.
Non-printable ASCII characters are subject to misinterpretation by the
different language processors and operating system utilities. If, for
example, COBOL were to write records which contained COMPUTATIONAL
(binary)
data items,
the values these items could contain would be
written in the file in the same binary format as represented in the
computer.
Such binary values may look like non-printable ASCII
characters such as CR, LF, CTRL/Z, escape, which could cause system
utilities to perform in an unpredictable manner while processing the
records.
Other ways that non-printable ASCII characters can
are:
that

the

into

USAGE

a
IS

file

having data definitions
clause;

moving HIGH-VALUES or LOW-VALUES;

moving any redefinition of a COMP or USAGE IS INDEX field;
6-51

contain

get

INDEX

FILE HANDLING
4.

reading a data
characters;

file

that

contains

non-printable

having mUltiple record definitions of varying sizes and
filling a shorter record area then writing a longer one.
(The excess characters, not filled, may be non-printing.)

ASCII

This list is not complete. There are many other ways for non-printing
ASCII characters to find their ways into printable ASCII files.

6.9

PROCESSING I/O ERRORS - USE STATEMENT

The USE statement provides COBOL programs with a way to process I/O
errors.
It allows the program to specify possible recovery steps
following the I/O handling procedures performed by the software.
When a COBOL program contains a USE procedure and an I/O error occurs,
the OTS and Record Management Services execute their standard I/O
error handling procedures and then transfer control to the procedure
following the USE statement.
(For further information concerning
run-time I/O errors, see section 12.3.)
Consider the following sample coding.
When either THOREAU
or
ARTICHOKE causes an I/O error, the OTS executes its standard I/O error
procedures and then transfers control to the paragraph (or paragraphs)
that follow the USE statement.
PROCEDURE DIVISION.
DECLARATIVES.
REPAIR SECTION.
USE AFTER STANDARD ERROR PROCEDURE
ON THOREAU ARTICHOKE.
DISPLAY-ERROR.
IF ...
The paragraphs following the USE statement may contain any valid COBOL
statement, except for the following:
1.

Those statements that refer to a procedure outside of the
DECLARATIVES.
(Any attempt to transfer control out of the
DECLARATIVES causes the OTS to abort the program.)

Those statements that would cause the USE procedure being
executed to be invoked again.
(Recursive USE procedures
cause the OTS to abort the program.)
USE p~ocedures are executed in the same manner PERFORM ranges
in Procedure Division coding. Therefore, paragraphs with the
USE procedure section should follow all rules specified for
paragraphs within PERFORM ranges.
For further information on
PERFORM ranges, see Use of the PERFORM Statement in Chapter 7
of this guide.)
If a status key is declared for the file in error, all status
information is made available for processing in the USE
procedure.

6-52

CHAPTER 7
GOOD PROGRAMMING PRACTICES

7.1

FORMATTING THE SOURCE PROGRAM

Since most COBOL programs are usually long,
the programmer needs
techniques that will help him to simplify and improve the readability
of his COBOL programs. The guidelines in this chapter,
if followed,
will help produce source programs that are easy to read and maintain.
The guidelines described in this chapter are based on the use of
Terminal format which is the TRAX COBOL default format.
Besides the
obvious advantage of an uncluttered printout, the Terminal format has
other programming advantages:
1.

it requires less storage area;

it requires no line numbers;

its statements may be aligned with tab characters.

Further, whenever required, the REFORMAT utility program will convert
Terminal format programs to the Conventional format.
(The REFORMAT
utility program is discussed in Chapter 2).
The following suggestions should help to
most complicated source programs.

further

simplify

even

the

Begin division, section, and paragraph names in column 1.
Although these names may start anywhere in Area A, aligning
them in column 1 produces a much more readable listing. When
required, place the * and - in column 1.
(Column 1 then
becomes column D.)

Insert a blank line, or one or more comment lines (describing
the purpose of the file) before each SELECT statement in the
FILE-CONTROL paragraph. Place the phrases of the SELECT
statement on separate lines and begin each of them in column
5 (use the tab character to skip over Area A). Consider
the
following illustration of a typical SELECT statement:

7-1

GOOD PROGRAMMING PRACTICES
AREA A
1 .

AREA B
.

5 • • • • • • •
SELECT MASTER-FILE
ASSIGN TO "DKl:"
ORGANIZATION IS RELATIVE
ACCESS IS SEQUENTIAL.

Place the phrases of the file description statement on
separate lines and begin each of them in column 5.
(Use the
tab to skip over Area A.) Consider the following illustration
of a typical file description entry:
AREA A

AREA B

1 .

5 •

•

MASTER-FILE
LABEL RECORDS ARE STANDARD
VALUE OF ID IS MASTER-FILE-NAME
DATA RECORD IS MASTER-pECORD.

In both the File and Working-Storage sections, begin
level items in column 1.

all

Indent,
by four columns, all
subordinate
items
with
higher-valued level numbers.
(For example, if the item that
is subordinate to a Ol-level record description is 05, begin
the record description level number in column 1 and the 05
level number in column 5.) Use the tab character for
the
first
indentation, a tab and four spaces for the second, two
tabs for the third, etc. When indented in this manner,
the
listing will show, clearly and neatly,
the hierarchical
relationships of all of the data names in the program as well
as their level number values.
Increment level numbers by 5;
then later,
if it becomes
necessary to insert additional group items,
they may be
inserted without having to change the level numbers of all
items that are subordinate to that group.
If desired, write the level numbers as single digits (such as
1 instead of 01).
Use level number 01 instead of 77 in the Working-Storage
Section.
(77, as a level number has the same meaning as 01,
and 77 may eventually be omitted from the COBOL standard.)
Since all elementary items, except for
index data items,
require PICTURE clauses,
these clauses fill a good part of
the source program listing.
However,
the PICTURE clause
itself may be simplified to enhance the listing's readability
as follows:

use PIC as an abbreviation for PICTURE,

omit the noiseword IS, and

align the PIC clauses on successive lines.
character to align the clauses.}

(Use the

tab

Put all paragraph name declarations in the Procedure Division
on lines separate from the statements in the paragraph. This
not only makes the program more readable,
it also makes
modification of the first statement in the paragraph easier.

7-2

GOOD PROGRAMMING PRACTICES
6.

Follow all imperative statements with a period, making them
I-statement sentences.
Place only one statement on a line.
In addition to making the lines shorter and more readable,
this will prove quite helpful when debugging the program.
For example, if the program contains a coding error, it will
be on one line and therefore easier to modify without
affecting the other portions of the sentence;
further,
the
diagnostic messages will refer to the correct line and their
meanings will be clearer.
S~nce

left-aligned statements in any program enhance the
readability of that program, develop the habit of starting
all COBOL sentences in column 5.
(Use the tab character to
skip over Area A.)
Some statements, however,
should be
further indented, as explained in the following paragraphs.

If the true path of a conditional statement contains another
conditional statement or more than one imperative statement,
place all statements in the true path on lines immediately
following the conditional statement and indent them to show
their dependence upon that statement. Consider the following
illustration of an IF statement and its true path:
IF COMPUTED-TAX > TAX-LIMIT
SUBTRACT TAX-LIMI'r FROM COMPUTED-TAX GIVING EXCESS-TAX
MOVE TAX-LIMIT TO COMPUTED-TAX
ADD EXCESS-TAX TO TOTAL-EXCESS-TAX.
If the statement has an ELSE (or false) path, align the word
ELSE under the preceding IF and indent all statements that
are dependent on the ELSE statement. Thus:
IF condition
true path statement
true path statement
ELSE
false path statement
false path statement.
Be sure to place the period after the last statement only!
Another good method for simplifying conditionals is to write
only a single imperative statement in the true or false path.
If the path requires more statements, place them 1n a
separate paragraph and either PERFORM the paragraph from the
path or GO to it. This technique avoids the possibility of
inadvertently placing a period at the end of a statement
within the path, thereby terminating it prematurely.
When writing a GO TO ...
DEPENDING statement, place each
procedure name on a separate line and indent them all.
Consider the readability of the following sample statement:
GO TO P35
P40
P45
P60
P65
DEPENDING ON P-SWITCH.

7-3

GOOD PROGRAMMING PRACTICES
8.

When grouping statements into paragraphs
the following organizational ideas:

and

sections,

use

Group together logical units of processing into a section.
Select a section name that reflects the type of processing
being conducted within that section (such as TAX-COMPUTATION
SECTION,
PRINT-LINE-FORMATTER SECTION,
etc.).
Follow the
section name with sufficient comment lines to explain the
processing that is carried out by the statements within that
section.
Make paragraph names as short and simple as possible.
A
numbered abbreviation of the section name often suffices.
Thus the paragraph names in the TAX-COMPUTATION section might
be TCIO, TC20, TC30, etc.
Use paragraph names sparingly,
placing them only where the true and false paths
of
conditional statements require branch points for GO TO
statements.
If the temptation arises to give a paragraph a
longer name
in an attempt to reflect the type of processing
in that paragraph, use comment lines instead.
(Comment lines
usually convey more information, more clearly.)
When using simple numbered paragraph names, assign increasing
numeric characters to sequential paragraphs.
If the numeric
portion of the names increases by 5 or 10, new ones may be
inserted later without disturbing the sequ~nce of the names.
Do not use the PERFORM verb in the form, PERFORM a THRU b.
If the paragraphs a thru b must be performed, place them in a
section by themselves and PERFORM the section, thus avoiding
the use of the THRU option.
Place single paragraphs that are to be performed into
sections and use the section name as the object of PERFORM
verbs. Then, if future design changes introduce complicated
conditional logic
into the paragraph, requiring additional
paragraph names, the PERFORM statements need not be altered.
The preceding guidelines divide the Procedure Division into
modular blocks of coding.
If these guidelines are used, the
following additional techniques may be applied.

7.2

Restrict entry to all sections through
the
first
statement of the section by use of a GO TO, a PERFORM, or
a "fall through" from the preceding section~

Ensure that all GO TO statements refer to only section
names or paragraph names that are internal to the section
containing the GO TO statement.

USE OF PUNCTUATION

Avoid using the COBOL punctuation characters,
comma and semicolon.
They lend little to the readability of programs that have their
statements neatly aligned,
as discussed earlier
in this chapter.
Further,
it is quite easy to misuse these characters, which can cause
serious errors for many compilers.
(Other compilers either
ignore
incorrect punctuation characters or flag them with warning messages.)
At best, even when used correctly and in the proper places, they have
no effect on the meaning of the program.

7-4

GOOD PROGRAMMING PRACTICES
7.3

USE OF THE ALTER STATEMENT

Avoid using the ALTER statement to change the flow of control in a
program.
It is impossible to test the setting of an alterable GO
statement except by executing it.
Also, unless explicit comments
accompany an alterable GO statement, it is difficult to tell whether
or not it is referenced by ALTER statements or what the possible
destinations might be.
All of this makes debugging programs that
contain these statements quite difficult.
There are two other
techniques that may be used in their place:
1.

If control branches one of two ways (i.e., a binary switch),
write the switch as a conditional variable. Consider the
following sample coding:
P-SWITCH PIC 59 COMP VALUE O.
88 NO-PRINT VALUE 1.

MOVE 1 TO P-SWITCH

IF NO-PRINT GO TO P40.
P40.
MOVE 0
2.

TO P-5WITCH.

If control branches more than two ways, use MOVE statements
to place integers into a data item,
and a GO TO .•.
DEPENDING ...
statement to test the data item and branch
accordingly. Consider the following sample coding:
01

P-SWITCH PIC 59999 COMP VALUE O.

MOVE 1 TO P-SWITCH

MOVE 3 TO P-SWITCH.

GO TO

7.4

PART-TIME
PIECE-WORK
HOURLY
SALARIED-WEEKLY
SALARIED-OTHER
DEPENDING ON P-SWITCH.
FALL THROUGH IS A BUG
DISPLAY "117".
STOP RUN.

USE OF THE PERFORM STATEMENT

The general rules for the PERFORM statement
following rules:

7-5

are

augmented

with

the

GOOD PROGRAMMING PRACTICES
1.

The endpoint of a section and the endpoint of the last
paragraph in the same section are two distinct points. This
means that it is possible to execute a PERFORM of the
section, then while that PERFORM is still active, to execute
a PERFORM of the last paragraph.

On the start of a PERFORM,
if the end point of the new
PERFORM is the end point of an already active PERFORM, the
OTS aborts the task and issues an error message.

At the end of any procedure, a check is made to see if the
procedure being ended is the end of the most recent PERFORM
range. If so, the most recent PERFORM range is exited.
If
not,
the end point of the most recent procedure is checked
against the end point of all
currently
active PERFORMs.
If the end point of the procedure is the end point of any
currently active PERFORM range, the OTS issues an error
message and aborts the task because the perform ranges are
not being exited in the reverse of the order in which they
were entered.

NOTE
The OTS error messages are discussed in
Section 11.4, Run-Time Error Messages.

7.5

USE OF LEVEL 88 CONDITION-NAMES

Condition-names provide a convenient method for
testing a value or
range of values in a field.
The use of condition-names makes programs
easier to maintain, because it ensures a uniform method of testing
fields and helps to reduce recoding when the specifications of the
program change.
The following example illustrates the use of condition-names and shows
the advantages inherent in their use.
Suppose the records of a file each describe a student in an
educational institution
(or an employee in a corporation). Some of
the records contain categories of information which are not present in
other records.
A "code" field,
which contains a digit or letter,
indicates the presence (or type) of some categories; while a special
value in the information itself (such as a numeric value being zero,
negative, or maximum) indicates the presence of other categories. The
processing of such a record may vary considerably depending on these
indicator fields. The fields may require interrogation at various
points in the program, and the interrogation may require more than a
simple relation test.
Consider a "code" field that holds one of seven values,
coded as a
mnemonic character. For example, S,1,2,3,4,G,P might be seven values
3rd
that indicate student categories of Special, 1st year, 2nd year,
year, 4th year, Graduate, and postgraduate. The field is described as
follows:
05 STUDENT-CATEGORY PIC X.

7-6

GOOD PROGRAMMING PRACTICES
Program logic requires certain processing for enrolled undergraduates,
different
processlng for special students,
and still different
processing for all students except enrolled undergraduates.
Without
the aid of condition-names, statements might be written as follows to
resolve this problem:
IF STUDENT-CATEGORY = US" ...
IF STUDENT-CATEGORY NOT LESS THAN "1"
IF STUDENT-CATEGORY NOT GREATER THAN "4"
IF STUDENT-CATEGORY EQUAL TO "G" NEXT SENTENCE
ELSE IF STUDENT-CATEGORY EQUAL TO UP"
NEXT SENTENCE ELSE GO TO ...
However, if various level 88 entries follow the STUDENT-CATEGORY
description, as shown below, condition-names can simplify this coding.
05 STUDENT-CATEGORY PIC X.
88 UNDERGRADUATE VALUE "1" THRU "4".
88 SPECIAL-STUDENT VALUE US".
88 GRAD-STUDENT VALUE "G" Up".
88 SENIOR VALUE "4".
88 NON-DEGREE-STUDENT VALUE US" Up".
Now, the following procedural statements can solve the problem:
IF SPECIAL-STUDENT .. .
IF UNDERGRADUATE .. .
IF GRAD-STUDENT .. .
Procedural statements with condition-names are much easier to read and
debug than those containing the complete test.
For example, the
procedural statements, IF UNDERGRADUATE ... , and IF STUDENT-CATEGORY
NOT LESS THAN "1" IF STUDENT-CATEGORY NOT GREATER THAN "4" both
accomplish the same thing, but the first statement is simpler and less
confusing.
In addition, the statement, IF NOT UNDERGRADUATE
can test the
category of not being an undergraduate, which is equivalent to anyone
of the following statements:
IF NOT (STUDENT-CATEGORY NOT < "1" AND
STUDENT-CATEGORY NOT> "4")
or
IF STUDENT-CATEGORY < "1" OR
STUDENT-CATEGORY > "4"
or
IF STUDENT-CATEGORY < "1" NEXT SENTENCE
ELSE IF STUDENT-CATEGORY > "4" NEXT SENTENCE
ELSE GO TO ...
Statements such as these are tedious to write and a frequent source of
coding errors.
Further, if a change creates a new student category,
the recoding takes more time and is even more error prone. A careful
and controlled use of condition-names forces a higher degree of
programming control and checkout.
If the program logic does require
the modification of the STUDENT-CATEGORY field, it can even be named
FILLER thus removing the opportunity to shortcut the
use
of
condition-names.
7-7

GOOD PROGRAMMING PRACTICES
To apply condition-names, follow the description of the
item to be
tested with a
level 88 entry.
The item being tested, known as the
conditional
variable
(STUDENT-CATEGORY
in
the
preceding
illustrations), may be either DISPLAY or COMPUTATIONAL usage, but not
INDEX usage;
it may also be a group item.
The compiler stores all of the values supplied by the level 88 entries
in the object program exactly as written.
(They are pooled with all
of the literals from the Procedure Division.) A value supplied by a
level 88 entry for a conditional variable of COMPUTATIONAL usage is
stored in binary format to save conversion at object time.
The
compiler stores all other values as byte strings with the proper
attributes.
It does not make the level 88 entries equal to their
conditional-variables in size.
This means that it neither truncates
nor pads (with spaces)
non-numeric literals.
Further,
it neither
truncates nor pads (with zeros) numeric literals, but stores them as
written or, if converted to binary, in the minimum size COMP item that
will
hold
the converted value.
It stores signs as trailing
overpunches on numeric DISPLAY literals,
and removes and remembers
decimal points.
Do not enter level 88 items under group items that have subordinate
SYNCHRONIZED,
entries containing any of the following clauses:
JUSTIFIED, COMPUTATIONAL, INDEX.

7.6

USE OF QUALIFIED REFERENCES

7.6.1

Qualified Data References

The COBOL language provides facilities to define and reference
user-defined data items.
Data items are programmer-defined variables
declared in the Data Division of a COBOL program.
Such variables
include,
among others, file record descriptions and internal working
areas.
These data items are processed by procedural statements such
as the WRITE,
MOVE,
and ADD statements.
Procedural operations on
these data are facilitated through references to the data
items by
name.
For example, to update a variable, YTD-GROSS-PAY, by a weekly
gross pay amount WEEKLY-GROSS, write the program fragment shown in
Figure 7-1.

WORKING-STORAGE SECTION.
01 YTD-GROSS-PAY PIC 9(5)V99.
01 WEEKLY-GROSS PIC 999V99.

ADD WEEKLY-GROSS TO YTD-GROSS-PAY.
Figure 7-1
Unqualified Data Item Reference
In this example, YTD-GROSS-PAY and WEEKLY-GROSS are defined in the
Working Storage Section of the Data Division as COBOL variables with a
level number of 01. The variable representing the "year-to-date gross
7-8

GOOD PROGRAMMING PRACTICES
pay
(YTD-GROSS-PAY)" is computed by incrementing its present value by
the "weekly gross pay (WEEKLY-GROSS)" amount through reference to the
appropriate data
items in the ADD statement.
References are made to
the data items by the singular, unqualified names of YTD-GROSS-PAY and
WEEKLY-GROSS.
Since YTD-GROSS-PAY and WEEKLY-GROSS are defined with
level numbers of 01 in the working Storage Section,
these variables
must be unique in their spelling and, hence, can only be referenced by
the spelling of each data item's name without any COBOL qualification.
The example in Figure 7-1 is artificial because the data
item
representing the "year-to-date gross pay"
is defined as a level 1
variable in the Working Storage Section.
More
realistically,
YTD-GROSS-PAY is defined as a field within an employee payroll record
residing on an external master payroll file.
The process of updating
the "year-to-date gross pay" by a "weekly gross pay" amount is shown
more appropriately in Figure 7-2.

FILE SEC'rION.
FD MASTER-IN
LABEL RECORD IS STANDARD
VALUE OF 10 IS "MASTER.PAY".
01 PAY-RECORD.
PIC X(30).
03 NAME
03 EMPLOYEE-NO
PIC 9(9).
PIC 9(S)V99.
03 YTD-GROSS-PAY

FD MASTER-OUT
LABEL RECORD IS STANDARD
VALUE OF 10 IS "MASTER.PAY".
01 PAY-RECORD.
03 NAME
PIC X (30) .
03 EMPLOYEE-NO
PIC 9 (9) .
PIC 9(S)V99.
03 YTD-GROSS-PAY

WORKING-STORAGE SECTION.
01 WEEKLY-GROSS
PIC 999V99.

PROCEDURE DIVISION.
INIT.
OPEN INPUT MASTER-IN.
OPEN OUTPUT MASTER-OUT.

ADD WEEKLY-GROSS, YTD-GROSS-PAY OF MASTER-IN
GIVING YTD-GROSS-PAY OF MASTER-OUT.

Figure 7-2
Qualified Data Item Reference

7-9

GOOD PROGRAMMING PRACTICES
In this example, YTD-GROSS-PAY is defined as a field in both the input
and output record descriptions.
There are two separate data items
whose spellings are identical.
To reference each data item, it is necessary to qualify the name of
each data item with sufficient information to constitute a unique
reference. Thus, to reference the "year-to-date gross pay" amount in
the output record, we write "YTD-GROSS-PAY OF MASTER-OUT" where such a
reference is called a qualified reference. The filename MASTER-OUT is
functioning as a qualifier in the reference.
The reserved word "OF"
is the qualification connector and may be used interchangeabely with
the reserved word "IN" in this context.
Another way of referencing
the same data item is to write "YTD-GROSS-PAY OF PAY-RECORD IN
MASTER-OUT".
This
reference is called a completely qualified
reference because all possible qualifiers are specified in the
reference.
A reference of the form "YTD-GROSS-PAY" or "YTD-GROSS-PAY
OF PAY-RECORD" is illegal since it does not uniquely identify which of
the two data items is desired.
Such a reference is termed an
ambiguous reference.
In the area of data item definition and referencing, COBOL is unlike
other languages such as FORTRAN and ALGOL 60. While FORTRAN requires
each data item to have a unique name (i.e., no two data items may have
a name of identical spelling), COBOL relaxes this requirement to the
extent that each data item must be uniquely referable. That is,
two
or more data items may have their names spelled identically, but there
must exist a way to reference each distinct data item. Thus, there is
a
distinction between a data item and its name.
Central to
understanding this distinction is understanding the concept of unique
referability.
The functionalities of data item definition and referencing may be
understood by stating three guidelines which relate the concepts of
data item definition, reference format, and unique referability.

7.6.2

Guideline 1 (Data Item Definition)

Each data item has a name.
Each name is immediately preceded by an
associated positive integer called its level number.
A name either
refers to an elementary item or else it is the name of a group of one
or more items whose names follow.
In the latter case, each item in
the group must have the same level number, which must be greater than
the level number of the group item.

7.6.3

Guideline 2 (Re!erence Format)

Data-name qualification is performed by following a data-name or
condition-name by one or more phrases of a qualifier preceded by IN or
OF.
IN and OF are logically equivalent.
The general format of a
qualified reference to an elementary item or group of items named
"name-O" is given in Figure 7-3.
name-O OF name-I ... OF name-m
Figure 7-3
General Format of a Qualified Data Reference

7-10

GOOD PROGRAMMING PRACTICES
where m )= 0 and where, for 0 (= j ( m, name-j is the name of some
item contained directly or
indirectly within a group item named
"name-j+l". A reference of the form given in Figure 7-3 is called a
(partially)
qualified reference with name-l,name-2, .•. ,name-m being
called qualifiers. Such a reference is termed a completely qualified
reference if "name-j+l" is the father of name-j for a (= j (= m-l.
In the hierarchy of qualification,
names associated with an FD
indicator are the most significant, then the names associated with
level-number 01, then names associated with level-number 02, .•. ,49.
The most significant name in the hierarchy must be unique and cannot
be qualified.
Subscripted or
indexed data-names,
unsubscripted
data-names,
and
condition
variables
may
be made unique by
qualification. The name of a condition variable can be used as a
qualifier for
any of its condition-names. Enough qualification must
be mentioned to make the reference unique;
however,
it may not be
necessary to mention all levels of the hierarchy as the example in
Figure 7-2 demonstrates.

7.6.4

Guideline 3 (Unique Referability)

If more than one data item is defined with the same name "name-a",
there must be a way to refer to each use of the name by using
qualification. That is, each definition of "name-On must be uniquely
referable.
A data item is uniquely referable if the complete set of
qualifiers for
the data item are not identical to any partial
(including complete) set of qualifiers for another data item.

7.6.5

Qualified Procedure References

The facility of qualification may be applied to procedure references.
A
procedure name is either a paragraph or section name.
By
definition,
a paragraph name is unique only within a
section
containing the paragraph while, on the other hand, section names must
be unique within a COBOL program. The general format of a qualified
procedure reference is shown in Figure 7-4.
paragraph-name OF section-name
Figure 7-4
General Format of a Qualified Procedure Reference
A paragraph name may be qualified by its containing section name;
a
section name may never be qualified in a procedure reference.
When a
paragraph name is referenced without an explicit section
name
qualifier,
the
paragraph name is implicitly qualified by the
appropriate section name.
If a paragraph name is unique within a COBOL program it is not
necessary to qualify the paragraph name in the procedure reference.
Finally, if a paragraph name is not unique within a COBOL program, the
paragraph name must be qualified in a procedure reference when the
reference is made outside of the section which contains the paragraph.

7-11

GOOD PROGRAMMING PRACTICES
7.6.6

Qualification and Compiler Performance

Qualification is a powerful language facility for the development of
COBOL programs.
Used wisely, it increases the readability of COBOL
programs. However, the user pays a price for
utilization of this
facility in terms of a slower compilation rate (i.e., COBOL source
lines per unit of time).
Qualification requires a tree-structured symbol table at compile-time.
The time required for building and looking up on a tree-structured
symbol table is considerably longer than for a non-tree-structured
symbol table. This translates into a general degradation of compiler
performance.
If qualification is not employed in a program compiled
by the
TRAX
COBOL compiler,
compilation speed is not affected.
However, when qualification is used, the compilation rate slows down
due to the additional system overhead.
In general, if there are deeper levels of qualification, there will be
a slower compilation.
This is especially so at the end of the Data
Division text where duplicate data-name declarations are detected by
the compiler. Object-time performance is not affected by usage of the
qualification facility.

7-12

CHAPTER 8
SEGMENTATION

TRAX COBOL allows you to break the Procedure Division up into
overlayable and non-overlayable program segments to optimize memory
utilization. An overlayable program segment can be overlayed by any
other overlayable segment. However, a non-overlayable program segment
can never be overlayed.
NOTE
The object code generated
for
the
Identification Division through the Data
Division is non-overlayable.

8.1

USING THE TRAX COBOL SEGMENTATION FACILITY

The TRAX COBOL Segmentation Facility allows you to specify your own
segmentation requirements. To effect segmentation, you must define a
segment limit by specifying the SEGMENT-LIMIT IS clause in the
Environment Division of your source program. The value you specify in
this clause is used by the compiler as a basis for determining whether
a program segment is overlayable or non-overlayable.
A segment
consists of one or more COBOL sections. Each COBOL section should b~
composed of a series of closely related operations designed to
collectively perform a particular function. To designate a section as
belonging to an overlayable or non-overlayable segment, assign a
segment number to it using the following format:
Section-name SECTION segment-number.
Where:
Section-name

Is a user-defined
section

COBOL

word

that

names

the

Segment-number Is an integer ranging from 0 to 49.
If you specify a segment-number whose value is less than the value
specified in the SEGMENT-LIMIT IS clause, you have defined the section
as being non-overlayable. A segment-number whose value is greater
than or equal to the value specified in the SEGMENT-LIMIT IS clause
defines the segment as being overlayable.

8-1

SEGMENTATION
8.1.1

Programming Considerations

The most frequently used sections of your program should be made
non-overlayable.
Assign segment-numbers that are less than the value
specified in the SEGMENT-LIMIT IS clause
to
these
sections.
Infrequently
used sections should be made overlayable.
Assign
segment-numbers that are greater than or equal to the value specified
in the SEGMENT-LIMIT IS clause to these sections. Sections that
communicate with each other should be assigned to the same segment.
Assign the same segment-number to these sections. Sections having
identical segment-numbers are assigned to the same segment.

8.2

SEGMENTATION AND THE PDP-II COBOL COMPILER

The previous sections provided you with detailed information on how to
segment.
This section describes what segmentation means in terms of
code generation. The TRAX COBOL compiler breaks up the object code it
generates into program sections called PSECTs. One or more PSECTs are
generated for each program SECTION.
The maximum size PSECT generated
is 2000 decimal words. However, this maximum size can be altered by
specifying the ICSEG:nnnn switch in the compiler command line. (PSECTs
are described in Appendix E: The ICSEG:nnnn Switch is described in
Section 8.4, and Section 2.2.4).
Also generated, are Overlay Description Language (ODL) directives that
group together all PSECTs that belong in the same overlay. These ODL
directives are placed in an ODL file to be used as input to the Task
Builder.
The Task Builder uses the ODL file to generate a task image
containing the correct combination of overlayable/non-overlayable
PSECTs.
If the source program is written without explicit segmentation, all of
the
generated PSECTs are concatenated into one non-overlayable
program. If the source program does contain explicit segmentation,
ODL directives are created to group PSECTs together into the correct
combination of overlayable and non-overlayable program segments.

8.3

SEGMENTATION OSING THE lov SWITCH

The IOV switch, when appended to the compiler command line, directs
the compiler to produce ODL directives that make all of the procedural
PSECTs overlayable. Therefore, the amount of memory required to store
the
program
1S
equal to that required to contain the root
(non-overlayable portion) and the largest PSECT.
(See Figure 8-1,
Segmentation Using The IOV Switch;
and Section 2.2.4, Compiler
Switches) .
The IOV switch is particularly useful for quickly segmenting programs
that were written without explicit segmentation or for overriding
explicit segmentation.

8-2

SEGMENTATION

available
memory
Data
and
Control
PSECTs
S1 SECTION

program too big

S2SECTION

procedural PSECTs
S3 SECTION

S4SECTION

available
memory

generated code using /OV switch

Data
a!ld
Control
PSECTs

S1 SECTION

S2 SECTION

S3 SECTION

S4 SECTION

\~----------------------~,,-----------------------~)
procedural PSECTs

Figure 8-1

8.4

Segmentation using the /OV Switch

USING THE /CSEG:nnnn SWITCH

The TRAX COBOL compiler generates a PSECT for each COBOL section.
If the code generated for a particular section exceeds the default
maximum size for a PSECT (4000 decimal bytes), more than one PSECT is
generated.
TRAX COBOL provides a switch (/CSEG:nnn) that allows you
to control the size of PSECTs generated by the compiler.
(See Section
2.2.4 Compiler Switches).
If, for example, you compile a program that produces a PSECT that is
too large to be linked, you can recompile the program using the
/CSEG:nnn switch to reduce the size of the PSECTs generated.
See
Figure 8-2 for an example of using the /CSEG:nnnn switch.

8-3

SEGMENTATION
Command Line (Without /CSEG:nnnn switch specified)
COBOL/SWITCHES: (/MAP

CBLMRG~

SEGMENTATION MAP
SECTION NAME

SEGMENT NO.

NAME

00
00
00
00
00

$C$OOl
$C$002
$C$003
$C$004
$C$005

OUTPUT-OOL-USE
INPUT-OOL-USE
MAIN-CONTROL
PROCESS-INPUT-OOL
HOR-CHECK

One large PSECT is generated

SIZE
000172
UOO172
003336
001130
000322

00061
00061
00879
00300
00105

Command Line (With the /CSEG:nnnn switch specified)
COBOL/SWITCHES: (/MAP/CSEG:IOOO)

CBLMRG~

SEGMENTATION MAP
SECTION NAME

SEGMENT NO.

NAME

00
00
00
00
00
00

$C$OOl
$C$002
$C$003
$C$004
$C$005
$C$006

OUTPUT-OOL-USE
INPUT-OOL-USE
MAIN-CON'rROL
PROCESS-INPUT-OOL
HOR-CHECK

SIZE
000172
000172
001744
001426
001130
000322

Two PSECTs are generated
Figure 8-2

using the /CSEG:nnnn Switch

8-4

00061
00061
00498
00395
00300
00105

CHAPTER 9
INTER-PROGRAM COMMUNICATIONS

Inter-program communications is the passing of control and optional
data from one program within a task to another.
TRAX COBOL provides
you with the ability to Link separately compiled COBOL programs
into a single task image. During task execution, these separately
compiled programs can communicate with each other using the COBOL CALL
statement.
A task can consist of a stand-alon~ program or a main program and one
or more subprograms. A stand-alone program is one that does not call
subprograms and cannot itself be called. A COBOL main program is one
that calls subprograms but can never be called in return. A COBOL
subprogram, however, is always called by another program, either the
main program or a subprogram. Inter-program communications deals only
with main programs and subprograms.
Developing a program as a main program and a set of subprograms offers
a number of advantages:

9.1

Large monolithic programs are no longer required.
These
large programs can be replaced by a controlling main program
and a set of subprograms, where each subprogram is designed
to perform a well-defined function.

Small subprograms can be developed independently
members of a programming staff.

several

Small subprograms
programs.

than

large

Small subprograms can be modified and recompiled faster
large programs.

than

General purpose subprograms can be developed and used in more
than one programming application.

can

tested

easily

COBOL MAIN PROGRAMS VERSUS SUBPROGRAMS

A COBOL main program is one that calls other programs
(subprograms)
but cannot be called in return. A COBOL main program contains at
least one CALL statement. A COBOL subprogram is one that is called by
another program, either the main program or another subprogram. The
main program is automatically activated at task execution time.
A
subprogram, however, is activated only when called by another program.
The COBOL compiler differentiates between a main program and a
subprogram by the presence or absence of a USING phrase in the
The USING
Procedure Division header of the program being compiled.

9-1

INTER-PROGRAM COMMUNICATIONS
phrase is used only in COBOL subprograms.
It defines the program as
being a subprogram and optionally identifies the data expected from
the calling program. The Procedure Division header has the following
format:
PROCEDURE DIVISION [USING

[data-name-l

data-name-2] ... ] .

A subprogram, that does not process data (arguments) passed to it by a
calling program, has only the word USING appended to the Procedure
Division header.
For example:
PROCEDURE DIVISION USING.
A subprogram that processes passed data, has a USING phrase with one
or more data-names specified.
If a data-name{s) is specified, the
program must also contain a Linkage Section in the Data Division. The
Linkage Section describes the size and type of data being passed.
(See Figure 9-1, Sample LINKAGE SECTION and USING phrase).
LINKAGE SECTION.

SUBPROGRAM-DATA.

1ST-PARAMETER

PIC X(S).

2ND-PARAMETER

PIC X(S).

3RD-PARAMETER

PIC X(S).

PROCEDURE DIVISION USING 2ND-PARAMETER, 3RD-PARAMETER.
NOTES
1.

All of the data-names appearing in the using phrase must also
appear in the LINKAGE SECTION.

Not all of the data-names in the LINKAGE SECTION need
in the USING phrase.

A LINKAGE SECTION can appear in a subprogram even if the
USING phrase does not contain a data-name.
However, if any
of the data-items contained in the LINKAGE SECTION are
referenced in procedures,
the compiler will issue a fatal
diagnostic.
Figure 9-1

9.1.1

appear

Sample LINKAGE SECTION and USING Phrase

Calling a COBOL Subprogram from a COBOL Program

To call a subprogram from a COBOL program, a CALL statement having the
following format must be used:
CALL literal [USING data-name-l [, data-name-2] ..• ].

9-2

INTER-PROGRAM COMMUNICATIONS
Where:
literal

is the name that appears in the
of the called program.

data-name-l
through
data-name-n

identify those data-items in the calling program
that can be referred to by the called program.

9.1.2

PROGRAM-ID

entry

Returning from a COBOL Subprogram

In addition to the required USING phrase and optional LINKAGE SECTION,
a subprogram should contain at least one EXIT PROGRAM statement. The
EXIT PROGRAM statement identifies the subprogram return point.
That
is,
the point in the subprogram at which control is returned to the
calling program. If the EXIT PROGRAM statement is missing, the COBOL
compiler will generate one after the last statement in the program.
NOTE
More than one EXIT PROGRAM statement
allowed in a subprogram.

9.2

UNIQUENESS OF PSECT NAMES

The names of all PSECTs within a task must be unique. When a task is
composed of more than one COBOL program, you must insure that the
PSECTs generated by the COBOL compiler for each program are unique.
(See Appendix E, Section E.l, PSECT Naming Conventions) .

9.3

COBOL OTS - ERROR CHECKING

At task execution, the COBOL OTS performs a check to insure that the
number of arguments passed to a called COBOL subprogram is the same as
the number expected. That is, the subprogram Procedure Division USING
phrase must contain the same number of data-names as the USING phrase
in the calling programs CALL statement. If the number of data-names
in each USING phrase are not equal, the OTS issues a diagnostic error
message and aborts the task. No checks are made to insure that the
passed arguments are the same size as the expected arguments.
It is
your responsibility to insure that these sizes are compatible.
Recursive calls to COBOL subprograms are not allowed.
If a COBOL
subprogram contains a CALL statement that directly or indirectly
causes a subprogram to be re-entered before it has exited from its
original entry, the OTS will issue a diagnostic error message and
abort the task.

9-3

INTER-PROGRAM COMMUNICATIONS
9.4

INCLUDING A MACRO OBJECT MODULE IN A COBOL TASK

MACRO object modules can be combined with COBOL object modules at link
time to produce a single task image. To activate a COBOL subprogram, a
MACRO calling program must contain the equivalent of a COBOL CALL
statement.
If data is being passed to the COBOL subprogram, program
register R5 must be set to the address of an argument list. The argument
list must contain pointers to the data being passed.
(See Figure 9-2,
Argument List Format.)
A MACRO subprogram, to be activated by a COBOL program, must contain
the equivalent of the COBOL PROGRAM-ID statement and the COBOL EXIT
PROGRAM statement (See Example 1 below).
If data is being passed, the
MACRO subprogram can access that data using program register R5.
The following sections provide an example of how MACRO programs can be
written for inclusion in a COBOL task image.
Example 1 -

(Calling MACRO Programs from COBOL)

The format for calling any program from COBOL is:
CALL literal [USING data-name-l[, data-name-2] ... ]
when a MACRO program is bein"g called, literal contains the global
entry point specified in the MACRO program.
If the COBOL program
contains:
CALL "BILBO" USING BOFFIN, BOMBUR, BOFUR.
The MACRO program must contain:
.GLOBL BILBO I

ientry point - equivalent to PROGRAM-ID

BILBO:

RTS PC

ireturn point - equivalent to EXIT PROGRAM

If there are any arguments to be passed to the called program (BOFFIN,
BOMBUR, and BOFUR in this example), these arguments can be accessed
through program register R5.

9-4

INTER-PROGRAM COMMUNICATIONS
Example 2 -

(Calling CaSaL Programs from MACRO)

When the calling program is a MACRO program, control is passed to
called program with the following instruction:

the

JSR PC,subprogram-name
Where:

Subprogram-name is the first
PROGRAM-ID.

six

characters

the

COSOL

If the MACRO program contains:
.GLOSL

FRODO

MOV #ARGLST,RS

ipoint RS to argument list

JSR PC,FRODO

isubprogram call statement

The COBOL subprogram will contain:
PROGRAM-ID.

FRODO

LINKAGE SECTION.

FRODO-ARGUMENTS.

BOFFIN

PIC X(S).

BOMBUR

PIC X(S).

BOFUR

PIC X(S).

PROCEDURE DIVISION USING BOFFIN,BOMBUR.

EXIT PROGRAM.
The MACRO program, in this example, has set
argument list expected by the COBOL program.
RS to access the passed arguments.

9-5

RS to point to the
The COBOL OTS will use

INTER-PROGRAM COMMUNICATIONS

ARGUMENT ADDRESS LIST
Word 1

unused

# of arguments
in list (n· 1)

Word 2

address of argument #1

Word 3

address of argument #2

"1....1

Word n

R5 must be set
to poi nt here

address of argument #n . 1

Figure 9-2

Argument Address List

9-6

CHAPTER 10
HAND-TAILORING ODL FILES

This chapter is provided as a guide to those of you who are faced with
the problem of having to generate OOL files that are compatible with
either the Merge Utility or the TRAX Linker.
The most common reason
for having to hand tailor an OOL file occurs when non-COBOL programs
are being merged into a COBOL task image. The information presented
here is predicated on the assumption that you have read and are
familiar with the TRAX Linker Reference Manual that pertains to your
operating system. The following sections describe the standard OOL
file as it pertains to TRAX COBOL.

10.1

STANDARD ODL FILE

The standard OOL file generated by the TRAX COBOL compiler consists
of a header and a body.
The header contains information that is
required to merge one or more OOL files.
The body contains OOL
directives that describe the Object program.

10.2

ODL FILE HEADER

The OOL file header consists of a sequence of comment lines. Two
required in every OOL file, others are supplied as needed.
required comment lines are:

are
The

iCOBOBJ=XXXXXX.OBJ
iCOBKER=KK
Where:
XXXXXX.OBJ

is the name of the object module being described

is the kernel that was used to generate the
names for the COBOL program.

PSECT

The following comment lines are supplied as needed:
iCOBMAIN

This comment line is supplied if the program being
described is a main program. The absence of this
line means that the OOL file was generated for a
COBOL subprogram.

iRMSSEQ=CIOOXY This comment line is specified if the program
requires RMS-ll I/O support. One or more lines
may be supplied. X and Y represent integer codes
that respectively specify the file organization
and operational
support
required
for
that
10-1

HAND-TAILORING ODL FILES
organization.
File
the following codes:

organization is specified by

CODE

ORGANIZATION

sequential

relative

indexed

The values allowed for
the operational support
code are meaningful only to future versions of
TRAX COBOL and the Merge Utility.
Therefore,
they are not defined here.

10.3

ODL FILE BODY

The ODL file body describes the overlay structure of the
program. The body contains the following OOL directive types:
1.

.PSECT

defines the name of the code PSECT
known to the TRAX Linker.

and

.NAME

defines the name to be assigned
segment by the Task Builder.

.FCTR

describes the contents of the segments.

• ROOT

defines the root.

.END

informs the TRAX Linker that the end of
file has been reached.

;comments

contains comment entries.

the

COBOL

makes

overlay

the

ODL

The .ROOT and .END directives are not supplied by the COBOL compiler.
They are inserted into the OOL file generated by the Merge Utility.
If you are generating a stand alone OOL file, these directives must be
supplied by you.
If the aOL file you are generating is to be used as
input to the Merge Utility, leave these directives out.
within a compiler-generated OOL file, the directives
.PSECT,
.NAME,
and
.FCTR are generated around the PSECT kernel.
If the PSECT name
kernel for a given program is KK, the format of the names generated in
the aOL file is:
Entity

Format of Name

.PSECT

$KKMMM

.NAME

KK$MMM

.FCTR

KKMMM$

Each .PSECT defined in the OOL file begins with a $ followed by the
two character kernel ($KK). Each .NAME directive begins with the two
character kernel followed by $ (KK$).
Finally, each
.FCTR directive
begins with the two-character kernel and ends with a $ (KKMMM$).

10-2

HAND-TAILORING ODL FILES
10.4

COMPILER-GENERATED ODL FOR COBOL PSECTS

The following sections discuss the ,OOL directives generated for
different types of overlay requirements. The characters NNN when used
in examples refer to the three character suffix generated by the
compiler for each PSECT.
The characters KK refer to the kernel
characters that make the PSECT unique to a particular compilation.

10.4.1

ODL Generated for Overlays Containing Only One PSECT

For overlays containing
generated:

KKNNN~

10.4.2

only

one

PSECT,

.PSECT

$KKNNN,GBL,RW,CON,I

.NAME

KK$NNN,GBL

.FCTR

*KK$NNN-$KKNNN

the

following

lines

are

ODL Generated for Overlays Containing More Than One PSECT

For each overlay that contains more than one PSECT, a .PSECT directive
is generated for each PSECT in the overlay. These .PSECT directives
are followed by a .NAME and .FCTR directive. Consider the following
example.
Example
Two PSECTs, $AAOOl and $AA002, are to be placed in the same overlay.
The segment-number assigned to the PSECTs is 20. The following OOL
directives are generated:
:DEFINE

PSECT $AAOOl

.PSECT

$AAOOl,GBL,RW,CON,I

:OEFINE

PSECT $AA002

.PSECT

$AAOU2,GBL,RW,CON,I

iOEFINE THE OVERLAY NAME
.NAME

AA$020,GBL

:OEFINE OVERLAY CONTENTS
AA020$:

10.4.3

.FCTR

*AA$020-$AAOOl-$AA002

ODL Generated for All Overlayable PSECTs

All .FCTR directives that describe the overlayable PSECTs must be
collapsed into one final .FCTR directive. This directive describes
the entire overlayable portion of the object code.
The
name
associated with this .FCTR directive is derived from the two-character
kernel assigned to the PSECTs.
If the kernel is KK, then the name of
the
.FCTR directive that describes the entire overlayable part of the
object code is KKOVR$.

10-3

HAND-TAILORING ODL FILES
The following example shows how the KKOVR$
various overlay configurations:
Example 1:

developed

All Code Psects Overlay One Another

AAOOl:

.PSECT
.NAME
.FCTR

$AAOOl,GBL,RW,CON,I
AA$OOl,GBL
*AA$OOl-$AAOOl

AA002$:

.PSECT
.NAME
.FCTR

$AA002,GBL,RW,CON,I
AA$002,GBL
*AA$002-$AA002

AA003$:

.PSECT
.NAME
.FCTR

$AA003,GBL,RW,CON,I
AA$003,GBL
*AA$003-$AA003

.PSECT

$AA004,GBL,RW,CON,I
AA$004,GBL
*AA$004-$AA004

• NAME

AA004$:

factor

.FCTR
;

AAOOS$:
AAOVR$:

.PSECT
$AAOOS,GBL,RW,CON,I
.NAME
AA$OOS,GBL
.FCTR
*AA$OOS-$AAOOS
;IN THIS EXAMPLE, ALL PSECTS OVERLAY
:ONE ANOTHER.
.FCTR
(AAOOl$,AA002$,AA003$,AA004$,AA004$,AA005$)

Example 2:

Two Code Psects Are in the Same Overlay
.PSECT

$AAOOl,GBL,RW,CON,I

.PSECT

$AA002,GBL,RW,CON,I

AAOOl$:

.NAME
.FCTR

AA$OOl,GBL
*AA$OOl-$AAOOl-$AA002

AA003$:

.PSECT
.NAME
.FCTR

$AA003,GBL,RW,CON,I
AA$003,GBL
*AA$003-$AA003

AA004$:

.PSECT
.NAME
.FCTR

$AA004,GBL,RW,CON,I
AA$004,GBL
*AA$004-$AA004

;

AA005$:

.PSECT
.NAME
.FCTR

$AAOOS,GBL,RW,CON,I
AA$005,GBL
*AA$005-$AA005

;

AAOVR$ :

.FCTR

Example 3:

AAOOl$,AA003$,AA004$,AAOOS$

Two Occurrences of Two Psects in the Same Overlay
;IN THIS EXAMPLE, PSECTS $AAOOI AND $AA002
;ARE IN THE SAME OVERLAY. PSECTS $AA003
;AND $AA004 ARE IN THE SAME OVERLAY.
;PSECT $AA005 IS IN AN OVERLAY ALL BY ITSELF

;PSECT

$AAOOl,GBL,RW,CON,I

;PSECT

$AA002,GBL,RW,CON,I

.NAME

AA$OOl,GBL

10-4

for

HAND-TAILORING ODL FILES
AAOOl$:

.FCTR

*AA$OOl-$AAOOl-$AA002

iPSECT

$AAOO3,GBL,RW,CON,I

.PSECT

$AA004,GBL,RW,CON,I

AA003$:

.NAME
.FCTR

AA$003,GBL
*AA$003-$AA003-$AA004

AA005$:

.PSECT
.NAME
.FCTR

$AA005,GBL,RW,CON,I
AA$OO5,GBL
*AA$005-~AAOO5

AAOVR$ :

10.5

.FCTR

AAOOl$,AA003$,AAOO5$

MERGING STANDARD ODL FILES

To develop an ODL file for a task composed of more than one COBOL
object program,
it is necessary to merge the ODL files for each
individual object program into a single ODL file that describes the
overlay requirements for the task.
All of the ODL files to be merged are partial ODL files.
That is,
none of these ODL files can be submitted directly to the
Linker
to link a task; because, none of the compiler generated ODL files
contain a .ROOT directive.
The .ROOT directive that describes the
task is supplied by the Merge Utility.
Merging COBOL compiler generated ODL files
executing the ODL merge utility.
(See Section
Merge Utility).

10.6

is accomplished
2.6, Using The

by
ODL

INCLUDING NON-COBOL PROGRAMS IN A TASK

To use the Merge Utility to include a non-COBOL
task image, you must:

object

module

Create a standard COBOL ODL file (use the DEC editor)

Specify this ODL file as input to the ODL Merge Utility.

10.6.1

Creating a Standard COBOL ODL File

A standard COBOL ODL file for a non-COBOL object module
or two directive lines:
1.

contains

one

Object Program 10 Line
This line is required.
It
identifies the object module to be included in the task
image. The format of this line is:
iCOBOBJ=XXXXXX.OBJ
Where XXXXXX.OBJ is the name
included in the task image.

10-5

the

object

module

HAND-TAILORING ODL FILES
2.

Main Program 10 Line
This line is present only for
non-COBOL object modules that are main programs as opposed to
being subprograms. The format of the line is:
iCOBMAIN

For each invocation of the COBOL ODL Merge Utility, one and only one
main program aDL file can be specified.
If no main program aOL file
is specified, the Merge Utility continues to request more input until
a main program aOL file is specified.
If more than one main program
ODL file is specified, all but the first is rejected, and appropriate
diagnostic
error
messages are issued.
Consider the following
examples.
Example 1
MACRO program START.aBJ is a main program in a task
main
program' and
several
subprograms.
The
hand-generated is:

consisting of a
OOL file to be

iCOBOBJ=START.OBJ
iCOBMAIN
Example 2
Macro subprogram SUBX.OBJ is to be part of a task image that consists
of several COBOL subprograms and a COBOL main program. The OOL file
to be hand-generated is:
iCOBOBJ=SUBX.OBJ

10.7

REARRANGING A COMPILER-GENERATED ODL FILE

The OOL file generated by the compiler can be rearranged to modify the
overlay structure of a task.
If the OOL file describes a task that
has overlayable segments, one or more of these segments can be
converted into non-overlayable segments by:
1.

Modifying the compiler-generated OOL file.

Specifying a one-line Linker option
segment made non-overlayable.

10.7.1

Link

time

for each

the

following

Modifying the Compiler-Generated ODL File

Modifying the compiler
steps:

generated

OOL

file

requires

Each overlayable segment is named in the ODL file by an
.NAME directive. This .NAME directive must be removed.

Each
and
each
must

ODL

name appearing in a .NAME directive is marked with an *
placed as the first element of a .FCTR directive.
For
.NAME directive removed by step 1, this .FCTR directive
be removed.

10-6

HAND-TAILORING ODL FILES
3.

All references to the name of the .FCTR directive removed
step 2 must be removed from the ODL file.

All PSECTs referenced in the .FCTR directive that was removed
in step 3, must be removed from the ODL file.

Example
The task image contains three overlayable segments, C$$OlO, C$$015,
and C$$020.
Segment C$$020 is to be forced into the root. Figure
10-1 contains a listing of the merged ODL file.
iMERGED ODL FILE CREATED ON 26-JAN-77 AT 10:50:00
iCOBOL STANDARD ODL FILE GENERATED ON: 26-JAN-77
:COBOBJ=TEST1.OBJ
iCOBKER=C$
;COBMAIN
.NAME C$$OlO,GBL
.PSECT $C$003,GBL,I,RW,CON
.FCTR *C$$OlO-$C$003
C$OlO$:
.NAME C$$015,GBL
.PSECT $C$004,GBL,I,RW,CON
C$015$:
.FCTR *C$$015-$C$004
.NAME C$$020,GBL
.PSECT $C$005,GBL,I,RW,CON
C$020$:
.FCTR *C$$020-$C$005
C$OVR$:
.FCTR
C$OlO$,C$OI5$,C$020$
.FCTR TEST1.OBJ
CBOBJ$:
.FCTR C$OVR$
CBOVR$ :
.FCTR [320,13]COBLIB/LB
CBOTS$:
RMS$:
.FCTR [l,l]RMSLIB/LB
OBJRT$:
.FCTR CBOBJ$-CBOTS$-RMS$
.ROOT OBJRT$-(CBOVR$)
.END
Figure 10-1

10:48:37

Merged ODL File Listing

To force segment C$$020 into the root, the merged
modified as follows:

ODL

file

must

The .NAME directive referencing C$$020 must be removed.

The .FCTR directive containing *C$$020 must be removed.

All references to the PSECTs in the removed
must be removed.

10-7

.FCTR

directive

HAND-TAILORING ODL FILES
Figure 10-2
been made.

contains the ODL listing

after

the

iMERGED ODL FILE CREATED ON 26-JAN-77 AT 10:55:22
iCOBOL STANDARD ODL FILE GENERATED ON: 26-JAN-77
iCOBOBJ=TESTl.OBJ
iCOBKER=C$
iCOBMAIN
.NAME C$$OlO,GBL
.PSECT $C$003,GBL,I,RW,CON
C$OlO$:
.FCTR *C$$010-$C$003
.NAME C$$015,GBL
.PSECT $C$004,GBL,I,RW,CON
C$015$:
.FCTR *C$$015-$C$004
.FCTR
C$010$,C$015$
C$OVR$:
CBOBJ$ :
.FCTR TESTl.OBJ
.FCTR C$OVR$
CBOVR$ :
CBOTS$ :
.FCTR [l,l]COBLIB/LB
.FCTR [l,l]RMSLIB/LB
RMS$:
.FCTR CBOBJ$-CBOTS$-RMS$
OBJRT$ :
.ROOT OBJRT$-(CBOVR$)
.END
Figure 10-2

10.7.2

modifications

have

10:48:37

Modified ODL File

Specifying LINKER Options

For each overlayable segment made non-overlayable, a GBLDEF LINKER
option must be specified at link time. The format of the option is:
GBLDEF=KK$MMM:O
Where:
KK$MMM is the name of the segment that is being made
non-overlayable.
(This is the name in the
.NAME ODL
directive that was deleted when the ODL file was modified).
Consider the following example.
Example
To make the overlayable segment (C$$020) described in tbe example in
Section 11.7 non-overlayable, enter the following in response to the
Linker ENTER OPTIONS prompt:
GBLDEF C$$020 ~
Figure 10-3 shows the overlay description of the task image before and
after segment C$$020 was made non-overlayable.

10-8

HAND-TAILORING ODL FILES

BEFORE
TESTl.TSK;l

MEMORY ALLOCATION MAP TKB M27
26-JAN-77
10:51

PARTITION NAME : GEN
IDENTIFICATION : 026108
TASK UIC
[320,4]
STACK
LIMITS: 000176 001175 001000 00512.
PRG XFR ADDRESS: 022514
TOTAL ADDRESS WINDOWS: 1.
TASK IMAGE SIZE
6880. WORDS
TASK ADDRESS LIMITS: 000000 032657

TESTl.TSK;l OVERLAY DESCRIPTION:
BASE

TOP

000000
032510
032510
032510

032507
032607
032657
032617

LENGTH
032510
000100
000150
000110

13640.
00064.
00104.
00072.

TESTI
C$$010
C$$015
C$$020

3 over1ayable

C$$010
C$$015

2 overlayable
segments

segments

AFTER
TEST2.TSKi2

MEMORY ALLOCATION MAP TKB M27
26-JAN-77
10:57

PARTITION NAME : GEN
IDENTIFICATION : 026108
TASK UIC
[320,4]
STACK
LIMITS: 000176 001175 001000 00512.
PRG XFR ADDRESS: 022514
TOTAL ADDRESS WINDOWS: 1.
TASK IMAGE SIZE
6912. WORDS
TASK ADDRESS LIMITS: 000000 032743

TEST2.TSK:2 OVERLAY DESCRIPTION:
BASE

TOP

000000
032574
032574

032573
032673
032743

Figure 10-3

LENGTH
032574
000100
000150

13692.
00064.
00104.

TESTI

Overlay Description Map Before and After Modification

10-9

CHAPTER 11
ERROR MESSAGES

11.1

COMPILER SYSTEM ERRORS

The TRAX COBOL compiler is a complex system program consisting of
many program overlays that manipulate numerous data structures.
Throughout the compiler, consistency checks are performed on program
flow and the contents of data fields.
If the compiler detects an
inconsistency, it types a message on the console and terminates the
compilation. A system error message has the following format:
SYSTEM ERROR NNNNN
where NNNNN is a number used by the DEC COBOL developers to determine
the probable cause of the error.
When a system error occurs, the
compiler's input file is closed and all output files
(object,
list,
and ODL) are closed and deleted.
In the event of a
Software Support

11.2

TRAX COBOL compiler system error, contact your DEC
Specialist immediately.

DIAGNOSTIC ERROR MESSAGES

This chapter contains a numerical listing of the diagnostic messages
generated by the TRAX COBOL compiler. The compiler generates these
messages whenever it detects an error
in the source program.
In
general,
a source error detected by the compiler results in the
associated diagnostic message being embedded within the source program
listing.
That is,
when an error is detected in the source program,
the compiler prints the diagnostic message either before or after
the
erroneous source program line.
There are two exceptions to the
general concept of "embedded diagnostics":
1.

There may be diagnostic messages listed after the last entry
in the Data Division and before the Procedure Division
header.
These are diagnostics which logically can not be
issued until the entire Data Division text is processed.

There may be diagnostic messages listed after the last line
of the Procedure Division.
These are diagnostics which
logically can not be
issued until the entire Procedure
Division text is processed.

In addition to the error message number and message text, the display
contains a source line number, which identifies the error line, and an
alphabetic code (discussed below)
which informs the user
of
the
seriousness of the error.
The information within a diagnostic message
line is displayed (from left to right) in the following order:

11-1

ERROR MESSAGES
1.

Alphabetic code,

Source line number,

Numerical error number,

Text of the diagnostic message.

For convenience, the alphabetic code is left-justified in the listing
so the user merely scans the listing to identify any diagnostic
message issued during compilation. Again, for the user's convenience,
a summary of the number of errors detected during the compilation is
given at the end of the source listings.
If no errors are detected
during the compilation, the compiler prints "NO ERRORS" at the end of
the source listing.
The following illustration shows a typical diagnostic message and
manner in which it appears on the source listing:
00096
00097
00098
00099

the

MOVE 72.5 TO N2
IF N2 NOT = T2 DISPLAY "? #10".

MOVE 3250 TO N3.

I 00099 372 POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION.
00100
00101
00102
00103
00104

IF N3 NOT

= T3 DISPLAY "? #11".

MOVE -432 TO N4.
IF N4 NOT = T4 DISPLAY "? #12".

In the example, the diagnostic message is immediately identified by
the appearance of the left-justified alphabetic code I.
The
alphabetic code indicates that
the
message
is
an
I-type
(informational)
diagnostic;
the diagnostic is issued for source
line number 99;
the error number is 372;
and the text of the
message is POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION. Note that
the diagnostic message line, in this example, appears after the
source line for which it was issued.
The error messages, used in conjunction with this chapter, provide
the user with an important debugging tool. This chapter contains
information necessary for interpreting the messages.
It explains
what caused the error and how the compiler handled the error.
Since different errors cause varying degrees of problems for
the
compiler
(some do not affect the compilation at all, while others
may be so critical that they cause an abort of the compilation), the
TRAX COBOL compiler provides four general types
(or severity
levels) of diagnostic messages. Alphabetic codes (I, W, F, and A)
identify these error levels. When it detects an error in the source
program, the compiler attempts to recover from the error and
continue to compile the program. This recovery action may force the
compiler to make an assumption about the source program.
The four
levels of diagnostic messages are categorized according to the
likelihood that the result of the compiler's assumption will be an
object program that runs as originally intended by the programmer.
The following list explains the purpose of and the compiler's action
for each of the four message levels:

11-2

ERROR MESSAGES
I

(Informational) Informative diagnostic. The purpose of such
a diagnostic is to convey information to the user in an
observational or advisory capacity.
The compiler's error
recovery
(if any is required) is almost certain to be thc",
desired by the user.

(Warning) Warning diagnostic. The purpose of this type of
message is to warn the user that something is wrong with the
associated source statement, but that the compiler can take
corrective action on the source element in error.
The
compiler's recovery action may not be that desired by the
user,
but the statement, as corrected by the compiler, will
be executable.

(Fatal) Fatal diagnostic. The purpose of such a diagnostic
is to indicate to the user that something is fatally wrong
with the indicated source statement. By fatal, the compiler
means it cannot generate the object code required for the
functionality the programmer coded in the erroneous source
statement.
The compiler's error recovery action will
probably leave out a portion of the source program.
In
general, the compiler will not produce an object program for
COBOL source programs which have F-type errors in them.
However,
the user can force the compiler to generate an
object program by specifying the /ACC:2
switch in the
command string input to the compiler prior to compilation
(See
Section
2.4,
Compiler
Switches for a detailed
explanation
of the /ACC:n switch.) The /ACC:2 switch
instructs the compiler to generate an object program,
even
if the source program contains F-type errors.
In this case,
when an F-type error is detected in the Procedure Division,
the compiler generates special error trap object code in
place of the incorrect source statement.
When the object
program is executed and the special error trap code is
encountered, the software displays the following message on
the console and aborts the program execution:
FATAL ERROR ON SOURCE LINE XXXXX
where XXXXX is the source line number for which an F-type
diagnostic
was issued during compilation.
For F-type
diagnostics issued in the Identification, Environment,
and
Data Divisions, no special error trap coding is generated
since, in general, executable code is not generated for
these divisions. However, the fact that F-type diagnostics
are issued for these divisions can have a definite effect on
the behavior of the execution of the object program.
WARNING
When the user specifies the /ACC:2 switch, the user
is
formally
acknowledging
to the software a
willingness to let the program go into execution
even though it may have fatal errors in it.
Because
the source program has very severe errors in it, the
behavior of the associated object program is, in
general, unpredictable.
In certain cases, such as a
COBOL program with files opened in I-a mode, letting
the program with F-type errors go into execution
could be disastrous. Thus, the /ACC:2 switch should
be used with caution. The facility is provided as
an extra debugging option.
It can be useful in
shortening the compile-debug cycle, particularly if
11-3

ERROR MESSAGES
applied
to
large
COBOL
programs which take
considerable compilation time~ The point is that
the user should use the /ACC:2 facility wisely and
discretely.
(Abortive) Abortive diagnostic. The purpose of this type of
diagnostic is to inform the user that the compiler must
abort compilation. The compiler's error recovery is not
possible:
it can make no val id assump't ions and has no
choice but to abort the compilation.

Appendix

contains

error
messages
reference.

11.3

the

arranged

TRAX COBOL compiler diagnostic
in numerical order for easy

RUNTIME FILE I/O ERROR PROCEDURES

When an error condition occurs during I/O
procedure is used:

operations,

the

following

If the file status key for the file is present, it is set to
the appropriate code for
the error condition.
(See Table
11-1 for sequential file status keys, or Table 11-2
for
relative and indexed file status keys.)

If an AT END or INVALID KEY imperative condition is specified
for the I/O operation, the path indicated by the imperative
statement is taken.
The file system performs no other
processing in the file for the current statement. The USE
procedure, if one is declared for the file, is not performed.

If no AT END or INVALID KEY imperative condition is specified
for the I/O operation and a USE procedure is declared for the
file, the USE procedure section is performed,
and then
control is returned to the program. The file system performs
no further processing for this file.
If no USE procedure is declared for the file, a fatal error
condition exists;
the OTS aborts the program and displays
the following I/O error message:
IICBL
IICBL

37:
FILE: NN ... NO USE PROCEDURE FOR
I/O ERROR"
RECORD MANAGEMENT SERVICES - XXII

represents the name of the file:

represents the Record Management Services
(See Appendix H for these error codes.)

11-4

error

code.

ERROR MESSAGES
The following tables show various error numbers and error codes that
identify error conditions and messages. The error codes in Tables
11-1 and 11-2 are accessible to the user's program through the
declaration and use of the FILE STATUS key in the program. The error
codes in Appendix G are not returned to the user's program but
represent error conditions detected by Record Management Services.
The error message numbers in Appendix G are merely identifying numbers
for the messages and appear at the user terminal in the following
form:
"CSL --nn:

message

nn is the message number.
Tables 11-1 and 11-2 contain status key codes. The left-hand digit of
the status key code is status key 1, and the right-hand digit is
status key 2.
Table 11-1
Sequential I/O File Status Key Values (ASCII)
Status Key
Code

Meaning

No further information (successful)

End-Of-File indicator detected

Permanent error

Permanent error (boundary error on WRITE statement)

File locked by another task

REWRITE attempted without prior READ

Improper operation attempted

Allocation failure on OPEN (no file space on device)

No buffer space {program tried to open a file that is
sharing buffer space (SAME AREA) with another file)

No such file (the file named in an OPEN statement was
not found)

CLOSE error (error discovered while in the process of
closing the file)

11-5

ERROR MESSAGES
Table 11-2
Relative And Indexed I/O File Status Key Values (ASCII)
Status Key
Code

11.4

Meaning

No further information (successful)

Duplicate
alternate
record
key
values
were
successfully created during the execution of a WRITE
or REWRITE statement

End-Of-File indicator detected

Sequence error on primary key during the execution of
a WRITE or REWRITE statement

Duplicate key error

No such record error

Boundary error on WRITE statement

Permanent error

File locked by another task

Record locked by another task

REWRITE or DELETE attempted without prior READ

Improper operation attempted

Allocation failure (no file space on device)

No buffer space (program tried to open a file that is
sharing buffer space (SAME AREA) with another file)

No such file (the file named in an OPEN statement was
not found)

CLOSE error (error discovered while in the process of
closing the file)

RUN-TIME ERROR MESSAGES

Appendix I contains a list of the COBOL Object Time System (OTS) error
messages.
Wherever
it can,
the COBOL OTS will list auxiliary
information along with the error message. This auxiliary information
is defined in Section 11.4.1.

11.4.1

OTS Auxiliary Error Message Information

Following each OTS error message, the OTS will attempt to display
additional clarifying information.
This information is intended to
direct you to the exact source line statement causing the error.
The
auxiliary information has the following format:

11-6

ERROR MESSAGES
PROGRAM-ID AAAAAA , IDENT:
IN PSECT:

CCCCCC

AT OFFSET:

DDDDDD

BBBBBB

Where:
AAAAAA

is the first six characters of the PROGRAM-ID specified
in the source program.

BBBBBB

is the value appearing in the IDENT field
listing.

CCCCCC

is the name of the procedural code PSECT containing the
error.

DDDDDD

is the octal byte offset (within PSECT CCCCCC) at which
the error occurred.

compiler

If the statement in error is a PERFORM,
the nested PERFORM stack,
containing the source line location of every PERFORM statement
encountered thus far, is displayed (see Example 1). If an error
is
detected while a chain of nested CALL statements is being processed,
auxiliary information is displayed for each element in the chain
(see
Example 2).
To take full advantage of this auxiliary information,
you must have
compiled the source program with the jMAP and jOBJ switches specified.
Using the PSECT name (CCCCCC)
and octal byte offset
(DDDDDD),
in
conjunction with the Procedure Name Map, you can identify the two
source procedure names that bracket the location of the error.
Also,
using the octal byte offset
(DDDDDD) you can (via the jOBJ output
listing) identify the specific verb causing the error.
Consider
the
following examples:
Example 1
Figure 11-1 contains the listings generated for the COBOL program used
in this example. Execution of the program depicted in Figure 11-1 will
yield the following results:
RUN DIAG3
CBL

25:
ILLEGAL NESTED PERFORM AT SOURCE LINE 16
PROGRAM 10: DIAG3, IDENT:
038105
IN PSECT:
$ZZOOI
AT OFFSET:
000074
NESTED PERFORM SOURCE LINE NUMBERS:
00014
00015

CBL -- 15:

STOP RUN

Ready
The PROGRAM-ID and IDENT line refer to the corresponding lines is the
compiler listing
(DIAG3 and 038105 in this example). The IN PSECT
line identifies the exact PSECT containing the error ($ZZOOl in this
example) .
See the Procedure Name Map in Figure 11-1. The AT OFFSET
line identifies the octal byte offset within the PSECT at which the
statement in error exists
(000074
in this example). See the /OBJ
compiler listing in Figure 11-1.
Finally,
the last three lines
identify
the
source line location of every PERFORM statement
encountered thus far in the program.
11-7

ERROR MESSAGES
SAMPLE /OBJ LISTING
CMD:DIAG3,DIAG3/MAP/OBJ/KE:ZZ=DIAG3
IDENT:
038105
00001
00002
00003
00004
00005
00006
00007
00008
00009
00010
00011
00012
00013
PERFORM

001

000024

PERFORM

001

000050

PERFORM

001

000074

IDENTIFICATION DIVISION.
PROGRAM-ID. DIAG3.

*
*
*

INVOKE "?ILLEGAL NESTED PERFORM AT LINE XXXXX"

ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. PDP-II.
OBJECT-COMPUTER. PDP-II.
DATA DIVISION.
WORKING-STORAGE SECTION.
PROCEDURE DIVISION.
SO SECTION.

00014

PO. PERFORM PI THRU P5.

00015

Pl. PERFORM P2 THRU p4.

00016
00017
00018
00019

P2. PERFORM P3 THRU P4.
P3.
P4.
P5.

SAMPLE PROCEDURE NAME MAP
PROCEDURE NAME MAP
NAME

SOURCE
LINE

PSECT

OFFSET

SEG

SECT

SO
PO
PI
P2
P3
P4
P5

00013
00014
00015
00016
00017
00018
00019

$ZZOOl
$ZZOOl
$ZZOOl
$ZZOOl
$ZZOOl
$ZZ001
$ZZ001

000024
000024
000050
000074
000120
000126
000134

00
00
00
00
00
00
00

PARA

Figure 11-1
Sample Listing of Program Used in Examp1e-l

11-8

P
P
P
P
P
P

ERROR MESSAGES
Example 2
Figure 11-2 contains the listings generated for the COBOL programs used
in this example.
Execution of the programs depicted in Figure 11-2
will yield the following results:
RUN TEST
BEGIN MAIN PROGRAM
BEGIN SUBl SUBPROGRAM
BEGIN SUB2 SUBPROGRAM
CBL -- 13: NULL ALTERABLE GO TO
PROGRAM ID: SUB2 , IDENT: 080130
IN PSECT:
$CCOOl
AT OFFSET:
000062
LISTING OF NESTED ENVIRONMENTS:
PROGRAM ID: SUBl , IDENT: 080130
AT OFFSET:
000054
PROGRAM ID: MAIN , IDENT: Od0129
AT OFFSET: 000042
CBL -- 15: STOP RUN
Ready
As in the previous example, the PROGRAM-ID and IDENT lines refer to
the corresponding lines in the compiler listing;
the IN PSECT line
identifies the exact PSECT containing the error;
and the AT OFFSET
line
identifies the octal byte offset.
Note also,
that this
information is repeated for every program within the chain of
subprograms comprising the task.

11-9

ERROR MESSAGES

SAMPLE /OBJ LISTING (Main Program)
CMD:MAIN,MAIN/KE:AA/OBJ/MAP=MAIN
IDENT: 080129

00001
00002
00003
00004
00005
00006
00007
00008
00009
00010
00011
00012
00013
00014
DISPLAY

000024

CALL

000042

DISPLAY

000060

STOP

000076

IDENTIFICATION DIVISION.
PROGRAM-ID. MAIN.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. PDP-II.
OBJECT-COMPUTER. PDP-II.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 A PIC 99.
77 B PIC 99.
77 C PIC 99.
PROCEDURE DIVISION.
SO SECTION.
PO.

00015

DISPLAY "BEGIN MAIN PROGRAM".

00016

CALL "SUB1" USING ABC •

00017

DISPLAY "ENDING MAIN PROGRAM".

00018

STOP RUN.

SAMPLE PROCEDURE MAP (Main Program)
PROCEDURE NAME MAP
NAME

SOURCE
LINE

PSECT

OFFSET

SEG

SECT

00013
00014

$AAOOI
$AAOOI

000024
000024

00
00

Figure 11-2

Sample Listing of Program Used in Example-2

11-10

PARA

ERROR MESSAGES

SAMPLE /OBJ LISTING (Subprogram)
CMD:SUB1,SUB1/KE:BB/OBJ/MAP=SUB1
IDENT: 080130

00001
00002
00003
00004
00005
00006
00007
00008
00009
00010
00011
00012
00013
00014
00015
DISPLAY

000024

SUBTRACT

000042

CALL

000054

DISPLAY

000072

STOP

000110

IDENTIFICATION DIVISION.
PROGRAM-ID. SUB1.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. PDP-II.
OBJECT-COMPUTER. PDP-II.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
77 D PIC 99.
77 EPIC 99.
77 F PIC 99.
PROCEDURE DIVISION USING D E F .
Sl SECTION.
Pl.

00016

DISPLAY "BEGIN SUB1 SUBPROGRAM".

00017

SUBTRACT D FROM E GIVING F .

00018

CALL "SUB2" USING D E F .

00019

DISPLAY "EXITING SUB1 SUBPROGRAM".

00020

STOP RUN .

SAMPLE PROCEDURE MAP (Subprogram)
PROCEDURE NAME MAP
NAME

SOURCE
LINE

PSECT

OFFSET

SEG

SECT

Sl
PI

00014
00015

$BB001
$BB001

000024
000024

00
00

Figure 11-2 (Cont.)

PARA

Sample Listing of Program Used in Examp1e-2

11-11

APPENDIX A
THE COBOL FORMATS

COBOL NOTATION USED IN FORMATS
•

Underlined upper-case words (key words) - required words;

•

Upper-case words (not underlined) - optional words;

•

Lower-case words - generic terms, must be supplied by the user;

•

Brackets [] - enclosed portion is optional; if several enclosed words are
vertically stacked, only one of them may be used;

•

Braces {} - a selection must be made from the vertical stack of enclosed words;

•

Ellipsis ••• - the position at which repetition may occur;

•

Comma and semicolon - optional punctuation;

•

Period - required where shown in the formats.

IDENTIFICATION DIVISION.
PROGRAM-ID. program-name.
[AUTHOR. [comment-entry] ••• ]
[~LATION.
[comment-entry] ••• ]
[DATE-WRITTEN. [comment-entry] ••• ]
[DATE-COMPILED. [comment-entry] ••• ]
[SECURITY. [comment-entry] ••• ]

ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.

PDP-II

OBJECT-COMPUTER.

PDP-II

[MEMORY SIZE integer

{ OO~S

CHARACTERS
MODULES

[PROGRAM COLLATING SEQUENCE IS alphabet-name]
[SEGMENT-LIMIT IS segment-number].

A-I

THE COBOL FORMATS
[SPECIAL-NAMES.
[CARD-READER IS mnemonic-name-l]
[CONSOLE IS mnemonic-name-2]
[LINE-PRINTER IS mnemonic-name-3]
[PAPER-TAPE-PUNCH IS mnemonic-name-4]
[PAPER-TAPE-READER IS mnemonic-name-S]
SWITCH integer-l
[

{ON STATUS IS condition-name-l
OFF STATUS IS condition-name-2
[OFF STATUS ~ condition-name-2]}]
[ON STATUS IS condition-name-l]

[AlPhabet-name IS

{~RD-l}]

[CURRENCY SIGN IS literal-I]
[DECIMAL-POINT IS COMMA.]][INPUT-OUTPUT SECTION.
FILE-CONTROL. {file-control-entry} •••• ,

Format 1:
SELECT [OPTIONAL] file-name
ASSIGN TO literal-l

~ RESERVE integer-l

[::s]]

[; ORGANIZATION IS SEQUENTIAL]
[; ACCESS MODE IS SEQUENTIAL]
[; FILE STATUS IS data-name-l] •

Format 2:
SELECT file-name
ASSIGN TO literal-l

GRESERVE integer-l
ORGANIZATION IS RELATIVE
SEQUENTIAL
[

ACCESS MODE IS

{ { RANDOM }
DYNAMIC

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

[; FILE STATUS IS data-name-2] •

A-2

THE COBOL FORMATS
Format 3:
SELECT file-name
ASSIGN TO literal-l

[. RESERVE integer-l
ORGANIZATION IS INDEXED

[

ACCESS MODE IS

{

SEQUENTIAL ~
RANDOM

DYNAMIc

RECORD KEY IS data-name-l
[; ALTE'RNATE RECORD KEY IS data-name-2 [WITH DUPLICATES]] •••
[; FILE STATUS IS data-name-3] •
[I-O-CONTROL.
[SAME [RECORD] AREA FOR file-name-l {file-name-2} ••• ] •••
[MULTIPLE FILE TAPE CONTAINS file-name-3 [POSITION integer-I]
[file-name-4 [POSITION integer-2] ••• ] •••
[APPLY

PRINT-CONTROL

ON file-name-5 [file-name-G] ••• ] •••

DATA DIVISION.
[FILE SECTION.
[FD file-name

~LOCK CONTAINS [integer-l TO] integer-2

RECORDS
{ CHARACTERS

[RECORD CONTAINS [integer-3 TO]
integer-4
RECORD IS}
{ STANDARD }
LABEL { RE'CORDs ARE
OMITTED

fVALUE OF 10 IS {d~ta-name-l}J
t----- -- -l1teral-l
~ATA {~S I!RE}
data-name-3
fLINAGE IS

{~ata-name-5}

[ 1 n t eg er-s

LINES

{~atta-name7-7}]

LINES AT TOP
[
--1n eger[CODE-SET IS alphabet-name].
[WORKING-STORAGE SECTION.

77-level-descriP tion-entryJ
[ record-description-entry

[data-name-4]

[LINES AT BOTTOM

-----

...

]

[LINKAGE SECTION.

~7-level-descriPtion-entryJ
Lrecord-description-entry
••• ]

A-3

CHARACTERS]

[WITH FOOTING AT

[record-description-entry] ••• ] ••• ]

},l

•• ]

•••

{~ata-name-G}]
1nteger-G

{~ata-name-8}]J
1nteger-8

THE COBOL FORMATS
Data description entry:
Format 1:
level-number

[{

[

{dat~-name-l}
FILLER
---

[REDEFINES data-name-2]
PICTURE} IS character-str1ng
. ]
PIC

~ {gE;~::ONALI~
IS)

DISPLAY-7
INDEX

[SIGN IS]

{

~:r~~~G }

SYNCHRONIZED }
[ {SYNC

[LEFT
RIGHT

---

[SEPARATE CHARACTER]

----

JUSTIFIED}
]
[{ JUST
RIGHT
----raLANK WHEN ZERO]
[VALUE IS Iitenl]

[

OCCURS

integer-l ~ integer-2 TIMES DEPENDING ON data-name-3}
{ integer-2 TIMES

ASCENDING }
[{ DESCENDING

KEY IS data-name-4

[INDEXED BY index-name-l

[data-name-S] ••• ]

[index-n ame-21 ooolJ

Format 2:
66 data-name-l RENAMES data-name-2
THROUGH}
[{ THRU

data-name- 3J

Format 3:
IS }
{~
VALUES ARE

88 condition-name

[literal-3

literal-l

THROUGH}
[{ THRU

literal-2]

[I ~~~UGH I literal-4JJ

PROCEDURE DIVISION

[data-name-l] [,data-name-2] ••• ].

Format 1:
[DECLARATIVES.
{section-name SECTION [segment-number] • declarative-sentence
[paragraph-name. [sentence] ••• ] ••• } •••
END DECLARATIVES.]
{section-name SECTION [segment-number].
[paragraph-name. [sentence] ••• ] ••• } •••
Format 2:
{paragraph-name. [sentence] ••• } •••

A-4

THE COBOL FORMATS
STATEMENTS

:::::: :::::::::: ;:::M

mn{~~c}-name]
TIME

identifier-I}
{literal-l

ADD

[identifier-2]
literal-2

TO identifier-m [ROUNDED]

[identifier-n[ROUNDED]] ••• [ON ~~ imperative-statement]
ADD
{i~entifier-l}
{i~entifier-2}
[i?entifier-3] •••
--11teral-1
11teral-2
11teral-3
GIVING identifier-m [ROUNDED]
[identifier-n [ROUNDED]]
[ON ~~ imperative-statement]
ADD

CORRESPONDING}
{ CORR
identifier-l TO identifier-2 [ROUNDED]
[ON SIZE ~ imperative-statement]

ALTER procedure-name-l TO [PROCEED TO] procedure-name-2
~rocedure-name-3 TO-rPROCEED TOY-procedure-name-4]
CALL literal-l
----[USING data-name-l [,data-name-2] ••• ]

CLOSE file-name-l

~{:~~}
[~~~H~O~]~
~{NO~}
LOCK

file-name-2
[

REEL}

WITH

REWINDJ~~

[WITH NO
FOR REMOVAL
{NO REWIND}
LOCK

COMPUTE identifier-l [ROUNDED] [identifier-2 [ROUNDED]]
= arithmetic-expression [ON SIZE ~ imperative-statement]
DELETE file-name RECORD
[INVALID KEY imperative-statement]
identifier-I} [identifier-2]
DISPLAY { literal-l
literal-2
[UPON mnemonic-name] [WITH ~ ADVANCING]
DIVIDE

identifier-I}
INTO identifier-2 [ROUNDED]
{ literal-l
[identifier-3[ROUNDED]] ••• [ON SIZE ERROR imperative-statement]

DIVIDE

identifier-I}
{identifier-2}
INTO
literal-2
GIVING identifier-3[ROUNDED]
{ literal-l
[identifier-4[ROUNDED]] ••• [ON ~ ~ imperative-statement]

DIVIDE

identifier-I}
{identifier-2}
BY
literal-2
~ identifier-3[ROUNDED]
{ literal-l
[identifier-4[ROUNDED]] ••• [ON ~ ~ imperative-statement]

DIVIDE

identifier-I}
{identifier-2}
INTO
literal-2
~ identifier-3[ROUNDED]
{ literal-l
REMAINDER identifier-4[ON SIZE ERROR imperative-statement]

DIVIDE

identifier-I}
{identifier-2}
BY
literal-2
~ identifier-3[ROUNDED]
{ literal-l
REMAINDER identifier-4[ON SIZE ~ imperative-statement]

A-5

THE COBOL FORMATS
EXIT [PROGRAM]
GO TO [procedure-name-l]
GO TO procedure-name-l [procedure-name-2] ••• procedure-name-n DEPENDING ON identifier
IF condition

statement-l }
{ NEXT SENTENCE

ELSE statement-2
}
{ _E_L_SE__
N_E_XT_ . ; ;,S. ; ;,E.;.;.N. ; ;,TE; ; ,N.;.;.C.; ;,;E.; ;,;

INSPECT identifier-l TALLYING
{

identifier-2 FOR

{{ {

~ING }

i~entifier-3}} [{ BEFORE}
{ 11teral-l
AFTER

INITIAL

CHARACTERS

INSPECT identifier-l REPLACING
CHARACTERS ~

~ING}

{{ FIRST

{{

{ i~~:~~~~~r-6 }

i~entifier-5}

BEFORE}
[{ AFTER
BY

11teral-3

INITIAL

{i~entifier-7}J
11teral-5

identifier-6}
{ literal-4

[{BEFORE}
AFTER

INITIAL

identifier-3}}
literal-l

[I::~~

INITIAL

INSPECT identifier-l TALLYING
{

~DING}

{

{identifier-6}
literal-4

[{ ~}
AFTER

identifier-2 FOR {{ (

CHARACTERS

REPLACING
CHARACTERS BY

{{

5
~ING
} {{ i~~:~~~~~r- }
FIRST

i~entifier-7}J} •••}
{ l1teral-S

INITIAL

identifier-6}
{ literal-4

identifier-7 }]
{literal-5

[{ ~}
AFTER

INITIAL

...J

MOVE

identifier-I}
{ literal

TO identifier-2 [identifier-3] •••

MOVE

CORRESPONDING}
{ CORR

identifier-l TO identifier-2

identifier-I}
BY identifier-2[ROUNDED]
{ literal-l
[identifier-3 [ROUNDED]] ••• [ON ~ ~ imperative-statement]

MULTIPLY

identifier-I}
{identifier-2}
MULTIPLY
BY
literal-2
~ identifier-3 [ROUNDED]
{ literal-l
[identifier-4 [ROUNDED]] ••• [ON ~ ERROR imperative-statement]

A-6

THE COBOL FORMATS

0PEN

{

~ file-name-l [WITH NO REWIND]

[file-name-2 [WITH NO REWIND]] ••• }
OUTPUT file-name-3[WITH NO REWIND] [file-name-4 [WITH NO REWIND]] •••
1-0 file-name-5 [file-name-~
-------EXTEND file-name-7 [file-name-8] •••

[I
[I
[I
[I

PERFORM procedure-name-l
PERFORM procedure-name-l
PERFORM procedure-name-l
PERFORM procedure-name-l

VARYING

identifier-2 }
{ index-name-l

THROUGH

THRU

THROUGH

THRU

THROUGH

THRU

THROUGH

THRU

I
I
I
I

pro cedure-n ame-2]
procedure-name-2]

{~dentifier-l }
1nteger-l

procedure-n ame-2]

UNTIL condition-l

TIMES

procedure-name-2]
rdentifier-3 }

FROM

index-name-2
literal-l

{ identifier-4 }
literal-2

UNTIL condition-l

{ identifier-S }
index-name-3

FROM

{ identifier-7}
literal-4

UNTIL condition-2

{ identifier-8 }
index-name-S

FROM

{ identifier-IO }
literal-6

~ condition-3]]

{identifier-G}
index-name-4
literal-3

{identifier-9}
index-name-6
literal-5

READ [WITH UNLOCK] file-name [NEXT] RECORD [INTO identifier] [AT END imperative-statement]
- - WITH LOCK
READ [WITH UNLOCK] file-name RECORD [INTO identifier] [INVALID KEY imperative-statement]
- - WITH LOCK
READ [:~~: ~~CK] file-name RECORD[INTO identifier] [;KEY IS data-name]
[;INVALID KEY imperative-statement]
REWRITE [WITH UNLOCK]
WITH LOCK
REWRITE

record-name [FROM identifier] [INVALID KEY imperative-statement]

WITH UNLOCK]
[ WITH LOCK

SEARCH identifier-l

record-name[FROM identifier]

[VARYING

~dentifier-2 }]

{ 1ndex-name-1

WHEN condition-l

imp erative-statement-2}
{ NEXT SENTENCE

[~ condition-2

imp erative-statement- 3
{ NEXT SENTENCE

A-7

[AT ~ imperative-statement-l]

THE COBOL FORMATS
SEARCH ~ identifier-l [AT ~ imperative-statement-l]
data-name-l
WHEN

identifier-3
}}
literal-l
{
arithmetic-expression-l

IS EQUAL TO}
{ IS =

{
condition-name-l

IS EQUAL TO}
{ IS =

data-name-2
{

identifier-4
}}
literal-2
{ arithmetic-expression-2

condition-name-2

imp erative-statement-2}
{ NEXT SENTENCE

SET

[~dentifier-2] ••• }
[lndex-name-2] •••

identifier-l
{ index-name-l

SET

index-name-4

[index-name-5] •••

identifier-3}
index-name-3
{
integer-l
{

UP BY
}
~~

{ ~dentifier-4}
lnteger-2

~KEY

IS EQUAL TO
}
IS IS GREATER THAN
START file-name
IS >
{ IS NOT LESS THAN
----IS NOT <
[INVALID KEY imperative-statement]

STRING

identifier-2]
[ literal-2

identifier-I}
{ literal-l

U~~~:=!i~:r-41

[~~~::~i~~r-

5
]

DELIMITED BY

•••

DELIMITED BY

{

identifier-3}
literal-3
{ SIZE

identifier-6 ~
literal-6
SIZE

INTO identifier-7 [WITH POINTER identifier-8]
---[ON OVERFLOW imperative-statement]
identifier-I}
[identifier-2]
literal-2
FROM identifier-m[ROUNDED]
{ literal-l
[identifier-n[ROUNDED]] ••• [ON ~ ~ imperative-statement]

SUBTRACT

identifier-I}
{ literal-l

identifier-2]
[ literal-2

FROM

identifier-m}
{ literal-m

GIVING identifier-n[ROUNDED] [identifier-o[ROUNDED]] •••
[ON SIZE ERROR imperative-statement]
SUBTRACT

CORRESPONDING}
{ CORR

identifier-l FROM identifier-2 [ROUNDED]

[ON SIZE ERROR imperative-statement]
RECORD
] £'1
UNLOCK [ ALL RECORDS
1 ename
UNSTRING identifier-l
identifier-2}
[
{identi£ier-3}]
~ [ALL]
literal-2
[ DELIMITED BY [~]
{ literal-l
INTO identifier-4[DELIMITER IN identifier-5] [COUNT IN identifier-6]
[identifier-7 [DELIMITER IN identifier-8] [COUNT IN identifier-9]] •••
[WITH POINTER identifier-IO] [TALLYING IN identifier-II]
[ON OVERFLOW imperative-statement]

A-8

... ]

THE COBOL FORMATS

file-name-l[file-name-2]eeej

USE AFTER STANDARD

-----

EXCEPTION}
{ ERROR

PROCEDURE ON

INPUT
OUTPUT
I-O
EXTEND

WITH UNLOCK]
WRITE [ WITH LOCK
record-name [~ identifier-I]

~ ::~ I

~dentifier-2}

ADVANCING

END-OF-PAGE }
{ EOP

[AT

{ { l.nteger
{

[PAGE]

imperative-statement]

UNLOCK] record-name [FROM identifier]
WRITE [ WITH
WITH LOCK

COpy

[INVALID KEY imperative-statement]

text-name}
{ literal-3
[ REPLACING

NOTE:

literal-I}
{ { word-l

literal-2})
{ word-2

...J

A COPY statement may appear anywhere that a word
appears in the COBOL source programe

A-9

APPENDIX B
COBOL DATA CONVERSION SUBROUTINES

TRAX COBOL provides two data conversion subroutines which are accessed
through the CALL statement.
These are CNVT which converts one
specified data type to another specified data type, and STRNUM which
converts a specified character string to numeric format.

B.l

CNVT

CNVT accepts a value of a specified data type and converts it to a
value of another designated data type. The data types recognized by
CNVT along with a description of each data type are listed below:
ASCII -- an ASCII string of digits with an optional leading
and an optional decimal point.

sign

Overpunch right -- an ASCII string of digits with the sign of the
number encoded into the right-most digit.
Overpunch left -- an ASCII string of digits with the sign of
number encoded into the left-most digit.

the

Separate right -- an ASCII string of digits with a required ASCII
"+" or "-" following the right-most digit.
Separate left -- an ASCII string of digits with a required
"+" or "-" to the left of the left-most digit.

ASCII

Zoned decimal -- an ASCII string of digits with the sign encoded
in the sixth bit of the right-most digit. Also known as DIBOL
format.
Short -- a single word,

(16 bits) two's complement, binary value.

Fortran -- a double word, two's complement, binary value in which
the most significant word follows the least significant word.
COBOL -- a double word two's complemented binary value
the most significant bits occur first.

which

Short floating-point -- a 32 bit floating point number.
Long floating-point -- a 64 bit floating point number.
Packed decimal -- a string of decimal digits packed 2 digits to a
byte, with the sign in the last half of the last byte. A 10, 12,
14, or 15 represents a plus (+), and an 11 or 13 represents a
minus (-).

B-1

COBOL DATA CONVERSION SUBROUTINES
Table B-1 summarizes the conversions performed by CNVT.
An "x"
indicates that CNVT will convert the data type on the left to, the
data type above. Note that the only conversions that cannot be made
are those which are made to overpunch, separate, and zoned data types.
Table B-1
Data Type Conversions Performed by CNVT

T
0

FROM

B.l.l

A
S
C
I
I

P
L

S
R

ASCII
Overpunch Right
Overpunch Left
Separate Right
Separate Left
Zoned
Short
FORTRAN
COBOL
Short Floating
Long Floating

x
x
x
x
x
x
x
x
x
x

PACKED Decimal

S
L

P
A
C
K
E
D

F
L

x
x
x
x
x
x
x

x
x
x
x
x
x
x
x

x
x
x

x
x
x
x
x
x
x
x
x

x
x

x
x
x
x
x
x
x
x
x
x

x
x
x
x
x
x
x
x
x
x
x

S
h

r
t

R
T

x
x
x
x
x
x

-x

CALL Statement

The following statement is used to call CNVT:
CALL "CNVT" USING VALl,TYPl,LENl,VAL2,TYP2,LEN2,STAT.
Each of the arguments for CNVT are described below:
VALl (input)

The address of the value to be converted.

TYPI (input)
The data type code for VALl.
codes are shown below.

o - Ascii number
1 - Overpunch right
2 - Overpunch left
3 - Separate right
4 - Separate left
5 - Short decimal
6 - Fortran long decimal
7 - Cobol long decimal
8 - Short floating-point
9 - Long floating-point
10 - Packed decimal
LENl (input) -- The length in bytes of TYP1.

B-2

The valid data type

COBOL DATA CONVERSION SUBROUTINES
VAL2 (output) -- The address where the converted value is
transferred.

TYP2 (input) -- The data type code in which VALl is to be
converted.
The data type codes are the same as TYPl, except
values 1 - 5 may not be used.
LEN2 (output)

The length in bytes of VAL2.

STAT (output)
are:

A status code.

The

possible

returned

values

1 - Warning: binary overflow. Value truncated.
o - Success
-1 - Arithmetic overflow
-2 - Value too big
-3 - invalid overpunch sign
-4 - illegal placement of minus sign
-5 - Non-digit in number
-6 - Bad input data type
-7 - Bad output data type
-8 - Multiple decimal point
-9 - Illegal placement of ,sign in Separate data type
-10 - Bad packed decimal digit

B.l.2

Details on Use of CNVT

For ASCII input to CNVT, the length of a string may be up to 20 bytes
long and the string may contain leading, trailing, or imbedded blanks.
For ASCII output from CNVT, the string length will be the exact length
of the numeric string with no imbedded or padding blanks. The string
is placed left-justified in the space designated by VAL2.
Any
characters not over-written in VAL2 will remain as they were before
CNVT was called. The length of VAL2 will never be greater than 20.
Overpunch, Separate and Zoned inputs are treated in the same manner as
Ascii.
However, these data types are not allowed as output.
For Short data, the input length argument, LENl, is always assumed
be 2. The output length argument, LEN2, will always be 2.

For Fortran and Cobol, the input length is always assumed to be 4
the output length will also be 4.

and

For floating-point data,
the input length for
short floating
is
assumed to be 4, as long floating is 8. The output length will be 4
and 8 respectively.

B.2

STRNUM

STRNUM accepts a character string with either leading or
trailing
spaces and stores it into a COBOL numeric data item with a usage of
display and a picture of S9(l2)V(6). This data item can then be used
within the object program for arithmetic or any other valid COBOL
operations on numeric items.

B-3

COBOL DATA CONVERSION SOBROOTINES
CALL State.ent

B.2.1

The following statement is used to call STRNUM:
CALL STRNUM using identifier-I, identifier-2, identifier-3, identifier-4.
Syntax Rules
1.

Identifier-l is the
display.

source

string

and

must

usage

Identifier-2 is the destination string and must be numeric
where the usage is display, sign is leading separate, and a
picture is S9(12)V9(6).

Identifier-3 must be numeric with usage computational and
picture 9(3).
It must contain the number of character
positions in the source string identifier-i.

Identifier-4 must be numeric with usage computational and
picture 9(3). The status code is returned in identifier-4 at
the completion of the call.

General Rules
1.

Identifier-l can contain
order specified:

the

following

characters

the

optional leading spaces

optional plus, '+1, or minus,
positive assumed

numeric characters representing integer part

optional decimal point,

optional numeric characters representing fractional part

optional trailing spaces

commas are ignored

I. "

I_I, sign.

If not present,

if function used

If a character is found that is out of order or invalid, as
defined above, then an error code is returned (see General
Rule 4). Any invalid character will be ignored and the
operation will continue until the end of the source string is
reached.
2.

Identifier-2 at the completion of the operation will contain
a valid TRAX COBOL numeric item with leading separate sign
and no editing characters.

Identifier-3 must contain the length of the source string
(Identifier-I)
at the time of the "CALL". For example, if
Identifier-l is declared with a picture of X (29)
then
Identifier-3 must have a value of 29.

Identifier-4 at the completion
contains the error code.
The
meanings are:

B-4

of the STRNUM operation
values and corresponding

COBOL DATA CONVERSION SUBROUTINES

Value

Meaning

No error
Illegal character in string
Truncation error
String contained only spaces

2
3

B-5

APPENDIX C
LOGICAL UNIT NUMBER (LUN) ASSIGNMENTS

LUN

ASSIGNMENT

Console, input

Console, output

Source input file

Source listing output file

Object output file

ODL output file

CREF scratch file

COpy library input file

Work file

Intermediate file

Sort work file

C-l

APPENDIX D
TRAX COBOL COMPILER IMPLEMENTATION LIMITATIONS

This appendix documents the implementation limitations for the TRAX
COBOL compiler system
(compiler and OTS).
The reader should not
confuse the term "limitations" with "restrictions".
Restrictions
delimit those language facilities which are not implemented or should
not be used due to known bugs in their existent implementation.
Implementation
limitations quantify the limits of a particular
language facility supported by the system.
Practical implementation
limitations exist in every compiler.
Such limitations are due to the finite size of various compiler
tables, compiler data structure representations,
etc.
Since the
TRAX COBOL compiler employs a Virtual Memory System to support many
compiler
data structures,
the quantities specified for various
implementation limitations are approximations. However, as a general
rule,
the following guidelines should not be exceeded in the
development of a COBOL program.
IMPLEMENTATION LIMITATIONS
1.

The maximum length of any COBOL data item
elementary item, table) is 4095 characters.

The default depth of dynamic PERFORM statement nesting is 10.
The default depth can be modified by using the /PFM switch at
compile time.

The maximum number of sending operands in a DISPLAY statement
is 16.

The maximum number of data-name
program is approximately 2000.

COBOL

The maximum number of procedure name definitions in
program is approximately 2000.

COBOL

The maximum nesting depth of matching parentheses in a
expression is 10.

COBOL

The maximum number of qualifiers
reference is 48.

The maximum number of procedure names in a
statement is 16.

D-1

definitions

(group

qualified
GO

item,

data-name
DEPENDING

APPENDIX E
COMPILER GENERATED PSECTS

An object program generated by the TRAX COBOL compiler is composed
of program sections called PSECTs.
Three types of PSECTs are
generated:
•

Data Psects

Contain the memory for the Data Division
of a COBOL program.

•

Control PSECTS

Contain the data that is required by the
OTS during program execution.

•

Procedural PSECTS

Contain the object code
the Procedure Division.

generated

for

Data and Control PSECTs are always non-overlayable.
Procedural
PSECTs, however, can be optionally overlayable or non-overlayable.

E.l

PSECT NAMING CONVENTIONS

The PSECTs generated by the TRAX COBOL compiler are named entities.
Each PSECT name is composed of a three character prefix followed by a
three character suffix. There are two different forms of the prefix:
•

$KK
Where: $
KK

•

Is a sentinel character and is always present.
Is a two character kernel that identifies the
PSECT.
It is this kernel character that is
specified by the /KER:kk switch.
The /KER:kk
switch is appended to the compiler command line to
assign a unique kernel value to the
PSECTs
generated during the compilation.
The default
kernel assignment is C$.

$CB
Where: $
CB

Is a sentinel character, and is always present.
Is a two character code that identifies the
as a COBOL compiler generated PSECT.

E-l

PSECT

COMPILER GENERATED PSECTS

PSECTs with the prefix $CB are generated to provide
control and work space required for I/O operations.

the

PSECTs with these same names are generated for each COBOL
compilation.
They are either overlayed or concatenated at
task-build time. Those that are overlayed, have a known fixed
length at task-build time. Those that are concatenated, have
a known length at compile-time and contribute their size to
the total size of the PSECT that is built by the TRAX Linker.
The three character suffix identifies the type of code or data the
PSECT contains. Table E-1 describes the suffixes assigned to $KK type
PSECTs, and Table E-2 describes the suffixes assigned to $CB type
PSECTs.
Table E-1
$KK PSECT Name Suffixes
Type

Suffix

Data

DAT

Data Division data storage areas.

DDD

Data Division
directories
descriptions of referenced
items.

ARG

Directories of referenced
items.

LIT

Literal Pool - contains all of the literals
referenced in the program.

LTD

Literal Directory.

lOB

Input/Output buffers.

WRK

COBOL compile unit work space - contains a
description
of
the
compile
unit
environment.

PDT

PSECT
dispatch
table
used
for
intra-program control of segmented COBOL
programs.

SDT

Subprogram dispatch table used
for
inter-program
control
(i.e.,
calling
subprograms) .

LST

Argument list work space - used to contain
the argument list passed to the called
subprogram.

PFM

Perform work space
control and checking
statements.

ADT

ALTER Dispatch Table - used to contain the
destination of alterable GO TO statements.

Control

Content

E-2

contains
Data Division

Linkage

used to
of nested

Section

provide
PERFORM

COMPILER GENERATED PSECTS
Table E-l (Cont.)
$KK PSECT Name Suffixes
Type

Procedural

Suffix

Content

USE

Default USE procedure
table - used
to
access
the
default OPEN mode
(INPUT,
OUTPUT, I-a, or EXTEND) USE procedures,
if
present.

ENT

Code generated by the
program entry point.

nnn

Numbered suffixes beginning
with
001.
These numbered PSECTs contain the object
code generated for the Procedure Division
of a COBOL program.

compiler

for

the

Table E-2
PSECT Name Suffixes
Allocation

Suffix

Content

OVR

lOT

Input/Output Table - contains a
reference
to each COBOL Input/Output OTS routine
required by the COBOL compilation.

OVR

FAI

File Access Block (FAB) - used to transmit
information to RMS at open and close time.

OVR

XAI

Auxiliary Access Blocks (XABs)
used to
transmit
information
on the keys for
indexed files to RMS at open time.

OVR

SWT

COBOL switches flag
PSECT.
Indicates
whether COBOL switches are referenced in
the COBOL program.

CON

IFI

Internal File Access Blocks (IFABs) used
internally by RMS to store information.

CON

IRI

Internal Record Access Blocks
used
internally
by
RMS
information.

CON

KDl

Internal Key Descriptors - used internally
by RMS to store information on the keys for
indexed files.

CON

BOI

Buffer Descriptor Blocks
(BOBs)
used
internally by RMS to store information on
the buffers.

E-3

(IRABs)
to
store

COMPILER GENERATED PSECTS
Table E-2 (Cont.)
PSECT Names Suffixes
Allocation

Suffix

Content

CON

KBI

Key Buffers - used internally
store keys for indexed files.

RMS

CON

FDI

FDA Index Vector contains
first FDA in program.

address

Note:
OVR

indicates overlayable PSECT.

CON

indicates concatenatable PSECT.

E-4

APPENDIX F
SORTING FILES IN A COBOL PROGRAM

Files prepared for or by COBOL programs may be sorted using the SORT
utility, which is discussed in the TRAX SORT Reference Manual.
A
major portion of that facility is available to the COBOL programmer
through usage of a set of subroutine linkages, described in detail in
this chapter. All such linkages involve use of a CALL statement with
an appropriate parameter list.

F.l

CALL STATEMENTS REQUIRED

A set of five CALL statements, each calling a particular SORT
subroutine,
is required within a COBOL program in order to produce a
sorted output file.
Each of these subroutines (RSORT, RELES, MERGE,
RETRN, ENDS)
performs a specialized function in the SORT procedural
sequence and lets the COBOL programmer both specify sorting parameters
and perform special operations on individual records as they pass
through the initial and final phases.

F.l.l

Initializing the SORT - CALL RSORT

The following statement is needed to initialize the sorting operation:
CALL "RSORT" USING IERROR, KEYSIZ, MAXREC, KEYLOC, SRTBUF,
BUFSIZ, SCRNUM.
Parameter usage is as follows:
IERROR -

location in which a SORT subroutine may place a
non-zero error code, if necessary, in COMP form,
value less than 100.

KEYSIZ -

location containing byte count of total
in CaMP form, a positive even integer.

MAXREC -

location containing byte count of maximum data
record size in CaMP form, a positive even integer.
The sum of KEYSIZ and MAXREC cannot exceed 16,383
(decimal) .

KEYLOC -

address of most major word in key.
See
F.2 for details on setting up sort key.

SRTBUF -

address of first word in sort work area.

BUFSIZ -

location containing byte count of sort
size in CaMP form.
F-l

key

size

Section

work

area

SORTING FILES IN A COBOL PROGRAM
SCRNUM -

F.I.2

location containing number of
scratch
files
available to the SORT (not less than 3, not more
than 8), in COMP form.

Passing a Record to the Sort - CALL RELES

The following statement is needed to pass a record to the sort:
CALL "RELES" USING IERROR, RECSIZ, INREC.
Parameter usage is as follows:

F.I.3

IERROR -

usage is as described above.

RECSIZ -

location containing byte count of data record size
in COMP form, a positive even integer not greater
than value in MAXREC.

INREC -

address of record to be passed to the sort.

Merging the Scratch Files - CALL MERGE

The following statement is needed to merge the scratch files
sort after all input records have been passed to the sort:

the

records,

one

CALL "MERGE" USING IERROR.
IERROR usage is as described above.

F.I.4

Requesting an OUTPUT Record - CALL RETRN

The following statement is needed to request the output
at a time, produced in sorted order by the sort:
CALL "RETRN" USING IERROR, RECSIZ, OUTREC.
Parameter usage is as follows:
IERROR -

usage is as described above.

RECSIZ -

location to receive byte count of returned data
record size in COMP form, a positive even integer
not greater than value in MAXREC.

OUTREC -

address of area to receive returned data record.
NOTE
RETRN indicates "no more records"
placing a negative value in IERROR.

F-2

SORTING FILES IN A COBOL PROGRAM
F.l.S

Terminating the Sort - CALL ENDS

The following statement is needed to terminate
sorted output records have been returned:

the

sort

after

all

CALL "ENDS" USING IERROR.
IERROR usage is as described above.

F.2

SETTING UP THE KEY

Before CALL RELES is executed, the COBOL programmer must first set up
the key in an area outside the record itself. Since the key area must
begin and end on a word boundary, usage of an 01 level description in
the Working - Storage Section is recommended. The most major byte for
the key, that byte "on the left", must be stored in the highest memory
location of the key area, and the most minor byte, that byte "on the
right", must be stored in the lowest memory location.
Thus the data must be moved byte by byte, NOT word by word, to the key
area,
resulting in the key being stored "backwards" by bytes.
If the
actual key contains an odd number of bytes, the last unused position
must be zeroed out, to insure proper results from word compares. Thus
for a key of 7 bytes, KEYSIZ - 8;
the contents of the lowest byte
address should always be zero.
The form of the comparison is logical, i.e., all eight bits of a byte
are significant;
there is no implied sign.
The programmer is
responsible for organizing the key data passed to the sort in a form
which ensures the correct sequence.

F.3

WORK AREA SIZE

The size of the sort work area, BUFSIZ, must be at least as
the result of the following calculation:
Minimum BUFSIZE = SCRNUM

large

* (1110 + MAXREC + KEYSIZE)

If less space is provided, the sort will keep decreasing the number of
work files until either the above equation is satisfied or the number
of files drop below three;
the latter is an error condition (error
code 17).
Any extra memory will be used to expand the in-core sort area.
in general, the more space supplied, the faster the sort.

F.4

Thus,

TYPICAL USAGE SEQUENCE

Sort the file SORT-IN to produce the file SORT-OUT.
1.

Open SORT-IN.

Call RSORT to initialize the sort.

Read the next logical record from SORT-IN.
go to step 7.

F-3

If no more

data,

SORTING FILES IN A COBOL PROGRAM

F.S

Perform any desired operations upon the input record.
is not to be submitted to the sort, go to step 3.

Set up the keys from the new record.

Call RELES to give the record to the sort, then loop back
step 3.

Close SORT-IN.

Call MERGE to collate the records submitted to the sort.

Open SORT-OUT.

10.

Call RETRN to get the next sorted output record.
records, go to step 13.

11.

Perform any desired operations upon the sorted output record.
If it is not to b€ included in the SORT-OUT file, go to step
10.

12.

Write the record onto SORT-OUT, then loop back to step 10.

13.

Close SORT-OUT.

14.

Call ENDS to clean up the sort scratch files.

If no

LINKING SORT ROUTINES WITH A COBOL PROGRAM

The actual sorting subroutines are contained in SORTS.OBJ
and
SIORMS.OBJ which are included in the COBOL object library (COBLIB).
The programmer can link these to his own calling program, by following
the usual procedure for using the TRAX Linker to link any COBOL
program.
Note that the sort subroutines use LUNs 5, 6, ... 12 for the scratch
files.
Use
the task builder device assignment
(ASG)
command
appropriately.
The LUN can be overridden by globally patching
location $RFIRL. Insure that the LUNs used by the sort subroutines do
not conflict with the LUNs assigned to files in the COBOL program that
might be open when the sort subroutines are called.

F.6

COMPARISON WITH ANS COBOL SORT VERB

Readers familiar with the ANS COBOL SORT verb will recognize that a
substantial portion of that capability has been described in this
chapter. The following points of comparison will be helpful in
converting from such usage to the described facility:
1.

INPUT PROCEDURES are available thru the CALL RELES usage.

OUTPUT PROCEDURES are available thru the CALL RETRN usage.

Only ASCENDING keys are supported. The programmer can get
the effect of DESCENDING key fields by simply complementing
them when he stores them in KEYLOC.
Note that the data
record itself is unaffected by this procedure, so restoration
of such fields after the sort is unnecessary.

F-4

SORTING FILES IN A COBOL PROGRAM

F.7

The COLLATING-SEQUENCE option is not directly available.
Again,
however,
the programmer could transform key fields
when storing them in KEYLOC to achieve the desired effect.

There is no MERGE feature.

Multiple usages of the sort may occur within a given COBOL
program provided that "RSORT" and "END" bracket each usage.

There is no restriction on the presence
addition to INPUT and OUTPUT PROCEDURES.

COBOL

code

ERROR CODES

Whenever the sort detects an error, it returns a non-zero code to the
location specified by the programmer (IERROR in discussion above).
The error codes (octal representation) and their meanings are:
DEC

OCTAL
00

No errors

Device input error

Device output error

OPEN INPUT failure

OPEN OUTPUT failure

Size of current
maximum size

Not enough work area

"RETRN" was called after it had exited with a
negative error code (end of sort).

SORT routine called out of order.
The order
of the calls must be RSORT, RELES, MERGE,
RETRN, ENDS.

Sort already in progress.
To do a second
sort, ENDS must be called to clean up the
first sort.

Key size is not positive, SORTS detected a
zero or
negative key size in its calling
parameter.

Record size not positive.

Key address not even.
The keys must start at
an even address (SORT uses word moves) .

Record address not even.

F-S

record

greater

than

SORTING FILES IN A COBOL PROGRAM
DEC

OCTAL

Scratch records will be too large. The size
of the keys plus the size of the largest
record must be less than 377776 (octal).

Too few scratch files.
A minimum
scratch files must be specified.

Too many scratch files.
A maximum
scratch files may be specified.

End-of-string record was detected where
was expected.

Like 21, but for End-of-File.

SORT found a record larger than it expected.

Record length
SORTA, SORTI.

non-standard

for

[COMP items are displayed in DECIMAL!)

F-6

none

SORTT,

APPENDIX G
DIAGNOSTIC ERROR MESSAGES

This Appendix contains a numerical listing of the diagnostic messages
generated by
the
TRAX COBOL compiler.
The general format of
presentation is to give the error message number and the text of the
diagnostic message to the left. On the right, a detailed explanation
of the diagnostic is given indicating the reason(s)
for which the
diagnostic message is issued and the recovery action taken by the
compiler.
NOTE
In many explanations, the word "Fatal."
appears as the very last sentence of the
explanation. This means that this is a
fatal diagnostic issued in the Procedure
Division.
If the /ACC:2 switch
is
specified in the command string input to
the compiler, the associated diagnostic
message will cause the generation of the
special error trap coding
discussed
previously.
001

CONTINUE PUNCH WITH BLANK
STATEMENT. IGNORED.

A blank line has a continue
punch. The continue punch is
ignored.

002

QUOTE OR CONTINUE PUNCH MISSING.
QUOTE ASSUMED.

A non-numeric literal has no
quote and the following line
has no continue punch. A
terminal quote is assumed at
the end of the line.

003

VIOLATION OF AREA A.
ASSUMED CORRECT.

The first non-blank character
on a continued line occurs in
Area A. The error is ignored.

004

LINE LENGTH EXCEEDS INPUT
BUFFER. TRUNCATED.

Continuation lines cause a
COBOL word to exceed the
capacity of the input buffer.
The word is truncated on the
right; the number of
characters retained depends
on the type of word being
processed.

G-l

DIAGNOSTIC ERROR MESSAGES
005

.10 CONTROL. WITHOUT .FILE
CONTROL.
IGNORED.

An I-O-CONTROL paragraph
appears when no FILE-CONTROL
paragraph was present. The
I-O-CONTROL paragraph is
ignored.

006

.STRING. DATA ITEM MUST HAVE
DISPLAY USAGE.

A data item in a STRING
statement has been given a
COMP or INDEX usage.
Fatal.

007

NAME EXCEEDS 30 CHARACTERS.
TRUNCATED TO 30.

A character string which
appears to be a name exceeds
30 characters in length. The
string is truncated on the
right to 30 characters.

010

NUMERIC LITERAL OVER 18
DIGITS. TRUNCATED TO 18.

A numeric literal exceeds 18
digits in length. The
literal is truncated on the
right, with any necessary
adjustment to scaling. The
sign is retained.

011

NUMERIC LITERAL HAS MULTIPLE
DECIMAL POINTS.

A numeric literal has more
than one decimal point.

012

PICTURE CLAUSE ILLEGAL ON
GROUP LEVEL.
IGNORED.

A group level item has a
PICTURE clause. The clause
is ignored.

013

.SELECT.
IGNORED.

A FILE-CONTROL statement
should begin with the word
SELECT, but does not.
All
words up to the next period
are ignored.

014

JUST.SYNC.BLANK CLAUSES
WRONG AT GROUP.
IGNORED.

A group level item may not
contain JUSTIFIED,
SYNCHRONIZED, or BLANK WHEN
ZERO clauses. The clause is
ignored.

015

FILENAME MISSING OR
INVALID. SELECT IGNORED.

A SELECT statement either
contains no user name or the
the user name is invalid. The
SELECT statement is ignored.

016

USAGE CONFLICTS WITH GROUP
USAGE.
USES GROUP.

The usage specified for this
item differs from the usage
stated at a higher group
level. The group level usage
is used.

017

ILLEGAL NUMERIC DATANAME
IN .STRING.

A numeric data item in a
STRING statement has an
illegal description.
Fatal.

020

.ALL.
ILLEGAL IN CONTEXT OF
• STRING. STATEMENT.

An ALL literal has been used
in a STRING statement. Fatal •

NOT FOUND.

SENTENCE

G-2

DIAGNOSTIC ERROR MESSAGES
021

SYNTAX ERROR OR NO
TERMINATOR. CLAUSES SKIPPED.

A SELECT statement is missing
its terminating period or an
error causes the statement to
be processed before all
clauses were found. The
SELECT statement is ignored.

022

NUMERIC LITERAL ILLEGAL
IN THIS STATEMENT.

A STRING, UNSTRING, or
INSPECT statement contains a
numeric literal. Fatal.

023

SENDING LIST OMITTED IN
.STRING. STATEMENT.

A STRING statement contains
no sending fields before a
DELIMITED BY phrase. Fatal.

024

MORE THAN ONE FILENAME
IN .ASSIGN.

The non-numeric literal of an
ASSIGN clause contains more
than one file specification.
Only the first specification
is used.

025

ILLEGAL DATANAME FOLLOWS
. INTO. IN .STRING.

The receiving field of a
STRING statement is invalid .
Fatal.

026

SUBSCRIPTING DEPTH EXCEEDS
3. OVER 3 IGNORED.

This OCCURS clause is nested
more than three deep. The
OCCURS clause is ignored.

027

VALUE
ITEM.

ILLEGAL IN OCCURS
IGNORED.

A VALUE clause appears in an
item with an OCCURS clause or
in an item subordinate to an
OCCURS clause. The VALUE
clause is ignored.

030

VALUE ILLEGAL IN
REDEFINES ITEM.
IGNORED.

A VALUE clause appears in an
item which either contains a
REDEFINES clause, or is
subordinate to an item with a
REDEFINES clause.

031

NO TERMINATOR FOR .10
CONTROL. PARAGRAPH.

The I-O-CONTROL paragraph is
not terminated by a period.
The terminator is assumed
present.

032

.MAP. NO LONGER APPLICABLE.
IGNORED.

An APPLY clause with the MAP
option is not applicable for
this version and future
versions of TRAX COBOL. The
APPLY clause is ignored.

033

AN 10 CONTROL CLAUSE
WITHOUT FILES.

A file-name is missing in a
clause of the I-O-CONTROL
paragraph. The clause is
ignored.

034

SYNTAX ERROR IN .APPLY ..

An APPLY clause has illegal
syntax. The clause is
ignored.

G-3

DIAGNOSTIC ERROR MESSAGES
035

INVALID ACCESS MODE.
TREAT AS SEQUENTIAL.

The SELECT statement contains
an invalid ACCESS mode.
SEQUENTIAL ACCESS mode is
assumed.

036

INVALID FILE ORGANIZATION.
TREAT AS SEQUENTIAL.

THE SELECT statement contains
an invalid ORGANIZATION
specification. SEQUENTIAL
organization is assumed.

037

NO SELECT STATEMENTS.

A FILE-CONTROL paragraph
either contains no SELECT
statements or none of those
present are valid. The
FILE-CONTROL paragraph is
ignored.

040

.ASSIGN. OMITTED FROM
SELECT. SELECT IGNORED.

A SELECT statement contains
no ASSIGN clause. The SELECT
statement is ignored.

041

DECIMAL PLACES TRUNCATED.

Decimal places have been
truncated from a numeric
literal during conversion for
use as an integer. The
integer positions are used.

042

INTEGER EXPECTED, ZERO
ASSUMED.

An integer literal was
expected but fractional
positions were found.
The
literal is ignored and a
value of zero is assumed.

043

INTEGER VALUE TOO BIG.
LARGEST VALUE USED.

A numeric literal is too big
for conversion as an integer
in the given context. A
value of 32,767 is used.

044

ERROR IN DATA RECORDS
CLAUSE. CLAUSE SKIPPED.

The word DATA is not followed
by RECORD or RECORDS in the
DATA RECORDS clause. The
DATA RECORDS clause is
ignored.

045

ERROR IN LABEL RECORDS
CLAUSE. CLAUSE SKIPPED.

The word LABEL is not
followed by RECORD or RECORDS
in the LABEL RECORDS clause.
The LABEL RECORDS clause is
ignored.

046

NO INTEGER IN BLOCK
CLAUSE. CLAUSE SKIPPED.

The BLOCK clause does not
contain a numeric literal.
The BLOCK clause is ignored.

047

BAD VALUE IN BLOCK
CLAUSE. CLAUSE SKIPPED.

The numeric literal in the
BLOCK clause causes an
illegal block size. The block
size in bytes must be greater
than 0 and less than 32768.
The BLOCK clause is ignored.

050

NO INTEGER IN RECORD
CLAUSE. CLAUSE SKIPPED.

The RECORD CONTAINS clause
does not contain a numeric
literal. The RECORD CONTAINS
clause is ignored.
G-4

DIAGNOSTIC ERROR MESSAGES

051

INVALID VALUE IN RECORD
CLAUSE. CLAUSE SKIPPED.

The numeric literal in the
RECORD CONTAINS clause is not
greater than zero. The
RECORD CONTAINS clause is
ignored.

052

INVALID FILENAME.
FD SKIPPED.

The word following FD is not
valid as a file-name. The
FD entry is ignored.

053

FD TERMINATOR MISSING.
ASSUMED PRESENT.

The file description entry
contains no period
terminator. The error is
ignored.

054

KEY WORD EXPECTED.
REMAINING CLAUSES SKIPPED.

A keyword, which begins a
clause, such as BLOCK, LABEL,
DATA, etc. is missing. The
remainder of the FD entry is
ignored.

055

NO LABEL CLAUSE IN FD.
. STANDARD. ASSUMED.

The FD entry contains no
LABEL RECORD clause. LABEL
RECORD IS STANDARD is assumed.

056

NO SELECT. FILE
DELETED.

The FD entry's file-name has
no corresponding SELECT
statement. The FD entry is
ignored. All references to
the filename will be
diagnosed as undefined.

057

ALLOCATED SPACE EXCEEDS
LARGEST RECORD.

The maximum record size
specified by the RECORD
CONTAINS clause exceeds the
space required for any 01
entry under the same file.
The value specified by the
RECORD CONTAINS clause is
used.

060

RECORD AREA EXTENDED TO
CONTAIN LARGEST RECORD.

The space required by the
largest 01 record under a
file description exceeds the
space required by the RECORD
CONTAINS clause in the FD
entry. The value derived
from the 01 record
description is used.

061

NO RECORD AREA.
DELETED.

No record area is allocated
for a file description. The
file description is ignored.
All references to the file
will be diagnosed as
undefined.

062

ILLEGAL DATANAME FOLLOWS
.WITH POINTER. PHRASE.

The data item used as a
pointer in a STRING or
UNSTRING statement is
illegal. Fatal.

063

ILLEGAL SYNTAX IN .STRING.
STATEMENT.

A STRING statement contains
illegal syntax. Fatal.

FILE

G-S

DIAGNOSTIC ERROR MESSAGES
064

77 ILLEGAL IN FILESECTION.
CHANGED TO 01.

A 77 level item description
has been found in the FILE
SECTION. The 77 level is
treated as an 01 level.

065

ILLEGAL WORD FOLLOWS
.DELIMITED BY. PHRASE.

A data-name or literal is
expected following a
DELIMITED BY phrase in a
STRING or UNSTRING statement.
Fatal.

066

ILLEGAL USE OF .ALL ..
IGNORED.

In the VALUE clause, an ALL
numeric literal is detected.
This is illegal. ALL is
ignored by the compiler.

067

CONDITION NAME MISSING OR
INVALID. 88 IGNORED.

The condition-name in an 88
level entry is either missing
or invalid. The entire entry
is ignored.

070

TWO INDEXED KEYS START AT
SAME OFFSET IN RECORD

The leftmost character
position of the RECORD KEY or
ALTERNATE RECORD KEY dataname
corresponds to the leftmost
character position of some
other RECORD KEY or ALTERNATE
RECORD KEY data-name. The
clause is ignored.

071

.REDEFINES. ON 01 LEVEL
IN FILE SECTION INVALID.

The REDEFINES clause is
present on the 01 level
in the FILE SECTION, where
redefinition is implicit.
REDEFINES clause is ignored.

072

PICTURE IGNORED
FOR INDEX ITEM.

An item defined as USAGE
INDEX has a PICTURE clause.
The PICTURE clause is
is ignored.

073

NONNUMERIC PIC ON COMP
ITEM. TREATED AS DISPLAY.

An item defined as USAGE COMP
has a picture-string with
non-numeric characters. The
stated usage is ignored. The
item is treated as USAGE
DISPLAY.

074

SUBSCRIPT OUT OF RANGE.
ASSUME 1.

A literal subscript is either
less than 1 or greater than
the maximum allowable value.
A value of 1 is used.

075

.STATUS. OMITTED FROM
.FILE STATUS •. ASSUMED.

The FILE STATUS clause has
incorrect syntax. The error
is ignored.

076

SOME FILES WITHOUT POSIT.
NO. IN MUL. FILE TAPE.

A MULTIPLE FILE TAPE clause
contains file-names with
POSITION Clauses. Not all
the file-names contain
POSITION clauses. The error
is ignored. File searching
during OPEN will find the
file.
G-6

DIAGNOSTIC ERROR MESSAGES
077

.MULTIPLE FILE TAPE.
ERROR.

SYNTAX

A MULTIPLE FILE TAPE clause
contains a syntax error. The
clause is ignored.

100

OPERAND CLASSES IN CONFLICT.

One or more operands in a
statement have invalid class.
Fatal.

101

POSSIBLE RECEIVING
FIELD TRUNCATION.

A MOVE statement results
in right hand truncation of
the receiving field value.
This is not an error and is
ignored.

102

TOO FEW SOURCE FIELDS
FOR ADD .GIVING •.

At least two valid source
operands must appear in an
ADD ... GIVING statement.
Fatal.

103

.EXIT. WAS NOT THE ONLY
VERB IN PARAGRAPH.

An EXIT statement is not
only statement in a
paragraph. The EXIT
statement is ignored.

104

SENDING ITEM INVALID
OR OMITTED.

A MOVE statement contains
an invalid or missing
sending operand. Fatal.

105

SENDING ITEM NOT FOLLOWED
BY .TO ..

A MOVE statement does not
have a TO following the
sending operand. Fatal.

106

RECEIVING ITEM INVALID
OMITTED.

A MOVE statement has no valid
receiving operand. Fatal.

107

INVALID CLASS FOR
DESTINATION FIELD.

The receiving operand of an
ADD or SUBTRACT statement is
not numeric or numericedited. Fatal.

110

RELATIVE OR RECORD KEY OR STATUS
NAME INVALID.

The name referenced in a
RELATIVE KEY, RECORD KEY,
ALTERNATE RECORD KEY or
FILE STATUS clause is invalid.
The clause is ignored.

III

.STOP.

The STOP statement is not
followed by a literal or
the word RUN.
Fatal.

112

.SIZE ERROR.
INCORRECT.

113

.PROCEDURE DIVISION.

OMITTED.

The source program does not
contain a PROCEDURE DIVISION.
Fatal.

114

INTERMEDIATE RESULT TOO LARGE.
HIGH ORDER TRUNC.

An arithmetic statement calls
for an intermediate result in
excess of 18 digits.
The intermediate result is
truncated on the left to 18
digits with a possible loss
of high order non-zero digits
at execution time.

SYNTAX ERROR.

the

The word ERROR is not found
in ON SIZE clause. Fatal.

STATEMENT

G-7

DIAGNOSTIC ERROR MESSAGES
115

INTERMEDIATE RESULT TOO
LARGE. LOW ORDER TRUNC.

An arithmetic expression
calls for an intermediate
result in excess of 18
digits. The intermediate
result is truncated on the
right to 18 digits with a
possible loss of low order
non-zero digits at execution
time.

116

.DIVISION. OMITTED AFTER
.PROCEDURE ..

The word DIVISION is missing
in the PROCEDURE DIVISION
header. The error is
ignored.

117

TERMINATOR MISSING AFTER
DIVISION HEADER.

The period terminator is
missing from a division
header. The error is
ignored.

120

LITERAL INCOMPATIBLE WITH
ATTEMPTED USAGE.

Conversion of a literal
from one form to another
has failed. Fatal.

121

DATANAME MUST FOLLOW .INTO.
IN THIS STATEMENT.

A valid data-name is not
present following INTO in
a STRING or UNSTRING
statement. Fatal.

122

NUMERIC SUBJECT OR OBJECT
MUST BE INTEGER.

A numeric, non-integer
subject or object is invalid
in the context of this
relation condition.
Fatal.

123

OPERANDS CONFLICT IN .SET .•.

A SET ... TO statement
TO. STATEMENT. references
invalid operands.
Fatal.

124

OPERANDS CONFLICT IN .SET ...
BY. STATEMENT.

A SET ... BY statement
references invalid operands.
Fatal.

125

ILLEGAL FILENAME LITERAL
OR FILENAME DATANAME.

An ASSIGN statement or a
VALUE OF 10 statement
contains an invalid file
specification or data-name.
The statement is ignored.

126

INVALID SUBJECT OF
SIGN CONDITION.

The subject of a sign
condition is not a valid
arithmetic expression.
Fatal.

127

ITEM IN TABLE MAY NOT
BE USED AS A SUBSCRIPT.

A data item used as a
subscript is itself a table
element. Fatal.

130

.POINTER. MUST FOLLOW .WITH.
IN THIS STATEMENT.

A STRING or UNSTRING
statement has an invalid
WITH POINTER phrase.
Fatal.

131

RELATIVE KEY INVALID FOR
THIS FILE. IGNORED.

A RELATIVE KEY clause has
been applied to a file which

G-8

DIAGNOSTIC ERROR MESSAGES
does not have RELATIVE
organization.
The RELATIVE KEY clause is
ignored.
132

SUBJECT OR OBJECT OMITTED IN
RELATION CONDITION.

The subject or object is
omitted in a COBOL relation
condition. The condition
expression is considered
syntactically invalid. Fatal.

133

UNIDENTIFIABLE WORD FOUND IN
SUBSCRIPT.

A subscript list contains
a word which is neither a
data-name or numeric literal.
The remainder of the list or
sentence is ignored.
Fatal.

134

INVALID SUBJECT OR OBJECT IN
RELATION CONDITION.

The subject or object of a
relation condition is an
invalid operand. Fatal.

135

SUBSCRIPTS OMITTED.
VALUE OF 1.

ASSUME

A reference to a table item
contains no subscript list.
Literal subscripts of 1 are
supplied as defaults.

136

RELATIVE INDEX LITERAL OUT
OF
RANGE. INDEX USED.

The literal value of a
relative index causes an
out of range reference
to the table. The literal
value is ignored, and the
index-name only is used.

137

SUBSCRIPTS GIVEN WHERE NOT
REQUIRED.
IGNORED.

A reference is made to
a non-table item, and a
subscript list follows the
reference. The subscript
list is ignored.

140

TOO FEW SUBSCRIPTS GIVEN.
ASSUME 1 FOR REST.

A reference to a table item
contains a subscript list
with too few subscripts.
Default literal subscripts of
1 are supplied for missing
subscripts.

141

TOO MANY SUBSCRIPTS
GIVEN. IGNORE EXCESS.

A reference to a table item
contains too many subscripts
in the subscript list. Extra
subscripts are ignored.

142

SUBJECT AND OBJECT USAGE
MUST MATCH.

A relation condition between
non-numeric operands requires
the same usage for both
operands. Fatal.

143

ARITHMETIC EXPRESSION
REQUIRED IN THIS CONTEXT.

An arithmetic expression is
required in the context of
the COBOL statement being
compiled. The compiler has
failed to recognize the
arithmetic expression in this
context. Fatal.
G-9

DIAGNOSTIC ERROR MESSAGES
144

CONDITION EXPRESSION REQUIRED
IN THIS CONTEXT.

A condition expression is
required in the context of
the COBOL statement being
compiled. The compiler has
failed to recognize the
condition expression in this
context. Fatal.

145

ILLEGAL OPERAND FOUND IN
COBOL EXPRESSION.

An invalid data-name or
literal has been found in the
COBOL statement being
compiled. The class or USAGE
of the data item may be
invalid in the context as a
reference in an expression.
Fatal.

146

OPERATOR IS MISSING IN COBOL
EXPRESSION.

An operator is omitted in the
specification of this COBOL
expression. The compiler
cannot recognize this
expression as a syntactically
valid COBOL expression.
Fatal.

147

ABSOLUTE VALUE STORED.

A negative value has been
supplied for an unsigned
numeric item. The absolute
value of the numeric literal
is stored in the item.

150

ILLEGAL WORD FOUND AFTER
.NOT. IN EXPRESSION.

The compiler has detected an
illegal expression operator
following a NOT keyword in
the COBOL expression being
compiled. The COBOL
expression is considered
syntactically invalid. Fatal.

151

VERB FOUND IN AREA A.
ALLOWED.

A statement begins in
Area A. The error is ignored.

152

EXPECTED .RELATIVE KEY.
DATANAME NOT DEFINED.

The data-name given in a
RELATIVE KEY clause has not
been defined in the Data
Division.

153

.LINAGE. CLAUSE DATAITEM
IS TOO LONG.

A data item named in a LINAGE
clause is declared in the
Data Division with more than
four decimal integer
positions of precision.

154

PROCEDURE NAME DUPLICATES
DATA NAME. ALLOWED.

A procedure name is identical
to a data-name. The error is
ignored, since there can be
no ambiguity in legal
references.

155

STATEMENTS FOLLOWING .GO.
CAN NEVER BE EXECUTED.

A statement follows an
unconditional GO statement.
The statements following the
GO are compiled, but can
not be executed.
G-IO

DIAGNOSTIC ERROR MESSAGES
156

NONSEQUENTIAL FILE MAY
NOT BE OPTIONAL.

The SELECT statement may
specify OPTIONAL only on
files with sequential
organization. The word
OPTIONAL is ignored.

157

FILE HAS 10 CONTROL
CLAUSE CONFLICTS.

A file is given conflicting
clause specifications in the
I-O-CONTROL paragraph of the
INPUT-OUTPUT SECTION.

160

FILE REQUIRES REL. KEY.
TREATED AS SEQ. ACCESS.

A file with relative
organization and random
or dynamic access has no
RELATIVE KEY clause. The
access mode is changed to
SEQUENTIAL.

161

INVALID INDEX DATAITEM USE IN
RELATIONAL.

The compiler detects the
invalid use of an index data
item reference as the subject
or object of a relation
condition. Fatal.

162

UNKNOWN WORD.
NEXT CLAUSE.

An unknown word is
encountered when a clause
keyword is expected. All
words are ignored up to the
next valid clause.

163

CLAUSE DUPLICATED.
OCCURRENCE USED.

164

NO FD FOR THIS SELECT.

The file-name supplied in a
SELECT statement is not
further described in an fD
in the Data Division. The
SELECT statement is ignored,
causing the filename to
become undefined.

165

DIFFERENT SAME REC. AREAS
FOR SAME AREA.

The compiler detects a
conflict between the SAME
RECORD AREA clause and the
SAME AREA clause.

166

.READ. WITHOUT .INVALID KEY.
.AT END. OR .USE.

A READ statement contains
no conditional clauses and
the file being read has no
USE procedure applied to it.
Fatal.

167

10 CONTROL CLAUSE HAS FILE
WITH NO .SELECT.

An I-O-CONTROL clause
references a file-name which
was not named in a SELECT
statement. The file-name is
ignored in the I-O-CONTROL
statement.

170

INTEGER OMITTED IN
.RESERVE •• DEFAULT ASSUMED.

A RESERVE clause fails
to specify the number of
buffer areas to reserve.

SCAN TO

SECOND

A SELECT statement contains
two occurrences of the same
clause. The second
occurrence is used.

G-ll

The

DIAGNOSTIC ERROR MESSAGES
clause is ignored, and a
default of one area for
SEQUENTIAL and RELATIVE or two
areas for INDEXED is supplied.
171

INVALID SUBJECT OF CLASS
CONDITION.

The subject of a class
condition is not a data
item with acceptable class.
Fatal.

172

VALUE EXCEEDS FIELD CAPACITY.
TRUNCATED.

A numeric literal supplied
by a VALUE clause exceeds the
length of the field. The
value is right truncated and
stored in the field.

173

NO DATA DIVISION STATEMENTS
PROCESSED.

The Data Division contains
no valid entries. This
is an observation only.

174

INVALID GRP LEV NUM.
REST OF RECORD IGNORED.

A level-number is encountered
which terminates a previous
group item, but does not
match any previous group
item's level-number. All
data entries are skipped
until the next 01 level,
level indicator or header.

175

INVALID PROCEDURE NAME
DEFINITION IN AREA A.

The compiler detects source
text in Area A of the
Procedure Division which does
not conform to the rules for
the definition of a
legitimate paragraph or
section name. Source text
found in Area A of the
Procedure Division is
interpreted by the compiler
as a user attempt to define a
new paragraph or section
name. The compiler supplies a
system-defined procedure name
and proceeds with the
processing of the source line
text containing the invalid
Area A text. The systemdefined procedure name is
transparent and, thus,
inaccessible to the user.

176

MISSING QUOTE ON CONTINUE
LINE. QUOTE ASSUMED.

A non-numeric literal is
continued, but the first
non-space character is not a
quote. The error is ignored
by assuming a quote in front
of the first non-space
character.

177

COMPARISON OF LITERALS IS
NOT PERMITTED.

A relation condition has
a literal as both subject and
object. Fatal.

G-12

DIAGNOSTIC ERROR MESSAGES
200

COpy IGNORED WITHIN
LIBRARY TEXT.

A COPY statement is
encountered within library
text. The COpy statement
is ignored.

201

INVALID FILENAME ON COPY.
COpy IGNORED.

A COpy statement supplies
a file specification which
is invalid. The COpy
statement is ignored.

202

COpy FILENAME NOT FOUND.

A COPY statement supplies
a valid file specification,
but the file cannot be found
on the specified device. The
COPY statement is ignored.

203

PERIOD OMITTED AFTER
.DECLARATIVES ..

The word DECLARATIVES is not
followed by a period. The
error is ignored.

204

.DECLARATIVES. OMITTED FROM
. END. STATEMENT •

The word END is not followed
by DECLARATIVES. END
DECLARATIVES is assumed.

205

PERIOD OMITTED AFTER
. END DECLARATIVES ..

The words END DECLARATIVES
.are not followed by a period .
The error is ignored.

206

SOURCE PROGRAM ENDS IN
DECLARATIVES.

The end of the source program
occurs in the Declaratives
area.
Fatal.

207

DATANAME MUST FOLLOW
.WITH POINTER. PHRASE.

A STRING or UNSTRING
statement contains an invalid
WITH POINTER phrase. Fatal.

210

.OVERFLOW. MUST FOLLOW .ON.
IN THIS STATEMENT.

A STRING or UNSTRING
statement contains an invalid
ON OVERFLOW phrase.
Fatal.

211

ILLEGAL SENDING FIELD
DATANAME IN .UNSTRING.

The sending field of an
UNSTRING statement has
invalid class. Fatal.

212

ILLEGAL SYNTAX IN
. UNSTRING. STATEMENT .

An UNSTRING statement
has invalid syntax. Fatal.

213

MULTIPLE SIGN
ON THIS I'rEM.

CLAUSES

More than one SIGN clause
appears in a data
descr iption.
(SEPARATE must
follow LEADING or TRAILING.) .
The second clause is used.

214

ILLEGAL SYNTAX IN COBOL
EXPRESSION.

The compiler detects a syntax
error of a general nature in
the COBOL expression being
compiled. Fatal.

215

SIGN CLAUSE ON
NONNUMERIC ITEM.

A SIGN clause appears in
a non-numeric data
description. The SIGN clause
is ignored.

G-13

DIAGNOSTIC ERROR MESSAGES
216

SIGN CLAUSE APPLIED
TO NONDISPLAY ITEM.

A SIGN clause appears in
a numeric data description
with usage other than
DISPLAY. The SIGN clause is
ignored.

217

SIGN CLAUSE APPLIED
TO UNSIGNED DATAITEM.

A SIGN clause appears in a
numeric data description
which has no "S" in its
PICTURE string. The SIGN
clause is ignored.

220

ILLEGAL DELIMITING DATA
ITEM IN .UNSTRING.

An UNSTRING statement
references an invalid
delimiter. Fatal.

221

.ALL. FIGURATIVE CONSTANT
ILLEGAL IN .UNSTRING.

An UNSTRING statement
contains an ALL literal
reference.
Fatal.

222

ILLEGAL RECEIVING DATANAME
IN .UNSTRING.

An UNSTRING statement
references a receiving data
item which is invalid.
Fatal.

223

.DELIMITED. CLAUSE REQUIRED
IN THIS .UNSTRING.

An UNSTRING statement
contains no DELIMITED BY
clause. Fatal.

224

DATANAME MUST FOLLOW
.DELIMITER IN. PHRASE.

An UNSTRING statement
contains a DELIMITER
IN phrase with an illegal
reference.
Fatal.

225

ILLEGAL DATANAME FOLLOWS
.DELIMITER IN. PHRASE.

An UNSTRING statement
contains a DELIMITER IN
phrase referencing a data
item which is invalid.
Fatal.

226

DATANAME MUST FOLLOW
.COUNT IN. PHRASE.

An UNSTRING statement
contains a COUNT IN phrase
with an illegal reference.
Fatal.

227

ILLEGAL DATANAME FOLLOWS
.COUNT IN. PHRASE.

An UNSTRING statement
contains a COUNT IN phrase
which references a data item
which is invalid. Fatal.

230

DATANAME MUST FOLLOW
.TALLYING IN. PHRASE.

An UNSTRING statement
contains a TALLYING phrase
with an illegal reference.
Fatal.

231

ILLEGAL DATANAME FOLLOWS
.TALLYING IN. PHRASE.

An UNSTRING statement
contains a TALLYING
phrase referencing a data
item which is invalid.
Fatal.

232

DATANAME MUST FOLLOW
.INSPECT. VERB.

A valid data-name reference
does not follow the INSPECT
keyword. Fatal.
G-14

DIAGNOSTIC ERROR MESSAGES

233

ILLEGAL DATANAME FOLLOWS
.INSPECT. VERB.

An INSPECT statement
references a data item
which is invalid. Fatal.

234

ILLEGAL DATANAME PRECEDES
.FOR. IN .INSPECT.

An INSPECT ... TALLYING
statement references a tally
data item which is invalid.
Fatal.

235

.FOR. OMITTED IN
. INSPECT. STATEMENT

An INSPECT ... TALLYING
statement has invalid syntax .
Fatal.

236

DATANAME MUST FOLLOW
.TALLYING. PHRASE.

An INSPECT ... TALLYING
statement does not reference
a tally data-name.
Fatal.

237

ILLEGAL WORD FOLLOWS
.FOR. IN .INSPECT.

An INSPECT ... TALLYING
statement does not state
a valid search condition.
Fatal.

240

DATAITEM OMITTED AFTER
.ALL . . LEADING. OR .FIRST.

An INSPECT statement
does not reference a
valid search argument.
Fatal.

241

.ALL. FIGURATIVE CONSTANT
ILLEGAL IN .INSPECT.

An ALL literal appears in an
INSPECT statement. Fatal.

242

ILLEGAL DATANAME FOLLOWS
.ALL. OR .LEADING.

An INSPECT statement
does not reference a
valid search argument.
Fatal.

243

ILLEGAL DATANAME FOLLOWS
.BEFORE. OR .AFTER.

An INSPECT statement does
not reference a valid
delimiter in the BEFORE/
AFTER phrase. Fatal.

244

ILLEGAL DATANAME FOLLOWS
.BY.

An INSPECT statement
does not reference a valid
replacement argument. Fatal.

245

ILLEGAL DATANAME PRECEDES
.BY.

An INSPECT statement does not
reference a legal data-name
or literal preceding the
BY phrase. Fatal.

246

DATAITEM OMITTED IN
.BEFORE. OR .AFTER. PHRASE.

An INSPECT statement does
not reference a legal dataname or literal after the
BEFORE or AFTER phrase.
Fatal.

247

ILLEGAL SYNTAX IN
.INSPECT. STATEMENT.

Both the TALLYING and
REPLACING keywords are
missing in the INSPECT
statement.
Fatal.

250

.BY. MUST FOLLOW .CHARACTERS.
IN REPLACING LIST.

The INSPECT ... REPLACING
statement must have
CHARACTERS BY phrase
completely specified. Fatal.

G-15

DIAGNOSTIC ERROR MESSAGES
251

DATAITEM OMITTED AFTER
.BY. IN .INSPECT.

The INSPECT ... REPLACING
statement does not reference
a legal data-name or literal
after BY.
Fatal.

252

DATAITEM FOLLOWING .BY.
EXCEEDS 1 CHARACTER.

In an INSPECT ... REPLACING
statement, either when the
CHARACTERS BY phrase is
specified or when a
figurative constant preceding
the BY keyword of the ALL,
LEADING, or FIRST phrase is
specified, the data-name or
literal after the BY keyword
must be defined as one
character in length.
Fatal.

253

DATAITEMS BEFORE AND AFTER
.BY. UNEQUAL IN SIZE.

In an INSPECT ... REPLACING
statement, the data items
before and after the BY
keyword of the ALL, LEADING,
or FIRST phrase must be equal
in length.
Fatal.

254

.BEFORE. OR .AFTER. OPERAND
EXCEEDS 1 CHARACTER.

In an INSPECT ... REPLACING
CHARACTERS BY statement, the
data-name or literal following the BEFORE or AFTER
keyword must be one character
in length.
Fatal.

255

ILLEGAL WORD FOLLOWS
.REPLACING. IN INSPECT ..

A legal keyword was not
recognized following
REPLACING in the INSPECT
statement.
Fatal.

256

.BY. OMITTED AFTER REPLACING
COMPARISON OPERAND.

The keyword BY is omitted in
the ALL, LEADING, or FIRST
phrase where it separates
operands to be compared.
Fatal.

257

TOO MANY RIGHT PARENTHESES IN
COBOL EXPRESSION.

The compiler detects an
excess of right parentheses
in the COBOL expression being
compiled. Parentheses must be
specified in balanced pairs
i.e., a left parenthesis for
each right parenthesis specified. This COBOL expression
is considered syntactically
incorrect. Fatal.

260

TOO MANY LEFT PARENTHESES IN
COBOL EXPRESSION.

The compiler detects an
excess of left parentheses in
the COBOL expression being
compiled. Parentheses must
be specified in balanced
pairs i.e., a right parenthesis for each left parenthesis specified. This COBOL
expression is considered syntactically incorrect. Fatal.

G-16

DIAGNOSTIC ERROR MESSAGES

261

MISSING OPERAND IN ARITHMETIC
EXPRESSION.

An operand is omitted in a
COBOL arithmetic expression.
The COBOL expression is considered syntactically invalid. Fatal.

262

ILLEGAL OPERAND IN ARITHMETIC
EXPRESSION.

The compiler detects an
illegal operand in a COBOL
arithmetic expression. The
class or usage of the operand
may be invalid in the context
as a reference in an arithmetic expression. Fatal.

263

NONINTEGER EXPONENT FOUND IN
COBOL EXPRESSION.

The compiler detects a
non-integer, numeric exponent
in a COBOL arithmetic
expression. The arithmetic
expression is considered
invalid. Fatal.

264

SUBJECT OMITTED IN
CLASS CONDITION.

The compiler detects the
omission of the subject in a
NUMERIC or ALPHABETIC class
condition. The class
condition is considered
syntactically invalid. Fatal.

265

SUBJECT OMITTED IN SIGN
CONDITION.

The compiler detects the
omission of the subject in a
sign condition. The sign
condition is considered
syntactically invalid.
Fatal.

266

OPERAND MISSING IN
COMPLEX CONDITION.

The compiler detects the
omission of an operand in an
AND or OR complex condition.
The COBOL condition
expression. is considered
syntactically invalid. Fatal.

267

INVALID OPERAND IN
COMPLEX EXPRESSION.

The compiler detects a
complex condition operand
which, in turn, is neither a
simple condition, combined
condition, nor a complex
condition. Fatal.

270

ILLEGAL SYNTAX IN NEGATED
SIMPLE CONDITION.

The compiler detects illegal
syntax in a COBOL negated
simple condition. Fatal.

271

INVALID NEGATED SIMPLE
CONDITION.

The compiler detects the
application of the NOT
keyword to an invalid simple
condition. Fatal.

272

ILLEGAL SYNTAX IN
COMPUTE. STATEMENT.

The compiler detects illegal
syntax in a COMPUTE
statement. The left side of
the assignment symbol, or
the assignment symbol itself
may have been omitted. Fatal.
G-17

DIAGNOSTIC ERROR MESSAGES
273

.AT END. ILLEGAL FOR
RANDOM .READ

Either the file has ACCESS
RANDOM or DYNAMIC without the
word NEXT being included in
the READ statement. In either
case, the AT END clause is
illegal and is treated as an
INVALID KEY clause.

274

INVALID KEY ILLEGAL FOR
SEQUENTIAL .READ.

Either the file has ACCESS
SEQUENTIAL or the READ
statement contains the word
NEXT. In either case, the
INVALID KEY clause is illegal.
It is treated as an AT END
clause.

275

INDEX DATA ITEM ILLEGAL
AS INDEX ON TABLE.

An index data item is used as
an index on a table. The
index data item reference is
ignored. A literal subscript
of 1 replaces the index
data item reference.

276

INDEX NAME NOT DEFINED
FOR THIS TABLE.

An index-name used in a subscript list either is not
defined for this table or
appears in the wrong logical
position of the subscript
list for this table. The
index-name is ignored and a
default value of 1 is assumed
as the subscript.

277

RELATIVE INDEX IS INVALID.

The literal component of a
relative index is zero or
less in value or is an
invalid word.
Relative
indexing is ignored and the
index-name only is used.

300

PROGRAM NAME OMITTED
AFTER .CALL. VERB

The program-name is omitted
after the key word CALL in
a CALL statement. This is
syntactically invalid.
Fatal.

301

LINAGE 0 OR LESS
THAN FOOTING.

The LINAGE clause must
specify a page body of at
least one line and that page
body size must be equal to or
greater than the footing size
specified in the FOOTING
phrase.

302

FILE CLOSED BUT NOT
OPENED.

A CLOSE statement was seen
for a file that was not
OPENed in this program.
Fatal.

303

PRINT CONTROL ON NON SEQUENTIAL
FILE.
IGNORED.

An APPLY PRINT-CONTROL clause
references a file which does
not have SEQUENTIAL
organization. The file-name
is ignored in the APPLY
clause.

G-l8

DIAGNOSTIC ERROR MESSAGES
304

DATANAME OMITTED IN .KEY
IS. PHRASE.

The KEY IS phrase of the START
statement is not followed by a
data-name. The prime RECORD
KEY data-name is assumed
present.

305

SECTION OR PARAGRAPH
NAME MISSING.

The Procedure Division does
not start with a section or
paragraph name or a section
header is not followed by a
paragraph name. Fatal.

306

.PROCEDURE. MISSING IN .USE.
STATEMENT. ASSUMED.

The keyword PROCEDURE is
missing in the USE
statement. It is assumed and
processing is continued.

307

.START. WITHOUT .INVALID
KEY. OR .USE.

The INVALID KEY option is
missing from the START
statement or no USE procedure is declared for the
referenced file.
Fatal.

310

.WRITE. WITHOUT .INVALID
KEY. OR .USE.

THE INVALID KEY option
is missing from the WRITE
statement or no USE
procedure is declared for
the referenced file.
Fatal.

311

DATA DIVISION MUCH TOO
LARGE.

Too much buffer space is
being used for the
files in this program. Too
many files are declared to be
OPEN simultaneously. Fatal.

312

.REDEFINES. SPECIFIES INVALID
REDEFINITION.

The compiler detects the
invalid application of
REDEFINES to a data
description entry which
contributes new character
positions between the data
description entry containing the REDEFINES clause
and the item being redefined.
Also, the source of error may
be the definition of another
data description entry with a
lower level number appearing
between the data description
entry containing the
REDEFINES clause and the item
being redefined. The compiler
ignores the REDEFINES clause
and continues processing the
data description entry.

313

ILLEGAL TO REDEFINE ANOTHER
REDEFINITION.

The REDEFINES clause specifies the redefinition of a
data item whose data
description entry contains a
REDEFINES clause itself. This
is syntactically invalid. The
compiler ignores the
REDEFINES clause and continues
G-19

DIAGNOSTIC ERROR MESSAGES
processing of the data
description entry.
314

ILLEGAL TO REDEFINE A
COBOL TABLE.

The REDEFINES clause specifies the redefinition of a
data item whose data description entry contains an OCCURS
clause. This is syntactically
invalid. The compiler ignores
the REDEFINES clause and
continues processing of the
data description entry.

315

.REDEFINES. APPLIED TO
VARIABLE LENGTH DATAITEM.

The compiler detects an
application of the REDEFINES
clause to a data item whose
length is variable at runtime. This data item is
variable in length because it
has a subordinate data item
whose data description entry
contains an OCCURS DEPENDING
ON clause. The application of
the REDEFINES clause to such
a data item is syntactically
invalid. The compiler ignores
the REDEFINES clause and
continues processing of the
data description entry.

316

.OCCURS DEPENDING ON. ILLEGAL
IN REDEFINITION.

The compiler detects a
redefinition which contains a
data description entry
declared with an OCCURS
DEPENDING ON clause. The
OCCURS DEPENDING ON clause
causes the redefinition to
contain a data item whose
length is variable at runtime. This is syntactically
invalid. The DEPENDING ON
phrase is ignored and processing continues.

317

PICTURE EXCEEDS 30
CHARACTERS. PIC X ASSUMED.

The unexpanded PICTURE string
exceeds 30 characters in
length. This is syntactically
invalid. The compiler ignores
the user-supplied PICTURE
and declares the data-name
alphanumeric with a
"PICTURE X" declaration.

320

FILENAME MUST FOLLOW .CLOSE
VERB.

The data item following the
CLOSE verb was not a filename.
Fatal.

321

.NO. MUST FOLLOW .WITH.
IT IS ASSUMED.

The keyword NO is missing in
the WITH NO REWIND phrase of
the CLOSE statement. NO is
assumed present.

322

.REWIND. MUST FOLLOW .NO.
IT IS ASSUMED.

The WITH NO REWIND phrase of
the CLOSE statement must be
G-20

DIAGNOSTIC ERROR MESSAGES
completely specified.
assumed present.

It is

323

.REMOVAL. MUST FOLLOW .FOR.
IT IS ASSUMED.

The FOR REMOVAL phrase of the
CLOSE statement must be
completely specified.
It is
assumed present.

324

.LOCK. OMITTED AFTER .WITH.
IT IS ASSUMED.

The keyword WITH in a CLOSE
statement is recognized but
is not followed by one of the
keywords NO or LOCK. The
WITH LOCK phrase is assumed
present.

325

DATANAME SPECIFIED WHERE
FILENAME EXPECTED.

The name used in an I/O verb
to reference a file was not a
file name but was some other
data-name. Fatal.

326

FILENAME MUST FOLLOW
MODE SPEC. IN .OPEN •.

The OPEN statement does not
reference a valid file name
where a file-name reference
is expected.
Fatal.

327

ILLEGAL MODE SPECIFIED
AFTER .OPEN. VERB.

One of the OPEN mode keywords
INPUT, OUTPUT, 1-0, or EXTEND
is required immediately after
the OPEN verb.
None of these
four keywords was
recognized.
Fatal.

330

.END. MUST FOLLOW .AT ..
IT IS ASSUMED.

The keyword END was omitted
in the AT END phrase of the
READ statement. The AT END
phrase is assumed present.

331

FILENAME MUST FOLLOW
.READ. VERB.

Either the file-name was
omitted following the READ
verb or the data item
following the READ verb is
not a valid file-name
reference.
Fatal.

332

DATANAME OMITTED AFTER .INTO.
IN . READ.

The data-name reference
following the INTO keyword
of the READ statement was
omitted. Fatal.

333

RECORDNAME MUST FOLLOW
.WRITE. OR .REWRITE.

The 01 record-name reference
immediately following the
WRITE or REWRITE verb was
omitted.
Fatal.

334

STATEMENT IGNORED DUE
TO ILLEGAL RECORDNAME.

The data-name immediately
following the WRITE or
REWRITE verb is not a valid
01 record-name reference.
Fatal.

335

.ADVANCING. OPTION OMITTED
IN .WRITE. 1 ASSUMED.

A data-name reference, numeric integer literal reference,
or the keyword PAGE was not
recognized in the BEFORE/
G-21

DIAGNOSTIC ERROR MESSAGES
AFTER ADVANCING phrase of the
WRITE statement. A numeric
integer literal value of 1 is
assumed.
336

.EOP. MUST FOLLOW .AT ..
IT IS ASSUMED.

The keyword EOP was omitted
in the AT EOP phrase of the
WRITE statement. The AT EOP
phrase is assumed present.

337

DATANAME OMITTED AFTER
.FROM.

The data-name reference
following the FROM keyword of
the WRITE or REWRITE
statement was omitted.
Fatal.

340

.ADVANCING. INTEGER TOO BIG.
TRUNCATED TO 63.

The numeric integer in the
BEFORE/AFTER ADVANCING phrase
of the WRITE statement is
greater than 63.
63
is assumed.

341

.NO REWIND. ILLEGAL WITH
.10. OR .EXTEND. MODE.

An OPEN statement with the
1-0 or EXTEND mode specified
cannot have the NO REWIND
phrase also specified.
Fatal.

342

ILLEGAL .ADVANCING. DATANAME.
1 IS ASSUMED.

The data-name in the BEFORE/
AFTER ADVANCING phrase of the
WRITE statement is not an
elementary numeric integer
data-name reference. A
numeric integer literal value
of 1 is assumed.

343

FILENAME MUST FOLLOW
.DELETE. VERB.

Either the file-name was
omitted following the DELETE
verb Qr the data item
following the DELETE verb is
not a valid file-name
reference. Fatal.

344

FILENAME MUST FOLLOW
.START. VERB.

Either the file name was
omitted following the START
verb or the data item
following the START verb is
not a valid file name
reference. Fatal.

345

.LESS. OMITTED AFTER .NOT.
IN .START. ASSUMED.

The keyword LESS is omitted
after NOT in the relational
condition of the START
statement. LESS is assumed
present.

346

DATANAME OMITTED IN .KEY
IS. PHRASE. ASSUMED.

The RELATIVE KEY data-name
for the referenced file was
omitted in the KEY IS phrase
of the START statement. The
RELATIVE KEY data-name is
assumed present.

G-22

DIAGNOSTIC ERROR MESSAGES

347

RELATIONAL WORD OMITTED
AFER .KEY IS. PHRASE.

None of the relational
keywords EQUAL, GREATER, or
NOT was recognized following
the KEY IS phrase of the
START statement. Fatal.

350

TERMINATOR IGNORED IN
.10 CONTROL. PARAGRAPH.

A clause is terminated by a
period, but a header does not
follow in Area A. The period
is ignored. The compiler
assumes it is still in the
I-O-CONTROL paragraph.

351

TERMINATOR IGNORED IN
.SPECIAL NAMES. PARAGRAPH.

A clause is terminated by a
period, but is not followed
by a header in Area A. The
period is ignored, and the
compiler continues processing
the SPECIAL-NAMES paragraph.

352

.NATIVE. MISSING IN
SPECIALNAMES CLAUSE.

The alphabet-name clause does
not contain NATIVE or
STANDARD-I. The alphabetname clause is ignored.

353

SYNTAX ERROR IN .OBJECT
COMPUTER. PARAGRAPH.

The OBJECT-COMPUTER paragraph
contains an unrecognizable
word. Recovery is made by
scanning over all words until
a word is found in area A.

354

TERMINATOR OMITTED IN
.OBJECT COMPUTER. PARA.

The OBJECT-COMPUTER paragraph
is not terminated by a
period. Recovery is made by
scanning over all words until
a word is found in area A.

355

DATANAME FOLLOWING .KEY IS.
PHRASE IS ILLEGAL

The data-name following the
KEY IS phrase of the START
statement is not a RECORD KEY
associated with the referenced
indexed file, nor is it
subordinate to a RECORD KEY
whose left-most character
position corresponds to its
own left-most character
position. FATAL.

356

INVALID USAGE ON
CONDITIONAL VARIABLE.

The level 88 condition
variable does not have
DISPLAY or COMPUTATIONAL
usage.

357

ILLEGAL SEPARATOR IN
COBOL STATEMENT.
IGNORED.

An illegal character was
detected between two
consecutive words of a COBOL
statement. The illegal
character is ignored.

360

ILLEGAL CHARACTER FOUND
WITHIN A COBOL WORD.

Illegal characters were found
in an alphanumeric COBOL
word, not within an
alphanumeric literal. The
illegal characters are
G-23

DIAGNOSTIC ERROR MESSAGES
replaced by dollar signs in
the internal representation
of the COBOL word.
361

UNRECOGNIZABLE TEXT FOUND
IN COBOL STATEMENT.

In scanning the source text,
the compiler was unable to
recognize an alphanumeric
COBOL word (i.e., a keyword
or user-defined word), an
alphanumeric literal, or a
numeric literal. The error
is not internally corrected
and usually will propagate
further error messages.

362

COBOL WORD BEGINS WITH
OR ENDS IN HYPHEN.

In attempting to recognize a
keyword or user-defined word,
the compiler has detected
that the COBOL word begins
or ends with a hyphen
character.

363

NONNUMERIC LITERAL TOO LONG.
TRUNCATED TO MAX.

An alphanumeric literal
greater than 132 characters
in length is detected.
The
literal is truncated on right,
retaining the first 132 characters as the literal.

36.4

COBOL SOURCE LINE TOO LONG.
TRUNCATED TO MAX.

The indicated COBOL source
line contains more than 65
characters in terminal
format.
The excess
characters are ignored and
only those characters in the
printed COBOL source line are
retained.

365

.BY. OMITTED IN REPLACING
OPTION. COpy IGNORED.

The keyword BY was not found
in this COPY •.. REPLACING
statement.
The statement
will be ignored.

366

TERMINATOR OMITTED IN
.COPY.
IT IS ASSUMED.

The required period
terminating the COpy
statement is omitted.
assumed present.

It is

367

.LINAGE. CLAUSE DATANAME
MUST BE AN INTEGER.

A data-name referenced in the
LINAGE clause of the FILE
SECTION is defined in the
WORKING-STORAGE SECTION with
decimal places.

370

.LINAGE.CLAUSE DATANAME
MUST BE UNSIGNED.

A numeric data-name referenced in the LINAGE clause of
the FILE SECTION is defined
in the WORKING-STORAGE SECTION as a signed data item.

371

POSSIBLE HIGH ORDER
RECEIVING FIELD TRUNCATION.

Truncation of high order
information during a MOVE
or an arithmetic operation
upon a receiving field is
G-24

DIAGNOSTIC ERROR MESSAGES
possible. This is an
observation only.
372

POSSIBLE LOW ORDER
RECEIVING FIELD TRUNCATION.

Truncation of low order
information during a MOVE
or an arithmetic operation
upon a receiving field is
possible. This is an
observation only.

373

PD HEADER NOT FOLLOWED
BY AN AREA A WORD.

The word following the
PROCEDURE DIVISION header
does not begin in Area A. A
scan is made over all words
until a word is found in Area
A.

374

OPEN OPTIONAL FILES ONLY
IN .INPUT. MODE.

An OPTIONAL file can be
OPENed in INPUT mode only.
The compiler assumes that the
OPTIONAL file is OPENed in
INPUT mode.

375

EXPECTED .FILE STATUS.
DATANAME NOT DEFINED.

A data-name referenced in a
FILE STATUS phrase of a
SELECT clause in the FILECONTROL paragraph is not
defined in the WORKINGSTORAGE SECTION of the DATA
DIVISION.

376

EXPECTED .VALUE OF 10.
DATANAME NOT DEFINED.

The data-name referenced in a
VALUE OF ID clause of an FD
is not defined in the
WORKING-STORAGE SECTION of
the DATA DIVISION.
Fatal.

377

EXPECTED .LINAGE. CLAUSE
DATANAME NOT DEFINED.

A data-name referenced in the
LINAGE clause of the FILE
SECTION is not defined in the
WORKING-STORAGE SECTION of
the DATA DIVISION.

400

.RELATIVE KEY. DATANAME
HAS INVALID CLASS.

A data-name referenced in a
RELATIVE KEY phrase of a
SELECT clause in the FILECONTROL paragraph is defined
in the WORKING-STORAGE
SECTION with non-numeric
class.

401

.RELATIVE KEY. DATANAME
HAS INVALID USAGE.

A data-name referenced in a
RELATIVE KEY phrase of a
SELECT clause must be defined
with COMPUTATIONAL or
DISPLAY usage in the WORKINGSTORAGE SECTION.

402

.RELATIVE KEY.
IS TOO LONG.

A numeric integer data-name
referenced in a RELATIVE KEY
phrase is defined with more
than eight digits of
precision in the WORKINGSTORAGE SECTION.

DATAITEM

G-25

DIAGNOSTIC ERROR MESSAGES
403

.RELATIVE KEY. DATANAME
MUST BE AN INTEGER.

A numeric data-name referenced in a RELATIVE KEY
phrase is defined in the
WORKING-STORAGE SECTION with
decimal places.

404

.FILE STATUS. DATANAME
HAS INVALID CLASS.

A data-name referenced in a
the FILE STATUS phrase of a
SELECT clause must be defined
in with DISPLAY usage in the
WORKING-STORAGE SECTION.

405

.FILE STATUS. DATA NAME
HAS INVALID USAGE.

A data-name referenced in a
FILE STATUS phrase of a
SELECT clause is defined with
DISPLAY USAGE in the WORKINGSTORAGE SECTION.

406

LENGTH OF .FILE STATUS.
DATAITEM IS ILLEGAL.

An alphanumeric data-name
referenced in a FILE STATUS
phrase of a SELECT clause
must be defined as an
alphanumeric variable
consisting of two characters
in the WORKING-STORAGE
SECTION.

407

.VALUE OF 10. DATANAME
HAS INVALID CLASS.

A data-name referenced in a
VALUE OF ID clause of an FD
is defined in the WORKINGSTORAGE SECTION with nonalphanumeric class.

410

.VALUE OF 10. DATANAME
HAS INVALID USAGE.

A data-name referenced in a
VALUE OF ID clause of an FD
must be defined with DISPLAY
usage in the WORKING-STORAGE
SECTION.

411

LENGTH OF .VALUE OF ID.
DATAITEM IS ILLEGAL.

An alphanumeric data-name
referenced in a VALUE OF 10
clause of an FD must be
defined in the
WORKING-STORAGE section as
alphanumeric variable whose
length L falls in the range
9<=L<=40 characters.

412

.LINAGE. CLAUSE DATANAME
HAS INVALID CLASS.

A data-name referenced in
the LINAGE clause of the FILE
SECTION is defined in the
WORKING-STORAGE SECTION with
non-numeric class.

413

.LINAGE. CLAUSE DATANAME
HAS INVALID USAGE.

A data-name referenced in the
LINAGE clause of the FILE
SECTION must be defined with
COMPUTATIONAL USAGE in the
WORKING-STORAGE SECTION.

414

INVALID RECEIVING OPERAND
IN .SET •• IGNORED.

A receiving operand of a
SET statement is invalid.
Fatal.

G-26

DIAGNOSTIC ERROR MESSAGES
415

NO RECEIVING OPERAND
SPECIFIED IN .SET ..

No receiving operands are
specified in a SET statement.
Fatal.

416

OMITTED OR ILLEGAL OPERAND
AFTER .TO. IN .SET .•

A SET statement has no valid
sending operand. Fatal.

417

ILLEGAL SYNTAX IN
.SET. STATEMENT.

The words TO, UP or DOWN do
not follow the receiving
operands of a SET statement.
Fatal.

420

.BY. MUST FOLLOW .UP.
OR .DOWN .. ASSUMED.

The keyword BY does not
follow the word UP or DOWN in
a SET statement. BY is
assumed present.

421

OMITTED OR ILLEGAL OPERAND
AFTER .BY. IN .SET ..

The operand following the UP
BY or DOWN BY phrase in a SET
statement is invalid or
omitted. Fatal.

422

NO OPERANDS SPECIFIED
IN .DISPLAY.

No operands to be displayed
were recognized by the
compiler in this DISPLAY
statement.
Fatal.

423

SETTING INDEX NAME OUT
OF RANGE.
.SET. IGNORED.

A SET statement is attempting
to set an index name using a
literal that is too large.
Fatal.

424

.IF. TRUE PATH OMITTED.
ASSUME .NEXT SENTENCE.

The true path code is omitted
from the IF statement. NEXT
SENTENCE is assumed as the
true path of the IF
statement.

425

CONFLICTING SIGN SYMBOLS
IN PICTURE STRING.

The compiler recognizes
both the + and - sign symbols
in this PICTURE string. The
compiler ignores the usersupplied PICTURE and declares
the data-name alphanumeric
with a "PICTURE X"
declaration

426

ZERO SUPPRESSION CONFLICTS
IN PICTURE STRING.

The compiler recognizes
both the Z and * zero
suppression symbols in this
PICTURE string. The compiler
ignores the user-supplied
PICTURE and declares the
data-name alphanumeric with a
"PICTURE X" declaration.

427

ILLEGAL CHARACTER IN
THE PICTURE STRING.

A character which is not in
the PICTURE string character
set is recognized in this
PICTURE by the compiler. The
compiler ignores the usersupplied PICTURE and declares
the data-name alphanumeric
with a "PICTURE X"
declaration.
G-27

DIAGNOSTIC ERROR MESSAGES
430

.BLANK WHEN ZERO. CONFLICTS
WITH ZERO SUPPRESS.

A BLANK WHEN ZERO clause is
recognized with a zero
suppression field specified
in the PICTURE string. The
compiler ignores the BLANK
WHEN ZERO clause and
continues with its
processing.

431

PARENTHESIZED SPECIFIER
EXCEEDS 18 DIGITS

The specification contained
inside parentheses of a
PICTURE string exceeds 18
digits in length. The
compiler ignores the usersupplied PICTURE and declares
the data-name alphanumeric
with a "PICTURE X"
declaration.

432

SPECIFIER MISSING INSIDE
PARENTHESES.

The specification contained
inside parentheses of a
PICTURE string is missing.
The compiler ignores the
user-supplied PICTURE and
declares the data-name
alphanumeric with a "PICTURE
X" declaration.

433

ILLEGAL SYMBOL PRECEDES
LEFT PAREN. IN PICTURE.

The compiler recognizes
an S, V, CR, DB, or "."
character preceding a left
parenthesis in a PICTURE
string. The error is ignored
and processing continues.

434

TERMINATOR OMITTED IN
.NOTE. PARAGRAPH

A NOTE paragraph that does
not end with a period
was detected.

435

INVALID OPERAND IN .VARYING.
OR .AFTER. PHRASE.

The expected operand is not a
valid name reference in the
VARYING or AFTER phrase of
this PERFORM VARYING
statement. Fatal.

436

INVALID OPERAND IN .FROM. OR
.BY. PHRASE.

The FROM or BY phrase of this
PERFORM VARYING statement
does not contain a valid
operand reference. Fatal.

437

TOO MANY .AFTER. PHRASES IN
.PERFORM. STATEMENT.

The compiler detects more
than two AFTER phrases in the
PERFORM VARYING statement
being compiled. This is
syntactically invalid.
Fatal.

440

.FROM. OR .BY. OR .UNTIL.
MISSING IN PERFORM.

The compiler detects the
omission of the keywords
FROM, BY, or UNTIL in the
PERFORM VARYING statement.
Fatal.

G-28

DIAGNOSTIC ERROR MESSAGES
441

ILLEGAL CONDITION EXPRESSION
IN THE PERFORM.

The compiler detects an
invalid condition expression
in the PERFORM statement.
Fatal.

442

NONPOSITIVE LITERAL IN .FROM.
OR .BY. PHRASE.

The compiler detects a
non-positive, numeric integer
literal in this PERFORM
statement. This is
syntactically invalid.
Fatal.

443

INVALID RELATION CONDITION IN
.SEARCH ALL.

The compiler detects either a
syntax error or an
invalid operand in the
restricted form of a relation
condition in the SEARCH ALL
statement. Fatal.

444

NON INTEGER DATA CONFLICTS
WITH INDEXNAME USAGE.

The compiler detects a
non-integer data item
reference in a PERFORM
VARYING statement in which
the VARYING, AFTER, and/or
FROM phrase contains an
index-name reference. This is
syntactically invalid. Fatal.

445

IMPLICIT REFERENCE TO BAD
CONDITION VALUES.

Through a reference to a
condition-name, the compiler
detects a reference to an
associated condition-value
which is improperly declared
in the Data Division. The
compiler considers this to be
syntactically invalid.
Fatal.

446

IMPLICIT REFERENCE TO BAD
CONDITION VARIABLE.

Through a reference to a
condition-name, the compiler
detects that the associated
condition-variable is
improperly declared in the
Data Division. The compiler
considers this to be
syntactically invalid. Fatal.

447

TOO MANY NAMES IN COBOL
PROGRAM. RECOMPILE.

The COBOL program being
compiled has too many datanames or procedure-names.
This condition has caused a
compiler table to overflow
with the resultant action of
aborting the compilation. The
user is advised to recompile
the program using the
"/SYM:N" switch to get more
space for the compiler
symbol tables.

450

REFERENCE TO UNDEFINED
DATANAME. IGNORED.

The COBOL statement being
compiled contains a reference
to an undefined data-name.
The compiler considers this
G-29

DIAGNOSTIC ERROR MESSAGES
to be syntactically invalid
and ignores the reference.
This diagnostic may be issued
in conjunction with other
diagnostics for the
erroneous statement.
451

QUALIFIED REFERENCE ILLEGAL
IN THIS CONTEXT.

The compiler detects a
qualified reference in a
context in which an
unqualified reference is
required. The compiler
permits the qualified
reference in this context and
continues with the
compilation of the statement
containing the reference.

452

QUALIFIER OMITTED IN
QUALIFIED REFERENCE.

A data-name is omitted after
the keyword OF or IN in a
qualified reference in the
COBOL statement being
compiled. The reference is
ignored. This diagnostic may
be issued in conjunction with
other diagnostics for the
statement in error.

453

TOO MANY QUALIFIERS IN
QUALIFIED REFERENCE.

The compiler detects more
than 48 qualifiers in a
qualified reference. The
excess qualifiers are ignored
in the reference.

454

UNDEFINED QUALIFIER IN
QUALIFIED REFERENCE.

The compiler detects a
qualified reference one of
whose qualifiers is a
reference to an undefined
data-name. The compiler
considers this to be
syntactically invalid
and ignores the entire
qualified reference. This
diagnostic may be issued in
conjunction with other
diagnostics for the erroneous
statement containing the
reference.

455

COBOL STATEMENT CONTAINS
AMBIGUOUS REFERENCE.

The compiler detects a
reference to COBOL data which
is not uniquely referenceable
through qualification. The
compiler uses a reference to
COBOL datum which satisfies
the reference in the text of
the COBOL program. This
diagnostic may be issued in
conjunction with other
diagnostics fo~ the statement
in error.

456

DATANAME REFERENCE EXPECTED
IN THIS CONTEXT.

The compiler detects a
reference to a COBOL datum
G-30

DIAGNOSTIC ERROR MESSAGES
which is not alphabetic,
numeric, alphanumeric,
alphanumeric-edited, or
numeric-edited. The context
of this reference requires
that the reference be to one
of these classes of data
items.
The compiler considers the
referenced item to be
syntactically invalid. This
diagnostic may be issued in
conjunction with other
diagnostics for the statement
in error.
457

ILLEGAL REFERENCE DETECTED IN
THIS CONTEXT.

The compiler detects a
reference to a COBOL datum
which is invalid in the
context of its usage. The
compiler considers the
referenced item to be
syntactically invalid. This
diagnostic may be issued in
conjunction with other
diagnostics for the statement
in error. Fatal.

460

PARENTHESIZED SPECIFIER
LARGER THAN 4095.

The specification contained
inside parentheses of a
PICTURE string is larger than
4095 in value. The specifier
exceeds an implementation
limitation of 4095. The
compiler assumes 4095 and
continues with the processing
of the PICTURE string.

461

EXTRA OPENING QUOTE ON
LITERAL IS IGNORED.

The compiler detects a
superfluous quote at the
beginning of a non-numeric
literal specification. The
compiler ignores the extra
quote and continues with the
processing of the non-numeric
literal.

462

PROGRAM NAME MUST BE A
NONNUMERIC LITERAL

The program-name literal
following the key word CALL
is not a nonnumeric
literal. This is
syntactically invalid. Fatal.

464

LITERALS ARE ILLEGAL IN
ARGUMENT LIST OF .CALL ..

Literals are not allowed in
the argument list of a CALL
statement. Fatal.

465

ARGUMENT LIST OMITTED
AFTER .USING. IN .CALL .•

The required argument list
is missing after the key
word USING in the CALL
statement. Fatal.

470

ILLEGAL SYNTAX IN .CODE SET.
CLAUSE. IGNORED.

A valid alphabet-name
reference is omitted in the
G-31

DIAGNOSTIC ERROR MESSAGES
CODE-SET clause. The
compiler ignores the CODE-SET
clause and continues to process the remainder of the FD.
471

DATANAME IN .KEY IS. PHRASE
NOT ALPHANUMERIC.

The data-name following the
KEY IS phrase in a START
statement referencing an
indexed file must be
alphanumeric. FATAL.

472

.RECORD KEY. DATAITEM
LENGTH GREATER THAN 255.

A data-name referenced in a
RECORD KEY or ALTERNATE RECORD
KEY phrase of a SELECT clause
in the FILE-CONTROL paragraph
must be defined in the FILE
SECTION as an item whose
length is less than or equal
to 255.

473

DATANAME IN .KEY IS PHRASE
IS SUBSCRIPTED OR INDEX

The data-name following the
KEY IS phrase in a READ or
START statement referencing an
indexed file must not be
subscripted or index. Fatal.

474

.RECORD KEY. DATAITEM MUST
NOT BE A COBOL TABLE

A data-name referenced in a
RECORD KEY or ALTERNATE RECORD
KEY phrase of a SELECT clause
in the FILE-CONTROL paragraph
must not be defined in the
FILE SECTION with an OCCURS
clause or subordinate to an
item with an OCCURS clause.

475

.RECORD. OMITTED FROM
.ALTERNATE RECORD. ASSUMED.

The reserved word RECORD is
missing from the ALTERNATE
RECORD KEY clause. The error
is ignored.

476

UNDEFINED .ALTERNATE RECORD
KEY. DATANAME.

The data-name given in an
ALTERNATE RECORD KEY clause
has not been defined in the
Data Division.

477

.ALTERNATE RECORD KEY.
CLAUSES ARE SEPARATED

In the SELECT statement the
ALTERNATE RECORD KEY clauses
are interleaved among the
other clauses. The ALTERNATE
RECORD KEY clauses should
follow one another with no
intervening clauses. This
error is ignored.

500

LINKAGE SECTION ITEM
APPEARS TWICE IN .USING.

A LINKAGE SECTION data item
must not appear more than once
in the USING phrase of a
PROCEDURE DIVISION USING
header. FATAL.

501

ILLEGAL .SEGMENT-LIMIT.
VALUE. IGNORED

The segment-limit is either
not a numeric literal or a
numeric literal whose value is
outside of allowed segmentlimit range.
G-32

DIAGNOSTIC ERROR MESSAGES
502

INTEGER 1 BEYOND
TREATED AS LEVEL

AREA A
NUMBER.

503

MULTIPLE PICTURES FOR
SAME ITEM.
LAST USED.

A data item has more than 1
PICTURE clause. The compiler
used the last PICTURE clause
specified.

504

CLOSING PARENTHESIS MISSING
IN PICTURE.

The right parenthesis is
missing in the PICTURE
string. The compiler uses
the last four digits of the
PICTURE string.

505

OT A SUBPROGRAM .PROGRAM.
IGNORED.

An EXIT PROGRAM has been
detected, but the COBOL
program being compiled is not
a subprogram. Because EXIT
PROGRAM is meaningful only in
a subprogram, the word PROGRAM
is ignored, and the statement
is treated as if it were a
simple EXIT statement.

506

EXPANDED PICTURE STRING TOO
LONG. PIC X ASSUMED.

The process of expanding a
PICTURE string specification
produces a string which
exceeds implementation
limitation. The compiler
ignores the user-supplied
PICTURE and declares the
data-name with a "PICTURE X"
declaration.

507

SPECIFIER OMITTED BEFORE
LEFT PAREN. IN PIC.

The first character of a
PICTURE string is a left
parenthesis.
The compiler
ignores the user-supplied
PICTURE and declares the
data-name alphanumeric with a
"PICTURE X" declaration.

510

SECTION NO. GREATER THAN
49 TREATED AS 49.

A segment number greater than
49 follows the word SECTION.
The segment is treated as if
it were 49.

511

INVALID ITEM LENGTH IN
PARENTHESES OF PICTURE.

The parenthesized length
specifier in a PICTURE
contains non-numeric
characters.
The compiler
ignores the user-supplied
PICTURE and declares the
data-name alphanumeric with a
"PICTURE X" declaration.

512

VALUE CLAUSE NOT ALLOWED
IN LINKAGE SECTION.

The VALUE clause cannot appear
in data items in the LINKAGE
SECTION. The only place the
VALUE clause can appear in the
LINKAGE SECTION is in a
condition name definition.

An 01 level item was detected
beyond Area A and accepted as
if in Area A.

G-33

DIAGNOSTIC ERROR MESSAGES
513

OPERAND IN .USING. MUST BE
LINKAGE SECTION ITEM.

Only level 01 or 77 LINKAGE
SECTION items may appear in
the USING phrase of a
PROCEDURE DIVISION header.
FATAL.

514

MULTIPLE FLOATING FIELDS
IN NUMERIC EDIT ITEM.

The PICTURE string contains
multiple floating fields.
The compiler ignores the
user-supplied PICTURE and
declares the data-name
alphanumeric with a "PICTURE
X" declaraton.

515

MULTIPLE ZERO SUPPRESS
FIELDS IN PICTURE STRING.

Multiple zero suppression
fields are detected in
PICTURE string. The compiler
ignores the user-supplied
PICTURE and declares the
data-name alphanumeric with a
"PICTURE X" declaration.

516

ZERO SUPPRESSION ILLEGAL
WITH FLOATING FIELD.

The PICTURE string contains
both floating and zero
suppression fields. The
compiler ignores the usersupplied PICTURE and declares
the data-name alphanumeric
with a "PICTURE X"
declaration.

517

ILLEGAL SYNTAX IN
PICTURE STRING.

The PICTURE string is not
specified correctly according
to the rules of PICTURE
string syntax. The compiler
ignores the user-supplied
PICTURE and declares the
data-name alphanumeric with a
"PICTURE X" declaration.

520

MULTIPLE DECIMAL POINTS
IN PICTURE.

The PICTURE string contains
multiple decimal point
specifications (ViS, piS, or
periods). The compiler
ignores the user-supplied
PICTURE and declares the
data-name alphanumeric with a
"PICTURE X" declaration.

521

OPERAND IN USING MUST BE
LEVEL 01 OR 77

Only level 01 or 77 LINKAGE
SECTION items may appear in
the USING phrase of a
PROCEDURE DIVISION header.
FATAL.

522

INVALID USAGE.

IGNORED.

The USAGE clause contains an
invalid word. The compiler
ignores the entire USAGE
clause.

523

MULTIPLE USAGE CLAUSES.
LAST USED.

The defined data-name has
multiple USAGE clauses
specified. The last USAGE
clause specified is used by
the compiler.
G-34

DIAGNOSTIC ERROR MESSAGES
524

MULTIPLE OCCURS CLAUSES.
LAST USED.

The defined data-name has
multiple OCCURS clauses
specified. The compiler uses
the last OCCURS clause
specified.

525

OCCURS SPECIFICATION ERROR.
1 ASSUMED.

The integer entry of the
OCCURS clause is either
non-numeric or non-integer or
does not lie in the range 1
to 4095. The compiler
assumes an integer value
of 1.

526

DATANAME OMITTED IN DATA
DESCRIPTION ENTRY.

The data-name declaration is
omitted after a level-number
in the data description
entry. The compiler supplies
a system-defined name and
proceeds with the processing
of the data description
entry. The system-defined
name is transparent and,
thus, inaccessible to the
user.

527

INVALID INDEX NAME.
IGNORED.

The compiler did not
recognize a valid index name
in the INDEXED BY phrase.
The compiler ignores the
INDEXED BY phrase.

530

USAGE OPTION NOT YET
IMPLEMENTED. IGNORED.

The compiler detected COMP-l
in the USAGE clause. This
option is not implemented and
is ignored. The default
USAGE of DISPLAY is used by
the compiler.

531

TERMINATOR OMITTED AFTER
DATAITEM DESCRIPTION.

A data item description entry
in the DATA DIVISION is not
terminated by a period. The
compiler assumes the period
is present and continues
processing.

532

INVALID SIGN IN NUMERIC
PICTURE.

The sign character S is
detected in a position other
than the leading character
position of a numeric PICTURE
string. The compiler ignores
the user-supplied PICTURE and
declares the data-name
alphanumeric with a "PICTURE
X" declaration.

533

PICTURE CLAUSE OMITTED ON
ELEMENTARY ITEM.

An elementary item is
recognized with its PICTURE
clause omitted in the
description. The compiler
declares the data-name
alphanumeric with a PICTURE
X declaration.

G-35

DIAGNOSTIC ERROR MESSAGES
534

NUMERIC ITEM EXCEEDS 18
DIGIT MAX. TRUNCATED.

A numeric field is defined in
this PICTURE with more than
18 digits of precision. The
numeric field is truncated to
18 digits.

535

COMP ITEM EXCEEDS 18
DIGITS. ASSIGN 4 WORDS.

A COMPUTATIONAL data item
exceeds 18 digits in its
specification. The compiler
truncates it and allocates
four words for its run-time
storage.

536

INDEX ITEM HAS
ILLEGAL CLAUSE.

The compiler recognized a
JUSTIFIED, SYNCHRONIZED,
VALUE, PICTURE, or SIGN
clause on a data-item
description which has INDEX
USAGE. This is illegal. The
compiler ignores the
offensive clause.

537

NUMERIC VALUE FOR
DISPLAY ITEM.
IGNORED.

The VALUE clause specifies
numeric value initialization
for a non-numeric data-item
which is defined with DISPLAY
USAGE. This is illegal. The
VALUE clause is ignored.

540

VALUE TOO LONG.
TRUNCATED.

The length of the non-numeric
literal in the VALUE clause
is longer than the associated
data-item. The literal is
truncated on the right to fit
in the storage allocated to
the data-item.

541

CLAUSE DUPLICATION.

542

INVALID WORD IN .BLANK
WHEN ZERO .. IGNORED.

The keyword ZERO was not
recognized in the BLANK WHEN
ZERO clause. The entire
clause is ignored.

543

LEVEL NUMS UNEQUAL IN
.REDEFINES. CLAUSE IGNORED.

A REDEFINES clause attempts
to redefine two items of
different level numbers. The
REDEFINES clause is ignored.

544

POSSIBLE OVERLAP OF DEPENDING
ON ITEM AND TABLE

The depending on item and
variable length table are
both defined in the LINKAGE
SECTION. Because LINKAGE
SECTION items are associated
with data items appearing in
a CALL statement, there is
no way at compile time to
insure that the depending on
items and table do not
overlap. The COBOL run-time
OTS does not check for overlap

IGNORED.

G-36

This clause has been
previously recognized for
this item. The duplicate
clause is ignored.

DIAGNOSTIC ERROR MESSAGES

of the depending on item and
the table during execution.
It is, therefore, your
responsibility to insure
that overlap does not occur.
545

LEVEL ILLEGAL AFTER 77.
TREATED AS 01.

An invalid level number
(02-49) follows a 77 level
item.
The 77 level item is
treated as an 01 level item.
This action may propagate
further diagnostics if it is
not a valid group item.

546

PERIOD OMITTED AFTER .EXIT
PROGRAM.

The words EXIT PROGRAM are not
followed by a period. The
error is ignored.

547

.EXIT PROGRAM. NOT LAST
STMT OF SENTENCE.

An EXIT PROGRAM statement
appears in a sequence of
statements within a sentence.
But, it is not the last
statement. All of the
statements following it are
compiled, but can never be
reached during execution.

550

REDEFINING LENGTH SHOULD
MATCH ORIGINAL LENGTH.

The length of a non-Ol level
redefines item is not the
same as the length of the
item it REDEFINES.
The new
length is used.

551

REDEFINITION OF .OCCURS.
ITEM.
IGNORED

Items with OCCURS cannot
be redefined.
REDEFINES
is ignored.

552

PROCESSING RESUMES AFTER
BAD FD.

Prior to issuing this
message, the compiler had
discovered bad syntax in the
FD of the FILE SECTION. The
compiler at that time issued
an error message identifying
the syntax error.
Then the
compiler went into recovery
mode attempting to recognize
another FD, the WORKINGSTORAGE SECTION header or the
PROCEDURE DIVISION. Upon
recognizing one of these
three language elements, the
compiler issues this
diagnostic indicating that
normal processing resumes.

553

INVALID CLAUSE KEYWORD.
OTHER CLAUSES SKIPPED.

A reserved clause keyword was
expected at this point in a
data item description entry
of the DATA DIVISION, but was
not recognized by the
compiler. The compiler skips
to the next level number
data item description.

G-37

DIAGNOSTIC ERROR MESSAGES
554

INVALID WORD FOLLOWING
.VALUE .. IGNORED.

The VALUE clause contains an
invalid word for this data
description. The entire
VALUE clause is ignored.

555

VALUE CONFLICT.
GROUP VALUE USED.

This VALUE clause assigns
a value to an item
subordinate to a group item
that also has a VALUE clause.
The subordinate VALUE clause
is ignored.

556

LEVEL NUMBER OMITTED.
ITEM IGNORED.

The level number has been
omitted in a data-item
description.
All the source
text is ignored up to and
including the next period.

557

NO VALUE AFTER CONDITION
NAME. 88 IGNORED.

An 88 level condition-name
has no VALUE clause
specified. The entire 88
level data-item is ignored.

560

SYNTAX ERROR IN SWITCH
CLAUSE. CLAUSE IGNORED.

The SWITCH clause has a
syntax error in its
specification. The compiler
ignores the entire clause.

561

.NO. MISSING IN
ADVANCING PHRASE.

The keyword NO is missing in
the ADVANCING phrase of the
DISPLAY statement. NO is
assumed present.

ASSUMED.

562

.ADVANCING.
MISSING AFTER
.NO .. ASSUMED.

The keyword ADVANCING is
missing in the ADVANCING
phrase of the DISPLAY
statement. ADVANCING is
assumed present.

563

DUPLICATE DATANAME
DECLARATION DETECTED.

In the ENVIRONMENT and/or
DATA DIVISION, a data-name is
defined which, if referenced,
is not uniquely referenceable
even with complete
qualification.

564

ILLEGAL PARAGRAPH HEADER
ID DIV. PAR IGNORED.

An illegal paragraph header
appears in the IDENTIFICATION
DIVISION. The paragraph is
ignored.

565

ILLEGAL PARAGRAPH HEADER
ENV DIV. PAR IGNORED.

An illegal paragraph header
appears in the ENVIRONMENT
DIVISION. The paragraph is
ignored.

566

NUMERIC LITERAL ILLEGAL
ON GROUP ITEM.
IGNORED.

A numeric literal is illegal
in the VALUE clause of a
group item. The VALUE clause
is ignored.

G-38

DIAGNOSTIC ERROR MESSAGES
567

• ENVIRONMENT. NOT FOLLOWED
BY .DIVISION ..

The word ENVIRONMENT is
not followed by the word
DIVISION. DIVISION is
assumed present.

570

TERMINATOR MISSING AFTER
• DATA DIVISION. HEADER.

The DATA DIVISION header is
not followed by a period .
The period is assumed present
and processing continues.

571

TERMINATOR MISSING AFTER
PARAGRAPH HEADER.

A paragraph header in the
IDENTIFICATION or ENVIRONMENT
DIVISION is not terminated by
a period. The period is
assumed present and
processing continues.

572

.RENAMES. SPECIFIES STORAGE
OVERLAP ON RIGHT.

In processing the RENAMES
clause, the compiler detects
the condition in which the
end of the storage allocated
to the data-name after the
THRU keyword is not positionally to the right of the end
of the storage allocated to
the data-name after the
RENAMES keyword. This is
syntactically invalid. The
compiler ignores the entire
RENAMES data description
entry.

573

.SECTION. OMITTED FROM
SECTION HEADER.

An ENVIRONMENT DIVISION
section name is not followed
by the word SECTION. The
error is ignored.

574

TERMINATOR MISSING AFTER
SECTION HEADER.

An ENVIRONMENT DIVISION
section header is not
terminated by a period.
error i~ ignored.

The

600

ILLEGAL LEVEL NUMBER.
TREAT AS 01.

This level number is not an
01-49, 66, 77, or 88 level
number. The level number is
assumed to be 01.

601

TERMINATOR MISSING AFTER
ENV DIV HEADER.

The ENVIRONMENT DIVISION
header is not terminated by a
period. The period is assumed
present and processing
continues.

602

.DATA. NOT FOLLOWED BY
.DIVISION.

The word DATA is not
followed by the word
DIVISION. DIVISION is
assumed present.

603

ENVIRONMENT DIVISION HEADER
OMITTED.

The program contains no
ENVIRONMENT DIVISION header.
The compiler resumes
processing at the next
paragraph header.

G-39

DIAGNOSTIC ERROR MESSAGES
604

UNRECOGNIZABLE COBOL PROGRAM
FORMAT. ABORT.

The compiler is unable to
recognize the reserved word
IDENTIFICATION as the first
word required in a COBOL
source program. Failure to
recognize this required
reserved word may be due to
one of the following reasons:
(1) IDENTIFICATION is, in
fact, omitted as the first
word of the source file, (2)
the user is attempting to
compile a COBOL source
program in conventional
format without specifying the
"/CVF" switch, or (3) the
user is attempting to compile
a file which is not a COBOL
source program. The compiler
issues a string of
diagnostics to the printer,
informs the user on the
system console, and then
aborts the compilation.

605

.IDENTIFICATION. NOT FOLLOWED
BY .DIVISION ..

The word IDENTIFICATION is
not followed by the word
DIVISION. DIVISION is
assumed present.

606

TERMINATOR OMITTED AFTER
.ID DIVISION. HEADER.

The IDENTIFICATION DIVISION
header is not terminated by a
period. The period is
assumed present and
processing continues.

607

.PROGRAMID. EXPECTED AFTER
DIVISION HEADER.

The IDENTIFICATION DIVISION
header is not followed by
the PROGRAM-ID paragraph.
The error is ignored and
processing continues.

610

TERMINATOR OMITTED AFTER
.PROGID. PARA HEADER.

The PROGRAM-ID paragraph-name
is not terminated by a
period. The period is
assumed present and
processing continues.

611

INVALID PROGRAM NAME IN
.PROGRAM ID. PARAGRAPH.

The program name of the
PROGRAM-ID paragraph contains
an invalid character or
exceeds nine characters in
length. The error is ignored
and processing continues.

G-40

DIAGNOSTIC ERROR MESSAGES
612

TOO MANY FILES FOR LUNS
OR TEMPORARY SPACE.

The compiler has discovered
either that more than 30
files are declared in the
program or that more than 30
SAME RECORD AREA clauses are
specified in the program.
The compiler imposes a limit
of 30 in both cases, because
the associated compiler and/
or object time table space is
exhausted.

613

INVALID WORD SUSPENDS
PROCESSING. SCAN FORWARD.

An unidentifiable word is
found where a verb is
expected. A scan is made to
a verb, or period, or word in
Area A.

614

PROCESSING RESTARTS ON
VERB.

Due to a previous syntax
error, the compiler went into
recovery mode looking for the
next verb, period, or Area A
word upon which to resume
compilation. The compiler
has recognized a verb and
resumes normal compilation at
this point. This message is
an observation only.

615

PROCESSING RESTARTS ON
PROCEDURE NAME.

Due to a previous syntax
error, the compiler went into
recovery mode looking for the
next verb, period, or Area A
word upon which to resume
compilation. The compiler
has recognized an Area A word
and resumes compilation at
this point. This message is
an observation only.

616

PROCESSING RESTARTS AFTER
TERMINATOR.

Due to a previous syntax
error, the compiler went into
recovery mode looking for the
next verb, period, or Area A
word upon which to resume
compilation. The compiler
has recognized a period and
resumes normal compilation on
the word following the
period. This is an
observation only.

617

.IDENTIFICATION.
KEYWORD NOT IN AREA A.

The compiler detects that the
IDENTIFICATION keyword is not
in Area A. The compiler
ignores the error and
continues processing.

620

PARAGRAPH TERMINATOR
ASSUMED OMITTED.

A paragraph was terminated
without a period. The period
is assumed and processing
continues.

G-41

DIAGNOSTIC ERROR MESSAGES
621

.LINAGE. INVALID FOR THIS
FILE. CLAUSE IGNORED.

The LINAGE clause must not be
specified for a file which
has RELATIVE or INDEXED
organization. The LINAGE
clause is ignored.

622

TERMINATOR MISSING AFTER
PROCEDURE NAME.

A section or paragraph
name is not terminated by a
period. The period is
assumed present and
processing continues.

623

.ELSE DOES NOT HAVE
ASSOCIATED .IF .. IGNORED.

The word ELSE has no
associated IF statement.
ELSE is ignored.

624

VERB EXPECTED TO FOLLOW
ELSE . . . ELSE. IGNORED.

A SENTENCE ENDS WITH THE
word ELSE. The ELSE is
ignored.

625

.JUSTIFY. WITH NUMERIC OR
EDITED ITEM. IGNORED.

The JUSTIFIED clause must not
be specified for a numeric or
numeric-edited dataitem. The
JUSTIFIED clause is ignored.

626

. BLANK WHEN ZERO.
ILLEGAL,LY
SPECIFIED. IGNORED.

The BLANK WHEN ZERO clause
must be specified only for a
numeric or numeric-edited
data-item. The clause is
ignored.

627

INVALID OR MISSING DATANAME
AFTER .REDEFINES .•

The compiler detects the
omission of a valid data-name
reference following the
keyword REDEFINES. The
compiler ignores the
REDEFINES clause and
continues with the processing
of the data description
entry.

630

.REDEFINES. MUST FOLLOW
DATA NAME.
IGNORED.

The REDEFINES keyword appears
in the wrong position of a
data description entry. The
REDEFINES clause is ignored.

631

DEPTH OF NESTED .IF.
EXCEEDS LIMIT.

A nested IF statement has
exceeded the maximum depth of
30 levels. The compiler
ignores nesting beyond this
depth of nesting.

632

DUPLICATE PROCEDURE
NAME DETECTED.

In the Procedure Division, a
paragraph or section-name is
defined which, if referenced,
is not uniquely referenceable, even with
qualification.

633

REFERENCE TO UNDEFINED
PARAGRAPH NAME.

In the Procedure Division, an
explicit qualified reference
is made to a paragraph-name
which is undefined in the
section specified by the
qualifier.
G-42

The

DIAGNOSTIC ERROR MESSAGES
634

FILENAME LITERAL TOO LONG.
TRUNCATED.

A file specification in the
ASSIGN clause exceeds 40
characters in length.
It is
truncated to 40 characters.

635

ILLEGAL SYNTAX IN .GO
TO. STATEMENT.

The compiler detects illegal
syntax in the GO TO
statement. Fatal.

636

INVALID INTEGER OR
DATANAME.

In the LINAGE clause, the
compiler failed to recognize
a non-negative integer
literal or a numeric integer
data-name. This phrase of
the LINAGE clause is ignored.

637

.GO TO. HAS MULTIPLE
PROCEDURE NAMES.

A simple GO TO statement
(i.e., without the DEPENDING
ON phrase) has more than one
procedure-name. Fatal.

640

INVALID WORD FOLLOWS
.DATA DIVISION.

The word following the DATA
DIVISION header either does
not start in Area A or is not
one of the reserved words
FILE, WORKING-STORAGE,
LINKAGE, or PROCEDURE. The
compiler goes into recovery
mode skipping all source
text until one of the
keywords FILE, WORKINGSTORAGE, LINKAGE, or
PROCEDURE is recognized.

641

INVALID WORD IN FILE
SECTION. SCAN FORWARD.

An invalid word was detected
in the FILE SECTION where
the keyword FD is expected.
The compiler goes into
recovery mode skipping all
source text until one of the
keywords FD, WORKING-STORAGE,
LINKAGE, or PROCEDURE
is recognized.

642

.OMITTED LABELS IGNORED
WITH .VALUE OF 10.

The LABEL RECORDS ARE OMITTED
clause is ignored if VALUE OF
10 is specified for a file.
STANDARD labels are assumed.
WARNING.

643

.SECTION. EXPECTED AFTER
HEADER WORD.

The keyword SECTION is
omitted after the word FILE,
WORKING-STORAGE, OR LINKAGE
SECTION is assumed present
and processing continues.

644

TERMINATOR EXPECTED AFTER
SECTION HEADER.

The FILE SECTION, WORKINGSTORAGE SECTION, or LINKAGE
header is not terminated
by a period. The
period is assumed and
processing continues.

G-43

DIAGNOSTIC ERROR MESSAGES
646

.OF. OR .ID. MISSING
IN .VALUE OF 10 ..

One or both of the keywords
OF or ID is omitted in the
VALUE OF ID clause.
Their
presence is assumed and
processing continues.

647

ILLEGAL WORD IN AREA A.
SCAN FORWARD.

In the WORKING-STORAGE
SECTION, an 01 or 77
level number or the
PROCEDURE keyword was
expected in Area A, but was
not recognized.
The compiler
goes into recovery mode
skipping source text until
one of the three language
elements aforementioned is
recognized in Area A.

650

GROUP LEVEL .VALUE.
DISALLOWED.

The VALUE clause on this
group item is not permitted
because a subordinate
elementary item has a nonDISPLAY usage specified or
has a SYNCHRONIZED clause
specified.
The group VALUE
clause is ignored.

651

REFERENCED LINKAGE SECTION
ITEM NOT IN .PD. USING ..

This LINKAGE SECTION item has
been referenced in the
PROCEDURE DIVISION. However,
neither this item nor the
level 01 to which
it is subordinate, appeared in
the PROCEDURE DIVISION USING
phrase. Only those LINKAGE
SECTION items appearing in the
PROCEDURE DIVISION USING
phrase, or items subordinate
to them may be referenced in
the PROCEDURE DIVISION of a
COBOL program. FATAL.

652

NON-SEQ FILE IN .MULTIPLE.
FILE TAPE. CLAUSE.

In the 1-0 CONTROL paragraph,
the MULTIPLE FILE TAPE clause
is specified for a file whose
organization is not
SEQUENTIAL. This is illegal.
The MULTIPLE FILE TAPE clause
is ignored for this file.

653

.VALUE. CLAUSE ILLEGAL IN
FILE SECTION.

A VALUE clause is specified
for a data description entry
given in the FILE SECTION.
This is illegal.
The VALUE
clause is ignored.

654

SYNTAX ERROR IN CURRENCY
CLAUSE.

The alphanumeric literal
expected in the CURRENCY SIGN
clause of the SPECIAL-NAMES
paragraph is omitted. The
clause is ignored and the
currency sign defaults to the
dollar sign.

G-44

DIAGNOSTIC ERROR MESSAGES
655

ILLEGAL CURRENCY SIGN.

The alphanumeric literal in
the CURRENCY SIGN clause is
not allowed as the currency
sign either because the
literal is longer than one
character or because it is an
invalid COBOL currency sign.
The CURRENCY SIGN clause is
ignored and the currency sign
defaults to the dollar sign.

656

SPECIALNAMES CLAUSE INVALID.

An unrecognizable word
appears in a position where a
SPECIAL-NAMES paragraph
clause keyword is expected.
All source text is skipped up
to the next recognizable
keyword.

657

SYNTAX ERROR IN
DECIMALPOINT CLAUSE.

The keyword COMMA is omitted
in the DECIMAL-POINT IS COMMA
clause of the SPECIAL-NAMES
paragraph. The clause is
ignored.

660

.AFTER. MISSING IN
.USE. STATEMENT. ASSUMED.

The keyword AFTER is omitted
in the USE statement. AFTER
is assumed present and
processing continues.

661

NO .ERROR. OR .EXCEPTION.
IN .USE. ASSUMED.

One of the keywords ERROR or
EXCEPTION is omitted in the
USE statement. The missing
keyword is assumed present
and processing continues.

662

NO KNOWN CLAUSES IN
SPECIALNAMES.

The SPECIAL-NAMES paragraph
contains no valid clauses.
This is an observation only.

663

REDUNDANT .USE. COVERAGE.
PREVo .USE. IGNORED.

Multiple USE statements have
referenced the same file.
The last USE statement
specified is then applied to
the referenced file.
Fatal.

664

UNKNOWN OPEN MODE IN
.USE. STATEMENT.

An unrecognizable OPEN mode
option was specified in the
USE statement.
Fatal.

665

GROUP ITEM HAS BEEN CALLED
FILLER.

A FILLER item cannot have any
elementary items subordinate
to it. The compiler replaces
the FILLER declaration with a
system-defined name and
proceeds with the processing
of the newly named group
item. The system-defined name
is transparent and inaccessible to the user.

G-45

DIAGNOSTIC ERROR MESSAGES
666

MISSING ENVIRONMENT
DIVISION.

The program does not contain
an ENVIRONMENT DIVISION. The
compiler skips to the DATA
DIVISION and continues
processing.

667

DIVISION BY ZERO.

The divisor of a DIVIDE
statement is a literal of
zero value. The error is
ignored.

670

VALUE NOT PERMITTED WITH
THIS ITEM.

A VALUE clause is recognized
in a data description entry
which contains a REDEFINES or
an OCCURS clause. This is
illegal. The VALUE clause is
ignored.

671

INVALID CONSTANT OR
LITERAL FOLLOWING .ALL ..

The reserved word ALL is not
followed by a non-numeric
literal or a figurative
constant. Thus, this is not
a valid ALL literal. ALL is
ignored and processing
continues.

672

BAD FILENAME IN .USE.
STATEMENT.

An unrecognizable word
appears where a filename is
expected in the USE
statement. Fatal.

673

FILE NOT CLOSED.

The referenced file was
OPENed but there was no CLOSE
statement detected for this
file in the program.

674

SUBJECT OF .ALTER. IS
SECTION NAME.

The ALTER statement references
a section name. Only paragraph
names may be altered. If this
statement is reached during
execution, the program will be
aborted.

675

FILE COVERED BY CONFLICTING
USE PROCEDURE.

There was more than one
conflicting USE procedure
specified for the referenced
file.
Fatal.

676

DATAITEM LENGTH EXCEEDS 4095
CHARACTERS.

An elementary or group item
is longer than the
implementation limit of 4095
characters. The compiler
declares the data item with a
length of 4095 characters and
proceeds with the processing
of the data item.

677

SUPPLIED VALUE INVALID FOR
NUM ITEM. IGNORED.

The VALUE clause specifies
invalid value initialization
for a numeric data item. The
compiler ignores the VALUE
clause.

G-46

DIAGNOSTIC ERROR MESSAGES
700

FILE ACCESSED BY VERB
REQUIRING REL. OR lOX ORG.

A file whose organization is
SEQUENTIAL is referenced by
the START or DELETE verbs or
by an I/O verb which has the
INVALID KEY clause specified.
This is illegal. In all
these cases, the referenced
file must have RELATIVE or
INDEXED organization. Fatal.

701

FILE ACCESSED BY VERB REQ.
SEQUENTIAL ORG.

A file whose organization is
RELATIVE or INDEXED is
referenced by an I/O verb
which has the AT EOP or
ADVANCING clauses specified.
This is illegal. The
referenced file must have
SEQUENTIAL organization.
Fatal.

702

VERB NOT IMPLEMENTED.

An ANS 1974 COBOL verb
appears that is not
implemented in this release
of the compiler. The
compiler scans to another
verb, period, or word in Area
A.

704

OCCURS ILLEGAL FOR 01
OR 77 ITEM. IGNORE.

An OCCURS clause is specified
for an 01 or 77 level
data-name. The compiler
ignores the OCCURS clause.

705

.ACCEPT FROM. OBJECT NOT
IN SPECIALNAMES.

The mnemonic name used in the
ACCEPT statement was not
defined in the SPECIAL-NAMES
paragraph. Fatal.

706

ACCEPT IDENTIFIER INVALID.

The word following the ACCEPT
verb is not a data-name or is
a data-name which has nonDISPLAY usage or invalid
class. Fatal.

707

VERB OR CONDo CLAUSE
CONFLICTS WITH FILE ACCESS.

There is a conflict between
the ACCESS MODE of the
referenced file and the I/O
verbs and/or condition
clauses which reference this
file. Fatal.

710

DATANAME AFTER .GO
DEPENDING. INVALID.

The word following the
DEPENDING ON phrase of the GO
TO statement is not a
data-name or is a data-name
which has INDEX usage. This
is illegal. Fatal.

711

INVALID CLASS OF DATANAME
AFTER .GO DEPENDING.

The data-name following the
DEPENDING ON phrase of the GO
TO statement is not a numeric
data-name or is a numeric,
non-integer data-name. This
is illegal. Fatal.
G-47

DIAGNOSTIC ERROR MESSAGES
712

.DISPLAY UPON. OBJECT
NOT IN SPECIALNAMES.

The mnemonic name used in the
DISPLAY statement was not
defined in the SPECIAL-NAMES
paragraph. Fatal.

713

.DISPLAY. OPERAND IS INVALID.

A data item in the DISPLAY
statement has invalid class
or USAGE.

714

MISSING OR INVALID OPERAND.
OF .MULTIPLY ..

One of the operands of the
MULTIPLY statement either is
missing or is invalid.
Fatal.

715

ILLEGAL .MULTIPLY. DUE
TO MISSING .BY ..

The keyword BY is omitted in
the MULTIPLY statement.
Fatal.

716

MISSING OR INVALID OPERAND
OF .DIVIDE ..

One of the operands of the
DIVIDE statement either is
missing or is invalid.
Fatal.

717

ILLEGAL .DIVIDE. DUE TO
MISSING .BY. OR .INTO ..

One of the keywords BY or
INTO is omitted in the DIVIDE
statement. Fatal.

720

.GIVING. OPTION OF .DIVIDE.
MISSING.

The GIVING option must be
specified in a DIVIDE
statement when one of the
following syntactic elements
is present in the DIVIDE
statement: (1) a numeric
literal follows the keyword
INTO or (2)the keyword BY
is specified.
In this DIVIDE
statement, the GIVING option
was omitted while one of the
two aforementioned syntactic
elements was present.
Fatal.

721

MISSING OR INVALID OPERAND OF
.ADD. OR .COMPUTE.

One of the operands of an ADD
or COMPUTE statement is
either missing or is invalid.
Fatal.

722

.TO. OR .GIVING. MISSING
FROM .ADD ..

One of the keywords TO or
GIVING is omitted in the ADD
statement. Fatal.

723

MISSING OR INVALID
OPERAND OF SUBTRACT.

One of the operands in the
SUBTRACT statement either is
missing or is invalid.
Fatal.

724

FILE NEEDS DYNAMIC ACCESS
FOR .READ NEXT ..

In a READ NEXT statement, the
referenced file must have
ACCESS MODE IS DYNAMIC
specified in the FILE-CONTROL
paragraph.
Fatal.

G-48

DIAGNOSTIC ERROR MESSAGES
725

BAD PROCEDURE NAME IN
.PERFORM •.

A missing or invalid
procedure-name is recognized
in the PERFORM statement.
Fatal.

726

ILLEGAL OPERAND OF .TIMES.
OPTION OF .PERFORM •.

The TIMES operand of the
PERFORM statement is not
a numeric integer data-name
or numeric integer literal.
The compiler assumes a value
of 1 for the TIMES operand.

727

.TIMES. MISSING FROM
.PERFORM .. ASSUMED.

The PERFORM statement does
not contain the keyword TIMES
but does contain the
iteration value required to
execute the PERFORM
correctly. The keyword TIMES
is assumed present.

730

PROCEDURE NAME OMITTED
IN .ALTER .•

A valid procedure-name was
not recognized in the ALTER
statement. Fatal.

731

ILLEGAL .ALTER. DUE
TO MISSING .TO ..

The keyword TO was not
recognized in the ALTER
statement. Fatal.

732

FILE HAS VAR. SIZE RECS.
.READ INTO. ILLEGAL.

It is illegal for the READ
INTO statement to reference a
file which has multiple
record descriptions of
different lengths.
Fatal.

733

FILE ACCESSED BY VERB
REQUIRING .LINAGE.

A file is accessed by an I/O
verb which did not have a
LINAGE clause in its
specification. Fatal.

734

.DELETE. OR .REWRITE.
WITHOUT INV. KEY OR USE.

A DELETE or REWRITE statement
references a file for which
there was no USE procedure
specified and for which the
INVALID KEY option was not
specified in that DELETE or
REWRITE statement.
Fatal.

735

OPEN MODE OR NO READ
PROHIBITS REWRITE OR DELETE.

A DELETE or REWRITE statement
references a file which was
not OPENed in the proper mode
or which has no READ
statement referencing it in
the program.
Fatal.

736

.START. CONFLICTS WITH OPEN
MODE.

A START statement references
a file which was not opened
in the proper mode. Fatal.

737

.WRITE. CONFLICTS WITH OPEN
MODE.

A WRITE statement references
a file which was not opened
in the proper mode.
Fatal.

G-49

DIAGNOSTIC ERROR MESSAGES
740

.READ. CONFLICTS WITH OPEN
MODE.

A READ statement references
a file which is only opened
in OUTPUT or EXTEND
mode. Fatal.

741

USE NOT IN DECLAR. OR NOT
FOLLOWING SECTION NAME.

The USE statement is not in
the DECLARATIVES section of
the PROCEDURE DIVISION or is
not immediately following a
section name inside the
DECLARATIVES. Fatal.

742

MORE THAN 255 ALTERNATE
KEYS. IGNORED.

The maximum of 255 ALTERNATE
KEYS has been exceeded. The
clause is ignored.

743

INTEGER IN SWITCH CLAUSE
INVALID OR OMITTED.

A SWITCH clause of the
SPECIAL-NAMES paragraph
either contains an invalid
numeric integer or has
omitted the integer in its
specification. A SWITCH
clause integer, for example,
n must fall in the decimal
range 1<=n<=16. The SWITCH
clause is ignored.

744

.IS. OMITTED IN SPECIALNAMES.
ASSUMED PRESENT.

The required keyword IS is
omitted in a clause of the
SPECIAL-NAMES paragraph.
IS
is assumed present and
processing continues.

745

DEVICE MNEMONIC OMITTED IN
SPECIALNAMES.

A valid device mnemonic-name
is not recognized in one of
the CONSOLE, LINE-PRINTER,
CARD-READER, PAPER-TAPEREADER, or PAPER-TAPE-PUNCH
clauses of the SPECIAL-NAMES
paragraph. All source text is
skipped up to the next
recognizable keyword.

746

TERMINATOR OMITTED IN
SPECIALNAMES.

The SPECIAL-NAMES paragraph
is not terminated by a
period. The period is
assumed present and
processing continues.

747

SUBJECT OF .ALTER. NOT .GO
TO •. ALTER IGNORED.

The paragraph referenced by
this ALTER statement does not
contain a GO TO statement
as its first statement.
The ALTER statement
is ignored.

750

KEYWORD OMITTED IN
.SWITCH. CLAUSE.

One of the keywords OFF or ON
is omitted in the SWITCH
clause of the SPECIAL-NAMES
paragraph. The SWITCH clause
is ignored.

G-50

DIAGNOSTIC ERROR MESSAGES
751

CONDITION NAME MISSING
IN .SWITCH. CLAUSE.

A valid condition-name is not
recognized in the SWITCH
clause of the SPECIAL-NAMES
paragraph. The SWITCH clause
is ignored.

752

.CR. OR .DB. NOT AT RIGHT
END OF PICTURE.

The PICTURE symbol CR or DB
does not appear at the
right end of the PICTURE
string. The compiler ignores
the user-supplied PICTURE and
declares the data-name
alphanumeric with a "PICTURE
X" DECLARATION.

753

.CR. OR .DB. USED WITH
SIGNED ITEM.

Both the PICTURE symbols, CR
or DB, and a sign, + or -,
appear in the same PICTURE.
The compiler ignores the
user-supplied PICTURE and
declares the data-name
alphanumeric with a "PICTURE
X" declaration.

754

MULTIPLE DEFINITION OF
SWITCH. FIRST USED.

Multiple definitions of a
COBOL switch are detected in
the SPECIAL-NAMES paragraph.
All but the first definition
of SWITCH are ignored.

755

.SENTENCE. ASSUMED AFTER
. NEXT .•

The keyword NEXT is not
followed by the keyword
SENTENCE. SENTENCE is
assumed present and
processing continues.

756

SUBSCRIPT NOT NUMERIC
INTEGER.

A data-name used as a
subscript is not numeric
in class. A default value of
1 is assumed as the
subscript.

760

ILLEGAL SYNTAX IN
.DIVIDE. STATEMENT.

The compiler detects illegal
syntax in the DIVIDE
statement. Fatal.

761

INDEXED FILE REQUIRES
. RECORD KEY. PHRASE.

Self explanatory .

762

RECORD KEY INVALID FOR THIS
FILE.

The RECORD KEY clause is only
valid for indexed files.

763

.ALT RECORD KEY. INVALID
FOR FILE. IGNORED.

The ALTERNATE RECORD KEY
clause is only valid for
indexed files.

764

READ-AHEAD. OR. WRITE-BEHIND.
NOT SUPPORTED.

The APPLY READ-AHEAD or APPLY
WRITE-BEHIND clauses are not
supported in this version of
the compiler. The APPLY
clause is ignored.

G-51

DIAGNOSTIC ERROR MESSAGES

765

INTEGER INVALID IN. RESERVE
AREA. CLAUSE.

The number of buffer areas
rese~ved by the RESERVE clause
is invalid. The clause is
ignored and a default of one
area for SEQUENTIAL and
RELATIVE or two areas for
INDEXED is supplied.

766

BAD VALUE IN BLOCK CONTAINS
CLAUSE.

The numeric literal in the
BLOCK clause is less than the
sum of the record size, the
record header size, and the
bucket header size. The BLOCK
CONTAINS clause is ignored.

767

VALUE IN. BLOCK CONTAINS.
CLAUSE IS ROUNDED UP

The numeric literal in the
BLOCK clause is not a multiple
of 512. The value is rounded
up to the next even multiple
of 512.

770

EXPECTED .RECORD KEY.
DATANAME NOT DEFINED.

The data-name given in a
RECORD KEY clause has not been
defined in the DATA DIVISION.

771

.RECORD KEY. DATANAME HAS
INVALID CLASS.

A data-name referenced in a
RECORD KEY or ALTERNATE RECORD
KEY phrase of a SELECT clause
in the FILE-CONTROL paragraph
is defined in the FILE SECTION
with non-alphanumeric class.

772

.RECORD KEY. DATA ITEM
CANNOT BE VARIABLE LENGTH.

A data-name referenced in a
RECORD KEY or ALTERNATE RECORD
KEY phrase of a SELECT clause
in the FILE-CONTROL paragraph
is defined in the FILE SECTION
as an item whose size is
variable.

773

.RECORD KEY. ITEM NOT
DEFINED IN RECORD OF FILE

A data-name referenced in a
RECORD KEY or an ALTERNATE
RECORD KEY phrase of a SELECT
clause is not defined in the
record description of the
associated file.

774

FILE ACCESSED BY VERB
REQUIRING INDEXED ORG.

A file whose organization is
SEQUENTIAL or RELATIVE is
referenced by the READ verb
which has the KEY IS data-name
phrase specified. This is
illegal. The referenced file
must have INDEXED
organization. FATAL.

775

.KEY IS. PHRASE INVALID
FOR SEQUENTIAL .READ.

Either the file has ACCESS
SEQUENTIAL or the READ
statement contains the word
NEXT. In either case the KEY
IS data-name phrase is
illegal. FATAL.

G-S2

DIAGNOSTIC ERROR MESSAGES
776

INVALID DATANAME IN .KEY
IS. PHRASE.

The KEY IS phrase of the READ
statement was not followed by
a data-name. FATAL.

777

.KEY IS. PHRASE NOT FOLLOWED
BY RECORD KEY.

The data-name following the
KEY IS phrase of the READ
statement is not a RECORD KEY
or ALTERNATE RECORD KEY for
the referenced file. The
RECORD KEY data-name
is assumed.

1000 VARIABLE OCCURRENCES TABLE
MUST END RECORD.

A COBOL table declared with
the DEPENDING ON phrase may
only be followed, within the
record, by data description
entries whose level-numbers
are strictly greater than
the level-number of this
table entry. The compiler
ignores the remainder of the
record descriptor from the
point where the error is
detected. Fatal.

1001 .ASCENDING. OR .DESCENDING.
DATANAME EXPECTED.

A user-defined data-name was
expected, but not found, in
the ASCENDING KEY IS or
DESCENDING KEY IS phrase.

1002 RENAMED OATAITEMS NOT IN
CURRENT RECORD.

The data items specified
after the RENAMES keyword
(i.e., the data items being
renamed) are defined outside
of the current record
description. This is syntactically invalid. The compiler
ignores the entire RENAMES
data description entry.

1003 MAXIMUM OCCURRENCES NOT
GREATER THAN MINIMUM.

In a variable occurrence
table declaration, the
integer following the
keyword TO (i.e., the
maximum) must be strictly
greater than the integer
following the keyword OCCURS
(i.e., the minimum). The
compiler assumes the maximum
value to be equal to the
minimum value plus one.

1004 .DEPENDING. IS OMITTED IN THE
.OCCURS. CLAUSE.

In a variable occurrence
table declaration, the
keyword DEPENDING has
been omitted. The compiler
ignores the remainder of the
OCCURS clause and treats the
table declaration as an
ordinary COBOL table.

1005 A DATANAME MUST FOLLOW THE
.DEPENDING. KEYWORD.

In a variable occurrence
table declaration, a valid
data-name is not found
G-53

DIAGNOSTIC ERROR MESSAGES
following the keyword
DEPENDING. The compiler
ignores the remainder of the
OCCURS clause and treats the
table declaration as an
ordinary COBOL table.
1006 .OCCURS DEPENDING.
SUBORDINATE TO AN .OCCURS.

The compiler detects a table
declaration with a DEPENDING
ON phrase subordinate to a
group item which has an
OCCURS clause. This is
syntactically illegal. The
compiler ignores the
DEPENDING ON phrase and
treats the declaration as an
ordinary COBOL table.

1007 MAXIMUM NO. TABLE OCCURRENCES
MUST BE POSITIVE.

In a variable occurrence
table declaration, the
integer following the keyword
TO (i.e., the maximum) must
be greater than zero. The
compiler assumes the maximum
value to be equal to the
integer value following the
keyword OCCURS (i.e., the
minimum) plus one.

1010 EXPECTED .DEPENDING ON.
DATANAME NOT DEFINED.

The data-name referenced in a
DEPENDING ON phrase was not
defined in the DATA DIVISION.
Fatal.

1011 EXPECTED .ASCENDING KEY.
DATANAME NOT DEFINED.

The data-name referenced in
an ASCENDING KEY phrase was
not defined in the DATA
DIVISION. Fatal.

1012 EXPECTED .DESCENDING KEY.
DATANAME NOT DEFINED.

The data-name referenced in a
DESCENDING KEY phrase was not
defined in the DATA DIVISION.
Fatal.

1013 .DEPENDING ON. DATANAME NOT A
NUMERIC INTEGER.

The data-name referenced in a
DEPENDING ON phrase was not
declared as a numeric integer
in the DATA DIVISION. Fatal.

1014 .RENAMES. APPLIED TO AN
INVALID LEVEL OF DATA.

The RENAMES clause specifies
the renaming of data items
whose level number is an 01,
66, 77, or 88. This is syntactically invalid. The
compiler ignores the entire
RENAMES data description
entry.

1015 .DEPENDING ON. DATANAME
DETECTED WITHIN TABLE.

The compiler detects a
data-name, which follows a
DEPENDING ON phrase and which
defines the current number of
occurrences in a variable
occurrence table, to have its
G-54

DIAGNOSTIC ERROR MESSAGES
storage allocated within the
range of the table. This is
syntactically illegal. Fatal.
1016 .OCCURS. CLAUSE ON A TABLE
KEY DATANAME.

The compiler detects the
presence of an OCCURS clause
on a data item which has been
declared as an ASCENDING or
DESCENDING KEY. This is
syntactically illegal. Fatal.

1017 .SEARCH ALL. TABLE DOES
NOT HAVE KEYS.

The table being searched by
by SEARCH ALL statement must
have the ASCENDING KEY or
DESCENDING KEY phrase
specified in its declaration.
Fatal.

1020 IMPERATIVE STATEMENT EXPECTED
DURING .SEARCH.

A period or a non-imperative
statement was found where the
SEARCH statement environment
is expecting an imperative
statement. Fatal.

1021 KEYS SPECIFIED FOR .SEARCH
ALL. NOT DENSE.

When a key is referenced for
the SEARCH ALL statement, all
preceding keys in the KEY
clause of the table declaration must also be referenced.
Fatal.

1022 .WHEN. EXPECTED BUT NOT FOUND
IN .SEARCH.

The compiler expected but
failed to recognize the WHEN
keyword while compiling the
SEARCH statement. This SEARCH
statement is considered
syntactically invalid. Fatal.

1023 THE KEYWORD .WHEN. ILLEGAL IN
THIS CONTEXT.

The compiler detects the
presence of the keyword WHEN
outside the environment of
the SEARCH statement. This is
syntactically invalid. Fatal.

1024 THE KEYWORD .SEARCH. ILLEGAL
IN THIS CONTEXT.

While compiling a SEARCH
statement, the compiler
detects the presence of
another SEARCH statement in
the environment of the
original SEARCH statement.
The second SEARCH statement
is detected at a point where
an imperative statement is
expected. This is syntactically invalid. Fatal.

1025 KEY MUST BE SUBSCRIPTED BY
FIRST INDEX OF TABLE.

The SEARCH ALL statement
requires that the key referenced on the left side of the
simple condition must be subscripted by the first indexname of the table being
searched. Fatal.

G-55

DIAGNOSTIC ERROR MESSAGES
1026 THE KEYWORD .SENTENCE.
EXPECTED AFTER .NEXT ..

The keyword SENTENCE was not
detected after the NEXT
keyword during the
compilation of a SEARCH
statement. Fatal.

1027 TABLE NAME NOT FOUND AFTER
.SEARCH. VERB.

The compiler failed to
recognize a valid table data
item after the keyword SEARCH
or SEARCH ALL. Fatal.

1030 INVALID TABLE REFERENCE IN
.SEARCH. STATEMENT.

The table data item reference
following the SEARCH or
SEARCH ALL verbs must have
both the INDEXED BY and the
OCCURS clauses specified in
its declaration. Fatal.

1031 DATANAME EXPECTED AFTER
.VARYING. IN .SEARCH.

No data-name reference was
found after the VARYING
keyword in the SEARCH statement being compiled. Fatal.

1032 .VARYING. ITEM MUST BE INDEX
OR INTEGER.

The data-name reference
following the VARYING keyword
must be an index data item,
an index-name, or an
elementary numeric integer
data-name reference. Fatal.

1033 .SEARCH ALL. DATA ITEM
IS NOT A KEY.

The data item referenced on
the left side of the SEARCH
ALL simple condition must be
declared as an ASCENDING or
DESCENDING KEY. Fatal.

1034 DATA ITEM NOT A KEY FOR THIS
.SEARCH. TABLE.

The data item referenced on
the left side of the SEARCH
ALL simple condition is not
a key for the table being
searched. This is considered
illegal. Fatal.

1035 .RENAMES. SPECIFIES RENAMING
OF A COBOL TABLE.

The RENAMES clause specifies
the renaming of a datum which
has an OCCURS clause in its
declaration or is subordinate
to another datum having an
OCCURS clause. This is
syntactically invalid. The
compiler ignores the entire
RENAMES data description
entry.

1036 .RENAMES. APPLIED TO VARIABLE
LENGTH DATAITEM.

The compiler detects an
application of the RENAMES
clause to a range of data
items which contains a data
item whose length is variable
at run-time. This data item
is variable in length because
is has a subordinate data
item whose data description
entry contains an OCCURS

G-56

DIAGNOSTIC ERROR MESSAGES
DEPENDING ON clause. The
application of the RENAMES
clause to such a range of
data items is syntactically
invalid. The compiler ignores
the entire RENAMES data
description entry.
1037 DATANAME OMITTED AFTER
66 LEVEL NUMBER.

The data-name declaration is
omitted after a 66 level
number. The compiler ignores
the entire RENAMES data
description entry.

1040 .RENAMES. OMITTED IN LEVEL 66
DESCRIPTION ENTRY.

The RENAMES keyword is
omitted in a level 66 data
description entry. The
compiler ignores the entire
level 66 data description
entry.

1041 SEARCH KEY NOT
SUBORDINATE TO TABLE.

The compiler detects an
ASCENDING or DESCENDING dataname key which is not defined
as a data item subordinate to
the associated SEARCH table.
This is syntactically
invalid.

1042 INVALID OR MISSING DATANAME
AFTER .RENAMES ..

The data-name is missing
after the RENAMES keyword or,
if present, is not recognized
as a valid data item
previously defined. The
compiler ignores the entire
RENAMES data description
entry.

1043 .OCCURS. ITEM NOT ALLOWED
BETWEEN TABLE AND KEY.

The compiler detects a data
item declared with an OCCURS
clause "sandwiched" between
the declaration of another
COBOL table and its
associated SEARCH key.
This is syntactically
invalid.

1044 .RENAMES. SPECIFIES INVALID
NOMENCLATURE RANGE.

In processing the RENAMES
clause, the compiler detects
an invalid nomenclature range
specified by identical datanames following the RENAMES
and THRU keywords,
respectively. This is
syntactically invalid. The
compiler ignores the entire
RENAMES data description
entry.

1045 .RENAMES. SPECIFIES STORAGE
OVERLAP ON LEFT END.

In processing the RENAMES
clause, the compiler detects
the condition in which the
beginning of the storage
allocated to the data-name
G-57

DIAGNOSTIC ERROR MESSAGES

after the THRU keyword is
positionally to the left of
the beginning of the storage
allocated to the data-name
after the RENAMES keyword.
This is syntactically
invalid. The compiler
ignores the entire RENAMES
data description entry.
1046 INVALID OR MISSING DATANAME
AFTER .THRU ..

In specifying the RENAMES
clause, a data-name is
missing after the THRU
keyword or, if present, is
not recognized as a valid
data item previously defined.
The compiler ignores the
entire RENAMES data
description entry~

1047 INVALID OR MISSING DATANAME
AFTER CORRESPONDING.

In the processing of an ADD,
SUBTRACT, or MOVE
CORRESPONDING statement, the
compiler detects the omission
of a valid data-name
reference after the CORRESPONDING keyword. Fatal.

1050 .TO. OR .FROM. OMITTED IN
.CORRESPONDING.

In the processing of an ADD,
SUBTRACT, or MOVE CORRESPONDING statement, the
compiler detects the omission
of the TO or FROM keyword.
Fatal.

1051 INVALID OR MISSING DATANAME
AFTER .TO. OR .FROM.

In the processing of an ADD,
SUBTRACT, or MOVE
CORRESPONDING statement,
the compiler detects the
omission of a valid data-name
reference after the keyword
TO or FROM. Fatal.

1052 NO OBJECT CODE PRODUCED FOR
.CORRESPONDING.

In the processing of an ADD,
SUBTRACT, or MOVE
CORRESPONDING statement,
the compiler produced no
object code. No object code
is produced because no
"correspondence" was found
between the two group items
referenced in the COBOL
statement containing the
CORRESPONDING option. This
diagnostic is informational
only.

G-58

DIAGNOSTIC ERROR MESSAGES
1053 GROUP ITEM NOT REFERENCED IN
.CORRESPONDING.

In the processing of an ADD,
SUBTRACT, or MOVE
CORRESPONDING statement,
the compiler discovers that
one of the references is a
reference to an elementary
item. This is syntactically
invalid. Fatal.

1054 LEVEL 66 REFERENCE DISALLOWED
IN .CORRESPONDING.

In the processing of an ADD,
SUBTRACT, or MOVE
CORRESPONDING statement, the
compiler detects a reference
to a data-name declared at
level 66. This is an invalid
reference. Fatal.

1055 .FILE STATUS. ITEM DEFINED IN
.FILE SECTION.

A data-name referenced in a
FILE STATUS phrase of a
SELECT clause is defined in
the FILE SECTION of the
COBOL program. The compiler
ignores this error and
continues to process the
FILE STATUS data-name.

1056 INCOMPATIBLE OPERANDS FOUND
IN .CORRESPONDING.

In the processing of an ADD,
SUBTRACT, or MOVE
CORRESPONDING statement, the
compiler detects a pair of
CORRESPONDING data items
which are incompatible. This
diagnostic is informational
only.

1057 EMPTY .GO TO. WAS NOT THE
SUBJECT OF AN .ALTER ..

A GO TO statement without a
procedure reference was
detected. The empty GO TO is
not the subject of an ALTER
statement. FATAL.

1060 QUALIFIER OMITTED IN
PROCEDURE REFERENCE.

A section name is omitted
after the keyword OF or IN in
a qualified procedure
reference of the COBOL
statement being compiled.
Fatal.

1061 INCONSISTENT NUMBER OF
ARGUMENTS IN .CALL •.

The subprogram referenced in
this CALL $tatement has been
referenced before. The number
of arguments in the earlier
CALL differs from the number
in the current CALL.

1062 PARAGRAPH WITHOUT SECTION
PRECEDES THIS SECTION.

In a COBOL program, if one
paragraph is in a section,
then all paragraphs must be in
sections. In this $ource
program, a paragraph not
within a section has been
detected, preceding this
section in the source program.

G-59

DIAGNOSTIC ERROR MESSAGES

1063 DUPLICATE PARAGRAPH
NAME DETECTED.

In a section of the Procedure
Division, a paragraph name is
defined more than once which,
if referenced, is not
uniquely referenceable, even
with qualification.

1064 REFERENCE TO UNDEFINED
PROCEDURE NAME.

The compiler detects a
reference to an undefined
procedure name in the
PROCEDURE DIVISION. This is
syntactically invalid.

1065 UNDEFINED PROCEDURE QUALIFIER
REFERENCE.

The compiler detects a
qualified procedure reference
which contains an undefined
qualifier in the PROCEDURE
DIVISION. This is syntactically invalid.

1066 ILLEGAL PROCEDURE NAME
REFERENCE.

The compiler detects an
invalid procedure name
reference in the PROCEDURE
DIVISION. This is syntactically invalid.

1067 AMBIGUOUS PROCEDURE
NAME REFERENCE.

The compiler detects a
reference in the PROCEDURE
DIVISION to a procedure name
which is not uniquely
referenceable, even through
qualification. This is
syntactically invalid.

1070 PARAGRAPH NAME
DISALLOWED AS QUALIFIER.

The compiler detects a
qualified procedure reference
in the PROCEDURE DIVISION
in which the qualifier is a
paragraph name. This is
syntactically invalid.

1071 SECTION NAME REFERENCE MAY
NOT BE QUALIFIED.

The compiler detects a
qualified procedure reference
in the PROCEDURE DIVISION
in which a section name is
qualified by another section
name. This is syntactically
invalid.

1072 AMBIGUOUS PARAGRAPH
NAME REFERENCE.

The compiler detects a
reference in the PROCEDURE
DIVISION to a paragraph name
which is not uniquely
referenceable, even through
qualification.

G-60

DIAGNOSTIC ERROR MESSAGES

1073 POSSIBLE .PERFORM.
RANGE VIOLATION.

The compiler detects a
PERFORM THRU statement in
which the procedure name
following the THRU keyword
is defined in the text of
the Procedure Division
before the procedure name
following the PERFORM
keyword. This condition may
potentially represent a logic
problem in the COBOL program
being compiled, although not
necessarily so.

1074 NUMERIC PROCEDURE NAME
EXCEEDS 30 CHARACTERS.

A numeric string which
appears to be a numeric
procedure name exceeds 30
characters in length. The
string is truncated on the
right to 30 characters and
processing of the numeric
procedure name continues.

1075 NUMERIC PROCEDURE NAME
CONTAINS DECIMAL POINT.

A numeric string which
appears to be a numeric
procedure name contains a
decimal point. This is
syntactically invalid. The
compiler ignores the presence
of the decimal point and
proceeds with the processing
of the numeric procedure
name.

1076 .RELATIVE KEY. ITEM DEFINED
IN RECORD OF FILE.

A data-name referenced in a
RELATIVE KEY phrase of a
SELECT clause is defined in
the record description of the
associated file. The compiler
ignores this error and
continues to process the
RELATIVE KEY data-name.

1077 NO. OF AREAS DEFAULTS TO MAX.
FOR FILE TYPE

The number of buffer areas
reserved by the RESERVE clause
is greater than the maximum
allowed for the file
organization. Instead, the
clause will cause two areas to
be allocated for a sequential
file and one for a relative
file.

G-6l

APPENDIX H
RECORD MANAGEMENT SERVICES ERROR CODES

Any of the following I/O error conditions could occur during COBOL
program execution.
The codes appear in a COBOL message in the form
shown below:
"RECORD MANAGEMENT SERVICES ERROR - nn"
(nn represents the Record Management Services error code).
These error codes are listed in Table H-l.
Table H-l
RMS System Standard Error Codes
Value
-16
-32
-48
-64
-80
-96
-112
-128
-144
-160
-176
-192
-208
-224
-232
-240
-256
-272
-288
-304

-320
-352
-368
-384
-400
-416
-432
-448
-464

Meaning
OPERATION ABORTED(STV=ER$STK/MAP)
FI1ACP COULD NOT ACCESS FILE{STV=SYS ERROR CODE)
"FILE" ACTIVITY PRECLUDES OPERATION
BAD AREA ID{STV=@XAB)
ALIGNMENT OPTIONS ERROR(STV=@XAB)
ALLOCATION QUANTITY TOO LARGE
NOT ANSI "D" FORMAT
ALLOCATION OPTIONS ERROR{STV=@XAB)
INVALID{I.E. SYNCH) OPERATION AT AST LEVEL
ATTRIBUTE READ ERROR(STV=SYS ERR CODE)
ATTRIBUTE WRITE ERROR(STV=SYS ERR CODE)
BUCKET SIZE TOO LARGE(FAB}
BUCKET SIZE TOO LARGE(STV=@XAB)
"BLN" LENGTH ERROR (RAB/FAB)
BEGINNING OF FILE DETECTED
PRIVATE POOL ADDRESS NOT MULTIPLE OF "4"
PRIVATE POOL SIZE NOT MULTIPLE OF "4"
INTERNAL RMS ERROR CONDITION DETECTED
CAN'T CONNECT RAB
$UPDATE-KEY CHANGE A KEY WITHOUT HAVING ATTRIBUTE OF
XB$CHG SET
BUCKET FORMAT CHECK-BYTE FAILURE
INVALID OR UNSUPPORTED "COD" FIELD(STV=@XAB)
F11-ACP COULD NOT CREATE FILE(STV=SYS ERR CODE)
NO CURRENT RECORD(OPERATION NOT PRECEDED BY GET/FIND)
FI1-ACP DEACCESS ERROR DURING "CLOSE"(STV=SYS ERR CODE)
DATA "AREA" NUMBER INVALID(STV=@XAB)
RFA-ACCESSED RECORD WAS DELETED
BAD DEVICE, OR INAPPROPRIATE DEVICE TYPE
ERROR IN DIRECTORY NAME

H-l

RECORD MANAGEMENT SERVICES ERROR CODES

Table H-l (Cont.)
RMS System Standard Error Codes
Value
-480
-496
-512
-520
-528
-544
-560
-576
-592
-608
-616
-624
-640
-656
-672
-680
-688
-704
-720
-736
-752
-768
-784
-800
-816
-832
-848
-864
-880
-896
-912
-928
-944
-960
-976
-992
-1008
-1024
-1040
-1048
-1056
-1072
-1088
-1104
-1120
-1136
-1152
-1168
-1184
-1216
-1232
-1248
-1264
-1280
-1296

Meaning
DYNAMIC MEMORY EXHAUSTED
DIRECTORY NOT FOUND
DEVICE NOT READY
DEVICE POSITIONING ERROR(STV=SYS ERR CODE)
"DTP" FIELD INVALID(STV=@XAB)
DUPLICATE KEY DETECTED, XB$DUP ATTRIBUTE NOT SET
RSX-FIIACP ENTER FUNCTION FAItED(STV=SYS ERR CODE)
OPERATION NOT SELECTED IN "ORG$" MACRO
END-OF-FILE
EXPANDED STRING AREA TOO SHORT
FILE EXPIRATION DATE NOT YET REACHED
FILE EXTEND FAILURE(STV=SYS ERR CODE)
NOT A VALID FAB("BID" NOT=FB$BID)
ILLEGAL FAC FOR REC-OP,O, OR FB$PUT NOT SET FOR "CREATE"
FILE ALREADY EXISTS
INVALID FILE-ID
INVALID FLAG-BITS COMBINATION(STV=@XAB)
FILE IS LOCKED BY OTHER USER
PSX-FIIACP "FIND" FUNCTION FAILED(STV=SYS ERR CODE)
FILE NOT FOUND
ERROR IN FILENAME
INVALID FILE OPTIONS
DEVICE/FILE FULL
INDEX "AREA" NUMBER INVALID(STV=@XAB)
INDEX NOT INITIALIZED(STV ONLY,STS=ER$RNF)
INVALID IFI VALUE
MAX NUM(254) AREAS/KEY XABS EXCEEDED(STV=@XAB)
$INIT MACRO NEVER ISSUED
OPERATION ILLEGAL, OR INVALID FOR FILE ORG.
ILLEGAL RECORD ENCOUNTERED (SEQ. FILES ONLY)
INVALID lSI VALUE, ON UNCONNECTED RAB
BAD KEY BUFFER ADDRESS (KBF=O)
INVALID KEY FIELD{KEY=O/NEG)
INVALID KEY-OF-REFERENCE($GET/$FIND)
KEY SIZE TOO LARGE(IDX)/NOT=4(REL)
LOWEST-LEVEL-INDEX "AREA" NUMBER INVALID(STV=@XAB)
NOT ANSI LABELED TAPE
LOGICAL CHANNEL BUSY
LOGICAL CHANNEL NUMBER TOO LARGE
LOGICAL EXTEND ERROR, PRIOR EXTEND STILL VALID(STV=@XAB)
"LOC" FIELD INVALID(STV=@XAB)
BUFFER MAPPING ERROR
FIIACP COULD NOT MARK FILE FOR DELETION (STV=SYS ERR CODE)
MRN VALUE=NEG/REL.KEY)MRN
MRS VALUE=O FOR FIXED LENGTH RECS/=O FOR REL. FILES
"NAM" BLOCK ADDRESS INVALID(NAM=O, OR NOT ACCESSIBLE)
NOT POSITIONED TO EOF(SEG. FILES ONLY)
CAN'T ALLOCATE INTERNAL INDEX DESCRIPTOR
INDEXED FILE-NO PRIMARY KEY DEFINED
XAB'S NOT IN CORRECT ORDER(STV=@XAB)
INVALID FILE ORGANIZATION VALUE
ERROR IN FILE'S PROLOGUE(RECONSTRUCT FILE)
"POSH FIELD INVALID(POS)MRS,STV=@XAB)
BAD FILE DATE FIELD RETRIEVED(STV=@XAB)
PRIVILEGE VIOLATION(OS DENYS ACCESS)

H-2

RECORD MANAGEMENT SERVICES ERROR CODES

Table H-l (Cant.)
RMS System Standard Error Codes
Value

-1312
-1328
-1344
-1360
-1376
-1392
-1408
-1424
-1440
-1456
-1472
-1488
-1504
-1520
-1536
-1552
-1568
-1584
-1600
-1616
-1632
-1648
-1664
-1680
-1696
-1712
-1728
-1744
-1760
-1776
-1784
-1792
-1808

Meaning
NOT A VALID RAB("BID" NOT=RB$BID)
ILLEGAL RAC VALUE
ILLEGAL RECORD ATTRIBUTES
INVALID RECORD BUFFER ADDR("ODD", OR NOT WORD-ALIGNED IF
BLK-IO)
FILE READ ERROR(STV=SYS ERR CODE)
RECORD ALREADY EXISTS
BAD RFA VALUE (RFA=O)
INVALID RECORD FORMAT
TARGET BUCKET LOCKED BY ANOTHER STREAM
RSX-FIIACP REMOVE FUNCTION FAILED(STV=SYS ERR CODE)
RECORD NOT FOUND (STV=O/ER$IDX)
RECORD NEVER WAS IN FILE, OR HAS BEEN DELETED
RECORD NOT LOCKED
INVALID RECORD OPTIONS
ERROR WHILE READING PROLOGUE(STV=SYS ERR CODE)
INVALID RRV RECORD ENCOUNTERED
RAB STREAM CURRENTLY ACTIVE
BAD RECORD SIZE(RSZ>MRS, OR NOT=MRS IF FIXED LENGTH RECS
RSZ NOT=CURRENT REC.SIZE FOR $UPDATE TO SEQ. FILE
RECORD TOO BIG FOR USER'S BUFFER(STV=ACTUAL REC SIZE)
PRIMARY KEY OUT OF SEQUENCE(RAC=RB$SEQ FOR $PUT)
"SHR" FIELD INVALID FOR FILE(CAN'T SHARE SEQ FILES)
"SIZ" FIELD INVALID(STV=@XAB)
STACK TOO BIG FOR SAVE AREA
SYSTEM DIRECTIVE ERROR(STV=SYS ERR CODE)
INDEX TREE ERROR
ERROR IN FILE TYPE
INVALID USER BUFFER ADDR(O,ODD, OR IF BLK-IO NOT WORD
ALIGNED)
INVALID USER BUFFER SIZE(USZ=O)
ERROR IN VERSION NUMBER
INVALID VOLUME NUMBER(STV=@XAB)
FILE WRITE ERROR(STV=SYS ERR CODE)
DEVICE IS WRITE-LOCKED
ERROR WHILE WRITING PROLOGUE (STV=SYS ERR CODE)
NOT A VALID XAB(@XAB=ODD,STV=@XAB)

H-3

APPENDIX I

OBJECT TIME SYSTEM ERROR MESSAGES

Table I-I
COBOL Object Time System Error Messages
Number

Message

Meaning

NON EXISTENT OTS ROUTINE
INVOKED

The COBOL compiler has generated
reference to a nonexistent OTS
routine.
This
should
never
occur;
(COBOL
compiler
error - notify your DEC Software
Specialist) •

DEPENDING DATA NAME
OUT OF RANGE

The data item which defines the
current number of elements in the
table does not fall within the
defined table size range.

ILLEGAL SUBROUTINE
REENTRY

A COBOL subprogram
m~y
not be
called
while
it
1S
still
processing a previous call.

INCORRECT NUMBER OF
SUBROUTINE ARGUMENTS

The number of arguments expected
by a COBOL subprogram does not
agree with the number actually
received.

FILE: NN .•. ATTEMPT TO
OPEN 2
'MULTIPLE
SAME AREAl
FILES
SIMULTANEOUSLY

The program tried to open a file
that uses the same buffer area of
another file that is still open.
(NN...
represents
the
file-name.)

FILE: NN .•• NOT OPEN

The
an
was
the

I-I

program attempted to perform
I/O operation on a file that
not open.
(NN •..
represents
file-name.)

OBJECT TIME SYSTEM ERROR MESSAGES
Table I-I (Cont.)
COBOL Object Time System Error Messages
Number

Message

FILE: NN ... ALREADY
OPEN

The program
a file that
(NN ...
file-name.)

SUBSCRIPT TOO BIG

PERFORM STACK
OVERFLOW

The perform stack is
used to
process nested performs.
The
size of this stack is fixed at
compile time.
To increase the
default Size, specify the /PFM
switch at compile time.

NULL ALTERABLE
GO TO

An alterable GOTO statement has
been reached,
and no procedure
name was assigned to it.

STOP, CR TO CONTINUE

STOP
The program executed
a
waits
statement.
The
OTS
type
indefinitely. To continue,
carriage return.

STOP RUN

The program executed a STOP RUN
statement. The program stops all
activity and closes all
open
files.

SUBSCRIPT TOO SMALL

The subscript value
item is less than
zero.

PERFORM END OF
RANGE VIOLATION

The
end-point
of
an active
perform
range
has
occurred.
However,
the perform range in
question is not the most recent.

The OTS is asking the operator to
FILE: NN •.. OPTIONAL
FILE MOUNTED? Y OR N? specify whether the file NN .•.
is
available
to the running
program.
(NN...
represents the
file-name.)
Type a Y for yes, or
N (or some other character)
for
no.

Meaning
attempted to open
was already open.
represents
the

subscript value used in
a
subscripted data item reference
has exceeded the upper bounds of
the number of items in the table.

1-2

of a data
or equal to

OBJECT TIME SYSTEM ERROR MESSAGES
Table I-I (Cont.)
COBOL Object Time System Error Messages
Number

Message

Meaning

INDEX VALUE TOO SMALL
OR TOO LARGE AT
SOURCE LINE NNNNN

A value for
an index name is
being used in a SET statement
that is outside the bounds of the
table.
(NNNNN represents the
source
program's
page-line
number. )

WRITE ERROR IN DISPLAY

A DISPLAY statement encountered a
bad device or a record length of
more than 132 characters.

ILLEGAL NESTED
PERFORM

An attempt was made to invoke a
perform range whose end-point
is
that of an active perform range.

UNKNOWN PROCEDURE

Self-explanatory:
an appropriate
diagnostic
error
message was
produced by the compiler.
See
the compiler listing.

SPECIFY "ON" SWITCHES

See Section 2.4

ACCEPT-INPUT TOO LONG

A single ACCEPT
statement
has
attempted to read more than 80
characters.
The
OTS
currently
imposes a limit of 80 characters on
the ACCEPT statement.

FILE: NN ... OPEN ERROR-XX The program attempted to open file
NN...
but the open failed.
The
Record Management services error
code specifies the kind of error.
(See Appendix H for the RMS error
codes.)
(NNN..
represents the
file-name.
XX represents the error
code. )

FILE: NN .•• CLOSE ERROR-XX The program attempted to close
file NN ..•
but the close operation
failed.
The
RMS
error
code
specifi·es the kind of error.
(See
Appendix H for the
RMS
error
codes.)
(NN...
represents the
file-name.
XX represents the error
code. )

FILE: NN .•. NOT OPEN

The program attempted to close file
NN .•.
but file NN ...
is not open.
(NN ..•
represents the file-name.)
1-3

OBJECT TIME SYSTEM ERROR MESSAGES
Table I-I (Cont.)
COBOL Object Time System Error Messages
Number

Message

Meaning

FILE: NN ... INVALID
LINAGE

The LINAGE clause specified a
page body size that has been
calculated to be zero.
(NN •..
represents the file-name.)

FILE: NN ... REWRITE/
DELETE NOT LEGAL
WITHOUT PRIOR READ

The program requested a REWRITE
or a DELETE
operation
on a
sequential file and the last I/O
operation in the file was not a
READ.

FILE: NN ... NO USE
PROCEDURE FOR I/O
ERROR-XX

The OTS detected an I/O error for
file NN ... and no USE procedure
is
specified
for
the
file
(explicitly or implicitly). The
RMS error code XX, specifies the
kind of error.
(See Appendix H
for the RMS error codes.) This
message
results from a fatal
error;
the OTS executes a STOP
RUN and closes all open files.

FILE: NN ... LOCKED

The program previously closed the
file
with
lock
during this
program
execution.
(NN ...
represents the file-name.)

FILE: NN ... INVALID
OPERATION

The program attempted to issue
one
of
the
following
I/O
statements on a file open in an
incompatible mode:

ABORT EXECUTION

•

A READ on
output;

file

open

for

•

A WRITE on a file
input or 1-0;

open

for

•

A REWRITE or DELETE on a file
open for input or output.

Execution of the task has arrived
at
a
point
where
a fatal
diagnostic was detected by the
compiler.
NOTE

The following errors indicate
condition within the task.

1-4

fault

OBJECT TIME SYSTEM ERROR MESSAGES
Table I-l (Cont.)
COBOL Object Time System Error Messages
Number

Message

ODD ADDRESS ERROR

MEMORY PROTECTION
VIOLATION

T-BIT TRAP OR BPT
INSTRUCTION

lOT INSTRUCTION

RESERVED INSTRUCTION

NON-RSX EMT

FLOATING POINT EXCEPTION

Meaning

1-5

INDEX

/ACC:nn, 2-13
ACCEPT statement, 6-48
Access modes (indexed), 6-32
Access modes (relative), 6-19
Active/inactive arguments,
3-41
Add statement, 4-15, 4-16
ALTER statement, 7-5
Argument,
Replacement, 3-52
Search, 3-51
Tally, 3-44
Argument match, 3-42
Arguments,
Active/inactive, 3-41
REPLACING, 3-40
TALLYING, 3-40
Arithmetic expression
processing, 4-19
Arithmetic statements, 4-12
Arithmetic statements errors,
4-18
ASSIGN clause, 6-44
Assignments,
Device, 6-44
LUN, B-1

BEFORE/AFTER phrase, 3-37
BLOCK CONTAINS Cnum
CHARACTERS, 6-16
BLOCK CONTAINS integer
RECORDS, 6-7
BLOCK CONTAINS Rnum RECORDS,
6-16, 6-29
Blocking (indexed),
Record, 6-27
Blocking (sequential),
Record, 6-6, 6-15
Buffer areas (indexed),
I-O, 6-30
Buffer areas (sequential),
I-O, 6-8
Buffer size (indexed), 6-30
Buffer size (sequential), 6-8
Buffer space (indexed), 6-31
Buffering (indexed), 6-30
Buffering (relative), 6-17

CALL statement, 9-2
Calling COBOL subprograms,
9-2
Character handling,
Non-numeric, 3-1
Numeric, 4-1

Characters,
Special, 3-3
Class tests, 3-6, 4-7
Classes of data, 3-5
Clause,
ASSIGN, 6-44
RECORD CONTAINS, 6-4, 6-14,
6-27
SAME RECORD AREA, 6-5, 6-15,
6-27
SEGMENT-LIMIT, 8-1
SYNCHRONIZED, 5-3
VALUE OF ID, 6-41
Closing indexed files, 6-37
Closing relative files, 6-24
Closing sequential files, 6-13
CMD, 2-16
COBOL,
Data conversion subroutines, B-1
COBOL command line, 2-18
COBOL compiler, 1-1
Compiling, 2-2
Linking, 2-4
Running, 2-4
COBOL compiler limitations,
C-l
COBOL file types, 6-2
COBOL formats, A-I
COBOL ODL files,
Creating standard, 10-5
COBOL source program, 1-5
COBOL subprograms,
Calling, 9-2
COBOL task,
Running a, 2-4
COBOL utility programs, 1-7, 2-1
Codes,
Device, 6-37
RMS error, H-l
Sort error, F-5
Communicating with the
program, 6-48
Communications,
Inter-program, 9-1
COMP, 4-1
Comparison operation, 3-6
Compiler (see COBOL compiler)
Compiler generated PSECT, E-l
Compiler limitations,
COBOL, 0-1
Compiler switches, 2-13
Compiler system errors, 11-1,
G-l
Compiler-generated ODL file, 10-6
COMPUTE statement, 4-18
Condition-names,
Level 88, 7-6
Index-l

INDEX (Cont.)

COPY, 2-7
COPY REPLACING statement,
2-9
COpy statement, 2-5
COUNT phrase, 3-28
Counter,
Tally, 3-44
Creating a library file, 2-5
Creating a source file, 2-7
Creating standard COBOL ODL
files, 10-5
/CREF, 2-13
/CSEG:nnnm, 2-13, 8-3
/CVF, 2-14
CVNT, B-1

Data,
Classes of, 3-5
Data conversion subroutines, B-1
DATA DIVISION, 1-5
Data file transportability,
6-51
Data item definition, 7-10
Data items,
Index, 5-14
Data Map sample, 2-19
Data movement, 3-7
Data organization, 3-2
Data references,
Qualified, 7-8
Data-names,
Subscripting with, 5-11
Data type conversions, B-2
Defining tables, 5-1
Definition,
data item, 7-10
Deleting records from
indexed files, 6-35
Deleting records from
relative files, 6-22
DELIMITED BY phrase, 3-15,
3-23
DELIMITER phrase, 3-29
Delimiters,
Multiple, 3-27
Device assignments, 6-44
Device codes, 6-37
Devices, 6-37
Disk, 6-38
Line printer, 6-39
Magnetic tape, 6-39
Diagnostic error messages,
G-l
Diagnostic errors, 11-1
Disk devices, 6-38
DISPLAY, 4-1
DISPLAY statement, 6-49
DIVIDE statement, 4-17

DIVISION,
DATA, 1-5
ENVIRONMENT, 1-5
IDENTIFICATION, 1-5
PROCEDURE, 1-6

Edited moves, 3-10
Numeric, 4-10
Elementary items, 3-2
Elementary moves, 3-8
• END, 10-2
ENVIRONMENT DIVISION, 1-5
Error codes,
RMS, H-1
Sort, F-5
Error messages,
Diagnostic, 11-1, G-l
OTS, 1-1
Errors,
Arithmetic statements,
4-18
Compiler system, 11-1, G-1
Diagnostic, 11-1
I/O, 11-4
INSPECT statement, 3-55
Merge utility, 2-30
MOVE statement, 3-12, 4-12
OTS, 11-6
Processing 1-0, 6-52
Run-time, 11-6
STRING statement, 3-20
UNSTRING statement, 3-36
EXIT PROGRAM statement, 9-3
Explicit filenames, 6-41
Expression processing,
Arithmetic, 4-19

• FCTR, 10-2
Fields,
Illegal values in numeric,
4-3
testing numeric, 4-6
File,
Compiler-generated ODL,
10-6
Creating a library, 2-5
Creating a source, 2-1
Listing, 1-1
Object, 1-1
Overlay description
language, 1-1
Standard ODL, 10-1
File body,
ODL, 10-2
File compatibility, 6-50
File handling, 6-1
Index-2

INDEX (Cont.)

File header,
ODL, 10-1
File organization,
Indexed, 6-24
Relative, 6-13
Sequential, 6-3
File section, 1-5
File switches, 6-43
File transportability,
Data, 6-51
File types,
COBOL, 6-2
Filenames,
Explicit, 6-41
Files,
Closing indexed, 6-37
Closing relative, 6-24
Closing sequential, 6-13
Creating standard COBOL
ODL, 10-5
Deleting records from
indexed, 6-35
Deleting records from
relative, 6-22
Hand-tailoring ODL, 10-1
LST, 1-2
Merging standard ODL, 10-5
OBJ, 1-2
ODL, 1-2, 2-25
Opening indexed, 6-33
Opening relative, 6-20
Opening sequential, 6-9
Reading foreign, 6-51
Reading indexed, 6-34
Reading relative, 6-21
Reading sequential, 6-11
Rewriting indexed, 6-34
Rewriting relative, 6-22
Rewriting sequential, 6-12
Sorting, F-l
Writing foreign, 6-50
Writing relative, 6-22
Writing sequential, 6-12
Files and filenames, 6-40
Files and logical units,
6-44
Foreign files,
Reading, 6-51
Writing, 6-50
Format,
Reference, 7-10
Formats,
COBOL, A-I
Formatting the source
program, 7-1

Hand-tailoring ODL files,
10-1
Handling,
file, 6-1
Non-numeric character, 3-1
Numeric character, 4-1
/HELP, 2-14

1-0 buffer areas (indexed),
6-30
1-0 buffer areas (sequential),
6-8
1-0 statements, 6-2
Indexed, 6-31
Relative, 6-18
Sequential, 6-9
I/O errors, 11-4
IDENTIFICATION DIVISION, 1-5
Illegal values in numeric
fields, 4-3
Implicit redefinition, 3-38
Index data items, 5-14
Indexed file organization,
6-24
Indexed files,
Closing, 6-37
Deleting records from, 6-35
Opening, 6-33
Reading, 6-34
Rewriting, 6-34
Indexed 1-0 statements, 6-31
Indexes,
Subscripting with, 5-12
Indexing, 5-9
relative, 5-13
Initializing tables, 5-7
INSPECT operation, 3-40
INSPECT statement, 3-36
Subscripting in, 3-43
INSPECT statement errors,
3-55
Inter-program communications,
9-1
Intermediate results, 4-12
Invoking the Merge utility, 2-26
Items,
Elementary, 3-2
Group, 3-2
Index data, 5-14

Justified moves, 3-10
GIVING phrase, 4-15
Group items, 3-2
Group moves, 3-8, 4-8

/KER:kk, 2-14
Index-3

INDEX (Cont.)

Level 88 condition-names,
7-6
Library Facility,
Common errors, 2-12
COPY REPLACING statement, 2-8
COPY statement, 2-5
Library File,
Creating, 2-5
Merging, 2-7
Line printer devices, 6-39
Linker options, 10-8
Linking the Task, 2-4
Listing file, 1-1
Literals,
subscripting with, 5-9
LST, 1-1
LUN, 6-44
LUN assignments, C-l

Magnetic tape devices, 6-39
Main program, 9-1
/MAP, 2-14
Mapping table elements, 5-3
MERGE, F-l
Merge utility, 1-7, 2-25
Merge utility errors, 2-30
Merge utility program, 1-2
Merging standard ODL files,
10-5
Messages,
Diagnostic error, G-l
OTS error, I-I
MOVE CORRESPONDING, 3-12
MOVE statement, 3-8, 4-8
MOVE statement errors, 3-12,
4-12
Moves,
Edited, 3-10
Elementary, 3-8
Group, 4-8
Justified, 3-10
Numeric, 4-8
Numeric edited, 4-10
Subscripted, 3-11
Multiple delimiters, 3-27
MULTIPLY statement, 4-17

. NAME, 10-2
/NL, 2-15
Non-COBOL programs, 10-5
Non-numeric character
handling, 3-1
Non-numerics,
Testing, 3-4
Numeric character handling,
4-1
Numeric edited moves, 4-10

Numeric fields,
Illegal values in, 4-3
testing, 4-6
Numeric moves, 4-8

OBJ, 1-1
/OBJ, 2-16
Object file, 1-2
OCCURS phrase, 5-2
ODL, 1-2, 10-1
/ODL, 2-15
ODL file,
Compiler-generated, 10-6
Standard, 10-1
ODL file body, 10-2
ODL file header, 10-1
ODL files,
Body, 10-2
Creating standard COBOL,
10-5
Hand-tailoring, 10-1
Merging standard, 10-5
ODL directive types, 10-2
ODL overlays, 10-3
OPEN modes,
Relative, 6-19
OPEN modes (indexed), 6-32
Opening indexed files, 6-33
Opening relative files, 6-20
Opening sequential files, 6-9
Operation,
Comparison, 3-6
INSPECT, 3-40
Optimization, 6-45
Space, 6-47
Speed, 6-45
Options,
Linker, 10-8
Organization,
Data, 3-2
Indexed file, 6-24
Relative file, 6-13
Sequential file, 6-3
OTS error messages, I-I
OTS errors, 11-6
/OV, 2-23, 8-2
OVERFLOW phrase, 3-17, 3-33
Overlayable PSECTS, 10-3
Overlay description language
file, 1-2
Overlay directives (see ODL
directive types)
PERFORM statement, 7-5
/PFM:nn, 2-15
Phrase,
BEFORE/AFTER, 3-37
COUNT, 3-28
Index-4

INDEX (Cont.)

Phrase (Cont.),
DELIMITED BY, 3-15, 3-23
DELIMITER, 3-29
GIVING, 4-15
OCCURS, 5-2
OVERFLOW, 3-17, 3-33
POINTER, 3-30
POINTER, sample, 3-14
REPLACING, 3-51
ROUNDED, 4-13
SIZE ERROR, 4-14
TALLYING, 3-32, 3-43
IPLT, 2-16
POINTER phrase, 3-14, 3-30
Print-controlled records, 6-6
Printer devices,
Line, 6-39
PROCEDURE DIVISION, 1-6
PROCEDURE DIVISION USING,
9-2
Procedure references, 7-11
Processing I-O errors, 6-52
Program,
COBOL source, 1-5
Communicating with the,
6-48
formatting the source, 7-1
Main, 9-1
Merge utility, 1-2, 2-25
Programming languages,
other, 6-50
Programming practices, 7-1
Programs,
COBOL utility, 1-7
Non-COBOL, 10-5
.PSECT, 10-2
PSECT naming conventions,
E-l
Punctuation,
Use of, 7-4

Qualification, 7-12
Qualified data references,
7-8

READ NEXT (relative), 6-24
Reading foreign files, 6-51
Reading indexed files, 6-34
Reading relative files, 6-21
Reading sequential files, 6-11
Record blocking (indexed),
6-27
Record blocking (sequential),
6-6, 6-15

RECORD CONTAINS clause, 6-4,
6-14, 6-27
Record size (indexed), 6-27
Record size (relative), 6-14
Record size (sequential),
6-4
RECORDS,
BLOCK CONTAINS Rnum, 6-16
Records,
Print-controlled, 6-6
Redefinition,
Implicit, 3-38
Referability,
Unique, 7-11
Reference format, 7-10
Conventional, 2-2
References,
Procedure, 7-11
Qualified data, 7-8
Referencing tables, 5-15
REFORMAT command string,
2-31
REFORMAT error messages,
2-31
REFORMAT utility, 1-7, 2-30
Relation tests, 3-4, 4-6
Relative file organization,
6-13
Relative files,
Closing, 6-24
Deleting records from,
6-22
Opening, 6-20
Reading, 6-21
Rewriting, 6-22
Writing, 6-22
RelatIve 1-0 statements, 6-18
Relative indexing, 5-13
Relative OPEN modes, 6-19
RELES, F-l
Replacement argument, 3-52
Replacement value, 3-52
REPLACING arguments, 3-40
REPLACING phrase, 3-51
Results,
Intermediate, 4-12
RETRN, F-l
Rewriting indexed files,
6-34
Rewriting relative files,
6-22
Rewriting sequential files,
6-12
RMS error codes, H-l
IRO, 2-15
• ROOT, 10-2
ROUNDED phrase, 4-13
RSORT, F-l
Run-time errors, 11-6

Index-5

INDEX (Cont.)

SAME RECORD AREA clause,
6-5, 6-15, 6-27
Search argument, 3-51
SEARCH verb, 5-16
SECTION, 8-1
Section-name, 8-1
SEGMENT-LIMIT clause, 8-1
Segment-number, 8-1
Segmentation, 8-1
Sequential file organization,
6-3
Sequential files,
Closing, 6-13
Opening, 6-9
Reading, 6-11
Rewriting, 6-12
Writing, 6-12
Sequential 1-0 statements,
6-9
SET statement, 5-14
Sharing buffer space
(sequential), 6-8
Sign convention, 4-2
Sign tests, 4-6
SIZE ERROR phrase, 4-14
Sort error codes, F-5
Sorting files, F-1
Source Language Statement files,
Creating, 2-1
Source program,
COBOL, 1-5
formatting the, 7-1
sample listing of, 2-16
Space optimization, 6-47
Special characters, 3-3
Speed optimization, 6-45
START statement (indexed),
6-35
START statement (relative),
6-23
Statement,
ACCEPT, 6-48
ADD, 4-15, 4-16
ALTER, 7-5
CALL, 9-2
COMPUTE, 4-18
COPY, 2-5
COpy REPLACING, 2-8
DISPLAY, 6-49
DIVIDE, 4-17
EXIT PROGRAM, 9-3
INSPECT, 3-36
MOVE, 3-8, 4-8
MULTIPLY, 4-17
ODL, 1-2
PERFORM, 7-5
SET, 5-14
Subscripting in INSPECT,
3-43
Subscripting in UNSTRING, 3-34

Statement (Cont.),
SUBTRACT, 4-15, 4-16
UNSTRING, 3-21
USE, 6-52
Statement errors,
INSPECT, 3-55
MOVE, 3-12, 4-12
STRING, 3-20
UNSTRING, 3-36
Statements,
Arithmetic, 4-12
1-0, 6-2
Indexed 1-0, 6-31
Relative 1-0, 6-18
Sequential 1-0, 6-9
Statements errors,
Arithmetic, 4-18
STRING statement, 3-13
Subscripting in, 3-18
STRING statement errors,
3-20
STRNUM, B-1
Subprogram, 9-2
Subprograms,
Calling COBOL, 9-2
Subroutines, B-1
Subscripted moves, 3-11
Subscripting, 5-9
Subscripting with data-names,
5-11
Subscripting with indexes,
5-12
Subscripting with literals,
5-9
SUBTRACT statement, 4-15, 4-16
Support environment, 1-1, 2-1
Switches,
Compiler, 2-13
file, 6-43
/SYM:n, 2-15
SYNCHRONIZED clause, 5-3
System errors,
Compiler, G-l, 11-1

Table handling, 5-1
Tables,
defining, 5-1
Initializing, 5-7
Referencing, 5-15
Tally argument, 3-44
Tally counter, 3-44
TALLYING arguments, 3-40
TALLYING phrase, 3-32, 3-43
Tape devices,
Magnetic, 6-39
Testing non-numerics, 3-4
Testing numeric fields, 4-6
Index-6

INDEX (Cont.)

Tests,
Class, 3-6
class, 4-7
Relation, 3-4
Sign, 4-6
TRAX Linker, 1-2, 2-4, 10-2
TRAX support environment
(see Support environment)
TRAX support terminal, 1-1

Utility,
Merge, 1-7, 2-25
REFORMAT, 1-7, 2-30
Utility program,
Merge, 1-2
REFORMAT, 1-2
Utility programs,
COBOL, 1-7

Unique referability, 7-11
UNSTRING statement, 3-21
Subscripting in, 3-34
UNSTRING statement errors,
3-36
USAGE, 4-1
USE statement, 6-52
USING,
PROCEDURE DIVISION, 9-2

VALUE OF ID clause, 6-41

Writing foreign files, 6-50
Writing relative files, 6-22
Writing sequential files,
6-12

Index-7

TRAX COBOL
User's Guide
AA-D339A-TC

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.

m
o
c
c

Did you find errors in this manual?
page number.

If so, specify the error and the

Please indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Other (please specify) _____________________________________

Name

Date _________________________

Organization ______________________________________________________________
Street _____________________________________________________________________
City.___________________________ State _____________ Zip Code _____________
or
Country

-------------------------------------------------------------Fold lIere------------------------------------------------------------

----------------------------------------------- Do Not Tear - Fold lIere and Staple -----------------------------------------------

FIRST CLASS
PERMIT NO. 33
MAYNARD, MASS.
BUSINESS REPLY MAIL
NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES

Postage will be paid by:

Software Documentation
146 Main Street MLS-S/E39
Maynard, Massachusetts 01754