COBOL ANSI 85 Programming Reference Manual, Volume 1 COBOL85 Vol

86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003 86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003

86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003 manual pdf -FilePursuit

86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003 86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003

COBOL85 Vol 1 COBOL85 Vol 1

User Manual: COBOL85 Vol 1

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

Download
Open PDF In Browser	View PDF

Application Development
Solutions
COBOL ANSI-85
Programming Reference Manual
Volume 1:
Basic Implementation

ClearPath MCP Release 8.0
February 2003

Printed in USA
8600 1518–307

Application Development
Solutions
COBOL ANSI-85
Programming Reference Manual
Volume 1:
Basic Implementation

UNISYS

ClearPath MCP Release 8.0
February 2003

Printed in USA
8600 1518–307

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information
described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to
purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the
products described in this document are set forth in such agreement. Unisys cannot accept any financial or other
responsibility that may be the result of your use of the information in this document or software material, including
direct, special, or consequential damages.
You should be very careful to ensure that the use of this information and/or software material complies with the laws,
rules, and regulations of the jurisdictions with respect to which it is used.
The information contained herein is subject to change without notice. Revisions may be issued to advise of such
changes and/or additions.
Notice to Government End Users: This is commercial computer software or hardware documentation developed at
private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard
commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data
rights clauses.
Correspondence regarding this publication can be e-mailed to doc@unisys.com.

Unisys and ClearPath are registered trademarks of Unisys Corporation in the United States and other countries.
All other brands and products referenced in this document are acknowledged to be the trademarks or registered
trademarks of their respective holders.

Application Development
Solutions

Application
Development
Solutions

COBOL ANSI-85

Programming Reference
Manual

Programming
Reference
Manual

Volume 1:
Basic Implementation

Volume 1:
Basic
Implementation

ClearPath MCP
Release 8.0

8600 1518–307

ClearPath MCP
Release 8.0

8600 1518–307

Bend here, peel upwards and apply to spine.

Contents
Section 1.

Program Structure and Language Elements
About This Manual ................................................................................ 1–1
Purpose ................................................................................ 1–1
Audience .............................................................................. 1–1
Conventions ......................................................................... 1–2
Acknowledgments ............................................................... 1–2
Program Overview ................................................................................ 1–3
Divisions of a Source Program .............................................................. 1–3
Contents of a Division ........................................................................... 1–4
Reference Format ................................................................................. 1–5
Division and Section Headers................................................................ 1–7
Level-Numbers ...................................................................................... 1–8
Special-Purpose Lines—Fixed Indicators .............................................. 1–9
Continuation Lines ............................................................... 1–9
Comment Lines ................................................................. 1–10
Floating Comment Indicator............................................... 1–11
Debugging Lines ................................................................ 1–11
Compiler Control Option Lines........................................... 1–12
Blank Lines......................................................................... 1–12
Pseudotext ......................................................................... 1–12
COBOL Character Set ......................................................................... 1–13
Using Separator Characters for Punctuation ....................................... 1–14
Types of COBOL Words...................................................................... 1–16
Reserved Words ................................................................ 1–16
Connectives............................................................... 1–17
Figurative Constants.................................................. 1–17
Functions................................................................... 1–19
Special Registers....................................................... 1–20
Arithmetic and Relational Operators ......................... 1–22
System-Names .................................................................. 1–23
User-Defined Words .......................................................... 1–24
Identifiers............................................................................................. 1–28
Literals ................................................................................................. 1–29
Nonnumeric Literals........................................................... 1–30
National Literals ................................................................. 1–31
Numeric Literals ................................................................. 1–32
Undigit Literals ................................................................... 1–33
Floating-Point Literals......................................................... 1–34
Boolean Literals ................................................................. 1–35

8600 1518–307

iii

Contents

Section 2.

Identification Division
General Format ..................................................................................... 2–1
Identification Division Header ............................................................... 2–1
PROGRAM-ID Paragraph ...................................................................... 2–2
IS COMMON PROGRAM Clause ........................................ 2–3
IS INITIAL PROGRAM Clause ............................................. 2–3
IS LIBRARY PROGRAM Clause........................................... 2–3
IS DEFINITION PROGRAM Clause...................................... 2–3
AUTHOR Paragraph .............................................................................. 2–4
INSTALLATION Paragraph .................................................................... 2–5
DATE-WRITTEN Paragraph ................................................................... 2–6
DATE-COMPILED Paragraph ................................................................ 2–7
Security Paragraph ................................................................................ 2–8

Section 3.

Environment Division
General Format ..................................................................................... 3–1
Environment Division Header ............................................................... 3–1
Configuration Section............................................................................ 3–2
Configuration Section Header.............................................. 3–2
SOURCE-COMPUTER Paragraph ........................................ 3–3
OBJECT-COMPUTER Paragraph ......................................... 3–4
MEMORY SIZE Clause ............................................... 3–5
DISK SIZE Clause........................................................ 3–5
PROGRAM COLLATING SEQUENCE Clause............. 3–6
SPECIAL-NAMES Paragraph ............................................... 3–7
CHANNEL Clause ..................................................... 3–10
ODT Clause ............................................................... 3–10
SWITCH-NAME Clause............................................. 3–10
ALPHABET Clause .................................................... 3–11
SYMBOLIC CHARACTERS Clause ........................... 3–16
CLASS Clause ........................................................... 3–17
CURRENCY SIGN Clause.......................................... 3–18
Literal-7 IS MNEMONIC-NAME Clause .................... 3–19
DECIMAL-POINT Clause........................................... 3–19
DEFAULT DISPLAY SIGN and DEFAULT
COMPUTATIONAL SIGN Clauses ........................ 3–19
Input-Output Section........................................................................... 3–21
Input-Output Section Header............................................. 3–21
FILE-CONTROL Paragraph ................................................ 3–22
General Format of the FILE-CONTROL
Paragraph.............................................................. 3–22
File Control Entry Format 1: Sequential
Organization.......................................................... 3–23
File Control Entry Format 2: Relative
Organization.......................................................... 3–30
File Control Entry Format 3: Indexed I/O .................. 3–34
File Control Entry Format 4: Sort-Merge................... 3–39

8600 1518–307

Contents

I-O-CONTROL Paragraph ................................................... 3–41
Input-Output Control Entry Format 1:
Sequential I/O ....................................................... 3–41
Input-Output Control Entry Format 2: Relative
and Indexed Organization ..................................... 3–44
Input-Output Control Entry Format 3: SortMerge.................................................................... 3–46
I-O Status Codes ................................................................ 3–49
Recovering from I-O Errors ................................................ 3–56
How the Recovery Process Occurs................................... 3–57
Modifying the Recovery Process for COBOL74
Compatibility .................................................................. 3–58
Section 4.

Data Division
Structure of the Data Division ............................................................... 4–1
Record Concepts ................................................................. 4–2
Level Concepts .................................................................... 4–3
Level-Numbers ............................................................ 4–4
Level Indicators (FD, SD)............................................. 4–4
Classes and Categories of Data Items................................. 4–5
Class and Category of Figurative Constants
and Intrinsic Functions ............................................ 4–6
Long Numeric Data Items ........................................... 4–7
Algebraic Signs .................................................................... 4–8
Standard Alignment Rules ................................................... 4–8
Increasing Object-Code Efficiency ....................................... 4–9
Uniqueness of Reference .................................................... 4–9
Qualification ....................................................................... 4–10
Reference Modifiers .......................................................... 4–14
General Format.................................................................................... 4–17
Record Description Entry .................................................................... 4–18
Data Description Entry Format 1......................................................... 4–19
Data-Name or FILLER Clause ............................................ 4–22
REDEFINES Clause............................................................ 4–23
ALIGNED Clause................................................................ 4–24
BLANK WHEN ZERO Clause ............................................. 4–24
COMMON Clause.............................................................. 4–25
INTEGER and STRING Clauses.......................................... 4–26
JUSTIFIED (JUST) Clause .................................................. 4–26
LOCAL Clause.................................................................... 4–26
LOWER-BOUNDS Clause .................................................. 4–27
OCCURS Clause ................................................................ 4–28
OWN Clause ...................................................................... 4–31
PICTURE Clause ................................................................ 4–32
Restrictions ............................................................... 4–32
Symbols..................................................................... 4–33
Categories of Items................................................... 4–38
Determining the Size of an Elementary Item............ 4–40
Editing Rules ............................................................. 4–41
Precedence Rules ..................................................... 4–47

8600 1518–307

Contents

RECEIVED BY Clause ........................................................ 4–49
RECORD AREA Clause...................................................... 4–50
SIGN Clause....................................................................... 4–50
SYNCHRONIZED Clause ................................................... 4–52
TYPE Clause ...................................................................... 4–53
USAGE Clause ................................................................... 4–54
USAGE IS BINARY.................................................... 4–55
USAGE IS BIT ........................................................... 4–56
USAGE IS COMPUTATIONAL and USAGE IS
COMP ................................................................... 4–57
USAGE IS COMPUTATIONAL-5 and USAGE
IS COMP-5............................................................ 4–57
USAGE IS CONTROL-POINT .................................... 4–57
USAGE IS DISPLAY .................................................. 4–58
USAGE IS DOUBLE .................................................. 4–58
USAGE IS EVENT...................................................... 4–59
USAGE IS INDEX ...................................................... 4–60
USAGE IS LOCK ....................................................... 4–61
USAGE IS KANJI (Obsolete) ..................................... 4–61
USAGE IS NATIONAL ............................................... 4–62
USAGE IS PACKED-DECIMAL.................................. 4–62
USAGE IS REAL........................................................ 4–62
USAGE IS TASK ........................................................ 4–63
VALUE Clause.................................................................... 4–64
Data Description Entry Format 2: Level-66 RENAMES Entry ............. 4–67
RENAMES Clause.............................................................. 4–68
Data Description Entry Format 3: Level-88 Condition-Name
Entry................................................................................................ 4–70
VALUE Clause.................................................................... 4–71
Data Description Entry Format 4: IPC ................................................. 4–75
Data-Name or FILLER Clause ............................................ 4–77
COMMON Clause.............................................................. 4–77
EXTERNAL Clause ............................................................. 4–77
GLOBAL Clause................................................................. 4–78
OWN Clause ...................................................................... 4–78
REDEFINES Clause............................................................ 4–79
VALUE Clause.................................................................... 4–79
Data Division Header .......................................................................... 4–80
File Section.......................................................................................... 4–81
File Description Entry Format 1: Sequential I-O.................................. 4–82
BLOCK CONTAINS Clause ................................................ 4–84
CODE-SET Clause.............................................................. 4–86
DATA RECORDS Clause ................................................... 4–87
LABEL RECORDS Clause.................................................. 4–87
LINAGE Clause .................................................................. 4–88
RECORD Clause ................................................................ 4–91
VALUE OF Clause.............................................................. 4–95
File Description Entry Format 2: Relative I-O, Indexed I-O ................. 4–98
BLOCK CONTAINS Clause ................................................ 4–99
Variable Length Records.................................................. 4–100

8600 1518–307

Contents

File Description Entry Format 3: Sort-Merge .................................... 4–101
DATA RECORDS Clause.................................................. 4–102
RECORD Clause .............................................................. 4–102
File Description Entry Format 4: IPC and Sequential I-O .................. 4–103
EXTERNAL Clause ........................................................... 4–105
GLOBAL Clause ............................................................... 4–105
File Description Entry Format 5: IPC, Relative I-O, and Indexed
I-O ................................................................................................. 4–107
Working-Storage Section................................................................... 4–109
Noncontiguous Working Storage..................................... 4–110
Working-Storage Records ................................................ 4–110
Initial Values ..................................................................... 4–111
Linkage Section ................................................................................. 4–112
Noncontiguous Linkage Storage...................................... 4–113
Linkage Records .............................................................. 4–113
Initial Values ..................................................................... 4–114
Local-Storage Section........................................................................ 4–115
Noncontiguous Local-Storage .......................................... 4–116
Local-Storage Records ..................................................... 4–116
Initial Values ..................................................................... 4–116
Library Description Entry Format 1: Export Definition ...................... 4–118
ATTRIBUTE Clause .......................................................... 4–119
ENTRY PROCEDURE Clause ........................................... 4–119
Library Description Entry Format 2: Import Definition ...................... 4–121
ATTRIBUTE Clause .......................................................... 4–122
ENTRY PROCEDURE Clause ........................................... 4–123
Section 5.

Procedure Division Concepts
Structure of the Procedure Division ...................................................... 5–2
General Formats.................................................................................... 5–2
Procedure Division Header .................................................. 5–2
Declarative Procedure Format ............................................. 5–6
Nondeclarative Procedure Format ....................................... 5–8
End Program Header............................................................ 5–9
Elements of a Procedure..................................................................... 5–10
Statement Scope Terminators ........................................... 5–11
Explicit Terminators................................................... 5–11
Implicit Terminators................................................... 5–12
Types of Statements and Sentences................................. 5–12
Imperative Statements and Sentences..................... 5–13
Conditional Statements and Sentences .................... 5–14
Compiler-Directing Statements and
Sentences ............................................................. 5–15
Delimited Scope Statements .................................... 5–15
Categories of Verbs ........................................................... 5–16
Arithmetic Expressions ....................................................................... 5–26
Allowed Combinations of Elements .................................. 5–27
Precedence in Evaluation of Arithmetic Expressions ........ 5–28
Rules for Exponentiation.................................................... 5–29
Intermediate Data Item...................................................... 5–30

8600 1518–307

vii

Contents

General Rules for Arithmetic Statements.......................... 5–31
Data Descriptions...................................................... 5–31
Operand Size Limit.................................................... 5–32
Multiple Results in Arithmetic Statements............... 5–32
ROUNDED Phrase .................................................... 5–33
SIZE ERROR Phrase ................................................. 5–35
OFFSET Function............................................................... 5–36
Boolean Expressions........................................................................... 5–37
Conditional Expressions ...................................................................... 5–39
Simple Conditions.............................................................. 5–40
Relation Conditions ................................................... 5–40
Class Conditions ....................................................... 5–49
Condition-Name Conditions ...................................... 5–52
Switch-Status Conditions.......................................... 5–53
Sign Conditions ......................................................... 5–54
Event Condition......................................................... 5–55
Boolean Condition..................................................... 5–55
Negated Simple Conditions ............................................... 5–56
Complex Conditions .......................................................... 5–57
Allowed Combinations of Elements ......................... 5–58
Combined Condition Format ..................................... 5–60
Abbreviated Combined Relation Conditions ............. 5–61
Precedence in Evaluation of Complex
Conditions............................................................. 5–64
Table Handling..................................................................................... 5–66
Defining a Table ................................................................. 5–66
Table Dimensions .............................................................. 5–67
INDEXED BY Option .......................................................... 5–68
Initializing Tables................................................................ 5–69
In the Data Division................................................... 5–69
In the Procedure Division.......................................... 5–70
References to Table Items ................................................ 5–70
Sort and Merge Operations ................................................................ 5–75
Sorting ............................................................................... 5–75
Merging ............................................................................. 5–75
Sort and Merge Constructs ............................................... 5–76

viii

8600 1518–307

Contents

Section 6.

Procedure Division Statements A–H
ACCEPT Statement ............................................................................... 6–2
Format 1: Transfer Data from Hardware Device.................. 6–2
Format 2: Transfer Data from Date and Time
Registers.......................................................................... 6–5
Format 3: Transfer Number of Storage Queue
Entries.............................................................................. 6–8
Format 4: Transfer Formatted System Date and
Time................................................................................. 6–9
ADD Statement ................................................................................... 6–10
Format 1: ADD . . . TO ....................................................... 6–10
Format 2: ADD . . . TO . . . GIVING .................................... 6–12
Format 3: ADD CORRESPONDING ................................... 6–14
ALLOW Statement.............................................................................. 6–16
ALTER Statement................................................................................ 6–17
ATTACH Statement............................................................................. 6–18
CALL Statement .................................................................................. 6–20
Format 1: CALL with ON OVERFLOW Option .................. 6–21
Format 2: CALL with ON EXCEPTION Option................... 6–24
Format 3: CALL a System Procedure ................................ 6–30
Format 4: CALL for Binding ............................................... 6–34
Format 5: CALL for Library Entry Procedure...................... 6–36
Format 6: CALL for Initiating a Synchronous,
Dependent Process ....................................................... 6–40
Format 7: CALL MODULE ................................................. 6–44
CANCEL Statement............................................................................. 6–47
CAUSE Statement............................................................................... 6–50
CHANGE Statement............................................................................ 6–52
Format 1: Changing the Value of a Numeric File
Attribute......................................................................... 6–52
Format 2: Changing the Value of an Alphanumeric
File Attribute .................................................................. 6–54
Format 3: Changing the Value of a Mnemonic File
Attribute......................................................................... 6–55
Format 4: Changing the Value of a Library Attribute ......... 6–56
Format 5: Changing the Value of a Task Attribute ............. 6–58
CLOSE Statement ............................................................................... 6–62
Format 1: Sequential I-O .................................................... 6–62
Format 2: Relative and Indexed I-O ................................... 6–71
COMPUTE Statement ......................................................................... 6–74
Format 1: Arithmetic Compute .......................................... 6–74
Format 2: Boolean Compute.............................................. 6–77
CONTINUE Statement ........................................................................ 6–78
Format 1: Designating an Unexecutable Line of
Code .............................................................................. 6–78
Format 2: Returning to the Called Process........................ 6–79
COPY Statement ................................................................................. 6–80
DEALLOCATE Statement.................................................................... 6–88
DELETE Statement ............................................................................. 6–89

8600 1518–307

Contents

DETACH Statement ............................................................................ 6–92
Format 1: Detaching from a Task Variable ........................ 6–92
Format 2: Detaching from an Event .................................. 6–93
DISALLOW Statement........................................................................ 6–94
DISPLAY Statement............................................................................ 6–95
DIVIDE Statement............................................................................... 6–98
Format 1: DIVIDE . . . INTO ............................................... 6–99
Format 2: DIVIDE . . . INTO . . . GIVING .......................... 6–101
Format 3: DIVIDE . . . BY . . . GIVING .............................. 6–103
Format 4: DIVIDE . . . INTO . . . GIVING . . .
REMAINDER ............................................................... 6–105
Format 5: DIVIDE . . . BY . . . GIVING . . .
REMAINDER ............................................................... 6–107
EVALUATE Statement ...................................................................... 6–109
EXIT Statement ................................................................................. 6–119
Format 1: EXIT from an Out-of-Line PERFORM.............. 6–119
Format 2: EXIT from a Called Program (ANSI IPC) .......... 6–121
Format 3: EXIT from a Bound Procedure ........................ 6–123
Format 4: EXIT from a Called Program (Tasking)............. 6–123
Format 5: EXIT MODULE ................................................ 6–124
Format 6: EXIT from a PERFORM Statement ................. 6–125
GO TO Statement ............................................................................. 6–128
Format 1: GO TO ............................................................. 6–128
Format 2: GO TO . . . DEPENDING ON ........................... 6–129
Section 7.

Procedure Division Statements I–R
IF Statement ......................................................................................... 7–2
INITIALIZE Statement ........................................................................... 7–6
INSPECT Statement............................................................................ 7–10
Format 1: INSPECT . . . TALLYING.................................... 7–10
Format 2: INSPECT . . . REPLACING................................. 7–15
Format 3: INSPECT . . . TALLYING and REPLACING ........ 7–19
Format 4: INSPECT. . . CONVERTING............................... 7–21
LOCK Statement ................................................................................. 7–23
LOCKRECORD Statement .................................................................. 7–25
MERGE Statement.............................................................................. 7–28
MOVE Statement................................................................................ 7–37
Format 1: MOVE Data ....................................................... 7–37
Format 2: MOVE CORRESPONDING................................ 7–44
Format 3: MOVE Selected Bits ......................................... 7–47
MULTIPLY Statement ......................................................................... 7–49
Format 1: MULTIPLY ......................................................... 7–49
Format 2: MULTIPLY . . . GIVING...................................... 7–51
OPEN Statement................................................................................. 7–54
PERFORM Statement ......................................................................... 7–63
Format 1: Basic PERFORM ............................................... 7–63
Format 2: PERFORM . . . TIMES ....................................... 7–66
Format 3: PERFORM . . . UNTIL........................................ 7–69

8600 1518–307

Contents

Format 4: PERFORM . . . VARYING................................... 7–71
Rules for Identifiers ................................................... 7–73
Rules for Arithmetic Expressions.............................. 7–73
Rules for Index-Names.............................................. 7–73
Rules for Condition-Names ....................................... 7–74
Action of Various PERFORM Statements ................. 7–74
How Changes in Variables Affect the
PERFORM Statement........................................... 7–81
Rules for All Formats of the PERFORM Statement .......... 7–82
PROCESS Statement .......................................................................... 7–85
READ Statement ................................................................................. 7–88
Format 1: Files in Sequential Access Mode ...................... 7–88
Format 2: Sequential and Relative Files in Random
Access Mode................................................................. 7–91
Format 3: Indexed Files in Random Access Mode ............ 7–92
READ Statement Examples ............................................... 7–98
RECEIVE Statement .......................................................................... 7–100
Format 1: Receive Data Synchronously........................... 7–100
Format 2: Receive Data Asynchronously (STOQ) ............ 7–102
RELEASE Statement ......................................................................... 7–104
REPLACE Statement......................................................................... 7–106
Format 1: Start REPLACE Operations ............................ 7–106
Format 2: Discontinue REPLACE Operations ................. 7–109
RESET Statement.............................................................................. 7–111
RETURN Statement .......................................................................... 7–112
REWRITE Statement......................................................................... 7–117
Format 1: Sequential Files .............................................. 7–117
Format 2: Relative and Indexed Files.............................. 7–119
RUN Statement ................................................................................. 7–123
Section 8.

Procedure Division Statements S–Z
SEARCH Statement .............................................................................. 8–2
Format 1: SEARCH . . . VARYING (Serial Search) ............... 8–2
Format 2: SEARCH ALL (Binary Search)............................. 8–8
SEEK Statement.................................................................................. 8–12
SEND Statement ................................................................................. 8–13
Format 1: Send Data Synchronously (CRCR)..................... 8–13
Format 2: Send Data Asynchronously (STOQ)................... 8–15
SET Statement .................................................................................... 8–18
Format 1: SET . . . TO ....................................................... 8–18
Format 2: SET . . . UP BY (DOWN BY) ............................. 8–21
Format 3: SET an External Switch .................................... 8–22
Format 4: SET a Condition TO TRUE ................................ 8–23
Format 5: SET or Modify a File Attribute .......................... 8–24
SORT Statement ................................................................................. 8–26
START Statement................................................................................ 8–39
STOP Statement ................................................................................. 8–45
STRING Statement.............................................................................. 8–47

8600 1518–307

Contents

SUBTRACT Statement ........................................................................ 8–53
Format 1: SUBTRACT . . . FROM ..................................... 8–54
Format 2: SUBTRACT . . . FROM . . . GIVING .................. 8–56
Format 3: SUBTRACT CORRESPONDING....................... 8–58
UNLOCK Statement............................................................................ 8–60
UNLOCKRECORD Statement............................................................. 8–61
UNSTRING Statement ........................................................................ 8–63
Format 1: UNSTRING . . . INTO........................................ 8–63
Format 2: UNSTRING . . . INTO . . . FOR ......................... 8–69
USE Statement ................................................................................... 8–71
Format 1: USE AFTER ...................................................... 8–71
Format 2: USE PROCEDURE ........................................... 8–75
Format 3: USE AS INTERRUPT PROCEDURE ................. 8–76
Format 4: USE AS EPILOG PROCEDURE ........................ 8–77
WAIT Statement ................................................................................. 8–78
Format 1: Wait for Time or Condition ................................ 8–79
Format 2: Wait Until Interrupt............................................ 8–83
WRITE Statement ............................................................................... 8–84
Format 1: WRITE (Files in Sequential Access Mode)........ 8–84
Format 2: WRITE (Files in Random Access Mode) .......... 8–91
Section 9.

Intrinsic Functions
Summary of Functions .......................................................................... 9–1
Types of Functions................................................................................ 9–5
Rules for Using Functions ..................................................................... 9–6
Syntax for a Function ............................................................................ 9–7
Arguments ............................................................................................ 9–8
Types of Arguments ............................................................ 9–8
Evaluation of Arguments ..................................................... 9–9
Subscripting an Argument ................................................... 9–9
ABS Function ...................................................................................... 9–12
ACOS Function.................................................................................... 9–13
ANNUITY Function .............................................................................. 9–14
ASIN Function ..................................................................................... 9–15
ATAN Function .................................................................................... 9–16
CHAR Function.................................................................................... 9–17
CHAR-NATIONAL Function................................................................. 9–18
CONVERT-TO-DISPLAY Function ....................................................... 9–19
CONVERT-TO-NATIONAL Function .................................................... 9–20
COS Function ...................................................................................... 9–21
CURRENT-DATE Function .................................................................. 9–22
DATE-OF-INTEGER Function .............................................................. 9–24
DAY-OF-INTEGER Function ................................................................ 9–25
DIV Function........................................................................................ 9–26
EXP Function....................................................................................... 9–27
FACTORIAL Function .......................................................................... 9–28
FIRSTONE Function ............................................................................ 9–29
FORMATTED-SIZE Function ............................................................... 9–30
INTEGER Function .............................................................................. 9–31
INTEGER-OF-DATE Function .............................................................. 9–32

xii

8600 1518–307

Contents

INTEGER-OF-DAY Function................................................................. 9–33
INTEGER-PART Function..................................................................... 9–34
LENGTH Function................................................................................ 9–35
LENGTH-AN Function.......................................................................... 9–36
LINENUMBER Function ...................................................................... 9–38
LOG Function ...................................................................................... 9–39
LOG10 Function .................................................................................. 9–40
LOWER-CASE Function ...................................................................... 9–41
MAX Function...................................................................................... 9–42
MEAN Function ................................................................................... 9–44
MEDIAN Function ............................................................................... 9–46
MIDRANGE Function .......................................................................... 9–48
MIN Function....................................................................................... 9–50
MOD Function ..................................................................................... 9–52
NUMVAL Function .............................................................................. 9–53
NUMVAL-C Function ........................................................................... 9–55
ONES Function.................................................................................... 9–57
ORD Function ...................................................................................... 9–58
ORD-MAX Function............................................................................. 9–59
ORD-MIN Function.............................................................................. 9–60
PRESENT-VALUE Function ................................................................. 9–61
RANDOM Function ............................................................................. 9–62
RANGE Function ................................................................................. 9–63
REM Function...................................................................................... 9–65
REVERSE Function.............................................................................. 9–66
SIGN Function ..................................................................................... 9–67
SIN Function ........................................................................................ 9–68
SQRT Function .................................................................................... 9–69
STANDARD-DEVIATION Function ...................................................... 9–70
SUM Function ..................................................................................... 9–71
TAN Function....................................................................................... 9–73
UPPER-CASE Function........................................................................ 9–74
VARIANCE Function ............................................................................ 9–75
WHEN-COMPILED Function ............................................................... 9–76
Section 10.

Interprogram Communication
The Run Unit ....................................................................................... 10–2
Nested Source Programs .................................................................... 10–2
Accessing Files and Data in a Run Unit............................................... 10–3
File Connectors ................................................................................... 10–3
Global and Local Names...................................................................... 10–3
External and Internal Objects .............................................................. 10–5
Common and Initial Programs ............................................................. 10–6
Scope of Names .................................................................................. 10–7
Conventions for Program-Names........................................................ 10–8
Conventions for Names of Data, Files, and Records ........................ 10–10
Conventions for Index-Names........................................................... 10–11
Forms of Interprogram Communication............................................ 10–11
Transfer of Control ........................................................... 10–11
Passing Parameters to Programs .................................... 10–12

8600 1518–307

xiii

Contents

Sharing Data .................................................................... 10–14
Sharing Files .................................................................... 10–15
Using the ANSI IPC Constructs ........................................................ 10–16
Section 11.

Library Concepts
Library Programs ................................................................................. 11–2
User Programs .................................................................................... 11–2
Interface between Libraries and User Programs ................................ 11–2
Directory Data Structure.................................................... 11–2
Template Data Structure ................................................... 11–3
Library Initiation................................................................................... 11–4
Linkage between User Programs and Libraries .................................. 11–5
Creating Libraries ................................................................................ 11–6
Library Sharing Specifications ............................................................. 11–7
Making References to Libraries .......................................................... 11–8
Library Attributes................................................................................. 11–9
FUNCTIONNAME .............................................................. 11–9
INTERFACENAME ............................................................. 11–9
INTNAME........................................................................... 11–9
LIBACCESS...................................................................... 11–10
LIBPARAMETER.............................................................. 11–10
TITLE................................................................................ 11–10
Matching Formal and Actual Parameters.......................................... 11–11
COBOL85 Library Example ............................................................... 11–13
COBOL85 User Program Example.................................................... 11–15
ALGOL User Program Example ........................................................ 11–16
Passing a File as a Parameter ........................................................... 11–19
Library Program Example ................................................ 11–19
Calling Program Example................................................. 11–20

Section 12.

File Concepts
Overview............................................................................................. 12–2
Physical versus Logical Records........................................ 12–2
Manipulating Files.............................................................. 12–3
File Attributes...................................................................................... 12–4
File-Attribute Identifier ........................................................................ 12–5
MCPRESULTVALUE Identifier ............................................................ 12–8
Port Files ........................................................................................... 12–10
File Organization................................................................................ 12–11
Sequential Files................................................................ 12–11
Relative Files.................................................................... 12–12
Indexed Files.................................................................... 12–13
Access Mode .................................................................................... 12–14
Sequential Access Mode................................................. 12–14
Random Access Mode .................................................... 12–14
Dynamic Access Mode.................................................... 12–15

xiv

8600 1518–307

Contents

File Organization Checklists .............................................................. 12–16
Sequential File Checklists ................................................ 12–16
Sequential File Program Example .................................... 12–18
Relative File Checklist ...................................................... 12–19
Relative File Program Example ........................................ 12–22
Indexed File Checklist ...................................................... 12–25
Indexed File Program Example ........................................ 12–27
Section 13.

Tasking in COBOL85
Programs and Processes..................................................................... 13–1
Task Attributes .................................................................................... 13–2
Task Variables...................................................................................... 13–3
Interprocess Relationships .................................................................. 13–4
Internal Processes ............................................................. 13–4
External Processes ............................................................ 13–4
Synchronous and Asynchronous Processes...................... 13–4
Dependent and Independent Processes ........................... 13–6
Details about Process Dependency................................... 13–6
Coroutines ........................................................................................... 13–8
Structuring a Program to Initiate Processes........................................ 13–9
Environment Division ......................................................... 13–9
Data Division .................................................................... 13–10
Naming the Program to Be Executed
(Alternate Method).............................................. 13–10
Declaring the Task Variable ..................................... 13–10
Describing the Formal Parameters in the
Called Program.................................................... 13–11
Describing the Formal Parameters in the
Calling Program................................................... 13–11
Describing the Actual Parameters in the
Calling Program................................................... 13–12
Procedure Division ........................................................... 13–12
Procedure Division Header in the Called
Program .............................................................. 13–12
Declaratives Section................................................ 13–13
Changing Task Attribute Values .............................. 13–13
Initiating External Procedures ................................. 13–13
Implementing Coroutines........................................ 13–14
Dissociating a Task Variable from a Process........... 13–14
Examples of Declaring the Object Code File
Name of the Called Program .............................. 13–14
Example of Passing Control between Two
Programs............................................................. 13–15
Preventing Critical Block Exits........................................................... 13–18

8600 1518–307

Contents

Section 14.

Report Writer
Overview............................................................................................. 14–1
File Section.......................................................................................... 14–2
Report Section .................................................................................... 14–3
Report Description Entry..................................................................... 14–3
CODE Clause ..................................................................... 14–4
CONTROL Clause .............................................................. 14–5
PAGE Clause...................................................................... 14–7
Special Counters ............................................................................... 14–11
LINE-COUNTER ............................................................... 14–11
PAGE-COUNTER ............................................................. 14–12
Report-Group Description Entry........................................................ 14–13
Report-Group Description Entry Format 1....................... 14–14
Report-Group Description Entry Format 2....................... 14–24
Report-Group Description Entry Format 3....................... 14–25
Procedure Division ............................................................................ 14–32
CLOSE Statement ........................................................... 14–32
GENERATE Statement .................................................... 14–34
INITIATE Statement......................................................... 14–36
OPEN Statement ............................................................. 14–37
SUPPRESS Statement..................................................... 14–39
TERMINATE Statement................................................... 14–40
USE AFTER STANDARD EXCEPTION PROCEDURE
Statement.................................................................... 14–41
USE BEFORE REPORTING Statement............................ 14–43
Report Writer Examples.................................................................... 14–44

Section 15.

Compiler Operations
Input and Output Data Flow................................................................ 15–2
COBOL Compiler Files ...................................................... 15–3
Input Files .......................................................................... 15–4
CARD File.................................................................. 15–4
SOURCE File ............................................................. 15–4
COPY Library Files .................................................... 15–4
INCLUDE Files .......................................................... 15–5
INITIALCCI File.......................................................... 15–5
Controlling Compiler Input ................................................. 15–7
Output Files ....................................................................... 15–8
CODE File.................................................................. 15–8
NEWSOURCE File .................................................... 15–8
LINE File.................................................................... 15–9
ERRORFILE File ........................................................ 15–9
Using System Support Libraries ....................................................... 15–10
Compiling and Executing COBOL Programs .................................... 15–11
Compiling and Executing through WFL ........................... 15–11
Compiling and Executing through CANDE ...................... 15–12
Compiling and Executing from the ODT.......................... 15–13
Displaying the Compiling Progress.................................. 15–13
Preventing Stack Overflows ............................................ 15–14

xvi

8600 1518–307

Contents

Types of Compiler Control Options ................................................... 15–15
Boolean Compiler Options ............................................... 15–15
Boolean Title Compiler Options ....................................... 15–16
Boolean Class Compiler Options ..................................... 15–16
Enumerated Compiler Options ........................................ 15–17
Immediate Compiler Options........................................... 15–17
String Compiler Options................................................... 15–18
User-Defined Compiler Options....................................... 15–18
Value Compiler Options ................................................... 15–18
Syntax for Compiler Control Options ................................................ 15–19
Compiler Control Records................................................ 15–19
Conditional Compilations Options.................................... 15–24
Setting Compiler Options When Initiating the
Compiler ...................................................................... 15–26
Compiler Options .............................................................................. 15–27
ANSI Option ..................................................................... 15–27
ANSICLASS Option.......................................................... 15–28
ASCII Option .................................................................... 15–32
AUTOINSERT Option ....................................................... 15–32
BINARYCOMP Option ..................................................... 15–33
BINARYEXTENDED Option.............................................. 15–33
BINDER_MATCH Option ................................................. 15–34
BINDINFO Option ............................................................ 15–35
BINDSTREAM Option ...................................................... 15–35
BOUNDS Option .............................................................. 15–37
CALL MODULE Option.................................................... 15–39
C68MOVEWARN Option ................................................. 15–39
CALLNESTED Option....................................................... 15–40
CODE Option ................................................................... 15–40
COMMON Option............................................................ 15–41
COMPATIBILITY Option .................................................. 15–41
Copy Boundary Options ................................................... 15–44
CONCURRENTEXECUTION Option................................. 15–45
CORRECTOK Option........................................................ 15–45
CORRECTSUPR Option ................................................... 15–45
CURRENCYSIGN Option.................................................. 15–46
DELETE Option ................................................................ 15–47
ELSE and ELSE IF Options .............................................. 15–47
EMBEDDEDKANJI Option ............................................... 15–48
END Option ...................................................................... 15–48
ERRORLIMIT Option........................................................ 15–49
ERRORLIST Option.......................................................... 15–49
FARHEAP Option ............................................................. 15–51
FEDLEVEL Option............................................................ 15–52
FOOTING Option ............................................................. 15–53
FREE Option .................................................................... 15–54
FS4XCONTINUE Option................................................... 15–55
INCLNEW Option............................................................. 15–55
INCLUDE Option.............................................................. 15–56
INLINEPERFORM Option ................................................ 15–58
IPCMEMORY Option ....................................................... 15–59
LEVEL Option................................................................... 15–60

8600 1518–307

xvii

Contents

LIBRARY Option .............................................................. 15–60
LIBRARYLOCK Option..................................................... 15–61
LIBRARYPROG Option .................................................... 15–61
LINEINFO Option............................................................. 15–62
LIST Option...................................................................... 15–62
LISTDOLLAR Option ....................................................... 15–63
LISTINCL Option.............................................................. 15–64
LISTINITIALCCI Option .................................................... 15–64
LISTIPCMEMORY Option................................................ 15–65
LISTOMITTED Option...................................................... 15–65
LISTP Option.................................................................... 15–66
LIST1 Option.................................................................... 15–66
LI_SUFFIX Option ............................................................ 15–67
LOCALTEMP Option ....................................................... 15–68
LOCALTEMPWARN Option ............................................ 15–68
LONGLIMIT Option.......................................................... 15–69
MAPONELINE Option ..................................................... 15–69
MAP or STACK Option .................................................... 15–70
MEMORY_MODEL Option.............................................. 15–70
MERGE Option ................................................................ 15–71
MODULEFAMILY Option ................................................ 15–72
MODULEFILE Option ...................................................... 15–72
MUSTLOCK Option ......................................................... 15–73
NEW Option..................................................................... 15–74
NEWID Option ................................................................. 15–75
NEWSEQERR Option ...................................................... 15–75
OMIT Option.................................................................... 15–76
OPT1 Option .................................................................... 15–77
OPT2 Option .................................................................... 15–78
OPT3 Option .................................................................... 15–78
OPT4 Option .................................................................... 15–79
OPTIMIZE Option ............................................................ 15–80
OPTION Option................................................................ 15–82
OWN Option .................................................................... 15–83
PAGE Option.................................................................... 15–83
PAGESIZE Option ............................................................ 15–83
PAGEWIDTH Option........................................................ 15–84
RPW (Report Writer) Option............................................ 15–84
SDFPLUSPARAMETERS Option ..................................... 15–84
SEARCH Option............................................................... 15–85
SEPARATE Option ........................................................... 15–86
SEQUENCE or SEQ Option ............................................. 15–87
Sequence Base Option .................................................... 15–87
Sequence Increment Option ........................................... 15–87
SHARING Option ............................................................. 15–88
SHOWOBSOLETE Option ............................................... 15–89
SHOWWARN Option....................................................... 15–89
STACK Option.................................................................. 15–89
STATISTICS Option ......................................................... 15–90
STRINGS Option .............................................................. 15–91
STRICTPICTURE Option .................................................. 15–92
SUMMARY Option .......................................................... 15–92

xviii

8600 1518–307

Contents

TADS Option .................................................................... 15–93
TARGET Option................................................................ 15–94
TEMPORARY Option ....................................................... 15–95
TITLE Option .................................................................... 15–96
UDMTRACK Option ......................................................... 15–96
VERSION Option.............................................................. 15–97
VOID Option..................................................................... 15–98
WARNFATAL Option ....................................................... 15–98
WARNSUPR Option....................................................... 15–100
XREF Option .................................................................. 15–100
XREFFILES Option ......................................................... 15–102
XREFLIT Option ............................................................. 15–103
Section 16.

Internationalization
Localization .......................................................................................... 16–1
Accessing the Internationalization Features........................................ 16–2
Using the Ccsversion, Language, and Convention
Default Settings ............................................................. 16–3
Hierarchy for Default Settings............................................ 16–4
Components of the MLS Environment ............................................... 16–5
Coded Character Sets and Ccsversions............................. 16–5
Mapping Tables ......................................................... 16–7
Data Classes.............................................................. 16–8
Text Comparisons ..................................................... 16–9
Sorting and Merging................................................ 16–10
Supporting Natural Languages......................................... 16–11
Creating Messages for an Application
Program .............................................................. 16–11
Creating Multilingual Messages for
Translation........................................................... 16–12
Supporting Business and Cultural Conventions............... 16–12
Using the Date and Time Features ......................... 16–13
Formatting the Date and Time with Syntax
Elements ............................................................. 16–13
Formatting the Date and Time with Library
Calls..................................................................... 16–14
Formatting Numerics and Currencies ..................... 16–15
Formatting Page Size .............................................. 16–15
Formatting Page Size with Syntax Elements .......... 16–15
Formatting Page Size with Library Call.................... 16–16
Summary of Language Syntax by Division........................................ 16–17
ENVIRONMENT DIVISION............................................... 16–17
DATA DIVISION ............................................................... 16–17
PROCEDURE DIVISION................................................... 16–18
Summary of CENTRALSUPPORT Library Procedures ...................... 16–22
Identifying Available Coded Character Sets and
Ccsversions ................................................................. 16–23
Mapping Data From One Coded Character Set to
Another ........................................................................ 16–23
Processing Data According to a Ccsversion .................... 16–24

8600 1518–307

xix

Contents

Comparing and Sorting Text ............................................ 16–25
Positioning Characters..................................................... 16–25
Determining Available Natural Languages....................... 16–25
Accessing CENTRALSUPPORT Library Messages ......... 16–26
Identifying Available Convention Definitions ................... 16–26
Obtaining Convention Information................................... 16–27
Formatting Dates According to a Convention ................. 16–28
Formatting Times According to a Convention ................. 16–29
Determining Default Page Size........................................ 16–29
Calling the CENTRALSUPPORT Library ............................................ 16–30
Implicit Calls..................................................................... 16–30
Explicit Calls..................................................................... 16–30
Parameter Categories ....................................................................... 16–32
Input Parameters ............................................................. 16–32
Input Parameters with Type Values................................. 16–32
Output Parameters .......................................................... 16–34
Result Parameter ............................................................. 16–34
Procedure Descriptions..................................................................... 16–35
CCSTOCCS_TRANS_TEXT .............................................. 16–35
CCSTOCCS_TRANS_TEXT_COMPLEX ........................... 16–39
CCSVSN_NAMES_NUMS ............................................... 16–45
CENTRALSTATUS ........................................................... 16–49
CNV_CURRENCYEDITTMP_DOUBLE_COB ................... 16–54
CNV_CURRENCYEDIT_DOUBLE_COB........................... 16–57
CNV_DISPLAYMODEL_COB........................................... 16–60
CNV_FORMATDATETMP_COB ...................................... 16–63
CNV_FORMATDATE_COB .............................................. 16–66
CNV_FORMATTIMETMP_COB ....................................... 16–70
CNV_FORMATTIME_COB............................................... 16–73
CNV_FORMSIZE.............................................................. 16–77
CNV_NAMES ................................................................... 16–80
CNV_SYMBOLS............................................................... 16–84
CNV_SYSTEMDATETIMETMP_COB............................... 16–90
CNV_SYSTEMDATETIME_COB ...................................... 16–93
CNV_TEMPLATE_COB .................................................... 16–97
CNV_VALIDATENAME .................................................. 16–101
GET_CS_MSG................................................................ 16–104
MCP_BOUND_LANGUAGES ........................................ 16–109
VALIDATE_NAME_RETURN_NUM ............................... 16–112
VALIDATE_NUM_RETURN_NAME ............................... 16–115
VSNCOMPARE_TEXT.................................................... 16–118
VSNESCAPEMENT ........................................................ 16–123
VSNGETORDERINGFOR_ONE_TEXT ........................... 16–127
VSNINSPECT_TEXT ....................................................... 16–132
VSNTRANS_TEXT .......................................................... 16–137
Errors............................................................................................... 16–141
Using the Properties File................................................................. 16–147
Example of Calling Procedures in the CENTRALSUPPORT
Library ......................................................................................... 16–163

8600 1518–307

Contents

Appendix A. Output Messages
Normal Compiler Output Messages .....................................................A–1
Numerical Compiler Output Messages ...............................A–1
Non-numerical Compiler Output Messages ......................A–83
Abnormal Compiler Output Messages..............................................A–107
Run-Time Compiler Output Messages..............................................A–108
Appendix B. Reserved Words

Appendix C. Interpreting General Formats
Uppercase Words..................................................................................C–2
Lowercase Words .................................................................................C–3
Rules for Creating User-Defined Words................................................C–4
Brackets.................................................................................................C–5
Braces....................................................................................................C–6
Vertical Bars ..........................................................................................C–7
Ellipses ..................................................................................................C–8
Punctuation Marks ................................................................................C–9
Mathematical Symbols........................................................................C–10
Appendix D. Using the Checkpoint/Restart Utility
CALLCHECKPOINT Procedure............................................................. D–2
CHECKPOINTDEVICE Option ............................................. D–2
CHECKPOINTTYPE Option ................................................. D–2
COMPLETIONCODE Option............................................... D–2
CHECKPOINTNUMBER Option .......................................... D–3
RESTARTFLAG Option........................................................ D–3
Restarting a Job ................................................................................... D–4
Checkpoint/Restart Messages ............................................................. D–6
Output Messages from an Attempt to Restart................... D–6
Output Messages and Completion Codes.......................... D–8
Locking ............................................................................................... D–11
Rerunning Programs........................................................................... D–11
CHECKPOINT Procedure Call Examples ............................................ D–12
Appendix E. COBOL Binding

Appendix F. Comparison of COBOL Versions
Differences Among COBOL Versions ................................................... F–2
Changes That Probably Affect Your Programs...................................... F–2
Changes That Might Affect Your Programs ........................................ F–31
Changes that Do Not Affect Your Programs ....................................... F–38

8600 1518–307

xxi

Contents

Appendix G. COBOL Migration
Migration Methods................................................................................G–1
COBOL Migration Tool (CMT)...............................................................G–2
CMT Migration Strategy ......................................................G–3
Verifying the COBOL Migration Tool is Available ................G–4
Running the COBOL Migration Tool....................................G–4
Getting Help.........................................................................G–4
Understanding the COBOL Migration Tool Report..............G–4
Changes Made by the CMT ..................................................................G–5
Language Elements .............................................................G–5
Identification Division ..........................................................G–9
Environment Division.........................................................G–10
Data Division......................................................................G–12
Procedure Division.............................................................G–17
Warnings Issued by the CMT .............................................................G–26
Language Element.............................................................G–26
Data Division......................................................................G–26
Procedure Division.............................................................G–27
Error Messages .................................................................G–29
Warning Messages............................................................G–39
Appendix H. Migrating V Series Intrinsics
Summary of Procedures .......................................................................H–2
BINARYDECIMAL Procedure................................................................H–6
DATECOMPILED Procedure.................................................................H–7
DATENOW Procedure ..........................................................................H–9
DECIMALBINARY Procedure..............................................................H–10
EVA_TASKSTRING Procedure ............................................................H–11
GETMCP Procedure ............................................................................H–13
GETPARAM Procedure .......................................................................H–14
GETSWITCH Procedure ......................................................................H–15
INTERROGATE Procedure ..................................................................H–16
JOBINFO Procedure ...........................................................................H–17
JOBINFO5 Procedure .........................................................................H–19
MIX Procedure ....................................................................................H–22
MIX5 Procedure ..................................................................................H–23
MIXID Procedure.................................................................................H–24
MIXID5 Procedure...............................................................................H–25
MIXNUM Procedure ...........................................................................H–28
MIXNUM5 Procedure .........................................................................H–29
MIXTBL Procedure..............................................................................H–32
MIXTBL5 Procedure............................................................................H–34
PROGINFO Procedure ........................................................................H–37
PROGINFO5 Procedure ......................................................................H–39
SETSWITCH Procedure ......................................................................H–42
SPOMESSAGE Procedure ..................................................................H–43
TIMENOW Procedure .........................................................................H–45
UNIQUENAME Procedure ..................................................................H–46
VDISKFILEHEADER Procedure...........................................................H–47

xxii

8600 1518–307

Contents

VREADTIMER Procedure ................................................................... H–50
VTRANSLATE Procedure.................................................................... H–52
Format 1: Translate DISPLAY Source to DISPLAY
Destination.................................................................... H–53
Format 2: Translate DISPLAY Source to COMP
Destination.................................................................... H–54
Format 3: Translate COMP Source to COMP
Destination.................................................................... H–54
Format 4: Translate COMP Source to DISPLAY
Destination.................................................................... H–54
Format 5: Translate Signed Numeric Source to
COMP Destination........................................................ H–55
Format 6: Translate Signed Numeric Source to
DISPLAY Destination.................................................... H–55
ZIP Procedure ..................................................................................... H–60
ZIPSPO Procedure.............................................................................. H–61
Appendix I.

Tips and Techniques
Improving Performance of COBOL85 Programs ................................... I–2
Distinguishing CALL Statements .......................................... I–2
Reading STREAM Files Faster .............................................. I–3
Generating Temporary Arrays with the
$LOCALTEMP Option ...................................................... I–6
Diagnosing Performance with the $STATISTICS
Option ............................................................................... I–7
Using Multiple Versions of COBOL85 on One
Server ............................................................................... I–8
Improving Reliability of Non-numeric Information in
COMPUTATIONAL Fields............................................... I–10
Maintaining Precision in Programs ..................................... I–11
Producing Object Files for Multiple ClearPath MCP
Servers............................................................................ I–11
Using Key Features of COBOL85 ........................................................ I–12
Nested Programs ................................................................ I–12
Intrinsic Functions ............................................................... I–13
LINENUMBER Function...................................................... I–14
Scope Terminators.............................................................. I–14
In-line Performs................................................................... I–14
EVALUATE Option .............................................................. I–15
$IF Option ........................................................................... I–15
$INCLUDE Option............................................................... I–16
INITIALCCI File.................................................................... I–16
CONSTANT Entry................................................................ I–17
USE AS EPILOG Procedure ................................................ I–17
COBOL85 Dump Analysis................................................... I–18
COBOL85 Library Interfaces............................................... I–19
SHAREDBYALL Libraries .................................................... I–20

Index

8600 1518–307

.............................................................................................. 1

xxiii

Contents

xxiv

8600 1518–307

Figures
1–1.

Sample of COBOL Coding Form ........................................................................ 1–5

7–1.
7–2.
7–3.
7–4.
7–5.

TEST BEFORE with One Identifier Varied........................................................ 7–75
TEST BEFORE with Two Identifiers Varied...................................................... 7–77
TEST AFTER Phrase with One Identifier Varied............................................... 7–78
TEST AFTER Phrase with Two Identifiers Varied............................................. 7–80
Valid PERFORM Structures.............................................................................. 7–84

8–1.

Format 1 SEARCH Statement with Two WHEN Phrases .................................. 8–6

10–1.
10–2.

Nested Source Programs ................................................................................. 10–2
Identical Program-Names ................................................................................. 10–8

14–1.

Page Format Control ...................................................................................... 14–10

15–1.

COBOL Compiler Input and Output Files ......................................................... 15–2

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

Coding the Format 4 ACCEPT Statement ...................................................... 16–19
Coding the MOVE Statement for Internationalization .................................... 16–20
Sample Data Declarations for Type Value Data Items ................................... 16–34
Calling the CCSTOCCS_TRANS_TEXT Procedure.......................................... 16–37
Calling the CCSTOCCS_TRANS_TEXT_COMPLEX Procedure ...................... 16–42
Calling the CCSVSN_NAMES_NUMS Procedure........................................... 16–47
Calling the CENTRALSTATUS Procedure....................................................... 16–52
Calling the CNV_CURRENCYEDITTMP_DOUBLE_COB Procedure .............. 16–55
Calling the CNV_CURRENCYEDIT_DOUBLE_COB Procedure ...................... 16–58
Calling the CNV_DISPLAYMODEL_COB Procedure ...................................... 16–61
Calling the CNV_FORMATDATETMP_COB Procedure.................................. 16–64
Calling the CNV_FORMATDATE_COB Procedure ......................................... 16–67
Calling the CNV_FORMATTIMETMP_COB Procedure .................................. 16–71
Calling the CNV_FORMATTIME_COB Procedure .......................................... 16–74
Calling the CNV_FORMSIZE Procedure ......................................................... 16–78
Calling the CNV_NAMES Procedure .............................................................. 16–81
Calling the CNV_SYMBOLS Procedure.......................................................... 16–86
Calling the CNV_SYSTEMDATETIMETMP_COB Procedure.......................... 16–91
Calling the CNV_SYSTEMDATETIME_COB Procedure ................................. 16–94
Calling the CNV_TEMPLATE_COB Procedure ............................................... 16–98
Calling the CNV_VALIDATENAME Procedure.............................................. 16–102
Calling the GET_CS_MSG Procedure ........................................................... 16–106
Calling the MCP_BOUND_LANGUAGES Procedure.................................... 16–110
Calling the VALIDATE_NAME_RETURN_NUM Procedure .......................... 16–113
Calling the VALIDATE_NUM_RETURN_NAME Procedure .......................... 16–116
Calling the VSNCOMPARE_TEXT Procedure ............................................... 16–120
Calling the VSNESCAPEMENT Procedure ................................................... 16–125

8600 1518–307

xxv

Figures

16–28.
16–29.
16–30.
16–31.
16–32.

xxvi

Calling the VSNGETORDERINGFOR_ONE_TEXT Procedure ...................... 16–129
Calling the VSNINSPECT_TEXT Procedure .................................................. 16–133
Calling the VSNTRANS_TEXT Procedure ..................................................... 16–138
Sample Declarations for Message Values ................................................... 16–142
Calling Procedures in the CENTRALSUPPORT Library................................ 16–166

8600 1518–307

Tables
1–1.
1–2.
1–3.
1–4.
1–5.
1–6.
1–7.
1–8.

Areas of a Line of Code for Columns 1–72 ........................................................ 1–6
Areas of a Line of Code for Characters ............................................................ 1–13
Valid Separator Characters ............................................................................... 1–14
Types of Reserved Words................................................................................ 1–16
Figurative Constants......................................................................................... 1–17
Special Registers .............................................................................................. 1–20
Special Character Words .................................................................................. 1–22
Types of User-Defined Words.......................................................................... 1–26

3–1.
3–2.
3–3.
3–4.
3–5.
3–6.

I-O Status Codes: Successful Execution.......................................................... 3–49
I-O Status Codes: Unsuccessful READ—End-of-File Condition....................... 3–50
I-O Status Codes: Unsuccessful I/O—Invalid Key Condition ........................... 3–51
I-O Status Codes: Unsuccessful I/O—Permanent Error Condition .................. 3–52
I-O Status Codes: Unsuccessful I/O—Invalid Operations ................................ 3–53
I-O Status Codes: Unisys Defined Conditions.................................................. 3–54

4–1.
4–2.
4–3.
4–4.
4–5.

Relationship between Class and Category of Data Items.................................. 4–5
Picture Clause Symbols.................................................................................... 4–33
Specification of Data Item Categories in the PICTURE Clause........................ 4–38
Types of Editing for Data Item Categories ....................................................... 4–41
Precedence Rules ............................................................................................ 4–48

5–1.
5–2.
5–3.
5–4.
5–5.
5–6.
5–7.

Elements of a Procedure.................................................................................. 5–10
Categories of COBOL Verbs ............................................................................ 5–16
Combination of Symbols in Arithmetic Expressions ........................................ 5–27
Numeric Comparisons Involving HIGH-VALUES .............................................. 5–44
Numeric Comparisons Involving LOW-VALUES .............................................. 5–45
Truth Table for Logical Operators..................................................................... 5–58
Combinations of Conditions, Logical Operators, and Parentheses.................. 5–59

6–1.
6–2.
6–3.
6–4.
6–5.
6–6.

Effect of the $ANSI and $ANSICLASS Compiler Options.................................. 6–3
Parameter Mapping among Languages ........................................................... 6–25
Formal and Actual Parameters for Bound Procedures ..................................... 6–34
Parameter Mapping for Tasking Calls .............................................................. 6–42
Relationship of File Types and CLOSE Formats............................................... 6–67
Relationship of CLOSE Formats and Nonsequential Units .............................. 6–72

7–1.
7–2.
7–3.
7–4.
7–5.

Categories of Elementary Data Items .............................................................. 7–39
Valid MOVE Actions ......................................................................................... 7–40
Result of OPEN Statement .............................................................................. 7–58
Permissible Statements—Sequential Files ...................................................... 7–59
Permissible Statements—Relative and Indexed Files...................................... 7–60

8–1.

Valid Operand Combinations for the SET . . . TO Statement ........................... 8–20

8600 1518–307

xxvii

Tables

9–1.
9–2.
9–3.
9–4.
9–5.
9–6.
9–7.
9–8.
9–9.

Intrinsic Functions .............................................................................................. 9–2
Types of Functions............................................................................................. 9–5
Types of Arguments for Functions .................................................................... 9–8
CURRENT-DATE Function, Characters 1–21 ................................................... 9–22
CURRENT-DATE Function, Characters 18–19 ................................................. 9–23
CURRENT-DATE Function, Characters 20–21 ................................................. 9–23
WHEN-COMPILED Function, Characters 1–21 ............................................... 9–76
WHEN-COMPILED Function, Characters 18–19 ............................................. 9–77
WHEN-COMPILED Function, Characters 20–21 ............................................. 9–77

10–1.

COBOL85 Program Communication Techniques ............................................ 10–1

11–1.
11–2.
11–3.

Syntax Differences for COBOL85 Libraries ..................................................... 11–6
Syntax Differences for COBOL85 User Programs........................................... 11–8
Data Type Mapping between COBOL85, ALGOL, and Pascal ...................... 11–11

12–1.

File Organization and Access Mode............................................................... 12–14

14–1.
14–2.

Page Regions Established by the PAGE Clause ............................................ 14–10
Permissible Clause Combinations in Format 3 Report Group
Description Entries .................................................................................... 14–31

15–1.
15–2.

Compiler Input Files ......................................................................................... 15–3
Compiler Output Files ...................................................................................... 15–3

16–1.
16–2.
16–3.
16–4.
16–5.
16–6.

System Default Settings for Internationalization ............................................. 16–3
Types of Comparisons Provided by CENTRALSUPPORT Library.................... 16–9
Valid Character Substitution Types ................................................................ 16–10
CENTRALSUPPORT Library Procedures for Formatting Date and Time ....... 16–14
Symbols and Offsets Returned in the SYM-ARY Record .............................. 16–88
Error Result Values....................................................................................... 16–143

C–1.

Valid Mathematical Symbols............................................................................ C–10

H–1.
H–2.
H–3.
H–4.
H–5.

EVASUPPORT Library Procedures.....................................................................H–2
Values in JOBINFO Result Structure ...............................................................H–18
Values in JOBINFO5 Result Structure .............................................................H–20
Table Structure for MIXTBL Procedure............................................................H–33
Values of the SPECIAL-PROGRAM-CODE Field for the MIXTBL
Procedure ....................................................................................................H–33
H–6.
Table Structure for MIXTBL5 Procedure..........................................................H–35
H–7.
Values of the SPECIAL-PROGRAM-CODE Field for the MIXTBL5
Procedure ....................................................................................................H–36
H–8.
Values in PROGINFO Result Structure ............................................................H–38
H–9.
Values in PROGINFO5 Result Structure ..........................................................H–40
H–10. ClearPath and A Series File Attributes for VDISKFILEHEADER Fields ............H–49

xxviii

8600 1518–307

Section 1
Program Structure and Language
Elements

About This Manual
Common Business-Oriented Language (COBOL) is a programming language that enables
a programmer to write computer instructions in a language much like standard English.
This implementation of COBOL85 follows the American National Standard Programming
Language COBOL ANSI X3.23-1985.
This manual provides the complete COBOL85 syntax and the extensions to COBOL85.
Information concerning the interface between COBOL ANSI-85 and various products is
located in Volume 2 of this manual, subtitled, “Product Interfaces.”
This section describes the

•

Components of a source program

•

Rules for entering the components in the source program

•

The COBOL character set

•

Punctuation characters used as separators

•

Various elements that make up the language, such as COBOL words, identifiers,
literals, and figurative constants

Purpose
This manual explains the syntax and concepts of this implementation of the Common
Business-Oriented Language (COBOL) ANSI-85.

Audience
The primary audience for this manual includes programmers and systems analysts who
are experienced in developing, maintaining, and reading COBOL programs. The
secondary audience consists of technical support personnel and information systems
management. A possible tertiary audience includes programmers who are learning
COBOL; however, note that the manual is not designed for this audience.

8600 1518–307

1–1

About This Manual

Conventions
Throughout this manual, Unisys extensions to the American National Standard for
Programming Language COBOL, ANSI X3.23-1985 are highlighted.
In addition, the term ClearPath MCP servers refers to ClearPath NX, LX, CS, and Libra
Series servers.
Unless otherwise stated, the term Windows is used in this book to refer to Windows NT
Server 4.0; Windows NT Server 4.0, Enterprise Edition; Windows 2000 Server; and
Windows 2000 Advanced Server.

Acknowledgments
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 have
specifically authorized the use of this material, in whole or in part, in the COBOL
specifications. These authors or copyright holders are the following:
IBM: IBM Commercial Translator Form No. F 28-8013 (copyright 1959)
Minneapolis-Honeywell: FACT, DSI 27A5260-2760 (copyright 1960)
Sperry Rand Corporation: FLOW-MATIC, Programming for the UNIVAC (R) I and II, Data
Automation Systems (copyright 1958, 1959)
Such authorization extends to the reproduction and use of COBOL specifications in
programming manuals or similar publications.

1–2

8600 1518–307

Program Overview

Program Overview
The program written in COBOL is called the source program. Before a computer can read
a source program, the COBOL instructions must be translated into machine language.
This translation is the job of the COBOL compiler. First, the COBOL compiler verifies that
the source program satisfies all the rules of the COBOL language. Then the compiler
translates the COBOL instructions to machine language and produces an object program
that contains the translated instructions.
After compilation, the COBOL compiler prints a copy of the source program and lists any
compilation errors on that printout. If program corrections are necessary, you can make
the appropriate changes in the source program and then recompile it.

Divisions of a Source Program
A COBOL source program consists of four parts called divisions. Each division has a
heading and can contain one or more sections or paragraphs, which are constructed and
combined according to specific rules. The divisions of a COBOL source program must
occur in the order shown.

Division

Purpose

Identification
Division

Identifies and describes the program.

Environment
Division

Identifies file processing requirements, hardware requirements,
computers used, nonstandard internal memory allocation for
files, and notation used throughout the program. This division is
optional in certain programming situations.

Data Division

Describes the data elements that the object program is to
manipulate or create. These data elements can be constants or
items within files, records, or program work areas. This division
is optional in certain programming situations.

Procedure Division

Defines the steps needed to accomplish a desired task using
the data defined in the Data Division. This division is optional in
certain programming situations.

8600 1518–307

1–3

Contents of a Division

Contents of a Division
Divisions can contain one or more sections. A section is made up of paragraphs, which
are formed by a variety of sentences, statements, clauses, phrases, and words. The
following table describes the language elements that make up a COBOL85 division.

Element

1–4

Description

Section

A section consists of a section header optionally followed by one or
more entries in the Data Division or one or more paragraphs in the
Environment and Procedure divisions.

Paragraph

In the Identification and Environment Divisions, a paragraph consists of
a paragraph header optionally followed by one or more entries. In the
Procedure Division, a paragraph consists of a paragraph-name with a
separator period at the end, optionally followed by one or more
sentences.

Clause

A clause is an ordered set of consecutive COBOL character-strings that
specify an attribute of an entry.

Phrase

A phrase is an ordered set of consecutive COBOL character-strings that
form a portion of a COBOL procedural statement or a COBOL clause.

Sentence

A sentence is a sequence of one or more statements, the last of which
is terminated by a separator period.

Statement

A statement is a syntactically valid combination of words, literals, and
separators that begins with a verb.

Word

A COBOL word is a string of a maximum of 30 characters. The valid
types of COBOL words and the rules for forming them are described
later in this section under the heading “Types of COBOL Words.”

Separator

A character or a space that is used to punctuate a portion of a COBOL
program.

8600 1518–307

Reference Format

Reference Format
The COBOL compiler expects the components of your source program to appear in
specific areas along a line of code. Each line has 72 columns, which are grouped into five
areas. This line-formatting scheme is referred to as the reference format. Specific
portions of a program must be placed in each area on the coding form. Predesigned
coding forms are available to assist you in structuring lines of code in the correct way. An
example of a coding form is shown in Figure 1–1.

Figure 1–1. Sample of COBOL Coding Form

8600 1518–307

1–5

Reference Format

Table 1–1 describes the areas in which specific information must be placed in a line of
code.
Table 1–1. Areas of a Line of Code for Columns 1–72

Columns

Area

Description

1–6

Sequence field

You can put a sequence number in this area to
label a source program line. The sequence number
can consist of any character in the character set of
the computer. The content of the sequence
number area does not need to be unique or to have
any particular sequence.

Indicator area

You can place a symbol in this area to indicate that
the succeeding line is of a specific type. The types
of lines and the symbols used to denote them are
as follows:
To denote a . . .
Continuation line, use a hyphen (-)
Comment line, use an asterisk (*) or a slash (\)
Debugging line, use the letter D
Compiler control option, use a dollar symbol ($)
When the FREE compiler option is

8–11

12–72

1–6

Area A

Area B

•

Set, any character in column 7 other than an
asterisk, slash, hyphen, dollar sign, or space is
treated as part of the source image.

•

Reset, any character in column 7 other than an
asterisk, slash, hyphen, or dollar sign is treated
as a space.

The items that must begin in this area are as
follows:

•
•

Division, section, and paragraph headers

•
•

The level indicators FD and SD

The keywords DECLARATIVES and END
DECLARATIVES
The level numbers 01 and 77

Items not placed in the other areas must begin and
end at some position in this area.

8600 1518–307

Division and Section Headers

Division and Section Headers
A division header is a combination of words, followed by a separator period, that
indicates the beginning of a division.
A section header is a combination of words, followed by a separator period, that
indicates the beginning of a section. Section headers are used in the Environment, Data,
and Procedure Divisions. In the Environment and Data Divisions, a section header is
composed of reserved words followed by a separator period.
The valid section headers for the Environment Division are
CONFIGURATION SECTION.
INPUT-OUTPUT SECTION.
The valid section headers for the Data Division are
FILE SECTION.
DATA-BASE SECTION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
COMMUNICATION SECTION.
LOCAL-STORAGE SECTION.
REPORT SECTION.
PROGRAM-LIBRARY SECTION.
In the Procedure Division, a section header consists of a user-defined section-name
followed by the reserved word SECTION. The section header must end with a period.
Note: The compiler ignores segment numbers that follow the reserved word SECTION
in a section header. You can retain the segment numbers, but it is recommended that
you make the Segmentation module a comment for the sake of clarity. Note that the
Segmentation module has been placed in the obsolete element category.

8600 1518–307

1–7

Level-Numbers

Level-Numbers
A level-number is a one- or two-digit number that indicates the hierarchical position or a
special characteristic of a data item. Level-number 1 is typically used for a line that
identifies a record. Level-numbers 2 through 49 typically specify fields within the record.
Level numbers 66, 77, and 88 have specific meanings in COBOL and identify a special
property of the data in the field.
When specific level-numbers appear in a general format, COBOL requires that you use
those level-numbers in your COBOL program. For more information on level-numbers,
refer to Section 4.
Example
The following example shows an input record for a magazine subscription list. The
01-level entry identifies the record. The 05-level entries identify a name and an address
field within the record. The 07-level entries specify the content of each field in the record.
Note that you could use any numbers from 02 through 49 in place of 05 and 07.
01

1–8

MAGAZINE-SUBSCRIPTION-INPUT-RECORD.
05 NAME.
07 FIRST
07 MIDDLE-INITIAL
07 LAST
05 ADDRESS.
07 STREET
07 CITY
07 STATE-ABBREV
07 ZIP-CODE

PIC X(10).
PIC X(2).
PIC X(13).
PIC
PIC
PIC
PIC

X(12).
X(10).
X(2).
x(10).

8600 1518–307

Special-Purpose Lines—Fixed Indicators

Special-Purpose Lines—Fixed Indicators
In addition to standard lines of code, there are several special-purpose lines that you can
include in a source program. Special-purpose lines are usually designated by a special
character in the indicator area (column 7) of the line. The types of special-purpose lines
and their associated characters are as follows:

Type of Line

Special Character

Comment line

Asterisk (*) or slash (/)

Continuation line

Hyphen (-)

Debugging line

Letter D (D)

Compiler control option line

Dollar sign ($)

Blank line

Blank

Continuation Lines
Sometimes a line of code requires more than the 72 characters allocated on a coding
form. You can continue any entry, including a sentence, phrase, clause, word, literal, or
PICTURE character-string onto a subsequent line. The subsequent line is called a
continuation line.
Designating a Continuation Line
You designate a continuation line by placing a hyphen (-) in the indicator area (column 7)
of a line. The hyphen indicates that the first nonblank character in area B (columns 1272)
of the continuation line follows the last nonblank character of the preceding line (with no
spaces). If the indicator area of a line does not contain a hyphen, the compiler assumes
that a space precedes the first nonblank character in the line. Area A of a continuation
line must be blank.
Rules
You can use successive continuation lines. Also, you can place comment lines and blank
lines between a line and its continuation lines.
Double-byte names must be placed completely on a single line. You cannot continue
some of the characters of a double-byte name onto a continuation line.
When you use continuation lines with pseudocode, note that the characters that
compose the pseudocode designator (==) must be on the same line.

8600 1518–307

1–9

Special-Purpose Lines—Fixed Indicators

When you use a continuation line with a nonnumeric literal, an undigit literal, or a national
literal, observe the following rules:

•

Use all 72 columns of the line to be continued. All spaces at the end of the line are
considered to be part of the literal.

•

Do not place a quotation mark (") or a commercial at sign (@) in column 72 of the line
to be continued. Doing so delimits the literal and prevents it from being continued.

•

Enter a quotation mark (for a nonnumeric literal), a commercial at sign (for an undigit
literal), or the delimiter N" (for a national literal) as the first nonblank character in area
B. The literal continues with the character immediately following the quotation mark
or commercial at sign.

Examples
The following example shows how a SELECT statement is continued over two lines.
200100
200110-

SELECT MASTERFILE ASSIGN TO DISK OR
GANIZATION IS SEQUENTIAL.

The following example assumes that the Y in the word KEY is in column 72, the end of
Area B. The literal must end with a quotation mark. Thus, a continuation line is needed
that begins with a quotation mark (to signify a nonnumeric literal) and ends with a
quotation mark (to end the literal).
200120 01
200130-

WARNING-MESSAGE PIC X(24) VALUE IS "WRONG ENTRY FOR THIS KEY
" " .

Comment Lines
A comment line is any line with an asterisk (*) or a slash (/) in the indicator area
(position 7) of the line. A comment line can appear as any line in a source program after
the Identification Division header and as any line in library text of a COBOL library. You
can include any combination of the characters from the computer’s character set,
including national standard data format characters, in area A and area B of a comment
line.
A slash in the indicator area causes page ejection before the comment line if the listing of
the source program is printed. An asterisk in the indicator area causes the line at the next
available line position in the listing to be printed. The asterisk or slash and the characters
in area A and area B appear on the listing but serve as documentation only. For example,
if you want a heading at the top of a page, type a slash in the indicator area and the
heading in areas A and B. The compiler does not perform a syntax check on comment
lines.

1–10

8600 1518–307

Special-Purpose Lines—Fixed Indicators

Floating Comment Indicator
A comment indicator, signified by the symbols *>, is used to indicate the following:

•

A comment line, when specified as the first character-string in the program-text area

•

A floating inline comment, when specified following one or more character-strings in
the program-text area, subject to the following conditions:

−

The floating comment indicator of an inline comment must be preceded by a
separator space; it can be specified wherever a separator space can be
specified.

−

For purposes of analyzing the text of a compilation group, a space is implied
immediately following a floating comment indicator.

−

When a floating comment indicator is present, the rest of the line is treated as a
comment.

−

All the characters that form a multiple-character floating comment must be
specified on the same line.

Debugging Lines
A debugging line is any line with a D in the indicator area (column 7) of the line. A
debugging line with spaces in columns 8 through 72 is considered to be the same as a
blank line. You can enter a debugging line anywhere after the OBJECT-COMPUTER
paragraph.
Debugging lines are used when the debugging module is activated. The debugging
module is activated when you specify the WITH DEBUGGING MODE clause in the
SOURCE-COMPUTER paragraph. If you do not activate the debugging module, the
compiler treats a debugging line like a comment line. Thus, you should make sure that
your program is syntactically correct when the debugging lines are considered to be
comment lines. $FREE must be reset to compile debugging lines.
You can use successive debugging lines, and you can continue debugging lines. Each
continued debugging line must contain a D in the indicator area. Character-strings cannot
be continued across multiple lines.
Example
The following example shows the use of debugging lines.
010000
100000
100050
100100

IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER MICROA WITH DEBUGGING MODE.
.
.
.
100600 WORKING-STORAGE Section.
100700D77 PERFORMANCE-COUNT
PIC 9(4).
100800D77 BAD-RECORDS
PIC 9(4).

8600 1518–307

1–11

Special-Purpose Lines—Fixed Indicators

100900D77 RATIO
PIC 9(4) 99.
.
.
.
101000 PROCEDURE DIVISION.
102000 OPEN-IT.
102100
OPEN INPUT GUEST-FILE.
103000D
MOVE ZEROS TO PERFORMANCE-COUNT, BAD-RECORDS, RATIO.
104000 READ-IT.
104100
READ GUEST-FILE AT END GO TO FINISH-IT.
105000D
ADD 1 TO PERFORMANCE-COUNT.
106000D
IF IN-KEY NOT NUMERIC ADD 1 TO BAD-RECORDS.
.
.
.
107000
GO TO READ-IT.
108000 FINISH-IT.
108100
CLOSE GUEST-FILE.
109000D
DIVIDE PERFORMANCE-COUNT BY BAD-RECORDS GIVING RATIO.
.
.
.

Compiler Control Option Lines
A compiler control option is designated by a line that has a dollar sign ($) in the indicator
area (column 7) of the line. Such a line specifies the compiler control options to be used
during the compilation process. For details about compiler control options, refer to
Section 15.

Blank Lines
A blank line is a line that has no characters except blanks in Area B (positions 8 through
72). You can include blank lines anywhere in the source program to help make it more
readable.

Pseudotext
Pseudotext is a sequence of text words, comment lines, or the separator space in a
source program or COBOL library bounded by, but not including, pseudotext delimiters.
Pseudotext delimiters are two contiguous equal sign (=) characters that surround the
pseudotext. Pseudotext must not consist entirely of a separator comma or a separator
semicolon.
The text or space that makes up pseudotext can start in either area A or area B. If,
however, a hyphen (-) is in the indicator area of a line that follows the opening pseudotext
delimiter, area A of the line must be blank, and the normal rules for continuation lines
apply to the formation of text. For more information on the use of the hyphen, refer to
“Continuation Lines” earlier in this section.

1–12

8600 1518–307

COBOL Character Set

COBOL Character Set
The characters you use to write a COBOL source program include the letters of the
alphabet, digits, and special characters. The standard character set is shown in Table 1–2.
Certain characters of the COBOL character set might not be represented graphically in
definitions of national and international standard character sets. In these instances, you
can specify a substitute graphic to replace the character or characters not represented.
Table 1–2. Areas of a Line of Code for Characters

Character

Meaning

0 through 9

Digit

A through Z

Uppercase letter

a through z

Lowercase letter

(Blank)

Space

Plus sign

Minus sign (hyphen)

Asterisk

Slant (slash)

Equal sign

Currency (dollar) sign

Comma (decimal point)

;

Semicolon

Period (decimal point, full stop)

Quotation mark

(

Left parenthesis

)

Right parenthesis

Greater than symbol

Less than symbol

Colon

Underscore

8600 1518–307

1–13

Using Separator Characters for Punctuation

Using Separator Characters for Punctuation
When writing the text of a source program, you often need to show where one language
element ends and the next one begins. You can differentiate between language
elements by using separator characters. Sometimes separators are required by a general
format. Other times, you can use separators at your discretion to improve the readability
of your program. The characters you can use as separators and the rules for using them
are described in Table 1–3. Note that the rules provided in Table 1–2 do not apply to the
characters contained in nonnumeric literals, comment-entries, or comment lines.
Table 1–3. Valid Separator Characters

Separator

(space)

Guidelines for Use

Spaces can precede or follow all other separators except when
restricted by reference format rules as discussed in this section.
All spaces that immediately follow the comma, semicolon, or period
are recognized as part of that separator and are not recognized as
the space separator.
A space is required before the opening pseudotext delimiter.
A space that follows the opening quotation mark (" ) of a
nonnumeric literal is considered to be part of the literal. A space
that precedes the ending quotation mark of a nonnumeric literal is
considered to be part of the literal.

A period marks the end of a COBOL entry. The period must be
followed by a space, which is interpreted as part of the period
separator.

, ;

You can use the comma and semicolon as separators anywhere you
would use a space, with the exception that you cannot use the
comma as a separator in a PICTURE character-string.
You should include a space after the comma or semicolon
separators. Although the compiler may permit the omission of the
trailing space if the resulting code is not ambiguous, it is
recommended that you include the space to prevent encountering
problems when a space is required, but not supplied.

( )

1–14

A pair of parentheses (left and right) delimits subscripts, reference
modifiers, arithmetic expressions, and conditions. They must
appear only in balanced pairs of left and right.

8600 1518–307

Using Separator Characters for Punctuation

Table 1–3. Valid Separator Characters

Separator

" "

Guidelines for Use

Quotation marks delimit nonnumeric literals. They must appear in
balanced pairs, except when the literal is continued onto another
line.
A line that is to be continued must contain opening quotation marks
preceding the literal. Each continuation line contains opening
quotation marks as the first nonblank character in Area B. The last
continuation line contains closing quotation marks following the
literal.
An opening quotation mark must be immediately preceded by a
space, left parenthesis, comma, or semicolon.
A closing quotation mark must be followed immediately by a space,
right parenthesis, comma, semicolon, or period.

Two contiguous equal signs are pseudotext delimiters. You must
place two contiguous equal signs at the beginning of a line of
pseudotext and at the end of the line.
An opening pseudotext delimiter must be immediately preceded by
a space.
A closing pseudotext delimiter must be immediately followed by a
space, comma, semicolon, or period.

The colon is a required separator when it appears in general
formats.

The at-sign character delimits undigit literals.
An opening at-sign character must be preceded immediately by a
space, comma, semicolon, or left parenthesis.
A closing at-sign character must be followed immediately by a
space, comma, semicolon, period, or right parenthesis.

The letter B followed by a quotation mark is an opening separator
for a Boolean literal. You must use another quotation mark to end
the Boolean literal. The B" separator must be preceded by a space
or a left parenthesis.

The letter N followed by a quotation mark is an opening separator
for a national literal. You must use another quotation mark to end
the national literal. The N" separator must be preceded by a space
or a left parenthesis.

Note: Any punctuation character that you use in a PICTURE character-string or a
numeric literal is considered to be part of the string or literal rather than a punctuation
character. You can delimit PICTURE character-strings with spaces, commas, semicolons,
or periods.

8600 1518–307

1–15

Types of COBOL Words

Types of COBOL Words
A COBOL word is a character-string that contains a maximum of 30 characters. Words
can be classified into three categories:

•

Reserved words (compiler-defined)

•

System-names

•

User-defined words

You cannot use a reserved word as a system-name or a user-defined word.
You can use the same word for a system-name and a user-defined word. The compiler
can determine how the word is to be used by the context of the clause or phrase in
which the word occurs.
The following paragraphs describe the types of COBOL words.

Reserved Words
A reserved word is a COBOL85 word that has a specific meaning to the compiler and is
reserved for use only as indicated by a general format. A reserved word appears in
uppercase letters in the general formats. When the reserved word is a required part of
the syntax, it appears underlined. Underlined reserved words are called keywords. If a
reserved word is not underlined, you can omit it from the syntax.
A reserved word cannot appear in the program as a user-defined word or a systemname. Table 1–4 shows the way reserved words are used by the COBOL language.
Table 1–4. Types of Reserved Words

Word Types

Purpose

Connectives

Qualify data, link operands in a series, or link logical operators to
form conditions.

Figurative constants

Associate names with commonly used values.

Functions

Associate names with commonly used calculations.

Special registers

Serve as compiler-generated, read-only storage areas that access
specific COBOL85 features.

Arithmetic and
relational operators

Indicate arithmetic operation or quantify a relation.

Keywords and
optional words

Satisfy the requirements of the syntax and improve the readability
of your program.

The following paragraphs describe each of the types of reserved words. A complete list
of reserved words is provided in Appendix B.

1–16

8600 1518–307

Types of COBOL Words

Connectives
Connectives are reserved words that you can use in one of the following ways:

•

As qualifiers to associate data-names, condition-names, text-names, or paragraphnames. Examples of qualifier connectives are OF and IN.

•

As logical connectives to form conditions. Examples of logical connectives are AND
and OR.

Figurative Constants
A figurative constant is a reserved word, such as ALL or SPACES, that takes on the value
implied by the word.
You can use figurative constants in place of a literal in a general format. However, if the
literal is restricted to a numeric literal, you are limited to the figurative constant ZERO or
its alternate forms ZEROS and ZEROES.
When you use a figurative constant in a context that requires national data, the figurative
constant represents a national literal value.
The figurative constants you can use and the values they imply are described in Table
1-5. Note that the singular and plural forms of figurative constants are equivalent, so you
can use them interchangeably.
Table 1–5. Figurative Constants

The figurative
constant . . .

Represents . . .

ZERO, ZEROS, or
ZEROES

The numeric value 0 or one or more of the 0 characters from the
computer's character set. For national data, it represents the
national literal @A3B0@.

SPACE OR
SPACES

One or more space characters. For national data, it represents the
national literal @A1A1@.

HIGH-VALUE or
HIGH-VALUES

One or more of the characters that has the highest ordinal position
in the program collating sequence. For national data, it represents
the national literal @FFFF@ .
The actual characters associated with each figurative constant
depend upon the program collating sequence specified.
To define HIGH-VALUE in the SPECIAL-NAMES paragraph of the
Environment Division (invalid for national literals), you must use the
ALPHABET clause. For details, refer to “SPECIAL-NAMES
Paragraph” in Section 3.

8600 1518–307

1–17

Types of COBOL Words

Table 1–5. Figurative Constants

The figurative
constant . . .

LOW-VALUE or
LOW-VALUES

Represents . . .

One or more of the characters that has the lowest ordinal position in
the program collating sequence. For national data, it represents the
national literal @0000@ .
The actual characters associated with each figurative constant
depend upon the program collating sequence specified.
To define LOW-VALUE in the SPECIAL-NAMES paragraph of the
Environment Division (invalid for national literals), you must use the
ALPHABET clause. For details, refer to “SPECIAL-NAMES
Paragraph” in Section 3.

QUOTE or
QUOTES

One or more quotation marks ("). For national data, it represents the
national literal @A1C9@ .
You can use the following statement to avoid using a literal:
MOVE QUOTE TO PRINT-LINE
You cannot use the word QUOTE or QUOTES in place of the
quotation mark in a source program to enclose a nonnumeric literal.
Thus, QUOTE ABD QUOTE is incorrect as a way of stating the
nonnumeric literal “ABD”.

ALL literal

A continuous sequence of an alphanumeric or a national literal. The
literal must be nonnumeric and must not be a figurative constant.
Note that associating the figurative constant [ALL] literal, and a
literal of length greater than one, with a data item that is numeric or
numeric-edited is becoming obsolete in COBOL ANSI-85 and will be
deleted from the next revision of the COBOL standard.

[ALL] symboliccharacter

The name of a position in the collating sequence.
For example, the end-of-text position does not have a name. If you
designate ETX IS 14, the name ETX becomes the same as position
14 in the collating sequence. Then, you can use the name ETX in
your program.
You designate the symbolic-character in the SYMBOLIC
CHARACTERS clause of the SPECIAL-NAMES paragraph in the
Environment Division. Refer to “SPECIAL-NAMES Paragraph” in
Section 3.

1–18

8600 1518–307

Types of COBOL Words

When you use a figurative constant other than the [ALL] literal, using the word ALL is
redundant and is for readability purposes only.
When a figurative constant represents a string of one or more characters, the compiler
determines the length of the string from context according to the following rules:

•

When a figurative constant is specified in a VALUE clause, or when a figurative
constant is associated with another data item (for example, when the figurative
constant is moved to or compared with another data item), the string of characters
specified by the figurative constant is repeated character by character on the right
until the size of the resultant string is greater than or equal to the number of
character positions in the associated data item.
The resultant string is then truncated from the right until it is equal to the number of
character positions in the associated data item. This truncation is done before, and
independently of, the application of any JUSTIFIED clause that might be associated
with the data item.

•

When a figurative constant, other than the [ALL] literal, is not associated with
another data item (for example, when the figurative constant appears in a DISPLAY,
STOP, STRING, or UNSTRING statement), the length of the string is one character.

•

When the figurative constant [ALL] literal is not associated with another data item,
the length of the string is the length of the literal.

•

When a figurative constant is used in conjunction with the VALUE clause as part of a
data description entry, editing characters in the PICTURE clause are included in
determining the size of the data, but they have no effect on the initialization of the
data item.

Functions
A function is a temporary data item whose value is derived automatically at the time of
reference during the execution of the object program. Functions are specified by a
function-identifier, which consists of the reserved word FUNCTION, a reserved functionname, and optional user-defined arguments. Functions are described in detail in
Section 9.

8600 1518–307

1–19

Types of COBOL Words

Special Registers
Special registers are compiler-generated storage areas whose primary use is to store
information produced by specific COBOL features. Table 1–6 describes the special
registers.
Table 1–6. Special Registers

The register . . .

DATE

Contains . . .

If DATE is followed by the qualifier "YYYYMMDD", the system
date is formatted as an unsigned, 8-digit elementary numeric
integer made up of the year (four digits), month of the year
(two digits) and the day of month (two digits). For example,
July 1, 1993 is expressed as 19930701.
If DATE is not qualified, the system date is formatted as an
unsigned, 6-digit elementary numeric integer made up of the
year of the century (two digits), the month of year (two digits),
and the day of the month (two digits). For example, July 1,
1993 is expressed as 930701.
To query this special register, use Format 2 of the ACCEPT
statement.

DAY

If DAY is followed by the qualifier "YYYYDDD", the system date
is formatted as an unsigned, 7-digit elementary numeric integer
made up of the year (four digits) followed by the number of
days since the beginning of the year (three digits). For
example, July 1, 1993 is expressed as 1993183.
If DAY is not qualified, the system date is formatted as an
unsigned 5-digit elementary numeric integer made up of the
year of the century (two digits) followed by the number of days
since the beginning of the year (three digits). For example, July
1, 1993 is expressed as 93183.
To query this special register, use Format 2 of the ACCEPT
statement.

1–20

DAY-OF-WEEK

A single data element that represents the day of the week. A
value of 1 represents Monday, a value of 2 represents
Tuesday, and so on. When accessed by a COBOL program,
this register behaves as an unsigned elementary numeric
integer 1 digit in length (PIC9(1) COMP). To query this special
register, use Format 2 of the ACCEPT statement.

LINAGE-COUNTER

The number of lines advanced within a printed page. LINAGECOUNTER is a fixed data-name for a line counter suitable for
computation. It is generated by the presence of a LINAGE
clause in a file description (FD) entry. The implicit class of a
LINAGE-COUNTER is numeric. No data item is referenced; it is
treated as a LINENUMBER attribute for purposes of retrieval.
The compiler automatically supplies one LINAGE-COUNTER for
each file in the File Section that has a LINAGE clause in its FD
entry. For more information, refer to “LINAGE” Clause in
Section 4.

8600 1518–307

Types of COBOL Words

Table 1–6. Special Registers

The register . . .

Contains . . .

LINE-COUNTER

The vertical position in a report. LINE-COUNTER is a fixed dataname for a line counter suitable for computation. It is
generated for each report description (RD) entry in the Report
Section. The compiler automatically provides one LINECOUNTER register for each report in the RD entry. You can
query this special register by using the Report Writer facility.

PAGE-COUNTER

Page numbers within a report group. PAGE-COUNTER is a
fixed data-name for a page counter suitable for computation. It
is generated for each report-description (RD) entry in the
Report Section. The compiler automatically supplies one PAGECOUNTER for each report that has the word PAGE-COUNTER
as a source data item in an RD entry. You can query this
special register by using the Report Writer facility.

TIME

The elapsed time after midnight based on a 24-hour clock in
hours, minutes, seconds, and hundredths of a second. TIME is
an unsigned, 8-digit, elementary numeric integer. For example,
2:41 p.m. is expressed as 14410000. The maximum value of
TIME is 23595999. You can query this special register by using
Format 2 of the ACCEPT statement.

TIMER

The number of 2.4-microsecond intervals since midnight.
TIMER is a single, unsigned 11-digit numeric integer. It is
composed of the current value of the computer's interval timer.
You can query this special register by using Format 2 of the
ACCEPT statement.

TODAYS-DATE

If TODAYS-DATE is followed by the qualifier "MMDDYYYY", the
system date is formatted as an unsigned, 8-digit elementary
numeric integer made up of the month of the year (two digits),
the day of the month (two digits), and the year (four digits). For
example, July 1, 1993 is expressed as 07011993.
If TODAYS-DATE is not qualified, the system date is formatted
as an unsigned, 6-digit elementary numeric integer made up of
the month of the year (two digits), the day of the month (two
digits), and the year of the century (two digits). For example,
July 1, 1993 is expressed as 070193.
To query this special register, use Format 2 of the ACCEPT
statement.

TODAYS-NAME

8600 1518–307

The current day of the week. TODAYS-NAME is an elementary,
9-character, alphanumeric item. If the day of the week is less
than nine characters long, it is left-justified in the 9-character
area provided, with space-fill on the right. You can query this
special register by using Format 2 of the ACCEPT statement.

1–21

Types of COBOL Words

Arithmetic and Relational Operators
Arithmetic and relational operators are symbols used to imply a mathematical operation
or to compare the value of two operands. Table 1–7 lists these COBOL operators. Note
that the operators are required when they appear in a general format even though they
are not underlined.
Table 1–7. Special Character Words

Type of Operator

Symbol

Meaning

Arithmetic

Addition

Subtraction

Multiplication

Division

Exponentiation

Greater than

Less than

Equal to

Greater than or equal to

Less than or equal to

Relational

1–22

8600 1518–307

Types of COBOL Words

System-Names
A system-name is a word that you use to communicate with the operating system. A
system-name can be one of two types, as shown in the following table.

Type of System-Name

Description

Computer-name

This is the name of the computer, for example MICROA or
A17, on which the COBOL program is to be compiled or
executed.

Implementor-name

This is a name that refers to a particular feature, such as
ODT or SW1.

You can use the same word as a system-name and a user-defined word. The compiler
determines the class of a specific occurrence of the word by the context of the clause or
phrase in which the word occurs.
Rules
Observe the following rules when you form a system-name:

•

Make the system-name no more than 30 characters long.

•

Select each character from the set of characters A through Z, 0 through 9, the
underscore (_), and the hyphen (-). (Each lowercase letter is equivalent to its
corresponding uppercase letter.)

•

Do not use the underscore or the hyphen as the first or last character of a systemname.

•

Do not use a reserved word as a system-name.

8600 1518–307

1–23

Types of COBOL Words

User-Defined Words
A user-defined word is a word that you supply to complete the syntax of a clause or
statement. You can use the same word as a user-defined word and a system-name. The
compiler determines the class of a specific occurrence of the word by the context of the
clause or phrase in which the word occurs.
Rules
Observe the following rules when you form a user-defined word:

1–24

•

Make the user-defined word no more than 30 characters long.

•

Select each character from the set of characters A through Z, 0 through 9, the
underscore (_), and the hyphen (-). (Each lowercase letter is equivalent to its
corresponding uppercase letter.)

•

Do not use the underscore or the hyphen as the first or last character of a userdefined word.

•

Do not use a reserved word.

•

Make sure that all user-defined words, except level-numbers and segment-numbers,
are unique. You can use qualification to make similar words unique. (Qualification is
discussed in Section 4.)

•

Include at least one alphabetic character in all user-defined words, except in the
following types of words:

−

Family-names

−

Level-numbers

−

Library-names

−

Paragraph-names

−

Section-names

−

Segment-numbers

−

Text-names

8600 1518–307

Types of COBOL Words

Double-Byte Names
Double-byte names are user-defined words made up of 16-bit characters and are used
with national languages that require a 16-bit coded character set. Double-byte names
include an SDO (start of double octet) character, one or more 16-bit characters, and an
EDO (end of double octet) character. SDO and EDO are control characters that
distinguish double-byte names from standard single-byte names.
As with national literals, you must enter double-byte names from a keyboard and terminal
that uses a 16-bit coded character set and that automatically inserts control characters.
Also, printer backup files that contain images of double-byte names must be printed by a
printer that automatically interprets control characters. The SDO and EDO control
characters appear as space characters on terminals and printers that use 16-bit coded
character sets.
The types of user-defined words that can be specified in 16-bit characters are

•

Alphabet-name

•

Class-name

•

Condition-name

•

Data-name

•

Index-name

•

Mnemonic-name

•

Paragraph-name

•

Record-name

•

Section-name

•

Symbolic-character

Rules
Observe the following rules when you form a double-byte name:

•

Include any character from the 16-bit character set.

•

Make names no more than 14 16-bit characters long. The maximum length allowed
is 28 bytes plus 2 bytes for the SDO and EDO control characters.

•

Use 16-bit characters only. You cannot mix standard 8-bit characters with 16-bit
characters to form a double-byte name.

•

Make names unique. You can use qualification to make similar words unique. Refer
to Section 4, “Data Division,” for information on qualification.

•

Place names completely on a single line. You cannot continue some of the
characters of a double-byte name to a continuation line.

8600 1518–307

1–25

Types of COBOL Words

Table 1–8 lists and describes the types of user-defined words that most frequently
appear in COBOL85 general formats.
Table 1–8. Types of User-Defined Words

Type

Purpose

Alphabet-name

Assigns a name to a specific character set and collating sequence.

Class-name

Assigns a name to any group of characters in the computer's
character set in the SPECIAL-NAMES paragraph of the Environment
Division. You can use a class-name in a conditional expression.

Condition-name

Assigns a name to a specific value, set of values, or range of values
from a complete set of values that a conditional variable can have. (A
conditional variable is a data item that can assume more than one
value.) A condition-name can also assign a name to a switch or
device.
You define condition-names in the Data Division or in the SpecialNames paragraph of the Environment Division.
You can use a condition-name as an abbreviation for a relation
condition. A relation condition assumes that the associated
conditional variable is equal to one of the set of values to which that
condition-name is assigned.
You can also use a condition-name in a SET statement to indicate that
the associated value is to be moved to the conditional variable.

1–26

Data-name

Names a data item described in a data description entry. A data-name
must not have a reference-modifier, qualifier, or subscript unless
specifically permitted by the rules of the general format. A data-name
that has a reference-modifier, qualifier, or subscript is referred to as
an identifier. Identifiers are described in detail later in this section.

File-name

Names a file described in a file description entry or a sort-merge file
description (FD) entry in the File Section of the Data Division.

Index-name

Names an index associated with a specific table.

Level-number

Defines a one- or two-digit number that indicates the hierarchical
position of a data item or the special properties of a data description
entry.

Library-name

Names a COBOL library that is to be used by the compiler for a given
source program compilation.

Mnemonicname

Assigns a user-defined word to an implementor-name in the
SPECIAL-NAMES paragraph of the Environment Division. An
implementor-name is a system-name that refers to a particular
feature available on the COBOL85 compiler.

Paragraph-name

Identifies and begins a paragraph in the Procedure Division.
Paragraph-names are equivalent only if they consist of the same
sequence of the same number of digits and/or characters.

8600 1518–307

Types of COBOL Words

Table 1–8. Types of User-Defined Words

Type

Purpose

Program-name

Identifies a COBOL source program in the Identification Division and
the end-program header.

Record-name

Names a record described in a record description (RD) entry in the
Data Division.

Section-name

Names a section in the Procedure Division. Section-names are
equivalent only if they consist of the same sequence of the same
number of digits and/or characters.

Symboliccharacter

Specifies a user-defined figurative constant. Refer to “Figurative
Constants” in this section for more information.

Text-name

Specifies the external identification of a file in the COBOL library.

Note that within a source program, excluding nested programs, user-defined words are
grouped into disjoint sets. A disjoint set is a set that has no common elements. Thus the
user-defined words within the set must be unique. In addition, all user-defined words,
except level numbers, can belong to only one disjoint set.
User-defined words are grouped into the following disjoint sets:

•

Alphabet-names

•

Class-names

•

Condition-names, data-names, and record-names

•

File-names

•

Index-names

•

Library-names

•

Mnemonic-names

•

Paragraph-names

•

Program-names

•

Section-names

•

Symbolic-characters

•

Text-names

8600 1518–307

1–27

Identifiers

Identifiers
An identifier is a syntactically correct sequence of character-strings and separators used
to uniquely identify a data item.
When a data item other than a function is specified, the term identifier is used in a
general format to indicate a data-name that must be either unique in a program or must
be followed by a syntactically correct combination of qualifiers, subscripts, or reference
modifiers to make it unique. (Qualifiers and reference modifiers are described in
Section 4. Subscripts are discussed in Section 5.)
The general syntax for an identifier is as follows:
Ú
³
³
data-name-1³
³
³
À

ä
³
ã
³
æ

IN
ïï
OF
ïï

¿
å
³
³
³
â data-name-2 ³...
³
³
ç
³
Ù

[({subscript} ... )]

Ú
³
³
³
³
³
À

ä
³
ã
³
æ

IN
ïï
OF
ïï

å
³
â
³
ç

ä
³ cd-name-1
³
ã file-name-1
³
æ report-name-1

å
³
³
â
³
ç

¿
³
³
³
³
³
Ù

[reference-modifier]

Note that the words IN and OF are equivalent in this syntax.
Some special identifiers do not exactly follow the ANSI COBOL85 format for an identifier.
These identifiers and the sections in this manual in which they are described are shown
in the following table:

1–28

For information about . . .

Refer to . . .

Event-identifiers

Section 6 (CAUSE statement)

File attribute identifiers

Section 12

Function identifiers

Section 9

Task attribute identifiers

Section 6 (CHANGE statement) and
Section 13

8600 1518–307

Literals

Literals
A literal is a word, number, or symbol that names, describes, or defines itself and not
something else that it might represent. For example, consider the following general
format for the ADD statement:

ADD
ïïï

ä
å
³ identifier-1 ³
ã
â ... TO
³ literal-1
³
ïï
æ
ç

{ identifier-2 [ ROUNDED ] } ...
ïïïïïïï

Assume that you want the value for identifier-2 to be “TOTAL.” If you choose to use a
literal as shown in the preceding syntax, your program line might read “ADD 1 TO
TOTAL.” The computer adds the actual value of 1 to the value stored in the TOTAL field.
If you want to add the value stored in the EXTRA-INCOME field to the value stored in the
TOTAL field, you would use an identifier instead of a literal. Your program line might read
“ADD EXTRA-INCOME TO TOTAL.”
Every literal belongs to one of the following types:

•

Nonnumeric

•

National

•

Numeric

•

Undigit

•

Floating-point

•

Boolean

The types of literals are described in the following paragraphs.

8600 1518–307

1–29

Literals

Nonnumeric Literals
A nonnumeric literal is an alphanumeric value from 1 through 160 characters in length.
The characters can include any character in the alphanumeric and national character sets.
National characters and the control characters SDO and EDO, which are used to
distinguish national characters from nonnumeric characters, can be mixed with
nonnumeric characters to form nonnumeric literals.
To indicate that a value is a nonnumeric literal, you must place quotation marks (") before
and after the value. The quotation marks are not considered to be part of the value of the
literal. The general format for a nonnumeric literal is as follows:
" { character-1 } ... "
Character-1 can be any character in the computer’s character set.
Details
To use the quotation mark as a literal, use two contiguous quotation marks. For example,
assume that you want to produce the name William “Bud” Smith, with the name Bud in
quotation marks. You would use the following code:
"William ""Bud"" Smith".
Note that all punctuation characters are part of the value of the nonnumeric literal and are
not used as separators.
The value of a nonnumeric literal in the object program is the value represented by
character-1.
Examples
The following table provides examples of the coding of nonnumeric literals.

1–30

Coding

Result

"MY NAME"

MY NAME

""""

"FEET/SQ. IN."

FEET/SQ. IN.

"THIS IS ""EDITED""
OUTPUT"

THIS IS "EDITED" OUTPUT

8600 1518–307

Literals

National Literals
A national literal is a character string in a language other than standard American English.
A national literal is of the national class and category.
The general format for a national literal is as follows:
ä
³
ã
³
æ

N
ï
NC
ïï

å
³
â
³
ç

" {character-1}..."

The letter N and the quotation mark (") serve only as delimiters and are not part of the
value of the national literal. Character-1 is a string of 8-bit or 16-bit characters in national
standard data format. The 16-bit national literal must be keyed in from a terminal that
uses a national character set and automatically inserts control characters.
Details
The 8-bit national characters do not require the insertion of control characters at the
beginning and end of the literal.
The 16-bit national characters are distinguished from 8-bit national or nonnumeric
characters by the insertion of control characters at the beginning and end of the literal.
The control characters SDO (start of double octet) must follow the first double quotation
mark and immediately precede character-1. The control character EDO (end of double
octet) must immediately follow character-1 and precede the ending double quotation
mark. Control characters cannot be used within the character-1 string. Each control
character occupies one byte of space, so the length of a national literal can be from 1 to
79 16-bit characters, or from 2 to 158 bytes long. Multi Octet Character Set support for
the COBOL85 compiler supports only the Kanji 16-bit character set.
Note: COBOL74 uses the delimiter NC instead of N to specify a 16-bit national literal.
Both the NC and N delimiters can be used for this release of COBOL85.
Example
An example of a national literal declaration that is 10 national characters long is as
follows:
01 NAME PIC N(10) VALUE N"AAAAAAAAAA".

8600 1518–307

1–31

Literals

Numeric Literals
A numeric literal is a literal composed of one or more numeric characters. Numeric
literals do not have delimiters.
COBOL85 acknowledges two types of numeric literals:

•

Standard numeric literals (1 to 23 digits)

•

Long numeric literals (24 to 160 digits)

The rules for forming both types of literals are explained in the following paragraphs.
Rules for All Numeric Literals
The following rules apply to both standard numeric literals and long numeric literals:

•

Every numeric literal is in the numeric category.

•

The value of a numeric literal is the algebraic quantity represented by the characters
in the numeric literal.

•

The size of a numeric literal in standard data format characters equals the number of
digits specified in the character-string.

•

If the literal conforms to the rules for the formation of numeric literals but is enclosed
in quotation marks ("), it is a nonnumeric literal and the compiler treats it as such. For
example, "1234" is a nonnumeric literal.

Rules for Standard Numeric Literals
Observe the following rules when forming standard numeric literals:

•

The literal can contain only one sign character.
If you use a sign, it must appear as the leftmost character of the literal.

•

If the literal is unsigned, it is assumed to be positive.

•

The literal can contain only one decimal point.
The decimal point can appear anywhere within the literal except in the rightmost
character position.
The decimal point is treated as an assumed decimal point, which means that it does
not involve the existence of an actual character in a data item. The assumed decimal
point has logical meaning with no physical representation.

•

1–32

If the literal does not contain a decimal point, the literal is an integer.

8600 1518–307

Literals

Rules for Forming Long Numeric Literals
Observe the following rules when forming long numeric literals:

•

Long numeric literals must be described as unsigned integers, so they cannot have
operational signs or decimal points.

•

Arithmetic operations and relative arithmetic comparisons are not permitted on long
numeric literals.

•

You can use long numeric literals only with the following Procedure Division
statements: CALL, IF, INITIALIZE, INSPECT, MERGE, MOVE, READ, SORT, and
WRITE. For details, refer to the description of each statement in Sections 6 through
8 of this manual.

Undigit Literals
An undigit literal is a string of hexadecimal characters delimited at the beginning and end
by the at-sign (@). A hexadecimal character is a character from the set composed of the
digit characters 0 through 9 and the uppercase letters A through F.
Whether an undigit literal is interpreted as 4-bit numeric characters, 8-bit alphanumeric
characters, 8-bit national characters, or 16-bit national characters depends upon the data
item to which it is associated:

•

If the undigit literal appears in the VALUE clause of a data item whose usage is
COMPUTATIONAL, the undigit literal is interpreted as 4-bit numeric characters.

•

If the undigit literal is associated with an alphanumeric data item, the undigit literal is
interpreted as 8-bit alphanumeric characters. The undigit literal must contain an even
number of hexadecimal characters because two hexadecimal characters are required
for each alphanumeric character.

•

If the undigit literal is associated with a national data item and the CCSVERSION
phrase is specified in the program, the undigit literal is interpreted as 8-bit national
characters. The undigit literal must contain an even number of hexadecimal
characters because two hexadecimal characters are required for each 8-bit national
character.

•

If the undigit literal is associated with a national data item and no CCSVERSION
phrase is specified, the undigit literal is interpreted as 16-bit national characters. The
undigit literal must contain a number of characters that is divisible by four because
four hexadecimal characters are required for each 16-bit national character.

8600 1518–307

1–33

Literals

An undigit literal is interpreted as national in the following cases:

•

In the INSPECT statement where the inspected data item is national

•

In the STRING statement where the receiving data item is national

•

In the UNSTRING statement where the sending data item is national

•

In the MOVE statement where the receiving field is national

•

In the VALUE clause associated with a national data item or in the VALUE clause of a
condition-name associated with national data items

•

In the conditional expression of an EVALUATE, IF, PERFORM, or SEARCH statement
where the category of the other relational operand is national

•

In the ALL figurative constant if it occurs in the situations described for the preceding
cases

An undigit literal cannot be treated as national in a DISPLAY or STOP statement.

Floating-Point Literals
Floating-point literals provide an alternate means of representing REAL and DOUBLE data
items. The general format of a floating point literal is
mantissa E exponent
The mantissa is the decimal part of the number. The mantissa can be signed and must
have one decimal point. The exponent signifies a power of 10 used as a multiplier. The
exponent can be signed and must be an integer.
The value represented by a floating-point literal is the mantissa multiplied by 10 raised to
the power of the exponent. For single-precision, the permissible range for the value of a
floating point literal is
8.75811540203 * 10-47 to 4.31359146673 * 1068
For double-precision, the permissible range for the value magnitude is
1.9385458571375858335564 * 10–29581
to
1.94882838205028079124467 * 1029603
Floating-point literals can be used in the language anywhere a noninteger numeric literal
is permitted.
Examples
1.E–40
–.0023E29
+.0012345E–5
+1.2E9500
2.E40
+123.45678901234E20

1–34

8600 1518–307

Literals

Boolean Literals
A Boolean literal is a character string delimited on the left by the separator B" and on the
right by the separator quotation mark.
General Format
B"Boolean-character"
ï
The Boolean-character is a "0" or a "1".
Examples
B"1"
B"0"

8600 1518–307

1–35

Literals

1–36

8600 1518–307

Section 2
Identification Division
This section presents and explains the syntax of the Identification Division, the first
division of a COBOL program.

General Format
The general format of the Identification Division is as follows:
IDENTIFICATION DIVISION.
ïïïïïïïïïïïïïï ïïïïïïïï
[ PROGRAM-ID. program-name. ]
ïïïïïïïïïï
[ AUTHOR. [ comment-entry ] ... ]
ïïïïïï
[ INSTALLATION. [ comment-entry ] ... ]
ïïïïïïïïïïïï
[ DATE-WRITTEN. [ comment entry ] ... ]
ïïïïïïïïïïïï
[ DATE-COMPILED. [ comment-entry ] ... ]
ïïïïïïïïïïïïï
[ SECURITY. [ comment-entry ] ... ]
ïïïïïïïï
Except for the DATE-COMPILED paragraph, the entire Identification Division is copied
from the input source program and is included on the output listing. The object program,
however, is not affected by the information included in this division.
Note: The AUTHOR, INSTALLATION, DATE-WRITTEN, DATE-COMPILED, and
SECURITY paragraphs are obsolete elements in COBOL ANSI-85 and will be deleted
from the next revision of the COBOL standard.

Identification Division Header
The following header identifies and must begin the Identification Division:
IDENTIFICATION DIVISION.
ïïïïïïïïïïïïïï ïïïïïïïï
These keywords begin in area A and must be followed by a period.

8600 1518–307

2–1

PROGRAM-ID Paragraph

PROGRAM-ID Paragraph
The PROGRAM-ID paragraph is the only required paragraph in the Identification Division
of a program nested within another program. Otherwise, this paragraph is optional, and
the compiler will implicitly generate a PROGRAM-ID record if it is missing. However,
multiple source programs arranged sequentially in a single source program must be
delimited by the PROGRAM-ID paragraph, which specifies the name of the program and
assigns selected program attributes to that program.
Refer also to “Using the ANSI IPC Constructs,” “The Run Unit,” “Nested Source
Programs,” and “Common and Initial Programs” in Section 10.
The format of the PROGRAM-ID paragraph is as follows:

PROGRAM-ID. program-name
ïïïïïïïïïï

Ú
³
³ IS
³
³
³
³
³
³
³
À

ä
³
³
³
ã
³
³
³
æ

|
|
|
|
|
|
|

COMMON
ïïïïïï
INITIAL
ïïïïïïï
LIBRARY
ïïïïïïï
DEFINITION
ïïïïïïïïïï

|
|
|
|
|
|
|

å
³
³
³
â
³
³
³
ç

PROGRAM

¿
³
³ .
³
³
³
³
³
³
³
Ù

PROGRAM-ID

This keyword begins in area A and must be followed by a period.
program-name

This name is a user-defined word that identifies the source program, the object program,
and all listings that pertain to a particular program.
The program-name in the PROGRAM-ID paragraph is not necessarily the same as the
source program name or object program name, which are determined by the method of
compilation. For example, if TESTSOURCE/C85/XYZ were the source file name, its
PROGRAM-ID could be PROGRAM-ID xyz COMMON), and, if compiled through CANDE,
its object code file name could be OBJECT/TESTSOURCE/C85/XYZ.
When a sequence of programs is compiled, the second program is named -1, the third program is named -2, and so on.
Note that a nested program must not be assigned the same program-name as that of
any other program contained in the separately compiled program that contains the
nested program.

2–2

8600 1518–307

PROGRAM-ID Paragraph

IS COMMON PROGRAM Clause
You can use this clause if the program is contained in another program. When used, this
clause specifies that the program can be called from programs other than the one
containing it. Refer also to “Common and Initial Programs” in Section 10.

IS INITIAL PROGRAM Clause
This clause specifies that the program (and any programs it contains) will be placed in its
initial state each time it is called. Refer also to “Common and Initial Programs” in
Section 10.

IS LIBRARY PROGRAM Clause
This clause identifies a program as a library program. The program that contains this
clause must be the outermost program of a collection of programs; the library program
cannot be nested within another program.
A program that contains an IS LIBRARY PROGRAM clause must also contain an export
definition in the Program-Library Section of the Data Division. For more information, refer
to “Program-Library Section” in Section 4. For information on library programs, refer to
Section 11.
Note: If the IS LIBRARY PROGRAM clause is present in a source program, the
compiler control options LIBRARYPROG and LEVEL cannot be set.

IS DEFINITION PROGRAM Clause
This clause identifies the program as a definition program. The program that contains this
clause must be the first program. It is followed by a list of multi-procedure programs
separated by a LIBRARY control option. The BINDSTREAM compiler control option must
be set.
A program that contains an IS DEFINITION PROGRAM can contain only the
Working-Storage Section, Local-Storage Section, and the import definitions in the
Program-Library Section of the Data Division. For more information, refer to
BINDSTREAM and LIBRARY compiler control options.

8600 1518–307

2–3

AUTHOR Paragraph

AUTHOR Paragraph
The AUTHOR paragraph gives the name of the person who wrote the program. Use of
this paragraph is optional.
The format of the AUTHOR paragraph is as follows:
[ AUTHOR. [ comment-entry ] ... ]
ïïïïïï

AUTHOR

This keyword begins in area A and must be followed by a period.
comment-entry

2–4

8600 1518–307

INSTALLATION Paragraph

INSTALLATION Paragraph
The INSTALLATION paragraph gives the name of the site where the program will be
used. Use of this paragraph is optional.
The format of the INSTALLATION paragraph is as follows:
[ INSTALLATION. [ comment-entry ] ... ]
ïïïïïïïïïïïï

INSTALLATION

This keyword begins in area A and must be followed by a period.
comment-entry

8600 1518–307

2–5

DATE-WRITTEN Paragraph

DATE-WRITTEN Paragraph
The DATE-WRITTEN paragraph gives the date that the program was written. Use of this
paragraph is optional.
The format of the DATE-WRITTEN paragraph is as follows:
[ DATA-WRITTEN. [ comment-entry] ... ]
ïïïïïïïïïïïï

DATE-WRITTEN

This keyword begins in area A and must be followed by a period.
comment-entry

2–6

8600 1518–307

DATE-COMPILED Paragraph

DATE-COMPILED Paragraph
The DATE-COMPILED paragraph gives the date that the program was compiled. If this
paragraph is present, the system automatically updates the compilation date in the
source program listing. Use of this paragraph is optional.
The format of the DATE-COMPILED paragraph is as follows:
[ DATE-COMPILED. [ comment-entry ] ... ]
ïïïïïïïïïïïïï

DATE-COMPILED

This keyword begins in area A and must be followed by a period.
This keyword causes the current date to be inserted in the source program listing during
program compilation.
comment-entry

year month day hh:mm

Example
DATE-COMPILED. 1988 FEBRUARY 11 10:15.
This example shows how the DATE-COMPILED paragraph would appear on the output
listing of a program that was compiled on February 11, 1988, at 10:15.
Note: The DATE-COMPILED paragraph is an obsolete element in COBOL ANSI-85 and
will be deleted from the next revision of the COBOL standard.

8600 1518–307

2–7

Security Paragraph

Security Paragraph
The SECURITY paragraph identifies the security restrictions under which the program
can be accessed. Use of this paragraph is optional.
The format of the SECURITY paragraph is as follows:
[ SECURITY. [ comment-entry ] ... ]
ïïïïïïïï

SECURITY

This keyword begins in area A and must be followed by a period.
comment-entry

This can be any combination of characters from the computer's character set. You must
not continue a comment-entry with a hyphen in the indicator area; however, a commententry can extend beyond one line. The comment-entry is becoming obsolete in
COBOL85 and will be deleted from the next revision of the ANSI COBOL standard.
Example
IDENTIFICATION DIVISION.
PROGRAM-ID. IDEX.
AUTHOR. WATSINA NAM.
INSTALLATION. YOUR CORPORATION.
DATE-WRITTEN. FEBRUARY 11, 1988.
DATE-COMPILED.
SECURITY. CONFIDENTIAL.
The Identification Division in this example includes all five optional paragraphs. Because
the DATE-COMPILED paragraph is included, the compilation date will be provided on the
source listing.
Note: The SECURITY paragraph is an obsolete element in COBOL ANSI-85 and will be
deleted from the next revision of the COBOL standard.

2–8

8600 1518–307

Section 3
Environment Division
This section illustrates and explains the syntax of the Environment Division, the second
division of a COBOL program.

General Format
The general format of the Environment Division is as follows:
ENVIRONMENT DIVISION.
ïïïïïïïïïïï ïïïïïïïï
[ CONFIGURATION SECTION.
ïïïïïïïïïïïïï ïïïïïïï
[ SOURCE-COMPUTER. [ computer-name [ WITH DEBUGGING MODE ] ]
ïïïïïïïïïïïïïïïï
[ OBJECT-COMPUTER. [ object computer entry ] ]
ïïïïïïïïïïïïïïïï
[ SPECIAL-NAMES. [ special names entry ] ]
ïïïïïïïïïïïïïï
[ INPUT-OUTPUT SECTION.
ïïïïïïïïïïïï ïïïïïïï
FILE-CONTROL. { file control entry } ...
ïïïïïïïïïïïï
[ I-O-CONTROL. [ input output control entry ] ] ] ]
ïïïïïïïïïïï

Environment Division Header
The following header identifies and must begin the Environment Division:
ENVIRONMENT DIVISION.
ïïïïïïïïïïï ïïïïïïïï

ENVIRONMENT DIVISION

These keywords begin in area A and must be followed by a period.

8600 1518–307

3–1

Configuration Section

Configuration Section
The Configuration Section identifies the source computer, the object computer, and the
mnemonic-names that are substituted for system-names in the program. Use of this
section is optional.
Note that the Configuration Section must not be included in a program that is contained
directly or indirectly in another program. Refer to “Nested Source Programs” in
Section 10.
The Configuration Section includes a header and the following three optional paragraphs:

•

SOURCE-COMPUTER Paragraph
Describes the computer configuration on which the source program will be compiled.

•

OBJECT-COMPUTER Paragraph
Describes the computer configuration on which the object program produced by the
compiler will be run.

•

SPECIAL-NAMES Paragraph
Provides a means of specifying the currency sign, choosing the decimal point,
specifying symbolic-characters, relating implementor-names to user-specified
mnemonic-names, relating alphabet-names to character sets or collating sequences,
relating class-names to sets of characters, and specifying the default sign position for
all signed data items whose usage is DISPLAY or COMPUTATIONAL.

Configuration Section Header
The following header identifies and must begin the Configuration Section:
CONFIGURATION SECTION.
ïïïïïïïïïïïïï ïïïïïïï

CONFIGURATION SECTION

These keywords begin in area A and must be followed by a period.

3–2

8600 1518–307

Configuration Section

SOURCE-COMPUTER Paragraph
The SOURCE-COMPUTER paragraph identifies the computer on which the program will
be compiled. Use of this paragraph is optional.
SOURCE-COMPUTER. [ computer-name [ WITH DEBUGGING MODE ] . ]
ïïïïïïïïïïïïïïï

SOURCE-COMPUTER

This keyword begins in area A and must be followed by a period.
computer-name

This name is a system-name (any COBOL word) that identifies the computer on which
the source program is to be compiled.
The computer-name is for documentation purposes only.
WITH DEBUGGING MODE

This clause serves as a compile time switch over the debugging lines written in a
separately compiled program. When the WITH DEBUGGING MODE clause is specified in
a separately compiled program, all debugging lines are compiled as specified in the
program. When the WITH DEBUGGING MODE clause is not specified in a program and
the program is not contained within a program including a WITH DEBUGGING MODE
clause, then the debugging lines are compiled as comment lines. $FREE must be reset
to compile debugging lines.
Details
All clauses of the SOURCE-COMPUTER paragraph apply to the program in which they
are explicitly or implicitly specified and to any program contained in that program.
If you specify the SOURCE-COMPUTER paragraph but not the computer-name (refer to
“General Format of the Environment Division” in this section), the computer on which
the source program is compiled is the source computer.
If you specify the SOURCE-COMPUTER paragraph but the program is not contained in a
program that includes a SOURCE-COMPUTER paragraph, again, the computer on which
the source program is compiled is the source computer.

8600 1518–307

3–3

Configuration Section

OBJECT-COMPUTER Paragraph
The OBJECT-COMPUTER paragraph identifies the computer on which the program will
be executed. Use of this paragraph is optional.
All clauses of the OBJECT-COMPUTER paragraph apply to the program in which they are
explicitly or implicitly specified and to any program contained in that program.
The format of the OBJECT-COMPUTER paragraph is as follows:
OBJECT-COMPUTER. [ computer-name ]
ïïïïïïïïïïïïïïï
Ú
¿
³
ä WORDS
å
³
³
³ ïïïïï
³
³
³
MEMORY SIZE integer-1 ã CHARACTERS â
³
³
ïïïïïï
³ ïïïïïïïïïï ³
³
³
æ MODULES
ç
³
À
ïïïïïïï
Ù
Ú
¿
³
DISK SIZE IS integer-2 ä WORDS
å
³
³
ïïïï
ã ïïïïï
â
³
³
æ MODULES
ç
³
À
ïïïïïïï
Ù
Ú
³ PROGRAM COLLATING SEQUENCE
³
ïïïïïïïï
³
ä
³
³ IS alphabet-name-1 [alphabet-name-2]
³
³
³
ã ä |FOR ALPHANUMERIC IS alphabet-name-1| å
³
³ ã ³
ïïïïïïïïïïïï
| â
³
³ æ |FOR NATIONAL IS alphabet-name-2
| ç
³
æ
ïïïïïïïï
À

å
³
³
â
³
³
ç

¿
³
³
³
³
³
³
³
³
³
Ù

OBJECT-COMPUTER

This keyword begins in area A and must be followed by a period.
computer-name

This name is a system-name (any COBOL word) that identifies the hardware for which
object code is to be generated. The computer-name is optional.

3–4

8600 1518–307

Configuration Section

MEMORY SIZE Clause
The SORT and MERGE statements can also specify MEMORY SIZE and take precedence
over the OBJECT-COMPUTER paragraph. Refer to “MERGE Statement” in Section 7 and
“SORT Statement” in Section 8 for more information. This clause specifies the actual
main storage requirement needed for execution.
If you use this clause but a SORT or MERGE statement does not appear in the program,
the clause is ignored. If you do not use this clause in either a SORT or MERGE statement
or the OBJECT-COMPUTER paragraph, a default memory size of 12,000 words is
assumed. (One module of memory is equivalent to 16,384 words of memory.)
Note that the MEMORY SIZE clause is an obsolete element in COBOL ANSI-85 and will
be deleted from the next revision of the COBOL standard.
integer-1

The value contained in integer-1 specifies the number of bytes, words, or modules of
main storage, exclusive of control program requirements that are available for object
program execution.
WORDS
CHARACTERS
MODULES

You can specify the memory size in words with WORDS, in bytes with CHARACTERS,
and in 16,384-word units with MODULES.

DISK SIZE Clause
This clause specifies the amount of disk space to be used for SORT operations.
The DISK SIZE clause is used only in conjunction with the SORT statement. If you omit
the DISK SIZE clause from a program containing a SORT statement, DISK SIZE is
assumed to be 900,000 words. If you use the DISK SIZE clause, but a SORT statement
does not appear in the program, the DISK SIZE is ignored.
The DISK SIZE can be specified in either MODULES or WORDS. A module of disk is
equivalent to 1.8 million words of disk.

8600 1518–307

3–5

Configuration Section

PROGRAM COLLATING SEQUENCE Clause
If you use this clause, the program-collating sequence is the collating sequence
associated with the alphabet-name specified in this clause. The same collating sequence
is also applied to any nonnumeric merge or sort keys, unless the COLLATING
SEQUENCE phrase of the respective MERGE or SORT statement is specified.
If this clause is not specified, the EBCDIC collating sequence is used.
alphabet-name-1

This name is a user-defined word.
The collating sequence associated with alphabet-name-1 is used to determine the truth
value of any nonnumeric comparisons that are explicitly specified in relation conditions or
condition-name conditions.
alphabet-name-2

This name is a user-defined word.
The collating sequence associated with alphabet-name-2 is used to determine the truth
value of any national comparisons that are explicitly specified in relation conditions or in
condition-name conditions.
When the PROGRAM COLLATING SEQUENCE clause is specified, the initial
alphanumeric program collating sequence is the collating sequence associated with
alphabet-name-1 and the initial national program collating sequence is the collating
sequence associated with alphabet-name-2. When alphabet-name-1 is not specified, the
initial alphanumeric program collating sequence is the native alphanumeric collating
sequence, EBCDIC. When alphabet-name-2 is not specified, the initial program collating
sequence is the native national collating sequence, JAPAN EBCDIC D1-2.
For localization purposes, the program can specify the PROGRAM COLLATING
SEQUENCE clause and a CCSVERSION collating sequence associated with an alphabetname. In this case, the truth value of the alphabetic characters that are explicitly
specified in the class condition does not always consist entirely of the letters A through Z
and the space character. The class of alphabetic characters is determined by the system
collating sequence when the CCSVERSION collating sequence is specified.
When the PROGRAM COLLATING SEQUENCE clause is not specified for a given
program, and the program is not contained within a program for which a PROGRAM
COLLATING SEQUENCE clause is specified, the initial program collating sequences are
the native alphanumeric collating sequence and the native national collating sequence.

3–6

8600 1518–307

Configuration Section

SPECIAL-NAMES Paragraph
The SPECIAL-NAMES paragraph does the following:

•

Relates implementor-names used by the compiler to mnemonic-names used by the
source program

•

Assigns condition-names to the status of switches

•

Relates alphabet-names to character sets or collating sequences

•

Specifies symbolic-characters

•

Relates class-names to sets of characters

•

Exchanges the functions of the comma and the period in the PICTURE character
string and in numeric literals

•

Specifies a substitution character for the currency symbol in the PICTURE character
string

•

Changes default editing characters

•

Specifies the default sign position for all signed data items whose usage is DISPLAY
or COMPUTATIONAL

•

Associates a mnemonic-name with an object program

This paragraph is optional. All clauses specified in the SPECIAL-NAMES paragraph for a
program also apply to programs contained in that program.

8600 1518–307

3–7

Configuration Section

The format of the SPECIAL-NAMES paragraph is as follows:
SPECIAL-NAMES.
ïïïïïïïïïïïïï
Ú
¿
³
CHANNEL nn IS mnemonic-name-1
³
³
ïïïïïïï
³
³
ODT IS mnemonic-name-2
³
³
ïïï
³
³
switch-name [ IS mnemonic-name-3 ]
³
³
³
³
ä
ON STATUS IS condition-name-1
å
³
³
³
ïï
³
³
³
³ [ OFF STATUS IS condition-name-2 ] ³
³
³
ã
ïïï
â
³
³
³
OFF STATUS IS condition-name-2
³
³
³
³
ïïï
³
³
³
æ [ ON STATUS IS condition-name-1 ] ç
³
À
ïï
Ù
Ú
³ ALPHABET
³ ïïïïïïïï
³ ä
³ ³ alphabet-name-1 [FOR ALPHANUMERIC] IS
³ ³
ïïïïïïïïïïïï
³ ³
ä EBCDIC
³ ³
³ ïïïïïï
³ ³
³ ASCII
³ ³
³ ïïïïï
³ ³
³ STANDARD-1
³ ³
³ ïïïïïïïïïï
³ ³
³ STANDARD-2
³ ³
³ ïïïïïïïïïï
³ ³
³ NATIVE
³ ³
ã ïïïïïï
³ ³
³ä
Ú
¿
å
³ ³
³³
³ä
å
³
³
³ ã
³³
³³ THROUGH ³
³
³
³ ³
³³
³ã ïïïïïïï â
³
³
³ ³
³ãliteral-1³³ THRU
³literal-2³...â
³ ³
³³
³æ ïïïï
ç
³
³
³ ³
³³
³
³
³
³ ³
³³
³{ALSO literal-3 ...}³
³
³ ³
³³
À ïïïï
Ù
³
³ ³
ææ
ç
³ ³
³ ³ alphabet-name-2 FOR NATIONAL IS
³ ³
ïïïïïïïï
³ ³
ä
å
³ ³
³ NATIVE
³
³ ³
ã ïïïïïï
â
³ ³
³ CCSVERSION [literal-1] ³
³ ³
æ ïïïïïïïïïï
ç
³ æ
³
À

. . .

å
³
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
³
³
ç

å
³
³
³
³
³
³
³
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
ç

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³...
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
Ù

continued

3–8

8600 1518–307

Configuration Section

Ú
¿
³ SYMBOLIC CHARACTERS Ú
¿
³
³ ïïïïïïïï
³ FOR ä ALPHANUMERIC å ³
³
³
³
³ ïïïïïïïïïïïï ³ ³
³
³
³
ã
â ³
³
³
³ FOR ³ NATIONAL
³ ³
³
³
³
æ ïïïïïïïï
ç ³
³
³
À
Ù
³
³
³
³
ä
Ú
¿
³
³
³
³ IS
³
³
³
ã { symbolic-character-1 } ... ³
³
³
³
³
³ ARE ³
³
³
æ
À
Ù
³
³
³
³
å
³
³
³
³
³
{ integer-1 }...â ... [ IN alphabet-name-2 ] ³ ...
³
³
ïï
³
³
ç
³
À
Ù
Ú
³ CLASS class-name-1 Ú
¿
³ ïïïïï
³ FOR ä ALPHANUMERIC å ³
³
³
³ ïïïïïïïïïïïï ³ ³
³
³
ã
â ³
³
³ FOR ³ NATIONAL
³ ³
³
³
æ ïïïïïïïï
ç ³
³
À
Ù
³
³
ä
Ú
³
³
³ ä
³
³
³ ³ THROUGH
³
ã
³ ã ïïïïïïï
³
IS ³ literal-4 ³ ³ THRU
³
³
³ æ ïïïï
³
æ
À
À

¿
å
³
³
³
â literal-5 ³
³
³
ç
³
Ù

¿
³
³
³
³
³
³
³
³
å
³
³
³
³
³
â...³...
³
³
³
³
ç
³
Ù

[CURRENCY SIGN IS literal-6 [WITH PICTURE SYMBOL literal-7]]...
ïïïïïïïï
ïïïïïïï ïïïïïï
[ literal-7 IS mnemonic-name-4 ] ...
[ DECIMAL-POINT IS COMMA ]
ïïïïïïïïïïïïï
ïïïïï
Ú
³ DEFAULT DISPLAY [SIGN IS]ä LEADING
³ ïïïïïïïïïïïïïïï ïïïï
ã ïïïïïïï
³
æ TRAILING
À
ïïïïïïïï
Ú
³
ä
å
ä
³DEFAULT ³ COMPUTATIONAL ³ [SIGN IS]³
³ïïïïïïï ã ïïïïïïïïïïïïï â ïïïï
ã
³
æ COMP
ç
æ
À
ïïïï

8600 1518–307

¿
å [SEPARATE CHARACTER]³
â ïïïïïïïï
³
ç
³
Ù
¿
å
³
LEADING ³[SEPARATE CHARACTER]³.
ïïïïïïï â ïïïïïïïï
³
TRAILING ç
³
ïïïïïïïï
Ù

3–9

Configuration Section

CHANNEL Clause
This clause relates a mnemonic-name to a particular channel number. You can then use
the mnemonic-name in a WRITE or SEND statement in place of CHANNEL nn. (WRITE
and SEND statements are discussed in Section 8.)
nn

This is an integer from 01 to 11.
mnemonic-name-1

This name is a user-defined word that is associated with the channel number specified in
the CHANNEL clause.

ODT Clause
This clause relates a mnemonic-name to the Operator Display Terminal (ODT). You can
then use the mnemonic-name in an ACCEPT or DISPLAY statement. (The ACCEPT and
DISPLAY statements are discussed in Section 6.)
mnemonic-name-2

This name is a user-defined word that is associated with the ODT.

SWITCH-NAME Clause
This clause associates mnemonic-names and condition-names with program switches.
switch-name

The switch-names you can use to specify the switches are SW1, SW2, SW3, SW4, SW5,
SW6, SW7, and SW8.
mnemonic-name-3

This name is a user-defined word that can be associated with the switch-name.
This name can be referenced only in the SET statement. (The SET statement is
discussed in Section 8.)

3–10

8600 1518–307

Configuration Section

condition-name-1
condition-name-2

These condition-names are user-defined words that specify the status of a switch. One
condition-name can be associated with the ON status, another with the OFF status. The
condition-name associated with ON STATUS is TRUE when the switch is set, and FALSE
when the switch is not set. The condition-name associated with OFF STATUS is TRUE
when the switch is not set, and FALSE when the switch is set.
The status of the switch can be interrogated by testing these condition-names in the
program's Procedure Division. The status of the switch can be altered by execution of a
Format 3 SET statement, which specifies as its operand the mnemonic-name associated
with that switch.
The condition-names specified in the containing program's SPECIAL-NAMES paragraph
can be referred to from any contained program.
Details
Switches provide a means of communicating with the external environment. The
meaning associated with each switch is user-defined. Switches can be set at program
initiation time or through Work Flow Language (WFL) using the task attributes SW1,
SW2, SW3, SW4, SW5, SW6, SW7, and SW8.
Refer to “Condition-Name Conditions” and “Switch-Status Conditions” in Section 5 for
more information.

ALPHABET Clause
This optional clause relates alphabet-names to character sets or collating sequences.
alphabet-name-1
alphabet-name-2

This is a user-defined word that assigns a name to a specific character code set or
collating sequence.
An alphabet name can consist of the characters A through Z, a through z, 0 through 9,
and the hyphen (-). You cannot use the hyphen or 0 through 9 as the first character, and
you cannot use the hyphen as the last character.
When alphabet names are referred to in the PROGRAM COLLATING clause of the
OBJECT-COMPUTER paragraph or in the COLLATING SEQUENCE phrase of a SORT or
MERGE statement, the ALPHABET clause specifies a collating sequence.
When alphabet names are referred to in the SYMBOLIC CHARACTERS clause or in a
CODE-SET clause in a file description entry, the ALPHABET clause specifies a character
code set.

8600 1518–307

3–11

Configuration Section

EBCDIC
ASCII
STANDARD-1
STANDARD-2
NATIVE

STANDARD-1 and ASCII indicate that alphabet-name-1 is the character code set and
collating sequence defined by the American National Standard Code for Information
Interchange, X3.4-1977.
STANDARD-2 indicates that alphabet-name-1 is the character code set and collating
sequence defined by the International Reference Version of the ISO 7-bit code defined in
International Standard 646, 7-Bit Coded Character Set for Information Processing
Interchange.
If the NATIVE phrase is specified, the native character code set and native collating
sequence are identified with alphabet-name-1. The native character code set is the
character code set associated with DISPLAY usage, EBCDIC.
When the NATIVE phrase is specified for a national alphabet name, the native national
coded character set and native national collating sequence are defined as
JAPAN EBCDIC D1-2.
The correspondence between characters of the ASCII character code set and characters
of the EBCDIC character code set is determined by the standard translation tables for
EBCDIC-to-ASCII and ASCII-to-EBCDIC.
literal-1
literal-2
literal-3

If the literal phrase of the ALPHABET clause is specified:

•

A given character must not be specified more than once in that clause.

•

The alphabet-name cannot be referred to in a CODE-SET clause.

The following syntax rules apply to the literals specified in the literal phrase of the
ALPHABET clause:

•

If numeric, the literals must be unsigned integers and must have values in the range
of 1 through 256.

•

If nonnumeric and associated with a THROUGH (THRU) or ALSO phrase, each literal
must be one character in length.

Note that literal-1, literal-2, and literal-3 must not specify a symbolic-character figurative
constant.
THROUGH
THRU

These keywords are equivalent.

3–12

8600 1518–307

Configuration Section

ALSO

If you specify the ALSO phrase, the characters of the native character set specified by
the value of literal-1 and literal-3 are assigned to the same ordinal position in the collating
sequence being specified or in the character code set that is used to represent the data.
If alphabet-name-1 is referenced in a SYMBOLIC CHARACTERS clause, only literal-1 is
used to represent the character in the native character set.
Refer to “OBJECT-COMPUTER Paragraph” in this section, “SORT Statement” in Section
8, and “MERGE Statement” in Section 7.
CCSVERSION

If the CCSVERSION option is specified, the character code set and the collating
sequence identified with the alphabet-name is the system collating sequence. If the
CCSVERSION phrase is specified without literal-1, the collating sequence identified with
the alphabet-name is the internationalized system default collating sequence. If the
CCSVERSION phrase is specified with literal-1, the collating sequence is identified by
literal-1, provided that literal-1 is valid. The alphabet-name cannot be referred to in a
CODE-SET clause.
If the CCSVERSION "ASERIESNATIVE" is specified, the native national coded character
set and native national collating sequence are referenced as JAPAN EBCDIC D1-2.

Example of CCSVERSION Defined at RUN Time
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
OBJECT-COMPUTER.
PROGRAM COLLATING SEQUENCE FOR NATIONAL IS CCS.
SPECIAL-NAMES.
ALPHABET CCS FOR NATIONAL IS CCSVERSION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 DATA1 PIC N(10).
PROCEDURE DIVISION.
BEGIN.
MOVE HIGH-VALUES TO DATA1.
IF DATA1 = HIGH-VALUES
DISPLAY "OK".
STOP RUN.

8600 1518–307

3–13

Configuration Section

Example of CCSVERSION Specified by
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
OBJECT-COMPUTER.
PROGRAM COLLATING SEQUENCE FOR NATIONAL IS CCS.
SPECIAL-NAMES.
ALPHABET CCS FOR NATION AL IS CCSVERSION "FRANCE".
DATA DIVISION.
WORKING-STORAGE SECTION.
01 DATA1 PIC N(10).
PROCEDURE DIVISION.
BEGIN.
MOVE HIGH-VALUES TO DATA1.
IF DATA1 = HIGH-VALUES
DISPLAY "OK".
STOP RUN.
The CCSVERSION phrase can be specified only once in a program.
Note: Using the internationalized system-default ccsversion can produce unexpected
results for the HIGH-VALUE and LOW-VALUE figurative constants if a program is run on
a host with a system-default ccsversion that differs from the ccsversion compiled into
the program. In this case, the HIGH-VALUE and LOW-VALUE figurative constants contain
values that are correct for the ccsversion compiled into the program. For example, if the
program is compiled on a host with a system-default ccsversion of SPANISH and the
program is run on a host with a default ccsversion of FRANCE, the HIGH-VALUE and
LOW-VALUE constants define their values from the SPANISH ccsversion at compile
time, not from the FRANCE ccsversion.
Rules for the ALPHABET Clause

The collating sequence identified in the ALPHABET clause is defined according to the
following rules:

•

If the ALPHABET clause is specified without either the ALPHANUMERIC or the
NATIONAL phrase, the ALPHANUMERIC phrase is used.

•

The value of each literal specifies the following:

•

3–14

−

If numeric, the literal defines the ordinal number of a character in the native
character set. This value must not exceed 256.

−

If nonnumeric, the literal defines the actual character in the native character set.
If the value of the nonnumeric literal contains multiple characters, each character
in the literal, starting with the leftmost character, is assigned successive
ascending positions in the specified collating sequence.

The order in which the literals appear in the ALPHABET clause determines, in
ascending sequence, the ordinal numbers of the characters in the specified collating
sequence.

8600 1518–307

Configuration Section

•

Any characters in the native collating sequence that are not explicitly defined in the
literal phrase assume a position in the specified collating sequence that is greater
than any of the explicitly specified characters. The relative order in the set of these
unspecified characters is unchanged from the native collating sequence.

•

If the THROUGH (THRU) phrase is used, the set of contiguous characters in the
native character set, beginning with the character defined by the value of literal-1 and
ending with the character defined by the value of literal-2, is assigned a successive
ascending position in the specified collating sequence. In addition, the set of
contiguous characters defined by a given THROUGH (THRU) phrase can specify
characters of the native character set in either ascending or descending sequence.

•

If the ALSO phrase is used, the characters of the native character set specified by
the value of literal-1 and literal-3 are assigned to the same ordinal position in the
specified collating sequence or in the character code set that is used to represent the
data. If alphabet-name-1 is referred to in a SYMBOLIC CHARACTERS clause, only
literal-1 is used to represent the character in the native character set.

The character that has the highest ordinal position in the program collating sequence is
associated with the figurative constant HIGH-VALUE, except when this figurative
constant is defined as a literal in the SPECIAL-NAMES paragraph. If more than one
character has the highest position in the program collating sequence, the last character
specified is associated with the figurative constant HIGH-VALUE.
The character that has the lowest ordinal position in the specified program-collating
sequence is associated with the figurative constant LOW-VALUE, except when this
figurative constant is defined as a literal in the SPECIAL-NAMES paragraph. If more than
one character has the lowest position in the program-collating sequence, the first
character specified is associated with the figurative constant LOW-VALUE.
When defined as literals in the SPECIAL-NAMES paragraph, the figurative constants
HIGH-VALUE and LOW-VALUE are associated with those characters having the highest
and lowest positions, respectively, in the native collating sequence.

8600 1518–307

3–15

Configuration Section

SYMBOLIC CHARACTERS Clause
This optional clause specifies symbolic characters.
symbolic-character-1
integer-1

There must be a one-to-one correspondence between occurrences of symboliccharacter-1 and occurrences of integer-1.
The internal representation of symbolic-character-1 is the internal representation of the
character that is used in the native character set.
A symbolic-character-1 can appear only once in a SYMBOLIC CHARACTERS clause.
The relationship between each symbolic-character-1 and the corresponding integer-1 is
determined by position in the SYMBOLIC CHARACTERS clause. The first symboliccharacter-1 is paired with the first integer-1, the second symbolic-character-1 is paired
with the second integer-1, and so on.
The ordinal position specified by integer-1 must exist in the native character set.
There must be a one-to-one correspondence between occurrences of symboliccharacter-1 and occurrences of integer-1.
When the SYMBOLIC CHARACTERS clause is specified with neither the
ALPHANUMERIC nor the NATIONAL phrase, the ALPHANUMERIC phrase is implied.
When the NATIONAL phrase is specified, the following conditions apply:

•

When the IN phrase is specified, alphabet-name-2 references an alphabet that
defines a single-octet national character set; the ordinal position specified by integer1 exists in that character set.

•

When the IN phrase is not specified, the ordinal position specified by integer-1 exists
in the national character set specified with the "ALPHABET FOR NATIONAL IS
CCSVERSION" clause.

IN alphabet-name-2

The alphabet name is a user-defined word.
If the IN phrase is used, integer-1 determines the ordinal position of the character that is
represented in the character set named by alphabet-name-2.
If the IN phrase is not used, symbolic-character-1 represents the character whose ordinal
position in the native character set is determined by integer-1.

3–16

8600 1518–307

Configuration Section

CLASS Clause
This optional clause relates a name to the set of characters listed in the clause.
class-name-1

This name is a user-defined word that can be referred to only in a class condition.
The characters specified by the values of the literals of this clause define the exclusive
set of characters of which this name consists.
literal-4
literal-5

When the CLASS clause is specified without the ALPHANUMERIC or the NATIONAL
phrase, the ALPHANUMERIC phrase is implied.
When the ALPHANUMERIC phrase is specified or implied the following conditions apply:

•

If literal-4 is numeric, the literal specifies the ordinal number of a character in the
native character set. This value cannot exceed 256.

•

If literal-4 is nonnumeric, the literal specifies the actual character in the native
character set. If the value of the literal contains multiple characters, each character in
the literal is included in the set of characters identified by class-name-1.

When the NATIONAL phrase is specified the following conditions apply:

•

If literal-4 is numeric, it is an unsigned integer and has a value within the range of one
through the number of characters in the national character set specified with the
ALPHABET FOR NATIONAL IS CCSVERSION clause.

•

Each non-integer literal is a national literal.

•

The THROUGH (THRU) phrase cannot be specified for a national character.

•

The number of characters specified cannot exceed the number of characters in the
national character set specified with the ALPHABET FOR NATIONAL IS
CCSVERSION clause.

Note: The aforementioned literals cannot specify a symbolic-character figurative
constant.
The following syntax rules apply to the literals specified in the literal phrase of the CLASS
clause:

•

If numeric, the literals must be unsigned integers and must have values in the range
of 1 through 256.

•

If nonnumeric and associated with a THROUGH (THRU) phrase, each literal must be
one character in length.

8600 1518–307

3–17

Configuration Section

THROUGH
THRU

These keywords are equivalent.
If the THROUGH (THRU) phrase is used, the contiguous characters in the native
character set, beginning with the character specified by the value of literal-4 and ending
with the character specified by the value of literal-5, are included in the set of characters
identified by class-name-1. In addition, the contiguous characters identified by a given
THROUGH (THRU) phrase can specify characters of the native character set in either
ascending or descending sequence.

CURRENCY SIGN Clause
The CURRENCY SIGN clause specifies a currency string that is placed into numericedited data items when they are used as receiving items. The CURRENCY SIGN clause
also specifies a currency string that is placed into de-edited data items when they are
used as sending items that have a numeric or numeric-edited receiving item. In addition,
the clause is used to determine which symbol will be used in a picture character string to
specify the presence of a currency string. This symbol is referred to as the currency
symbol.
If the CURRENCY SIGN clause is specified without the PICTURE SYMBOL phrase,
literal-6 is used as the currency symbol. If the CURRENCY SIGN clause is specified with
the PICTURE SYMBOL phrase, literal-7 is used as the currency symbol.
literal-6

Literal-6 represents the value of the currency string. Literal-6 must be an alphanumeric or
national literal that is not a figurative constant.
If the PICTURE SYMBOL phrase is not specified, then literal-6 is specified and can
consist of only a single character. In this case, literal-6 can be any single character from
the character set except for the following:

•

Digits 0 through 9

•

Alphabetic characters consisting of the uppercase letters A, B, C, D, E, N, P, R, S, V,
X, Z; the lowercase form of these alphabetic characters; and the space character

•

Special characters consisting of the plus sign (+), the minus sign (-), the comma (,),
the period (.), the asterisk (*), the slant (/), the semicolon (;), parenthesis (( )), the
double quotation mark ("), and the equal sign (=)

If the PICTURE SYMBOL phrase is specified, then literal-6 can be any number of
characters. In this case, it must contain at least one non-space character and can consist
of any characters from the character set except for the following:

3–18

•

Digits 0 through 9

•

Special characters consisting of the plus sign (+), the minus sign (-), the comma (,),
the period (.), and the asterisk (*)

8600 1518–307

Configuration Section

literal-7

Literal-7 can be any single character from the character set except for the following:

•

Digits 0 through 9

•

Alphabetic characters consisting of the uppercase letters A, B, C, D, E, N, P, R, S, V,
X, Z; the lowercase form of these alphabetic characters; and the space character

•

Literal-7 IS MNEMONIC-NAME Clause
This clause associates an object-program with a user-defined mnemonic name. It can be
used to declare the file name of a program to be bound or a program to be initiated as a
separate procedure.
In this clause, literal-7 must be a valid file title. It can be of the form AAA/BBB/CCC . . .,
where each group of characters between two slashes is one directory, or file title node,
of the file title. A directory name can contain a maximum of 17 characters. A file title can
consist of a maximum of 14 directories. Mnemonic-name is a user-defined word of your
choice.
For information on binding, refer to Appendix E. For details about tasking and structuring
a COBOL85 program to initiate separately compiled programs, refer to Section 13.

DECIMAL-POINT Clause
This optional clause exchanges the functions of the comma and the period in the
character string of the PICTURE clause and in numeric literals. All numeric literals used in
the program are affected by this clause.
With this clause in use, a comma used as a separator must be followed by a space. The
space is required because a comma immediately followed by a numeric literal is
interpreted as a decimal point by the compiler.

DEFAULT DISPLAY SIGN and DEFAULT COMPUTATIONAL SIGN
Clauses
.These optional clauses specify the default sign position for all signed data items whose
usages are DISPLAY or COMPUTATIONAL, respectively. The default sign position
specified with these clauses is used when a signed data item is declared in the Data
Division without the optional SIGN clause. If the SIGN clause is used in the Data Division,
it overrides the DEFAULT clauses specified in this division. For more information about
signed data items, refer to the discussion of the SIGN clause and character S of
thePICTURE clause in Section 4.

8600 1518–307

3–19

Configuration Section

Example of the SPECIAL-NAMES Paragraph
IDENTIFICATION DIVISION.
PROGRAM-ID. PAYROL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON
OFF STATUS IS SW5-OFF;
CURRENCY SIGN IS "E";
DECIMAL-POINT IS COMMA.
In this example, the program PAYROL includes the optional Configuration Section in its
Environment Division. The source and object computers are the same (both are A5s). A
switch, SW5, is named in the SPECIAL-NAMES paragraph, and the condition-names
SW5-ON and SW5-OFF are used to specify ON STATUS and OFF STATUS, respectively,
of this switch. The one-character nonnumeric literal E defined in the CURRENCY SIGN
clause will replace the dollar sign character ($) in the PICTURE clause. The DECIMALPOINT clause is present, so the comma will replace the period in the PICTURE clause
and in numeric literals, and the period will replace the comma.

3–20

8600 1518–307

Input-Output Section

Input-Output Section
The Input-Output Section includes the information needed to control transmission and
handling of data between external media and the object program. This section is optional
in a COBOL source program.
The Input-Output Section is divided into the following two paragraphs:

•

The FILE-CONTROL paragraph names and associates the files with external media.

•

The I-O-CONTROL paragraph defines special control techniques to be used in the
object program.

Input-Output Section Header
The following header identifies and must begin the Input-Output Section:
INPUT-OUTPUT SECTION.
ïïïïïïïïïïïï ïïïïïïï

INPUT-OUTPUT SECTION

These keywords begin in area A and must be followed by a period.

8600 1518–307

3–21

Input-Output Section

FILE-CONTROL Paragraph
The FILE-CONTROL paragraph does the following:

•

Names each file

•

Identifies the file medium

•

Specifies hardware

•

Specifies alternate input/output areas

•

Specifies the organization of the file

The FILE-CONTROL paragraph is required.

General Format of the FILE-CONTROL Paragraph
The general format of the FILE-CONTROL paragraph is as follows:
FILE-CONTROL. { file control entry } ...
ïïïïïïïïïïïï

FILE-CONTROL

This keyword begins in area A and must be followed by a period.
file control entry

The file control entry has the following four formats:

•

Format 1 declares the physical attributes of a sequential file.

•

Format 2 declares the physical attributes of a relative file.

•

Format 3 declares the physical attributes of an indexed file.

•

Format 4 declares the physical attributes of a sort or merge file.

Each of these formats is discussed in the following pages.

3–22

8600 1518–307

Input-Output Section

File Control Entry Format 1: Sequential Organization
You can use this format to declare the physical attributes of a sequential file.
Ú
SELECT ³ LOCAL
ïïïïïï ³ ïïïïï
³ COMMON
À ïïïïïï

¿
³
³
³
Ù

Ú
ä
³ [RECEIVED] [BY] ³ REFERENCE
³
ã ïïïïïïïïï
³
³ REF
À
æ ïïï

å
³
â
³
ç

¿
³
³
³
Ù

[ OPTIONAL ] file-name-1
ïïïïïïïï
ä
å
ASSIGN TO
³ DISK
³
ïïïïïï
³ ïïïï
³
³ PORT
³
³ ïïïï
³
³ PRINTER ³
³ ïïïïïïï ³
ã READER â
³ ïïïïïï ³
³ REMOTE ³
³ ïïïïïï ³
³ TAPE
³
³ ïïïï
³
³ VIRTUAL ³
æ ïïïïïï ç
[ IS EXTERNAL-FORMAT FOR NATIONAL ]
ïïïïïïïïïïïïïïïïïïïïïïïïïïïï
Ú
Ú
¿ ¿
³ RESERVE integer-1 ³ AREA ³ ³
À ïïïïïïï
À AREAS Ù Ù
[ [ ORGANIZATION IS ] SEQUENTIAL ]
ïïïïïïïïïïïï
ïïïïïïïïïï
Ú
ä
å
³RECORD DELIMITER IS ³ STANDARD-1 ³
³ïïïïïï ïïïïïïïïï
ã ïïïïïïïïïï â
³
³ UNISYS
³
À
æ ïïïïïï
ç
Ú
ä
å
³PADDING CHARACTER IS ³ data-name ³
³ïïïïïïï
ã
â
³
³ literal-1 ³
À
æ
ç
Ú
ä
å
¿
³ACCESS MODE IS ³ SEQUENTIAL ³
³
³ïïïïïï
ã ïïïïïïïïïï â
³
³
³ RANDOM
³
³
À
æ ïïïïïï
ç
Ù
[ ACTUAL KEY IS data-name-3 ]
ïïïïïï
[ FILE STATUS IS data-name-2 ] .
ïïïïïï

¿
³
³
³
Ù
¿
³
³
³
Ù

In the FILE-CONTROL paragraph, you must specify the SELECT clause first. The clauses
that follow the SELECT clause can appear in any order.

8600 1518–307

3–23

Input-Output Section

SELECT Clause
LOCAL

This phrase specifies that the file is a formal parameter for a procedure. A file specified
as LOCAL can be named only in the WITH clause and USING clause of one of the
following:

•

The ENTRY PROCEDURE clause associated with a procedure imported from a library

•

The USE statement associated with a separately compiled, or bound procedure

COMMON

This phrase specifies that the file is declared in another module to which this program is
to be bound. The file description and record description entries in each module in which
the file is declared COMMON must match.
Note: The compiler option COMMON does not affect entries in the Environment
Division or in the File Section of the Data Division.
RECEIVED BY REFERENCE
REF

This phrase allows two or more programs to use the file. Because access to the file is by
reference, any program can perform input-output operations to the file.
OPTIONAL

This phrase only applies to files opened in input, I-O, or extend mode. It is required for
files that are not necessarily present each time the object program is executed.
If you designate an input file with the OPTIONAL phrase in its SELECT clause, and the
file is not present at the time the OPEN statement is executed, the operator is notified of
this fact. At this time, the file can be loaded, or the operator can enter the system
command OF. If the operator uses the OF command, the first READ statement for this
file causes an AT END or INVALID KEY condition to occur. Refer to the System
Commands Operations Reference Manual for information on the OF command.

3–24

8600 1518–307

Input-Output Section

file-name-1

This is a user-defined word that names a file connector.
Each file-name specified in the SELECT clause must have a file description entry in the
Data Division of the same program. Also, each file-name in the Data Division must be
specified only once in the FILE-CONTROL paragraph.
If the file connector referred to by file-name-1 is an external file connector (refer to
“EXTERNAL Clause” in Section 4 and to “File Connectors” in Section 10), all file control
entries in the run unit that refer to this file connector must have:

•

The same specification for the OPTIONAL phrase

•

A consistent specification in the ASSIGN clause

•

A consistent specification in the RECORD DELIMITER clause

•

The same value for integer-1 in the RESERVE clause

•

The same organization

•

The same access mode

•

The same specification for the PADDING CHARACTER clause

ASSIGN Clause
This clause associates the file referenced by file-name-1 to a storage medium.
You can assign file-name-1 to the following:

•

DISK

•

PORT

•

PRINTER

•

READER

•

VIRTUAL

8600 1518–307

3–25

Input-Output Section

IS EXTERNAL-FORMAT FOR NATIONAL Clause
The IS EXTERNAL-FORMAT FOR NATIONAL clause causes data items of the national
class to be transmitted in external format to be suitable for display or printing. External
format means that the control characters SDO (for “start of double octet”) and EDO (for
“end of double octet”) are inserted at the beginning and the end of the data to
distinguish it as national data.
This clause can be specified only for remote files and printer files.
Files with this clause cannot be referenced by a SAME clause (see “Input-Output Control
Entry Format 1: Sequential I/O” later in this section for details about the SAME clause).
If the CCSVERSION clause is specified, the EXTERNAL-FORMAT FOR NATIONAL option
is ignored and a warning is issued.

RESERVE Clause
This clause specifies the number of input-output areas allocated.
integer-1

If the RESERVE clause is specified, the number of input-output areas allocated is equal to
the value of integer-1.
If the RESERVE clause is not specified, two input-output areas are automatically
allocated.

ORGANIZATION IS SEQUENTIAL Clause
This clause specifies sequential organization as the logical structure of a file. If If this
clause is not used, sequential organization is implied.
Details
Sequential organization is a permanent logical file structure in which a record is identified
by a predecessor-successor relationship. This relationship is established when the record
is placed into the file.
The file organization is established at the time a file is created and cannot subsequently
be changed.

RECORD DELIMITER Clause
This clause indicates the method of determining the length of a variable-length record on
the external medium. Any method used will not be reflected in the record area or the
record size used in the program.
Note that this clause can be specified only for variable-length records.

3–26

8600 1518–307

Input-Output Section

STANDARD-1
UNISYS

If either STANDARD-1 or UNISYS is specified, the external medium must be a magnetic
tape file.
If this phrase is specified, the method used for determining the length of a variable
length record is that specified in American National Standard X3.27-1978, Magnetic Tape
Labels and File Structure for Information Interchange, and in International Standard 1001
1979, Magnetic Tape Labels and File Structure for Information Interchange.
Details
At the time the OPEN statement that creates the file is executed, the record delimiter
used is the one specified in the RECORD DELIMITER clause associated with the filename specified in the OPEN statement.
If the associated file connector is an external file connector, all RECORD DELIMITER
clauses in the run unit that are associated with that file connector must have the same
specifications.

PADDING CHARACTER Clause
This clause is for documentation purposes only.

ACCESS MODE IS SEQUENTIAL Clause
This clause specifies the order in which records are to be accessed in the file. If you
specify SEQUENTIAL, records are accessed sequentially. If you do not use this clause,
sequential access is assumed.

ACCESS MODE IS RANDOM Clause
If you specify RANDOM, records are accessed randomly. Random access can be
specified for mass-storage files only.
Details
Records in the file are accessed in the sequence dictated by the file organization. For
sequential files, this sequence is specified by predecessor-successor record relationships
established by the execution of WRITE statements when the file is created or extended.
If the associated file connector is an external file connector, every file control entry in the
run unit that is associated with that file connector must specify the same access mode.

8600 1518–307

3–27

Input-Output Section

ACTUAL KEY Clause
For mass-storage files that specify an ACTUAL KEY, the value of the ACTUAL KEY data
item specifies the logical ordinal position of the record in the file.
For port files, the value of the ACTUAL KEY data item specifies the subfile index of the
port file. The ACTUAL KEY clause must be specified for a port file that contains more
than one subfile.
For remote files, the value of the ACTUAL KEY data item specifies the ordinal number of
the station within the station list of the remote file. A zero value specifies all stations
within the station list of the remote file.
data-name-3

This name is a user-defined word that must refer to an unsigned integer data item whose
description does not contain the PICTURE symbol P.
This name can be qualified.
Note that you can significantly improve the performance of all I/O statements that act
upon a sequential file declared with an actual key by declaring the appropriate key as
follows:
77 USERKEY

REAL.

FILE STATUS Clause
This clause specifies a data item that contains the status of an input-output operation.
data-name-2

This name is a user-defined word. This name must be defined in the Data Division as a
two-character alphanumeric data item and must not be defined in the File Section. This
name can be qualified.
The data item referred to by data-name-2 is the one specified in the file control entry
associated with that statement. See “General Format of the Environment Division” in
this section.
Details
When the FILE STATUS clause is specified, the data item referred to by data-name-2 is
updated to contain the value of the I-O status whenever the I-O status is updated. This
value indicates the status of execution of the statement. See“I-O Status Codes” in this
section.

3–28

8600 1518–307

Input-Output Section

Example of File Control Entry Format 1: Sequential Organization
IDENTIFICATION DIVISION.
PROGRAM-ID. PAYROL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON
OFF STATUS IS SW5-OFF;
CURRENCY SIGN IS "E";
DECIMAL-POINT IS COMMA.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT DATA-CAPTURE ASSIGN TO DISK;
ORGANIZATION IS SEQUENTIAL;
ACCESS MODE IS SEQUENTIAL;
FILE STATUS IS FS-1.
SELECT PRINTOUT ASSIGN TO PRINTER.
.
.
.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 FS-1
PIC XX.
The program PAYROL includes both a Configuration Section and an Input-Output Section.
File Control Entry Format 1 is used in the FILE-CONTROL paragraph. The input file DATACAPTURE, a sequential file, will be stored on disk. The records of this file will be
accessed sequentially. (If the ACCESS MODE clause is not specified, sequential access
is assumed.) The data item FS-1 is specified in the FILE STATUS clause and is defined in
the Data Division. A value will be moved by the operating system into FS-1 after the
execution of every statement that refers to that file. This value indicates the status of
execution of the statement. The output file PRINTOUT is assigned to a printer.

8600 1518–307

3–29

Input-Output Section

File Control Entry Format 2: Relative Organization
You can use this format to declare the physical attributes of a relative file.
Ú
SELECT ³ LOCAL
ïïïïïï ³ ïïïïï
³ COMMON
À ïïïïïï

¿
³
³
³
Ù

Ú
ä
³ [RECEIVED] [BY] ³ REFERENCE
³
ã ïïïïïïïïï
³
³ REF
À
æ ïïï

å
³
â
³
ç

¿
³
³
³
Ù

[ OPTIONAL ] file-name-1
ïïïïïïïï
ASSIGN TO DISK
ïïïïïï
ïïïï
Ú
³ RESERVE integer-1
À ïïïïïïï

Ú
¿
³ AREA ³
À AREAS Ù

¿
³
Ù

[ ORGANIZATION IS ] RELATIVE
ïïïïïïïïïïïï
ïïïïïïïï
Ú
ä
å
³ACCESS MODE IS ³ SEQUENTIAL [ RELATIVE KEY IS data-name-1 ] ³
³ïïïïïï
ã ïïïïïïïïïï
ïïïïïïïï
â
³
³äRANDOM å
³
³
³ãïïïïïï â
³
³
ææDYNAMICç
RELATIVE KEY IS data-name-1
ç
À
ïïïïïïï
ïïïïïïïï

¿
³
³
³
³
³
Ù

[ FILE STATUS IS data-name-2 ] .
ïïïïïï
Refer to File Control Entry Format 1 for information on the RESERVE clause and the FILE
STATUS clause.

SELECT Clause
Refer to File Control Entry Format 1 for information on the SELECT clause, the LOCAL
phrase, the COMMON phrase, the RECEIVED BY REFERENCE phrase, and the
OPTIONAL phrase.
In addition, if the file connector referred to by file-name-1 is an external file connector
(refer to “EXTERNAL Clause” in Section 4 and to “File Connectors” in Section 10), all file
control entries in the run unit that reference this file connector must have:

3–30

•

The same specification for the OPTIONAL phrase

•

A consistent specification in the ASSIGN clause

•

The same value for integer-1 in the RESERVE clause

•

The same organization

•

The same access mode

•

The same external data item for data-name-1 in the RELATIVE KEY phrase

8600 1518–307

Input-Output Section

ASSIGN Clause
Refer to File Control Entry Format 1 for information on this clause.
In addition, in this format DISK specifies that mass storage is the storage medium of the
file. You can define the medium more precisely in the VALUE OF clause of the FD entry
in the Data Division or through the use of file equation.

ORGANIZATION IS RELATIVE Clause
In this format, this clause specifies relative organization as the logical structure of a file.
Details
Relative organization is a permanent logical file structure in which each record is uniquely
identified by an integer value greater than zero, which specifies the record's logical
ordinal position in the file.
The file organization is established at the time a file is created and cannot subsequently
be changed.

ACCESS MODE Clause
This clause specifies the order in which records are to be accessed in the file.
There are three forms of the ACCESS MODE clause in this format: the ACCESS MODE
IS SEQUENTIAL clause, the ACCESS MODE IS RANDOM clause, and the ACCESS
MODE IS DYNAMIC clause.
If this clause is not used, sequential access is assumed.
ACCESS MODE IS SEQUENTIAL

If the access mode is sequential, records in the file are accessed in the sequence
dictated by the file organization. For relative files, this sequence is the order of ascending
relative record numbers of existing records in the file.
ACCESS MODE IS RANDOM

If the access mode is random, the value of the relative key data item for relative files
indicates the record to be accessed.
Note that this access mode must not be specified for file-names specified in the USING
or GIVING phrase of a SORT or MERGE statement.
ACCESS MODE IS DYNAMIC

If the access mode is dynamic, records in the file can be accessed sequentially and/or
randomly.

8600 1518–307

3–31

Input-Output Section

RELATIVE KEY

If a relative file is referred to by a START statement, the RELATIVE KEY phrase within
the ACCESS MODE clause must be specified for that file.
data-name-1

This name is a user-defined word that must refer to an unsigned integer data item whose
description does not contain the PICTURE symbol P. The data item specified by dataname-1 is used to communicate a relative record number to the I-O handler.
This name can be qualified.
This name must not be defined in a record description entry associated with that filename.
The relative key data item associated with the execution of an input-output statement is
the data item referred to by data-name-1 in the ACCESS MODE clause.
Details
All records stored in a relative file are uniquely identified by relative record numbers. The
relative record number of a given record specifies the record's logical ordinal position in
the file. The first logical record has a relative record number of 1, and subsequent logical
records have relative record numbers of 2, 3, 4, and so forth.
If the associated file connector is an external file connector, every file control entry in the
run unit associated with that file connector must specify the same access mode. In
addition, data-name-1 must reference an external data item and the RELATIVE KEY
phrase in each associated file control entry must reference that same external data item
in each case.

3–32

8600 1518–307

Input-Output Section

Example of File Control Entry Format 2: Relative Organization
IDENTIFICATION DIVISION.
PROGRAM-ID. PAYROL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON
OFF STATUS IS SW5-OFF;
CURRENCY SIGN IS "E";
DECIMAL-POINT IS COMMA.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT DATA-CAPTURE-2 ASSIGN TO DISK;
ORGANIZATION IS RELATIVE;
ACCESS MODE IS DYNAMIC; RELATIVE KEY IS ACCT-NO.
In this example, the program PAYROL includes both a Configuration Section and an
Input-Output Section in its Environment Division. File Control Entry Format 2 is used in
the FILE-CONTROL paragraph. The input file DATA-CAPTURE-2, which is a relative file,
will be stored on disk. The file organization is relative. The access mode is dynamic, so
the records of DATA-CAPTURE-2 can be accessed either sequentially (that is, in
ascending order by relative record number) or randomly (that is, in a sequence
determined by use of the RELATIVE KEY phrase). The desired record is accessed by
placing its relative record number in the RELATIVE KEY data item, ACCT-NO.

8600 1518–307

3–33

Input-Output Section

File Control Entry Format 3: Indexed I/O
You can use this format to declare the physical attributes of an indexed file.
Ú
SELECT³
ïïïïïï³
³
À

LOCAL
ïïïïï
COMMON
ïïïïïï

¿
³
³
³
Ù

Ú
ä
³ [ RECEIVED ] [ BY ] ³ REFERENCE
³
ã ïïïïïïïïï
³
³ REF
À
æ ïïï

å
³
â
³
ç

¿
³
³
³
Ù

[ OPTIONAL ] file-name-1
ïïïïïïïï
ASSIGN TO DISK
ïïïïïï
ïïïï
Ú
³ RESERVE integer-1
À ïïïïïïï

Ú
¿
³ AREA ³
À AREAS Ù

¿
³
Ù

[

ORGANIZATION IS ] INDEXED
ïïïïïïïïïïïï
ïïïïïïï
Ú
ä
å ¿
³ACCESS MODE IS ³ SEQUENTIAL ³ ³
³ïïïïïï
ã ïïïïïïïïïï â ³
³
³ RANDOM
³ ³
³
³ ïïïïïï
³ ³
³
æ DYNAMIC
ç ³
À
ïïïïïïï
Ù
RECORD KEY IS data-name-1
ïïïïïï
[ ALTERNATE RECORD KEY IS data-name-2 [ WITH DUPLICATES ] ] ...
ïïïïïïïïï ïïïïïï
ïïïïïïïïïï
[ FILE STATUS IS data-name-3 ] .
ïïïïïï
Refer to File Control Entry Format 1 for information on the RESERVE clause.

3–34

8600 1518–307

Input-Output Section

SELECT Clause
Refer to File Control Entry Format 1 for information on the SELECT clause, the LOCAL
phrase, the COMMON phrase, the RECEIVED BY REFERENCE phrase, and the
OPTIONAL phrase.
In addition, in this format, if the file connector referred to by file-name-1 is an external file
connector (refer to “EXTERNAL Clause” in Section 4 and to “File Connectors” in Section
10), all file control entries in the run unit that reference this file connector must have:

•

The same specification for the OPTIONAL phrase

•

A consistent specification in the ASSIGN clause

•

The same value for integer-1 in the RESERVE clause

•

The same organization

•

The same access mode

•

The same data description entry for data-name-1 with the same relative location
within the associated record

•

The same data description entry for data-name-2, the same relative location within
the associated record, the same number of alternate record keys, and the same
DUPLICATES phrase

ASSIGN Clause
Refer to File Control Entry Format 1 for information on this clause.
In addition, in this format, DISK specifies that mass storage is the storage medium of the
file. You can define the medium more precisely in the VALUE OF clause of the FD in the
Data Division or with file equation.

ORGANIZATION IS INDEXED Clause
In this format, this clause specifies indexed organization as the logical structure of a file.
Details
Indexed organization is a permanent logical file structure in which each record is
identified by the value of one or more keys within that record.
The file organization is established at the time a file is created and cannot subsequently
be changed.
The native character set is assumed for data on the external media.
For an indexed file, the collating sequence associated with the native character set is
assumed. This is the sequence of values of a given key of reference used to process the
file sequentially.

8600 1518–307

3–35

Input-Output Section

ACCESS MODE Clause
This clause specifies the order in which records are to be accessed in the file.
There are three forms of the ACCESS MODE clause in this format: the ACCESS MODE
IS SEQUENTIAL clause, the ACCESS MODE IS RANDOM clause, and the ACCESS
MODE IS DYNAMIC clause.
If this clause is not specified, sequential access is assumed.
ACCESS MODE IS SEQUENTIAL

If the access mode is sequential, records in the file are accessed in the sequence
dictated by the file organization. For indexed files, this sequence is ascending within a
given key of reference according to the collating sequence of the file.
ACCESS MODE IS RANDOM

If the access mode is random, the value of a record key data item for indexed files
indicates the record to be accessed.
Note that this access mode must not be specified for file-names specified in the USING
or GIVING phrase of a SORT or MERGE statement.
ACCESS MODE IS DYNAMIC

If the access mode is dynamic, records in the file can be accessed sequentially and/or
randomly.
Details
If the associated file connector is an external file connector, every file control entry in the
run unit that is associated with that file connector must specify the same access mode.

RECORD KEY Clause
This clause specifies a prime record key for the file with which this clause is associated.
The values of the prime record key must be unique among the records of the file. The
prime record key provides an access path to records in an indexed file.
If the indexed file contains variable length records, the prime record key must be
contained within the first x character positions of the record, where x equals the
minimum record size specified for the file (refer to “RECORD Clause” in Section 4).
data-name-1

This name is a user-defined word. It must reference an alphanumeric or a numeric data
item in a record description entry associated with the file-name to which the RECORD
KEY clause is subordinate.
This name can be qualified.

3–36

8600 1518–307

Input-Output Section

This name must not reference a group item that contains a variable occurrence data
item.
The data description of data-name-1, as well as its relative location within a record, must
be the same as that used when the file was created.
If the file has more than one record description entry, data-name-1 need be described
only in one of these record description entries. The identical character positions referred
to by data-name-1 in any one record description entry are implicitly referred to as keys for
all other record description entries of that file.
Details
If the associated file connector is an external file connector, all file description entries in
the run unit that are associated with that file connector must specify the same data
description entry for data-name-1, with the same relative location within the associated
record.

ALTERNATE RECORD KEY Clause
This clause specifies an alternate record key for the file with which this clause is
associated. The alternate record key provides an alternate access path to the records in
an indexed file.
If the indexed file contains variable length records, each alternate record key must be
contained within the first x character positions of the record, where x equals the
minimum record size specified for the file (refer to “RECORD Clause” in Section 4).
data-name-2

This name is a user-defined word. This name must be defined as an alphanumeric or a
numeric data item in a record description entry associated with the file-name to which
the ALTERNATE RECORD KEY clause is subordinate.
This name can be qualified.
This name must not reference a group item that contains a variable occurrence data
item.
This name must not refer to an item whose leftmost character position corresponds to
the leftmost character position of the prime record key or of any other alternate record
key associated with this file.
The data description of data-name-2, as well as its relative location within a record, must
be the same as that used when the file was created. The number of alternate record
keys for the file must also be the same as that used when the file was created.
If the file has more than one record description entry, data-name-1 need be described
only in one of these record description entries. The identical character positions referred
to by data-name-2 in any one record description entry are implicitly referred to in keys for
all other record description entries of that file.

8600 1518–307

3–37

Input-Output Section

WITH DUPLICATES

This phrase specifies that the value of the associated alternate record key can be
duplicated in any of the records in the file.
If this phrase is not specified, the value of the associated alternate record key must not
be duplicated among any of the records in the file.
Details
If the associated file connector is an external file connector, every file control entry in the
run unit that is associated with that file connector must specify the same data
description entry for data-name-2, the same relative location within the associated
record, the same number of alternate record keys, and the same DUPLICATES phrase.

FILE STATUS Clause
Refer to File Control Entry Format 1 for information on this clause. Note that information
about data-name-2 in Format 1 applies to data-name-3 in this format.

Example of File Control Entry Format 3: Indexed I/O
PROGRAM-ID. PAYROL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON
OFF STATUS IS SW5-OFF;
CURRENCY SIGN IS "E";
DECIMAL-POINT IS COMMA.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT DATA-CAPTURE-3 ASSIGN TO DISK;
RESERVE 5 AREAS;
ORGANIZATION IS INDEXED;
ACCESS MODE IS RANDOM;
RECORD KEY IS NAME;
ALTERNATE RECORD KEY IS MODEL-NO WITH DUPLICATES.
In this example, the program PAYROL includes both a Configuration Section and an
Input-Output Section in its Environment Division. File Control Entry Format 3 is used in
the FILE-CONTROL paragraph. The input file DATA-CAPTURE-3, which is an indexed file,
will be stored on disk. Five input-output areas are allocated with the RESERVE clause.
The file organization is indexed. The access mode is random, so the records of DATACAPTURE-3 can be accessed in a sequence determined by use of the RECORD KEY
clause. The desired record is accessed by placing the value of its prime record key in the
RECORD KEY data item, NAME. MODEL-NO is specified as an alternate record key for
the file.

3–38

8600 1518–307

Input-Output Section

File Control Entry Format 4: Sort-Merge
You can use this format to declare the physical attributes of a sort or merge file.
SELECT file-name-1
ïïïïïï
ASSIGN TO
ïïïïïï
ä
³
³
Ú
³
³
³
³
³
³
³
³
³
³ ä
å
³
SORT ³ ³ FOR ³
³
ïïïï ³ ã
â
³
³ ³ WITH ³
³
³ æ
ç
³
³
³
³
³
³
³
³
ã
³
³
³
³
À
³
Ú
³
³ ä
³
MERGE
³ ³ FOR
³
ïïïïï
³ ã
³
³ ³ WITH
³
³ æ
³
³
³
³
³
À
³
æ

ä
³
³
³
³
³
³
ã
³
³
³
³
³
³
æ
å
³
â
³
ç

Ú
¿
³
ä
å ³
³ DISK [ AND integer-1 ] ³ TAPE ³ ³
³ ïïïï
ã ïïïï â ³
³
³ TAPES ³ ³
³
æ ïïïïï ç ³
À
Ù
ä
[ integer-2 ] ³
ã
³
æ

ä
³
³
ã
³
³
æ

å
DISK ³
ïïïï ³
TAPE â
ïïïï ³
TAPES ³
ïïïïï ç

TAPE
ïïïï
TAPES
ïïïïï

å
³
â
³
ç

¿
³
³
³
³
³
³
³
Ù

å
³
³
³
³
³
³
â
³
³
³
³
³
³
ç

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
Ù

å
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
³
³
³
³
³
ç

Refer to File Control Entry Format 1 for information on the SELECT clause.
File-name-1 represents a sort or merge file.
Details
In this format, since file-name-1 represents a sort or merge file, only the ASSIGN clause
is permitted to follow file-name-1 in the FILE-CONTROL paragraph.
Each sort or merge file described in the Data Division must be specified only once as a
file-name in the FILE-CONTROL paragraph.

8600 1518–307

3–39

Input-Output Section

ASSIGN Clause
This clause associates the sort or merge file referred to by file-name-1 with a storage
medium.
DISK

When DISK is specified, mass storage is the primary work medium.
TAPE, TAPES

TAPE or TAPES can be specified to contain any overflow.
integer-1
integer-2

Integer-1 and integer-2 must have values within the range of 3 through 8.
If integer-1 is not specified, three tapes are assumed.
If TAPE or TAPES is specified as the primary work medium of the sort and integer-2 is
not specified, the default number of tapes is three.

Example of File Control Entry Format 4: Sort-Merge
IDENTIFICATION DIVISION.
PROGRAM-ID. PAYROL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON
OFF STATUS IS SW5-OFF;
CURRENCY SIGN IS "E";
DECIMAL-POINT IS COMMA.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT SORT-FILE ASSIGN TO SORT FOR DISK AND 3 TAPES.
The program PAYROL includes both a Configuration Section and an Input-Output Section.
File Control Entry Format 4 is used in the FILE-CONTROL paragraph. The ASSIGN clause
is the only clause that can be specified in this format. The input file SORT-FILE, a sort
file, is assigned to the storage medium SORT, with mass storage (DISK) as the primary
work medium of the sort and three tapes for overflow.

3–40

8600 1518–307

Input-Output Section

I-O-CONTROL Paragraph
The I-O-CONTROL paragraph specifies:

•

The memory area that is to be shared by different files

•

The location of files on a multiple file reel

This paragraph is optional. Clauses can appear in any order in this paragraph.

I-O-CONTROL. [ input-output control entry . ]
ïïïïïïïïïïï

I-O-CONTROL

This keyword begins in area A and must be followed by a period.
input-output control entry

The input-output control entry should have a period only at the end. The input-output
control entry has three formats:

•

Format 1 is used for sequential I/O.

•

Format 2 is used for relative and indexed I/O.

•

Format 3 is used for sort-merge.

Input-Output Control Entry Format 1: Sequential I/O
I-O-CONTROL.
ïïïïïïïïïïïï
[ [ SAME [ RECORD ] AREA FOR file-name-3 { file-name-4 } ... ] ...
ïïïï
ïïïïïï
[MULTIPLE FILE TAPE CONTAINS { file-name-5 [POSITION integer-3] } ... ] ...
ïïïïïïïï ïïïï
ïïïïïïïï

]

I-O-CONTROL

This keyword begins in area A and must be followed by a period.

8600 1518–307

3–41

Input-Output Section

SAME Clause
This clause specifies the memory area that is to be shared by different files.
There are two forms of the SAME clause: the SAME AREA clause and the SAME
RECORD AREA clause.
SAME AREA

The SAME AREA clause specifies that two or more files that do not represent sort or
merge files are to use the same memory area during processing. The area being shared
includes all storage areas assigned to the files referred to by file-name-3 and file-name-4;
thus, only one file can be open at a time.
SAME RECORD AREA

The SAME RECORD AREA clause specifies that two or more files are to use the same
memory area for processing of the current logical record. Only the record work area is
shared. All of the files can be open at the same time. A logical record in the SAME
RECORD AREA is considered a logical record of each opened output file whose file-name
appears in the SAME RECORD AREA clause and of the most recently read input file
whose file-name appears in the SAME RECORD AREA clause. Like an implicit
redefinition of the area, records are aligned at the leftmost character position.
file-name-3
file-name-4

These names must be specified in the FILE-CONTROL paragraph of the same program.
These names must not reference an external file connector.
These names must not reference a file that uses the IS EXTERNAL-FORMAT FOR
NATIONAL clause.
Rules
More than one SAME clause can be included in a program, subject to the following
restrictions:

3–42

•

A file-name must not appear in more than one SAME AREA clause.

•

A file-name must not appear in more than one SAME RECORD AREA clause.

•

If one or more file-names of a SAME AREA clause appear in a SAME RECORD AREA
clause, all of the file-names in the SAME AREA clause must appear in the SAME
RECORD AREA clause. However, additional file-names not appearing in that SAME
AREA clause can also appear in that SAME RECORD AREA clause. The rule that only
one of the files mentioned in a SAME AREA clause can be open at any given time
takes precedence over the rule that all files mentioned in a SAME RECORD AREA
clause can be open at any given time.

8600 1518–307

Input-Output Section

MULTIPLE FILE TAPE Clause
This clause specifies the location of files on a multiple-file reel.
This clause is required when more than one file shares the same physical reel of tape.
Regardless of the number of files on a single reel, only those files that are used in the
object program need to be specified.
POSITION

If all file-names have been listed in consecutive order, the POSITION phrase need not be
given. If any file in the sequence is not listed, the position relative to the beginning of the
tape must be given. No more than one file on the same tape reel can be open at one
time.
Note: This clause is an obsolete element in COBOL ANSI-85 and will be deleted from
the next revision of the COBOL standard.

Example of Input-Output Control Entry Format 1: Sequential I/O
IDENTIFICATION DIVISION.
PROGRAM-ID. PAYROL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON
OFF STATUS IS SW5-OFF;
CURRENCY SIGN IS "E";
DECIMAL-POINT IS COMMA.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT INFIL ASSIGN TO TAPE.
SELECT OUTFIL ASSIGN TO TAPE.
I-O-CONTROL.
SAME AREA FOR INFIL OUTFIL.
In this example, the program PAYROL includes both a Configuration Section and an
Input-Output Section in its Environment Division. The SELECT clause in the FILECONTROL paragraph assigns two sequential files, INFIL and OUTFIL, to the storage
medium TAPE. The SAME clause in the I-O-CONTROL paragraph, which uses InputOutput Control Entry Format 1, specifies that INFIL and OUTFIL will share the same
memory area during processing (but only one of these files can be open at a time).

8600 1518–307

3–43

Input-Output Section

Input-Output Control Entry Format 2: Relative and Indexed
Organization
I-O-CONTROL.
ïïïïïïïïïïï
[ [ SAME [ RECORD ] AREA FOR file-name-3 { file-name-4 } ... ]
ïïïï
ïïïïïï

...

. ]

Refer to Input-Output Control Entry Format 1 for information on the SAME clause.
I-O-CONTROL

This keyword begins in area A and must be followed by a period.
Examples of Input-Output Control Entry Format 2: Relative and Indexed
Organization
IDENTIFICATION DIVISION.
PROGRAM-ID. PAYROL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON
OFF STATUS IS SW5-OFF;
CURRENCY SIGN IS "E";
DECIMAL-POINT IS COMMA.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT INFIL ASSIGN TO DISK;
ORGANIZATION IS RELATIVE;
ACCESS MODE IS SEQUENTIAL;
SELECT OUTFIL ASSIGN TO DISK;
ORGANIZATION IS RELATIVE;
ACCESS MODE IS SEQUENTIAL;
I-O-CONTROL.
SAME AREA FOR INFIL OUTFIL.

RELATIVE KEY IS ACCT-NO.

RELATIVE KEY IS MODEL-NO.

The program PAYROL includes a Configuration Section and an Input-Output Section. The
SELECT clause assigns two relative files, INFIL and OUTFIL, to DISK. The SAME clause
causes the INFIL and OUTFIL files to use the same memory area for file information.
These two files must not be open at the same time.

3–44

8600 1518–307

Input-Output Section

IDENTIFICATION DIVISION.
PROGRAM-ID. PAYROL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON
OFF STATUS IS SW5-OFF;
CURRENCY SIGN IS "E";
DECIMAL-POINT IS COMMA.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT INFIL ASSIGN TO DISK;
ORGANIZATION IS INDEXED;
ACCESS MODE IS SEQUENTIAL;
RECORD KEY IS NAME;
ALTERNATE RECORD KEY IS MODEL-NO WITH DUPLICATES.
SELECT OUTFIL ASSIGN TO DISK;
ORGANIZATION IS INDEXED;
ACCESS MODE IS SEQUENTIAL;
RECORD KEY IS ACCT-NO;
ALTERNATE RECORD KEY IS DEPT-NO.
I-O-CONTROL.
SAME RECORD AREA FOR INFIL OUTFIL.
In this example, the program PAYROL includes both a Configuration Section and an
Input-Output Section in its Environment Division. The SELECT clause in the FILECONTROL paragraph assigns two indexed files, INFIL and OUTFIL, to the storage
medium DISK. The SAME RECORD clause in the I-O-CONTROL paragraph, which uses
Input-Output Control Entry Format 2, specifies that INFIL and OUTFIL will share the
same record area for processing of the current logical record. Both of these files can be
open at the same time.

8600 1518–307

3–45

Input-Output Section

Input-Output Control Entry Format 3: Sort-Merge
I-O-CONTROL.
ïïïïïïïïïïï
Ú Ú
³ ³
ä
³ ³
³
³ ³
³
³ ³ SAME ã
³ ³ ïïïï ³
³ ³
³
³ ³
æ
À À

¿
å
³
RECORD
³
³
ïïïïïï
³
³
SORT
â AREA FOR file-name-1 {file-name-2}... ³ ...
ïïïï
³
³
SORT-MERGE ³
³
ïïïïïïïïïï ç
³
Ù

¿
³
³
³
. ³
³
³
³
Ù

I-O-CONTROL

This keyword begins in area A and must be followed by a period.

SAME Clause
This clause specifies the memory area that is to be shared by different files. At least one
of these files must be a sort or merge file.
There are two forms of the SAME clause in this format: the SAME RECORD AREA
clause and the SAME SORT AREA or SAME SORT-MERGE AREA clause.
SAME RECORD AREA

This clause specifies that two or more files referred to by file-name-1 and file-name-2 are
to use the same memory area for processing of the current logical record. All of these
files can be in the open mode at the same time. A logical record in the SAME RECORD
AREA is considered to be a logical record of each file that is open in the output mode and
whose file-name appears in the SAME RECORD AREA clause, and of the most recently
read file that is open in the input mode and whose file-name appears in the SAME
RECORD AREA clause. This is equivalent to an implicit redefinition of the area; that is,
records are aligned on the leftmost character position.
SAME SORT AREA
SAME SORT-MERGE AREA

These keywords are equivalent. If this clause is used, at least one of the file-names must
represent a sort or merge file.

3–46

8600 1518–307

Input-Output Section

file-name-1
file-name-2

Each file-name specified in the SAME clause must be specified in the FILE-CONTROL
paragraph of the same program. File-name-1 and file-name-2 must not reference an
external file connector.
A file-name that represents a sort or merge file must not appear in the SAME clause
unless the SORT, SORT-MERGE, or RECORD phrase is used.
The files referred to in the SAME clause need not all have the same organization or
access.
Details
The SAME clause specifies that storage is shared as follows:

•

The SAME SORT AREA or SAME SORT-MERGE AREA clause specifies a memory
area that will be made available for use in sorting or merging each sort or merge file
named. Thus, any memory area allocated for the sorting or merging of a sort or
merge file is available for reuse in sorting or merging any of the other sort or merge
files.

•

In addition, storage areas assigned to files that do not represent sort or merge files
can be allocated as needed for sorting or merging the sort or merge files named in
the SAME SORT AREA or SAME SORT-MERGE AREA clause.

•

Files other than sort or merge files do not share the same storage area with each
other. For these files to share the same storage area with each other, the program
must contain a SAME AREA or SAME RECORD AREA clause specifying file-names
associated with these files.

•

During the execution of a SORT or MERGE statement that refers to a sort or merge
file named in this clause, any non-sort or non-merge files associated with file-names
named in this clause must not be in the open mode.

Rules
More than one SAME clause can be included in a program. If more than one SAME
clause is included in a program, the following restrictions apply:

•

A file-name must not appear in more than one SAME RECORD AREA clause.

•

A file-name that represents a sort or merge file must not appear in more than one
SAME SORT AREA or SAME SORT-MERGE AREA clause.

•

If a file-name that does not represent a sort or merge file appears in a SAME clause
and one or more SAME SORT AREA or SAME SORT-MERGE AREA clauses, all of
the files named in that SAME clause must be named in that SAME SORT AREA or
SAME SORT-MERGE AREA clause(s).

8600 1518–307

3–47

Input-Output Section

Example of Input-Output Control Entry Format 3: Sort-Merge
IDENTIFICATION DIVISION.
PROGRAM-ID. PAYROL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON
OFF STATUS IS SW5-OFF;
CURRENCY SIGN IS "E";
DECIMAL-POINT IS COMMA.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT DATA-CAPTURE-1 ASSIGN TO TAPE.
SELECT DATA-CAPTURE-2 ASSIGN TO TAPE.
SELECT SORT-FILE ASSIGN TO SORT.
SELECT MERGE-FILE ASSIGN TO MERGE.
I-O-CONTROL.
SAME SORT-MERGE AREA FOR SORT-FILE MERGE-FILE.
In this example, the program PAYROL includes both a Configuration Section and an
Input-Output Section in its Environment Division. In the FILE-CONTROL paragraph, the
input file SORT-FILE, which is a sort file, is assigned to the storage medium SORT, and
the input file MERGE-FILE, which is a merge file, is assigned to the storage medium
MERGE. The SAME clause in the I-O-CONTROL paragraph, which uses Input-Output
Control Entry Format 3, specifies that SORT-FILE and MERGE-FILE will share the same
memory area for sorting or merging.

3–48

8600 1518–307

Input-Output Section

I-O Status Codes
The I-O status is a two-character conceptual entity whose value is set to indicate the
status of an input-output operation. Some status values indicate successful execution,
while other values indicate unsuccessful execution. The value of the I-O status is made
available to the COBOL program through the data item named in the FILE STATUS
clause of the file control entry for the file.
The I-O status value is placed into the FILE STATUS data item in the following situations:

•

During the execution of a CLOSE, DELETE, OPEN, READ, REWRITE, START or
WRITE statement before the execution of any imperative statement associated with
the statement

•

Before the execution of any applicable USE AFTER STANDARD EXCEPTION
procedure

Note: To receive the standard COBOL ANSI-85 status codes, you must set the
$ANSICLASS compiler option. For COBOL74 compatibility, this option must be reset
(FALSE). The default value is FALSE. For details about this option, refer to Section 15.
Tables 3–1 through 3–6 describe each of the possible I-O status codes. The symbols
used in the File Organization column of these tables are as follows:

Symbol

Meaning

Organization is sequential.

Organization is relative.

Organization is indexed.

The I-O status values in Table 3–1 indicate that the input-output statement was
successfully executed.
Table 3–1. I-O Status Codes: Successful Execution

File
Organization

I-O Status

Condition Description

SRI

The input-output statement was successfully
executed and no further information is available
concerning the input-output operation.

SRI

A READ statement was successfully executed, but
the length of the record that was processed did not
conform to the fixed file attributes for that file.

SRI

An OPEN statement was successfully executed, but
the referenced optional file was not present when
execution of the OPEN statement began. If the open
mode was I-O or EXTEND, the file was created.

8600 1518–307

3–49

Input-Output Section

Table 3–1. I-O Status Codes: Successful Execution

File
Organization

I-O Status

Condition Description

The input-output statement was successfully
executed. However, for a CLOSE statement with the
NO REWIND, REEL/UNIT, or FOR REMOVAL phrase
or for an OPEN statement with the NO REWIND
phrase, the referred to file was on a non-reel/unit
medium.

The I-O status values in Table 3–2 indicate that a sequential READ statement was
unsuccessfully executed as a result of an end-of-file condition.
Table 3–2. I-O Status Codes: Unsuccessful READ—End-of-File
Condition

File
Organization

I-O Status

Condition Description

SRI

The execution of a sequential READ statement was
unsuccessful because:

3–50

•

The end of the file has been reached (no next
logical record was present in the file).

•

A sequential READ statement was attempted
for the first time on an optional input file that
was not present when the associated OPEN
statement was executed.

•

An attempt was made to sequentially read a
port file when no next logical record existed
and the communication path with the
connected process was no longer established.

A sequential READ statement was attempted for a
relative file, but the number of significant digits in
the relative record number is larger than the size of
the actual or relative key data item described for the
file.

8600 1518–307

Input-Output Section

The I-O status values in Table 3–3 indicate that the input-output statement was
unsuccessfully executed as a result of an invalid key condition.
Table 3–3. I-O Status Codes: Unsuccessful I/O—Invalid Key Condition

File
Organization

I-O Status

Condition Description

A sequence error exists for a sequentially accessed
indexed file. Either the prime record key value was
changed by the program between the successful
execution of a READ statement and the execution of
the next REWRITE statement for that file, or the
ascending sequence requirements for successive
record key values were violated.

An attempt was made to write a record that would
create a duplicate key in a relative file.

An attempt was made to write or rewrite a record that
would create a duplicate prime record key or a
duplicate alternate record key without the
DUPLICATES phrase in an indexed file.

SRI

This condition exists because:

•

An attempt was made to randomly access a
record that does not exist in the file.

•

A START or random READ statement was
attempted on an optional input file that is not
present.

A sequential WRITE statement was attempted, but
the relative record number is larger than the size of
the relative key data item described for the file.

SRI

No space is available on the disk, and the
NORESOURCEWAIT file attribute is TRUE.

8600 1518–307

3–51

Input-Output Section

The I-O status values in Table 3–4 indicate that the input-output statement was
unsuccessfully executed as a result of an error that precluded further processing of the
file. Any specified exception procedures are executed. The permanent error condition
remains in effect for all subsequent input-output operations on the file, until you take
action to correct the error or your program performs error recovery.
Table 3–4. I-O Status Codes: Unsuccessful I/O—Permanent Error
Condition

3–52

File
Organization

I-O Status

Condition Description

SRI

A permanent error exists and no further information is
available concerning the input-output operation.

A permanent error exists because of a boundary
violation; an attempt was made to write beyond the
externally defined boundaries of a sequential file.

SRI

A permanent error exists because an OPEN
statement with the INPUT, I-O, or EXTEND phrase
was attempted on a non-optional file that is not
present. This error occurs only after you enter the
command ?NF RSVP.

SRI

A permanent error exists because an OPEN
statement is attempted on a file and that file will not
support the open mode specified in the OPEN
statement. The possible violations are:

•

The EXTEND or OUTPUT phrase was specified,
but the file will not support write operations.

•

The I-O phrase was specified, but the file will not
support the input and output operations that are
permitted for a sequential, relative, or indexed
file when opened in the I-O mode.

•

The INPUT phrase was specified, but the file will
not support read operations.

SRI

A permanent error exists because an OPEN
statement was attempted on a file previously closed
with lock.

SRI

The OPEN statement was unsuccessful because a
conflict has been detected between the fixed file
attributes and the attributes for that file in the
program.

8600 1518–307

Input-Output Section

The I-O status values in Table 3–5 indicate that the statement was unsuccessfully
executed either as a result of an improper sequence of operations that were performed
on the file, or as a result of violating a limit defined by the user.
Table 3–5. I-O Status Codes: Unsuccessful I/O—Invalid Operations

File
Organization

I-O Status

Condition Description

SRI

An OPEN statement was attempted for a file in the
open mode.

SRI

A CLOSE statement was attempted for a file not in
the open mode.

SRI

For a mass-storage file in the sequential access mode
the last input-output statement executed for the
associated file prior to the execution of a DELETE or
REWRITE statement was not a successfully executed
READ statement.

SRI

A boundary violation exists because:

SRI

•

An attempt was made to write or rewrite a record
that is larger than the largest or smaller than the
smallest record allowed by the RECORD IS
VARYING or RECORD CONTAINS clause of the
associated file-name.

•

An attempt was made to rewrite a record to a
sequential file and the record is not the same size
as the record being replaced. (Sequential)

A sequential READ statement was attempted on a file
open in the input or I-O mode and no valid next record
has been established because:

•

The preceding READ statement was
unsuccessful but did not cause an at end
condition.

•

The preceding READ statement caused an at end
condition.

•

The preceding START statement was
unsuccessful. (Relative/Indexed).
This does not apply to port files or remote files for
which a non-zero TIMELIMIT is specified.

SRI

The execution of a READ or START statement was
attempted on a file opened in a mode other than input
or I-O.

The execution of a WRITE statement was attempted
on a file opened in a mode other than output.

SRI

The execution of a WRITE statement was attempted
on a file opened in a mode other than I-O, output, or
extend.

8600 1518–307

3–53

Input-Output Section

Table 3–5. I-O Status Codes: Unsuccessful I/O—Invalid Operations

File
Organization

I-O Status

Condition Description

The execution of a REWRITE statement was
attempted on a file opened in a mode other than
output.

The execution of a DELETE or REWRITE statement
was attempted on a file opened in a mode other than
I-O.

The I-O status values in Table 3–6 indicate Unisys defined conditions.
Table 3–6. I-O Status Codes: Unisys Defined Conditions

3–54

File
Organization

I-O Status

Condition Description

SRI

Short Block. A physical block shorter than the
physical blocksize declared for the file was received
from the hardware device. The operation completed
successfully because an I/O status value of 91 is to
be considered a warning, not an error.

SRI

Data Error. When logical records are declared variable
in length and the logical record length is supplied by
the programmer (by the RECORD CONTAINS clause),
a data error occurs on a READ, WRITE, or REWRITE
statement if the logical record length supplied is less
than the minimum record size or greater than the
maximum record size declared for the file. This
condition initiates no I/O operation and does not
cause data to be transferred to or from the record
area.

Port File. A broadcast write operation failed on one or
more subports.

No Data. The WITH NO WAIT clause was used with
the READ statement and no data was available.

No Buffer. The WITH NO WAIT clause was used with
the WRITE statement and no buffer was available.

SRI

Timeout. A time limit elapsed before the transfer of
data to or from the hardware device.

8600 1518–307

Input-Output Section

Table 3–6. I-O Status Codes: Unisys Defined Conditions

File
Organization

I-O Status

Condition Description

Form Not Found. A READ FORM or WRITE FORM
statement to a file that is designated ASSIGN TO
REMOTE requested a form that does exist in the
form library or requested a form for which the
compile-time version does not equal the run-time
version.

Timeout. A deadly embrace (or “deadlock”) occurred
because multiple programs tried to lock the same
records in a different order.

SRI

Break on Output. For an output or I-O file, this
condition occurs if the hardware device is equipped
with a break so that the transfer of data in process
can be halted.

Deadlock.

SRI

Unexpected I/O Error. An error might have occurred
in the I/O operation, but its nature cannot be
determined.

You specified a file with the LOCK statement that
does not support locking.

An existing locked region of the file is blocking the
LOCK request, and the resulting wait timed out.

The LOCK statement failed, because the number of
locked regions met the system-imposed maximum.

An UNLOCK statement was issued but failed,
because no locked records matched its record
specification.

The record being written is unlocked by the current
user.

8600 1518–307

3–55

Input-Output Section

Recovering from I-O Errors
You can enable a COBOL85 program to recover from an I-O error by specifying a
particular action for the program to take if an error occurs during the execution of an I-O
statement. To specify the alternate action, use one of the following syntaxes:

•

FILE STATUS clause in the Environment Division
The FILE STATUS clause associates a file status variable with the file. You can use
this method to detect and recover from any I-O error for the file.

•

USE AFTER STANDARD EXCEPTION statement in the Procedure Division
You can associate a USE procedure with the file to detect and recover from an I-O
error in a file

•

−

That is named in the USE statement

−

That has the same open mode as that of the file named in the USE statement
(for files not explicitly named in any USE AFTER STANDARD EXCEPTION
statement)

AT END or INVALID KEY phrase with the READ and WRITE statements as allowed
by the specific formats
You can use this method to detect and recover from either an AT END or an INVALID
KEY error condition. For details on these error conditions, see the READ statement in
Section 7 and the WRITE statement in Section 8.

3–56

8600 1518–307

Input-Output Section

How the Recovery Process Occurs
Recovery from an I-O error occurs in the following way:
1. If the FILE STATUS clause is present in the program, the specified data item is
updated to reflect the error condition.
2. The next action depends upon the following conditions:

If an AT END or INVALID
KEY phrase is . . .

And . . .

Then . . .

Present

The error code in the FILE
STATUS data item
indicates AT END or an
INVALID key,

The specified imperative
statement is executed.

Present

The error code in the FILE
STATUS data item does
not indicate AT END or an
INVALID key,

The USE AFTER
STANDARD EXCEPTION
procedure is executed, if
present.

Not Present

The USE AFTER
STANDARD EXCEPTION
procedure is executed, if
present.

3. Finally, the next statement in the program is executed.

8600 1518–307

3–57

Input-Output Section

Modifying the Recovery Process for COBOL74 Compatibility
The $FS4XCONTINUE compiler option is available to provide error semantics similar to
COBOL74 if you are migrating COBOL74 code to COBOL85. When reset (FALSE), this
compiler option causes a program to be terminated if it issues

•

An OPEN statement for an open file

•

A CLOSE statement for a file that is already closed

•

A READ, SEEK, or START statement for a file opened in a mode other than INPUT or
I-O

•

A WRITE statement for a file opened in a mode other than EXTEND, I-O, or OUTPUT

•

A DELETE or REWRITE statement for a file opened in a mode other than I-O

Before the program terminates, it executes either the imperative statement named in the
AT END or INVALID KEY phrase, if specified, or the USE AFTER STANDARD EXCEPTION
statement, if specified.
Because the semantics provided by the $FS4XCONTINUE option often conflict with
COBOL85, you can modify the settings of the option (and thus, the semantics of the
compiled code) at any point in the source program listing.
When the $FS4XCONTINUE option is TRUE, error recovery occurs as described in this
section under “How the Recovery Process Occurs.”
Note: For COBOL74 compatibility, the $ANSICLASS option must be reset (FALSE),
which is the default value. For details about this option, refer to Section 15.

3–58

8600 1518–307

Section 4
Data Division
This section illustrates and explains the concepts and syntax of the Data Division, the
third division of a COBOL program. The Data Division describes the data that the object
program is to accept as input, to manipulate, to create, or to produce as output.
Use of the Data Division is optional in a COBOL source program.

Structure of the Data Division
The Data Division consists of the header DATA DIVISION, followed by eight optional
sections:

Section

Function

File Section

This section describes the physical structure of data files
used by the program.

Data-Base Section

Refer to Section 3 of MCP/AS COBOL ANSI-85
Programming Reference Manual, Volume 2: Product
Interfaces.

Working-Storage
Section

This section describes the records and the subordinate
data items that are developed and processed internally in
the program and that have values assigned in the source
program that do not change during execution of the object
program.

Linkage Section

Located in a called program, this section describes the
data in the calling program that is to be referenced by both
programs. The Linkage Section is meaningful only if the
object program functions under the control of a calling
program that contains a CALL statement with a USING
phrase.

Communication Section

Refer to Section 1 of MCP/AS COBOL ANSI-85
Programming Reference Manual, Volume 2: Product
Interfaces.

Local-Storage Section

Located in a calling program, this section describes
parameters in the calling program that are to be
referenced by both the calling and the called programs.

8600 1518–307

4–1

Structure of the Data Division

Section

Function

Report Section

Refer to Section 14.

Program-Library Section

This section defines the interface between a user program
and a library program.

Data entries in a section can take the following forms:

•

File description entries
File description entries represent the highest level of organization in the File Section.
File description entries follow the File Section header. Each entry begins in area A
with a level indicator, followed by a space, followed by a file-name, followed by a set
of file clauses, as required.

•

Record description entries
A record description entry consists of one or more data description entries that
describe one record in the file.

•

Data description entries
Data description entries begin with a level-number, followed by a space, followed by
a data-name (if required), followed by a set of data clauses, as required. The total set
of data description entries associated with a particular record is a record description
entry. The syntax for various data description entries is provided in this section.

Record Concepts
To separate the logical characteristics of data from the physical characteristics of the
data storage media, separate clauses or phrases are used. In a COBOL program, the
input or output statements refer to one logical record of a file, as opposed to a physical
record. A physical record is a physical unit of information whose size and recording mode
is convenient to a particular computer for the storage of data on an input or output
device. The size of a physical record is hardware dependent and does not bear a direct
relationship to the size of the file contained on a device.
A COBOL logical record is a group of related information that is uniquely identifiable and
treated as a unit. A logical record can be contained in a single physical unit; several logical
records can be contained in a single physical unit; or a logical record can be contained in
more than one physical unit.
The concept of a logical record is not restricted to file data but is carried over into the
definition of working-storage. Thus, working-storage is grouped into logical records and
defined by a series of record description entries.

4–2

8600 1518–307

Structure of the Data Division

Level Concepts
The concept of levels is inherent in the structure of a logical record. Levels indicate the
subdivision of a record for the purpose of data reference. Once a subdivision has been
specified, it can be further divided for more detailed data referral.
The most basic subdivisions of a record (that is, those that cannot be further subdivided)
are called elementary items. A record can consist of a sequence of elementary items or
can itself be an elementary item. For reference purposes, the elementary items are
combined into groups. Each group consists of a named sequence of one or more
elementary items. Groups, in turn, can be combined into groups of two or more groups,
and so forth. Thus, an elementary item can belong to more than one group.
A group includes all group and elementary items following it until a level-number less
than or equal to the level-number of that group is encountered. All items that are
immediately subordinate to a given group item must be described by using identical
level-numbers greater than the level-number used to describe that group item.
A true concept of levels does not exist for the following types of entries:

•

Entries that specify elementary items or groups introduced by a RENAMES clause

•

Entries that specify noncontiguous working-storage and linkage data items

•

Entries that specify condition-names

Example
01

PRIMARY.
03 ACCT-NO
PIC 9(8).
03 NAME
PIC X(20).
03 OTHER-NAMES.
05 NME
PIC X(20).
05 FLAG
PIC 9.

This data description entry defines the group item PRIMARY. PRIMARY consists of the
elementary items ACCT-NO and NAME, and the group item OTHER-NAMES. OTHERNAMES consists of the elementary items NME and FLAG.

8600 1518–307

4–3

Structure of the Data Division

Level-Numbers
A system of level-numbers shows the organization of elementary items and group items
(that is, the hierarchy of data in a logical record). Level-numbers identify entries for
working-storage items, linkage items, condition-names, and the RENAMES clause.
A one- or two-digit level-number is required as the first element in each data description
entry. At least one space must follow a level-number. Because records are the most
inclusive data items, level-numbers for records start at 01. Multiple level-01 entries that
are subordinate to any given level indicator represent implicit redefinitions of the same
area. Less inclusive data items are assigned higher (not necessarily successive) levelnumbers not greater in value than 49. Separate entries are written in the source program
for each level-number used. Level-numbers can identify special properties of a data
description entry, as shown next.

Number . . .

Identifies entries that . . .

Describe items through RENAMES clauses for the purpose of
regrouping data items

Specify noncontiguous data items that are not subdivisions of
other items and are not themselves subdivided

Specify condition-names to be associated with particular values of
a conditional variable

The syntax for these types of entries is provided later in this section.
For data description entries that begin with a level-number 01 or 77, the level-number
must begin in area A. Data description entries that begin with other level-numbers can
begin any number of positions to the right of margin A.
Note that the extent of indentation is determined only by the width of the physical
medium. The entries on the output listing need to be indented only if the input is
indented. Indentation does not affect the magnitude of a level-number.

Level Indicators (FD, SD)
A level indicator consists of two alphabetic characters that identify a specific type of file.
The level indicators FD and SD are used in file description entries in the Data Division. FD
identifies the beginning of a file description entry, and SD identifies the beginning of a
sort-merge file description entry. The level indicator must precede the file-name.

4–4

8600 1518–307

Structure of the Data Division

Classes and Categories of Data Items
Every data item is considered to belong to one of five classes: alphabetic, numeric,
alphanumeric, national, or Boolean
Each class is further subdivided into categories:

•

Alphabetic

•

Numeric

•

Alphanumeric

•

National

•

Boolean

•

Alphanumeric-edited

•

National-edited

•

Numeric-edited

The relationship between the class and category of data items is shown in Table 4–1.
Information on how to define the different categories of items is presented under
“PICTURE Clause” in this section.
Table 4–1. Relationship between Class and Category of Data Items

Level of Item

Elementary

Nonelementary (Group)

Class

Category

Alphabetic

Numeric
Alphanumeric

Numeric
Numeric-edited
Alphanumeric-edited
Alphanumeric

National

National
National-edited

Boolean

Alphanumeric

Alphabetic
Numeric
Numeric-edited
Alphanumeric-edited
Alphanumeric
National
National-edited

Note that the class of a group item is treated as alphanumeric at object time regardless
of the class of elementary items subordinate to that group item.

8600 1518–307

4–5

Structure of the Data Division

Class and Category of Figurative Constants and Intrinsic Functions
Following are the class and category for figurative constants and intrinsic functions:

•

When moved to a national or national-edited field, all figurative constants belong to
the national class and category.

•

The figurative constant space, except when moved to a national or national-edited
field, belongs to the alphabetic class and category.

•

The figurative constant ZERO (ZEROS, ZEROES), except when moved to a Boolean,
national, or national-edited category, belongs to the numeric class and category when
moved to a numeric field and the numeric-edited class and the alphanumeric
category when moved to a nonnumeric field.

•

In all other cases, figurative constants belong to the alphanumeric class and
category.

•

Intrinsic functions belong to either the numeric class and category or the
alphanumeric class and category. For details, refer to Section 9.
The PICTURE clause describes the general characteristics and editing requirements
of an elementary data item. When the PICTURE clause of the item contains a picture
character N, the usage is implicitly NATIONAL.
The USAGE clause specifies the manner in which a data item is represented in the
storage of a computer, and can affect the type of character representation of the
item. If the USAGE clause is not specified for an elementary item, or for any group to
which the item belongs, the usage is implicitly DISPLAY. The syntax for these
clauses is provided in this section.

When a computer provides more than one means of representing data, the standard data
format or national standard data format must be used for data items other than integer
and numeric functions, if not otherwise specified by the data description.
Note that an alphanumeric function is always represented in the standard data format.
The size of an elementary data item or a group item is the number of characters in the
standard data format of the item. Synchronization and usage can cause a difference
between this size and that required for internal representation.
The size of a national data item is the number of national characters in the national
standard data format of the item.

4–6

8600 1518–307

Structure of the Data Division

Long Numeric Data Items
Standard numeric data items are limited to 23 digits. To ease the moving of programs
from V Series systems, a longer data item is supported. The “long numeric data item”
consists of 24 to 99,999 digits. It is intended to be used primarily to initialize structures
and arrays that overlay the long numeric data item itself.
The general rules for forming and using long numeric data items are as follows:

•

You can declare a long numeric data item with a usage of DISPLAY or
COMPUTATIONAL. If the usage is COMPUTATIONAL, then the long numeric data
item must contain an even number of digits.

•

A long numeric data item cannot have a usage of BINARY, DOUBLE, or REAL.

•

You must define a long numeric data item as an unsigned integer without editing or
decimal point characters.

•

A long numeric data item cannot appear in a database record.

•

A long numeric data item cannot appear as a file key, sort key, or search key.

•

You cannot explicitly reference long numeric data items in COBOL85 TADS
statements.

For specific details about declaring long numeric data items, refer to “PICTURE Clause”
and “VALUE Clause” later in this section.
You can reference long numeric data items in certain comparison operations. Refer to
“Comparison of Numeric Operands” under “Relation Conditions” in Section 5 for more
information.
You can reference long numeric data items in the following Procedure Division
statements:
CALL
IF
INITIALIZE
INSPECT
MERGE

MOVE
READ
SORT
WRITE

For more specific information, refer to the discussion of each statement in Sections
6 through 8.

8600 1518–307

4–7

Structure of the Data Division

Algebraic Signs
There are two categories of algebraic signs: operational signs and editing signs.
Operational signs are associated with signed numeric data items and signed numeric
literals to indicate their algebraic properties. Editing signs appear on edited reports, for
example, to identify the sign of the item.
The SIGN clause, discussed in this section, allows the programmer to state explicitly the
location of the operational sign.
Editing signs are inserted into a data item through the sign control symbols of the
PICTURE clause, which is also defined under the data description entry formats in this
section.

Standard Alignment Rules
The standard rules for positioning data in an elementary item depend on the category of
the receiving item.

Category of Receiving Item

Numeric

Positioning of Data

The data is aligned by decimal point and is moved to the
receiving digit positions with zero fill or truncation on
either end as required.
If an assumed decimal point is not explicitly specified,
the data item is treated as if it has an assumed decimal
point immediately following its rightmost digit and is
aligned in the same way.

Numeric-edited

The data moved to the edited data item is aligned by
decimal point with zero fill or truncation at either end as
required in the receiving character positions of the data
item, except where editing requirements cause
replacement of the leading zeros.

Alphanumeric (other than a
numeric-edited data item),
alphanumeric-edited, or
alphabetic

The sending data is moved to the receiving character
positions and aligned at the leftmost character position
in the data item with space fill or truncation to the right,
as required.

National or national-edited

The sending data is moved to the receiving character
positions and is aligned at the leftmost character position
in the data item with national space fill or truncation to
the right, as required.

Note that if the JUSTIFIED clause is specified for the receiving item, these standard rules
are modified (refer to “JUSTIFIED Clause” in this section).

4–8

8600 1518–307

Structure of the Data Division

Increasing Object-Code Efficiency
Certain uses of data (for example, in arithmetic operations or in subscripting) can be
made easier if the data is stored so that it is aligned on the natural addressing boundaries
in the computer memory (for example, word boundaries and byte boundaries).
Specifically, additional machine operations in the object program can be required for the
accessing and storage of data if portions of two or more data items appear between
adjacent natural boundaries, or if certain natural boundaries divide a single data item.
Data items that are aligned on these natural boundaries in such a way as to avoid such
additional machine operations are said to be synchronized. With increases in machine
speeds, the measurable effect of SYNCHRONIZE might be recognized only at the level of
millions of calculations. Synchronization can be accomplished in two ways:

•

By using the SYNCHRONIZED clause

•

By recognizing the appropriate natural boundaries and organizing the data suitably
without using the SYNCHRONIZED clause

Uniqueness of Reference
Every user-defined name in a COBOL program is assigned by the programmer to name a
resource that will be used in solving a data processing problem. To use a resource, a
statement in a COBOL program must contain a reference that uniquely identifies that
resource. To ensure that a user-defined name is unique, you can add a subscript, a
qualifier, or a reference modifier. Qualifiers and reference modifiers are discussed in this
section. Subscripts are discussed in Section 5.
When the same name has been assigned in separate programs to two or more
occurrences of a resource of a given type, and when qualification by itself does not allow
the reference in one of those programs to differentiate between the two identically
named resources, then certain conventions that limit the scope of names apply. These
conventions ensure that the resource identified is the one described in the program that
contains the reference (refer to “Scope of Names” in Section 10). When the resource is
an ANSI intrinsic function, the values assigned to the arguments of each function help
differentiate between the two functions.
Unless otherwise specified, subscripts and reference modifiers are evaluated only when
a statement is executed.

8600 1518–307

4–9

Structure of the Data Division

Qualification
Every user-defined name explicitly referred to in a COBOL source program must be
unique in one of the following ways:

•

No other name has the identical spelling and hyphenation.

•

The name is unique within the context of a REDEFINES clause (refer to “REDEFINES
Clause” in this section).

•

The name exists in a hierarchy of names so that reference to the name can be made
unique by mentioning one or more of the higher-level names in the hierarchy.

•

The name is contained in a program that is contained in another program or contains
another program (refer to “Scope of Names” in Section 10).

Higher-level names in a hierarchy of names are called qualifiers, and the process that
specifies uniqueness is called qualification. The formats on the following pages can be
used for qualification.
Identical user-defined names can appear in a source program. However, uniqueness
must then be established through qualification for each user-defined name that is
explicitly referred to (except in the case of redefinition). As long as uniqueness is
established, all available qualifiers do not need to be specified.
Reserved words that name the special registers require qualification to provide
uniqueness of reference whenever a source program would result in more than one
occurrence of any of these special registers. A paragraph-name or section-name in one
program cannot be referred to from any other program.
The same data-name must not be used as the name of an external record and as the
name of any other external data item described in any program that is contained in or
contains the program that describes that external data record. Also, the same data-name
must not be used as the name of an item that possesses the global attribute and as the
name of any other data item described in the program that describes that global data
item.

4–10

8600 1518–307

Structure of the Data Division

Qualification Format 1

ä
Ú
¿
³ ä ä IN å
å
³ ä IN å
³
³ ã ã ïï â data-name-2 â ... ³ ã ïï â file-name-1 ³
ä data-name-1
å ³ æ æ OF ç
ç
³ æ OF ç
³
ã
â ã
ïï
À
ïï
Ù
æ condition-name-1 ç ³
ä IN å
³
ã ïï â file-name-1
æ
æ OF ç
ïï

å
³
³
³
â
³
³
ç

In this format, each qualifier must be the name associated with a level indicator, the
name of a group item to which the item being qualified is subordinate, or the name of the
conditional variable with which the condition-name being qualified is associated.
Qualifiers are specified in the order of successively more inclusive levels in the hierarchy.
data-name-1
data-name-2

A data-name is a user-defined word that names a data item described in a data
description entry. When used in the general formats, data-name represents a word that
must not be reference-modified, subscripted, or qualified unless specifically permitted by
the rules of the format.
In this format, either of these data-names can be a record-name.
condition-name-1

A condition-name is a user-defined word that assigns a name to a subset of values that a
conditional variable can assume; or a user-defined word assigned to a status of a switch
or device. When condition-name is used in the general formats, it represents a unique
data item reference consisting of a syntactically correct combination of a condition-name,
together with qualifiers and subscripts, as required for uniqueness of reference.
file-name-1

A file-name is a user-defined word that names a file connector described in a file
description entry or a sort-merge file description entry in the File Section of the Data
Division.
IN
OF

These keywords are logically equivalent.

8600 1518–307

4–11

Structure of the Data Division

Qualification Format 2

paragraph-name-1

ä IN å
ã ïï â
æ OF ç
ïï

section-name-1

paragraph-name-1

A paragraph-name is a user-defined word that identifies and begins a paragraph in the
Procedure Division.
If explicitly referenced, a paragraph-name must not be duplicated in a section.
When a paragraph-name is qualified by a section-name, the word SECTION must not
appear.
A paragraph-name does not need to be qualified when it is referred to within the same
section.
A paragraph-name in one program cannot be referred to from any other program.
IN
OF

These keywords are logically equivalent.
section-name-1

A section-name is a user-defined word that names a section in the Procedure Division.
A section-name in one program cannot be referred to from any other program.
Qualification Format 3

text-name-1

ä
ã
æ

IN
ïï
OF
ïï

å
â
ç

library-name-1

text-name-1

A text-name is a user-defined word that identifies library text.
If more than one COBOL library is available to the compiler during compilation, textname-1 must be qualified each time it is referred to.

4–12

8600 1518–307

Structure of the Data Division

IN
OF

These keywords are logically equivalent.
library-name-1

A library-name is a user-defined word that names a COBOL library that is to be used by
the compiler for a given source program compilation.
Qualification Format 4

LINAGE-COUNTER
ïïïïïïïïïïïïïï

ä IN å
ã ïï â
æ OF ç
ïï

file-name-2

LINAGE-COUNTER

LINAGE-COUNTER must be qualified each time it is referred to if more than one file
description entry containing a LINAGE clause have been specified in the source program.
IN
OF

These keywords are logically equivalent.
file-name-2

A file-name is a user-defined word that names a file connector described in a file
description entry or a sort-merge file description entry in the File Section of the Data
Division.
Details
For each nonunique user-defined name that is explicitly referred to, uniqueness must be
established through a sequence of qualifiers that precludes any ambiguity of reference.
A name can be qualified even though it does not need qualification; if there is more than
one combination of qualifiers that ensures uniqueness, then any such set can be used.

8600 1518–307

4–13

Structure of the Data Division

Reference Modifiers
A reference modifier identifies a function or a data item by specifying a leftmost
character and a length for the function or data item. Unless otherwise specified, a
reference modifier is allowed only when the function-name or data-name references an
alphanumeric function or data item.

ädata-name-1
å
ã
â
æFUNCTION funct-name-1 [({argument-1}...)]ç
ïïïïïïïï
(leftmost-char-position:[length])
Note: The reference modifier consists only of the leftmost-character-position and the
length. The other elements in the preceding syntax are provided only for context.
data-name-1

This data-name must refer to a data item whose usage is DISPLAY or NATIONAL. It can
be qualified or subscripted.
FUNCTION function-name-1 (argument-1)

This is an alphanumeric function. For information about functions, refer to Section 9.
leftmost-character-position

This must be an arithmetic expression. For details about arithmetic expressions, refer to
Section 5.
Evaluation of the leftmost-character-position specifies the ordinal position of the leftmost
character of the unique data item in relation to the leftmost character of the data item or
function specified in this format.
Evaluation of the leftmost-character-position must result in a positive nonzero integer
less than or equal to the number of characters in the data item or function specified in
this format.

4–14

8600 1518–307

Structure of the Data Division

length

This must be an arithmetic expression. For details, see Section 5.
The evaluation of the length specifies the size of the data item to be used in the
operation.
The evaluation of the length must result in a positive nonzero integer.
The sum of the leftmost-character-position and the length minus the value 1 must be
less than or equal to the number of characters in the data item or function specified in
this format.
If the length is not specified, the unique data item extends from and includes the
character identified by the leftmost-character-position up to and including the rightmost
character of the data item or function specified in this format.
Details
Reference modification creates a unique data item that is a subset of the data item or
function specified in this format. The syntax descriptions for the leftmost-characterposition and the length contain the definitions of the unique data item.
The unique data item is considered an elementary data item without the JUSTIFIED
clause. If a function is specified, the data item has the class and category of
alphanumeric. When a data item is specified, the unique data item has the same class
and category as defined for the data item referred to by data-name-1, with the
exceptions shown in the following table.

The category . . .

Is considered to be class and category . . .

Numeric

Alphanumeric

Numeric-edited

Alphanumeric

Alphanumeric-edited

Alphanumeric

National-edited

National

Each character of a data item or a function specified in this format is assigned an ordinal
number that is incremented by one from the leftmost position to the rightmost position.
The leftmost position is assigned the ordinal number one. Note that if the data
description entry for data-name-1 contains a SIGN IS SEPARATE clause, the sign position
is assigned an ordinal number within that data item.

8600 1518–307

4–15

Structure of the Data Division

The type of data item specified by data-name-1 determines how that data item is treated
for purposes of reference modification:

If the data item specified by
data-name-1 is described as . . .

Then it is treated in reference modification
as if it were redefined as . . .

Numeric, numeric-edited,
alphabetic, or alphanumeric-edited

An alphanumeric data item of the same size as
the data item referred to by data-name-1

National-edited

A national data item of the same size as the
data item referred to by data-name-1

Reference modification for an operand is evaluated as follows:

•

If subscripting is specified for the operand, the reference modification is evaluated
immediately after evaluation of the subscripts.

•

If subscripting is not specified for the operand, the reference modification is
evaluated at the time subscripting would be evaluated if subscripts had been
specified.

•

If the subscript ALL is specified for an operand, the reference modifier is applied to
each of the implicitly specified elements of the table.

If a reference modifier is specified in a function reference, the reference modifier is
evaluated immediately after the function is evaluated.

4–16

8600 1518–307

General Format

General Format
The general format of the Data Division is as follows:

DATA DIVISION.
ïïïï ïïïïïïïï
[ FILE SECTION.
ïïïï ïïïïïïï
[ file description entry
{ record description entry } ... ] ...
[ sort-merge file description entry
{ record description entry }... ] ... ]
[ DATA-BASE SECTION.
ïïïïïïïïï ïïïïïïï
[ 01 [ internal-set name ]

INVOKE set-name ]

[ WORKING-STORAGE SECTION.
ïïïïïïïïïïïïïïï ïïïïïïï
[ 77-level description entry ]
record description entry
[ LINKAGE SECTION.
ïïïïïïï ïïïïïïï
[ 77-level description entry ]
record description entry
[ COMMUNICATION SECTION.
ïïïïïïïïïïïïï ïïïïïïï
[ COMS headers ] ...

...

]

... ]

]

[ LOCAL-STORAGE SECTION.
ïïïïïïïïïïïïï ïïïïïïï
local-storage description entry
ä 77-level description entry å
ã
â ... ]
æ record description entry
ç
[ REPORT SECTION.
ïïïïïï ïïïïïïï
[ A report description entry ... ] ...
[ A report-group description entry ... ] ... ]
[ PROGRAM-LIBRARY SECTION.
ïïïïïïïïïïïïïïï ïïïïïïï
[ library description entry ] ...

]

Because the record description entry is used in each of the sections of the Data Division,
it is described in the following subsection rather than as an element of each section.
For information on the Data-Base Section and the Communication Section, refer to
COBOL ANSI-85 Programming Reference Manual, Volume 2: Product Interfaces.

8600 1518–307

4–17

Record Description Entry

Record Description Entry
A record description consists of a set of data description entries that describe the
characteristics of a particular record. Because a record description can have a hierarchical
structure, the clauses used with an entry can vary considerably, depending on whether it
is followed by subordinate entries.
One or more record description entries must follow the file description entry.

Format

Use

Format 1

This format identifies noncontiguous working-storage data items and
noncontiguous linkage data items.

Format 2

This format renames a data-name or range of data-names.

Format 3

This format defines condition-names associated with conditional variables.

Format 4

This format is used for interprogram communication. It determines whether
the data record and its subordinate data items have local names or global
names, and it determines the internal or external attribute of the data record
and its subordinate data items.

The syntax of each data description entry is illustrated and explained on the following
pages.

4–18

8600 1518–307

Data Description Entry Format 1

Data Description Entry Format 1
The format for Data Description Entry Format 1 is shown on the following three pages. A
user will use this syntax for most data items.

ä data-name-1 å
Ú
level-number ã
â [ REDEFINES data-name-2 ] ³
æ FILLER
ç
ïïïïïïïïï
³
³
À
Ú
¿
Ú
¿ ³ COMMON ³
³ ä PICTURE å
³ ³ ïïïïïï ³
³ ã ïïïïïïï â IS character-string ³ ³ OWN
³
³ æ PIC
ç
³ ³ ïïï
³
À
ïïï
Ù ³ LOCAL ³
À ïïïïï Ù

Ú
³
³
³
³
³
³
³
³
³
³
³
³
³
À

8600 1518–307

ä
³SHORT-DATE
³ïïïïïïïïïï
³LONG-DATE
³ïïïïïïïïï
TYPE IS ãNUMERIC-DATE
ïïïï
³ïïïïïïïïïïïï
³NUMERIC-TIME
³ïïïïïïïïïïïï
³LONG-TIME
æïïïïïïïïï

å
³
³
³
³
â
³
³
³
³
ç

Ú
³
³
³
³
³
³USING
³ïïïïï
³
³
³
³
À

INTEGER
ïïïïïïï
STRING
ïïïïïï

¿
³
³
³
Ù

ä
³
ä
å
³
³literal-1 ³
³CONVENTION OF ã
â
³ïïïïïïïïïï
³data-name-3³
ã
æ
ç
³
ä
å
³
³literal-2 ³
³LANGUAGE OF ã
â
³ïïïïïïïï
³data-name-4³
æ
æ
ç

å
³
³
³
³
â
³
³
³
³
ç

¿
³
³
³
³
³
³
³
³
³
³
³
Ù

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
Ù

4–19

Data Description Entry Format 1

Ú
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
À

4–20

[ USAGE IS ]

ä
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
æ

BINARY
ïïïïïï

Ú
³
³
³
À

¿
TRUNCATED ³
ïïïïïïïïï ³
EXTENDED ³
ïïïïïïïï Ù

BIT
ïïï
COMPUTATIONAL
ïïïïïïïïïïïïï
COMP
ïïïï
COMPUTATIONAL-5
ïïïïïïïïïïïïïïï
COMP-5
ïïïïïï
CONTROL-POINT
ïïïïïïïïïïïïï
DISPLAY
ïïïïïïï
DOUBLE
ïïïïïï
EVENT
ïïïïï
INDEX
ïïïïï
KANJI
ïïïïï
LOCK
ïïïï
NATIONAL
ïïïïïïïï
PACKED-DECIMAL
ïïïïïïïïïïïïïï
REAL
ïïïï
TASK
ïïïï

å
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
ç

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
Ù

Ú
³
ä CONTENT
³
³ ïïïïïïï
³ RECEIVED BY ã REFERENCE
³
³ ïïïïïïïïï
³
æ REF
À
ïïï

å
³
â
³
ç

¿
³
³
³
³
³
Ù

8600 1518–307

Data Description Entry Format 1

Ú
ä
å
¿
³[ SIGN IS ] ³ LEADING ³ [ SEPARATE CHARACTER ] ³
³ ïïïï
ã ïïïïïïï â
ïïïïïïïï
³
³
³ TRAILING ³
³
À
æ ïïïïïïïï ç
Ù
Ú
¿
³
³
³OCCURS integer-2 TIMES
³
³ïïïïïï
³
³
Ú
¿
³
³
³ ä
å
³
³
³
³ ³ ASCENDING ³ KEY IS {data-name-3} ... ³...
³
³
³ ã ïïïïïïïïï â
³
³
³
³ ³ DESCENDING ³
³
³
³
³ æ ïïïïïïïïïï ç
³
³
³
À
Ù
³
³
INDEXED BY [ LOCAL ] { index-name-1 } ... ]
³
³
ïïïïïïï
³
³OCCURS integer-1 TO integer-2 TIMES DEPENDING ON data-name-4 ³
³ïïïïïï
ïï
ïïïïïïïïï
³
³
Ú
¿
³
³
³ ä
å
³
³
³
³ ³ ASCENDING ³ KEY IS {data-name-3}... ³ ...
³
³
³ ã ïïïïïïïïï â
³
³
³
³ ³ DESCENDING ³
³
³
³
³ æ ïïïïïïïïïï ç
³
³
³
À
Ù
³
³
[ INDEXED BY [ LOCAL ] {index-name-1 } ... ]
³
³
ïïïïïïï
³
À
Ù
Ú
³
³ä
å Ú
¿ ¿
Ú ä
å
¿
³³ SYNCHRONIZED ³ ³ LEFT ³ ³
³ ³ JUSTIFIED ³ RIGHT
³
³ã ïïïïïïïïïïïï â ³ ïïïï ³ ³
³ ã ïïïïïïïïï â
³
³³ SYNC
³ ³ RIGHT ³ ³
³ ³ JUST
³
³
³æ ïïïï
ç À ïïïïï Ù Ù
À æ ïïïï
ç
Ù
³
À
[ BLANK WHEN ZERO ]
[ VALUE IS literal-1 ] [ WITH LOWER BOUNDS ]
ïïïïï
ïïïï
ïïïïï
ïïïïï ïïïïïï
[ALIGNED]
ïïïïïïï

8600 1518–307

[

RECORD AREA
ïïïïïï ïïïï

] .

4–21

Data Description Entry Format 1

The level-number, the data-name, and the REDEFINES clause must appear in the order in
which they are described in the syntax diagram. All other clauses of Format 1 can appear
in any order.
The first three clauses of this data description entry are described in order on the
following pages. The remaining clauses are described in alphabetical order.
level-number

In this format, this number can be one of the following:

•

Any number from 01 through 49

•

Level-number 77 identifies noncontiguous working-storage data items and
noncontiguous linkage data items. Level-number 77 is used only in this format of a data
description entry.

Data-Name or FILLER Clause
data-name-1

This name is a user-defined word that specifies the name of the data item being
described.
FILLER

This keyword can be used to name an elementary item in a record.
A FILLER item can never be referred to explicitly. However, the keyword FILLER can be
used to name a conditional variable because such use does not require explicit reference
to the FILLER item itself, but only to the value of the FILLER item.
Example
03 FILLER PIC 9.
88 ANNUAL VALUE 1.
88 WEEKLY VALUE 2.
88 DAILY VALUE 3.
Details
If this clause is omitted, the data item being described is treated as though FILLER had
been specified.

4–22

8600 1518–307

Data Description Entry Format 1

REDEFINES Clause
This clause allows the same computer storage area to be described by different data
description entries.
When specified, this clause must immediately follow the data-name-1 or FILLER clause if
either is specified; otherwise, it must immediately follow the level-number. The
remaining clauses can be written in any order.
Note that this clause must not be used in level 01 entries in the File Section.
data-name-2

The level-numbers of data-name-2 and the subject of this entry (the data-name-1 or
FILLER clause) must be identical, but must not be 66 or 88.
The data description entry for data-name-2 cannot contain an OCCURS clause; however,
data-name-2 can be subordinate to an item whose data description entry contains an
OCCURS clause. In this case, the reference to data-name-2 in the REDEFINES clause
must not be subscripted. Neither the original definition nor the redefinition can include a
variable-occurrence data item.
If the data item referred to by data-name-2 is declared to be an external data record or is
specified with a level-number other than 01, the number of character positions it contains
must be greater than or equal to the number of character positions in the data item
referred to by the subject of this entry (the data-name-1 or FILLER clause). If the dataname referred to by data-name-2 is specified with a level-number of 01 and is not
declared to be an external data record, there is no such constraint.
Data-name-2 must not be qualified, even if it is not unique. (No ambiguity of reference
exists in this case because of the required placement of the REDEFINES clause in the
source program.)
Rules
Multiple redefinitions of the same character positions are permitted. These redefinitions
must all use the data-name of the entry that originally defined the area.
The entries that give the new description of the character positions must not contain a
VALUE clause, except in condition-name entries.
No entry having a level-number numerically lower than the level-number of data-name-2
and the subject of this entry (data-name-1 or FILLER) can occur between the data
description entries of data-name-2 and the subject of this entry (data-name-1 or FILLER).
The entries that give the new descriptions of the character positions must follow the
entries defining the area of data-name-2, without intervening entries that define new
character positions.

8600 1518–307

4–23

Data Description Entry Format 1

Details
Data-name-2 can be subordinate to an entry that contains a REDEFINES clause.
Storage allocation starts at data-name-2 and continues over a storage area sufficient to
contain the number of character positions in the data item referred to by the data-name-1
or FILLER clause.
When the same character position is defined by more than one data description entry,
the data-name associated with any of those data description entries can be used to refer
to that character position.

ALIGNED Clause
This clause can be specified only for an elementary bit data item. The ALIGNED clause
specifies that an elementary bit data item be aligned at the leftmost bit of the next
character boundary in storage. The ALIGNED clause and the SYNCHRONIZED clause are
mutually exclusive.

BLANK WHEN ZERO Clause
This clause fills a data item with spaces when the value of the data item is zero.
This clause can be specified only for an elementary item whose PICTURE is specified as
numeric or numeric-edited (refer to “PICTURE Clause” in this section).
The numeric or numeric-edited data description entry to which this clause applies must
be described, either implicitly or explicitly, as USAGE IS DISPLAY.
When this clause is used for an item whose PICTURE is numeric, the category of the
item is considered to be numeric-edited.
Example
01

PRODUCT.
05 PART-NO
05 QUANTITY
05 UNIT-PRICE
05 TOTAL-PRICE

PIC
PIC
PIC
PIC

IS 99999.
S9999
SIGN IS LEADING SEPARATE.
IS 999V99.
9(5)V99 BLANK WHEN ZERO.

In this example, the data item TOTAL-PRICE is set to blank spaces when its value is
zero.

4–24

8600 1518–307

Data Description Entry Format 1

COMMON Clause
COBOL procedures compiled at lexicographic level 3 or higher can use untyped
procedures, files, and certain variables in the outer block of the host program when those
procedures, files, and variables are declared as COMMON.
Any 77-level item or 01-level item declared in the Working-Storage Section of a host
program can be passed as a parameter. You can declare such a data item as COMMON
in a bound procedure by using the COMMON clause in the data description entry for the
item.
COMMON declarations are matched by name and type to the global directory of the
host.
Using the COMMON clause in the host program is redundant, because each data item
declared in a host program is placed in the global directory of the host. However, no error
or warning message is issued if the COMMON clause is declared in the host program.
Index-names generated for a COMMON array are COMMON items themselves.
If you must declare most or all of the variables in the Working-Storage Section as
COMMON, you can set the COMMON compiler option to TRUE. This option affects only
variables in the Working-Storage Section that can be declared COMMON. For more
information about compiler options, refer to Section 15. You can use the LOCAL or OWN
clause to override the COMMON compiler option.
If the data item you are declaring as COMMON has an OCCURS clause, you can specify
the index-name as LOCAL by using the INDEXED BY LOCAL clause within the OCCURS
clause.
Examples
77
77
01

8600 1518–307

GLASTATUS COMMON COMP PIC 9(11).
GL-RCD COMMON.
GL-EBCARY COMMON.
03 CMP-ITM COMP PIC 9(11) OCCURS 100 INDEXED BY I.

4–25

Data Description Entry Format 1

INTEGER and STRING Clauses
These clauses identify the type of the data item used as a library parameter. INTEGER
will identify the data type as an integer, and STRING will identify the data type as a string.
To use the INTEGER clause, the level-number of the data item must be either 01 or 77,
and the USAGE of the data item must be COMPUTATIONAL.
To use the STRING clause, the level-number of the data item must be either 01 or 77,
and the USAGE of the data item must be DISPLAY or NATIONAL.
Note: The INTEGER clause and the STRING clause are ignored for data items not
referenced as formal parameters.

JUSTIFIED (JUST) Clause
This clause permits alternate (nonstandard) positioning of data in a receiving data item.
“JUST” and “JUSTIFIED” are equivalent words.
Rules

•

This clause can be specified only at the elementary item level.

•

This clause cannot be specified for any data item described as numeric or for which
editing is specified.

•

This clause must not be specified for an index data item.

Details
When the receiving data item is described with the JUSTIFIED clause and the sending
data item is larger than the receiving data item, the leftmost characters are truncated.
When the receiving data item is described with the JUSTIFIED clause and it is larger than
the sending data item, the data is aligned at the rightmost character position in the data
item with space fill for the leftmost character positions.
When the JUSTIFIED clause is omitted, the standard rules for aligning data in an
elementary item apply (refer to “Standard Alignment Rules” earlier in this section).

LOCAL Clause
A local variable is a variable that is referenced in the same procedure in which it is
declared. Any value stored in a local variable is lost upon exit from that procedure.
For COBOL procedures compiled at level 3 or higher, the variables are declared implicitly
LOCAL unless the COMMON or OWN clause is specified.
Index-names for a LOCAL array are treated as LOCAL variables.

4–26

8600 1518–307

Data Description Entry Format 1

LOWER-BOUNDS Clause
The LOWER-BOUNDS clause enables COBOL85 programs to handle array parameters
that generate a stack item to pass the lower bound of the array.
This clause is used in the data description of a 01 item in the Linkage Section or WorkingStorage Section (if LOWER-BOUNDS are received), or the Local-Storage Section (if
LOWER-BOUNDS are to be passed).
This clause declares formal parameters to be compatible with FORTRAN and ALGOL.
It must be used when communicating with ALGOL programs with formal array
parameters declared with a variable lower-bound description (for example,
ARRAYNAME [*] ).
The actual lower bound passed by a COBOL program as a parameter to another program
will always have a value of zero. The actual lower bound received by a COBOL program
as a parameter will not be used in addressing the array. Therefore, the LOWER-BOUNDS
clause affects bound and library procedures. ALGOL programs that call a library passing
an array parameter with a lower-bound [*] send two parameters: a by-reference array
followed by a by-value integer. Thus, the COBOL85 library must declare a data
description with LOWER-BOUNDS to receive the lower-bound parameter.
Note: This clause is ignored for data items not referenced as formal parameters.
Examples
COBOL Parameter

Corresponding ALGOL Parameter

01 BINARY

REAL array [ ]

01 BINARY WITH LOWER-BOUNDS

REAL array [*]

01 COMP

HEX array[]

01 COMP WITH LOWER-BOUNDS

HEX array[*]

01 DISPLAY

EBCDIC char array[]

01 DISPLAY WITH LOWER-BOUNDS

EBCDIC char array[*]

The use of in the preceding examples refers to a specified lower bound
associated with the array.

8600 1518–307

4–27

Data Description Entry Format 1

OCCURS Clause
This clause eliminates the need for separate entries for repeated data items and supplies
information required for the application of subscripts or indexes.
This clause must not be specified in a data description entry that has either:

•

A level-number of 01, 66, 77, or 88

•

A variable-occurrence data item subordinate to the entry

Except for the OCCURS clause, all data description clauses associated with an item
whose description includes an OCCURS clause apply to each occurrence of the item
described.
OCCURS integer-2 TIMES

This form of the OCCURS clause specifies that the subject of this entry (the data-name-1
or FILLER clause) occurs the number of times indicated by the integer in this clause.
integer-2

The value of this integer represents the exact number of occurrences of the subject of
this entry (the data-name-1 or FILLER clause).
OCCURS integer-1 TO integer-2 TIMES

This form of the OCCURS clause specifies that the subject of this entry (the data-name-1
or FILLER clause) has a variable number of occurrences. (Note that the length of the
subject of this entry is not variable, just the number of occurrences.)
A data description entry that contains this form of the OCCURS clause can only be
followed, within that record description, by data description entries that are subordinate
to it.
If this form of the OCCURS clause is specified in a record description entry and the
associated file description entry or sort-merge description entry contains the VARYING
phrase of the RECORD clause, the records are variable length. If the DEPENDING ON
phrase of the RECORD clause is not specified, the content of the data item referred to
by data-name-4 of the OCCURS clause must be set to the number of occurrences to be
written before the execution of any RELEASE, REWRITE, or WRITE statement.
integer-1

The value of this integer represents the minimum number of occurrences of the subject
of this entry (the data-name-1 or FILLER clause).
When both integer-1 and integer-2 are used, integer-1 must be greater than or equal to
zero, and integer-2 must be greater than integer-1.

4–28

8600 1518–307

Data Description Entry Format 1

integer-2

The value of this integer represents the maximum number of occurrences of the subject
of this entry (the data-name-1 or FILLER clause).
DEPENDING ON data-name-4

Data-name-4 can be qualified.
Data-name-4 must describe an integer.
The data item defined by data-name-4 must not occupy a character position in the range
between the first character position defined by the data description entry containing the
OCCURS clause and the last character position defined by the record description entry
containing that OCCURS clause.
If the OCCURS clause is specified in a data description entry that is included in a record
description entry containing the EXTERNAL clause, data-name-4, if specified, must
reference a data item that possesses the external attribute that is described in the same
Data Division.
If the OCCURS clause is specified in a data description entry subordinate to one
containing the GLOBAL clause, data-name-4, if specified, must be a global name and
must reference a data item that is described in the same Data Division.
The data item identified by data-name-4 must not contain an OCCURS clause except
when data-name-4 is the subject of this entry.
The current value of the data item referred to by data-name-4 represents the number of
occurrences of the subject of this entry.
At the time the subject of this entry is referred to or any data item subordinate or
superordinate to the subject of this entry is referred to, the value of the data item
referred to by data-name-4 must fall in the range of integer-1 through integer-2. The
contents of the data items whose occurrence numbers exceed the value of the data item
referred to by data-name-4 are undefined.
When a group item is referred to that has subordinate to it an entry that contains this
form of the OCCURS clause, the part of the table area used in the operation is
determined as follows:

•

If the data item referred to by data-name-4 is outside the group, only that part of the
table area that is specified by the value of the data item referred to by data-name-4 at
the start of the operation will be used.

•

If the data item referred to by data-name-4 is included in the same group and the
group data item is referred to as a sending item, only that part of the table area that
is specified by the value of the data item referred to by data-name-4 at the start of
the operation will be used in the operation. If the group is a receiving item, the
maximum length of the group will be used.

8600 1518–307

4–29

Data Description Entry Format 1

ASCENDING/DESCENDING data-name-3

No entry that contains an OCCURS clause can appear between the descriptions of the
data items identified by the data-names in the KEY IS phrase and the subject of this
entry.
When the KEY IS phrase is specified, the repeated data must be arranged in ascending
or descending order according to the values contained in data-name-3. The ascending or
descending order is determined according to the rules for the comparison of operands
(see “Conditional Expressions” in Section 5). The data-names are listed in their
descending order of significance.
Data-name-3 can be qualified. The first specification of data-name-3 must be the name of
either the entry containing the OCCURS clause or an entry subordinate to the entry
containing the OCCURS clause. Subsequent specification of data-name-3 must be
subordinate to the entry containing the OCCURS clause.
Data-name-3 must be specified without the subscripting normally required.
INDEXED BY

This phrase is required if the subject of this entry, or an entry subordinate to this entry, is
to be referred to by indexing. The index-name identified by this phrase is not defined
elsewhere, since its allocation and format are dependent on the hardware and, not being
data, cannot be associated with a data hierarchy.
LOCAL

This option designates the specified index-name as a LOCAL item along with the other
LOCAL host and subprogram items. LOCAL indicates that the item is declared in the
procedure that references it. If multiple index-names are specified in an INDEXED BY
clause, the LOCAL clause applies to each index-name.
If the COMMON or OWN clause is specified for a data item, you can specify the indexname as LOCAL by using the INDEX BY LOCAL clause within the OCCURS clause.
index-name-1

This name must be a unique word in the program.
Example
01

4–30

PRIMARY.
03 ACCT-NO
PIC 9(8).
03 NAME
PIC X(20).
03 OTHER-NAMES OCCURS 1 TO 5 TIMES
DEPENDING ON ALTERNATE-NAMES.
05 NME
PIC X(20).
05 FLAG
PIC 9.

8600 1518–307

Data Description Entry Format 1

OWN Clause
COBOL procedures compiled at level 3 or higher can declare certain variables to be
OWN. These variables retain their values through repeated exit and reentry of the
procedure in which they are declared. You can declare any item in the Working-Storage
Section as OWN by using the OWN clause or by setting the OWN compiler control
option.
All related index-names for OWN items are also OWN; redefinitions of OWN items are
implicitly OWN and do not require the OWN clause. If most or all of the variables
declared in the Working-Storage Section must be declared OWN, then you can set the
OWN compiler control option to TRUE throughout the compilation. To override the OWN
compiler control option, use the LOCAL or COMMON clause.
Index-names for an OWN array are treated as OWN variables.
If the data item you are declaring as OWN has an OCCURS clause, you can specify the
index-name as LOCAL by using the INDEXED BY LOCAL clause within the OCCURS
clause.
Example
77 X
PIC X(10) OWN.
77 Y
REDEFINES X PIC 9(10).
01 A OWN.
03 CMP-ITEM
COMP PIC 9 (11) OCCURS 100 INDEXED BY J.

8600 1518–307

4–31

Data Description Entry Format 1

PICTURE Clause
This clause describes the general characteristics and editing requirements of an
elementary data item.
PICTURE
PIC

These keywords are equivalent.
IS character-string

A character-string consists of certain allowable combinations of characters in the COBOL
character set used as symbols. The allowable combinations determine the category of
the elementary item.
The allowable PICTURE clause symbols are A, B, I, N, P, S, V, X, Z, 0, 1, 9, slant (/),
comma (,), period (.), plus sign (+), minus sign (-), asterisk (*), currency symbol (usually $),
CR, and DB. Refer to the paragraphs under the heading “Symbols” in this section for
information on each of these symbols.
The lowercase letters that correspond to the uppercase letters that represent the
PICTURE clause symbols A, B, I, N, P, S, V, X, Z, CR, and DB are the same as their
uppercase representations in a PICTURE character-string. However, all other lowercase
letters are not equivalent to their corresponding uppercase representations.
The maximum number of characters allowed in the character-string is 30.

Restrictions
The PICTURE clause has the following restrictions:

4–32

•

A PICTURE clause can be specified only at the elementary item level.

•

A group item must not have a PICTURE clause.

•

Every elementary data item except an index data item or the subject of a RENAMES
clause must have a PICTURE clause. The PICTURE clause is prohibited for an index
data item and the subject of a RENAMES clause.

•

The asterisk, when used as the zero suppression symbol, and the BLANK WHEN
ZERO clause cannot appear in the same entry.

8600 1518–307

Data Description Entry Format 1

Symbols
The PICTURE clause symbols and their functions are described in Table 4–2.
Table 4–2. Picture Clause Symbols

Symbol

Function

Each A in the character-string represents a character position that
can contain only an alphabetic character. This symbol is counted in
the size of the item.

Each B in the character-string represents a character position into
which the space character will be inserted and is counted in the size
of the item.
For an alphanumeric-edited item, each B represents an alphanumeric
character position in the item into which an alphanumeric space
character will be inserted.
For a national-edited item, each B represents a national character
position in the item into which a national space character is to be
inserted.

Each I in the character string indicates that the nonblank character
immediately following it is treated as a simple insertion character.
Specifying the character I as the currency symbol overrides its use
to indicate simple insertion characters. The I itself is not counted in
the size of the item, but the single, nonblank character following it is
counted in the size of the item. The 30-character limit for the size of
a PICTURE string includes both the I symbol and the character that
follows it.

Each N in the character-string represents a character position that
contains a national character. Each N is counted in the size of the
data item being described. The size is considered to be the total
number of character positions defined for the data item.

8600 1518–307

4–33

Data Description Entry Format 1

Table 4–2. Picture Clause Symbols

Symbol

Function

Each P in the character-string indicates an assumed decimal scaling
position, which is used to specify the location of an assumed
decimal point when the point is not in the number that appears in
the data item. The scaling position character P is not counted in the
size of the data item. Scaling position characters are counted in
determining the maximum number of digit positions (23) in numericedited items or numeric items. The scaling position character P can
appear only as a continuous string of Ps in the leftmost or rightmost
digit positions in a PICTURE character-string, because the scaling
positions character P implies an assumed decimal point (to the left
of Ps if Ps are leftmost PICTURE symbols and to the right if Ps are
either the leftmost or rightmost character in such a PICTURE
description).
The symbol P and the insertion symbol period (.) cannot both occur
in the same PICTURE character-string. The symbol P and the symbol
V cannot both occur in the same PICTURE character-string (unless
they are immediately adjacent, indicating the same character
position).
In certain operations that refer to a data item whose PICTURE
character-string contains the symbol P, the algebraic value of the
data item is used rather than the actual character representation of
the data item. This algebraic value assumes the decimal point in the
prescribed location and zero in place of the digit position specified by
the symbol P. The size of the value is the number of digit positions
represented by the PICTURE character-string. These operations can
be:

•
•

Any operation that requires a numeric sending operand

•

A MOVE statement in which the sending operand is numericedited and its PICTURE character-string contains the symbol P
and the receiving operand is numeric or numeric-edited

•

A comparison operation in which both operands are numeric

A MOVE statement in which the sending operand is numeric
and its PICTURE character-string contains the symbol P

In all other operations the digit positions specified with the symbol P
are ignored and not counted in the size of the operand.

4–34

8600 1518–307

Data Description Entry Format 1

Table 4–2. Picture Clause Symbols

Symbol

Function

The letter S is used in a character string to indicate the presence of
an operational sign in the internal representation of a numeric data
item. A single S must be the first (leftmost) character in the
character string and there cannot be more than one S character in a
PICTURE clause character-string.
The symbol S can be used in the PICTURE character string of any
data item with the USAGE clause equal to DISPLAY,
COMPUTATIONAL, or BINARY. The SIGN clause can be used to
specify the exact representation and position of the operational sign.
When an operational sign is specified for a DISPLAY data item and a
SIGN clause is not specified, the sign is maintained and expected in
the zone of the least significant (rightmost) character. When the data
item is in the receiving field in an arithmetic statement and when the
native character set is EBCDIC, the four zone bits are set to binary
1101 for negative values and to binary 1100 or 1111 for positive
values.
When the data item is used in an algebraic comparison or operation
to supply an algebraic value, specification of the least significant
zone as binary 1101 causes the value to be considered negative.
Only the zone values 1100, 1101, and 1111 qualify the data item as
NUMERIC if it is tested by the numeric class condition. For DISPLAY
data items, the presence or absence of an operational sign has no
effect on the amount of storage required to contain the data item,
unless the SIGN SEPARATE clause is specified.
When an operational sign is specified for a COMPUTATIONAL data
item and a SIGN clause is not specified, the sign is maintained and
expected as a leading, separate 4-bit character to the left of the most
significant digit position.
When the native character set is EBCDIC, the binary pattern of the
sign character is 1101 for negative values and 1100 for positive
values. Like DISPLAY data items, only these values allow the item to
be considered NUMERIC in the class condition test. Unlike DISPLAY
data items, the specification of an operational sign for
COMPUTATIONAL data items increases by one the number of 4-bit
character positions occupied by the data item in storage.

The V is used in a character-string to indicate the location of the
assumed decimal point and can appear only once in a characterstring. The V does not represent a character position and is not
counted in the size of the elementary item.
The V is redundant if the assumed decimal point is to the right of the
rightmost symbol in the string that represents a digit position or
scaling position.

8600 1518–307

Each X in the character-string represents a character position that
contains any allowable character from the computer's character set.
The X is counted in the size of the item.

4–35

Data Description Entry Format 1

Table 4–2. Picture Clause Symbols

Symbol

Function

Each Z in a character-string can be used to represent only the
leftmost leading numeric character positions that will be replaced by
a space character when the content of that character position is a
leading zero. Each Z is counted in the size of the item.

Each 0 (zero) in the character-string represents a character position
into which the character 0 is to be inserted. The 0 is counted in the
size of the item.
For an alphanumeric-edited item, each 0 represents an alphanumeric
character position into which the alphanumeric character 0 is to be
inserted.
For a national-edited item, each 0 represents a national character
position into which the national character 0 is to be inserted.

The 1 in a PICTURE character-string represents a Boolean position
that contains a Boolean character and can occur only once in a
character-string. The 1 is counted in the size of the item.

Each 9 in the character-string represents a digit position that
contains a numeric character. The 9 is counted in the size of the
item.

Each slant (/) in the character-string represents a character position
into which the slant character is to be inserted. The slant is counted
in the size of the item.
For an alphanumeric-edited item, each slant represents an
alphanumeric character position into which an alphanumeric
character slant is to be inserted.
For a national-edited item, each slant represents a national character
position into which a national character slant is to be inserted.

Each comma (,) in the character-string represents a character
position into which the comma will be inserted. The comma is
counted in the size of the item.

The period (.) in the character-string is an editing symbol that
represents the decimal point for alignment purposes, and in addition,
represents a character position into which the period will be
inserted. The period is counted in the size of the item.
For a given program, the functions of the period and comma are
exchanged if the clause DECIMAL-POINT IS COMMA is stated in the
SPECIAL-NAMES paragraph. In this exchange, the rules for the
period apply to the comma, and the rules for the comma apply to the
period wherever they appear in a PICTURE clause.

+
CR
DB

4–36

These symbols are editing sign control symbols. When used, they
represent the character position into which an editing sign control
symbol will be placed. The symbols are mutually exclusive in any
one character-string. Each character used in the symbol is counted in
determining the size of the data item.

8600 1518–307

Data Description Entry Format 1

Table 4–2. Picture Clause Symbols

Symbol

Function

Each asterisk (*) in the character-string represents a leading numeric
character position into which an asterisk will be placed when the
content of that position is a leading zero. Each * is counted in the
size of the item.

The currency symbol in the character-string represents a character
position into which a currency symbol will be placed. The currency
symbol in a character-string is represented by either the currency
sign ($) or by the single character specified in the CURRENCY SIGN
clause in the SPECIAL-NAMES paragraph. The currency symbol is
counted in the size of the item.

8600 1518–307

4–37

Data Description Entry Format 1

Categories of Items
The PICTURE clause can describe the following categories of data items:

•

Alphabetic

•

Numeric

•

Alphanumeric

•

National

•

Boolean

•

Alphanumeric-edited

•

National-edited

•

Numeric-edited

Table 4–3 contains information on how to define the different categories of items.
Table 4–3. Specification of Data Item Categories in the PICTURE
Clause

Item

Alphabetic

Definition

The PICTURE character-string for an alphabetic item can contain only
the symbol A.
The content of the character-string, when represented in standard
data format, must be one or more alphabetic characters.

Numeric

The PICTURE character-string can describe two types of numeric data
items: standard numeric items and long numeric items.
The PICTURE character-string for standard numeric items can contain
from 1 through 23 digits. The valid symbols for the PICTURE
character-string are 9, P, S, and V.
An unsigned numeric item, when represented in standard data format,
must be one or more numeric characters. A signed numeric item can
also contain a plus sign (+), minus sign (-), or other representation of
an operational sign.
The PICTURE character-string for long numeric items can contain from
1 to 99,999 digits. A long numeric item must be described as an
unsigned integer, so operational signs, editing symbols, and the
symbols P and V are not valid in its PICTURE character-string.

Alphanumeric

The PICTURE character-string for an alphanumeric item is restricted to
certain combinations of the symbols A, X, and 9. The item is treated
as if the character-string contained all Xs. An alphanumeric PICTURE
character-string cannot consist entirely of As or entirely of 9s.
The PICTURE character-string, when represented in standard data
format, must be one or more characters in the computer's character
set.

4–38

8600 1518–307

Data Description Entry Format 1

Table 4–3. Specification of Data Item Categories in the PICTURE
Clause

Item

National

Definition

The PICTURE character-string for a national data item can contain only
the letter N or X. When the letter N is used, the PICTURE clause must
be accompanied by the USAGE IS NATIONAL clause. When the letter
X is used, the PICTURE clause must be accompanied by the USAGE
IS KANJI clause. (Note that the USAGE IS KANJI clause might become
obsolete in a future release.)
The PICTURE character-string, when represented in national standard
data format, must be one or more characters in the national character
set of the computer.

Boolean

Symbol 1 is the only symbol that the PICTURE character-string for a
Boolean item can contain.

Alphanumericedited

The PICTURE character-string for an alphanumeric-edited item is
restricted to certain combinations of simple insertion editing symbols
and the symbols A, X, and 9. The PICTURE character string must
contain at least one A or X, and must contain at least one simple
insertion editing symbol.
The PICTURE character-string, when represented in standard data
format, must be two or more characters in the computer's character
set.

National-edited

The PICTURE character-string for national-edited data items is
restricted to certain combinations of the symbols X, N, I, B, 0, and
slant (/). When the letter X is used, the PICTURE clause must be
accompanied by the USAGE IS KANJI clause. Note that this clause
might become obsolete in a future release.
The PICTURE character-string, when represented in national standard
data format, must be one or more characters in the national character
set of the computer.

8600 1518–307

4–39

Data Description Entry Format 1

Table 4–3. Specification of Data Item Categories in the PICTURE
Clause

Item

Definition

Numeric-edited

The PICTURE character-string for a numeric-edited item is restricted to
certain combinations of simple insertion editing symbols; the symbols
P, V, Z, 9, comma (,), period (.), plus sign (+), minus sign (-), CR, and
DB; and the currency symbol ($). The allowable combinations are
determined from the order of precedence of symbols and the editing
rules. Refer to the paragraphs headed “Precedence Rules” and
“Editing Rules” in this section.
The number of digit positions that can be represented in the PICTURE
character-string must range from 1 to 23 inclusive.
The character-string must contain at least one simple insertion editing
symbol, asterisk (*), plus sign (+), comma (,), period (.), minus sign (-),
slant (/), CR, DB, or currency symbol ($).
The content of each character position must be consistent with the
corresponding PICTURE symbol.
The size of an elementary item refers to the number of character
positions occupied by the item in standard data format. The number of
allowable symbols that represent character positions determines the
size of an elementary item.
The following symbols can appear only once in a given PICTURE: S, V,
period (.), CR, and DB.

Determining the Size of an Elementary Item
The size of an elementary item is the number of character positions it occupies in
standard data format. You indicate the size of an elementary item by using the number of
allowable symbols that represent character positions. For example, 9999 indicates a field
with four digits.
The symbols A, B, P, X, Z, 9, 0 (zero), asterisk (*), slant (/), comma (,), plus sign (+), minus
sign (-), or currency symbol ($) can appear more than once in a given PICTURE clause.
You can specify a number of consecutive occurrences of a symbol by using an unsigned
integer enclosed in parentheses after the symbol. For example, X(8) indicates eight
alphanumeric characters.

4–40

8600 1518–307

Data Description Entry Format 1

Editing Rules
Editing in the PICTURE clause can be done either by insertion or by suppression and
replacement. The four types of insertion editing are

•

Simple insertion

•

Special insertion

•

Fixed insertion

•

Floating insertion

The two types of suppression and replacement editing are

•

Zero suppression and replacement with spaces

•

Zero suppression and replacement with asterisks

The category to which an item belongs determines the type of editing that can be used,
as shown in Table 4–4.
Table 4–4. Types of Editing for Data Item Categories

Category

Type of Editing

Alphabetic

None.

Numeric

None.

Alphanumeric

None.

National

None.

Alphanumeric-edited

Simple insertion.

National-edited

Simple insertion (B, slash (/), and zero (0) only).

Numeric-edited

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

8600 1518–307

4–41

Data Description Entry Format 1

Simple Insertion Editing
Unisys supports the following two forms of simple insertion editing:

•

ANSI simple insertion editing
The space character (B), slash (/), zero (0), and comma (,) are used as insertion
characters.
When the STRICTPICTURE compiler control option is set, PICTURE character strings
are expected to conform to the rules set forth in ANSI X3.23-1985; syntax errors are
issued for any PICTURE character strings that do not conform. When the
STRICTPICTURE compiler control option is reset, certain additional variations on
simple insertion editing are allowed as detailed in the following explanations for
Manual insertion editing and automatic insertion editing.

•

Manual insertion editing
When the AUTOINSERT option is RESET, a Unisys extension to ANSI X3.23-1985
COBOL allows the symbol I to be used to introduce any nonblank character as a
simple insertion character. Therefore, any nonblank character that immediately
follows the symbol I in a PICTURE character string is treated as a simple insertion
character. This feature is intended as a replacement for automatic insertion editing,
which is scheduled for deimplementation in a future software release.

•

Automatic insertion editing
When the AUTOINSERT compiler control option is SET, a Unisys extension to ANSI
X3.23-1985 COBOL allows any character within a PICTURE character string that is
not recognized by the compiler as valid in its particular immediate context is treated
as a simple insertion character. This rule applies whether or not the particular
character has a meaning in another context within a PICTURE character string (such
as specified in Table 4-5, “Precedence Rules”).
Note: The AUTOINSERT compiler control option and the Automatic insertion
editing extension are scheduled for deimplementation in a future software
release. Refer to the preceding explanation of Manual insertion editing for an
improved method of using arbitrary symbols as simple insertion characters.
For example, an extra left or right parenthesis that is not part of a valid parenthetical
expression indicating multiple occurrences of the same symbol is by this rule an
insertion character. Any digit other than 9 is also an insertion character when it does
not occur within such a parenthetical expression. Plus and minus signs are insertion
characters when they appear outside of the contexts in which they are correctly
interpreted as signs. The Z and * characters in a PICTURE clause in which floating
insertion editing or zero suppression is already indicated by other specifications are
insertion characters. CR and DB sequences before the end of the PICTURE clause or
after another sign has already appeared in the PICTURE clause are treated as
insertions.
This list is illustrative and is not intended to cover all of the possibilities. The
extension applies to all characters in the EBCDIC character set in any context within
the PICTURE clause, except the character B, the space character, and those
characters for which a role has been defined in that particular context.

4–42

8600 1518–307

Data Description Entry Format 1

The character B already specifies simple insertion editing according to ANSI
standards in that it causes the insertion of a space into the output string. This same
functionality applies, according to this extension, even when the B character appears
outside of ANSI-defined contexts. The B character in a PICTURE string never results
in the insertion of a B into the output even if it appears in a context in which it would
otherwise be treated as invalid.
The space character always indicates that the character immediately preceding it is
the last character in the PICTURE character string.
A period followed by a space character always serves to indicate the end of the
PICTURE string, as it does for ANSI-compliant PICTURE character strings.
The only simple insertion editing functionality that Unisys supports is as stated in the
preceding descriptions. The results of using characters in a PICTURE character string that
does not conform to either ANSI or automatic insertion editing rules are unpredictable.
If the insertion character comma (,) is the last symbol in the PICTURE character-string,
then the PICTURE clause must be the last clause of the data description entry and must
be immediately followed by the separator period. As a result, the combination of a
comma and a period (,.) appears in the data description entry (or, if the DECIMAL POINT
IS COMMA clause is used, two consecutive periods (..) will appear).
Special Insertion Editing
The period (.) is used as the insertion character. In addition to being an insertion
character, it also represents the decimal point for alignment purposes. The insertion
character used for the actual decimal point is counted in the size of the item. The use of
the assumed decimal point, represented by the symbol V , and the actual decimal point,
represented by the insertion character, in the same PICTURE character-string is not
allowed.
If the insertion character period (.) is the last symbol in the PICTURE character-string, the
PICTURE clause must be the last clause of that data description entry and must be
followed by the separator period. As a result, two consecutive periods (..) appear in the
data description entry (or the combination of a comma and a period (,.) if the DECIMALPOINT IS COMMA clause is used). The result of special insertion editing is the
appearance of the insertion character in the item in the same position as shown in the
character-string.

8600 1518–307

4–43

Data Description Entry Format 1

Fixed Insertion Editing
The currency symbol and the editing sign control symbols plus sign (+), minus sign (-),
CR, and DB are the insertion characters. Only one currency symbol and only one of the
editing sign control symbols can be used in a given PICTURE character-string. When the
symbols CR or DB are used, they represent two character positions in determining the
size of the item and they must represent the rightmost character positions that are
counted in the size of the item. If these character positions contain the symbols CR or
DB, the uppercase letters are the insertion characters. The plus sign (+) or minus sign (-),
when used, must be either the leftmost or rightmost character position to be counted in
the size of the item. The currency symbol must be the leftmost character position to be
counted in the size of the item except that it can be preceded by either a plus sign (+) or
minus sign (-). Fixed insertion editing results in the insertion character occupying the
same character position in the edited item as it occupied in the PICTURE characterstring. Editing sign control symbols produce the following results depending upon the
value of the data item:

Result
Editing Symbol in
PICTURE
Character-string

Positive or Zero Data
Item

Negative Data Item

–

space

–

2 spaces

Floating Insertion Editing
The currency symbol and editing sign control symbols plus sign (+) and minus sign (-) are
the floating insertion characters. They are mutually exclusive in a given PICTURE
character-string.
Floating insertion editing is indicated in a PICTURE character-string by using a string of at
least two of the floating insertion characters. This string can contain any of the simple
insertion characters or have simple insertion characters immediately to the right of this
string. These simple insertion characters are part of the floating string. When the floating
insertion character is the currency symbol, the string of floating insertion characters can
have the fixed insertion characters CR and DB immediately to the right of this string.
The leftmost character of the floating insertion string represents the leftmost limit of the
floating symbols in the data item. The rightmost character of the floating string
represents the rightmost limit of the floating symbols in the data item.
The second floating character from the left represents the leftmost limit of the numeric
data that can be stored in the data item. Nonzero numeric data may replace all the
characters at or to the right of this limit.

4–44

8600 1518–307

Data Description Entry Format 1

In a PICTURE character-string, there are only two ways of representing floating insertion
editing. One way is to represent any or all of the leading numeric character positions on
the left of the decimal point by the insertion character. The other way is to represent all
the numeric character positions in the PICTURE character-string by the insertion
character.
If the insertion character positions are only to the left of the decimal point in the
PICTURE character-string, the result is that a single floating insertion character will be
placed into the character position immediately preceding either the decimal point or the
first nonzero digit in the data represented by the insertion symbol string, whichever is
farther to the left in the PICTURE character-string. The character positions preceding the
insertion character are replaced with spaces.
If all numeric character positions in the PICTURE character-string are represented by the
insertion character, at least one of the insertion characters must be to the left of the
decimal point.
When the floating insertion character is the plus sign (+) or minus sign (-), the character
inserted depends on the value of the data item:

Result
Editing Symbol in
PICTURE
Character-string

Positive or Zero Data
Item

Negative Data Item

–

space

–

If all numeric character positions in the PICTURE character-string are represented by the
insertion character, the result depends on the value of the data. If the value is zero, the
entire data item will contain spaces. If the value is not zero, the result is the same as
when the insertion character is only to the left of the decimal point.
To avoid truncation, the minimum size of the PICTURE character-string for the receiving
data item must be the number of characters in the sending data item, plus the number of
nonfloating insertion characters being edited into the receiving data item, plus one for the
floating insertion character. If truncation does occur, the value of the data that is used for
editing is the value after truncation. Refer to “Standard Alignment Rules” in this section
for more information.

8600 1518–307

4–45

Data Description Entry Format 1

Zero-Suppression Editing
The suppression of leading zeros in numeric character positions is indicated by the use of
the alphabetic character Z or the character asterisk (*) as suppression symbols in a
PICTURE character-string. These symbols are mutually exclusive in a given PICTURE
character-string. Each suppression symbol is counted in determining the size of the item.
If Z is used, the replacement character will be the space and if the asterisk is used, the
replacement character will be an asterisk (*).
Zero-suppression and replacement is indicated in a PICTURE character-string by using a
string of one or more of the allowable symbols to represent leading numeric character
positions that are to be replaced when the associated character position in the data
contains a leading zero. Any of the simple insertion characters embedded in the string of
symbols or to the immediate right of this string are part of the string.
In a PICTURE character-string, there are only two ways of representing zero suppression.
One way is to represent any or all of the leading numeric character positions to the left of
the decimal point by suppression symbols. The other way is to represent all of the
numeric character positions in the PICTURE character-string by suppression symbols.
If the suppression symbols appear only to the left of the decimal point, any leading zero
in the data that corresponds to a symbol in the string is replaced by the replacement
character. Suppression terminates at the first nonzero digit in the data represented by
the suppression symbol string or at the decimal point, whichever is encountered first.
If all numeric character positions in the PICTURE character-string are represented by
suppression symbols and the value of the data is not zero, the result is the same as if the
suppression characters were only to the left of the decimal point. If the value is zero and
suppression symbol is Z, the entire data item, including any editing characters, is spaces.
If the value is zero and the suppression symbol is an asterisk (*), the entire data item,
including any insertion editing symbols except the actual decimal point, will be an
asterisk (*). In this case, the actual decimal point will appear in the data item.
When the symbols plus sign (+), minus sign (-), asterisk (*), Z, and the currency symbol
(usually $) are used as floating replacement characters, they are mutually exclusive
within a given character-string. The zero-suppression editing characters Z and asterisk (*)
can be used as simple insertion characters in limited situations. When they are the
trailing characters to the right of the decimal point in what would otherwise be a valid
floating insertion editing picture, the Z or asterisk is treated as a simple insertion
character.

4–46

8600 1518–307

Data Description Entry Format 1

Precedence Rules
The following table shows the order of precedence for characters as symbols in a
character-string. An X at an intersection indicates that the symbol or symbols at the top
of the column can precede (not necessarily immediately), in a given character-string, the
symbol or symbols at the left of the row. Arguments in braces {} indicate that the
symbols are mutually exclusive. The currency symbol is indicated by the symbol cs.
At least one of the symbols A, X, N, Z, 9, or asterisk (*), or at least two occurrences of
one of the symbols plus sign (+), minus sign (-), or a currency symbol (for example, $)
must be present in a PICTURE character-string.
The nonfloating insertion symbols plus sign (+) and minus sign (-); the floating insertion
symbols Z, asterisk (*), plus sign (+), minus sign (-), and currency symbol; and symbol P
appear twice in the PICTURE character precedence in the tables that follow. The
leftmost column and uppermost row for each symbol represent its use to the left of the
decimal point position. The second appearance of the symbol in the chart represents its
use to the right of the decimal point position.
Note: The symbol I in the following table represents any manual insertion character
when $AUTOINSERT is set, and the nonblank character following the I in the PICTURE
string when $AUTOINSERT is reset.

8600 1518–307

4–47

Data Description Entry Format 1

Table 4–5. Precedence Rules

4–48

8600 1518–307

Data Description Entry Format 1

RECEIVED BY Clause
This clause identifies the way in which parameters and results are passed between two
procedures or between a user program and an imported library procedure.

•

If the parameter or result is declared with the RECEIVED BY CONTENT clause, the
parameter is passed by value.
When parameters are passed by value, the value of the actual parameter is assigned
to the formal parameter, which is handled as a local variable by the receiving
procedure. Any change made to the value of a RECEIVED BY CONTENT parameter
has no effect outside of the receiving procedure.

•

If the parameter or result is declared with the RECEIVED BY REFERENCE clause, the
parameter is passed by reference.

•

When parameters are passed by reference, the address of the actual parameter is
evaluated once and passed to the formal parameter. Every reference to the formal
parameter within the receiving procedure references this address. Any change made
to the value of the formal parameter within the receiving procedure changes the
value of the actual parameter.

If the RECEIVED BY clause is not specified, all data items and files are RECEIVED BY
REFERENCE. Exceptions to this are 77-level USAGE IS BINARY, DOUBLE, and REAL
parameters to bound procedures which are assumed to be RECEIVED BY CONTENT, if
not otherwise specified.
REF is a synonym for REFERENCE.
Note: This clause is ignored for data items not referenced as formal parameters.

8600 1518–307

4–49

Data Description Entry Format 1

RECORD AREA Clause
This clause specifies that the record being described is to be used for DIRECT I–O
buffering. This clause may only appear on the 01 level in a WORKING–STORAGE
SECTION or a LOCAL–STORAGE SECTION.
Areas described with the RECORD AREA clause become non–overlayable until the area
is specified in a DEALLOCATE statement.
An area described with the RECORD AREA clause must not be declared to be binary.

SIGN Clause
Every numeric data description entry whose PICTURE clause contains the character S is
considered to be a signed numeric data description entry. The S indicates only the
presence of the operational sign. To indicate the position and mode of representation of
the operational sign, you can use the SIGN clause.
A numeric data description entry with an S in the PICTURE clause, but to which no
optional SIGN clause applies, has an operational sign that is positioned and represented
according to the standard default position and representation of operational signs.
(If you do not specify a SIGN clause, the sign is assumed to be in the trailing position for
a DISPLAY data item or in the leading position for a COMPUTATIONAL data item unless
a default sign is specified by the DEFAULT DISPLAY SIGN clause or the DEFAULT
COMP SIGN clause in the Special-Names paragraph of the Environment Division.)
If a SIGN clause is specified in a group item, each item subordinate to the group item is
affected.
If a SIGN clause is specified in a group item subordinate to a group item for which a SIGN
clause is specified, the SIGN clause specified in the subordinate group item takes
precedence for that subordinate group item.
If a SIGN clause is specified in an elementary numeric data description entry that is
subordinate to a group item for which a SIGN clause is specified, the SIGN clause
specified in the subordinate elementary numeric data description entry takes precedence
for that elementary numeric data item.
Note that when the SIGN clause is used, any conversion necessary for computation or
comparisons takes place automatically.
SIGN IS SEPARATE
If the CODE-SET clause is specified in a file description entry, any signed numeric data
description entries associated with that file-description entry must be described with this
form of the SIGN clause.

4–50

8600 1518–307

Data Description Entry Format 1

SEPARATE CHARACTER
If a SIGN clause with a SEPARATE CHARACTER phrase applies to a numeric data
description entry, the following rules apply:

•

The operational sign is presumed to be the leading or, respectively, trailing character
position of the elementary numeric data item. This character position is not a digit
position.

•

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

•

The operational signs for positive and negative are the standard data format
characters plus sign (+) and minus sign (-), respectively.

•

When the usage of the data item is DISPLAY, the operational sign is maintained and
expected as a LEADING or TRAILING character separate from, and in addition to, the
numeric character positions. The operational sign for negative values is the character
minus sign (-) , and for positive values, plus sign (+).

•

When the usage of the data item is COMPUTATIONAL, the operational sign is
maintained and expected as a binary 1100, 1111, or 1101 in the zone of the
LEADING or TRAILING character. Adding this binary character increases by one 4-bit
character the amount of storage allocated for the data item, in addition to the storage
allocated for an unsigned COMPUTATIONAL data item. The binary numbers 1100
and 1111 represent a positive sign, whereas the binary number 1101 represents a
negative sign. The presence or absence of the SEPARATE CHARACTER phrase has
no effect on the position or representation of the operational sign for
COMPUTATIONAL data items.

If a SIGN clause without a SEPARATE CHARACTER phrase applies to a numeric data
description entry, the following rules apply:

•

The operational sign will be presumed to be associated with the leading (or,
respectively, trailing) digit position of the elementary numeric data item.

•

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

•

When the usage of the data item is DISPLAY, the operational sign is maintained and
expected as a binary 1100 or 1101 in the zone of the LEADING or TRAILING
character and does not cause additional storage to be allocated for the data item.

•

When the usage of the data item is COMPUTATIONAL, the operational sign is
maintained and expected as a binary 1100 or 1101 LEADING or TRAILING 4-bit
character. Adding this binary character increases by one 4-bit character the amount
of storage allocated for the data item, in addition to the storage allocated for an
unsigned COMPUTATIONAL data item. The presence or absence of the SEPARATE
CHARACTER phrase has no effect on the position or representation of the
operational sign for COMPUTATIONAL data items.

8600 1518–307

4–51

Data Description Entry Format 1

SYNCHRONIZED Clause
This clause specifies the alignment of an elementary item on the natural boundaries of
the computer memory (refer to “Increasing Object-Code Efficiency” in this section).
This clause specifies that the subject data item is to be aligned in the computer so that
no other data item occupies any of the character positions between the leftmost and
rightmost natural boundaries that delimit this data item. If the number of character
positions required to store this data item is less than the number of character positions
between those natural boundaries, the unused character positions (or portions thereof)
must not be used for any other data item. Such unused character positions, however, are
included in the following:

•

The size of any group item or items to which the elementary item belongs.

•

The number of character positions allocated when any such group item is the object
of a REDEFINES clause. The unused character positions are not included in the
character positions redefined when the elementary item is the object of a
REDEFINES clause.

This clause can appear only with an elementary item.
SYNCHRONIZED
SYNC

These keywords are equivalent.
The SYNCHRONIZED keyword not followed by either RIGHT or LEFT specifies that the
elementary item is to be positioned between natural boundaries in such a way as to
effect efficient utilization of the elementary data item. LEFT and RIGHT have no effect on
alignment and are treated only as commentary.
If the subject data item is of type COMP, it is aligned on a byte boundary. If it is a single
word type (REAL or PIC 9(11) or less in BINARY or COMP-5) or a double word type
(DOUBLE, or PIC (12) or larger in BINARY or COMP-5), it is aligned on a word boundary.
If the previous data item did not end on a byte (or word) boundary, an implicit FILLER is
generated. This unused filler is included in the size of any group item or items to which
the elementary item belongs.
Whenever a SYNCHRONIZED item is referred to in the source program, the original size
of the item, as shown in the PICTURE clause, the USAGE clause, and the SIGN clause, is
used in determining any action that depends on size, such as justification, truncation, or
overflow.
If the data description of an item contains an operational sign and any form of the
SYNCHRONIZED clause, the sign of the item appears in the sign position explicitly or
implicitly specified by the SIGN clause.

4–52

8600 1518–307

Data Description Entry Format 1

When the SYNCHRONIZED clause is specified in a data description entry of a data item
that also contains an OCCURS clause, or in a data description entry of a data item that is
subordinate to a data description entry that contains an OCCURS clause, then the data
description entry is affected as follows:

•

Each occurrence of the data item is SYNCHRONIZED.

•

Any implicit FILLER generated for other data items within that same table is
generated for each occurrence of those data items.

BINARY, REAL, and DOUBLE data items that are subordinate to a data description entry
containing an OCCURS clause are not SYNCHRONIZED.

TYPE Clause
The TYPE clause provides automatic date and time editing based on the CONVENTION
and LANGUAGE options specified. The TYPE clause can be used only for
internationalization purposes. The desired format for the five date and time data items
can be obtained via the ACCEPT or MOVE statements.
Data items can be declared as one of the following date or time types:

Type

Example

SHORT-DATE

Fri, Aug 31, 1998

LONG-DATE

Friday, August 31, 1998

NUMERIC-DATE

08/31/98

NUMERIC-TIME

13:37:20

LONG-TIME

14:37:20.0000

Data items can also be declared with an associated LANGUAGE or CONVENTION option.
Each convention defined by Unisys has a specified format for the five date and time data
items. The program formats an item that is declared to be one of the five date and time
types according to the predefined format of the specified convention. For the SHORTDATE, LONG-DATE, and LONG-TIME options, the specified language is also used in
formatting the output. If the convention or language is not specified, the system
determines the language and convention to be used based on system-defined hierarchy.
The only clauses that can be used with the TYPE clause are the PICTURE clause and the
USAGE clause. If the PICTURE clause is specified, the TYPE clause can designate only
PICTURE X or PICTURE N. If the USAGE clause is specified, the TYPE clause can
designate only USAGE IS DISPLAY or USAGE IS NATIONAL. If the date or time items are
edited in the PICTURE clause, the TYPE clause overrides the edit and the compiler issues
a warning message.

8600 1518–307

4–53

Data Description Entry Format 1

The total length of the data item must be greater than or equal to the length required by
the format of the specified conventions. If the length of a data item is shorter than the
required length, the compiler issues a truncation warning message.
Example
The following example shows TYPE clause coding. The NUM-DATE-ITEM is declared as
a NUMERIC-DATE type and it is formatted by using the ASERIESNATIVE convention. The
NUM-DATE-ITEM language is determined by the system hierarchy. The LONG-DATEITEM data is formatted according to the convention and language determined by the
system hierarchy. The LONG-TIME-ITEM is declared as the LONG-TIME type and is
formatted using the UNITEDKINGDOM1 convention and the ENGLISH language.
01 NUM-DATE-ITEM PIC X(8) TYPE IS NUMERIC-DATE
USING CONVENTION OF "ASERIESNATIVE".
01 LONG-DATE-ITEM PIC X(20) TYPE IS LONG-DATE.
01 LONG-TIME-ITEM PIC X(20) TYPE IS LONG-TIME
USING CONVENTION OF "UNITEDKINGDOM1"
LANGUAGE OF "ENGLISH".

USAGE Clause
This clause specifies the manner in which a data item is represented in the storage of a
computer. The USAGE clause does not affect the use of the data item, although certain
statements in the Procedure Division might restrict the USAGE clause to certain
operands. For example, the PROCESS statement requires a data item to be declared
with the USAGE IS TASK clause. The USAGE clause can affect the type of character
representation of the item.
This clause can be written in any data description entry except those defined with a levelnumber of 66 or 88.
If this clause is written in the data description entry for a group item, it can also be
written in the data description entry for any subordinate elementary item or group item,
but the same usage must be specified in both entries. Note that if the USAGE clause is
written at a group level, it applies to each elementary item in the group.
An elementary data item (or an elementary data item subordinate to a group item) whose
declaration contains a USAGE clause that specifies BINARY, COMPUTATIONAL, or
PACKED-DECIMAL must be declared with a PICTURE character-string that describes a
numeric item (that is, a PICTURE character-string that contains only the symbols P, S, V,
and 9. Refer to “PICTURE Clause” in this section.)
An elementary data item declaration that contains a USAGE clause that specifies BIT is
specified only with a PICTURE character-string that describes a Boolean data item.

4–54

8600 1518–307

Data Description Entry Format 1

USAGE IS BINARY
This form of the USAGE clause indicates that the data is in a binary-coded format. A
BINARY item is capable of representing a value to be used in computations and therefore
is always numeric. A long numeric data item cannot have a usage of BINARY.
BINARY items occupy memory as follows:

•

When the declared size is less than or equal to 11 decimal digits, the actual size is
equal to one computer word (the equivalent of 6 DISPLAY digits or 12
COMPUTATIONAL digits). Note that the item is not necessarily aligned on a word
boundary.

•

When the declared size is greater than 11 digits, the actual size is equal to two
computer words (the equivalent of 12 DISPLAY digits); however, the item is not
necessarily aligned on a word boundary.

•

The actual size is used for determining the size of a record and for testing for size
error conditions.

Although BINARY items are not required to start at a word boundary, faster execution
results when they do start at a word boundary.

USAGE IS BINARY TRUNCATED
USAGE IS BINARY TRUNCATED is synonymous with USAGE BINARY. This syntax is
provided for compatibility with COBOL74.

USAGE IS BINARY EXTENDED
USAGE IS BINARY EXTENDED is similar to COBOL74 USAGE BINARY and is provided
for compatibility with that language.
The value stored in a USAGE BINARY EXTENDED data item is maintained internally as an
integer; if the associated PICTURE clause contains an explicit decimal point, the compiler
takes this into account in any operations, as for USAGE BINARY.
High-order digit truncation of that internal integer value is limited to ensuring that its
magnitude does not exceed the internal representation of a single-precision or doubleprecision integer on the underlying architecture.
If the PICTURE clause of the data item specifies a digit length from 1 to 11 digits
inclusive, the maximum internal magnitude that can be stored in the item is
549,755,813,887. If the PICTURE clause specifies from 12 to 23 digits inclusive, the
magnitude of the internal value stored in the item must not exceed
302,231,454,903,657,293,676,543.
When arithmetic statements with ON SIZE ERROR clauses produce internal results that
exceed these values, the ON SIZE ERROR condition is set. For other statements,
INTEGER OVERFLOW program terminations prevent the data corruption that would
otherwise result (and that could occur with COBOL74 USAGE BINARY under similar
circumstances).

8600 1518–307

4–55

Data Description Entry Format 1

USAGE IS BIT
The USAGE BIT clause specifies that Boolean data items be represented as bits.
The following criteria are used to determine the alignment of an elementary data item
described with USAGE BIT:

•

When an ALIGNED clause is specified:
Alignment of elementary bit data items occurs at the leftmost bit position of the next
available byte in storage.

•

When an ALIGNED clause is not specified and a SYNCHRONIZED clause is not
specified:
Alignment of an elementary bit data item within a record occurs at the next bit
position in storage if that item is an elementary bit data item that immediately
follows an elementary bit data item.
Alignment of all other bit data items within a record occurs at the leftmost bit
position of the next available byte.
Alignment of elementary bit data items of level 1 or level 77 occurs at the leftmost
bit position of a word.

•

When an ALIGNED clause is not specified and a SYNCHRONIZED clause is not
specified:
SYNCHRONIZED LEFT specifies that the elementary bit data item begin at the
leftmost bit of the next available word in which the elementary item is placed. An
implicit elementary filler bit data item with the unused bits of the word is generated
after the bit data item.
SYNCHRONIZED RIGHT specifies that the elementary bit data item terminate at the
rightmost bit of the next available word in which the elementary item is placed. An
implicit elementary filler bit data item with the unused bits of the word is generated
before the bit data item.
If you specify SYNCHRONIZED without LEFT or RIGHT, elementary bit data items
are treated as if you specified SYNCHRONIZED LEFT.

4–56

8600 1518–307

Data Description Entry Format 1

USAGE IS COMPUTATIONAL and USAGE IS COMP
A COMPUTATIONAL item can represent a value to be used in computations and must be
numeric. The system interprets COMPUTATIONAL fields as packed-decimal numeric
items rather than hexadecimal strings. Thus, if nonnumeric values are assigned to a
COMPUTATIONAL item, the content of the COMPUTATIONAL item is undefined.
A numeric literal can be described as a COMPUTATIONAL item. Valid characters for a
numeric literal are the numbers 0 through 9, the plus sign (+), the minus sign (-), and the
decimal point. The hexadecimal digits A through F are not valid in a numeric literal.
If a group item is described as COMPUTATIONAL, the elementary items in the group are
COMPUTATIONAL, but the group item itself is not COMPUTATIONAL (that is, it cannot
be used in computations).
Elementary COMPUTATIONAL data items are represented internally as contiguous 4-bit
digits.
A long numeric data item with a usage of COMPUTATIONAL must contain an even
number of digits.
The keywords COMP and COMPUTATIONAL are equivalent.

USAGE IS COMPUTATIONAL-5 and USAGE IS COMP-5
This form of the USAGE clause indicates that the data behaves as a binary item with the
SYNCHRONIZED clause specified. (The SYNCHRONIZED clause specifies that a binary
item is to be aligned on a word boundary. For more information, see “SYNCHRONIZED
Clause” earlier in this section.)
A COBOL85 data item declared as COMP-5 PIC S9(4) maps to a C short integer.
A COBOL85 data item declared as COMP-5 PIC S9(9) maps to a C long integer.
A long numeric data item cannot have a USAGE of COMP-5.
COMP-5 is a valid abbreviation for COMPUTATIONAL-5.

USAGE IS CONTROL-POINT
This clause is an obsolete synonym for the USAGE IS TASK clause.

8600 1518–307

4–57

Data Description Entry Format 1

USAGE IS DISPLAY
This form of the USAGE clause, whether specified explicitly or implicitly, indicates that a
standard data format is used to represent a data item in the storage of the computer, and
that the data item is aligned on a character boundary.
If the USAGE clause is not specified for an elementary item, or for any group to which
the item belongs, the usage is implicitly DISPLAY.
DISPLAY data items are represented internally as contiguous 8-bit characters
represented in the EBCDIC character set.
Every occurrence of a DISPLAY data item begins and ends on a byte boundary. In a
record description, the declaration of a DISPLAY data item immediately following a
COMPUTATIONAL or INDEX data item that does not end on a byte boundary causes
automatic generation of a 4-bit filler between the two items. This filler area between the
two data items is not included in the size of either item but is included in the size of all
group items to which the two items are subordinate. Similarly, if the last item declared in
a group item at the next-lowest hierarchic level is a COMPUTATIONAL or INDEX data
item that does not end on a byte boundary, automatic generation of a 4-bit filler occurs.
This filler is included in the size of a group item.

USAGE IS DOUBLE
This form of the usage clause specifies that a data item is a double-precision real
number. All real numbers are represented internally in floating-point format.
A DOUBLE data item can represent a value that can be used in computations, and is
always numeric. The actual size of a DOUBLE data item is equal to two computer words.
DOUBLE data items are not necessarily word-aligned. Whether the data item is aligned
on a word boundary is dependent on the context in which it is declared.
When a DOUBLE data item represents a value that the machine must approximate, and
it is assigned to a DISPLAY, COMP, or BINARY data item, then precision might be lost.
Example
If A is declared as DOUBLE, and B is declared as PIC 9V99, the following statements
yield the value of 1.79 for B, because B has the approximate value of
1.7999999999883584678:
MOVE 1.8 TO A
COMPUTE B = A
Although DOUBLE data items are not required to start at a word boundary, faster
execution results when they do start at a word boundary.

4–58

8600 1518–307

Data Description Entry Format 1

USAGE IS EVENT
This clause specifies that the data item is an event item, which is used to provide
synchronization and common interlocks between two or more tasks. An event item
occupies two words of memory.
An event item has two states associated with it: available and happened.
The available state has two values: not available and available. The not available value is
used to temporarily restrict access to a particular object so that only one process can
access the object during a given period of time. The available value permits access to the
object.
The happened state also has two values: not happened and happened. This state is used
to allow one or more processes to wait without using any processor time while they
wait.
You can specify the USAGE IS EVENT clause for a 77-level data item or a 01-level or
subordinate data item.
If you specify the USAGE IS EVENT clause for a group item, the elementary items in the
group are considered to be event items. The group itself is not an event item. You cannot
used the group in any construct except the USING PHRASE of a CALL (Format 6),
PROCESS, or RUN statement.
Event items cannot be doubly subscripted. This means that an event item with an
OCCURS clause cannot have a subordinate event item with an OCCURS clause.
Event items cannot be redefined by items of any other usage.
You cannot use any other clauses with an item whose usage is EVENT.

8600 1518–307

4–59

Data Description Entry Format 1

USAGE IS INDEX
This form of the usage clause specifies that a data item is an index data item and
contains a value that must correspond to an occurrence number of a table element.
If a group item is described with the USAGE IS INDEX clause, the elementary items in
the group are all index data items. The group itself is not an index data item and cannot
be used in the SEARCH or SET statement or in a relation condition.
A group item is also considered to be a group data item if its class is numeric, if its
USAGE IS INDEX, and if it can be referred to at any place in the syntax that is acceptable
for such an item. The size of the group item is considered in terms of DISPLAY
characters (four characters for each subordinate index data item).
An index data item can contain a signed value. An index data item occupies the same
space and has the same alignment as an item declared PICTURE S9(7) USAGE IS
COMPUTATIONAL.
An elementary data item described with a USAGE IS INDEX clause must not be a
conditional variable.
An index data item can be referred to explicitly only in a SEARCH or SET statement, a
relation condition, the USING phrase of a Procedure Division header, or the USING
phrase of a CALL statement.
When a MOVE statement or an input-output statement that refers to a group item that
contains an index data item is executed, no conversion of the index data item takes
place.
The BLANK WHEN ZERO, JUSTIFIED, PICTURE, SYNCHRONIZED, and VALUE clauses
must not be specified for data items whose usage is INDEX.

4–60

8600 1518–307

Data Description Entry Format 1

USAGE IS LOCK
This clause specifies that the data item is a lock item, which is used to provide
synchronization and common interlocks between two or more tasks. A lock item
occupies two words of memory. A lock item has two states: not available and available.
The not available value is used to temporarily restrict access to a particular object so that
only one process can access the object during a given period of time. The available value
permits access to the object.
You can specify the USAGE IS LOCK clause for a 77-level data item or a 01-level or
subordinate data item.
If you specify the USAGE IS LOCK clause for a group item, the elementary items in the
group are considered to be lock items. The group itself is not a lock item. You cannot use
the group in any construct except the USING PHRASE of a CALL (Format 6), PROCESS,
or RUN statement.
Lock items cannot be doubly subscripted. This means that a lock item with an OCCURS
clause cannot have a subordinate lock item with an OCCURS clause.
Lock items cannot be redefined by items of any other usage.
You cannot use any other clauses with an item whose usage is LOCK.

USAGE IS KANJI (Obsolete)
KANJI is a synonym for NATIONAL. Any data item that uses the USAGE IS KANJI clause
must have the letter X in its PICTURE clause. The KANJI synonym might become
obsolete in a future release of COBOL85; thus, NATIONAL is the preferred usage.

8600 1518–307

4–61

Data Description Entry Format 1

USAGE IS NATIONAL
This form of the USAGE clause, whether specified explicitly or implicitly, indicates that a
national standard data format is being used to represent a data item. National data items
are represented internally as contiguous 16-bit characters in the national character set. If
the CCSVERSION clause is specified with options other than NATIVE or CCSVERSION
"ASERIESNATIVE", national data items are represented internally as contiguous 8-bit
characters in the national character set.
To have a usage of national, the data item must have an N or the characters N, B, 0, and
slant (/) in its PICTURE character-string.
Data items with a SIGN clause or a BLANK WHEN ZERO clause cannot be declared with
a USAGE IS NATIONAL clause.
Every occurrence of a national data item begins and ends on a byte boundary. In a record
description, if a national data item immediately follows a computational or an index data
item that does not end on a byte boundary, the compiler automatically generates a 4-bit
filler between the national item and the other item. This filler area between the two data
items is not included in the size of either item, but is included in the size of all group
items to which the two items are subordinate.
If the last item declared in a group item at the next-lowest hierarchic level is a
computational or index data item that does not end on a byte boundary, automatic
generation of a 4-bit filler occurs. This filler is included in the size of a group item.

USAGE IS PACKED-DECIMAL
This clause is the same as the USAGE IS COMPUTATIONAL/USAGE IS COMP clause.

USAGE IS REAL
This form of the usage clause specifies that a data item is a single-precision real number.
All real numbers are represented internally in floating-point format.
A REAL data item can represent a value that can be used in computations and is always
numeric. A long numeric cannot have a usage of REAL. The actual size of a REAL data
item is equal to one computer word. A REAL data item can be used to store any item
that is documented as being equivalent to a REAL data item without altering the bit
pattern. REAL data items are not necessarily word-aligned. Whether the data item is
aligned on a word boundary is dependent on the context in which it is declared. Although
REAL data items are not required to start at a word boundary, faster execution results
when they do start at a word boundary.
When a REAL data item represents a value that the machine must approximate, and it is
assigned to a DISPLAY, COMP, or BINARY data item, then precision might be lost.

4–62

8600 1518–307

Data Description Entry Format 1

Example
If A is declared as REAL, and B is declared as PIC 9V999, the following statements yield
the value of 1.119 for B, because A has the approximate value of
1.1199999999953433871:
MOVE 1.12 TO A
COMPUTE B = A

USAGE IS TASK
This form of the USAGE clause enables you to define a data item as a task variable. You
can define a 77-level or a 01-level or subordinate data item as a task variable.
If you describe a group item with the USAGE IS TASK clause, all the elementary items in
the group are considered to be task variables. The group itself is not a task variable. You
can use the group item only as a parameter in the USING phrase of the CALL (Format 6),
PROCESS, and RUN statements. For the syntax of these statements, refer to Section 7
and Section 8.
Note that a task variable with an OCCURS clause cannot have a subordinate task variable
with an OCCURS clause.
Task variables cannot be redefined by variables of any other usage. No other clauses are
allowed for a data item when the USAGE IS TASK clause is declared.
For details about task variables, refer to Section 13.

8600 1518–307

4–63

Data Description Entry Format 1

VALUE Clause
In this format, the VALUE clause defines the initial value of Working-Storage Section data
items.
The following rules apply to the literals specified in a VALUE clause of an item:
If the item is . . .

Then the literal must . . .

Numeric

Have a value in the range of values indicated by the PICTURE
clause, and must not have a value that would require truncation
of nonzero digits

Signed Numeric

Have a signed numeric PICTURE character-string associated with
it

Nonnumeric

Not exceed the size indicated by the PICTURE clause

Long numeric

•
•

Be ZERO or 0

•

Be an undigit literal of the same size in bytes as the item

Be a numeric literal of the same size in digits as the data
item

The VALUE clause must not conflict with other clauses in the data description of the
item or in the data description in the hierarchy of the item.
The following rules apply:
If the category of
the item is . . .

Then all literals in the VALUE clause must be . . .

Numeric

Numeric.
If a literal defines the value of a WORKING-STORAGE item, that
literal is aligned in the data item according to the standard
alignment rules (refer to “Standard Alignment Rules” in this
section).

Numeric-edited

Numeric or nonnumeric.
If the literal is a nonnumeric literal, it is aligned in the data item
as if the data item had been described as alphanumeric.
If the literal is a numeric literal, it is aligned on the data item
according to the standard alignment rules for numeric literals.
Refer to “Standard Alignment Rules” in this section.
Editing characters in the PICTURE clause are included when
determining the size of the data item but have no effect on
initialization of the data item (refer to “PICTURE Clause” in this
section). Therefore, the VALUE clause for an edited item must
be specified in edited form.

4–64

8600 1518–307

Data Description Entry Format 1

If the category of
the item is . . .

Alphabetic
Alphanumeric
Alphanumeric-edited

Then all literals in the VALUE clause must be . . .

Nonnumeric.
The literal is aligned in the data item as if the data item had
been described as alphanumeric (refer to “Standard Alignment
Rules” in this section).
Editing characters in the PICTURE clause are included in
determining the size of the data item but have no effect on
initialization of the data item (refer to “PICTURE Clause” in this
section). Therefore, the VALUE clause for an edited item must
be specified in edited form.

National
National-edited

National.
The literal is aligned in the data item as if the data item had
been described as national (refer to “Standard Data Alignment
Rules” in this section).
Editing characters in the PICTURE clause are included in
determining the size of the data item (refer to “PICTURE
Clause” in this section). Therefore, the VALUE clause for an
edited item must be specified in edited form.

Boolean

Note that initialization is not affected by any BLANK WHEN ZERO or JUSTIFIED clause
that might be specified.
Rules that govern the use of the VALUE clause differ depending on the section of the
Data Division in which the VALUE clause occurs.
For Data Description Entry Format 1, the rules in the following table apply:

In . . .

The VALUE clause . . .

The File Section

Cannot be used.

The Linkage Section

Cannot be used, except for the data items which
are not used as formal parameters.

The Local-Storage Section

Cannot be used.

The Working-Storage Section

Takes effect only when the program is placed into
its initial state.
If the VALUE clause is used in the description of
the data item, the data item is initialized to the
defined value. If the VALUE clause is not
associated with a data item, the initial value of that
data item is undefined. If the data item is defined
as a formal parameter, then the VALUE clause will
be ignored.

8600 1518–307

4–65

Data Description Entry Format 1

4–66

In . . .

The VALUE clause . . .

A data description entry that
contains a REDEFINES clause, or
an entry that is subordinate to an
entry that contains a REDEFINES
clause

Cannot be used.

A data description entry that is part
of the description or redefinition of
an external data record

Cannot be used.

A data description entry that
contains an OCCURS clause, or an
entry that is subordinate to an
OCCURS clause

Causes every occurrence of the associated data
item to be assigned the specified value.

An entry at the group level

Must contain a figurative constant or a
nonnumeric literal, and the group area is initialized
without consideration for the individual elementary
or group items contained within this group. The
VALUE clause cannot be stated at the subordinate
levels within this group.

A group item containing
subordinate items with
descriptions include JUSTIFIED,
SYNCHRONIZED, or USAGE (other
than USAGE IS DISPLAY)

Cannot be used.

8600 1518–307

Data Description Entry Format 2: Level-66 RENAMES Entry

Data Description Entry Format 2: Level-66
RENAMES Entry
This format renames a data-name or range of data-names.
Ú ä
66 data-name-1 RENAMES data-name-2³ ³
ïïïïïïï
³ ã
³ ³
À æ

THROUGH
ïïïïïïï
THRU
ïïïï

å
³
â
³
ç

¿
data-name-3 ³
³
³
Ù

Level-number 66 identifies RENAMES entries. Level-number 66 is used only in this
format of a data description entry.
A level-66 entry cannot rename another level-66 entry, nor can it rename a level-number
77, 88, or 01 entry.
data-name-1

This name is a user-defined word. It cannot be used as a qualifier and can be qualified
only by the names of the associated level-01, FD, or SD entries.
When data-name-3 is specified, data-name-1 is a group item that includes all elementary
items starting with data-name-2 (if data-name-2 is an elementary item) or with the first
elementary item in data-name-2 (if data-name-2 is a group item), and concluding with
data-name-3 (if data-name-3 is an elementary item) or with the last elementary item in
data-name-3 (if data-name-3 is a group item).
When data-name-3 is not specified, data-name-1 assumes all characteristics of dataname-2 as determined from the data description of data-name-2, including usage,
justification, synchronization, and editing requirements.

8600 1518–307

4–67

Data Description Entry Format 2: Level-66 RENAMES Entry

RENAMES Clause
This clause allows alternative, possibly overlapping, groupings of elementary items.
Any number of RENAMES entries can be written for a logical record.
All RENAMES entries that refer to data items in a given logical record must immediately
follow the last data description entry of the associated record description entry.
data-name-2

These keywords are equivalent.
data-name-3

This name is a user-defined word and must be the name of an elementary item or a
group of elementary items in the same logical record.
This name cannot have an OCCURS clause in its data description entry and cannot be
subordinate to an item that has an OCCURS clause in its data description entry.
This name cannot be the same name as data-name-2.
This name can be qualified.
The beginning of the area described by this data-name must not be to the left of the
beginning of the area described by data-name-2. Also, the end of the area described by
this data-name must be to the right of the end of the area described by data-name-2.
Therefore, data-name-3 cannot be subordinate to data-name-2.

4–68

8600 1518–307

Data Description Entry Format 2: Level-66 RENAMES Entry

Details
None of the items in the range of data-name-2 through data-name-3 (including dataname-2 and data-name-3) can be variable-occurrence data items.
Example
03

NAME-PARTS.
05 LAST1
05 FIRST1
05 MID
PARTIAL-NAME

PIC X(15).
PIC X(15).
PIC X(10).
RENAMES LAST1 THROUGH FIRST1.

The RENAMES entry associates the user-defined name PARTIAL-NAME with the data
descriptions for the elementary items LAST1 and FIRST1 of the group item NAMEPARTS.

8600 1518–307

4–69

Data Description Entry Format 3: Level-88 Condition-Name Entry

Data Description Entry Format 3: Level-88
Condition-Name Entry
This format contains the name of the condition and the value, values, or range of values
associated with the condition-name. This format is used for each condition-name.

ä
å
88 condition-name-1 ³VALUE IS ³
ãïïïïï
â
³VALUES ARE³
æïïïïïï
ç

ä
³
³literal-1
ã
³
³
æ

å
Úä
å
¿³
³³THROUGH³ literal-2³³... .
³ãïïïïïïïâ
³â
³³THRU
³
³³
Àæïïïï
ç
Ù³
ç

Level-number 88 identifies entries that define condition-names associated with a
conditional variable. Level-number 88 is used only in this format of a data description
entry.
Note that each condition-name requires a separate entry with level-number 88.
condition-name-1

This name is a user-defined word. The Condition-name entries for a particular conditional
variable must immediately follow the entry describing the item with which the conditionname is associated.
A condition-name can be associated with any data description entry that contains a levelnumber except the following:

•

Another condition-name

•

A level-66 item

•

A group containing items with descriptions including JUSTIFIED, SYNCHRONIZED,
or USAGE (other than USAGE IS DISPLAY)

•

An index data item

VALUE
VALUES

This clause is explained in the following subsection under the heading “VALUE Clause.”

4–70

8600 1518–307

Data Description Entry Format 3: Level-88 Condition-Name Entry

literal-1 THROUGH literal-2

Whenever the THROUGH (THRU) phrase is used, literal-1 must be less than literal-2.
THROUGH
THRU

These keywords are equivalent.

VALUE Clause
In this format, the VALUE clause defines the values associated with condition-names.
The VALUE clause is required in a condition-name entry. The VALUE clause and the
condition-name itself are the only two clauses permitted in the entry. The characteristics
of a condition-name are implicitly those of its conditional variable.
The following rules apply to the literals specified in a VALUE clause of an item:
If the item is . . .

Then the literal must . . .

Numeric

Have a value in the range of values indicated by the PICTURE
clause and must not have a value that would require truncation
of nonzero digits

Signed numeric

Have a signed numeric PICTURE character-string associated
with it

Nonnumeric

Not exceed the size indicated by the PICTURE clause

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

If the category of
the item is . . .

Then all literals in the VALUE clause must be . . .

Numeric

Numeric.
If the literal defines the value of a WORKING-STORAGE item, the
literal is aligned in the data item according to the standard
alignment rules (refer to “Standard Alignment Rules” in this
section).

Numeric-edited

8600 1518–307

Numeric or nonnumeric.

4–71

Data Description Entry Format 3: Level-88 Condition-Name Entry

If the category of
the item is . . .

Alphabetic
Alphanumeric
Alphanumericedited

Then all literals in the VALUE clause must be . . .

Nonnumeric.
The literal is aligned in the data item as if the data item had been
described as alphanumeric (refer to “Standard Alignment Rules” in
this section).
Editing characters in the PICTURE clause are included in
determining the size of the data item but have no effect on
initialization of the data item (refer to “PICTURE Clause” in this
section). Therefore, the VALUE clause for an edited item must be
specified in edited form.

National
National-edited

National.
The literal is aligned in the data item as if the data item had been
described as national (refer to “Standard Data Alignment Rules” in
this section).
Editing characters in the PICTURE clause are included in
determining the size of the data item (refer to “PICTURE Clause”
in this section). Therefore, the VALUE clause for an edited item
must be specified in edited form.

Boolean

Note that initialization is not affected by any BLANK WHEN ZERO or JUSTIFIED clause
that might be specified.
Rules that govern the use of the VALUE clause differ depending on the section of the
Data Division in which the VALUE clause occurs. In Data Description Entry Format 3, the
rules in the following table apply:

4–72

In . . .

The VALUE clause . . .

The File Section

Can be used only in condition-name
entries. Therefore, the initial value of the
data items in the File Section is undefined.

The Linkage Section

Can be used only in condition-name entries
(level 88).

8600 1518–307

Data Description Entry Format 3: Level-88 Condition-Name Entry

In . . .

The VALUE clause . . .

The Working-Storage Section

Must be used in condition-name entries.
VALUE clauses in the Working-Storage
Section of a program take effect only
when the program is placed into its initial
state.
If the VALUE clause is used in the
description of the data item, the data item
is initialized to the defined value. If the
VALUE clause is not associated with a data
item, the initial value of that data item is
undefined.

A data description entry that contains a
REDEFINES clause, or an entry that is
subordinate to an entry that contains a
REDEFINES clause

Can be used.

A data description entry that includes, or is
subordinate to, an entry that includes the
EXTERNAL clause

Can be used.

A data description entry that is part of the
description or redefinition of an external
data record

Can be used.

A data description entry that contains an
OCCURS clause, or an entry that is
subordinate to an OCCURS clause

Causes every occurrence of the associated
data item to be assigned the specified
value. (The OCCURS clause is described
earlier in this section.)

An entry at the group level

Must contain a figurative constant or a
nonnumeric literal, and the group area is
initialized without consideration for the
individual elementary or group items
contained within this group.
The VALUE clause cannot be stated at the
subordinate levels within this group.

A data item referred to by a DEPENDING
ON phrase

Can be used. The value is considered to be
placed in the data item after the variable
occurrence data item is initialized (refer to
“OCCURS Clause” in this section).

A group item containing items subordinate
to it with descriptions including
JUSTIFIED, SYNCHRONIZED, or USAGE
(other than USAGE IS DISPLAY)

Cannot be used.

8600 1518–307

4–73

Data Description Entry Format 3: Level-88 Condition-Name Entry

Examples
01

MONTH
88 QI
88 QII
88 QIII
88 QIV

PIC 99.
VALUES ARE
VALUES ARE
VALUES ARE
VALUES ARE

01
04
07
10

02
05
08
11

03.
06.
09.
12.

These condition-name entries associate values with the conditions QI, QII, QIII, and QIV.
02

MONTH
PIC 99.
88 MONTHS-WITH-31-DAYS
VALUES ARE 01, 03, 05, 07
08, 10, 12.

This condition-name entry associates values with the condition MONTHS-WITH-31DAYS.
01 ITEM-1
01 ITEM-2

PIC ZZ99
PIC ZZ99

VALUE 1.
VALUE " 01".

In this example, the VALUE clauses define the same initial value for both ITEM-1 and
ITEM-2.

4–74

8600 1518–307

Data Description Entry Format 4: IPC

Data Description Entry Format 4: IPC
In interprogram communication (IPC), a level-01 or level-77 data description entry in the
Working-Storage Section or a level-01 data description entry in the File Section
determines whether the data record and its subordinate data have local names or global
names.

ä01å
ãïïâ
æ77ç
ïï

Ú
¿
³ data-name-1 ³
³
³
³ FILLER
³
À
Ù

[ IS EXTERNAL
ïïïïïïïï
Ú
¿
³ COMMON ³
³ ïïïïïï ³
³ OWN
³
³ ïïï
³
³ LOCAL
³
À ïïïïï
Ù
Ú
³
³
³
³
³
³
³
³[USAGE IS]
³ ïïïïï
³
³
³
³
³
³
³
³
³
³
³
³
³
³
À

8600 1518–307

ä
³
³
³
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
³
³
³
³
æ

]

Ú
[ REDEFINES data-name-2 ]³ INTEGER
ïïïïïïïïï
³ ïïïïïïï
³ STRING
À ïïïïïï

¿
³
³
³
Ù

[IS GLOBAL ]
ïïïïïï

Ú
³ äPICTUREå
³ ãïïïïïïïâ
³ æPIC
ç
À ïïï

¿
IS character-string ³
³
³
Ù

Ú
³ TRUNCATED
BINARY
³ ïïïïïïïïï
ïïïïïï
³ EXTENDED
À ïïïïïïïï
COMPUTATIONAL
ïïïïïïïïïïïïï
COMP
ïïïï
DISPLAY
ïïïïïïï
DOUBLE
ïïïïïï
INDEX
ïïïïï
KANJI
ïïïïï
NATIONAL
ïïïïïïïï
PACKED-DECIMAL
ïïïïïïïïïïïïïï
REAL
ïïïï

¿å
³³
³³
³³
Ù³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
³
³
³
ç

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
Ù

Ú
³
ä CONTENT
³
³ ïïïïïïï
³ RECEIVED BY ã REFERENCE
³
³ ïïïïïïïïï
³
æ REF
À
ïïï

å
³
â
³
ç

¿
³
³
³
³
³
Ù

4–75

Data Description Entry Format 4: IPC

Ú
ä
å
¿
³[ SIGN IS ] ³ LEADING ³ [ SEPARATE CHARACTER ] ³
³ ïïïï
ã ïïïïïïï â
ïïïïïïïï
³
³
³ TRAILING ³
³
À
æ ïïïïïïïï ç
Ù
Ú
¿
³
³
³OCCURS integer-2 TIMES
³
³ïïïïïï
³
³
Ú
¿
³
³
³ ä
å
³
³
³
³ ³ ASCENDING ³ KEY IS [data-name-3] ... ³...
³
³
³ ã ïïïïïïïïï â
³
³
³
³ ³ DESCENDING ³
³
³
³
³ æ ïïïïïïïïïï ç
³
³
³
À
Ù
³
³
[ INDEXED BY [ LOCAL ] [ index-name-1 ] ... ]
³
³
ïïïïïïï
³
³OCCURS integer-1 TO integer-2 TIMES DEPENDING ON data-name-4 ³
³ïïïïïï
ïï
ïïïïïïïïï
³
³
Ú
¿
³
³
³ ä
å
³
³
³
³ ³ ASCENDING ³ KEY IS {data-name-3}... ³ ...
³
³
³ ã ïïïïïïïïï â
³
³
³
³ ³ DESCENDING ³
³
³
³
³ æ ïïïïïïïïïï ç
³
³
³
À
Ù
³
³
[ INDEXED BY [ LOCAL ] {index-name-1 } ...]
³
³
ïïïïïïï
³
À
Ù
Ú
³
³ä
å Ú
¿ ¿
Ú ä
å
¿
³³ SYNCHRONIZED ³ ³ LEFT ³ ³
³ ³ JUSTIFIED ³ RIGHT
³
³ã ïïïïïïïïïïïï â ³ ïïïï ³ ³
³ ã ïïïïïïïïï â
³
³³ SYNC
³ ³ RIGHT ³ ³
³ ³ JUST
³
³
³æ ïïïï
ç À ïïïïï Ù Ù
À æ ïïïï
ç
Ù
³
À
[ BLANK WHEN ZERO ]
[ VALUE IS literal-1 ] [ WITH LOWER BOUNDS ] .
ïïïïï
ïïïï
ïïïïï
ïïïïï ïïïïïï
Refer to “Data Description Entry Format 1” for information on the BLANK WHEN ZERO,
JUSTIFIED, LOCAL, LOWER BOUNDS, OCCURS, PICTURE, RECORD AREA, RECEIVED
BY, SIGN, STRING, SYNCHRONIZED, and USAGE clauses.

4–76

8600 1518–307

Data Description Entry Format 4: IPC

Data-Name or FILLER Clause
Refer to “Data Description Entry Format 1” for information on this clause.
In Format 4, data-name-1 must be specified for any entry that contains the GLOBAL or
EXTERNAL clause, or for record descriptions associated with a file description entry that
contains the EXTERNAL or GLOBAL clause.

COMMON Clause
Refer to “Data Description Entry Format 1” for information on this clause.
The COMMON clause cannot be specified in the same data description entry as the
EXTERNAL clause.
In addition, in Format 4, the COMMON clause can occur only at the outermost level of a
group of nested programs.
Also, the compiler option COMMON does not apply to data-items declared in the
Working-Storage Section of nested programs.

EXTERNAL Clause
The EXTERNAL clause specifies that a data item is external. The data items and group
data items of an external data record are available to every program in the run unit that
describes that record. This clause can be specified only in 01-level data description
entries in the Working-Storage Section that are described as USAGE IS DISPLAY.
Rules
Observe the following guidelines when using the EXTERNAL clause:

•

The EXTERNAL clause cannot be specified in a data description entry with the
REDEFINES, COMMON, or OWN clause.

•

Within a program, a data-name specified as the subject of a level-01 data description
entry that includes the EXTERNAL clause cannot be specified for any other data
description entry that includes the EXTERNAL clause.

•

If two or more programs in a run unit describe the same external data record, the
same record-name must appear in a record description entry in each program and
the records must define the same number of standard data format characters.

•

If a program contains a data description entry that includes the REDEFINES clause,
which redefines the complete external record, this complete redefinition need not
occur identically in other programs in the run unit (refer to “REDEFINES Clause” in
this section).

Note that use of the EXTERNAL clause does not imply that the associated data-name is a
global name. (Refer to “GLOBAL Clause” in this section.) For information on the
EXTERNAL clause, refer to “File Description Entry Format 4: IPC and Sequential I–O.”

8600 1518–307

4–77

Data Description Entry Format 4: IPC

GLOBAL Clause
Refer to “File Description Entry Format 4: IPC and Sequential I-O” for a complete
description of this clause.
Rules
The following conditions apply to the GLOBAL clause when used in Data Description
Entry Format 4:

•

This clause can be specified only in data description entries whose level-number is
01 or 77.

•

This clause specifies that a data-name is a global name. A global name is available to
every program contained within the program that declares it.

•

A data-name described using a GLOBAL clause is a global name. All data-names
subordinate to a global name are global names. All condition-names associated with
a global name are global names.

•

In the same Data Division, the data description entries for any two data items for
which the same data-name is specified must not include this clause.

•

A statement in a program that is contained directly or indirectly in a program that
describes a global name can reference that name without describing it again (refer to
“Scope of Names” in Section 10).

•

If this clause is used in a data description entry that contains the REDEFINES clause,
only the subject of that REDEFINES clause possesses the global attribute.

OWN Clause
Refer to “Data Description Entry Format 1” for a complete description of this clause.
Rules
Observe the following rules when you use the OWN clause:

4–78

•

The OWN clause can occur at any level of nested programs.

•

The OWN clause cannot be specified in the same data description entry as the
EXTERNAL clause.

•

The compiler option OWN applies to all data-items declared in the Working-Storage
Section of nested programs.

8600 1518–307

Data Description Entry Format 4: IPC

REDEFINES Clause
Refer to “Data Description Entry Format 1” for a complete description of this clause.
In Format 4, this clause and the EXTERNAL clause must not be specified in the same
data description entry.

VALUE Clause
Refer to “Data Description Entry Format 1” for a complete description of this clause.
In Format 4, the VALUE clause must not be used in any data description entry that
includes, or is subordinate to, an entry that includes the EXTERNAL clause. (The VALUE
clause can be specified for condition-name entries associated with such data description
entries.)

8600 1518–307

4–79

Data Division Header

Data Division Header
The following header identifies and must begin the Data Division:

DATA DIVISION.
ïïïï ïïïïïïïï

DATA DIVISION

These keywords begin in area A and must be followed by a period.

4–80

8600 1518–307

File Section

File Section
The File Section defines the structure of data files. Use of this section is optional.
Each file is defined by a file description entry and one or more record description entries.
Record descriptions are written immediately following each file description entry. The
format of record descriptions is described earlier in this section.
The general format of the File Section is as follows:

FILE SECTION.
ïïïï ïïïïïïï
[ file description entry

{ record description entry } ... ] ...

FILE SECTION

These keywords begin in area A and must be followed by a period.
file description entry

A file description entry associates a file-name with a file connector.

Format

Use

Format 1

This format provides information on the physical structure, identification,
and record-names that pertain to a sequential file.

Format 2

This format provides information on the physical structure, identification,
and record-names that pertain to a relative or indexed file.

Format 3

This format provides information on the physical structure and recordnames that pertain to a sort or merge file.

Format 4

This format is used for interprogram communication and sequential I-O.
It determines the internal or external attributes of a file connector, of the
associated data records, and of the associated data items. It also
determines whether a file-name is a local name or a global name.

Format 5

This format is used for interprogram communication and relative I-O or
indexed I-O. It determines the internal or external attributes of a file
connector, of the associated data records, and of the associated data
items. It also determines whether a file-name is a local name or a global
name.

8600 1518–307

4–81

File Description Entry Format 1: Sequential I-O

File Description Entry Format 1: Sequential I-O
This format provides information on the physical structure, identification, and recordnames that pertain to a sequential file. The clauses that follow file-name-1 can appear in
any order. They are described on the following pages in alphabetical order.

4–82

8600 1518–307

File Description Entry Format 1: Sequential I-O

FD file-name-1
ïï
Ú
¿
³
ä RECORDS
å ³
³ BLOCK CONTAINS [ integer-1 TO ] integer-2 ã ïïïïïïï
â ³
³ ïïïïï
ïï
æ CHARACTERS ç ³
À
Ù
Ú
³
ä CONTAINS integer-3 CHARACTERS
³
³
³
³ IS VARYING IN SIZE [ [ FROM integer-4 ]
³
³
ïïïïïïï
³
³
[ TO integer-5 ] CHARACTERS ]
³ RECORD ã
ïï
³ ïïïïïï ³
[ DEPENDING ON data-name-1 ]
³
³
ïïïïïïïïï
³
³ CONTAINS integer-6 TO integer-7 CHARACTERS
³
³
ïï
³
æ
[ DEPENDING ON data-name-8 ]
À
ïïïïïïïïï
Ú
¿
³
ä RECORD IS
å ä STANDARD å ³
³ LABEL ã ïïïïïï
â ã ïïïïïïïï â ³
³ ïïïïï æ RECORDS ARE ç æ OMITTED ç ³
À
ïïïïïïï
ïïïïïïï
Ù
Ú
¿
³
ä
å ³
³
³ mnemonic-fileIS
mnemonic-attribute³ ³
³
³
attribute-name
value
³ ³
³ ä VALUE å
³
³ ³
³ ã ïïïïï â OF ã ä alphanumeric-file- å
â ³
³ æ VA
ç ïï ³ ³
attribute-name ³
ä data-name-2 å ³ ³
³
ïï
³ ã
â IS ã
â ³ ³
³
³ ³ numeric-file³
æ literal-1
ç ³ ³
³
³ æ
attribute-name ç
³ ³
³
æ
ç ³
À
Ù
Ú
¿
³
ä RECORD IS
å
³
³ DATA ã ïïïïïï
â { data-name-3 } ... ³
³ ïïïï æ RECORDS ARE ç
³
À
ïïïïïïï
Ù
Ú
³
Ú
³
ä data-name-4 å
³
ä data-name-5 å
³ LINAGE IS ã
â LINES ³ WITH FOOTING AT ã
â
³ ïïïïïï
æ integer-8
ç
³
ïïïïïïï
æ integer-9
ç
³
À
À
Ú
³
³
³
À

ä data-name-6 å
LINES AT TOP ã
â
ïïï æ integer-10 ç
[ CODE-SET IS alphabet-name-1 ]
ïïïïïïïï

8600 1518–307

¿
³
³
³
³
³
³
³
³
³
³
³
Ù

å
³
³
³
³
â
³
³
³
³
ç

...

¿
³
³
³
Ù

¿
Ú
¿ ³
³
ä data-name-7 å ³ ³
³ LINES AT BOTTOM ã
â ³ ³
³
ïïïïïï æ integer-11 ç ³ ³
À
Ù ³
Ù

¿
³
³
³
Ù
.

4–83

File Description Entry Format 1: Sequential I-O

This level indicator identifies the beginning of a file description entry and must precede
file-name-1.
FD refers to file description.
file-name-1

This name is a user-defined word.
The clauses that follow file-name-1 can appear in any order.

BLOCK CONTAINS Clause
The BLOCK CONTAINS clause specifies the size of a physical record. This clause is
required except when one or more of the following conditions exist:

•

A physical record contains only one complete logical record.

•

The hardware device assigned to the file has only one physical record size.

•

The number of records contained in a block is specified in the operating environment.

integer-1
integer-2

If integer-1 is not specified, integer-2 represents the exact number of RECORDS or
CHARACTERS in the physical record.
If integer-1 and integer-2 are both specified, they refer to the minimum and maximum
size of the physical record, respectively.
If the associated file connector is an external file connector, all BLOCK CONTAINS
clauses in the run unit that are associated with that file connector must have the same
values for integer-1 and integer-2.
RECORDS

The size of a physical record can be stated in terms of records unless one or more of the
following conditions exists, in which case the RECORDS phrase must not be used:

•

In mass-storage files, where logical records can extend across physical records.

•

The physical record contains padding (area not contained in a logical record). Logical
records are grouped in such a manner that an inaccurate physical record size would
be implied.

When RECORDS is specified, the physical record size is considered to be integer-2
multiplied by the largest record specified for this file.

4–84

8600 1518–307

File Description Entry Format 1: Sequential I-O

CHARACTERS

If this phrase is specified, the physical record size is specified in terms of the number of
character positions required to store the physical record, regardless of the types of
characters used to represent the items in the physical record.
When CHARACTERS is specified, the physical record size is considered to be integer-2
characters.
Details
If logical records of differing sizes are grouped into one physical record, the amount of
data transferred from the record area to the physical record depends on the size of the
record named in the WRITE or REWRITE statement. In this case, the logical records are
aligned on maximum record-size boundaries. If the size of the record named does not
equal the maximum record size specified for the file, the data is transferred to the
physical record according to the rules specified for the MOVE statement without the
CORRESPONDING phrase. The sending area is considered to be a group item.
If variable-length records are specified (refer to “RECORD Clause” in this section), then
the physical record size is determined as follows:

If . . . is specified in the
BLOCK CONTAINS clause

Then the physical record size equals . . .

Integer-2 RECORDS

Integer-2 multiplied by the maximum record size.

Integer-1 and integer-2
RECORDS

Either integer-1 multiplied by the maximum record
size or integer-2 multiplied by the minimum record
size, whichever is larger.

CHARACTERS

Either integer-2 or the maximum record size,
whichever is larger. If the maximum record size is
larger, a warning is issued. (Integer-1 is shown for
documentation purposes only.)

8600 1518–307

4–85

File Description Entry Format 1: Sequential I-O

CODE-SET Clause
This clause specifies the character code set used to represent data on the external
media.
If this clause is specified, alphabet-name-1 specifies the algorithm for converting the
character codes on the external media to or from EBCDIC during the execution of an
input or output operation.
If this clause is not specified, the native character code set (EBCDIC) is assumed for data
on the external media.
If this clause is specified for a file, all data in that file must be described as USAGE IS
DISPLAY, and any signed numeric data must be described with the SIGN IS SEPARATE
clause (refer to “Data Description Entry Format 1” for descriptions of the USAGE and
SIGN clauses).
alphabet-name-1

This name is a user-defined word.
The alphabet-name clause referred to by the CODE-SET clause must not specify the
literal phrase (refer to the “ALPHABET Clause” in Section 3).
If the CODE-SET clause is specified, upon successful execution of an OPEN statement,
the character set used to represent the data on the external media is the one referred to
by alphabet-name-1 in the file description entry associated with the file-name specified in
the OPEN statement.
Details
If the associated file connector is an external file connector, all CODE-SET clauses in the
run unit that are associated with that file connector must have the same character set.

4–86

8600 1518–307

File Description Entry Format 1: Sequential I-O

DATA RECORDS Clause
This clause serves only as documentation for the names of data records in their
associated file.
The DATA RECORDS clause is an obsolete element in COBOL ANSI-85 and will be
deleted from the next revision of standard COBOL.
data-name-3

This name is a user-defined word.
This is the name of a data record that must have a level-01 record description (with the
same name) associated with it.
The presence of more than one data-name indicates that the file contains more than one
type of data record. These records can be different in size, format, and so forth. The
order in which they are listed is not significant.
Details
Conceptually, all data records in a file share the same area, even if more than one type of
data record is present in the file.

LABEL RECORDS Clause
This clause specifies the presence or absence of label information.
If this clause is not specified for a file, STANDARD is assumed.
The LABEL RECORDS clause is an obsolete element in COBOL ANSI-85 and will be
deleted from the next revision of standard COBOL.
STANDARD

This specifies that labels exist for the file or the device to which the file is assigned and
that the labels conform to the standard label specifications. STANDARD should be used if
you wish to take advantage of the automatic file allocation and handling procedures in
the operating system. (Note that disk devices maintain a directory instead of a system of
labels.) The format of labels depends on the device containing the file. (Refer to the I/O
Subsystem Programming Guide for label formats.)
OMITTED

OMITTED must be used if an input file does not have standard labels or if labels are not
desired on output files.

8600 1518–307

4–87

File Description Entry Format 1: Sequential I-O

Details
If the file connector associated with this file description entry is an external file connector
(refer to the “EXTERNAL Clause” in this section, and to “File Connectors” in Section 10),
all LABEL RECORDS clauses in the run unit associated with that file connector must
have the same specification.

LINAGE Clause
This clause specifies the size of a logical page according to the number of lines. It also
specifies the size of the top and bottom margins on the logical page, and the line
number, at which the footing area begins in the page body. (The terms logical page and
page body are defined under the paragraph headed “Details,” which follows the
description of syntax elements.)
data-name-4
integer-8

Integer-8 or the value of the data item referred to by data-name-4 specifies the number
of lines that can be written and/or spaced on the logical page. The value must be greater
than zero. The part of the logical page in which these lines can be written and/or spaced
is called the page body.
At the time an OPEN statement with the OUTPUT phrase is executed for the file, either
integer-8 or the value of the data item referred to by data-name-4, whichever is specified,
is used to specify the number of lines that will make up the page body for the first logical
page.
At the time a WRITE statement with the ADVANCING PAGE phrase is executed or a
page overflow condition occurs, the value of the data item referred to by data-name-4, if
specified, is used to define the page body for the next logical page.
FOOTING

This phrase specifies the line number in the page body at which the footing area begins.
If this phrase is not specified, the assumed value is equal to integer-8 or the contents of
the data item referred to by data-name-4, whichever is specified.

4–88

8600 1518–307

File Description Entry Format 1: Sequential I-O

data-name-5
integer-9

Integer-9 or the value of the data item referred to by data-name-5 specifies the line
number in the page body at which the footing area begins. The value must be greater
than zero and less than or equal to integer-8 or the value of the data item referred to by
data-name-4.
Integer-9 must not be greater than integer-8.
At the time an OPEN statement with the OUTPUT phrase is executed for the file, either
integer-9 or the value of the data item referred to by data-name-5, whichever is specified,
is used to specify the number of lines that will make up the footing area for the first
logical page.
At the time a WRITE statement with the ADVANCING PAGE phrase is executed or a
page overflow condition occurs, the value of the data item referred to by data-name-5, if
specified, is used to define the footing area for the next logical page.
LINES AT TOP

This phrase specifies the number of lines that make up the top margin on the logical
page.
If this phrase is not specified, the value for this function is zero.
data-name-6
integer-10

Integer-10 or the value of the data item referred to by data-name-6 specifies the number
of lines that make up the top margin on the logical page. This value can be zero.
At the time an OPEN statement with the OUTPUT phrase is executed for the file, either
integer-10 or the value of the data item referred to by data-name-6, whichever is
specified, is used to specify the number of lines that will make up the top margin for the
first logical page.
At the time a WRITE statement with the ADVANCING PAGE phrase is executed or a
page overflow condition occurs, the value of the data item referred to by data-name-6, if
specified, is used to define the top margin for the next logical page.
LINES AT BOTTOM

This phrase specifies the number of lines that make up the bottom margin on the logical
page.
If this phrase is not specified, the value for this function is zero.

8600 1518–307

4–89

File Description Entry Format 1: Sequential I-O

data-name-7
integer-11

Integer-11 or the value of the data item referred to by data-name-7 specifies the number
of lines that make up the bottom margin on the logical page. This value can be zero.
At the time an OPEN statement with the OUTPUT phrase is executed for the file, either
integer-11 or the value of the data item referred to by data-name-7, whichever is
specified, is used to specify the number of lines that will make up the bottom margin for
the first logical page.
At the time a WRITE statement with the ADVANCING PAGE phrase is executed or a
page overflow condition occurs, the value of the data item referred to by data-name-7, if
specified, is used to define the bottom margin for the next logical page.
Details
The data-names used in this clause must refer to elementary unsigned numeric integer
data items. All of the data-names can be qualified.
The logical page size is the sum of the values referred to by each phrase except the
FOOTING phrase. Each logical page is contiguous to the next, and additional spacing is
not provided.
Note that there is not necessarily a relationship between the size of the logical page and
the size of a physical page.
The part of the logical page in which the lines can be written and/or spaced is called the
page body.
The footing area is made up of the area of the page body between the line represented
by integer-9 or the value of the data item referred to by data-name-5 and the line
represented by integer-8 or the value of the data item referred to by data-name-4,
inclusive.
If the file connector associated with this file description entry is an external file
connector, all file description entries in the run unit that are associated with this file
connector must have the following:

•

A LINAGE clause, if any file description entry has a LINAGE clause

•

The same corresponding values for integer-1, integer-2, integer-3, and integer-4, if
specified

•

The same corresponding external data items referred to by data-name-1,
data-name-2, data-name-3, and data-name-4

A separate LINAGE-COUNTER register is generated for each file whose file description
entry contains a LINAGE clause. Because more than one LINAGE-COUNTER can exist in
a program, you must qualify LINAGE-COUNTER by file-name when necessary (refer to
Format 4 under “Qualification” in this section). You can refer to a LINAGE-COUNTER
only in Procedure Division statements.

4–90

8600 1518–307

File Description Entry Format 1: Sequential I-O

The value in the LINAGE-COUNTER at any given time represents the line number at
which the device is positioned in the current page body. Only the input-output control
system can change the value of the LINAGE-COUNTER.

•

When an OPEN statement with the OUTPUT phrase is executed for a file, the value
of LINAGE-COUNTER is automatically set to 1.

•

When a WRITE statement is executed, LINAGE-COUNTER is automatically modified
according to the rules in the following table:

If the . . .

Then the LINAGE-COUNTER . . .

ADVANCING PAGE phrase of the WRITE
statement is specified.

Is automatically reset to 1.

ADVANCING identifier-2 or integer-1
phrase of the WRITE statement is
specified.

Is incremented by integer-1 or the value of
the data item referred to by identifier-2.

ADVANCING phrase of the WRITE
statement is not specified.

Is incremented by the value 1.

Device is repositioned to the first line that
can be written on for each of the
succeeding logical pages.

Is automatically reset to 1.

During the resetting of the LINAGECOUNTER to the value 1, the value of
LINAGE-COUNTER is implicitly incremented
to exceed the value specified by integer-1 or
the data item referred to by data-name-1.

RECORD Clause
The RECORD clause specifies the number of character positions in a fixed-length record
or the range of character positions in a variable-length record. If the number of character
positions varies, you can specify the minimum and maximum number of character
positions.
If the RECORD clause is omitted, the record-description entry completely defines the
size of each record, and the file is considered to have fixed-length records. When
multiple record-description entries are associated with this file, the record size for the file
is that of the largest record-description entry. The other record descriptions merely
represent a redefinition of the same memory area. As a result, each READ or WRITE
statement for the file uses the full length of the record for data transfer.
There are three forms of the RECORD clause: the RECORD CONTAINS integer-3
CHARACTERS clause, the RECORD IS VARYING IN SIZE clause, and the RECORD
CONTAINS integer-6 TO integer-7 clause.
RECORD CONTAINS integer-3 CHARACTERS

This form of the RECORD clause enables you to specify fixed-length records.

8600 1518–307

4–91

File Description Entry Format 1: Sequential I-O

integer-3

This integer represents the exact number of character positions contained in each record
of the file.
An error message is issued if the number of character positions specified by integer-3
does not match the record description entry.
RECORD IS VARYING IN SIZE

This form of the RECORD clause enables you to specify variable-length records.
integer-4

This integer specifies the minimum number of character positions that can be contained
in any record of the file.
If this integer is not specified, the minimum number of character positions to be
contained in any record of the file is equal to the least number of character positions
described for a record in that file.
integer-5

This integer specifies the maximum number of character positions in any record of the
file.
If this integer is not specified, the maximum number of character positions to be
contained in any record of the file equals the greatest number of character positions
described for a record in that file.
data-name-1

This name is a user-defined word. Data-name-1 can be qualified.
The number of character positions associated with a record description is determined by
the sum of the number of character positions in all elementary data items excluding
redefinitions and renamings, plus any implicit FILLER due to synchronization. If a table is
specified,

•

The minimum number of table elements described in the record is used in the
summation to determine the minimum number of character positions associated
with the record description.

•

The maximum number of table elements described in the record is used in the
summation to determine the maximum number of character positions associated
with the record description.
The contents of the data item referred to by data-name-1 and the number of
character positions in the record depend upon whether data-name-1 is specified in
the RECORD clause, as described in the following tables.

4–92

8600 1518–307

File Description Entry Format 1: Sequential I-O

If data-name-1 is specified in the
RECORD clause and . . .

Then . . .

A RELEASE, REWRITE, or WRITE
statement has not yet been executed for
the file.

The number of character positions in the
record must be placed into the data item
referred to by data-name-1 before any
RELEASE, REWRITE, or WRITE statement
is executed for the file.

A DELETE, RELEASE, REWRITE, START,
or WRITE statement has been executed
for the file.

The content of the data item referred to by
data-name-1 is not altered.

A READ or RETURN statement has been
unsuccessfully executed for the file.

The content of the data item referred to by
data-name-1 is not altered.

A READ or RETURN statement has been
successfully executed for the file.

The content of the data item referred to by
data-name-1 indicates the number of
character positions in the record just read.

A RELEASE, REWRITE, or WRITE
statement is being executed for the file.

The number of character positions in the
record is determined by the content of the
data item referred to by data-name-1.

The INTO phrase is specified in the READ
or RETURN statement.

The number of character positions in the
current record that participate as the
sending data items in the implicit MOVE
statement is determined by the content of
the data item referred to in data-name-1.

If data-name-1 is not specified in the
RECORD clause and . . .

Then . . .

The record does not contain a variableoccurrence data item.

The number of character positions in the
record is determined by the number of
character positions in the record.

The record contains a variable-occurrence
data item.

The number of character positions in the
record is determined by the sum of the
fixed portion and that portion of the table
described by the number of occurrences at
the time of execution of the output
statement.

The INTO phrase is specified in the READ
or RETURN statement.

The number of character positions in the
current record that participate as the
sending data items in the implicit MOVE
statement is determined by the value that
would have been moved into the data item
referred to in data-name-1 if data-name-1
had been specified.

8600 1518–307

4–93

File Description Entry Format 1: Sequential I-O

RECORD CONTAINS integer-6 TO integer-7 CHARACTERS [DEPENDING ON dataname-8]

This form of the RECORD clause enables you to specify the minimum and maximum
number of character positions when the number of character positions varies. In this
case, the logical records have variable lengths.
integer-6

This integer refers to the minimum number of characters in the smallest size data record.
integer-7

This integer refers to the maximum number of characters in the largest size data record.
data-name-8

Data-name-8 is a user-defined word that can be qualified.
Special Considerations for Sequential Files
The use of data-name-8 determines the BLOCKSTRUCTURE of the declared file. When
data-name-8 is omitted from the RECORD CONTAINS clause or when it is internal to the
record description of a file, the default is the same as that of data-name-1 as described
earlier in this section. When data-name-8 is external to the record descriptions for a file,
the file uses the BLOCKSTRUCTURE = EXTERNAL statement.

Details
How Record Size Is Determined
In this form of the RECORD clause, the size of each data record is completely defined in
the record description entry. The size of each data record is specified according to the
number of character positions required to store the logical record, regardless of the types
of characters used to represent the items in the logical record.
The size of a record is determined by the sum of the number of characters in all fixedlength elementary items plus the sum of the maximum number of characters in any
variable-length item subordinate to the record. This sum might be different from the
actual size of the record (refer to “SYNCHRONIZED Clause” and “USAGE Clause” in this
section). The size of the record is part of the record when the type of the file is DISK OR
TAPE, but is not written if the file is PORT, PRINTER, or READER.
External File Connectors
If the associated file connector is an external file connector, all file description entries in
the run unit that are associated with that file connector must specify the same values for
integer-3 in the RECORD CONTAINS clause or integer-4 and integer-5 in the RECORD IS
VARYING clause. If a RECORD clause is not specified, all record description entries
associated with the file connector must be the same length.

4–94

8600 1518–307

File Description Entry Format 1: Sequential I-O

Special Considerations for Relative and Indexed Files
The FROM integer-4 clause and the integer-6 TO clause are ignored for indexed or
relative files unless the ANSI compiler control option has been set prior to the file
description (FD) entry for the file. Only fixed length record files are created for indexed or
relative files unless the ANSI compiler control option has been set. Specifying variable
length records for indexed or relative files when the ANSI compiler control option is set
makes these files incompatible with files created or retrieved through programs compiled
with COBOL74. The DEPENDING ON clause is not allowed for indexed or relative files
unless the ANSI compiler control option has been set prior to the file description (FD)
entry for the file.
Special Considerations for Sequential Files
Data-name-1 of the DEPENDING phrase influences the file type of the file to which it
applies, when it is a field internal to the file. Generally a BLOCKSTRUCTURE = VARIABLE
file is created when the data item is a display numeric which occupies the first four
characters of the record. Should the internal length field be elsewhere in the record or be
of a different size, then a BLOCKSTRUCTURE = VARIABLEOFFSET file is created, with
the supporting attributes SIZE2, SIZEOFFSET and SIZEMODE set accordingly. Should a
single or double-word data item, which is used as the internal length field of the record,
start on a character boundary, the resulting file will have BLOCKSTRUCTURE =
EXTERNAL. Any other use of a double-word data item as an internal length field is invalid.

VALUE OF Clause
This clause defines the initial values for the attributes of a file.
The descriptive clauses and phrases of the Input-Output Section and the file record
descriptions (other than the VALUE OF clause) implicitly determine the initial values for
appropriate attributes of a file. These attribute values, however, can be overridden, or
other attributes can be specified, by the VALUE OF clause.
File attributes provide access to functions not otherwise available within the language.
Also, file attributes can be used to declare and access files. When both a file attribute
and standard COBOL syntax are available to accomplish a desired function, it is always
preferable to use the standard COBOL syntax, because changing the attribute can lead to
unexpected results in cases when the attribute is also used or altered by the compiler.
Refer to the I/O Subsystem Programming Guide for a description of available attributes
and their values.
Note: The VALUE OF clause is an obsolete element in COBOL ANSI-85 and will be
deleted from the next revision of standard COBOL. Unisys, however, will continue to
support this element as an extension to the COBOL language.
VALUE
VA

These keywords are equivalent.

8600 1518–307

4–95

File Description Entry Format 1: Sequential I-O

mnemonic-attribute-value

This value must be associated with the attribute specified.
alphanumeric-file-attribute-name

If this is specified, the literal must be a nonnumeric literal, and the identifier must be a
nonnumeric DISPLAY data item. Additionally, the contents of the data-name must be
ended by a period.
numeric-file-attribute-name

If this is specified, the literal must be a numeric literal, and the identifier must be a
numeric data item that represents an integer.
data-name-2

This name is a user-defined word.
This data-name should be qualified when necessary, but it cannot be subscripted, nor
can it be described with the USAGE IS INDEX clause.
This data-name must be in the Working-Storage Section.
When an attribute is equated to the value of this data-name, the attribute is implicitly
changed to this value just prior to execution of any explicit OPEN, SORT, or MERGE
statement that refers to the file.
literal-1

When an attribute is equated to the value of this literal, the value becomes a part of the
file description given by the file when first referred to at run time. Any specification in
this file description can be overridden by a file-equation.
Details
If the associated file connector is an external file connector, all VALUE OF clauses in the
run unit that are associated with that file connector must be consistent.
File titles must not contain special characters.
Using data-name-2 in file descriptions for port files is not recommended if your program
specifies that subfiles will be opened independently and remain open simultaneously.
The compiler explicitly sets all dynamic attributes for the entire file on each OPEN
statement. The MCP will reject an OPEN statement for a subport of a file if any other
subport of the file is open and the file declaration contains a dynamic file attribute that is
permitted to be modified only when the file is closed.

4–96

8600 1518–307

File Description Entry Format 1: Sequential I-O

You should use the CHANGE statement to dynamically change attributes of port files
that have multiple subfiles explicitly opened. Note that the CHANGE statement must be
executed while the port file is closed. Refer to “CHANGE Statement” in Section 6 for
more information.
This restriction does not apply if your program opens the entire port file; if your program
has only one subfile of a port open at any given time; or if there is no limitation on when
a particular file attribute can be modified. For information on port files, refer to Section
12.

Examples
FD

SEQ-FILE
BLOCK CONTAINS 10 RECORDS
VALUE OF FILENAME IS "MASTER"
DATA RECORDS ARE PRIMARY SECONDARY.

This file description entry defines a file with an internal file name of SEQ-FILE, and an
external file name of MASTER. Each logical block of the file contains 10 physical file
records. The records are identified as PRIMARY and SECONDARY for documentation
purposes.
FD

PFILE
LINAGE IS 40 LINES
LINES AT TOP
5
LINES AT BOTTOM 15.

This file description entry defines a file with an internal file name of PFILE. The logical
page associated with PFILE is 40 lines in length with a top margin of 5 lines and a bottom
margin of 15 lines.

8600 1518–307

4–97

File Description Entry Format 2: Relative I-O, Indexed I-O

File Description Entry Format 2: Relative I-O,
Indexed I-O
This format provides information on the physical structure, identification, and recordnames that pertain to a relative file or an indexed file.
FD file-name-1
ïï
Ú
¿
³
ä RECORDS
å ³
³ BLOCK CONTAINS [ integer-1 TO ] integer-2 ã ïïïïïïï
â ³
³ ïïïïï
ïï
æ CHARACTERS ç ³
À
Ù
Ú
¿
³
ä CONTAINS integer-3 CHARACTERS
å ³
³
³
³ ³
³
³ IS VARYING IN SIZE [ [ FROM integer-4 ]
³ ³
³
³
ïïïïïïï
³ ³
³ RECORD ã
[ TO integer-5 ] CHARACTERS ] â ³
³ ïïïïïï ³
ïï
³ ³
³
³
[ DEPENDING ON data-name-1 ]
³ ³
³
³
ïïïïïïïïï
³ ³
³
æ CONTAINS integer-6 TO integer-7 CHARACTERS
ç ³
À
ïï
Ù
Ú
¿
³
ä RECORD IS
å ä STANDARD å ³
³ LABEL ã ïïïïïï
â ã ïïïïïïïï â ³
³ ïïïïï æ RECORDS ARE ç æ OMITTED ç ³
À
ïïïïïïï
ïïïïïïï
Ù
Ú
³
³
³
³
³
³
³
³
³
³
À
Ú
³
³
³
À

ä VALUE å
ã ïïïïï â
æ VA
ç
ïï

DATA
ïïïï

OF
ïï

ä
³ mnemonic-fileIS
³
attribute-name
³
ã ä alphanumeric-file³ ³
attribute-name
³ ã
³ ³ numeric-file³ æ
attribute-name
æ

mnemonic-attributevalue
å
³
ä data-name-2 å
â IS ã
â
³
æ literal-1
ç
ç

ä RECORD IS
å
ã ïïïïïï
â { data-name-3 } ...
æ RECORDS ARE ç
ïïïïïïï

¿
³
³
³
Ù

å
³
³
³
â
³
³
³
³
ç

¿
³
³
³
³
³
³
³
³
Ù

...

Refer to “File Description Entry Format 1: Sequential I-O” for information on the DATA
RECORDS, LABEL RECORDS, RECORD, and VALUE OF clauses.

4–98

8600 1518–307

File Description Entry Format 2: Relative I-O, Indexed I-O

This level indicator identifies the beginning of a file description entry and must precede
file-name-1. FD refers to file description.
file-name-1

This name is a user-defined word. The clauses that follow file-name-1 can appear in any
order.

BLOCK CONTAINS Clause
Refer to “File Description Entry Format 1: Sequential I-O” for a complete description of
this clause.
In this format (in the case of relative file organization) the physical record size is adjusted
by the I/O subsystem to be integer-2 multiplied by six bytes larger than what would be
determined by the methods stated in the BLOCK CONTAINS clause in “File Description
Entry Format 1: Sequential I-O.”
Examples
FD

REL-FILE
BLOCK CONTAINS 2 RECORDS
LABEL RECORD IS STANDARD
VALUE OF AREAS IS 10
AREASIZE IS 1000
DATA RECORDS ARE PRODUCT, PRODUCT-PART.

This file description entry defines a file with an internal file name of REL-FILE. Each
logical block of the file contains 2 physical file records. The file attributes AREAS and
AREASIZE associated with REL-FILE are assigned the values 10 and 1000, respectively.
The records are identified as PRODUCT and PRODUCT-PART for documentation
purposes.
FD

INDX-FILE
BLOCK CONTAINS 10 RECORDS
DATA RECORD IS ACCOUNT.

This file description entry defines a file with an internal file name of INDX-FILE. Each
logical block of the file contains 10 physical file records. The record is identified as
ACCOUNT for documentation purposes.
FD

CUSTOMER-FILE
BLOCK CONTAINS 40 TO 60
RECORD IS VARYING IN SIZE
DEPENDING ON SIZE-VARIABLE.

This file description entry defines a file with an internal file name of CUSTOMER-FILE.
Each logical block of the file contains between 40 and 60 physical file records. The
records are variable length with the record length of each record stored in the variable
SIZE-VARIABLE.

8600 1518–307

4–99

File Description Entry Format 2: Relative I-O, Indexed I-O

Variable Length Records
To provide the capability of variable length records, the compiler takes advantage of the
I/O system implementation of files that have the following attributes:
BLOCKSTRUCTURE=VARIABLE
FILESTRUCTURE=STREAM
UNITS=CHARACTERS
FILEORGANIZATION=RELATIVE
Although this is declared as a variable length record implementation, the I/O system
actually maintains a fixed block and record size, where the length of each record is at
least the length of the declared MAXRECSIZE value. For this reason, processor execution
time, I/O transfer time and disk sector space requirements are larger than expected for
files that have an average record size that is less than the declared MAXRECSIZE.
If the DEPENDING data-name is the leading 4–byte field of one of the record description
entries for the file, the system sets the SIZEVISIBLE attribute to TRUE and maintains the
length in the field. If the DEPENDING data-name is not a part of the record described for
the file, SIZEVISIBLE is set to FALSE and the system maintains the length. In either
case, before performing a WRITE or REWRITE operation, the intended record length
must be programmatically established in the DEPENDING data-name. In the case of a
READ followed by a REWRITE, the READ statement automatically returns the record
length into the DEPENDING data-name.
Note that the DEPENDING clause is not available for indexed files.

4–100

8600 1518–307

File Description Entry Format 3: Sort-Merge

File Description Entry Format 3: Sort-Merge
This format provides information on the physical structure and record-names that pertain
to a sort or merge file.
SD file-name-1
ïï
Ú
¿
³
ä CONTAINS integer-1 CHARACTERS
å ³
³
³
³ ³
³
³ IS VARYING IN SIZE [ [ FROM integer-2 ]
³ ³
³
³
ïïïïïïï
³ ³
³ RECORD ã
[ TO integer-3 ] CHARACTERS ] â ³
³ ïïïïïï ³
ïï
³ ³
³
³
[ DEPENDING ON data-name-1 ]
³ ³
³
³
ïïïïïïïïï
³ ³
³
æ CONTAINS integer-4 TO integer-5 CHARACTERS
ç ³
À
ïï
Ù
Ú
³
³ DATA
³ ïïïï
À

ä RECORD IS
å
ã ïïïïïï
â { data-name-2 } ...
æ RECORDS ARE ç
ïïïïïïï

¿
³
³
³
Ù

This level indicator identifies the beginning of a sort-merge file description entry and
must precede file-name-1.
SD refers to sort-merge description.
Note that one or more record description entries must follow the sort-merge file
description entry. However, input-output statements (except RELEASE and RETURN)
cannot be executed for this sort or merge file.
file-name-1

This name is a user-defined word.
The clauses that follow file-name-1 can appear in any order.

8600 1518–307

4–101

File Description Entry Format 3: Sort-Merge

DATA RECORDS Clause
Refer to “File Description Entry Format 1: Sequential I-O” for a complete description of
this clause.
Note that information about data-name-3 in Format 1 applies to data-name-2 in this
format.

RECORD Clause
Refer to “File Description Entry Format 1: Sequential I-O” for a complete description of
this clause.
Note that information about integer-3, integer-4, integer-5, integer-6, and integer-7 in
Format 1 applies to integer-1, integer-2, integer-3, integer-4, and integer-5, respectively,
in this format.
Example
SD

SORT-FILE
RECORD CONTAINS 200 CHARACTERS
DATA RECORD IS SORT-RECORD.

This sort-merge file description entry defines a file with an internal file name of SORTFILE. Each record of the file contains 200 characters. The record is identified as SORTRECORD for documentation purposes.

4–102

8600 1518–307

File Description Entry Format 4: IPC and Sequential I-O

File Description Entry Format 4: IPC and Sequential
I-O
This format is used for interprogram communication (IPC) and sequential I-O. This format
determines the internal or external attributes of a file connector, of the associated data
records, and of the associated data items. It also determines whether a file-name is a
local name or a global name. Refer to the diagram on the following page.

8600 1518–307

4–103

File Description Entry Format 4: IPC and Sequential I-O

FD file-name-1
ïï
[ IS EXTERNAL ]
ïïïïïïïï
[ IS GLOBAL ]
ïïïïïï
Ú
¿
³
ä RECORDS
å ³
³ BLOCK CONTAINS [ integer-1 TO ] integer-2 ã ïïïïïïï
â ³
³ ïïïïï
ïï
æ CHARACTERS ç ³
À
Ù
Ú
¿
³
ä CONTAINS integer-3 CHARACTERS
å ³
³
³
³ ³
³
³ IS VARYING IN SIZE [ [ FROM integer-4 ]
³ ³
³
³
ïïïïïïï
³ ³
³ RECORD ã
[ TO integer-5 ] CHARACTERS ] â ³
³ ïïïïïï ³
ïï
³ ³
³
³
[ DEPENDING ON data-name-1 ]
³ ³
³
³
ïïïïïïïïï
³ ³
³
æ CONTAINS integer-6 TO integer-7 CHARACTERS
ç ³
À
ïï
Ù
Ú
¿
³
ä RECORD IS
å ä STANDARD å ³
³ LABEL ã ïïïïïï
â ã ïïïïïïïï â ³
³ ïïïïï æ RECORDS ARE ç æ OMITTED ç ³
À
ïïïïïïï
ïïïïïïï
Ù
Ú
¿
³
ä
å ³
³
³ mnemonic-fileIS
mnemonic-attribute³ ³
³
³
attribute-name
value
³ ³
³ ä VALUE å
³
³ ³
³ ã ïïïïï â OF ã ä alphanumeric-file- å
â ³ ...
³ æ VA
ç ïï ³ ³
attribute-name ³
ä data-name-2 å ³ ³
³
ïï
³ ã
â IS ã
â ³ ³
³
³ ³ numeric-file³
æ literal-1
ç ³ ³
³
³ æ
attribute-name ç
³ ³
³
æ
ç ³
À
Ù
Ú
¿
³
ä RECORD IS
å
³
³ DATA
ã ïïïïïï
â
{ data-name-3 }
... ³
³ ïïïï
æ RECORDS ARE ç
³
À
ïïïïïïï
Ù
Ú
³
Ú
¿
³
ä data-name-4 å
³
ä data-name-5 å ³
³ LINAGE IS ã
â LINES ³ WITH FOOTING AT ã
â ³
³ ïïïïïï
æ integer-8
ç
³
ïïïïïïï
æ integer-9
ç ³
³
À
Ù
À
¿
Ú
¿ Ú
¿ ³
³
ä data-name-6 å ³ ³
ä data-name-7 å ³ ³
³ LINES AT TOP ã
â ³ ³ LINES AT BOTTOM ã
â ³ ³
³
ïïï æ integer-10 ç ³ ³
ïïïïïï æ integer-11 ç ³ ³
À
Ù À
Ù ³
Ù
[ CODE-SET IS alphabet-name-1 ] .
ïïïïïïïï

4–104

8600 1518–307

File Description Entry Format 4: IPC and Sequential I-O

Refer to “File Description Entry Format 1: Sequential I-O” for information on the BLOCK
CONTAINS, RECORD, LABEL RECORDS, VALUE OF, DATA RECORDS, LINAGE, and
CODE-SET clauses.
FD

This level indicator identifies the beginning of a file description entry and must precede
file-name-1.
FD refers to file description.
file-name-1

This name is a user-defined word.
The clauses that follow file-name-1 can appear in any order.

EXTERNAL Clause
In this format, this clause specifies that a file connector is external. The subordinate data
items and group data items of an external data record are available to every program in
the run unit that describes that record.
This clause can be specified only in file description entries in the File Section when used
for interprogram communication.
If the file description entry contains the LINAGE clause and the EXTERNAL clause, the
LINAGE-COUNTER data item is an external data item.
The file connector associated with this file description entry is an external file connector.
Note that use of the EXTERNAL clause does not imply that the associated file-name is a
global name. (Refer to the GLOBAL Clause in this section.)

GLOBAL Clause
In this format, this clause specifies that a file-name is a global name. A global name is
available to every program contained within the program that declares it. A statement in
a program contained directly or indirectly within a program that describes a global name
can refer to that name without describing it again (refer to “Scope of Names” in
Section 10).
This clause can be specified only in file description entries.
If the file description entry contains the LINAGE clause and the GLOBAL clause, the
special register LINAGE-COUNTER is a global name.
Note that if the SAME RECORD AREA clause is specified for several files, the filedescription entries for these files must not include the GLOBAL clause.

8600 1518–307

4–105

File Description Entry Format 4: IPC and Sequential I-O

Examples
FD

SEQ-FILE
IS EXTERNAL
BLOCK CONTAINS 20 RECORDS
RECORD CONTAINS 22 CHARACTERS
VALUE OF ACCESSMODE IS SEQUENTIAL.

This file description entry defines an external file with an internal file name of SEQ-FILE.
Each logical block of the file contains 20 physical file records, and each physical record
contains 22 characters. The file attribute ACCESSMODE associated with SEQ-FILE is
assigned the value SEQUENTIAL.
FD

SEQ-FILE
IS GLOBAL
BLOCK CONTAINS 5 RECORDS
DATA RECORD IS RECORD-NAME.

This file description entry defines a global file with an internal file name of SEQ-FILE.
Each logical block of the file contains 5 physical file records. The record is identified as
RECORD-NAME for documentation purposes.
FD

PFILE
IS EXTERNAL
LINAGE IS 30
WITH FOOTING AT 6.

This file description entry defines an external file with an internal file name of PFILE. The
logical page associated with PFILE is 30 lines in length, with the footing area beginning at
line number 6 of the page body.

4–106

8600 1518–307

File Description Entry Format 5: IPC, Relative I-O, and Indexed I-O

File Description Entry Format 5: IPC, Relative I-O,
and Indexed I-O
This format is used for interprogram communication (IPC) and relative I-O or indexed I-O.
This format determines the internal or external attributes of a file connector, of the
associated data records, and of the associated data items. It also determines whether a
file-name is a local name or a global name.
FD file-name-1
ïï
[ IS EXTERNAL ]
ïïïïïïïï
[ IS GLOBAL ]
ïïïïïï
Ú
³
³ BLOCK CONTAINS [ integer-1 TO ]
³ ïïïïï
ïï
À

¿
ä RECORDS
å ³
integer-2 ã ïïïïïïï
â ³
æ CHARACTERS ç ³
Ù

Ú
³
³
³
³
³ RECORD
³ ïïïïïï
³
³
³
À

¿
ä CONTAINS integer-3 CHARACTERS
å ³
³
³ ³
³ IS VARYING IN SIZE [ [ FROM integer-4 ]
³ ³
³
ïïïïïïï
³ ³
ã
[ TO integer-5 ] CHARACTERS ] â ³
³
ïï
³ ³
³
[ DEPENDING ON data-name-1 ]
³ ³
³
ïïïïïïïïï
³ ³
æ CONTAINS integer-6 TO integer-7 CHARACTERS
ç ³
ïï
Ù

Ú
³
³
³
À

ä RECORD IS
å ä STANDARD å
ã ïïïïïï
â ã ïïïïïïïï â
æ RECORDS ARE ç æ OMITTED ç
ïïïïïïï
ïïïïïïï

Ú
³
³
³
³
³
³
³
³
³
³
À
Ú
³
³
³
À

8600 1518–307

LABEL
ïïïïï

ä VALUE å
ã ïïïïï â
æ VA
ç
ïï

DATA
ïïïï

OF
ïï

ä
³ mnemonic-fileIS
³
attribute-name
³
ã ä alphanumeric-file³ ³
attribute-name
³ ã
³ ³ numeric-file³ æ
attribute-name
æ

¿
³
³
³
Ù

mnemonic-attributevalue
å
³
ä data-name-2 å
â IS ã
â
³
æ literal-1
ç
ç

ä RECORD IS
å
ã ïïïïïï
â { data-name-3 } ...
æ RECORDS ARE ç
ïïïïïïï

¿
³
³
³
Ù

å
³
³
³
â
³
³
³
³
ç

¿
³
³
³
³
³
³
³
³
³
³
Ù

...

4–107

File Description Entry Format 5: IPC, Relative I-O, and Indexed I-O

Refer to “File Description Entry Format 1: Sequential I-O” for information on the BLOCK
CONTAINS, RECORD, LABEL RECORDS, VALUE OF, and DATA RECORDS clauses.
Refer to “File Description Entry Format 4: IPC and Sequential I-O” for information on the
EXTERNAL and GLOBAL clauses.
FD

This level indicator identifies the beginning of a file description entry and must precede
file-name-1.
FD refers to file description.
file-name-1

This name is a user-defined word.
The clauses that follow file-name-1 can appear in any order.
Examples
FD

REL-FILE
IS GLOBAL
BLOCK CONTAINS 3 RECORDS
LABEL RECORDS ARE STANDARD.

This file description entry defines a global file with an internal file name of REL-FILE.
Each logical block of the file contains 3 physical file records.
FD

CUSTOMER-FILE
IS EXTERNAL
BLOCK CONTAINS 40 TO 60
RECORD IS VARYING IN SIZE
DEPENDING ON SIZE-VARIABLE.

This file description entry defines an external file with an internal file name of
CUSTOMER-FILE. Each logical block of the file contains between 40 and 60 physical file
records. The records are variable in length, with the record length of each record stored
in the variable SIZE-VARIABLE.
FD

INDX-FILE
IS GLOBAL
BLOCK CONTAINS 10 RECORDS
DATA RECORD IS ACCOUNT.

This file description entry defines a global file with an internal file name of INDX-FILE.
Each logical block of the file contains 10 physical file records. The record is identified as
ACCOUNT for documentation purposes.

4–108

8600 1518–307

Working-Storage Section

Working-Storage Section
The Working-Storage Section describes records and subordinate data items that are not
part of external data files, but are developed and processed internally. In addition, the
Working-Storage Section describes data items that have values assigned in the source
program that do not change during the execution of the object program. Use of this
section is optional.
The Working-Storage Section is composed of the section header and record description
entries (and/or data description entries) for noncontiguous data items.
The general format of the Working-Storage Section is as follows:

WORKING-STORAGE SECTION.
ïïïïïïïïïïïïïïïïïïïïïïï
Ú
³ 77-level description entry
³
³ record description entry
À

¿
³
³
³
Ù

...

WORKING-STORAGE SECTION

These keywords begin in area A and must be followed by a period.
77-level description entry

This is a data description entry that describes a noncontiguous data item with the levelnumber 77. Refer to “Data Description Entry Format 1” in this section for more
information about this entry.
record description entry

This is the total set of data description entries associated with a particular record. Refer
to “General Format of the File Section” in this section for more information about this
entry.
Note that a record description entry is also referred to as a record description.

8600 1518–307

4–109

Working-Storage Section

Noncontiguous Working Storage
Items and constants in working storage that do not have a hierarchical relationship to one
another do not need to be grouped into records if they do not need to be further
subdivided. Instead, they are classified and defined as noncontiguous elementary items.
Each of these items is defined in a separate data description entry that begins with the
special level-number 77.
The following data clauses are required in each data description entry:

•

Level-number 77

•

Data-name

•

The PICTURE clause or the USAGE IS INDEX clause

Other data description clauses are optional but can be used to complete the description
of the item, if necessary.

Working-Storage Records
Data elements in the Working-Storage Section that have a definite hierarchical
relationship to one another must be grouped into records according to the rules for
formation of record descriptions.
Data elements in the Working-Storage Section that do not have a hierarchical relationship
to any other data item can be described as records that are single elementary items.
All clauses used in record descriptions in the File Section can be used in record
descriptions in the Working-Storage Section.

4–110

8600 1518–307

Working-Storage Section

Initial Values
The initial value of any data item in the Working-Storage Section, except an index data
item, is specified by associating the VALUE clause with the data item. The initial value of
any index data item or any data item not associated with a VALUE clause is undefined.
Example
WORKING-STORAGE
77 DISK-CONTROL
77 TOTAL-SALES
01 STATE-TABLE.
05 STATES.
10 CA
10 NEVADA
10 ORE
01 HDG-LINE.
03 FILLER
03 FILLER
03 FILLER
.
.
.

SECTION.
PIC 9(8).
PIC 9(11)

VALUE IS ZERO.

PIC 9(4).
PIC 9(4).
PIC 9(4).
PIC X(58) VALUE IS SPACES.
PIC X(11) VALUE IS "PERFORMANCE".
PIC X(51) VALUE IS SPACES.

In this example, DISK-CONTROL and TOTAL-SALES represent noncontiguous
elementary items. STATE-TABLE and HDG-LINE represent working-storage records with
subordinate entries (STATES and FILLER). This entire working-storage section describes
the records in a sales performance report.

8600 1518–307

4–111

Linkage Section

Linkage Section
The Linkage Section appears in a called program and describes data items that are
referred to by the calling program and the called program. If a data item in the Linkage
Section is accessed in a program that is not a called program, the effect is undefined.
The Linkage Section describes data that is available through the calling program, but will
be referred to in both the calling and the called program.
The Linkage Section is meaningful in a program only if both of the following are true:

•

The object program will function under the control of a CALL, PROCESS, or RUN
statement.

•

The CALL, PROCESS, or RUN statement in the calling program contains a USING
phrase.

The way that data items described in the Linkage Section of a called program correspond
to data items described in the calling program is discussed in Section 5 under “Procedure
Division Header” and in Section 6 under “CALL Statement.”
In the case of index-names, a correspondence is not established, and index-names in the
called and calling programs always refer to separate indexes.
Note: Data items defined in the Linkage Section but not referenced in a USING phrase
will be treated in the same way as other Working-Storage Section data items.
The Linkage Section consists of a section header and noncontiguous data items and/or
record description entries.
The format for the Linkage Section is as follows:

LINKAGE SECTION.
ïïïïïïïïïïïïïïïï
Ú
³ ä 77-level description entry
³ ã
³ æ record description entry
À

å
â
ç

¿
³
³
³
Ù

LINKAGE SECTION

These keywords begin in area A and must be followed by a period.

4–112

8600 1518–307

Linkage Section

77-level description entry

This is the total set of data description entries associated with a particular record. Refer
to “Record Description Entry” in this section for more information about this entry.
A record description entry is also referred to as a record description.

Noncontiguous Linkage Storage
Items in the Linkage Section that do not have a hierarchical relationship to one another
do not need to be grouped into records. Instead, they are classified and defined as
noncontiguous elementary items. Each of these items is defined in a separate data
description entry that begins with the special level-number 77.
The following data clauses are required in each data description entry:

•

Level-number 77

•

Data-name

•

The PICTURE clause or the USAGE clause

Other data description clauses are optional but can be used to complete the description
of the item, if necessary.

Linkage Records
Data elements in the Linkage Section that have a definite hierarchical relationship to one
another must be grouped into records according to the rules for the formation of record
descriptions.
Data elements in the Linkage Section that do not have a hierarchical relationship to any
other data item can be described as records that are single elementary items.

8600 1518–307

4–113

Linkage Section

Initial Values
The VALUE clause must not be specified in the Linkage Section, except in conditionname entries (level 88). Refer to “Data Description Entry Format 3: Level-88 ConditionName Entry.”
Example
IDENTIFICATION DIVISION.
PROGRAM-ID. CALLER-PROGRAM.
DATA DIVISION.
.
.
.
WORKING-STORAGE SECTION.
01 COLOR
PIC X(10).
01 LOC-SIZE PIC 99V99.
01 AMOUNT

PIC 999.

.
.
.
PROCEDURE DIVISION.
PARA-1.
CALL CALLED-PROGRAM
USING LOC-SIZE, COLOR.
.
.
.

IDENTIFICATION DIVISION.
PROGRAM-ID. CALLED-PROGRAM.
DATA DIVISION.
.
.
.
WORKING-STORAGE SECTION.
01 WS-1
PIC 99V99.
.
.
.
LINKAGE SECTION.
01 HUE
PIC X(10).
01 MY-SIZE PIC 99V99.
PROCEDURE DIVISION
USING MY-SIZE, HUE.
PARA-A.
MOVE MY-SIZE TO WS-1.
MOVE "RED" TO HUE.
EXIT PROGRAM.

The program on the left (CALLER-PROGRAM) is calling the program on the right
(CALLED-PROGRAM). The identifiers (SIZE and COLOR) that will be passed to the called
program are defined in the program that contains the CALL statement. These identifiers
correspond to MY-SIZE and HUE, which are defined in the Linkage Section of the called
program.

4–114

8600 1518–307

Local-Storage Section

Local-Storage Section
The Local-Storage Section describes data that is available through the user program, but
is referred to in both the user program and the imported library procedure. The data
descriptions in the Local-Storage Section are the formal parameters expected by
separate tasks, bound programs, or library procedures imported into the Program-Library
Section. These data descriptions are used only to perform parameter matching when the
separate task is started, when the host program and bound procedure are compared, or
when the program and library are linked. Therefore, no space is allocated in the computer
for the data described in this section. For more information on libraries, refer to
“Program-Library Section” later in this section, and to Section 11.
The Local-Storage Section is optional.
The format for the Local-Storage Section is as follows:

LOCAL-STORAGE SECTION.
ïïïïïïïïïïïïïïïïïïïïïï
LD { local-name } .
Ú
³ ä 77-level description entry
³ ã
³ æ record description entry
À

å
â
ç

¿
³
³
³
Ù

LOCAL-STORAGE SECTION

These keywords begin in area A and must be followed by a period.
LD

This level indicator identifies the beginning of a local-storage-description entry.
local-name

This name is a user-defined word.
77-level description entry

This is a data description entry that describes a noncontiguous data item with the levelnumber 77. Refer to “Record Description Entry” in this section for more information
about this entry.
record description entry

This is the total set of data description entries associated with a particular record. Refer
to “Record Description Entry” earlier in this section for more information about this
entry.

8600 1518–307

4–115

Local-Storage Section

Details
When an imported procedure is declared in the Program-Library Section, the LocalStorage Section must contain the data descriptions that describe the formal parameters
of that procedure. Also, the data descriptions that describe the formal parameters of
external procedures bound into the program must be placed in the Local-Storage Section.
The level indicator and its associated local-name provide a method of grouping data
descriptions under a single heading. In the declaration of the imported procedure, the
WITH clause permits specification of the local-name or local-names under which the data
descriptions of the formal parameters can be found

Noncontiguous Local-Storage
If data items in the Local-Storage Section do not have a hierarchical relationship to one
another, they do not need to be grouped into records, provided that they do not need to
be further subdivided. Instead, the data items are classified and defined as
noncontiguous elementary items. Each of these items is defined in a separate datadescription entry, beginning with the special level-number 77.
The following data clauses are required in each data description entry for a
noncontiguous elementary data item:

•

Level-number 77

•

Data-name

•

The PICTURE clause or the USAGE clause

Local-Storage Records
If data items in the Local-Storage Section have a hierarchical relationship to one another,
they must be grouped into records according to the rules for formation of record
descriptions. All clauses used in record descriptions in the File Section can be used in
record descriptions in the Local-Storage Section.

Initial Values
The VALUE clause must not be specified in the Local-Storage Section, except in
condition-name entries (level 88). Refer to “Data Description Entry Format 3: Level-88
Condition-Name Entry.”
Program-Library Section
The Program-Library Section defines the interface between a user program and a library
program.
Each library is defined by a library description entry.

4–116

8600 1518–307

Local-Storage Section

The general format of the Program-Library Section is as follows:

PROGRAM-LIBRARY SECTION.
ïïïïïïïïïïïïïïïïïïïïïïï
[ library description entry ] ...

PROGRAM-LIBRARY SECTION

These keywords begin in area A and must be followed by a period.
library description entry

A library description entry defines the interface established for a particular library.
There are two formats for the library description entry:

Format

Use

Format 1

This format provides information required to make the current program
into a library program. This format is also known as an export definition.

Format 2

This format provides information required to permit the current
program to access a library program. This format is also known as an
import definition.

8600 1518–307

4–117

Library Description Entry Format 1: Export Definition

Library Description Entry Format 1: Export
Definition
This format provides information on the directly nested programs contained in this library
that are to be exported as entry points into the library. Only the outermost program can
contain an export definition.

library-name
Ú
³
³
³
³
³
³
³
³
³
À
Ú
³
À

ATTRIBUTE
ïïïïïïïïï

EXPORT
Ú
³
³
³
³
³
³
³
À

SHARING IS
ïïïïïïï

ENTRY PROCEDURE
ïïïïïïïïïïïïïïï

ä
³
³
ã
³
³
æ

DONTCARE
ïïïïïïïï
PRIVATE
ïïïïïïï
SHAREDBYRUNUNIT
ïïïïïïïïïïïïïïï
SHAREDBYALL
ïïïïïïïïïïï

{ program-name-1 }

å
³
³
â
³
³
ç

¿
³
³
³
³
³
³
³
Ù

¿
³
³
³
³
³
³
³
³
³
Ù

[ FOR { actual-name } ]
ïïï

¿
³
Ù

This level indicator identifies the beginning of a library description entry.
library-name

This name is a user-defined name, and must be the same as the program-name defined
in the PROGRAM-ID paragraph of the current program.
EXPORT

This identifies the library description entry as an export definition. The procedures
exported by this definition are assumed to be nested programs in the current program.

4–118

8600 1518–307

Library Description Entry Format 1: Export Definition

ATTRIBUTE Clause
The ATTRIBUTE clause specifies the setting of library attributes. For an export definition,
only the SHARING attribute can be specified. The SHARING attribute controls how user
programs share access to the library. For more information, see Section 11.
DONTCARE

The operating system determines the sharing.
PRIVATE

A copy of the library is invoked for each user (calling program). Any changes made to
global items in the library by the actions of the user are visible only to that user.
SHAREDBYRUNUNIT

All invocations of the library within a run unit share the same copy of the library. A run
unit consists of a program and all libraries that are initiated either directly or indirectly by
that program.
SHAREDBYALL

All simultaneous users share the same instance of the library.

ENTRY PROCEDURE Clause
The ENTRY PROCEDURE clause defines the directly nested programs contained in this
library that are to be exported as entry points when the library “freezes” (suspends
execution and makes entry points available).
program-name

The program-name is defined in the PROGRAM-ID paragraph of a nested program to be
made available as an entry point. The program defined by program-name must be directly
nested within the program containing this Program-Library Section export definition.
FOR actual-name

The FOR phrase specifies the name of the entry point. If the FOR phrase is omitted, the
name of the entry point is program-name.
If the FOR phrase is used, the actual-name is assigned as the name of the entry point,
and is used by user programs to import the procedure. The actual-name item is a literal.

8600 1518–307

4–119

Library Description Entry Format 1: Export Definition

Details
When the library executes a library FREEZE, the entry points defined by this export
definition become available to user programs. The formal parameters of the nested
program must be declared in the Linkage Section of the nested program, and must be
specified in the Procedure Division header (with the USING and GIVING clauses) of the
exported program. The information on formal parameters ensures that the interface
provided by a user program matches the interface expected by the library procedure.
To access the programs within the library, a user program must include an import
definition in its Program-Library Section (refer to “Library Description Entry Format 2:
Import Definition” in this section).
For more information on COBOL85 libraries, refer to Section 11.

4–120

8600 1518–307

Library Description Entry Format 2: Import Definition

Library Description Entry Format 2: Import
Definition
This format provides information on the external library procedures that are imported by
this program. External library procedures are procedures (nested programs in COBOL85)
that have been exported by a library program.

LB library-name IMPORT
ïï
ïïïïïï
[ IS GLOBAL ]
ïïïïïï
[ IS COMMON ]
ïïïïïï
Ú
³ ATTRIBUTE
³ ïïïïïïïïï
³
[ FUNCTIONNAME IS { literal-1 } ]
³
ïïïïïïïïïïïï
³
Ú
¿
³
³
ä BYFUNCTION å
³
³
³ LIBACCESS IS ã ïïïïïïïïïï â
³
³
³ ïïïïïïïïï
æ BYTITLE
ç
³
³
À
ïïïïïïï
Ù
³
³
[ LIBPARAMETER IS { literal-2 } ]
³
ïïïïïïïïïïïï
³
[ TITLE IS { literal-3 } ]
À
ïïïïï
Ú
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
À

8600 1518–307

ENTRY PROCEDURE { program-name-1 }
ïïïïïïïïïïïïïïï
[ FOR { actual-name } ]
ïïï
Ú
¿
³
ä local-name
å
³
³ WITH ã
â ... ³
³ ïïïï æ file-name-1
ç
³
À
Ù
Ú
¿
³
ä data-name-1 å
³
³ USING ã
â ... ³
³ ïïïïï æ file-name-2 ç
³
À
Ù
[ GIVING
ïïïïïï

{ data-name-2 } ]

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
Ù
¿
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
Ù

...

4–121

Library Description Entry Format 2: Import Definition

This level indicator identifies the beginning of a library description entry.
library-name

This name is a user-defined name, and must be the same as the program-name defined
in the PROGRAM-ID paragraph of the library program that contains the procedures to be
imported.
IMPORT

This identifies the library description entry as an import definition. The procedures
imported by this definition must be contained in and exported by the library program
identified by library-name.
IS GLOBAL

This clause declares the imported library and its entry procedures to be global to any
programs that might be contained in this program. If an imported library and its entry
procedures are global to nested programs, those nested programs can access the
imported library without having to duplicate the import definition for the library.
IS COMMON

This clause declares the imported library and its entry procedures to be common to both
the bound program and the host program. If the IS COMMON clause is specified, the
import definition for the library is assumed to be specified in the host program.

ATTRIBUTE Clause
The ATTRIBUTE clause specifies the setting of library attributes. For an import definition,
the following library attributes can be specified. (See “Library Attributes” in Section 11).
FUNCTIONNAME

This specifies the system function name used to find the object code file for the library.
LIBACCESS

This specifies how the object code file for the library is located. LIBACCESS can be set to
the following values:

•

BYFUNCTION

The FUNCTIONNAME attribute locates the object code file for the library.

•

BYTITLE

The TITLE attribute locates the object code file.

4–122

8600 1518–307

Library Description Entry Format 2: Import Definition

LIBPARAMETER

This is used to pass information from the user program to the selection procedures of
libraries that provide entry points dynamically.
TITLE

This specifies the file title of the object code file of the library.

ENTRY PROCEDURE Clause
The ENTRY PROCEDURE clause defines the procedure or procedures to be imported
from the library identified by library-name.
program-name

This is the name of a program referenced by a CALL statement in the user program that
resides in the library identified by library-name. If the FOR clause is omitted, programname must match the name of an entry point exported by the library identified by libraryname.
FOR actual-name

The FOR clause specifies the name of the library entry point to be associated with
program-name. If the FOR clause is used, actual-name must match the name of an entry
point exported by the library identified by library-name.
WITH clause

The WITH clause specifies the LD clause in the Local-Storage Section that contains the
description of the formal parameter data referenced by this imported procedure.
The Local-Storage Section appears in a user program and describes data items referred
to by a user program and imported library procedures. Data type formal parameters must
be described under the specified local-name. A file-name formal parameter must be
defined as a LOCAL RECEIVED BY REFERENCE file in the FILE-CONTROL paragraph of
the user program. For more information, refer to “Local-Storage Section” in this section.
USING clause

The USING clause specifies the formal parameters expected by the imported procedure.
If the imported procedure is from a COBOL85 library, then the specification of the USING
clause must match the Procedure Division header of the imported program. If the
imported procedure is from a library written in another programming language, then the
specification of the USING clause must match the formal parameter declaration for the
imported procedure.
Any data parameters specified in the USING clause (data-name-1 to data-name-n) must
be declared in the Local-Storage Section of the user program. Any file parameters must
be declared as LOCAL RECEIVED BY REFERENCE files in the FILE-CONTROL paragraph
of the user program.

8600 1518–307

4–123

Library Description Entry Format 2: Import Definition

GIVING clause

The GIVING clause is valid only for imported procedures that return a result. If the
imported procedure is from a COBOL85 library, the specification of a GIVING clause
must match the GIVING clause in the Procedure Division header of the imported
program. If the imported procedure is from a library written in another programming
language, then the specification of the GIVING clause must match the formal result
declaration for the imported procedure.
The result returned by the program is identified by data-name-2, which must be declared
in the Local-Storage Section of the user program. Data-name-2 must be a NUMERIC data
item.
Details
When the library executes a library FREEZE, the entry points defined by this export
definition are made available to user programs. The information concerning formal
parameters (with the USING and GIVING clauses) is used to ensure that the interface
provided by the user program matches the interface expected by the exported library
procedure.
To access the programs in the library, a user program must include an import definition in
its Program-Library Section. Import definitions are discussed later in this section.
For more information on COBOL85 libraries, refer to Section 11.

4–124

8600 1518–307

Section 5
Procedure Division Concepts
The Procedure Division is the fourth and last division of a COBOL source program. This
division contains procedures that direct the system to perform certain actions in a given
sequence.
The Procedure Division is optional in a COBOL source program. For example, you would
not need a Procedure Division in a program that is to be nested in another program. You
could also omit the Procedure Division when compiling part of a program to check
syntax.
This section discusses the following concepts:

•

The structure of the Procedure Division

•

The general formats for the syntax of the Procedure Division

•

The elements of a procedure

•

The classifications of statements and sentences used in the Procedure Division

•

The categories of COBOL verbs

•

Information on common Procedure Division applications, such as arithmetic and
conditional expressions, table handling, and sorting and merging

For the syntax of the elements and statements that comprise the Procedure Division,
refer to Sections 6 through 8.

8600 1518–307

5–1

Structure of the Procedure Division

Structure of the Procedure Division
The Procedure Division begins with a header and can contain declarative and
nondeclarative procedures. Declarative procedures are grouped at the beginning of the
Procedure Division. The remainder of the division must consist of nondeclarative
procedures.
An end program header can be used to indicate the end of the named COBOL source
program. The end program header can be followed by a COBOL program that is to be
compiled separately in the same invocation of the compiler.
Execution begins with the first statement of the Procedure Division, excluding
declaratives. Statements are then executed in the order in which they are presented for
compilation, except where the rules indicate some other order.

General Formats
The following general formats apply to the Procedure Division and are discussed in this
section:

•

Procedure Division header format

•

Declarative procedure format

•

Nondeclarative procedure format

•

End program header format

Procedure Division Header
The following header identifies and must begin the Procedure Division:

PROCEDURE DIVISION
ïïïïïïïïï ïïïïïïïï

Ú
³
³
³
³
³
À

ä
³
USING ã
ïïïïï ³
æ
[ GIVING
ïïïïïï

5–2

data-name-1
file-name
STRING ( data-name-2 )
ïïïïïï
INTEGER ( data-name-3 )
ïïïïïïï
data-name-2 ]

å
³
â
³
ç

. . .

¿
³
³
³
³
³
Ù

8600 1518–307

General Formats

PROCEDURE DIVISION

These keywords begin in area A.
USING

The USING clause names the identifiers that are received as parameters.
The data-name in the USING clause of the Procedure Division header must be defined in
the Linkage Section of the program in which this header occurs, and it must have a 01 or
77 level-number and must not be a redefined item. If a file-name is specified, the file
must be declared as a RECEIVED BY REFERENCE file in the SELECT clause.
When the USING clause is present, the object program operates as if each identifier in
the list is replaced by the corresponding identifier from the USING clause of the CALL
statement of the calling program.
When the RECEIVED BY REFERENCE clause appears in an identifier's data description,
the corresponding identifier refers to a single set of data available to both the calling and
called program.
When the data-name is RECEIVED BY CONTENT, the invocation of the procedure will
initialize the corresponding data-name in the called program's USING clause to the
current value in the initiating program. The correspondence is positional and not by
symbolic name.
The calling program must contain a CALL, PROCESS, or RUN statement with a USING
phrase. Section 8 provides detailed information about these statements.
data-name

This identifies a data item or items that will be shared by both the calling program and
the called program.
The following rules apply to the data-name:

•

The data-name must be defined as a level-01 or level-77 entry in the Linkage Section
of the program in which this header occurs. The Linkage Section describes data to be
shared when a program is communicating with another program.

•

You cannot specify the same data-name more than once in a USING phrase.

•

The record description entry for a data-name must not contain a REDEFINES clause.

•

The description of the data item in both the calling and called program must describe
the same number of character positions.

•

The data-name in the called program and the data-name in the calling program do not
have to be the same name. Correspondence between data-names is based on the
data-name's position in the data description entry, not by name.

•

Data items in a USING phrase (data-names and file-names) are separated by a
comma.

8600 1518–307

5–3

General Formats

file-name

This identifies a file to be shared by both the calling and called program. The file must be
declared RECEIVED BY REFERENCE in the SELECT clause.
GIVING data-name-2

The GIVING clause identifies the procedure as a function that returns a value to the
calling program in data-name-2. Data-name-2 must be a numeric data item.
Details
When the USING clause in the Procedure Division header is present, the object program
operates as if each data-name in the list is replaced by the corresponding data-name
from the USING phrase of the CALL, PROCESS, or RUN statement of the calling
program.
You can refer to data items defined in the Linkage Section of the called program in the
Procedure Division of that program.
Related Information
The following table provides references for additional information related to this topic:

5–4

For information about . . .

Refer to . . .

The Linkage Section

Section 4

The REDEFINES Clause

Section 4

The Working-Storage Section

Section 4

The CALL, PROCESS, or RUN statement

Sections 6 and 7

Interprogram communication

Section 10

8600 1518–307

General Formats

Example
IDENTIFICATION DIVISION.
PROGRAM-ID. PROGA.
.
.
.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 A.
05 A1 PIC X(20).
05 A2 PIC X(20).
05 A3 PIC X(4).
01 B
PIC X(6).
01 C
PIC 9(4)V99.
.
.
.
PROCEDURE DIVISION.
.
.
.
CALL "PROGB" USING A, C.

IDENTIFICATION DIVISION.
PROGRAM-ID. PROGB.
.
.
.
DATA DIVISION.
LINKAGE SECTION.
01 Employee-Data.
05 Name
PIC X(20).
05 Title
PIC X(20).
05 Dept-no PIC X(4).
01 Hire-date
PIC X(6).
01 Salary
PIC 9(4)V99.
.
.
.
PROCEDURE DIVISION USING
Employee-Data, Salary.

The statement PROCEDURE DIVISION USING Employee-Data Salary indicates the
beginning of the Procedure Division and that the program containing this header,
PROGB, is to be called by another program. The two programs will have access to the
data in Employee-Data and Salary.
The CALL statement in PROGA contains a USING phrase.
Employee-Data and Salary are defined as level-01 items in the Linkage Section. The datanames A and C are defined as level-01 items in the Working-Storage Section.
Data-name A in PROGA corresponds to Employee-Data in PROGB; data-name C in
PROGA corresponds to Salary in PROGB.
All corresponding data-names have the same number of characters, but do not have the
same names.

8600 1518–307

5–5

General Formats

Declarative Procedure Format
Declarative procedures consist of a set of one or more special-purpose sections that are
grouped together at the beginning of the Procedure Division following the Procedure
Division header. Each declarative procedure is composed of a section header, followed
by a USE compiler-directing sentence, optionally followed by one or more associated
paragraphs. Declarative procedures can be used when special conditions, such as inputoutput errors, occur during the execution of a program.

[ DECLARATIVES.
ïïïïïïïïïïïï
{section-name SECTION.
ïïïïïïï
declarative-sentence.
[paragraph-name.
[sentence]

... ] ... }

...

END DECLARATIVES. ]
ïïïïïïïïïïïïïïïï
{section-name SECTION.
ïïïïïïï
[paragraph-name.
[sentence]

... ] ... }

...

DECLARATIVES

This keyword must appear on a line by itself, begin in area A, and be followed by a
period.
section-name

This user-defined word names a section of code. A section-name can consist of the
characters A through Z, a through z, 0 through 9, and the hyphen (-). The hyphen cannot
appear as the first or last character of the section-name.
You can use the section-name in the nondeclarative portion of this syntax in Format 7 of
the CALL statement to enter another program. Refer to the CALL statement in Section 6
for details.
paragraph-name

This user-defined word names a paragraph of code. A paragraph-name can consist of the
characters A through Z, a through z, 0 through 9, and the hyphen (-). The hyphen cannot
appear as the first or last character of the paragraph-name.

5–6

8600 1518–307

General Formats

sentence

This sentence consists of one or more compiler-directing statements and ends with a
period.
END DECLARATIVES

These keywords must appear on a line by themselves, begin in area A, and be followed
by a period (.).
The next source statement following the END DECLARATIVES statement must be a
section-name.
Details
Each declarative consists of a single section.
A SORT statement cannot appear in the DECLARATIVES section of a COBOL program.
Refer also to “USE Statement” in Section 8 for more information.
Example
IDENTIFICATION DIVISION.
PROGRAM-ID. DECL-IO-EXAMPLE.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT INPUT-FILE ASSIGN TO DISK
FILE STATUS IS INPUT-STATUS.
DATA DIVISION.
FILE SECTION.
FD INPUT-FILE
VALUE OF TITLE IS "DISK-FILE".
01 INPUT-REC PIC X(80).
WORKING-STORAGE SECTION.
77 INPUT-STATUS PIC XX.
PROCEDURE DIVISION.
DECLARATIVES.
DECL-1 SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON INPUT.
D-0010.
DISPLAY "I/O ERROR READING FILE".
DISPLAY "FILE STATUS IS" INPUT-STATUS.
STOP RUN.
END DECLARATIVES.
MAIL-1000 SECTION.
P-1010.
MOVE "00" TO INPUT-STATUS.
OPEN INPUT INPUT-FILE.
READ INPUT-FILE.
STOP RUN.

8600 1518–307

5–7

General Formats

This program illustrates the use of declaratives to handle input-output errors when
reading the file INPUT-FILE. After an input-output error has occurred, and the system's
standard retry procedures have been used, “I/O ERROR READING FILE” and “FILE
STATUS IS” with the value of INPUT-STATUS will be displayed.

Nondeclarative Procedure Format
Nondeclarative procedures comprise the main portion of a COBOL85 program. A
nondeclarative procedure consists of a paragraph-name followed by one or more
statements that make a logical unit.
Once the program is compiled and initiated, execution begins with the first statement in
the Procedure Division, excluding declaratives. Statements are then executed in the
order in which they were compiled, except where the rules indicate some other order.

{paragraph-name.
[sentence]... } ...

paragraph-name

This name is a user-defined word and can consist of the characters A through Z, a
through z, 0 through 9, and the hyphen (-). The hyphen cannot appear as the first or last
character. A paragraph-name ends with a period.
sentence

This sentence consists of one or more statements and ends with a period. The
Procedure Division statements are presented in Section 6.
Example
WRITE-PARA.
MOVE IN-NAME TO OUT-NAME
WRITE OUT-RECORD AFTER ADVANCING 2 LINES.
This example contains the paragraph-name WRITE-PARA and a sentence containing two
statements—MOVE and WRITE.

5–8

8600 1518–307

General Formats

End Program Header
The end program header indicates the end of the named COBOL source program. You
must use the end program header if the COBOL source program

•

Contains one or more other COBOL source programs.

•

Is contained in another COBOL source program.

•

Is in a sequence of programs to be separately compiled in the same invocation of the
compiler. Only the last program in the sequence would not need an end program
header.
END PROGRAM
ïïïïïïïïïïï

program-name .

END PROGRAM

The end program header begins in area A.
program-name

This name is a user-defined word and must be identical to the program-name declared in
the PROGRAM-ID paragraph of the source program's Identification Division.
A program-name must have at least one alphabetic character.
Details
If the source program does not have a Procedure Division, the end program would follow
the end of the Data Division.
Example
IDENTIFICATION DIVISION.
PROGRAM-ID. EMPFIL.
.
.
.
END PROGRAM EMPFIL.
The END PROGRAM header indicates the end of the program EMPFIL.
Refer to “IPC Examples” in Section 10 for examples of the end program header used
with a sequence of programs and nested programs.

8600 1518–307

5–9

Elements of a Procedure

Elements of a Procedure
A procedure is composed of a section, or a group of successive sections, or a paragraph,
or a group of successive paragraphs. Paragraphs can be further broken down into
sentences, statements, and verbs. Table 5–1 describes the elements that form a
procedure.
Table 5–1. Elements of a Procedure

Element

5–10

Definition

Format

Section

A section contains a
section-name followed by
a period and zero, one, or
more paragraphs. If one
paragraph is in a section,
then all paragraphs must
be in sections.

A section-name begins in area A and
must be unique throughout the
program.

Paragraph

A paragraph consists of a
paragraph-name followed
by a period and zero, one,
or more sentences.

A paragraph-name begins in area A.
The paragraph-name must be unique
within the section in which it appears.

Sentence

A sentence consists of one
or more statements and
ends with a period.

The first sentence in a paragraph
begins either on the same line as the
paragraph-name or in area B of the
next nonblank line that is not a
comment line. Successive sentences
begin in either area B of the same line
as the preceding sentence, or in area
B of the next nonblank line that is not
a comment line. When sentences
require more than one line, they can
be continued on a subsequent line or
lines.

Statement

A statement begins with a
verb and contains a
syntactically valid
combination of other
words and symbols.

Statements are positioned similarly to
sentences. For the specific format of
COBOL statements, refer to Sections
6 through 8.

Verb

A verb is a word that
indicates the way data will
be manipulated or the
actions to be taken by the
COBOL compiler or object
program.

Verbs appear in area B. Verbs are a
subset of the COBOL reserved
words. A list of COBOL reserved
words is provided in Appendix B. To
see how verbs are used in COBOL
statements, refer to Sections 6
through 8.

8600 1518–307

Elements of a Procedure

Statement Scope Terminators
Scope terminators delimit the scope of certain Procedure Division statements. The scope
of statements can be terminated either explicitly or implicitly.

Explicit Terminators
Explicit scope terminators are phrases that occur at the end of some Procedure Division
statements to indicate the end of the statement. The presence of such a terminator
indicates that the statement contains no more phrases. The explicit scope terminators
are as follows:
END-ABORT-TRANSACTION

END-FREE

END-RETURN

END-ADD

END-GENERATE

END-REWRITE

END-ASSIGN

END-IF

END-SAVE

END-BEGIN-TRANSACTION

END-INSERT

END-SEARCH

END-CALL

END-LOCK

END-SECURE

END-CANCEL-TRANSACTION

END-MODIFY

END-SET

END-CLOSE

END-MULTIPLY

END-START

END-COMPUTE

END-OF-PAGE

END-STORE

END-CREATE

END-OPEN

END-STRING

END-DELETE

END-PERFORM

END-SUBTRACT

END-DIVIDE

END-READ

END-TRANSACTION

END-END

END-RECEIVE

END-UNSTRING

END-EVALUATE

END-RECREATE

END-WRITE

END-FIND

END-REMOVE

Example
MULTIPLY RATE BY TIME GIVING DISTANCE
ON SIZE ERROR
DISPLAY "DISTANCE ERROR"
PERFORM INIT-PROCEDURE
END-MULTIPLY.
In this example, the END-MULTIPLY phrase explicitly terminates the scope of the
MULTIPLY statement.

8600 1518–307

5–11

Elements of a Procedure

Implicit Terminators
Implicit scope terminators refer to the period at the end of a sentence that terminates
the scope of all previous statements not yet terminated.
READ GFILE INTO New-Record
AT END
CLOSE GFILE
PERFORM Search-Para.
The period at the end of Search-Para implicitly terminates the scope of the READ,
CLOSE, and PERFORM statements.
A statement contained in another statement is called a nested statement. The scope of
nested statements can be implicitly terminated by the ELSE, WHEN, or NOT AT END
phrase of the containing statement.
IF Dept-No = 0113
MOVE "Sales Department" TO Print-Dept-Name
IF Emp-Name = SPACES
PERFORM Proc-2
ELSE MOVE Emp-Name TO Print-Emp-Name
ELSE PERFORM Read-Proc.
The phrase ELSE PERFORM Read-Proc implicitly terminates the scope of the two IF and
two MOVE statements. When statements are nested, the period that terminates the
sentence also implicitly terminates all nested statements.

Types of Statements and Sentences
Statements and sentences can be one of the following types:

5–12

•

Imperative, indicating a specific unconditional action to be taken by the object
program

•

Conditional, specifying that the truth value of a condition is to be determined and that
the subsequent action of the object program depends on this truth value

•

Compiler-directing, causing the compiler to take a specific action during compilation

•

Delimited scope, which is a statement that includes its explicit scope terminator

8600 1518–307

Elements of a Procedure

Imperative Statements and Sentences
An imperative statement

•

Begins with an imperative verb

•

Specifies an unconditional action to be taken by the object program

•

Is a conditional statement delimited by its explicit scope terminator (delimited scope
statement)

•

Can consist of a sequence of imperative statements, each separated from the next
by a separator

An imperative statement, when it appears as a variable in the format of a Procedure
Division statement, refers to that sequence of consecutive imperative statements that
must be ended by a period or by any phrase associated with a statement containing that
imperative statement.
An imperative sentence is an imperative statement terminated by the
separator period.
Examples
MOVE LNAME TO LNAME-PR.
The above example moves the data from the identifier LNAME to the identifier
LNAME-PR.
PERFORM PARA-1.
The above example causes the statements specified in paragraph PARA-1 to be
executed first. Then the statements immediately following this PERFORM statement will
be executed.

8600 1518–307

5–13

Elements of a Procedure

Conditional Statements and Sentences
A conditional statement specifies that the truth-value of a condition will be determined
and that the subsequent action of the object program depends on this truth value.
A conditional statement can be any one of the following:

•

An EVALUATE, IF, or SEARCH statement, or a RETURN statement that includes the
AT END phrase

•

A LOCK statement with the AT LOCKED phrase

•

A PERFORM statement with the UNTIL phrase

•

A READ statement that includes the AT END, NOT AT END, INVALID KEY, or NOT
INVALID KEY phrase

•

A WRITE statement that includes the INVALID KEY, NOT INVALID KEY, END-OFPAGE, or NOT AT END-OF-PAGE phrase

•

A START, REWRITE, or DELETE statement that includes the INVALID KEY or NOT
INVALID KEY phrase

•

An arithmetic statement (ADD, COMPUTE, DIVIDE, MULTIPLY, or SUBTRACT) that
includes the ON SIZE ERROR or NOT ON SIZE ERROR phrase

•

A STRING or UNSTRING statement that includes the ON OVERFLOW or NOT ON
OVERFLOW phrase

•

A CALL statement that includes the ON OVERFLOW, ON EXCEPTION, or NOT ON
EXCEPTION phrase

•

A SORT or MERGE statement that includes the ON ERROR phrase

Conditional expressions are fully explained in this section. COBOL statements, including
those that use conditional expressions, are explained in Sections 6 through 8.
Examples
IF A > B PERFORM PARA-1
ELSE PERFORM PARA-2.
These statements cause the statements in paragraph PARA-1 to be executed if the value
of A is greater than the value of B. If A is not greater than B, the statements in PARA-2
are executed.
ADD X, Y TO Z ON SIZE ERROR PERFORM SIZE-ERROR-PROC.
This statement adds the value of X to the value of Y and stores the result in Z. If, after
decimal point alignment, the absolute value of the result exceeds the largest value that
can be contained in Z, a size-error condition occurs. When a size-error condition occurs,
the procedures in SIZE-ERROR-PROC are executed, and the value of Z is not changed.

5–14

8600 1518–307

Elements of a Procedure

Compiler-Directing Statements and Sentences
A compiler-directing statement, which consists of a compiler-directing verb and its
operands, causes the compiler to take a specific action during compilation. The compilerdirecting verbs are COPY, REPLACE, and USE.
A compiler-directing sentence is a single compiler-directing statement terminated by a
period and followed by a space.
Examples
COPY ERROR-REC-PROC OF COB85.
This statement directs the compiler to copy the ERROR-REC-PROC portion of the library
program COB85 into the source program that contains this COPY statement. The COPY
statement is processed before the resulting source program is processed.
FILE-ERROR SECTION.
FILE1-ERROR PARA.
USE AFTER STANDARD ERROR PROCEDURE ON FILE1.
MOVE ERROR-MSG TO ERROR1
WRITE PRINT-ERROR-REC.
This example directs the compiler to follow the error-handling procedures associated
with the USE statement after it completes the standard error routine of the system.

Delimited Scope Statements
Delimited scope statements are statements that include their explicit scope terminators.
Examples
ADD A TO B GIVING C END-ADD
This example adds the value of A to the value of B, and stores the result in C. The ENDADD phrase explicitly terminates the scope of the ADD statement.
When a delimited scope statement is nested in another delimited scope statement with
the same verb, each explicit scope terminator terminates the statement begun by the
most recently preceding, and as yet unpaired, occurrence of that verb.
ADD A TO B GIVING C
SIZE ERROR
ADD A TO B GIVING OVER-SIZE END-ADD
PERFORM SIZE-ERR-PARA
END-ADD
This adds the value of A to the value of B, and stores the result in C. If the result exceeds
the size specified for C, a size error occurs, and the result of A added to B is stored in
OVER-SIZE and the procedures in SIZE-ERR-PARA are executed.

8600 1518–307

5–15

Elements of a Procedure

The first END-ADD in this series of statements terminates the scope of the ADD A TO B
GIVING OVER-SIZE statement. The second END-ADD terminates the scope of the ADD
A TO B GIVING C statement.

Categories of Verbs
Table 5–2 categorizes the COBOL verbs according to their functions. For a detailed
discussion of the specific Procedure Division verbs with examples of syntax, refer to
Sections 6 through 8. Refer to Volume 2: Product Interfaces for COBOL verbs intended
for use with various products.
Table 5–2. Categories of COBOL Verbs

Category

Arithmetic

Compiler-Directing

5–16

Verb

Function

ADD

Sums two or more numeric operands
and stores the result.

COMPUTE

Calculates an arithmetic expression
and stores the result.

DIVIDE

Divides a numeric operand into
another operand and stores the
quotient and remainder.

INSPECT (TALLYING)

Searches for and tallies the
occurrences of specified characters
in a data item.

MULTIPLY

Multiplies numeric operands and
stores the result.

SUBTRACT

Subtracts one or the sum of two or
more numeric operands from one or
more operands and stores the result.

COPY

Incorporates text from a library
program into a COBOL source
program.

REPLACE

Replaces source program text.

USE

Specifies procedures for handling
input- output errors in addition to the
standard procedures provided by the
input-output control system.

8600 1518–307

Elements of a Procedure

Table 5–2. Categories of COBOL Verbs

Category

Conditional

8600 1518–307

Verb

Function

ADD (ON SIZE ERROR,
NOT ON SIZE ERROR)

Sums two or more numeric operands
and stores the result. If a size-error
conditions occurs, specific
procedures are followed

CALL (ON OVERFLOW,
ON EXCEPTION, NOT ON
EXCEPTION)

Transfers control from one program
to another during program execution.
If the called program is not present,
specified procedures are followed.

COMPUTE (ON SIZE
ERROR, NOT ON SIZE
ERROR)

Calculates an arithmetic expression
and stores the result. If a size-error
condition occurs, specified
procedures are followed.

DELETE (INVALID KEY,
NOT INVALID KEY)

Removes a logical record from a
relative or indexed file. If the file does
not have the record indicated by the
key, specified procedures are
followed.

DIVIDE (ON SIZE ERROR,
NOT ON SIZE ERROR)

Divides one numeric operand into
another and stores the quotient and
remainder. If a size-error condition
occurs, specified procedures are
followed.

EVALUATE

Causes multiple conditions to be
evaluated. Subsequent action of the
object program depends on the
results of the evaluations.

Evaluates a condition. Subsequent
action of the object program depends
on whether the value of the condition
is true or false.

LOCK (with AT LOCKED)

Locks a common data storage area
so that related processes cannot
access it. The AT LOCKED phrase
specifies statements to be performed
if the storage area is already locked.

MULTIPLY (ON SIZE
ERROR, NOT ON SIZE
ERROR)

Multiplies numeric operands and
stores the result. If a size-error
condition occurs, specified
procedures are followed.

PERFORM (UNTIL)

Transfers control to the specified
subroutine until the condition in the
UNTIL phrase is true.

5–17

Elements of a Procedure

Table 5–2. Categories of COBOL Verbs

Category

Conditional

5–18

Verb

Function

READ (AT END, NOT AT
END, INVALID KEY, NOT
INVALID KEY)

For sequential access, it makes the
next logical record from a sequential
file available. For random access, it
makes a specific record from a massstorage file available. If the end of the
file is reached or if the file does not
contain the indicated key, specified
procedures are followed.

RETURN (AT END, NOT AT
END)

Causes the next record in a sortmerge file to be read. If the end of
the file is reached, specified
procedures are followed.

REWRITE (INVALID KEY,
NOT INVALID KEY)

Logically replaces a record in a massstorage file. If the file does not
contain the record identified by the
indicated key, specified procedures
are followed.

Searches a table for a table element
that satisfies a specified condition
and adjusts the associated indexname to point to that table element.

SORT (ON ERROR)

Sorts the contents of one or more
input files. If an error condition is
encountered, specific action can be
performed.

START (INVALID KEY, NOT
INVALID KEY)

Provides a logical position for a
relative or indexed file when the file
will be read sequentially. If the file
does not contain the indicated key,
specified procedures are followed.

STRING (ON OVERFLOW,
NOT ON OVERFLOW)

Provides juxtaposition of the partial or
complete contents of one or more
data items into a single data item.

SUBTRACT (ON SIZE
ERROR, NOT ON SIZE
ERROR)

Subtracts one or the sum of two or
more numeric operands from one or
more operands and stores the result.
If a size-error condition occurs,
specified procedures are followed.

8600 1518–307

Elements of a Procedure

Table 5–2. Categories of COBOL Verbs

Category

Conditional

Imperative

8600 1518–307

Verb

Function

UNSTRING (ON
OVERFLOW, NOT ON
OVERFLOW)

Causes contiguous data items in a
sending field to be separated and
placed into multiple receiving fields. If
the value of the pointer is less than 1
or greater than the sending field, or if
all the receiving fields have been
acted upon and the sending field
contains characters that have not
been examined, specified procedures
are followed.

WRITE (INVALID KEY, NOT
INVALID KEY, END-OFPAGE, NOT END-OFPAGE)

Releases a logical record for an
output or input-output file. If the file
does not contain the indicated key, or
if an end-of-page condition exists,
specified procedures are followed.

ACCEPT (DATE, DAY, DAYOF-WEEK, TIME)

Makes low-volume data available to a
specified data item. Data from the
DATE, DAY, DAY-OF-WEEK, or TIME
register is moved to the specified
item.

INITIALIZE

Sets selected types of data fields to
predetermined values.

INSPECT (REPLACING,
CONVERTING)

Searches for and replaces
occurrences of specified characters
in a data item.

MOVE

Transfers data, according to the rules
of editing, to one or more data areas.

STRING

Provides juxtaposition of the partial or
complete contents or one or more
data items into a single data item.

UNSTRING

Causes contiguous data items in a
sending field to be separated and
placed into multiple receiving fields.

Makes low-volume data available to a
specified data item from an ODT.

ADD (without ON SIZE
ERROR, NOT ON SIZE
ERROR)

Sums two or more numeric operands
and stores the result.

ALLOW

Readies an interrupt procedure for
execution when its associated events
are activated.

ATTACH

Associates an interrupt procedure
with an event.

5–19

Elements of a Procedure

Table 5–2. Categories of COBOL Verbs

Category

Imperative

5–20

Verb

Function

ALTER

Modifies a predetermined sequence
of operations.

CALL (without ON
OVERFLOW, ON
EXCEPTION, NOT ON
EXCEPTION)

Transfers control from one program
to another during program execution.

CANCEL

Ensures that the next time a program
referenced in a CALL statement is
called, the program will be in its initial
state.

CAUSE

Initiates specified events.

CHANGE

Modifies a file, task, or library
attribute.

Ends the processing of a file and
specifies the disposition of the file
and the device to which the file is
assigned.

COMPUTE (without ON
SIZE ERROR, NOT ON
SIZE ERROR)

Calculates an arithmetic expression
and stores the result.

CONTINUE task-variable

Reinstates a synchronous, dependent
process that was previously initiated
by a CALL statement from another
program and then exited by an EXIT
PROGRAM statement.

COPY

Incorporates text from a library
program into the program that
contains the COPY statement.

DELETE (without INVALID
KEY, NOT INVALID KEY)

Removes a logical record from a
relative or indexed file.

DETACH

Dissociates an interrupt procedure
from an event or a task variable from
a task.

DISALLOW

Prevents an interrupt procedure from
executing when its associated event
is activated.

DISPLAY

Causes low-volume data to be
transferred to an ODT.

DIVIDE (without ON SIZE
ERROR, NOT ON SIZE
ERROR)

Divides one numeric operand into
another and stores the quotient and
remainder.

8600 1518–307

Elements of a Procedure

Table 5–2. Categories of COBOL Verbs

Category

Imperative

8600 1518–307

Verb

Function

EXIT

Indicates a logical end for a series of
sections or paragraphs referenced by
a PERFORM statement.

EXIT PROGRAM

Indicates the logical end of a called
program.

Unconditionally transfers control from
one procedure to another. Control is
not implicitly returned to the
statement following the GO
statement.

INITIALIZE

Sets selected types of data fields to
predetermined values.

INSPECT

Searches for and can tally or replace
specified characters in a data item.

LOCK (without AT
LOCKED)

Locks a common data storage area
so that related processes cannot
access it

MERGE

Merges two or more identically
sequenced files on a set of specified
keys. The merged records then
become available to an output
procedure or output file.

MOVE

Transfers data, according to the rules
of editing, to one or more data areas.

MULTIPLY (without ON
SIZE ERROR, NOT ON
SIZE ERROR)

Multiplies numeric operands and
stores the result.

OPEN

Makes a file available for processing.

PERFORM

Unconditionally transfers control to
the specified subroutine and returns
control to the statement following the
PERFORM statement.

PROCESS

Initiates a separately compiled
program as an asynchronous,
dependent process

READ (without AT END or
INVALID KEY, NOT AT
END, NOT INVALID KEY)

For sequential access, it makes the
next logical record from a sequential
file available. For random access, it
makes a specific record from a massstorage file available.

5–21

Elements of a Procedure

Table 5–2. Categories of COBOL Verbs

Category

Imperative

5–22

Verb

Function

RELEASE

Transfers records to the initial phase
of a sort operation and writes records
to a sort file.

REPLACE

Replaces source program text.

RESET

Turns off specified events.

REWRITE (without
INVALID KEY, NOT
INVALID KEY)

Logically replaces a record in a massstorage file. If the file does not
contain the indicated key, specified
procedures are followed.

RUN

Initiates a separately compiled
program as an asynchronous,
independent process.

SEARCH (without AT END
or WHEN)

Searches a table for a table element
that satisfies a specified condition
and adjusts the associated indexname to point to that table element.

SEEK

Repositions a file to a specified
record.

SET

Establishes reference points for table
handling operations by setting
indexes associated with table
elements; can alter the value of
external switches; and can alter the
value of the conditional variables.

SORT

Sequences a file on a set of specified
keys and makes the sort file available
to output procedures or output files

START (without INVALID
KEY, NOT INVALID KEY)

Provides a logical position for a
relative or indexed file when the file
will be read sequentially. If the file
does not contain the indicated key,
specified procedures are followed.

STOP

Suspends the execution of a program
either permanently or temporarily.

STRING (without ON
OVERFLOW, NOT ON
OVERFLOW)

Provides juxtaposition of the partial or
complete contents of one or more
data items into a single data item.

SUBTRACT (without SIZE
ERROR, NOT ON SIZE
ERROR)

Subtracts one or the sum of two or
more numeric operands from one or
more operands and stores the result.

8600 1518–307

Elements of a Procedure

Table 5–2. Categories of COBOL Verbs

Category

Imperative

Input-Output

8600 1518–307

Verb

Function

UNLOCK

Frees a common storage area that
was previously restricted by a LOCK
statement.

UNSTRING (without ON
OVERFLOW, NOT ON
OVERFLOW)

Causes contiguous data items in a
sending field to be separated and
placed into multiple receiving fields.

WAIT

Suspends program execution for a
specified period of time.

WRITE (without INVALID
KEY or END-OF-PAGE,
NOT INVALID KEY, NOT
AT END-OF-PAGE)

Releases a logical record for an
output of input-output file.

ACCEPT (identifier)

Transfers low-volume data from an
ODT to a specified data item.

Ends the processing of a file,
specifies the disposition of the file
and of the device to which the file is
assigned.

DELETE

Removes a logical record from a
relative or indexed file.

DISPLAY

Causes low-volume data to be
transferred to an ODT.

OPEN

Makes a file available for processing.

READ

For sequential access, it makes the
next logical record from a sequential
file available. For random access, it
makes a specific record from a massstorage file available.

REWRITE

Logically replaces a record in a massstorage file.

SEEK

Repositions a file to a specified
record.

START

Provides a logical position for a
relative or indexed file when the file
will be read sequentially.

STOP (literal)

Suspends the execution of a
program. The literal is communicated
to the operator, and execution
continues with the next executable
statement in the program.

5–23

Elements of a Procedure

Table 5–2. Categories of COBOL Verbs

Category

Verb

Function

WRITE

Releases a logical record for an
output or input-output file.

CALL

Transfers control from one program
to another during program execution.

CANCEL

Ensures that the next time a program
referenced in a CALL statement is
called, the program will be in its initial
state.

Interprogram
Communication

EXIT PROGRAM

Indicates the logical end of a called
program.

No Operation

CONTINUE

Indicates that no executable
statement is present.

EXIT

Indicates a logical end to a series of
sections or paragraphs referenced by
a PERFORM statement.

MERGE

Merges two or more identically
sequenced files on a set of specified
keys. The merged records then
become available to an output
procedure or output file.

RELEASE

Transfers records to the initial phase
of a sort operation and writes records
to a sort file.

RETURN

Causes the next record in a sortmerge file to be read.

SORT

Sequences a file on a set of specified
keys and makes the sort file available
to output procedures or to output
files.

ALTER

Modifies a GO TO statement to a
different destination.

CALL

Transfers control from one program
to another during program execution.

EXIT

Indicates a logical end to a series of
sections or paragraphs referenced by
a PERFORM statement.

EXIT PROGRAM

Indicates the logical end of a called
program.

Interprogram
Communication

Ordering

Procedure Branching

5–24

8600 1518–307

Elements of a Procedure

Table 5–2. Categories of COBOL Verbs

Category

Verb

Function

Unconditionally transfers control to a
procedure-name. Control is not
implicitly returned to the statement
following the GO statement.

PERFORM

Unconditionally transfers control to
the specified subroutine and returns
control to the next statement
following the PERFORM statement.

Scope Termination

END-ADD
END-CALL
END-COMPUTE
END-DELETE
END-DIVIDE
END-EVALUATE
END-IF
END-LOCK
END-MULTIPLY
END-PERFORM
END-READ
END-RETURN
END-REWRITE
END-SEARCH
END-START
END-STRING
END-SUBTRACT
END-UNSTRING
END-WRITE

Delimits the scope of its
corresponding statement.

String Handling

INSPECT (REPLACING,
CONVERTING, TALLYING)

Searches for and replaces the
occurrences of specified characters
in a data item.

STRING

Provides juxtaposition of the partial or
complete contents or one or more
data items into a single data item.

UNSTRING

Causes contiguous data items in a
sending field to be separated and
placed into multiple receiving fields.

Searches a table for a table element
that satisfies a specified condition
and adjusts the associated indexname to point to that table element.

SET

Table Handling

8600 1518–307

5–25

Arithmetic Expressions

Arithmetic Expressions
An arithmetic expression contains combinations of identifiers and literals, which are
separated by arithmetic operators and parentheses.
Identifiers and literals that appear in arithmetic expressions must represent either
numeric elementary items or numeric literals on which arithmetic operations can be
performed. Numeric literals cannot exceed 23 digits when used for arithmetic operations.
An arithmetic operator is a single character or a fixed two-character combination that
indicates a particular arithmetic operation. Binary operators link two variables together,
such as in A + B. Unary operators contain only one variable, such as +A or –B.
The binary arithmetic operators are represented by specific characters, as follows:

Operator

Meaning

Addition

Subtraction

Multiplication

Division

Exponentiation

The unary arithmetic operators are represented by specific characters, as follows:

Operator

Meaning

The effect of multiplication by the numeric literal +1

The effect of multiplication by the numeric literal –1

Note that binary arithmetic operators must be preceded and followed by a space.
Any arithmetic expression can be preceded by a unary operator.
Parentheses can be used in arithmetic expressions to change the order in which
expressions are evaluated. Refer to “Precedence in Evaluation of Arithmetic
Expressions” in this section for more information.
There must be a one-to-one correspondence between left and right parentheses of an
arithmetic expression. That is, each left parenthesis is to the left of its corresponding
right parenthesis.

5–26

8600 1518–307

Arithmetic Expressions

Allowed Combinations of Elements
Table 5–3 shows the permissible combinations of identifiers and literals, arithmetic
operators, and parentheses in an arithmetic expression.
Table 5–3. Combination of Symbols in Arithmetic Expressions

Second Symbol
First
Symbol

Identifier
or Literal

* / **
–+

Unary +
or –

(

)

Variable

—

* / **
+–

—

Unary +
–

—

--—

—

(

—

)

—

----

An arithmetic expression can begin only with a left parenthesis, plus sign, minus sign, or
an identifier or literal and can end only with a right parenthesis or an identifier or literal.
Examples
The following examples show valid arithmetic expressions.
COMPUTE X = Y ** 10
This first example causes the value of the identifier Y to be raised to the power of the
numeric literal 10 and stored in X.
MULTIPLY -6 BY Z
This second example causes the value of Z to be multiplied by –6. The –6 is a
combination of a unary and a numeric literal.
SUBTRACT Discount FROM Item-Cost GIVING Sale-Price
This third example causes identifier Discount to be subtracted from identifier Item-Cost
and the result to be stored in identifier Sale-Price.

8600 1518–307

5–27

Arithmetic Expressions

Precedence in Evaluation of Arithmetic Expressions
Arithmetic expressions are evaluated as follows:

•

Expressions in parentheses are evaluated first:
COMPUTE A = B + (C - D)
D is subtracted from C and the result is added to B.

•

Within nested parentheses, the sequence of operations works outward from the
innermost parentheses:
COMPUTE A = B + (C - (D + E))
D and E are added first. The result is subtracted from C. This result is then added
to B.

•

When parentheses are not used, or parenthesized expressions are at the same
hierarchical level, the sequence of execution is as follows:

−

Unary plus and minus (+, –)

−

Exponentiation (**)

−

Multiplication and division (*, /)

−

Addition and subtraction (+, –)
COMPUTE A = B ** .5 * C - D

Exponentiation is performed first, which results in the square root of B. The result is
multiplied by C, and then D is subtracted.

•

Parentheses help either to eliminate ambiguities in logic where consecutive
operations of the same level appear, or to modify the normal sequence of execution
in expressions where it is necessary to have some deviation from the normal
precedence:
COMPUTE A = B + (C - D) + (E - F)
D is subtracted from C; then F is subtracted from E. B is added to the result of C – D,
which is then added to the result of E – F.

•

When the sequence of execution is not specified by parentheses, the order of
execution of consecutive operations of the same hierarchical level is from left to
right:
COMPUTE X = A + B / C + (D ** E) * F - G

5–28

8600 1518–307

Arithmetic Expressions

This example would be interpreted as:
((A + (B / C)) + ((D ** E) * F)) - G
First the exponentiation (D ** E) is performed; then the multiplication of (D ** E) by F
and division (B / C). Addition and subtraction are last, proceeding from left to right, so
A is first added to (B / C). The sum is added to the next group. Finally, G is subtracted
from the resulting value.

Rules for Exponentiation
The following rules apply to the evaluation of exponents in an arithmetic expression:

•

You cannot have the value of an expression be zero raised to any power. For
example, you cannot have A ** 2, if the value of A is 0.
You cannot have the value of an expression be raised to a power of zero. For
example, you cannot have A ** B, if the value of B is 0.
Either case causes a size-error condition. Refer to “SIZE ERROR Phrase” in this
section for more information.

•

If the evaluation yields both a positive and a negative real number, the value returned
as the result is the positive number. For example, in 4 ** .5, which calculates the
square root of 4, the result is +2 or –2. The value returned and stored as the result is
+2.

•

If the result of an evaluation is not a real number, a size-error condition exists. For
example, in A ** .5, if the value of A is a negative number, the result would be an
imaginary number, and a size-error condition would exist.

•

If an identifier to store the value of a result is not associated with an expression, an
intermediate data item will be used. Intermediate data items are described in the
following subsection.

•

For all noninteger operands, the operand value is scaled into a double-precision,
floating-point value as part of the preparation for the operation. Various arithmetic
operations are performed during the operation itself. The result of exponentiation
should always be regarded as an approximation. Performing the appropriate
calculations directly within the program might produce more precise results than
exponentiation, particularly when the exponent is known to be an integer.

8600 1518–307

5–29

Arithmetic Expressions

Intermediate Data Item
An intermediate data item is a signed numeric data item provided by the compiler to
contain the values developed during evaluation of an arithmetic expression.
The contents of the intermediate data item are then moved to the resultant-identifier,
which is a user-defined data item that contains the result of the arithmetic operation,
according to the rules for the MOVE statement. (Refer to “MOVE Statement” in Section
7 for detailed information.) Rounding is performed, if specified, and the size-error
condition determined only during this move.
An intermediate data item occurs when an arithmetic statement involves several
operations. Consider the following example:
COMPUTE X = A * B + C
This example requires an intermediate item to contain the value of A * B; then C is added
to this intermediate item to produce the final result.

Limitations on Intermediate Data Items
The length of an intermediate data item is limited to 23 decimal digits. It contains the
leading zeros and the leftmost digits of the value produced in the arithmetic operation.
If the size of the result exceeds the size of the intermediate data item, the result is
truncated on the right to the size of the intermediate data item. The truncated value is
used in the remainder of the computation.
Addition and subtraction operations have the following limitation: When the two
operands aligned on their decimal points require a field longer than 23 decimal digits,
truncation occurs before the operation is performed. The right end of the longer operand
will be truncated, with the most significant 23 decimal digits saved.
Example
COMPUTE X = A + B
The value of A is 11.000000000123456789012, and the value of B is 11111.23.
A contains 23 digits, which is the maximum allowed for an intermediate data item. When
A and B are aligned on their decimal points, the sum will contain more than 23 digits,
because B contains five digits before the decimal point. The value of A is truncated on
the right end by three digits before the addition will be performed. The value of A
becomes 11.000000000123456789.

5–30

8600 1518–307

Arithmetic Expressions

General Rules for Arithmetic Statements
The COBOL arithmetic statements are the

•

ADD statement, which sums two or more numeric operands and stores the result

•

COMPUTE statement, which calculates an arithmetic expression and stores the
result

•

DIVIDE statement, which divides a numeric operand into another and stores the
quotient and remainder

•

MULTIPLY statement, which multiplies numeric operands and stores the result

•

SUBTRACT statement, which subtracts one or the sum of two or more numeric
operands from one or more operands and stores the result

These statements have features in common regarding data descriptions, operand size
limit, multiple results, the ROUNDED phrase, and the ON SIZE ERROR phrase.
When a REAL or a DOUBLE data item, or an intermediate result, is assigned to a
DISPLAY, COMP, or BINARY data item in an Arithmetic statement, precision can be lost
if the REAL or DOUBLE data item, or the intermediate result, represents a value that the
machine must approximate. For more information, refer to “USAGE IS REAL” and
“USAGE IS DOUBLE” in “Data Description Entry Format 1” in Section 4.

Data Descriptions
The data descriptions of the operands need not be the same; any necessary conversion
and decimal point alignment is supplied throughout the calculation.
Data to be used in arithmetic operations, and data that is to be edited for a report, must
be defined in the Data Division as numeric data.
Example
IDENTIFICATION DIVISION.
PROGRAM-ID. ADD-EXAMPLE.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 MATH-ITEMS.
05 AA PIC 99.
05 BB PIC 9V999.
01 OUT-ITEM.
05 CC PIC ZZZZ.999.
PROCEDURE DIVISION.
.
.
.
ADD AA TO BB GIVING CC END-ADD.
STOP RUN.

8600 1518–307

5–31

Arithmetic Expressions

The data items AA, BB, and CC are described in the Data Division. The values for AA and
BB are:
AA = 02
BB = 1.005
CC would be 3.005 after the calculation and decimal point alignment.

Operand Size Limit
The maximum size of each operand is 23 decimal digits. An operand that exceeds the
size limit causes a syntax error.

Multiple Results in Arithmetic Statements
The ADD, COMPUTE, DIVIDE, MULTIPLY, and SUBTRACT statements can have multiple
results. Such statements behave as though they had been written in the following way:

•

A statement whose execution accesses all data items that are part of the initial
evaluation of the statement, performs any necessary arithmetic or combining of
these data items and stores the result of this operation in a temporary location. See
the individual statements for the rules indicating which items are part of the initial
evaluation.

•

A sequence of statements whose execution transfers or combines the value in this
temporary location with each single resulting data item. These statements are
considered to be written in the same left-to-right sequence that the multiple results
are specified.

For example, assume that temp is an intermediate data item provided by the compiler.
The multiple results of the statement ADD a, b, c TO c, d (c), e are equivalent to:
ADD
ADD
ADD
ADD

a, b, c
temp TO
temp TO
temp TO

GIVING temp
c
d (c)
e

And the multiple results of the statement MULTIPLY a (i) BY i, a (i) are equivalent to:
MOVE a (i) TO temp
MULTIPLY temp BY i
MULTIPLY temp BY a (i)

5–32

8600 1518–307

Arithmetic Expressions

ROUNDED Phrase
The ROUNDED phrase is used to round the result from an arithmetic operation so that it
fits into its specified data item. The ROUNDED phrase increases the absolute value of
the result from the COMPUTE statement by adding 1 to its low-order digit whenever the
absolute value of the most significant digit of the excess is greater than or equal to 5.
(The excess refers to the number of digits greater than the size of the data item in which
the result is to be stored.)
Assume, for example, that you created a data item that can have two numbers after the
decimal point. The result of the COMPUTE statement yields four numbers after the
decimal point, “.5678”. To fit into the defined data item, the ROUNDED phrase rounds
“.5678” to “.57”.
The ROUNDED phrase often requires a resultant-identifier to store the final results of the
arithmetic operation. Truncation occurs if, after decimal point alignment, the number of
places in the fraction of the result of an arithmetic operation is greater than the number
of places provided for the fraction of the resultant-identifier. When using large BINARY
EXTENDED integers in the calculation of the source expression, an overly large result can
occur while scaling for decimal alignment and subsequent rounding. It is suggested that
the ON SIZE ERROR phrase be used with rounded COMPUTE results to detect and deal
with this possibility.
Example
Data Division.
.
.
.
01 IN-RECORD.
05 hourly-wage PIC 999V99.
05 no-of-hours PIC 999V99.
01 OUT-RECORD.
05 Gross-pay PIC ZZZZZ9.99.
.
.
.
PROCEDURE DIVISION.
MULTIPLY hourly-wage BY no-of-hours GIVING Gross-pay ROUNDED.
The values are as follows:
hourly-wage = 7.50
no-of-hours = 45.25
The actual result of the multiplication is 339.3750, and the result is rounded prior to being
stored in Gross-pay as 339.38.

8600 1518–307

5–33

Arithmetic Expressions

When the low-order integer positions in a resultant-identifier are represented by the
character P in the PICTURE clause, which implies an assumed decimal point location,
rounding or truncation occurs relative to the rightmost integer position for which storage
is allocated. Refer to “PICTURE Clause” in Section 4 for more information.
Example
05 C1 PIC 9PP.
05 C2 PIC 9PP.
.
.
.
ADD A B Giving C1.
ADD A B Giving C2 ROUNDED.

The values are as follows:
A = 100
B = 50
The result of the calculation would be
C1 = 100
C2 = 200

5–34

8600 1518–307

Arithmetic Expressions

SIZE ERROR Phrase
The SIZE ERROR phrase enables you to specify procedures to be executed when a size
error condition exists. Size error conditions occur under the following circumstances:

•

If, after decimal point alignment, the absolute value of a result exceeds the largest
value that can be contained in the associated resultant-identifier.

•

If, in the case noted above, the USAGE IS BINARY clause is specified for the
resultant-identifier, and the value exceeds what can be contained in the resultantidentifier implied by the associated decimal PICTURE character-string.

•

Division by zero. The execution of the program is abnormally terminated if the SIZE
ERROR phrase is not specified.

•

Violation of the rules for evaluation of exponentiation. This terminates the arithmetic
operation.

The size error condition applies only to the final results of an arithmetic operation and
does not apply to intermediate results, except in the DIVIDE and COMPUTE statements.
An intermediate result of a COMPUTE statement can exceed the 23-digit length limit of
the intermediate data item, but a size error condition does not result unless the final
results of the COMPUTE statement exceed the limit of the resultant-identifier. Such a
condition can produce unexpected results.
If the SIZE ERROR phrase is not used and a size error condition occurs, the value of the
affected resultant-identifiers is undefined. Values of resultant-identifier(s) for which no
size error condition occurs are unaffected by size errors that occur for the other resultantidentifier(s) during the execution of this operation.
If the SIZE ERROR phrase is used and a size error condition occurs, then the values of
resultant-identifier(s) affected by the size errors are not altered. After completion of this
operation, the imperative statement in the SIZE ERROR phrase is executed.
If the ROUNDED phrase is specified, rounding takes place before checking for a size
error. When such a size error condition occurs, the subsequent action depends on
whether or not the SIZE ERROR phrase is specified.
If you use the CORRESPONDING phrase in an ADD or SUBTRACT statement and any of
the individual operations produces a size error condition, the imperative statement in the
SIZE ERROR phrase is not executed until all of the individual additions and subtractions
are completed.

8600 1518–307

5–35

Arithmetic Expressions

OFFSET Function
OFFSET is a numeric function that returns a count of the number of characters that
precede a data item in the logical record in which the data item is defined.
If data-name refers to a packed numeric data item that is not aligned on a character
boundary, then the returned value is equal to the number of characters preceding the
character with which data-name begins. If data-name is a record-name or a 77-level item,
the value returned is 0. Data-name can be qualified.
Example
Given the following data declaration:
77
01

CURRENT-OFFSET
PIC 9999.
PERSONNEL-GRP.
05 NAME
PIC X(16).
05 EMPLOYEE-NUMBER
PIC 9999.
05 JOB-TITLE
PIC X(16).
05 DATES
PIC X(16).
05 SUPP-FILE-NO
PIC 9999.

The following statement sets CURRENT-OFFSET to a value of 20:
COMPUTE CURRENT-OFFSET = OFFSET (JOB-TITLE OF PERSONNEL-GRP).

5–36

8600 1518–307

Boolean Expressions

Boolean Expressions
A Boolean expression can be any of the following:

•

An identifier referencing a Boolean data item

•

A Boolean literal

•

The figurative constant ZERO (ZEROS, ZEROES)

•

The figurative constant ALL literal, where literal is a Boolean literal

•

A Boolean expression preceded by an unary Boolean operator

•

Two Boolean expressions separated by a binary Boolean operator

•

A Boolean expression enclosed in parentheses

General Format
ä
å
³
BOOLEAN IDENTIFIER
³
³
³
³
ä BOOLEAN LITERAL
å
³
³
³
³
³
³
³ ZERO
³
³
³
ã
â
³
³
³ ZEROS
³
³
³
³
³
³
³
æ ZEROES
ç
³
ã
â
³
³
³ B-NOT BOOLEAN-EXPRESSION
³
³
³
³
³
³ ( BOOLEAN-EXPRESSION )
³
³
³
³
³
³ BOOLEAN-EXPRESSION BINARY-BOOLEAN-OPERATOR BOOLEAN-EXPRESSION ³
³
³
æ
ç

Note: The unary Boolean operator B-NOT cannot be immediately followed by another
B-NOT.

8600 1518–307

5–37

Boolean Expressions

The following table shows the permissible combinations of operands, operators, and
parentheses in a Boolean expression.

Second Symbol

First
Symbol

Identifier
or Literal

B-AND
B-OR
B-XOR

B-NOT

(

)

Identifier
or literal

—

B-AND,
B-OR,
B-XOR

—

B-NOT

—

(

5–38

8600 1518–307

Conditional Expressions

Conditional Expressions
Conditional expressions contain conditions to be tested. The object program selects
between alternate paths of control depending upon the truth value of the condition.
You can specify conditional expressions in the following statements:

Use a conditional expression
in the . . .

To . . .

EVALUATE statement

Evaluate multiple conditions. Subsequent action of the
object program depends on the results of the
evaluations.

IF statement

Evaluate a single condition. Subsequent action of the
object program depends on whether the value of the
condition is TRUE or FALSE.

PERFORM statement (with
the UNTIL phrase)

Transfer control to one or more procedures until a
particular condition specified in the UNTIL phrase is
TRUE.

SEARCH statement

Search a table for a table element that satisfies a
specified condition and adjusts the associated index to
indicate that table element.

Conditions associated with conditional expressions can be one of the following types:

•

Simple conditions
In a simple condition, a comparison is made. The value of the comparison is either
TRUE or FALSE.

•

Complex conditions
In a complex condition, one or more logical operators (AND, OR, and NOT) act upon
one or more conditions. The value of a complex condition is the truth value that
results from the interaction of all the comparisons.

Conditions can be enclosed in any number of paired parentheses.

8600 1518–307

5–39

Conditional Expressions

Simple Conditions
A simple condition has a truth-value of either TRUE or FALSE. The types of simple
conditions that you can use are

•

Relation

•

Class

•

Condition-name

•

Switch status

•

Sign

•

Event

•

Boolean

Relation Conditions
A relation condition causes a comparison of two operands. The operands can be a literal,
a task attribute, a data item referred to by an identifier, the value resulting from an
arithmetic expression, or an index-name. A relation condition has a truth value of TRUE if
the relation exists between the operands.
A relation condition must contain at least one reference to a variable. Otherwise, there is
no question as to the truth-value of the condition, and no reason to have the condition.
Consequently, you cannot compare one literal with another literal.

5–40

8600 1518–307

Conditional Expressions

General Format for Relation Conditions

ä
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
³
æ

identifier-1
arithmeticexpression-1
literal-1
index-name-1
task-attributeidentifier-1
file-attributeidentifier-1
booleanexpression-1

å
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
ç

ä
³
³
³
³
³
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
³
³
³
æ

ä GREATER THAN å
IS [ NOT ] ã ïïïïïïï
â
ïïï
æ >
ç
ä LESS THAN
IS [ NOT ] ã ïïïï
ïïï
æ <

å
â
ç

ä EQUAL TO
IS [ NOT ] ã ïïïïï
ïïï
æ =

å
â
ç

ä GREATER THAN OR EQUAL TO å
IS ã ïïïïïïï
ïïïïïïïï
â
æ
>=
ç
ä LESS THAN OR EQUAL TO
IS ã ïïïï
ïï ïïïïï
æ
<=

å
â
ç

å
³
³
³
³
³
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
³
³
ç

ä
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
³
æ

identifier-2
arithmeticexpression-2
literal-2
index-name-2
task-attributeidentifier-2
file-attributeidentifier-2
booleanexpression-2

å
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
ç

The first operand in the condition is called the subject of the condition.
identifier-1
literal-1
index-name-1

Identifiers, literals, and index-names are user-defined words. The hyphen (-) cannot
appear as the first or last character in a user-defined word.
arithmetic-expression-1

Arithmetic-expression-1 refers to the result of an arithmetic operation.
task-attribute-identifier-1

Task-attribute-identifier-1 specifies one of the task attributes. For the syntax of the task
attribute identifier, refer to Format 5 of the CHANGE statement in Section 6.
file-attribute-identifier-1

File-attribute-identifier-1 specifies one of the file attributes. For the syntax of the file
attribute identifier, refer to Section 12.
boolean-expression-1

Boolean-expression-1 refers to the result of a Boolean expression.

8600 1518–307

5–41

Conditional Expressions

IS [NOT] GREATER THAN
>
IS [NOT] LESS THAN
<
IS [NOT] EQUAL TO
=
IS GREATER THAN OR EQUAL TO
>=
IS LESS THAN OR EQUAL TO
<=

These relational operators specify the type of comparison to be made in a relation
condition.
A space must precede and follow the first reserved word of the relational operator.
NOT, when used, determines the test to be true if the subject does not meet the
specified relation. For example, IS NOT LESS THAN would be TRUE if the subject were
equal to or greater than the object.
The second operand in the condition is called the object of the condition.
identifier-2
index-name-2
literal-2

Identifiers, literals, and index-names are user-defined words. The hyphen (-) cannot
appear as the first or last character of a user-defined word.
arithmetic-expression-2

Arithmetic-expression-2 refers to the result of an arithmetic operation.
task-attribute-identifier-2

Task-attribute-identifier-2 is one of the task attributes, the value of which you are
comparing to the value of the attribute specified by task-attribute-identifier-1. For the
syntax of the task attribute identifier, refer to Format 5 of the CHANGE statement in
Section 6.
file-attribute-identifier-2

File-attribute-identifier-2 is one of the file attributes, the value of which you are comparing
to the value of the attribute specified by file-attribute-identifier-1. For the syntax of the file
attribute identifier, refer to Section 12.
boolean-expression-2

Boolean-expression-2 refers to the result of a boolean expression.

5–42

8600 1518–307

Conditional Expressions

Details
You can compare two numeric operands regardless of the formats indicated in their
respective USAGE clauses. The USAGE clause in the Data Division specifies the format
of a data item in computer storage, not the actual format of the numeric operand. For
more information on the USAGE clause, refer to Section 4.
For comparisons that involve nonnumeric operands, index-names or index data items,
the operands must have the same usage. If either of the operands is a group item, the
nonnumeric comparison rules apply. Refer to “Comparison of Nonnumeric Operands”
later in this section for more information.
A relation condition involving operands of class Boolean is a Boolean relation condition.
An operand of class Boolean can be compared with another operand of class Boolean for
equality (EQUAL and NOT EQUAL) only. Comparison of operands of class Boolean is a
comparison of Boolean values, regardless of usage.
Examples
IF JOB-NO < 10 MOVE "ADMINISTRATIVE" TO CLASS.
This first example compares the identifier JOB-NO and the literal 10.
IF A + B >= C PERFORM C-PROC.
This second example compares the result of the arithmetic expression A + B and the
identifier C.
PERFORM Year-End-Calc THRU Total-Proc VARYING Year FROM 1948 BY 1 UNTIL
Year = 1985 END-PERFORM.
This third example executes the procedures in Year-End-Calc through Total-Proc until the
comparison of the index-name Year and the literal 1985 is TRUE.
Comparison of Numeric Operands
Numeric operands are compared according to their algebraic value, that is, the relation of
the value to zero. Zero is a unique value regardless of the sign. That is, a plus or minus
zero equals zero. The length of the literal or arithmetic expression operands, in number of
digits represented, is not significant.
Numeric operands can be compared regardless of the formats described in their USAGE
clauses. When needed, the numeric items are converted to their algebraic values. If the
numeric item contains characters other than the digits 0 through 9, a conversion to valid
numeric values occurs before the comparison is done.
Unsigned numeric operands are considered positive for purposes of comparison.

8600 1518–307

5–43

Conditional Expressions

Comparisons involving long numeric operands are restricted to the following:

•

Comparing a long numeric operand against 0 (zero) or an approximate figurative
constant

•

Comparing a long numeric operand for equality or nonequality against a long numeric
operand of equal size and usage

Numeric Comparisons Involving HIGH-VALUES and LOW-VALUES
On Unisys V Series platforms, the rules and behavior for comparing these figurative
constants to numeric data items is different than on Unisys A Series platforms. Tables
5-4 and 5–5 describe the results of moving HIGH-VALUES or LOW-VALUES to a data
item of a certain type with a specific type of sign field.
Table 5–4. Numeric Comparisons Involving HIGH-VALUES
Platform
Data Value
and Field
Type

A Series
COBOL85
with
FIGCONST
set

A Series
COBOL74

A Series
COBOL85

COMP
Unsigned

Syntax Error

TRUE

Syntax Error

COMP
TRAILING

Syntax Error

COMP
LEADING

Syntax Error

COMP
TRAILING
SEPARATE

Syntax Error

COMP
LEADING
SEPARATE

Syntax Error

DISPLAY
Unsigned

FALSE

TRUE

DISPLAY
TRAILING

FALSE

TRUE

DISPLAY
LEADING

FALSE

TRUE

DISPLAY
TRAILING
SEPARATE

FALSE

TRUE

DISPLAY
LEADING
SEPARATE

FALSE

TRUE

FALSE

5–44

V Series
COBOL74

8600 1518–307

Conditional Expressions

Table 5–5. Numeric Comparisons Involving LOW-VALUES
Platform
Data Value
and Field
Type

A Series
COBOL85
with
FIGCONST
set

A Series
COBOL74

A Series
COBOL85

COMP
Unsigned

Syntax Error

TRUE

Syntax Error

COMP
TRAILING

Syntax Error

COMP
LEADING

Syntax Error

COMP
TRAILING
SEPARATE

Syntax Error

COMP
LEADING
SEPARATE

Syntax Error

DISPLAY
Unsigned

FALSE

TRUE

DISPLAY
TRAILING

FALSE

DISPLAY
LEADING

FALSE

DISPLAY
TRAILING
SEPARATE

FALSE

DISPLAY
LEADING
SEPARATE

FALSE

8600 1518–307

V Series
COBOL74

5–45

Conditional Expressions

Comparison of Nonnumeric Operands
A comparison of nonnumeric operands, or one numeric and one nonnumeric operand, is
made according to a specified collating sequence of characters. Refer to “OBJECTCOMPUTER Paragraph” in Section 3 for information on collating sequences.
The size of an operand is the total number of standard data format characters in the
operand. A numeric and a nonnumeric operand can be compared only when their usage
is the same, such as in a comparison of two operands whose usage is DISPLAY. If the
numeric item contains characters other than the digits 0 through 9, no conversion to valid
numeric values occurs before the comparison is done.
Compared operands need not be equal in size, because the comparison proceeds as
though the shorter operand were extended on the right by enough spaces to make the
operands of equal size.
Comparison of Undigit Literals and Numeric Operands
You can compare undigit literals with numeric operands on the basis of equality or
nonequality. Comparisons involving greater than or less than operators are not allowed.
Observe the following rules:

•

Only unsigned integers can be compared with undigit literals.

•

The PICTURE clause for the numeric operand cannot contain any editing characters
or the characters S, V, or P.

•

Binary and real items cannot be used.

•

The undigit literal must be of the same length as the numeric data item with which it
is being compared.

−

For packed items (COMP), there must be as many hex digits as specified in the
PICTURE for the numeric data item.

−

For items with a usage of DISPLAY, there must be two hex digits for each
number position in the item's definition.

Numeric Operands in Nonnumeric Comparisons
A numeric operand can be an integer data-item, non-integer data-item, or literal.
Example
01

Job-Data.
05 Job-No PIC X(3).
05 Job-Class PIC X(10).

Working-Storage Section.
01 Field-1 PIC 999 Value Is 200.
.
.
.
IF Job-No = Field-1 PERFORM 200-Proc.
In the IF statement, Job-No is a nonnumeric data item and Field-1 is a numeric field.

5–46

8600 1518–307

Conditional Expressions

If the nonnumeric operand is an elementary data item or a nonnumeric literal, the
numeric operand is treated as though it had been moved to an elementary alphanumeric
data item of the same size as the numeric data item (in standard data format characters)
ignoring the decimal point, if any. The contents of this alphanumeric data item are then
compared to the nonnumeric operand. For detailed information on MOVE rules and data
item descriptions, refer to “MOVE Statement” in Section 7 and the “PICTURE Clause” in
Section 4.
In the preceding example, Job-No is an elementary alphanumeric data item that consists
of three characters. For the comparison, the numeric operand Field-1 is also considered
an alphanumeric data item of three characters.
If the nonnumeric operand is a group item, the numeric operand is treated as though it
were moved to a group item of the same size as the numeric data item (in standard data
format characters) ignoring the decimal point, if any. Then the contents of this group item
were compared to the nonnumeric operand. Consider the following example, which uses
data items from the preceding example:
IF Job-Data = Field-1 PERFORM Print-Proc.
Job-Data is a group item, and Field-1 will be considered as 13 alphanumeric characters in
length.
A noninteger numeric operand cannot be compared to a nonnumeric operand.
If Job-No contains 102, the result of the comparison is true.
How Comparisons Are Made
The comparison proceeds by comparing characters in corresponding character positions.
The evaluation starts from the high-order end and continues until either a pair of unequal
characters is encountered or the low-order end of the operand is reached, whichever
comes first.
The operands are equal if all pairs of characters compare equally when the low-order end
is reached.
The first encountered pair of unequal characters is compared to determine their relative
positions in the collating sequence. The operand that contains the character positioned
higher in the collating sequence is recognized as the greater operand.

8600 1518–307

5–47

Conditional Expressions

Comparisons Involving National Operands
A comparison of national operands is made according to a specified collating sequence of
characters. For more information on collating sequences, refer to “OBJECT-COMPUTER
Paragraph” in Section 3.
The size of an operand is the total number of national standard data format characters in
the operand.
Compared operands need not be equal in size, because the comparison proceeds as
though the shorter operand were extended on the right by enough space to make the
operands of equal size.
Comparisons Involving Index-Names, Index Data Items
An index-name is a user-defined word that names an index associated with a specific
table of data. Index-names are defined by an INDEXED BY phrase of the OCCURS
clause. An index data item contains values associated with an index-name. It is an
elementary data item described by a USAGE IS INDEX clause. For more information,
refer to “OCCURS Clause” and “USAGE Clause” in Section 4.
For comparisons involving index-names and index data items, relation tests can be made
only between:

5–48

•

Two index-names. The result is the same as if the corresponding occurrence
numbers were compared.

•

An index-name and a data-item (other than an index data item) or literal. The
occurrence number that corresponds to the value of the index name is compared to
the data item or literal.

•

An index data item and an index-name or another index data item. The actual values
are compared without conversion, that is, according to their occurrence in the table.
Refer to “Data-Names and Integers versus Index-Names” under “Table Handling” in
this section for information on conversion.

8600 1518–307

Conditional Expressions

Class Conditions
The class condition determines whether the operand is entirely numeric, alphabetic,
contains only lowercase or only uppercase alphabetic characters, or contains only
characters in a set specified by the CLASS phrase of the SPECIAL-NAMES paragraph of
the Environment Division.

identifier IS [ NOT ]
ïïï

ä
³
³
³
ã
³
³
³
æ

NUMERIC
ïïïïïïï
ALPHABETIC
ïïïïïïïïïï
ALPHABETIC-LOWER
ïïïïïïïïïïïïïïïï
ALPHABETIC-UPPER
ïïïïïïïïïïïïïïïï
class-name

å
³
³
³
â
³
³
³
ç

identifier

The identifier is a user-defined word that references a data item or a function that will be
the object of the class test. Only alphanumeric functions can be used in class tests. For
more information about identifiers, refer to Section 1.
NOT

NOT determines a test to be true if an operand is not of the specified class.
NUMERIC

This test classification determines whether the identifier consists entirely of the
characters 0 through 9, with or without an operational sign.
You cannot use the NUMERIC test with an identifier whose data description describes
the identifier as alphabetic or with a group item composed of elementary items whose
data description indicates the presence of operational sign(s).
If the data description of the identifier does not indicate the presence of an operational
sign, the identifier is determined to be numeric only if the contents are numeric and an
operational sign is not present.
If the data description of the identifier indicates the presence of an operational sign, the
identifier is determined to be numeric only if the contents are numeric and a valid
operational sign is present. Valid operational signs for data items described with the SIGN
IS SEPARATE clause are the standard data format characters + and - .
For information on the position and representation of valid operational signs, refer to
“PICTURE Clause” and “SIGN Clause” in Section 4.

8600 1518–307

5–49

Conditional Expressions

ALPHABETIC

This test classification determines if the identifier consists entirely of any combination of
characters A through Z, a through z, and spaces.
The ALPHABETIC test cannot be used with an identifier whose data description defines
the item as numeric.
ALPHABETIC-LOWER

This test classification determines if the identifier consists entirely of the lowercase
characters a through z and spaces.
The ALPHABETIC-LOWER test cannot be used with an identifier whose data description
describes the item as numeric.
ALPHABETIC-UPPER

This test classification determines if the identifier consists entirely of the uppercase
characters A through Z and spaces.
The ALPHABETIC-UPPER test cannot be used with an identifier whose data description
describes the item as numeric.
Note: For applications using the internationalization features, the data item being tested
is determined to be alphabetic, alphabetic-upper, or alphabetic-lower only if the contents
consist of any combination of the alphabetic characters in the truthset. To use a system
collating sequence other than the characters A through Z, a through z, and the space, the
program must use the ALPHABET FOR NATIONAL alphabet-name IS CCSVERSION
phrase of the SPECIAL-NAMES paragraph.
class-name

This test classification determines if the identifier consists only of the characters in the
set specified by the CLASS phrase of the SPECIAL-NAMES paragraph of the
Environment Division. For more information, refer to “SPECIAL-NAMES Paragraph” in
Section 3.
The class-name test must not be used with an item whose data description describes
the item as numeric.
Details
The USAGE of the operand used with the NUMERIC test must be DISPLAY or
COMPUTATIONAL. The USAGE of the operand used with the ALPHABETIC tests must
be DISPLAY. Refer to “USAGE Clause” in Section 4 for more information.

5–50

8600 1518–307

Conditional Expressions

Examples
IF Item-Price IS NUMERIC PERFORM Price-Calc
ELSE PERFORM Print-Error-Proc.
This first example tests the identifier Item-Price to see if it is entirely numeric. If it is, the
procedures under Price-Calc are performed. If the test is not true, the procedures under
Print-Error-Proc are performed.
SPECIAL-NAMES.
CLASS A-to-K IS "A" THROUGH "K".
.
.
.
IF Element IS A-to-K GO TO Para-4.
This second example tests identifier Element to see if it contains only the characters
specified in class-name A-to-K in the SPECIAL-NAMES paragraph.

8600 1518–307

5–51

Conditional Expressions

Condition-Name Conditions
In a condition-name condition, a conditional variable is tested to determine whether or
not its value is equal to one of the values associated with a condition-name.

condition-name

This is a user-defined word that assigns a name to a subset of values that a conditional
variable can assume.
A condition-name is defined as a level 88 entry in the Data Division.
If the condition-name is associated with a range or ranges of values, then the conditional
variable is tested to determine whether or not its value falls in this range, including the
end values.
Details
The rules for comparing a conditional variable with a condition-name value follow those
specified for relation conditions. For more information, refer to “Relation Conditions”
earlier in this section and to “Working-Storage Section” in Section 4.
The result of the test is true if one of the values corresponding to the condition-name
equals the value of its associated conditional variable.
Example
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Dept-Code PIC X.
88 Operations Values"A" Thru "D" .
88 Programming Values "E" Thru "P" .
88 Documentation Values "Q" Thru "T" .
88 Personnel Values "U" Thru "Z" .
.
.
.
PROCEDURE DIVISION.
IF Programming PERFORM Prog-Para.
IF NOT Personnel PERFORM Activity-Para.
This example tests conditional variable Dept-Code to see if it contains the range of values
described for condition-name Programming. If it does, the procedure Prog-Para will be
performed. The second statement tests Dept-Code for the values not described for
condition-name Personnel, that is, if Dept-Code contains the values “A” through “T”. If it
does, then the procedure Activity-Para will be performed.

5–52

8600 1518–307

Conditional Expressions

Switch-Status Conditions
A switch-status condition determines the ON or OFF status of a switch. The switch
name and the ON or OFF value associated with the condition must be defined in the
SPECIAL-NAMES paragraph of the Environment Division. For more information, refer to
“SPECIAL-NAMES Paragraph” in Section 3.

condition-name

This is a user-defined word assigned to the status of a switch or device.
Details
The result of the test is true if the switch is set to the specified position corresponding to
the condition-name.
Example
ENVIRONMENT DIVISION.
.
.
.
SPECIAL-NAMES.
SW5 ON STATUS IS SW5-ON.
.
.
.
PROCEDURE DIVISION.
IF SW5-ON PERFORM SEARCH-PROC.
.
.
.

This example tests switch SW5 for its ON or OFF status. If condition-name SW5-ON
tests true, the procedures specified in SEARCH-PROC will be performed.

8600 1518–307

5–53

Conditional Expressions

Sign Conditions
The sign condition determines whether or not the algebraic value of an arithmetic
expression is less than, greater than, or equal to zero.

arithmetic-expression IS

[ NOT ]
ïïï

ä
³
ã
³
æ

POSITIVE
ïïïïïïïï
NEGATIVE
ïïïïïïïï
ZERO
ïïïï

å
³
â
³
ç

arithmetic-expression

This indicates an arithmetic operation and must contain at least one reference to a
variable. For example, you could not have COMPUTE A = 1 + 2, which contains two
literals.
NOT

NOT determines the test to be true if the arithmetic expression does not meet the
specified sign condition.
POSITIVE

When you specify POSITIVE, the test is determined to be true if the arithmetic
expression has a value greater than zero.
NEGATIVE

When you specify NEGATIVE, the test is determined to be true if the arithmetic
expression has a value less than zero.
ZERO

When you specify ZERO, the test is determined to be true if the arithmetic expression
has a value equal to zero.
Example
IF A / B Is Negative Add C To D Giving E.
This statement tests to see if the result of A divided by B has a value less than zero. If it
does, C will be added to D and the value stored in E.

5–54

8600 1518–307

Conditional Expressions

Event Condition
The event condition tests an event-valued file attribute, event-valued task attribute, or a
data item declared with the USAGE IS EVENT clause to determine whether the event is
TRUE or FALSE.

ä
³
ã
³
æ

event-task-attribute
event-file-attribute
event-data-name

å
³
â
³
ç

The use of an event-identifier as a condition returns the value TRUE when the event has
been caused and not reset. It returns the value FALSE when the event is reset. For
details, refer to the CAUSE statement in Section 6 and the RESET statement in
Section 7.

Boolean Condition
A Boolean condition determines whether a Boolean expression is true or false.
General Format
[NOT] Boolean-expression-1

General Rules

•

Boolean-expression-1 refers to Boolean items of length 1 only.

•

Boolean-expression-1 evaluates true if the result of the expression is 1 and evaluates
false if the result of the expression is 0.

•

The condition NOT Boolean-expression-1 evaluates the reverse truth-value of
Boolean-expression-1.

8600 1518–307

5–55

Conditional Expressions

Negated Simple Conditions
The logical operator NOT negates a simple condition.

NOT simple-condition
ïïï

NOT

This is a logical negator.
simple-condition

The simple-condition contains a comparison, the value of which is either TRUE or FALSE.
The simple condition can be a relation, class, condition-name, switch-status, or sign
condition.
Details
The negated simple condition produces the opposite truth value for a condition. Thus, the
truth value of a negated simple condition is TRUE if the truth value of the condition is
FALSE and FALSE if the truth value of the condition is TRUE.
Parentheses do not change the truth value of a negated condition.
Example
IF NOT A IS > = B
MOVE ITEM-2 TO ITEM-3
ELSE MOVE A TO ITEM-3.
This example tests the truth value of the relational condition “A is greater than or equal
to B.” If A is less than B, the condition is TRUE and ITEM-2 is moved to ITEM-3. If A is
greater than or equal to B, the condition is FALSE, and A is moved to ITEM-3.
The statement IF NOT A IS >= B could be phrased as IF A IS NOT >= B. Both
statements would cause the same results, but IF NOT A IS >= B is considered a negated
condition and IF A IS NOT >= B is a relation condition that contains the optional word
NOT.

5–56

8600 1518–307

Conditional Expressions

Complex Conditions
A complex condition is a condition in which one or more logical operators act upon one or
more conditions.
A logical operator is one of the reserved words AND, OR, or NOT. The reserved words
AND and OR are called logical connectors; NOT is a logical negator. Logical operators
must be preceded and followed by a space.
The logical operators and their meanings are as follows:

Logical
Operator

Description

Effect on Condition

AND

Logical conjunction

The truth value is TRUE if both of the joined
conditions are TRUE; FALSE if one or both of
the joined conditions is FALSE.

Logical inclusive OR

The truth value is TRUE if one or both of the
included conditions are TRUE; FALSE if both
included conditions are FALSE.

NOT

Logical negation or
reversal of truth value

The truth value is TRUE if the condition is
FALSE and FALSE if the condition is TRUE.

The truth value of a complex condition results from the interaction of all the stated logical
operators on the individual truth values of simple conditions, or the intermediate truth
values of conditions logically connected or logically negated.
Table 5–6 shows the truth table for complex conditions with logical operators. For
example, the first line of Table 5–6 shows the following:

•

A simple condition that results in the variable A is TRUE.

•

A simple condition that results in the variable B is TRUE.

•

If a complex condition uses the logical operator AND, and both A and B are TRUE,
the result of that complex condition is TRUE.

•

If a complex condition uses the logical operator OR, and both A and B are TRUE, the
result of that complex condition is TRUE.

•

If a complex condition uses the logical negator NOT to negate the simple condition
that results in A, and both A and B are TRUE, the result of that complex condition is
FALSE.

8600 1518–307

5–57

Conditional Expressions

Table 5–6. Truth Table for Logical Operators

Values of Condition

TRUE

Values of Complex Condition

A AND B

A OR B

NOT A

TRUE

FALSE

TRUE

FALSE

TRUE

FALSE

TRUE

FALSE

TRUE

FALSE

TRUE

Example
EVALUATE TRUE ALSO TRUE
WHEN B <= C AND D <= E ALSO E NOT = F OR 10
COMPUTE A = C + 10
WHEN OTHER PERFORM Para-3
END-EVALUATE.
This example evaluates several conditions: The COMPUTE statement will be executed if
B is equal to or less than C, D is equal to or less than E, and if E does not equal F or 10.
For all other conditions, Para-3 will be executed.

Allowed Combinations of Elements
Complex conditions can include simple conditions, the logical operators AND and OR, the
logical negator NOT, and parentheses.
Although parentheses are not needed when either AND or OR (but not both) is used
exclusively in a combined condition, parentheses can be used to affect a final truth value
when a mixture of AND, OR and NOT is used. Refer to “Precedence in Evaluation of
Complex Conditions” later in this section for information on how parentheses affect a
complex condition.
Table 5–7 shows the allowable combinations of conditions, logical operators, and
parentheses.
Note that there must be a one-to-one correspondence between left and right
parentheses.

5–58

8600 1518–307

Conditional Expressions

Table 5–7. Combinations of Conditions, Logical Operators, and
Parentheses

Element, When Not First, Can Be Immediately
Given the
Following
Element:

Preceded Only
By:

Followed Only By:

First

Last

Simplecondition

Yes

OR, NOT, AND, )

OR, AND, )

OR or AND

Simple-condition,
)

Simple-condition, NOT, (

NOT

Yes

OR, AND, (

Simple-condition, (

(

Yes

OR, NOT, AND, (

Simple-condition, NOT, (

)

Yes

Simple-condition,
)

OR, AND, )

Example
SEARCH Tab1
WHEN (Age IS < 45 OR Age is > 35)
AND ( "V" is = Operations OR Dept)
PERFORM Op-Proc
END-SEARCH.
This example searches the table Tab1, and tests the “Age is less than or greater than”
conditions. If one of these conditions is TRUE, Tab1 is searched to see if Operations or
Dept equals “V”. If either of these conditions is TRUE, the statements in Op-Proc will be
executed.

8600 1518–307

5–59

Conditional Expressions

Combined Condition Format
A combined condition results from connecting conditions with one of the logical
operators AND or OR.

condition-1

ä
ã
æ

AND
ïïï
OR
ïï

å
â
ç

condition-2

å
â
ç

...

condition-1
condition-2

These elements can be any one of the following:

•

A simple condition

•

A negated simple condition

•

A combined condition

•

A negated combined condition; that is, the NOT logical operator followed by a
combined condition enclosed in parentheses

•

Combinations of the previous conditions that follow the rules summarized in
Table 5–7.

AND

This is a logical connector. The value of the combined conditions is TRUE if both
conditions are TRUE.
OR

This is a logical connector. The value of the combined conditions is TRUE even if only
one of them is TRUE.
Example
IF SW5-ON AND Sale-Item IS ALPHABETIC
MOVE Sale-Item To Report-Line-1
ELSE IF Regular-Item IS ALPHABETIC
AND NOT Regular-Item < = Sale-Item
MOVE Regular-Item To Report-Line-1
END-IF.
This example illustrates combined conditions. IF SW5-ON is a switch-status condition;
Sale-Item IS ALPHABETIC and Regular-Item IS ALPHABETIC are class conditions; and
NOT Regular-Item <= Sale-Item is a negated relative condition. This example uses the
logical connector AND.

5–60

8600 1518–307

Conditional Expressions

If the switch status of SW5 is TRUE and the Sale-Item consists entirely of alphabetic
characters, the data in Sale-Item moves to Report-Line-1. If one or both of these
conditions is FALSE, Regular-Item is tested to see if it consists entirely of alphabetic
characters. If this tests TRUE, Regular-Item is tested to see if it is not less than or equal
to Sale-Item. If this is also TRUE, the data in Regular-Item moves to Report-Line-1.

Abbreviated Combined Relation Conditions
Any simple or negated simple relation condition other than the first that appears in a
combined conditional statement can be abbreviated.
You can abbreviate a combined conditional statement if the sequence of relation
conditions:

•

Has no parentheses

•

Is combined by a logical connector (AND or OR)

•

Contains identical subjects

•

Contains identical subjects and relational operators

The sequence can be abbreviated as follows:

•

You can omit identical subjects. For example:
IF A = B AND = C
This is equivalent to IF A = B AND A = C.

•

You can omit identical subjects and relational operators. For example:
IF A = B AND C
This is equivalent to IF A = B AND A = C.

8600 1518–307

5–61

Conditional Expressions

The use of abbreviated relations in conditional statement sequences that contain
parentheses is a Unisys extension. When a condition is abbreviated, the subject and the
relational operator are assumed, and are declared immediately before the object for
which the assumption was made. This situation occurs even if the expression in which
the relational operator, or the subject (or both), is embedded within a parenthetical
expression. For example, the statement:
IF (A = 1) AND (B-2) AND (C-3) AND (D-4) THEN...
is expanded to:
IF (((A = 1) AND (A = B-2))) AND
(A = (C-3))) AND (A = (D-4))) THEN...

relation-condition

ä
³
ã
³
æ

ä AND å
ã ïïï â
æ OR ç
ïï

[ NOT ] [ relational-operator ]
ïïï

object

å
³
â
³
ç

. . .

relation-condition

This causes a comparison of two operands, each of which can be a data item referred to
by an identifier, a literal, the value resulting from an arithmetic expression, or an indexname.
AND

This is a logical connector. The truth value is TRUE if both of the joined conditions are
TRUE; FALSE if one or both is FALSE.
OR

This is a logical connector. The truth value is TRUE if one or both of the included
conditions are TRUE; FALSE if both are FALSE.
NOT

This can be part of a relational operator, if immediately followed by any of the following:
GREATER >
LESS <
EQUAL =
GREATER THAN OR EQUAL TO >=
LESS THAN OR EQUAL TO <=
NOT can also be a logical negator, which would make a negated relation condition.
When used, NOT causes the truth value to be TRUE if the condition is FALSE and FALSE
if the condition is TRUE.

5–62

8600 1518–307

Conditional Expressions

relational-operator

This specifies the type of comparison to be made in the relation condition and refers to
the following:
GREATER >
LESS <
EQUAL =
GREATER THAN OR EQUAL TO >=
LESS THAN OR EQUAL TO <=
object

This refers to an operand in the comparison test.
Relation Conditions Details
In a sequence of relation conditions, you can use both forms of abbreviation; that is,
omission of the subject or omission of the subject and relational-operator.
The effect of using abbreviations is as if the last preceding stated subject were inserted
in place of the omitted subject, and the last stated relational-operator were inserted in
place of the omitted relational-operator. The result of such implied insertion must comply
with the rules of Table 5–7.
The insertion of an omitted subject and the relational-operator ends once a complete
simple condition occurs in a complex condition.
Examples
The examples in the following table show abbreviated combined and negated combined
relation conditions and their expanded equivalents.

Abbreviated Condition

Expanded Equivalent

a > b AND NOT < c OR d

((a > b AND (a NOT < c)) OR (a NOT < d))

a NOT EQUAL b OR c

(a NOT EQUAL b) OR (a NOT EQUAL c)

NOT a = b OR c

(NOT (a = b)) OR (a = c)

NOT (a GREATER b OR < c)

NOT ((a GREATER b) OR (a < c))

NOT (a NOT > b AND c AND NOT d)

NOT ((((a NOT > b)
AND (a NOT > c))
AND (NOT (a NOT > d))))

8600 1518–307

5–63

Conditional Expressions

Precedence in Evaluation of Complex Conditions
Parentheses specify the order in which individual conditions in complex conditions will be
evaluated when you want to depart from the implied evaluation precedence.
Conditions in parentheses are evaluated first. Within nested parentheses, evaluation
proceeds from the least inclusive condition to the most inclusive condition. An entire
complex condition can be considered a nested structure of hierarchical levels with the
entire complex condition itself being the most inclusive level. In this context, the
evaluation of the conditions is an entire complex condition and proceeds according to the
following rule, recursively applied where necessary.
For conditions without parentheses or those that contain parenthesized conditions at the
same level of inclusiveness, the evaluation proceeds in the following implied hierarchical
order to determine the final truth value:
1. Values for arithmetic expressions
2. Truth values for simple conditions in the following order:
a.

Relation (following the expansion of any abbreviated relation condition)

b. Class
c.

condition-name

d. Switch-status
e. Sign
3. Truth values for negated simple conditions
4. Truth values for combined conditions. The AND logical operators are evaluated
before OR logical operators.
5. Truth values for negated combined conditions
6. Truth values of consecutive operations of the same hierarchical level from left to
right when the sequence of evaluation is not completely specified by parentheses

5–64

8600 1518–307

Conditional Expressions

Example
IF CURRENT-MONTH AND DAY1 = 6 OR 12.
For this example, evaluation proceeds in the following order:
1. Truth value of the simple condition-name condition (CURRENT-MONTH is TRUE).
2. Truth value for the relation DAY1 = 6.
3. Truth value for combined conditions using AND (CURRENT-MONTH is TRUE AND
DAY1 = 6).
4. Truth value for the relation DAY1 = 12.
5. Truth value for combined conditions using OR (the combined condition is the
abbreviated combined relational, subject is DAY1, object is = 12, so DAY1 = 12).
Two possible conditions satisfy this example:

•

CURRENT-MONTH is TRUE AND DAY1 = 6.

•

DAY1 = 12.

8600 1518–307

5–65

Table Handling

Table Handling
Table handling refers to a way of organizing data items into a table, so that they can be
accessed according to their position in the table.
You can create multidimensional variable-length tables, specify ascending or descending
keys, and search a dimension of a table for an item that satisfies a condition.

Defining a Table
One way to describe repeating items that make up a table is to use a series of separate
data description entries that have the same level-number and that are all subordinate to
the same group item, as in the following example:
01 Seasons.
05 Filler
05 Filler
05 Filler
05 Filler

PIC
PIC
PIC
PIC

X(6)
X(6)
X(6)
X(6)

VALUE
VALUE
VALUE
VALUE

IS
IS
IS
IS

"Spring".
"Summer".
"Autumn".
"Winter".

However, this approach has several undesirable effects: it can generate long tables that
are cumbersome to document; homogeneity of the table elements is not always
apparent; and accessing an individual element of such a table is very difficult.
A better approach is to define a table by including an OCCURS clause in the data
description entry of the item to be referenced. The OCCURS clause specifies that a data
item is a table element that is to be repeated as many times as stated. The name and
description of the data item apply to each repetition.
The following example shows a table defined by the item Mailing-Address. Twenty
occurrences of Mailing-Address are specified by the OCCURS clause, and each
occurrence consists of a name and an address.
01 Table-1.
02 Mailing-Address OCCURS 20 TIMES.
03 Name . . .
03 Address . . .
The OCCURS clause enables you to designate either a fixed number of occurrences for a
table element or a variable number of occurrences. For more information, refer to
“OCCURS Clause” in Section 4.

5–66

8600 1518–307

Table Handling

Table Dimensions
You can define the dimensions of a table by subordinating a table element under multiple
group items and including the OCCURS clause with the table element and the group
items that contain the element. Theoretically, you can define up to 48 dimensions for any
one table. However, due to current hardware limitations, the maximum number of
practical dimensions that you can use is 19. This number is derived by using subscripts
that range from 1 to 2 with element sizes of 1 byte or 1 hex unit for all dimensions. The
practical number of dimensions you can declare decreases with larger subscript ranges
or larger element sizes.
In the following example, the table defined by Department is not nested in any other
table, so it is a one-dimensional table. The table defined by employee, however, is nested
within one other table, Department, and is thus, a two-dimensional table.
01 Table-1.
02 Department OCCURS 10 TIMES.
03 Employee OCCURS 50 TIMES.
04 Name . . .
04 Address . . .
Note that the preceding example has been assigned the name Table-1. You do not need
to give a group name to the table unless you want to refer to the complete table as a
group item. For example, neither of the one-dimensional tables shown in the following
example has a group name:
01 Produce.
02 Lettuce OCCURS 2 TO 5 TIMES DEPENDING ON Lettuce-Count . . .
02 Cucumber . . .
02 Apple OCCURS 10 TIMES . . .

8600 1518–307

5–67

Table Handling

INDEXED BY Option
The optional INDEXED BY phrase in the OCCURS clause enables you to refer to the
subject of the entry (and subordinate entries) by a technique called indexing. Indexing is
especially useful for operations such as table searches and the manipulation of specific
items.
To use indexing, you assign one or more index-names to an item whose data description
entry contains an OCCURS clause. An index-name must be a unique word in the
program. The index associated with an index-name acts as a subscript, and its value
corresponds to an occurrence number for the item to which the index-name is
associated.
No separate entry describes the index associated with an index-name. At object time,
the contents of the index correspond to an occurrence number for the table dimension
with which the index is associated. In the following example, Apple-1 is an index-name
associated with a table of data:
01 Produce.
02 Lettuce . . .
02 Apple OCCURS 10 TIMES INDEXED BY Apple-1 . . .
02 Cucumber . . .

5–68

8600 1518–307

Table Handling

Initializing Tables
You can set initial values of tables either in the Data Division or through statements in
the Procedure Division.

In the Data Division
You can specify the initial values of table elements in the Working-Storage Section of the
Data Division as follows:

•

The table can be described as a series of separate data description entries all
subordinate to the same group item. Each data description entry can specify the
value of an element, or part of an element, of the table:
WORKING-STORAGE SECTION.
01 Seasons.
05 Filler PIC X(6) VALUE
05 Filler PIC X(6) VALUE
05 Filler PIC X(6) VALUE
05 Filler PIC X(6) VALUE

IS
IS
IS
IS

"Spring".
"Summer".
"Autumn".
"Winter".

In defining the record and its elements, any data description clause (USAGE,
PICTURE, and so forth) can be used to complete the definition, where required. The
previous example uses a picture clause of PIC X(6).

•

The hierarchical structure of the table can be shown by a REDEFINES entry and its
associated subordinate entries. The subordinate entries are repeated because of
OCCURS clauses and must not contain VALUE clauses:
WORKING-STORAGE SECTION.
01 Seasons PIC X(24)
VALUE IS "SpringSummerAutumnWinter".
01 Season-Table REDEFINES Seasons.
02 Season PIC X(6) OCCURS 4 TIMES.

•

All the dimensions of a table can be initialized by associating the VALUE clause with
the description of the entry defining the entire table. The lower level entries will
show the hierarchical structure of the table; lower level entries must not contain
VALUE clauses:
03 Seasons PIC X(28)
VALUE IS "Spring1Summer2Autumn3Winter4".
03 Season-Table REDEFINES Seasons OCCURS 4 TIMES.
05 Name PIC X(6).
05 Number PIC 9.

For detailed information on these clauses, refer to “REDEFINES Clause” and “VALUE
Clause” in Section 4.

8600 1518–307

5–69

Table Handling

In the Procedure Division
The INITIALIZE statement sets the initial values for an entire table or for specific
elements of a table. For detailed information on the syntax of this statement, refer to
“INITIALIZE Statement” in Section 6.
If you are using the INDEXED BY option of the OCCURS clause, the initial value of an
index at object time is undefined. You must initialize an index before you use it. The
following Procedure Division statements can assign an initial value to an index:

•

PERFORM statement with the VARYING phrase
During execution, this statement augments the values referenced by one or more
identifiers or index-names in an orderly fashion. For detailed information on the
syntax of this statement, refer to Section 7.

•

SEARCH statement with the ALL phrase
This statement performs a binary search of a table and looks for a table element that
satisfies the specified condition. It then adjusts the value of the associated index to
indicate that table element. For detailed information on the syntax of the SEARCH
statement, refer to Section 8.

•

SET statement
This statement assigns a value to an index or to index data items. For detailed
information on the syntax of the SET statement, refer to Section 8.

References to Table Items
You can refer to table items by specifying the data-name with the occurrence number.
The occurrence number is called a subscript.
Whenever you refer to a table element or a condition-name that is associated with a
table element, the reference must indicate which occurrence of the element is intended.
This rule applies except for the SEARCH statement.
In a one-dimensional table, the occurrence number of an element table provides
complete information for you to access it. For tables of more than one dimension, you
must supply an occurrence number for each dimension of the table.
Consider the following example:
02 Apple OCCURS 10 TIMES . . .
03 Granny-Smith . . .
03 Delicious OCCURS 5 TIMES . . .
A reference to the fourth Apple or the fourth Granny-Smith would be complete.
However, a reference to the fourth Delicious would be incomplete, because Delicious
could be one of five possible occurrences in a two-dimensional table. To reference
Delicious, you must define a specific occurrence of it; for example, the fourth Delicious in
the fifth Apple.

5–70

8600 1518–307

Table Handling

Subscripting
You specify occurrence numbers by appending one or more subscripts to a conditionname or a data-name.

ä
ã
æ

condition-name
data-name-1

å
â
ç

(

ä
³
³
³
ã
³
³
³
æ

integer
data-name-2
index-name-1

[ + integer ]
ï
[ + integer ]
ï

ALL
ïïï
arithmetic-expression

å
³
³
³
â
³
³
³
ç

. . . )

condition-name

This is a user-defined word that assigns a name to a subset of values. A conditional
variable can assume these values.
A condition-name is defined as a level-number 88 entry in the Working-Storage Section of
the Data Division and can be associated with a range of values.
data-name-1

This is a user-defined word and can consist of the characters A through Z, a through z, 0
through 9, and the hyphen (-). The hyphen cannot appear as the first or last character.
()

The left and right parentheses enclose the subscript.
integer
data-name-2
index-name-1

The integer represents the occurrence number. The lowest permissible occurrence
number is 1. The highest permissible occurrence number is the maximum number of
occurrences of the item as specified in the OCCURS clause.
You can also represent a subscript with a data-name or an index name: data-name-2
must refer to an integer numeric elementary item, and index-name-1 is an index-name
associated with a table.
You can mix integers, data-names, and index-names in a single set of subscripts that
refer to an individual occurrence in a multidimensional table.

8600 1518–307

5–71

Table Handling

+ integer
– integer

These can follow a data-name for relative subscripting or an index-name for relative
indexing. The plus sign (+) or the minus sign (–) and an integer are used as an increment
or decrement, respectively.
ALL

ALL can be used as a subscript only for data-names that are used as arguments to
functions. The ALL subscript causes the argument to be repeated the number of times
specified in the OCCURS clause. You cannot use ALL with a condition-name.
arithmetic-expression

An arithmetic-expression can be used as a subscript. In addition, integers, data-names,
and arithmetic-expressions can be mixed in a single set of subscripts that is a reference
to an individual occurrence in a multidimensional table. Arithmetic-expressions used in
subscripts must be references to integer values.
Details
You write subscripts, which are enclosed in parentheses, immediately following any
qualification for the name of the table element. The number of subscripts in such a
reference must equal the number of dimensions in the table whose element is being
referenced. That is, there must be a subscript for each OCCURS clause in the hierarchy
containing the data-name. Moreover, the data-name itself must also have a subscript.
When the table element requires more than one subscript, write the subscripts in order
of the outermost to the innermost table. A multi-dimensional table can be thought of as a
series of nested tables. The outermost table is the major table; the innermost, the minor
table. Therefore, you would write the subscripts from left to right in the order major,
intermediate, and minor.
Subscript a reference to an item only if the item is either of the following:

•

A table element

•

An item or a condition-name in a table element

Example
The following example shows the data-description entries for a three-dimensional table
definition.
01

5–72

CENSUS-TABLE.
05 CONTINENT-TABLE
10 CONTINENT-NAME
10 COUNTRY-TABLE
15 COUNTRY-NAME
15 CITY-TABLE
20 CITY-NAME
20 CITY-POPULATION

OCCURS 8 TIMES.
PIC X(16).
OCCURS 15 TIMES.
PIC X(18).
OCCURS 20 TIMES.
PIC X(10)
PIC X (12)

8600 1518–307

Table Handling

Related Information
The following table provides references for additional information related to this topic:

For information about . . .

Refer to . . .

The USAGE and OCCURS clauses

Section 4

The INITIALIZE Statement,
PERFORM Statement, SEARCH
Statement, and SET Statement

Sections 6, 7, and 8

Error handling for subscripts

The BOUNDS compiler control
option in Section 15

Subscripts Using Integers or Data-Names
When an integer or data-name represents a subscript, it can refer to items in different
tables. Elements in these tables are not required to be of the same size. The same
integer or data-name can appear as the only subscript with one item and as one of two or
more subscripts with another item.
Subscripts Using Index names
An index-name can refer to only the table with which it is associated through the
INDEXED BY phrase of the OCCURS clause.
Relative indexing is an added option that you can use to refer to a table element or to an
item in a table element. When the name of a table element is followed by a subscript of
the form (index-name + or – integer), the occurrence number required to complete the
reference is the same as if the index-name were set up or down by the integer through
the SET statement before the reference. The use of relative indexing does not cause the
object program to alter the value of the index.
Data-Names and Integers versus Index-Names
The primary difference between subscripting with an integer or data-name and
subscripting with an index-name is in the method used to access the desired table entry.
At object time, a subscript is an integer that represents an occurrence in a table, that is, 1
for the first entry, 2 for the second, and so forth.
Since the subscript data-item contains only an occurrence number of the item to be
accessed, the program must multiply the occurrence number by the length of a table
entry to locate the desired item.
For example, consider a table defined as follows:
Y PIC 9(4) COMP OCCURS 10 TIMES INDEXED BY NDX.

8600 1518–307

5–73

Table Handling

Assume that a numeric data-item SUB has also been declared for use as a subscript.
To execute the statement MOVE Y(SUB) TO X, the program must first multiply the value
in SUB by the length of the table element Y. (The multiplication is repeated each time
you use SUB to access an item.) This gives the offset value of the desired element from
the beginning of the table. Adding the offset value to the beginning address of the table
(actually, to an address one element-length before the beginning of the table) gives the
location of the item.
Literal subscripts, for example Y(5), are calculated once at compile time, so they involve
the same code as nonsubscripted items.
An index-name contains an offset value to a table instead of a simple occurrence
number. The statement SET NDX TO data-name causes the program to compute the
offset value of the element whose position is given by data-name. SET NDX UP (or
DOWN) BY 1 causes the length of one table item to be added to (or subtracted from) the
value in NDX.
In the statement MOVE Y(NDX) TO X, the location of Y is determined by adding the
contents of NDX to the beginning address (actually, an address one element-length
before the beginning) of the table. The index does not require the multiplication that is
required for the subscript.
The index value is always carried in its final form as an offset value. Multiplication is
performed, when applicable, at the time the index is set, not each time it is used.
If you are using indexing, which contains an offset value to a table, and then use a
statement that requires an occurrence number, conversion takes place. The offset value
will be converted into an occurrence number.
Index Data Items
The value of an index can be made accessible to an object program by storing the value
in an index data item. Index data items are memory locations and are described in the
program by a data description entry that contains a USAGE IS INDEX clause. The index
value is moved to the index data-name by the execution of a SET statement.
Refer to “USAGE Clause” in Section 4 and to “SET Statement” in Section 8 for more
information.

5–74

8600 1518–307

Sort and Merge Operations

Sort and Merge Operations
The COBOL sort function orders the occurrence of records in one or more files. Sort
functions are performed according to a set of specified keys that are contained in each
record.
The COBOL merge function combines two or more identically ordered files according to
specified keys.

Sorting
A sort file is a collection of records to be sorted by a SORT statement.
Sort files often require special processing, such as addition, deletion, creation, alteration,
and editing of the individual records in the file. Special processing might be needed
before or after the records are reordered by the sort. The COBOL sort function enables
you to do this special processing and to specify whether it should occur before or after
the sort.
A COBOL program can contain any number of sorts, each with its own input and output
procedures. The sort function automatically causes execution of these procedures at the
specified point.
In an input procedure, the RELEASE statement creates a sort file. When the input
procedure has completed, those records processed by the RELEASE statement
compose the sort file. This file is available only to the SORT statement.
Execution of the SORT statement arranges the entire set of records in the sort file
according to the keys specified. The sorted records are made available from the sort file
through the RETURN statement during execution of the output procedure.
The sort file does not have label procedures that the programmer can control. The rules
for blocking and for allocation of internal storage are unique to the SORT statement. The
RELEASE and RETURN statements imply nothing about buffer areas, blocks, or reels.
A sort file, then, is an internal file created from the input file by the RELEASE statement,
processed by the SORT statement, and then made available to the output file by the
RETURN statement. The sort file itself is referred to and accessed only by the SORT
statement.

Merging
A merge file is a collection of records to be merged with another input file by a MERGE
statement.
Merged files sometimes require special processing, such as addition, deletion, creation,
alteration, and editing of the individual records in the file. The COBOL merge function
enables you to execute output procedures as the merged output is created.

8600 1518–307

5–75

Sort and Merge Operations

The merged records from the merge file are made available through the RETURN
statement in the output procedure.
The merge file does not have label procedures that the programmer can control. The
rules for blocking and for allocation of internal storage are unique to the MERGE
statement. The RETURN statement implies nothing about buffer areas, blocks, or reels.
A merge file, then, is an internal file created from input files by combining them (MERGE
statement) as the file is made available (RETURN statement) to the output file. The
merge file itself is referred to and accessed only by the MERGE statement.

Sort and Merge Constructs
A sort or a merge file is named by a file control entry in the Environment Division and
described by a sort-merge file description entry in the Data Division. A sort file is referred
to in the Procedure Division by the SORT, RELEASE, and RETURN statements. A merge
file is referred to by the MERGE and RETURN statements.
The following list shows the COBOL constructs to use with sort and merge operations.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.

•

Use Format 4 of the FILE-CONTROL paragraph. This file control entry declares the
relevant physical attributes of a sort or a merge file.
Each sort or merge file must be specified in the SELECT clause of the FILECONTROL paragraph and must have a sort-merge file description entry in the Data
Division of the same program.
Each sort or merge file described in the Data Division must be specified only once in
the FILE-CONTROL paragraph.
Since the file-name in the SELECT clause represents a sort or a merge file, only the
ASSIGN clause can follow the file-name in the FILE-CONTROL paragraph.
Use the ASSIGN clause to associate the file reference with a storage medium
reference.

•

Specify the memory area to be shared by the sort or merge files in the SAME
RECORD/SORT/SORT-MERGE AREA clause of the I-O-CONTROL paragraph.
The files referenced in the SAME RECORD/SORT/SORT-MERGE AREA clause are
not required to have the same organization or access.
Each file-name specified in the SAME RECORD/SORT/SORT-MERGE AREA clause
must be specified in the FILE-CONTROL paragraph of the same program.
For detailed information on the syntaxes, uses, and restrictions of these paragraphs,
refer to “FILE-CONTROL Paragraph” and “I-O-CONTROL Paragraph” in Section 3.

5–76

8600 1518–307

Sort and Merge Operations

DATA DIVISION.
FILE SECTION.

•

Use sort-merge file description entry, Format 4, in the File Section; see Section 4 for
details.
Each sort or merge file specified in a sort-merge file description entry must also be
specified in the SELECT clause of the FILE-CONTROL paragraph of the Environment
Division of the same program.
The sort-merge file description entry (the SD entry) furnishes information on the
physical structure and record-names that pertain to a sort or a merge file.
The FILE SECTION header is followed by a sort-merge file description entry that
consists of a level indicator, a file-name, and a series of independent clauses.
The clauses of an SD entry specify the size and the names of the data records
associated with a sort file or a merge file.

•

Record description entries are written immediately after the sort-merge file
description entry. A record description consists of a set of data description entries
that describe the characteristics of a particular record. Each data description entry
consists of a level number followed by the data-name or FILLER clause, if specified,
followed by a series of independent clauses as required. A record description can
have a hierarchical structure. Therefore, the clauses used with an entry can vary
considerably, depending upon whether or not the entry is followed by subordinate
entries.
The RECORD clause of the SD entry is the same as the RECORD clause in the FD
entry for sequential files.
The DATA RECORDS clause is the same as the DATA RECORDS clause in the FD
entry for sequential files. The DATA RECORDS clause is an obsolete element in
Standard COBOL and will be deleted from the next revision of Standard COBOL.

•

Refer to “File Section” in Section 4 for detailed information on syntax, usage, and
restrictions.

PROCEDURE DIVISION.

•

Use the SORT statement to sequentially order a file on a set of specified keys and to
make the sort file available to output procedures or an output file.

•

Use the RELEASE statement to transfer records to the initial phase of a SORT
operation and to write records to a sort file.

•

Use the RETURN statement to obtain sorted or merged records from the final phase
of a SORT or MERGE operation and to read records from a sort file.

•

Use the MERGE statement to combine two or more identically sequenced files on a
specified key.

Refer to “RELEASE Statement,” “RETURN Statement,” and “MERGE Statement” in
Section 7 and to “SORT Statement” in Section 8 for detailed information and syntax.

8600 1518–307

5–77

Sort and Merge Operations

Example
The following example shows the COBOL constructs used in sort and merge operations.
IDENTIFICATION DIVISION.
PROGRAM-ID. SORTMERGE-EXAMPLE.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT DATA-CAPTURE-1
ASSIGN
SELECT DATA-CAPTURE-2
ASSIGN
SELECT DATA-CAPTURE-3
ASSIGN
SELECT MASTER-FILE
ASSIGN
SELECT SHOW
ASSIGN
SELECT SORT-FILE
ASSIGN
SELECT MERGE-FILE
ASSIGN
DATA DIVISION.
FILE SECTION.
FD DATA-CAPTURE-1.
01 D-RECORD-1.
03 FILLER
PIC X(180).
FD DATA-CAPTURE-2.
01 D-RECORD-2.
03 FILLER
PIC X(180).
FD DATA-CAPTURE-3.
01 D-RECORD-3.
03 FILLER
PIC X(180).
FD MASTER-FILE.
01 M-RECORD.
03 FILLER
PIC X(180).
FD SHOW.
01 OUT-RECORD.
03 FILLER
PIC X(5).
03 PAYNO
PIC 9(5).
03 FILLER
PIC X(5).
03 DEPTNO
PIC X(10).
03 FILLER
PIC X(107).
SD SORT-FILE.
01 SORT-RECORD.
03 FILLER
PIC X(10).
03 ACC-NO
PIC 9(6).
03 FILLER
PIC X(10).
03 QTE
PIC 9(4).
03 FILLER
PIC X(10).
03 PRICE
PIC 9(10).
03 FILLER
PIC X(130).
SD MERGE-FILE.
01 MERGE-RECORD.
03 FILLER
PIC X(20).
03 PAY-NO
PIC 9(5).
03 FILLER
PIC X(50).
03 DEPT-NO
PIC X(10).

5–78

TO
TO
TO
TO
TO
TO
TO

DISK.
DISK.
DISK.
DISK.
PRINTER.
SORT.
MERGE.

8600 1518–307

Sort and Merge Operations

03 FILLER
PIC X(95).
PROCEDURE DIVISION.
BEGIN-SORT.
SORT SORT-FILE
ON ASCENDING KEY ACC-NO
INPUT PROCEDURE IS PROC-1 THRU END-1
OUTPUT PROCEDURE IS PROC-2 THRU END-2.
GO TO BEGIN-MERGE.
PROC-1.
OPEN INPUT DATA-CAPTURE-1.
PROC-1A.
READ DATA-CAPTURE-1 AT END GO TO END-1.
RELEASE SORT-RECORD.
GO TO PROC-1A.
END-1.
CLOSE DATA-CAPTURE-1.
PROC-2.
OPEN OUTPUT DATA-CAPTURE-2.
PROC-2A.
RETURN SORT-FILE AT END GO TO END-2.
MOVE SORT-RECORD TO D-RECORD-2.
WRITE D-RECORD-2.
GO TO PROC-2A.
END-2.
CLOSE DATA-CAPTURE-2.
BEGIN-MERGE.
OPEN OUTPUT SHOW.
MERGE MERGE-FILE ON ASCENDING KEY PAY-NO
USING MASTER-FILE, DATA-CAPTURE-3
OUTPUT PROCEDURE IS OUT-1.
OUT-1.
RETURN MERGE-FILE
AT END GO TO FINISH-1.
PERFORM WRITE-PROC.
WRITE-PROC.
MOVE SPACES TO OUT-RECORD.
MOVE PAY-NO TO PAYNO.
MOVE DEPT-NO TO DEPTNO.
WRITE OUT-RECORD.
FINISH-1.
CLOSE MERGE-FILE.
CLOSE SHOW.
STOP RUN.
In the Environment Division, SORT-FILE is declared as a sort file, and MERGE-FILE is
declared as a merge file.
SORT-FILE and MERGE-FILE have SD entries in the Data Division.

8600 1518–307

5–79

Sort and Merge Operations

Data-Capture-1 will be sorted by ACC-NO on an ascending key. The input procedure
opens and reads DATA-CAPTURE-1. If the file is not at the end, SORT-RECORD is
transferred and written to SORT-FILE. If the file is at the end, DATA-CAPTURE-1 is
closed. DATA-CAPTURE-2 is opened output. The next record of SORT-FILE is read. If the
file is at the end, then DATA-CAPTURE-2 is closed.
Then the merge begins. The file SHOW is opened output. MASTER-FILE and DATACAPTURE-3 are merged into MERGE-FILE. The records in MERGE-FILE are read, and
their data is moved to OUT-RECORD. When MERGE-FILE is at end, MERGE-FILE and
SHOW are closed.

5–80

8600 1518–307

Section 6
Procedure Division Statements A–H
This section illustrates and explains the syntax of the Procedure Division statements.
Statements beginning with the letters A through H are listed in alphabetical order with
the following information:

•

A brief description of the function of the statement

•

A syntax diagram for each format of the statement (if you need information on how
to interpret a COBOL syntax diagram, refer to Appendix C)

•

A statement of what portion of the syntax, if any, can be used interactively in a Test
and Debug System (TADS) session

•

An explanation of the elements in the syntax diagram

•

Details, rules, and restrictions about the particular statement

•

An example of the statement

•

References to additional information relevant to the statement

Detailed information about language elements common to many Procedure Division
statements, such as user-defined names, literals, and identifiers, is provided in Section 1.
Concepts such as arithmetic and conditional expressions, and operations such as table
handling, sorting, and merging are described in Section 5.

8600 1518–307

6–1

ACCEPT Statement

ACCEPT Statement
The ACCEPT statement makes low-volume data available to a specified data item.

Format

Use

Format 1

This format transfers data from a hardware device to a data item.

Format 2

This format transfers data from date and time registers to a data item.

Format 3

This format returns the number of entries in a storage queue (STOQ)
into the entry-data-length field of the specified STOQ parameter block.

Format 4

This format transfers a formatted system date or time to a data item
based on the type, convention, and language in effect for the item.

Format 1: Transfer Data from Hardware Device
ACCEPT
ïïïïïï

identifier-1

[ FROM {mnemonic-name-1 } ]
ïïïï

Explanation
identifier-1

This is the data item to which data is transferred from the hardware device.
mnemonic-name-1

The mnemonic-name must be specified in the SPECIAL-NAMES paragraph of the
Environment Division, and must be associated with the hardware name ODT. If the
FROM clause is not specified, the hardware device is assumed to be ODT.

6–2

8600 1518–307

ACCEPT Statement

Details
The $ANSI and $ANSICLASS compiler control options control the transfer of data to the
receiving item. Table 6–1 explains the effects of this option upon the transfer of data.
Table 6–1. Effect of the $ANSI and $ANSICLASS Compiler Options

When the
$ANSI or
$ANSICLAS
S option
is . . .

And . . .

Then . . .

Set

The size of the transferred
data is less than the size of
the receiving data item.

The transferred data is leftjustified in the receiving data
item, and a “MORE” prompt is
displayed on the ODT requesting
additional input.

Set

The size of the transferred
data is greater than the size of
the receiving data item.

The left-most digits are moved
into the receiving field and the
remainder of the digits are
ignored.

Reset

The size of the transferred
data is greater than the size of
the receiving data item.
(Leading zeros are not
considered in computing the
size of the transfer field.)

The compiled code issues a runtime error and prompts you to reenter your data.

Reset

The receiving field is
alphanumeric or national.

The transferred data is stored
aligned to the left and blank-filled.

Reset

The receiving field is numeric.

The transferred data is stored
aligned to the right and zero-filled.

Any necessary conversion of data from one form of internal representation to another
takes place during data transfer. Control information is removed from national data
before the data is transferred into the receiving national data field.
Data transferred to a numeric field is validated by the compiler to prevent you from
inadvertently entering a nonnumeric character into a numeric field. Additionally, you
cannot enter a number that is too large to fit into the named data item. In either case, an
error message appears requesting that you re-enter your data.
Data accepted into an elementary data item of class alphanumeric can contain national
characters in external format. In this situation, the control information necessary for
external format is retained in the content of the data item.

8600 1518–307

6–3

ACCEPT Statement

Examples
ACCEPT keyboard-option
In this example, the ACCEPT statement transfers data from the ODT (that is, the default
hardware device) to the data item keyboard-option.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
ODT IS TERMINAL1.
.
.
.
PROCEDURE DIVISION.
PARA-1.
ACCEPT keyboard-option FROM TERMINAL1.
In this example, the ACCEPT statement transfers data from the ODT to the data item
keyboard-option. The ODT has been given the mnemonic-name TERMINAL1 in the
SPECIAL-NAMES paragraph of the Environment Division.

6–4

8600 1518–307

ACCEPT Statement

Format 2: Transfer Data from Date and Time Registers

ACCEPT identifier-2 FROM
ïïïïïï
ïïïï

ä
³
³
³
³
³
ã
³
³
³
³
³
æ

DATE [ YYYYMMDD ]
ïïïï ïïïïïïïïïïïï
DAY [ YYYYDDD ]
ïïï ïïïïïïïïïïï
DAY-OF-WEEK
ïïïïïïïïïï
TIME
ïïïï
TIMER
ïïïïï
TODAYS-DATE [ MMDDYYYY ]
ïïïïïïïïïïï ïïïïïïïïïïïï
TODAYS-NAME
ïïïïïïïïïïï

å
³
³
³
³
³
â
³
³
³
³
³
ç

Explanation
In this format, the ACCEPT statement transfers one of the special registers (date, day,
time, and so on) to the data item named by identifier-2. The transfer of data occurs
according to the rules of the MOVE statement. For information about these rules, refer
to “MOVE Statement” in Section 7. Special registers are conceptual data items that are
not declared in a COBOL program. Each register is described in the following list.
identifier-2

This identifier is the user-defined name of the data item.
DATE

This register contains the data elements year, month, and day. If DATE is followed by the
qualifier YYYYMMDD, the year is four digits, otherwise the year is two digits.
The sequence of the data elements is from high order to low order (year, month, day).
Therefore, July 1, 1988 is expressed as 880701, or, if qualified by YYYYMMDD, July 1,
1988 is expressed as 19880701.
When accessed by a COBOL program, this register behaves as if it had been described
in the COBOL program as an unsigned elementary numeric integer data item six digits in
length (PIC 9(6) COMP), or, if qualified by YYYYMMDD, a data item eight digits in length
(PIC 9(8) COMP).
Data from the DATE register cannot be transferred to a national data item.

8600 1518–307

6–5

ACCEPT Statement

DAY

This register contains the data elements year and Julian day (that is, days are numbered
consecutively from 001 to 365, or 366 if it is a leap year). If DAY is followed by the
qualifier "YYYYDDD", the year is four digits, otherwise the year is two digits. The
sequence of the data element codes is from high order to low order (year and day).
Therefore, July 1, 1989 is expressed as 89183, or, if qualified by "YYYYDDD", July 1,
1989 is expressed as 1989183.
When accessed by a COBOL program, this register behaves as if it had been described
in a COBOL program as an unsigned elementary numeric integer data item five digits in
length (PIC 9(5) COMP), or, if qualified by "YYYYDDD", a data item seven digits in length
(PIC 9(7) COMP).
DAY-OF-WEEK

This register contains a single data element that represents the day of the week. A value
of 1 represents Monday, a value of 2 represents Tuesday, and so on.
When accessed by a COBOL program, this register behaves as an unsigned elementary
numeric integer one digit in length (PIC 9(1) COMP).
TIME

This register contains the data elements hours, minutes, seconds, and hundredths of a
second. The value of this register is based on elapsed time after midnight on a 24-hour
clock; therefore, 2:41 p.m. is expressed as 14410000.
The minimum value of this register is 00000000 (midnight); the maximum value is
23595999 (one one-hundredth of a second before midnight).
If the hardware cannot provide fractional parts of the data elements contained in this
register, the value is converted to the closest decimal approximation.
When accessed by a COBOL program, this register behaves as if it had been described
in COBOL as an unsigned elementary numeric integer data item eight digits in length
(PIC 9(8) COMP).
Data from the TIME register cannot be transferred to a national data item.
TIMER

This register contains the current value of the object computer's interval timer (that is,
the number of 2.4-microsecond intervals since midnight).
When accessed by a COBOL program, this register behaves as if it had been described
in COBOL as an unsigned elementary numeric integer data item 11 digits in length (PIC
9(11) COMP).

6–6

8600 1518–307

ACCEPT Statement

TODAYS-DATE

This register contains the following data elements: month, day, and year. If TODAYSDATE is followed by the qualifier "MMDDYYYY", the year is four digits, otherwise the
year is two digits. Therefore, July 1, 1989 is expressed as 070189, or, if qualified by
"MMDDYYYY", July 1, 1989 is expressed as 07011989.
When accessed by a COBOL program, this register behaves as if it had been described
in COBOL as an unsigned elementary numeric integer data item six digits in length (PIC
9(6) COMP), or, if qualified by "MMDDYYYY", a data item eight digits in length (PIC 9(8)
COMP).
TODAYS-NAME

This register contains the name of the current day of the week.
When accessed by a COBOL program, this register behaves as if it had been described
in COBOL as an elementary data item nine alphanumeric characters in length (PIC X(9)).
The name is left-justified and space-filled.

Examples
ACCEPT date-1 FROM DATE
In this example, the ACCEPT statement transfers the content of the DATE register (that
is, the current year, month, day) to the data item date-1.
ACCEPT time-1 FROM TIME
In this example, the ACCEPT statement transfers the content of the TIME register (that
is, the current time in hours, minutes, seconds and hundredths of a second) to the data
item time-1.
ACCEPT name-1 FROM TODAYS-NAME
In this example, the ACCEPT statement transfers the content of the TODAYS-NAME
register (that is, the name of the current day) to the data item name-1.

8600 1518–307

6–7

ACCEPT Statement

Format 3: Transfer Number of Storage Queue Entries
ACCEPT identifier-1 MESSAGE COUNT
ïïïïïï
ïïïïï

Explanation
This format of the ACCEPT statement transfers the number of messages in the storage
queue to the entry-data-length field of the storage queue (STOQ) parameter block
specified by identifier-1.
identifier-1

Identifier-1 refers to a 01-level data description entry for a STOQ parameter block.

Details
The STOQ parameter block must be defined as a 01-level data description entry of the
following format:
01 Identifier-1.
02 Queue-name
02 Entry-name-length
02 Entry-name
02 Entry-data-length
02 Entry-data

PIC
PIC
PIC
PIC
PIC

X(6).
9(2) COMP.
X(nn).
9(4) COMP.
X(nnnn).

For a complete description of the STOQ function and the STOQ parameter block, refer to
“SEND Statement” later in this section.
If an entry-name is specified in the STOQ parameter block, the count returned by this
format of the ACCEPT statement is the number of entries in the queue for the specified
entry-name or name-group.
If an entry-name is not specified, the count returned is the total number of entries in the
queue.
The response is returned as an unsigned integer in the entry-data-length field of the
specified STOQ parameter block. A response of zero means that the queue or the
designated portion of the queue is empty or cannot be found.

6–8

8600 1518–307

ACCEPT Statement

Format 4: Transfer Formatted System Date and Time
ACCEPT identifier-1
ïïïïïï

[FROM
ïïïï
[

{DATE}]
ïïïï
{TIME}]
ïïïï

Explanation
This format of the ACCEPT statement transfers the formatted system date or time to the
data item specified by the identifier-1 using the type, convention, and language in effect
for the item. Format 4 is used when the identifier has an associated TYPE clause. If
either the convention or language has not been declared for the item, the system
determines the convention and language based on a default hierarchy.
identifier-1

This identifier is the user-defined name of the data item specified with the TYPE clause.

Details
The FROM clause is optional and used only for documentation. The specification of either
the DATE or the TIME should match the type of the identifier. The DATE specification
should be used when the receiving item is of the following types: SHORT-DATE, LONGDATE, or NUMERIC-DATE. The TIME specification should be used when the item is of
either the LONG-TIME type or the NUMERIC-TIME type. If the type of the item and the
special register do not match, the compiler issues a warning message, continues the
compilation, and assumes the special register is valid for the type declared for the
receiving item.

8600 1518–307

6–9

ADD Statement

ADD Statement
The ADD statement adds two or more numeric operands together and stores the result.
This statement is partially supported in the TADS environment. Supported syntax is
noted in this section.

Format

Use

Format 1

The ADD . . . TO format adds elementary numeric items and/or
numeric literals.

Format 2

The ADD . . . TO . . . GIVING format adds elementary numeric
items and/or numeric literals, resulting in either an elementary
numeric item or an elementary numeric-edited item.

Format 3

The ADD CORRESPONDING format adds the corresponding
data items of two group items.

Format 1: ADD . . . TO

ADD
ïïï

ä identifier-1 å
ã
â . . . TO
æ literal-1
ç
ïï

{ identifier-2 [ ROUNDED ] } . . .
ïïïïïïï

[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-ADD ]
ïïïïïïï

TADS Syntax

ADD
ïïï

ä identifier-1 å
ã
â . . . TO
æ literal-1
ç
ïï

{ identifier-2 [ ROUNDED ] } . . .
ïïïïïïï

[ END-ADD ]
ïïïïïïï

6–10

8600 1518–307

ADD Statement

Explanation
identifier-1
literal-1
identifier-2

In this format, each identifier must refer to an elementary numeric item. Each literal must
be a numeric literal.
ROUNDED

This phrase causes the result to be rounded. Refer to “ROUNDED Phrase” in Section 5
for information about the rounding process.
ON SIZE ERROR imperative-statement-1

If a size error condition occurs, imperative-statement-1 will be executed. Refer to “SIZE
ERROR Phrase” and “Imperative Statements and Sentences” in Section 5 for more
information.
NOT ON SIZE ERROR imperative-statement-2

If a size error does not occur and this phrase is specified, imperative-statement-2 will be
executed.
END-ADD

This phrase delimits the scope of the ADD statement.

Details
The values of the operands preceding the word TO are added together, and the sum is
stored in a temporary data item. The temporary data item is then added to the value of
identifier-2. This process is repeated as many times as required by the statement.
The composite length of the operands cannot exceed 23 decimal digits (the composite
length is based on the length of all of the operands in the statement).
The compiler ensures that enough places are carried so as not to lose any significant
digits.

8600 1518–307

6–11

ADD Statement

Examples
ADD key-1 TO key-2
In this first example, the elementary numeric item key-1 is added to the elementary
numeric item key-2. The result is stored in the data item key-2.
ADD key-1, key-2 TO key-3, key-4 ROUNDED END-ADD
In this second example, key-1 and key-2 (both elementary numeric items) are added
together; the result is stored in a temporary data item. The temporary data item is added
to the data item key-3, and the result is stored in the data item key-3. The temporary data
item is then added to the data item key-4, and the result is rounded and stored in data
item key-4. The END-ADD option terminates the scope of this ADD statement.

Format 2: ADD . . . TO . . . GIVING

ADD
ïïï

ä identifier-1 å
ä identifier-2 å
ã
â . . . [ TO ] ã
â
æ literal-1
ç
ïï
æ literal-2
ç

GIVING { identifier-3 [ ROUNDED ] } . . .
ïïïïïï
ïïïïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-ADD ]
ïïïïïïï

TADS Syntax

ADD
ïïï

ä identifier-1 å
ä identifier-2 å
ã
â . . . [ TO ] ã
â
æ literal-1
ç
ïï
æ literal-2
ç

GIVING { identifier-3 [ ROUNDED ] } . . .
ïïïïïï
ïïïïïïï
[ END-ADD ]
ïïïïïïï

6–12

8600 1518–307

ADD Statement

Explanation
Refer to Format 1 for information on the ROUNDED, ON SIZE ERROR, NOT ON SIZE
ERROR, and END-ADD phrases.
identifier-1
identifier-2

Identifier-1 and identifier-2 must be elementary numeric items.
literal-1
literal-2

Each literal must be a numeric literal.
GIVING identifier-3

The values of the operands preceding the word GIVING are added together, and the sum
is stored into the data item named by identifier-3. The data item represented by identifier3 can be an elementary numeric item or an elementary numeric-edited item.

Details
The composite length of the operands in the ADD statement cannot exceed 23 decimal
digits (the composite length is based on all of the operands that precede the word
GIVING).
The compiler ensures that enough places are carried so as not to lose any significant
digits.

Examples
ADD key-1 TO key-2 GIVING key-3
In this first example, the data items key-1 and key-2 are added, and the result is stored in
the data item key-3.
ADD key-1, key-2 TO key-3
GIVING key-4, key-5 ROUNDED
END-ADD.
In this second example, the data items key-1, key-2, and key-3 are added together, and
the result is stored in the data item key-4 and in the data item key-5. The result in key-5
is rounded.

8600 1518–307

6–13

ADD Statement

Format 3: ADD CORRESPONDING
ä CORRESPONDING å
ã ïïïïïïïïïïïïï â identifier-1 TO identifier-2 [ ROUNDED ]
æ CORR
ç
ïï
ïïïïïïï
ïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-ADD ]
ïïïïïïï
ADD
ïïï

TADS Syntax
ä CORRESPONDING å
ã ïïïïïïïïïïïïï â
æ CORR
ç
ïïïï
[ END-ADD ]
ïïïïïïï
ADD
ïïï

identifier-1 TO identifier-2 [ ROUNDED ]
ïï
ïïïïïïï

Explanation
For more information about the CORRESPONDING phrase, refer to “MOVE Statement”
in Section 7.
CORRESPONDING
CORR

The CORRESPONDING (or CORR) option enables you to add numeric data items from
one group item to data items of the same name within another group item. Only
elementary numeric data items can be added with this phrase. Refer to the discussion of
the CORRESPONDING phrase under “MOVE Statement” in Section 7 for rules that also
apply to the ADD CORRESPONDING phrase.
CORRESPONDING and CORR are equivalent.
identifier-1
identifier-2

In this format, each identifier must refer to a group item.
Data items in the group referred to by identifier-1 are added to and stored in the
corresponding data items in the group referred to by identifier-2.
The compiler ensures that enough places are carried so as not to lose any significant
digits.

6–14

8600 1518–307

ADD Statement

A data item that is subordinate to the data item referred by identifier-1 or identifier-2 and
that contains a REDEFINES, RENAMES, OCCURS, or USAGE IS INDEX clause is ignored.
In addition, any data item subordinate to such a subordinate data item is also ignored.
A valid group item identifier cannot contain level-number 66, level-number 77, levelnumber 88, or the USAGE IS INDEX clause.
A valid group item identifier cannot be reference-modified.
Refer to “USAGE Clause,” “REDEFINES Clause,” “RENAMES Clause,” and “OCCURS
Clause” in Section 4.
Overlapping Operands
When a sending item and a receiving item share a part of their storage areas and are not
defined by the same data description entry, the result of the ADD statement is
undefined. The undefined result occurs only when operands share a part, but not all, of
their storage areas.

Example
DATA DIVISION.
01 group-1.
05 A PIC 99.
05 B PIC X(4).
05 C PIC 9(8).
01 group-2
05 A PIC 99.
05 D PIC 99.
05 B PIC X(4).
05 E PIC 9(4).
05 C PIC 9(8).
05 F PIC 9(8).
.
.
.
ADD CORR group-1 TO group-2 ROUNDED END-ADD
In this example, the data items belonging to the group item group-1 are added to the
corresponding data items (A, B, and C) that belong to the group item group-2. The results
are rounded.
Refer to “Imperative Statements and Sentences,” “ROUNDED Phrase,” and “SIZE
ERROR Phrase” in Section 5 for more information.

8600 1518–307

6–15

ALLOW Statement

ALLOW Statement
The ALLOW statement reverses the effect of the DISALLOW statement, enabling
interrupt procedures to be executed when their associated events are activated (by a
CAUSE statement). See the CAUSE statement and the DISALLOW statement for
additional information.

ALLOW
ïïïïï

ä section-name-1
ã
æ INTERRUPT
ïïïïïïïïï

[ ,section-name-2 ]. . . å
â
ç

section-name-1 [, section-name-2] . . .

This syntax is used to allow access to interrupt procedures that were previously
restricted by the DISALLOW section-name statement. Using this syntax during the time
that the DISALLOW INTERRUPT statement is in effect causes the interrupt procedures
to be queued when their events are activated. The procedures remain queued until an
ALLOW INTERRUPT statement is executed.
Section-name indicates the name of the section in the Procedure Division that contains
the interrupt procedure to be affected by the ALLOW statement. You can use multiple
section names to affect multiple interrupt procedures.
INTERRUPT

The ALLOW INTERRUPT syntax reverses the effect of a previous DISALLOW
INTERRUPT statement. Queued interrupt procedures are immediately executed, unless
they were queued because of a specific DISALLOW section-name statement. In that
case, an ALLOW section-name statement must be issued for those procedures.

Details
You can use the ALLOW statement for interrupt procedures not attached to an event.
Note that performing an ATTACH statement for a procedure that has not been
specifically restricted by the DISALLOW statement automatically establishes the ALLOW
condition for that procedure.

Example
ALLOW INTERRUPT.
ALLOW INTERRUPT-PROCEDURE-ONE.

6–16

8600 1518–307

ALTER Statement

ALTER Statement
The ALTER statement modifies a predetermined sequence of operations. This statement
is obsolete and will be deleted from the next revision of Standard COBOL.
Refer to “GO TO Statement” in this section for a description of the GO TO statement
and the DEPENDING phrase.
ALTER
ïïïïï

{ procedure-name-1 TO [ PROCEED TO ] procedure-name-2 } . . .
ïï
ïïïïïïï ïï

Explanation
procedure-name-1

Procedure-name-1 refers to the name of a paragraph in the Procedure Division that
contains a single sentence consisting of a GO TO statement without the DEPENDING
phrase.
procedure-name-2

Procedure-name-2 refers to the name of a paragraph or section in the Procedure Division.

Details
Execution of the ALTER statement modifies the GO TO statement in the paragraph
named procedure-name-1, so that a subsequent execution of the GO TO statement
transfers control to the procedure named procedure-name-2.

Example
Main-paragraph.
.
.
.
ALTER Search-1 TO PROCEED TO Search-2
Search-1.
GO TO Unstring-1.
Search-2.

In this example, the ALTER statement modifies the GO TO statement in the paragraph
named Search-1, so that when the GO TO statement is executed, control is transferred
to the paragraph named Search-2.

8600 1518–307

6–17

ATTACH Statement

ATTACH Statement
The ATTACH statement associates an interrupt procedure with an event.
ATTACH section-name TO event-identifier.
ïïïïïï
ïï

Explanation
section-name

This is the name of the section in the Procedure Division that contains the interrupt
procedure with which you want to associate this event.
You can attach multiple interrupt procedures to a single event. When the event is
activated, the procedures referenced by the section-names are executed in the reverse
order in which they were specified.
event-identifier

This can be one or more of the following:

•

The name of a data-item declared with the USAGE IS EVENT phrase. The data-name
must be properly qualified and properly subscripted.

•

A task attribute of type EVENT. The event task attributes are ACCEPTEVENT and
EXCEPTIONEVENT. For details about these task attributes, refer to the Task
Attributes Programming Reference Manual.

•

A file attribute of type EVENT. The event file attributes are CHANGEEVENT,
INPUTEVENT, and OUTPUTEVENT. For details about these file attributes, refer to the
File Attributes Programming Reference Manual.

Details
The ATTACH statement causes an implicit ALLOW condition for specified interrupt
procedures that have not been restricted by a previous DISALLOW statement.

6–18

8600 1518–307

ATTACH Statement

The following table explains what happens to interrupt procedures when an event item is
activated.

When an EVENT item is activated
by a CAUSE statement and . . .

Then . . .

And . . .

The ALLOW INTERRUPT
statement was previously used.

The calling program
is suspended.

All interrupt procedures
attached to that event
are executed
immediately.

An interrupt procedure attached to
that event was previously readied
by the ALLOW section-name
statement.

The calling program
is suspended.

The interrupt procedure
is executed
immediately.

The DISALLOW INTERRUPT
statement was previously used.

The calling program
continues executing.

All interrupt procedures
attached to that event
are queued.

An interrupt procedure attached to
that event was previously
restricted by the DISALLOW
section-name statement.

The calling program
continues executing.

The interrupt procedure
is queued.

Note: An interrupt procedure should be attached to only one event at a time. If an
interrupt procedure is already attached to an event when the ATTACH statement is
executed, the interrupt procedure is automatically detached from the old event and then
attached to the new event. Any queued invocations of the interrupt procedure are lost.

Example
ATTACH INTERRUPT-PROCEDURE-ONE TO WS-EVENT77.

8600 1518–307

6–19

CALL Statement

CALL Statement
The CALL statement transfers control from one object program to another object
program in the same run unit.

Format

6–20

Use

Format 1

This format provides a CALL statement with an ON OVERFLOW
option. This format uses the interprogram communication (IPC)
technique, which is described in Section 10.

Format 2

This format provides a CALL statement with an ON EXCEPTION
option. This format uses the interprogram communication (IPC)
technique, which is described in Section 10.

Format 3

This format provides a CALL statement for invoking an external
system procedure or WFL job. This format is partially supported in
the TADS environment. Supported syntax is noted in the
description of the format.

Format 4

This format provides a CALL statement for binding. The use of
Binder with COBOL85 programs is discussed in Appendix E.

Format 5

This format provides a CALL statement for access to entry
procedures residing in program libraries. Library concepts and the
programmatic components required in programs that call libraries
are described in Section 11.

Format 6

This format provides a CALL statement for executing an
independently compiled program as a synchronous, dependent
task. The concepts of tasking and the components required in
programs that perform tasking are described in Section 13.

Format 7

This format provides a CALL statement for transferring control to
a portion of code in an externally compiled program bound into
the calling program. You can specify a section-name or a userdefined program-name as an entry point.

8600 1518–307

CALL Statement

Format 1: CALL with ON OVERFLOW Option
ä identifier-1 å
CALL ã
â
ïïïï æ literal-1
ç
Ú
³
ä
³
³ Ú
³
³ ³ BY REFERENCE
³USING ã ³
ïïïïïïïïï
³ïïïïï ³ ³ BY CONTENT
³
³ À
ïïïïïïï
³
æ
À

¿
³
³
³
Ù

ä
³
³
ã
³
³
æ

¿
å
å
³
³
³
³
file-name
³
³
³
â . . . â . . . ³
INTEGER ( identifier-4 )³
³
³
ïïïïïïï
³
³
³
STRING ( identifier-5 } ç
ç
³
ïïïïïï
Ù
identifier-2

[ GIVING identifier-3 ]
ïïïïïï
[ ON OVERFLOW imperative-statement-1 ]
ïïïïïïïï
[ END-CALL ]
ïïïïïïïï

Explanation
identifier-1

This identifier must be defined as an alphanumeric data item whose value is consistent
with program-naming conventions. It identifies the name of the called program.
literal-1

This must be a nonnumeric literal that identifies the name of the called program. If you
are calling a library entry point, you can specify the called program by using the following
syntax:
Ú
³
³ entrypoint
³
À

ä IN å
ã ïï â
æ OF ç
ïï

¿
³
³
³
Ù

library

Ú
³
³
³
À

BYTITLE
ïïïïïïï
BYFUNCTION
ïïïïïïïïïï

¿
³
³
³
Ù

In this syntax, entrypoint is the program-name specified by the PROGRAM-ID paragraph
in the Identification Division, which is exported by the ENTRY PROCEDURE clause in the
Program-Library Section. For details about library entrypoints, refer to Table 9-1. Library is
the file title of the library if BYTITLE is specified or the function name of the library if
BYFUNCTION is specified. If neither BYTITLE nor BYFUNCTION is specified, the library
will be called by title. If you choose the BYTITLE option, you can specify the ON clause in the title.

8600 1518–307

6–21

CALL Statement

USING

The USING phrase identifies the individual parameters that can be passed. Parameters
can be passed either by reference or by content. Passing by reference is the default.
Long numeric data items are valid in the USING phrase. A long numeric data item is an
unsigned numeric DISPLAY or COMPUTATIONAL data item from 24 to 99,999 digits
long. Long numeric data items are treated as group items. Data items larger than 23
digits must be unsigned integers.
BY REFERENCE

The BY REFERENCE phrase enables the calling program to pass data to the called
program. The values of the passed data may be modified by the called program. If the
values of the passed data were modified by the called program, they will be modified in
the calling program when control is returned to the calling program.
If the BY REFERENCE phrase is either specified or implied for a parameter, the object
program operates as if the corresponding data item in the called program occupies the
same storage area as the data item in the calling program.
The data item in the called program and the corresponding data item in the calling
program must have the same number of character positions.
Both the BY CONTENT and the BY REFERENCE phrases are transitive across the
parameters that follow them until another BY CONTENT or BY REFERENCE phrase is
encountered. If neither the BY CONTENT nor the BY REFERENCE phrase is specified
prior to the first parameter, the BY REFERENCE phrase is assumed.
BY CONTENT

The BY CONTENT phrase enables the program that contains the CALL statement to pass
data to the called program. The original values of the passed data will be restored to the
calling program when control is returned to the calling program. This occurs despite any
changes the called program might make to the passed data.
The data description of each parameter in the BY CONTENT phrase of the CALL
statement must match the data description of the corresponding parameter in the USING
phrase of the Procedure Division header.
identifier-2

This is a data item that will be passed to the called program.
Identifier-2 can be an elementary data item or a non-01-level group item declared in the
File Section, Working-Storage Section, or the Linkage Section of the calling program. The
compiler generates a copy of the data and passes the copy to the called program. If the
parameter is passed BY REFERENCE, the data is copied back into the original area on
return from the call.
Identifier-2 cannot be a function-identifier.

6–22

8600 1518–307

CALL Statement

Identifier-2 can be a national data item.
To prevent data corruption, identifier-2 cannot be a redefined data item. This rule includes
implicit as well as explicit redefinitions. An explicit redefinition occurs when a data item is
declared in the File Section with a REDEFINES clause or is subordinate to a data item
declared with a REDEFINES clause. An implicit redefinition occurs when the first data
item declared in the File Section is followed by subsequent level 01 items. The
subsequent level-01 items are considered to be implicit redefinitions of the first item.
COMS headers can be sent as parameters to entry points of libraries and will match to a
real array.
file-name

This is a file name of a file to be passed as a parameter. The file must be declared as
RECEIVED BY REFERENCE in the file's SELECT clause of the FILE-CONTROL paragraph.
INTEGER (identifier-4)

This declares the parameter to be an integer type parameter. Integer type parameters
must be declared with USAGE COMPUTATIONAL.
STRING (identifier-5)

This declares the parameter to be a string type parameter. String type parameters must
be declared with USAGE DISPLAY.
GIVING identifier-3

The GIVING phrase is used to provide a data item into which the value of the called
function is to be stored. The procedure identified by identifier-1 must be a function that
returns a value. Identifier-3 must be a numeric item.
ON OVERFLOW imperative-statement-1

If the program is not present, imperative-statement-1 is executed.
END-CALL

This phrase delimits the scope of the CALL statement.

Details
Details for the CALL with ON OVERFLOW option and the CALL with ON EXCEPTION
option appear under the heading “Format 2: CALL with ON EXCEPTION Option” in this
section.

8600 1518–307

6–23

CALL Statement

Format 2: CALL with ON EXCEPTION Option

CALL
ïïïï
Ú
³
³
³USING
³ïïïïï
³
À

ä identifier-1 å
ã
â
æ literal-1
ç
ä
³
³
ã
³
³
æ

ä
Ú
¿ ³
³ BY REFERENCE ³ ³
³
ïïïïïïïïï ³ ã
³ BY CONTENT
³ ³
À
ïïïïïïï
Ù ³
æ

identifier-2

å
å
¿
³
³
³
file-name
³
³
³
â . . . â . . . ³
INTEGER ( identifier-4 )³
³
³
ïïïïïïï
³
³
³
STRING ( identifier-5 ) ç
ç
Ù
ïïïïïï

[ GIVING identifier-3 ]
ïïïïïï
[ ON EXCEPTION imperative-statement-1 ]
ïïïïïïïïï
[ NOT ON EXCEPTION imperative-statement-2 ]
ïïï
ïïïïïïïïï
[ END-CALL ]
ïïïïïïïï

Explanation
Refer to Format 1 for descriptions of the syntax elements identifier-1, literal-1, identifier2, file-name, USING, BY REFERENCE, BY CONTENT, INTEGER (identifier-4), STRING
(identifier-5), GIVING, and END-CALL.
ON EXCEPTION imperative-statement-1

If the called program is not present and this phrase is specified, imperative-statement-1
is executed.
NOT ON EXCEPTION imperative-statement-2

If the called program is available and executable as a called program, imperativestatement-2 is executed.

Details
The calling program is the program in which the CALL statement appears. The called
program is the object of a CALL statement, combined at execution time with the calling
program to produce a run unit.
Literal-1 or the content of the data item referenced by identifier-1 must contain the object
name of the called program.

6–24

8600 1518–307

CALL Statement

If the program being called in identifier-1 or literal-1 is not a COBOL program, the number
of parameters in the formal parameter list of this program must match the number of
operands in each USING phrase of the COBOL program. In case of parameter size
difference, the COBOL MOVE rules apply.
When a CALL statement is executed, and the program specified by the CALL statement
is made available for execution, control is transferred to the called program.
The BY CONTENT phrase of the CALL statement is a method of passing parameters
between programs without changing the value in the calling program. Whether the BY
CONTENT or the BY REFERENCE phrase is specified in the CALL statement, for the
implicit entry procedure interface, the compiler treats the formal parameter as though the
BY REFERENCE phrase had been specified. In this case, a copy is made for the BY
CONTENT data item and passed by reference. True BY CONTENT applies only to the
explicit library interface for level-77 BINARY, DOUBLE, and REAL data items.
Table 6–2 illustrates parameter mapping among COBOL85, ALGOL, Pascal, and
COBOL74 programs.
Table 6–2. Parameter Mapping among Languages

Implicit Interface
COBOL85 Data

ALGOL Data

Pascal Data

COBOL74 Data

BY CONTENT

Reference

BY REFERENCE

Reference

Explicit Interface
COBOL85 Data

ALGOL Data

Pascal Data

COBOL74 Data

BY CONTENT
(REAL, DOUBLE,
BINARY)

Value

No Match

To use the explicit library interface, you must add a LOCAL-STORAGE SECTION and a
PROGRAM-LIBRARY SECTION in your program to describe the library and its parameters
and attributes. You can pass the parameters from COBOL85 to ALGOL as by value and
match the ALGOL VALUE parameter by specifying BY CONTENT in the LOCALSTORAGE SECTION on the formal description of the COBOL85 parameter; nothing is
specified on the corresponding CALL statement.

8600 1518–307

6–25

CALL Statement

Example
The following COBOL85 program calls an ALGOL library that is passing a parameter by
value.
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77
WS-PARAM1 PIC 9(3) BINARY.
LOCAL-STORAGE SECTION.
LD PROG1.
77
PARAM1 PIC 9(3) BINARY BY CONTENT.
PROGRAM-LIBRARY SECTION.
LB MYLIB IMPORT
ATTRIBUTE LIBACCESS IS BYTITLE
TITLE IS "OBJECT/ALGOL/LIB".
ENTRY PROCEDURE PROC1 WITH PROG1 USING
PARAM1.
PROCEDURE DIVISION.
START-MAIN.
MOVE 3 TO WS-PARAM1.
DISPLAY "BEFORE LIB CALL WS-PARAM1=" WS-PARAM1.
CALL PROC1 USING WS-PARAM1.
DISPLAY "AFTER LIB CALL WS-PARAM1=" WS-PARAM1.
END-MAIN.
STOP RUN.
And here is the library:
BEGIN
PROCEDURE PROC1(I1);
VALUE I1;
INTEGER I1;
BEGIN
I1:=*+1;
DISPLAY("IN LIBRARY, PARAMETER CHANGED TO " CAT STRING(I1,*));
END;
EXPORT PROC1;
FREEZE(TEMPORARY);
END.
When the COBOL85 program runs, the displays show that the value of WS-PARAM1 is
not changed:
RUNNING 9061
9061 DISPLAY:BEFORE LIB CALL WS-PARAM1=003.
9061 DISPLAY:IN LIBRARY, PARAMETER CHANGED TO 4.
9061 DISPLAY:AFTER LIB CALL WS-PARAM1=003.
ET=0.4 PT=0.1 IO=0.1

6–26

8600 1518–307

CALL Statement

Control and the ON OVERFLOW and ON EXCEPTION Phrases
After control is returned from the called program, the ON EXCEPTION or ON
OVERFLOW phrase (if specified) is ignored. Control is transferred to the end of the CALL
statement.
After control is returned from the called program and the NOT ON EXCEPTION phrase is
specified, control is transferred to imperative-statement-2. Then, execution continues
according to the rules for each statement specified in imperative-statement-2. If a
procedure-branching or conditional statement that causes explicit transfer of control is
executed, control is transferred according to the rules for that statement. Otherwise,
upon completion of the execution of imperative-statement-2, control is transferred to the
end of the CALL statement.
If the program specified by the CALL statement cannot be made available for execution
when it is called, one of the following actions will occur:

•

If the ON OVERFLOW or ON EXCEPTION phrase is specified, control is transferred
to imperative-statement-1. Execution then continues according to the rules for each
statement specified in imperative-statement-1.
If a procedure branching or conditional statement that causes explicit transfer of
control is executed, control is transferred according to the rules for that statement.
Otherwise, upon completion of the execution of imperative-statement-1, control is
transferred to the end of the CALL statement, and the NOT ON EXCEPTION phrase,
if specified, is ignored.

•

If the ON OVERFLOW or ON EXCEPTION phrase is not specified in the CALL
statement, then imperative-statement-2 in the NOT ON EXCEPTION phrase, if
specified, is ignored.

Program-Name Conventions
Two or more programs in a run unit can have the same program-name. If a CALL
statement refers to a duplicated program-name, the problem is resolved by the
conventions for the scope of names for program-names. Refer to “Conventions for
Program-Names” in Section 10 for more information.
For example, when only two programs in the run unit have the same name as that
specified in a CALL statement:

•

One of those two programs must also be contained directly or indirectly in the
program which includes that CALL statement or in the separately compiled program
which itself directly or indirectly contains the program which includes that CALL
statement.

•

The other of those two programs must be a different, separately compiled program.
The mechanism used in this example is as follows:

•

If one of the two programs having the same name as that specified in the CALL
statement is directly contained within the program which includes that CALL
statement, that program is called.

8600 1518–307

6–27

CALL Statement

•

If one of the two programs having the same name as that specified in the CALL
statement possesses the common attribute and is directly contained within another
program which directly or indirectly contains the program which includes the CALL
statement, that common program is called unless the calling program is contained
within that common program.

•

Otherwise, the separately compiled program is called.

Program States
A called program (and each program it directly or indirectly contains) is in its initial state
the first time it is called in a run unit or the first time it is called after it has been canceled
by a CANCEL statement.
If the called program possesses the initial attribute, it and each program it directly or
indirectly contains are placed into an initial state every time the called program is called in
a run unit.
On all other entries in the called program, the state of the program (including each
program it directly or indirectly contains) remains unchanged from its state when it was
last exited.
Files associated with a called program's internal file connectors are not in the open mode
when the program is in an initial state. On all other entries into the called program, the
states and positions of all such files are the same as when the called program was last
exited.
The process of calling a program or exiting from a called program does not alter the
status or position of a file associated with any external file connector.
The USING Phrase
The USING phrase is included in the CALL statement only if there is a USING phrase in
the Procedure Division header of the called program. In this case, the number of
operands in each USING phrase must be the same.
The sequence in which data-names appear in the USING phrase of the CALL statement
and in the corresponding USING phrase in the called program's Procedure Division
header determines the relationship between the data-names used by the calling and
called programs. This relationship is based on position; the first data-name in one USING
phrase corresponds to the first data-name in the other, the second to the second, and so
forth.
The values of the parameters referenced in the USING phrase of the CALL statement are
available to the called program at the time the CALL statement is executed.

6–28

8600 1518–307

CALL Statement

CALL Statements in Nested Programs
Called programs can contain CALL statements. However, a called program must not
execute a CALL statement that directly or indirectly calls the calling program. As a result,
there are no recursive calls.
If a CALL statement is executed within the range of a declarative procedure, that CALL
statement cannot directly or indirectly reference any called program to which control has
been transferred or that has not completed execution.

Example
IDENTIFICATION DIVISION.
PROGRAM-ID. CALLER.
DATA DIVISION.
.
.
.
WORKING-STORAGE SECTION.
01 COLOR
PIC X(10).
01 SIZE1
PIC 99v99.
01 AMOUNT
PIC 999.
.
.
.

IDENTIFICATION DIVISION.
PROGRAM-ID. CALLED.
DATA DIVISION.
.
.
.
WORKING-STORAGE SECTION.
.
.
.
LINKAGE SECTION.
01 HUE
PIC X(10).
01 MY-SIZE PIC 99V99.

PROCEDURE DIVISION.
PARA-1.
CALL "CALLED"
USING BY CONTENT SIZE1
BY REFERENCE COLOR
ON EXCEPTION PERFORM EX-1
NOT ON EXCEPTION
PERFORM PARA-4.

PROCEDURE DIVISION
USING MY-SIZE, HUE.
PARA-A.
.
.
.

MOVE MY-SIZE TO WS-1.
MOVE "RED" TO HUE.
EXIT PROGRAM.

The program on the left (CALLER) is calling the program on the right (CALLED). The
identifiers that will be passed, which are SIZE1 and COLOR, are defined in the program
that contains the CALL statement. These identifiers correspond to the identifiers MYSIZE and HUE in the called program.
The values of SIZE1 and COLOR will be passed from CALLER to CALLED, but the value
of SIZE1 cannot be modified because it is passed BY CONTENT.
If an exception condition exists, the statements in EX-1 will be executed. The NOT ON
EXCEPTION phrase will be ignored. If an exception condition does not exist, the
statements in PARA-4 will be executed. The ON EXCEPTION phrase will be ignored.

8600 1518–307

6–29

CALL Statement

Format 3: CALL a System Procedure
CALL SYSTEM
ïïïï ïïïïïï

ä
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
³
æ

Ú
Ú
¿ ¿
³ FREEZE ³ PERMANENT ³ ³
³ ïïïïïï ³ ïïïïïïïïï ³ ³
³
³ TEMPORARY ³ ³
À
À ïïïïïïïïï Ù Ù
DUMP
ïïïï
IOTERMINATE USING filename-1
ïïïïïïïïïïï ïïïïï
OCTERMINATE USING filename-2
ïïïïïïïïïïï ïïïïï
WFL
ïïï

USING
ïïïïï

VERSION
ïïïïïïï

USING
ïïïïï

ä identifier-1 å
ã
â
æ literal-1
ç
{ identifier-2 }

å
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
ç

[ END-CALL ]

TADS Syntax
CALL SYSTEM DUMP
ïïïïïïïïïïïïïïïï

Explanation
This format of the CALL statement invokes a system procedure or a WFL job or retrieves
the value of $VERSION. COBOL85 supports calls to the following system procedures:
FREEZE

This calls the library freeze function. The freeze function suspends execution of the
library program and makes available all declared entry points into the library.
For more information on libraries, refer to Section 11.
PERMANENT
TEMPORARY

The optional reserved words PERMANENT and TEMPORARY can be used to specify the
disposition of the library.
For more information on libraries, refer to Section 11.

6–30

8600 1518–307

CALL Statement

DUMP

This calls the dump facility which produces a “snapshot” of the memory area of the
program.
IOTERMINATE

This option causes a process to self-terminate after the unsuccessful execution of an I/O
statement. The current value of the MCPRESULTVALUE identifier along with the
filename specified in this clause are passed to the MCP to produce a meaningful I-DS
message. For details about the MCPRESULTVALUE identifier, refer to Section 12.
OCTERMINATE

This option causes a process to self-terminate after the unsuccessful execution of either
an OPEN or CLOSE statement. The current value of the MCPRESULTVALUE identifier
along with the filename specified in this clause are passed to the MCP to produce a
meaningful I-DS message. For details about the MCPRESULTVALUE identifier, refer to
Section 12.
WFL

This option initiates an independent task that invokes the WFL job. After initiating the
task, the program executes the next statement. The program does not wait for the task
executing the WFL job to be completed.
The COBOL compiler does not check the syntax of the WFL job. Thus, errors in the WFL
syntax have no effect on the calling program.
The COBOL program does not determine if the CALL action is successful. You can check
for successful termination of the WFL compilation and the job itself by using the CANDE
?C command or the MARC C command. The WFL compilation is assigned the name
CONTROLCARD. The name assigned to the WFL job is constructed from the BEGIN JOB
statement of the WFL job.
For more information about WFL jobs, refer to the Work Flow Language (WFL)
Programming Reference Manual.
identifier-1

This identifier names a WFL source file that contains a complete WFL job. Identifier-1
must be defined as a 01-level data item that includes the USAGE IS DISPLAY phrase.
literal-1

This literal must be nonnumeric and must specify a complete WFL job.
VERSION

This option causes the $VERSION value to be assigned to a specified receiving area.

8600 1518–307

6–31

CALL Statement

Identifier-2

This identifier specifies the receiving area for the value of $VERSION. The identifier must
be defined as a data item with the usage of DISPLAY. The format of the identifier is
, where rr is the release number, ccc is the cycle number, and pppp is the
patch number.

Examples
CALL SYSTEM FREEZE PERMANENT.
This statement calls the library freeze function and requests that the library be frozen
permanently.
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
OBJECT-COMPUTER. A15.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WFL-SRC
PIC X(46)
VALUE "BEGIN JOB J;DISPLAY ""THIS IS A TEST""; END JOB.".
PROCEDURE DIVISION.
PARA-1.
CALL SYSTEM WFL USING WFL-SRC.
STOP RUN.

6–32

8600 1518–307

CALL Statement

This program is written to execute the WFL job referenced by the identifier WFL-SRC.
Notice that the identifier WFL-SRC is declared as a 01-level data item and that the
complete WFL job follows that declaration.
$VERSION 12.345.6789
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 VERSION-VALUE.
05
REL
PIC 9(2).
05
CYCLE PIC 9(3).
05
PATCH PIC 9(4).
PROCEDURE DIVISION.
PARA-1.
CALL SYSTEM VERSION USING VERSION-VALUE.
IF REL = 12 AND CYCLE = 345 AND PATCH = 6789
DISPLAY "PASSED"
ELSE
DISPLAY "FAILED".
STOP RUN
This program calls the version value and displays pass/fail status.

8600 1518–307

6–33

CALL Statement

Format 4: CALL for Binding
CALL section-name [ USING actual-parameter-list ]
ïïïï
ïïïïï

Explanation
This format is used to call a procedure in an externally compiled program that will be
bound to the calling program.
The actual-parameter-list must consist of a series of data-items, control items, and
expressions optionally separated by commas.

Details
In addition to passing arithmetic values, certain kinds of variables can be passed
(received) by reference. As a general rule, the usage of the actual parameter must not
conflict with the corresponding formal parameter, as specified in the Local-Storage
Section.
Table 6–3 shows the formal parameters that can be declared in COBOL85 for bound and
host programs, along with the corresponding declarations in ALGOL, and the permissible
actual parameters that can be passed.
Table 6–3. Formal and Actual Parameters for Bound Procedures

COBOL85
Formal Parameter

6–34

ALGOL Formal Parameter

Permissible Actual
Parameters

BINARY, 77, 1-11 digits
(RECEIVED BY CONTENT)

INTEGER

Arithmetic-expression

REAL, 77
(RECEIVED BY CONTENT)

REAL

Arithmetic-expression

BINARY, 77, 12-23 digits or
DOUBLE, 77 (RECEIVED BY
CONTENT)

DOUBLE

Arithmetic-expression

BINARY 77, 1-11 digits
(RECEIVED BY REFERENCE)

INTEGER

BINARY, 77, 1-11 digits

REAL, 77
(RECEIVED BY REFERENCE)

REAL

REAL, 77

BINARY, 77, 12-23 digits
(RECEIVED BY REFERENCE)

DOUBLE

BINARY, 77, 12-23 digits

8600 1518–307

CALL Statement

Table 6–3. Formal and Actual Parameters for Bound Procedures

COBOL85
Formal Parameter

ALGOL Formal Parameter

Permissible Actual
Parameters

DOUBLE, 77 (RECEIVED BY
REFERENCE)

DOUBLE

DOUBLE, 77

BINARY, 01, 1-11 digits

INTEGER ARRAY

BINARY, 01, 1-11 digits
COMP, 01
DISPLAY 01

BINARY, 01, 12-23 digits
or DOUBLE, 01

DOUBLE ARRAY

BINARY, 01, 12-23 digits
DOUBLE, 01
REAL, 01

REAL, 01

REAL ARRAY

REAL, 01

COMP, 01
INDEX, 01

HEX ARRAY

COMP, 01
DISPLAY, 01
BINARY, 01, 1-11 digits

DISPLAY, 01

EBCDIC ARRAY

COMP, 01
DISPLAY, 01
BINARY, 01, 1-11 digits

FILE

TASK, 77 or 01

TASK

TASK, 77 or 01

TASK, 01 group

TASK ARRAY

TASK, 01 group

EVENT or LOCK, 77

EVENT

EVENT or LOCK, 77

EVENT or LOCK, 01 group

EVENT ARRAY

EVENT or LOCK, 01
group

BIT, 77
SYNC RIGHT
(RECEIVED BY CONTENT)

BOOLEAN

BIT, 77
Boolean-expression

BIT, 77
SYNC RIGHT
(RECEIVED BY REFERENCE)

BOOLEAN

BIT, 77

BIT, 01
SYNC RIGHT

BOOLEAN ARRAY

BIT, 01

8600 1518–307

6–35

CALL Statement

Format 5: CALL for Library Entry Procedure

CALL entry-procedure-name
ïïïï
Ú
³
³ USING
³ ïïïïï
À

Ú
³ ä OF å
³ ã ïï â
³ æ IN ç
À
ïï

¿
³
library-name ³
³
Ù

¿
ä identifier-1 å
³
ã
â . . . ³
æ file-name
ç
³
Ù

[ GIVING identifier-2 ]
ïïïïïï
[ ON EXCEPTION imperative-statement-1 ]
ïïïïïïïïï
[ NOT ON EXCEPTION imperative-statement-2]
ïïï
ïïïïïïïïï
[ END-CALL ]
ïïïïïïïï

Explanation
This format of the CALL statement transfers program control to a procedure in a library
program. Refer to Format 1 for information on the USING clause, the GIVING clause, and
the END-CALL clause. Matching of formal and actual parameters can result in coercion of
the actual parameter to match the formal parameter description.
entry-procedure-name

This is the name of the procedure to be called in the library program. The entryprocedure-name must have been previously declared in the Program-Library Section of
the calling program.
OF library-name
IN library-name

This identifies the library program that contains the called procedure. This phrase is
optional, and is used only to differentiate like-named procedures residing in different
library programs. The library-name must have been previously declared in the ProgramLibrary Section of the calling program.
ON EXCEPTION imperative-statement-1

If the called library linkage fails or if the program successfully links to the library but some
of the entry points do not exist in the library, and this phrase is specified, imperativestatement-1 is executed and the library entry procedure is not called.
If an exception occurs, the LINKLIBRARY-RESULT predefined identifier can be used to
find out which type of exception has occurred. Refer to “Linkage Between user
Programs and Libraries” in Section 11, “Library Concepts,” for more information.

6–36

8600 1518–307

CALL Statement

NOT ON EXCEPTION imperative-statement-2

If the called library links successfully and all entry points are in the library, the library entry
procedure will be called and imperative-statement-2 is executed.

Details
National-character data-items and national-character literals cannot be passed in the
USING phrase of this format of the CALL statement.
Refer to the Local-Storage Section of the Data Division for information on passing
parameters in library programs.
Control and the ON EXCEPTION Phrase
If the program cannot link to the library containing the entry procedure specified in the
CALL statement, or if the program successfully links to the library but not all entry points
exist in the library, one of the following actions occurs:

•

If the ON EXCEPTION phrase is specified, control is transferred to imperativestatement-1. Execution then continues according to the rules for each statement
specified in imperative-statement-1.
If a procedure branching or conditional statement that causes explicit transfer of
control is executed, control is transferred according to the rules for that statement.
Otherwise, upon completion of imperative-statement-1, control is transferred to the
end of the CALL statement and the NOT ON EXECPTION phrase, if specified, is
ignored.

•

If ON EXCEPTION is not specified in the CALL statement, the imperative-statement2 in the NOT ON EXCEPTION phrase, if specified, is ignored.

8600 1518–307

6–37

CALL Statement

Examples
The following examples show an ALGOL library program and three possible COBOL
programs that could call the ALGOL library.
ALGOL Library Program
BEGIN
PROCEDURE ENTRYPOINT( A, B);
STRING A;
INTEGER B;
BEGIN
B := B + 1;
DISPLAY( A );
END;
EXPORT ENTRYPOINT;
FREEZE( TEMPORARY );
END.

This library program takes two parameters, A and B, passed in from the calling program.
It adds 1 to B, and then displays A. Control then returns to the calling program.
COBOL74 Library Program
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 A
PIC X(010)
VALUE ALL "*".
01 B
PIC 9(011) COMP VALUE ZERO.
PROCEDURE DIVISION.
P1.
CALL "ENTRYPOINT OF OBJECT/TEXT/X/STR1"
USING STRING( A ) INTEGER( B ).
DISPLAY B.
STOP RUN.

This COBOL74 program calls the ALGOL program, passing the parameters A (filled
with “*”) and B (filled with zero). Once control returns from the ALGOL program, the
COBOL74 program displays the value returned in B and stops.

6–38

8600 1518–307

CALL Statement

COBOL85 Implicit Library Program
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 REC.
02 A
PIC X(010)
VALUE ALL "*".
02 B
PIC 9(011) COMP VALUE ZERO.
PROCEDURE DIVISION.
P1.
CALL "ENTRYPOINT OF OBJECT/TEXT/X/STR1"
USING STRING( A ) BY CONTENT INTEGER( B ).
DISPLAY B.
STOP RUN.

This COBOL85 program is exactly like its COBOL74 counterpart, except that the data
items A and B have been made part of a group item called REC, and the data item B is
passed to the library program BY CONTENT. Since B is passed BY CONTENT, the value
of B does not change when control is returned to the calling program. Consequently,
when B is displayed, it still contains zero.
COBOL85 Explicit Library Program
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 A
PIC X(010)
VALUE ALL "*".
01 B
PIC 9(011) COMP VALUE ZERO.
LOCAL-STORAGE SECTION.
LD LOCAL1.
01 C
PIC X(010) DISPLAY STRING.
01 D
PIC 9(011) COMP
INTEGER.
PROGRAM-LIBRARY SECTION.
LB ALGOLLIB IMPORT
ATTRIBUTE TITLE IS "OBJECT/TEXT/X/STR1".
ENTRY PROCEDURE ENTRYPOINT WITH LOCAL1 USING C D.
PROCEDURE DIVISION.
P1.
CALL ENTRYPOINT USING A B.
DISPLAY B.
STOP RUN.
This is the same program as the two previous programs, except that the library is
declared as an explicit library rather than an implicit one.

8600 1518–307

6–39

CALL Statement

Format 6: CALL for Initiating a Synchronous, Dependent
Process
This format of the CALL statement enables a COBOL85 program to execute a separately
compiled program as a synchronous, dependent process.

CALL task-variable WITH section-name [ USING actual-parameter-list ].
ïïïï
ïïïï
ïïïï

Explanation
task-variable

This specifies the task variable that is to be associated with the process declared in the
USE EXTERNAL statement of the specified section-name. The task variable associates a
process with its program so that when the program modifies task attribute values, the
system knows which process is to be affected. The task variable must be declared as a
data item in the Working-Storage section of the Data Division (refer to the USAGE clause
in Section 4 for details). For more information about task variables, refer to Section 13.
section-name

This identifies the section in the Procedure Division that contains the name of the object
code file that is to be initiated by this CALL statement. You must define the sectionname in the Declaratives Section of the Procedure Division and follow the definition with
a USE EXTERNAL statement that specifies the name of the object code file.
USING actual-parameter-list

The USING phrase indicates the parameters in the calling program that are to be passed
to the called program.
You can include the USING phrase only if a USING phrase occurs in the Procedure
Division header of the called program and in the USE statement of the section identified
by section-name in the calling program.
The parameters in the USING phrase can be a combination of any 77-level items that
reside in the stack or 01-level items. A 77-level item that resides in the stack would be of
USAGE BINARY, REAL or DOUBLE. In general, the level number, type, length, and order
of items in the USING phrase of the calling and called programs must be identical.
However, the items in the following list are interchangeable as parameters, that is, each
item can be passed to and received by the other. The lengths of the associated items
must be the same, however, or run-time errors might occur.

6–40

8600 1518–307

CALL Statement

Interchangeable Group Items

•

BINARY

•

COMP

•

DISPLAY

•

DOUBLE

•

REAL

Other Interchangeable Items

•

DOUBLE items with RECEIVED BY REFERENCE clause

•

77-level BINARY REAL data items

Files to be passed as parameters must have a record description. The record description
itself can be passed as a parameter. The USING phrase in the Procedure Division header
of the called program must not reference any data item in the File Section of the called
program. Both the calling and the called programs can read from and write to the file
passed as a parameter in the CALL statement.
Including a task-variable in the USING phrase enables the called program to make
references to the calling program.

8600 1518–307

6–41

CALL Statement

Variables can be passed by value or by reference. Table 6–4 describes the matching of
formal parameters between the COBOL74/85, ALGOL, and COBOL68 languages.
Table 6–4. Parameter Mapping for Tasking Calls

COBOL74/85 Parameter

6–42

ALGOL Parameter

COBOL68 Parameter

77-level REAL or BINARY
item (single precision)

REAL, INTEGER

77-level COMP or COMP4 item (single precision)

77-level DOUBLE or
BINARY item (double
precision)

DOUBLE

77-level COMP or COMP5 item (double precision)

01-level DISPLAY, COMP,
BINARY, REAL, or
DOUBLE item

REAL ARRAY[*]
INTEGER ARRAY[*]
EBCDIC ARRAY[*]
HEX ARRAY[*]
REAL ARRAY[0]
INTEGER ARRAY[0]
EBCDIC ARRAY[0]
HEX ARRAY[0]

01-level DISPLAY, COMP,
OR COMP-2 group item
with or without LOWERBOUNDS

77-level EVENT or LOCK
item

EVENT

77-level or 01-level EVENT
or LOCK item

77-level or 01-level TASK
elementary item

TASK

77-level or 01-level TASK
elementary item

01-level EVENT or LOCK
group item

EVENT ARRAY

77-level EVENT or LOCK
group item

01-level TASK group item

TASK ARRAY

01-level TASK group item

FILE

BIT, 77
SYNC RIGHT

BOOLEAN

BIT, 77
Boolean-expression

BIT, 01
SYNC RIGHT

BOOLEAN ARRAY

BIT, 01

8600 1518–307

CALL Statement

Details
When the CALL statement is executed, the calling program is suspended, and the called
program is initiated. Upon initiation, the values of any parameters referenced in the
USING phrase of the calling program are made available to the called program.
Naming the Program to Be Called
You can specify the name of the program to be called in one of the following ways:

•

Put a CHANGE statement before the CALL statement that changes the NAME
attribute of the task variable.

•

Define a mnemonic-name in the Special-Names paragraph of the Environment
Division, and then use it in the USE EXTERNAL statement.

•

Use the following steps:
1. Declare a data item in the Working-Storage Section of the Data Division.
2. Name the data item in a USE EXTERNAL statement in the Declarative Section of
the Procedure Division.
3. Assign the object code file title to the data item by using a MOVE statement in
the Procedure Division.

For program examples that show how to declare the name of the program to be called,
refer to Section 13.
How Processor Time Is Shared
Processor control is passed between the calling and the called programs as follows:

When the called program . . .

Then the calling program . . .

Executes an EXIT PROGRAM
statement

Resumes execution.

Terminates abnormally

Resumes execution beginning with the statement
following the CALL statement.

The calling program can reinitiate the called program
by executing a CONTINUE statement.

The calling program must execute another CALL
statement to reinitiate the called program.
Executes a STOP RUN
statement

Resumes execution beginning with the statement
following the CALL statement.
The calling program must execute another CALL
statement to reinitiate the called program.

If the calling program is terminated before the called program, a critical block exit error
occurs. For details about this type of error and how to prevent it, refer to Section 13.
For program examples that show how control is passed between two programs, refer to
Section 13.

8600 1518–307

6–43

CALL Statement

Format 7: CALL MODULE
This format of the CALL statement transfers control to a portion of code in an externally
compiled program bound into the calling program. You can specify a section-name or a
user-defined program-name as an entry point.

CALL MODULE [ "section-name" OF ] "program-id"
ïïïï ïïïïïï
ä "file-name" å
FROM
ã
â [ ON "family-name"]
æ MODULEFILE ç
ïïïïïïïïïï

Explanation
“section-name”

This name is a user-defined word that you specify in the nondeclarative portion of the
Procedure Division in the program being called. Double-byte section names cannot be
used in this statement. Refer to “Nondeclarative Procedure Format” in Section 5 for
details on declaring a section-name.
“program-id”

This identifier is a user-defined word that you specify in the PROGRAM-ID paragraph in
the Identification Division of the program being called.
“file-name”

This name is the file name of the code file that contains the program being called.
“family-name”

This name is the family on which the code file that contains the called program resides.
The ON “family-name” phrase is optional if you have specified a default family name
with the MODULEFAMILY compiler option. See Section 15, “Compiler Operations” for
details.
MODULEFILE

This keyword indicates that the file name specified by the MODULEFILE compiler option
is the name of the code file that contains the called program.

6–44

8600 1518–307

CALL Statement

Details
You must include the CALLMODULE compiler option in the called program to ensure
that it contains the necessary structures to make the call possible.
When the calling program enters a section of code in another program, the code in the
called program is executed until either a RETURN statement or the end of the program is
encountered. You can specify the end of a section with an EXIT MODULE statement,
which causes control to be returned to the calling program.

Example
Calling Program TEST/CALLER
$ BINDINFO
$ SET LIST CODE
IDENTIFICATION DIVISION.
PROGRAM-ID. HOST.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CO-ITEM
PIC X(36).
01 ORIG
PIC X(36).
01 NEW
PIC X(36).
PROCEDURE DIVISION.
FIRST-PA SECTION.
START-PA.
DISPLAY "WE ARE STARTING NOW !".
SECOND-PA SECTION.
START-PA2.
MOVE "THIS IS A COMMON DATA ITEM." TO CO-ITEM.
CALL MODULE "MODA" OF "TEXTMOD"
FROM "OBJECT/TEST/CALLED" ON "DISK".
CALL MODULE "MODB" OF "TEXTMOD"
FROM "OBJECT/TEST/CALLED" ON "DISK".
CALL MODULE "MODC" OF "TEXTMOD"
FROM "OBJECT/TEST/CALLED" ON "DISK".
CALL MODULE "MODD" OF "TEXTMOD"
FROM "OBJECT/TEST/CALLED" ON "DISK".
STOP RUN.

8600 1518–307

6–45

CALL Statement

Called Program TEST/CALLED
$SET LEVEL = 3 CALLMODULE
IDENTIFICATION DIVISION.
PROGRAM-ID. TESTMOD.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CO-ITEM PIC X(36) COMMON.
PROCEDURE DIVISION.
MODA SECTION.
START-MODA.
DISPLAY "WE'VE ARRIVED AT
DISPLAY CO-ITEM.
EXIT-PARA.
EXIT MODULE.
MODB SECTION.
START-MODB.
DISPLAY "WE'VE ARRIVED AT
EXIT-MODB.
EXIT MODULE.
MODC SECTION.
START-MODC.
DISPLAY "WE'VE ARRIVED AT
EXIT-MODC.
EXIT MODULE.
MODD SECTION.
START-MODD.
DISPLAY "WE'VE ARRIVED AT

MODA".

MODB".

MODC".

MODD".

Binder File TEST/BIND
HOST IS OBJECT/TEST/CALLER;
Explanation
The calling begins with the calling program initiating the called program at the MODA
SECTION. After the MODA SECTION in the called program is executed, an EXIT
MODULE statement is encountered, and control is returned to the next CALL MODULE
statement in the calling program. The calling continues in a similar way until the end of
the called program is encountered (after the MODD SECTION). Then control returns to
the calling program, which executes a STOP RUN.
Notice that the LEVEL compiler option is set to 3 in the called program. A called program
must be compiled at level 3 or higher to use the EXIT MODULE statement.
Refer to the Binder Programming Reference Manual for information on how to use the
Binder file.

6–46

8600 1518–307

CANCEL Statement

CANCEL Statement
The CANCEL statement breaks the link between the called program and a calling
program. The next time the program is called, it will be in its initial state.
For information on program-naming conventions, refer to “User-Defined Words” in
Section 1.
Refer to “PROGRAM-ID Paragraph” in Section 2 for information on how a program
receives the initial attribute.
For conceptual information on interprogram communication and the use of the CANCEL
statement, refer to Section 10.
Refer to “CALL Statement” and “EXIT Statement” in this section for more information.

CANCEL
ïïïïïï

ä identifier-1
³
³ literal-1
ã
³ library-name-1
³
³
æ

Ú
³
³
³
À

BYTITLE
ïïïïïïï
BYFUNCTION
ïïïïïïïïïï

¿
³
³
³
Ù

å
³
³
â
³
³
³
ç

Explanation
identifier-1

This identifier must reference an alphanumeric data-item whose value is consistent with
program-naming conventions.
The content of the data-item referenced by the identifier can identify the program to be
canceled.
literal-1

This is a nonnumeric literal that identifies the name of the program to be canceled.
library-name-1

This is the name of the library to be canceled. Cancellation of a library causes the
program to be delinked from the library.
Literal-1 must be the file title of the library if the BYTITLE option is specified, or the
function name of the library if the BYFUNCTION name is specified. The library name and
the option you choose must match those used when the library program was called.

8600 1518–307

6–47

CANCEL Statement

BYTITLE
BYFUNCTION

These options are described as follows:

•

BYTITLE indicates that the library was referred to by its file title in the CALL
statement of the calling program.

•

BYFUNCTION indicates that the library was referred to by its function name in the
CALL statement of the calling program.
The library name and the option you choose must match those used when the library
program was called.

•

If you do not specify an option, BYTITLE is assumed.

Details
When a program is canceled, the contents of data items in external data records
described by that program are not changed.
When Cancellation Occurs
A called program is canceled when any one of the following occurs:

•

When it is referred to as the operand of a CANCEL statement

•

At the termination of the run unit of which the program is a member

•

When an EXIT PROGRAM statement is executed in a called program that has the
initial attribute

All programs contained in the program referenced by the CANCEL statement are also
canceled.
Explicit and Implicit Cancel Statements
A CANCEL statement can be explicit or implicit. An explicit cancellation occurs when one
program cancels another. An implicit cancellation occurs with nested calls. Consider the
following example:
1. Program A calls Program B, and Program B calls Program C.
2. Program A contains a CANCEL statement to cancel Program B.
3. This statement, in effect, cancels Program C and then cancels Program B.
Program B is canceled explicitly, because it is directly canceled through a CANCEL
statement in Program A. Program C is canceled implicitly because its parent program,
Program B, was canceled.
After the execution of an explicit or implicit CANCEL statement, the referenced program
does not have a logical relationship to the run unit in which the CANCEL statement
appears. If the program referenced by a successfully executed explicit or implicit
CANCEL statement in a run unit is then called in that run unit, that program is in its initial
state.

6–48

8600 1518–307

CANCEL Statement

No action is taken when an explicit or implicit CANCEL statement is executed naming a
program that has not been called into the run unit or that has been called and is presently
canceled. Instead, control is transferred to the next executable statement following the
explicit CANCEL statement.
During execution of an explicit or implicit CANCEL statement, an implicit CLOSE
statement without optional phrases is executed for each file in the open mode that is
associated with an internal file connector in the program named in the explicit CANCEL
statement. USE procedures associated with these files are not executed.
Rules for Referenced Programs
A program named in a CANCEL statement in another program must be callable by that
other program.
A program named in the CANCEL statement must not refer directly or indirectly to any
program that has been called and has not yet executed an EXIT PROGRAM statement.
You can establish a logical relationship to a canceled program only by executing a
subsequent CALL statement that names the program.

Examples
03 Nme PIC X(6) VALUE
.
.
.
CANCEL NME.

"PROG-1".

This cancels the called program PROG-1. NME is an identifier, which contains a programname.
CANCEL

"AUDIT1" "AUDIT2".

This cancels the called programs AUDIT1 and AUDIT2.
CANCEL "AUDIT1", NME, "OBJECT/AUDIT2".
This cancels the called programs AUDIT1, PROG-1, and OBJECT/AUDIT2.

8600 1518–307

6–49

CAUSE Statement

CAUSE Statement
The CAUSE statement initiates the specified events.

CAUSE [ AND RESET ] event-identifier-1 [ ,event-identifier-2 ] . . .
ïïïïï
ïïï ïïïïï

Explanation
[AND RESET]

This phrase causes the specified events to be immediately reset for later use. Using this
phrase prevents the interrupt procedure from having to reset the events.
event-identifier-1, event-identifier-2 . . .

The event-identifier can be one or more of the following:

•

The name of a data-item declared with the USAGE IS EVENT phrase. The data-name
must be properly qualified and properly subscripted.

•

A task attribute of type EVENT. The two event task attributes are ACCEPTEVENT
and EXCEPTIONEVENT. For details about these task attributes, refer to the Task
Attributes Programming Reference Manual.

•

A file attribute of type EVENT. The three event file attributes are CHANGEEVENT,
INPUTEVENT, and OUTPUTEVENT. For details about these files attributes, refer to
the File Attributes Programming Reference Manual.

Details
When a process is suspended because it encountered a WAIT event-identifier
statement, and the CAUSE statement activates that event-identifier, the process
resumes execution.

6–50

8600 1518–307

CAUSE Statement

Activating events has the following effect upon interrupt procedures:

When an EVENT item is
activated by a CAUSE
statement and . . .

Then . . .

And . . .

The ALLOW INTERRUPT
statement was previously
used.

The calling program is
suspended.

All interrupt procedures
attached to that event are
executed immediately.

An interrupt procedure
attached to that event was
previously readied by the
ALLOW section-name
statement.

The calling program is
suspended.

The interrupt procedure is
executed immediately.

The DISALLOW
INTERRUPT statement
was previously used.

The calling program
continues executing.

All interrupt procedures
attached to that event are
queued.

An interrupt procedure
attached to that event was
previously restricted by
the DISALLOW sectionname statement.

The calling program
continues executing.

The interrupt procedure is
queued.

Refer to the ALLOW and DISALLOW statements for additional information.
If an event item activated by the CAUSE statement is tested as a conditional expression
in an IF statement, the event condition returns the value TRUE.
An event activated by the CAUSE statement remains activated until it is explicitly
deactivated by a RESET statement.

Example
CAUSE WS-EVENT (3).
CAUSE AND RESET WS-77-EVENT.

8600 1518–307

6–51

CHANGE Statement

CHANGE Statement
The CHANGE statement enables you to change the value of a file, library, or task
attribute.
This statement is fully supported in the TADS environment.

Format

Use

Format 1

This format changes the value of a numeric file attribute.

Format 2

This format changes the value of an alphanumeric file attribute.

Format 3

This format changes the value of a mnemonic file attribute.

Format 4

This format changes the value of a library attribute.

Format 5

This format changes the value of a task attribute.

Format 1: Changing the Value of a Numeric File Attribute
CHANGE file-attribute-identifier
ïïïïïï
ä TO
å
³ ïï
³ ä identifier-1 å
ã UP BY
â ã
â
³ ïï ïï
³ æ literal-1
ç
æ DOWN BY ç
ïïïï ïï
This format is supported in the TADS environment.

Explanation
file-attribute-identifier

This is the syntax that identifies the file attribute whose value you want to change. The
syntax of this clause is as follows:
ä OF å
ATTRIBUTE attribute-name ã ïï â file-name
æ IN ç
Ú
ïï
³ ( arithmetic-expression-1 [, arithmetic-expression-2 ] )
³ ( VALUE [(] attribute-name [)] )
À
ïïïïï

6–52

¿
³
³
Ù

8600 1518–307

CHANGE Statement

attribute-name

This is the name of one of the file attributes. For a comprehensive list of all the file
attributes, refer to the File Attributes Programming Reference Manual.
file-name

This is the name of the file whose attribute values you want to change.
arithmetic-expression

If arithmetic-expression-1 is used with a port file, the value of the expression must
specify which subfile of the file is affected. A subfile index is required for accessing or
changing attributes of a subfile of a port file.

If arithmetic-expression-1 is . . .

Then . . .

Not specified

The attribute of the port is accessed.

Specified and its value is nonzero

The value of the expression specifies a
subfile index and causes the attribute of the
subfile to be accessed.

Specified and its value is zero

The attributes of all subfiles are accessed.

If an arithmetic expression is used with a disk file, the values of arithmetic-expression-1
and arithmetic-expression-2 must specify the row and copy parameters for the file.
VALUE (attribute-name)

This phrase is valid for use only with the FILEEQUATED attribute.
identifier-1
literal-1

Identifier-1 must be a numeric data item that represents an integer. Literal-1 must be a
numeric literal.
UP BY
DOWN BY

These descriptors are for use only with the STATIONLIST file attribute. When UP BY is
specified, the current value of the STATIONLIST attribute is increased by the value of
identifier-1 or literal-1. When DOWN BY is specified, the value is decreased by the value
of identifier-1 or literal-1.

Example
CHANGE ATTRIBUTE BLOCKSIZE OF INPUTFILE TO 420.
This statement changes the BLOCKSIZE attribute of the file INPUTFILE to the value 420.

8600 1518–307

6–53

CHANGE Statement

Format 2: Changing the Value of an Alphanumeric File Attribute

CHANGE
ïïïïïï

file-attribute-identifier TO
ïï

ä identifier-1 å
ã
â
æ literal-1
ç

This format is supported in the TADS environment.

Explanation
file-attribute-identifier

This syntax identifies the file attribute whose value you want to change. The syntax of
this identifier is provided with the explanation of Format 1.
identifier-1
literal-1

Identifier-1 must be a nonnumeric, DISPLAY data item that ends with a period (.). Literal1 must be a nonnumeric literal.

Examples
CHANGE ATTRIBUTE TITLE OF MY-FILE TO "MY/FILE".
This example shows how to specify a file name for the TITLE file attribute.
CHANGE ATTRIBUTE YOURIPADDRESS OF PFILE TO """192.39.0.20"".".
This example shows how to specify the IP address when writing a port file program for
TCP/IP. Note that the IP address must be enclosed in quotation marks.

6–54

8600 1518–307

CHANGE Statement

Format 3: Changing the Value of a Mnemonic File Attribute

CHANGE
ïïïïïï

file-attribute-identifier TO
ïï
[ VALUE ] [ ( ] mnemonic-attribute-value [ ) ]
ïïïïï

This format is supported in the TADS environment.

Explanation
file-attribute-identifier

This syntax identifies the file attribute whose value you want to change. The syntax for
this identifier is provided in the explanation of Format 1.
mnemonic-attribute-value

This is the mnemonic value that you want to assign to the specified file attribute. If a
data-name has the same name as the mnemonic-attribute-value, the value assigned to
the attribute is dependent upon whether the optional word VALUE is used. If the word
VALUE is present, the attribute is set to the value of the mnemonic. If the word VALUE
is omitted, the attribute is set to the current value of the data-name.

Details
The current state of the file might inhibit the changing of certain file attributes. Some file
attributes cannot be changed while the file is in open mode. Also, some file attributes
cannot be changed until the file is opened. For more information on file attributes, refer
to Section 12.
Certain file attributes are used by the compiler to implement various constructs required
to declare and access files within the program. Whenever possible, it is preferable to use
standard COBOL syntax for setting or declaring a file attribute that is used also by the
compiler.

Example
CHANGE ATTRIBUTE UNITS OF INPUTFILE TO VALUE WORDS.
This changes the UNITS attribute of the file INPUTFILE to the value associated with the
mnemonic WORDS.

8600 1518–307

6–55

CHANGE Statement

Format 4: Changing the Value of a Library Attribute
ä
³
³
³
CHANGE ATTRIBUTE ã
ïïïïïï ïïïïïïïïï ³
³
³
æ

TO
ïï

ä
³
³
³
ã
³
³
³
æ

FUNCTIONNAME å
ïïïïïïïïïïïï ³
INTNAME
³
ïïïïïïï
³
LIBACCESS
â OF
ïïïïïïïïï
³ ïï
LIBPARAMETER ³
ïïïïïïïïïïïï ³
TITLE
ç
ïïïïï
Ú
[ VALUE ] ³ BYFUNCTION
ïïïïï
³ ïïïïïïïïïï
³ BYINITIATOR
³ ïïïïïïïïïïï
³ BYTITLE
À ïïïïïïï
literal-2

ä
Ú
³
³
³ literal-1
³
ã
³
³
À
æ library-name

¿
³
³
³
³
³
Ù

å
³
³
³
â
³
³
³
ç

BYTITLE
ïïïïïïï
BYFUNCTION
ïïïïïïïïïï

¿
³
³
³
Ù

å
³
³
â
³
ç

This format is supported in the TADS environment.

Explanation
FUNCTIONNAME
INTNAME
LIBACCESS
LIBPARAMETER
TITLE

These are the library attributes you can change. The FUNCTIONNAME, INTNAME,
LIBPARAMETER, and TITLE library attributes are either string or DISPLAY library
attributes. The LIBACCESS library attribute is a mnemonic library attribute. For a
description of the library attributes, refer to Section 11.
literal-1

This option identifies the library whose attribute is to be changed. If the library is
identified by a literal, the library is assumed to be a COBOL74 or implicit library program.
BYTITLE
BYFUNCTION

This indicates whether the CALL statement called the library by its file title or by its
function name. BYTITLE indicates that the library was referred to by its file title in the
CALL statement. BYFUNCTION indicates that the library was referred to by its function
name in the CALL statement. The library name and the option you choose must match
those used in the CALL statement.

6–56

8600 1518–307

CHANGE Statement

library-name

If the library is identified by an unquoted library-name, the library is assumed to be an
explicit library program. The library-name must have been previously declared in the
Program-Library Section of the program containing the CHANGE statement.
BYFUNCTION
BYTITLE
BYINITIATOR

You can assign one of these values to the LIBACCESS library attribute. The LIBACCESS
attribute specifies the way in which the library object code file is to be accessed when
the library is called.

•

If LIBACCESS is equal to BYTITLE, then the TITLE attribute of the library is used to
find the object code file. BYTITLE is the default value.

•

If LIBACCESS is equal to BYFUNCTION, then the FUNCTIONNAME attribute of the
library is used to access the MCP library function table, and the object code file
associated with that FUNCTIONNAME is used.

•

If LIBACCESS is equal to BYINITIATOR, then the library that initiated the program is
the library that is accessed.

For a discussion of library attributes, refer to Section 11.
literal-2

This literal is the value to be assigned to the FUNCTIONNAME, LIBPARAMETERS, or
TITLE library attribute.

Examples
CHANGE ATTRIBUTE FUNCTIONNAME OF LIB/TEST/1 TO LIBOPS.
This statement changes the system function name of the library titled LIB/TEST/1 to
LIBOPS.
CHANGE ATTRIBUTE LIBACCESS OF LIB/TEST/1 TO BYFUNCTION.
This statement changes the value of the LIBACCESS attribute of the library named
LIB/TEST/1 to BYFUNCTION.

8600 1518–307

6–57

CHANGE Statement

Format 5: Changing the Value of a Task Attribute

CHANGE task-attributeïïïïïï identifier-1 TO
ïï

ä
³
³
³
ã
³
³
³
³
æ

identifier
literal
Ú
¿
³ ä
å ³
³ ã VALUE â ³ task-attribute-mnemonic
³ æ ïïïïï ç ³
À
Ù
task-attribute-identifier-2

å
³
³
³
â
³
³
³
³
ç

This format is supported in the TADS environment.

Explanation
task-attribute-identifier-1

This identifies the task attribute whose value you want to change. The syntax for the task
attribute identifier is provided with the description of task-attribute-identifier-2.
identifier
literal

This is the value you want to assign to the task attribute.

•

If the task attribute requires a numeric value, the identifier must be a numeric data
item that represents an integer, or the literal must be a numeric literal.

•

If the task attribute requires an alphanumeric value, the identifier must be a
nonnumeric DISPLAY data item that ends with a period (.), or the literal must be a
nonnumeric literal.

For details about task attributes, see the Task Attributes Programming Reference
Manual.
task-attribute-mnemonic
VALUE task-attribute-mnemonic

This name is associated with a constant value for an attribute that has a set number of
predetermined possible values. If the same name is used for a data-name and a taskattribute-mnemonic, the value assigned to the attribute is determined by the presence of
the word VALUE. If the word VALUE is present, the attribute is set to the value of the
mnemonic. If the word VALUE is omitted, the attribute is set to the current value of the
data-name.
You must use task-attribute-mnemonics to access specific options of the OPTION task
attribute. The mnemonics represent specific bits in the OPTION task attribute word. You
can access these bits by using Format 3 of the MOVE statement.

6–58

8600 1518–307

CHANGE Statement

Note that attribute mnemonics are not treated as COBOL reserved words. They are
reserved only within the context in which they are used and can also be used as data
names or procedure names.
task-attribute-identifier-2

This identifier enables you to change the attribute value to the value used by the same
attribute of another process. The syntax for the task-attribute-identifier is as follows:

ATTRIBUTE attribute-name OF
ïïïïïïïïï

ä
³
³
ã
³
³
³
³
æ

å
³
³
MYSELF
â
ïïïïïï
³
MYJOB
³
ïïïïï
³
ATTRIBUTE attribute name OF ... ³
ïïïïïïïïï
ç
task-variable [ (subscript) ]

attribute-name

This is the name of one of the task attributes. The complete set of task attributes is
documented in the Task Attributes Programming Reference Manual.
Attribute names are not reserved words. They are reserved only within the context in
which they are used and can also be used as data names or procedure names.
task-variable [(subscript)]

This is the task variable that is associated with the process whose task attribute value
you want to change. The optional subscript is used to identify a specific task variable
when multiple task variables are declared with an OCCURS clause. A maximum of one
subscript is permitted. For an example of how a task variable is used with a subscript,
refer to “Example of Passing Control Between Two Programs” in Section 13.
A user-declared task variable must be declared as a data item in the Working Storage
Section of the Data Division.
MYSELF
MYJOB

These are system-declared task variables. MYSELF refers the process itself. MYJOB
refers to the independent process in a group of related dependent processes (the
process family).

8600 1518–307

6–59

CHANGE Statement

ATTRIBUTE attribute-name OF . . .

This syntax gives a process access to the task attributes of an associated process. For
example, you could specify the parent of TASK-EXAMPLE1 by using the following syntax:
ATTRIBUTE NAME OF ATTRIBUTE EXCEPTIONTASK OF TASK-EXAMPLE1

Details
You can display the value of any task attribute, except string-type task attributes
(attributes whose values are character strings), by using the DISPLAY statement. For
string-type task attributes, you must move the attribute into a data area with the MOVE
statement, and then display the value with the DISPLAY statement.
Attributes with an implicit numeric class can be used in DISPLAY statements and in
place of any identifier in an arithmetic statement, except the receiving-field identifier.
You can determine the mnemonic value of a task attribute by using the task attribute in a
conditional expression. For details about conditional expressions, see Section 5.
In general, the types of task attributes and the values that are valid for them are shown in
the following table. For detailed information about task attributes and their values, refer
to the Task Attributes Programming Reference Manual.

For the attribute type of . . .

The accepted and returned values are . . .

String

Alphanumeric

Boolean

Numeric (or the value associated with a mnemonic)

Integer

Numeric (or the value associated with a mnemonic)

All other attributes types

Numeric identifier, literal, arithmetic expression, or
the value associated with a mnemonic

If the value you assign to a task attribute is not within the permissible range for the
specified attribute, an error occurs at the time of compilation or execution.

6–60

8600 1518–307

CHANGE Statement

Examples
CHANGE ATTRIBUTE OPTION OF VERSION1/TEST TO TODISK.
This first example changes the value of the OPTION attribute of the process named
VERSION1/TEST to the value TODISK. (The OPTION attribute affects program dump
contents, job summary printing, and backup file handling. For details, refer to the File
Attributes Programming Reference Manual.)
CHANGE ATTRIBUTE BLOCKSIZE OF VERSION1/TEST TO ATTRIBUTE BLOCKSIZE OF
STANDARD/SYS/RUN.
This second example changes the value of the BLOCKSIZE attribute of the process
named VERSION1/TEST to the value used by the BLOCKSIZE attribute of the process
named STANDARD/SYS/RUN.
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-TASK
TASK.
01 WS-NAME
PIC X(50).
PROCEDURE DIVISION.
MAIN SECTION.
MAIN-PARA.
CHANGE ATTRIBUTE NAME OF WS-TASK TO "TEST/RUNFILE/FEB".
MOVE ATTRIBUTE NAME OF WS-TASK TO WS-NAME.
DISPLAY WS-NAME.
STOP RUN.

This program example illustrates how you can change the name of a task by using the
CHANGE statement, and how you can verify the name change by using the MOVE and
DISPLAY statements. The NAME task attribute is a string-type task attribute, which
means that its value is a character string. You must use the MOVE and DISPLAY
statements to check the value of a string-type task attribute. For all other task attributes,
you can use just the DISPLAY statement.

8600 1518–307

6–61

CLOSE Statement

CLOSE Statement
The CLOSE statement ends the processing of a file or a reel/unit of a file. Also, it can
specify the disposition of the file and the device to which the file is assigned.
This statement is partially supported in the TADS environment. Applicable exclusions are
noted in this section.

Format

Use

Format 1

This format ends the processing of sequential files.

Format 2

This format ends the processing of either relative or indexed files.

Format 1: Sequential I-O

CLOSE
ïïïïï

ä
³
³
³
³
³file-name-1
³
³
³
³
³
ã
³
³
³
³
³
³
³
³
³
³
³
³
æ

Ú
³
³ ä REEL å
³ ã ïïïï â [ FOR REMOVAL ]
³ æ UNIT ç
ïïïïïïï
³
ïïïï
³
³
ä NO REWIND
å
³
³ ïï ïïïïïï
³
³
³ LOCK
³
³
³ ïïïï
³
³
³ SAVE
³
³
³ ïïïï
³
³
³ PURGE
³
³ WITH ã ïïïïï
â
³
³ CRUNCH
³
³
³ ïïïïïï
³
³
³ RELEASE
³
³
³ ïïïïïïï
³
³
³ DISMISS
³
³
³ ïïïïïïï
³
³
³ REMOVE [ CRUNCH ] ³
³
³ ïïïïïï
ïïïïïï
³
³
æ NO WAIT
ç
À
ïï ïïïï

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
Ù

å
³
³
³
³
³
³
³
³
³
³
â . . .
³
³
³
³
³
³
³
³
³
³
³
³
ç

This format is supported in the TADS environment.

6–62

8600 1518–307

CLOSE Statement

Explanation
file-name-1

This name is a user-defined word that specifies the name of the file to be closed.
The specified file must be in an open mode.
Files referenced in the CLOSE statement can have different organizations and access
modes.
REEL
UNIT

These are equivalent.
The reel/unit is closed and rewound.
Treatment of sequential mass storage files is logically equivalent to the treatment of a
file on tape or a similar sequential medium.
Treatment of a file contained in a multiple-file tape environment is logically equivalent to
the treatment of a sequential single-reel/unit file, if the file is contained on one reel.
The REEL or UNIT phrase and the NO REWIND option cannot be specified together in a
CLOSE statement.
FOR REMOVAL

This option is used for sequential single-reel/unit files and multi-reel/unit files. The
reel/unit is closed, and the system waits for the next reel/unit.
NO REWIND

The file is closed, and the current reel/unit is left in its current position.
The NO REWIND option and the REEL or UNIT phrase cannot be specified together in a
CLOSE statement.
LOCK

The logical file is marked as locked, so that it cannot be reopened during the execution of
the program. If the file is a mass-storage file, it becomes a permanent file before it is
made unavailable. If the file is assigned to tape, the physical unit is made not ready.
SAVE

This disposition is valid only for mass-storage files. The file is made permanent and can
be reopened during execution of the program.

8600 1518–307

6–63

CLOSE Statement

PURGE

This disposition is valid only for files assigned to tape or to mass-storage devices.
If the file is assigned at execution time to a tape device, the reel is rewound. If the reel
has a write ring, a scratch label is written on it, and the device is released as available to
the system.
If the file is a permanent mass-storage file, the file-name is removed from the directory
of the system, and the mass-storage area occupied by the file is released as available to
the system.
PURGE is generally used for a temporary file that you have used and then want to
relinquish to free the space allocated for the file.
RELEASE
DISMISS

DISMISS and RELEASE are synonymous.
This disposition severs the association between the logical file and the physical file. The
areas of memory allocated for buffers can be released to the system.
If the device to which the file was assigned can be controlled by the object program, it is
released as available to the system.
REMOVE

This disposition is valid only for mass-storage files.
The file is closed, and the association between the logical file and the physical file is
severed. The file is made permanent and can be reopened during execution of the
program.
CRUNCH

This disposition is valid only for mass-storage files.
The file is made a permanent file. Unused portions of mass-storage areas allocated for
the file are released as available to the system. The file cannot subsequently be
extended by opening the file with an OPEN EXTEND statement.
NO WAIT

The WITH NO WAIT phrase can be specified only for port files. It is mutually exclusive
with all other CLOSE options.
With this option, the program does not wait until the file is closed before resuming
execution. Control is returned to the next statement without waiting for the CLOSE
operation to be completed.

6–64

8600 1518–307

CLOSE Statement

Details
The execution of the CLOSE statement updates the value of the I-O status associated
with the specified file. Refer to Table 3–1 for information on the I-O status codes.
A CLOSE statement can be executed only for a file in open mode. In general, a CLOSE
statement changes the FILEUSE attribute of the file to I-O. This change can affect the
results of any subsequent access to the RESIDENT, PRESENT, or AVAILABLE attribute
of the file. (A CLOSE statement without a specified option retains the file and does not
change the FILEUSE attribute of the file.)
End-of-file or reel/unit processing is performed for the file if an optional input file is
present. Processing is not performed if an optional input file is not present. In this case,
the file position indicator and the current volume pointer are unchanged.
Following the successful execution of a CLOSE statement without the REEL or UNIT
phrase, the record area associated with the specified file is no longer available. After the
unsuccessful execution of such a CLOSE statement, the record area remains
unchanged.
Following the successful execution of a CLOSE statement without the REEL or UNIT
phrase, the file is removed from the open mode, and the file is no longer associated with
the file connector.
If more than one file-name is specified in a CLOSE statement, the result of executing this
CLOSE statement is as if a separate CLOSE statement had been written for each filename in the same order as specified in the CLOSE statement.
TADS
Any USE procedure is not executed when a CLOSE statement that is compiled and
executed in a TADS session fails.
Effect of CLOSE Statements on Different Storage Media
In general, a CLOSE statement changes the FILEUSE attribute of the file to I-O. This
change can affect the results of any subsequent access to the RESIDENT, PRESENT, or
AVAILABLE attributes of the file. (A CLOSE statement without a specified option retains
the file and does not change the FILEUSE attribute of the file.)
A CLOSE statement without file retention also checks the EXCLUSIVE attribute of the
file during the CLOSE operation. If this attribute is found to be TRUE, it is set to FALSE
during the CLOSE process.

8600 1518–307

6–65

CLOSE Statement

The formats of the CLOSE statements affect various storage media differently. To show
the effects of CLOSE statements on various storage media, all files are divided into the
following categories:

•

Non-reel/unit file
This is a file whose input or output medium is such that the concepts of rewind,
reels, and units have no meaning. This category includes mass-storage files.
A CLOSE statement executed for a non-reel/unit file can affect the disposition of the
device to which it is assigned. The CLOSE statement affects only the disposition of
the physical file and its association with the logical file, not the disposition of the
physical device.

•

Sequential single-reel/unit file
This is a sequential file that is entirely contained on one reel/unit.

•

Sequential multi-reel/unit file
This is a sequential file that is contained on more than one reel/unit.

6–66

8600 1518–307

CLOSE Statement

Table 6–5 summarizes the results of executing each type of CLOSE statement for each
category of file. Definitions of the numeric entries appear in the paragraphs following the
table.
Table 6–5. Relationship of File Types and CLOSE Formats

CLOSE
Statement
Format

Non-Reel or Unit

Sequential
Single-Reel or
Unit

Sequential MultiReel or Unit

379

1 2 3 17

CLOSE
REEL/UNIT

6 15

6 7 15

CLOSE
REEL/UNIT FOR
REMOVAL

6 15

467

CLOSE WITH NO
REWIND

3 8 15

289

1 2 3 17

CLOSE WITH
LOCK

3 5 10 11

3 5 7 10 11

1 3 5 7 10 11

CLOSE WITH
SAVE

3 10 13

CLOSE WITH
PURGE

3 12

3 7 12

1 3 7 12

CLOSE WITH
RELEASE

3 10 11

3 7 10 11

1 3 7 10 11

CLOSE WITH
DISMISS

3 10 11

3 7 10 11

1 3 7 10 11

CLOSE WITH
REMOVE

3 10 13

CLOSE WITH
CRUNCH

3 10 14

CLOSE WITH
REMOVE
CRUNCH

3 10 13

CLOSE WITH NO
WAIT

8600 1518–307

6–67

CLOSE Statement

The following paragraphs explain the meaning of the numerical values in Table 6-5. In
these paragraphs, definitions apply to input, output, and input-output files. Alternate
definitions are given where the type of file affects the definition.
1. Previous reels or units are closed.
Input Files and Input-Output Files:
All reels or units in the file before the current reel/unit are closed (except for those
reels or units controlled by a prior CLOSE REEL or CLOSE UNIT statement). The
reels or units in the file following the current one are not processed.
Output Files:
All reels or units in the file before the current reel/unit are closed (except for those
reels or units controlled by a prior CLOSE REEL or CLOSE UNIT statement).
2. The current reel is not rewound.
The current reel/unit is left in its current position.
3. The logical file is closed.
Input Files and Input-Output Files:
If the file is positioned at its end and label records are specified for the file, the labels
are processed according to the system standard label conventions. The results of the
CLOSE statement when label records are specified but not present, or when label
records are not specified but are present, are unpredictable.
If the file is positioned at its end and label records are not specified for the file, label
processing does not take place. If the file is not positioned at its end, standard
closing operations are executed, but there is no end label processing.
Output Files:
If label records are specified for the file, the labels are processed according to the
system standard label conventions. The results of the CLOSE statement when label
records are specified but not present, or when label records are not specified but are
present, are unpredictable. If label records are not specified for the file, label
processing does not take place.
4. The reel/unit is removed.
The current reel/unit is rewound, when applicable, and the reel/unit is logically
removed from the run unit.
The reel/unit can be accessed again in its proper order of reels or units within the file.
This can occur if a CLOSE statement without the REEL or UNIT phrase is
subsequently executed for this file followed by the execution of an OPEN statement
for the file.
5. The file is locked.
The file cannot be opened again during this execution of the run unit.

6–68

8600 1518–307

CLOSE Statement

6. The reel/unit is closed.
Input Files and Input-Output Files:
There is no reel/unit swap and the current volume pointer remains unchanged if one
of the following conditions exists: if the current reel/unit is the last or only reel/unit
for the file; or it the reel is a non-reel or non-unit medium.
However, if another reel/unit exists for the file, or if a reel/unit swap occurs, the
current volume pointer is updated to point to the next reel/unit that exists in the file.
The standard beginning reel/unit label procedure is executed. Another reel/unit swap
occurs if no data records exist for the current volume.
Output Files (Reel/Unit Media):
The standard ending reel/unit label procedure is executed. A reel/unit swap occurs,
and the current volume pointer is updated to point to the new reel/unit, and the
standard beginning reel/unit label procedure is executed. The next executed WRITE
statement to reference that file directs the next logical data record to the next
reel/unit of the file.
Output Files (Nonreel or Nonunit Media):
Execution of this statement is successful. The file remains in open mode, and no
action takes place (except that the value of the I-O status associated with the
specified file-name is updated).
7. Rewinding occurs.
The current reel or a similar device is positioned at its physical beginning.
8. Optional phrases are ignored.
The CLOSE statement is executed, and optional phrases, if present, are ignored.
9. The file is retained.
The association between the logical file and the physical file is retained. Subsequent
reopening of the file cannot require the operating system to search for the physical
file.
10. The file is released.
11. The device is released.
12. The file is purged.
13. The file is saved.
14. The file is crunched.
15. The combination of CLOSE option and file category is illegal.
If the CLOSE statement specifies the REEL or UNIT phrase, the CLOSE statement
has no effect, and the file is not closed.
If the CLOSE statement does not specify the REEL or UNIT phrase, any optional
disposition is ignored, but the file is closed.
16. The WITH NO WAIT phrase can be specified only for port files and is mutually
exclusive with all other CLOSE options.
17. The file is reserved.

8600 1518–307

6–69

CLOSE Statement

Port Files
For a port file with an ACTUAL KEY clause, the value of the ACTUAL KEY determines
which subfile of the file is to be closed. If the ACTUAL KEY value is nonzero, only the
specified subfile is closed. If the ACTUAL KEY value is 0 or if the ACTUAL KEY is not
specified, all opened subfiles are closed.
A CLOSE statement with no phrase specified causes the program to wait until the file is
closed before resuming execution. This suspension is prevented for port files by
specifying the WITH NO WAIT phrase, which causes control to be returned to the next
statement without waiting for the CLOSE to be completed.

Examples
CLOSE DSKFIL WITH NO REWIND
This ends the processing of the file DSKFIL and the reel or unit is left in its current
position.
CLOSE MYTAPE REEL FOR REMOVAL
This ends the processing of the file MYTAPE, and the reel is closed. The system expects
the next volume to this multireel file.

6–70

8600 1518–307

CLOSE Statement

Format 2: Relative and Indexed I-O

CLOSE
ïïïïï

ä
³
³
³
³
³
ã
³file-name-1
³
³
³
³
³
³
æ

Ú
³
³
³
³
³
³
³ WITH
³
³
³
³
³
³
À

ä
³
³
³
ã
³
³
³
³
³
æ

LOCK
ïïïï
SAVE
ïïïï
PURGE
ïïïïï
RELEASE
ïïïïïïï
DISMISS
ïïïïïïï
REMOVE [ CRUNCH ]
ïïïïïï
ïïïïïï

å
³
³
³
â
³
³
³
³
³
ç

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
Ù

å
³
³
³
³
³
â
³
³
³
³
³
³
³
ç

. . .

This format is supported in the TADS environment.

Explanation
Refer to Format 1 for descriptions of the syntax elements file-name-1 and WITH LOCK,
and for other details concerning the CLOSE statement.
For detailed information on file attributes, file organization, and file access modes, refer
to Section 11.
Refer to the File Attributes Programming Reference Manual for information on file
attributes.
Refer to “OPEN Statement” in this section for syntax and detailed information.
Effect of CLOSE Statements on Different Storage Media
Relative and indexed files belong to the category of non-sequential single- or multi-reels
or units.
Table 6–6 summarizes the results of executing each type of CLOSE statement for this
category of file. Definitions of the numeric entries appear following the table.

8600 1518–307

6–71

CLOSE Statement

Table 6–6. Relationship of CLOSE Formats and Nonsequential
Units

Nonsequential Single- or
Multi-Reel or Unit

CLOSE Statement Format

CLOSE WITH LOCK

124

CLOSE WITH SAVE

145

CLOSE WITH PURGE

CLOSE WITH RELEASE

CLOSE WITH DISMISS

CLOSE WITH REMOVE

145

The following paragraphs explain the meaning of the numerical values in Table 6-6. In
these paragraphs, the definitions apply to input, output, and input-output files. Alternate
definitions are given where the file type affects the definition.
1. The file is closed.
Input Files and Input-Output Files (Sequential Access Mode):
If the file is positioned at its end and label records are specified for the file, the labels
are processed according to the system standard label conventions. The result of the
CLOSE statement when label records are specified but not present is unpredictable.
If the file is positioned at its end and label records are not specified for the file, label
processing does not occur.
If the file is not positioned at its end, the standard closing operations are executed,
but there is no end-label processing.
Input Files and Input-Output Files (Random or Dynamic Access Mode),
Output Files (Random, Dynamic, or Sequential Access Mode):
If label records are specified for the file, the labels are processed according to the
system standard label conventions. The results of the CLOSE statement when label
records are specified but not present, or when label records are not specified but are
present, are unpredictable.
2. The file is locked.
The file is locked and cannot be opened again during the execution of this run unit.
3. The file is retained.
The association between the logical file and the physical file is retained. Subsequent
reopening of the file cannot require the operating system to search for the physical
file.

6–72

8600 1518–307

CLOSE Statement

4. The file is released.
The association between the logical file and the physical file is severed. The areas of
memory allocated for buffers can be released to the system.
5. The file is saved.
The physical file is made permanent. Any existing file with the same name is
removed.
6. The file is purged.
If the file is permanent, the file-name is removed from the directory of the system.
Then, the storage area occupied by the file is released as available to the system.

Example
CLOSE INXFIL WITH LOCK, INX223 WITH RELEASE
This closes and locks INXFIL and then closes INX223. It releases to the system the areas
of memory allocated for buffers.

8600 1518–307

6–73

COMPUTE Statement

COMPUTE Statement
Format

Use

Format 1

This format assigns to one or more numeric data items the values of
an arithmetic expression

Format 2

This format assigns to one or more Boolean data items the values of a
Boolean expression

Format 1: Arithmetic Compute
This form of the COMPUTE statement calculates an arithmetic expression and stores the
result.
Rules and explanations of the COMPUTE statement and other arithmetic statements are
discussed under “Arithmetic Expressions” in Section 5.
For information on rounding, size error conditions, and intermediate data items, refer to
“ROUNDED Phrase,” “SIZE ERROR Phrase,” and “Intermediate Data Item” in
Section 5.
Refer to the ADD, DIVIDE, MULTIPLY, and SUBTRACT statements in this section for
syntax and detailed information.
This statement is partially supported in the TADS environment. Supported syntax is
noted in this section.

COMPUTE { identifier-1 [ ROUNDED ] } . . . =
ïïïïïïï
ïïïïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïï ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-COMPUTE ]
ïïïïïïïïïïï

arithmetic-expresion-1

TADS Syntax
COMPUTE { identifier-1 [ ROUNDED ]
ïïïïïïï
ïïïïïïï
[ END-COMPUTE ]
ïïïïïïïïïïï

6–74

} . . .

arithmetic-expresion-1

8600 1518–307

COMPUTE Statement

Explanation
identifier-1

This must refer to either an elementary numeric item or an elementary numeric-edited
item.
ROUNDED

This optional phrase rounds the result from the COMPUTE statement to the size required
by the data item where the result will be returned. For details about the ROUNDED
phrase, refer to Section 5.
arithmetic-expression-1

An arithmetic expression contains combinations of numeric identifiers and numeric
literals that are separated by arithmetic operators and parentheses.
An arithmetic expression that consists of a single identifier or literal provides a way to set
the value of the data item referenced by identifier-1 equal to the literal or the value of the
data item referenced by the single identifier.
ON SIZE ERROR imperative-statement-1

If a size error condition exists, imperative-statement-1 is executed.
NOT ON SIZE ERROR imperative-statement-2

If a size error condition does not exist, imperative-statement-2 is executed.
END-COMPUTE

This delimits the scope of the COMPUTE statement.

Details
The COMPUTE statement enables you to combine arithmetic operations without the
restrictions on composite operands and receiving data items imposed by the ADD,
SUBTRACT, MULTIPLY, and DIVIDE statements.
If more than one identifier is specified for the result of the operation, the value of the
arithmetic expression is calculated and stored as the new value of each of the data items
referred to by identifier-1 and so forth.
Notes on Lengths
The length of an intermediate data item is limited to 23 decimal digits. When coding
COMPUTE statements, design the statement so that no intermediate fields will be
longer than 23 digits.

8600 1518–307

6–75

COMPUTE Statement

The ON SIZE ERROR phrase checks for an overflow of significant data only as it is
moved into the output field. The phrase does not check for a 23-digit limit overflow in any
intermediate data items.
Multiplication results in a field length equal to the sum of the lengths of the operands.
The result of an addition requires a length one digit larger than the largest operand.
Exponentiation results in a field length equal to the length of the base times the power.
Subtraction and division require a result field equal in length to the largest operand.

Examples
COMPUTE A = B * C + 4
The value of identifier B is multiplied by the value of C, 4 is added to it, and the result is
stored in A.
COMPUTE A, B ROUNDED = X / 10
ON SIZE ERROR PERFORM SZ-ERR-PROC
NOT ON SIZE ERROR PERFORM WRITE-PROC
END-COMPUTE.
The value of X is divided by 10, and the result is stored in A and B. The result stored in B
is rounded. If a size error condition occurs, the statements in SZ-ERR-PROC are
executed. If a size error condition does not exist, the statements in WRITE-PROC are
executed.

6–76

8600 1518–307

COMPUTE Statement

Format 2: Boolean Compute
COMPUTE
ïïïïïïï

{ identifier-1 } . . .

Boolean-expression [ END-COMPUTE ]
ïïïïïïïïïïï

Explanation
identifier-1

This must refer to a Boolean data item.
Boolean-expression

A Boolean expression contains combinations of Boolean identifiers and Boolean literals
that are separated by Boolean operators and parentheses.
END-COMPUTE

This defines the ending limit of the COMPUTE statement.

Details
The number of Boolean positions in the value resulting from the evaluation of a Booleanexpression is the number of Boolean positions in the largest Boolean item referenced in
the expression.
The value resulting from the evaluation of a Boolean expression moves to the data item
referenced by the identifier according to the rules of the MOVE statement.

8600 1518–307

6–77

CONTINUE Statement

CONTINUE Statement
Format

Use

Format 1

This format indicates that no executable statement is present in the
line of code.

Format 2

This format returns control to a synchronous process that has been
previously called and exited.

Format 1: Designating an Unexecutable Line of Code
CONTINUE

Explanation
This form of the CONTINUE statement indicates that there are no executable statements
in a line of code.

Details
You can use a CONTINUE statement anywhere you can use a conditional statement or
an imperative statement.
The CONTINUE statement is a no-operation statement; it does not affect the execution
of the program.

Example
IF A > B PERFORM CALC-AB
IF A > C PERFORM CALC-AC
IF A > D PERFORM CALC-AD
IF A >= E PERFORM CALC-AD
ELSE MOVE E TO E-OUT
ELSE MOVE D TO D-OUT
ELSE MOVE C TO C-OUT
ELSE MOVE B TO B-OUT
END-IF.

CONTINUE
CONTINUE
CONTINUE

The CONTINUE statements in this example do not affect the outcome of the IF
statements. The CONTINUE statements are used for documentation purposes only.

6–78

8600 1518–307

CONTINUE Statement

Format 2: Returning to the Called Process
CONTINUE task-variable
ïïïïïïïï

Explanation
This form of the CONTINUE statement reinstates a synchronous, dependent process
that was previously initiated by a CALL statement from another program and then exited
by an EXIT PROGRAM statement.
task-variable

This task variable is associated with the process that you want to resume execution. This
task variable must be the same task variable that was used in a previously executed
CALL statement.

Details
If the called process was exited by an EXIT PROGRAM statement, the CONTINUE
statement causes the called process to restart at its first executable statement.
If the called process was exited by an EXIT PROGRAM RETURN HERE statement, the
CONTINUE statement causes the called process to restart at the statement following
the EXIT PROGRAM RETURN HERE statement.
Parameters to be passed between programs are initialized when the CALL statement is
executed and do not have to be passed again for successive CONTINUE statements.
Data items in the called program also retain their values.
For an example of how the CONTINUE statement is used, see the program examples in
Section 13.

8600 1518–307

6–79

COPY Statement

COPY Statement
The COPY statement incorporates text from a COBOL library file into the program that
contains the COPY statement.
Refer to “REPLACE Statement” in this section for information on replacing source
program text.

COPY
ïïïï

Ú
³
³text-name-1
³
³
³
³literal-2
À

Ú
³ä
³ã
³æ
À

Ú
Ú
³
³ ä THROUGH
³
³ ³ ïïïïïïï
³ FROM sequence-number-1 ³ ã THRU
³
³ ³ ïïïï
³
³ æ TO
À
À
ïï
Ú
³
³
³REPLACING
³ïïïïïïïïï
³
À

ä
³
³
ã
³
³
æ

¿
³
[ ON family-name ]³
ïï
³
³
³
³
Ù
¿ ¿
³ ³
³ ³
sequence-number-2 ³ ³
³ ³
³ ³
Ù Ù

OF å library-name-1
ïï â
IN ç literal-1
ïï

å
³
â
³
ç

¿
³
³ . . .
³
Ù

==pseudo-text-1== å
ä ==pseudo-text-2==
³
³
identifier-1
³
³ identifier-2
â BY ã
literal-3
³ ïï ³ literal-4
³
³
word-1
ç
æ word-2

å
³
³
â
³
³
ç

å
¿
³
³
³
³
â . . . ³ . [ ; ]
³
³ ï
ï
³
³
ç
Ù

Explanation
text-name-1

This is the external name of a file in the COBOL library. In the library name
LIBRARY/A/B/C, C is the actual file name and, thus, C would be specified for text-name1. Each text-name must be unique within a COBOL library.
OF
IN
library-name-1
literal-1

This construct specifies the external name of the directory in which the COBOL library
file named as text-name-1 resides.
You can specify a multilevel directory by specifying each directory name in reverse order
separated by the word OF or IN.

6–80

8600 1518–307

COPY Statement

For example, if a library has the file name LIBRARY/A/B/C, LIBRARY/A/B is the directory
and C is the file name. The complete specification of the file name and its directories in
the COPY statement would be
COPY C OF B OF A OF LIBRARY.
Literal-1 can have the same contents as library-name-1 and is a nonnumeric literal.
If more than one COBOL library is available during compilation, text-name-1 must be
qualified by library-name-1 to identify the COBOL library in which the text associated with
text-name-1 resides.
ON family-name

Family-name specifies the name of the family in which the library file resides.
literal-2

This literal allows you to specify the entire title of the copy library file in a single
nonnumeric literal rather than specifying the title of the library file in parts. This is an
alternative format to the text-name-1 OF library-name-1 ON family-name format.
FROM sequence-number-1

The FROM phrase causes copying to start at the sequence number specified in
sequence-number-1. If the THROUGH, THRU, or TO phrase is not specified, copying
continues to the end of the file.
THROUGH
THRU
TO
sequence-number-2

THROUGH, THRU, and TO are interchangeable. If this phrase is specified, copying
continues until the sequence number specified in sequence-number-2 has been copied.
pseudo-text-1 This is a sequence of text words beginning and ending with two

consecutive equal signs (==). Allowable separators within the pseudotext are commas,
semicolons, and spaces. A nonnumeric literal can contain quotation marks. Debugging
lines and comment lines are permitted within pseudo-text.
Pseudo-text-1 must contain one or more text words.
Pseudo-text-1 must not be null or consist only of commas, semicolons, and spaces.
If pseudo-text-1 is a PICTURE character-string, it must be preceded by the word
PICTURE or PIC.

8600 1518–307

6–81

COPY Statement

pseudo-text-2

This can contain zero, one, or more text words.
Pseudo-text-2 can be null.
Character-strings within pseudo-text-1 and pseudo-text-2 can be continued. However,
both characters of a pseudo-text delimiter must be on the same line.
identifier-1
identifier-2

Each identifier is a syntactically correct combination of a data-name and its qualifiers,
subscripts, and reference modifiers.
literal-3
literal-4

These literals can be any numeric, nonnumeric, or national literal.
Note: See “How the Copy Is Made,” later in this subsection (Copy Statement) for more
details.
word-1
word-2

These words can be any single COBOL word, including COBOL reserved words, except
COPY.
; (Semicolon)
The semicolon that follows the ending period can be used to control the behavior of
compiler control records (CCRs) and the format of listings. This semicolon should always
be separated from the ending period of the COPY statement by at least one space.
If a CCR immediately follows a COPY statement, the compiler option changes might
occur before the compiler processes the included source information. This situation can
be avoided by using the semicolon after the ending period. The semicolon ensures that
the compiler processes the included source information before the option changes.
When a compilation listing is produced, a comment immediately following a COPY
statement might be printed after the COPY statement but before the information
included as a result of the COPY statement. If a semicolon is placed after the ending
period, but before the comment entry, the comment is printed after the included source
information.

6–82

8600 1518–307

COPY Statement

Use the optional semicolon with caution. In some cases, the compiler may recognize the
optional semicolon. In other cases, the compiler may prohibit the use semicolon. In the
latter cases, the7 semicolon may not produce the desired listing format and may even
produce syntax errors. In such cases, use the semicolon as a tool in determining whether
errors can be eliminated.
In general, the semicolon can produce undesirable listing formats in the following cases:

•

Multiple COPY statements follow each other with no intervening syntax.

•

COPY statements have semicolons.

•

The last element in the library that is the subject of a COPY statement is a PICTURE
string that ends with one or more 9s followed by a period terminating the DATA
declaration.

If the last statement of a COBOL85 program is a COPY statement, do not use a
semicolon with that statement. The last syntax element of a COBOL85 program must
always be a period that terminates the last statement or paragraph-name of the program.

Details
The COPY statement must be preceded by a separator and ended by a period. The use
of a separator other than a space immediately before a COPY statement is a Unisys
extension to the COBOL language. To comply with language standards, at least one
space must be used as a separator immediately before a COPY statement.
COPY is a compiler-directing statement that indicates to the compiler that text will be
incorporated into a COBOL source program from another saved program. However,
actual inserted text appears only on the compilation listing.
Compiling a source program that contains COPY statements is logically equivalent to
processing all COPY statements before processing the resultant source program.
A COPY statement can be specified in a source program wherever a character-string or
separator (other than the closing quotation mark) can occur. However, a COPY statement
must not occur within a COPY statement.
If the word COPY appears in a comment-entry or in the place where a comment-entry
can appear, it is considered part of the comment-entry. In COBOL ANSI-85, the
comment-entry is an obsolete entry and will be deleted from the next revision of
standard COBOL.
A text word in pseudo-text and in library text can be from 1 through 322 characters long.
Library-name, text-name-1, and family-name can be user-defined words as well as
reserved words or unsigned integers.
A COPY library may be an optional file. If, during compilation, the COPY file is not found,
the compilation will stop and a message will appear on the ODT. The Optional File (?OF)
system command can be used to continue the compilation without the COPY library.

8600 1518–307

6–83

COPY Statement

How the Copy Is Made
When a COPY statement is executed, the library text associated with text-name-1 is
copied into the source program. Logically, this replaces the entire COPY statement. The
replacement begins with the reserved word COPY and ends with the punctuation
character period (.).
If the REPLACING phrase is not specified, the library text is copied unchanged.
If the REPLACING phrase is specified, each properly matched occurrence of pseudo-text1, identifier-1, word-1, and literal-3 in the library text is replaced by the corresponding
pseudo-text-2, identifier-2, word-2, or literal-4.
For purposes of matching, identifier-1, word-1, and literal-3 are treated as pseudo-text
containing only identifier-1, word-1, or literal-3, respectively.
The comparison to determine text replacement occurs as follows:
1. The first word used for comparison is the leftmost library text word that is not a
separator comma or a separator semicolon. Any text word or space that precedes
this text word is copied into the source program.
The entire REPLACING phrase operand that precedes the reserved word BY is
compared to an equivalent number of contiguous library text words. The comparison
starts with the first text word of the library and the first pseudo-text-1, identifier-1,
word-1, or literal-3 that was specified in the REPLACING phrase.
2. Pseudo-text-1, identifier-1, word-1, or literal-3 match the library text if the ordered
sequence of text words that forms the replacing phrase operand equals, character
for character, the ordered sequence of library text words.
For matching, each occurrence of a separator comma, semicolon, or space in
pseudo-text-1 or in the library text is treated as a single space. Each sequence of one
or more space separators is treated as a single space.
3. If a match does not occur, the comparison is repeated with each successive pseudotext-1, identifier-1, word-1, or literal-3, in the REPLACING phrase until either a match
is found or a successive REPLACING phrase operand is not found.
4. When all the REPLACING phrase operands have been compared and a match has
not occurred, the leftmost library text word is copied into the source program. The
next library text word is then considered the leftmost library text word, and the
comparison cycle starts again with the first pseudo-text-1, identifier-1, word-1, or
literal-3 specified in the REPLACING phrase.
5. Whenever a match occurs between pseudo-text-1, identifier-1, word-1, or literal-3
and the library text, the corresponding pseudo-text-2, identifier-2, word-2, or literal-4
is placed into the source program.
The library text word immediately following the rightmost text word that participated
in the match is then considered to be the leftmost text word. The comparison cycle
starts again with the first pseudo-text-1, identifier-1, word-1, or literal-3 specified in
the REPLACING phrase.

6–84

8600 1518–307

COPY Statement

6. The comparison operation continues until the rightmost text word in the library text
has either participated in a match or has been considered as a leftmost library text
word and has participated in a complete comparison cycle.
Comment Lines and Blank Lines
Comment lines or blank lines that occur in the library text and in pseudo-text-1 are
ignored for purposes of matching. The sequence of text words in the library text, if any,
and in pseudo-text-1 is determined by the rules for reference format. Refer to
“Reference Format” in Section 1 for more information.
Comment lines or blank lines that appear in pseudo-text-2 are copied into the resultant
program.
Comment lines or blank lines that appear in library text are copied into the resultant
source program and are unchanged with the following exception: a comment line or a
blank line in library text is not copied if it appears within the sequence of text words that
matches pseudo-text-1.
Debugging Lines
Debugging lines are permitted within library text and pseudo-text. Text words within a
debugging line participate in the matching rules as if the “D” did not appear in the
indicator area. A debugging line is specified within pseudo-text if the debugging line
begins in the source program after the opening pseudo-text-delimiter but before the
matching closing pseudo-text-delimiter.
Continuation of Lines and Additional Lines
Each text word that is copied from the library but not replaced is copied so it will start in
the same area of the line in the resultant program as it begins in the line within the
library. This is true except in the following situation. A text word that is copied from the
library begins in area A but follows another text word that also begins in area A of the
same line. If a preceding text word in the line is replaced by text of greater length, the
following text word begins in area B if it cannot begin in area A.
When either the $ANSI or $ANSICLASS compiler control option is set, the first text word
of pseudo-text-2 begins in the same area of the resultant program as it appears in
pseudo-text-2. Otherwise, the first text word of pseudo-text-2 begins in the same area of
the resultant program as the leftmost library text word that participated in the match
would appear if it had not been replaced.

8600 1518–307

6–85

COPY Statement

Each text word in pseudo-text-2 that will be placed into the resultant program begins in
the same area of the resultant program as it appears in pseudo-text-2. Each identifier-2,
literal-2, and word-2 that will be placed into the resultant program begins in the same
area of the resultant program as the leftmost library text word that participated in the
match would appear if it had not been replaced.
Library text must conform to the rules for COBOL reference format. Refer to “Reference
Format” in Section 1 for more information.
If additional lines are introduced into the source program as a result of a COPY
statement, each text word introduced appears on a debugging line if the COPY
statement begins on a debugging line or if the text word being introduced appears on a
debugging line in library text.
When a text word specified in the BY phrase is introduced, it appears on a debugging line
if the first library text word being replaced is specified on a debugging line. Except in the
preceding cases, only those text words that are specified on debugging lines where the
debugging line is within pseudo-text-2 appear on debugging lines in the resultant
program.
If a literal is specified as literal-4 or within pseudo-text-2 or if library text exceeds a single
line without continuation to another line in the resultant program and the literal is not
being placed on a debugging line, additional continuation lines are introduced that contain
the remainder of the literal.
If replacement requires that the continued literal be continued on a debugging line, an
error will result.
For compilation, text words after replacement are placed in the source program
according to the rules for reference format. When copying text words of pseudo-text-2
into the source program, additional spaces can be introduced only between text words
where there already exists a space (including the assumed space between source lines).
If additional lines are introduced into the source program as a result of processing COPY
statements, the indicator area of the introduced line will contain the same character as
the line on which the text being replaced begins. However, if that line contains a hyphen,
the introduced line will contain a space. If a literal is continued onto an introduced line
that is not a debugging line, a hyphen is placed in the indicator area.
Syntax Checking
The syntactic correctness of the library text cannot be independently determined. Except
for COPY and REPLACE statements, the syntactic correctness of the entire COBOL
source program cannot be determined until all COPY and REPLACE statements have
been completely processed.
When COPY . . . REPLACING a library file, if the library file contains a REPLACE
statement, character strings within the pseudo-text of the REPLACE statement will not
be affected.

6–86

8600 1518–307

COPY Statement

If replacement of a PICTURE string is required, then the word PICTURE (or PIC) must
precede the string to be replaced within pseudo-text-1.
In the event that an occurrence of a particular pseudo-text-1, identifier-1, literal-3, or
word-1 is not found in the library file, a warning is issued. The warning shows the item
that was not replaced.

Examples
COPY STANDARD-RECOVERY-ROUTINE OF ERRORS ON USER1
FROM 200 THRU 1000
REPLACING "Item-1" BY "Pay-Field".
This copies lines 200 to 1000 of the text STANDARD-RECOVERY-ROUTINE from the
library known as ERRORS, replacing the literal “Item-1” with another literal “Pay-Field”.
COPY FILE-DESCRIPTION REPLACING F-REC BY NEW-REC,
==VALUE OF FILENAME IS "NEWFIL"==
BY ==VALUE OF BLOCKSIZE IS 200==.
This copies all of the text associated with FILE-DESCRIPTION and inserts it into the
source file at the point where this COPY statement appears. Whenever the name F-REC
is encountered, it is replaced by the new name called NEW-REC. Also, the pseudo-text
string VALUE OF FILENAME IS “NEWFIL” is replaced by a new pseudo-text string
VALUE OF BLOCKSIZE IS 200.

8600 1518–307

6–87

DEALLOCATE Statement

DEALLOCATE Statement
The DEALLOCATE statement deallocates the storage of record areas.

DEALLOCATE
ïïïïïïïïïï

record name

The record–name must be a 01-level item.
A record-name described without a RECORD AREA clause does not need to be specified
in a DEALLOCATE statement since normal the normal system overlay releases the area
of memory used.
The record–name specified must not have a usage of EVENT, LOCK, CONTROL–POINT,
TASK, or BINARY.

6–88

8600 1518–307

DELETE Statement

DELETE Statement
The DELETE statement removes a logical record from a relative file or an indexed file.
Refer to the discussion of the RECORD CONTAINS clause under “File Section” in
Section 4 for more information.
For information on open mode, refer to “OPEN Statement” in Section 7. Also refer to
“READ Statement” in Section 7 and “USE Statement” in Section 8 for detailed
information and syntax.
For information on file organization and file access modes, refer to Section 12.
This statement is partially supported in the TADS environment. Applicable exclusions are
noted in this section.

DELETE file-name-1 RECORD
ïïïïïï
[ INVALID KEY imperative-statement-1 ]
ïïïïïïï
[ NOT INVALID KEY imperative-statement-2 ]
ïïï ïïïïïïï
[ END-DELETE ]
ïïïïïïïïïï
This format is supported in the TADS environment.

Explanation
file-name-1

The file referred to by file-name-1 must be a mass storage file and must be open in the
I/O mode when the DELETE statement is executed. The I/O mode is used for retrieving
and updating records.
INVALID KEY imperative-statement-1

If the file does not have the record indicated by the key, imperative-statement-1 will be
executed.
The INVALID KEY or NOT INVALID KEY phrases can be used if file-name-1 refers to a file
in random or dynamic access mode. These phrases cannot be used if file-name-1 refers
to a file in sequential access mode.
The INVALID KEY phrase must be specified for a DELETE statement if the file referred to
in the DELETE statement does not contain a USE AFTER STANDARD EXCEPTION
procedure.

8600 1518–307

6–89

DELETE Statement

NOT INVALID KEY imperative-statement-2

If the file has the record indicated by the key, the record is deleted and imperativestatement-2 is executed.
END-DELETEThis phrase delimits the scope of the DELETE statement.

Details
After the successful execution of a DELETE statement, the identified record is logically
removed from the file and cannot be accessed.
For a file in the sequential access mode, the last input-output statement executed for
file-name-1, before the execution of the DELETE statement, must have been a
successfully executed READ statement. The disk or disk pack logically removes from the
file the record that was accessed by that READ statement.
For a relative file in random or dynamic access mode, the disk or disk pack logically
removes from the file the record identified by the relative key data item associated with
file-name-1.
For an indexed file in random or dynamic access mode, the disk or disk pack logically
removes from the file the record identified by the prime record key data item associated
with file-name-1.
The invalid key condition occurs if the relative or indexed file does not contain the record
specified by the key.
Execution of the DELETE statement updates the value of the I/O status associated with
file-name-1.
The execution of a DELETE statement does not affect the content of the record area or
the content of the data item referenced by the data-name specified in the DEPENDINGON phrase of the RECORD clause associated with file-name-1. (The RECORD clause is
part of the file description entry for file-name-1.)
The file position indicator is not affected by the execution of a DELETE statement.
TADS
Any USE procedure is not executed when a DELETE statement that is compiled and
executed in a TADS session fails.

6–90

8600 1518–307

DELETE Statement

Example
ENVIRONMENT DIVISION.
.
.
.
FILE-CONTROL.
SELECT MSTFIL ASSIGN TO DISK
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS SOC-SEC-NO
.
.
.
PROCEDURE DIVISION.
.
.
.
READ MSTFIL RECORD INTO IN-RECORD
KEY IS SOC-SEC-NO
INVALID KEY PERFORM INVALID-PROC.
DELETE MSTFIL RECORD
INVALID KEY PERFORM NO-REC-PROC
NOT INVALID KEY PERFORM PROC-4
END-DELETE.

This program first reads the indexed file MSTFIL. If the key is invalid, the statements in
INVALID-PROC are executed. If the record is found, then the record identified by the
prime record key data item SOC-SEC-NO is logically deleted from the file, and the
statements in PROC-4 are executed.
If the record is not found, an invalid key condition exists, and the statements in NO-RECPROC are executed.

8600 1518–307

6–91

DETACH Statement

DETACH Statement
The DETACH statement dissociates a procedure from a task variable or an event.

Format

Use

Format 1

This format dissociates one or more processes from their
corresponding task variables. This statement dissociates only
those task variables that have been implicitly attached in CALL,
PROCESS, or RUN statements.

Format 2

This format dissociates interrupt procedures from an event.

Format 1: Detaching from a Task Variable
DETACH task-variable-1 [ ,task-variable-2 ] . . .
ïïïïïï

Explanation
task-variable-1
[task-variable-2] . . .

These are the task variables from which you want to dissociate the processes.

Details
For the DETACH statement to be valid, the task variable must have been previously
attached to the process by the execution of a CALL, PROCESS, or RUN statement.
The successful execution of the DETACH statement terminates the processes
associated with the specified task variables by setting the STATUS attributes of the
processes to TERMINATED. Once the processes are terminated, they are no longer
associated with the task variables.
Note that the program that contained the DETACH statement continues to execute
asynchronously while the detachment is performed. Thus, before using a detached task
variable in a subsequent CALL, PROCESS, or RUN statement, you should verify that the
STATUS attribute of the process to which it was attached has a value of TERMINATED.
You can check the value of an attribute by using the attribute in an IF statement. The IF
statement is described later in this section.

Example
DETACH INTERRUPT-PROCEDURE-ONE

6–92

8600 1518–307

DETACH Statement

Format 2: Detaching from an Event
DETACH section-name-1 [ ,section-name-2 ] . . .
ïïïïïï

section-name-1 [, section-name-2] . . .

This is the name of one or more sections that contain the processes that you want to
dissociate from the event. The section-name must be declared in the Declaratives
Section with a USE AS INTERRUPT clause.

Details
Execution of a DETACH section-name statement severs the association of an interrupt
procedure with its currently attached event. Executions of the interrupt procedure which
might have been queued at the time of the detachment do not occur.
Note that performing the DETACH statement for an interrupt procedure that is not
attached to an event does not cause an error.
The DETACH statement has no effect on the allowed or disallowed condition of an
interrupt procedure.
For additional information, refer to the ALLOW, ATTACH, CAUSE, and DISALLOW
statements described in this section.

Example
DETACH INTERRUPT-PROCEDURE-ONE

8600 1518–307

6–93

DISALLOW Statement

DISALLOW Statement
The DISALLOW statement prevents an interrupt procedure from being executed when
its associated event is activated by a CAUSE statement.

DISALLOW
ïïïïïïïï

ä section-name-1 [ ,section-name-2 ] . . . å
ã
â
æ INTERRUPT
ç
ïïïïïïïïï

Explanation
section-name-1 [, section-name-2] . . .

This syntax causes specific interrupt procedures to be queued when their attached
events are activated. Subsequent execution of an ALLOW section-name statement
causes the queued procedures to be executed immediately, unless the general
DISALLOW INTERRUPT statement is in effect. In this case, the procedures remain
queued until the general ALLOW INTERRUPT statement is executed.
Section-name indicates the section in the Procedure Division that contains the specific
interrupt procedure that you want to prevent from executing. You can use multiple
section names to specify multiple interrupt procedures.
INTERRUPT

The DISALLOW INTERRUPT statement causes all interrupt procedures to be queued
when their attached events are activated. Subsequent execution of an ALLOW
INTERRUPT statement causes the queued procedures to be executed immediately.
Note that a procedure restricted by a DISALLOW section-name statement remains
queued until an ALLOW section-name statement is executed for it.

Example
DISALLOW INTERRUPT.
DISALLOW INTERRUPT-PROCEDURE-ONE.

6–94

8600 1518–307

DISPLAY Statement

DISPLAY Statement
The DISPLAY statement causes low-volume data to be transferred to an operator display
terminal (ODT).
The TADS environment fully supports the DISPLAY statement. Additionally, it provides
the ITEMS, GROUP ITEMS, ELEMENTARY ITEMS, GROUPS, HEX, EBCDIC, and
DECIMAL clauses.

DISPLAY
ïïïïïïï

ä identifier-1
³
ã literal-1
³
æ ATTRIBUTE attribute-name-1 OF identifier-2
ïïïïïïïïï
ïï

[ UPON mnemonic-name-1 ]
ïïïï

å
³
â . . .
³
ç

[ WITH NO ADVANCING ]
ïï ïïïïïïïïï

Explanation
identifier-1

This identifier references a data-item to be displayed. Identifier-1 cannot reference a long
numeric data item.
If identifier-1 is a table, the number of subscripts must equal the number required by the
table item. In a COBOL85 TADS session, the subscripts are optional.
literal-1

Literal-1 specifies a literal to be displayed.
If the literal is a figurative constant, only a single occurrence of the figurative constant is
displayed. The figurative constant [ALL] literal is allowed. If [ALL] literal is used, the ALL
is ignored and the literal is displayed once.
The literal cannot be a long numeric literal.
attribute-name-1
identifier-2

Attribute-name-1 is a file, library, or task attribute. Identifier-2 must be the proper type to
match attribute-name-1. For example, if attribute-name-1 is a file attribute, then identifier2 must be a file.

8600 1518–307

6–95

DISPLAY Statement

UPON mnemonic-name-1

The data-item mnemonic-name-1 is the name of a mnemonic associated with a hardware
device defined in the SPECIAL-NAMES paragraph of the Environment Division.
Mnemonic-name-1 must be associated with the hardware-name ODT.
If the UPON phrase is not used, the device used is the ODT.
WITH NO ADVANCING

This optional phrase does not reset the hardware device to the next line or change it in
any other way following the display of the last operand.
If the hardware device can be positioned to a specific character position, the device will
remain at that character position immediately following the last character of the last
operand displayed.
If you do not specify the WITH NO ADVANCING phrase, then the positioning of the
hardware device will be reset to the leftmost position of the next line of the device after
the last operand has been transferred.

Details
The DISPLAY statement transfers the content of each operand to the hardware device in
the order listed. Any conversion of data required between a literal or the data item
referred to by the identifier and the hardware device is defined by the implementor. If
the hardware device is capable of receiving both national characters and alphanumeric
characters, figurative constants, except for the ALL national literal, are displayed as
alphanumeric characters.
The data item is transferred if the hardware device can receive data of the same size as
the data item being transferred. The maximum size of a data transfer to the ODT is 430
characters.
If the hardware device cannot receive data of the same size as the data item being
transferred, then one of the following applies:

•

If the size of the data item being transferred exceeds the size that the hardware
device can receive in a single transfer, the data beginning with the leftmost character
is stored and aligned to the left in the receiving hardware device. Any remaining data
is then transferred in like fashion, until all data is transferred. This process appears as
if multiple executions of the DISPLAY statement have occurred.

•

If the size of the data item that the hardware device can receive exceeds the size of
the data being transferred, the transferred data is stored and aligned to the left in the
receiving hardware device.

When a DISPLAY statement contains more than one operand, the size of the sending
item is the sum of the sizes associated with the operands. The values of the operands
are transferred in the sequence in which the operands are encountered without
modifying the positioning of the hardware device between the successive operands.

6–96

8600 1518–307

DISPLAY Statement

Data within the current file record can be displayed from COBOL85 TADS. The TITLE,
KIND, and OPEN attributes are displayed automatically for files. If the OPEN attribute is
TRUE, then the STATE and NEXTRECORD attributes are also displayed automatically. In
addition, a user can request the display of other file attributes.

Examples
DISPLAY OCCUPATION
This displays the contents of the data item OCCUPATION on the ODT.
IDENTIFICATION DIVISION.
PROGRAM-ID. DISPLAY-VERB.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
ODT IS MODT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 OCCUPATION
PIC X(20).
PROCEDURE DIVISION.
DISPLAY-PARA.
MOVE "THIS IS A TEST CASE"TO OCCUPATION.
DISPLAY OCCUPATION.
DISPLAY "PROCEDURE-1 COMPLETED" UPON MODT WITH NO ADVANCING.
DISPLAY "PROCEDURE-2 COMPLETED".
STOP RUN.
This example displays the contents of the data-item OCCUPATION and, after advancing
one line, the literal “Procedure-1 completed”, and, without advancing to another line, the
literal “Procedure-2 completed”.

8600 1518–307

6–97

DIVIDE Statement

DIVIDE Statement
The DIVIDE statement divides a numeric operand into another operand and stores the
quotient and the remainder.
This statement is partially supported in the TADS environment. Supported syntax is
noted in this section.

Format

6–98

Use

Format 1

The DIVIDE . . . INTO format enables you to divide a numeric operand
into another numeric operand and to store the result in the second
operand.

Format 2

The DIVIDE . . . INTO . . . GIVING format enables you to divide a
numeric operand into another numeric operand and to specify a place
to store the result.

Format 3

The DIVIDE . . . BY . . . GIVING format enables you to divide a numeric
operand by another numeric operand and to specify a place to store
the result.

Format 4

The DIVIDE . . . INTO . . . GIVING . . . REMAINDER format enables you
to divide a numeric operand into another numeric operand and to
specify a place to store the result and the remainder.

Format 5

The DIVIDE . . . BY . . . GIVING . . . REMAINDER format enables you to
divide a numeric operand by another numeric operand and to specify a
place to store the result and the remainder.

8600 1518–307

DIVIDE Statement

Format 1: DIVIDE . . . INTO
DIVIDE
ïïïïïï

ä identifier-1 å
ã
â INTO identifier-2
æ literal-1
ç ïïïï

[ [ , ]

[ ROUNDED ]
ïïïïïïï

identifier-3

[ ROUNDED ] ] . . .
ïïïïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-DIVIDE ]
ïïïïïïïïïï

TADS Syntax

DIVIDE
ïïïïïï

ä identifier-1 å
ã
â INTO identifier-2
æ literal-1
ç ïïïï

[ [ , ]

identifier-3

[ ROUNDED ]
ïïïïïïï

] . . .

[ END-DIVIDE ]
ïïïïïïïïïï

Explanation
identifier-1
literal-1
identifier-2
identifier-3

Each identifier must refer to an elementary numeric item.
Literal-1 must be a numeric literal.
During execution, the value of the data item referenced by identifier-1 or literal-1 is stored
in a temporary data item. The value in this temporary data item is then divided into the
value of the data item referenced by identifier-2.
The value of the dividend (that is, the value of the data item referenced by identifier-2) is
replaced by this quotient. Similarly, the temporary data item is divided into each
successive occurrence of identifier-3, and so on.
The composite value of operands is a hypothetical data item that results from the
superimposition of all receiving data items of a given statement aligned on their decimal
points. The composite must not contain more than 23 digits.

8600 1518–307

6–99

DIVIDE Statement

INTO

This keyword specifies that identifier-1 or literal-1 will be divided into identifier-2.
ROUNDED

This option increases the absolute value of the quotient by adding 1 to the quotient's
low-order digit. This occurs whenever the absolute value of the most significant digit of
the excess is greater than or equal to 5.
Refer to “ROUNDED Phrase” in Section 5 for more information.
ON SIZE ERROR
imperative-statement-1If a size error condition occurs and this phrase is specified,

imperative-statement-1 is executed.
Refer to “SIZE ERROR Phrase” in Section 5 for more information.
NOT ON SIZE ERROR
imperative-statement-2

If a size error condition does not occur and this phrase is specified, imperative-statement2 is executed.
END-DIVIDE

This phrase delimits the scope of the DIVIDE statement.

Example
DIVIDE .25 INTO Sale-Item ROUNDED
ON SIZE ERROR PERFORM Para-6
NOT ON SIZE ERROR PERFORM Write-Para
END-DIVIDE.
The literal .25 is divided into the value of Sale-Item. Then, the quotient is rounded, if
necessary, and stored in Sale-Item. If a size error condition occurs, the statements in
Para-6 are executed. If a size error condition does not occur, the statements in
Write-Para are executed.

6–100

8600 1518–307

DIVIDE Statement

Format 2: DIVIDE . . . INTO . . . GIVING
DIVIDE
ïïïïïï

ä identifier-1 å
ã
â INTO
æ literal-1
ç ïïïï

ä identifier-2 å
ã
â
æ literal-2
ç

GIVING identifier-3 [ ROUNDED ]
ïïïïïï
ïïïïïïï
[ [ , ] identifier-4 [ ROUNDED ] ] . . .
ïïïïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-DIVIDE ]
ïïïïïïïïïï

TADS Syntax

DIVIDE
ïïïïïï

ä identifier-1 å
ã
â INTO
æ literal-1
ç ïïïï

ä identifier-2 å
ã
â
æ literal-2
ç

GIVING identifier-3 [ ROUNDED ]
ïïïïïï
ïïïïïïï
[ [ , ] identifier-4 [ ROUNDED ]
ïïïïïïï
[ END-DIVIDE ]
ïïïïïïïïïï

] . . .

Explanation
Refer to Format 1 for descriptions of the ON SIZE ERROR and NOT ON SIZE ERROR
phrases and the syntax elements INTO and END-DIVIDE.
identifier-1
literal-1
identifier-2
literal-2

Each identifier must refer to an elementary numeric item.
Each literal must be a numeric literal.
The value of the data item referenced by identifier-1 or literal-1 is divided into the value of
the data item referenced by identifier-2 or literal-2. The result is stored in each data item
referenced by identifier-3, identifier-4, and so on.

8600 1518–307

6–101

DIVIDE Statement

GIVING identifier-3
identifier-4

The GIVING phrase allows the quotient to be stored in the data item referenced by
identifier-3 and, if present, in the data items referenced by identifier-4 and so on. Each
identifier must refer to either an elementary numeric item or an elementary numericedited item.
ROUNDED

This option increases the absolute value of the quotient, which will be stored in identifier3, by adding 1 to its low-order digit. This occurs whenever the absolute value of the most
significant digit of the excess is greater than or equal to 5.
Refer to “ROUNDED Phrase” in Section 5 for more information.

Example
DIVIDE Discount INTO Item GIVING Sale-Price ROUNDED
ON SIZE ERROR PERFORM Err-Proc
NOT ON SIZE ERROR PERFORM Write-Report
END-DIVIDE.
This example divides the value of the identifier Discount into the value of the identifier
Item. The result is rounded, if necessary, and stored in the identifier Sale-Price. If a size
error condition occurs, the statements in Err-Proc are executed. If a size error condition
does not occur, the statements in Write-Report are executed.

6–102

8600 1518–307

DIVIDE Statement

Format 3: DIVIDE . . . BY . . . GIVING

DIVIDE
ïïïïïï

ä identifier-1 å
ã
â BY
æ literal-1
ç ïï

ä identifier-2 å
ã
â
æ literal-2
ç

TADS Syntax

DIVIDE
ïïïïïï

ä identifier-1 å
ã
â BY
æ literal-1
ç ïï

ä identifier-2 å
ã
â
æ literal-2
ç

GIVING identifier-3 [ ROUNDED ]
ïïïïïï
ïïïïïïï
[ [ , ] identifier-4 [ ROUNDED ]
ïïïïïïï
[ END-DIVIDE ]
ïïïïïïïïïï

] . . .

Explanation
Refer to Format 1 for a description of the ON SIZE ERROR and NOT ON SIZE ERROR
phrases and the syntax element END-DIVIDE. Refer to Format 2 for a description of the
GIVING and ROUNDED phrases.
identifier-1
literal-1
identifier-2
literal-2

Each identifier must refer to an elementary numeric item. Each literal must be a numeric
literal.
The value of the data item referenced by identifier-1 or literal-1 is divided by the value of
the data item referenced by identifier-2 or literal-2. The result is stored in each data item
referenced by identifier-3, identifier-4, and so forth.

8600 1518–307

6–103

DIVIDE Statement

This keyword indicates that identifier-1 or literal-1 will be divided by identifier-2 or literal-2.
GIVING identifier-3
identifier-4

Examples
DIVIDE Salary BY 52 GIVING Weekly-Salary ROUNDED
ON SIZE ERROR GO TO SIZE-ERR
NOT ON SIZE ERROR MOVE Weekly-Salary TO Print-Out
END-DIVIDE.
This divides the value of identifier Salary by the numeric literal 52. The result is rounded,
if necessary, and stored in Weekly-Salary. If a size error condition occurs, control passes
to the statements in SIZE-ERR. If a size error condition does not occur, the value of
Weekly-Salary is moved to the data item Print-Out.

6–104

8600 1518–307

DIVIDE Statement

Format 4: DIVIDE . . . INTO . . . GIVING . . . REMAINDER

DIVIDE
ïïïïïï

ä identifier-1 å
ã
â INTO
æ literal-1
ç ïïïï

ä identifier-2 å
ã
â
æ literal-2
ç

GIVING identifier-3 [ ROUNDED ]
ïïïïïï
ïïïïïïï
REMAINDER identifier-4
ïïïïïïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-DIVIDE ]
ïïïïïïïïïï

TADS Syntax

DIVIDE
ïïïïïï

ä identifier-1 å
ã
â INTO
æ literal-1
ç ïïïï

ä identifier-2 å
ã
â
æ literal-2
ç

GIVING identifier-3 [ ROUNDED ]
ïïïïïï
ïïïïïïï
REMAINDER identifier-4
ïïïïïïïïï
[ END-DIVIDE ]
ïïïïïïïïïï

Explanation
Refer to Format 1 for a description of the ON SIZE ERROR and NOT ON SIZE ERROR
phrases and the syntax elements INTO and END-DIVIDE.
Refer to Format 2 for a description of identifier-1, literal-1, identifier-2, literal-2,
identifier-3, and the GIVING and ROUNDED phrases.
REMAINDER
identifier-4

The REMAINDER phrase stores the remainder of a division operation in a data item.
Identifier-4 will contain the value of the remainder and must refer to either an elementary
numeric item or an elementary numeric-edited item.
If identifier-4 is subscripted, the subscript is evaluated after the quotient is stored in
identifier-3 and immediately before the remainder is stored in the data item referenced
by identifier-4.

8600 1518–307

6–105

DIVIDE Statement

Defining the Remainder
The remainder in COBOL is defined as the result of subtracting the product of the
quotient (identifier-3) and the divisor from the dividend. If identifier-3 is defined as a
numeric-edited item, the quotient used to calculate the remainder is an intermediate field
that contains the unedited quotient.If the ROUNDED phrase is specified in formats 4 and
5, the quotient used to calculate the remainder is an intermediate field that contains the
quotient of the DIVIDE statement. The quotient in the intermediate field is truncated
rather than rounded. This intermediate field is defined as a numeric field that contains the
same number of digits, the same decimal point location, and the same presence or
absence of a sign as the quotient (identifier-3).
Using the ON SIZE ERROR Phrase
When the ON SIZE ERROR phrase is used, the following rules apply:

•

If the size error occurs on the quotient, the remainder calculation is not valid. The
contents of the data items referenced by both identifier-3 and identifier-4 remain
unchanged.

•

If the size error occurs on the remainder, the content of the data item referenced by
identifier-4 remains unchanged.

You must recognize which situation has actually occurred. Refer to “SIZE ERROR
Phrase” in Section 5 for more information.

Example
DIVIDE Item-1 INTO Item-2 GIVING Item-3 ROUNDED REMAINDER Item-4
ON SIZE ERROR DISPLAY "Size error"
NOT ON SIZE ERROR MOVE Item-3 TO Item-5 MOVE Item-4 TO Item-6
END-DIVIDE.
In this example, Item-1 is divided into Item-2. The quotient and the remainder are
calculated. If necessary, the quotient is rounded and then stored in Item-3. The
remainder is stored in Item-4. If a size error condition occurs, the literal “Size error” is
displayed on the ODT. If a size error condition does not occur, the quotient (Item-3) is
moved to Item-5, and the remainder (Item-4) is moved to Item-6.

6–106

8600 1518–307

DIVIDE Statement

Format 5: DIVIDE . . . BY . . . GIVING . . . REMAINDER
DIVIDE
ïïïïïï

ä identifier-1 å
ã
â BY
æ literal-1
ç ïï

ä identifier-2 å
ã
â
æ literal-2
ç

TADS Syntax

DIVIDE
ïïïïïï

ä identifier-1 å
ã
â BY
æ literal-1
ç ïï

ä identifier-2 å
ã
â
æ literal-2
ç

GIVING identifier-3 [ ROUNDED ]
ïïïïïï
ïïïïïïï
REMAINDER identifier-4
[ END-DIVIDE ]
ïïïïïïïïïï

Explanation
Refer to Format 1 for descriptions of the ON SIZE ERROR and NOT ON SIZE ERROR
phrases and the syntax element END-DIVIDE.
Refer to Format 2 for a description of the GIVING and ROUNDED phrases.
Refer to Format 3 for a description of the BY phrase.
Refer to Format 4 for a description of the REMAINDER phrase and for the paragraphs
labeled “Defining the Remainder” and using the “ON SIZE ERROR Phrase.”
For a detailed discussion of arithmetic expressions, refer to Section 5. Also refer to
“Intermediate Data Item,” “ROUNDED Phrase,” and “SIZE ERROR Phrase” in Section 5
for additional information.

8600 1518–307

6–107

DIVIDE Statement

Example
DIVIDE Item-1 BY Item-2 GIVING Item-3 ROUNDED REMAINDER Item-4
ON SIZE ERROR DISPLAY "Size error"
NOT ON SIZE ERROR MOVE Item-3 TO Item-5 MOVE Item-4 TO Item-6
END-DIVIDE.
In this example, Item-1 is divided by Item-2. The quotient and remainder are calculated. If
necessary, the quotient is rounded and then stored in Item-3. The remainder is stored in
Item-4. If a size error condition occurs, the literal “Size error” is displayed on the ODT. If
a size error condition does not occur, the quotient (Item-3) is moved to Item-5, and the
remainder (Item-4) is moved to Item-6.

6–108

8600 1518–307

EVALUATE Statement

EVALUATE Statement
The EVALUATE statement causes multiple conditions to be evaluated: it tests one or
many subjects against corresponding multiple objects. Subsequent action of the object
program depends on the results of the evaluations.
The operands or the words TRUE and FALSE that appear before the first WHEN phrase
of the EVALUATE statement are referred to individually as selection subjects and
collectively as the set of selection subjects.
The operands or the words TRUE, FALSE, and ANY that appear in a WHEN phrase are
referred to individually as selection objects and collectively as the set of selection
objects.
For conceptual information about the different statements, sentences, and expressions,
and how they are evaluated, refer to “Types of Statements and Sentences,” “Arithmetic
Expressions,” and “Conditional Expressions” in Section 5.
Refer to “IF Statement” in this section for information on evaluating a condition.

8600 1518–307

6–109

EVALUATE Statement

EVALUATE
ïïïïïïïï

ä
ã
æ

ä
³
³
ã
³
³
æ

identifier-1
literal-1
expression-1
TRUE
ïïïï
FALSE
ïïïïï

å
³
³
â
³
³
ç

Ú
³
³
³
³
³
³
³
À

ALSO

ä
³
³
ã
³
³
æ

identifier-2
literal-2
expression-2
TRUE
ïïïï
FALSE
ïïïïï

å
³
³
â
³
³
ç

¿
³
³
³
³
³
³
³
Ù

. . .

ä
ã WHEN
æ

ä ANY
³ ïïï
³ condition-1
³
³ TRUE
ã ïïïï
³ FALSE
³ ïïïïï
³
ä ä identifier-3 å
³ [ NOT ] ã ã literal-3
â
æ
ïïï
æ æ arith-exp-1 ç

Ú
¿
³ ä THROUGH å ä identifier-4 å ³ å
³ ã ïïïïïïï â ã literal-4
â ³ â
³ æ THRU
ç æ arith-exp-2 ç ³ ç
À
ïïïï
Ù

å
³
³
³
³
â
³
³
³
³
ç

[ ALSO
ïïïï
ä
³ ANY
³ ïïï
³ condition-2
³
³ TRUE
³ ïïïï
ã FALSE
³ ïïïïï
³
³
³
ä ä identifier-5 å
³ [ NOT ] ã ã literal-5
â
æ
ïïï
æ æ arith-exp-3 ç

Ú
¿
³ ä THROUGH å ä identifier-6 å ³ å
³ ã ïïïïïïï â ã literal-6
â ³ â
³ æ THRU
ç æ arith-exp-4 ç ³ ç
À
ïïïï
Ù

å
³
³
³
³
³
³
â
³
³
³
³
³
ç

¿
³
³
³
³
³
³
³
³ ...
³
³
³
³
³
³
Ù

å
³
³
³
³
³
³
³
â ...
³
³
³
³
³
³
ç

å
imperative-statement-1 â . . .
ç
[ WHEN OTHER imperative-statement-2 ]
ïïïï ïïïïï
[ END-EVALUATE ]
ïïïïïïïïïïïï

6–110

8600 1518–307

EVALUATE Statement

Explanation
identifier-1
identifier-2

These identifiers are selection subjects and are user-defined words that refer to a data
item.
literal-1
literal-2

These numeric, nonnumeric, or national literals are selection subjects.
expression-1
expression-2

These selection subjects can be arithmetic or conditional expressions. Refer to
“Arithmetic Expressions” and “Conditional Expressions” in Section 5 for a description of
these expressions.
TRUE

This reserved word is a conditional constant.
If TRUE appears before the WHEN phrase, it is a selection subject. If TRUE appears in a
WHEN phrase, it is a selection object. The truth value of “TRUE” is assigned to those
items specified with the word TRUE.
FALSE

This reserved word is a conditional constant.
If FALSE appears before the WHEN phrase, it is a selection subject. If FALSE appears in
a WHEN phrase, it is a selection object. The truth value of “FALSE” is assigned to those
items specified with the word FALSE.
ALSO

If this keyword appears before the WHEN phrase, it separates selection subjects from
each other.
If ALSO appears in a WHEN phrase, it separates selection objects from each other.
The selection subjects or selection objects connected by ALSO form a selection set.

8600 1518–307

6–111

EVALUATE Statement

WHEN

Each WHEN phrase contains the selection objects. These objects are evaluated and
compared with the selection subjects.
The number of selection objects within each set of selection objects must match the
number of selection subjects.
When multiple WHEN phrases are used, each WHEN phrase, except the last, is ended
by the beginning of the next WHEN phrase. The final WHEN phrase can be ended by a
period or with the END-EVALUATE phrase.
If all the selection objects and the corresponding subjects match, imperative-statement-1
is executed. If they do not match, the next WHEN phrase is evaluated. Otherwise,
control passes to the next executable statement.
ANY

This reserved word can correspond to a selection subject of any type.
condition-1
condition-2

These conditional expressions are selection objects.
NOT

This option causes the selection object preceded by the keyword NOT to match the
selection subject if the value or range of values are different from those specified by the
selection object.
For example, the NOT in the statement EVALUATE A WHEN NOT 14 MOVE A TO B
causes A to be moved to B if A is any number other than 14.
identifier-3 through identifier-6
literal-3 through literal-6
arithmetic-expression-1 through arithmetic-expression-4

These elements are selection objects. The identifiers are user-defined words that refer to
data items. The literals are numeric, nonnumeric, or national. For information on valid
arithmetic expressions, refer to “Arithmetic Expressions” in Section 5.
THROUGH
THRU

These keywords can be used interchangeably. They connect two operands that
represent a range of values.
The operands connected by a THROUGH or THRU phrase form a single selection object
and must be of the same class.

6–112

8600 1518–307

EVALUATE Statement

imperative-statement-1

This imperative statement will be executed if the selection object matches the selection
subject. After this statement is executed, control passes to the next executable
statement after the EVALUATE statement.
WHEN OTHER
imperative-statement-2

This additional WHEN phrase provides a WHEN phrase that will be executed if none of
the selection objects specified in the other WHEN phrases match the selection subjects.
END-EVALUATE

This phrase delimits the scope of the EVALUATE statement.
Correspondence between Selection Objects and Subjects
The selection object and selection subject must be of the same category and capable of
matching.
Within a set of selection objects, each selection object must correspond to the selection
subject that has the same position within the set of selection subjects. The following
rules apply:

•

Identifiers, literals, or arithmetic expressions that appear in a selection object must
be valid operands for comparison to the corresponding operand in the set of
selection subjects.

•

Condition-1 or condition-2 and the words TRUE or FALSE, when used as selection
objects, must correspond to either a conditional expression or the words TRUE or
FALSE in the set of selection subjects.

•

The word ANY can correspond to a selection subject of any type.

8600 1518–307

6–113

EVALUATE Statement

How Values Are Determined for Selection Subjects and Objects
The execution of the EVALUATE statement operates as if each selection subject and
selection object were evaluated and assigned a numeric or nonnumeric value, a range of
numeric or nonnumeric values, or a truth value. These values are determined as shown
in the following table:

If the selection subject
is specified by . . .

And the selection object
is specified by . . .

Then the assigned
value is . . .

Identifier-1 or identifier-2

Identifier-3 or identifier-5
(without the NOT or
THROUGH phrase)

The value and class of
the data item referenced
by the identifier.

Literal-1 or literal-2

Literal-3 or literal-5
(without the NOT or
THROUGH phrase)

The value and class of
the specified literal.

Arithmetic-expression-1 or
arithmetic-expression-3
(without either the NOT or
the THROUGH phrases)

A numeric value
according to the rules for
evaluating an arithmetic
expression.

An arithmetic expression
for expression-1 or
expression-2

If literal-3 or literal-5 is
the figurative constant
ZERO, the literal is
assigned the class of the
corresponding selection
subject.

Refer to “Arithmetic
Expressions” in Section
5 for more information.
A conditional expression
for expression-1 or
expression-2

Condition-1 or condition-2

A truth value that
adheres to the rules for
evaluating conditional
expressions.
Refer to “Conditional
Expressions” in Section
5 for more information.

The words TRUE or
FALSE

6–114

The words TRUE or
FALSE

A truth value (a value of
TRUE for TRUE and
FALSE for FALSE).

The word ANY

Not evaluated further.

The THROUGH phrase
(without the NOT
phrase)

A range of values that
includes all permissible
values of the selection
subject that are greater
than or equal to the first
operand and less than or
equal to the second
operand.

8600 1518–307

EVALUATE Statement

If the selection subject
is specified by . . .

And the selection object
is specified by . . .

Then the assigned
value is . . .

The NOT phrase

The set of all permissible
values of the selection
subject not equal to the
value, or not included in
the range of values, that
would have been
assigned to the item had
the NOT phrase been left
unspecified.

Comparison of Values
Execution of the EVALUATE statement proceeds as if the values assigned to the
selection subjects and selection objects were compared to determine if any WHEN
phrase satisfies the set of selection subjects. This comparison proceeds as follows:
1. Each selection object within the set of selection objects for the first WHEN phrase is
compared to the selection subject that has the same ordinal position in the set of
selection subjects. One of the conditions shown in the following table must be
satisfied for the comparison to result in a match.

Item Being Compared

How the Item Satisfies the Comparison

Numeric or nonnumeric values

If one value, or a range of values, of the
selection object equals the value of the
selection subject

Truth values

If the items are assigned identical truth values

ANY

Always satisfies a comparison, regardless of
the value of the selection subject

2. If the above comparison is satisfied for every selection object within the set of
compared selection objects, the WHEN phrase that contains the set of selection
objects satisfies the set of selection subjects.
3. If the above comparison is not satisfied for one or more selection objects within the
set of compared selection objects, that set of selection objects does not satisfy the
set of selection subjects.
4. This procedure is repeated for subsequent sets of selection objects, in the order of
their appearance in the source program, until either a WHEN phrase satisfies the set
of selection subjects or all sets of selection objects have been compared.

8600 1518–307

6–115

EVALUATE Statement

Completion of the EVALUATE Statement
After the comparison described in the preceding step is completed, execution of the
EVALUATE statement proceeds as follows:

•

If a WHEN phrase is selected, execution continues with the first
imperative-statement-1 following the selected WHEN phrase. The use of multiple
WHEN phrases with an imperative-statement is treated as a set of consecutive OR
conditions.

•

If a WHEN phrase is selected and a WHEN OTHER phrase is specified, exection
continues with imperative-statement-2.

•

The scope of execution of the EVALUATE statement is terminated when execution
reaches either the end of imperative-statement-1 of the selected WHEN phrase or
the end of imperative-statement-2, or when no WHEN phrase is selected and no
WHEN OTHER phrase is specified.

Examples
EVALUATE Days-Overdue
WHEN 0 THROUGH 30 PERFORM Standard-Bill
WHEN 31 THROUGH 60 PERFORM Notice1
WHEN 61 THROUGH 90 PERFORM Notice2
WHEN OTHER PERFORM Collections-Report
END-EVALUATE.
This example is explained in the following table:

If the identifier Days-Overdue
has a value that is . . .

Then the statements in . . .
are executed.

0 to 30

Standard-Bill

31 to 60

Notice1

61 to 90

Notice2

Different from the other entries in this table

Collections-Report

EVALUATE TRUE ALSO Employee-Only =
WHEN Medical-Option = 1 ALSO TRUE
WHEN Medical-Option = 2 ALSO TRUE
WHEN Medical-Option = 3 ALSO TRUE
END-EVALUATE.

6–116

"Y"
MOVE Name TO Report-1-Name
MOVE Name TO Report-2-Name
MOVE Name TO Report-3-Name

8600 1518–307

EVALUATE Statement

This example is explained in the following table.

If the Medical-Option
has a value of . . .

And Employee-Only
has a value of . . .

Then the value of
Name is moved to . . .

Report-1-Name

Report-2-Name

Report-3-Name

The following examples produce the same result.
EVALUATE Medical-Option
WHEN 1 ALSO TRUE MOVE
WHEN 2 ALSO TRUE MOVE
WHEN 3 ALSO TRUE MOVE
END-EVALUATE.

ALSO
Name
Name
Name

Employee-Only = "Y"
TO Report-1-Name
TO Report-2-Name
TO Report-3-Name

EVALUATE TRUE
WHEN Medical-Option = 1 AND Employee-Only = "Y" MOVE Name TO Report-1-Name
WHEN Medical-Option = 2 AND Employee-Only = "Y" MOVE Name TO Report-2-Name
WHEN Medical-Option = 3 AND Employee-Only = "Y" MOVE Name TO Report-3-Name
END-EVALUATE.
These examples are explained in the following table.

If the Medical-Option
has a value of . . .

8600 1518–307

And Employee-Only
has a value of . . .

Then the value of
Name is moved to . . .

Report-1-Name

Report-2-Name

Report-3-Name

6–117

EVALUATE Statement

The following example illustrates the use of multiple WHEN phrases:

*
*

6–118

EVALUATE WS-FIELD
Multiple WHEN phrases for one imperative-statement are ORed
to form the selection object.
WHEN 1
WHEN 2
True when WS-FIELD = 1 or 2.
DISPLAY "VALUE IS 2"
WHEN 3
DISPLAY "VALUE IS 3"
END-EVALUATE.
This produces the same result as the preceding EVALUATE.
EVALUATE TRUE
WHEN WS-FIELD = 1 OR 2
DISPLAY "VALUE IS 2"
WHEN WS-FIELD = 3
DISPLAY "VALUE IS 3"
END-EVALUATE.

8600 1518–307

EXIT Statement

EXIT Statement
Format

Use

Format 1

This format indicates the logical end of a series of sections or
paragraphs referenced by a PERFORM statement.

Format 2

This format exits a program that was called by Format 1 or Format 2 of
the CALL statement.

Format 3

This format exits a bound procedure that was called by Format 4 of the
CALL statement.

Format 4

This format exits a task that was initiated by Format 6 of the CALL
statement.

Format 5

This format exits a bound procedure that was called by a CALL
MODULE statement (Format 6 of the CALL statement).

Format 6

This format provides a way to bypass the remainder of a PERFORM
statement range.

Format 1: EXIT from an Out-of-Line PERFORM
EXIT

Explanation
EXIT

The EXIT statement must appear in a sentence by itself. It must be the only sentence in
the paragraph.

Details
An EXIT statement assigns a procedure-name to a given point in a program. The EXIT
statement has no other effect on the compilation or execution of the program.

8600 1518–307

6–119

EXIT Statement

Example
Main-Para.
.
.
.
PERFORM Read-Para THRU Exit-Para
UNTIL In-Record = "NO".
.
.
.
Read-Para.
READ INFILE AT END MOVE "NO" TO In-Record
GO TO Total-Print-Para.
GO TO Exit-Para.
Total-Print-Para.
.
.
.
Exit-Para.
EXIT.
The EXIT statement in this example concludes a series of paragraphs indicated by the
PERFORM statement.

6–120

8600 1518–307

EXIT Statement

Format 2: EXIT from a Called Program (ANSI IPC)
EXIT PROGRAM
ïïïï ïïïïïïï

Details
The EXIT PROGRAM statement is not required to be in a separate paragraph as is the
Format 1 EXIT statement.
The effect of the EXIT program statement on the called program depends on whether
the IS INITIAL PROGRAM clause is present in the PROGRAM-ID paragraph of the called
program. This clause declares that the program and any programs it contains are placed
in their initial state each time they are called.

•

If the IS INITIAL PROGRAM clause is present, the EXIT PROGRAM statement is
equivalent to a CANCEL statement for the called program.

•

If the IS INITIAL PROGRAM clause is absent, the EXIT PROGRAM statement causes
execution to continue with the next executable statement following the CALL
statement in the calling program.
When control is passed between the calling and called programs, it is possible for
the contents of shared data items and shared data files to change.
The EXIT PROGRAM statement closes all PERFORM statements in the called
program. If a PERFORM procedure is interrupted and the implicit return instruction at
the end of that procedure has not been executed, the EXIT PROGRAM statement
cancels that implicit return.
If the EXIT PROGRAM statement is in a program that is not under the control of a
calling program, the statement has no effect and the program continues execution.

Restrictions
The following restrictions apply to the EXIT PROGRAM statement; it must

•

Be the last statement in a consecutive sequence of imperative statements.

•

Not appear in a declarative procedure in which the GLOBAL phrase is specified.

8600 1518–307

6–121

EXIT Statement

Example
IDENTIFICATION DIVISION.
PROGRAM-ID. PROGA.
.
.
.
PROCEDURE DIVISION.
CALL "PROGB" USING A, C.
.
.
.

IDENTIFICATION DIVISION.
PROGRAM-ID. PROGB.
.
.
.
LINKAGE SECTION.
01 Employee-Data . . .
01 Salary . . .
.
.
.
PROCEDURE DIVISION USING
Employee-Data, Salary.
.
.
.
EXIT PROGRAM.

In this example, program PROGA calls program PROGB. The statements in PROGB are
executed. The EXIT PROGRAM statement causes execution to continue with the next
executable statement following the CALL statement in PROGA.

6–122

8600 1518–307

EXIT Statement

Format 3: EXIT from a Bound Procedure
EXIT PROCEDURE
ïïïï ïïïïïïïïï

Details
The EXIT PROCEDURE statement should be used only for procedures compiled at lexical
level 3 or higher. If the procedure has been processed or called as a coroutine when the
EXIT PROCEDURE statement is encountered, the process goes to end-of-task (EOT). If
the procedure has been called as a procedure, a normal procedure exit occurs back to
the statement that follows the procedure invocation in the calling program.
An implicit EXIT PROCEDURE statement is compiled for all procedures compiled at level
3 or higher. The EXIT PROCEDURE statement need not be used when it would be the
final statement in the procedure. Refer to “CALL Statement,” “CANCEL Statement,”
and “PERFORM Statement” in this section for syntax and detailed information.

Format 4: EXIT from a Called Program (Tasking)
EXIT PROGRAM
ïïïï ïïïïïïï

[ RETURN HERE ]
ïïïïïï ïïïï

Details
Use this statement in the called program to return to the calling program. (The calling
program originally initiated the called program by using Format 6 of the CALL statement.)
When either an EXIT PROGRAM or EXIT PROGRAM RETURN HERE statement is
reached in the called program, control is returned to the statement following the CALL
statement in the calling program. Afterward, control is passed between the two
programs as shown in the following table.

If the calling program issues a
subsequent CONTINUE statement
and the called program was
previously exited by an . . .

Then control returns to . . .

EXIT PROGRAM statement

The first logically executable statement in
the called program

EXIT PROGRAM RETURN HERE
statement

The statement immediately following the
EXIT PROGRAM RETURN HERE
statement

8600 1518–307

6–123

EXIT Statement

Note that the contents of data items and data files shared between the calling and called
programs might change between successive executions of the CONTINUE statement.
Note also that the EXIT PROGRAM statement closes all PERFORM statements in the
called program. If a PERFORM procedure is interrupted and the implicit return instruction
at the end of that procedure has not been executed, the EXIT PROGRAM statement
cancels that implicit return.
An EXIT PROGRAM RETURN HERE statement cannot appear in a bound procedure.
For an example of how the EXIT PROGRAM statement is used, refer to the tasking
examples in Section 13.

Format 5: EXIT MODULE
EXIT MODULE

Details
An EXIT MODUDE statement returns control from a called program to the calling
program. The EXIT MODULE statement must appear in a sentence by itself and must be
the only sentence in the paragraph. Refer to the “CALL MODULE Statement” in this
section and to the Binder Programming Reference Manual.
If a program has not been initiated by a CALL MODULE statement and an EXIT MODULE
statement is encountered, the program is not exited, and execution begins with the next
statement of the program.
The compiler generates a warning message if an EXIT MODULE statement is found in a
program that does not have the CALLMODULE CCI set. See Section 15 for a description
of the CALLMODULE compiler option.

6–124

8600 1518–307

EXIT Statement

Format 6: EXIT from a PERFORM Statement
EXIT PERFORM
ïïïï ïïïïïïï

Details
The EXIT PERFORM statement provides a way to bypass the remainder of a PERFORM
statement range.
If the program is under the control of an in-line or an out-of-line PERFORM statement
when the EXIT PERFORM statement is encountered, any remaining statements in the
PERFORM statement range are bypassed. This will terminate format 1 PERFORM
statements. All other PERFORM statement formats terminate only when the specified
terminating conditions are met. If an EXIT PERFORM statement is executed when no
PERFORM statement is active, control passes to the next statement.

Examples
Note: In the following out-of-line PERFORM and in-line PERFORM examples, the EXIT
PERFORM statement bypasses the ADD statement. The program displays
"WS-COUNT = 0".
Exit from basic out-of-line PERFORM:
IDENTIFICATION DIVISION.
ENVIRONMENT
DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-COUNT PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
MAIN.
PERFORM P1.
DISPLAY "WS-COUNT = " WS-COUNT.
STOP RUN.
P1.
IF (WS-COUNT = 0)
EXIT PERFORM
ELSE
CONTINUE
END-IF.
ADD 1 TO WS-COUNT.

8600 1518–307

6–125

EXIT Statement

Exit from basic in-line PERFORM:
IDENTIFICATION DIVISION.
ENVIRONMENT
DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-COUNT PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
MAIN.
PERFORM
IF (WS-COUNT = 0)
EXIT PERFORM
ELSE
CONTINUE
END-IF
ADD 1 TO WS-COUNT
END-PERFORM.
DISPLAY "WS-COUNT = " WS-COUNT.
STOP RUN.

Note: In the following out-of-line PERFORM ... UNTIL and in-line PERFORM ... UNTIL
examples, The PERFORM statement range is executed five times. The EXIT PERFORM
statement bypasses the DISPLAY statement in the PERFORM statement range. The
program display "WS-COUNT = 1" and "COUNT = 5".
Exit from out-of-line PERFORM ... UNTIL:
IDENTIFICATION DIVISION.
ENVIRONMENT
DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-COUNT PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
MAIN.
PERFORM P1 UNTIL WS-COUNT = 5
DISPLAY "COUNT = " WS-COUNT.
STOP RUN.
P1.
ADD 1 TO WS-COUNT.
IF (WS-COUNT > 1)
EXIT PERFORM
ELSE
CONTINUE
END-IF.
DISPLAY "WS-COUNT = " WS-COUNT.

6–126

8600 1518–307

EXIT Statement

Exit from in-line PERFORM ... UNTIL:
IDENTIFICATION DIVISION.
ENVIRONMENT
DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-COUNT PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
MAIN.
PERFORM UNTIL WS-COUNT = 5
ADD 1 TO WS-COUNT
IF (WS-COUNT > 1)
EXIT PERFORM
ELSE
CONTINUE
END-IF
DISPLAY "WS-COUNT = " WS-COUNT
END-PERFORM.
DISPLAY "COUNT = " WS-COUNT.
STOP RUN.

Note: In the following example, the EXIT PERFORM statement is executed when no
PERFORM statement is active, so control passes to the DISPLAY statement. The
program displays "WS-COUNT = 1".
EXIT PERFORM when no PERFORM statement is active:
IDENTIFICATION DIVISION.
ENVIRONMENT
DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-COUNT PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
MAIN.
IF WS-COUNT = 0
GO TO P1.
STOP RUN.
P1.
ADD 1 TO WS-COUNT.
EXIT PERFORM.
DISPLAY "WS-COUNT = " WS-COUNT.

8600 1518–307

6–127

GO TO Statement

GO TO Statement
The GO TO statement transfers control unconditionally from one procedure to another.

Format

Use

Format 1

The GO TO format transfers control from one part of the Procedure
Division to another.

Format 2

The GO TO . . . DEPENDING ON format transfers control from one part
of the Procedure Division to another depending on the value of a
specified integer identifier.

Format 1: GO TO
GO TO
ïï ïï

[ procedure-name-1 ]

Explanation
GO TO

If procedure-name-1 is specified, control is transferred to procedure-name-1.
If procedure-name-1 is not specified, the following rules apply:

•

The GO TO statement can appear only in a single statement paragraph (that is, a
paragraph that consists of a paragraph header followed by the GO TO statement).

•

An ALTER statement that refers to this GO TO statement must be executed before
the execution of this GO TO statement. (The ALTER statement directs the GO TO
statement to a destination.)

Control is not returned to the statement following the GO TO statement.
procedure-name-1

This user-defined word names a paragraph or section in the Procedure Division. It
consists of a paragraph-name (which can be qualified) or a section-name.
Procedure-name-1 as an option is an obsolete element that will be deleted from the next
revision of Standard COBOL. Procedure-name-1 will become a mandatory part of the
syntax.

Details
If a Format 1 GO TO statement appears in a consecutive sequence of imperative
statements in a sentence, it must appear as the last statement in that sequence.

6–128

8600 1518–307

GO TO Statement

Format 2: GO TO . . . DEPENDING ON
GO TO [ procedure-name-1 [ [
ïï ïï
DEPENDING ON identifier-1
ïïïïïïïïï

, ] procedure-name-2 ] ] . . .

Explanation
procedure-name-1
procedure-name-2

These user-defined words name a paragraph or section in the Procedure Division. A
procedure-name consists of a paragraph-name (which can be qualified) or a sectionname.
DEPENDING ON

This phrase causes the transfer of control to depend on the value of identifier-1 being 1,
2, . . . , n. The exact procedure-name is selected by the value of identifier-1. If the value
of identifier-1 is anything other than the positive or unsigned integers 1, 2, . . . , n, then
no transfer occurs and control passes to the next statement in the normal sequence for
execution.
identifier-1

This element must reference an elementary, numeric data item that is an integer.
Identifier-1 cannot reference a long numeric data item.
Refer to “ALTER Statement” in this section and “PERFORM Statement” in Section 7 for
syntax and detailed information.

8600 1518–307

6–129

GO TO Statement

Examples
WORKING-STORAGE SECTION.
01 POINTER-ID PIC 99 VALUE 01.
.
.
.
PROCEDURE DIVISION.
.
.
.
Check-Para.
IF POINTER-ID IS GREATER THAN 59 MOVE 01 TO POINTER-ID
GO TO UNSTRING-Para.
MOVE SPACES TO OUT-RECORD.
.
.
.
UNSTRING-Para.
In this example, if the value of POINTER-ID is greater than 59, 01 is moved to POINTERID, and control is transferred to UNSTRING-Para.
WORKING-STORAGE SECTION.
77 I
PIC 9.
.
.
.
PROCEDURE DIVISION.
P1.
.
.
.
P2.
.
.
.
P3.
GO TO P1, P2 DEPENDING ON I.
In this example, control will be transferred from the GO TO statement in P3 depending
on the value in I. If I equals 1, then P1 is executed. If I equals 2, P2 is executed. If I
equals anything but 1 or 2, the program proceeds to the statements that follow the GO
TO statement in the program.

6–130

8600 1518–307

Section 7
Procedure Division Statements I–R
This section illustrates and explains the syntax of the Procedure Division statements.
Statements beginning with the letters I through R are listed in alphabetical order with the
following information:

•

A brief description of the function of the statement

•

A syntax diagram for each format of the statement (if you need information on how
to interpret a COBOL syntax diagram, refer to Appendix C).

•

A statement of what portion of the syntax, if any, can be used interactively in a Test
and Debug System (TADS) session

•

An explanation of the elements in the syntax diagram

•

Details, rules, and restrictions about the particular statement

•

An example of the statement

•

References to additional information relevant to the statement

Detailed information about language elements common to many Procedure Division
statements, such as user-defined names, literals, and identifiers is provided in Section 1.
Concepts such as arithmetic and conditional expressions, and operations such as table
handling, sorting, and merging are described in Section 5.

8600 1518–307

7–1

IF Statement

IF Statement
The IF statement evaluates a condition. Subsequent action of the object program
depends on whether the value of the condition is TRUE or FALSE.
See “Conditional Expressions” in Section 5 for conceptual information on the different
types of conditions. See “EVALUATE Statement” in this section for more information.

IF condition-1 THEN
ïï
ä
³
ã
³
æ

ä
ã
æ

ä statement-1
å
å
ã
â . . . â
æ NEXT SENTENCE ç
ç
ïïïï ïïïïïïïï

ELSE { statement-2 } . . . [ END-IF ]
ïïïï
ïïïïïï
ELSE NEXT SENTENCE
ïïïï ïïïï ïïïïïïïï
END-IF
ïïïïïï

å
³
â
³
ç

Explanation
condition-1

This element specifies a test condition. The object program selects between alternate
paths of control depending on the truth-value of the condition. A condition can be simple
or complex. Refer to “Conditional Expressions” in Section 5 for detailed information.
THEN statement-1 . . .

If the condition is TRUE, statement-1 is executed. If the condition is FALSE, statement-1
is ignored.
Statement-1 can be either an imperative statement or a conditional statement optionally
preceded by an imperative statement.
Statement-1 can contain an IF statement. In this case, the IF statement is said to be
nested.
NEXT SENTENCE

This phrase is for documentation purposes only. If condition-1 is TRUE, NEXT SENTENCE
indicates that the next sentence (the sentence following the IF statement) will be
executed.

7–2

8600 1518–307

IF Statement

ELSE statement-2 . . .
END-IF

If condition-1 is false, statement-2 is executed.
Statement-2 can contain an IF statement. In this case, the IF statement is said to be
nested.
The END-IF phrase delimits the scope of an IF statement at the same level of nesting.
ELSE NEXT SENTENCE

This phrase is for documentation purposes only. If condition-1 is false, NEXT SENTENCE
indicates that the sentence following the IF statement will be executed.
This phrase can be omitted if it immediately precedes the terminal period of the
sentence.
END-IF

This delimits the scope of the IF statement.
If the END-IF phrase is specified, the NEXT SENTENCE phrase must not be specified.
How the IF Statement Is Evaluated
When an IF statement is executed, transfers of control occur according to the conditions
described in the following tables.

If condition-1 is TRUE and . . .

Then . . .

One or more statements are
specified with the THEN phrase

Control is transferred to the first statement
specified with the THEN phrase. Execution
continues according to the rules for that
statement.
If statement-1 is a conditional statement or a
procedure-branching statement that explicitly
transfers control, then control is transferred
according to the rules for that statement.
After the statement or statements associated with
the THEN phrase are executed, control passes to
the end of the IF statement. Note that any
statements specified with the ELSE phrase are
ignored.

The NEXT SENTENCE phrase is
specified (instead of statement-1)

8600 1518–307

Control passes to the next executable sentence.
Any statements specified with the ELSE phrase
are ignored.

7–3

IF Statement

If condition-1 is FALSE and . . .

Then . . .

One or more statements are
specified with the ELSE phrase.

Statement-1 or its surrogate NEXT SENTENCE is
ignored, and control is transferred to the first
statement specified in the ELSE phrase. Execution
continues according to the rules for each statement.
If statement-2 is a conditional statement or a
procedure-branching statement that explicitly
transfers control, then control is transferred
according to the rules for that statement.
After the statement or statements associated with
the ELSE phrase are executed, control passes to the
end of the IF statement.

The ELSE phrase is not specified

Statement-1 is ignored and control passes to the
next executable sentence.

Nested IF Statements
IF statements within IF statements can be considered as paired IF, ELSE, and END-IF
combinations, proceeding from left to right. Each ELSE or END-IF encountered
corresponds to the immediately preceding IF that has not been paired with an ELSE or
END-IF, as follows:
IF A > B PERFORM A-PROC
IF B < C PERFORM C-PROC
ELSE PERFORM B-PROC
END-IF
ELSE PERFORM MAIN-ROUTINE
END-IF.
The first IF (IF A > B) is paired with the last ELSE (ELSE PERFORM MAIN-ROUTINE) and
the last END-IF. The second IF (IF B < C) is paired with the next encountered ELSE (ELSE
PERFORM B-PROC) and END-IF.
Terminating an IF Statement
The scope of an IF statement can be terminated by one of the following:

7–4

•

An END-IF phrase at the same level of nesting

•

A separator period

•

If nested, by an ELSE phrase associated with an IF statement at a higher level of
nesting

8600 1518–307

IF Statement

Examples
IF hours-worked > 40
SUBTRACT 40 FROM hours-worked GIVING overtime-hours
MULTIPLY .5 BY hourly-rate GIVING overtime-pay ROUNDED
ADD overtime-pay TO gross-pay
ELSE
PERFORM Standard-Pay-Routine
END-IF.
If the value of hours-worked is greater than 40, the calculations for overtime pay are
made. If the value of hours-worked is equal to or less than 40, the statements in
Standard-Pay-Routine are executed.
IF SW1-ON
PERFORM Inspect-Proc
ELSE IF SW5-ON
PERFORM Search-Proc
ELSE NEXT SENTENCE.
If SW1 is set, then the statements in Inspect-Proc are executed. If SW1 is not set and
SW5 is set, the statements in Search-Proc are executed. If SW1 is not set and SW5 is
not set, control passes to the next executable sentence.

8600 1518–307

7–5

INITIALIZE Statement

INITIALIZE Statement
The INITIALIZE statement enables you to set selected types of data fields to
predetermined values (for example: numeric data to zeros, or alphanumeric data to
spaces). A group of elementary data items can have its initial value set with one
statement.

INITIALIZE
ïïïïïïïïïï
Ú
³
³
³
³
³
³
³REPLACING
³ïïïïïïïïï
³
³
³
³
³
À

{ identifier-1 } . . .

ä
³
³
³
³
³
ã
³
³
³
³
³
æ

ALPHABETIC
ïïïïïïïïïï
ALPHANUMERIC
ïïïïïïïïïïïï
NATIONAL
ïïïïïïïï
NATIONAL-EDITED
ïïïïïïïïïïïïïïï
NUMERIC
ïïïïïïï
ALPHANUMERIC-EDITED
ïïïïïïïïïïïïïïïïïïï
NUMERIC-EDITED
ïïïïïïïïïïïïïï

¿
å
å
³
³
³
³
³
³
³
³
³
³
³
³
³
³
ä identifier-2 å ³
³
â DATA BY ã
â â . . . ³
³
ïï æ literal-1
ç ³
³
³
³
³
³
³
³
³
³
³
³
³
³
ç
ç
³
Ù

Explanation
identifier-1

The data item referred to by identifier-1 represents the receiving area. Identifier-1 can
represent an elementary or group item.

7–6

8600 1518–307

INITIALIZE Statement

The following restrictions apply to identifier-1:

•

An index data item cannot appear as an operand of an INITIALIZE statement. If
identifier-1 is a long numeric data item, then one of the following conditions must be
true:

−

Identifier-2 must be a long numeric data item of the same size and usage.

−

Literal-1 must be either an appropriate figurative constant, 0 (zero), or a numeric
literal that contains the same number of digits as the long numeric data item.

•

The description of the data item referred to by identifier-1, or any items subordinate
to identifier-1, cannot contain the DEPENDING phrase of the OCCURS clause. In
addition, the data description entry for the data item referred to by identifier-1 cannot
contain a RENAMES clause.

•

Any item that is subordinate to the data item referred to by identifier-1 and that
contains the REDEFINES clause, or any item that is subordinate to such an item, is
excluded from the initialization operation. However, the data item referred to by
identifier-1 can have a REDEFINES clause, or be subordinate to a data item with a
REDEFINES clause.

REPLACING . . .

The data category you specify in the REPLACING phrase must be a permissible category
for the data item. You cannot repeat the same data category in the same REPLACING
phrase.
If you do not specify a REPLACING phrase, the following values are assumed for the
categories of data items:

Data items of category . . .

Are set to. . .

Alphabetic

Spaces

Alphanumeric

Spaces

Alphanumeric-edited

Spaces

National

National spaces

National-edited

National spaces

Numeric

Zeros

Numeric-edited

Zeros

In all cases, the INITIALIZE statement operates as if each affected data item is the
receiving area in an elementary MOVE statement with the indicated source literal (that is,
spaces or zeros).

8600 1518–307

7–7

INITIALIZE Statement

BY
identifier-2
literal-1

The data item referred to by identifier-2 or the string in literal-1 represents the sending
area.

Details
All operations are performed as if a series of MOVE statements (each with an
elementary item as its receiving field) had been written, subject to the following rules:

•

If identifier-1 references a group item, any elementary item within that group item is
initialized only if it belongs to the data category specified in the REPLACING phrase.

•

If identifier-1 references an elementary item, that item is initialized only if it belongs
to the data category specified in the REPLACING phrase.

The data item referred to by identifier-2 or literal-1 acts as the sending operand in an
implicit MOVE statement (refer to the “MOVE Statement” in this section for more
information). The data item referred to by identifier-1 is set to the indicated value in the
order (left to right) of the appearance of identifier-1. Within this sequence, where
identifier-1 references a group item, affected elementary items are initialized in the
sequence of their definitions within the group. However, index data items and filler data
items are not affected by an INITIALIZE statement.
If the data item referred to by identifier-1 occupies the same storage area as the data
item referred to by identifier-2, the result of the execution of the INITIALIZE statement is
undefined, even if the data items are defined by the same data description entry.
Refer to “REDEFINES Clause,” “OCCURS Clause,” and “RENAMES Clause” in Section
4 for syntax and detailed information.
Refer to “MOVE Statement” in this section for information on the MOVE rules.

7–8

8600 1518–307

INITIALIZE Statement

Examples
DATA DIVISION.
WORKING-STORAGE SECTION.
77 Temp-1 PIC X(3).
.
.
.
PROCEDURE DIVISION.
INITIALIZE Temp-1 REPLACING ALPHANUMERIC DATA BY

"ABC".

This statement moves the literal “ABC” to the data item Temp-1.
DATA DIVISION.
01 Group-1
05 Name
05 Address
05 Age
05 Salary

PIC
PIC
PIC
PIC

A(10).
X(20).
99.
$99999V99.

PROCEDURE DIVISION.
INITIALIZE Group-1.
The INITIALIZE statement in this example initializes the elementary data items in Group-1
with zeros or spaces, depending on their definition. Name and Address are initialized with
spaces; Age and Salary are initialized with zeros.

8600 1518–307

7–9

INSPECT Statement

INSPECT Statement
The INSPECT statement can tally, replace, or tally and replace occurrences of single
characters or groups of characters in a data item.
Refer to “STRING Statement” and “UNSTRING Statement” in this section for
information on other statements that enable you to manipulate data.

Format

Use

Format 1

The INSPECT . . . TALLYING format tallies single
characters or groups of characters.

Format 2

The INSPECT . . . REPLACING format replaces single
characters or groups of characters.

Format 3

The INSPECT . . . TALLYING and REPLACING format
tallies and replaces single characters or groups of
characters; this format combines Formats 1 and 2.

Format 4

The INSPECT . . . CONVERTING format replaces single
characters as if multiple Format 2 statements had been
written.

Format 1: INSPECT . . . TALLYING
INSPECT id-1
ïïïïïïï

TALLYING
ïïïïïïïï

ä
³
Ú
³
³ ä BEFORE
³CHARACTERS ³ ã ïïïïïï
³ïïïïïïïïïï ³ æ AFTER
id-2 FOR ã
À
ïïïïï
ïïï ³
Ú
³äALL
å ä äid-3 å ³
³ãïïï
â ã ã
â ³
³æLEADINGç æ ælit-1ç ³
æ ïïïïïïï
À

7–10

å
³
³
...
³
³
â ...
¿
³
äBEFOREå
äid-4 å ³
å
³
ãïïïïïïâ INITIAL ã
â ³...â... ³
æAFTER ç
ælit-2ç ³
ç
³
ïïïïï
Ù
ç
¿
å
ä id-4 å ³
â INITIAL ã
â ³
ç
æ lit-2 ç ³
Ù

8600 1518–307

INSPECT Statement

Explanation
id-1

Id-1 references the data item that you want to inspect.
Id-1 must reference either a group item or any category of elementary item described
(either implicitly or explicitly) as USAGE IS DISPLAY or USAGE IS NATIONAL.
Identifier-1 can reference a long numeric data item.
The INSPECT statement treats id-1 as shown in the following table.

If the data item is . . .

Then the INSPECT statement treats the content of the
data item as . . .

Alphanumeric

A character string.

_ Alphanumeric-edited

Though it had been redefined as alphanumeric, and as
though the INSPECT statement had been written to
reference the redefined data item.

_ Numeric-edited
_ Unsigned numeric
National

A national character string.

National-edited

Though it had been redefined as national, and as though
the INSPECT statement had been written to reference
the redefined data item.

Signed numeric

Though it had been moved to an unsigned numeric data
item of the same length, and as though the INSPECT
statement had been written to reference the redefined
data item. The original value of the sign is retained upon
completion of the INSPECT statement.

id-2

Id-2 designates the data item in which the tally count is to be accumulated. The data item
referenced by identifier-2 must be an elementary numeric item. The data item cannot be
a long numeric data item. Note that the data item is not initialized by the execution of the
INSPECT statement.
id-3
id-4

Id-3 and id-4 must reference either a group item or any category of elementary item,
described (either implicitly or explicitly) as USAGE IS DISPLAY or USAGE IS NATIONAL.
The usage for id-3 and id-4 must be the same as the usage for id-1.
The INSPECT statement treats id-3 and id-4 in the same way as id-1. Refer to the
description of id-1.
When the CHARACTERS phrase is used, id-4 and lit-2 must be one character in length.

8600 1518–307

7–11

INSPECT Statement

lit-1
lit-2

Lit-1 and lit-2 must be nonnumeric literals if id-1 is described as USAGE IS DISPLAY, or
national literals if id-1 is described as USAGE IS NATIONAL.
When the CHARACTERS phrase is used, lit-2 and id-4 must be one character in length.
CHARACTERS

If you specify CHARACTERS, the content of the data item referred to by id-2 is
incremented by one for each character within the data item referred to by id-1.
ALL
LEADING

These adjectives apply to each lit-1 or id-3 that follows them, until the next ALL or
LEADING phrase.
If you specify ALL, the content of id-2 is incremented by one for each occurrence of lit-1
(or the data item referred to by id-3) found within the data item referred to by id-1.
If you specify LEADING, the content of id-2 is incremented by one for each contiguous
occurrence of lit-1 (or the data item referred to by id-3) found within the data item
referred to by id-1, provided that the leftmost occurrence is at the point where
comparison began in the first comparison cycle in which lit-1 or id-3 was eligible to
participate (refer to the heading “The Comparison Cycle” under this statement).
BEFORE
AFTER

You can specify only one BEFORE and one AFTER phrase for any one ALL, LEADING, or
CHARACTERS phrase. Both BEFORE and AFTER can appear in the same INSPECT
statement. See “The Comparison Cycle” for details of how these keywords function.
The Process of Inspection
Inspection, which includes the comparison cycle, the establishment of boundaries for the
BEFORE and AFTER phrases, and the mechanism for tallying, begins at the leftmost
character position of the data item referred to by id-1, regardless of its class. Inspection
proceeds from left to right to the rightmost character position.
Function-identifiers and identifiers with subscripts are evaluated only once as the first
operation in the execution of the INSPECT statement.
If the data items referred to by id-1, id-3, or id-4 occupy the same storage area as the
data item referred to by id-2, the result of the execution of the INSPECT statement is
undefined, even if the identifiers are defined by the same data description entry.

7–12

8600 1518–307

INSPECT Statement

During inspection of the content of the data item referred to by id-1, each properly
matched occurrence of lit-1 (or the data item referred to by id-3) is tallied, and the tally is
stored in the data item referred to by id-2.
The Comparison Cycle
The operands of the TALLYING phrase are considered in the order they are specified in
the INSPECT statement from left to right. The first lit-1 is compared to an equal number
of contiguous characters, starting with the leftmost character position in the data item
referred to by id-1. Lit-1 matches that portion of the content of the data item referred to
by id-1 if, and only if, they are equal, character for character.
Note: In this discussion, any reference to lit-1 applies to id-3. Any reference to lit-2
applies to id-4.
If a match does not occur, the comparison continues with the next lit-1. This process
repeats until there is no next lit-1.
The next cycle begins with the character position in the data item referred to by id-1
immediately to the right of the leftmost character position considered in the last
comparison cycle.
Whenever a match occurs, the content of the data item referred to by id-2 is
incremented as described earlier, and the character position to the right of the rightmost
character position considered in the comparison becomes the leftmost character position
of a new comparison cycle.
The comparison cycles continue until the rightmost character position of the data item
referred to by id-1 has participated in a match or has been considered as the leftmost
character position. When this occurs, inspection is terminated.
How the BEFORE and AFTER Phrases Affect the Comparison Cycle
The BEFORE and AFTER phrases affect the comparison cycle as follows:

•

If you do not specify a BEFORE or AFTER phrase, the entire data item referred to by
id-1 is involved in the inspection.

•

If you specify the BEFORE phrase, the comparison cycle includes only that portion of
the data item referred to by id-1 from its leftmost character up to, but not including,
the first occurrence of the data item referred to by lit-2. The position of this first
occurrence is determined before the first comparison cycle.

•

If the data item referred to by lit-2 is not found in the content of the data item
referred to by id-1, the INSPECT statement executes as if you did not specify a
BEFORE phrase.

•

If you specify the AFTER phrase, the comparison cycle includes only that portion of
the data item referred to by id-1 between the character position immediately to the
right of the rightmost character position of the first occurrence of lit-2 and the
rightmost character position of the data item referred to by id-1. The position of this
first occurrence is determined before the first comparison cycle begins.

•

If the data item referred to by lit-2 is not found in the content of the data item
referred to by id-1, there is no inspection for the corresponding lit-1.

8600 1518–307

7–13

INSPECT Statement

Examples
INSPECT Word TALLYING count1
FOR LEADING "L"BEFORE INITIAL "A".
If the data item Word contained the value LARGE, the tally, which is stored in the data
item Count1, would be 1.
If the data item Word contained the value ANALYST, the tally would be 0.
INSPECT Word TALLYING count1
FOR CHARACTERS AFTER INITIAL "J".
If the data item Word contained the value ADJECTIVE, the tally, which is stored in the
data item Count1, would be 6.

7–14

8600 1518–307

INSPECT Statement

Format 2: INSPECT . . . REPLACING
INSPECT identifier-1 REPLACING
ïïïïïïï
ïïïïïïïïï
ä
ä identifier-1 å
³
CHARACTERS BY ã
â
³
ïïïïïïïïïï ïï æ literal-1
ç
³
Ú
¿
³
³ ä BEFORE å
ä identifier-4 å ³
³
³ ã ïïïïïï â INITIAL ã
â ³
³
³ æ AFTER ç
æ literal-2
ç ³
³
À
ïïïïï
Ù
³
³ ä ALL
å ä ä identifier-3 å
ä identifier-2
ã ³ ïïï
³ ³ ã
â BY ã
³ ã LEADING â ã æ literal-3
ç ïï æ literal-1
³ ³ ïïïïïïï ³ ³
³ æ FIRST
ç æ
³
ïïïïï
³
Ú
³
³ ä BEFORE å
ä identifier-4
³
³ ã ïïïïïï â INITIAL ã
³
³ æ AFTER ç
æ literal-2
³
À
ïïïïï
æ

å
³
³
³
³
. . .
³
³
³
³
å
³
â
â. . .
ç
³
³
³
³
¿
å
³
å ³
³
³
â ³ . . . â . . .³
ç ³
³
³
Ù
ç
³
ç

Explanation
identifier-1
identifier-2
identifier-3
identifier-4

Identifier-1 must refer to either a group item or any category of elementary item
described (either implicitly or explicitly) as USAGE IS DISPLAY or USAGE IS NATIONAL.
Identifier-1 can reference a long numeric data item.
Identifier-2 through identifier-n must refer to an elementary alphanumeric (alphabetic)
item, an elementary numeric item, or an elementary national item.
When identifier-1 through identifier-n are alphanumeric (alphabetic) or numeric, the data
items they reference must be described (implicitly or explicitly) as USAGE IS DISPLAY.
When identifier-1 through identifier-n are national, the data items they reference must be
described (implicitly or explicitly) as USAGE IS NATIONAL.
The size of the data item referred to by identifier-3 must be equal to the size of the data
item referred to by identifier-2.
When you specify the CHARACTERS BY phrase, the data item referred to by identifier-2
and identifier-4 must be one character in length.

8600 1518–307

7–15

INSPECT Statement

In Format 2 of the INSPECT statement, the following rules apply to the data item
referenced by identifiers:

If the data item is . . .

Then the INSPECT statement treats the content of the
data item as . . .

Alphanumeric

A character-string.

_ Alphanumeric-edited

Though it is redefined as alphanumeric and as though the
INSPECT statement is written to refer to the redefined data
item.

_ Numeric-edited
_ Unsigned numeric
National

A national character string.

National-edited

Though it is redefined as national, and as though the
INSPECT statement is written to reference the redefined
data item.

Signed numeric

Though it is moved to an unsigned numeric data item of the
same length and as though the INSPECT statement is
written to refer to the redefined data item.

literal-1
literal-2
literal-3

These literals must be nonnumeric if identifier-1 is described as USAGE IS DISPLAY.
These literals must be national if identifier-1 is described as USAGE IS NATIONAL. These
literals cannot be any figurative constant that begins with the word ALL. If any literal is
national, all the literals must be national. When you specify the CHARACTERS BY phrase,
literal-1 and literal-2 must be one character in length.
If literal-2 is a figurative constant, it is implicitly a one-character data item.
The size of literal-3 must be equal to the size of literal-1.
REPLACING

The REPLACING phrase enables you to replace a single character or groups of characters
in a data item.
CHARACTERS BY

If you specify the CHARACTERS BY phrase, each character in the data item referred to
by identifier-1 is replaced by literal-1 or the data item referred to by identifier-2.
Literal-1 (or the data item referred to by identifier-2) and literal-2 (or the data item referred
to by identifier-4) must be one character in length.

7–16

8600 1518–307

INSPECT Statement

ALL
LEADING
FIRST

These apply to each literal-3 or identifier-3 that follows them, until the next ALL,
LEADING, or FIRST phrase.
If you specify ALL, each occurrence of literal-3 that is matched in the content of the data
item referred to by identifier-1 is replaced by literal-1.
If you specify LEADING, each contiguous occurrence of literal-3 that is matched in the
content of the data item referred to by identifier-1 is replaced by literal-1, provided that
the leftmost occurrence is at the point where the comparison began in the first
comparison cycle in which literal-3 was eligible to participate (refer to “The Comparison
Cycle” in the discussion of the Format 1 INSPECT statement).
If you specify FIRST, the leftmost occurrence of literal-3 that is matched within the
content of the data item referred to by identifier-1 is replaced by literal-1.
Note: In this discussion, any reference to literal-1 applies to identifier-2. Any reference
to literal-2 applies to identifier-4.
BEFORE
AFTER

You can specify only one BEFORE and one AFTER phrase for any one ALL, LEADING,
FIRST, or CHARACTERS phrase. However, both BEFORE and AFTER can be used in the
same INSPECT statement. See “The Comparison Cycle” in the discussion of the Format
1 INSPECT statement for an explanation of how the BEFORE and AFTER phrases
operate.

Details
Inspection, which includes the comparison cycle, the establishment of boundaries for the
BEFORE and AFTER phrases, and the mechanism for replacing, begins at the leftmost
character position of the data item referred to by identifier-1, regardless of its class.
Inspection proceeds from left to right to the rightmost character position.
If an identifier is subscripted or is a function-identifier, the subscript or function-identifier
is evaluated once, as the first operation in the execution of the INSPECT statement.

8600 1518–307

7–17

INSPECT Statement

Examples
INSPECT Word REPLACING CHARACTERS BY "B"BEFORE INITIAL "R".
If the data item Word contained the value ARXAX, the resulting value of Word after
replacement would be BRXAX.
INSPECT Word REPLACING ALL "ABC"BY "XYZ".
If the data item Word contained the value BBEABCABABBCABEE, the resulting value of
Word after replacement would be BBEXYZABABBCABEE.
INSPECT Word REPLACING
ALL "AB"BY "XY",
"D"BY "X",
"BC"BY "VW",
LEADING "EF"BY "TU",
FIRST "G"BY "R",
FIRST "G"BY "P",
CHARACTERS BY "Z".
If the data item Word contains the value EFABDBCGABEFGG, the resulting value of
Word after replacement is TUXYXVWRXYZZPZ.

7–18

8600 1518–307

INSPECT Statement

Format 3: INSPECT . . . TALLYING and REPLACING
INSPECT identifier-1 TALLYING
ïïïïïïï
ïïïïïïïï
ä identifier-2 FOR
³
ïïï
³ ä
Ú
³ ³ CHARACTERS ³ ä BEFORE å
ä identifier-4 å
³ ³ ïïïïïïïïïï ³ ã ïïïïïï â INITIAL ã
â
³ ³
³ æ AFTER ç
æ literal-2
ç
³ ³
À
ïïïïï
³ ã ä
å
³ ³ ³ALL
³ ä ä identifier-3 å
ã ³ ãïïï
â ³ ã
â
³ ³ ³LEADING ³ ã æ literal-1
ç
³ æ æïïïïïïï ç ³
³
æ
³
³
Ú
¿
å
³
³ ä BEFORE å
ä identifier-4 å ³
³
³
³ ã ïïïïïï â INITIAL ã
â ³ ...â
³
³ æ AFTER ç
æ literal-2
ç ³
³
³
À
ïïïïï
Ù
ç
æ

å
³
³
³
³
³
³
³
â ...
³
³
³
å
³
³
³
³
³
... â ... ³
ç
³
³
³
ç
ç
¿
³
³ ...
³
Ù

REPLACING
ïïïïïïïïï
ä
³
ä identifier-5 å
³ CHARACTERS BY
ã
â
³ ïïïïïïïïïï ïï
æ literal-3
ç
³
Ú
¿
³
³ ä BEFORE å
ä identifier-4 å ³
³
³ ã ïïïïïï â INITIAL ã
â ³ ...
³
³ æ AFTER ç
æ literal-2
ç ³
³
À
ïïïïï
Ù
³
³äALL
å ä ä identifier-3 å
ä identifier-5 å
ã³ïïï
³ ³ ã
â BY ã
â
³³LEADING ³ ã æ literal-1
ç ïï æ literal-3
ç
³ãïïïïïïï â ³
³³FIRST
³ æ
³æïïïïï
ç
³
Ú
¿
å
³
³ ä BEFORE å
ä identifier-4 å ³
³
³
³ ã ïïïïïï â INITIAL ã
â ³ ...â ...
³
³ æ AFTER ç
æ literal-2
ç ³
³
³
À
ïïïïï
Ù
ç
æ

8600 1518–307

å
³
³
³
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³ ...
³
³
ç

7–19

INSPECT Statement

Explanation
This format of the INSPECT statement is interpreted and executed as though two
successive INSPECT statements specify the same identifier-1: one statement is a
Format 1 statement (TALLYING), and the other statement is a Format 2 statement
(REPLACING). Refer to the descriptions of Formats 1 and 2.
Subscripting associated with any identifier in the Format 2 part of this statement is
evaluated only once before executing the Format 1 statement.
Refer to Formats 1 and 2 for descriptions of the syntax elements in Format 3.

Examples
INSPECT Word TALLYING Count1 FOR ALL "L",
REPLACING ALL "A"BY "E"AFTER INITIAL "L".
This example of a Format 3 INSPECT statement is equivalent to the following two
statements:
INSPECT Word TALLYING Count1 FOR ALL "L".
INSPECT Word REPLACING ALL "A"BY "E"AFTER INITIAL "L".
If the data item Word contained the value CALLAR, the data item Count1 would contain
2, and the value of Word after replacement would be CALLER.

7–20

8600 1518–307

INSPECT Statement

Format 4: INSPECT. . . CONVERTING
INSPECT identifier-1 CONVERTING
ïïïïïïï
ïïïïïïïïïï
ä identifier-2 å
ä identifier-3 å
ã
â TO ã
â
æ literal-1
ç ïï æ literal-2
ç
Ú
¿
³ ä BEFORE å
ä identifier-4 å ³
³ ã ïïïïïï â INITIAL ã
â ³ ...
³ æ AFTER ç
æ literal-3
ç ³
À
ïïïïï
Ù

Explanation
identifier-1

The same rules for an identifier-1 in a Format 1 or Format 2 statement apply to this
identifier.
CONVERTING

With the CONVERTING phrase, you can replace single characters as if you had written a
Format 2 (REPLACING) statement with a series of ALL phrases, one ALL phrase for each
character in literal-1.
identifier-2
identifier-3

The size of identifier-2 must be equal to the size of identifier-3. The same character
cannot appear more than once in the data item referred to by identifier-2.
When you use a figurative constant as literal-3, the data item referred to by identifier-2
(or literal-1) must be the same size as the figurative constant.
identifier-4

The same rules for an identifier-4 in a Format 1 or Format 2 statement apply to this
identifier.
literal-1
literal-2
literal-3

The size of literal-1 must be equal to the size of literal-2. The same character cannot
appear more than once in literal-1.
When you use a figurative constant as literal-3, literal-1 (or the data item referred to by
identifier-2) must be the same size as the figurative constant.

8600 1518–307

7–21

INSPECT Statement

Details
The first character in the data item referred to by identifier-2 (or literal-1) is replaced by
the first character in the data item referred to by identifier-3 (or literal-2) wherever that
character occurs in the data item referred to by identifier-1.
If identifier-2, identifier-3, or identifier-4 occupies the same storage space as identifier-1,
the result of the execution of the INSPECT statement is undefined, even if the identifiers
are defined by the same data description entry.
The BEFORE and AFTER phrases are discussed in “The Comparison Cycle” in the
discussion of Format 1.
Subscripting associated with any identifier is evaluated only once, as the first operation in
the execution of the INSPECT statement.

Example
The following two INSPECT statements are equivalent:
INSPECT Word CONVERTING
BEFORE "#".

"ABCD"TO

INSPECT Item REPLACING
ALL "A"BY "X"AFTER QUOTE
ALL "B"BY "Y"AFTER QUOTE
ALL "C"BY "Z"AFTER QUOTE
ALL "D"BY "X"AFTER QUOTE

BEFORE
BEFORE
BEFORE
BEFORE

"XYZX"AFTER QUOTE

"#".
"#".
"#".
"#".

If the data item Word contained AC"AEBDFBCD#AB"D, the resulting value of data item after
the INSPECT statement would be AC"XEYXFYZX#AB"D.

7–22

8600 1518–307

LOCK Statement

LOCK Statement
The LOCK statement enables a process to lock a common data storage area so that
other related processes cannot access it.

LOCK
ïïïï

ä event-identifier å
ã
â
æ lock-identifier ç

[ END-LOCK ]
ïïïïïïïï

Ú
³ AT LOCKED
³ ïïïïïïïïï
³
À

¿
ä statement-1
å ³
ã
â ³
æ NEXT SENTENCE ç ³
ïïïïïïïïïïïïï
Ù

Explanation
event-identifier
lock-identifier

The event-identifier can be one or more of the following:

•

The name of a data-item declared with the USAGE IS EVENT phrase. The data-name
must be properly qualified and properly subscripted.

•

A task attribute of type EVENT. The two event task attributes are ACCEPTEVENT
and EXCEPTIONEVENT. For details about these task attributes, refer to the Task
Attributes Programming Reference Manual.

•

A file attribute of type EVENT. The three event file attributes are CHANGEEVENT,
INPUTEVENT, and OUTPUTEVENT. For details about these file attributes, refer to the
File Attributes Programming Reference Manual.

The lock-identifier is the data-name of the storage area declared as a data item with the
USAGE IS LOCK clause. (For details, see “USAGE Clause” in Section 4).
AT LOCKED statement-1
AT LOCKED NEXT SENTENCE

This syntax enables the process to test the storage area represented by the event or lock
identifier to see if it is locked. If the area is locked when the LOCK statement is
executed, control passes either to the statement specified with the AT LOCKED phrase
or to the next sentence after the LOCK statement.
END-LOCK

If multiple LOCK statements are nested in the same block, you must use the END-LOCK
phrase to signify the end of each LOCK statement.

8600 1518–307

7–23

LOCK Statement

Details
If you do not use the AT LOCKED phrase, the system continues to try to lock the storage
area until it is successful. This might cause a time delay if the process has to wait until
another process unlocks the storage area.

Example
LOCK WS-EVENT (3).
LOCK WS-77-EVENT AT LOCKED GO TO ERROR1.

7–24

8600 1518–307

LOCKRECORD Statement

LOCKRECORD Statement
The LOCKRECORD statement enables a process to lock a record in a file so that other
processes cannot access it. The LOCKRECORD statement has the following format:
LOCKRECORD file-name
[ON EXCEPTION imperative-statement-1]
[NOT ON EXCEPTION imperative-statement-2]
[END-LOCKRECORD]

Explanation
file-name

This user-defined word is the name of the file that contains the record to be locked. You
specify the record to be locked with the ACTUAL KEY clause in the File Control Entry of
the Environment Division.
The file you specify for locking must be an open file that resides on the local host and has
a KIND of DISK. In addition the file must have

•

Sequential organization

•

Random access mode

•

The BUFFERSHARING file attribute value declared as SHARED or
EXCLUSIVELYSHARED

ON EXCEPTION imperative-statement-1

This clause specifies an alternate statement to be performed if the LOCKRECORD
statement is not successful.
NOT ON EXCEPTION

This clause specifies a statement to be performed after the record is successfully locked.

Details
The successful execution of the LOCKRECORD statement locks the record specified by
the value contained in the data item referenced by the ACTUAL KEY clause in the File
Control Entry of the Environment Division. The record remains locked until one of the
following actions occurs:

•

An UNLOCKRECORD statement is executed.

•

The file is closed.

•

The job is terminated.

8600 1518–307

7–25

LOCKRECORD Statement

If an existing locked record blocks the request, the system-wide default time-limit
FILELOCKTLIMIT is used to time out the request. Deadlocks are not detected.
Failure of the LOCKRECORD Statement
The LOCKRECORD statement can fail for any of the following reasons:

•

The specified file does not exist.

•

The specified file does not support locking (see the requirements for the file
described with the explanation of the file-name syntax).

•

The specified file is not open.

•

The specified file is not open for write operations.

•

The specified record key has an invalid or inconsistent value.

•

An existing locked record blocks the request and the resulting waiting period timed
out.

•

The number of locked records would exceed the system limit if the lock request
were successfully executed.

Security and Integrity Issues
The BUFFERSHARING attribute and record locking protect a file during concurrent
access only if all users of the file declare the file as shared (set the BUFFERSHARING
attribute to a value other than NONE) and then lock the record before using it.
If you open a file without setting a value for BUFFERSHARING, the value defaults to
NONE, for no sharing. Other users can open the same file with BUFFERSHARING set to
SHARED. Likewise, a user can open a file declared as SHARED while the same physical
file is not declared as SHARED. In both situations, the users who opened the file as
SHARED are not protected from operations performed by users who do not declare the
file as SHARED.
Locking a record prevents other users only from locking the same record. Other users
can still read and write a locked record. If the MUSTLOCK compiler option is TRUE, the
current user must lock a record before executing a WRITE statement.
The typical procedure for updating a record in a shared file is as follows:
1. Lock the desired record.
2. Read, modify, and write the record.
3. Unlock the record.

7–26

8600 1518–307

LOCKRECORD Statement

Related Information
The following table provides references to information related to this topic:

For information about . . .

Refer to . . .

The BUFFERSHARING file attribute

The File Attributes Programming
Reference Manual.

Unlocking a file

The UNLOCKRECORD statement.

I/O status codes resulting from error with
locking and unlocking files

Table 3-6.

8600 1518–307

7–27

MERGE Statement

MERGE Statement
The MERGE statement combines two or more identically sequenced files on a set of
specified keys. The merged records then become available, in merged order, to an output
procedure or to an output file. A MERGE statement can appear anywhere in the
Procedure Division, except in the declaratives portion. The syntax for the MERGE
statement is displayed on the following two pages.

Ú
¿
³ ä PURGE å
³
³ ³ ïïïïï ³
³
MERGE file-name-1 ³ ã RUN
â ON ERROR
³
ïïïïï
³ ³ ïïï
³
ïïïïï
³
³ æ END
ç
³
À
ïïï
Ù
ä
ä ASCENDING å
å
ã ON ã ïïïïïïïïï â KEY data-name-1 [ ,data-name-2 ] . . . â .
æ
æ DESCENDING ç
ç
ïïïïïïïïïï
Ú
³
ä
³
³ IS alphabet-name-1 [alphabet-name-2]
³
³
³ COLLATING SEQUENCE ã ä |FOR ALPHANUMERIC IS alphabet-name-1|
³
ïïïïïïïï ³ ã ³
ïïïïïïïïïïïï
|
³
³ æ |FOR NATIONAL IS alphabet-name-2
|
³
æ
ïïïïïïïï
À
Ú
¿
³
ä WORDS
å ³
³
³ ïïïïï
³ ³
³ MEMORY SIZE IS integer-1
ã CHARACTERS â ³
³ ïïïïïï
³ ïïïïïïïïïï ³ ³
³
æ MODULES
ç ³
À
ïïïïïïï
Ù
Ú
¿
³
ä WORDS
å ³
³ DISK SIZE IS integer-2 ã ïïïïï
â ³
³ ïïïï
æ MODULES ç ³
À
ïïïïïïï
Ù

7–28

. .

å
â
ç

å
³
³
â
³
³
ç

¿
³
³
³
³
³
³
³
Ù

8600 1518–307

MERGE Statement

[ RE-START IS integer-3 ]
ïïïïïïïï
ä
Ú
¿ å
³
³ LOCK
³ ³
³
³ ïïïï
³ ³
USING ã file-name-2 ³ PURGE
³ â . .
ïïïïï ³
³ ïïïïï
³ ³
³
³ RELEASE ³ ³
æ
À ïïïïïïï Ù ç
ä
Ú
³
³
³ OUTPUT PROCEDURE IS procedure-name-1 ³
³ ïïïïïï ïïïïïïïïï
³
³
Ú
¿À
³
ä
³ LOCK
³
³
³
³ ïïïï
³
ã
³
³ SAVE
³
³
³
³ ïïïï
³
³ GIVING
ã file-name-3 ³ NO REWIND ³
³ ïïïïïï
³
³ ïï ïïïïïï ³
³
³
³ CRUNCH
³
³
³
³ ïïïïïï
³
³
æ
³ RELEASE
³
æ
À ïïïïïïï
Ù

8600 1518–307

¿
ä THROUGH å
³
ã ïïïïïïï â procedure-name-2 ³
æ THRU
ç
³
ïïïï
Ù
å
³
³
³
â . . .
³
³
³
ç

å
³
³
³
³
³
³
â
³
³
³
³
³
³
ç

7–29

MERGE Statement

Explanation
file-name-1

This refers to the merge file, which is an internal file.
File-name-1 must be described in a sort-merge file description entry in the Data Division.
The size of the records contained in the file referred to by file-name-1 must not be larger
than the largest record described for file-name-3.
No more than one file-name from a multiple-file reel can appear in the MERGE
statement.
File-names cannot be repeated within the MERGE statement.
file-name-2
file-name-3

File-name-2, which may repeat, refers to the input file or files, which contain the records
to be merged.
File-name-3 refers to the output file.
These file names must be described in a file description entry in the Data Division, not in
a sort-merge file description entry.
The size of the records contained in the files referred to by file-name-2 cannot be larger
than the largest record defined for file-name-1.
No more than one file-name from a multiple-file reel can appear in the MERGE
statement.
File-names cannot be repeated within the MERGE statement.
No two files, except those in the GIVING clause, can be specified in the same
SAME/RECORD/SORT/SORT-MERGE AREA clause.
If the records in the files referred to by file-name-2 are not ordered by an ASCENDING or
DESCENDING KEY phrase, the results of the MERGE statement are undefined.
If the file referred to by file-name-3 is a relative file, the content of the relative KEY data
item after execution of the MERGE statement will indicate the last record returned to the
file.

7–30

8600 1518–307

MERGE Statement

data-name-1
data-name-2

These data-names are KEY data-names and are subject to the following rules:

•

The data items identified by these KEY data-names must be described in records
associated with file-name-1.

•

KEY data-names can be qualified.

•

The data items identified by these KEY data-names cannot be variable-length items
or long numeric data items.

If file-name-1 has more than one record description, the data items identified by these
KEY data-names can all be described within one of the record descriptions or in any
combination of record descriptions. It is not necessary to redescribe the KEY data-names
in each record description.
None of the data items identified by KEY data-names can be described by an entry that
either contains an OCCURS clause or is subordinate to an entry which contains an
OCCURS clause.
If file-name-3 references an index file, the first specification of data-name-1 must be
associated with an ASCENDING phrase, and the data item referred to by that data-name1 must occupy the same character positions in its record as the data item associated
with the prime record key for that file.
The KEY data-names are listed from left to right in the MERGE statement in order of
decreasing significance, without regard to how they are divided into KEY phrases; that is,
data-name-1 is the major key, data-name-2 is the next most significant key, and so on.
When, according to the rules for the comparison of operands in a relation condition, the
contents of all the KEY data items of one data record are equal to the contents of the
corresponding KEY data items of one or more other data records, the order of return of
these records follows the order of the associated input files as specified in the MERGE
statement. Therefore, all records associated with one input file are returned before the
return of records from another input file.
ON ERROR

The ON ERROR options enable you to have control over irrecoverable parity errors when
input/output procedures are not present in a program.
PURGE causes all records in a block that contains an irrecoverable parity error to be
dropped; processing is continued after a message displayed on the ODT gives the
relative position of the bad block in the file.
RUN causes the bad block to be used by the program and provides the same message
as defined for PURGE.
END causes a program termination; this is the default.

8600 1518–307

7–31

MERGE Statement

ASCENDING DESCENDING

The ASCENDING and DESCENDING phrases have the following effects:

•

If you specify the ASCENDING phrase, the merged sequence will be from the lowest
value of the contents of the data items identified by the KEY data-names to the
highest value, according to the rules for comparison of operands in a relation
condition.

•

If you specify the DESCENDING phrase, the merged sequence will be from the
highest value of the contents of the data items identified by the KEY data-names to
the lowest value, according to the rules for comparison of operands in a relation
condition.

COLLATING SEQUENCE

Alphabet-name-1 references an alphabet that defines an alphanumeric collating
sequence.
Alphabet-name-2 references an alphabet that defines a national collating sequence.
The alphanumeric collating sequence that applies to the comparison of key data items for
class alphabetic and class alphanumeric, and the national collating sequence that applies
to the comparison of key data items of class national, are determined separately at the
beginning of the execution of the MERGE statement in the following order of
precedence:
1. The collating sequence is established by the COLLATING SEQUENCE phrase, if
specified, in this MERGE statement.
The collating sequence associated with alphabet-name-1 applies to key data items of
class alphabetic and alphanumeric; the collating sequence associated with alphabetname-2 applies to key data items of class national.
2. The collating sequences are established as the program collating sequences.
MEMORY SIZE IS integer-1

MEMORY SIZE is a guideline for allocating MERGE memory area, and it takes
precedence over the same clause in the OBJECT-COMPUTER paragraph. It can be
allocated as MODULES, WORDS, or CHARACTERS. If MEMORY SIZE is not specified,
either in the OBJECT-COMPUTER paragraph or in the MERGE statement, a default value
of 12,000 words is assumed.
DISK SIZE IS integer-2

DISK SIZE is a guideline for allocating MERGE disk area, and it takes precedence over
the same clause in the OBJECT-COMPUTER paragraph. It can be allocated as WORDS
or MODULES. If DISK SIZE is not specified, either in the OBJECT-COMPUTER paragraph
or in the MERGE statement, a default value of 900,000 words is assumed. One module
of disk is equivalent to 1.8 million words of disk.

7–32

8600 1518–307

MERGE Statement

RE-START IS integer-3

The RE-START specification enables the sort intrinsic to resume processing at the most
recent checkpoint after discontinuation of a program during the merge. The program
restores and maintains variables, files, and everything that is necessary for the program
to continue from the point of interruption.
The restart capability is implemented only for disk merges and sorts.
Select the type of RE-START action to be performed by choosing one of the following
values for integer-3:
0

No restart capability.

Restart previous sort. The prior uncompleted sort must have been
capable of a restart.

Allow restartable sort.

4 or 6

Allow a restartable sort and enable extensive error recovery from I/O
errors.

Restart previous sort if all input has been received. The prior
uncompleted sort must have been capable of a restart.

Allow restartable sort after all input is received.

12 or 14

Options 4 and 10.

Refer to the MERGE section in the System Software Utilities Operations Reference
Manual for more details on the RE-START capability of MERGE.
USING

You can specify up to eight file-names in the USING phrase.
OUTPUT PROCEDURE

Procedure-name-1 represents the name of an output procedure.
The OUTPUT PROCEDURE phrase must consist of one or more paragraphs or sections
that appear in a source program and do not form a part of any other procedure.
To make merged records available for processing, the output procedure must include the
execution of at least one RETURN statement. Control cannot be passed to the output
procedure except when a related SORT or MERGE statement is being executed. The
output procedure can consist of any procedures needed to select, modify, or copy the
records that are being returned, one at a time in merged order, from file-name-1.

8600 1518–307

7–33

MERGE Statement

Restrictions
The restrictions on the procedural statements in the output procedure are as follows:

•

The output procedure cannot contain any transfers of control to points outside the
output procedure; ALTER, GO TO, and PERFORM statements in the output
procedure are not permitted to refer to procedure-names outside the output
procedure. Statements that cause an implied transfer of control to declaratives are
allowed.

•

The output procedures cannot contain any SORT, MERGE, or RELEASE statements.

•

The remainder of the Procedure Division cannot contain any transfers of control to
points inside the output procedures; ALTER, GO TO, and PERFORM statements in
the remainder of the Procedure Division are not permitted to refer to procedurenames within the output procedures.

If you specify an output procedure, control passes to it during execution of the MERGE
statement. The compiler inserts a return mechanism at the end of the last paragraph or
section in the output procedure. When control passes the last statement in the output
procedure, the return mechanism provides for termination of the merge, and then passes
control to the next executable statement after the MERGE statement. Before entering
the output procedure, the merge procedure reaches a point at which it can select the
next record in merged order when requested. The RETURN statements in the output
procedure are the requests for the next record.
During execution of the output procedure, no statement can be executed that
manipulates the file referred to by or accesses the record area associated with
file-name-2.
THRU
THROUGHThe keywords THRU and THROUGH are interchangeable.
GIVINGIf you specify the GIVING phrase, all the merged records are automatically

written on file-name-3 as the implied output procedure for the MERGE statement. At the
start of execution of the MERGE statement, the file referred to by file-name-3 cannot be
in the open mode. You can specify up to eight file names in the GIVING phrase.

7–34

8600 1518–307

MERGE Statement

LOCK
PURGE
RELEASE
SAVE
NO REWIND
CRUNCH

These options enable you to specify the type of close procedure to use on a file.
You can specify the LOCK, PURGE, and RELEASE options for file-name-2 (input files
specified by the USING phrase).
You can specify SAVE, LOCK, NO REWIND, CRUNCH, and RELEASE options for filename-3 (output file specified by the GIVING phrase).
For a description of these options, refer to “CLOSE Statement” in this section.

Details
The MERGE statement will merge all records contained in file-name-2. The files
referenced in the MERGE statement cannot be open at the time the MERGE statement
is executed. These files are automatically opened and closed by the merge operation
with all implicit functions performed, such as the execution of any associated USE
procedures. The terminating function for each file is performed as if a CLOSE statement,
without optional phrases, had been executed.
If a record in the file referred to by file-name-2 (the file to merge) has fewer character
positions than the record length of the file referred to by file-name-1 (the base file), then
the record from file-name-2 is space-filled on the right, beginning with the first character
position after the last character in the record, when the record is released to the file
referred to by file-name-1.
During the execution of any USE AFTER EXCEPTION procedure implicitly invoked by the
MERGE statement, no statement can be executed that manipulates the file referenced
by, or accesses the record area associated with, file-name-2 or file-name-3.
If the OUTPUT PROCEDURE clause is used, the GIVING clause cannot be used. If the
GIVING clause is used, the OUTPUT PROCEDURE clause cannot be used.
Refer to “SAME Clause” under “Input-Output Control Entry Format 3: Sort-Merge” in
Section 3.
Refer to “File Description Entry” in Section 4 for information on how to describe a merge
file.
Refer to “Sort and Merge Operations” in Section 5 for conceptual information on sort
and merge operations.
Refer to “CLOSE Statement” in Section 6 and “SORT Statement” in Section 8 for a
description of close options and sort operations, respectively.

8600 1518–307

7–35

MERGE Statement

Example
MERGE File-abc ON ASCENDING KEY Name, Number1
USING File-def, File-ghi, File-jkl
OUTPUT PROCEDURE IS Routine-1 THRU Routine-8.

The MERGE statement in this example merges the three files File-def, File-ghi, File-jkl
into File-abc using the output procedures Routine-1 through Routine-8. After execution of
the output procedures, control of the program will pass to the next executable statement
after this sentence.
For another example of the MERGE statement, refer to “Example” under “Sort and
Merge Operations” in Section 5.

7–36

8600 1518–307

MOVE Statement

MOVE Statement
The MOVE statement transfers data from one data area to one or more data areas.
This statement is fully supported in the TADS environment.

Format

Use

Format 1

This format transfers data to one or more data areas.

Format 2

The MOVE CORRESPONDING format transfers selected
items in identifier-1 to selected items in identifier-2. This
format transfers items having the same name as one in the
receiving field to that corresponding field.

Format 3

This format transfers selected bit ranges between two
BINARY data items.

Format 1: MOVE Data

MOVE
ïïïï

ä
³
³
³
ã
³
³
³
æ

å
³
³
literal-1
³
â
file-attribute-identifier ³
³
task-attribute-identifier ³
ç
identifier-1

TO { identifier-2 } . . .
ïï

This format is supported in the TADS environment.

Explanation
In this format, the item before the word TO represents the sending area. The item after
the word TO represents the receiving area.
identifier-1
literal-1
identifier-2

Literal-1 or the data item referred to by identifier-1 (the sending field) represents the data
that is to be moved to the data item referred to by identifier-2 (the receiving field).
Literal-1 can be a long numeric literal.
Identifier-1 and identifier-2 can reference long numeric data items. If both identifiers
reference long numeric data items, the data items must be of the same size and usage.

8600 1518–307

7–37

MOVE Statement

If identifier-2 references a long numeric data item, then literal-1 must be the same size.
You can move an appropriate figurative constant or the value 0 (zero) to a long numeric
data item.
file-attribute-identifier
task-attribute-identifier

These identifiers represent the attribute value that you want to move to the data area
defined by identifier-2. You can then use the data item in a number of Procedure Division
statements to monitor or query the attribute value. For more information about file
attributes, refer to Section 10 of this manual and the File Attributes Programming
Reference Manual. For details about task attributes, refer to Section 11 of this manual
and the Task Attributes Programming Reference Manual.

Details
The MOVE statement transfers data according to the rules of editing as described under
the heading “Editing Rules” under “PICTURE Clause” in Section 4.
How the MOVE Statement Is Evaluated
If identifier-1 has a subscript or a reference modifier or is a function identifier, the
subscript, reference modifier, or function-identifier is evaluated only once. The evaluation
occurs immediately before data is moved to the first of the receiving operands. The rules
that apply to identifier-2 apply to the other receiving areas as well.
An indexed data item must not appear as an operand of a MOVE statement.
Any length or subscripting associated with identifier-2 is evaluated immediately before
the data is moved to the respective data item.
The evaluation of the length of identifier-1 or identifier-2 can be affected by the
DEPENDING ON phrase of the OCCURS clause. Refer to “OCCURS Clause” in Section 4
for more information.
The following MOVE statement yields the same result as the three subsequent MOVE
statements:
MOVE a (b) TO b, c (b)
MOVE a (b) TO temp
MOVE temp TO b
MOVE temp TO c (b)
In this case, temp is an intermediate data item provided by the compiler. Refer to
“Intermediate Data Item” in Section 5 for more information.

7–38

8600 1518–307

MOVE Statement

Categories of Elementary Data Items
An elementary move is any move in which the receiving operand is an elementary item
and the sending operand is either a literal or an elementary item.
Elementary items must belong to one of the following categories:

•

Alphabetic

•

Alphanumeric

•

Alphanumeric-edited

•

Boolean

•

National

•

National-edited

•

Numeric

•

Numeric-edited

Refer to “PICTURE Clause” in Section 4 for explanations of each category.
Table 7–1 shows the categories in which literals, figurative constants, and intrinsic
functions belong.
Table 7–1. Categories of Elementary Data Items

Elementary Items

Category

Numeric literals

Numeric

Nonnumeric literals

Alphanumeric

National literals

National

Boolean literals

Boolean

Figurative constant ZERO (ZEROS, ZEROES)

Numeric, when moved to a numeric or a
numeric-edited item
National, when moved to a national or
national-edited item
Alphanumeric, in all other cases

Figurative constant SPACE (SPACES)

National, when moved to a national or
national-edited item
Alphabetic, in all other cases

Figurative constants when moved to a
national or national-edited item

National

Figurative constants in general

Alphanumeric

Intrinsic Functions

Alphanumeric or numeric, depending
upon the definition of the function (see
Section 7 for details)

8600 1518–307

7–39

MOVE Statement

Valid MOVE Actions
Table 7–2 summarizes valid MOVE actions between categories of data items.
Table 7–2. Valid MOVE Actions

Category of Receiving Data Item

Boolean

National or
Nationaledited

Numeric
Integer or
Numeric
Noninteger or
NumericEdited

Yes

AlphanumericEdited

Yes

Boolean

Yes

National

Yes

National-edited

Yes

Numeric Integer

Yes

Numeric
Noninteger

Yes

Numeric-Edited

Yes

Alphabetic

Alphanumeric
or
Alphanumeric
-Edited

Alphabetic

Yes

Alphanumeric

Category of
Sending Data
Item

Note: If the CCSVERSION clause is specified in the program, the national or nationaledited data items are represented internally as contiguous 8-bit characters in the national
character set. In this case, MOVE operations between the following categories are
permitted: alphabetic, alphanumeric, alphanumeric-edited, national, and national-edited.
Alphanumeric and Alphanumeric-Edited Moves
When the receiving item is alphanumeric-edited or alphanumeric, alignment and any
necessary space-filling takes place according to the rules presented under “Standard
Alignment Rules” in this section.
If the usage of the sending operand is different from that of the receiving operand,
conversion of the sending operand to the internal representation of the receiving operand
takes place.

7–40

8600 1518–307

MOVE Statement

In addition, note the following results of specific MOVE operations when the receiving
field is alphanumeric or alphanumeric-edited:

When the receiving operand is
alphanumeric or alphanumeric-edited,
and the sending operand is . . .

Then . . .

Signed numeric

The operational sign is not moved.
If the operational sign occupies a separate
character position, the character is not
moved. In this case, the size of the sending
operand is considered to be one less than its
actual size in terms of standard data format
characters. Refer to “SIGN Clause” in
Section 4 for more information.

Numeric-edited

De-editing does not take place.

Numeric

All digit positions specified with the
PICTURE symbol P have the value of zero
and are counted in determining the size of
the sending operand.

National and National-Edited Moves
If the receiving item is national or national-edited, the following rules apply:

•

Alignment and any necessary space-filling takes place according to the standard
alignment rules. A discussion of the standard alignment rules is included at the end
of the discussion of the MOVE statement.

•

The sending operand must be described as national or national-edited.

Numeric and Numeric-Edited Moves
When the receiving item is numeric or numeric-edited alignment is by decimal point. Any
necessary zero-filling takes place according to the standard alignment rules, except
where zeros are replaced because of editing requirements. For more information, refer to
the paragraphs headed “Standard Alignment Rules” under “Format 2: MOVE
CORRESPONDING” in this section.
When the receiving item is signed numeric, the sign of the sending operand is placed in
the receiving item. Conversion of the representation of the sign takes place as
necessary. Refer to “SIGN Clause” in Section 4 for more information.
If the receiving item is unsigned numeric, the absolute value of the sending operand is
moved, and no operational sign is generated for the receiving item.
When the sending operand is REAL or DOUBLE, and the receiving item is DISPLAY,
COMP, or BINARY, precision can be lost if the sending operand represents a value that
the machine must approximate. For more information, refer to USAGE IS REAL and
USAGE IS DOUBLE of Data Description Entry Format 1 in Section 4.

8600 1518–307

7–41

MOVE Statement

In addition, note the following results of specific MOVE operations when the receiving
field is numeric or numeric-edited:

When the receiving operand is
numeric or numeric-edited, and
the sending operand is . . .

Then . . .

Numeric-edited

De-editing is applied to establish the unedited
numeric value of the operand (which can be
signed). The unedited numeric value is moved to
the receiving field.

Unsigned

A positive sign is generated for the receiving
item.

Alphanumeric

Data is moved as if the sending operand were
described as an unsigned numeric integer. If the
alphanumeric item contains characters other
than the digits 0 through 9, the result in the
receiving field is unpredictable.
When the figurative constants HIGH-VALUE,
LOW-VALUE, or ALL "literal" are moved to data
items of usage COMP or DISPLAY and the
COMPATIBILITY suboption FIGCONST is set,
the specified values are copied so that the entire
field is filled into the data area, including any
decimal places. No conversion of the data to
valid numeric values occurs. Moves to
COMPUTATIONAL fields strip the zone before
the move operation occurs. A move of a HIGHVALUES or LOW-VALUES figurative constant to
an item defined as usage COMP will result in a
syntax error when the $COMPATIBILITY suboption FIGCONST is reset.
A move of a HIGH-VALUE, LOW-VALUE,
QUOTE, nonnumeric literal, ALL nonnumeric
literal, symbolic character, or ALL symbolic
character to an item defined as usage
CONTROL-POINT, DOUBLE, EVENT, INDEX,
LOCK, REAL, or TASK results in a syntax error.

Alphabetic Moves
If the receiving item is alphabetic, justification and any necessary space filling takes place
according to the standard alignment rules, which are described near the end of the
discussion of the MOVE statement.
Unless other data-item categories are specified in the MOVE statement, all moves are
treated as alphanumeric-to-alphanumeric elementary moves. However, data is not
converted from one internal representation to another. In such a move, the receiving area
will be filled without consideration for the individual elementary or group items contained
within either the sending or receiving area. Refer to “OCCURS Clause” in Section 4 for a
description of the exceptions.

7–42

8600 1518–307

MOVE Statement

Examples
IDENTIFICATION DIVISION.
PROGRAM-ID. PROCESS-TASK-CALLED.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 MY-NAME
PIC X(45).
PROCEDURE DIVISION.
MAIN SECTION.
MAIN-PARA.
MOVE ATTRIBUTE NAME OF MYSELF TO MY-NAME.
DISPLAY MY-NAME.
STOP RUN.
The preceding example shows how to use the MOVE and DISPLAY statements to
display the current value of the NAME task attribute for the process associated with the
system-declared task variable, MYSELF. (MYSELF refers to the process itself.)
01 A PIC X(30).
01 B PIC $99.99.
MOVE B TO A.
Because the receiving data item is alphanumeric, the value of B is left-justified in the
receiving character positions, with space-fill to the right. Because the sending field is
numeric-edited, de-editing does not occur.
The following is an example of a MOVE statement that transfers data into a numericedited receiving item:
01 A PIC $99.99.
01 B PIC 99V99.
MOVE B TO A.
Because the receiving data item is numeric-edited, the value of B is aligned by decimal
point in the receiving character positions, with zero-fill or truncation at either end, as
required.
The following is an example of a MOVE statement with de-editing:
01 A PIC $99.99.
01 B PIC 99V99.
MOVE A TO B.
If A contains the value $19.87, B will contain the value 1987 after the MOVE.

8600 1518–307

7–43

MOVE Statement

The following is an example of a MOVE statement with the DEPENDING ON phrase in
the OCCURS clause:
77 D
PIC 99
01 GRP.
02 TBL PIC X(10) OCCURS 10 TO 20 TIMES
DEPENDING ON D.
01 GRP-1 PIC X(300).
MOVE GRP TO GRP-1.
The result of the MOVE statement depends on the value of D.

Format 2: MOVE CORRESPONDING

MOVE
ïïïï

ä CORRESPONDING å
ã ïïïïïïïïïïïïï â
æ CORR
ç
ïïïï

identifier-1 TO {identifier-2}...
ïï

This format is supported in the TADS environment.

Explanation
CORRESPONDING
CORR

When you specify MOVE CORR, the results are the same as if you had referred to each
pair of corresponding identifiers in separate MOVE statements. CORRESPONDING and
CORR are synonymous.
The paragraphs headed “CORRESPONDING Phrase” in this section explain the rules that
govern a Format 2 MOVE statement.
identifier-1
identifier-2

All identifiers used with the CORRESPONDING phrase must be group items.

7–44

8600 1518–307

MOVE Statement

Details
CORRESPONDING Phrase
If the CORRESPONDING phrase is used, selected items in identifier-1 are moved to
selected items in identifier-2, according to the rules in the following paragraphs. In these
paragraphs, the terms D1 and D2 represent identifiers that refer to group items. A pair of
data items, one from D1 and one from D2, correspond if the following conditions exist:

•

Corresponding data items in D1 and D2 are not designated by the keyword FILLER,
and have the same data-name and the same qualifiers up to, but not including, D1
and D2.

•

At least one of the data items is an elementary data item, and the resulting move is
valid according to the rules for the MOVE statement.

•

The description of D1 and D2 does not contain level-number 66, 77, or 88, or the
USAGE IS INDEX clause.

•

A data item is ignored if it is subordinate to D1 or D2 and contains a REDEFINES,
RENAMES, OCCURS, or USAGE IS INDEX clause. Also ignored are those data items
subordinate to the data item that contains the REDEFINES, OCCURS, or USAGE IS
INDEX clause.

•

D1 and D2 cannot be reference modified.

•

The name of each data item that satisfies the conditions in the previous paragraphs
must be unique after application of the implied qualifiers.

Standard Alignment Rules
The standard rules for positioning data in an elementary item depend on the category of
the receiving item. The following table describes how sending data is aligned after it is
moved to the receiving data field. Note that these rules are modified if the JUSTIFIED
clause is specified for the receiving item. (Refer to the paragraphs headed “JUSTIFIED
Clause” under “Data Description Entry Format 1” in Section 4 for more information.)

If the receiving
data item is . . .

Then the moved data is aligned . . .

Numeric

By decimal point.
Zero-fill or truncation occurs on either end, as
required.
When an assumed decimal point is not explicitly
specified, the data item is treated as if it has an
assumed decimal point immediately following its
rightmost digit and is aligned as stated in the
preceding phrase.

Numeric-edited

By decimal point
Zero-fill or truncation occurs at either end, as required.
This rule is true except where editing requirements
cause replacement of the leading zeros.

8600 1518–307

7–45

MOVE Statement

If the receiving
data item is . . .

Then the moved data is aligned . . .

Alphanumeric (other than a
numeric-edited data item),
alphanumeric-edited, or
alphabetic

At the leftmost character position in the data item.

National or national-edited

At the leftmost character position in the data item.

Space-fill or truncation to the right can occur, as
required

Space-fill with national space characters or truncation
to the right can occur as required.
Valid MOVE actions between
categories of data items

Table 7–2

Related Information
The following table provides references for more information related to this statement:

For information about . . .

Refer to . . .

The alignment of receiving items

“JUSTIFIED Clause” in Section 4

Declaring long numeric data items

“PICTURE Clause” in Section 4.

Filling the receiving area in a MOVE
action

“OCCURS Clause” in Section 4

The categories of elementary data
items

“PICTURE Clause” in Section 4

Signed data items

“SIGN Clause” in Section 4

Intermediate data items

“Intermediate Data Item” in Section 5

Example
03 GRP-1
05 A
05 C
05 D
05 X

03 GRP-2
05 Z
05 A
05 D
05 E
05 X

PROCEDURE DIVISION.
MOVE CORR GRP-1 TO GRP-2
In this example, items A, D, and X from GRP-1 are moved to the corresponding (A, D,
and X) items in GRP-2. Each data item moved must be an elementary item at the same
level.

7–46

8600 1518–307

MOVE Statement

Format 3: MOVE Selected Bits
MOVE
ïïïï
[
ï

identifier-1

TO
ïï

identifier-2

ä literal-1
å
ã
â
æ arithmetic-expression-1 ç
ä literal-2
å
: ã
â
ï æ arithmetic-expression-2 ç

:
ï

ä literal-3
å
ã
â
æ arithmetic-expression-3 ç

]
ï

This format is supported in the TADS environment.

Explanation
identifier-1
identifier-2

The data item referred to by identifier-1 represents the sending area. The data item
referred to by identifier-2 represents the receiving area. Both data items must be singleprecision BINARY data items (declared as USAGE IS BINARY) or single-precision REAL
data items (declared as REAL). Both data items must have a size of 11 digits or less).
literal-1
arithmetic-expression-1

This represents the location in identifier-1 at which the transfer begins. This is referred to
as the source bit location.
literal-2
arithmetic-expression-2

This represents the location in identifier-2 at which the transfer begins. This is referred to
as the destination bit location.
literal-3
arithmetic-expression-3

This represents the number of bits to be transferred.

8600 1518–307

7–47

MOVE Statement

Details
Starting with the bit value in the source bit position, data is moved from identifier-1 to the
destination bit position of identifier-2. Succeeding bits are transferred until the number of
bits specified have been transferred.
The bit positions in a single-precision BINARY data item are numbered from left to right,
with the leftmost bit position assigned the number 47, and the rightmost bit position
assigned the number 0. Therefore, only values ranging from 0 to 47 are valid for source
and destination bit positions.

Examples
MOVE A-AND-B-BOTH TO A-ONLY [39:19:20].
MOVE A-AND-B-BOTH TO B-ONLY [19:19:20].
These examples unpack a BINARY data item that contains two 20-bit fields.
MOVE B-ONLY TO A-AND-B-BOTH.
MOVE A-ONLY TO A-AND-B-BOTH [19:39:20].
These examples repack the fields unpacked in the previous example.

7–48

8600 1518–307

MULTIPLY Statement

MULTIPLY Statement
The MULTIPLY statement multiplies numeric data items and stores the result.
The composite length of the operands in successive MULTIPLY operations is based on a
hypothetical data item resulting from the superimposition of all receiving data items of a
given statement on their decimal points. This length cannot exceed 23 decimal digits.
This statement is partially supported in the TADS environment. Supported syntax is
noted in this section.
The MULTIPLY statement has two formats:

Format

Use

Format 1

This format multiplies elementary numeric items.

Format 2

This format multiplies elementary numeric items. The
operands of the GIVING phrase must be either elementary
numeric items or numeric-edited items.

Format 1: MULTIPLY
MULTIPLY
ïïïïïïïï

ä identifier-1 å
ã
â
æ literal-1
ç

BY
ïï

{ identifier-2

[ ROUNDED ] } . . .
ïïïïïïï

[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-MULTIPLY ]
ïïïïïïïïïïïï

TADS Syntax
MULTIPLY
ïïïïïïïï

ä identifier-1 å
ã
â
æ literal-1
ç

BY
ïï

{ identifier-2

[ ROUNDED ] } . . .
ïïïïïïï

[ END-MULTIPLY ]
ïïïïïïïïïïïï

8600 1518–307

7–49

MULTIPLY Statement

Explanation
identifier-1
identifier-2
literal-1

In this format, each identifier must refer to an elementary numeric item. Each literal must
be a numeric literal.
ROUNDED

The word ROUNDED causes the value of the result to be rounded. Refer to “ROUNDED
Phrase” in Section 5 for more information.
ON SIZE ERROR imperative-statement-1
NOT ON SIZE ERROR imperative-statement-2

The options ON SIZE ERROR and NOT ON SIZE ERROR enable you to specify an action
to be taken if an error in the size of the result is or is not encountered. Refer to “SIZE
ERROR Phrase” in Section 5 for more information.
END-MULTIPLY

This phrase delimits the scope of the MULTIPLY statement.

Details
The value of the operand that precedes the word BY is stored in a temporary data item.
The value of this data item is multiplied by the value of identifier-2. The product of the
multiplication replaces the value of identifier-2. The temporary data item is multiplied by
each successive occurrence of identifier-2 in the left-to-right order in which identifier-2 is
specified.

Example
MULTIPLY A BY B ON SIZE ERROR PERFORM ERROR-PARA.
In this example, the value of A is multiplied by the value of B. If the result creates an ON
SIZE ERROR, the compiler will execute the ERROR-PARA and the value of B remains
unchanged.

7–50

8600 1518–307

MULTIPLY Statement

Format 2: MULTIPLY . . . GIVING
MULTIPLY
ïïïïïïïï

ä identifier-1 å
ã
â
æ literal-1
ç

BY
ïï

ä identifier-2 å
ã
â
æ literal-2
ç

GIVING { identifier-3 [ ROUNDED ] } . . .
ïïïïïï
ïïïïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-MULTIPLY ]
ïïïïïïïïïïïï

TADS Syntax
MULTIPLY
ïïïïïïïï

ä identifier-1 å
ã
â
æ literal-1
ç

BY
ïï

ä identifier-2 å
ã
â
æ literal-2
ç

GIVING { identifier-3 [ ROUNDED ] } . . .
ïïïïïï
ïïïïïïï
[ END-MULTIPLY ]
ïïïïïïïïïïïï

Explanation
Refer to Format 1 for descriptions of the following phrases: ROUNDED, ON SIZE
ERROR, NOT ON SIZE ERROR, and END-MULTIPLY.
identifier-1
identifier-2
identifier-3
literal-1

Each identifier preceding the word GIVING must refer to an elementary numeric item.
Each identifier following the word GIVING must refer to either an elementary numeric
item or an elementary numeric-edited item. Each literal must be a numeric literal.
GIVING

Using the GIVING phrase in this format enables you to multiply data items and to store
the result in a data item referred to by identifier-3.

8600 1518–307

7–51

MULTIPLY Statement

Details
The values of the operands that precede the word GIVING are multiplied. The result is
stored in the data items referred to by each identifier-3.

Related Information
The following table provides references for additional information related to this
statement:

For information about . . .

Refer to . . .

The ROUNDED phrase

Section 5

The ON SIZE ERROR and NOT ON
SIZE ERROR options

The SIZE ERROR Phrase in Section 5

The MULTIPLY statement and rules
regarding this statement

The following headings in Section 5:
“Arithmetic Expressions”
“Allowed Combinations of Elements”
“General Rules for Arithmetic Statements”
“Multiple Results in Arithmetic
Statements”
“Conditional Statements and Sentences”
“Statement Scope Terminators”
“Delimited Scope Statements”

7–52

8600 1518–307

MULTIPLY Statement

Examples
MULTIPLY A BY B GIVING C ROUNDED.
In this example, the value of A is multiplied by the value of B and the result is stored in C.
The value of C is rounded.
Results of COBOL ANSI-74 and COBOL ANSI-85 are the same with overlapping fields
and the same data description. The following examples show COBOL ANSI-74 and
COBOL ANSI-85 programs with overlapping operands.
COBOL ANSI-74 Program
IDENTIFICATION DIVISION.
PROGRAM-ID. LEESTEST.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-MISC-VALUES.
03 C PIC 9(03).
03 CB REDEFINES C.
05 FILLER PIC X(01).
05 D
PIC 9(02).
03 A PIC 9(03) VALUE 000.
03 B REDEFINES A
PIC 9(03).
PROCEDURE DIVISION.
MOVE-IT.
MOVE 5 TO D, A.
MOVE 4 TO C.
MULTIPLY C BY D GIVING C.
DISPLAY C.
MULTIPLY A BY B GIVING A.
DISPLAY A.
STOP RUN.
Results
RUN
#RUNNING 7203
#7203 DISPLAY:016
#7203 DISPLAY:025
#ET

8600 1518–307

COBOL ANSI-85 Program
IDENTIFICATION DIVISION.
PROGRAM-ID. LEESTEST.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-MISC-VALUES.
03 C PIC 9(03).
03 CB REDEFINES C.
05 FILLER PIC X(01).
05 D
PIC 9(02).
03 A PIC 9(03) VALUE 000.
03 B REDEFINES A
PIC 9(03).
PROCEDURE DIVISION.
MOVE-IT.
MOVE 4 TO D, B.
MOVE 5 TO C.
MULTIPLY C BY D GIVING D.
DISPLAY D.
MULTIPLY A BY B GIVING B.
DISPLAY B.
STOP RUN.
Results

RUN
#RUNNING 7217
#7217 DISPLAY:25
#7217 DISPLAY:016
#ET

(D)
(B)

7–53

OPEN Statement

OPEN Statement
The OPEN statement initiates the processing of files. It also performs checking and/or
writing of labels and other input-output operations.
There are three types of file organization in COBOL: sequential, relative, and indexed.
There are three types of file access in COBOL: sequential, random, and dynamic. The
files referenced in the OPEN statement need not all have the same organization or
access. If you specify more than one file-name in an OPEN statement, the result is the
same as if you had specified multiple OPEN statements.
For information on file attributes, file organization, and file access modes, refer to Section
10. Also refer to “CLOSE Statement” in Section 6 and “MERGE Statement” and “READ
Statement” in this section.
This statement is partially supported in the TADS environment. Applicable exclusions are
noted in this section.
ä
³
³
³
³
³
³
³
OPEN ã
ïïïï ³
³
³
³
³
³
³
³
³
³
æ

INPUT
ïïïïï

ä
³
³
ã file-name-1
³
³
æ

Ú
³
³
³
³
³
À

WITH LOCK
ïïïï
REVERSED
ïïïïïïïï
WITH NO REWIND
ïï ïïïïïï

¿
³
³
³
³
³
Ù

å
³
³
â . . .
³
³
ç

OUTPUT { file-name-2 [ WITH NO REWIND ]
} . . .
ïïïïïï
ïï ïïïïïï
I-O { file-name-3
[ WITH LOCK ] } . . .
ïïï
ïïïï
EXTEND { file-name-4
[ WITH LOCK ] } . . .
ïïïïïï
ïïïï
AVAILABLE { FILE-NAME-5 } . . .
ïïïïïïïïï
OFFER { file-name-6 } . . .
ïïïïï
[ WITH ] NO WAIT { file-name-7 } . . .
ïï ïïïï

å
³
³
³
³
³
³
³
â . . .
³
³
³
³
³
³
³
³
³
³
ç

This format is supported in the TADS environment.

7–54

8600 1518–307

OPEN Statement

Explanation
The REVERSED, NO REWIND, and EXTEND options apply only to sequential files.
file-name-1
file-name-2
file-name-3
file-name-4

The file description entry for files must be equivalent to that used when the file was
created.
If you specify more than one file-name in an OPEN statement, the result is the same as if
you had written separate OPEN statements for each file.
The minimum and maximum record sizes for a file are established at the time the file is
created and cannot be subsequently changed.
file-name-5
file-name-6
file-name-7

These file-names must be names of port files. File-name-1 through file-name-4 cannot be
names of port files.
WITH LOCK

This phrase applies to mass-storage files only and is ignored if applied to other types of
files.
OPEN WITH LOCK on a mass-storage file denies the use of that file to all other programs
in the mix. When you execute an OPEN WITH LOCK, the following occurs:

•

If the specified file is already in the open mode, the program is suspended, and waits
for exclusive availability of the file.

•

If the specified file is not currently in an open mode, the file is opened.

NO REWIND
REVERSED

These options can be used only with the following:

•

Sequential reel/unit files with a single reel/unit

•

Sequential files that are wholly contained in a single reel of tape within a multiple-file
tape environment

These phrases will be ignored if they do not apply to the storage medium on which the
file resides.

8600 1518–307

7–55

OPEN Statement

If the medium on which the file resides permits rewinding, the following rules apply:

•

If you do not specify REVERSED, EXTEND, or NO REWIND, execution of the OPEN
statement causes the file to be positioned at its beginning.

•

If you specify NO REWIND, execution of the OPEN statement does not cause the
file to be repositioned; that is, the file must already be positioned at the beginning
before the execution of the OPEN statement.

•

If you specify REVERSED, execution of the OPEN statement positions the file at its
end.

If you specify REVERSED, the last record of the file is the first available record.
INPUT

For sequential or relative files being opened with the INPUT phrase, the OPEN statement
sets the current record pointer to the first record currently existing within the file. If the
file does not contain any records, the current record pointer is set such that the next
executed READ statement for the file will result in an AT END condition.
When you open a sequential or relative file with the INPUT phrase, the file position
indicator is set to 1.
When you open an indexed file with the INPUT phrase, the file position indicator is set to
the characters that have the lowest ordinal position in the collating sequence associated
with the file, and the prime record key is established as the key of reference.
If you open an optional file with the INPUT phrase and the file is unavailable, the OPEN
statement sets the file position indicator to indicate that an optional input file is not
present.
OUTPUT

Upon successful execution of an OPEN statement with the OUTPUT phrase specified, a
file is created. At that time, the associated file does not contain any data records.
When you open a sequential file with the OUTPUT option, all files on the associated
multiple-file reel whose position numbers are less than the position number of the file
being opened must already exist on the reel. In addition, there cannot be a file with a
position number greater than the position number of the file being opened.I-O
For files being opened with the I-O phrase, the OPEN statement sets the current record
pointer to the first record currently existing within the file. If the file does not contain any
records, the current record pointer is set such that the next executed READ statement
for the file will result in an AT END condition.
The OPEN statement with the I-O phrase must reference a file that supports the input
and output operations allowed for that file organization (sequential, relative, or indexed).
The execution of the OPEN statement with the I-O phrase places the referenced file in
the open mode for both input and output.
Multiple files located on disk pack or tape are allowed for sequential I-O.

7–56

8600 1518–307

OPEN Statement

The I-O phrase can be used only for mass-storage files and port files. The I-O phrase
permits the opening of a mass-storage file for both input and output operations. Because
this phrase implies the existence of the file, it cannot be used if the mass-storage file is
being initially created.
When you open a sequential or relative file with the INPUT phrase, the file position
indicator is set to 1.
When you open an indexed file with the I-O phrase, the file position indicator is set to the
characters that have the lowest ordinal position in the collating sequence associated with
the file, and the prime record key is established as the key of reference.
The execution of the OPEN statement causes the value of the I-O status associated with
the file-name to be updated.
For an optional file that is unavailable, the successful execution of an OPEN statement
with an I-O phrase creates the file as if the following statements had been executed:
OPEN OUTPUT file-name.
CLOSE file-name.
EXTEND

This option enables you to write additional records to the end of a sequential file.
The EXTEND option can be used only with the following:

•

Sequential reel/unit files with one reel/unit

•

Files for which the LINAGE clause has not been specified

This option requires file-name-4 to be a previously created file (that is, already in the disk
or pack directory, or on tape).
When you specify the EXTEND option, execution of the OPEN statement positions the
file immediately after the last logical record for that file (that is, the last record written in
the file). Subsequent WRITE statements that reference the file will add records to the file
as though the file had been opened with the OUTPUT phrase.
For an optional file that is unavailable, the successful execution of an OPEN statement
with an EXTEND phrase creates the file as if the following statements had been
executed:
OPEN OUTPUT file-name.
CLOSE file-name.

8600 1518–307

7–57

OPEN Statement

AVAILABLE

When the available phrase is specified for nonport files and the file cannot be opened,
the system reports the reason for the failure without suspending the program or
requiring operator intervention. For more information, refer to the discussion of the
AVAILABLE file attribute in the File Attributes Programming Reference Manual .
For information about using the AVAILABLE phrase with port files, see the paragraphs on
port files under the following “Details” heading.
OFFER

The OFFER phrase can be specified for port files only. See the paragraphs on port files
under the following “Details” heading.
WITH NO WAIT

The WITH NO WAIT phrase can be specified for port files only.

Details
The successful execution of an OPEN statement determines the availability of the file
and results in the file being in an open mode. The successful execution of an OPEN
statement associates the file with the file-name. Table 7–3 shows the result of an OPEN
statement on available and unavailable files.
The execution of an OPEN statement does not affect either the content or availability of
the file's record area. Execution of the OPEN statement does not obtain or release the
first data record.
When a given file is not in an open mode, statements that reference the file, either
explicitly or implicitly, cannot be executed, except for an OPEN statement, or for a
MERGE or SORT statement with the USING or GIVING phrases.
Table 7–3. Result of OPEN Statement

File Disposition

7–58

File Available

File Unavailable

INPUT

Normal open

Open is unsuccessful.

INPUT (optional file)

Normal open

Normal open; the first
read causes an AT END or
INVALID KEY condition.

I-O

Normal open

Open is unsuccessful.

I-O (optional file)

Normal open

Open causes the file to be
created.

OUTPUT

Normal open; the file
contains no records

Open causes the file to be
created.

8600 1518–307

OPEN Statement

Table 7–3. Result of OPEN Statement

File Disposition

File Available

File Unavailable

EXTEND

Normal open

Open is unsuccessful.

EXTEND (optional file)

Normal open

Open causes the file to be
created.

An OPEN statement must be successfully executed before the execution of any of the
permissible input-output statements. In Tables 7–4 and 7–5, an X indicates that the
specified statement, used in the access mode shown in the leftmost column, can be
used with the file organization and open mode shown at the top of the column.
A file can be opened with the INPUT, OUTPUT, I-O, and EXTEND phrases in the same
program. Following the initial execution of an OPEN statement, each subsequent OPEN
statement execution for the same file must be preceded by the execution of a CLOSE
statement without a REEL, UNIT, or LOCK phrase.
During execution of an OPEN statement, file attribute conflicts result in an unsuccessful
open operation on the file.
Treatment of a sequential file contained in a multiple-file tape environment is logically
equivalent to the treatment of a sequential file contained in a single-file tape
environment. Whenever a set of sequential files resides on a multiple-file reel, and one
file of the set is referenced in an OPEN statement, the following rules apply:

•

Not more than one sequential file of the set can be in the open mode at any one
time.

•

You can open sequential files in the input mode in any order.

Table 7–4. Permissible Statements—Sequential Files

Open Mode
Statement

READ
WRITE
REWRITE

8600 1518–307

Input

Output

I-O

Extend

X
X

7–59

OPEN Statement

Table 7–5. Permissible Statements—Relative and Indexed Files

Open Mode
File
Access
Mode

Sequential

Statement

READ

Input

Output

WRITE

READ

X
X

DELETE
Random

Extend

REWRITE
START

I-O

X
X

WRITE

X
X

REWRITE

X
X

START
DELETE
Dynamic

READ

X
X

WRITE

REWRITE
START
DELETE

X
X
X

X
X

If you designate an input file with the OPTIONAL phrase in its SELECT clause, and the
file is not present at the time the OPEN statement is executed, the operator is notified of
this fact. At this time, the file can be loaded, or the operator can enter the system
command OF. If the operator uses the OF command, the first READ statement for this
file causes an AT END or INVALID KEY condition to occur. (Refer to the System
Commands Operations Reference Manual for information on the OF command.)

7–60

8600 1518–307

OPEN Statement

If you specify label records for the file, the beginning labels are processed as follows:

•

If you specify the INPUT phrase, the execution of the OPEN statement causes the
labels to be checked.

•

If you specify the OUTPUT phrase, the execution of the OPEN statement causes the
labels to be written.

•

If you specify the EXTEND phrase and the LABEL RECORDS clause indicates that
label records are present, the execution of the OPEN statement includes the
following steps:
1. The beginning file labels are processed only in the case of a single reel/unit file.
2. The beginning reel/unit labels on the last existing reel/unit are processed as
though the file were being opened with the INPUT phrase.
3. The existing ending file labels are processed as though the file were being
opened with the INPUT phrase. These labels are then deleted.
4. Processing then proceeds as though the file had been opened with the OUTPUT
phrase.

If you do not specify label records, the operator can intervene to equate the file to one
with labels, in which case the label records are ignored.
TADS: Any USE procedure is not executed when a DELETE statement that is compiled
and executed in a TADS session fails.
Port Files
The logical communication path between two port files is established by the operating
system, provided that the connection descriptions of the two files match.
If an ACTUAL KEY is specified, its value determines which subfile of the file is to be
opened. If the ACTUAL KEY value is 0 or if it is not specified, the entire port file is
opened. If the ACTUAL KEY value is nonzero, only the specified subfile is opened.
AVAILABLE

The AVAILABLE phrase for a port file specifies that the subfile is opened if it matches a
port subfile that has already been offered. If a match does not occur, the port file is not
opened and is no longer considered for subsequent matching. A failure to match is
considered an error in the open procedure. It causes the program to abort if there is no
FILE STATUS or ERROR PROCEDURE declared for the file.
OFFER

The OFFER phrase specifies that the port subfile can be offered for matching to another
process and that control returns immediately to the next statement without waiting for a
match to occur. OPEN OFFER implies a pending open procedure. This state is not an
error, provided that an I/O error has not occurred and the status key value is 00 (although
the file has not been opened).

8600 1518–307

7–61

OPEN Statement

WITH NO WAIT

A READ statement for a port file normally causes the program to wait until a message is
available. This suspension can be prevented by using the NO WAIT phrase. For OPEN
WITH NO WAIT with AVAILABLEONLY = FALSE, a pending open procedure is not an
error, and a status key value of 00 is returned with the subfile unopened. For normal
OPEN with AVAILABLEONLY = TRUE, failure to open is an error. If an error is returned
by the OPEN operation, control is transferred to the applicable USE procedure. If no USE
procedure is specified, the program is terminated.
If FILE STATUS is declared for the subfile, the status key is updated to 00 if the OPEN
statement is executed correctly. A status key of 81 is returned if an error is encountered
during the execution of the OPEN statement.

Example
OPEN INPUT File-A NO REWIND, INPUT File-B.
This statement opens two files; File-A must be a sequential file.

7–62

8600 1518–307

PERFORM Statement

PERFORM Statement
The PERFORM statement transfers control explicitly to one or more procedures and
returns control implicitly whenever execution of the specified procedure is complete. The
PERFORM statement also controls execution of one or more imperative statements that
are in the scope of that PERFORM statement.

Format

Use

Format 1

This format is for basic PERFORM statements.

Format 2

The PERFORM . . . TIMES format enables you to PERFORM
procedures a specified number of times.

Format 3

The PERFORM . . . UNTIL format enables you to PERFORM
procedures until a specified condition is TRUE.

Format 4

The PERFORM . . . VARYING format enables you to PERFORM
procedures that augment the values referred to by identifiers or indexnames in an orderly fashion.

Format 1: Basic PERFORM

PERFORM
ïïïïïïï

Ú
Ú
³
³
³ procedure-name-1 ³
³
³
À
À

[ imperative-statement-1

ä THROUGH å
ã ïïïïïïï â
æ THRU
ç
ïïïï

¿
³
procedure-name-2 ³
³
Ù

¿
³
³
³
Ù

END-PERFORM ]
ïïïïïïïïïïï

Explanation
procedure-name-1
procedure-name-2

These elements are the names of the procedures to be performed. Together, they
represent the beginning and ending of a range of procedures to be performed. If you
specify procedure-name-1, do not specify the imperative-statement-1 END-PERFORM
phrase.
THROUGH
THRU

These words are interchangeable and connect two procedures that represent the range
of the PERFORM statement.

8600 1518–307

7–63

PERFORM Statement

imperative-statement-1 END-PERFORM

The syntax element imperative-statement-1 and the END-PERFORM phrase are required
for in-line PERFORM statements. If you specify imperative-statement-1 END-PERFORM,
do not specify procedure-name-1.
The END-PERFORM phrase delimits the scope of an in-line PERFORM statement.

Details
When you specify procedure-name-1, the PERFORM statement is known as an out-ofline PERFORM statement. When you omit procedure-name-1, the PERFORM statement
is known as an in-line PERFORM statement.
If you use an in-line PERFORM statement, you must specify both imperative-statement-1
and the END-PERFORM phrase.
If you use an out-of-line PERFORM statement, do not specify either imperativestatement-1 or the END-PERFORM phrase.
In Format 1, the specified set of statements is executed once. Then, control passes to
the end of the PERFORM statement.
The specified set of statements is defined as follows:

•

For an out-of-line PERFORM statement, the set is composed of the statements
contained in the range of procedure-name-1 (through procedure-name-2, if specified).

•

For an in-line PERFORM statement, the set is composed of the statements
contained in the PERFORM statement itself.

When you specify both procedure-name-1 and procedure-name-2, and either one is the
name of a procedure in the declaratives portion of the Procedure Division, both must be
procedure-names in the same declarative section. For a definition of declarative
procedures and a description of format requirements, refer to Section 5.

7–64

8600 1518–307

PERFORM Statement

Examples
PARA-3.
PERFORM PROCESS-PARA.
.
.
.
PROCESS-PARA.
MOVE SPACES TO PRINT-LINE.
In this first example, control passes to the procedure PROCESS-PARA. When the last
statement in PROCESS-PARA is executed, control passes to the end of the PERFORM
statement.
PARA-3.
PERFORM FACT THRU END-1.
.
.
.
FACT.
.
.
.
SEARCH-PARA.
.
.
.
END-1.
In this second example, control is transferred to the range of procedures referred to by
FACT THRU END-1. When the last statement in the range (FACT THRU END-1) is
executed, control passes to the end of the PERFORM statement.
PERFORM ADD 1 TO COUNTER
IF COUNTER = 10
MOVE 0 TO COUNTER
DISPLAY "LIMIT EXCEEDED"
END-IF
END-PERFORM.
In this third example, there is no transfer of control. After the PERFORM statement is
executed, control passes to the end of the PERFORM statement. This basic in-line
PERFORM could be enhanced later with a TIMES or an UNTIL phrase (refer to Format 2
and Format 3 in this section).

8600 1518–307

7–65

PERFORM Statement

Format 2: PERFORM . . . TIMES
Ú
³
PERFORM ³ procedure-name-1
ïïïïïïï ³
À
arithmetic-expression
[imperative-statement-1

Ú
³
³
³
À

ä THROUGH å
ã ïïïïïïï â
æ THRU
ç
ïïïï
TIMES

¿
³
procedure-name-2 ³
³
Ù

¿
³
³
³
Ù

END-PERFORM ]
ïïïïïïïïïïï

Explanation
Refer to Format 1 for descriptions of the syntax elements procedure-name-1, procedurename-2, THROUGH, THRU, imperative-statement-1, and the END-PERFORM phrase.
Note that you cannot specify both procedure-name-1 and imperative-statement-1.
arithmetic-expression

This element represents the number of times that a particular set of statements is
performed. The result of the expression is integerized and truncated as necessary.
TIMES

In the PERFORM...TIMES statement, a particular set of statements is performed a
specified number of times. The number of executions is indicated by the initial value of
arithmetic-expression.

Details
When the PERFORM statement is executed, if the value of the arithmetic-expression
referred to by arithmetic-expression is equal to zero or is negative, control is passed to
the end of the PERFORM statement. After the specified set of statements is executed
the specified number of times, control is passed to the end of that PERFORM statement.
While the PERFORM statement is executing, other statements can refer to identifier-1.
However, the statements in the scope of the PERFORM cannot alter the number of
times that the specified set of statements is executed.
The following statement is not allowed in a nested program where the name used for
section/paragraph is declared previously anywhere in the source.
PERFORM () TIMES

7–66

8600 1518–307

PERFORM Statement

In other words, if the name specified in a PERFORM statement is followed by a left
parenthesis, is a global subscripted data item, and is also used as a local section or
paragraph that has not yet been recognized, then the name specified in the PERFORM
statement must be designated to the global subscripted data item. For example:
In the main source
...
01 AA GLOBAL.
03 BB OCCURS 10 TIMES.
05 CC PIC 9(10).
In a nested program
...
PERFORM CC ( I + 1 ) TIMES ...
CC.
DISPLAY "In paragraph CC".
then the name CC in the PERFORM statement refers to the global subscripted
data item CC.

8600 1518–307

7–67

PERFORM Statement

Examples
PERFORM 10 TIMES
ADD CST-LIVING-INC TO TOTAL-PAY
END-PERFORM.
This first example shows an in-line PERFORM statement. In this program, the
procedures for the imperative statement “ADD CST-LIVING-INC TO TOTAL-PAY” are
performed 10 times. Then, control is passed to the END-PERFORM phrase, which is a
required element for an in-line PERFORM.
PARA-3.
PERFORM FACT 3 TIMES.
.
.
.
FACT.
.
.
.
PARA-4.
In this second example, control passes to FACT. After all statements in FACT are
performed three times, control passes to the end of the PERFORM statement.
PARA-3.
PERFORM READS THRU WRITES 4 TIMES.
.
.
.
READS.
.
.
.
PARA-4.
.
.
.
WRITES.
.
.
.
PARA-5.
In this third example, control is transferred to the range of procedures referred to by
READS THRU WRITES. After the procedure range (READS THRU WRITES) is executed
four times, control passes to the end of the PERFORM statement.

7–68

8600 1518–307

PERFORM Statement

Format 3: PERFORM . . . UNTIL

PERFORM
ïïïïïïï

Ú
Ú
³
³ ä THROUGH å
³ procedure-name-1 ³ ã ïïïïïïï â procedure-name-2
³
³ æ THRU
ç
À
À
ïïïï
Ú
¿
³
ä BEFORE å ³
³ WITH TEST ã ïïïïïï â ³ UNTIL condition-1
³
ïïïï æ AFTER ç ³ ïïïïï
À
ïïïïï
Ù
[ imperative-statement-1

¿
³
³
³
Ù

END-PERFORM ]
ïïïïïïïïïïï

These phrases enable you to specify whether the condition is tested before or after the
specified set of statements is executed.
UNTIL condition-1

This phrase enables you to specify a condition that you want to test. Condition-1 is a
conditional expression. Refer to “Conditional Expressions” in Section 5 for more
information.

Details
In the PERFORM . . . UNTIL format, the specified set of statements is performed until
the condition specified by the UNTIL phrase is true. When this condition is true, control
passes to the end of the PERFORM statement.
If the condition is true when the PERFORM statement is entered, and the TEST BEFORE
phrase is specified or implied, control is not transferred to procedure-name-1. Instead,
control passes to the end of the PERFORM statement.
If the TEST AFTER phrase is specified, the PERFORM statement functions as if the TEST
BEFORE phrase were specified, except that the condition is tested after the specified
set of statements has been executed.

8600 1518–307

7–69

PERFORM Statement

If you specify neither the TEST BEFORE nor the TEST AFTER phrase, the TEST BEFORE
phrase is assumed.
Any subscripting or reference modification that is associated with the operands specified
in condition-1 is evaluated each time the condition is tested.

Examples
PARA-3.
PERFORM PROCESS-PARA THRU PROCESS-EXIT UNTIL A = B.
.
.
.
PROCESS-PARA.
.
.
.
PARA-7.
.
.
.
PARA-8.
.
.
.
PROCESS-EXIT.
In this first example, control passes to the range of statements from the beginning of
PROCESS-PARA through the last statement in PROCESS-EXIT. This range of statements
is executed iteratively until the condition A equal to B is true.
SECTION-02.
PARA-4.
PERFORM SECTION-04 UNTIL I GREATER THAN 10.
.
.
.
SECTION-04.
PARA-9.
Because SECTION-04 is a section and can include several paragraphs, the range of the
PERFORM statement includes all statements from the first statement in the first
paragraph through the final statement in the last paragraph. These statements are
performed until the value of I is greater than 10. Then, control passes to the end of the
PERFORM statement.

7–70

8600 1518–307

PERFORM Statement

PARA-3.
PERFORM FACT WITH TEST AFTER UNTIL CONDITION-1 =
.
.
.
FACT.

"TRUE".

In this second example, condition-1 will be tested after the specified set of statements is
executed. If condition-1 is true, control passes to the end of the PERFORM statement. If
condition-1 is false, the specified set of statements is executed again. Then, the
condition is tested.

Format 4: PERFORM . . . VARYING

PERFORM
ïïïïïïï

Ú
Ú
³
³ ä THROUGH å
³ procedure-name-1 ³ ã ïïïïïïï â
³
³ æ THRU
ç
À
À
ïïïï
Ú
¿
³
ä BEFORE å ³
³ WITH TEST ã ïïïïïï â ³
³
ïïïï æ AFTER ç ³
À
ïïïïï
Ù
VARYING
ïïïïïïï

BY
ïï
Ú
³
³ AFTER
³ ïïïïï
À

ä identifier-1 å
ã
â
æ index-name-1 ç

FROM
ïïïï

arithmetic-expression-2

ä identifier-2 å
ã
â
æ index-name-3 ç

FROM
ïïïï

¿
³
procedure-name-2 ³
³
Ù

¿
³
³
³
Ù

ä index-name-2
å
ã
â
æ arithmetic-expression-1 ç

UNTIL condition-1

ä index-name-4
å
ã
â
æ arithmetic-expression-3 ç

¿
³
BY
arithmetic-expression-4
UNTIL condition-2 ³
ïï
³
Ù
[ imperative-statement-1 END-PERFORM ]
ïïïïïïïïïïï

8600 1518–307

. . .

7–71

PERFORM Statement

These phrases enable you to specify whether the condition is tested before or after the
specified set of statements is executed.
If you specify neither phrase, the TEST BEFORE phrase is assumed.
VARYING
identifier-2
index-name-1

This phrase enables you to vary a data item referred to by an identifier or an index-name.
Index-name is a user-defined word that names an index associated with a table.
FROM
index-name-2
arithmetic-expression-1

The FROM phrase establishes the starting value of identifier-1 or index-name-1 that is
varied. If arithmetic-expression-1 is used and the data item referred to by identifier-1 is an
integer or index-name-1 is used, the result of arithmetic-expression-1 will be integerized
and truncated.
BY
arithmetic-expression-2

The BY phrase determines the amount by which identifier-1 or index-name-1 is to be
augmented between iterations of the PERFORM range.
UNTIL condition-1

This phrase establishes a condition that, when met, terminates the VARYING . . .
FROM . . . BY operation.
AFTER
identifier-2
index-name-3

This option enables you to use a maximum of six nested PERFORM loops in each
PERFORM statement. If you omit procedure-name-1, do not specify the AFTER phrase.

7–72

8600 1518–307

PERFORM Statement

FROM
arithmetic-expression-3

This FROM phrase establishes the starting value of identifier-2 or index-name-3 that is to
be varied in the nested PERFORM loop. If arithmetic-expression-3 is used and the data
item referred to by identifier-2 is integer or index-name-3 is used, the result of arithmeticexpression-3 will be integerized and truncated.
BY
arithmetic-expression-4

The BY phrase determines the amount by which identifier-2 or index-name-3 is to be
augmented between iterations of the PERFORM range.
UNTIL condition-2

This phrase establishes a condition that, when met, terminates the AFTER . . . FROM . . .
BY operation.

Rules for Identifiers
Each identifier represents a numeric elementary item that is described in the Data
Division.
If identifier-2 is subscripted, the subscripts are evaluated each time the content of the
data item referred to by the identifier is set or augmented.

Rules for Arithmetic Expressions
The results of arithmetic expressions referred to by arithmetic-expression-2 and
arithmetic-expression-4 cannot have a value of zero. If arithmetic-expression-1,
arithmetic-expression-2, arithmetic-expression-3, or arithmetic-expression-4 contain
subscripted data items, the subscripts are evaluated each time the associated data item
is referred to in the expression.

Rules for Index-Names
If you specify index-name-1 or index-name-3, the value of the associated index at the
beginning of the PERFORM statement is set to index-name-2, which must not be greater
than the number of occurrences. Subsequent augmentation, as described later in this
section, of index-name-1 or index-name-3 must not result in the associated index being
set to a value outside the range of the table associated with index-name-1 or indexname-3. This restriction applies until the completion of the PERFORM statement; at that
time, the index associated with index-name-1 can contain a value that is outside the
range of the associated table by one increment or decrement value.
If you specify index-name-2 or index-name-4, the value of the data item referred to by
identifier-2 or identifier-5, at the beginning of the PERFORM statement, must be equal to
an occurrence number of an element in a table associated with index-name-2 or indexname-4.

8600 1518–307

7–73

PERFORM Statement

If you specify an index-name in the VARYING or AFTER phrase, then the arithmetic
expression in the associated FROM or BY phrases must result in a positive integer.
If you specify an index-name in the FROM phrase, then

•

The identifier in the associated VARYING or AFTER phrase must refer to an integer
data item.

•

The arithmetic expression in the associated BY phrase must result in an integer.

Rules for Condition-Names
Condition-1, condition-2, and so forth, can be any conditional expression. For a
description of conditional expressions, refer to “Conditional Expressions” in Section 5.
Any subscripting or reference modification associated with the operands specified in
condition-1 and condition-2 is evaluated each time the condition is tested.

Action of Various PERFORM Statements
Representations of the actions of several types of Format 4 PERFORM statements
appear on the following pages.
In the following discussions, each reference to identifiers as the object of the VARYING,
AFTER, and FROM (current value) phrases also refers to index-names.
TEST BEFORE with One Identifier
If the TEST BEFORE phrase is specified or implied, and the data item associated with
one identifier is varied, the following actions occur in order:
1. The content of the data item referred to by identifier-2 is set to literal-1 or to the
current value of the data item referred to by identifier-3 at the time the PERFORM
statement was initially executed.
2. If the condition of the UNTIL phrase is FALSE, the specified set of statements is
executed once. The value of the data item referred to by identifier-2 is augmented by
the specified increment or decrement value (literal-2 or the value of the data item
referred to by identifier-4), and condition-1 is evaluated again.
3. When condition-1 is TRUE, control is transferred to the end of the PERFORM
statement.
4. If condition-1 is TRUE at the beginning of execution of the PERFORM statement,
control is transferred to the end of the PERFORM statement.

7–74

8600 1518–307

PERFORM Statement

Figure 7–1 illustrates the TEST BEFORE phrase with one identifier varied.

Figure 7–1. TEST BEFORE with One Identifier Varied

8600 1518–307

7–75

PERFORM Statement

TEST BEFORE with Two Identifiers
If the TEST BEFORE phrase is specified or implied, and the data items associated with
two identifiers are varied, the following actions occur in order:
1. The content of the data item referred to by identifier-2 is set to literal-1 or to the
current value of the data item referred to by identifier-3.
2. The content of the data item referred to by identifier-5 is set to literal-3 or to the
current value of the data item referred to by identifier-6.
3. After the contents of the data items of these identifiers have been set, condition-1 is
evaluated.
a.

If condition-1 is TRUE, control is transferred to the end of the PERFORM
statement.

b. If condition-1 is false, condition-2 is evaluated.
c.

If condition-2 is false, the specified set of statements is executed once. The
content of the data item referred to by identifier-5 is augmented either by literal-4
or by the content of the data item referred to by identifier-7. Then, condition-2 is
evaluated again.

d. The evaluation and augmentation cycle continues until condition-2 is true. When
condition-2 is true, the content of the data item referred to by identifier-2 is
augmented by literal-2 or by the content of the data item referred to by
identifier-4. The content of the data item referred to by identifier-5 is set to literal3 or to the current value of the data item referred to by identifier-6. Then,
condition-1 is reevaluated.
4. The PERFORM statement is completed if condition-1 is true; the cycle continues
until condition-1 is true.
5. When the PERFORM statement ends, the data item referred to by identifier-5
contains literal-3 or the current value of the data item referred to by identifier-6. The
data item referred to by identifier-2 contains a value that exceeds the last-used
setting by one increment or decrement value, unless condition-1 was true when the
PERFORM statement was entered. In that case, the data item referred to by
identifier-2 contains literal-1 or the current value of the data item referred to by
identifier-3.

7–76

8600 1518–307

PERFORM Statement

Figure 7–2 illustrates the TEST BEFORE phrase with two identifiers varied.

Figure 7–2. TEST BEFORE with Two Identifiers Varied

8600 1518–307

7–77

PERFORM Statement

TEST AFTER with One Identifier
If the TEST AFTER phrase is specified and the data item associated with one identifier is
varied, the following actions occur in order:
1. The content of the data item referred to by identifier-2 is set either to literal-1 or to
the value of the data item associated with identifier-3 at the time the PERFORM
statement is executed.
2. The specified set of statements is executed once, and condition-1 of the UNTIL
phrase is tested.
a.

If condition-1 is false, the value of the data item referred to by identifier-2 is
augmented by the specified increment or decrement value (literal-2 or the value
of the data item referred to by identifier-4), and the specified set of statements is
executed again.

b. When condition-1 is true, control is transferred to the end of the PERFORM
statement.
Figure 7–3 illustrates the TEST AFTER phrase with one identifier varied

Figure 7–3. TEST AFTER Phrase with One Identifier Varied

7–78

8600 1518–307

PERFORM Statement

TEST AFTER with Two Identifiers
If the TEST AFTER phrase is specified and the data items associated with two identifiers
are varied, the following actions occur in order:
1. The content of the data item referred to by identifier-2 is set to literal-1 or to the
current value of the data item referred to by identifier-3.
2. The content of the data item referred to by identifier-5 is set to literal-3 or to the
current value of the data item referred to by identifier-6. Then, the specified set of
statements is executed.
3. Condition-2 is evaluated.
a.

If condition-2 is false, the content of the data item referred to by identifier-5 is
augmented by literal-4 or by the content of the data item referred to by
identifier-7. Then, the specified set of statements is executed again.

b. When condition-2 is true, condition-1 is evaluated.
c.

If condition-1 is false, the content of the data item referred to by identifier-2 is
augmented by literal-2 or by the content of the data item referred to by identifier4. The content of the data item referred to by identifier-5 is set to literal-3 or to
the current value of the data item referred to by identifier-6. Then, the specified
set of statements is executed.

d. When condition-1 is true, control is transferred to the end of the PERFORM
statement.

8600 1518–307

7–79

PERFORM Statement

Figure 7–4 illustrates the TEST AFTER phrase with two identifiers varied.

Figure 7–4. TEST AFTER Phrase with Two Identifiers Varied
When the PERFORM statement ends, each data item that was varied by an AFTER or
VARYING phrase contains the same value it contained at the end of the most recent
execution of the specified set of statements.

7–80

8600 1518–307

PERFORM Statement

How Changes in Variables Affect the PERFORM Statement
When the specified set of statements associated with the PERFORM statement is
executed, changes to any of the following variables will affect the operation of the
PERFORM statement:

•

The VARYING variable (the data item referred to by identifier-2 and index-name-1)

•

The BY variable (the data item referred to by identifier-4 or identifier-7)

•

The AFTER variable (the data item referred to by identifier-5 and index-name-3)

•

The FROM variable (the data item referred to by identifier-3, identifier-6, index-name2 or index-name-4)

When the data items associated with two identifiers are varied, the data item referred to
by identifier-5 goes through a complete cycle (FROM, BY, UNTIL) each time the content
of the data item associated with identifier-2 is varied.
Varying the contents of three or more data items is similar to varying the contents of two
data items. The data item being varied by each AFTER phrase goes through a complete
cycle each time the data item being varied by the preceding AFTER or VARYING phrase
is augmented.

Example
01 TOTALS.
03 DIV OCCURS 3 TIMES INDEXED BY DIV-CODE.
05 DEPT OCCURS 15 TIMES INDEXED BY DEPT-CODE.
07 COST-CENTER PIC S9(10) COMP OCCURS 30 TIMES
INDEXED BY COST-CENTER-CODE.
PROCEDURE DIVISION.
.
.
.
PERFORM PRINT-ROUTINE VARYING DIV-CODE FROM 1 BY 1
UNTIL DIV-CODE > 3
AFTER DEPT-CODE FROM 1 BY 1
UNTIL DEPT-CODE GREATER THAN 15
AFTER COST-CENTER-CODE FROM 1 BY 1
UNTIL COST-CENTER-CODE GREATER THAN 30.
.
.
.
PRINT-ROUTINE.
.
.
.
MOVE COST-CENTER (DIV-CODE, DEPT-CODE,
COST-CENTER-CODE) TO PRINT-LINES.
WRITE PRINT-LINES BEFORE 2.

8600 1518–307

7–81

PERFORM Statement

In the example, the PERFORM VARYING statement is used to print division, department,
and cost-center names on a report. Division, department, and cost-center are indexed by
DIV-CODE, DEPT-CODE, and COST-CENTER-CODE, respectively. The two AFTER
phrases are used to vary the cost-center code and the department code 15 times and 30
times, respectively.

Rules for All Formats of the PERFORM Statement
Unless specifically qualified by the word in-line or out-of-line, all rules that apply to the
out-of-line PERFORM statement also apply to the in-line PERFORM statement. An in-line
PERFORM statement can achieve the same result as an out-of-line PERFORM
statement, except that the statements contained in the in-line PERFORM statement are
executed in place of the statements in the range procedure-name-1 (through procedurename-2, if specified).
When the PERFORM statement is executed, control is transferred to the first statement
of the specified set of statements (except as indicated in the rules for formats 2, 3, and
4). This transfer of control occurs only once for each execution of a PERFORM
statement. When an explicit transfer of control to the specified set of statements does
take place, an implicit transfer of control to the end of the PERFORM statement is
established as indicated in the following table:

If . . .

And . . .

Then . . .

Procedure-name-1 is a
paragraph-name.

You have not
specified procedurename-2.

Control returns to the next
executable statement after the
last statement of procedurename-1.

Procedure-name-1 is a
section-name.

You have not
specified procedurename-2.

Control returns to the next
executable statement after the
last statement of the last
paragraph in procedure-name-1.

You specify procedurename-2.

It is a paragraphname.

Control returns to the next
executable statement after the
last statement of the last
paragraph of procedure-name-2.

You specify procedurename-2.

It is a section-name.

Control returns to the next
executable statement after the
last statement of the last
paragraph in procedure-name-2.

You specify an in-line
PERFORM statement.

7–82

An execution of the PERFORM
statement is completed after the
last statement contained within it
has been executed.

8600 1518–307

PERFORM Statement

A relationship between procedure-name-1 and procedure-name-2 is not necessary. This
is true except when a consecutive sequence of operations will be executed from the
procedure named by procedure-name-1 through the procedure named by procedurename-2. In particular, GO TO and PERFORM statements can occur between procedurename-1 and the end of procedure-name-2. If there are two or more logical paths to the
return point, then procedure-name-2 can be the name of a paragraph that consists of the
EXIT statement, to which all of the logical paths must lead.
If control passes to the specified set of statements by means other than a PERFORM
statement, control will pass through the last statement of the set to the next executable
statement as if no PERFORM statement referred to the set.
Range of a PERFORM Statement
The range of a PERFORM statement consists, logically, of all statements that are
executed as a result of executing the PERFORM statement until the implicit transfer of
control to the end of the PERFORM statement. Also, the range includes all statements
that are executed as a result of a transfer of control by CALL, EXIT, GO TO, and other
PERFORM statements, within the range of the PERFORM statement; and all statements
in declarative procedures that are executed as a result of the execution of statements in
the range of the PERFORM statement. The statements in the range of a PERFORM
statement need not appear consecutively in the source program.
Statements executed as a result of a transfer of control that was caused by the
execution of an EXIT PROGRAM statement are not considered part of the range of the
PERFORM statement when the EXIT PROGRAM statement is

•

Specified in the same program in which the PERFORM statement is specified

•

Is within the range of the PERFORM statement

Procedure-name-1 and procedure-name-2 must not name sections or paragraphs in any
other program in the run unit, whether or not the other program contains or is contained
in the program that includes the PERFORM statement. In the run unit, statements in
other programs can be obeyed only as a result of executing a PERFORM statement, if
the range of that PERFORM statement includes CALL and EXIT PROGRAM statements.
The CALL statement and the EXIT statement are described earlier in this section.
If the range of a PERFORM statement includes another PERFORM statement, the
sequence of procedures associated with the included PERFORM statement must be
either totally included in, or totally excluded from, the logical sequence referred to by the
first PERFORM statement. Thus, an active PERFORM statement whose execution point
begins within the range of another active PERFORM statement must not allow control to
pass to the end of the other active PERFORM statement. Moreover, two or more such
active PERFORM statements cannot have a common exit.

8600 1518–307

7–83

PERFORM Statement

Figure 7–5 shows examples of valid PERFORM structures.

Figure 7–5. Valid PERFORM Structures
For more information about conditional expressions, refer to “Conditional Expressions” in
Section 5.
Refer to “CALL Statement” and “EXIT Statement” in Section 6 for more information
about CALL or EXIT PROGRAM statements within a PERFORM statement.

7–84

8600 1518–307

PROCESS Statement

PROCESS Statement
The PROCESS statement enables a program to execute a separately compiled program
as an asynchronous, dependent process.
The format for this statement is as follows:

PROCESS task-variable WITH section-name [ USING actual-parameter-list ].
ïïïïïïï
ïïïï
ïïïïï

Explanation
task-variable

This specifies the task variable that is to be associated with the process declared in the
section identified by section-name. The task variable must be declared as a data item in
the Working-Storage Section of the Data Division. For more information about task
variables, refer to the USAGE clause in Section 4 and to Section 11.
section-name

This identifies the section in the Procedure Division that contains the name of the object
code file that is to be initiated by the PROCESS statement. You must define the sectionname in the Declaratives Section of the Procedure Division followed by a USE
EXTERNAL statement that specifies the name of the object code file.
USING actual-parameter-list

The USING phrase indicates the parameters in the calling program that are to be passed
between both programs. Include the USING phrase only if a USING phrase exists in the
Procedure Division header of the called program and in the USE statement of the section
identified by section-name in the calling program.
The parameters in the USING phrase can be any combination of 77-level or 01-level or
greater data items. In general, the level number, type, length, and order of items in the
USING phrase of the calling and called programs must be identical. However, the items
in the following list are interchangeable as parameters. That is, each item can be passed
to and received by the other. The lengths of the associated items must be the same,
however, or run-time errors might occur.
Interchangeable Group Items

•

BINARY

•

COMP

•

DISPLAY

•

DOUBLE

•

REAL

8600 1518–307

7–85

PROCESS Statement

Other Interchangeable Items

•

DOUBLE items with RECEIVED BY REFERENCE clause

•

77-level BINARY REAL data items

Files to be passed as parameters must have a record description. The record description
itself can be passed as a parameter. The USING phrase in the Procedure Division header
of the called program must not reference any data item in the File Section of the called
program. Both the calling and the called programs can read and write to the file passed
as a parameter in the CALL statement.
Including a task-variable in the USING phrase enables the called program to make
references to the calling program.
Variables can be passed by reference (default) or by value. Table 7–4, which
accompanies Format 6 of the CALL statement, describes the matching of formal
parameters between the COBOL74/85, ALGOL, and COBOL68 languages.

Details
The process initiated by the PROCESS statement is asynchronous, so it executes
simultaneously with the program that initiated it. The initiated process is also dependent,
so its existence relies on the continued execution of the process that initiated it. If the
initiating process terminates before the dependent process terminates, a critical block
exit occurs. For information on how to prevent critical block exit errors, refer to Section
11.
Naming the Program to Be Initiated
You can specify the name of the program to be initiated by the PROCESS statement in
one of the following ways:

•

Precede the PROCESS statement by a CHANGE statement that changes the NAME
attribute of the task variable.

•

Define a mnemonic-name in the Special-Names paragraph of the Environment
Division, and then use it in the USE EXTERNAL statement.

•

Use the following steps:

−

Declare a data item in the Working-Storage section of the Data Division.

−

Name the data item in a USE EXTERNAL statement in the Declarative Section of
the Procedure Division.

−

Assign the object code file title to the data item by using a MOVE statement in
the Procedure Division.

For program examples that show how to name the program to be initiated, refer to
Section 11.

7–86

8600 1518–307

PROCESS Statement

Example
IDENTIFICATION DIVISION.
PROGRAM-ID. CALL-TASK-CALLER.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
"OBJECT/CALLED"IS TASK-ID.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 DEP-TASK
TASK.
PROCEDURE DIVISION.
DECLARATIVES.
CALL-A-TASK SECTION.
USE EXTERNAL TASK-ID AS PROCEDURE.
END DECLARATIVES.
MAIN SECTION.
MAIN-PARA.
PROCESS DEP-TASK
WITH CALL-A-TASK.
STOP RUN.

8600 1518–307

7–87

READ Statement

READ Statement
The READ statement enables you to access records from various kinds of files. For files
in sequential access mode, the READ statement makes available the next logical record
from a file. For files in random access mode, the READ statement makes available a
specific record from a mass storage file.
For an explanation of the three types of file organization (sequential, relative, and
indexed) and the three file access modes (sequential, random, and dynamic), refer to
Section 10.
If the logical records of a file are described by more than one record description, the
records share the same record area in storage. This sharing implicitly redefines the
record area. The contents of any data items that are outside the range of the current data
record are undefined when the READ statement is executed.
This statement is partially supported in the TADS environment. Applicable exclusions are
noted in this section.

Format

Use

Format 1

This format reads the next logical record in a sequential file or
any file in sequential access mode.

Format 2

This format is for relative files in random access mode or for
files in dynamic access mode when records will be retrieved
randomly.

Format 3

This format is for indexed files in random access mode or for
files in dynamic access mode when records will be retrieved
randomly.

Format 1: Files in Sequential Access Mode
READ file-name-1 [ NEXT ] RECORD [WITH NO WAIT ] [ INTO identifier-1 ]
ïïïï
ïïïï
ïï ïïïï
ïïïï
[ AT END imperative-statement-1 ]
ïïï
[ NOT AT END imperative-statement-2 ]
ïïï
ïïï
[ END-READ ]
ïïïïïïïï
This format is supported in the TADS environment.

7–88

8600 1518–307

READ Statement

Explanation
file-name-1

This user-defined word is the name of the file you want to read.
NEXT

In sequential access mode, the NEXT phrase is optional and does not affect the
execution of the READ statement. The NEXT phrase must be specified for files in
dynamic access mode when records are retrieved sequentially.
RECORD

This optional word makes the program more specific.
WITH NO WAIT

This phrase is valid only for port files. When this phrase is specified, the program does
not wait for a logical record to become available.
INTO identifier-1

This option enables you to move the current record from the record area to the data item
specified by identifier-1. Identifier-1 can reference a long numeric data item.
AT END imperative-statement-1

This option enables you to specify an action to be taken if the AT END condition occurs.
If there is no next logical record and the AT END phrase is specified, imperativestatement-1 will be executed.
NOT AT END imperative-statement-2

This option enables you to specify an action to be taken if the NOT AT END condition
occurs. If the file is not AT END and the NOT AT END phrase is specified, imperativestatement-2 will be executed.
END-READ

This phrase delimits the scope of the READ statement.

Details
Format 1 is for all files in sequential access mode whether the organization of the file is
sequential, relative, or indexed.

•

A sequential file consists of records organized in a series, one after the other.

•

A relative file consists of records defined by their ordinal position in the file.

8600 1518–307

7–89

READ Statement

•

An indexed file is a two-part file that consists of an index or key file and a data file
that contains the actual data records.

The imperative-statement-1 can be the NEXT SENTENCE phrase. The NEXT SENTENCE
phrase is valid only for sequential files.
Refer to the paragraphs headed “Rules for Record Selection” in this section for
information on file position indicators and comparisons of records in sequential access
mode.
The method used to overlap access time with processing time does not change the use
of the READ statement. A record is available to the object program before the execution
of imperative-statement-2, if specified, or before the execution of any statement
following the READ statement, if imperative-statement-2 is not specified.
If, during the execution of the READ statement, the end of a reel or a unit is recognized,
or a reel or a unit does not contain a next logical record, and the logical end of the file has
not been reached, the following operations are executed:

•

The standard ending reel or unit label procedure is executed.

•

A reel or a unit swap occurs: the current volume pointer is updated to point to the
next reel or unit existing for the file.

•

The standard beginning reel or unit label procedure is executed.

Rules for Relative and Indexed Files (Format 1)
When dynamic access mode is specified for a relative or an indexed file, execution of a
Format 1 READ statement with the NEXT phrase retrieves the next logical record from
the file.
If file-name-1 is a relative file and the RELATIVE KEY phrase is specified in the file control
entry of the Input-Output Section for that file, execution of a Format 1 READ statement
moves the relative record number of the record made available to the relative key data
item, according to the rules for the MOVE statement. The MOVE statement is described
earlier in this section.
When sequential access mode is specified for an indexed file, records that have the
same value in an alternate record key (which is the key of reference) are made available
in one of the following ways:

•

In the same order in which they are released by the execution of WRITE statements

•

By the execution of REWRITE statements that create such duplicate values

If you specify dynamic access mode for an indexed file, data-name-1 or the prime record
key can also be used for retrievals by subsequent executions of Format 1 READ
statements until another key of reference is established for the file.

7–90

8600 1518–307

READ Statement

Format 2: Sequential and Relative Files in Random Access Mode
READ file-name-1 RECORD [ WITH NO WAIT ] [ INTO identifier-1 ]
ïïïï
ïï ïïïï
ïïïï
[ INVALID KEY imperative-statement-3 ]
ïïïïïïï
[ NOT INVALID KEY imperative-statement-4 ]
ïïï ïïïïïïï
[ END-READ ]
ïïïïïïïï
This format is supported in the TADS environment.

Explanation
Refer to Format 1 for descriptions of syntax elements file-name-1, WITH NO WAIT, INTO
identifier-1, and END-READ.
INVALID KEY imperative-statement-3

The INVALID KEY option enables you to specify an action to be taken when the key is
invalid.
For more information about the invalid key condition, refer to the “Details” section which
follows.
You must include the INVALID KEY option if there is no USE AFTER STANDARD
EXCEPTION statement specified for file-name-1.
NOT INVALID KEY imperative-statement-4

The NOT INVALID KEY option enables you to specify an action to be taken when the key
is valid.

Details
A sequential file consists of records organized in a series, one after the other.
A relative file consists of records defined by their ordinal position in the file.
The execution of a Format 2 READ statement:

•

Sets the file position indicator to the value contained in the data item referred to by
the ACTUAL KEY phrase for sequential files or the RELATIVE KEY phrase for relative
files. (These phrases are located in the file control entry for the file in the InputOutput Section.)
For more information on file position indicators and comparisons of records for
relative files, refer to "Rules for Record Selection" later in this section.

8600 1518–307

7–91

READ Statement

•

Makes the record whose sequential or relative record number equals the file position
indicator available in the record area associated with file-name-1.

If the contents of the ACTUAL KEY or RELATIVE KEY data item are less than 1 or are
greater than the ordinal number of the last record written to the file, the INVALID KEY
condition exists and the READ statement is unsuccessful. For more information about
this condition, refer to “Rules for Exception Processing of the READ Statement” later in
this section.
If a READ statement is unsuccessful, the content of the associated record area is
undefined and the file position indicator is set to indicate that a valid next record has not
been established.

Format 3: Indexed Files in Random Access Mode
READ file-name-1 RECORD [ INTO identifier-1 ]
ïïïï
ïïïï
[ KEY IS data-name-1 ]
ïïï
[ INVALID KEY imperative-statement-3 ]
ïïïïïïï
[ NOT INVALID KEY imperative-statement-4 ]
ïïï ïïïïïïï
[ END-READ ]
ïïïïïïïï
This format is supported in the TADS environment.

Explanation
Refer to Format 1 for descriptions of syntax elements file-name-1, INTO identifier-1, and
END-READ.
Refer to Format 2 for descriptions of the INVALID KEY and NOT INVALID KEY phrases.
KEY IS data-name-1

This phrase establishes data-name-1 as the key of reference for this retrieval. Data-name1 must be the name of a data item specified as a record key associated with file-name-1.
Data-name-1 can be qualified.
Data-name-1 cannot reference a long numeric data item.

7–92

8600 1518–307

READ Statement

Details
An indexed file consists of two parts, an index or “key file” and a data file that contains
the actual data records. The key determines the position of each record in the file. This
type of file organization provides multiple paths to a given record.
Refer to the paragraphs headed “Rules for Record Selection” in this section for
information on file position indicators and comparisons of records for indexed files.
If you specify the KEY phrase in a Format 3 READ statement, data-name-1 becomes the
key of reference for this retrieval.
If you do not specify the KEY phrase in a Format 3 READ statement, the prime record
key becomes the key of reference for this statement.
The execution of a Format 3 READ statement sets the file position indicator to the value
of the key of reference. The first record that matches the value of the key of reference is
selected. If there is an alternate key with duplicate values, the record selected is the first
record of a sequence of duplicates that was released by the execution of WRITE or
REWRITE statements. The selected record is made available to the record area that is
associated with file-name-1. If a record is not selected, the invalid key condition exists
and execution of the READ statement is unsuccessful.
If the contents of the data item used as the key are less than 1 or are greater than the
ordinal number of the last record written to the file, the INVALID KEY condition exists.
For more information about this condition, refer to “Rules for Exception Processing of
the READ Statement” later in this section.
If a READ statement is unsuccessful, the associated record area is undefined, the key of
reference is undefined for indexed files, and the file position indicator is set to indicate
that a valid next record has not been established.
Using Port Files (Format 1 or Format 2)
A READ statement causes the program to wait until a logical record is available. The
possibility of this suspension is prevented for port files by specifying the WITH NO WAIT
phrase. A status key value of 94 indicates that no logical record was available for the
read.
If an ACTUAL KEY is declared for a port file, your program is responsible for updating the
ACTUAL KEY with an appropriate subfile index. If the ACTUAL KEY is nonzero, a READ
statement from the specified subfile is performed. If the ACTUAL KEY is 0 (zero), a
nonselective read is performed and the ACTUAL KEY is updated to indicate the subfile
index of the subfile that was read.
For a nonselective read, the first logical record to arrive at a subfile in the port file is
returned as the data for the READ statement. The subfile to be read is determined by the
operating system, and no specific selection algorithm is guaranteed. However, no subfile
is read continuously at the expense of the other subfiles.
If no ACTUAL KEY is declared for the port file, the file must contain only a single subfile,
and that subfile is read.

8600 1518–307

7–93

READ Statement

Rules for All Formats of the READ Statement
The storage area associated with the data item referred to by identifier-1 and the record
area associated with the file referred to by file-name-1 must not be the same storage
area.
The file referred to by file-name-1 must be open in the INPUT or I-O mode when the
READ statement is executed.
The execution of the READ statement updates the value of the I-O status that is
associated with file-name-1. I-O status codes are described in Section 3.
The INTO phrase can be specified in a READ statement when one of the following
conditions is true:

•

If only one record description is subordinate to the file description entry

•

If all record-names associated with file-name-1 and the data item referred to by
identifier-1 describe a group item or an elementary alphanumeric item

The result of the execution of a READ statement with the INTO phrase is the same as
the result of the following statements:

•

The execution of the same READ statement without the INTO phrase.

•

An implied MOVE, in which the current record is moved from the record area to the
area specified by identifier-1, according to the rules for the MOVE statement without
the CORRESPONDING phrase.
In this operation, the size of the current record is determined by rules specified in the
RECORD clause. If the file description entry contains a RECORD IS VARYING clause,
the implied move is a group move. The implied move does not occur if the execution
of the READ statement was unsuccessful. Any subscripting associated with
identifier-1 is evaluated after the record has been read and immediately before it is
moved to the data item. The record is available in both the record area and the data
item referred to by identifier-1.
Refer to “MOVE Statement” in this section for an explanation of MOVE actions
without the CORRESPONDING phrase.

If the number of character positions in the record that is read is less than the minimum
size specified by the record description entries for file-name-1, the portion of the record
area to the right of the last valid character is undefined. If the number of character
positions in the record that is read is greater than the maximum size specified by the
record description entries for file-name-1, the record is truncated on the right to the
maximum size. In either of these cases, execution of the READ statement is successful
and an I-O status is set to indicate that a record length conflict has occurred. I-O status
codes are described in Section 3.

7–94

8600 1518–307

READ Statement

TADS: Any USE procedure is not executed when a READ statement that is compiled
and executed in a TADS session fails.
Using the READ Statement with Sequential Files
Records in sequential files are compared according to their record number. The following
rules apply:

•

If the file position indicator was established by an OPEN statement, the record
selected is the first in the file whose record number is greater than or equal to the
file position indicator.

•

If the file position indicator was established by a READ statement, the record
selected is the first in the file whose record number is greater than the file position
indicator.

•

If a record is available, the file position indicator points to the record number of that
record.

Using the READ Statement with Relative Files
Records in relative files are compared according to their relative key number. The
following rules apply:

•

If the file position indicator was established by an OPEN or a START statement, the
record selected is the first in the file whose relative record number is greater than or
equal to the file position indicator.

•

If the file position indicator was established by a READ statement, the record
selected is the first in the file whose relative record number is greater than the file
position indicator.

•

If a record is found that satisfies the preceding rules, it is made available in the
record area that is associated with file-name-1. The record is available unless you
specify the RELATIVE KEY phrase for file-name-1, and the number of significant
digits in the relative record number of the selected record is larger than the size of
the relative key data item. In this case, the I-O status is set to a value of 14. Then,
execution proceeds as described in the paragraphs headed "Rules for Exception
Processing of the READ Statement" in this section.

•

If a record is available, the file position indicator points to the relative record number
of that record.

8600 1518–307

7–95

READ Statement

Using the READ Statement with Indexed Files
Records in indexed files are selected according to the value of the current key of
reference. Comparisons are made according to the collating sequence of the file. The
following rules apply:

•

If the file position indicator was established by an OPEN or a START statement, the
record selected is the first in the file whose key value is greater than or equal to the
file position indicator.

•

If the file position indicator was established by a READ statement, and the current
key of reference does not allow duplicate values, the record selected is the first in
the file whose key value is greater than the file position indicator.

•

If the file position indicator was established by a READ statement, and the current
key of reference does allow duplicate values, the record is selected in one of the
following ways:

•

−

The first record in the file whose key value is equal to the file position indicator
and whose logical position in the set of duplicates is immediately after the record
that was made available by that READ statement is selected.

−

The first record in the file whose key value is greater than the file position
indicator is selected.

If a record is available, the file position indicator points to the value of the current key
of reference for that record.

Using the READ Statement with Relative and Indexed Files
You must use Format 2 or Format 3 for files in random access mode, or for files in
dynamic access mode when records will be retrieved randomly.
You must specify the INVALID KEY phrase or the AT END phrase if you do not specify an
applicable USE AFTER STANDARD EXCEPTION procedure for file-name-1.
The method used to overlap access time with processing time does not change the use
of the READ statement. A record is available to the object program before the execution
of imperative-statement-2 or imperative-statement-4, if specified, or before the execution
of any statement following the READ statement, if neither imperative-statement-2 nor
imperative-statement-4 is specified.
Rules for Record Selection
The setting of the file position indicator at the start of the execution of a READ statement
determines which record will be made available. The following rules apply:

•

If the file position indicator indicates that a valid next record has not been
established, execution of the READ statement is unsuccessful.

•

If the file position indicator indicates that an optional input file is not present,
execution proceeds as described in the paragraphs headed “Rules for Exception
Processing of the READ Statement” in this section.

If a record is found that satisfies these rules, it is made available in the record area that is
associated with file-name-1.

7–96

8600 1518–307

READ Statement

If a record is not found that satisfies these rules, the file position indicator is set to
indicate that a next logical record does not exist. Execution proceeds as described in the
paragraphs headed “Rules for Exception Processing of the READ Statement” in this
section.
Rules for Exception Processing of the READ Statement
If the file position indicator shows that a next logical record does not exist, an optional
input file is not present, or the number of significant digits in the relative record number
is larger than the size of the relative key data item, the following rules apply:

•

A value of 24 is placed into the I-O status that is associated with file-name-1 to
indicate the AT END condition.

•

If the AT END phrase is specified in the statement causing the AT END condition,
control passes to imperative-statement-1 in the AT END phrase. Any USE AFTER
STANDARD EXCEPTION procedure that is associated with file-name-1 is not
executed.

•

If the AT END phrase is not specified, a USE AFTER STANDARD EXCEPTION
procedure must be associated with file-name-1, and that procedure is executed.
After that procedure is executed, control returns to the next executable statement
after the READ statement.

If an AT END or an invalid key condition does not occur during the execution of a READ
statement, the AT END phrase or the INVALID KEY phrase is ignored, if specified. The
following actions occur:

•

The file position indicator is set, and the I-O status associated with file-name-1 is
updated.

•

If an exception condition exists that is not an AT END or an invalid key condition,
control is transferred (according to the rules of the USE statement) after the
execution of any USE AFTER STANDARD EXCEPTION procedure that is associated
with file-name-1. The USE statement is described later in this section.

•

If an exception condition does not exist, the record is made available in the record
area, and any implicit move resulting from the presence of an INTO phrase is
executed. Control passes to the end of the READ statement or to imperativestatement-2, if specified. Execution continues according to the rules for each
statement specified in imperative-statement-2. If a procedure branching or a
conditional statement that explicitly transfers control is executed, control is
transferred according to the rules for that statement. Otherwise, upon completion of
the execution of imperative-statement-2, control passes to the end of the READ
statement.

If the AT END condition occurs, execution of the READ statement is unsuccessful. If a
READ statement is unsuccessful, the associated record area is undefined, the key of
reference is undefined for indexed files, and the I-O status is set to indicate that a valid
next record has not been established.
TADS: Any USE procedure is not executed when a READ statement that is compiled
and executed in a TADS session fails.

8600 1518–307

7–97

READ Statement

READ Statement Examples
The following paragraphs contain program examples and brief descriptions of how the
READ statement in each example is used.
FILE-CONTROL.
SELECT EMP-FILE ASSIGN TO DISK
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS ACC-NO
ALTERNATE RECORD KEY IS NAME WITH DUPLICATES.
DATA DIVISION.
FILE SECTION.
FD EMP-FILE.
01 EMP-NUMBER.
03 NAME
PIC X(10).
03 ACC-NO
PIC X(6).
03 BALANCE
PIC 9(6).
PROCEDURE DIVISION.
BEGIN.
OPEN I-O EMP-FILE.
MOVE "010000"TO ACC-NO.
START EMP-FILE KEY IS NOT LESS THAN ACC-NO
INVALID KEY PERFORM EDIT-KEY-TROUBLE.
READ EMP-FILE NEXT AT END PERFORM ERR-PARA.
.
.
.
EMP-FILE is an indexed file in dynamic access mode that is opened I/O. The value
“010000” is moved to ACC-NO. The first record with a key value not less than “010000”
is found, and the pointer is moved to that record. The INVALID KEY phrase is required.
When an invalid key condition exists, the EDIT-KEY-TROUBLE procedure is performed.
The file is processed beginning with the next record. Refer to “START Statement” in this
section for more information about its use with an indexed file.
READ EMP-FILE KEY IS NAME
INVALID KEY PERFORM ERROR1.
In this first example, EMP-FILE is an indexed file in random access mode. A key other
than the primary key is specified, which affects the order of the record delivery. A value
must be placed in NAME before a READ can occur. If an invalid key condition occurs,
ERROR1 is performed.

7–98

8600 1518–307

READ Statement

FILE-CONTROL.
SELECT EMP-FILE ASSIGN TO DISK
ORGANIZATION IS SEQUENTIAL
ACCESS MODE IS SEQUENTIAL.
DATA DIVISION.
FILE SECTION.
FD EMP-FILE.
01 EMP-NUMBER.
03 NAME
PIC X(10).
03 ACC-NO
PIC X(6).
03 BALANCE
PIC 9(6).
WORKING-STORAGE SECTION.
01 WK-AREA
PIC X(22).
PROCEDURE DIVISION.
BEGIN-PARA.
OPEN INPUT EMP-FILE.
READ EMP-FILE INTO WK-AREA
AT END PERFORM ERR-PARA.

In this second example, EMP-FILE is a sequential file. EMP-FILE is read into WK-AREA,
which is an identifier that refers to a data item in the working storage area. If an AT END
condition occurs, ERR-PARA is performed.
FILE-CONTROL.
SELECT EMP-FILE ASSIGN TO DISK
ORGANIZATION IS RELATIVE
ACCESS MODE IS RANDOM
RELATIVE KEY IS REC-KEY.
DATA DIVISION.
FILE SECTION.
FD EMP-FILE.
01 EMP-NUMBER.
03 NAME
PIC X(10).
03 ACC-NO
PIC X(6).
03 BALANCE
PIC 9(6).
WORKING-STORAGE SECTION.
01 REC-KEY
PIC 999.
01 WK-AREA
PIC X(22).
PROCEDURE DIVISION.
BEGIN-PARA.
OPEN I-O EMP-FILE.
MOVE 12 TO REC-KEY.
READ EMP-FILE INVALID KEY
PERFORM ERR-PARA.

In this third example, EMP-FILE is a relative file in random access mode. Before this file
is read, a value pointing to the ordinal position of the record is moved to the key. The
INVALID KEY phrase is required.

8600 1518–307

7–99

RECEIVE Statement

RECEIVE Statement
The RECEIVE statement enables a program to obtain data from another program in the
same multiprogramming mix or from a storage queue.

Format

Use

Format 1

This format is used to receive data in a synchronous way from
another program that is active in the same multiprogramming mix.
Format 1 uses the CRCR (core-to-core) capabilities of the MCP. For
an overview of CRCR functionality, refer to Format 1 of the SEND
Statement and to the Task Management Programming Guide.

Format 2

This format is used to receive data from a storage queue in an
asynchronous way. Format 2 uses the STOQUE (STOQ) capability of
the MCP. For an overview of the STOQ functionality, refer to Format
2 of the SEND Statement and to the Task Management Programming
Guide.

Format 1: Receive Data Synchronously
(CRCR)
RECEIVE
ïïïïïïï

ä identifier-1 å
ã
â
æ literal-1
ç

INTO identifier-2
ïïïï

[ ON EXCEPTION imperative-statement ]
ïïïïïïïïï
[ NOT ON EXCEPTION imperative-statement ]
ïïï
ïïïïïïïïï
[ END-RECEIVE ].
ïïïïïïïïïïï

Explanation
identifer-1
literal-1

This must be a nonnumeric data item that specifies the name of the program that is to
send the data. The program name must be a file title that contains a maximum of 256
characters. It is not necessary to terminate the file title with a period. If no usercode is
specified, the usercode of the receiving program is used. If the “ON ”
clause is used in the file title, it is ignored by the system in the comparison.
The program sending the data must be present in the mix.
If the value of identifier-1 or literal-1 is all blanks (called GLOBAL FILL), the receiving
program can receive data from any program in the mix that issues a CRCR SEND
statement.

7–100

8600 1518–307

RECEIVE Statement

identifier-2

This identifier must reference either an alphanumeric data item or a long numeric data
item in the receiving program where the transferred data is to be stored. If the size of the
sending and receiving fields is unequal, the smaller size is used, and the data is truncated
or filled with blanks, whichever is necessary.
The variable declared in the sending process can be of a different type than the variable
declared in the receiving process. However, the system does not perform any data
translation. The data received is a bit-image of the data that was sent.
ON EXCEPTION imperative-statement

This clause provides an alternate statement for the receiving program to perform if the
sending program is not ready (an exception condition.) If this clause is not used and the
sending program is not ready, the receiving program is suspended until the sending
program is ready.
NOT ON EXCEPTION imperative-statement

This clause provides a statement for the receiving program to perform after the data
transfer has successfully occurred.

Details
This format of the RECEIVE statement uses the CRCR (core-to-core) capabilities of the
MCP. CRCR is a synchronous communication method that enables a program to send
data to or receive data from another program that is present in the mix. Both programs
must be ready to communicate for the data transfer to occur.
If the program designated to receive the data does not execute a RECEIVE statement,
the sending program is suspended until the RECEIVE statement is executed. For details
about the CRCR functionality, refer to Format 1 of the SEND statement and to the Task
Management Programming Guide.

8600 1518–307

7–101

RECEIVE Statement

Format 2: Receive Data Asynchronously (STOQ)
ä TOP
å
ã ïïï
â identifier-1
æ BOTTOM ç
ïïïïïï
[ ON EXCEPTION imperative-statement-1 ]
ïïïïïïïïï
[ NOT ON EXCEPTION imperative-statement-2 ]
ïïï
ïïïïïïïïï
[ END-RECEIVE ].
ïïïïïïïïïïï
RECEIVE FROM
ïïïïïïï ïïïï

Explanation
TOP
BOTTOM

This determines whether the received data is to be retrieved from the top of the queue
or from the bottom of the queue.
identifier-1

This identifier must refer to a 01-level data-description-entry for a storage queue (STOQ)
parameter block.
ON EXCEPTION imperative-statement

This clause provides an alternate instruction to be performed if the queue is empty or no
individual entry satisfies the specified name (exception conditions.) If this clause is not
used and an exception condition exists, the receiving program is suspended until the
requested item is placed in the queue.
NOT ON EXCEPTION imperative-statement

This clause provides an instruction for the receiving program to perform after the data
transfer has occurred.

Details
To understand how the RECEIVE statement retrieves data from a queue, it is necessary
to know the structure of a storage queue (STOQ) parameter block. The STOQ parameter
block is a 01-level data description entry of the following format:
01 Identifier-1.
02 Queue-name
02 Entry-name-length
02 Entry-name
02 Entry-data-length
02 Entry-data

7–102

PIC
PIC
PIC
PIC
PIC

X(6).
9(2) COMP.
X(nn).
9(4) COMP.
X(nnnn).

8600 1518–307

RECEIVE Statement

For a detailed description of the STOQ parameter block and an overview of STOQ
functionality, refer to Format 2 of the SEND Statement and to the Task Management
Programming Guide.
Operation of the RECEIVE Statement
The RECEIVE statement causes the user program to receive data from the queue named
in the STOQ parameter block identified by identifier-1. If an entry-name is also specified
in the parameter block, the data is received from the item or items (sub-queue) within the
queue that match the entry-name. The data is placed in the entry-data field.
When the request is complete, execution resumes with either the statement included
with the NOT ON EXCEPTION clause, if specified, or with the next statement in the
program.
Size of Received Data
The size of the data is returned by the system and reflects the actual length of the data
returned.

If the data in the queue is . . .

Then . . .

Longer than the value in the
entry-data-length field

Only the first entry-data-length characters are
received.
The entry-data-length field is adjusted to show the
actual number of characters of the data in the queue.

Shorter than the value in the
entry-data-length field

The field is adjusted to show the actual number of
characters in the data.

Entry-Name
More than one item in the storage queue can have the same name; the entry name need
not be unique. Also, the name given to an item when sent by the SEND verb can be
longer than the name specified in the entry-name for a RECEIVE request. In either
situation, the queue is searched for an item whose name matches the entry-name in the
first entry-name-length of characters, as follows:

•

If you specify RECEIVE FROM TOP, the first entry from the top of the queue that
meets the selection criteria is chosen.

•

If you specify RECEIVE FROM BOTTOM, the first entry from the bottom of the
queue that meets the selection criteria is chosen.

Exception Conditions
If the queue is empty or if no individual entry satisfies the specified name, the ON
EXCEPTION condition exists. In that case,

•

If you included the ON EXCEPTION clause, the imperative-statement is executed.

•

If you did not include the ON EXCEPTION clause, the program is suspended until the
requested item is placed in the queue.

8600 1518–307

7–103

RELEASE Statement

RELEASE Statement
The RELEASE statement transfers records to the initial phase of a sort operation and
writes records to a sort file or a merge file.

RELEASE
ïïïïïïï

record-name-1

[ FROM identifier-1 ]
ïïïï

Explanation
record-name-1

Record-name must be the name of a logical record in a sort/merge file description entry.
It can be qualified.
FROM identifier-1

This option moves the contents of the data item referred to by identifier-1 to recordname-1.

Details
You can use a RELEASE statement only within the range of an input procedure. The
input procedure must be associated with a SORT statement for the file-name whose
sort/merge file description entry contains record-name-1.
Record-name-1 and identifier-1 cannot refer to the same storage area.
The execution of a RELEASE statement releases the record referred to by record-name-1
to the initial phase of a sort operation. That is, a RELEASE statement writes a record into
the sort/merge file.
Once you release a logical record by executing the RELEASE statement, the record is no
longer available in the record area. This is true unless the sort/merge file-name that is
associated with record-name-1 is specified in a SAME RECORD AREA clause. In this
case, the logical record is also available as a record of other files referenced in that SAME
RECORD AREA clause.
If you use the FROM phrase when you execute a RELEASE statement, the result is the
same as the execution of the following two statements, in order:
1. MOVE identifier-1 TO record-name-1
2. RELEASE record-name-1
In these statements, the contents of identifier-1 are moved to record-name-1. Then, the
contents of record-name-1 are released to the sort file. Movement occurs according to
the rules specified for the MOVE statement. Refer to “MOVE Rules” under “MOVE
Statement” in this section for more information about MOVE actions.

7–104

8600 1518–307

RELEASE Statement

After the execution of the RELEASE statement, the information in the area referred to by
identifier-1 is available. The information in the area referred to by record-name-1 is not
available, except as specified by the SAME RECORD AREA clause.
If you do not use the FROM phrase, you must use MOVE statements to move data into
the sort/merge file record area.

Related Information
The following table provides references for additional information related to this
statement:

For information about . . .

Refer to . . .

Sort/merge file descriptions

“File Description Entry” in Section 4

Sort/merge file operations

“Sort and Merge Operations,” “Sorting,”
“Merging,” and “Sort and Merge
Constructs” in Section 5

RELEASE and RETURN actions
(examples)

“RETURN Statement” in this section

Relationship of RELEASE statement to
SORT statement

“SORT Statement” in Section 8

8600 1518–307

7–105

REPLACE Statement

REPLACE Statement
The REPLACE statement replaces source program text.

Format

Use

Format 1

This format starts REPLACE operations.

Format 2

This format discontinues REPLACE operations.

Format 1: Start REPLACE Operations
REPLACE { ==pseudo-text-1==
ïïïïïïï

==pseudo-text-2== }

. . .

Explanation
REPLACE . . . BY

This syntax specifies the text of the source program to be replaced and describes the
text that is to replace it. Each matched occurrence of pseudo-text-1 in the source
program is replaced by the corresponding pseudo-text-2.
pseudo-text-1
pseudo-text-2

Pseudotext is a sequence of text words, comment lines, or a separator space in a source
program. Double equal signs (=) serve as delimiters. For more information on
pseudotext, refer to Section 1.
Pseudo-text-1 must contain one or more text words and must not consist entirely of
commas (,) or semicolons (;). Pseudo-text-2 can contain zero, one, or more text words.
Character-strings in pseudo-text-1 and pseudo-text-2 can be continued.

Details
Each occurrence of a REPLACE statement is in effect from the point at which it is
specified to the next occurrence of the REPLACE statement or to the end of the
separately compiled program.
REPLACE statements in a source program are processed after COPY statements. Refer
in Section 6 to “COPY Statement,” which copies text from a library program into the
program that contains the COPY statement.

7–106

8600 1518–307

REPLACE Statement

Rules
A REPLACE statement can occur in the source program anywhere a character-string can
occur. The statement must be preceded by a period (.) unless it is the first statement in a
separately compiled program.
A REPLACE statement must be terminated by a separator period.
If the word REPLACE appears in a comment-entry or in the area where a comment-entry
can appear, it is recognized as part of the comment-entry.
The text produced by a REPLACE statement must not contain another REPLACE
statement.
A text word in pseudotext can be from 1 through 322 characters long.
Text Replacement Comparisons
During text replacement operations, the following comparisons occur:
1. The text words in pseudo-text-1 are compared to an equivalent number of
contiguous source program text words. The comparison begins with the leftmost
source program text word and the first word in pseudo-text-1.
2. If the ordered sequence of text words that forms pseudo-text-1 is equal, character
for character, to the ordered sequence of source program text words, a match of the
source program text occurs. During comparisons, each occurrence of a separator
comma, semicolon, or space in pseudo-text-1 or in the source program text is
recognized as a single space. Each sequence of one or more space separators is
recognized as a single space.
a.

If a match does not occur, each new comparison begins with each successive
occurrence of pseudo-text-1, until either a match is found or a successive
occurrence of pseudo-text-1 does not exist.

b. When all occurrences of pseudo-text-1 have been compared and a match has not
occurred, the next source program text word becomes the leftmost source
program text word. Then, the comparison cycle begins again with the first
occurrence of pseudo-text-1.
c.

When a match occurs between pseudo-text-1 and the source program text, the
corresponding pseudo-text-2 replaces the matched text in the source program.
The source program text word immediately following the rightmost text word
that participated in the match becomes the leftmost source program text word.
Then, the comparison cycle begins again with the first occurrence of pseudotext-1.

3. The comparison cycles continue until the rightmost text word in the source program
text that is in the scope of the REPLACE statement either has participated in a
match, or has become the leftmost source program text word and has participated in
a complete comparison cycle.

8600 1518–307

7–107

REPLACE Statement

Comment Lines
Comment lines or blank lines that appear in the source program text and in pseudo-text-1
are ignored during comparisons. The rules for reference format determine the sequence
of text words in the source program text and in pseudo-text-1. For a description of
reference format, see Section 1.
If a comment line or a blank line appears in the sequence of text words that match
pseudo-text-1, it is not copied into the resultant source program text. Comment lines or
blank lines in pseudo-text-2 are inserted, unchanged, in the resultant program whenever
pseudo-text-2 is inserted in the source program by a REPLACE statement.
Debugging Lines
Pseudotext permits debugging lines, which are identified by a D in the indicator area.
Text words within a debugging line participate in the matching rules as if the D were not
present in the indicator area.
Except for COPY and REPLACE statements, the syntactic accuracy of the source
program text cannot be determined until all COPY and REPLACE statements have been
processed completely.
Text Words
Text words that are inserted in the source program by a REPLACE statement are
inserted in the source program according to the rules for reference format.
When text words of pseudo-text-2 are inserted in the source program, additional spaces
can be introduced only between text words where a space already exists (including the
assumed space between source lines).
Additional Lines
If additional lines are introduced in the source program by REPLACE statements, the
indicator area of the introduced lines contains the same character as the line on which
the text being replaced begins. However, if that line contains a hyphen (-), the introduced
line contains a space.
Literals
If the length of any literal in pseudo-text-2 is too long to fit on a single line in the resultant
program, and the literal is not on a debugging line, additional continuation lines are
introduced for the remainder of the literal. If replacement requires that the literal be
continued on a debugging line, the program is in error.

7–108

8600 1518–307

REPLACE Statement

Format 2: Discontinue REPLACE Operations
REPLACE OFF
ïïïïïïï ïïï

Explanation
REPLACE OFF

This syntax discontinues any text replacement currently in effect.

Details
A REPLACE statement can be stopped in one of two ways:

•

If you specify a new REPLACE . . . BY statement

•

If you specify REPLACE OFF

Rules
A REPLACE statement can occur in the source program anywhere a character-string can
occur. The statement must be preceded by a separator period unless it is the first
statement in a separately compiled program.
A REPLACE statement must be terminated by a separator period.
If the word REPLACE appears in a comment-entry or in the area where a comment-entry
can appear, it is recognized as part of the comment-entry. (In COBOL ANSI-85,
comment-entry is an obsolete element and will be deleted from the next revision of
standard COBOL.)

Related Information
The following table provides references for additional information related to this
statement:

For information about . . .

Refer to . . .

Sort and merge file operations

“Sort and Merge Operations,” “Sorting,”
“Merging,” and “Sort and Merge
Constructs” in Section 5

The relationship of the RETURN
statement to the MERGE and SORT
statements

“MERGE Statement” in this section and
“SORT Statement” in Section 8

Valid and invalid move actions

“MOVE Statement” in this section

8600 1518–307

7–109

REPLACE Statement

Examples
REPLACE ==PICTURE-68== BY ==REC-1==
==CMP== BY ==COMP==.
02 PICTURE-68
PIC 99 CMP.
REPLACE OFF.
In this example, REC-1 and COMP replace PICTURE-68 and CMP. REPLACE OFF cancels
the REPLACE statement. You can also cancel one REPLACE statement by introducing
another REPLACE statement.
The REPLACE statement is especially useful for resolving conflicts between the new
COBOL ANSI-85 reserved words and user-defined words in COBOL ANSI-74 or COBOL
ANSI-68 programs. For example, the following REPLACE statement changes several
user-defined words that are acceptable in COBOL ANSI-68 and COBOL ANSI-74 (but not
in COBOL ANSI-85) into user-defined words acceptable in COBOL ANSI-85:
REPLACE ==WITH DEBUGGING MODE== BY == ==
==ORDER==
BY ==SEQUENCE==
==TEST==
BY ==TEST-CASE==
==CONVERTING==
BY ==CONVERTING-TO==
==CONTENT==
BY ==CONTENT-OF==
==PURGE==
BY ==REMOVE==.

In this example, several user-defined words replace new reserved words. To remove text
from a source program, insert two equal signs, a space, and two more equal signs (==
==) following the word BY. In this example, WITH DEBUGGING MODE is removed from
the program because the DEBUG module is an obsolete element in COBOL ANSI-85 and
will be deleted from the next revision of standard COBOL.

7–110

8600 1518–307

RESET Statement

RESET Statement
The RESET statement turns off specified events.

RESET event-identifier-1 [ ,event-identifier-2 ] . . .
ïïïïï

Explanation
event-identifier-1
event-identifier-2 . . .

The event-identifier can be one or more of the following:

•

The name of a data-item declared with the USAGE IS EVENT phrase. The data-name
must be properly qualified and properly subscripted.

•

A task attribute of type EVENT. The two event task attributes are ACCEPTEVENT
and EXCEPTIONEVENT. For details about these task attributes, refer to the Task
Attributes Programming Reference Manual.

•

Example
RESET WS-01-EVENT.

8600 1518–307

7–111

RETURN Statement

RETURN Statement
The RETURN statement obtains sorted or merged records from the final phase of a
SORT or MERGE operation.

RETURN file-name-1 RECORD [ INTO identifier-1 ]
ïïïïïï
ïïïï
AT END imperative-statement-1
ïïï
[ NOT AT END imperative-statement-2 ]
ïïï ïï ïïï
[ END-RETURN ]

Explanation
file-name-1

This user-defined word is the name of a sort or merge file. File-name-1 must be
described in a sort-merge file description entry in the Data Division.
INTO identifier-1

This option returns records to a record area and to a data item referred to by identifier-1.
The record is available in both the record area and the data item referred to by identifier1.
AT END imperative-statement-1

This option enables you to include an imperative statement that specifies an action to be
taken if the AT END condition occurs. If the file is at the end (there is no next logical
record) and the AT END phrase is specified, imperative-statement-1 will be executed.
A possible value for imperative-statement-1 is the literal “NEXT SENTENCE.” This phrase
is valid only for sequential files. If an end-of-file condition occurs, this phrase causes
control to be passed to the next executable statement.
NOT AT END imperative-statement-2

This option enables you to include an imperative statement that specifies an action to be
taken if the NOT AT END phrase is specified. If the file is not at the end and the NOT AT
END phrase is specified, imperative-statement-2 is executed.
END-RETURN

This phrase delimits the scope of the RETURN statement.

7–112

8600 1518–307

RETURN Statement

Details
The storage area associated with identifier-1 and the record area associated with filename-1 cannot be the same storage area.
You can use a RETURN statement only within the range of an output procedure that is
associated with a SORT or a MERGE statement for file-name-1.
When the logical records in a file are described by more than one record description,
these records share the same storage area. This sharing is the same as an implicit
redefinition of the area. Note that the contents of any data items that are outside the
range of the current data record are undefined when the execution of the RETURN
statement is complete.
The execution of the RETURN statement transfers the next existing record in the file
referred to by file-name-1 (as determined by the keys listed in the SORT or MERGE
statement) to the record area that is associated with file-name-1.

8600 1518–307

7–113

RETURN Statement

Function of the RETURN Statement
When the RETURN
statement is executed
and . . .

7–114

Then . . .

And . . .

A next logical record does
not exist in the file
referred to by file-name-1.

The “at end” condition
exists.

Control passes to
imperative-statement-1 of
the AT END phrase.
Execution continues
according to the rules for
each statement specified
in imperative-statement-1.

Imperative-statement-1 is
a procedure-branching or
conditional statement that
explicitly transfers control.

The statement is
executed.

Control is transferred
according to the rules for
that statement.

Imperative-statement-1 is
not a statement that
explicitly transfers control.

The statement is
executed.

Control passes to the end
of the RETURN statement
and the NOT AT END
phrase is ignored, if
specified.

The “at end” condition
occurs.

Execution of the RETURN
statement is
unsuccessful. In this case,
the contents of the record
area that is associated
with file-name-1 are
undefined. After the
execution of imperativestatement-1 in the AT
END phrase, a RETURN
statement cannot be
executed as part of the
current output procedure.

An “at end” condition
does not occur.

The record is made
available and any implicit
move resulting from the
presence of an INTO
phrase is executed.

Control passes to
imperative-statement-2, if
specified.

8600 1518–307

RETURN Statement

Specifying the INTO Phrase
The INTO phrase can be specified in a RETURN statement when either of the following
conditions is true:

•

Only one record description is subordinate to the sort-merge file description entry.

•

All record-names associated with file-name-1 and the data item referred to by
identifier-1 describe a group item or an elementary alphanumeric item.

The result of executing a RETURN statement with an INTO phrase is the same as the
application of the following two rules, in order:
1. The execution of the same RETURN statement without the INTO phrase.
2. An implied MOVE statement, in which the current record is moved from the record
area to the area specified by identifier-1, according to the rules for the MOVE
statement without the CORRESPONDING phrase. In this operation, the size of the
current record is determined by rules specified for the RECORD clause. If the file
description entry contains a RECORD IS VARYING clause, the implied move is a
group move. The implied MOVE statement is not performed if the execution of the
RETURN statement was unsuccessful. Any subscripting associated with identifier-1
is evaluated after the record has been read and immediately before it is moved to the
data item.

Example
FILE CONTROL.
SELECT FILE-1
ASSIGN TO DISK.
SELECT FILE-2
ASSIGN TO DISK.
SELECT SRT-FIL
ASSIGN TO SORT.
DATA DIVISION.
FILE SECTION.
FD
FILE-1.
01
F1REC.
03 FILLER
PIC X(180).
FD
FILE-2.
01
F2REC.
03 FILLER
PIC X(180).
SD
SRT-FIL.
01
SREC.
03 FILLER
PIC X(10).
03 ACC-NO
PIC 9(6).
03 FILLER
PIC X(10).
03 BAL-DUE
PIC 9(20).
PROCEDURE DIVISION.
BEGIN.
SORT SRT-FIL
ON ASCENDING KEY ACC-NO
INPUT PROCEDURE IS PROC-1 THRU END-1
OUTPUT PROCEDURE IS PROC-2 THRU END-2.
.
.

8600 1518–307

7–115

RETURN Statement

.
PROC-1.
OPEN INPUT FILE-1.
PROC-1A.
READ FILE-1 AT END GO TO END-1.
.
.
.
RELEASE SREC FROM F1REC.
GO TO PROC-1A.
END-1.
CLOSE FILE-1.
PROC-2.
OPEN OUTPUT FILE-2.
RETURN SRT-FIL INTO F2REC AT END GO TO END-2.
WRITE F2REC.
.
.
.
END-2.
CLOSE FILE-2.
The input procedure occurs first. FILE-1 is opened and read. Then, its record is released
from F1REC to SORT. After the file is sorted, the output procedure begins. FILE-2 is
opened, and the sorted records are returned to F2REC and written to the disk file.

7–116

8600 1518–307

REWRITE Statement

REWRITE Statement
The REWRITE statement logically replaces a record that exists in a mass-storage file.
This statement is partially supported in a TADS environment. Applicable exclusions are
noted in this section.

Format

Use

Format 1

This format is for sequential files.

Format 2

This format is for relative and indexed files.

Format 1: Sequential Files
REWRITE
ïïïïïïï

record-name-1

[ SYNCHRONIZED ]
ïïïïïïïïïïïï
[ FROM identifier-1 ] [ END-REWRITE ]
ïïïï
ïïïïïïïïïïï

This format is supported in the TADS environment.

Explanation
record-name-1

This user-defined word names a logical record in the File Section of the Data Division. It
can be qualified.
SYNCHRONIZED

This option enables you to override the synchronization specified by the file attribute for a
specific output record.
Synchronization means that output must be written to the physical file before the
program initiating the output can resume execution, thereby ensuring synchronization
between logical and physical files. Synchronization of all output records can be
designated with the SYNCHRONIZE file attribute. Synchronization is available for use by
tape files and disk files with sequential organization only, and is not available for use by
port files.
A periodic synchronous REWRITE statement that follows one or more asynchronous
REWRITE statements can be used as a checkpoint to ensure that all outstanding records
are written to the file before the program continues execution.

8600 1518–307

7–117

REWRITE Statement

FROM identifier-1

This option enables you to move data from the data item referred to by identifier-1 into a
record, and then to rewrite the record. If identifier-1 is a function-identifier, it must
reference an alphanumeric function. If identifier-1 is not a function-identifier, it cannot
reference the same storage area as record-name-1.
END-REWRITE

This phrase delimits the scope of the REWRITE statement.

Details
A successfully executed READ statement must have been the last input-output
statement executed for the associated file before the execution of the REWRITE
statement. The disk or disk pack logically replaces the record that was accessed by the
READ statement.
If the number of character positions specified in the record referred to by record-name-1
is not equal to the number of character positions in the record being replaced, then

•

The execution of the REWRITE statement is unsuccessful.

•

The record is not updated.

•

The content of the record area is unaffected.

•

The I-O status of the file associated with record-name-1 is set to 44. Refer to "I-O
Status Codes" in Section 3 for more information.

Refer to the paragraphs headed “Rules for All File Organizations” in this section for more
information on Format 1.

Example
READ MST-FIL AT END PERFORM END-LOGIC.
REWRITE MST-FIL-REC FROM DATA-AREA.
In this example, MST-FIL-REC is obtained from DATA-AREA (another area of storage) and
is rewritten.

7–118

8600 1518–307

REWRITE Statement

Format 2: Relative and Indexed Files
REWRITE record-name-1 [ SYNCHRONIZED ] [ FROM identifier-1 ]
ïïïïïïï
ïïïïïïïïïïïï
ïïïï
[ INVALID KEY imperative-statement-1 ]
ïïïïïïï
[ NOT INVALID KEY imperative-statement-2 ]
ïïï ïïïïïïï
[ END-REWRITE ]
ïïïïïïïïïïï
This format is supported in the TADS environment.

Explanation
Refer to Format 1 for descriptions of the syntax elements record-name-1, FROM
identifier-1, and END-REWRITE.
SYNCHRONIZED

This phrase enables you to specify an action to be taken when the key is invalid.
NOT INVALID KEY imperative-statement-2

This phrase enables you to specify an action to be taken when the key is valid.

8600 1518–307

7–119

REWRITE Statement

Details
Rules for All File Organizations
Record-name-1 and identifier-1 must not refer to the same storage area.
The file referred to by the file-name that is associated with record-name-1 must be a
mass-storage file and must be open in I-O mode at the time the REWRITE statement is
executed. Refer to “OPEN Statement” in this section for more information on opening a
file in the I-O mode.
Execution of the REWRITE statement does not affect the contents or accessibility of the
record area.
Execution of a REWRITE statement with the FROM phrase is the same as the execution
of the statement “MOVE identifier-1 TO record-name-1” (according to the MOVE
statement rules), followed by the execution of the same REWRITE statement without
the FROM phrase. Refer to “MOVE Statement” in this section for more information on
the MOVE rules.
After execution of the REWRITE statement is complete, information in the area referred
to by identifier-1 is available. However, information in the area referred to by recordname-1 is not available except as specified in the SAME RECORD AREA clause.
The file position indicator is not affected by the execution of a REWRITE statement.
Execution of the REWRITE statement updates the value of the I-O status of the filename associated with record-name-1. Also, execution of the REWRITE statement
releases a logical record to the operating system. Refer to “I-O Status Codes” in Section
3 for more information on I-O status.
TADS: Any USE procedure is not executed when a REWRITE statement that is
compiled and executed in a TADS session fails.
Specifying the INVALID KEY and NOT VALID KEY Phrases
Transfer of control after the successful or unsuccessful execution of the REWRITE
operation depends on the presence or absence of the INVALID KEY and NOT INVALID
KEY phrases in the REWRITE statement.
For relative files in the random or dynamic access mode, you must specify the INVALID
KEY phrase in the REWRITE statement. However, for relative files in sequential access
mode, do not specify the INVALID KEY and the NOT INVALID KEY phrases in a
REWRITE statement.
For relative and indexed files, if you do not specify an applicable USE AFTER STANDARD
EXCEPTION procedure for the associated file-name, you must specify the INVALID KEY
and the NOT INVALID KEY phrases.
TADS: Any USE procedure is not executed when a REWRITE statement that is
compiled and executed in a TADS session fails.

7–120

8600 1518–307

REWRITE Statement

Invalid Key Condition (Indexed Files)
For an indexed file, the invalid key condition exists under any of the following conditions:

•

When the file is open in the sequential access mode, and the value of the prime
record key of the record to be replaced is not equal to the value of the prime record
key of the last record read from the file

•

When the file is open in the dynamic or random access mode, and the value of the
prime record key of the record to be replaced is not equal to the value of the prime
record key of any record existing in the file

•

When the value of an alternate record key of the record to be replaced, for which
duplicates are not allowed, equals the value of the corresponding data item of a
record already in the file

Results of Invalid Key Condition
The invalid key condition has the following effects on relative and indexed files:

•

The execution of the REWRITE statement is unsuccessful.

•

The record is not updated.

•

The content of the record area is unaffected.

•

The I-O status of the file associated with record-name-1 is set to a value that
indicates that an invalid key condition has occurred. Refer to "I-O Status Codes" in
Section 3 for more information. Status codes 21, 22, and 23 can indicate an invalid
key condition.

Rules for Record Length
For fixed-length records, the number of character positions in the record referred to by
record-name-1 must be equal to the number of character positions in the record being
replaced.
For variable-length records, the number of character positions in the record referred to by
record-name-1 must not be larger than the largest or smaller than the smallest number of
character positions specified in the RECORD IS VARYING clause for the file-name that is
associated with record-name-1.
If the number of character positions is larger or smaller than the number allowed, then

•

The execution of the REWRITE statement is unsuccessful.

•

The record is not updated.

•

The content of the record area is unaffected.

•

The I-O status of the file associated with record-name-1 is set to 44. Refer to "I-O
Status Codes" in Section 3 for more information.

8600 1518–307

7–121

REWRITE Statement

Record Replacement by the REWRITE Statement
For a relative file in random or dynamic access mode, the disk or disk pack logically
replaces the record specified by the content of the relative key data of the file-name that
is associated with record-name-1. If the file does not contain the record specified by the
key, the invalid key condition exists.
For an indexed file in the sequential access mode, the record to be replaced is specified
by the value of the prime record key. When REWRITE is executed, the value of the prime
record key of the record to be replaced must equal the value of the prime record key of
the last record read from this file.
For an indexed file in random or dynamic access mode, the record to be replaced is
specified by the prime record key.
Effect of REWRITE on Indexed Files with Alternate Record Keys
Execution of the REWRITE statement for an indexed file that has an alternate record key
occurs in one of the following ways:

•

When the value of a specific alternate record key is not changed and when that key
is the key of reference, the order of retrieval is unchanged.

•

When the value of a specific alternate record key is changed, the subsequent order
of retrieval of that record can be changed when that alternate record key is the key
of reference. When duplicate key values are permitted, the record is logically
positioned last within the set of duplicate records that contains the same alternate
record key value as the alternate record key value that was inserted in the record.

Example
REWRITE RANDM-FIL-REC INVALID KEY PERFORM ERR-PARA.
In this example, RANDM-FIL-REC is rewritten. If the invalid key condition exists, ERRPARA is performed.

7–122

8600 1518–307

RUN Statement

RUN Statement
The RUN statement enables a program to initiate another program as an asynchronous,
independent process.

RUN task-variable WITH section-name
ïïï
ïïïï
[ USING arithmetic-expression-1 [ ,arithmetic-expression-2 ] . . . ].
ïïïïï

Explanation
task-variable

This specifies the task variable that is to be associated with the program specified in the
section identified by section-name. The task variable must be declared as a data item in
the Working-Storage section of the Data Division. For more information about task
variables, refer to the USAGE clause in Section 4 and to Section 11.
section-name

This identifies the section in the Procedure Division that contains the name of the object
code file that is to be initiated by this RUN statement. You must define the section-name
in the Declaratives Section of the Procedure Division followed by a USE EXTERNAL
statement that specifies the name of the object code file.
USING arithmetic-expression

Only parameters with arithmetic values can be referenced in the USING phrase. The
formal parameters to which the values of the arithmetic expressions are passed must be
described as single-precision or double-precision 77-level data items and must have a
RECEIVED BY CONTENT clause.
To ensure that the passed value has the same precision as the corresponding formal
parameter, the compiler truncates double-precision values to single precision and
extends single-precision values to double precision. All values are passed with a scale of
0, regardless of the scale of the corresponding formal parameter. All values can be
passed as normalized values.

8600 1518–307

7–123

RUN Statement

Details
The RUN statement initiates a program as an asynchronous, independent process. An
asynchronous process executes simultaneously with the program that initiated it. An
independent process does not share the resources of the initiating program; thus, it can
continue to execute if the initiating program is terminated.
Naming the Program to Be Initiated
You can specify the name of the program to be executed by the RUN statement in one
of the following ways:

•

Precede the CALL statement with a CHANGE statement that changes the NAME
attribute of the task variable before the program is called.

•

Define a mnemonic-name in the Special-Names paragraph of the Environment
Division, and then use it in the USE EXTERNAL statement.

•

Use the following steps:

−

Declare a data item in the Working-Storage section of the Data Division.

−

Name the data item in a USE EXTERNAL statement in the Declarative Section of
the Procedure Division.

−

Assign the object code file title to the data item by using a MOVE statement in
the Procedure Division.

For program examples that show how to name the program to be initiated, refer to
Section 11.

Example
Following is an example:
IDENTIFICATION DIVISION.
PROGRAM-ID. RUN-TASK-CALLER-WPARM.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 IND-TASK
TASK.
01 WS-PROGID.
05 WS-PID-1
PIC X(11) VALUE "OBJECT/".
05 WS-PID2
PIC X(03) VALUE "C85".
05 WS-PID3
PIC X(18) VALUE "/RUN/CALLED/WPARM.".
77 WS-77-BINARY
PIC 9(11) BINARY.
77 WS-77-REAL
REAL.
77 WS-77-BINARY-DBL
PIC 9(23) BINARY.
77 WS-77-DOUBLE
DOUBLE.
LOCAL-STORAGE SECTION.
LD HOW-PARAMS-PASSED.
77 LS-77-BINARY-CON
PIC 9(11) BINARY CONTENT.
77 LS-77-REAL-CON
REAL RECEIVED BY CONTENT.
77 LS-77-BINARY-DBL-CON
PIC 9(23) BINARY CONTENT.

7–124

8600 1518–307

RUN Statement

77 LS-77-DOUBLE-CON
DOUBLE RECEIVED BY CONTENT.
PROCEDURE DIVISION.
DECLARATIVES.
RUN-A-PROCESS SECTION.
USE EXTERNAL AS PROCEDURE WITH HOW-PARAMS-PASSED USING
LS-77-BINARY-CON
LS-77-REAL-CON
LS-77-BINARY-DBL-CON
LS-77-DOUBLE-CON.
END DECLARATIVES.
MAIN SECTION.
MAIN-PARA.
CHANGE ATTRIBUTE NAME OF IND-TASK TO WS-PROGID.
RUN IND-TASK WITH RUN-A-PROCESS USING
WS-77-BINARY WS-77-REAL WS-77-BINARY-DBL WS-77-DOUBLE.
STOP RUN.
C85/RUN/CALLED/WPARM:
IDENTIFICATION DIVISION.
PROGRAM-ID. C85-RUN-CALLED-WPARM.
ENVIRONMENT DIVISION.
DATA DIVISION.
LINKAGE SECTION.
77 WS-1
PIC 9(11) BINARY.
77 WS-2
REAL.
77 WS-3
PIC 9(23) BINARY.
77 WS-4
DOUBLE.
*
PROCEDURE DIVISION USING
WS-1, WS-2, WS-3, WS-4,
MAIN SECTION.
MAIN-PARAG.
DISPLAY "THIS IS THE CALLED PROGRAM".
EXIT PROGRAM.

8600 1518–307

7–125

RUN Statement

7–126

8600 1518–307

Section 8
Procedure Division Statements S–Z
This section illustrates and explains the syntax of the Procedure Division statements.
Statements beginning with the letters S through Z are listed in alphabetical order with the
following information:

•

A brief description of the function of the statement

•

A syntax diagram for each format of the statement (if you need information on how
to interpret a COBOL syntax diagram, refer to Appendix C).

•

A statement of what portion of the syntax, if any, can be used interactively in a Test
and Debug System (TADS) session

•

An explanation of the elements in the syntax diagram

•

Details, rules, and restrictions about the particular statement

•

An example of the statement

•

References to additional information relevant to the statement

8600 1518–307

8–1

SEARCH Statement

SEARCH Statement
The SEARCH statement searches a table for an element that satisfies a specified
condition, and adjusts the value of the associated index to point to that table element.
Use the SEARCH statement only for indexed tables; do not use it for subscripted tables.

Format

Use

Format 1

This format performs a serial search on an unordered table. An unordered
table is not arranged in a particular order.

Format 2

This format performs a binary search on an ordered table. An ordered table
is arranged in ascending or descending order.

Format 1: SEARCH . . . VARYING (Serial Search)
Ú
³
ä identifier-2 å
SEARCH identifier-1 ³ VARYING ã
â
ïïïïïï
³ ïïïïïïï æ index-name-1 ç
À
[ AT END imperative-statement-1 ]
ïïï
ä
ä imperative-statement-2 å
ã WHEN condition-1 ã
â
æ ïïïï
æ NEXT SENTENCE
ç
ïïïï ïïïïïïïï
[ END-SEARCH ]
ïïïïïïïïïï

¿
³
³
³
Ù
å
â . . .
ç

Explanation
identifier-1

This user-defined data item can be neither subscripted nor reference-modified. However,
its description must contain an OCCURS clause that includes an INDEXED BY phrase.
Refer to “OCCURS Clause” in Section 4 for more information.
VARYING

This phrase enables you to increment an index-name and the associated index for a table
you are searching.

8–2

8600 1518–307

SEARCH Statement

identifier-2

This element must refer to a data item that is described in one of the following ways:

•

A data item that is declared in the Data Division with the USAGE IS INDEX clause

•

A numeric elementary data item without any positions to the right of the assumed
decimal point

This element cannot be subscripted by the first (or only) index-name specified in the
INDEXED BY phrase of the OCCURS clause that is associated with identifier-1.
index-name-1

This user-defined word names an index associated with a specific table.
AT END imperative-statement-1

This option enables you to include an imperative statement that specifies an action to be
taken if the at end condition occurs. If there are no more elements in the table and you
specify the AT END phrase, then imperative-statement-1 is executed.
WHEN condition-1

This phrase indicates what condition must be met for the search of the table to be
terminated. Condition-1 can be any conditional expression. Refer to “Conditional
Expressions” in Section 5 for more information.
imperative-statement-2

This option enables you to include an imperative statement that specifies an action to be
taken when all conditions in the WHEN phrase are satisfied.
NEXT SENTENCE

This phrase transfers control to the next executable sentence when all conditions in the
WHEN phrase are satisfied.
END-SEARCH

This phrase delimits the scope of the SEARCH statement. If the END-SEARCH phrase is
specified, the NEXT SENTENCE phrase must not be specified.

8600 1518–307

8–3

SEARCH Statement

Details
A serial search begins with the current index setting. The object program inspects each
table entry from the current index setting to the end of the table until it finds a match. If
you want to search the entire table, the value of the current index setting must be equal
to one. If the table is large, a serial search is very time consuming.
You can terminate the scope of the SEARCH statement by including:

•

An END-SEARCH phrase at the same level of nesting

•

A separator period

•

An ELSE or END-IF phrase that is associated with a previous IF statement

The following paragraphs describe how specific phrases in the SEARCH statement
syntax affect the operation of the SEARCH statement.
Identifier-1
The number of occurrences of identifier-1, the last of which is the highest permissible
occurrence, is discussed under “OCCURS Clause” in Section 4. The following table
indicates how the value of identifier-1 affects the SEARCH statement.

If the index-name associated with
identifier-1 contains a value that
corresponds to an occurrence number
that is . . .

8–4

Then the SEARCH statement . . .

Greater than the highest permissible
occurrence number for identifier-1

Stops immediately.

Not greater than the highest permissible
occurrence number for identifier-1

Evaluates the conditions in the order that
they are written, makes use of index
settings (wherever specified), and
determines the occurrence of items to be
tested.

8600 1518–307

SEARCH Statement

VARYING Phrase
The following paragraphs explain the effect of the VARYING phrase on the SEARCH
statement.

•

If you do not specify the VARYING phrase, the index-name used for the search is the
first (or only) index-name specified in the INDEXED BY phrase of the OCCURS clause
that is associated with identifier-1. Any other index-names for identifier-1 remain
unchanged.

•

If you specify the VARYING index-name-1 phrase, and if index-name-1 appears in the
INDEXED BY phrase in the OCCURS clause referred to by identifier-1, that indexname is used for this search. If this is not the case, or if you specify the VARYING
identifier-2 phrase, the first (or only) index-name given in the INDEXED BY phrase in
the OCCURS clause referred to by identifier-1 is used for the search.

•

If you specify the VARYING index-name-1 phrase, and if index-name-1 appears in the
INDEXED BY phrase in the OCCURS clause referred to by another table entry, the
occurrence number represented by index-name-1 is incremented at the same time
and by the same amount as the occurrence number represented by the index-name
associated with identifier-1.

•

If you specify the VARYING identifier-2 phrase, and identifier-2 is an index data item,
then the data item referred to by identifier-2 is incremented at the same time and by
the same amount as the index associated with identifier-1. If identifier-2 is not an
index data item, the data item referred to by identifier-2 is incremented by the value
one (1) at the same time as the index referred to by the index-name associated with
identifier-1.

AT END Phrase
If you specify the AT END phrase, imperative-statement-1 is executed. If you do not
specify the AT END phrase, control passes to the end of the SEARCH statement.
Imperative-Statement-1, Imperative-Statement-2
After the execution of an imperative-statement-1, or an imperative-statement-2 that does
not terminate with a GO TO statement, control passes to the end of the SEARCH
statement. Refer to “GO TO Statement” in this section for more information.
WHEN Phrase
If none of the conditions are satisfied, the index-name for identifier-1 is incremented to
refer to the next occurrence. The process is then repeated using the new index-name
settings, unless the new value of the index-name setting for identifier-1 corresponds to a
table element outside the permissible range of occurrence values. In this case, the
search stops immediately.
If one of the conditions is satisfied upon evaluation, the search stops immediately.
Control passes to the imperative statement associated with that condition, if present.
However, if the NEXT SENTENCE phrase is associated with that condition, control
passes to the next executable sentence. The index-name remains set at the occurrence
that caused the condition to be satisfied.

8600 1518–307

8–5

SEARCH Statement

If any of the conditions specified in the WHEN phrase cannot be satisfied for any setting
of the index within the permitted range, control passes to imperative-statement-1 if the
AT END phrase is specified. If the AT END phrase is not specified, control passes to the
end of the SEARCH statement. In either case, the final setting of the index cannot be
predicted.
If all conditions can be satisfied, the index indicates an occurrence that permits the
conditions to be satisfied. In this case, control passes to imperative-statement-2, if
specified, or to the next executable sentence, if the NEXT SENTENCE phrase is
specified.
Figure 8–1 represents the action of a Format 1 SEARCH statement that contains two
WHEN phrases.

Figure 8–1. Format 1 SEARCH Statement with Two WHEN Phrases
*

These operations are options included only when specified in the SEARCH
statement.

** Each of these steps transfers control to the end of the SEARCH statement, unless
the imperative statement ends with a GO TO statement.

8–6

8600 1518–307

SEARCH Statement

Example
05 TBL OCCURS 14 TIMES INDEXED BY J.
SEARCH TBL VARYING ALT-INX AT END PERFORM END-PARA
WHEN TBL(J) = "A"PERFORM ACCT-PARA
WHEN TBL(J) = "C"PERFORM COST-PARA
WHEN TBL(J) = "D"PERFORM DELIVERY-PARA
END-SEARCH.
In this example, J points to the table element where a serial search begins. The entire
table (from the current index setting) is searched for matches to the three WHEN
conditions. If a match occurs, the imperative statement is performed and control passes
to the END-SEARCH phrase. If a match does not occur, control passes to the AT END
phrase. Because VARYING is specified, the occurrence number represented by ALT-INX
is incremented at the same time and by the same amount as the occurrence number
represented by J.

8600 1518–307

8–7

SEARCH Statement

Format 2: SEARCH ALL (Binary Search)
SEARCH ALL identifier-1 [ AT END imperative-statement-1 ]
ïïïïïï ïïï
ïïï
ä
ä IS EQUAL TO å ä identifier-3
å
³ data-name-1
ã
ïïïïï
â ã literal-1
â
³
æ IS =
ç æ arithmetic-expression-1 ç
WHEN ã
ïï
ïïïï ³
³ condition-name-1
æ
Ú
³
ä
ä IS EQUAL TO å ä identifier-4
å
³
³ data-name-2 ã
ïïïïï
â ã literal-2
â
³
³
æ IS =
ç æ arithmetic-expression-2 ç
³ AND ã
ïï
³ ïïï ³
³
³ condition-name-2
³
³
À

å
³
³
â
³
³
ç
å
³
³
â
³
³
ç

¿
³
³
³
³ ...
³
³
³
Ù

ä imperative-statement-2 å
ã
â
æ NEXT SENTENCE
ç
ïïïï ïïïïïïïï
[ END-SEARCH ]
ïïïïïïïïïï

Explanation
Refer to Format 1 for descriptions of the syntax elements AT END imperative-statement1, imperative-statement-2, NEXT SENTENCE, and END-SEARCH.
SEARCH ALL

These words indicate that you are searching an entire ordered table. The OCCURS
clause, which defines the table, must specify the ASCENDING or DESCENDING phrase.
identifier-1

This user-defined data item can be neither subscripted nor reference-modified. However,
its description must contain an OCCURS clause that includes an INDEXED BY phrase.
Identifier-1 must also contain the KEY IS phrase in its OCCURS clause. Refer to
“OCCURS Clause” in Section 4 for more information.
WHEN
AND

These phrases provide the structure for searches that include matches of data-names or
condition-names with identifiers, literals, and arithmetic expressions. This format permits
only one WHEN phrase. Refer to “Arithmetic Expressions” and “Conditional
Expressions” in Section 5 for more information.

8–8

8600 1518–307

SEARCH Statement

data-name-1
data-name-2

The data-name associated with a condition-name must appear in the KEY IS phrase in the
OCCURS clause referred to by identifier-1.
These elements can be qualified.
These must be subscripted by the first index-name associated with identifier-1 along with
other subscripts, as required. They must be referred to in the KEY IS phrase in the
OCCURS clause referred to by identifier-1.
IS EQUAL TO
IS =

These phrases are interchangeable. They test for the equality of a data-name or a
condition-name and an identifier, a literal, or an arithmetic expression.
condition-name-1
condition-name-2

Each condition-name must have only a single value.
identifier-3
identifier-4

These identifiers, or the identifiers specified in arithmetic-expression-1 or arithmeticexpression-2, must not be

•

Referred to in the KEY IS phrase in the OCCURS clause referred to by identifier-1

•

Subscripted by the first index-name associated with identifier-1

literal-1
literal-2

These literals can have numeric or nonnumeric values.
arithmetic-expression-1
arithmetic-expression-2

Identifiers and literals that appear in arithmetic expressions must represent either
numeric elementary items or numeric literals on which arithmetic operations can be
performed. Refer to “Arithmetic Expressions” in Section 5 for more information.

8600 1518–307

8–9

SEARCH Statement

Details
When you refer to either

•

A data-name in the KEY IS phrase in the OCCURS clause that is referred to by
identifier-1, or

•

A condition-name that is associated with a data-name in the KEY IS phrase in the
OCCURS clause referred to by identifier-1

you must refer to all preceding data-names in the KEY IS phrase of the OCCURS clause
that are referred to by identifier-1 or their associated condition-names.
How A Binary Search Is Performed
In a binary search, the table elements must be in either ascending or descending order.
When you specify the ASCENDING phrase, table elements are searched from the lowest
to the highest value. When you specify the DESCENDING phrase, table elements are
searched from the highest to the lowest value. The search occurs as follows:
1. The object program compares the item being searched for to the item in the middle
of the table.
a.

If a match occurs, the search is completed.

b. If a match does not occur, the object program determines whether the item
being searched for is in the first or second half of the table. If the item being
searched for is in the first half of the table, only that portion of the table is
searched.
2. Next, the object program finds the item in the middle of the first half of the table.
a.

If a match occurs, the search is completed.

b. If a match does not occur, the object program determines whether the item
being searched for is in the first or second portion of this half of the table. If the
item being searched for is in the first portion of this half of the table, only that
part of the table is searched.
3. The object program continues to narrow down the items in the table that it compares
to the item being searched for until one of the following occurs:
a.

A match occurs.

b. The entire table has been searched and a match does not occur.

8–10

8600 1518–307

SEARCH Statement

Operation of the SEARCH ALL Statement
In a Format 2 SEARCH statement, the results of the SEARCH ALL operation are
predictable only when both of the following conditions are met:

•

The data in the table are ordered as described in the KEY IS phrase of the OCCURS
clause referred to by identifier-1.

•

The contents of the key or keys referred to by the WHEN phrase are sufficient to
identify a unique table element.

SEARCH ALL begins a binary search. In a binary search, the initial setting of the indexname for identifier-1 is ignored and its setting is varied during the search operation. This
setting is restricted so that it never contains either of the following values:

•

A value that exceeds the value that corresponds to the last element of the table

•

A value that is less than the value that corresponds to the first element of the table

The length of the table is discussed under “OCCURS Clause” in Section 4.
In a binary search, the index-name used for the search is the first (or only) index-name
specified in the INDEXED BY phrase of the OCCURS clause that is associated with
identifier-1. Any other index-names for identifier-1 remain unchanged.

Example
05 TBL OCCURS 20 TIMES ASCENDING KEY IS KEY-1 INDEXED BY J.
10 KEY-1
PIC X.
10 FLD
PIC X(15).
SEARCH ALL TBL AT END PERFORM END-PARA
WHEN KEY-1(J) = "X"
DISPLAY FLD(J).
In this example, the entire table is searched regardless of which table element J points
to. SEARCH ALL automatically initiates a binary search.

8600 1518–307

8–11

SEEK Statement

SEEK Statement
The SEEK statement repositions a mass-storage file for subsequent sequential access.

SEEK file-name RECORD.
ïïïï
This format is supported in the TADS environment.

Explanation
file-name

This name must identify a mass-storage file of sequential organization. The ACTUAL KEY
clause must be specified in the FILE-CONTROL paragraph for file-name.

Details
The SEEK statement uses the value of the data item declared in the ACTUAL KEY clause
for the file as the record number at which the file is to be repositioned. The next
input/output (I/O) operation accesses the record associated with the record number used
for the SEEK statement.
If the value of ACTUAL KEY item is less than or equal to zero, the file is repositioned to
the first record of the file.
The ACTUAL KEY clause cannot reference a long numeric data item.
Execution of a SEEK statement does not cause the contents of the STATUS KEY data
item to be updated, and cannot cause a USE routine to be executed.

8–12

8600 1518–307

SEND Statement

SEND Statement
The SEND statement enables a program to send data to another program in the same
multiprogramming mix or to a storage queue.

Format

Use

Format 1

This format is used to send data in a synchronous way to a program that
is active in the same multiprogramming mix. Format 1 uses the CRCR
(core-to-core) capabilities of the MCP.

Format 2

This format is used to send data in an asynchronous way to a storage
queue. The sending program need not be present in the mix at the same
time as the receiving program executes the RECEIVE statement. Format
2 uses the STOQUE (STOQ) capability of the MCP.

Format 1: Send Data Synchronously (CRCR)
SEND
ïïïï

ä identifier-1 å
ã
â
æ literal-1
ç

FROM identifier-2
ïïïï

[ ON EXCEPTION imperative-statement]
ïïïïïïïïï
[ NOT ON EXCEPTION imperative-statement]
ïïï
ïïïïïïïïï
[ END-SEND ].
ïïïïïïïï

Explanation
identifier-1
literal-1

This is a nonnumeric data item that specifies the name of the receiving program. The
value must be a file title that contains from 1 to 256 characters. It is not necessary to
terminate the file title with a period (.).
If no usercode is specified, the usercode of the sending program is used. If the ON
clause is used in the file title, it is ignored by the system in the
comparison.
The receiving program must be present in the multiprogramming mix.

8600 1518–307

8–13

SEND Statement

identifier-2

This field is referred to as the sending field. This identifier must reference either an
alphanumeric data item or a long numeric data item contained in the sending program.
The size of identifier-2 is limited only by the amount of memory required by the sending
and receiving programs. If the size of the sending and receiving fields is not equal, the
smaller size is used. The data is truncated if necessary.
ON EXCEPTION imperative-statement

This clause provides an alternate statement to be performed if the receiving program is
not ready when the SEND statement is executed (an exception condition.) If this clause
is not used and the receiving program is not ready, the sending program is suspended
until the receiving program is ready.
NOT ON EXCEPTION imperative-statement

This clause provides a statement to be performed after the data transfer has successfully
occurred.

Details
This format of the SEND statement uses the CRCR (core-to-core) capabilities of the
MCP. CRCR is a synchronous communication method that enables a program to send
data to or receive data from another program that is present in the same
multiprogramming mix.
When a program issues a SEND statement, the receiving program must issue a RECEIVE
statement before the data transfer can occur. If the program designated to receive the
data does not execute a RECEIVE statement, the sending program is suspended until the
RECEIVE statement is executed.
To prevent the sending program from being suspended if the receiving program is not
ready, you can specify an alternate course of action by including the ON EXCEPTION
clause. Note, however, that you must not use this clause if the RECEIVE statement in
the partner program has specified an ON EXCEPTION clause.
For more information on the CRCR functionality, refer to the Task Management
Programming Reference Manual.

8–14

8600 1518–307

SEND Statement

Format 2: Send Data Asynchronously (STOQ)
ä TOP
å
ã ïïï
â identifier-1
æ BOTTOM ç
ïïïïïï
[ ON EXCEPTION imperative-statement]
ïïïïïïïïï
[ NOT ON EXCEPTION imperative-statement]
ïïï
ïïïïïïïïï
[ END-SEND ].
ïïïïïïïï
SEND TO
ïïïï ïï

Explanation
TOP
BOTTOM

This determines whether the data is to be placed at the beginning of the queue or at the
end of the queue.
identifier-1

This identifier must refer to a 01-level data description entry that describes a STOQ
parameter block.
ON EXCEPTION imperative-statement

This clause provides an alternate statement to be performed if the specified queue is full
(an exception condition.) If this clause is not used and an exception condition exists, the
sending program is suspended until space becomes available in the queue.
NOT ON EXCEPTION imperative-statement

This clause provides a statement to be performed after the data has been successfully
added to the queue.

Details
The STOQ capability of the MCP enables programs to communicate asynchronously by
means of an external memory buffer called a storage queue. The MCP maintains a
predefined number of queues in main memory. Programs add data to the storage queue
by using the SEND statement. Any program can retrieve the data in the storage queue by
using the RECEIVE statement. Data remains in a storage queue after the sending
program terminates.
For more information about the STOQ functionality, refer to the Task Management
Programming Reference Manual.

8600 1518–307

8–15

SEND Statement

STOQ Parameter Block
To use storage queues, a program must contain a STOQ parameter block, which is a 01level data description entry that identifies and describes

•

The storage queue used for transferring data

•

The data that is to be transferred to or from the storage queue

The data description entry for a STOQ parameter block must have the following format:
01 Identifier-1.
02 Queue-name
02 Entry-name-length
02 Entry-name
02 Entry-data-length
02 Entry-data

PIC
PIC
PIC
PIC
PIC

X(6).
9(2) COMP.
X(nn).
9(4) COMP.
X(nnnn).

The elements of a STOQ parameter block are described as follows:
queue-name

This is the programmatically assigned symbolic name of the queue to which the request
pertains.
entry-name-length

This specifies the size of the optional entry-name field. A length of 0 (zero) indicates that
no subqueue name exists.
entry-name

This is the name associated with the individual queue entry (optional). This name can be
used to provide a substructure to a queue. This name also provides the means to access
data elements that are at locations other than the top or bottom of the queue.
More than one item in the queue can have the same name; the entry-name need not be
unique. Also, the name given to an item when it is stored by the SEND verb can be
longer than the name specified in entry-name for a RECEIVE request.
entry-data-length

This indicates the size of the entry data area that contains the transaction to be accessed
for a storage request. The size of the entry-data field can be from 0 to 9999 bytes,
inclusive. For a SEND statement, the value must be filled in by the application before
each SEND statement.
This field serves as the response area for a queue inquiry request made with the
ACCEPT MESSAGE COUNT statement (see Format 3 of the ACCEPT statement).

8–16

8600 1518–307

SEND Statement

entry-data

This data area contains the data to be added to the queue in a SEND operation or the
data retrieved from the queue in a RECEIVE operation. The data can include any EBCDIC
character, including embedded blanks and nonprintable values. This field is not applicable
to a queue inquiry request issued by the ACCEPT MESSAGE COUNT statement.
Action of the SEND Statement
The SEND statement Format 2 causes data to be sent from the entry-data-field in the
STOQ parameter block specified by identifier-1 to the queue named in that parameter
block. If an entry-name is also specified in the parameter block, the data is identified by
that entry-name within the queue.

•

If SEND TO TOP is specified, the item in the entry-data field is stored at the
beginning of the queue named in the queue-name field of the STOQ parameter
block.

•

If SEND TO BOTTOM is specified, the item is stored at the end of the queue named
in the queue-name field of the STOQ parameter block.

When the request is complete, execution resumes at the next statement.
If insufficient space exists in the queue for the storage request, the ON EXCEPTION
condition exists. In that case, the following rules apply:

•

If you specified the ON EXCEPTION clause, the imperative-statement is executed.

•

If you did not specify the ON EXCEPTION clause, the program is suspended until the
specified item is placed into the queue.

If a queue with the name given in the queue-name field does not already exist when the
SEND statement is executed, the queue is created.
Determining the Number of Messages in a Storage Queue
You can determine the number of entries in a storage queue by using the ACCEPT
MESSAGE COUNT statement. This statement returns a count of the number of entries
in a queue as an unsigned integer in the entry-data-length field of the STOQ parameter
block. You can optionally specify an entry-name to determine the number of entries for
that name or name group. For more information, refer to Format 3 of the ACCEPT
statement.

8600 1518–307

8–17

SET Statement

SET Statement
The SET statement can be used to establish reference points for table-handling
operations, change the status of external switches, change the value of conditional
variables, or modify a file attribute.

Format

Use

Formats 1, 2

These formats establish reference points for table-handling
operations.

Format 3

This format changes the status of external switches.

Format 4

This format changes the value of conditional variables.

Format 5

This format sets or modifies a file attribute.

Rules for Formats 1 and 2
All references to index-name-1, identifier-1, and index-name-3 apply to all index-names
and identifiers that precede the ellipsis marks.
Index-names are connected with a given table by being specified in the INDEXED BY
phrase of the OCCURS clause for that table. See “OCCURS Clause” in Section 4 for
details.
Formats 1 and 2 establish reference points for table-handling operations by setting
indexes that are associated with table elements.

Format 1: SET . . . TO

SET
ïïï

ä index-name-1 å
ã
â
æ identifier-1 ç

. . .

TO
ïï

ä index-name-2 å
ã identifier-2 â
æ integer-1
ç

Explanation
index-name-1
identifier-1

These elements identify the index-name or data item referred to by identifier-1 that you
want to set.

8–18

8600 1518–307

SET Statement

TO
index-name-2
identifier-2
integer-1

These elements represent the value you want to assign to index-name-1 or the data item
referred to by identifier-1.

Details
Index-names are user-defined words that name indexes associated with a specific table.
Identifiers must refer to an index data item or an elementary item that is described as an
integer.
Integer-1 can be signed; however, it must be positive.
If you specify index-name-1, the value of the index after the execution of the SET
statement must correspond to an occurrence number of an element in a table associated
with index-name-1. The index value that is associated with an index-name can be set to
an occurrence number that lies outside the range of its associated table, after the
execution of a PERFORM or a SEARCH statement. The PERFORM and SEARCH
statements are described earlier in this section.
If you specify index-name-2, the value of the index before the execution of the SET
statement must correspond to an occurrence number of a table element that is
associated with index-name-1.
Action of Set Statement, Format 1
In Format 1 operations, the following actions occur:

•

Index-name-1 is set to a value that refers it to the table element that corresponds, in
occurrence number, to the table element referred to by index-name-2, identifier-2, or
integer-1. If identifier-2 refers to an index data item, or if index-name-2 is related to
the same table as index-name-1, conversion does not occur.

•

If identifier-1 refers to an index data item, it can be set equal to either the content of
index-name-2, or identifier-2, where identifier-2 also refers to an index data item. In
either case, conversion does not occur.

•

If identifier-1 does not refer to an index data item, it can be set only to an occurrence
number that corresponds to the value of index-name-2. In this case, neither identifier2 nor integer-1 can be used.

•

The value-setting process is repeated for each recurrence of index-name-1 or
identifier-1, if specified. For each repetition, the value of index-name-2 or the data
item referred to by identifier-2 is used as it was at the beginning of the execution of
the statement. Any subscripting that is associated with identifier-1 is evaluated
immediately before the value of the respective data item is changed. Refer to ‘‘Table
Handling’’ in Section 5 for a description of subscripting.

8600 1518–307

8–19

SET Statement

Table 8–1 shows the valid operand combinations in Format 1 of the SET statement.
Table 8–1. Valid Operand Combinations for the SET . . . TO
Statement

Receiving Item

Sending Item
Integer Literal
Integer Data
Item
Index-Name
Index Data Item

Integer Data
Item

Index-Name

Index Data Item

Yes

Examples
02 II USAGE IS INDEX.
02 IDM PIC 999.
02 TBL PIC 99 OCCURS 10 TIMES
INDEXED BY J.
SET J TO II.
In this example, the index (J) is set to the value of the index data item referred to by II.
SET J TO IDM.
In this example, the index (J) is set to the value of the identifier referred to by IDM.
SET J TO 3.
In this example, the index (J) is set to the value of an integer.
SET IDM TO J.
In this example, the identifier referred to by IDM is set to the value of the index (J).

8–20

8600 1518–307

SET Statement

Format 2: SET . . . UP BY (DOWN BY)
SET
ïïï

{ index-name-3 } . . .

ä UP BY
å
ã ïï ïï
â
æ DOWN BY ç
ïïïï ïï

ä identifier-3 å
ã
â
æ integer-2
ç

Explanation
index-name-3

This user-defined word names an index associated with a specific table.
UP BY
DOWN BY

These elements indicate an increase (UP BY) or decrease (DOWN BY) in a value.
identifier-3

This element must refer to an elementary numeric integer.
integer-2

This element can be signed.

Details
In Format 2, the value of the index both before and after the execution of the SET
statement must correspond to an occurrence number of an element in the table that is
associated with index-name-3.
The content of index-name-3 is increased (UP BY) or decreased (DOWN BY) by the value
of integer-2, or the value of the data item referenced by identifier-3. This process is
repeated for each recurrence of index-name-3. For each repetition, the value of the data
item referenced by identifier-3 is used as it was at the beginning of the execution of the
statement.

Examples
SET M UP BY C.
In this example, the data item referred to by identifier-3 (C) has a value of 4 and M points
to the second element of the table. The content of index-name-3 (M) is increased by 4
when the SET statement is executed. After the execution of the SET statement, M
points to the sixth element of the table.
SET M DOWN BY 1.
After the execution of the SET statement, M points to the fifth element of the table.

8600 1518–307

8–21

SET Statement

Format 3: SET an External Switch

SET
ïïï

ä
ã { mnemonic-name-1 } . . .
æ

TO
ïï

ä ON å
ã ïï â
æ OFF ç
ïïï

å
â . . .
ç

Explanation
mnemonic-name-1

This user-defined word must be associated with an external switch-name, the status of
which can be changed. The external switches that can be referred to by the SET
statement are described in Section 3 under “SWITCH-NAME Clause.”
ON
OFF

These words represent the status of an external switch.

Details
The status of each external switch that is associated with the specified mnemonic-name1 is modified so that an evaluation of an associated condition-name results in one of the
following conditions:

•

An on status, if the ON phrase is specified

•

An off status, if the OFF phrase is specified

Section 3 contains a description of the switch-name clause.

Example
SET SW2 TO ON.
In this example, the status of the external switch (SW2) that is associated with
mnemonic-name-1 is set to ON.

8–22

8600 1518–307

SET Statement

Format 4: SET a Condition TO TRUE
SET
ïïï

{ condition-name-1 } . . .

TO TRUE
ïï ïïïï

Explanation
condition-name-1

This element is a user-defined word. Within a complete set of values, it is a name you
assign to a specific value, or range of values, that a data item can assume. The data item
itself is called a conditional variable.
In the SET statement, a condition-name indicates that the associated value will be moved
to the conditional variable. Therefore, condition-name-1 must be associated with a
conditional variable.
TRUE

This word indicates that a value is moved into the conditional variable.

Details
In the VALUE clause, the literal that is associated with condition-name-1 is inserted in the
conditional variable, according to the rules for the VALUE clause. If more than one literal
is specified in the VALUE clause, the conditional variable is set to the value of the first
literal that appears in the clause. If you specify multiple condition-names, the results are
the same as if a separate SET statement had been written for each condition-name-1.
SET statement operations are executed in the order in which they are specified in the
SET statement.

Example
In this example, the value assigned to FEB (02) is moved to MONTH.
DATA DIVISION.
03 MONTH PIC 99.
88 JAN VALUE 01.
88 FEB VALUE 02.
.
.
.
PROCEDURE DIVISION.
.
.
.
SET FEB TO TRUE.

8600 1518–307

8–23

SET Statement

Format 5: SET or Modify a File Attribute
SET file-name ( [ subscript-2 , ] file-attribute-name )
ïïï
ä identifier-6
å
³ literal-2
³
³ arithmetic-expression
³
ã Ú
¿
â
³ ³ ä VALUE å ³
³
³ ³ ã ïïïïï â ³ mnemonic-attribute-value ³
³ ³ æ VA
ç ³
³
æ À
ïï
Ù
ç

Explanation
file-name

This name identifies the file whose attribute is to be set or modified.
subscript-2

This name identifies the subfile of the file and is valid only for port files. The subscript can
be an arithmetic-expression with the value of the expression identifying the subport.
file-attribute-name

This identifies the file attribute to be set or modified.
identifier-6
literal-2
arithmetic-expression
VALUE or VA

This portion of the SET statement determines the value of the file attribute after the file
attribute is set or modified. For more information about file attributes in COBOL85, refer
to Section 10. For information about specific file attributes and their values, refer to the
File Attribute Programming Reference Manual.

8–24

8600 1518–307

SET Statement

Details
Mnemonic-attribute names can be used as data-names or procedure names provided
they are not reserved words in COBOL85.
If a data-name has the same name as a mnemonic-attribute name, the value assigned to
the attribute is determined by the use of the optional word VALUE. If the word VALUE is
present, the attribute is set to the value of the mnemonic. if the word VALUE is omitted,
the attribute is set to the current value of the data-name. Refer to “VALUE Clause” in
Section 4 for more information.
Format 5 of the SET statement is an obsolete element of COBOL85. The CHANGE
statement is the preferred syntax.

8600 1518–307

8–25

SORT Statement

SORT Statement
The SORT statement

•

Creates a sort file by executing an input procedure or by transferring records from
another file.

•

Sorts records in the sort file on a set of specified keys.

•

Makes available each record from the sort file, in sorted order, to an output
procedure or to an output file.

The SORT statement can appear anywhere in the Procedure Division except in the
declarative portion. The syntax for the SORT statement is displayed on the following two
pages.

SORT
ïïïï

Ú
¿
³ ä TAG-KEY
å ³
³ ã ïïïïïïï
â ³ file-name-1
³ æ TAG-SEARCH ç ³
À
ïïïïïïïïïï
Ù

ä
ã ON
æ

ä ASCENDING
ã ïïïïïïïïï
æ DESCENDING
ïïïïïïïïïï
[ WITH DUPLICATES IN
Ú
³
³
³
³ COLLATING SEQUENCE
³
ïïïïïïïï
³
³
À
Ú
³
³
³
³
³
À
Ú
³
³
³
À

8–26

å
â
ç

Ú
³
³
³
³
³
À

KEY data-name-1

ä
³
ã
³
æ

PURGE
ïïïïï
RUN
ïïï
END
ïïï

å
³
â
³
ç

¿
³
³
ON ERROR ³
ïïïïï ³
³
Ù

[ ,data-name-2 ] . . .

å
â
ç

. . .

ORDER ]
ä
³
³
ã
³
³
æ

ä
³
ã
³
æ

WORDS
ïïïïï
MEMORY SIZE IS arithmetic-expression-1
CHARACTERS
ïïïïïï
ïïïïïïïïïï
MODULES
ïïïïïïï
¿
ä WORDS
å ³
DISK SIZE IS arithmetic-expression-2
ã ïïïïï
â ³
ïïïï
æ MODULES ç ³
ïïïïïïï
Ù

å
³
â
³
ç

å
³
³
â
³
³
ç

¿
³
³
³
³
³
³
³
Ù

¿
³
³
³
³
³
Ù

8600 1518–307

SORT Statement

[ RE-START IS integer-3 ]
ïïïïïïïï
ä
³
³ INPUT PROCEDURE IS procedure-name-1
³ ïïïïï ïïïïïïïïï
³
Ú
¿
ã
ä
³ LOCK
³ å
³
³
³ ïïïï
³ ³
³ USING ã file-name-2 ³ PURGE
³ â
³ ïïïïï ³
³ ïïïïï
³ ³
³
æ
³ RELEASE ³ ç
æ
À ïïïïïïï Ù

Ú
³
³
³
À

Ú
ä
³
³ OUTPUT PROCEDURE IS procedure-name-3 ³
³ ïïïïïï ïïïïïïïïï
³
³
Ú
À
³
ä
³ LOCK
³
³
³ ïïïï
³
³
³ SAVE
ã
³
³ ïïïï
³
GIVING
³
file-name-3 ³ NO REWIND
³
ïïïïïï
ã
³ ïï ïïïïïï
³
³
³ CRUNCH
³
³
³ ïïïïïï
³
³
³ RELEASE
æ
³
³ ïïïïïïï
À

8600 1518–307

ä THROUGH å
ã ïïïïïïï â
æ THRU
ç
ïïïï

¿
³
procedure-name-2 ³
³
Ù

å
³
³
³
³
â
³
³
³
³
ç

¿
³
procedure-name-4 ³
³
Ù

å
³
³
³
³
³
³
â
³
³
³
³
³
³
ç

. . .

ä
ã
æ
¿
³
³
³
³
³
³
³
³
³
³
Ù

THROUGH å
ïïïïïïï â
THRU
ç
ïïïï
å
³
³
³
³ . . .
â
³
³
³
ç

8–27

SORT Statement

Explanation
TAG-KEY

This optional phrase specifies that sorting is performed on keys rather than on the entire
record. The record numbers are placed in the sorted order in the GIVING file. The GIVING
file is restricted to a record of eight DISPLAY digits.
The TAG-KEY option prohibits the use of the INPUT PROCEDURE and OUTPUT
PROCEDURE clauses.
TAG-SEARCH

This optional phrase specifies that sorting is performed on keys rather than on the entire
record. The records are placed in the GIVING file according to the sorted order of the
record numbers.
The TAG-SEARCH option prohibits the use of the INPUT PROCEDURE and OUTPUT
PROCEDURE clauses.
The TAG-SEARCH option is not supported for tape input files or for multiple-file input.
file-name-1

This refers to the sort file, which is an internal file.
This element is a user-defined word. It must be described in a sort-merge file description
entry in the Data Division.
ON ERROR

The ON ERROR options enable you to have control over irrecoverable parity errors when
input/output procedures are not present in a program.
PURGE causes all records in a block that contains an irrecoverable parity error to be
dropped; processing is continued after a message is displayed on the ODT, giving the
relative position in the file of the bad block.
RUN causes the bad block to be used by the program and provides the same message
as defined for PURGE.
END causes a program termination; this is the default.
ASCENDING

When you specify the ASCENDING phrase, records contained in file-name-1 are sorted
from the lowest value of data items identified by the key data-names to the highest
value, according to the rules for comparison of operands in a relation condition. Refer to
“Relation Conditions” in Section 5 for more information.

8–28

8600 1518–307

SORT Statement

DESCENDING

When you specify the DESCENDING phrase, records contained in file-name-1 are sorted
from the highest value of data items identified by the key data-names to the lowest
value, according to the rules for comparison of operands in a relation condition.
KEY

Keys enable you to specify the order in which you want to sort a set of records.
The data-names following the word KEY are listed from left to right in order of decreasing
significance without regard to how they are divided into KEY phrases. The leftmost dataname is the major key, the next data-name is the next most significant key, and so forth.
data-name-1
data-name-2 . . .

These user-defined words are key data-names. A key data-name is the name of a data
item that is used as a sort key. Refer to “Rules for Key Data-Names” under the “Details”
portion of this statement.
WITH DUPLICATES IN ORDER

This phrase determines the order in which duplicate records are returned after a SORT
statement has been executed.
COLLATING SEQUENCE IS

This phrase enables you to specify alternate collating sequences. Alphabet-name-1 and
alphabet-name-2 are user-defined words in the SPECIAL-NAMES paragraph of the
Environment Division that assign a name to a specific character set and collating
sequence.
MEMORY SIZE IS arithmetic-expression-1

This phrase is a guideline for allocating SORT memory area and overrides the same
clause in the OBJECT-COMPUTER paragraph. You can allocate MEMORY SIZE as
WORDS, CHARACTERS, or MODULES. If you do not specify MEMORY SIZE in the
SORT statement or in the OBJECT-COMPUTER paragraph, the compiler assumes a
default value of 12,000 words.
If the number of records to be sorted varies from run to run, you can allocate MEMORY
SIZE by specifying arithmetic-expression-1. An arithmetic expression contains
combinations of identifiers and literals, which are separated by arithmetic operators and
parentheses. For details about arithmetic expressions, refer to Section 5.

8600 1518–307

8–29

SORT Statement

DISK SIZE

This phrase is a guideline for allocating SORT disk area, and overrides the same clause in
the OBJECT-COMPUTER paragraph. You can allocate DISK SIZE as WORDS or
MODULES. If you do not specify DISK SIZE in the SORT statement or OBJECTCOMPUTER paragraph, the compiler assumes a default value of 900,000 words. One
module of disk is the same as 1.8 million words of disk.
If the number of records to be sorted varies from run to run, you can allocate DISK SIZE
by specifying arithmetic-expression-2. An arithmetic expression contains combinations of
identifiers and literals, which are separated by arithmetic operators and parentheses. For
details about arithmetic expressions refer to Section 5.
RE-START IS integer-3

No restart capability.

Restart previous sort. The prior uncompleted sort must have been
capable of a restart.

Allow restartable sort.

4 or 6

Allow a restartable sort, and enable extensive error recovery from I/O
errors.

Restart previous sort if all input has been received. The prior
uncompleted sort must have been capable of a restart.

Allow restartable sort after all input is received.

12 or 14

Options 4 and 10.

Refer to the MERGE section in the System Software Utilities Operations Reference
Manual for more details on the RE-START capability of MERGE.
INPUT PROCEDURE IS

If you use a RELEASE statement to make records available to the file referred to by filename-1, you can use an input procedure to select, modify, or copy those records.

8–30

8600 1518–307

SORT Statement

procedure-name-1
procedure-name-2

These elements represent the beginning and ending of the range of an input procedure.
USING file-name-2

This phrase enables you to direct the SORT statement to open the file referred to by filename-2 and to act upon it in the same manner as an input procedure. File-name-2 refers
to a file that contains the records to be sorted.
You can specify up to eight file-names in the USING phrase.
If you specify an input procedure, do not specify the USING phrase.
OUTPUT PROCEDURE IS

If you use a RETURN statement to make sorted records available to the file referred to
by file-name-1, you can use an output procedure to select, modify, or copy those records.
procedure-name-3
procedure-name-4

These elements represent the beginning and ending of the range of an output procedure.
GIVING file-name-3

File-name-3 refers to the output file. The GIVING phrase enables you to direct the SORT
statement to open the file referred to by file-name-3 and to act upon it in the same
manner as an output procedure.
You can specify up to eight file-names in the GIVING phrase.
If you specify an output procedure, do not specify the GIVING phrase.
THROUGH
THRU

These words are interchangeable. They connect two procedures that represent the range
of an input or an output procedure.

8600 1518–307

8–31

SORT Statement

LOCK
PURGE
RELEASE
SAVE
NO REWIND
CRUNCH

These options enable you to specify the type of close procedure to use on a file.
You can specify the LOCK, PURGE, and RELEASE options for file-name-2 (the USING
phrase).
You can specify SAVE, LOCK, NO REWIND, CRUNCH, and RELEASE options for filename-3 (the GIVING phrase).
For a description of these options, refer to “CLOSE Statement” in Section 6.

Details
A pair of file-names in the same SORT statement cannot be specified in the same SAME
SORT AREA clause or the same SAME SORT-MERGE AREA clause. File-names
associated with the GIVING phrase cannot be specified in the same SAME clause. Refer
to “SAME Clause” under “I-O CONTROL Paragraph” in Section 3 and “Sort and Merge
Constructs” in Section 5 for more information.
If you specify the DUPLICATES phrase and all key data items associated with one data
record equal the corresponding key data items associated with one or more other data
records, then the order of return of these records is one of the following:

•

If there is no input procedure, records are returned in the order of the associated
input files, as specified in the SORT statement. Within a given input file, records are
returned in the order they are accessed.

•

If there is an input procedure, records are returned in the order in which these
records are released by the input procedure.

If you do not specify the DUPLICATES phrase and all key data items associated with one
data record equal the corresponding key data items associated with one or more other
data records, then the order of return of these records is undefined.

8–32

8600 1518–307

SORT Statement

Action of the SORT Statement
The execution of the SORT statement consists of the following three phases:
1. Records are made available to the file referred to by file-name-1. The records are
available because of the execution of RELEASE statements in the input procedure, or
the implicit execution of READ statements for file-name-2. When this phase begins,
the file referred to by file-name-2 must not be in the open mode. When this phase
ends, the file referred to by file-name-2 is not in the open mode.
2. Records in the file referred to by file-name-1 are put in the order specified by the
ASCENDING or DESCENDING options. The files referred to by file-name-2 and filename-3 are not processed during this phase.
3. Records in the file referred to by file-name-1 are made available in sorted order. The
sorted records are written to the file referred to by file-name-3, or are made available
for processing by an output procedure with the execution of a RETURN statement.
When this phase begins, the file referred to by file-name-3 must not be in the open
mode. When this phase ends, the file referred to by file-name-3 is not in the open
mode.
Rules for Key Data-Names
Key data-names can be qualified. In addition, the data items referenced by key datanames

•

Must be described in a record description entry associated with file-name-1.

•

Must be described in only one record description, if file-name-1 has multiple record
descriptions. The same character positions referred to as a key data-name in one
record description entry are taken as the key for all records in that file.

•

Cannot be long numeric data items.

•

Cannot be group items that contain variable-occurrence data items.

•

Cannot be described by an entry that either contains an OCCURS clause or is
subordinate to an entry that contains an OCCURS clause.

8600 1518–307

8–33

SORT Statement

Collating Sequence
Alphabet-name-1 references an alphabet that defines an alphanumeric collating
sequence.
Alphabet-name-2 references an alphabet that defines a national collating sequence.
The alphanumeric collating sequence that applies to the comparison of key data items for
class alphabetic and class alphanumeric, and the national collating sequence that applies
to the comparison of key data items of class national, are each determined separately at
the beginning of the execution of the SORT statement in the following order or
precedence:
1. Collating sequence established by the COLLATING SEQUENCE phrase, if specified,
in this SORT statement
The collating sequence associated with alphabet-name-1 applies to key data items of
class alphabetic and alphanumeric; the collating sequence associated with alphabetname-2 applies to key data items of class national.
2. Collating sequences established as the alphanumeric and national collating
sequences
Input Procedure
The input procedure can consist of any procedure needed to select, modify, or copy the
records that are made available (one at a time) by the RELEASE statement to the file
referred to by file-name-1. The range of statements in the input procedure includes all
statements that are executed because of a transfer of control by CALL, EXIT, GO TO,
and PERFORM statements. The range also includes all statements in declarative
procedures that are executed as a result of the execution of statements in the range of
the input procedure. However, the range of the input procedure must not cause the
execution of a MERGE, RETURN, or SORT statement.
If you specify an input procedure, control passes to the input procedure that precedes
the file referred to by file-name-1, which puts the records in order (ascending or
descending). The compiler inserts a return mechanism at the end of the last statement in
the input procedure. When control passes to that last statement, the records that have
been released to the file referred to by file-name-1 are sorted.
USING Phrase
If you specify the USING phrase, the size of the records contained in the file referred to
by file-name-2 must not be larger than the largest record described for the file referred to
by file-name-1.
File-name-2 and file-name-3 must be described in a file description entry (not in a sortmerge file description entry) in the Data Division. The files referred to by file-name-2 and
file-name-3 can reside on the same multiple-file reel.

8–34

8600 1518–307

SORT Statement

If you specify the USING phrase, all records in the file(s) referred to by file-name-2 are
transferred to the file referred to by file-name-1. For each of the files referred to by filename-2, the following actions occur when the SORT statement is executed:
1. File processing is initiated. The initiation is performed as if an OPEN statement with
the INPUT phrase had been executed.
2. The logical records are obtained and released to the sort operation. Each record is
obtained as if a READ statement with the NEXT and the AT END phrases had been
executed.
For a relative file, the content of the relative key data item is undefined after the
SORT statement is executed if file-name-2 is not referred to by the GIVING phrase.
3. File processing is terminated. The termination is performed as if a CLOSE statement
without optional phrases had been executed. The termination occurs before the file
referred to by file-name-1 is put in either ascending or descending order.
These implicit functions are performed in a way that executes any associated USE
AFTER EXCEPTION/ERROR procedures. However, the execution of such procedures
must not cause the execution of any statement that manipulates the file referred to by,
or that accesses the record area associated with, file-name-2.
Output Procedure
The output procedure can consist of any procedure needed to select, modify, or copy the
records that are made available one at a time by the RETURN statement in sorted order
from the file referred to by file-name-1. The range of statements in the output procedure
includes all statements that are executed because of a transfer of control by CALL, EXIT,
GO TO, and PERFORM statements. The range also includes all statements in declarative
procedures that are executed as a result of the execution of statements in the range of
the output procedure. The range of the output procedure must not cause the execution
of a MERGE, RELEASE, or SORT statement.
If you specify an output procedure, control passes to the output procedure after the file
referred to by file-name-1 puts the records in either ascending or descending order. The
compiler inserts a return mechanism at the end of the last statement in the output
procedure. When control passes to that last statement, the return mechanism
terminates the sort operation and passes control to the next executable statement.
Before entering the output procedure, the sort procedure reaches a point at which it can
select the next record, in sorted order, when requested. The RETURN statements in the
output procedure are the requests for the next record.
GIVING Phrase
If you specify the GIVING phrase, the size of the records contained in the file referred to
by file-name-1 must not be larger than the largest record described for the file referred to
by file-name-3.
If file-name-3 refers to an indexed file, the first specification of data-name-1 must be
associated with an ASCENDING phrase. Also, the data item referred to by that dataname-1 must occupy the same character positions in its record as the data item that is
associated with the prime record key for that file.

8600 1518–307

8–35

SORT Statement

If you specify the GIVING phrase, all the sorted records are written in the file referred to
by file-name-3 as the implied output procedure for the SORT statement. For each of the
files referred to by file-name-3, the execution of the SORT statement causes the
following actions:
1. File processing is initiated. The initiation is performed as if an OPEN statement with
the OUTPUT phrase had been executed. Initiation occurs after the execution of any
input procedure.
2. The sorted logical records are returned and written to the file. Records are written as
if a WRITE statement without optional phrases had been executed.
For a relative file, the relative key data item for the first record returned contains the
value one (1); for the second record returned, the value two (2); and so forth. After
the SORT statement is executed, the content of the relative key data item indicates
the last record returned to the file.
3. File processing is terminated. The termination is performed as if a CLOSE statement
without optional phrases had been executed.
These implicit functions are performed in a way that executes any associated USE
AFTER EXCEPTION/ERROR procedures. However, the execution of such a USE
procedure must not cause the execution of any statement that manipulates the file
referred to by, or that accesses the record area associated with, file-name-3. On the first
attempt to write beyond the externally defined boundaries of the file, any USE AFTER
STANDARD EXCEPTION/ERROR procedure specified for the file is executed. If control is
returned from that USE procedure or if such a USE procedure is not specified, the
processing of the file is terminated as stated in step 3.
Space Fill of Records
Any record in the file referred to by file-name-2 that contains fewer character positions
than the record length of the file referred to by file-name-1 is space filled from the right.
Space fill begins with the first character position after the last character in the record,
when that record is released to the file referred to by file-name-1.
Any record in the file referred to by file-name-3 that contains fewer character positions
than the record length of the file referred to by file-name-1 is space filled from the right.
Space fill begins with the first character position after the last character in the record,
when that record is returned to the file referred to by file-name-3.

8–36

8600 1518–307

SORT Statement

Examples
IDENTIFICATION DIVISION.
PROGRAM-ID. MANUAL-COBOL85-SEC08-SORT.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT FILE-1
ASSIGN TO DISK.
SELECT FILE-2
ASSIGN TO DISK.
SELECT SRT-FIL
ASSIGN TO SORT.
DATA DIVISION.
FILE SECTION.
FD FILE-1.
01 F1REC.
03 FILLER
PIC X(180).
FD FILE-2.
01 F2REC.
03 FILLER
PIC X(180).
SD SRT-FIL.
01 SREC.
03 FILLER
PIC X(10).
03 ACC-NO
PIC 9(6).
03 FILLER
PIC X(10).
03 BAL-DUE
PIC 9(20).
PROCEDURE DIVISION.
BEGIN.
SORT SRT-FIL
ON ASCENDING KEY ACC-NO
INPUT PROCEDURE IS PROC-1 THRU END-1
OUTPUT PROCEDURE IS PROC-2 THRU END-2.
PROC-1.
OPEN INPUT FILE-1.
PROC -1A.
READ FILE-1 AT END GO TO END-1.
RELEASE SREC FROM F1REC.
GO TO PROC-1A.
END-1.
CLOSE FILE-1.
PROC-2.
OPEN OUTPUT FILE-2.
PROC-2A.
RETURN SRT-FIL INTO F2REC AT END GO TO END-2.
WRITE F2REC.
GO TO PROC-2A.
END-2.
CLOSE FILE-2.
STOP RUN.
In the example above, the input procedure occurs first. This procedure opens and reads
FILE-1. Then, the procedure releases the record from F1REC to SORT. After the file is
sorted, the output procedure begins. The output procedure opens FILE-2. Then, the sort
record is returned to F2REC, and the record is written to the disk file.

8600 1518–307

8–37

SORT Statement

IDENTIFICATION DIVISION.
PROGRAM-ID. MANUAL-COBOL85-SEC08-SORT.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE CONTROL.
SELECT FILE-1
ASSIGN TO DISK.
SELECT FILE-2
ASSIGN TO DISK.
SELECT SRT-FIL
ASSIGN TO SORT.
DATA DIVISION.
FILE SECTION.
FD FILE-1.
01 F1REC.
03 FILLER
PIC X(180).
FD FILE-2.
01 F2REC.
03 FILLER
PIC X(180).
SD SRT-FIL.
01 SREC.
03 FILLER
PIC X(10).
03 ACC-NO
PIC 9(6).
03 FILLER
PIC X(10).
03 BAL-DUE
PIC 9(20).
PROCEDURE DIVISION
BEGIN.
SORT SRT-FIL
ON ASCENDING KEY BAL-DUE
WITH DUPLICATES IN ORDER
USING FILE-1
GIVING FILE-2.
In this second example, the USING phrase and the GIVING phrase direct the SORT
statement to open, read, and close the files in the same way that the input procedure
and the output procedure opened, read, and closed the files in the previous example.
Because the DUPLICATES phrase is specified, duplicate records are returned in the order
of the associated input files, as specified in the SORT statement. Within a given input
file, the records are arranged in the order in which they are accessed from that file.

8–38

8600 1518–307

START Statement

START Statement
The START statement provides a basis for logical positioning in relative or indexed files
for the subsequent sequential retrieval of records.
This statement is partially supported in the TADS environment. Applicable exclusions are
noted in this section.

START file-name-1
ïïïïï

Ú
³
³
³
³
³
³
³
³ KEY
³ ïïï
³
³
³
³
³
³
À

ä
³
³
³
³
³
³
ã
³
³
³
³
³
³
æ

IS EQUAL TO
ïïïïï
IS =
IS GREATER THAN
ïïïïïïï
IS >
IS NOT LESS THAN
ïïï ïïïï
IS NOT <
ïïï
IS GREATER THAN OR EQUAL TO
ïïïïïïï
ïï ïïïïï
IS > =

å
³
³
³
³
³
³
â
³
³
³
³
³
³
ç

¿
³
³
³
³
³
³
³
data-name-1 ³
³
³
³
³
³
³
³
Ù

[ INVALID KEY imperative-statement-1 ]
ïïïïïïï
[ NOT INVALID KEY imperative-statement-2 ]
ïïï ïïïïïïï
[ END-START ]
ïïïïïïïïï
This format is supported in the TADS environment.

Explanation
file-name-1

This user-defined word represents the name of a file for which there is sequential or
dynamic access. The file referenced by file-name-1 must be open in the input or I-O
mode when the START statement is executed.

8600 1518–307

8–39

START Statement

KEY

The KEY phrase enables you to specify where you want to retrieve records. If you do not
specify the KEY phrase, the relational operator IS EQUAL TO is implied.IS EQUAL TO
IS =
IS GREATER THAN
IS >
IS NOT LESS THAN
IS NOT <
IS GREATER THAN OR EQUAL TO
IS > =
These relational operators are used for comparisons in the KEY phrase. Notice that IS
EQUAL TO is synonymous with IS =; IS GREATER THAN is synonymous with IS >; and
so forth.
data-name-1

This user-defined word can be qualified. Data-name-1 must point to the RELATIVE KEY
clause, the ALTERNATE KEY clause, or the RECORD KEY clause.
INVALID KEY imperative-statement-1

The INVALID KEY phrase is required if you do not specify an applicable USE AFTER
STANDARD EXCEPTION procedure for file-name-1.
The INVALID KEY phrase enables you to include an imperative statement that specifies
an action to be taken when the key is invalid. A key is invalid if there is not a matching
record in the file. For example, if you specify SMITH as the key for an indexed file and
there is not a record called SMITH in the file, the key is invalid.
NOT INVALID KEY imperative-statement-2

The NOT INVALID KEY phrase enables you to include an imperative statement that
specifies an action to be taken when the key is valid.
END-START

This phrase delimits the scope of the START statement.

Details
The execution of the START statement updates the value of the I-O status associated
with file-name-1.
The execution of the START statement does not alter either of the following:

8–40

•

The content of the record area

•

The content of the data item referred to by the data-name specified in the
DEPENDING ON phrase of the RECORD clause associated with file-name-1

8600 1518–307

START Statement

TADS
Any USE procedure is not executed when a START statement that is compiled and
executed in a TADS session fails.
Invalid Key Condition
When the START statement is executed and the file position indicator indicates that an
optional input file is not present, the invalid key condition occurs and the START
statement execution is unsuccessful.
Transfer of control after the successful or unsuccessful execution of the START
operation depends on the presence or absence of the INVALID KEY and NOT INVALID
KEY phrases in the START statement.
After the unsuccessful execution of a START statement, the file position indicator is set
to indicate that a valid next record has not been established. Also, for indexed files, the
key of reference is undefined.
Rules for Relative Files
If you specify data-name-1, it must be the data item specified in the RELATIVE KEY
phrase in the ACCESS MODE clause of the associated file control entry. The comparison
specified by the relational operator in the KEY phrase occurs between a key associated
with a record in the file referred to by file-name-1 and the data item referred to by the
RELATIVE KEY phrase of the ACCESS MODE clause associated with file-name-1.
Numeric comparison rules apply. Refer to “Relation Conditions” in Section 5 for
information about comparisons of numeric operands.
In addition, the following rules apply to comparisons:

•

The file position indicator is set to the relative record number of the first logical
record in the file whose key satisfies the comparison.

•

If the comparison is not satisfied by any record in the file, the invalid key condition
occurs and the execution of the START statement is unsuccessful.

Rules for Indexed Files
If you specify the KEY phrase, data-name-1 must refer to one of the following:

•

A data item that is specified as a record key or alternate key associated with filename-1

•

Any alphanumeric or national data item whose leftmost character position within a
record in a file corresponds to the leftmost character position of a record key
associated with file-name-1, and whose length is not greater than the length of that
record key

8600 1518–307

8–41

START Statement

The comparison specified by the relational operator in the KEY phrase occurs between a
key associated with a record in the file referred to by file-name-1 and a data item
specified as follows:

•

If you specify the KEY phrase, the comparison uses the data item referred to by dataname-1.

•

If you do not specify the KEY phrase, the comparison uses the data item referred to
by the RECORD KEY clause that is associated with file-name-1.

The comparison is made on the ascending key of reference, according to the collating
sequence of the file. If the operands are of unequal size, the comparison proceeds as if
the longer operand were truncated on the right, so that it equals the length of the shorter
operand. All other numeric comparison rules apply.
In addition, the following rules apply to comparisons:

•

The file position indicator is set to the value of the key of reference in the first logical
record whose key satisfies the comparison.

•

If the comparison is not satisfied by any record in the file, the invalid key condition
exists and the execution of the START statement is unsuccessful.

A key of reference is established as follows:

•

If you do not specify the KEY phrase, the prime record key specified for file-name-1
becomes the key of reference.

•

If you do specify the KEY phrase, and you specify data-name-1 as a record key for
file-name-1, that record key becomes the key of reference.

•

If you specify the KEY phrase, and you specify a name other than the record key for
file-name-1, the record key whose leftmost character position corresponds to the
leftmost character position of the data item specified by data-name-1 becomes the
key of reference.

The key of reference establishes the sequential order of records for the START
statement. If the START statement executes successfully, the key of reference is also
used for subsequent sequential READ statements. The READ statement is discussed
earlier in this section.

8–42

8600 1518–307

START Statement

Examples
FILE-CONTROL.
SELECT EMP-FILE ASSIGN TO DISK
ORGANIZATION IS RELATIVE
ACCESS MODE IS DYNAMIC
RELATIVE KEY IS KEY-1.
DATA DIVISION.
FILE SECTION.
FD EMP-FILE.
01 EMP-NUMBER.
03 NAME
PIC X(10).
03 ACC-NO
PIC X(6).
03 BALANCE
PIC 9(6).
WORKING-STORAGE SECTION.
01 KEY-1
PIC 999.
PROCEDURE DIVISION.
BEGIN.
OPEN I-O EMP-FILE.
MOVE 10 TO KEY-1.
START EMP-FILE KEY IS NOT LESS THAN KEY-1
INVALID KEY PERFORM EDIT-KEY-TROUBLE.
READ EMP-FILE NEXT AT END PERFORM ERR-PARA.
In this first example, the relative file EMP-FILE is positioned for sequential access. Before
the START statement is executed, a number must be moved into the relative key. The
file position indicator is set to the relative record number of the first logical record whose
key is not less than KEY-1. If the comparison is not satisfied by any record in the file, the
invalid key condition occurs, and EDIT-KEY-TROUBLE is performed.
FILE-CONTROL.
SELECT MASTERFILE ASSIGN TO DISK
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS ACC-NO
ALTERNATE KEY IS NAME1
ALTERNATE KEY IS DEPT-NO WITH DUPLICATES.
DATA DIVISION.
FILE SECTION.
FD MASTERFILE.
01 REC.
03 ACC-NO
03 NAME1
03 DEPT-NO
03 BALANCE

PIC
PIC
PIC
PIC

X(6).
X(10).
X(3).
9(6)V99.

PROCEDURE DIVISION.
BEGIN.
OPEN INPUT MASTERFILE.
MOVE "HARRIS" TO NAME1.

8600 1518–307

8–43

START Statement

START MASTERFILE KEY IS EQUAL TO NAME1 INVALID KEY
GO TO EDIT-KEY-TROUBLE.
READ MASTERFILE NEXT AT END PERFORM CLOSINGS.
.
.
.
In this second example, the indexed file MASTERFILE is positioned for sequential
retrieval. Before the START statement is executed, a value must be moved into the
record key or an alternate key. The file position indicator is set to the value of the key of
reference in the first logical record whose key satisfies the comparison. If the
comparison is not satisfied by any record in the file, the invalid key condition occurs, and
control is transferred to EDIT-KEY-TROUBLE.

8–44

8600 1518–307

STOP Statement

STOP Statement
The STOP statement permanently or temporarily suspends the execution of the run unit.
The STOP literal-1 construct of the STOP statement is an obsolete element and will be
deleted from the next revision of standard COBOL.

STOP
ïïïï

ä RUN
å
ã
â
æ literal-1 . . . ç

Explanation
STOP RUN

The STOP RUN statement stops the execution of the run unit, and control passes to the
operating system. If a STOP RUN statement appears in a consecutive sequence of
imperative statements within a sentence, it must appear as the last statement in that
sequence.
STOP literal-1

The STOP literal-1 statement suspends the execution of the run unit and displays literal-1
on the operator display terminal (ODT). Literal-1 must not be a figurative constant that
begins with the word ALL. Section 1 contains a description of figurative constants.
If literal-1 is numeric, then it must be an unsigned integer.
The STOP statement can display more than one literal value.

Details
During the execution of a STOP RUN statement, an implicit CLOSE statement (without
optional phrases) is executed for each file in the run unit that is in the open mode. USE
statements that are associated with these files are not executed. CLOSE and USE
statements are discussed in this section.
If the run unit has been accessing messages, the STOP RUN statement causes the
message control system (MCS) to eliminate from the queue any message partially
received by that run unit.
After the suspension of the run unit by STOP literal-1, you must reinitiate the run unit by
typing ?OK on your terminal. Then, execution of the run unit continues with the next
executable statement.

8600 1518–307

8–45

STOP Statement

Examples
PROCEDURE DIVISION.
PARA-1.
DISPLAY "HELLO".
STOP RUN.

PROCEDURE DIVISION.
P-1.
STOP "STOP ""THIS ""FROM ""HAPPENING".
DISPLAY "CONTINUED"
STOP RUN.

In the first example, the STOP RUN statement terminates a program that displays
HELLO on the ODT. In the second example, the STOP RUN statement terminates a
program that displays STOP THIS FROM HAPPENING CONTINUED on the ODT.

8–46

8600 1518–307

STRING Statement

STRING Statement
The STRING statement puts the partial or complete contents of one or more data items
into a single data item.
ä
ä
³
³
ä identifier-2 å
³
³ DELIMITED BY ã literal-2
â
³ ä identifier-1 å
³ ïïïïïïïïï
æ SIZE
ç
STRING ã ã
â . . . ã
ïïïï
ïïïïïï ³ æ literal-1
ç
³
ä identifier-5 å
³
³ FOR ã
â
³
³ ïïï æ literal-3
ç
æ
æ

å
³
³
³
â
³
³
³
ç

å
³
³
³
â . . .
³
³
³
ç

INTO identifier-3
ïïïï
[ WITH POINTER identifier-4 ]
ïïïïïïï
[ ON OVERFLOW imperative-statement-1 ]
ïïïïïïïï
[ NOT ON OVERFLOW imperative-statement-2 ]
ïïï
ïïïïïïïï
[ END-STRING ]
ïïïïïïïïïï

Explanation
identifier-1
literal-1

These elements represent the sending field that contains the data you want to move to
the data item referred to by identifier-3 (the receiving field).
Identifier-1 represents a data item you want to move. Identifier-1 cannot reference a long
numeric data item. If it is an elementary numeric data item, it must be described as an
integer without the symbol P in its PICTURE character-string.
Literal-1 represents the actual characters to be moved. Literal-1 cannot be a long numeric
literal. If literal-1 is a figurative constant, it refers to an implicit one-character data item
whose usage is DISPLAY or NATIONAL. Literal-1 cannot be a figurative constant that
begins with the word ALL. For a description of figurative constants, see Section 1.

8600 1518–307

8–47

STRING Statement

DELIMITED BY identifier-2
literal-2
SIZE

The DELIMITED BY phrase identifies the end of the data that will be moved.
Literal-2 or the content of the data item referred to by identifier-2 indicates the characters
that delimit the move.
When literal-2 is a figurative constant it refers to an implicit one-character, data item
whose usage is DISPLAY or NATIONAL. Literal-2 cannot be a figurative constant that
begins with the word ALL. For a description of figurative constants, Section 1.
Identifier-2 is an elementary numeric data item, it must be described as an integer
without the symbol P in its PICTURE character-string.
If you specify the SIZE phrase, the complete content of the data item referred to by
identifier-1 or literal-1 is moved.
FOR identifier-5
FOR literal-3

This phrase specifies the number of characters to transfer.
INTO identifier-3

This phrase identifies the receiving data item. Identifier-3 must not represent an edited
data item. In addition, it must not be reference-modified or include a JUSTIFIED clause in
its description.
WITH POINTER identifier-4

This phrase indicates the value of the data item referred to by identifier-4. Identifier-4
must be described as an elementary numeric integer data item of sufficient size to
contain a value equal to the size of the area referred to by identifier-3 plus 1. The symbol
P cannot be used in the PICTURE character-string of identifier-4.
ON OVERFLOW imperative-statement-1

This phrase enables you to include an imperative statement that specifies an action to be
taken when an overflow condition occurs.
NOT ON OVERFLOW imperative-statement-2

This phrase enables you to include an imperative statement that specifies an action to be
taken when an overflow condition does not occur.

8–48

8600 1518–307

STRING Statement

END-STRING

This phrase delimits the scope of the STRING statement.
All literals must be described as nonnumeric or national. All identifiers, except identifier-4
and identifier-5, must be described implicitly or explicitly with a usage of DISPLAY or
NATIONAL. The category of all literals and identifiers, except identifier-4, identifier-5, and
literal-3, must be the same.

Details
When the STRING statement is executed, characters from literal-1, or from the data item
referred to by identifier-1, are transferred to the data item referred to by identifier-3. This
transfer occurs according to the rules for alphanumeric-to-alphanumeric or national-tonational moves. However, space filling does not occur. MOVE operations are discussed
in this section.
Effect of DELIMTED and FOR Phrases on Data Transfer
Each STRING statement must specify at least one DELIMITED phrase or FOR phrase. All
data transfers occur in the sequence specified in the statement. Data transfers are
repeated until all occurrences of literal-1, or data items referred to by identifier-1, are
processed.

•

If you specify the DELIMITED phrase without the SIZE phrase, the data item referred
to by identifier-1, or the value of literal-1, is transferred to the receiving data item.
This transfer begins with the leftmost character and continues from left to right until
one of the following occurs:

−

The end of the sending data item is reached.

−

The end of the receiving data item is reached.

−

The characters specified by literal-2, or by the data item referred to by identifier2, are encountered. The characters specified by literal-2 or by the data item
referred to by identifier-2 are not transferred.

•

If you specify the DELIMITED phrase with the SIZE phrase, the entire content of
literal-1, or the content of the data item referred to by identifier-1, is transferred to
the data item referred to by identifier-3. This data transfer continues until all data are
transferred, or until the end of the data item referred to by identifier-3 is reached.

•

If you specify the FOR phrase, the contents of identifier-1 are transferred to
identifier-3 beginning with the leftmost character and continuing until one of the
following occurs:

−

The end of identifier-3 is reached.

−

The number of characters specified by literal-3 or by the contents of identifier-5
have been transferred.

8600 1518–307

8–49

STRING Statement

Effect of POINTER Phrase on Data Transfer
If you specify the POINTER phrase, the data item referred to by identifier-4 must have an
initial value that is greater than zero before STRING is executed.
If you do not specify the POINTER phrase, the rules in the following paragraphs apply as
if you had specified a data item with the initial value of 1 (one), which is referred to by
identifier-4. When characters are transferred to the data item referred to by identifier-3,
the moves occur in the following ways:

•

As if each character is moved one at a time from the source into the character
positions of the data item referred to by identifier-3.

•

The value of the data item is determined by the value of the data item referred to by
identifier-4 (if the value of the data item referred to by identifier-4 does not exceed
the length of the data item referred to by identifier-3).

•

As if the data item referred to by identifier-4 is increased by 1 (one) before the move
of the next character or before the end of the STRING statement.

During execution of the STRING statement, the value of the data item referred to by
identifier-4 is changed only as outlined here.
After the STRING statement is executed, only the portion of the data item referred to by
identifier-3 that was referred to during the execution of the STRING statement is
changed. All other portions of the data item referred to by identifier-3 will contain data
that was present before the STRING statement was executed.
Overflow Condition
Before each move of a character to the data item referred to by identifier-3, if the value
associated with the data item referred to by identifier-4 is either less than 1 (one) or
exceeds the number of character positions in the data item referred to by identifier-3, the
following actions occur:

8–50

•

Data is not transferred to the data item referred to by identifier-3.

•

The NOT ON OVERFLOW phrase, if specified, is ignored.

•

Control is transferred to the end of the STRING statement, or to imperativestatement-1, if the ON OVERFLOW phrase is specified.

−

If control is transferred to imperative-statement-1, execution continues according
to the rules for each statement specified in imperative-statement-1.

−

If a procedure-branching statement or a conditional statement that causes
explicit transfer of control is executed, control is transferred according to the
rules for that statement.

−

After imperative-statement-1 is executed, control is transferred to the end of the
STRING statement.

8600 1518–307

STRING Statement

If a STRING statement is executed with the NOT ON OVERFLOW phrase and the
conditions in the previous paragraphs are not encountered, the following actions occur:

•

Data is transferred according to the rules in the previous paragraphs.

•

The ON OVERFLOW phrase, if specified, is ignored.

•

Control is transferred to the end of the STRING statement or to imperativestatement-2, if the NOT ON OVERFLOW phrase is specified.

−

If control is transferred to imperative-statement-2, execution continues according
to the rules for each statement specified in that imperative statement.

−

If a procedure-branching statement or a conditional statement that causes
explicit transfer of control is executed, control is transferred according to the
rules for that statement.

−

After imperative-statement-2 is executed, control is transferred to the end of the
STRING statement.

If identifier-1 or identifier-2 occupies the same storage area as identifier-3 or identifier-4,
or if identifier-3 and identifier-4 occupy the same storage area, the result of the execution
of the STRING statement is undefined, even if these identifiers are defined by the same
data description entry.

Related Information
The following table provides references for additional information related to this
statement:

For information about . . .

Refer to . . .

Declaring the data items to be used as
identifiers and literals for this statement

“USAGE Clause,” “JUSTIFIED Clause,”
and “PICTURE Clause” in Section 4

8600 1518–307

8–51

STRING Statement

Example
IDENTIFICATION DIVISION.
PROGRAM-ID. MANUAL-COBOL85-SEC08-STRING.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 DEST PIC X(26).
01 REC-WS.
05 A PIC X(3)
VALUE IS "DOG".
05 B PIC X(10) VALUE IS "NAME".
05 C PIC X(4)
VALUE IS "XXXX".
77 PTR PIC 99 VALUE IS 1.
PROCEDURE DIVISION.
P1.
STRING A, B, C DELIMITED BY SPACE INTO DEST
WITH POINTER PTR
ON OVERFLOW PERFORM NEW-FLD
END-STRING.
GO TO P1.
NEW-FLD.
DISPLAY DEST.
MOVE 1 TO PTR.
STOP RUN.

In this example, let
A = DOG
B = NAME (blanks)
C = XXXX
Before the first execution of the STRING statement, PTR points to 1 (one). When the
STRING statement is executed, DEST contains “DOGNAMEXXXX” and PTR points to 12.
This execution of the STRING statement does not produce an overflow condition, so
control passes to the imperative statement READ REC-1 INTO REC-WS, the ENDSTRING phrase, and the GO TO statement.
Because DEST contains only 26 characters, the third execution of a STRING statement
(with the values shown here) produces an overflow condition. In this case, control
passes to the imperative statement PERFORM NEW-FLD. The NEW-FLD procedure
writes DEST, resets the pointer to 1, handles any excess data, and prepares a new field
for more data.

8–52

8600 1518–307

SUBTRACT Statement

SUBTRACT Statement
The SUBTRACT statement subtracts one, or the sum of two or more, numeric data items
from one or more items. Then, it sets the values of one or more items equal to the result
of the operation.
This statement is partially supported in the TADS environment. Supported syntax is
noted in this section.

Format

Use

Format 1

The SUBTRACT . . . FROM format subtracts elementary
numeric items.

Format 2

The SUBTRACT . . . FROM . . . GIVING format subtracts
elementary numeric or numeric-edited items.

Format 3

The SUBTRACT CORRESPONDING format subtracts
corresponding items.

The composite of operands must not contain more than 23 decimal digits.

•

Format 1 determines the composite of operands by using all operands in a given
statement.

•

Format 2 determines the composite of operands by using all operands in a given
statement except the data items that follow the word GIVING.

•

Format 3 determines the composite of operands separately for each pair of
corresponding data items.

The compiler ensures that enough places are carried so that significant digits are not lost
during SUBTRACT operations.
Additional rules and explanations relating to the SUBTRACT statement appear in
Section 5 under the following headings:

•

“Arithmetic Expressions”

•

“General Rules for Arithmetic Statements”

•

“Multiple Results in Arithmetic Statements”

•

“Statement Scope Terminators”

8600 1518–307

8–53

SUBTRACT Statement

Format 1: SUBTRACT . . . FROM

SUBTRACT
ïïïïïïïï

ä identifier-1 å
ã
â . . . FROM
æ literal-1
ç
ïïïï

{ identifier-2

[ ROUNDED ] } . . .
ïïïïïïï

[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-SUBTRACT ]
ïïïïïïïïïïïï

TADS Syntax

SUBTRACT
ïïïïïïïï

ä identifier-1 å
ã
â . . . FROM
æ literal-1
ç
ïïïï

{ identifier-2

[ ROUNDED ] } . . .
ïïïïïïï

[ END-SUBTRACT ]
ïïïïïïïïïïïï

Explanation
identifier-1
literal-1

Each identifier must refer to a numeric elementary item. Each literal must be numeric.
These elements represent the data item or literal you are subtracting from the value of
identifier-2.
FROM

When you use Format 1, the values of the operands that precede the word FROM are
added together, and the sum is stored in a temporary data item. The value in this
temporary data item is subtracted from the value of the data item referred to by
identifier-2. The result is stored in the data item referred to by identifier-2. This process
is repeated for each occurrence of identifier-2 in the left-to-right order in which identifier2 is specified.
identifier-2
ROUNDED

Identifier-2 refers to the data item from which you are subtracting identifier-1 or literal-1.
Each identifier must refer to a numeric elementary item. The ROUNDED phrase enables
you to round the result. Refer to “ROUNDED Phrase” in Section 5 for more information.

8–54

8600 1518–307

SUBTRACT Statement

ON SIZE ERROR imperative-statement-1
NOT ON SIZE ERROR imperative-statement-2

The options ON SIZE ERROR and NOT ON SIZE ERROR enable you to include an
imperative statement that specifies an action that will be taken if an error in the size of
the result is or is not encountered. Refer to the “SIZE ERROR Phrase” in Section 5 for
more information.
END-SUBTRACT

This phrase delimits the scope of the SUBTRACT statement.

Example
SUBTRACT A, B FROM C ROUNDED.
In this example, A and B are added together, and the sum is stored in a temporary data
item. The value of this temporary data item is subtracted from C. Then, the result is
rounded and stored in C.

8600 1518–307

8–55

SUBTRACT Statement

Format 2: SUBTRACT . . . FROM . . . GIVING

SUBTRACT
ïïïïïïïï

ä identifier-1 å
ã
â . . . FROM
æ literal-1
ç
ïïïï

ä identifier-2 å
ã
â
æ literal-2
ç

GIVING { identifier-3 [ ROUNDED ] } . . .
ïïïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-SUBTRACT ]
ïïïïïïïïïïïï

TADS Syntax

SUBTRACT
ïïïïïïïï

ä identifier-1 å
ã
â . . . FROM
æ literal-1
ç
ïïïï

GIVING { identifier-3
ïïïïïï
[ END-SUBTRACT ]
ïïïïïïïïïïïï

ä identifier-2 å
ã
â
æ literal-2
ç

[ ROUNDED ] } . . .

Explanation
Refer to Format 1 for descriptions of the syntax elements identifier-1, literal-1, the ON
SIZE ERROR and NOT ON SIZE ERROR options, and the END-SUBTRACT phrase.
identifier-2
literal-2
ROUNDED

Each identifier must refer to a numeric elementary item. Each literal must be numeric.
These elements represent the literal, or the value of the data item, from which you are
subtracting identifier-1 or literal-1. The ROUNDED phrase enables you to round the result.
GIVING identifier-3

Each identifier following the word GIVING must refer to either an elementary numeric
item or an elementary numeric-edited item. When you specify the GIVING phrase, the
result of the subtraction is stored in each data item referred to by identifier-3.

8–56

8600 1518–307

SUBTRACT Statement

Details
In Format 2, all literals and the values of the data items referred to by identifiers that
precede the word FROM are added together. The sum is subtracted from literal-2, or the
value of the data item referred to by identifier-2. The result of the subtraction is stored
as the new content of each data item referred to by identifier-3.

Example
SUBTRACT 456 FROM 1000
GIVING X
ON SIZE ERROR PERFORM ERROR-PARA.
In this example, the literal 456 is subtracted from the literal 1000. The result (544) is
stored in X. If the result contains more characters than X, an ON SIZE ERROR occurs and
the ERROR-PARA is performed.
When you use the GIVING phrase, the data item referred to by identifier-3 (X in this
example) can be a numeric-edited item.

8600 1518–307

8–57

SUBTRACT Statement

Format 3: SUBTRACT CORRESPONDING
ä CORRESPONDING å
ã ïïïïïïïïïïïïï â identifier-1 FROM identifier-2
æ CORR
ç
ïïïï
ïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-SUBTRACT ]
ïïïïïïïïïïïï

SUBTRACT
ïïïïïïïï

[ ROUNDED ]
ïïïïïïï

TADS Syntax
ä CORRESPONDING å
ã ïïïïïïïïïïïïï â identifier-1 FROM identifier-2
æ CORR
ç
ïïïï
ïïïï
[ ON SIZE ERROR imperative-statement-1 ]
ïïïï ïïïïï
[ NOT ON SIZE ERROR imperative-statement-2 ]
ïïï
ïïïï ïïïïï
[ END-SUBTRACT ]
ïïïïïïïïïïïï

SUBTRACT
ïïïïïïïï

[ ROUNDED ]
ïïïïïïï

Explanation
Refer to Format 1 for descriptions of identifier-1 and literal-1 and the phrases ON SIZE
ERROR, NOT ON SIZE ERROR, and END-SUBTRACT.
CORRESPONDING
CORR

The CORRESPONDING (or CORR) option enables you to subtract numeric data items in
one group item from data items of the same name in another group item. Only
elementary numeric data items can be subtracted with this phrase. Refer to the
discussion of the CORRESPONDING phrase under “MOVE Statement” for rules that
also apply to the SUBTRACT CORRESPONDING phrase.
CORR is an abbreviation for CORRESPONDING.
ROUNDED

Each identifier must refer to a group item. The ROUNDED phrase enables you to round
the results.

8–58

8600 1518–307

SUBTRACT Statement

Details
If you use Format 3, data items referred to by identifier-1 are subtracted from and stored
in corresponding data items in identifier-2.

Example
DATA DIVISION.
01 group-1.
05 A PIC 99.
05 B PIC X(4).
05 C PIC 9(8).
01 group-2.
05 A PIC 99.
05 D PIC 99.
05 B PIC X(4).
05 E PIC 9(4).
05 C PIC 9(8).
05 F PIC 9(8).
.
.
.
SUBTRACT CORR group-1 FROM group-2 ROUNDED END-SUBTRACT
In this example, the data items belonging to the group item group-1 are subtracted from
the corresponding data items (A, B, and C) that belong to the group item group-2. The
results are rounded. For details about rounding, refer to “ROUNDED Phrase” in
Section 5.

8600 1518–307

8–59

UNLOCK Statement

UNLOCK Statement
The UNLOCK statement frees a common storage area that was previously restricted by
a LOCK statement.
ä event-identifier å
UNLOCK ã
â
ïïïïïï æ lock-identifier ç

Explanation
event-identifier
lock-identifier

These identifiers indicate the data-name of the storage area that was previously
restricted by a LOCK statement.
The event-identifier can be one or more of the following:

•

The name of a data-item declared with the USAGE IS EVENT phrase. The data-name
must be properly qualified and properly subscripted. See the USAGE clause in
Section 4 for more information.

•

A task attribute of type EVENT. The two event task attributes are ACCEPTEVENT
and EXCEPTIONEVENT. For details about these task attributes, refer to the Task
Attributes Programming Reference Manual.

•

The lock-identifier is a data item declared with the USAGE IS LOCK clause. See the
USAGE clause in Section 4 for more information.

Example
UNLOCK WS-01-EVENT.

8–60

8600 1518–307

UNLOCKRECORD Statement

UNLOCKRECORD Statement
The UNLOCKRECORD statement frees a record in a file that was previously restricted by
a LOCKRECORD statement.

UNLOCKRECORD file-name
[ON EXCEPTION imperative-statement-1]
[NOT ON EXCEPTION imperative-statement-2]
[END-LOCKRECORD]

Explanation
file-name

This user-defined word is the name of the file that contains the record to be unlocked.
This file name must have been used in the previously executed LOCK statement.
ON EXCEPTION imperative-statement-1

This clause specifies an alternate statement to be performed if the UNLOCKRECORD
statement is not successful.
NOT ON EXCEPTION

This clause specifies a statement to be performed after the record is successfully
unlocked.

8600 1518–307

8–61

UNLOCKRECORD Statement

Details
The successful execution of the UNLOCKRECORD statement unlocks the record
specified by the value contained in the data item referenced by the ACTUAL KEY clause
in the File Control Entry of the Environment Division. No other locked records in the file
are affected.
The UNLOCKRECORD statement can fail for any of the following reasons:

•

The specified file

−

Does not exist.

−

Does not support locking (see the requirements for the file described with the
explanation of the file-name syntax for the LOCK statement).

−

Is not open.

•

The specified record key has an invalid or inconsistent value.

•

The record to be unlocked is not locked.

Related Information
The following table provides references to information related to this topic.

8–62

For information about . . .

Refer to . . .

Locking a file

The LOCKRECORD statement.

I-O status codes resulting from error with
locking and unlocking files

Table 3–6.

8600 1518–307

UNSTRING Statement

UNSTRING Statement
The UNSTRING statement separates contiguous data in a sending field and places the
data into multiple receiving fields. Format 2 is a modified version of Format 1.

Format 1: UNSTRING . . . INTO
UNSTRING identifier-1
ïïïïïïïï
Ú
Ú
¿
¿
³
äidentifier-2å ³
äidentifier-3å ³
³
³DELIMITED BY [ ALL ] ã
â ³ OR [ ALL ] ã
â ³ . . . ³
³ïïïïïïïïï
ïïï
æliteral-1
ç ³ ïï
ïïï
æliteral-2
ç ³
³
À
À
Ù
Ù
INTO { identifier-4 [ DELIMITER IN identifier-5 ]
ïïïï
ïïïïïïïïï
[ COUNT IN identifier-6 ] }. . .
ïïïïï
[ WITH POINTER identifier-7 ]
ïïïïïïï
[ TALLYING IN identifier-8 ]
ïïïïïïïï
[ ON OVERFLOW imperative-statement-1 ]
ïïïïïïïï
[ NOT ON OVERFLOW imperative-statement-2 ]
ïïï
ïïïïïïïï
[ END-UNSTRING ]
ïïïïïïïïïïïï

Explanation
identifier-1

The data item referenced by this identifier must be described, implicitly or explicitly, as
alphanumeric or national.
The data item referenced by identifier-1 represents the sending area. Identifier-1 cannot
be reference-modified.
DELIMITED BY

Each literal in this phrase must be a nonnumeric or a national literal.
Neither literal-1 nor literal-2 can be a figurative constant that begins with the word ALL.
Literal-1 or the data item referenced by identifier-2 can contain any character in the
computer's character set.
The data items referenced by identifier-2 and identifier-3 must be described, implicitly or
explicitly, as alphanumeric or national.

8600 1518–307

8–63

UNSTRING Statement

Each literal-1 or data item referenced by identifier-2 represents one delimiter. When a
delimiter contains two or more characters, all of the characters must be present (in the
order given in contiguous positions of the sending item) to be recognized as a delimiter.
When you use a figurative constant as a delimiter, it represents a single-character
nonnumeric or national literal.
When you specify two or more delimiters in the DELIMITED BY phrase, an OR condition
must exist between them.
Each delimiter is compared to the sending field. If a match occurs, the character or
characters in the sending field are considered to be a single delimiter. A character in the
sending field cannot be considered a part of more than one delimiter.
Each delimiter is applied to the sending field in the sequence specified.
You cannot specify the DELIMITER IN phrase or the COUNT IN phrase unless you also
specify the DELIMITED BY phrase.
ALL

If you specify the ALL phrase, one occurrence—or two or more contiguous
occurrences—of literal-1 or the content of the data item referenced by identifier-2 is
treated as only one occurrence, and this occurrence is moved to the receiving data item
according to rule 4 described in “Rules for Data Transfer” in this section. This rule applies
whether or not literal-1 is a figurative constant.
Without the ALL phrase, when any examination encounters two contiguous delimiters,
the current receiving area is either space- or zero-filled, according to the description of
the receiving area.
INTO identifier-4

The data item referenced by identifier-4 represents the receiving area. Identifier-4 can be
described as alphabetic, alphanumeric, national, or numeric (except that the symbol P
cannot be used in the PICTURE character-string). Identifier-4 must be described,
implicitly or explicitly, as USAGE IS DISPLAY or USAGE IS NATIONAL.
DELIMITER IN identifier-5

The data item referenced by identifier-5 must be described, implicitly or explicitly, as
alphanumeric or national.
Identifier-5 represents the receiving area for delimiters.
When you use a figurative constant as a delimiter, the delimiter must be a singlecharacter, nonnumeric or national literal.

8–64

8600 1518–307

UNSTRING Statement

If two contiguous delimiters are encountered, the current receiving area is as follows:

•

Space-filled if the area is described as alphabetic, alphanumeric, or national

•

Zero-filled if the area is described as numeric

COUNT IN identifier-6

The data item referenced by identifier-6 must be described as an integer data item
(except that the symbol P cannot be used in the PICTURE character-string).
The data item referenced by identifier-6 represents the number of characters in the
sending item that have been isolated by the delimiters for the move to the receiving
item. This value does not include a count of the delimiter character or characters.
WITH POINTER identifier-7

The data item referenced by identifier-7 must be described as an elementary numeric
integer data item of sufficient size to contain a value equal to 1 plus the size of the data
item referenced by identifier-1. The symbol P cannot be used in the PICTURE characterstring of identifier-7.
The data item referenced by identifier-7 contains a value that indicates a relative
character position within the area referenced by identifier-1.
The content of the data item referenced by identifier-7 is incremented by one for each
character examined in the data item referenced by identifier-1. When the execution of an
UNSTRING statement with a POINTER phrase is completed, the content of the data item
referenced by identifier-7 contains a value equal to the initial value plus the number of
characters examined in the data item referenced by identifier-1.
The program must initialize the contents of the data item used in the POINTER phrase
(identifier-7).
TALLYING IN identifier-8

The data item referenced by identifier-8 must be described as an integer data item
(except that the symbol P cannot be used in the PICTURE character-string).
The data item referenced by identifier-8 is a counter that is incremented by 1 for each
occurrence of the data item referenced by identifier-4 that is accessed during the
UNSTRING operation.
The program must initialize the contents of the data items in the TALLYING phrase
(identifier-8).
ON OVERFLOW imperative-statement-1
NOT ON OVERFLOW imperative-statement-2

8600 1518–307

8–65

UNSTRING Statement

When you specify a NOT ON OVERFLOW phrase and an overflow condition does not
exist, control passes to imperative-statement-2.
Either of the following situations causes an overflow condition:

•

An UNSTRING statement is initiated, and the value in the data item referenced by
identifier-7 is less than 1 or greater than the size of the data item referenced by
identifier-1.

•

During execution of an UNSTRING statement, all data receiving areas have been
acted upon, and the data item referenced by identifier-1 contains characters that
have not been examined.

END-UNSTRING

This phrase delimits the scope of the UNSTRING statement.
Overlapping Operands
The result of the execution of the UNSTRING statement is undefined, even if the
overlapping data items are defined by the same data description, if any of the following
conditions exist:

•

A data item referenced by identifier-1, identifier-2, or identifier-3 occupies the same
storage area as a data item referenced by identifier-4, identifier-5, identifier-6,
identifier-7, or identifier-8.

•

A data item referenced by identifier-4, identifier-5, or identifier-6 occupies the same
storage area as a data item referenced by identifier-7 or identifier-8.

•

A data item referenced by identifier-7 occupies the same storage area as a data item
referenced by identifier-8.

Rules for Data Transfer
When the UNSTRING statement is initiated, the current receiving area is the data item
referenced by identifier-4. Data is transferred from the data item referenced by identifier1 to the data item referenced by identifier-4 according to the following rules:

8–66

•

If you specify the POINTER phrase, the string of characters referenced by identifier-1
is examined beginning with the relative character position indicated by the contents
of the data item referenced by identifier-7.

•

If you do not specify the POINTER phrase, the string of characters is examined
beginning with the leftmost character position.

•

If you specify the DELIMITED BY phrase, the examination proceeds left to right until
either a delimiter specified by the value of literal-1 or the value of the data item
referenced by identifier-2 is encountered.

•

If you do not specify the DELIMITED BY phrase, the number of characters examined
equals the size of the current receiving area. However, if the sign of the receiving
item is defined as occupying a separate character position, the number of characters
examined is one less than the size of the current receiving area.

8600 1518–307

UNSTRING Statement

•

If the end of the data item referenced by identifier-1 is encountered before the
delimiting condition is met, the examination terminates with the last character
examined.

•

The characters thus examined (excluding any delimiting character or characters) are
treated as elementary alphanumeric or national data items. They are moved into the
current receiving field according to the rules of the MOVE statement. See “MOVE
Statement” in this section for details.

•

Note that if you specify delimiters and identifier-1 begins with the specified delimiter
or delimiters, the first receiving field—the data item referenced by identifier-4—is
either zero- or space-filled, according to the description of identifier-4. If this is not
desired, do the following:
1. INSPECT identifier-1 TALLYING the LEADING delimiter or delimiters.
2. UNSTRING identifier-1 using the POINTER phrase, setting identifier-7 to 1 more
than the count tallied by the INSPECT statement.

•

If you specify the DELIMITER IN phrase, the delimiting character or characters are
treated as elementary alphanumeric or national data items and are moved into the
data item referenced by identifier-5 according to the rules of the MOVE statement.
See “MOVE Statement” in this section for details. If the delimiting condition is the
end of the data item referenced by identifier-1, the data item referenced by identifier5 is space-filled.

•

If you specify the COUNT IN phrase, a value equal to the number of characters thus
examined (excluding any delimiter character or characters) is moved into the area
referenced by identifier-6 according to the rules for an elementary move (refer to
“MOVE Statement” in this section).

•

If you specify the DELIMITED BY phrase, the string of characters is further examined
beginning with the first character to the right of the delimiter.

•

If you do not specify the DELIMITED BY phrase, the string of characters is further
examined beginning with the character to the right of the last character transferred.

•

After data is transferred to the data item referenced by identifier-4, the current
receiving area is the data item referenced by identifier-7. The actions described in
paragraphs 2 through 6 are repeated until all the characters are exhausted in the data
item referenced by identifier-1, or until there are no more receiving areas.

8600 1518–307

8–67

UNSTRING Statement

Example
In the following example, DUMMY-ITEM is a data item that contains the string:
+,=,?"9,abc
The following procedure unstrings DUMMY-ITEM:
UNSTRING DUMMY-ITEM
DELIMITED BY ","
OR QUOTES
INTO
PLUS-SIGN, DELIMITER IN COMMA-MARK,
EQUAL-SIGN,
QUESTION-MARK, DELIMITER IN QUOTE-MARK,
NINE, COUNT IN COUNTER-ITEM,
PLUS-WORD,
TIMES-WORD,
TALLYING IN START-END-POSITIONS,
ON OVERFLOW
DISPLAY "WE FOUND MORE THAN"
START-END-POSITIONS "ITEMS TO UNSTRING".
The following data items result from this procedure:

8–68

•

PLUS-SIGN contains +

•

EQUAL-SIGN contains =

•

QUESTION-MARK contains ?

•

NINE contains 9

•

PLUS-WORD contains abc

•

TIMES-WORD is empty

•

COMMA-MARK contains the comma delimiter (,)

•

QUOTE-MARK contains the quote delimiter (")

•

COUNTER-ITEM contains 1

•

START-END-POSITIONS contains 5

8600 1518–307

UNSTRING Statement

Format 2: UNSTRING . . . INTO . . . FOR
UNSTRING identifier-1
ïïïïïïïï
ä
INTO ã identifier-2 FOR
ïïïï æ
ïïï

ä identifier-3 å å
ã
â â . . .
æ literal-1
ç ç

[ WITH POINTER identifier-4 ]
ïïïïïïï
[ TALLYING IN identifier-5 ]
ïïïïïïïï
[ ON OVERFLOW imperative-statement-1 ]
ïïïïïïïï
[ NOT ON OVERFLOW imperative-statement-2 ]
ïïï
ïïïïïïïï
[ END-UNSTRING ]
ïïïïïïïïïïïï

Explanation
Refer to the description of Format 1 for an explanation of the INTO, WITH POINTER,
TALLYING IN, and END-UNSTRING phrases, and the syntax element identifier-1.
identifier-2

The same rules apply to this data item as to identifier-4 of Format 1.
FOR
identifier-3
literal-1

This phrase specifies the number of characters to transfer. Identifier-3 must be described
as an elementary numeric integer data item (except that the symbol P cannot be used in
the PICTURE character-string).
ON OVERFLOW imperative-statement-1
NOT ON OVERFLOW imperative-statement-2

Either of the following situations causes an overflow condition:

•

An UNSTRING statement is initiated, and the value in the data item referenced by
identifier-3 is less than 1 or greater than the size of the data item referenced by
identifier-1.

•

During execution of an UNSTRING statement, all data receiving areas have been
acted upon, and the number of characters acted upon is less than the value of the
data item referenced by identifier-3 or the value of literal-1.

8600 1518–307

8–69

UNSTRING Statement

When an overflow condition exists, the UNSTRING operation is terminated. If you
specify an ON OVERFLOW phrase, the imperative statement included in the ON
OVERFLOW phrase is executed. If you do not specify an ON OVERFLOW phrase,
control passes to the next executable statement.
When you specify a NOT ON OVERFLOW phrase and an overflow condition is not
encountered, control is transferred to the statement specified in imperative-statement-2.

Details
Literal-1 or the data item referenced by identifier-3 specifies the number of characters in
identifier-1 that are moved to identifier-2. If the number of characters remaining in the
data item referenced by identifier-1 is less than the number of characters specified by
literal-1 or the data item referenced by identifier-3, the short field is transferred according
to rule 3 described in “Rules for Data Transfer” in Format 1 of this section.

Example
In the following example, the data item DUMMY-ITEM contains the string:
CALIFMINALNEBCONNIOWAOHTX
Before execution of the following procedure, the pointer P-WORD contains a value of 1:
UNSTRING DUMMY-ITEM INTO FIRST-ITEM FOR 5,
SECOND-ITEM FOR 3,
THIRD-ITEM FOR 2,
FOURTH-ITEM FOR 3,
FIFTH-ITEM FOR 4,
SIXTH-ITEM FOR 4,
WITH POINTER P-WORD,
TALLYING IN START-END-POSITIONS,
ON OVERFLOW
DISPLAY "ONLY" P-WORD "POSITIONS WERE EXAMINED".
The following data items result from this procedure:

8–70

•

FIRST-ITEM contains CALIF

•

SECOND-ITEM contains MIN

•

THIRD-ITEM contains AL

•

FOURTH-ITEM contains NEB

•

FIFTH-ITEM contains CONN

•

SIXTH-ITEM contains IOWA

•

START-END-POSITIONS contains 6

•

P-WORD contains 22

8600 1518–307

USE Statement

USE Statement
Format

Use

Format 1

The USE AFTER format defines the conditions for the execution of USE
procedures by the I/O control system for I/O error handling.

Format 2

The USE PROCEDURE format enables untyped procedures or subroutines
to be declared COMMON or EXTERNAL.

Format 3

The USE AS INTERRUPT PROCEDURE format specifies a declarative
statement as an interrupt procedure.

Format 4

The USE AS EPILOG PROCEDURE format specifies a declarative
statement as an epilog procedure.

Format 1: USE AFTER

ä EXCEPTION å
USE [GLOBAL] AFTER STANDARD ã ïïïïïïïïï â PROCEDURE ON
ïïï ïïïïïï ïïïïï
æ ERROR
ç ïïïïïïïïï
ïïïïï

ä
³
³
³
ã
³
³
³
æ

{ file-name-1 }å
³
INPUT
³
ïïïïï
³
OUTPUT
â
ïïïïïï
³
I-O
³
ïïï
³
EXTEND
ç
ïïïïïï

Explanation
USE AFTER

The USE AFTER statement is never executed itself; it merely defines the conditions
calling for the execution of the USE procedures.
A USE AFTER statement must immediately follow a section header in the declaratives
portion of the Procedure Division and must appear in a sentence by itself. The remainder
of the section must consist of any number of procedural paragraphs that define the
procedures to be used.
GLOBAL

The GLOBAL option enables any programs nested within the program that contains the
GLOBAL option to use the USE procedures, if applicable.
ERROR
EXCEPTION

The words ERROR and EXCEPTION are synonymous and can be used interchangeably.

8600 1518–307

8–71

USE Statement

file-name-1

The files implicitly or explicitly referenced in a USE AFTER statement need not all have
the same organization or access.
The appearance of file-name-1 in a USE AFTER statement must not cause the
simultaneous request for execution of more than one USE AFTER procedure. That is,
when file-name-1 is specified explicitly, no other USE statement can apply to file-name-1.
INPUT
OUTPUT
I-O
EXTEND

The INPUT, OUTPUT, I-O, and EXTEND phrases can each be specified only once in the
declaratives portion of a given Procedure Division.

Details
Declarative procedures can be included in any COBOL source program whether or not
the program contains, or is contained in, another program. Refer to Section 5 for
information about declarative procedures and compiler-directing statements.
A declarative is invoked when any of the conditions described in the USE AFTER
statement that prefaces the declarative occur while the program is being executed. Only
a declarative in the separately compiled program, which contains the statement that
caused the qualifying condition, is invoked when any of the conditions described in the
USE statement, which prefaces the declarative, occurs while that separately compiled
program is being executed. If a qualifying declarative does not exist in the separately
compiled program, the declarative is not executed.
A declarative procedure cannot reference nondeclarative procedures when the program
employs any of the following: Report Writer, a USE statement with the GLOBAL option,
the USE AS INTERRUPT statement, or the USE AS EPILOG statement. Procedurenames associated with a USE AFTER statement can be referenced in a different
declarative section, or in a nondeclarative procedure only with a PERFORM statement.
The procedures associated with the USE AFTER statement are executed by the inputoutput control system after completing the standard error retry routine if the execution of
the input-output routine was unsuccessful. However, an AT END phrase can take
precedence.

8–72

8600 1518–307

USE Statement

Rules
The following rules concern the execution of the procedures associated with the USE
AFTER statement:

•

If you specify file-name-1, the associated procedure is executed when the condition
described in the USE AFTER statement occurs to the file.

•

If you specify INPUT, the associated procedure is executed when the condition
described in the USE AFTER statement occurs for any file that is open in the input
mode, or that is in the process of being opened in the input mode. Those files
referenced by file-name-1 in another USE AFTER statement that specify the same
condition are not executed.

•

If you specify OUTPUT, the associated procedure is executed when the condition
described in the USE AFTER statement occurs for any file that is open in the output
mode, or that is in the process of being opened in the output mode. Those files
referenced by file-name-1 in another USE AFTER statement that specify the same
condition are not executed.

•

If you specify I-O, the associated procedure is executed when the condition
described in the USE AFTER statement occurs for any file that is open in the I-O
mode, or that is in the process of being opened in the I-O mode. Those files
referenced by file-name-1 in another USE AFTER statement that specify the same
condition are not executed.

•

If you specify EXTEND, the associated procedure is executed when the condition
described in the USE AFTER statement occurs for any sequential file that is open in
the EXTEND mode, or that is in the process of being opened in the EXTEND mode.
Those sequential files referenced by file-name-1 in another USE AFTER statement
that specify the same condition are not executed.

After execution of a USE procedure, control passes to the invoking routine in the inputoutput control system. If the I-O status value does not indicate a critical input-output
error, the input-output control system returns control to the next executable statement
that follows the input-output statement whose execution caused the exception. Refer to
the discussion of the STATUS IS clause in Section 3 for information on I-O status values.
In a USE procedure, a statement cannot be executed if it would cause the execution of a
USE procedure that had previously been invoked and had not yet returned the control to
the invoking routine.

8600 1518–307

8–73

USE Statement

Precedence Rules for Nested Programs
Special precedence rules are followed when programs are nested. In applying these
rules, only the first qualifying declarative is selected for execution. The declarative
selected for execution must satisfy the rules for execution of that declarative. The order
of precedence is as follows:
1. The declarative within the program that contains the statement that caused the
qualifying condition
2. The declarative in which the GLOBAL phrase is specified and that is within the
program directly containing the program which was last examined for a qualifying
declarative
3. Any declarative selected by applying rule 1 to each more inclusive containing
program until rule 2 is applied to the outermost program. If a qualifying declarative is
not found, none is executed.
The following scenario illustrates this order of precedence:
Program A contains program B, which contains program C. Each program contains USE
statements.
If an I/O error occurs while program C is executing, the system first looks for the USE
statement in program C. If the statement is not applicable, as in the case where an error
occurred on INPUT and the USE statement specified on OUTPUT, the system then looks
at the USE statement in program B. The USE statement in program B is executed if the
statement contains the GLOBAL option and is applicable. Otherwise, the system looks at
the USE statement in program A. The USE statement in program A is executed if it
contains the GLOBAL option and is applicable.
If none of the USE statements are applicable, none are executed.

Example
PROCEDURE DIVISION
DECLARATIVES.
PARITY-ERROR SECTION.
USE AFTER ERROR PROCEDURE ON TAPEIN.
ERROR-ROUTINE.
.
.
.
If an input-output error occurs for the file TAPEIN, the standard input-output errorhandling procedures are followed as well as the procedures specified in ERRORROUTINE.

8–74

8600 1518–307

USE Statement

Format 2: USE PROCEDURE

USE

ä
³
³
ã
³
³
æ

Ú
³ mnemonic-name
EXTERNAL ³
ïïïïïïïï ³ identifier-1
À
AS COMMON PROCEDURE
ïï ïïïïïï ïïïïïïïïï
Ú
³
³
³
³
À

WITH
ïïïï

¿
³
³
³
Ù

å
³
AS PROCEDURE ³
ïïïïïïïïï â
³
³
ç

ä local-storage-name å
ã
â . . .
æ file-name-1
ç

USING identifier-2
ïïïïï

¿
³
³
³ .
[ ,identifier-3 ] . . . ³
Ù

Explanation
The USE EXTERNAL phrase identifies procedures to be bound from another program or
the separately compiled program that is to be used as the task when this section is
referenced.
The USE AS COMMON PROCEDURE phrase identifies a procedure that exists in the
host program and is to be called in this bound procedure.
mnemonic-name

Mnemonic-name specifies either the program that contains the procedure to be bound or
the program that is to be executed as a task. The mnemonic-name must be defined in
the Special-Names paragraph of the Environment Division. In binding, the mnemonicname can be overridden by the explicit program-name specified in the BIND statement.
local-storage-name

All local-storage-names must be defined in the Local-Storage Section. You must include a
local-storage-name if the USING phrase is present in the CALL, PROCESS, or RUN
statement.
identifier-1

Identifier-1 specifies the program that is to be executed as a task. Identifier-1 must be
defined in the Working-Storage Section of the Data Division.
file-name-1

File-name-1 must be uniquely defined as a local file in the File Section.

8600 1518–307

8–75

USE Statement

identifier-2
identifier-3

Identifier-2, identifier-3 and so forth must be uniquely defined as 01-level or 77-level data
items of the local-storage-name specified in the WITH phrase, or they must be defined
as files in the File Section.

Format 3: USE AS INTERRUPT PROCEDURE
USE AS INTERRUPT PROCEDURE.
ïïï
ïïïïïïïïï ïïïïïïïïï

Explanation
The USE AS INTERRUPT PROCEDURE statement specifies a declarative as an interrupt
procedure. By declaring an interrupt procedure and then attaching an event to the
interrupt procedure (with the ATTACH statement), you can programmatically interrupt a
process when the event attached to that procedure occurs. You must include additional
statements after the USE statement to be executed when the event occurs and the
interrupt procedure is allowed (ALLOW statement).
When an interrupt procedure is being executed, all other interrupts to the process being
interrupted are disallowed. Thus, an interrupt procedure itself cannot be interrupted.

Related Information
The following table provides additional references for information related to this topic.

For more information about . . .

8–76

Refer to . . .

The mechanisms for handling interrupt
procedures

The ALLOW, ATTACH, CAUSE, DETACH,
DISALLOW, and RESET statements.

Specifying a data item as an event

The “USAGE Clause” in Section 4.

8600 1518–307

USE Statement

Format 4: USE AS EPILOG PROCEDURE
USE AS EPILOG PROCEDURE.
ïïï
ïïïïïï ïïïïïïïïï

Explanation
The USE AS EPILOG PROCEDURE statement specifies a declarative as an epilog
procedure. An epilog procedure enables you to designate a procedure that must be
executed before exiting the program. The epilog procedure executes each time the
program exits, whether the exit is normal or abnormal. This enables the user to perform
necessary clean-up or to free locked resources before terminating.
To see if a program terminated normally, include a test in the epilog procedure as
follows:
IF ATTRIBUTE HISTORYCAUSE OF MYSELF = 0 THEN

ELSE
.
Restrictions on Epilog Procedures
The following restrictions apply to the epilog procedure:

•

A GO TO statement cannot be used to exit from an epilog procedure.

•

A program cannot have more than one EPILOG PROCEDURE declaration.

•

A program with an EPILOG PROCEDURE declaration cannot be used as the host
code file when running BINDER.

•

If a program that contains an EPILOG PROCEDURE declaration fails because of a
fatal stack overflow, the epilog procedure is not executed.

•

If a program contains an EPILOG PROCEDURE declaration and the statistics option
is TRUE, the epilog procedure is executed before the statistics wrap-up code.

•

If certain Data Management System (DMS) statements such as OPEN or CLOSE are
executed, it might not be possible to return to the epilog procedure if the executing
task is discontinued.

•

During a TADS session, all breakpoints are ignored when the epilog procedure is
being executed after normal execution is completed.

•

An ALTER statement might not reference a paragraph within the epilog procedure.

8600 1518–307

8–77

WAIT Statement

WAIT Statement
The WAIT statement suspends execution of the program for a specified length of time or
until one or more conditions is true.

Format

8–78

Use

Format 1

This format suspends execution of the object program for a
specified length of time or until one or more conditions is true.

Format 2

This format suspends execution of the process until one of its
interrupt procedures is executed.

8600 1518–307

WAIT Statement

Format 1: Wait for Time or Condition
Following is the syntax diagram.

WAIT [ AND RESET ] UNTIL
ïïïï
ïïïïï
ä arithmetic-expression
³
³
Ú
¿
³ ATTRIBUTE CHANGEEVENT
³ä IN å³
Ú
³ ïïïïïïïïï ïïïïïïïïïïï
³³ ïï ³³
³
³ ATTRIBUTE INPUTEVENT
³ã OF â³file-name-1 ³(
³ ïïïïïïïïï ïïïïïïïïïï
³³ ïï ³³
³
³ ATTRIBUTE OUTPUTEVENT
³æ ON ç³
À
³ ïïïïïïïï ïïïïïïïïïïï
À ïï Ù
³
³
Ú
¿
³ ATTRIBUTE ACCEPTEVENT
³ä IN å³
Ú
³ ïïïïïïïïï ïïïïïïïïïïï
³³ ïï ³³
³
³ ATTRIBUTE EXCEPTIONEVENT ³ã OF â³ task-name ³(
³ ïïïïïïïïï ïïïïïïïïïïïïïï ³³ ïï ³³
³
³ event-identifier
³æ ON ç³
À
³
À ïï Ù
³
³
ä identifier-3 å
³ CRCR-INPUT ã
â
³ ïïïïïïïïïï æ literal-3
ç
ã
³
ä identifier-4 å
³ CRCR-OUTPUT ã
â
³ ïïïïïïïïïïï æ literal-4
ç
³
³ ODT-INPUT-PRESENT
³ ïïïïïïïïïïïïïïïïï
³
Ú
¿
³
³
ä literal-1
å
³
³ READ-OK ON file-name-1 ³ ( ã
â ) ³
³ ïïïïïïï
³
æ identifier-1 ç
³
³
À
Ù
³
³ WRITE-OK
³ ïïïïïïïï
³ STOQ-INPUT identifier-5
³ ïïïïïïïïïï
æ STOQ-OUTPUT identifier-6
ïïïïïïïïïïï
[ USING identifier-7 ]
ïïïïï
[ GIVING identifier-8 ]
ïïïïïï

8600 1518–307

ä identifier-1 å
ã
â
æ literal-1
ç

ä identifier-2 å
ã
â
æ literal-2
ç

å
³
³
¿³
³³
)³³
³³
Ù³
³
³
³
¿³
³³
)³³
³³
Ù³
³
³
³
³
³
â ...
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
ç

8–79

WAIT Statement

Explanation
AND RESET

The AND RESET phrase causes the condition or event that terminated the wait to be
reset. The condition or event is specified in the UNTIL phrase of this format.
arithmetic-expression

This specifies the number of seconds the program is suspended. The maximum wait
time is 164925 seconds (approximately 45.8 hours). If you specify a wait time that
exceeds this maximum, the task waits only 164925 seconds.
Only one arithmetic-expression can be specified in a WAIT statement. If multiple
conditions are specified, the arithmetic-expression must be the first condition in the list.
If the specified number of seconds elapses before an event occurs, the AND RESET
phrase has no effect.
ATTRIBUTE INPUTEVENT

This is a synonym for the READ-OK option. For details about this file attribute, refer to
the File Attributes Programming Reference Manual.
ATTRIBUTE OUTPUTEVENT

This is a synonym for WRITE-OK. For details about this file attribute, refer to the File
Attributes Programming Reference Manual.
ATTRIBUTE CHANGEEVENT

This condition suspends the program until the value of the FILESTATE attribute has
changed. For details about this file attribute, refer to the File Attributes Programming
Reference Manual.
READ-OK

This condition suspends the program until at least one record is available from file-name1 (that is, until the CENSUS attribute of the file has a value greater than 1.)
For files that are not open, this condition is always FALSE.
READ-OK is synonymous with ATTRIBUTE INPUTEVENT.
WRITE-OK

This condition suspends the program until enough space exists in the file for at least one
more record to be written (that is, until the CENSUS attribute of the file has a value less
than the MAXCENSUS attribute).
For files that are not open, this condition is always FALSE.

8–80

8600 1518–307

WAIT Statement

file-name-1
identifier-1
literal-1

File-name-1 must name a port file. You can specify a subport by including literal-1 or
identifier-1 in parentheses following the file name. If an identifier is specified, it must
describe an elementary numeric data item that does not contain the symbol P in its
PICTURE clause.
ATTRIBUTE ACCEPTEVENT
ATTRIBUTE EXCEPTIONEVENT
event-identifier

This is either a task attribute of type EVENT (either ACCEPTEVENT or
EXCEPTIONEVENT) or a data item declared with the USAGE IS EVENT clause. When
used, this format specifies that the program is to suspend execution until the event has
been activated by the CAUSE statement. ATTRIBUTE ACCEPTEVENT performs the
same function as the ODT-INPUT-PRESENT option.
task-name

Task-name must name a task variable. You can specify an entry in a task array by
including literal-2 or identifier-2 in parentheses following the task-name. If an identifier is
specified, it must describe an elementary numeric data item that does not contain the
symbol P in its PICTURE clause.
CRCR-INPUT

This condition suspends the program until the sending program is ready to send the data
by using the MCP core-to-core mechanism (refer to Format 1 of the SEND statement for
details). Identifier-3 or literal-3 must specify the name of the program that will send the
data.
CRCR-OUTPUT

This condition suspends the program until the receiving program is ready to receive the
data by using the MCP core-to-core mechanism (refer to Format 1 of the RECEIVE
statement for details). Identifier-4 or literal-4 must specify the name of the program that
will receive the data.
ODT-INPUT-PRESENT

This condition occurs whenever input is sent to the process through the AX command.
Execution of an ACCEPT statement that specifies the ODT as input causes this condition
to be reset. The AND RESET phrase also resets this condition. Only one ODT-INPUTPRESENT clause can be specified in a WAIT statement. ODT-INPUT-PRESENT is
synonymous with ATTRIBUTE ACCEPTEVENT.

8600 1518–307

8–81

WAIT Statement

STOQ-INPUT

This condition suspends the program until a STOQ entry is available to be received into
the program (refer to Format 2 of the RECEIVE statement for details). Identifier-5 must
be a 01 level data item that defines a STOQ parameter block.
STOQ-OUTPUT

This condition suspends the program until space is available in a storage queue for data
to be sent from the program (refer to Format 2 of the SEND statement for details).
Identifier-6 must be a 01 level data item that defines a STOQ parameter block.
USING identifier-7

This phrase specifies a value in identifier-7 that is used to determine which event should
be tested first for a true condition. When the USING phrase is not specified, the first
item in the list is tested first.
GIVING identifier-8

This phrase identifies the condition that caused the wait to terminate. When this phrase
is used, identifier-8 is set to the value of the position in the list of the event or condition
that terminated the wait. For example, if the second event in the list terminated the wait,
the data item referenced by identifier-8 is set to the value 2.

Details
If any condition specified in the WAIT statement is true, the wait terminates and control
passes to the next executable statement in the program.
If none of the conditions specified in the WAIT statement are true, program execution is
suspended until one of the conditions becomes true. When one of the conditions
becomes true, the wait terminates and control passes to the next executable statement
in the program.

8–82

8600 1518–307

WAIT Statement

Example
WAIT UNTIL (WAIT-RETRY-TIME + (LOAD-FACTOR * NUMBER-USERS)).
This suspends program execution for the number of seconds specified by the arithmetic
expression WAIT-RETRY-TIME + (LOAD-FACTOR * NUMBER-USERS).
WAIT AND RESET WAIT-RETRY-TIME
ODT-INPUT-PRESENT
GIVING WAIT-ENDER.
This suspends program execution for the number of seconds specified by WAIT-RETRYTIME, or until the condition ODT-INPUT-PRESENT becomes true, whichever occurs first.
The condition that terminated the wait is identified by the value of the data item WAITENDER. If the elapsed time exceeds the value of WAIT-RETRY-TIME, then WAIT-ENDER
contains the value 1. If the condition ODT-INPUT-PRESENT becomes true, then WAITENDER contains the value 2.

Format 2: Wait Until Interrupt
WAIT UNTIL INTERRUPT
ïïïï ïïïïï ïïïïïïïïï

Details
This statement suspends the execution of a program until one of its interrupt procedures
is executed. After the interrupt procedure executes, the suspended program resumes
execution. The program runs indefinitely unless one of its interrupt procedures contains a
STOP RUN statement.

8600 1518–307

8–83

WRITE Statement

WRITE Statement
The WRITE statement releases a logical record for a file. It can also be used for vertical
positioning of lines within a logical page.
This statement is partially supported in a TADS environment. Applicable exclusions are
noted in this section.

Format

Use

Format 1

This format is for use with sequential files.

Format 2

This format is for use with relative and indexed files.

Format 1: WRITE (Files in Sequential Access Mode)
ä FILE file-name-1 [ SYNCHRONIZED ]
ã ïïïï
ïïïïïïïïïïïï
æ record-name-1
[ SYNCHRONIZED ]
ïïïïïïïïïïïï

WRITE
ïïïïï
Ú
³
³
³
³
³
³
³
³
À
Ú
³
³
³
À
Ú
³
³
³
À

ä BEFORE å
ã ïïïïïï â ADVANCING
æ AFTER ç
ïïïïï

ä END-OF-PAGE å
ã ïïïïïïïïïïï â
æ EOP
ç
ïïï

ä END-OF-PAGE å
NOT AT ã ïïïïïïïïïïï â
ïïï
æ EOP
ç
ïïï

ä
³
³
ã
³
³
³
æ

ä
ã
æ
ä
ã
æ

FROM identifier-1
å
ïïïï
â
[ FROM identifier-1 ] ç
ïïïï

Ú
identifier-2 å ³ LINE
â ³
integer-1
ç ³ LINES
À
mnemonic-name-1 å
â
PAGE
ç
ïïïï

imperative-statement-1

imperative-statement-2

¿
³
³
³
Ù

å
³
³
â
³
³
³
ç

¿
³
³
³
³
³
³
³
³
Ù

¿
³
³
³
Ù
¿
³
³
³
Ù

[ END-WRITE ]
ïïïïïïïïï

This format is supported in the TADS environment.

8–84

8600 1518–307

WRITE Statement

Explanation
FILE file-name-1

File-name-1 is the name of a file in the File Section of the Data Division. To use the FILE
phrase, you must specify the EXTERNAL-FORMAT clause in the file description entry for
file-name-1.
File-name-1 cannot reference a sort-merge description entry or a report file.
When the FILE phrase is specified, the contents of the logical record area of the file are
not affected by identifier-1 specified in the accompanying FROM phrase. The result of
the execution of the WRITE FILE statement with the FROM phrase is the same as the
execution of the following statements:
MOVE identifier-1 TO implicit record.
WRITE implicit-record TO file-name.
The implicit-record refers to the record description that is the same as the data
description entry for identifier-1.
record-name-1

Record-name-1 is the name of a logical record in the File Section of the Data Division.
This name can be qualified.
Record-name-1 and identifier-1 cannot refer to the same storage area.
The file referenced by the file-name associated with record-name-1 must be in the
output, I-O, or extend mode at the time the WRITE statement is executed. (You must
reset the compiler option ANSICLASS (FS48) to enable the program to write to a file that
is open in the I-O mode.)
The execution of the WRITE statement releases a logical record to the operating system.
The execution of a WRITE statement does not affect the contents or accessibility of the
record area.
If the associated file is named in the SAME RECORD AREA clause, the logical record is
also available to the program as a record of other files referenced in that SAME RECORD
AREA clause as the associated output file, as well as to the file associated with recordname-1. As a result, records in a sequential file opened in I-O mode cannot normally be
replaced by a WRITE statement during an update operation. A READ-MODIFY-WRITE
sequence accesses logical record n, modifies it, and writes it into logical position n+1 in
the file. The next READ accesses logical record n+2, and so on. In order to modify a
record n in place in a sequential file, the sequence READ-MODIFY-REWRITE must be
used.

8600 1518–307

8–85

WRITE Statement

SYNCHRONIZED

This option enables you to override the synchronization specified by the file attribute for a
specific output record.
Synchronization means that output must be written to the physical file before the
program initiating the output can resume execution, thereby ensuring synchronization
between logical and physical files. Synchronization of all output records can be
designated with the SYNCHRONIZE file attribute. Synchronization is available for use by
tape files and disk files with sequential organization only, and is not available for use by
port files.
A periodic synchronous WRITE statement that follows one or more asynchronous WRITE
statements can be used as a checkpoint to ensure that all outstanding records are
written to the file before the program continues execution.
FROM identifier-1

If identifier-1 is a function-identifier, it must reference an alphanumeric function. If
identifier-1 is not a function-identifier, it cannot reference the same storage area as
record-name-1. Identifier-1 can reference a long numeric data item.
The result of the execution of the WRITE statement with the FROM phrase is the same
as the execution of the following statements:
MOVE identifier-1 TO record-name.
WRITE record-name.
The contents of the record area before the execution of the implicit MOVE statement do
not affect the execution of this WRITE statement. Refer to “MOVE Statement” in this
section for information on MOVE rules.
BEFORE ADVANCING
AFTER ADVANCING

Identifier-2 must refer to an integer data item. The value of identifier-2 can be zero.
Integer-1 can be positive or zero, but cannot be negative.
You cannot specify ADVANCING mnemonic-name when you write a record to a file that
is associated with a file description entry containing a LINAGE clause. The mnemonicname is defined in the SPECIAL-NAMES paragraph of the Environment Division.
The mnemonic-name must be associated with a CHANNEL number.
The phrases ADVANCING PAGE and END-OF-PAGE cannot both be specified in the
same WRITE statement.
Both the ADVANCING phrase and the END-OF-PAGE phrase allow control of the vertical
positioning of each line on a representation of a printed page.

8–86

8600 1518–307

WRITE Statement

If you do not use the ADVANCING phrase, automatic advancing occurs as if you had
specified AFTER ADVANCING 1 LINE. A WRITE BEFORE ADVANCING statement is
more efficient than a WRITE AFTER ADVANCING statement. Therefore, programs that
write printer files should specify a WRITE BEFORE ADVANCING statement rather than a
simple WRITE statement.
If you specify the ADVANCING phrase, advancing occurs as follows:
1. If you specify integer-1 or the value of identifier-2 is positive, the representation of
the printed page is advanced by that number of lines.
2. If you specify integer-1 or the value of identifier-2 is zero, repositioning of the
representation of the printed page does not occur.
3. If the value of identifier-2 is negative, the results are undefined.
4. If you specify mnemonic-name-1, the representation of the printed page is advanced
to the line number corresponding to the CHANNEL number.
5. If you specify the BEFORE phrase, the line is presented before the representation of
the printed page is advanced according to rules 1, 2, 3, and 4.
6. If you specify the AFTER phrase, the line is presented after the representation of the
printed page is advanced according to rules 1, 2, 3, and 4.
7. If you specify PAGE and the LINAGE clause is specified in the associated file
description entry, the record is presented on the logical page before or after
(depending on the phrase used) the device is repositioned to the next logical page.
The repositioning is to the first line that can be written on the next logical page, as
specified in the LINAGE clause.
8. If you specify PAGE and the LINAGE clause is not specified in the associated file
description entry, the record is presented on the logical page before or after
(depending on the phrase used) the device is repositioned to the next physical page.
The repositioning is to CHANNEL 1 or line 1 of the next logical page, when
appropriate for the hardware device.
If PAGE does not have meaning for a specific device, advancing occurs as if you had
specified BEFORE or AFTER ADVANCING 1 LINE.
END-OF-PAGE
EOP

The keywords END-OF-PAGE and EOP are synonymous and interchangeable.
Both the ADVANCING phrase and the END-OF-PAGE phrase allow control of the vertical
positioning of each line on a representation of a printed page.
The phrases END-OF-PAGE and ADVANCING PAGE cannot both be specified in the
same WRITE statement.
If you specify the END-OF-PAGE phrase, the LINAGE clause must be specified in the file
description entry for the associated file.

8600 1518–307

8–87

WRITE Statement

If the logical end of the representation of the printed page is reached during the
execution of a WRITE statement with the END-OF-PAGE phrase, imperative-statement-1
specified in the END-OF-PAGE phrase is executed. The logical end is specified in the
LINAGE clause associated with record-name-1.
An END-OF-PAGE condition occurs when the execution of a given WRITE statement
with the END-OF-PAGE phrase causes printing or spacing in the footing area of a page
body. This occurs when the execution of such a WRITE statement causes the LINAGECOUNTER to equal or exceed the value, if specified, in the FOOTING clause (that is, the
value specified by integer-2 or data-name-2 of the LINAGE clause). In this case, the
WRITE statement is executed, and the imperative statement in the END-OF-PAGE
phrase is then executed.
An automatic page overflow condition occurs when the execution of a given WRITE
statement (with or without an END-OF-PAGE phrase) cannot be fully accommodated
within the current page body. This occurs when a WRITE statement, if executed, would
cause the LINAGE-COUNTER to exceed the total number of lines specified for a page
(that is, the value specified by integer-1 or the data item referenced by data-name-1 of
the LINAGE clause). In this case, the record is presented on the logical page before or
after (depending on the phrase used) the device is repositioned to the first line that can
be written on the next logical page as specified in the LINAGE clause. The imperativestatement in the END-OF-PAGE clause, if specified, is executed after the record is
written and the device has been repositioned. If a FOOTING phrase is not specified in the
LINAGE clause, an END-OF-PAGE condition distinct from the page overflow condition is
not detected. In this case, the end-of-page condition and the page overflow condition
occur simultaneously.
If a FOOTING phrase is specified in the LINAGE clause but the execution of a given
WRITE statement would cause the LINAGE-COUNTER simultaneously to exceed the
total number of lines allowed on a page and in the footing area, the operation proceeds
as if you had not specified a footing area.
END-WRITE

This phrase delimits the scope of the WRITE statement.

Details
After the execution of the WRITE statement, the information in the area referenced by
identifier-1 is available, even though the information in the area referenced by recordname-1 is not available (except as specified by the SAME RECORD AREA clause).
The file position indicator is not affected by the execution of a WRITE statement.
The execution of the WRITE statement updates the value of the I-O status of the filename associated with record-name-1.
The maximum record size for a file is established at the time the file is created and must
not be changed later.

8–88

8600 1518–307

WRITE Statement

The number of character positions on a mass-storage device required to store a logical
record in a file may or may not be equal to the number of character positions defined by
the logical description of that record in the program.
The number of character positions in the record referenced by record-name-1 cannot be
larger than the largest or smaller than the smallest number of character positions allowed
by the RECORD IS VARYING clause associated with the file-name.
If the number of character positions exceeds these bounds, the following results occur:

•

The WRITE operation does not take place.

•

The content of the record area is unaffected.

•

The I-O status of the file associated with record-name-1 is set to a value that
indicates the cause of the condition.

The current record pointer is unaffected by the execution of a WRITE statement.
The successor relationship of a sequential file is established by the order of execution of
WRITE statements when the file is created. The relationship does not change except
when records are added to the end of the file.
When a sequential file is open in the extend mode, the execution of the WRITE
statement adds records to the end of the file as though the file were open in the output
mode. If there are records in the file, the first record written after the execution of the
OPEN statement with the EXTEND phrase is the successor of the last record in the file.
When you attempt to write beyond the externally defined boundaries of a sequential file,
an exception condition exists and the content of the record area is unaffected. The
following actions take place:

•

The value of the I-O status of the file-name associated with record-name-1 is set to a
value indicating a boundary violation.

•

If a USE AFTER STANDARD EXCEPTION declarative is explicitly or implicitly
specified for the file-name associated with record-name-1, that declarative procedure
is then executed.

•

If a USE AFTER STANDARD EXCEPTION declarative is not explicitly or implicitly
specified for the file-name associated with record-name-1, the result is undefined.

TADS
Any USE procedure is not executed when a WRITE statement that is compiled and
executed in a TADS session fails. If the end of the reel or unit is recognized and the
externally defined boundaries of the file have not been exceeded, the following
operations are executed:

•

The standard reel or unit label procedure

•

A reel or unit swap (the current volume pointer is updated to point to the next reel or
unit existing for the file)

•

The standard beginning reel or unit label procedure

8600 1518–307

8–89

WRITE Statement

The INVALID KEY condition exists when a maximum logical size has been specified for
the file and no more logical records can be written.
If the EXTERNAL-FORMAT FOR NATIONAL clause is specified in the file description
entry, the contents of elementary data items of class national are converted from internal
format to external format after the record leaves the record area and before the record is
written to the external medium. In determining the relevant data items, all REDEFINES
and RENAMES entries in the selected record description are ignored.
The record description that defines the national data items is selected as follows:

•

For a WRITE statement without the FILE phrase, the record description associated
with record-name-1 in the WRITE statement is used.

•

For a WRITE statement with the FILE phrase, the record description associated with
identifier-1 in the FROM phrase of the WRITE statement is used.

The size of the record area is adjusted to include the size of the storage area referenced
by identifier-1 in the FROM phrase plus the size of the control characters necessary to
convert from internal to external format.
Requirements for Shared Files
If the file to which you are attempting to write is a shared file, which means that it has
the phrase “VALUE OF BUFFERSHARING IS SHARED” in its File Description Entry (FD
entry), you must precede the WRITE statement with a LOCKRECORD statement. You
must follow the WRITE statement with an UNLOCKRECORD statement. If you do not
lock the record before attempting the WRITE operation,

•

The WRITE statement is not executed.

•

The I-O status code value 9E is returned.

•

The INVALID KEY action is executed.

If the value of BUFFERSHARING is altered in a CHANGE ATTRIBUTE statement or
through WFL, the WRITE code is not updated.
Example
WRITE Record-1 FROM Temp AFTER ADVANCING 2 END-WRITE
In this example, the record Record-1 is written to the file after advancing the
representation of the printed page two lines. The record Record-1 is contained in the
storage area called Temp. The END-WRITE phrase terminates the WRITE statement.

8–90

8600 1518–307

WRITE Statement

Format 2: WRITE (Files in Random Access Mode)
The format for the WRITE statement for relative and indexed files is as follows:
Ú
¿
³ WITH NO WAIT ³ ... [ FROM identifier-1 ]
³
ïï ïïïï ³
ïïïï
³ MOREDATA
³
³ ïïïïïïïï
³
³ SYNCHRONIZED ³
³ ïïïïïïïïïïïï ³
³ URGENT
³
À ïïïïïï
Ù
[ INVALID KEY imperative-statement-1 ]
ïïïïïïï
[ NOT INVALID KEY imperative-statement-2 ]
ïïï ïïïïïïï
[ END-WRITE ]
ïïïïïïïïï
WRITE record-name-1
ïïïïï

This format is supported in the TADS environment.

Explanation
record-name-1

If identifier-1 is a function-identifier, it must reference an alphanumeric function. If
identifier-1 is not a function-identifier, it cannot reference the same storage area as
record-name-1. Identifier-1 can reference a long numeric data item.
The result of the execution of the WRITE statement with the FROM phrase is the same
as the execution of the following statements:
MOVE identifier TO record-name.
WRITE record-name.
The contents of the record area before the execution of the implicit MOVE statement
have no effect on the execution of this WRITE statement. Refer to “MOVE Statement”
for information about the MOVE rules.

8600 1518–307

8–91

WRITE Statement

WITH NO WAIT

The WITH NO WAIT phrase can be specified only for port files. The WITH NO WAIT
phrase can be included only once.
A WRITE statement causes the program to wait until a buffer is available to store the
record. The possibility of this suspension is prevented for a port file by using the WITH
NO WAIT phrase. A status key value of 95 indicates that no buffer was available for the
logical record.
MOREDATA

This option enables an OSI port file that uses the segmented I/O capability to pass a
message segment with the indication that more data for the same message is
forthcoming.
SYNCHRONIZED

This option enables you to override the synchronization specified by the file attribute for a
specific output record.
Synchronization means that output must be written to the physical file before the
program starting the output can resume execution, thereby ensuring synchronization
between logical and physical files. Synchronization of all output records can be indicated
with the SYNCHRONIZE file attribute. Synchronization is available for use by tape and
disk files with sequential organization only, and is not available for use by port files.
A periodic synchronous WRITE statement that follows one or more asynchronous WRITE
statements can act as a checkpoint to ensure that all outstanding records are written to
the file before the program continues execution.
URGENT

The URGENT phrase is meaningful only when the Transmission Control Protocol/Internet
Protocol (TCP/IP) is being used. This phrase sets the urgent indicator associated with the
data. For information on TCP/IP, refer to the Distributed Systems Services (DSS)
Operations Guide.
INVALID KEY imperative-statement-1

The INVALID KEY phrase must be specified if an applicable USE AFTER STANDARD
EXCEPTION procedure for the file-name is not associated with the record-name.
For a sequential file, the INVALID KEY condition exists when the content of the ACTUAL
KEY data item is less than 1 or is greater than the ordinal number of the last record
written to the file. (The ACTUAL KEY data item is declared in the File Control Entry in the
Input-Output Section.)

8–92

8600 1518–307

WRITE Statement

For a relative file, the INVALID KEY condition exists under the following circumstances:

•

The access mode is random or dynamic, and the RELATIVE KEY data item specifies
a record that already exists in the file. (You declare the RELATIVE KEY data item with
the RELATIVE KEY clause in the File Control Entry of the Input-Output Section.) You
cannot specify a long numeric data item as the RELATIVE KEY.

•

An attempt is made to write beyond the externally defined boundaries of the file.

•

The number of significant digits in the relative record number is larger than the size
of the relative key data item described for the file.

For an indexed file, the INVALID KEY condition exists when

•

The file is opened in the sequential access mode, and the file is also opened in the
output or extend mode, and the value of the prime record key is not greater than the
value of the prime record key of the previous record.

•

The file is opened in the output or I-O mode, and the value of the prime record key is
equal to the value of the prime record key of a record already existing in the file.

•

The file is opened in the output, extend, or I-O mode, and the value of an alternate
record key (for which duplicates are not allowed) equals the corresponding data item
of a record already existing in the file.

•

An attempt is made to write beyond the externally defined boundaries of the file.

For both relative and indexed files, when the INVALID KEY condition exists:

•

The execution of the WRITE statement is unsuccessful.

•

The contents of the record area are unaffected.

•

The I-O STATUS of the file associated with record-name-1 is set to a value that
indicates an INVALID KEY condition.

Refer to Section 10 for details on file attributes, file organization, and access modes.
NOT INVALID KEY imperative-statement-2

Specify the INVALID KEY phrase if an applicable USE AFTER STANDARD EXCEPTION
PROCEDURE statement for the file-name is not associated with record-name-1.
If, during the execution of a WRITE statement with the NOT INVALID KEY phrase, the
invalid key condition does not occur, control passes to imperative-statement-2 as follows:

•

If the execution of the WRITE statement is successful, control passes after the
record is written and after the I-O status of the file-name associated with recordname-1 is updated.

•

If the execution of the WRITE statement is unsuccessful for a reason other than an
invalid key condition, control passes after updating the I-O status of the file-name
associated with record-name-1, and after executing the procedure, if any, specified
by a USE AFTER STANDARD EXCEPTION PROCEDURE statement applicable to the
file-name associated with record-name-1.

8600 1518–307

8–93

WRITE Statement

END-WRITE

This phrase delimits the scope of the WRITE statement.
Details
The file referenced by the file-name associated with record-name-1 must be in the output
or I-O mode at the time of execution of the WRITE statement. Refer to “OPEN
Statement” in this section for information on the OUTPUT, EXTEND, and I-O modes.
If the associated file is named in the SAME RECORD AREA clause, the logical record is
also available to the program as a record of other files referenced in that SAME RECORD
AREA clause as the associated output file, as well as to the file associated with recordname-1. Therefore, records in a sequential file opened in I-O mode cannot normally be
replaced by a WRITE statement during an update operation. For information on the
SAME RECORD AREA clause and the RECORD IS VARYING clause, refer to Section 4.
A READ-MODIFY-WRITE sequence accesses logical record n, modifies it, and writes it
into logical position n+1 in the file. The next READ accesses the logical record n+2, and
so on. In order to modify a record n in place in a sequential file, the sequence READMODIFY-REWRITE must be used.
After the execution of the WRITE statement, the information in the area referenced by
identifier-1 is available, even though the information in the area referenced by recordname-1 is not available (except as specified by the SAME RECORD AREA clause).
The file position indicator is not affected by the execution of a WRITE statement.
The execution of the WRITE statement updates the value of the I-O status of the filename associated with record-name-1.
The maximum record size for a file is established at the time the file is created and must
not be changed later.
The number of character positions on a mass-storage device required to store a logical
record in a file may or may not be equal to the number of character positions defined by
the logical description of that record in the program.
The number of character positions in the record referenced by the record-name cannot
be larger than the largest or smaller than the smallest number of character positions
allowed by the RECORD IS VARYING clause associated with the file-name. If the number
of character positions exceeds these bounds:

•

The WRITE operation does not take place.

•

The content of the record area is unaffected.

•

The I-O status of the file associated with the record-name is set to a value that
indicates the cause of the condition.

The current record pointer is unaffected by the execution of a WRITE statement.

8–94

8600 1518–307

WRITE Statement

TADS
Any USE procedure is not executed when a WRITE statement that is compiled and
executed in a TADS session fails.
Port Files
Format 2 must be used for port files.
If an ACTUAL KEY is declared for a port file, your program is responsible for updating the
ACTUAL KEY with an appropriate value. A WRITE statement causes the ACTUAL KEY to
be passed to the I/O system to indicate the desired subfile destination. If the ACTUAL
KEY is 0, a broadcast write is performed, for which the data is sent to all opened subfiles
of the port file.
If no ACTUAL KEY is declared for the file, it must contain a single subfile that is written.
Relative Files
The following rules apply specifically to relative files:

•

The RELATIVE KEY phrase cannot reference a long numeric data item.

•

When a file is opened in the output mode, records can be placed into the file by one
of the following methods:

−

If the access mode is sequential, the WRITE statement releases a record to the
mass-storage control system. The first record has a relative record number of 1,
and subsequent records released have relative record numbers of 2, 3, 4, and so
forth. If the RELATIVE KEY data item has been specified in the file control entry
for the associated file, the relative record number of the record just released is
placed into the RELATIVE KEY data item during the execution of the WRITE
statement.

−

If the access mode is random or dynamic, before the execution of the WRITE
statement, the value of the RELATIVE KEY data item must be initialized in the
program with the relative record number to be associated with the record in the
record area. That record is then released to the mass-storage system.

•

When a file is opened in the I-O mode and the access mode is random or dynamic,
records are inserted into the associated file. The value of the RELATIVE KEY data
item must be initialized by the program with the relative record number associated
with the record in the record area. Execution of a WRITE statement then releases
the contents of the record area to the mass-storage system.

•

When a file is opened in the extend mode, records are inserted into the file. The first
record released to the mass-storage control system has a relative record number of
1 greater than the highest relative record number existing in the file. Subsequent
records released to the mass-storage control system have consecutively higher
relative record numbers. If the RELATIVE KEY phrase is specified for the file-name
associated with record-name-1, the relative record number of the record being
released is moved into the RELATIVE KEY data item by the mass-storage control
system during execution of the WRITE statement according to the rules for the
MOVE statement.

8600 1518–307

8–95

WRITE Statement

Indexed Files
The following rules apply specifically to indexed files:

•

Execution of the WRITE statement releases the contents of the record area. The
mass-storage control system utilizes the contents of the record keys in such a way
that subsequent access of the record may be made based upon any of those
specified record keys.

•

The value of the prime record key must be unique in the records in the file.

•

The data item specified as the prime record key must be set by the program to the
desired value before execution of the WRITE statement.

•

If you specify the sequential access mode for the file, records must be released to
the mass-storage control system in ascending order of prime record key values
according to the collating sequence of the file.

•

If you specify the extend mode for the file, the first record released to the massstorage control system must have a prime record key whose value is greater than
the highest prime record key value existing in the file.

•

If you specify the random or dynamic access mode, records can be written in any
program-specified order.

•

When the ALTERNATE RECORD KEY clause is specified in the SELECT clause of the
FILE-CONTROL paragraph for an indexed file, the value of the alternate record key
can be nonunique only if the DUPLICATES phrase is specified for that data item. In
this case, records are stored so that when records are accessed sequentially, the
order of retrieval of those records is the order in which they are released to the
mass-storage control system.

•

The ALTERNATE RECORD KEY clause cannot reference a long numeric data item.

Requirements for Shared Files
If the file to which you are attempting to write is a shared file, which means that it has
the phrase “VALUE OF BUFFERSHARING IS SHARED” in its File Description Entry (FD
entry), you must precede the WRITE statement with a LOCKRECORD statement. You
must follow the WRITE statement with an UNLOCKRECORD statement. If you do not
lock the record before attempting the WRITE operation,

•

The WRITE statement is not executed.

•

The I-O status code value 9E is returned.

•

The INVALID KEY action is executed.

If the value of BUFFERSHARING is altered in a CHANGE ATTRIBUTE statement or
through WFL, the WRITE code is not updated.

8–96

8600 1518–307

WRITE Statement

Example
WRITE Record-1 FROM Temp INVALID KEY Imp-state END-WRITE
In this example, Record-1 is a relative or indexed file contained in the storage area Temp.
The imperative statement Imp-state is invoked if the INVALID KEY condition exists,
which is dependent on the file organization and the file access mode. The END-WRITE
phrase terminates the WRITE statement.

8600 1518–307

8–97

WRITE Statement

8–98

8600 1518–307

Section 9
Intrinsic Functions
A function represents a temporary data item whose value is derived automatically when
an object program makes a reference to it. This section describes the functions defined
by COBOL85 that you can use throughout the Procedure Division of a COBOL program.

Summary of Functions
The COBOL85 intrinsic functions are summarized in Table 9-1. Note that the Arguments
column indicates the type of argument used with a function and the number of
arguments available for that function. The types of arguments are abbreviated as follows:

Abbreviation

8600 1518–307

Argument Type

Alphabetic

Integer

Numeric

National

Alphanumeric

9–1

Summary of Functions

Table 9–1. Intrinsic Functions

Function
Type

Arguments
(Type and
Number)

ABS

Numeric

Absolute value of N1

ACOS

Numeric

Arccosine of N1

ANNUITY

Numeric

N1, I2

Ratio of annuity paid for 12
periods at interest of N1 to initial
investment of 1

ASIN

Numeric

Arcsine of N1

ATAN

Numeric

Arctangent of N1

CHAR

Alphanumeric

Character in position I1 of
program collating sequence

CHAR-NATIONAL

National

Character in position I1 of the
national character collating
sequence

CONVERT-TO-DISPLAY

Alphanumeric

G1, A2 or X2

Argument converted to DISPLAY
usage

CONVERT-TONATIONAL

National

A1 or X1, G2

Argument converted to
NATIONAL usage

COS

Numeric

Cosine of N1

CURRENT-DATE

Alphanumeric

None

Current date and time and
difference from Greenwich
Mean Time

DATE-OF-INTEGER

Integer

Standard date equivalent
(YYYYMMDD) of integer date

DAY-OF-INTEGER

Integer

Julian date equivalent
(YYYYDDD) of integer date

DIV

Integer

N1,N2

Integer part of quotient of
(N1/N2)

EXP

Numeric

Exponential function of N1

FACTORIAL

Numeric

Factorial of I1

FIRSTONE

Integer

Bit number, plus 1, of the
leftmost nonzero bits in N1.

FORMATTED-SIZE

Integer

G1 or X1

Formatted size of argument

FUNCTION
LINENUMBER

Integer

None

Line number of the source
record

INTEGER

Integer

The greatest integer not greater
than N1

Function Name

9–2

Value Returned

8600 1518–307

Summary of Functions

Table 9–1. Intrinsic Functions

Function
Type

Arguments
(Type and
Number)

INTEGER-OF-DATE

Integer

Integer date equivalent of
standard date (YYYYMMDD)

INTEGER-OF-DAY

Integer

Integer date equivalent of Julian
date (YYYYDDD)

INTEGER-PART

Integer

Integer part of N1

LENGTH

Integer

A1, N1, X1,
or G1

Integer length of argument

LENGTH-AN

Integer

A1, N1, X1,
or G1

Length of argument in bytes

LOG

Numeric

Natural logarithm of N1

LOG10

Numeric

Logarithm to base 10 of N1

LOWER-CASE

Alphanumeric
or national

A1, X1, or G1

All letters in the argument are
set to lowercase

MAX

(Depends
upon
arguments)

A1..., I1...,
N1..., X1...,
or G1...

Value of maximum argument

MEAN

Numeric

N1...

Arithmetic mean of arguments

MEDIAN

Numeric

N1...

Median of arguments

MIDRANGE

Numeric

N1...

Mean of minimum and
maximum arguments

MIN

(Depends
upon
arguments)

A1..., I1...,
N1..., X1...,
G1...

Value of minimum argument

MOD

Numeric

I1, I2

I1 modulo I2

NUMVAL

Numeric

Numeric value of simple numeric
string

NUMVAL-C

Numeric

X1, X2

Numeric value of simple numeric
string

ONES

Integer

Number of nonzero bits in N1

ORD

Integer

A1, X1, G1

Ordinal position of the argument
in collating sequence

ORD-MAX

Integer

A1..., N1...,
X1..., or G1...

Ordinal position of maximum
argument

ORD-MIN

Integer

A1..., N1...,
X1..., G1...

Ordinal position of minimum
argument

Function Name

8600 1518–307

Value Returned

9–3

Summary of Functions

Table 9–1. Intrinsic Functions

Function
Type

Arguments
(Type and
Number)

PRESENT-VALUE

Numeric

N1, N2...

Present value of a series of
future period-end amounts, N2,
at a discount rate of N1

RANDOM

Numeric

Random number

RANGE

Numeric

I1... or N1...

Value of maximum argument
minus value of minimum
argument

REM

Numeric

N1, N2

Remainder of (N1/N2)

REVERSE

Alphanumeric
or national

A1, X1, G1

Reverse order of the characters
of the argument

SIGN

Integer

Either +1, -1, or 0, depending on
whether N1 is greater than, less
than, or equal to zero,
respectively

SIN

Numeric

Sine of N1

SQRT

Numeric

Square root of N1

STANDARD-DEVIATION

Numeric

N1...

Standard deviation of arguments

SUM

Numeric

I1... or N1...

Sum or arguments

TAN

Numeric

Tangent or N1

UPPER-CASE

Alphanumeric
or national

A1, X1, G1

All letters in the argument are
set to uppercase

VARIANCE

Numeric

N1...

Variance or argument

WHEN-COMPILED

Alphanumeric

None

Date and time program was
compiled

Function Name

9–4

Value Returned

8600 1518–307

Types of Functions

Types of Functions
Functions can be classified according to the types of values they return, as described in Table 9-2.

Table 9–2. Types of Functions

Function
Type

Class

Category

Comments

Alphanumeric

Alphanumeric functions have
an implicit usage of DISPLAY.

Numeric

Numeric functions are always
assumed to have an
operational sign, and yield
double-precision results.

Integer

Numeric

Integer functions are always
assumed to have an
operational sign.

National

National functions have an
implicit usage of NATIONAL.

8600 1518–307

9–5

Rules for Using Functions

Rules for Using Functions
You can use functions throughout the Procedure Division as appropriate replacements
for identifiers, arithmetic expressions, and integer operands.
For . . .

Use . . .

Identifiers

Alphanumeric functions

Arithmetic expressions

Numeric or integer functions

Integer operands (signed)

Integer functions

Observe the following restrictions when you use functions:

9–6

•

Functions cannot be receiving operands of any statement.

•

A numeric function cannot be referenced where an integer operand is required, even
if the function yields an integer value.

•

Numeric and integer functions can be used only in arithmetic expressions.

•

Numeric functions yield double-precision results. If a result represents a value that
the machine must approximate, and it is assigned to a DISPLAY, COMP, or BINARY
data item, then precision can be lost. For more information, refer to USAGE IS
DOUBLE of Data Description Entry Format 1 in Section 4.

•

Alphanumeric functions cannot be used as identifiers in general formats where the
characteristics resulting from the evaluation of the function would not meet the
format's requirements for the characteristics of data items (such as class and
category, size, usage, and permissible values).

•

Functions used in class conditions must be alphanumeric.

•

Functions used in the FROM phrase of a RELEASE, REWRITE, or WRITE statement
must be alphanumeric.

•

Functions cannot appear as parameters in a CALL statement.

8600 1518–307

Syntax for a Function

Syntax for a Function
The syntax for a function consists of an identifier that includes the word FUNCTION, the
name of a specific predefined function, and one or more arguments:

FUNCTION function-name-1 [ ( {argument-1} . . .
ïïïïïïïï

) ] [reference-modifier]

Explanation
FUNCTION

This COBOL reserved word identifies the syntax as a function.
function-name-1

This indicates the name of the function. Although function names are defined by the
system, function names are not reserved words. Thus, a function name can also appear
in a program as a user-defined word or a system-name. The functions are listed in Table
9-1.
argument-1

This is a value to be used by the function. It can be either an identifier, a literal, or an
arithmetic expression, depending on the type of function. You must separate multiple
arguments with a comma (,) or a space. For more on arguments, see “Arguments” later
in this section.
reference-modifier

You can use a reference-modifier only with an alphanumeric function. The format for the
reference modifier is

(leftmost-character-position : [length] )

For details about reference modifiers, refer to Section 4.

8600 1518–307

9–7

Arguments

Arguments
Arguments specify values used in the evaluation of a function. Arguments can be
identifiers, literals, or arithmetic expressions. Some functions do not have arguments,
while other functions have one or more. Specific rules governing the number of
arguments that can be used with a function, as well as the class and category of the
arguments, are provided with the description of each function later in this section. Note
that you must separate multiple arguments with a comma (,) or a space.
A function might restrict the values that can be used for its arguments in order to permit
meaningful determination of the value of the function. If a value specified for a particular
argument is outside of the permissible range as defined by the function, the returned
value for the function is undefined.

Types of Arguments
The types of arguments are described in Table 9-3.
Table 9–3. Types of Arguments for Functions

Argument Type

9–8

Description

Numeric

You must specify arithmetic expressions for numeric arguments.
The value of the arithmetic expression, including the operational
sign, is used to determine the value of the function.

Alphabetic

You must specify an identifier that represents an elementary data
item of the class alphabetic or a nonnumeric literal that contains
only alphabetic characters for an alphabetic argument. The size of
the argument determines the size of the result. For example, if a
three character argument is used, as in FUNCTION REVERSE
(”ABC”), a three-character result is produced, in this case (”CBA”).

Alphanumeric

You must specify an identifier that represents an elementary data
item of the class alphabetic or alphanumeric, or a nonnumeric
literal. The size of the argument determines the size of the result.
For example, if a three character argument is used, as in FUNCTION
REVERSE (”ABC”), a three-character result is produced, in this case
(”CBA”).

Integer

You must specify an arithmetic expression that will always result in
an integer value for an integer argument. The value of the
arithmetic expression, including the operational sign, is used to
determine the value of the function.

National

You must specify an identifier that represents a data item of the
class national or a national-character literal for this type of
argument. The size of the argument determines the size of the
result. For example, if a three character argument is used, as in
FUNCTION REVERSE (N”ABC”), a three-character result is
produced, in this case (N”CBA”).

8600 1518–307

Arguments

Evaluation of Arguments
When a function has multiple arguments, the arguments are evaluated individually from
left to right in the order specified. An argument can be a function-identifier itself or an
expression containing function-identifiers. The function-identifier for which the argument
is specified can also be referenced in the argument, as shown in the following example:
FUNCTION REVERSE (FUNCTION REVERSE ("ABC"))
The result from this syntax is “ABC.”

Subscripting an Argument
Certain functions enable you to repeat an argument numerous times. Instead of
repeating the argument, you can reference a table by following the argument with the
subscript ALL. When the ALL subscript is specified, the effect is as if each table element
associated with that subscript position were specified.
For example, consider the following three-dimensional table.
01 Table-1.
02 Office OCCURS 2 TIMES.
03 Department OCCURS 05 TIMES.
04 Employee OCCURS 15 TIMES.
05 Name . . .
05 Address . . .
The first dimension of this table defines 2 offices.
The second dimension defines 5 departments for each office.
The third dimension defines 15 employees for each department.
The reference Employee(1,1,ALL) specifies all the employees in the first office and the
first department. The ALL subscript is incremented by 1 until the total number of
employees specified in the OCCURS clause is reached:
Employee(1,1,1)
Employee(1,1,2)
Employee(1,1,3)
.
.
.
Employee(1,1,15)

8600 1518–307

9–9

Arguments

The reference Employee(ALL,5,ALL) specifies all offices, department 5 of each office,
and all employees in department 5 of each office. The first ALL subscript begins with 1
and remains at 1 until the second ALL subscript has been incremented by 1 through its
range of values as specified in the OCCURS clause, which is 15 in the following example:
Employee(1,5,1)
Employee(1,5,2)
Employee(1,5,3)
.
.
.
Employee(1,5,15)
Employee(2,5,1)
Employee(2,5,2)
Employee(2,5,3)
.
.
.
Employee(2,5,15)
The reference Employee(ALL,ALL,ALL) specifies all offices, all departments in each
office, and all employees in every department of each office. The first and second ALL
subscripts begin with 1 and remain at 1 until the rightmost ALL subscript is incremented
by 1 through its range of values:
Employee(1,1,1)
Employee(1,1,2)
Employee(1,1,3)
.
.
.
Employee(1,1,15)
Then the rightmost ALL subscript is reset to 1, and the ALL subscript to the left of the
rightmost ALL subscript is incremented by 1 through its range of values. For each
increment of 1, the subscripts to the right increment through their range of values:
Employee(1,2,1)
Employee(1,2,2)
Employee(1,2,3)
.
.
.
Employee(1,2,15)
Employee(1,3,1)
Employee(1,3,2)
.
.
.

9–10

8600 1518–307

Arguments

The preceding process continues until all the subscripts are incremented through their
range of values. Then the first ALL subscript is incremented to 2 and the process begins
again. The process continues until the first ALL subscript has been repeated the number
of times specified by the OCCURS clause, which is 2 in this example.

8600 1518–307

9–11

ABS Function

ABS Function
The ABS function returns a value that is the absolute value of argument-1. The type of
this function is numeric.

Syntax
FUNCTION ABS (argument-1)
ïïïïïïïï ïïï

Explanation
Argument-1 must be of the numeric class. The returned value is the absolute value of
argument-1.

Example
Function with Argument

FUNCTION ABS (-6)

9–12

Result

8600 1518–307

ACOS Function

ACOS Function
The ACOS function returns a numeric value in radians that approximates the arccosine of
argument-1. The type of this function is numeric. This function is fully supported in the
COBOL85 TADS environment.

Syntax
FUNCTION ACOS (argument-1)
ïïïïïïïï ïïïï

Explanation
Argument-1 must be of the numeric class. The value of argument-1 must be greater than
or equal to -1 and less than or equal to +1. The returned value is the approximation of
the arccosine of argument-1 and is greater than or equal to zero and less than or equal to
pi.

Example
Function with Argument

FUNCTION ACOS (.5)

8600 1518–307

Result

1.047

9–13

ANNUITY Function

ANNUITY Function
The ANNUITY function (annuity immediate) returns a numeric value that approximates
the ratio of an annuity paid at the end of each period for the number of periods specified
by argument-2 to an initial investment of one. Interest is earned at the rate specified by
argument-1 and is applied at the end of the period, before the payment. The type of this
function is numeric.

Syntax
FUNCTION ANNUITY (argument-1, argument-2)
ïïïïïïïï ïïïïïïï

Explanation
Argument-1 must be of the numeric class and must have a value that is greater than or
equal to zero.

•

When the value of argument-1 is zero, the value of the function is the approximation
of 1 divided by argument-2.

•

When the value of argument-1 is not zero, the value of the function is the
approximation of the following computation:
argument-1 / (1 - (1 + argument-1) ** (-argument-2))

Argument-2 must be a positive integer.
You must separate argument-1 and argument-2 with a comma (,) or a space.
Note that an invalid argument results in a run-time error.

Example
Function with Arguments

FUNCTION ANNUITY (.1,12)

9–14

Result

.1467

8600 1518–307

ASIN Function

ASIN Function
The ASIN function returns a numeric value in radians that approximates the arcsine of
argument-1. The type of this function is numeric. This function is fully supported in the
COBOL85 TADS environment.

Syntax
FUNCTION ASIN (argument-1)
ïïïïïïïï ïïïï

Explanation
Argument-1 must be of the numeric class. The value of argument-1 must be greater than
or equal to -1 and less than or equal to +1.
An invalid argument results in a run-time error.
The returned value is the approximation of the arcsine of argument-1 and is greater than
or equal to -pi/2 and less than or equal to +pi/2.

Example
Function with Argument

FUNCTION ASIN (.5)

8600 1518–307

Result

.524

9–15

ATAN Function

ATAN Function
The ATAN function returns a numeric value in radians that approximates the arctangent
of argument-1. The type of this function is numeric. This function is fully supported in the
COBOL85 TADS environment.

Syntax
FUNCTION ATAN (argument-1)
ïïïïïïïï ïïïï

Explanation
Argument-1 must be of the numeric class. The returned value is the approximation of the
arctangent of argument-1 and is greater than -pi/2 and less than +pi/2.

Example
Function with Argument

FUNCTION ATAN (1.732)

9–16

Result

1.047

8600 1518–307

CHAR Function

CHAR Function
The CHAR function returns a one-character alphanumeric value that is the character in
the program collating sequence that has the ordinal position equal to the value of
argument-1. The type of this function is alphanumeric.

Syntax
FUNCTION CHAR (argument-1)
ïïïïïïïï ïïïï

Explanation
Argument-1 must be an integer. The value of argument-1 must be greater than zero and
less than or equal to the number of positions in the collating sequence. If more than one
character has the same position in the program collating sequence, the character
returned as the function value is that of the first literal specified for that character
position in the ALPHABET clause.
If the current program collating sequence was not specified by an ALPHABET clause,
then the default collating sequence is used.
An invalid argument results in a run-time error.

Example
Function with Argument

FUNCTION CHAR (91)

8600 1518–307

Result

]

9–17

CHAR-NATIONAL Function

CHAR-NATIONAL Function
The CHAR-NATIONAL (8-bit national character) function returns a one-character value
that is a character in the national program collating sequence with the ordinal position
equal to the value of argument-1. The type of this function is national.

Syntax
FUNCTION CHAR-NATIONAL (argument-1)
ïïïïïïïï ïïïïïïïïïïïïï

Explanation
Argument-1 must be an integer. The value of argument-1 must be greater than zero and
less than or equal to the number of positions in the national program collating sequence.
If more than one character has the same position in the national program collating
sequence, the character returned as the function value is that of the first literal specified
for that character position in the ALPHABET clause.
If the national program collating sequence was not specified in an ALPHABET clause, a
compile-time error is issued for the use of this function.
An invalid argument results in a run-time error.

Example
Consider the following ENVIRONMENT DIVISION.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
OBJECT-COMPUTER.
PROGRAM COLLATING SEQUENCE FOR NATIONAL IS FOREIGN.
SPECIAL-NAMES.
ALPHABET FOREIGN FOR NATIONAL IS CCSVERSION "FRANCE".

Function with Argument

FUNCTION CHAR-NATIONAL (20)

9–18

Result

N"A"

8600 1518–307

CONVERT-TO-DISPLAY Function

CONVERT-TO-DISPLAY Function
The CONVERT-TO-DISPLAY function returns a character string that contains the national
characters of the argument converted to the corresponding alphanumeric character
representation. The type of this function is alphanumeric.

Syntax
FUNCTION CONVERT-TO-DISPLAY ( argument-1 [,argument-2] )
ïïïïïïïï ïïïïïïïïïïïïïïïïïï

Explanation
Argument-1 must be of the national class and must be at least one character in length.
Argument-2 must be of either the alphabetic or the alphanumeric class and must be one
character in length. Argument-2 specifies a substitute alphanumeric character for use in
the conversion of any national character for which no corresponding alphanumeric
character exists.
You must separate argument-1 and argument-2 with a comma (,) or a space.
The returned value is a character string with each national character of argument-1
converted to the corresponding alphanumeric standard data format representation.

Example
Function with Argument

FUNCTION CONVERT-TO-DISPLAY
(N"ABC","?")

Result

ABC

In this example, N"ABC" is a national-character literal.

8600 1518–307

9–19

CONVERT-TO-NATIONAL Function

CONVERT-TO-NATIONAL Function
The CONVERT-TO-NATIONAL function returns a national-character string that contains
the characters of the argument converted to the corresponding national-character
representation. The type of this function is national.

Syntax
FUNCTION CONVERT-TO-NATIONAL ( argument-1 [,argument-2] )
ïïïïïïïï ïïïïïïïïïïïïïïïïïïï

Explanation
Argument-1 must be of the alphabetic or alphanumeric class and must be at least one
character in length.
Argument-2 must be of the national category and must be one character in length.
Argument-2 specifies a substitute national character for use in the conversion of any
alphanumeric character for which no corresponding national character exists.
You must separate argument-1 and argument-2 with a comma (,) or a space.
The returned value is a national-character string with each character of argument-1
converted to the corresponding national-character representation.

Example
Function with Argument

FUNCTION CONVERT-TO-NATIONAL
("ABC",N"?")

Result

ABC

In this example, N"?" is a national-character literal, and the result, ABC, is a nationalcharacter value.

9–20

8600 1518–307

COS Function

COS Function
The COS function returns a numeric value that approximates the cosine of an angle or
arc, expressed in radians, that is specified by argument-1. The type of this function is
numeric. This function is fully supported in the COBOL85 TADS environment.

Syntax
The syntax of this function is as follows:

FUNCTION COS (argument-1)
ïïïïïïïï ïïï

Explanation
Argument-1 must be of the numeric class. The returned value is the approximation of the
cosine of argument-1 and is greater than or equal to -1 and less than or equal to +1.

Example
Function with Argument

FUNCTION COS (.524)

8600 1518–307

Result

.866

9–21

CURRENT-DATE Function

CURRENT-DATE Function
The CURRENT-DATE function returns a 21-character alphanumeric value that represents
the calendar date, time of day, and local time differential factor provided by the system
on which the function is evaluated. The type of this function is alphanumeric.

Syntax
FUNCTION CURRENT-DATE
ïïïïïïïï ïïïïïïïïïïïï

Explanation
The character positions returned, numbered from left to right, are as follows:
Table 9–4. CURRENT-DATE Function, Characters 1–21

Character
Position

Contents

1-4

Four numeric digits of the year in the Gregorian calendar.

5-6

Two numeric digits of the month of the year, in the range 01 through 12.

7-8

Two numeric digits of the day of the month, in the range 01 through 31.

9-10

Two numeric digits of the hours past midnight, in the range 00 through 23.

11-12

Two numeric digits of the minutes past the hour, in the range 00 through
59.

13-14

Two numeric digits of the seconds past the minute, in the range 00
through 59.

15-16

Two numeric digits of the hundredths of a second past the second, in the
range 00 through 99.

One of the following characters:
Minus sign (-), which means the local time indicated in the previous
character positions is behind Greenwich Mean Time.
Plus sign (+), which means the local time indicated is the same as or
ahead of the Greenwich Mean Time.
Zero (0), which means the system on which this function is evaluated does
not provide the differential factor. Only the values + and - are returned.

9–22

18-19

The returned value in character positions 18 and 19 depends upon the
character in position 17 as shown in Table Section 9-5.

20-21

The returned value in character positions 20 and 21 depends upon the
character in position 17 as shown in Table Section 9-6.

8600 1518–307

CURRENT-DATE Function

Table 9–5. CURRENT-DATE Function, Characters 18–19

If the 17th character is a . . .

Then the returned value is . . .

Minus sign (-)

Two numeric digits in the range 00 through 12
indicating the number of hours that the reported
time is behind Greenwich Mean Time.

Plus sign (+)

Two numeric digits in the range 00 through 13
indicating the number of hours that the reported
time is ahead of Greenwich Mean Time.

Zero (0)

Table 9–6. CURRENT-DATE Function, Characters 20–21

If the 17th character is a . . .

Then the returned value is . . .

Minus sign (-)

Two numeric digits in the range 00 through 59
indicating the number of minutes that the reported
time is behind Greenwich Mean Time.

Plus sign (+)

Two numeric digits in the range 00 through 59
indicating the number of minutes that the reported
time is ahead of Greenwich Mean Time.

Zero (0)

Example
Function

FUNCTION CURRENT-DATE

8600 1518–307

Result

1993062813195795-0700

9–23

DATE-OF-INTEGER Function

DATE-OF-INTEGER Function
The DATE-OF-INTEGER function converts a date in the Gregorian calendar from integer
date form to standard date form (YYYYMMDD). The type of this function is integer.

Syntax
FUNCTION DATE-OF-INTEGER
ïïïïïïïï ïïïïïïïïïïïïïïï

(argument-1)

Explanation
Argument-1 is a positive integer that represents a number of days succeeding December
31, 1600, on the Gregorian calendar. An invalid argument will return a value of 0 (zero).
The returned value represents the ISO standard date equivalent of the integer specified
in argument-1 in the form (YYYYMMDD) where,
YYYY

Represents a year in the Gregorian calendar

Represents the month of that year

Represents the day of that month

Example
Function with Argument

FUNCTION DATE-OF-INTEGER (1096)

9–24

Result

16040101

8600 1518–307

DAY-OF-INTEGER Function

DAY-OF-INTEGER Function
The DAY-OF-INTEGER function converts a date in the Gregorian calendar from integer
date form to Julian date form (YYYYDDD). The type of this function is integer.

Syntax
FUNCTION DAY-OF-INTEGER (argument-1)
ïïïïïïïï ïïïïïïïïïïïïïï

Explanation
Argument-1 is a positive integer that represents a number of days succeeding December
31, 1600, in the Gregorian calendar. An invalid argument will return a value of 0 (zero).
The returned value represents the Julian equivalent of the integer specified in argument1. The returned value is an integer of the form (YYYYDDD) where YYYY represents a
year in the Gregorian calendar and DDD represents the day of that year.

Example
Function with Argument

FUNCTION DAY-OF-INTEGER (1096)

8600 1518–307

Result

1604001

9–25

DIV Function

DIV Function
The DIV function returns an integer equal to the integer part of the quotient after division.
The type of this function is integer.

Syntax
FUNCTION DIV (argument-1, argument-2)
ïïïïïïïï ïïï

Explanation
Argument-1 represents the dividend, and argument-2 represents the divisor. You must
separate each argument with a comma (,) or a space.
The result of argument-2 must not be zero.

Example
Function with Arguments

FUNCTION DIV (10,3)

9–26

Result

8600 1518–307

EXP Function

EXP Function
The EXP function returns a value that is the base of the natural system of logarithms
raised to the power of argument-1. The type of this function is numeric. This function is
fully supported in the COBOL85 TADS environment.

Syntax
FUNCTION EXP (argument-1)
ïïïïïïïï ïïï

Explanation
Argument-1 must be of the numeric class. The returned value is equal to the base of the
natural system of logarithms, which has an approximate numerical value of 2.7183,
raised to the power of argument-1.

Example
Function with Arguments

FUNCTION EXP (2)

8600 1518–307

Result

7.389056

9–27

FACTORIAL Function

FACTORIAL Function
The FACTORIAL function returns an integer that is the factorial of argument-1. The type
of this function is numeric.

Syntax
The syntax of this function is as follows:

FUNCTION FACTORIAL (argument-1)
ïïïïïïïï ïïïïïïïïï

Explanation
Argument-1 must be an integer greater than or equal to zero.

•

If argument-1 is zero, the value 1 is returned.

•

If argument-1 is positive, its factorial is returned.

An invalid argument results in a run-time error.

Example
Function with Argument

FUNCTION FACTORIAL (10)

9–28

Result

3628800

8600 1518–307

FIRSTONE Function

FIRSTONE Function
The FIRSTONE function returns a value that is the bit number, plus 1, of the leftmost
non- zero bits in argument-1. The type of this function is integer. This function is fully
supported in the COBOL85 TADS environment.

Syntax
FUNCTION FIRSTONE (argument-1)
ïïïïïïïï ïïïïïïïï

Explanation
Argument-1 must be of the numeric class. If argument-1 is a double-precision number,
only the first word is evaluated by the function. If argument-1 is 0 (zero), the FIRSTONE
function returns a value of 0 (zero). The returned value is the bit number, plus one, of the
leftmost non-zero bit in argument-1.

Example
Function with Argument

Result

FUNCTION FIRSTONE (0)

FUNCTION FIRSTONE (3)

8600 1518–307

9–29

FORMATTED-SIZE Function

FORMATTED-SIZE Function
The FORMATTED-SIZE function returns as a value the formatted size of a data name.
The type of this function is integer.
The returned value is equal to the result of the following calculation:
Length of data name in bytes + (number of National data items subordinate to
the data name * 2)

Syntax
FUNCTION FORMATTED-SIZE (argument-1)
ïïïïïïïï ïïïïïïïïïïïïïï

Explanation
Argument-1 must be either a group item or any category of elementary item described
implicitly or explicitly as USAGE IS DISPLAY or USAGE IS NATIONAL. Argument-1
cannot be a RENAMES entry. In addition, argument-1 must be qualified; it cannot be
subscripted or indexed.

Example
Consider the following portion of code:
01

D-GROUP.
02 X-ITEM
02 N-ITEM

PIC 9(5).
PIC N(5).

The formatted size of D-GROUP would be derived as follows:

Function with Argument

FUNCTION FORMATTED-SIZE (D-GROUP)

9–30

Result

8600 1518–307

INTEGER Function

INTEGER Function
The INTEGER function returns the greatest integer value that is less than or equal to the
argument. The type of this function is integer. This function is fully supported in the
COBOL85 TADS environment.

Syntax
FUNCTION INTEGER (argument-1)
ïïïïïïïï ïïïïïïï

Explanation
Argument-1 must be of the numeric class. The returned value is the greatest integer less
than or equal to the value of argument-1. For example, if the value of argument-1 is -1.5,
then -2 is returned. If the value of argument-1 is +1.5, then +1 is returned.

Example
Function with Argument

FUNCTION INTEGER (-2.1)

8600 1518–307

Result

-3

9–31

INTEGER-OF-DATE Function

INTEGER-OF-DATE Function
The INTEGER-OF-DATE function converts a date in the Gregorian calendar from standard
date form (YYYYMMDD) to integer date form. The type of this function is integer.

Syntax
FUNCTION INTEGER-OF-DATE (argument-1)
ïïïïïïïï ïïïïïïïïïïïïïïï

Explanation
Argument-1 must be an integer in the form YYYYMMDD, whose value is obtained from
the calculation (YYYY * 10000) + (MM * 100) + DD.

In the representation
YYYYMMDD, . . .

Represents . . .

YYYY

The year in the Gregorian calendar. It must be an integer
greater than 1600.

A month. It must be a positive integer less than 13,
provided that it is valid for the specified month and year
combination.

A day. It must be a positive integer less than 32, provided
that it is valid for the specified month and year combination.

An invalid argument will return a value of 0 (zero).
The returned value is an integer that is the number of days the date represented by
argument-1 succeeds December 31, 1600, in the Gregorian calendar.

Example
Function with Argument

FUNCTION INTEGER-OF-DATE (16040101)

9–32

Result

1096

8600 1518–307

INTEGER-OF-DAY Function

INTEGER-OF-DAY Function
The INTEGER-OF-DAY function converts a date in the Gregorian calendar from Julian
date form (YYYYDDD) to integer date form. This type of function is integer.

FUNCTION INTEGER-OF-DAY (argument-1)
ïïïïïïïï ïïïïïïïïïïïïïï

Explanation
Argument-1 must be an integer in the form YYYYDDD, whose value is obtained from the
calculation (YYYY * 1000) + DDD.

In the representation
YYYYDDD, . . .

Represents . . .

YYYY

The year in the Gregorian calendar. It must be an integer
greater than 1600.

DDD

The day of the year. It must be a positive integer less than
367, provided that it is valid for the year specified.

Example
Function with Argument

FUNCTION INTEGER-OF-DAY (1604001)

8600 1518–307

Result

1096

9–33

INTEGER-PART Function

INTEGER-PART Function
The INTEGER-PART function returns an integer that is the integer portion of argument-1.
The type of this function is integer. This function is fully supported in the COBOL85
TADS environment.

Syntax
FUNCTION INTEGER-PART (argument-1)
ïïïïïïïï ïïïïïïïïïïïï

Explanation
Argument-1 must be of the numeric class. The value of argument-1 determines the value
of the result as shown in the following table.

If the value of
argument-1 is . . .

Then the returned value is . . .

Zero

Zero.

Positive

The greatest integer less than or equal to the value of argument1.
For example, if the value of argument-1 is +1.5, then +1 is
returned.

Negative

The least integer greater than or equal to the value of argument1.
For example, if the value of argument-1 is -1.5, then -1 is
returned.

Example
Function with Argument

FUNCTION INTEGER-PART (-5.9)

9–34

Result

-5

8600 1518–307

LENGTH Function

LENGTH Function
The LENGTH function returns an integer equal to the length of the argument in character
positions. The type of this function is integer.

Syntax
FUNCTION LENGTH (argument-1)
ïïïïïïïï ïïïïïï

Explanation
Argument-1 can be either a nonnumeric literal or a data item of any class or category.
If argument-1 or any data item subordinate to argument-1 is described with the
DEPENDING phrase of the OCCURS clause, the contents of the data item referenced by
the data-name specified in the DEPENDING phrase are used at the time the LENGTH
function is evaluated.
The type of data in argument-1 determines the returned value, as follows:

If argument-1 is . . .

Then the returned value is . . .

•
•
•

A nonnumeric literal

An integer equal to the length of argument-1 in
character positions.

•

A national literal consisting of
multibyte characters

An elementary data item
A group data item that omits a
variable-occurrence data item

A group data item that contains a
variable-occurrence data item

An integer equal to the length of argument-1 in
national character positions (not in bytes).
An integer determined by evaluating the data
item specified in the DEPENDING phrase of the
OCCURS clause for the variable-occurrence
data item. The evaluation is done according to
the rules of the OCCURS clause for “sending”
data items.

The returned value includes implicit FILLER characters, if any.

Examples
Function with Argument

Result

FUNCTION LENGTH ("ABC")

FUNCTION LENGTH (N"ABC")
Note:N"ABC" is a national-character literal.

8600 1518–307

9–35

LENGTH-AN Function

LENGTH-AN Function
The LENGTH-AN function returns an integer equal to the length of the argument in
alphanumeric positions (bytes). The type of this function is integer.

Syntax
FUNCTION LENGTH-AN (argument-1)
ïïïïïïïï ïïïïïïïïï

Explanation
Argument-1 can be either a nonnumeric literal or a data item of any class or category.
If argument-1 or any data item subordinate to argument-1 is described with the
DEPENDING phrase of the OCCURS clause, the contents of the data item referenced in
the DEPENDING phrase are used when the LENGTH function is evaluated.
The type of data in argument-1 determines the returned value, as follows:

If argument-1 is . . .

Then the returned value is . . .

•
•
•

A nonnumeric literal

An integer equal to the length of argument-1
in alphanumeric positions.

•

A national literal of multibyte (8-bit or
16-bit) characters

An integer equal to the length of argument-1
in bytes (not in national character positions).

•

A group data item that contains a
variable-occurrence data item

An integer determined by evaluating the
data item specified in the DEPENDING
phrase of the OCCURS clause for the
variable-occurrence data item. The
evaluation is performed according to the
rules of the OCCURS clause for “sending”
data items.

An elementary data item
A group data item that does not
contain a variable-occurrence data
item

When argument-1 does not occupy an integral number of alphanumeric character
positions, the returned value is rounded to the next larger integer value. The returned
value includes implicit FILLER characters, if any.

9–36

8600 1518–307

LENGTH-AN Function

Examples
Function with Argument

Result

FUNCTION LENGTH-AN ("ABC")

FUNCTION LENGTH-AN (N"ABC")

Note: N"ABC" is an 8-bit national
character literal.
FUNCTION LENGTH-AN (N"ABC")

Note: N"ABC" is a 16-bit national
character literal.

8600 1518–307

9–37

LINENUMBER Function

LINENUMBER Function
The LINENUMBER function returns an integer value for the sequence number of the
source file record on which it appears.

Syntax
FUNCTION LINENUMBER
ïïïïïïïï ïïïïïïïïïï

Explanation
The source line sequence number is returned as an integer. When used in an INCLUDE
file or a COPY statement, the sequence number pertains to the line number in the
included file.

Example
Function

000100 DISPLAY FUNCTION
LINENUMBER

9–38

Result

DISPLAY:100.

8600 1518–307

LOG Function

LOG Function
The LOG function returns a numeric value that approximates the logarithm to the base e
(natural log) of argument-1. The type of this function is numeric. This function is fully
supported in the COBOL85 TADS environment.

Syntax
FUNCTION LOG (argument-1)
ïïïïïïïï ïïï

Explanation
Argument-1 must be of the numeric class. The value of argument-1 must be greater than
zero. An invalid argument results in a run-time error.
The returned value is the approximation of the logarithm to the base e of argument-1.

Example
Function with Argument

FUNCTION LOG (6.429)

8600 1518–307

Result

1.860

9–39

LOG10 Function

LOG10 Function
The LOG10 function returns a numeric value that approximates the logarithm to the base
10 of argument-1. The type of this function is numeric. This function is fully supported in
the COBOL85 TADS environment.

Syntax
FUNCTION LOG10 (argument-1)
ïïïïïïïï ïïïïï

Explanation
Argument-1 must be of the numeric class and must have a value greater than zero. An
invalid argument results in a run-time error.
The returned value is the approximation of the logarithm to the base 10 of argument-1.

Example
Function with Argument

FUNCTION LOG10 (6.429)

9–40

Result

.808

8600 1518–307

LOWER-CASE Function

LOWER-CASE Function
The LOWER-CASE function returns a character string that is the same length as
argument-1 with each uppercase letter replaced by the corresponding lowercase letter.
The type of this function is alphanumeric or national.

Syntax
FUNCTION LOWER-CASE (argument-1)
ïïïïïïïï ïïïïïïïïïï

Explanation
Argument-1 must be of either the alphabetic, alphanumeric, or national class and must
be at least one character in length.
The same character string as argument-1 is returned, except that each uppercase letter
is replaced by the corresponding lowercase letter.
The character string returned has the same length as argument-1.

Example
Function with Argument

FUNCTION LOWER-CASE ("ABC")

8600 1518–307

Result

abc

9–41

MAX Function

MAX Function
The MAX function returns the content of argument-1 that contains the maximum value in
the collating sequence for the program. If the type of argument-1 is National with 8-bit
national characters, the function returns the content of argument-1 corresponding to the
maximum ordinal number in the national collating sequence for the program. The type of
this function depends upon the type of argument used with the function. The argument
types and the corresponding function types are as follows:

Argument Type

Function Type

Alphabetic

Alphanumeric

Integer

Numeric

Numeric (some arguments might be
integer)

Numeric

National

Syntax
FUNCTION MAX ({argument-1} ... )
ïïïïïïïï ïïï

Explanation
If more than one argument-1 is specified,

•

All arguments must be of the same class.

•

Multiple arguments must be separated by a comma (,) or a space.

•

The returned value is the content of the argument that has the greatest value. The
comparisons used to determine the greatest value are made according to the rules
for simple conditions.
If more than one argument has the same greatest value, the content of the
argument returned is the leftmost argument having that value.

If the type of the function is alphanumeric or national, the size of the returned value is the
same as the size of the selected argument-1.

Example
Function with Arguments

FUNCTION MAX (17, 5, 11, 25, 52, 1, 17,
10)

9–42

Result

8600 1518–307

MAX Function

Considerations for Use
When the MAX function itself is assigned to a DISPLAY, COMP, or BINARY data item,
the function results in the exact value.
For example, if A is declared as PIC 9V99, the following statement yields the exact value
of 1.80 for A.
COMPUTE A = FUNCTION MAX (1.0, 1.8)
When the MAX function is contained within an expression and assigned to a DISPLAY,
COMP, or BINARY data item, the result of the function is an approximate value. The
precision might be lost.
For example, if A is declared as PIC 9V99, the following statement yields the
approximate value of 1.79 for FUNCTION MAX (1, 1.8), and yields 3.79 for A.
COMPUTE A = FUNCTION MAX (1.0, 1.8) + 2
To avoid losing precision, declare B as PIC 9V99, and use the following statements:
COMPUTE B = FUNCTION MAX (1.0, 1.8)
COMPUTE A = B + 2

8600 1518–307

9–43

MEAN Function

MEAN Function
The MEAN function returns a numeric value that is the arithmetic mean (average) of its
arguments. The type of this function is numeric.

Syntax
FUNCTION MEAN ({argument-1} ... )
ïïïïïïïï ïïïï

Explanation
Arguments must be of the numeric class and must be separated by a comma (,) or a
space.
The returned value is the arithmetic mean of the argument-1 series, defined as the sum
of the argument-1 series divided by the number of occurrences referenced by
argument-1.

Example
Function with Arguments

FUNCTION MEAN (17, 5, 11, 25, 52, 1, 17, 10)

Result

17.25

Considerations for Use
When the MEAN function itself is assigned to a DISPLAY, COMP, or BINARY data item,
the function results in the exact value.
For example, if A is declared as PIC 9V99, the following statement yields the exact value
of 1.80 for A.
COMPUTE A = FUNCTION MEAN (1.7, 1.8, 1.9)
When the MEAN function is contained within an expression and assigned to a DISPLAY,
COMP, or BINARY data item, the result of the function is an approximate value. The
precision might be lost.
For example, if A is declared as PIC 9V99, the following statement yields the
approximate value of 1.79 for FUNCTION MEAN (1.7, 1.8, 1.9), and yields 3.79 for A.
COMPUTE A = FUNCTION MEAN (1.7, 1.8, 1.9) + 2

9–44

8600 1518–307

MEAN Function

To avoid losing precision, declare B as PIC 9V99, and use the following statements:
COMPUTE B = FUNCTION MEAN (1.7, 1.8, 1.9)
COMPUTE A = B + 2

8600 1518–307

9–45

MEDIAN Function

MEDIAN Function
The MEDIAN function returns the content of the argument whose value is the middle
value in the list formed by arranging the arguments in sorted order. The type of this
function is numeric.

Syntax
FUNCTION MEDIAN ({argument-1} ... )
ïïïïïïïï ïïïïïï

Explanation
Arguments must be of the numeric class and must be separated by a comma (,) or a
space.
The returned value is the content of the argument-1 having the middle value in the list
formed by arranging all the argument-1 values in sorted order.

•

If the number of occurrences referenced by argument-1 is odd, the returned value is
such that at least half of the occurrences referenced by argument-1 are greater than
or equal to the returned value and at least half are less than or equal.

•

If the number of occurrences referenced by argument-1 is even, the returned value is
the arithmetic mean of the values referenced by the two middle occurrences.
The comparisons used to arrange the argument-1 values in sorted order are made
according to the rules for simple conditions.

Example
Function with Arguments

FUNCTION MEDIAN (17, 5, 11, 25, 52, 1, 17, 10)

9–46

Result

8600 1518–307

MEDIAN Function

Considerations for Use
When the MEDIAN function itself is assigned to a DISPLAY, COMP, or BINARY data
item, the function results in the exact value.
For example, if A is declared as PIC 9V99, the following statement yields the exact value
of 1.80 for A.
COMPUTE A = FUNCTION MEDIAN (1.0, 1.8, 2.0)
When the MEDIAN function is contained within an expression and assigned to a
DISPLAY, COMP, or BINARY data item, the result of the function is an approximate
value. The precision might be lost.
For example, if A is declared as PIC 9V99, the following statement yields the
approximate value of 1.79 for FUNCTION MEDIAN (1, 1.8, 2.0), and yields 3.79 for A.
COMPUTE A = FUNCTION MEDIAN (1.0, 1.8, 2.0) + 2
To avoid the losing precision, declare B as PIC 9V99, and use the following statements:
COMPUTE B = FUNCTION MEDIAN (1.0, 1.8, 2.0)
COMPUTE A = B + 2

8600 1518–307

9–47

MIDRANGE Function

MIDRANGE Function
The MIDRANGE (middle range) function returns a numeric value that is the arithmetic
mean (average) of the values of the minimum argument and the maximum argument.
The type of this function is numeric.

Syntax
FUNCTION MIDRANGE ( {argument-1} ... )
ïïïïïïïï ïïïïïïïï

Explanation
Arguments must be of the numeric class and must be separated by a comma (,) or a
space.
The returned value is the arithmetic mean of the greatest argument-1 value and the least
argument-1 value. The comparisons used to determine the greatest and least values are
made according to the rules for simple conditions.

Example
Function with Arguments

FUNCTION MIDRANGE (17, 5, 11, 25, 52, 1, 17, 10)

Result

26.5

Considerations for Use
When the MIDRANGE function itself is assigned to a DISPLAY, COMP, or BINARY data
item, the function results in the exact value.
For example, if A is declared as PIC 9V99, the following statement yields the exact value
of 1.80 for A.
COMPUTE A = FUNCTION MIDRANGE (1.7, 1.8, 1.9)
When the MIDRANGE function is contained within an expression and assigned to a
DISPLAY, COMP, or BINARY data item, the result of the function is an approximate
value. The precision might be lost.
For example, if A is declared as PIC 9V99, the following statement yields the
approximate value of 1.79 for FUNCTION MIDRANGE (1.7, 1.8, 1.9), and yields 3.79 for
A.
COMPUTE A = FUNCTION MIDRANGE (1.7, 1.8, 1.9) + 2

9–48

8600 1518–307

MIDRANGE Function

To avoid the losing precision, declare B as PIC 9V99, and use the following statements:
COMPUTE B = FUNCTION MIDRANGE (1.7, 1.8, 1.9)
COMPUTE A = B + 2

8600 1518–307

9–49

MIN Function

MIN Function
The MIN function returns the content of argument-1 that contains the minimum value in
the collating sequence for the program. If the type of argument-1 is National with 8-bit
national characters, the function returns the content of argument-1 corresponding to the
minimum ordinal number in the national collating sequence for the program. The type of
this function depends on the argument types as follows:

Argument Type

Function Type

Alphabetic

Alphanumeric

Integer

Numeric

Numeric (some arguments might be
integer)

Numeric

National

Syntax
FUNCTION MIN ({argument-1} ... )
ïïïïïïïï ïïï

Explanation
If multiple arguments are specified,

•

All arguments must be of the same class.

•

You must separate arguments with a comma (,) or a space.

•

The returned value is the content of the argument that has the least value. The
comparisons used to determine the least value are made according to the rules for
simple conditions.
If more than one argument has the same least value, the content of the argument
returned is the leftmost argument having that value.

If the type of the function is alphanumeric or national, the size of the returned value is the
same as the size of the selected argument-1.

Example
Function with Arguments

FUNCTION MIN (17, 5, 11, 25, 52, 1, 17, 10)

9–50

Result

8600 1518–307

MIN Function

Considerations for Use
When the MIN function itself is assigned to a DISPLAY, COMP, or BINARY data item,
the function results in the exact value.
For example, if A is declared as PIC 9V99, the following statement yields the exact value
of 1.80 for A.
COMPUTE A = FUNCTION MIN (1.8, 2.0)
When the MIN function is contained within an expression and assigned to a DISPLAY,
COMP, or BINARY data item the result of the function is an approximate value. The
precision might be lost.
For example, if A is declared as PIC 9V99, the following statement yields the
approximate value of 1.79 for FUNCTION MIN (1.8, 2), and yields 3.79 for A.
COMPUTE A = FUNCTION MIN (1.8, 2.0) + 2
To avoid the losing precision, declare B as PIC 9V99, and use the following statements:
COMPUTE B = FUNCTION MIN (1.8, 2.0)
COMPUTE A = B + 2

8600 1518–307

9–51

MOD Function

MOD Function
The MOD function returns an integer value that is argument-1 modulo argument-2. The
type of this function is numeric.

Syntax
FUNCTION MOD (argument-1, argument-2)
ïïïïïïïï ïïï

Explanation
Argument-1 and argument-2 must be integers. The value of argument-2 must not be
zero. You must separate argument-1 and argument-2 with a comma (,) or a space.
The returned value is argument-1 modulo argument-2, defined as follows:
argument-1 - (argument-2 * FUNCTION INTEGER (argument-1 / argument-2))

Examples
Function with Arguments

FUNCTION MOD (11,5)

9–52

Result

FUNCTION MOD (11,--5)

-4

FUNCTION MOD (-11,5)

FUNCTION MOD (-11,-5)

-1

8600 1518–307

NUMVAL Function

NUMVAL Function
The NUMVAL function returns the numeric value represented by the character string
specified by argument-1. The NUMVAL function does not accept an argument that
contains a currency sign or commas. (Use the NUMVAL-C function for that purpose.)
Leading and trailing spaces are ignored.
The type of this function is numeric.

Syntax
FUNCTION NUMVAL (argument-1)
ïïïïïïïï ïïïïïï

Explanation
Argument-1 must be a nonnumeric literal or alphanumeric data item whose content has
one of the following formats:
Format 1:
Ú
¿
³ + ³
[space] ³
³
³ - ³
À
Ù

[space]

ä
³
ã
³
æ

digit [ . [digit] ]
.digit

å
³
â
³
ç

[space]

Format 2:

ä
³ digit [ . [digit] ]
[space] ã
³ . digit
æ

8600 1518–307

å
³
â
³
ç

[space]

Ú ¿
³+ ³
³- ³
³ ³
³CR³
³ïï³
³DB³
ÀïïÙ

[space]

9–53

NUMVAL Function

In the preceding syntax . . .

Represents . . .

Space

A string of zero or more spaces.

Digit

A string of one to 18 digits. The total number of
digits in argument-1 must not exceed 18.

A credit.

A debit.

If the DECIMAL-POINT IS COMMA clause is specified in the SPECIAL-NAMES
paragraph, a comma (,) must be used in argument-1 rather than a decimal point (.).
An invalid argument results in a run-time error.
The returned value is the numeric value represented by argument-1. The number of digits
returned is 18.

Example
Function with Argument

Result

FUNCTION NUMVAL ("37.125DB")

-37.125

The NUMVAL function yields a double-precision result. When the NUMVAL function is
assigned to a DISPLAY, COMP, or BINARY data item, and the function is contained
within an expression, then the function result is an approximate value and precision can
be lost.
For example, if A is declared as PIC 9V99, the following statement yields the exact value
of 1.80 for A:
COMPUTE A = FUNCTION NUMVAL ("1.8")
However, the following statement yields the approximate value of 1.79 for FUNCTION
NUMVAL (“1.8”), and yield 3.79 for A:
COMPUTE A = FUNCTION NUMVAL ("1.8") + 2
The following example avoids this precision problem:
Declare B as PIC 9V99
COMPUTE A = FUNCTION NUMVAL ("1.8")
COMPUTE B = A + 2

9–54

8600 1518–307

NUMVAL-C Function

NUMVAL-C Function
The NUMVAL-C function returns the numeric value represented by the character string
specified by argument-1. Any optional currency sign specified by argument-2 and any
optional commas (,) preceding the decimal point (.) are ignored. The type of this function
is numeric.

Syntax
FUNCTION NUMVAL-C ( argument-1 [,argument-2] )
ïïïïïïïï ïïïïïïïï

Explanation
Argument-1 must be a nonnumeric literal or an alphanumeric data item that contains a
maximum of 18 digits. The content of argument-1 can have one of the following formats:
Format 1

[space]

Ú
¿
³ + ³
³ - ³
À
Ù

[space] [cs] [space]

ä
å
³ digit [, digit] ... [. [digit] ] ³
ã
â [space]
³ . digit
³
æ
ç

Format 2
Ú
ä
å
³ +
³ digit [, digit] ... [. [digit] ] ³
³ [space] [cs] [space] ã
â [space] ³ CR
³ . digit
³
³ ïï
æ
ç
³ DB
À ïï

¿
³
³
³ [space]
³
³
Ù

In the preceding syntax . . .

Represents . . .

Space

A string of zero or more spaces.

The string of one or more characters
specified by argument-2.

Digit

A string of one to 18 digits. The total
number of digits in argument-1 must not
exceed 18.

A credit.

A debit.

8600 1518–307

9–55

NUMVAL-C Function

If the DECIMAL-POINT IS COMMA clause is specified in the SPECIAL-NAMES
paragraph, the functions of the comma and decimal point in argument-1 are reversed.
Argument-2, if specified, must be a nonnumeric literal or alphanumeric data item. If
argument-2 is not specified, the character used for “cs” is the currency symbol specified
for the program.
You must separate argument-1 and argument-2 with a comma (,) or a space.
An invalid argument results in a run-time error.
The returned value is the numeric value represented by argument-1. The number of digits
returned is 18.

Example
Function with Argument

FUNCTION NUMVAL-C ("$ 1,23,567.89
CR")

Result

-1234567.89

The NUMVAL-C function yields a double-precision result. When the NUMVAL function is
assigned to a DISPLAY, COMP, or BINARY data item, and the function is contained
within an expression, then the function result is an approximate value and precision can
be lost.

9–56

8600 1518–307

ONES Function

ONES Function
The ONES function returns a value that is the number of non-zero bits in argument-1. The
type of this function is integer. This function is fully supported in the COBOL85 TADS
environment.

Syntax
FUNCTION ONES (argument-1)
ïïïïïïïï ïïïï

Explanation
Argument-1 must be of the numeric class. It can be either a single-precision or a doubleprecision expression. The returned value is the number of non-zero bits in argument-1.

Example
Function with Argument

FUNCTION ONES (3)

8600 1518–307

Result

9–57

ORD Function

ORD Function
The ORD function returns an integer value that is the ordinal position of argument-1 in
the collating sequence or in the national collating sequence for the program. The lowest
ordinal position is 1. The type of this function is integer.

Syntax
FUNCTION ORD (argument-1)
ïïïïïïïï ïïï

Explanation
Argument-1 must be one character in length and must be class alphabetic, alphanumeric,
or national. An invalid argument results in a run-time error.
The returned value is the ordinal position of argument-1 in the collating sequence or in
the national collating sequence for the program.

Example
Function with Argument

FUNCTION ORD ("]")

9–58

Result

8600 1518–307

ORD-MAX Function

ORD-MAX Function
The ORD-MAX function returns a value that is the ordinal number of the argument-1 that
contains the maximum value in the collating sequence or in the national collating
sequence for the program. The type of this function is integer.

Syntax
FUNCTION ORD-MAX ({argument-1} ... )
ïïïïïïïï ïïïïïïï

Explanation
If multiple arguments are specified,

•

All arguments must be of the same class.

•

Arguments must be separated with a comma (,) or a space.

•

The returned value is the ordinal number that corresponds to the position of the
argument that has the greatest value of all the arguments in the series. The
comparisons used to determine the argument with the greatest value are made
according to the rules for simple conditions.
If more than one argument has the same greatest value, the number returned
corresponds to the position of the leftmost argument having that value.

Example
Function with Arguments

FUNCTION ORD-MAX (17, 5, 11, 25, 52, 1, 17, 10)

8600 1518–307

Result

9–59

ORD-MIN Function

ORD-MIN Function
The ORD-MIN function returns a value that is the ordinal number of the argument-1 that
contains the minimum value in the collating sequence or in the national collating
sequence for the program. The type of this function is integer.

Syntax
FUNCTION ORD-MIN ({argument-1} ... )
ïïïïïïïï ïïïïïïï

Explanation
If multiple arguments are specified,

•

All arguments must be of the same class.

•

Arguments must be separated with a comma (,) or a space.

•

The returned value is the ordinal number that corresponds to the position of the
argument that has the least value of all the arguments in the series. The
comparisons used to determine the argument with the least value are made
according to the rules for simple conditions.
If more than one argument-1 has the same least value, the number returned
corresponds to the position of the leftmost argument having that value.

Example
Function with Arguments

FUNCTION ORD-MIN (17, 5, 11, 25, 52, 1, 17, 10)

9–60

Result

8600 1518–307

PRESENT-VALUE Function

PRESENT-VALUE Function
The PRESENT-VALUE function returns a value that approximates the present value of a
series of future period-end amounts specified by argument-2 at a discount rate specified
by argument-1. The type of this function is numeric.

Syntax
FUNCTION PRESENT-VALUE (argument-1 {argument-2} ... )
ïïïïïïïï ïïïïïïïïïïïïï

Explanation
Argument-1 and argument-2 must be of the numeric class. The value of argument-1
must be greater than -1. Argument-1 and argument-2 must be separated with a comma
(,) or a space.
An invalid argument results in a run-time error.
The returned value is an approximation of the summation of a series of calculations with
each term in the following form:
argument-2 / (1 + argument-1) ** n
One term exists for each occurrence of argument-2. The exponent, n, starts at 1 and is
incremented by 1 for each term in the series.

Example
Function with Arguments

FUNCTION PRESENT-VALUE (.05, 5, 4, 3, 2, 1)

8600 1518–307

Result

13.410

9–61

RANDOM Function

RANDOM Function
The RANDOM function returns a numeric value that is a pseudo-random number from a
rectangular distribution. The type of this function is numeric.

Syntax
FUNCTION RANDOM [(argument-1)]
ïïïïïïïï ïïïïïï

Explanation
If specified, argument-1 must be 0 (zero) or a positive integer. It is used as the seed
value to generate a sequence of pseudo-random numbers. For a given seed value, the
sequence of pseudo-random numbers is always the same.

•

If a subsequent reference specifies argument-1, a new sequence of pseudo-random
numbers is started.

•

If the first reference to this function in the run unit does not specify argument-1, then
some predefined seed value is used.
In each of the preceding cases, subsequent references that do not specify argument1 return the next number in the current sequence.

An invalid argument results in a run-time error.
The returned value is greater than or equal to 0 (zero) and less than 1.

Example
Function with Argument

FUNCTION RANDOM (32)

9–62

Result

.093

8600 1518–307

RANGE Function

RANGE Function
The RANGE function returns a value that is equal to the value of the maximum argument
minus the value of the minimum argument. The type of this function depends on the
type of argument used with the function. The argument types are as follows:

Argument Type

Function Type

Integer

Numeric

Numeric (some arguments might be
integer)

Numeric

Syntax
FUNCTION RANGE ({argument-1} ... )
ïïïïïïïï ïïïïï

Explanation
Arguments must be of the numeric class and must be separated by a comma (,) or a
space.
The returned value is equal to the value of the maximum argument minus the value of
the minimum argument. The comparisons used to determine the maximum and
minimum values are made according to the rules for simple conditions.

Example
Function with Arguments

FUNCTION RANGE (17, 5, 11, 25, 52, 1, 17, 10)

8600 1518–307

Result

9–63

RANGE Function

Considerations for Use
When the RANGE function itself is assigned to a DISPLAY, COMP, or BINARY data item,
the function results in the exact value.
For example, if A is declared as PIC 9V99, the following statement yields the exact value
of 1.80 for A.
COMPUTE A = FUNCTION RANGE (1.0, 2.0, 2.8)
When the RANGE function is contained within an expression and assigned to a DISPLAY,
COMP, or BINARY data item, the result of the function is an approximate value. The
precision might be lost.
For example, if A is declared as PIC 9V99, the following statement yields the
approximate value of 1.79 for FUNCTION RANGE (1.0, 2.0, 2.8), and yields 3.79 for A.
COMPUTE A = FUNCTION RANGE (1.0, 2.0, 2.8) + 2
To avoid the losing precision, declare B as PIC 9V99, and use the following statements:
COMPUTE B = FUNCTION RANGE (1.0, 2.0, 2.8)
COMPUTE A = B + 2

9–64

8600 1518–307

REM Function

REM Function
The REM function returns a numeric value that is the remainder of argument-1 divided by
argument-2. The type of this function is numeric.

Syntax
FUNCTION REM (argument-1, argument-2)
ïïïïïïïï ïïï

Explanation
Argument-1 and argument-2 must be of the numeric class and must be separated by a
comma (,) or a space. The value of argument-2 must not be 0 (zero).
The returned value is the remainder of (argument-1/argument-2). It is defined as the
expression:
argument-1 - (argument-2 * FUNCTION INTEGER-PART (argument-1/argument-2))

Example
Function with Arguments

FUNCTION REM (222.2, 70)

8600 1518–307

Result

12.2

9–65

REVERSE Function

REVERSE Function
The REVERSE function returns a character string that contains exactly the same
characters as in argument-1, except in reverse order. The type of this function is
alphanumeric or national.

Syntax
FUNCTION REVERSE (argument-1)
ïïïïïïïï ïïïïïïï

Explanation
Argument-1 must be of the alphabetic, alphanumeric, or national class and must be at
least one character in length. If argument-1 is a character string of length n, the returned
value is a character string of length n such that for 1 < = j < = n, the character position j
of the returned value is the character from position (n-j+1) of argument-1.

Example
Function with Argument

FUNCTION REVERSE ("ABC")

9–66

Result

CBA

8600 1518–307

SIGN Function

SIGN Function
The SIGN function returns a value that indicates whether the contents of argument-1 is
greater than, less than, or equal to 0 (zero). This function is fully supported in the
COBOL85 TADS environment.

Syntax
FUNCTION SIGN (argument-1)
ïïïïïïïï ïïïï

Explanation
Argument-1 must be of the numeric class.
If the value of argument-1 is
...

Then the returned value is . . .

Greater than zero

Less than zero

-1

Equal to zero

Example
Function with Argument

FUNCTION SIGN (-8)

8600 1518–307

Result

-1

9–67

SIN Function

SIN Function
The SIN function returns a numeric value that approximates the sine of an angle or arc,
expressed in radians, that is specified by argument-1. The type of this function is
numeric. This function is fully supported in the COBOL85 TADS environment.

Syntax
FUNCTION SIN (argument-1)
ïïïïïïïï ïïï

Explanation
Argument-1 must be of the numeric class. The returned value is the approximation of the
sine of argument-1 and is greater than or equal to -1 and less than or equal to +1.

Example
Function with Argument

FUNCTION SIN (.5326)

9–68

Result

.507

8600 1518–307

SQRT Function

SQRT Function
The SQRT function returns a numeric value that approximates the square root of
argument-1. The type of this function is numeric. This function is fully supported in the
COBOL85 TADS environment.

Syntax
FUNCTION SQRT (argument-1)
ïïïïïïïï ïïïï

Explanation
Argument-1 must be class numeric. The value of argument-1 must be 0 (zero) or positive.
An invalid argument results in a run-time error.
The returned value is the absolute value of the approximation of the square root of
argument-1.

Example
Function with Argument

FUNCTION SQRT (10)

8600 1518–307

Result

3.162

9–69

STANDARD-DEVIATION Function

STANDARD-DEVIATION Function
The STANDARD-DEVIATION function returns a numeric value that approximates the
standard deviation of its arguments. The type of this function is numeric.

Syntax
FUNCTION STANDARD-DEVIATION ({argument-1} ... )
ïïïïïïïï ïïïïïïïïïïïïïïïïïï

Explanation
Arguments must be of the numeric class and must be separated by a comma (,) or a
space.
The returned value is the approximation of the standard deviation of the argument-1
series, calculated as follows:
1. The difference between each argument-1 value and the arithmetic mean of the
argument-1 series is calculated and squared.
2. The resulting values are added together.
3. The sum from the preceding addition is divided by the number of values in the
argument-1 series.
4. The square root of the quotient from the preceding division is calculated. The
returned value is the absolute value of this square root.
If the argument-1 series consists of only one value, or if the argument-1 series consists
of all variable occurrence data items and the total number of occurrences for all of them
is one, the return value is 0 (zero).

Example
Function with Arguments

FUNCTION STANDARD-DEVIATION (7, 22, 12, 5, 6, 7, 10, 11)

9–70

Result

5.099

8600 1518–307

SUM Function

SUM Function
The SUM function returns a value that is the sum of the arguments. The type of this
function depends upon the argument types as follows:

Argument Type

Function Type

Integer

Numeric

Numeric (some arguments might be
integer)

Numeric

Syntax
FUNCTION SUM ({argument-1} ... )
ïïïïïïïï ïïï

Explanation
Arguments must be of the numeric class and must be separated by a comma (,) or a
space. The returned value is the sum of the arguments.

Example
Function with Arguments

FUNCTION SUM (7, 5, 11, 25, 52, 1, 17, 52)

8600 1518–307

Result

170

9–71

SUM Function

Considerations for Use
When the SUM function itself is assigned to a DISPLAY, COMP, or BINARY data item,
the function results in the exact value.
For example, if A is declared as PIC 9V99, the following statement yields the exact value
of 1.80 for A.
COMPUTE A = FUNCTION SUM (0.2, 0.6, 1.0)
When the SUM function is contained within an expression and assigned to a DISPLAY,
COMP, or BINARY data item, the result of the function is an approximate value. The
precision might be lost.
For example, if A is declared as PIC 9V99, the following statement yields the
approximate value of 1.79 for FUNCTION SUM (0.2, 0.6, 1.0), and yields 3.79 for A.
COMPUTE A = FUNCTION SUM (0.2, 0.6, 1.0) + 2
To avoid the losing precision, declare B as PIC 9V99, and use the following statements:
COMPUTE B = FUNCTION SUM (0.2, 0.6, 1.0)
COMPUTE A = B + 2

9–72

8600 1518–307

TAN Function

TAN Function
The TAN function returns a numeric value that approximates the tangent of an angle or
arc, expressed in radians, that is specified by argument-1. The type of this function is
numeric. This function is fully supported in the COBOL85 TADS environment.

Syntax
FUNCTION TAN (argument-1)
ïïïïïïïï ïïï

Explanation
Argument-1 must be of the numeric class. The returned value is the approximation of the
tangent of argument-1.

Example
Function with Argument

FUNCTION TAN (.7854)

8600 1518–307

Result

1.0

9–73

UPPER-CASE Function

UPPER-CASE Function
The UPPER-CASE function returns a character string that is the same length as
argument-1 with each lowercase letter replaced by the corresponding uppercase letter.
The type of this function is alphanumeric or national.

Syntax
FUNCTION UPPER-CASE (argument-1)
ïïïïïïïï ïïïïïïïïïï

Explanation
Argument-1 must be at least one character in length and must be of either the
alphabetic, alphanumeric, or national class.
The returned value is the same character string as argument-1, except that each
lowercase letter is replaced by the corresponding uppercase letter. The returned
character string has the same length as argument-1.

Example
Function with Argument

FUNCTION UPPER-CASE ("abc")

9–74

Result

ABC

8600 1518–307

VARIANCE Function

VARIANCE Function
The VARIANCE function returns a numeric value that approximates the variance of its
arguments. The type of this function is numeric.

Syntax
FUNCTION VARIANCE ({argument-1} ... )
ïïïïïïïï ïïïïïïïï

Explanation
Arguments must be of the numeric class and must be separated by a comma (,) or a
space.
The returned value is the approximation of the variance of the series of arguments and is
defined as the square of the standard deviation of the series of arguments. For more
information, refer to “STANDARD-DEVIATION Function.”
The returned value is 0 (zero) in the following situations:

•

If the series of arguments consists of only one value

•

If the series of arguments consists only of variable-occurrence data items and the
total number of occurrences for all of the data items is one

Example
Function with Arguments

FUNCTION VARIANCE (7, 22, 12, 5, 6, 7, 10, 11)

8600 1518–307

Result

9–75

WHEN-COMPILED Function

WHEN-COMPILED Function
The WHEN-COMPILED function returns the date and time the program was compiled.
The type of this function is alphanumeric.

Syntax
FUNCTION WHEN-COMPILED
ïïïïïïïï ïïïïïïïïïïïïï

Explanation
The returned value is the date and time of compilation of the program that contains the
function. If the program is a contained program, the returned value is the compilation
date and time associated with the separately compiled program in which it is contained.
The returned value denotes the same time as the compilation date and time if provided in
the listing of the source program and in the generated object code for the source
program, although their representations and precisions might differ. The characters in the
returned value provide the information in the following tables.
Table 9–7. WHEN-COMPILED Function, Characters 1–21

Character
Positions

Contents

1-4

Four numeric digits of the year in the Gregorian calendar

5-6

Two numeric digits of the month of the year, in the range 01 through 12

7-8

Two numeric digits of the day of the month, in the range 01 through 31

9-10

Two numeric digits of the hours past midnight, in the range 00 through 23

11-12

Two numeric digits of the minutes past the hour, in the range 00 through
59

13-14

Two numeric digits of the seconds past the minute, in the range 00
through 59

15-16

Two numeric digits of the hundredths of a second past the second, in the
range 00 through 99

One of the following characters:
Minus sign (-), which means the local time indicated in the previous
character positions is behind Greenwich Mean Time.
Plus sign (+), which means the local time indicated is the same as or ahead
of the Greenwich Mean Time.
Zero (0), which means the system on which this function is evaluated does
not provide the differential factor. Only the values + and - are returned.

9–76

8600 1518–307

WHEN-COMPILED Function

Table 9–7. WHEN-COMPILED Function, Characters 1–21

Character
Positions

Contents

18-19

The returned value in character positions 18 and 19 depends upon the
character in position 17 as shown in Table Section 9-8.

20-21

The returned value in character positions 20 and 21 depends upon the
character in position 17 as shown in Table Section 9-9.

Table 9–8. WHEN-COMPILED Function, Characters 18–19

If character 17 is a . . .

Then the returned value is . . .

Minus sign (-)

Two numeric digits in the range 00 through 12 indicating
the number of hours that the reported time is behind
Greenwich Mean Time.

Plus sign (+)

Two numeric digits in the range 00 through 13 indicating
the number of hours that the reported time is ahead of
Greenwich Mean Time.

Zero (0)

Table 9–9. WHEN-COMPILED Function, Characters 20–21

If character 17 is a . . .

Then the returned value is . . .

Minus sign (-)

Two numeric digits in the range 00 through 59 indicating
the number of minutes that the reported time is behind
Greenwich Mean Time.

Plus sign (+)

Two numeric digits in the range 00 through 59 indicating
the number of minutes that the reported time is ahead of
Greenwich Mean Time.

Zero (0)

Example
Function

Result

FUNCTION WHEN-COMPILED

1993062813391247-0700

8600 1518–307

9–77

WHEN-COMPILED Function

9–78

8600 1518–307

Section 10
Interprogram Communication
The ANSI COBOL85 interprogram communication (IPC) facility enables programs to
communicate with each other to form a complete solution to a data processing problem.
This section explains the major concepts involved with IPC, which are as follows:

•

The run unit

•

Nested source programs

•

How files and data are accessed

•

External and internal objects

•

Common and initial programs

•

Naming conventions

•

The four IPC forms of communication

•

How ANSI IPC constructs are used

This section also includes a list of COBOL constructs necessary for IPC and some IPC
coding examples.
Note that COBOL85 also provides other program communication techniques not related
to IPC. These techniques and where to find information on them are listed in Table 10–1.
Table 10–1. COBOL85 Program Communication Techniques

Communication Technique

Where to Find Details

Tasking

Section 11

Storage Queue (STOQ)

Section 8, SEND Statement Format 2

Core-to-Core (CRCR)

Section 8, SEND Statement Format 1

Binding

Appendix E

Note that the COBOL IPC implementation is a subset of the capabilities available through
the library facility. For more information on the library facility and COBOL85, refer to
Section 9 and to “CALL Statement” in Section 6.

8600 1518–307

10–1

The Run Unit

The Run Unit
A run unit is a complete problem solution that consists either of an object program or of
several intercommunicating object programs. A run unit is an independent entity that can
be executed without communicating with, or being coordinated with, any other run unit.
However, a run unit can process data files and messages or set and test switches that
were written or will be read by other run units.
When a program is called through a CALL statement, parameters can be passed to it by
the program that calls it.

Nested Source Programs
A COBOL source program can contain, or nest, other COBOL source programs. Nested
programs can include references to resources from the programs in which they are
contained.
A nested program can be contained either directly or indirectly. Figure 10–1 illustrates the
difference:

Figure 10–1. Nested Source Programs
In the preceding figure,

•

Program A contains Program B

•

Program B contains Program C and Program D

Program A contains Program B directly, and Program B contains Program C and Program
D directly. However, Program A contains Program C and Program D indirectly because
they are contained in another program (Program B), which is contained directly within
Program A.

10–2

8600 1518–307

Accessing Files and Data in a Run Unit

Accessing Files and Data in a Run Unit
Programs in a run unit sometimes need to access and have storage areas for

•

The position and status of a file and other attributes of file processing

•

Data item values and other attributes

File Connectors
A file connector is a storage area that contains information about a file. A file connector is
used as the link between a file-name and a physical file, and between a file-name and its
associated record area.

Global and Local Names
A data-name names a data item. A file-name names a file connector. Data-names and
file-names can be either global or local.
A global name can refer to its associated object either from the program where the
global name is declared or from any other program that is contained in the program that
declares the global name.
Consider the following example. Program A contains Program B. Names declared as
global in Program A can be accessed by Program B. However, names declared as global
in Program B cannot be accessed by Program A.
A local name, however, can refer to its associated object only from the program where
the local name is declared.
Some names are always global; some are always local. Other names can be either local
or global depending upon specifications in the program in which the names are declared.
A file-name is global if the GLOBAL clause is specified in the file description entry for that
file-name.
A record-name is global

•

If the GLOBAL clause is specified in the record description entry by which the
record-name is declared

•

If the GLOBAL clause is specified in the file description entry for the file-name
associated with the record description entry
A data-name is global if the GLOBAL clause is specified either in the data description
entry by which the data-name is declared or in another entry to which that data
description entry is subordinate.

8600 1518–307

10–3

Global and Local Names

A condition-name declared in a data description entry is global if that entry is
subordinate to another entry in which the GLOBAL clause is specified. However,
specific rules sometimes prohibit specification of the GLOBAL clause for certain data
description, file description, or record description entries. Refer to “GLOBAL Clause”
in Section 4 for syntax and detailed information.
If a data-name, a file-name, or a condition-name declared in a data description entry is
not global, then the name is local.

10–4

8600 1518–307

External and Internal Objects

External and Internal Objects
File connectors usually require storage of certain file information. Accessible data items
usually require storage of certain data representations. The storage associated with a file
connector or a data item can be external or internal to the program in which the object is
declared.
A file connector or data item is external if the storage associated with that object is
associated with the run unit rather than with any particular program in the run unit. Any
program in the run unit that describes an external object can refer to that object.
Moreover, different programs that describe the same external object can refer to that
object. However, there is only one representative of an external object in a run unit.
An object is internal if the storage associated with that object is associated only with the
program that describes the object.
External and internal objects can have either global or local names.
A file connector receives the external attribute through the EXTERNAL clause in the
associated file description entry. If the file connector does not have the external attribute,
it is internal to the program in which the associated file-name is described.
A data record described in the Working-Storage Section receives the external attribute if
it has the EXTERNAL clause in its data description entry. A data item is also considered
external if it is described by a data description entry subordinate to an entry describing an
external record. If a record or data item does not have the external attribute, it is part of
the internal data of the program in which it is described.
Data records are always internal to the program that describes the file-name when they
are described in one of the following ways:

•

Subordinate to a file description entry that does not contain the EXTERNAL clause

•

Subordinate to a sort-merge file description entry

This is also true for data items described as subordinate to the data description entries
for such records. If the EXTERNAL clause is included in the file description entry, the
data records and the data items receive the external attribute.
Data records, subordinate data items, and associated control information described in the
Linkage Section of a program are internal to the program describing that data. Special
considerations apply to data described in the Linkage Section, where an association is
made between the data records described and other data items accessible to other
programs. Refer to “Linkage Section” in Section 4 for more information.
Refer to “EXTERNAL Clause” in Section 4 for detailed information on this clause.

8600 1518–307

10–5

Common and Initial Programs

Common and Initial Programs
As an option, all programs in a run unit can have common and initial attributes.
A common program is directly contained in another program and can be called by any
program contained in the program in which the common program resides.
Using the IS COMMON PROGRAM clause in a program's Identification Division enables
the program to receive the common attribute. The COMMON clause makes it easier to
write subprograms that will be used by all the programs contained in a program.
An initial program is one whose program state is initialized when the program is called.
When an initial program is called, its program state is the same as it was when the
program was first called in that run unit. The IS INITIAL PROGRAM clause in the
program's Identification Division gives the program the initial attribute.
When an initial program is initialized, its internal data is also initialized. Data items whose
description contains a VALUE clause will be initialized to that defined value. However, an
item whose description does not contain a VALUE clause is initialized to an undefined
value. When an initial program is initialized, the file connectors associated with the
program are not in the open mode. Additionally, the control mechanisms for all
PERFORM statements contained in the program are set to their initial states.
For the general formats of these clauses, refer to Section 2.

10–6

8600 1518–307

Scope of Names

Scope of Names
User-defined words in a program refer only to the objects in that program. Thus,
programs in a run unit, as well as nested programs and the program in which they are
nested can have identical user-defined words.
You can refer to the following types of user-defined words only with statements and
entries in the program in which the user-defined word is declared:
paragraph-name
section-name
However, any COBOL program can refer to the following types of user-defined words:
library-name
text-name
When the following types of names are declared in the Configuration Section of a
program, you can refer to these names with statements and entries in that program. You
can also refer to these names in any program that is contained in the referring program.
alphabet-name
class-name
condition-name
mnemonic-name
symbolic-character
Specific conventions for declarations and references apply to the following types of userdefined words when the conditions listed previously do not apply:
condition-name
data-name
file-name
index-name
program-name
record-name
Refer to “User-Defined Words” in Section 1 for information on the different types of
user-defined words.

8600 1518–307

10–7

Conventions for Program-Names

Conventions for Program-Names
The name of a program is declared in the PROGRAM-ID paragraph of the program's
Identification Division. A program-name can be referred to only by the CALL statement,
the CANCEL statement, and the end program header.
The program-names allocated to the programs of a run unit are not necessarily unique.
However, when two programs in a run unit are identically named, one of them must be
directly or indirectly contained in another separately compiled program that does not
contain the other of those two programs.
Certain conventions apply when, in a separately compiled program, a name identical to
that specified for another separately compiled program in the run unit is specified for a
contained program.
Consider the situation illustrated by Figure 10–2:

Figure 10–2. Identical Program-Names

10–8

•

Program A contains program B and program DUPLICATE-NAME.

•

Program B contains program BB.

•

Program DUPLICATE-NAME contains program DN.

•

The name DUPLICATE-NAME has also been specified for a separately compiled
program.

•

If program A, but not any of the programs it contains, calls program DUPLICATENAME, the program activated is the one contained in program A.

8600 1518–307

Conventions for Program-Names

•

If either program B or program BB calls program DUPLICATE-NAME then:

−

If the program DUPLICATE-NAME (contained in program A) possesses the
common attribute, it is called.

−

If the program DUPLICATE-NAME contained in program A does not possess the
common attribute, the separately compiled program is called.

•

If either program DN or the program DUPLICATE-NAME contained in program A calls
program DUPLICATE-NAME, the program called is the separately compiled program.

•

If any other separately compiled program in the run unit or any other program
contained in such a program calls the program DUPLICATE-NAME, the program
called is the separately compiled program named DUPLICATE-NAME.

8600 1518–307

10–9

Conventions for Names of Data, Files, and Records

Conventions for Names of Data, Files, and Records
Condition-names, data-names, file-names, and record-names can be referred to by the
program in which they are declared.
A program cannot refer to any condition-name, data-name, file-name, or record-name
declared in any program it contains. However, a global name can be referred to in the
program in which it is declared or in any programs that are directly or indirectly contained
in that program.
For example, if Program B is directly contained in Program A, both programs can define a
condition-name, data-name, file-name, or record-name with the same user-defined word.
When such a duplicated name is referred to in Program B, the following rules determine
the referenced object:

•

The names you can use for the referenced object consist of all names defined in
Program B and all global names defined in Program A. (This also includes global
names defined any programs that directly or indirectly contain Program A.)
The normal rules for qualification and any other rules for uniqueness of reference
apply to these names until one or more objects is identified.

•

If only one object is identified, it is the referenced object.

•

Only one object can have a name local to Program B, even though more than one
object can be identified. If none or one of the objects has a name local to Program B,
the following rules apply:

−

If the name is declared in Program B, the object in Program B is the referenced
object.

−

If Program A is contained in another program, the referenced object is either the
object in Program A, if the name is declared in Program A or the object in the
containing program, if the name is not declared in Program A and is declared in
the program containing Program A. This rule is applied to other related containing
programs until a single valid name has been found.

Refer to “User-Defined Words” in Section 1 for the requirements governing the
uniqueness of the names allocated by a single program to be condition names, datanames, file-names, and record-names.

10–10

8600 1518–307

Conventions for Index-Names

Conventions for Index-Names
If a data item possesses the global attribute, and it includes a table accessed by an index,
that index also possesses the attribute.
Therefore, the scope of an index-name is identical to the scope of the data-name that
names the table whose index is named by that index-name. The scope of name rules for
data-names apply to index-names as well.
Index-names cannot be qualified.

Forms of Interprogram Communication
IPC can take four forms:

•

Transfer of control

•

Passing of parameters

•

Reference to common data

•

Reference to common files

These four forms of communication are provided when the communicating programs are
separately compiled and when one of the communicating programs is contained in the
other program.

Transfer of Control
The CALL statement transfers control from one program to another program in a run
unit. A called program can itself contain CALL statements.
When control is transferred to a called program, execution proceeds from statement to
statement from the first nondeclarative statement.
If control reaches an EXIT PROGRAM statement, this signals the logical end of the
execution of the called program only. Control then reverts to the next executable
statement following the CALL statement in the calling program. Thus, the EXIT
PROGRAM statement terminates only the execution of the program in which it occurs,
while the STOP RUN statement terminates the execution of a run unit.
The name assigned to a called program must be unique. This rule applies whether the
called program is contained directly or indirectly in another program.

8600 1518–307

10–11

Forms of Interprogram Communication

Scope of the CALL Statement
The following rules apply to the scope of the CALL statement:

•

Any calling program can call any separately compiled program in the run unit.

•

A calling program can call any program directly contained in the calling program.

•

A calling program can call any program that possesses the common attribute and is
directly contained in a program that itself contains (directly or indirectly) the calling
program. However, this rule does not apply if the calling program is contained in the
program that possesses the common attribute.

•

A calling program can call a program that neither possesses the common attribute
nor is separately compiled if, and only if, that program is directly contained in the
calling program.

Passing Parameters to Programs
In many cases, it is necessary for the calling program to define to the called program the
precise part of the problem solution to be executed. The calling program can make such
data values available to the called program in one of the following ways:

•

By passing the data values as parameters

•

By sharing the data values as parameters

•

By sharing the data values externally

The calling program can pass data values as parameters to the called program by using
either the CALL...USING BY CONTENT or CALL...USING BY REFERENCE statement. For
details about the BY CONTENT and BY REFERENCE phrases, refer to “CALL Statement”
Format 1 in Section 6.
For a discussion of how data is shared, refer to “Sharing Data” later in this section.

Identifying Parameters
To ensure that data passed as a parameter by a calling program to another program is
accessible to the calling program, the data item that will receive the data must be
declared in the Data Division of the called program.
In the called program, you identify the parameters by listing references to the names
assigned in that program's data description entries to the parameters in that program's
Procedure Division header.
In the calling program, you identify the values of the parameters to be passed by the
calling program by listing references in the CALL statement. At object time, these lists
establish the correspondence between the values as they are known to each program.
The correspondence is based on position. That is, the first parameter on one list
corresponds to the first parameter on the other, the second to the second, and so forth.

10–12

8600 1518–307

Forms of Interprogram Communication

Thus, a program can be called by another program; as shown in the following example:
PROGRAM-ID. EXAMPLE.
.
.
.
PROCEDURE DIVISION USING NUM, PCODE, COST.
The program can be called by executing:
CALL "EXAMPLE" USING NBR, PTYPE, PRICE.
This establishes the following correspondence. Only the positions of the data-names are
significant, not the names themselves.
Called program (example)
NUM
PCODE
COST

Calling program
NBR
PTYPE
PRICE

Values of Parameters
The calling program controls the methods by which a called program evaluates the
parameters passed to it and by which the called program returns results. Results are
returned as modified parameter values.
The individual parameters referred to in the USING phrase of the CALL statement can be
passed either by reference or by content.
When a parameter is passed by reference, a called program can access and modify the
value of the data item referred to in the calling program's CALL statement. When a
parameter is passed by content, the called program cannot modify the data item in the
calling program.
The value of the parameter is evaluated when the CALL statement is executed and
presented to the called program. This value can be changed by the called program during
the course of its execution. Note that the value of the parameter passed by reference
can be used by a called program to return to the calling program, whereas a parameter
passed by content cannot be so used.
The parameters referred to in a called program's Procedure Division header must be
described in the Linkage Section of that program's Data Division.

8600 1518–307

10–13

Forms of Interprogram Communication

Passing Parameters Explicitly and Implicitly
Parameters can be passed either explicitly or implicitly. A parameter is passed explicitly if
the parameter is specified in the USING phrase of a CALL statement. A parameter is
passed implicitly in the following situations:

•

The data item is subordinate to the data item specified in the USING phrase of the
CALL statement, as in the following example:
WORKING-STORAGE SECTION.
01 Item-A.
05 Part-1 PIC X(5).
05 Part-2 PIC X(5).
.
.
.
CALL PROGB USING Item-A.
Item-A is passed explicitly. Part-1 and Part-2 are passed implicitly.

•

The data item is defined with a REDEFINES or RENAMES clause, as in the following
example:
WORKING-STORAGE SECTION.
01 Item-A PIC X(10).
01 Item-B REDEFINES Item-A.
05 PIC X(5).
05 PIC X(5).
.
.
.
CALL PROGB USING Item-A.
Item-A is passed explicitly. Item-B is passed implicitly.

Sharing Data
Two programs in a run unit can refer to common data under the following circumstances:

10–14

•

Any program can refer to the data content of an external data record if the referring
program has described that data record.

•

If a program is contained in another program, both programs can refer to data that
possesses the global attribute, either in the containing program or in any program
that directly or indirectly contains the containing program.

•

The way a parameter value is passed by reference from a calling program to a called
program establishes a common data item. The called program can refer to a data
item in the calling program.

8600 1518–307

Forms of Interprogram Communication

Sharing Files
Programs in a run unit can share files by referring to common file connectors.
Two programs in a run unit can refer to common file connectors under the following
circumstances:

•

You can refer to an external file connector from any program that describes that file
connector.

•

If a program contains another program, both programs can refer to a common file
connector by referring to an associated global file-name, either in the containing
program or in any program that directly or indirectly contains the containing program.
(A global file-name is a file-name declared in only one program but which can be
referred to from that program and any program contained in that program.)

8600 1518–307

10–15

Using the ANSI IPC Constructs

Using the ANSI IPC Constructs
The following list shows the COBOL constructs to use for standard ANSI IPC operations:
IDENTIFICATION DIVISION

•

The PROGRAM-ID paragraph enables you to specify the name by which a program is
identified and to assign program attributes to that program.
Do not assign the same name to a nested program as that of any other program
contained in the separately compiled program that contains this program.
You can use the COMMON clause only if the program is nested. The COMMON
clause specifies that the program can be called from programs other than the one
containing it.
Use the INITIAL clause to specify that when the program is called, it and any
programs it contains will be used in their initial state (that is, as they were when they
first entered the run unit).
If you are nesting programs, each program must contain an end program header. The
program-name declared in the Program-ID paragraph must match the program-name
in the end program header.
Refer to “Program-ID Paragraph” in Section 2, and “End Program Header” in
Section 5 for a discussion of syntax and concepts.

DATA DIVISION

•

Describe data items that will be referenced by the calling program and the called
program in the Linkage Section.
Use the Linkage Section if the program will be called and the CALL statement in the
calling program contains a USING phrase in its Procedure Division header.
Data items in the Linkage Section (levels 01 or 77) can be contiguous or
noncontiguous.
The VALUE clause must not be specified in the Linkage Section except in conditionname entries (level 88).

•

Use the File Description IPC Formats 1 through 3. The file description entry in the
File Section determines the internal or external attributes of a file connector, the
associated data records, the associated data items, and whether a file-name is local
or global.
Format 1 is the file description entry for a sequential file; Format 2 for a relative file;
and Format 3 for an indexed file.

10–16

8600 1518–307

Using the ANSI IPC Constructs

•

Use the EXTERNAL clause to specify that a data item or a file connector is external.
The data items and group data items of an external data record are available to every
program in the run unit that describes that record. Internal is the default.

•

Use the GLOBAL clause to specify that a data-name or file-name is a global name. A
global name is available to every program contained in the program that declares it.
Local is the default.
Refer to “Linkage Section” in Section 4 for more information. Refer to “EXTERNAL
Clause” and “GLOBAL Clause” in Section 4 for syntax information and a detailed
discussion of the IPC FD formats.
Refer also to “Procedure Division Header” in this section.

PROCEDURE DIVISION

•

Use the USING clause in the Procedure Division header if the program will be called
by another program. The calling program must contain a CALL statement with a
USING phrase.

•

The CALL statement transfers control from one object program to another in the run
unit. Include the USING phrase of the CALL statement only if there is a USING
clause in the Procedure Division header of the called program. The number of
operands in each place USING occurs must be identical.
The BY REFERENCE phrase specifies that the parameters will be by reference. The
BY CONTENT phrase specifies that the parameters will be passed by content.

•

The CANCEL statement ensures that the next time the referenced program is called,
it will be in its initial state.

•

The EXIT PROGRAM statement marks the logical end of a called program.

•

The STOP statement with the RUN phrase stops the execution of the run unit and
transfers control to the operating system.

•

The USE statement specifies procedures for handling input-output errors in addition
to the standard procedures provided by the input-output control system.
Refer to “Procedure Division Header” in this section for information on the syntax for
the Procedure Division header.
Refer to “CALL Statement,” “CANCEL Statement,” and “EXIT Statement” in
Section 6 and “STOP Statement” and “USE Statement” in Section 8 for syntax and
detailed information.

8600 1518–307

10–17

Using the ANSI IPC Constructs

IPC Examples
Example 1
IDENTIFICATION DIVISION.
PROGRAM-ID. P011.
PROCEDURE DIVISION.
BEGIN-P011.
CALL
"P012".
CALL
"P014".
STOP RUN.
IDENTIFICATION DIVISION.
PROGRAM-ID.
P012 COMMON.
PROCEDURE DIVISION.
BEGIN-P012.
CALL
"P013".
EXIT PROGRAM.
IDENTIFICATION DIVISION.
PROGRAM-ID.
P013.
PROCEDURE DIVISION.
BEGIN-P013.
EXIT PROGRAM.
END PROGRAM
P013.
END PROGRAM
P012.
IDENTIFICATION DIVISION.
PROGRAM-ID.
P014.
PROCEDURE DIVISION.
BEGIN-P014.
CALL "P015".
CALL "P016".
EXIT PROGRAM.
IDENTIFICATION DIVISION.
PROGRAM-ID. P015.
PROCEDURE DIVISION.
BEGIN-P015.
CALL
"P012".
EXIT PROGRAM.
END PROGRAM
P015.
IDENTIFICATION DIVISION.
PROGRAM-ID. P016.
PROCEDURE DIVISION.
BEGIN-P016.
EXIT PROGRAM.
END PROGRAM
P016.
END PROGRAM
P014.
END PROGRAM
P011.
This first example shows nested programs and the COMMON attribute. COMMON is
declared in the PROGRAM-ID of P012. This enables P011 and P015 to call P012. If P012
were not declared as COMMON, P012 could be called only by P011.

10–18

8600 1518–307

Using the ANSI IPC Constructs

Example 2
IDENTIFICATION DIVISION.
PROGRAM-ID. P001.
PROCEDURE DIVISION.
BEGIN-P001.
PERFORM LOOP-B 10 TIMES.
STOP RUN.
LOOP-B.
CALL "P002".
LOOP-C.
IDENTIFICATION DIVISION.
PROGRAM-ID. P002 INITIAL.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 AMOUNT PIC 9(6) VALUE 3 GLOBAL.
PROCEDURE DIVISION.
BEGIN-P002.
ADD 7 to AMOUNT.
END-P002.
EXIT PROGRAM.
END PROGRAM P002.
END PROGRAM P001.
This second example shows nested programs and the INITIAL attribute. Because P002 is
declared as INITIAL, AMOUNT will have a value of 10 after P002 is executed (3 + 7 =
10). If INITIAL were not declared, the final value of AMOUNT would have been 73 (7 * 10
+ 3 = 73). This example also shows use of the GLOBAL clause. AMOUNT is declared as
global and so is available to every program contained in P001.

8600 1518–307

10–19

Using the ANSI IPC Constructs

Example 3
$SET LIBRARYPROG
IDENTIFICATION DIVISION.
PROGRAM-ID. P024.
DATA DIVISION.
LINKAGE SECTION.
01 W7 PIC 9(6).
01 W8 PIC 9(6).
PROCEDURE DIVISION USING W7, W8.
BEGIN-P024.
ADD W8 TO W7.
ADD 93 TO W7.
EXIT PROGRAM.
END PROGRAM P024.
$RESET LIBRARYPROG
IDENTIFICATION DIVISION.
PROGRAM-ID. P023.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 T1 PIC 9(6) VALUE 234.
01 T2 PIC 9(6) VALUE 567.
PROCEDURE DIVISION.
BEGIN-P023.
CALL "OBJECT/P024"
USING BY REFERENCE T1
BY CONTENT T2.
STOP RUN.
END PROGRAM P023.

Compile as P023 and Run P023.
This third example shows the use of the Linkage Section and the passing of parameters
by content and by reference.
P023 and P024 are a pair of separately compiled programs, whose source lines are
contained in one source file. Separately compiled programs generate separate, distinct
object files. If PO24 had been nested within PO23, both programs would be part of the
same object file.
The $SET LIBRARYPROG line forces P024 to be compiled as a library. The $RESET
LIBRARYPROG line turns off the assumed library declaration for the next sequential
program. These are required in order to compile P024 as a library instead of a program
and then compile P023 as a program instead of a library.

10–20

8600 1518–307

Using the ANSI IPC Constructs

Example 4
IDENTIFICATION DIVISION.
PROGRAM-ID. P021.
PROCEDURE DIVISION.
BEGIN-P021.
CALL
"P022".
CALL
"P022".
CANCEL
"P022".
CALL
"P022".
STOP RUN.
IDENTIFICATION DIVISION.
PROGRAM-ID. P022.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 AMOUNT PIC 9(6)
VALUE 3.
PROCEDURE DIVISION.
BEGIN-P022.
ADD 7 to AMOUNT.
DISPLAY AMOUNT.
END-P022.
EXIT PROGRAM.
END PROGRAM P022.
END PROGRAM P021.
This fourth example shows the CANCEL statement. P022 is called three times by P021.
The first time P022 is called, AMOUNT has a value of 3. The second time P022 is called,
AMOUNT has a value of 10 (3 + 7 = 10), which is a result of the previous CALL. Before
the third CALL, there is a CANCEL command that will set P022 back to its initial state.
Therefore, at the third call of PO22, AMOUNT is reset to its original value of 3.

8600 1518–307

10–21

Using the ANSI IPC Constructs

10–22

8600 1518–307

Section 11
Library Concepts
Note: Although this section is not highlighted, all of the information is relative to Unisys
extensions to COBOL ANSI-85.
The library facility is a feature that can be used to structure processes. Unlike COBOL74,
COBOL85 provides most of the library capabilities available to other extended languages
such as ALGOL, Pascal, and FORTRAN.
A library program is a program that provides a procedure or a set of procedures that can
be called by other programs. Each procedure made available, or “exported,” by a library
program is an entry point into the library program. Therefore, a library program can be
thought of as a collection of procedures, each procedure accessible to other programs
(including other library programs).
Programs and other library programs that use the entry points of a library program are
referred to as user programs or calling programs. Throughout this section, we will refer
to library programs as libraries, and procedures or entry points as nested programs.
For general information on the library facility, refer to the System Software Utilities
Operations Reference Manual.
The library capabilities discussed in this section are considered to be extensions to ANSI
COBOL85.
Do not confuse the library facility with the library program capabilities provided by
COBOL74. The LIBRARYPROG compiler option provides a technique for creating
COBOL74-type libraries using COBOL85. Do not use the LIBRARYPROG compiler option
if a program is explicitly declared to be a COBOL85 library.

8600 1518–307

11–1

Library Programs

Library Programs
A library program provides a directly nested program or a set of directly nested programs
that can be called by other programs. The entry points to the library provide access to
nested programs within the library. These entry points are explicitly declared as exported
items in the Program-Library section of the Data Division.
The PROGRAM-ID paragraph in the Identification Division must use the IS LIBRARY
PROGRAM clause. A library program becomes a library when it calls the system
procedure FREEZE to make the entry points available to user programs.
A program specified as a subprogram for binding purposes cannot be declared as an
explicit library.

User Programs
A user program is a program that calls entry points provided by a library. The entry points
are declared as imported objects in the Program-Library section of the Data Division.
A library can function as a user program and call other libraries. However, a chain of
library linkages must never be circular. That is, a library cannot make a reference to itself,
either directly or indirectly, through a chain of library references.

Interface between Libraries and User Programs
The MCP uses data from the compiler to match entry points declared in a calling program
with entry points of a library. When the compiler creates the object code for a

•

Library program, it builds a data structure called a directory for the library.

•

User program, it builds a data structure called a template for each library imported by
the user program.

Directory Data Structure
The description includes the name of the entry point, the type of entry point, the
parameters of the entry point, and linkage information. The directory contains a
description of all the entry points in the library.
NAME OF ENTRY POINT
This is the name of the exported program. The entry point name is the program-name
specified by the PROGRAM-ID paragraph in the Identification Division, and exported by
the ENTRY PROCEDURE clause in the Program-Library Section.
An entry point name other than the program-name can be specified by using the FOR
clause of the ENTRY PROCEDURE clause in the Program-Library Section. If a name other
than the program-name is assigned to an exported program, the name is referred to as
the actual name of the exported program.

11–2

8600 1518–307

Interface between Libraries and User Programs

TYPE OF ENTRY POINT
This is the type of the program. A program can be typed or untyped depending on
whether the GIVING clause is used in the Procedure Division header of the program. If
the GIVING clause is used, the procedure is typed, and returns a result to the calling
program. If the GIVING clause is not used, the procedure is untyped.
PARAMETERS OF ENTRY POINT
This is a description of the formal parameters expected by the exported program. Formal
parameters for exported programs are declared by the USING clause of the Procedure
Division header of the program. The declared formal data parameters must be described
in the Linkage Section of the program, and any formal file parameters must be described
in the File-Control paragraph of the program.
LINKAGE INFORMATION
This information describes the method used to link the library and the calling program
(refer to “Linkage between User Programs and Libraries” in this section.

Template Data Structure
The template contains a description of all the entry points for a given library declared in
the user program. The description includes the library attributes, the name of the entry
point, the type of entry point, and the parameters of the entry point. The compiler
creates a separate template for each library accessed by the user program.
LIBRARY ATTRIBUTES
This is a description of the library attributes declared by the user program (refer to
“Library Attributes” later in this section).
NAME OF ENTRY POINT
This is the name of the imported program. The entry point name is the program-name
specified by the ENTRY PROCEDURE clause of the Program-Library Section.
TYPE OF ENTRY POINT
This is the type of the imported program. A program can be typed or untyped depending
on whether the GIVING clause is used in the Procedure Header of the program. If the
GIVING clause is used, the procedure is typed, and returns a result to the calling
program. If the GIVING clause is not used, the procedure is untyped.
PARAMETERS OF ENTRY POINT
This is a description of the formal parameters expected by the imported program. Formal
parameters for imported programs are declared by the ENTRY PROCEDURE clause in
the Program-Library Section of the user program, and described in the Local-Storage
Section of the user program.

8600 1518–307

11–3

Library Initiation

Library Initiation
On the first call to a library entry point, the operating system suspends execution of the
user program. The description of the entry point in the template of the user program is
compared to the description of the entry point with the same name in the directory
associated with the referenced library. If the entry point does not exist in the library, or if
the two entry point descriptions are incompatible, the operating system issues a run-time
error and terminates the calling program. If the entry point exists and the two entry point
descriptions are compatible, the operating system initiates the library program (if it has
not already been initiated). The library program executes normally until it executes a
library FREEZE. The library FREEZE makes the entry points of the library available. The
operating system links to the user program all of the entry points of the library that are
declared in the user program, and the user program resumes execution at the entry point
of the first call.
A COBOL85 library executes a library FREEZE through a CALL statement of the form
CALL SYSTEM FREEZE.
Because a library runs as a regular program until the library FREEZE request, the
execution of the library FREEZE request can be conditional and can occur anywhere in
the outermost program block.
If a user program causes a library program to be initiated and the library program
terminates without executing a library FREEZE, the attempted linkage to the library entry
points cannot be made, and the user program is terminated.
If the calling program declares an entry point that does not exist in the library, an error is
not generated when the library is initiated. However, if the calling program attempts to
call the nonexistent entry point, the operating system issues a “MISSING ENTRY
POINT” run-time error, and terminates the user program.

Permanent and Temporary Libraries
A library can be specified as either a permanent library or a temporary library. A
permanent library remains available until it is terminated by the system commands DS or
THAW, or by execution of a CANCEL statement. A temporary library remains available so
long as there are users of the library. A temporary library that is not in use “unfreezes”
and resumes execution as a regular program with the statement that follows the library
FREEZE request.
A COBOL85 library is specified as a permanent library or a temporary library through use
of the PERMANENT or TEMPORARY options of the CALL SYSTEM FREEZE statement.

11–4

8600 1518–307

Linkage between User Programs and Libraries

Linkage between User Programs and Libraries
The linkage between the user program and the library can be established directly or
indirectly. The library specifies the form of linkage. Direct linkage occurs when the library
program contains the procedure that is named as an exported item in the LibraryProgram Section of the library. Indirect linkage occurs when the library exports a
procedure that is declared as an entry point of another library. When indirect linkage
occurs, the operating system attempts to link the user program to this other library.
The user program can control the library to which it is linked by specifying the object
code file title or the function name of the library, or by using the BYINITIATOR option.
The LIBACCESS library attribute controls which of these is used. The library attribute
TITLE allows you to specify the object code file title. The library attribute
FUNCTIONNAME allows you to specify the System Library (SL) function name of the
library. The BYINITIATOR attribute allows you to specify the library that initiated the
program.
LINKLIBRARY-RESULT Identifier
During compilation, the compiler inserts a predefined identifier labeled LINKLIBRARYRESULT. This identifier is updated to indicate whether the program is currently linked to,
or is capable of being linked to, the library program when an explicit library entry
procedure is called. If the user program cannot be linked to the library, the value in the
LINKLIBRARY-RESULT identifier indicates the reason for the failure. The values of this
identifier can be interpreted as follows.

Identifier

Description

Successful linkage was made to the library, but not all entry points were
provided. Treated as an exception.

Successful linkage was made to the library and all entry points were
provided.

The program was already linked to the library at the time of the library entry
procedure call.

The program failed to link to the library.
Refer to the ALGOL Programming Reference Manual, Volume 1: Basic
Implementation for possible values and their meanings.

8600 1518–307

11–5

Creating Libraries

Creating Libraries
When a library program is written using COBOL85, certain requirements are imposed on
syntactical elements in the source program. Table 11–1 summarizes these elements.
Table 11–1. Syntax Differences for COBOL85 Libraries

Program
Division

Description

Identification

The IS LIBRARY PROGRAM clause identifies a COBOL85 program as a
library program.

Environment

The SELECT clause of the FILE-CONTROL paragraph can be used to
specify how a file is handled as a procedure parameter.

Data

The Linkage Section of each nested program (exported procedure)
contains descriptions of the formal parameters of the procedure. The
formal parameters are the data items declared by the USING clause of
the Procedure Division header for the nested program.

Data

The Program-Library Section declares the directly nested programs to be
exported. When the library freezes, the nested programs declared in the
Program-Library Section are made available to user programs as entry
points. Included in the LB statement is the EXPORT clause, which
identifies the program as a library. The ATTRIBUTE clause permits
specification of the library SHARING attribute. Library sharing is
discussed later in this section.
The Program-Library Section of a library might also be used to specify
entry points imported by the library from other libraries. In other words, a
library can call other libraries.

Procedure

The Procedure Division header of the outermost program of a library
program cannot contain either the USING or the GIVING clause.
The Procedure Division headers for nested programs of a library program
describe the formal parameters expected by the nested program. The
data items declared in the USING clause must be defined in the Linkage
Section of the nested program.

Procedure

11–6

A procedural call to the library FREEZE facility explicitly freezes the
library and makes the entry points of the library available to user
programs. A library FREEZE can be invoked only from the outermost
program of the library.

8600 1518–307

Library Sharing Specifications

Library Sharing Specifications
The SHARING attribute controls how user programs that call the library share access to
the library.
The SHARING attribute can be specified in the Program-Library Section of the library. The
following table describes the available settings for this attribute:

Option Setting

Description

DONTCARE

The Master Control Program (MCP) determines the sharing.

PRIVATE

A copy of the library is invoked for each user (calling program).
Any changes made to global items in the library by the actions
of the user are visible only to that user of the library.

SHAREDBYRUNUNIT
(default)

All invocations of the library within a run unit share the same
copy of the library. The term run unit as used here refers to a
program and all the libraries that are initiated either directly or
indirectly by that program. Note that this definition differs
slightly from the COBOL ANSI-85 definition of run unit as
described in Section 8.

SHAREDBYALL

All simultaneous users share the same instance of the library.

The default value of the SHARING attribute is SHAREDBYRUNUNIT.

8600 1518–307

11–7

Making References to Libraries

Making References to Libraries
When a user program that accesses libraries is written using COBOL85, certain
requirements are imposed on syntactical elements in the source program. Table 11–2
summarizes these elements.
Table 11–2. Syntax Differences for COBOL85 User Programs

Program
Division

11–8

Description

Data

The Local-Storage Section of a user program contains descriptions of the
formal parameters expected by procedures imported from libraries. These
descriptions are associated with the imported procedure through the WITH
statement of an ENTRY PROCEDURE clause in the Program-Library Section
of the user program.

Data

The Program-Library Section declares the procedures to be imported. The
LB statement specifies the library to be imported. The ATTRIBUTE clause
specifies the initial description of the imported library. The ENTRY
PROCEDURE clause identifies the imported procedures. The WITH clause
of the ENTRY PROCEDURE clause specifies where the description of the
formal parameters of the procedure are found in the Local-Storage Section
of the user program. The USING clause specifies the order of the formal
parameters. The GIVING clause specifies the result returned by the entry
point.

Procedure

The CALL statement transfers control from the user program to a
procedure imported from a library.

Procedure

The CHANGE ATTRIBUTE statement changes a library attribute. Library
attributes are discussed later in this section.

8600 1518–307

Library Attributes

Library Attributes
The user program can assign values to certain library attributes. The library attributes
available to user programs control the method used to link the library and the user
program.
The user program can change library attributes dynamically. However, since the MCP
ignores any changes made to library attributes of linked libraries, these changes must be
made before the program is linked to the library.
When a mnemonic value is referenced in a context that is not associated with any of the
library attribute mnemonic identifiers, then it is treated as a signed numeric constant.
The following paragraphs describe the library attributes available to user programs.

FUNCTIONNAME
Access

Read/Write

Type

String (DISPLAY)

Default Value

The value of INTNAME, if LIBACCESS is
set to BYFUNCTION, else null string

This specifies the system function name used to find the object code file for the library.
The LIBACCESS attribute controls whether the function name or the object code file title
is used to find the object code file for the library.

INTERFACENAME
Access

Read/Write

Type

String (DISPLAY)

Default Value

The value of INTNAME

This identifies a particular connection library in a connection library program.

INTNAME
Access

Read/Write

Type

Default Value

String (DISPLAY)

Library-name declared in LB statement of
Program-Library Section

This specifies the internal name for the library during compilation.

8600 1518–307

11–9

Library Attributes

LIBACCESS
Access

Read/Write

Type

Default Value

Mnemonic

BYTITLE

This specifies how a library object code file is accessed when a library is called.
LIBACCESS can be set to BYFUNCTION, BYTITLE or BYINITIATOR. If LIBACCESS is
equal to BYTITLE, then the TITLE attribute of the library is used to find the object code
file. If LIBACCESS is equal to BYFUNCTION, then the FUNCTIONNAME attribute of the
library is used to access the MCP library function table, and the object code file
associated with that FUNCTIONNAME is used. If LIBACCESS is equal to BYINITIATOR,
then the library that initiated the program is the library that is accessed.
This specifies which information will be passed from the user program to the selection
procedures of libraries that provide entry points dynamically

LIBPARAMETER
Access

Read/Write

Type

Default Value

String (DISPLAY)

(null string)

This specifies the transmission of information from the linking library to the selection
procedure of the library or to the approval procedure of the connection library being
linked to. The linking library can be a client library or a connection library. The primary
library linked to can be a server library or a connection library. However, the selection
procedure in the primary library must select a secondary library that is a server library
(not a connection library). For connection libraries, the system also passes the
LIBPARAMETER library or connection attribute of the requesting library to the
APPROVAL procedure or procedures. The connection attribute is passed if it is set. If the
connection attribute is not set, the library attribute is used. The LIBPARAMETER attribute
for a single connection cannot be library-equated.

TITLE
Access

Read/Write

Type

String (DISPLAY)

Default Value

The value of INTNAME

This specifies the object code file title of the library. The LIBACCESS attribute controls
whether the function name or the object code file title is used to find the object code file
for the library.

11–10

8600 1518–307

Matching Formal and Actual Parameters

Matching Formal and Actual Parameters
When a user program written in COBOL85 imports procedures from a library written in
COBOL85, the data types of formal and actual parameters must be the same. For
example, an imported library procedure that expects an INTEGER data item and a
STRING data item must be passed an INTEGER data item and a STRING data item.
When the user program and the library are written using different programming
languages, the data types of the formal and actual parameters must correspond to one
another. Table 11–3 summarizes the correspondence between COBOL85 data types and
data types found in the programming languages ALGOL and Pascal.
Table 11–3. Data Type Mapping between COBOL85, ALGOL, and
Pascal

COBOL85 Data Type

ALGOL Data Type

Pascal Data Type

BIT, 77
SYNC RIGHT

BOOLEAN

BIT, 01
SYNC RIGHT

BOOLEAN ARRAY

BINARY
level 01

INTEGER ARRAY

ARRAY OF INTEGER

BINARY
level 77, 1–11 digits

INTEGER or REAL

INTEGER

BINARY
level 77, 12–23 digits

DOUBLE

DOUBLE REAL

COMPUTATIONAL and
INDEX

HEX ARRAY

ARRAY OF Hexadecimal
Characters

DISPLAY

EBCDIC ARRAY

ARRAY OF EBCDIC
Characters

DOUBLE
level 01

REAL ARRAY

ARRAY OF REAL

DOUBLE
level 77

DOUBLE

DOUBLE REAL

Integer
(COMPUTATIONAL)
1–11 digits

INTEGER

Integer
(COMPUTATIONAL)
12–23 digits

DOUBLE

DOUBLE REAL

REAL
level 01

REAL ARRAY

ARRAY OF REAL

8600 1518–307

11–11

Matching Formal and Actual Parameters

Table 11–3. Data Type Mapping between COBOL85, ALGOL, and
Pascal

COBOL85 Data Type

ALGOL Data Type

Pascal Data Type

REAL
level 77

REAL

String (DISPLAY)

EBCDIC STRING

STRING OF EBCDIC
Characters

Note: COBOL level 01 data types are EBCDIC data by default. Therefore, if a level 01
item containing a subordinate OCCURS item of BINARY, DOUBLE, or REAL data is being
passed as a parameter to a non-EBCDIC array, the COBOL 01 data item USAGE must be
explicitly declared to match the data type of the receiving array.

11–12

8600 1518–307

COBOL85 Library Example

COBOL85 Library Example
The following COBOL85 program is a library program containing two exported library
procedures (nested programs), the first named MSGLIB-PROG1 and the second named
MSGLIB-PROG2. The file is named TEST/LIBRARY, and resides under the usercode
COBOLUSER on the family COBOLPACK. The executable code file is named
“(COBOLUSER)OBJECT/TEST/LIBRARY ON COBOLPACK” .
* The outer block program containing the procedures
*
*
IDENTIFICATION DIVISION.
PROGRAM-ID. MSGLIB IS LIBRARY PROGRAM.
ENVIRONMENT DIVISION.
DATA DIVISION.
PROGRAM-LIBRARY SECTION.
LB MSGLIB EXPORT
ATTRIBUTE SHARING IS PRIVATE.
ENTRY PROCEDURE MSGLIB-PROG1.
ENTRY PROCEDURE MSGLIB-PROG2.
PROCEDURE DIVISION.
PARA-1.
CALL SYSTEM FREEZE TEMPORARY.
STOP RUN.
*
* THE NESTED PROGRAM MSGLIB-PROG1
*
IDENTIFICATION DIVISION.
PROGRAM-ID. MSGLIB-PROG1.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 ID-STR
PIC X(80).
LINKAGE SECTION.
01 MSG-STR
PIC X(80).

8600 1518–307

11–13

COBOL85 Library Example

*
*
*

The MSG-STR parameter is passed in by the calling program
PROCEDURE DIVISION USING MSG-STR.
PARA-1.
MOVE "THIS IS LIBRARY PROGRAM 1" TO ID-STR.
DISPLAY ID-STR.
DISPLAY MSG-STR.
EXIT PROGRAM.
END PROGRAM
MSGLIB-PROG1.

*
* The nested program MSGLIB-PROG2
*
IDENTIFICATION DIVISION.
PROGRAM-ID. MSGLIB-PROG2.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 ID-STR
PIC X(80).
LINKAGE SECTION.
01 MSG-STR
PIC X(80).
77 MSG-NUM
PIC 9(11) BINARY.
*
*
*
*

The MSG-STR and MSG-NUM parameters are passed in by
the calling program
PROCEDURE DIVISION USING MSG-STR, MSG-NUM.
PARA-1.
MOVE "THIS IS LIBRARY PROGRAM 2" TO ID-STR.
DISPLAY ID-STR.
DISPLAY MSG-NUM.
DISPLAY MSG-STR.
EXIT PROGRAM.
END PROGRAM
MSGLIB-PROG2.
END PROGRAM
MSGLIB.

11–14

8600 1518–307

COBOL85 User Program Example

COBOL85 User Program Example
The following program is a COBOL85 program that imports the library procedures of the
example COBOL85 library program provided earlier in this section:
IDENTIFICATION DIVISION.
PROGRAM-ID. USERPROGRAM.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 MSG-STR
PIC X(80).
77 NUM
PIC 9(11) BINARY.
LOCAL-STORAGE SECTION.
LD PROG1.
01 PROG1-STR PIC X(80).
LD PROG2.
01 PROG2-STR PIC X(80).
77 MSG-NUM
PIC 9(11) BINARY.
PROGRAM-LIBRARY SECTION.
LB MSGLIB IMPORT
ATTRIBUTE TITLE IS "(COBOLUSER)OBJECT/TEST/LIBRARY ON COBOLPACK".
ENTRY PROCEDURE MSGLIB-PROG1 WITH PROG1
USING PROG1-STR.
ENTRY PROCEDURE MSGLIB-PROG2 WITH PROG2
USING PROG2-STR, MSG-NUM.
PROCEDURE DIVISION.
PARA-1.
*
*
*

Put an identifying string into the MSG-STR

MOVE "USERPROGRAM SAYS HELLO TO THE TEST LIBRARY" TO MSG-STR.
*
* Call the library procedure passing the identifying string
*
CALL MSGLIB-PROG1 USING MSG-STR.
*
* Put an identifying string into the MSG-STR, and a value
* into NUM
*
MOVE "USERPROGRAM SAYS HELLO TO THE TEST LIBRARY" TO MSG-STR.
MOVE 1000 TO NUM.
*
* Call the library procedure passing the identifying string
*
CALL MSGLIB-PROG2 USING MSG-STR, NUM.
STOP RUN.
END PROGRAM
USERPROGRAM.

8600 1518–307

11–15

ALGOL User Program Example

ALGOL User Program Example
The following program is an ALGOL program that imports the library procedures of the
example COBOL85 library program provided earlier in this section. When executed from
a remote station, this program prompts the user for text input. The user input is passed
to the COBOL85 library program named “(COBOLUSER)OBJECT/TEST/LIBRARY ON
COBOLPACK.
BEGIN
FILE
REM

(KIND
= REMOTE
,UNITS
= CHARACTERS
,MYUSE
= IO
,BLOCKSTRUCTURE
= EXTERNAL
,MAXRECSIZE = 2040
);

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
SIZING DEFINES
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
DEFINE
MAX_INPUT_LENGTHV = 2040

;
EBCDIC ARRAY
REM_INPUT
,DISPLAY_ARY
;

[00:MAX_INPUT_LENGTHV]
[00:80]

REAL ARRAY
MSG_ARY
;

[00:12]

%-- THIS IS IN WORDS

POINTER
P_MSG_ARY
;
INTEGER
INPUT_LENGTH
,MESSAGE_NUMBER
;
BOOLEAN
DONE
;

11–16

8600 1518–307

ALGOL User Program Example

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%%
%
THIS IS THE IMPORTED LIBRARY, A COBOL85 LIBRARY
%%
%
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
LIBRARY
COBOL_LIBRARY
(LIBACCESS = BYTITLE
,TITLE
= "(COBOLUSER)OBJECT/TEST/LIBRARY ON COBOLPACK."
);
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%%
% MESSAGE_DISPLAY_1 ACCEPTS A SINGLE STRING PARAMETER AND DISPLAYS IT%%
%
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
PROCEDURE MESSAGE_DISPLAY_1 (MSG_STRING
);
EBCDIC ARRAY
MSG_STRING
[0]
;
LIBRARY
COBOL_LIBRARY (ACTUALNAME = "MSGLIB-PROG1")
;
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%%
% MESSAGE_DISPLAY_2 ACCEPTS TWO PARAMETERS, A STRING AND INTEGER
%%
%
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
PROCEDURE MESSAGE_DISPLAY_2 (MSG_STRING
,MSG_NUMBER
);
VALUE
MSG_NUMBER
;
EBCDIC ARRAY
MSG_STRING
[0]
;
INTEGER
MSG_NUMBER
;
LIBRARY
COBOL_LIBRARY (ACTUALNAME = "MSGLIB-PROG2")
;
DEFINE
TALK (MSG)
= IF MYSELF.INITIATOR NEQ 0 THEN
BEGIN
REPLACE P_MSG_ARY : POINTER (MSG_ARY [0])
BY MSG;
WRITE (REM
,OFFSET (P_MSG_ARY)

8600 1518–307

11–17

ALGOL User Program Example

,MSG_ARY
);
#

END
;
%---- END OF DEFINES
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%%
%
O U T E R
B L O C K
%%
%
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
DONE := FALSE;
MESSAGE_NUMBER := 0;
TALK ("Enter the message you want the library to display on ODT");
TALK ("Transmit a single blank space to exit");
WHILE NOT DONE DO
BEGIN
%
% READ FROM THE TERMINAL
%
READ (REM
,MAX_INPUT_LENGTHV
,REM_INPUT
);
%
% GET THE NUMBER OF CHARACTERS ENTERED, OR 80 IF GTR THAN 80
%
INPUT_LENGTH := MIN (REM.CURRENTRECORD
,80
);
%
% IF A SINGLE BLANK SPACE WAS TRANSMITTED, EXIT
%
DONE := (INPUT_LENGTH = 1) AND (REM_INPUT [0] = " ");
IF NOT DONE THEN
BEGIN
%
% LOAD THE INPUT CHARS INTO THE DISPLAY_ARY
%
REPLACE DISPLAY_ARY [0] BY REM_INPUT [0] FOR INPUT_LENGTH;
%
% CALL THE COBOL LIBRARY PROCEDURE
%
MESSAGE_DISPLAY_1 (DISPLAY_ARY);
%
% CALL THE SECOND COBOL LIBRARY PROCEDURE PASSING THE NUMBER
%
MESSAGE_DISPLAY_2 (DISPLAY_ARY, MESSAGE_NUMBER);
MESSAGE_NUMBER := * + 1;
END;
% IF NOT DONE THEN
END;
% WHILE NOT DONE DO
END.

11–18

8600 1518–307

Passing a File as a Parameter

Passing a File as a Parameter
In order to pass a file as a parameter, it is necessary for the calling program to declare
the file twice in the caller. The second instance of the file is the formal parameter and is
used in the imported entry point declaration of the LB.
The following library program and calling program examples illustrate how this is
accomplished.

Library Program Example
IDENTIFICATION DIVISION.
PROGRAM-ID. EXPRTD-ENTRY-PT IS LIBRARY PROGRAM.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
PROGRAM-LIBRARY SECTION.
LB EXPRTD-ENTRY-PT EXPORT
ATTRIBUTE SHARING IS PRIVATE.
ENTRY PROCEDURE INNERPROG.
PROCEDURE DIVISION.
MAIN-PROCEDURE.
DISPLAY "Initializing Library".
CALL SYSTEM FREEZE TEMPORARY.
STOP RUN.
**********************************
* INNER PROGRAM STARTS HERE
*
**********************************
IDENTIFICATION DIVISION.
PROGRAM-ID. INNERPROG.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT REFERENCE THE-FYLE ASSIGN DISK.
DATA DIVISION.
FILE SECTION.
FD THE-FYLE.
01 FYLE-REC PIC X(80).
WORKING-STORAGE SECTION.
LINKAGE SECTION.
PROCEDURE DIVISION USING
THE-FYLE.
MAIN-PROCEDURE.
IF ATTRIBUTE OPEN OF THE-FYLE = VALUE(TRUE)
DISPLAY "File was already open"
ELSE

8600 1518–307

11–19

Passing a File as a Parameter

DISPLAY "File was closed -- opening file"
PERFORM 200-OPEN-THE-FYLE.
100-EXIT-PROGRAM.
EXIT PROGRAM.
200-OPEN-THE-FYLE.
OPEN OUTPUT THE-FYLE.
DISPLAY "File opened in the library".
END PROGRAM INNERPROG.
**********************************
* END OF INNER PROGRAM
*
**********************************
END PROGRAM EXPRTD-ENTRY-PT.

Calling Program Example
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT THE-FYLE ASSIGN TO DISK.
SELECT LOCAL BY REFERENCE
FORMAL-FYLE ASSIGN TO DISK.
DATA DIVISION.
FILE SECTION.
FD THE-FYLE.
01 FYLE-REC
PIC X(84).
FD FORMAL-FYLE.
01 FYLE-REC
PIC X(84).
WORKING-STORAGE SECTION.
77 WS-PARAM PIC S9(11) BINARY.
LOCAL-STORAGE SECTION.
LD FORMAL-PARAMS.
77 LS-PARAM PIC S9(11) BINARY.
PROGRAM-LIBRARY SECTION.
LB EXPL-LIB IMPORT
ATTRIBUTE TITLE IS "OBJECT/C85/CALL/EXLIB/FD/CALLED".
ENTRY PROCEDURE INNERPROG
WITH FORMAL-PARAMS
FORMAL-FYLE
USING LS-PARAM
FORMAL-FYLE.

11–20

8600 1518–307

Passing a File as a Parameter

PROCEDURE DIVISION.
MAIN-PARAGRAPH.
complete CALL-THE-LIBRARY.
IF ATTRIBUTE OPEN OF THE-FYLE = VALUE(TRUE)
DISPLAY "File was returned OPEN"
CLOSE THE-FYLE
ELSE
DISPLAY "File was returned CLOSED".
STOP RUN.
CALL-THE-LIBRARY.
CHANGE ATTRIBUTE TITLE OF THE-FYLE TO "JUNK".
CALL INNERPROG
USING WS-PARAM
THE-FYLE.

8600 1518–307

11–21

Passing a File as a Parameter

11–22

8600 1518–307

Section 12
File Concepts
This section discusses three important file handling concepts in COBOL: file attributes,
file organization, and access mode.
File attributes enable you to define, monitor, and change file properties (attributes). File
organization determines the physical arrangement of the records of a file, which includes
the way records are stored on mass-storage devices. The specified organization of a file
determines the access mode of that file. Access mode determines the logical method
that a program uses to access the records.
This section is organized as follows:

•

Overview
A general discussion of file concepts, including file attributes, the three types of file
organization (sequential, relative, and indexed), and the three types of access mode
(sequential, random and dynamic).

•

File Attributes
An explanation of file attributes, port files, and subfiles.

•

File Organization
An explanation of the different ways to organize files.

•

Access Mode
An explanation of the different ways to access records in a file.

•

File Organization Checklists and Examples
A list of the COBOL elements used with each type of file organization. Each
statement in the list has a reference that directs you to more detailed information on
the statement. Annotated examples of programs that use each type of file
organization are provided.

8600 1518–307

12–1

Overview

Overview
File information is defined by distinguishing between the physical aspects of the file and
the conceptual characteristics of the data in the file.
The physical aspects of a file describe the data as it appears on the input or output
medium, that is, how logical records are grouped according to the physical limits of the
medium and the means by which the file can be identified.
The conceptual characteristics of a file define each logical entity in the file. In a COBOL
program, the input or output statements refer to an entity called a logical record.

Physical versus Logical Records
The distinction between a physical record and a logical record is important. A COBOL
logical record is a group of related information that is uniquely identifiable and treated as
a unit. A physical record is a physical unit of information with a size and recording mode
convenient to a particular computer for storing data on an input or output device. The size
of a physical record is hardware-dependent and has no direct relationship to the size of
the file contained on a device.
A single logical record can be contained in a single physical record, or several logical
records can be contained in a single physical record. In a mass-storage file, however, a
logical record can require more than one physical record. In this manual, references to
records mean logical records unless the term “physical record” is specified.
The concept of a logical record is not restricted to file data. A logical record can apply also
to the definition of working-storage. Thus, working-storage can be grouped into logical
records and defined by a series of record-description entries.
Special facilities can be accessed through logical records. For example, assigning a file to
REMOTE enables you to use the logical file mechanism to access a family of terminal or
station devices that use traditional file-handling methods rather than the specialized datacommunications-handling methods of the Communication Section.

12–2

8600 1518–307

Overview

Manipulating Files
Both the physical and the logical properties (attributes) of files can be defined, monitored,
and changed using file attributes.
To gain access to a logical file, a program must declare both the organization and access
mode of the file. There are three ways to organize a file and three possible ways that the
system can access the file. You designate both organization and access mode in the
SELECT statement of the FILE-CONTROL paragraph in the Environment Division.
The three types of file organization used in COBOL are sequential, indexed, and relative.
The type of file organization determines the physical relationship between records. To
choose a type of file organization, consider the way a file is used in your program and the
resources of your installation.
The types of access mode for files in COBOL are sequential, random, and dynamic. Not
all modes of access are available for all three different types of files (refer to Table 12–1,
later in this section).

8600 1518–307

12–3

File Attributes

File Attributes
File attributes enable you to define, monitor, or change file properties.
File attributes provide access to functions not otherwise available in the language. Also,
file attributes can be used to declare and access files. When both a file attribute and
standard COBOL syntax are available to accomplish a desired function, it is always
preferable to use the standard COBOL syntax, because changing the attribute can lead to
unexpected results in cases when the attribute is also used or altered by the compiler.
File attributes can be initialized using the VALUE OF clause. They can be changed using
the CHANGE statement, and set using the SET statement in the Procedure Division. A
full explanation of each file attribute and how it can be used is available in the File
Attributes Programming Reference Manual.

12–4

8600 1518–307

File-Attribute Identifier

File-Attribute Identifier
File-attribute identifiers enable you to monitor, manipulate, define, or dynamically change
any specific file attribute.
ä OF å
ATTRIBUTE attribute-name ã ïï â file-name
æ IN ç
Ú
ïï
³ ( arithmetic-expression-1 [, arithmetic-expression-2 ] )
³ ( VALUE [(] attribute-name [)] )
À
ïïïïï

¿
³
³
Ù

attribute-name

The attribute-name is a system-name.
arithmetic-expression

Then . . .

Not specified,

The attribute of the port is accessed.

Specified and its value is nonzero,

The value of the expression specifies a
subfile index and causes the attribute of
the subfile to be accessed.

Specified and its value is zero,

The attributes of all subfiles are
accessed.

If an arithmetic expression is used with a disk file, the values of arithmetic-expression-1
and arithmetic-expression-2 must specify the row and copy parameters for the file.

8600 1518–307

12–5

File-Attribute Identifier

VALUE attribute-name

The VALUE attribute-name phrase is valid only for the FILEEQUATED attribute.
Details
A file attribute belongs to one of four categories, depending on the type of attributename specified in the file-attribute identifier. The four file-attribute categories are
described in the following paragraphs:

•

Alphanumeric file-attribute identifier
Where allowed in syntax, an alphanumeric file-attribute identifier is similar to an
elementary alphanumeric DISPLAY data item that has a size equal to the maximum
size allowed for the specified attribute. The contents of the alphanumeric dataidentifier are left-justified with space fill. Alphanumeric file-attribute identifiers are
allowed as operands in relation conditions and as sending operands in Format 1
MOVE statements.

•

Numeric file-attribute identifier
Where allowed in syntax, a numeric file-attribute identifier is similar to an elementary
numeric DISPLAY data item that represents a signed integer with eight decimal
digits. Numeric file-attribute identifiers are allowed as operands in arithmetic
expressions and as sending operands in Format 1 MOVE statements. Some numeric
file attributes represent information that accounts for the number of areas, blocks,
records and so forth in the file. These attributes are “one relative” in that their value
specifies the exact number of areas, blocks, records, and so forth in the file.

•

Mnemonic file-attribute identifier
Certain file attributes are associated with values best expressed as mnemonicnames, because the magnitude of the actual value is unrelated to its meaning.
Mnemonic file-attribute identifiers can appear as the subject of a mnemonic-attribute
relation condition using a mnemonic value associated with the specified attribute as
the object. The name for the attribute value must follow the reserved word VALUE.
Mnemonic-attribute relation conditions are allowed in any conditional expression.

mnemonic-attribute-identifier IS [ NOT ]
ïïï
ä
ã
æ

•

VALUE
ïïïïï
VA
ïï

ä EQUAL å
ã ïïïïï â
æ
=
ç

å
â [ ( ] mnemonic-attribute-value [ ) ]
ç

File-attribute mnemonic value
When a mnemonic value is referenced in a context that is not associated with any of
the file attribute mnemonic identifiers, then it is treated as a signed numeric
constant.

12–6

8600 1518–307

File-Attribute Identifier

•

Mnemonic-attribute relation conditions cannot be abbreviated. The names for the
mnemonic-attribute values are system-names and are not necessarily reserved
words. File attributes with a Boolean nature are considered mnemonic attributes in
COBOL and are associated with the mnemonic-attribute values TRUE and FALSE.

•

The parentheses surrounding the mnemonic-attribute-value are optional. If either
parenthesis is used, both parentheses must be present.

•

Boolean file-attribute identifier.
These attributes are referenced in the same manner as numeric file-attribute
identifiers. These attributes return the value 1 for TRUE and 0 for FALSE.

8600 1518–307

12–7

MCPRESULTVALUE Identifier

MCPRESULTVALUE Identifier
During compilation, the compiler inserts into each program a predefined identifier labeled
MCPRESULTVALUE. This identifier is updated with the I/O result value returned by the
MCP after the execution of an OPEN, CLOSE, READ, WRITE, REWRITE, DELETE,
START, or SEEK statement. The value in the MCPRESULTVALUE identifier indicates the
success or failure of the I/O statement. The MCPRESULTVALUE predefined identifier is a
48-bit word that appears as a real-valued, Working-Storage data item declared as follows:
77 McpResultValue

REAL.

For details on the values placed in MCPRESULTVALUE after an OPEN or CLOSE
statement is executed, refer to the AVAILABLE attribute in the File Attributes
Programming Reference Manual.
For details on the values placed in MCPRESULTVALUE for all other I/O operations, refer
to the STATE attribute in the File Attributes Programming Reference Manual.
Note that an enumerated value is returned in the MCPRESULTVALUE identifier after the
execution of an OPEN or CLOSE statement. The value returned for all other statements
is a Boolean value in the lower part of the word with the enumerated value in the middle
of the word. For convenience, you can move the enumerated value to another real or
binary data item by using the following statement:
MOVE MCPRESULTVALUE TO identifier [26:9:10].
You can then query the alternate data item to determine the status value of the particular
I/O request.
Examples
The following code fragments illustrate the use of the MCPRESULTVALUE identifier to
aid in error recovery. In each case, it is assumed that the $FS4XCONTINUE compiler
option is set (TRUE), which allows a program to continue executing when an I/O request
fails as long as one of the following conditions is met:

•

The FILE STATUS clause is declared (Environment Division)

•

A USE routine is declared.

•

An alternate statement to perform in case of an unsuccessful I/O is declared with the
particular I/O statement (refer to each I/O statement for syntax)
WRITE F-REC.
MOVE MCPRESULTVALUE TO R [26:9:10].
IF R NOT = 0 THEN
IF R = 91 THEN
DISPLAY "IMPLICIT OPEN FAILED"
OPEN OUTPUT F
WRITE F-REC
ELSE
CALL SYSTEM IOTERMINATE USING F.

12–8

8600 1518–307

MCPRESULTVALUE Identifier

This example performs a WRITE operation, and then moves the enumerated value in the
MCPRESULTVALUE identifier to the identifier, R. It then uses an IF statement to test the
MCPRESULTVALUE in identifier R, and provides instructions for the failure or success of
the write operation.
OPEN OUTPUT F.
IF MCPRESULTVALUE NOT = 1 THEN
IF MCPRESULTVALUE = 40 THEN
DISPLAY "FILE WAS NOT CLOSED"
ELSE
CALL SYSTEM IOTERMINATE USING F.
This example issues an OPEN statement, and then issues an IF statement to test the
value in the MCPRESULTVALUE identifier.

8600 1518–307

12–9

Port Files

Port Files
User processes communicate across a BNA network through the standard I/O file
mechanism using a special kind of file called a port file. You can communicate with a
foreign process by performing READ and WRITE operations to a port file. A port file has
one or more associated subports, called subfiles, each of which can be connected to a
different process. Communication between local processes can use port files without
going through a BNA network.
A subfile provides a two-way, point-to-point, logical communication path between two
programs. To establish this path, each program must describe the desired connection.
These descriptions are declared using file attributes.
The ACTUAL KEY clause of the File-Control entry specifies the subfile index used for a
port file when an I/O operation is initiated. If the ACTUAL KEY clause specifies the value
zero, the OPEN statement opens all subfiles associated with the port file, the READ
statement performs a nonselective read, the WRITE statement performs a broadcast
write, and the CLOSE statement closes all opened subfiles associated with the port file.
If the ACTUAL KEY clause is not specified, the file must contain a single subfile. This
subfile is then assumed to be the subfile associated with the I/O statements (any OPEN,
READ, WRITE or CLOSE).

12–10

8600 1518–307

File Organization

File Organization
File organization controls the way records of the file are related to each other. For a
mass-storage file, the organization controls the way records are stored on the massstorage device. File organization relates to attributes of the physical file.
To choose the file organization, consider the type of processing the program is to
accomplish. More specifically, determine how the files in the program are used. The
device associated with a file can determine the organization of the file (for example, a
printer file is organized sequentially). The way that information in the file is accessed can
influence your choice of organization. For example, if records must be read randomly
from many different locations in the file, then the file should probably not be organized
sequentially. The resources of your installation can also influence the choice of file
organization (indexed files require more mass-storage space than other files).
The following paragraphs describe methods of file organization and discuss briefly how
they are used.

Sequential Files
A sequential file is the simplest type of file organization. Records are organized according
to the time that they are placed in the file. For example, the first record written to the file
is placed at the beginning of the file; the second record is placed in the second position in
the file. Frequently, files that do not reside on mass-storage devices (for example, tape or
cards) are organized sequentially.
The following steps illustrate the use of a sequential file: A master file that contains
records for all employees is first sorted by employee number, and then placed in a
sequential file. In a sequential file, every record has a predecessor and a successor
except for the first and last records. Therefore, the record for the employee number 5066
would be after the record for employee 5065 and before 5067. The records are in
numerical order by employee number because the file was sorted by employee number
before being placed in the sequential file. The records in a sequential file are organized by
the order they are placed in the file.
Sequential files are usually used when you must process most of the records in a file. In
a master payroll file, where most records are updated, a sequentially organized file is the
best choice. However, if most of the records in a file will not be accessed during
processing, then sequential file organization could be inefficient.
Types of sequential files

•

Printer file (output)

•

Tape file (input or output)

•

Card file (input)

•

Port file (input or output)

8600 1518–307

12–11

File Organization

Important considerations for use

•

All the predecessors to any record must be read before access is available.

•

Empty record spaces are not allowed.

•

You can only process forward in a file, from record 1 to 2 (except for tape files that
allow the file to be rewound). In order to move backwards in a file, you must reset—
that is, CLOSE and then OPEN—the file.

•

Records cannot be deleted.

Relative Files
Relative file organization makes random processing easier. Records in a relative file are
defined by the ordinal position in the file. The relative key reflects the relative position of
the record in the file. The key is required for all relative files and is not part of the record
itself.
To fully understand relative file organization, examine the difference between relative
files and sequential files. In a sequential file, every record has a predecessor and a
successor except for the first and last records. In a relative file, a record is located by the
relative record number, regardless of the location of the record. Consequently, it is
possible to have undefined record positions in a relative file.
Example of a relative file
An account file, where all information is accessed by account number. In such a file, the
account number could be used as the relative key. If an account becomes inactive, the
record is deleted, but the deleted record location remains in the file until the account
number is reassigned or the file is consolidated.
Important considerations for use

12–12

•

Relative files are designed to make random access easier. If a file is never accessed
randomly, you should consider a different type of file organization.

•

Deleted record locations are allowed in the file. The empty spaces are skipped in
sequential access mode.

•

Relative files must be disk files.

8600 1518–307

File Organization

Indexed Files
An indexed file is a type of file organization that allows access to records according to a
key field in each record. An indexed file consists of two parts: a data file containing all of
the records, and an index or key file that contains record keys in sorted order. When an
indexed file has multiple keys, there are multiple key files (one for each key). Each record
in a key file connects a record key value with the position of the corresponding record in
the data file. Therefore, when a specific record is needed for processing, the system
checks the key file to determine the exact position of that record.
Index files provide a more flexible access. For example, a programmer designates that an
employee number is a record key. The system then creates a key file on disk that
references the positions of employee records, based on their employee numbers. To
access a record during processing, the employee number is moved into the record area
of the program and the system reads the indexed file to locate the desired record.
Example of an indexed file
A typical indexed file is one that must be accessed by one or more different
characteristics. For example, records in an inventory file of cars for sale at a dealership
could be accessed by model, year, or color.
Important considerations for use

•

Flexibility: Indexed files enable you to access records sequentially by key, randomly
by key, or by relative record number.

•

Resources: Indexed files consume more space on disk or disk pack than other file
organizations.

•

Speed of processing: Indexed files generally require more I/Os and take longer to
access.

•

Indexed files are limited to mass-storage devices.

•

Any item declared as a record key must be part of the actual data record.

•

Indexed files allows record level locking.

•

Records in indexed files can be deleted.

8600 1518–307

12–13

Access Mode

Access Mode
Access mode describes the way that records in a file are processed. There are three
types of access modes in COBOL. Not all access modes can be used with all file
organizations. Table 12–1 lists each type of file organization, the types of access modes
that are possible with the organization, and the types of keys that are necessary.
(Information on the different types of keys is included under “FILE-CONTROL
Paragraph” in Section 3.) Immediately following the table are paragraphs describing each
type of access mode.
Table 12–1. File Organization and Access Mode

Organization

Sequential Files

Relative Files

Indexed Files

Access Mode

Key

Sequential

No key required

Random

Actual key (numeric)

Sequential

Key is optional

Random

Relative key (numeric)

Dynamic

Relative key (numeric)

Sequential

Record key (alphanumeric)

Random

Record key (alphanumeric)

Dynamic

Record key (alphanumeric)

Sequential Access Mode
Sequential access is valid for all three types of file organization and is the default for each
type of file organization. A file declared as sequential access is processed from beginning
to end, starting with the first record and finishing with the last record. A key is not
required unless the file is organized as an indexed file. Use the AT END phrase of the
READ statement for any in-line exception handling.

Random Access Mode
Random access is allowed for all three types of file organization. (This is an extension to
COBOL ANSI-85 for sequential files.)
A file declared as random access uses a relative record number to point to a specific
record in the file. The programmer must maintain the value of the key. To access a file
randomly, the file must be stored on disk. For random access files, the READ statement
must contain the INVALID KEY phrase for in-line exception handling.

12–14

8600 1518–307

Access Mode

Dynamic Access Mode
Dynamic access allows a file to be accessed in both the random and the sequential
modes. The mode of a file depends on which commands are used.
Dynamic access is allowed for indexed and relative files only.

•

For sequential access, the READ statement requires the AT END phrase to handle
any in-line exception handling.

•

For random access, the READ statement must contain the INVALID KEY phrase.

To read a file sequentially, the NEXT phrase must be used in the READ statement. The
specified key is not considered. The current record parameter is changed to point to the
next available record.
To read a file randomly, the value of the specified key points to the position in the file and
the record in that position is delivered during the evaluation of a READ statement. The
INVALID phrase determines the handling of the circumstances when the value of the key
points to a nonexistent record.

8600 1518–307

12–15

File Organization Checklists

File Organization Checklists
The following pages contain a list of the COBOL elements that are used to declare,
initialize, and process a file. The checklist is divided into sections for each type of file
organization: sequential, relative, and indexed. In each type of file organization, the
elements are listed according to the division where they appear. These pages also
include program examples to illustrate how these COBOL elements are used.
Each element in the list refers to more detailed information elsewhere in this manual.

Sequential File Checklists
Identification Division : None.
Environment Division
FILE-CONTROL paragraph of the Input-Output Section

•

Use Format 1 of the SELECT statement for sequential files.

•

Name each file used in the program in a SELECT statement and assign the
file to a type of hardware using the ASSIGN TO clause.

•

Let the default value of the ORGANIZATION IS clause define the
organization of the file as sequential. For documentation, define the
organization explicitly (ORGANIZATION IS SEQUENTIAL).

•

Use the ACCESS MODE IS clause to define the access mode the program
uses to access the file. The default access mode for sequential files is
SEQUENTIAL.

•

If the program monitors the status of the file, define a variable to receive
status key values by using the FILE STATUS IS clause.

Detailed information on the FILE-CONTROL paragraph and status key values for
sequential files is included in Section 3.
I-O-CONTROL paragraph of the Input-Output Section: The MULTIPLE FILE clause
defines sequentially organized tape files when more than one file shares the same
physical reel of tape. Detailed information on the I-O-CONTROL paragraph is included
in Section 3.
Data Division
FD Entry in the File Section : A valid file description (FD) entry must be defined for all
sequential files. Detailed information on the FD entry is included in Section 4.
Data-names in the WORKING-STORAGE SECTION: If the program monitors the
status of a file, a data-name must be defined to receive status key values. This dataname must be the same as the data-name in the FILE STATUS IS clause of the file's
SELECT entry, located in the FILE-CONTROL paragraph of the Environment Division.
Details on the FILE STATUS IS clause are included under “FILE-CONTROL
Paragraph” in Section 3.

12–16

8600 1518–307

File Organization Checklists

Procedure Division
CLOSE statement

•

Use Format 1 of the CLOSE statement.

•

You can use the REEL and UNIT phrases of the CLOSE statement for
sequential tape files. They are not valid for any other type of file organization.

Detailed information on the CLOSE statement is included in Section 8.
OPEN statement : You can use the REVERSED, NO REWIND, and EXTEND phrases
of the OPEN statement for sequential files. These phrases are not valid for any other
type of file organization. Details on the OPEN statement are included in Section 6.
READ statement: Use Format 1 of the READ statement. Detailed information on
the READ statement is included in Section 6. Information relating to sequentially
organized files is included in the discussion of both Format 1 and Format 2.
REWRITE statement

•

The REWRITE statement is valid only for mass-storage files.

•

When the access mode is sequential, a successful READ statement must be
performed on the file before a REWRITE statement is performed. No other IO statements that affect the file can be executed between the READ and
the REWRITE statements.

Detailed information on the REWRITE statement is included in Section 6.
WRITE statement: Use Format 1 of the WRITE statement. Detailed information on
the WRITE statement is included in Section 8.

8600 1518–307

12–17

File Organization Checklists

Sequential File Program Example
This COBOL program example uses a sequential file. The program name is EXECTEST,
and it creates a print file from the contents of a sequential data file named OUT-FILE.
IDENTIFICATION DIVISION.
PROGRAM-ID. EXECTEST.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. A-14.
OBJECT-COMPUTER. A-14.
SPECIAL-NAMES.
ALPHABET ASCII-SET IS ASCII.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT OPTIONAL OUT-FILE
STATUS WA-STAT ASSIGN TO DISK.
SELECT PRINT-FILE ASSIGN TO PRINTER.
DATA DIVISION.
FILE SECTION.
FD OUT-FILE
BLOCK CONTAINS 30 RECORDS
RECORD CONTAINS 84 CHARACTERS
VALUE OF INTNAME IS "IN"
CODE-SET IS ASCII-SET.
01 SOURCE-IN-REC.
05 SOURCE-IN
PIC X(72).
05 SOURCE-SEQ
PIC 9(8) COMP.
05 SOURCE-JUNK
PIC X(4).
FD PRINT-FILE.
01 PRINT-REC.
05 PRINT-LINENUM PIC 9(8).
05 BLANK-SPACES
PIC X(2).
05 PRINT-DATA
PIC X(72).
WORKING-STORAGE SECTION.
77 WA-STAT
PIC X(02).
01 LINE-NUMBER
PIC 9(8) COMP.
PROCEDURE DIVISION.
PARA-1.
OPEN INPUT OUT-FILE.
OPEN OUTPUT PRINT-FILE.
MOVE SPACES TO BLANK-SPACES.
MOVE 1 TO LINE-NUMBER.
PARA-2.
READ OUT-FILE AT END GO TO EOJ.
MOVE LINE-NUMBER TO PRINT-LINENUM.
MOVE SOURCE-IN TO PRINT-DATA.
WRITE PRINT-REC.
ADD 1 TO LINE-NUMBER.
GO TO PARA-2.
EOJ.

12–18

8600 1518–307

File Organization Checklists

Relative File Checklist
Identification Division: None.
Environment Division
FILE-CONTROL paragraph of the Input-Output Section

•

Use Format 2 of the SELECT statement for relative files.

•

Name each file used in the program in a SELECT statement and assign the
file to a type of hardware using the ASSIGN TO clause.

•

Use the ORGANIZATION IS clause to define the file organization as relative.

•

Use the ACCESS MODE IS clause to define the access mode the program
uses to retrieve records from the file. Allowable access modes are
sequential, random or dynamic.

•

If the program uses random or dynamic access mode, use the RELATIVE
KEY IS clause to define the key variable.

•

If the access mode is sequential, the RELATIVE KEY IS clause is optional.

•

If the program monitors the status of the file, define a variable to receive
status key values by using the FILE STATUS IS clause.

For details on the FILE-CONTROL paragraph and status key values, see Section
3.
Data Division
FD in the File Section: A valid file description entry (FD) must be defined for all
relative files. Detailed information on the FD is included in Section 4.
Data-names in the Working-Storage Section

•

Define the random access key. If the relative file is accessed randomly or
dynamically, a data item must be defined to be the key used for random
access. This data-name must be the same as the data-name in the
RELATIVE KEY IS clause of the SELECT entry for the file.

•

If the program monitors the status of a file, a data name must be defined to
receive status key values. This data name must be the same as the data
name in the FILE STATUS IS clause of the SELECT entry of the file.

Detailed information on the RELATIVE KEY IS clause and the FILE STATUS IS
clause is included under “FILE-CONTROL Paragraph” in Section 3.

8600 1518–307

12–19

File Organization Checklists

Procedure Division
CLOSE statement

•

Use Format 2 of the CLOSE statement.

•

The REEL and UNIT phrases are not valid for relative files.

Detailed information on the CLOSE statement is included in Section 6.
DELETE statement

•

The DELETE statement is valid only for mass-storage files.

•

If the file is accessed randomly or dynamically, a DELETE statement
removes the record indicated by the contents of the data item specified by
the RELATIVE KEY IS clause of the FILE-CONTROL paragraph.

Detailed information on the DELETE statement is included in Section 6.
OPEN statement: The REVERSED, NO REWIND and EXTEND phrases of the OPEN
statement are not valid for relative files. Detailed information on the OPEN
statement is included in Section 7.
READ statement: Use Format 1 of the READ statement to read the file in sequential
access mode.

•

If the access mode is random, use Format 2.

•

For dynamic access mode, use Format 1 (with the NEXT phrase) or Format
2, depending on the needs of the program.

Details on the READ statement are included in Section 7. Information on relative
files is included in the discussion of both Format 1 and Format 2.
REWRITE statement

•

The REWRITE statement is valid only for mass-storage files.

•

When the access mode is random or dynamic, a REWRITE statement
replaces the record indicated by the data item used in the RELATIVE KEY IS
clause of the FILE-CONTROL paragraph.

•

When the access mode is sequential, a successful READ statement must be
performed on the file before a REWRITE statement is performed. No other IO statements that affect the current record pointer can be executed
between the READ and the REWRITE statements.

Detailed information on the REWRITE statement is included in Section 7.

12–20

8600 1518–307

File Organization Checklists

START statement

•

The START statement is valid for sequential or dynamic access mode.

•

The data item used in the START statement must match the data item used
in the RELATIVE KEY IS clause of the FILE-CONTROL paragraph.

Detailed information on the START statement is included in Section 6.
WRITE statement : Use Format 2 of the WRITE statement. Details on the WRITE
statement are included in Section 8. Information on relative files is included in the
discussion of both Format 1 and Format 2.

8600 1518–307

12–21

File Organization Checklists

Relative File Program Example
This COBOL program example uses a relative file. The name of the program is RELEXMPL, and it prints a report of selected employee information from an employee
master file using the employee number as the record key.
IDENTIFICATION DIVISION.
PROGRAM-ID.
REL-EXMPL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
A-9.
OBJECT-COMPUTER.
A-9.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT PERSONNEL-FILE ASSIGN TO DISK
ORGANIZATION IS RELATIVE
ACCESS MODE IS RANDOM
RELATIVE KEY IS KEY-FOR-RECORD.
SELECT PRINT-FILE ASSIGN TO PRINTER.
DATA DIVISION.
FILE SECTION.
FD PERSONNEL-FILE BLOCK CONTAINS 3 RECORDS.
01 EMPLOYEE-RECORD.
05 EMPLOYEE-NUMBER
PIC 9999.
05 NAME
PIC X(16).
05 JOB-TITLE
PIC X(16).
05 DATES
PIC X(16).
05 MONTHLY-SALARY
PIC 9999.99.
01 DEPENDENT-RECORD.
05 DEP-NAME
PIC X(24).
05 DEP-SSN
PIC X(11).
05 CHILD-FLAG
PIC X(1).
FD PRINT-FILE.
01 PRINT-EMPLOYEE-RECORD.
05 PRINT-EMPL
PIC X(16) OCCURS 5 TIMES INDEXED BY EP.
01 PRINT-DEPENDENT-RECORD.
05 PRINT-DEP
PIC X(26) OCCURS 3 TIMES INDEXED BY DP.
05 PRINT-TRAILER-DEP PIC XX.
WORKING-STORAGE SECTION.
01 KEY-FOR-RECORD
01 RESULT-NEXT-EMPLOYEE
01 RESULT-DEPENDENT-NUMBER
01 RESULT-DESIRED-EMPLOYEE

PIC
PIC
PIC
PIC

99999
X
9
9999

VALUE
VALUE
VALUE
VALUE

IS
IS
IS
IS

0.
"Y".
0.
0.

PROCEDURE DIVISION.
S1 SECTION.
MAIN-PROGRAM.
OPEN OUTPUT PERSONNEL-FILE.

12–22

8600 1518–307

File Organization Checklists

OPEN OUTPUT PRINT-FILE.
PERFORM ENTER-DATA UNTIL RESULT-NEXT-EMPLOYEE = "N".
CLOSE PERSONNEL-FILE SAVE.
OPEN I-O PERSONNEL-FILE.
PERFORM GENERATE-REPORT THROUGH GENERATE-REPORT-ENDLOOP
UNTIL RESULT-NEXT-EMPLOYEE = "N".
CLOSE PERSONNEL-FILE.
CLOSE PRINT-FILE.
STOP RUN.
ENTER-DATA.
PERFORM GET-EMPLOYEE-DATA.
MULTIPLY EMPLOYEE-NUMBER BY 3 GIVING KEY-FOR-RECORD.
WRITE EMPLOYEE-RECORD; INVALID KEY DISPLAY "FILE SIZE EXCEE".
PERFORM PROMPT-FOR-NUM-OF-DEP.
PERFORM ENTER-DEPENDENT-DATA
RESULT-DEPENDENT-NUMBER TIMES.
PERFORM PROMPT-NEXT-EMPLOYEE.
ENTER-DEPENDENT-DATA.
PERFORM GET-DEPENDENT-DATA.
ADD 1 TO KEY-FOR-RECORD.
WRITE DEPENDENT-RECORD;
INVALID KEY DISPLAY "FILE SIZE EXCEEDED".
******************************************************************
GENERATE-REPORT.
PERFORM PROMPT-DESIRED-EMPLOYEE.
MULTIPLY RESULT-DESIRED-EMPLOYEE BY 3 GIVING KEY-FOR-RECORD.
READ PERSONNEL-FILE;
INVALID KEY DISPLAY "NO EMPLOYEE FOR THAT NUMBER"
PERFORM INVALID-EMPLOYEE
GO TO GENERATE-REPORT-ENDLOOP
NOT INVALID KEY PERFORM WRITE-EMPL-RECORD.
ADD 1 TO KEY-FOR-RECORD.
READ PERSONNEL-FILE;
INVALID KEY MOVE SPACES TO PRINT-DEPENDENT-RECORD
MOVE "NO DEPENDENTS" TO PRINT-DEP(1)
WRITE PRINT-DEPENDENT-RECORD
GO TO GENERATE-REPORT-ENDLOOP
NOT INVALID KEY PERFORM WRITE-DEP-RECORD.
ADD 1 TO KEY-FOR-RECORD.
READ PERSONNEL-FILE;
INVALID KEY MOVE SPACES TO PRINT-DEPENDENT-RECORD
MOVE "NO MORE DEPENDENTS" TO PRINT-DEP(1)
WRITE PRINT-DEPENDENT-RECORD
NOT INVALID KEY PERFORM WRITE-DEP-RECORD END-WRITE.
GENERATE-REPORT-ENDLOOP.
PERFORM PROMPT-NEXT-EMPLOYEE.
INVALID-EMPLOYEE.

8600 1518–307

12–23

File Organization Checklists

MOVE SPACES TO PRINT-EMPLOYEE-RECORD.
MOVE "INVALID EMPL. #" TO PRINT-EMPL(1)
MOVE RESULT-DESIRED-EMPLOYEE TO PRINT-EMPL(2)
WRITE PRINT-EMPLOYEE-RECORD.
WRITE-EMPL-RECORD.
MOVE SPACES TO PRINT-EMPLOYEE-RECORD.
MOVE EMPLOYEE-NUMBER TO PRINT-EMPL(1).
MOVE NAME TO PRINT-EMPL(2).
MOVE JOB-TITLE TO PRINT-EMPL(3).
MOVE DATES TO PRINT-EMPL(4).
MOVE MONTHLY-SALARY TO PRINT-EMPL(5).
WRITE PRINT-EMPLOYEE-RECORD.
WRITE-DEP-RECORD.
MOVE SPACES TO PRINT-DEPENDENT-RECORD.
MOVE DEP-NAME TO PRINT-DEP(1).
MOVE DEP-SSN TO PRINT-DEP(2).
MOVE CHILD-FLAG TO PRINT-DEP(3).
WRITE PRINT-DEPENDENT-RECORD.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * *
GET-EMPLOYEE-DATA.
*
TERMINAL COMMUNICATION PROCEDURE TO DISPLAY
*
FORMATTED SCREEN AND RETURN ENTERED DATA ABOUT
*
AN EMPLOYEE INTO THE FIELDS OF EMPLOYEE-RECORD.
GET-DEPENDENT-DATA.
*
*
*
PROMPT-NEXT-EMPLOYEE.
*
*
*
PROMPT-FOR-NUM-OF-DEP.
*
*
*
*
PROMPT-DESIRED-EMPLOYEE.
*
*
*
*
*

12–24

TERMINAL COMMUNICATION PROCEDURE TO DISPLAY
FORMATTED SCREEN AND RETURN ENTERED DATA ABOUT
A DEPENDENT INTO FIELDS OF DEPENDENT-RECORD.
TERMINAL COMMUNICATION PROCEDURE TO ASK IF
DATA FOR ANOTHER EMPLOYEE MUST BE ENTERED.
"Y" OR "N" IS RETURNED IN RESULT-NEXT-EMPLOYEE.
TERMINAL COMMUNICATION PROCEDURE TO ASK HOW
MANY DEPENDENTS DATA MUST BE ENTERED FOR.
RETURNS A NUMBER FROM 0 THROUGH 2 IN
RESULT-DEPENDENT-NUMBER.
TERMINAL COMMUNICATION PROCEDURE TO ASK FOR
THE EMPLOYEE NUMBER OF THE EMPLOYEE WHOSE
RECORDS WILL BE INCLUDED IN THE PRINTED REPORT.
THE EMPLOYEE'S NUMBER IS RETURNED IN
RESULT-DESIRED-EMPLOYEE.

8600 1518–307

File Organization Checklists

Indexed File Checklist
Identification Division: None.
Environment Division

•

FILE-CONTROL paragraph of the Input-Output Section

•

Use Format 3 of the SELECT statement for indexed files.

•

Name each file used in the program in a SELECT statement. Use the ASSIGN TO
clause to assign the file to a type of hardware.

•

Use the ORGANIZATION IS clause to define the organization of the file as
indexed. For documentation, define the organization explicitly (ORGANIZATION
IS INDEXED).

•

Use the ACCESS MODE IS clause to define the access mode the program uses
to access the file. The access mode can be sequential, random, or dynamic.

•

Required: Use the RECORD KEY IS clause to define the primary key for an
indexed file.

•

Optional: Use the ALTERNATE RECORD KEY IS clause to define any alternate
keys for an indexed file.

•

If the program monitors the status of the file, define a variable to receive status
key values by using the FILE STATUS IS clause.

Detailed information on the FILE-CONTROL Paragraph is included in Section 3.
Data Division
FD in File Section

•

A valid file description entry (FD) must be defined for all indexed files.

•

All keys defined in the FILE-CONTROL paragraph must be fields in the record
declared in the 01 Record Description.

Detailed information on the FD is included in Section 4.
Variables in the Working-Storage Section : If the program monitors the status of a
file, you must define a data-name to receive status key values. This data-name must
be the same as the data-name in the FILE STATUS IS clause of the SELECT entry for
the file in the FILE-CONTROL paragraph of the Environment Division. Details on the
FILE STATUS IS clause are included under “FILE-CONTROL Paragraph” in Section 3.

8600 1518–307

12–25

File Organization Checklists

Procedure Division
CLOSE statement: Use Format 2 of the CLOSE statement. Detailed information on
the CLOSE statement is included in Section 6.
OPEN statement: The REVERSED, NO REWIND and EXTEND phrases of the OPEN
statement are not valid for indexed files. Details on the CLOSE statement are
included in Section 7.
READ statement

•

Use Format 1 of the READ statement for indexed files with sequential or
dynamic access mode.

•

Use Format 2 of the READ statement for indexed files with random access
mode.

Detailed information on the READ statement is included in Section 7.
START statement

•

Use the general format of the START statement for indexed files.

•

If the KEY phrase is specified, the data-name can reference two different
items. Refer to the syntax rules of the START statement for more
information.

Detailed information on the START statement is included in Section 8.
REWRITE statement

•

Use the general format of the REWRITE statement for indexed files.

•

There are specific rules for using the REWRITE statement on indexed files.
Refer to the syntax rules of the REWRITE statement for more information.

Detailed information on the REWRITE statement is included in Section 8.
WRITE statement: Use Format 2 of the WRITE statement for indexed files. Detailed
information on the WRITE statement is included in Section 8.

12–26

8600 1518–307

File Organization Checklists

Indexed File Program Example
This example uses an indexed file. The name of this program is IND-EXMPL, and it prints
a report of the current clients of a kennel grouped by color, breed, or name.
IDENTIFICATION DIVISION.
PROGRAM-ID.
IND-EXMPL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
A9.
OBJECT-COMPUTER.
A9.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT KENNEL-FILE ASSIGN TO DISK
ORGANIZATION IS INDEXED
ACCESS MODE IS RANDOM
RECORD KEY IS NAME
ALTERNATE RECORD KEY IS COLOR WITH DUPLICATES
ALTERNATE RECORD KEY IS BREED WITH DUPLICATES.
SELECT PRINT-FILE ASSIGN TO PRINTER.
DATA DIVISION.
FILE SECTION.
FD
KENNEL-FILE BLOCK CONTAINS 6 RECORDS
VALUE OF TITLE IS "KENNEL/RECORDS".
01
KENNEL-RECORD.
05 NAME
PIC X(12).
05 COLOR
PIC X(10).
05 BREED
PIC X(10).
05 PRICE
PIC 9999.99.
05 KENNEL
PIC X(10).
05 KENNEL-NUMBER
PIC 9999.
FD
PRINT-FILE.
01
PRINT-RECORD.
05 PRINT-ITEM
PIC X(12) OCCURS 6 TIMES INDEXED BY J.
05 PRINT-TRAIL
PIC X(8).
WORKING-STORAGE SECTION.
01
RED
PIC X(10)
VALUE IS "RED".
01
TAN
PIC X(10)
VALUE IS "SPOTTED".
01
BLACK
PIC X(10)
VALUE IS "BLACK".
01
EXPENSIVE
PIC 999V99
VALUE IS 800.00.
01
CHEAP
PIC X(10)
VALUE IS "CHEAP".
01
NO-SALE
PIC X(10)
VALUE IS "NO SALE".
01
INDEX-TYPE
PIC X(10) DISPLAY.

8600 1518–307

12–27

File Organization Checklists

PROCEDURE DIVISION.
SECTION-1 SECTION.
PROCEDURE-1.
OPEN OUTPUT KENNEL-FILE.
MOVE "OTTO" TO NAME.
MOVE
MOVE EXPENSIVE TO PRICE.
MOVE
MOVE 13 TO KENNEL-NUMBER.
MOVE
WRITE KENNEL-RECORD;
INVALID KEY DISPLAY "ERROR

"GOLDEN" TO COLOR.
BLACK TO KENNEL.
"COLLIE" TO BREED.
- PRIMARY KEY NOT UNIQUE".

MOVE "GERONIMO" TO NAME.
MOVE
MOVE 350.00 TO PRICE.
MOVE
MOVE 97 TO KENNEL-NUMBER.
MOVE
WRITE KENNEL-RECORD;
INVALID KEY DISPLAY "ERROR

RED TO COLOR.
"ANOTHER" TO KENNEL.
"RETRIEVER" TO BREED.

MOVE "CHARLIE" TO NAME.
MOVE
MOVE CHEAP TO PRICE.
MOVE
MOVE 01 TO KENNEL-NUMBER.
MOVE
WRITE KENNEL-RECORD;
INVALID KEY DISPLAY "ERROR
CLOSE KENNEL-FILE SAVE.

"WHITE" TO COLOR.
"NONE" TO KENNEL.
"MIXED" TO BREED.

- PRIMARY KEY NOT UNIQUE".

PROCEDURE-2.
*
This procedure opens the indexed file, reads
*
data by alternate keys, writes to a printer file.
OPEN I-O KENNEL-FILE. OPEN OUTPUT PRINT-FILE.
MOVE "RED" TO COLOR.
MOVE "COLOR" TO INDEX-TYPE.
READ KENNEL-FILE KEY IS COLOR
INVALID KEY PERFORM INVALID-READ-MARKER
NOT INVALID KEY PERFORM WRITE-OUT-RECORD.
MOVE "MIXED" TO BREED.
MOVE "BREED" TO INDEX-TYPE.
READ KENNEL-FILE KEY IS BREED
INVALID KEY PERFORM INVALID-READ-MARKER
NOT INVALID KEY PERFORM WRITE-OUT-RECORD.
MOVE "WHITE" TO COLOR.
MOVE "COLOR" TO INDEX-TYPE.
READ KENNEL-FILE KEY IS COLOR
INVALID KEY PERFORM INVALID-READ-MARKER
NOT INVALID KEY PERFORM WRITE-OUT-RECORD.
CLOSE KENNEL-FILE. CLOSE PRINT-FILE.
STOP RUN.
WRITE-OUT-RECORD.
MOVE SPACES TO PRINT-RECORD.
MOVE NAME TO PRINT-ITEM(1).

12–28

8600 1518–307

File Organization Checklists

MOVE COLOR TO PRINT-ITEM(2).
MOVE BREED TO PRINT-ITEM(3).
MOVE PRICE TO PRINT-ITEM(4).
MOVE KENNEL TO PRINT-ITEM(5).
MOVE KENNEL-NUMBER TO PRINT-ITEM(6).
WRITE PRINT-RECORD.
INVALID-READ-MARKER.
DISPLAY "ERROR - NO SUCH " INDEX-TYPE " IN FILE"
MOVE "INVALID RECORD ACCESS" TO PRINT-RECORD.

8600 1518–307

12–29

File Organization Checklists

12–30

8600 1518–307

Section 13
Tasking in COBOL85
Note: Although this section is not highlighted, all of the information is relative to Unisys
extensions to COBOL ANSI-85.
COBOL85 provides a tasking capability, which enables you to write programs that initiate
other programs. This section discusses the basic concepts of tasking, including:

•

Terminology used to describe programs and processes

•

A discussion of task attributes and task variables

•

The three conditions that affect interprocess relationships

•

A discussion of coroutines

•

The instructions for writing a COBOL85 program that initiates other programs

•

The definition of a critical block and information for preventing critical block exits

You should read Sections 1 and 2 of the Task Management Programming Guide before
you attempt to implement tasking in a COBOL85 program.

Programs and Processes
A program is a sequence of statements that are stored in a source file. When the source
file is compiled, an object code file is created. You can initiate an object code file by using
a variety of commands and statements. Initiation causes the system to start performing
the instructions in the object code file. At this point, the object code file is being
executed. The system reads and performs the instructions in the object code file without
altering the contents of the file.
A separate, dynamic entity called a process is initiated any time an object code file is
initiated. The process appears in the active system mix and reflects the current state of
the execution of the object code file. A process also stores information used by the
object code file and keeps track of which statement is currently being executed.

8600 1518–307

13–1

Task Attributes

Task Attributes
All processes possess specific characteristics such as a usercode, a mix number, a
priority, printer defaults, and so on. These characteristics are defined by the operating
system and are known as task attributes. Task attributes record or control many aspects
of process execution, including security, processor usage, memory usage, and I/O
activity.
Task attributes have a fixed meaning, but their values can vary. For example, the
USERCODE task attribute always indicates the person who owns a particular process.
However, one process might have a USERCODE value of JSMITH and another process
might have a USERCODE value of JANEDOE.
You can display the value of any task attribute, except string-type task attributes
(attributes whose values are characters strings), by using the DISPLAY statement. For
string-type task attributes, you must move the attribute into a data area with the MOVE
statement, and then display the value with the DISPLAY statement. Refer to the second
program example in the following Examples section.
Attributes with an implicit numeric class can be used in DISPLAY statements and in
place of any identifier in an arithmetic statement, except the receiving-field identifier.
You can determine the mnemonic value of a task attribute by using the task attribute in a
conditional expression. For details about conditional expressions, see Section 5.
In general, the types of task attributes and the values that are valid for them are shown in
the following table. For a complete list of task attributes and their possible values, refer
to the Task Attributes Programming Reference Manual.

Attribute Type

Values Accepted and Returned

String

Alphanumeric

Boolean

Numeric (or the value associated with a mnemonic)

Integer

Numeric (or the value associated with a mnemonic)

All other attributes types

Numeric identifier, literal, arithmetic expression, or
the value associated with a mnemonic

You can change the value of a task attribute by using the CHANGE statement in the
Procedure Division of your COBOL85 program.

13–2

8600 1518–307

Task Variables

Task Variables
Because the same task attributes are common to all processes, the system must be able
to determine which task attribute value belongs to which process. For example, every
process has a USERCODE task attribute. When a program assigns a value to the
USERCODE task attribute, the system must have some way to identify the process to
which you want to apply the new USERCODE value. The system can differentiate among
processes by using task variables.
A task variable is a name that you use to represent a particular process. The system
automatically provides several predeclared task variables. Two of these variables are
MYSELF and MYJOB. The MYSELF task variable refers to the process itself. The
MYJOB task variable refers to the independent process in a group of related dependent
processes—the process family. (For a discussion of familial relationships among
processes, refer to the Task Management Programming Guide.)
In a COBOL85 program, you create a task variable by declaring a data item in the Data
Division with the USAGE IS TASK clause. You can associate a task variable with a
particular process by specifying the task variable in the program initiation statement
(either CALL, PROCESS, or RUN) in the Procedure Division. After the program is initiated,
the task variable is associated with the resulting process. For details about using task
variables in program initiation statements, refer to Format 6 of the CALL statement, the
PROCESS statement, or the RUN statement.
When a mnemonic value is referenced in a context that is not associated with any of the
task attribute mnemonic identifiers, then it is treated as a signed numeric constant.
The following program fragment sets the BDBASE option of the OPTION task attribute.
Note that the mnemonic value BDBASE is used as a destination bit location in this case.
Specific options of the OPTION task attribute can be accessed by using mnemonic
identifiers. The mnemonic identifiers represent specific bits in the OPTION word. One
way to access these bits is to use the Format 3 MOVE statement.
WORKING-STORAGE SECTION.
01 OPTION-WORD PIC 9(11) BINARY.
01 VALUE-ONE
PIC 9(11) BINARY VALUE 1.
PROCEDURE DIVISION.
OPTION-TEST.
MOVE ATTRIBUTE OPTION OF MYSELF TO OPTION-WORD.
MOVE VALUE-ONE TO OPTION-WORD [0:VALUE BDBASE:1].
CHANGE ATTRIBUTE OPTION OF MYSELF TO OPTION-WORD.

8600 1518–307

13–3

Interprocess Relationships

Interprocess Relationships
The type of relationship a process has with the process that initiated it depends upon
whether the initiated procedure

•

Exists internally or externally to the initiator

•

Relies on the continued existence of its initiator

•

Runs in parallel with the initiator or takes turns

The following subsections describe the way processes behave in each situation.

Internal Processes
An internal process results from the initiation of an internal procedure. A COBOL85
program cannot initiatean internal procedure.

External Processes
An external process results from the initiation of an external procedure. External
procedures are separate programs that exist outside the main program.
External processes do not inherit task attribute values.
COBOL85 programs can initiate separate programs by using the CALL, PROCESS, and
RUN statements.

Synchronous and Asynchronous Processes
Another condition that affects process relationships is the way the process shares the
processor. That is, does it take turns executing with the other process (synchronous
processing), or does it run in parallel with the other process (asynchronous processing).
Both situations are discussed in the following paragraphs.
Synchronous Processes
A COBOL85 program can initiate a synchronous process by using the CALL statement.
When a synchronous process is initiated, the initiating process stops executing and the
new process begins executing. The initiating process is still considered active during this
period and its process stack still exists. When the initiated process terminates, the
initiating process begins executing again, starting with the first executable statement
after the process initiation statement.

13–4

8600 1518–307

Interprocess Relationships

The initiating program can set the attributes of a synchronous process only at initiation
time and can interrogate the attributes only after the synchronous process has
terminated.
Synchronous processes are sometimes referred to as coroutines, but more properly the
term coroutine has a different use. For details, refer to “Coroutines” later in this section.
Asynchronous Processes
A COBOL85 program can initiate an asynchronous process by using either the PROCESS
or the RUN statement.
When an asynchronous process is initiated, the new process and the initiator execute in
parallel. Although they execute at the same time, they do not necessarily execute at the
same speed. It is for this reason that the new process is called asynchronous.
The initiating process can read or assign the task attributes of an asynchronous process
while the process is executing.
When you initiate an asynchronous process, you must take special measures to prevent
a critical blockexit error from occurring. For details, refer to the discussion of “Preventing
Critical Block Exits” later in this section.
Note that initiating processes asynchronously can create ambiguous timing situations
because it is impossible to predict exactly how long a process will take to execute. To
assist you in regulating the timing of asynchronous processes, you can use events, locks,
and interrupt procedures. For an overview of these mechanisms, refer to the Task
Management Programming Guide.
For information about establishing events in COBOL85, refer to the USAGE clause in
Section 4 , the ATTACH, CAUSE, and DETACH statements in Section 6, the RESET
statement in Section 7, and WAIT statement in Section 8.
For information about establishing locks in COBOL85, refer to the USAGE clause in
Section 4, the LOCK statement in Section 7, and the UNLOCK statement in Section 8.
For information about establishing interrupt procedures in COBOL85, refer to the ALLOW
and DISALLOW statements in Section 6 and the USE and WAIT statements in Section 8.

8600 1518–307

13–5

Interprocess Relationships

Dependent and Independent Processes
The final condition that affects interprocess relationships is dependency. The concept of
dependency involves two related concepts: critical objects and parents.
Critical objects are items that are declared by one process and used by another process,
such as the task variable and parameters. When a process is initiated, it receives these
critical objects from the initiator (also called the parent). Dependency is the relationship
between a process and its parent process, which determines how the system stores the
critical objects.
When an independent process is initiated, the system creates a separate copy of the
critical objects for the new process to use. As a result, the independent process can
continue executing if the parent process terminates.
The COBOL85 RUN statement initiates an independent process. An independent
process is sometimes referred to as a job.
When a dependent process is initiated, the system creates references to the objects
stored by the parent. Because of the sharing of the critical objects, a dependent process
relies on the continued existence of its parent.
The COBOL85 CALL statement initiates a dependent, synchronous process, and the
PROCESS statement initiates a dependent, asynchronous process. A dependent process
is sometimes referred to as a task.
The dependency of a process remains the same throughout execution. If the process is
initiated as dependent, it cannot later become independent or vice versa.

Details about Process Dependency
Observe the following details when planning the execution of dependent and
independent processes. For an expanded discussion of the effects of dependency on
processes, refer to the Task Management Programming Guide.
Independent Processes

13–6

•

Only external processes that result from the initiation of separate programs can be
independent.

•

An independent process is always asynchronous.

•

Parameters passed to an independent process can be passed only by value.

•

The task variable for an independent process ceases to be associated with the
parent once the independent task is initiated.

8600 1518–307

Interprocess Relationships

Dependent Processes

•

A dependent process is asynchronous if it is initiated with the PROCESS statement,
or synchronous if it is initiated with the CALL statement.

•

Parameters passed to a dependent process can be passed by reference or by value.

•

The task variable for a dependent process remains associated with the parent for as
long as the parent exists.

8600 1518–307

13–7

Coroutines

Coroutines
The term coroutines refers to a group of processes that exist simultaneously but take
turns executing, so that only one of the processes is executing at any given time. Every
synchronous process is a coroutine. However, not every coroutine is a synchronous
process. Unlike synchronous processes, which are terminated when exited, control can
alternate between the parent process and the coroutine.
The use of coroutines offers the following benefits:

•

The ability to execute a procedure repeatedly without incurring the processor time
required to enter or initiate the procedure each time.

•

The ability to execute a procedure repeatedly without losing the values of objects
declared in the procedure between each execution.

You can implement coroutines in your COBOL85 program by using the CALL,
CONTINUE, and EXIT PROGRAM statements. These statements perform the following
functions:

Statement

Location

Function

CALL

Calling program

Initiates a dependent
process

EXIT PROGRAM

Called program

Causes control to be
returned to the parent

CONTINUE

Calling program

Returns control to the
dependent process

For details about the CALL, CONTINUE, and EXIT PROGRAM statements, refer to the
discussion of each statement in Section 6 of this manual. For more information about
coroutines, refer to the Task Attributes Programming Reference Manual.

13–8

8600 1518–307

Structuring a Program to Initiate Processes

Structuring a Program to Initiate Processes
Writing a COBOL85 program that initiates a separate process requires you to
programmatically perform the functions described in the following table.

Function to Perform

Division

Name the object code file to be executed as a process

Environment or
Data Division

Describe any parameters to be passed between the two
programs

Data Division

Declare a task variable

Data Division

Associate parameters with the called program

Procedure Division

Declare the name of the external program to be used as the
procedure

Procedure Division

Change task attribute values as necessary

Procedure Division

Choose the appropriate program initiation statements

Procedure Division

Environment Division
You can specify the name of the external program to be executed in the Special-Names
paragraph of the Environment Division. The format for this specification is as follows:
ENVIRONMENT DIVISION.
SPECIAL-NAMES.
"OBJECT/TESTPROG" IS TESTPROG.
This format uses the “literal IS mnemonic-name” format. OBJECT/TESTPROG is the
literal name of the object code file. TESTPROG is the mnemonic-name by which you
refer to the object code file. You use the mnemonic-name that you assign in this division
in the USE EXTERNAL phrase of the Declaratives Section of the Procedure Division.

8600 1518–307

13–9

Structuring a Program to Initiate Processes

Data Division
In this division you

•

Name the object program to be executed (alternate method)

•

Declare the task variable

•

Describe parameters in the called program that are to be passed between programs

•

Describe parameters in the calling program that are to be passed between programs

Naming the Program to Be Executed (Alternate Method)
You can name the external program that is to be executed by declaring the program as a
data item in the Working-Storage Section of the Data Division. You can use the VALUE
clause with the declaration as shown in the following example:
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TESTPROG

PIC X(15) VALUE IS "OBJECT/TESTPROG".

You use the data item you declared in this division in the USE EXTERNAL phrase in the
Declaratives Section of the Procedure Division.
For details about describing data in the Data Division, refer to Section 4 of this manual.

Declaring the Task Variable
To declare a task variable, define a 77-level data item or a 01-level or subordinate data
item in the Working-Storage Section of the Data Division with the USAGE IS TASK
clause.
If you specify the USAGE IS TASK clause for a group item, all the elementary items in
the group are task variables. The group itself is not a task variable. A group item thus
defined can be used only in the USING phrase of the CALL statement Format 4 (for
binding), CALL statement Format 6 (for tasking), the PROCESS statement, and the RUN
statement.
An example of the syntax used for declaring a task variable is as follows:
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TASK-VAR-1

USAGE IS TASK.

You use the task variable you define here with one of the program initiation statements
in the Procedure Division. Doing so associates the task variable with the initiated
process. You can dissociate a task variable from a process by using the DETACH
statement.
For details on describing data in the Working-Storage Section, see Section 4 of this
manual.

13–10

8600 1518–307

Structuring a Program to Initiate Processes

Describing the Formal Parameters in the Called Program
Parameters in the called program that are to be used as references by both programs
must be described in the Linkage Section of the Data Division of the called program. The
data names you describe here are used as references to formal parameters in the
Procedure Division Header.
An example of this syntax is as follows:
DATA DIVISION.
LINKAGE SECTION.
01 RECEIVE-STRING
01 RECEIVE-NUMBER

PIC X(6)
PIC S9(22) COMP.

These parameters are received by the called program for use in its Procedure Division
statements.
For details on describing data items in the Linkage Section, see Section 4 of this manual.

Describing the Formal Parameters in the Calling Program
Parameters in the calling program that are to be referenced by both the calling and the
called programs must be described in the Local-Storage Section of the Data Division of
the calling program. The data items you describe here are referenced as formal
parameters in the USE EXTERNAL statement in the Declaratives Section of the
Procedure Division. An example of this syntax is as follows:
DATA DIVISION.
LOCAL-STORAGE SECTION.
LD PARAMS.
01 FORMAL-STRING
01 FORMAL-NUMBER

PIC X(6).
PIC S9(11) COMP.

These formal parameters are compared to the actual parameters specified in the process
initiation statement (CALL, PROCESS, or RUN) of the calling program.
For details on describing data items in the Local-Storage Section, see Section 4 of this
manual.

8600 1518–307

13–11

Structuring a Program to Initiate Processes

Describing the Actual Parameters in the Calling Program
Parameters in the calling program that are to be sent to the called program must be
described in either the Working-Storage or the Linkage Section in the Data Division of the
calling program. The data items you describe here are specified in the process initiation
statement (CALL, PROCESS, or RUN) in the Procedure Division. These data items are
also compared to the formal parameters referenced in the USE EXTERNAL statement in
the Declaratives portion of the Procedure Division. An example of this syntax is as
follows:
DATA DIVISION.
WORKING-STORAGE SECTION.
01 SEND-STRING
01 SEND-NUMBER

PIC X(6).
PIC S9(11) COMP.

These actual parameters are sent from the calling program to the called program.

Procedure Division
In this division, you

•

Associate parameters with the called program.

•

Declare the name of the external program and any parameters it references.

•

Change task attribute values.

•

Specify the process initiation statement.

•

Specify the EXIT PROGRAM statement and the CONTINUE statement for
coroutines.

•

Dissociate a task variable from a process.

Procedure Division Header in the Called Program
You must begin the Procedure Division of the called program with a header that names
the identifiers that the called process is to receive as parameters. The identifiers you use
in this header must be defined in the Linkage Section of the Data Division. An example of
this syntax is as follows:
PROCEDURE DIVISION USING RECEIVE-STRING, RECEIVE-NUMBER.

13–12

8600 1518–307

Structuring a Program to Initiate Processes

Declaratives Section
You must declare the name of the external program to be executed with a USE
EXTERNAL statement. A section-name must precede the USE EXTERNAL statement.
The object code file name is either the mnemonic name you defined in the SpecialNames paragraph of the Environment Division or the name you declared in the WorkingStorage Section of the Data Division. An example of this syntax is as follows:
PROCEDURE DIVISION.
DECLARATIVES SECTION.
EXTERNAL-PROG SECTION.
USE EXTERNAL TESTPROG AS PROCEDURE WITH PARAMS
USING FORMAL-STRING, FORMAL-NUMBER.
END DECLARATIVES.
The USE EXTERNAL phrase can also reference the parameters described in the LocalStorage Section of the Data Division. For details about the USE statement, refer to
Section 8 of this manual.

Changing Task Attribute Values
You can include a CHANGE statement anywhere after the Declaratives Section to
change the value of a task attribute. For details about the CHANGE statement, refer to
Section 6 of this manual. For a description of the task attributes and their default values,
refer to the Task Attributes Programming Reference Manual.

Initiating External Procedures
You can initiate an external procedure by using one of the statements as follows:

Use the . . .

To initiate a program as . . .

CALL statement

A synchronous, dependent process.

PROCESS statement

An asynchronous, dependent process.

RUN statement

An asynchronous, independent process.

An example of this syntax follows:
CALL TASK-VAR-1 WITH EXTERNAL-PROG
USING SEND-STRING, SEND-NUMBER.
For details about these program-initiation statements, refer to Sections 6 through 8.

8600 1518–307

13–13

Structuring a Program to Initiate Processes

Implementing Coroutines
You can implement coroutines by using the CALL, CONTINUE, and EXIT PROGRAM
statements. The CALL statement creates a synchronous task that is an active coroutine
and changes the parent process into a continuable coroutine. The task can return control
to its parent by executing an EXIT PROGRAM statement. The parent can return control
to its task by executing a CONTINUE statement.
The EXIT PROGRAM statement, in addition to transferring control to the parent, also
specifies the place where execution resumes when the parent later continues the task.
The simple form EXIT PROGRAM specifies that the task resumes from the beginning.
The EXIT PROGRAM RETURN HERE form specifies that the task resumes with the
statement that follows the EXIT PROGRAM statement.
For details about the CALL, CONTINUE, and EXIT PROGRAM statements, refer to
Section 6 of this manual.

Dissociating a Task Variable from a Process
When a task variable is used in a CALL, PROCESS, or RUN statement, the variable is
associated with the process initiated by that statement. To dissociate the task variable
from the process, you can use the DETACH statement. For details about using the
DETACH statement, refer to Section 6 of this manual.

Examples of Declaring the Object Code File Name of the Called
Program
The following example shows how you can declare the name of the object code file by
changing the NAME attribute of the task variable with the CHANGE statement before
using the CALL statement.
IDENTIFICATION DIVISION.
PROGRAM-ID. CALL-TASK-CALLER.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 DEP-TASK TASK.
PROCEDURE DIVISION.
DECLARATIVES.
INITIATE-PROCESS SECTION.
USE EXTERNAL AS PROCEDURE.
END DECLARATIVES.
MAIN SECTION.
MAIN-PARA.
CHANGE ATTRIBUTE NAME OF DEP-TASK TO "OBJECT/C85/CALLED".
CALL DEP-TASK WITH INITIATE-PROCESS.
STOP RUN.

13–14

8600 1518–307

Structuring a Program to Initiate Processes

The next example shows how you can declare the object code file name of the called
program by declaring a mnemonic name in the Special-Names paragraph of the
Environment Division and then using it in the USE EXTERNAL statement in the
Declaratives. In this example, the object code file is titled OBJECT/C85/CALLED, and the
mnemonic to which it is assigned is TASK-ID.
IDENTIFICATION DIVISION.
PROGRAM-ID. CALL-TASK-CALLER.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
"OBJECT/C85/CALLED" IS TASK-ID.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 DEP-TASK TASK.
PROCEDURE DIVISION.
DECLARATIVES.
INITIATE-PROCESS SECTION.
USE EXTERNAL TASK-ID AS PROCEDURE.
MAIN SECTION.
MAIN-PARA.
CALL DEP-TASK WITH INITIATE-PROCESS.
STOP RUN.

Example of Passing Control between Two Programs
The calling program initiates the program OBJECT/C85/CALLED as a separate process
and contains statements to pass control between the calling and the called program.
he object code file name of the called program is declared in the calling program by
1. The definition of a data item in the Working-Storage Section
2. The inclusion of that data item in the USE EXTERNAL statement in the Declaratives
of the Procedure Division
3. The assignment of an object code file title to the data item by the use of a MOVE
statement in the Procedure Division

8600 1518–307

13–15

Structuring a Program to Initiate Processes

Calling Program
IDENTIFICATION DIVISION.
PROGRAM-ID. CALL-TASK-CALLER.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 TASK-SUB
PIC 9 VALUE 4.
01 DEP-TASK-ARRAY
TASK.
05 DEP-TASK
OCCURS 5 TIMES.
77 WS-PROGID
PIC X(40).
PROCEDURE DIVISION.
DECLARATIVES.
RUN-A-PROCESS SECTION.
USE EXTERNAL WS-PROGID AS PROCEDURE.
END DECLARATIVES.
MAIN SECTION.
MAIN-PARA.
MOVE "OBJECT/C85/CALLED." TO WS-PROGID.
CALL DEP-TASK (TASK-SUB) WITH RUN-A-PROCESS.
DISPLAY "CONTINUE " WS-PROGID.
CONTINUE DEP-TASK (TASK-SUB).
DISPLAY "FINAL RETURN " WS-PROGID.
DETACH DEP-TASK (TASK-SUB).
WAIT-HERE.
IF ATTRIBUTE STATUS OF DEP-TASK(TASK-SUB) > VALUE
(TERMINATED) THEN
WAIT AND RESET
UNTIL ATTRIBUTE EXCEPTIONEVENT OF MYSELF
GO TO WAIT-HERE.
STOP RUN.
In the preceding program, a group of task variables is declared in the Working-Storage
Section. These task variables share the name DEP-TASK. The system distinguishes them
logically by number, DEP-TASK 1, 2, 3, and so on. A task variable subscript is declared as
a data item named TASK-SUB, and the value of 4 is assigned to it. A task variable is used
with a subscript to indicate which specific task variable of a group is to be used, in this
case DEP-TASK 4.
The called program, OBJECT/C85/CALLED, is initiated by the calling program.

13–16

8600 1518–307

Structuring a Program to Initiate Processes

Called Program
IDENTIFICATION DIVISION.
PROGRAM-ID. CALL-TASK-CALLED.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 MY-NAME
PIC X(45).
PROCEDURE DIVISION.
MAIN SECTION.
MAIN-PARA.
MOVE ATTRIBUTE NAME OF MYSELF TO MY-NAME.
DISPLAY MY-NAME " WAS CALLED".
EXIT PROGRAM RETURN HERE.
DISPLAY MY-NAME " CALLED AGAIN".
EXIT PROGRAM.
STOP RUN.
The transfer of control between these two programs occurs in the following sequence:
1. The calling program executes the statement CALL DEP-TASK (TASK-SUB) WITH
RUN-A-PROCESS.
2. The called program begins execution at the MOVE statement and continues
executing until it reaches the first EXIT PROGRAM statement.
3. Upon execution of the EXIT PROGRAM statement in the called program, control is
returned to the statement following the CALL statement in the calling program,
which is DISPLAY “CONTINUE” WS-PROGID.
4. After executing the DISPLAY statement, the calling program executes a CONTINUE
statement, and control is returned to the second DISPLAY statement in the called
program: DISPLAY MY-NAME “CALLED AGAIN”.
5. After executing the DISPLAY statement, the called program executes an EXIT
PROGRAM statement, and control is returned to the second DISPLAY statement in
the calling program (DISPLAY “FINAL RETURN” WS-PROGID) without executing the
STOP RUN in the called program.
6. After executing the DISPLAY statement, the calling program executes a DETACH
statement to dissociate the called process from the task variable. The status
attribute of the process attached to the task variable is updated to TERMINATED,
and the process is discontinued.
7. To prevent a critical block exit, the calling program cannot terminate before the called
program. So that this does not occur, the calling program executes a WAIT
statement with the condition that if the status of DEP-TASK is not updated to
terminated, the calling program waits until its own EXCEPTIONEVENT attribute is
been caused. Then it returns to WAIT-HERE. When the attribute of DEP-TASK is
equal to –1 (a status of TERMINATED), the calling program executes its STOP RUN
statement and ceases to execute.
Because the called program does not execute its STOP RUN statement, the DETACH
statement is used to dissociate a called process from its task variable. If the calling
program contains no DETACH statement, the calling program would execute its STOP
RUN statement and terminate, causing a critical block exit error.

8600 1518–307

13–17

Preventing Critical Block Exits

Preventing Critical Block Exits
A critical block is a block that includes the definition of the critical objects that are to be
passed from the initiating process to the initiated process. The critical objects include
task variables and parameters to be passed.
The process that executes the critical block is considered to be the parent of any process
it initiates. All processes initiated by the parent are considered to be offspring of that
parent. If the parent exits the critical block while a dependent process is in use, the error
message “CRITICAL BLOCK EXIT” is displayed. The parent process is terminated and all
offspring are discontinued.
To prevent a critical block exit error, you can include statements such as the following to
check for termination of dependent processes before terminating your program:
PROCWAIT SECTION.
P2.
WAIT AND RESET UNTIL ATTRIBUTE EXCEPTIONEVENT OF MYSELF.
IF ATTRIBUTE STATUS OF TASK-VAR-1 IS GREATER THAN
VALUE TERMINATED THEN GO PROCWAIT.
STOP RUN.
The preceding example assumes that an asynchronous offspring was initiated by using
the task variable TASK-VAR-1. The COBOL85 program waits on its own
EXCEPTIONEVENT task attribute, which is automatically caused whenever the offspring
changes status. The program then checks the status of the offspring and returns to a
waiting state if the offspring has not yet terminated.

13–18

8600 1518–307

Section 14
Report Writer
This section explains how to use Report Writer, which is a special-purpose language
subset of COBOL that enables you to produce reports.

Overview
Report Writer enables you to specify the physical appearance of a report, rather than
requiring specification of the detailed procedure necessary to produce that report.
A hierarchy of levels is used in defining the logical organization of a report. Each report is
divided into report groups, which in turn are divided into sequences of items. This
hierarchical structure enables explicit reference to a report group with implicit reference
to other levels in the hierarchy. A report group contains one or more items to be
presented on zero, one, or more lines.
For each report group, you must define an output file, called the report file, with a
sequential file organization. A report file has a file description entry containing a REPORT
clause. The content of a report file consists of records that are written under control of
the report writer control system (RWCS). The structure of a report file is defined in the
File Section of the Data Division. A report file differs from a regular sequential file in the
following two ways:

•

A REPORT clause is associated with a report file.

•

Record description entries cannot follow the file description entry for a report file.

A report file is referred to and accessed by the following statements:

•

OPEN

•

GENERATE

•

INITIATE

•

SUPPRESS

•

TERMINATE

•

USE AFTER STANDARD EXCEPTION PROCEDURE

•

USE BEFORE REPORTING

•

8600 1518–307

14–1

File Section

File Section
The File Section defines the structure of data files. When you use Report Writer, the File
Section defines the structure of report files. You define each report file by a file
description entry containing a REPORT clause.

REPORT Clause
The REPORT clause specifies the names of reports that make up a report file.

ä REPORT IS
å
ã ïïïïïï
â
æ REPORTS ARE ç
ïïïïïïï

{ report-name-1 } ...

REPORT IS
REPORTS ARE

These keywords indicate the number of reports in a file.
report-name-1

Each report-name specified in a REPORT clause must be the subject of a reportdescription entry in the Report Section. The order of appearance of the report-names is
not significant. A report-name must appear in only one REPORT clause.
In the Procedure Division, you can reference the subject of a file-description entry that
specifies a REPORT clause only by the USE statement, the CLOSE statement, or the
OPEN statement with the OUTPUT or EXTEND phrase.
Details
The presence of more than one report-name in a REPORT clause indicates that the file
contains more than one report.
After execution of an INITIATE statement and before the execution of a TERMINATE
statement for the same report file, the report file is under the control of the report writer
control system (RWCS). While a report file is under the control of RWCS, you cannot
execute any input-output statement that references a report file.
If the associated file connector is an internal file connector, each file description entry in
the run unit that is associated with that file connector must describe it as a report file.

14–2

8600 1518–307

Report Section

Report Section
You must describe, in the Report Section, the format of each report named in the
REPORT clause of a file description entry. The Report Section is located in the Data
Division of a source program (refer to Section 4, “General Format of the DATA
DIVISION,” for proper placement). The Report Section consists of the following two
components:

•

A report description entry

•

A report-group description entry

Both of these components are described in the following pages.

Report Description Entry
The report description entry contains information pertaining to the overall format and
structure of a report named in the File Section. It is uniquely identified in the Report
Section by the level indicator RD.
RD report-name-1
[
Ú
³
³
³
À
Ú
³
³
³
À

CODE literal-1 ]
ïïïï
ä CONTROL IS
å
ã ïïïïïïï
â
æ CONTROLS ARE ç
ïïïïïïïï
Ú
PAGE ³ LIMIT IS
ïïïï ³ LIMITS ARE
À

ä FINAL [ data-name-1 ] ...
ã ïïïïï
æ { data-name-1 } ...
¿
Ú
³ integer-1 ³ LINE
³
³ LINES
Ù
À

¿
å ³
â ³
ç ³
Ù

¿
³
³
Ù

[ HEADING integer-2 ]
ïïïïïïï
[ FIRST DETAIL integer-3 ]
ïïïïïïïïïïïï
[ LAST DETAIL integer-4
ïïïïïïï
[ FOOTING integer-5 ]
ïïïïïïï

]
¿
³
³
³
Ù

The level indicator RD (report description) identifies the beginning of a report description
and must precede the report-name.

8600 1518–307

14–3

Report Description Entry

report-name-1

This is a user-defined name assigned to the report. This must appear in only one
REPORT clause.
Details
The clauses that follow the report-name are optional, and the order of appearance is not
significant. These clauses are the CODE clause, the CONTROL clause, and the PAGE
clause. Each of these clauses is discussed in turn in the pages that follow.
Report-name is the highest permissible qualifier that you can specify for LINE-COUNTER,
PAGE-COUNTER, and all data-names defined in the Report Section. Refer to “Special
Counters” in this section for descriptions of LINE-COUNTER and PAGE-COUNTER.

CODE Clause
The CODE clause specifies a two-character literal that identifies each print line as
belonging to a specific report.

CODE literal-1
ïïïï

Literal-1

Literal-1 must be a 2-character nonnumeric literal.
Details
If you specify the CODE clause for any report in a file, it must be specified for all reports
in that file.
When you specify the CODE clause, literal-1 is automatically placed in the last two
character positions of each generated report.
The positions occupied by literal-1 are not included in the description of the print line, but
are included in the size of a logical record.
If more than one report is associated with a file and the reports are produced
simultaneously, you can use the CODE clause literal to select a report to be printed
individually from the WFL PB statement. The system printer-backup routine will look for
printer backup files with BDREPORT as the filename prefix, and then print the report
indicated by the CODE literal you specify. To take advantage of this you must set
BDNAME before opening the file to write to it. Once BDNAME is set, all printer files that
the program opens will use the BDREPORT prefix. If you need to open a printer file with
the default BDNAME, then you must reset BDNAME to null before opening it.

14–4

8600 1518–307

Report Description Entry

Use the CHANGE statement to set and reset BDNAME in the program. CHANGE
ATTRIBUTE BDNAME OF MYSELF TO "BDREPORT" sets it. CHANGE ATTRIBUTE
BDNAME OF MYSELF TO "." resets it. With BDNAME set to BDREPORT, either of the
two following statements can be used to print a report, based upon its CODE literal:
PB D job-number KEY REPORT EQUAL literal-1.
PB D * KEY REPORT EQUAL literal-1.
Job-number is the mix number of the job that created the report. Literal-1 is the CODE
clause literal specified in the CODE clause for the report. The asterisk (*) indicates that
the job number is that of the WFL job itself. The asterisk function is useful when a PB
(Printer Backup) statement is included in a WFL statement that both creates and prints
the report. For further details on the use of PB, please refer to Section 3, “The
SYSTEM/BACKUP Utility” of the Printing Utilities Operations Guide (8600 0692).

CONTROL Clause
The CONTROL clause establishes the level of the control hierarchy for the report.

ä
ã
æ

CONTROL IS
ïïïïïïï
CONTROLS ARE
ïïïïïïïï

å
â
ç

ä
ã
æ

FINAL [ data-name-1 ] ...
ïïïïï
{ data-name-1 } ...

å
â
ç

data-name-1

The data-name must not be defined in the Report Section. You can qualify the dataname, however, you cannot subscript or index the data-name.
Each data-name must identify a different data item.
Data-name-1 must not have subordinate variable-occurrence data items. Control data
items are subject to the same rules that apply to SORT keys.
FINAL
data-name-1

The FINAL keyword and the data-names specify the level of the control hierarchy. FINAL
is the highest control. Data-name-1 is the major control. The next recurrence of dataname-1 is an intermediate control, and so on. The last recurrence of data-name-1 is the
minor control.
Details
The CONTROL clause is required when you use control heading or control footing
groups. The data-names specified in the CONTROL clause are the only data-names
referred to by the RESET and TYPE clauses in the report-group descriptions for a report.
You cannot reference a data-name, including FINAL, by more than one type-controlheading report group and one type-control-footing report group.

8600 1518–307

14–5

Report Description Entry

The execution of the first chronological GENERATE statement for a report causes the
values of all control data items associated with that report to be saved. On subsequent
executions of all GENERATE statements for that report, control data items are tested for
a change of value. A change of value in any control data item causes a control break to
occur. The control break is associated with the highest level for which a change of value
is noted.
A test for a control break is made by comparing the contents of each control data item
with the prior contents saved from the execution of the previous GENERATE statement
for the same report.
The relation test is applied as follows:
1. If the control data item is a numeric data item, the relation test is for the comparison
of two numeric operands.
2. If the control data item is an index data item, the relation test is for the comparison
of two index data items.
3. If the control data item is a data item other than those described in items 1 and 2
above, the relation test is for the comparison of two nonnumeric operands.
A control break for FINAL occurs before the first detail line is printed and whenever a
TERMINATE statement is executed. A control break occurring at a particular level implies
a control break for each lower level in the control hierarchy. For example, if you use the
CONTROL clause “CONTROLS ARE MAJ-KEY, INT-KEY, MIN-KEY”, and you specify
control headings and footings, they are printed in the following order on a control break
on MAJ-KEY:

14–6

CONTROL FOOTING

(for MIN-KEY)

CONTROL FOOTING

(for INT-KEY)

CONTROL FOOTING

(for MAJ-KEY)

CONTROL HEADING

(for MAJ-KEY)

CONTROL HEADING

(for INT-KEY)

CONTROL HEADING

(for MIN-KEY)

8600 1518–307

Report Description Entry

PAGE Clause
The PAGE clause defines the length of a page and the vertical subdivisions within which
report groups are presented.

PAGE
ïïïï

Ú
³ LIMIT IS
³ LIMITS ARE
À

¿
³
³
Ù

integer-1

[

HEADING integer-2
ïïïïïïï

[

FIRST DETAIL integer-3
ïïïïïïïïïïïï

[

LAST DETAIL integer-4
ïïïïïïïïïïï

[

FOOTING integer-5
ïïïïïïï

Ú
³
³
À

LINE
LINES

¿
³
³
Ù

]
]
]

]

LIMIT IS
LIMITS ARE

These keywords identify the number of lines on a page of a report.
LINE
LINES

These keywords indicate the number of lines on a page of a report.
integer-1

Integer-1 must not exceed three significant digits in length. Also, integer-1 must be
greater than or equal to integer-5.
integer-2

Integer-2 must be greater than or equal to one.
integer-3

Integer-3 must be greater than or equal to integer-2.
integer-4

Integer-4 must be greater than or equal to integer-3.
integer-5

Integer-5 must be greater than or equal to integer-4.

8600 1518–307

14–7

Report Description Entry

HEADING
FIRST DETAIL
LAST DETAIL
FOOTING

These phrases can be written in any order.
Rules for Placing Report Groups
The following rules indicate the vertical subdivision of the page in which each type of
report group can appear when you specify the PAGE clause:

•

If you define a REPORT HEADING report group that is presented on a page by itself,
then you must define the REPORT HEADING report group so that it is presented in
the vertical subdivision of the page that extends from the line number specified by
integer-2 to the line number specified by integer-1, inclusive.
If you define a REPORT HEADING report group that is not presented on a page by
itself, then you must define the REPORT HEADING report group so that it is
presented in the vertical subdivision of the page that extends from the line number
specified by integer-2 to the line number specified by integer-3 minus 1, inclusive.

•

If you define a PAGE HEADING report group, then you must define the PAGE
HEADING report group so that it is presented in the vertical subdivision of the page
that extends from the line number specified by integer-2 to the line number specified
by integer-3 minus 1, inclusive.

•

If you define a CONTROL HEADING or DETAIL report group, then you must define
the CONTROL HEADING or DETAIL report group so that they are presented in the
vertical subdivision of the page that extends from the line number specified by
integer-3 to the line number specified by integer-4, inclusive.

•

If you define a CONTROL FOOTING report group, then you must define the
CONTROL FOOTING report group so that it is presented in the vertical subdivision of
the page that extends from the line number specified by integer-3 to the line number
specified by integer-5, inclusive.

•

If you define a PAGE FOOTING report group, then you must define the PAGE
FOOTING report group so that it is presented in the vertical subdivision of the page
that extends from the line number specified by integer-5 plus 1 to the line number
specified by integer-1, inclusive.

•

If you define a REPORT FOOTING report group on a page by itself, then you must
define the REPORT FOOTING report group so that it is presented in the vertical
subdivision of the page that extends from the line number specified by integer-2 to
the line number specified by integer-1, inclusive.
If you define a REPORT FOOTING report group that is not presented on a page by
itself, then you must define the REPORT FOOTING report group so that it is
presented in the vertical subdivision of the page that extends from the line number
specified by integer-5 plus 1 to the line number specified by integer-1, inclusive.

You must describe all report groups so that they are presented on one page. A multiline
report group is never split across page boundaries.

14–8

8600 1518–307

Report Description Entry

Rules for Setting the Vertical Format
You establish the vertical format of a report page using the following integer values
specified in the PAGE clause:

•

Integer-1 defines the size of a report page by specifying the number of lines available
on each page.

•

HEADING integer-2 defines the first line number on which a REPORT HEADING or
PAGE HEADING report group is presented.

•

FIRST DETAIL integer-3 defines the first line number on which a body group is
presented. REPORT HEADING (without NEXT GROUP NEXT PAGE) and PAGE
HEADING report groups cannot be presented on or beyond the line number specified
by integer-3.

•

LAST DETAIL integer-4 defines the last line number on which a CONTROL HEADING
or DETAIL report groups is presented.

•

FOOTING integer-5 defines the last line number on which a CONTROL FOOTING
report group is presented. PAGE FOOTING and REPORT FOOTING report groups
must follow the line number specified by integer-5.

If absolute line spacing is indicated for all report groups, you do not need to specify
integer-2 through integer-5. If relative line spacing is indicated for individual detail report
groups entries, you must define some or all of the limits (depending on the type of report
groups within the report) for control of page formatting to be maintained.
Defaults
If you specify the PAGE clause, the following implicit values are assumed for any omitted
phrases:

•

If you omit the HEADING phrase, a value of one is assumed for integer-2.

•

If you omit the FIRST DETAIL phrase, a value equal to integer-2 is given to integer-3.

•

If you omit both the LAST DETAIL and the FOOTING phrases, the value of integer-1
is given to both integer-4 and integer-5.

•

If you specify the FOOTING phrase and you omit the LAST DETAIL phrase, the value
of integer-5 is given to integer-4.

•

If you specify the LAST DETAIL phrase and you omit the FOOTING phrase, the value
of integer-4 is given to integer-5.

If you omit the PAGE clause, the report consists of a single page of indefinite length.
Absolute line number or absolute NEXT GROUP spacing must be consistent with
controls specified in the PAGE LIMIT clause.

8600 1518–307

14–9

Report Description Entry

Figure 14–1 illustrates page format control of report groups when you specify the PAGE
LIMIT clause.

Figure 14–1. Page Format Control
Page regions established by the PAGE clause are depicted in Table 14–1.
Table 14–1. Page Regions Established by the PAGE Clause

Report Groups Presented in the Region

REPORT HEADING described with NEXT
GROUP NEXT PAGE

First Line Number
of the Region

Last Line
Number of the
Region

integer-2

integer-1

integer-2

integer-3

REPORT FOOTING described with LINE
integer-1 NEXT PAGE
REPORT HEADING not described with
NEXT GROUP NEXT PAGE

minus 1

PAGE HEADING
CONTROL HEADING

integer-3

integer-4

CONTROL FOOTING

integer-3

integer-5

PAGE FOOTING

integer-5

integer-1

REPORT FOOTING not described with
LINE integer-1 NEXT PAGE

plus 1

DETAIL

14–10

8600 1518–307

Special Counters

Special Counters
The following special counters are available for each report described in the Report
Section:

•

LINE-COUNTER

•

PAGE-COUNTER

LINE-COUNTER
LINE-COUNTER is a special register that is automatically created for each report where
you specify the PAGE LIMIT clause. If more than one LINE-COUNTER register exists in a
program, then you must qualify all references to LINE-COUNTER. In the Report Section,
an unqualified reference to LINE-COUNTER is implicitly qualified by the name of the
report in which the reference is made.
In the Report Section, a reference to LINE-COUNTER can appear only in a SOURCE
clause. Outside the Report Section, LINE-COUNTER can be used in any context in which
a data-name of integral value can appear. However, the content of LINE-COUNTER can
be changed only by RWCS.
Execution of an INITIATE statement causes the LINE-COUNTER register for that report
to reset to 0 (zero). LINE-COUNTER is also reset to 0 each time a page advance is
executed for the associated report.
After a report group is printed, the LINE-COUNTER register contains the line number on
which the last line of the report group was printed, unless the report group specifies the
NEXT GROUP clause. In that case, LINE-COUNTER contains 0 if you specify NEXT PAGE
or the line number.
For further information on line number positioning, refer to “LINE NUMBER Clause” and
“NEXT GROUP Clause” in this section.

8600 1518–307

14–11

Special Counters

PAGE-COUNTER
PAGE-COUNTER is a special register that is automatically created for each report that
you specify in the Report Section.
In the Report Section, a reference to PAGE-COUNTER can appear only in a SOURCE
clause. Outside the Report section, PAGE-COUNTER can be used in any context in which
a data-name of integral value can appear.
If more than one PAGE-COUNTER register exists in a program, you must qualify PAGECOUNTER by a report-name whenever it is referenced in the Procedure Division. In the
Report Section, an unqualified reference to PAGE-COUNTER is implicitly qualified by the
name of the report in which the reference is made, whenever you reference the PAGECOUNTER of a difference report. You must explicitly qualify PAGE-COUNTER by that
report-name.
Execution of the INITIATE statement causes the PAGE-COUNTER of the referenced
report to reset to 1.
You can alter PAGE-COUNTER by using Procedure Division statements. If you want a
starting value other than 1, change the contents of PAGE-COUNTER following the
INITIATE statement for that report.

14–12

8600 1518–307

Report-Group Description Entry

Report-Group Description Entry
One or more report groups follow each report description (RD) entry. Each group
describes one or more print lines related to a specific function in producing a report. A
report group is described by a hierarchical data structure similar to record descriptions in
the other sections of the Data Division.

Format

Use

Format 1

This format specifies the vertical positioning and type of the
report group.

Format 2

This format describes a single line of the report group.

Format 3

This format describes the single, printable items for a line,
and a line that contains only one printable item.

The report-group description entry can appear only in the Report Section. Integers must
be greater than 0.
The description of a report group can consist of one, two, or three hierarchical levels. The
first entry of a report group must be a Format 1 entry. A Format 2 entry must be followed
immediately by a Format 3 entry.

8600 1518–307

14–13

Report-Group Description Entry

Report-Group Description Entry Format 1
This format describes the vertical positioning and type of the report group.

01 [ data-name-1 ]
Ú
³
³
³
À
Ú
³
³
³
³
³
À

LINE NUMBER IS
ïïïï

NEXT GROUP IS
ïïïïïïïïïï

TYPE IS
ïïïï

[

14–14

ä
ã
æ
ä
³
ã
³
æ
ä
³
³
³
³
³
³
³
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
æ

integer-1

[ ON NEXT PAGE ]
ïïïïïïïï
PLUS integer-2
ïïïï
¿
integer-3
å
³
³
³
PLUS integer-4 â
³
ïïïï
³
³
NEXT PAGE
ç
³
ïïïïïïïïï
Ù
ä
ã
æ

REPORT HEADING
ïïïïïïïïïïïïïï
RH
ïï

å
â
ç

ä
ã
æ

PAGE HEADING
ïïïïïïïïïïïï
PH
ïï

å
â
ç

ä
ã
æ

CONTROL HEADING
ïïïïïïïïïïïïïïï
CH
ïï

å
â
ç

ä
ã
æ

DETAIL
ïïïïïï
DE
ïï

å
â
ç

ä
ã
æ

CONTROL FOOTING
ïïïïïïïïïïïïïïï
CF
ïï

å
â
ç

ä
ã
æ

PAGE FOOTING
ïïïïïïïïïïïï
PF
ïï

å
â
ç

ä
ã
æ

REPORT FOOTING
ïïïïïïïïïïïïïï
RF
ïï

å
â
ç

[ USAGE IS ]
ïïïïï

å
â
ç

¿
³
³
³
Ù

ä
ã
æ

data-name-2

ä
ã
æ

data-name-3

FINAL
ïïïïï

å
â
ç

å
³
³
³
³
³
³
³
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
ç

DISPLAY ]
ïïïïïïï

8600 1518–307

Report-Group Description Entry

01
The level-number 01 identifies the first entry in a report group. A level-number is required
as the first element in each data description entry. Data description entries subordinate
to an RD entry must have level-numbers 01 through 49 only.
data-name-1
This is a user-defined name of a data file. The data-name, if used, must follow a levelnumber. However, you can write the clauses following a data-name in any sequence.
You can reference data-name-1 of a Format 1 entry only in the following cases:

•

When a DETAIL report group is referenced by a GENERATE statement

•

When a DETAIL report group is referenced by the UPON phrase of a SUM clause

•

When a report group is referenced in a USE BEFORE REPORTING sentence

•

When the name of a CONTROL FOOTING report group is used to qualify a reference
to a sum-counter

LINE NUMBER Clause
The LINE NUMBER clause specifies vertical positioning information for its report group.

LINE NUMBER IS
ïïïï

ä
ã
æ

integer-1

[ ON NEXT PAGE ]
ïïïïïïïïï
PLUS integer-2
ïïïï

å
â
ç

integer-1
integer-2
Integer-1 and integer-2 must not exceed three significant digits in length. Integer-2 can
be zero.
You cannot specify integer-1 or integer-2 if any line of a report group is presented outside
the vertical page subdivision designated for that report group type, as defined by the
PAGE clause. Refer to “PAGE Clause” in this section for more information.
Integer-1 specifies an absolute line number. An absolute line number specifies the line
number on which the print line is printed.
Integer-2 specifies a relative line number. If you specify a relative LINE NUMBER clause,
the line number on which the print line is printed is determined by the sum of the line
number on which the previous print line of the report group was printed and integer-2 of
the relative LINE NUMBER clause.
ON NEXT PAGE
The ON NEXT PAGE phrase specifies that the report group is to be presented beginning
on the indicated line number on a new page.

8600 1518–307

14–15

Report-Group Description Entry

Details of LINE NUMBER Clause
You must specify the LINE NUMBER clause to establish each print line of a report group.
The vertical positioning specified by the LINE NUMBER clause occurs before the line
established by that LINE NUMBER clause is printed.
In a given report-group description entry, the following rules apply:

•

An entry that contains a LINE NUMBER clause must not contain a subordinate entry
that also contains a LINE NUMBER clause.

•

All absolute LINE NUMBER clauses must precede all relative LINE NUMBER
clauses.

•

Successive absolute LINE NUMBER clauses must specify integers in ascending
order. The integers do not need to be consecutive.

•

If you omit the PAGE clause, you can specify only relative LINE NUMBER clauses in
any report-group description entry in the report.

•

An ON NEXT PAGE phrase can appear only once. If present, this phrase must be in
the first LINE NUMBER clause. A LINE NUMBER clause with the ON NEXT PAGE
phrase can appear only in the description of body groups and in a REPORT FOOTING
report group.

Every entry that defines a printable item must either contain a LINE NUMBER clause or
be subordinate to an entry that contains a LINE NUMBER clause.
The first LINE NUMBER clause specified within a PAGE FOOTING report group must be
an absolute LINE NUMBER clause.
NEXT GROUP Clause
The NEXT GROUP clause specifies information for vertical positioning of a page following
the presentation of the last line of a report group.

NEXT GROUP IS
ïïïïïïïïïï

ä
³
ã
³
æ

integer-3
PLUS integer-4
ïïïï
NEXT PAGE
ïïïïïïïïï

å
³
â
³
ç

integer-3
integer-4
Integer-3 and integer-4 must not exceed three significant digits in length.

14–16

8600 1518–307

Report-Group Description Entry

NEXT PAGE
You must not specify the NEXT PAGE phrase of the NEXT GROUP clause in a PAGE
FOOTING report group.
Refer to the preceding discussion under “LINE NUMBER Clause” for more information
on the NEXT PAGE phrase.
Details of NEXT GROUP Clause
A report-group entry must not contain a NEXT GROUP clause unless the description of
the report group contains at least one LINE NUMBER clause.
If you omit the PAGE clause from the report description entry, you can specify only a
relative NEXT GROUP clause in any report-group description entry in that report.
You must not specify the NEXT GROUP clause in a REPORT FOOTING report group or in
a PAGE HEADING report group.
Any positioning of the page you specify using the NEXT GROUP clause takes place after
the report group in which the clause appears is printed.
The vertical positioning information supplied by the NEXT GROUP clause is interpreted
along with information from the TYPE and PAGE clauses and the value in LINECOUNTER to determine a new value for LINE-COUNTER.
The NEXT GROUP clause is ignored when you specify it on a CONTROL FOOTING report
group that is at a level other than the highest level at which a control break is detected.
The NEXT GROUP clause of a body group refers to the next body group to be printed,
and therefore can affect the location at which the next body group is printed. The NEXT
GROUP clause of a REPORT HEADING report group can affect the location at which the
PAGE HEADING report group is printed. The NEXT GROUP clause of a PAGE FOOTING
report group can affect the location at which the REPORT FOOTING report group is
printed.

8600 1518–307

14–17

Report-Group Description Entry

TYPE Clause
The TYPE clause specifies the particular type of report group described by the report
description entry and indicates the time at which the report group is to be processed.

TYPE IS
ïïïï

ä
³
³
³
³
³
³
³
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
æ

ä
ã
æ

REPORT HEADING
ïïïïïïïïïïïïïï
RH
ïï

å
â
ç

ä
ã
æ

PAGE HEADING
ïïïïïïïïïïïï
PH
ïï

å
â
ç

ä
ã
æ

CONTROL HEADING
ïïïïïïïïïïïïïïï
CH
ïï

å
â
ç

ä
ã
æ

DETAIL
ïïïïïï
DE
ïï

å
â
ç

ä
ã
æ

CONTROL FOOTING
ïïïïïïïïïïïïïïï
CF
ïï

å
â
ç

ä
ã
æ

PAGE FOOTING
ïïïïïïïïïïïï
PF
ïï

å
â
ç

ä
ã
æ

REPORT FOOTING
ïïïïïïïïïïïïïï
RF
ïï

å
â
ç

ä
ã
æ

data-name-2

ä
ã
æ

data-name-3

FINAL
ïïïïï

å
â
ç

å
³
³
³
³
³
³
³
³
³
³
³
³
³
³
â
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³
ç

REPORT HEADING

The REPORT HEADING phrase specifies a report group that is processed only once per
report as the first report group of that report. The REPORT HEADING report group is
processed during execution of the first chronological GENERATE statement for that
report. The REPORT HEADING phrase can appear no more than once in the description
of a report.
The minimum abbreviation is RH.

14–18

8600 1518–307

Report-Group Description Entry

PAGE HEADING

The PAGE HEADING phrase specifies a report group that is processed as the first report
group on each page of that report except under the following conditions:

•

A PAGE HEADING report group is not processed on a page that is to contain only a
REPORT HEADING report group or only a REPORT FOOTING report group.

•

A PAGE HEADING report group is processed as the second report group on a page
when it is preceded by a REPORT HEADING report group that is not to be printed on
a page by itself.

The PAGE HEADING report group can appear no more than once in the description of a
report. Also, you can specify the PAGE HEADING only if you specify a PAGE clause in
the corresponding report description entry.
The minimum abbreviation is PH.
CONTROL HEADING

The CONTROL HEADING phrase specifies a report group that is processed in one of two
ways:

•

At the beginning of a control group for a designated control data-name.

•

During execution of the first chronological GENERATE statement for that report, in
the case of FINAL.

If a control break is detected during execution of any GENERATE statement, then any
CONTROL HEADING report groups associated with the highest control level of the break
and lower levels are processed.
The CONTROL HEADING FINAL report group can appear no more than once in the
description of a report.
The minimum abbreviation is CH.
data-name-1
data-name-2
FINAL

You must specify data-name-1, data-name-2, and FINAL, if present, in the CONTROL
clause of the corresponding report-description entry. At most, you can specify one
CONTROL HEADING report group and one CONTROL FOOTING report group for each
data-name of FINAL in the CONTROL clause of the report-description entry. However,
neither a CONTROL HEADING report group nor a CONTROL FOOTING report group is
required for a data-name or FINAL specified in the CONTROL clause of the reportdescription entry.

8600 1518–307

14–19

Report-Group Description Entry

DETAIL

DETAIL report groups are processed as a direct result of GENERATE statements. If a
report group is other than TYPE DETAIL, processing is an automatic function.
When you specify a GENERATE report name statement in the Procedure Division, the
corresponding report-description entry must include no more than one DETAIL report
group. If you do not specify any GENERATE data-name statements for such a report, a
DETAIL report group is not required.
The minimum abbreviation is DE.
CONTROL FOOTING

The CONTROL FOOTING phrase specifies a report group that is processed at the end of
a control group for a designated control data-name. In the case of FINAL, the CONTROL
FOOTING report group is processed only once for each report, as the last body group of
that report. During execution of any GENERATE statement in which a control break is
detected, any CONTROL FOOTING report group associated with the highest level of the
control break or with minor levels is printed. All CONTROL FOOTING report groups are
printed during execution of the TERMINATE statement if at least one GENERATE
statement has been executed for the report.
CONTROL FOOTING FINAL can appear no more than once in the description of a report.
The minimum abbreviation is CF.
PAGE FOOTING

The PAGE FOOTING phrase specifies a report group that is processed as the last report
group on each page, except under the following conditions:

•

A PAGE FOOTING report group is not processed on a page that is to contain only a
REPORT HEADING report group or a REPORT FOOTING report group.

•

A PAGE FOOTING report group is processed as the second-to-last report group on a
page when it is followed by a REPORT FOOTING report group that is not to be
processed on a page by itself.

PAGE FOOTING can appear no more than once in the description of a report.
You can specify a PAGE FOOTING report group only if you specify a PAGE clause in the
corresponding report-description entry.
The minimum abbreviation is PF.

14–20

8600 1518–307

Report-Group Description Entry

REPORT FOOTING

The REPORT FOOTING phrase specifies a report group that is processed only once for
each report as the last report group of that report. The REPORT FOOTING report group is
processed during execution of a corresponding TERMINATE statement, if at least one
GENERATE statement has been executed for the report.
REPORT FOOTING can appear no more than once in the description of a report.
The minimum abbreviation is RF.
Additional Information about the TYPE Clause
Additional information about the TYPE clause is grouped in the following topics:

•

REPORT HEADING, PAGE HEADING, CONTROL HEADING, PAGE FOOTING, and
REPORT FOOTING report groups processing

•

CONTROL FOOTING report group processing

•

DETAIL/No DETAIL report group processing

•

Body groups processing

•

Control break processing

•

Other information

REPORT HEADING, PAGE HEADING, CONTROL HEADING, PAGE FOOTING, and
REPORT FOOTING Report Group Processing

The following sequence of steps is executed when a REPORT HEADING, PAGE
HEADING, CONTROL HEADING, PAGE FOOTING, or REPORT FOOTING report group is
processed:
1. If a USE BEFORE REPORTING procedure is present that references the data-name
of the report group, the USE procedure is executed.
2. If you have executed a SUPPRESS statement or the report group is not printable, no
further processing is done for the report group.
3. If you have not executed a SUPPRESS statement and the report group is printable,
the print lines are formatted and printed according to the rules for the given type of
report group.

8600 1518–307

14–21

Report-Group Description Entry

CONTROL FOOTING Report Group Processing

The following sequence of steps is executed when a CONTROL FOOTING report group
is processed:
The GENERATE rules specify that when a control break occurs, the CONTROL FOOTING
report groups, beginning at the minor level and proceeding upwards, are processed
through the level at which the highest control break was detected. Even if no CONTROL
FOOTING report group has been defined for a given control data-name, step 5 is
executed if a RESET phrase within the report description specifies that control dataname.
1. Sum counters are crossfooted. That is, when the addend is a sum counter defined in
the same CONTROL FOOTING report group, then the accumulation of that addend
into the sum counter is termed crossfooting. Thus, all sum counters defined in this
report group that are operands of SUM clauses in the same report group are added
to the sum counters.
2. Sum counters are rolled forward. Thus, all sum counters defined in the report group
that are operands of SUM clauses in higher-level CONTROL FOOTING report groups
are added to the higher-level sum counters.
3. If a USE BEFORE REPORTING procedure references the data-name of the report
group, the USE procedure is executed.
4. If you have executed a SUPPRESS statement or the report group is not printable,
step 5 is executed next; otherwise, the print lines are formatted and the report group
is printed according to the rules for CONTROL FOOTING report groups.
5. Sum counters that are to be reset when this level is processed in the control
hierarchy are reset.
DETAIL or No DETAIL Report Group Processing

Step 1 of the following list is executed in response to a GENERATE report-name
statement when the description of a report does not include DETAIL report groups. This
step is performed as if the description of the report includes exactly one DETAIL report
group and a GENERATE data-name statement is being executed.
Steps 1 through 5 are executed in response to a GENERATE report-name statement
when the description of a report includes exactly one DETAIL report group. These steps
are performed as if a GENERATE data-name statement is being executed.
1. Any subtotaling designated for the DETAIL report group is performed.
2. If a USE BEFORE REPORTING procedure refers to the data-name of the report
group, the USE procedure is executed.
3. If you have executed a SUPPRESS statement or the report group is not printable, no
further processing is done for the report group.
4. If the DETAIL report group is processed as a consequence of a GENERATE reportname statement, no further processing is done for the report group.

14–22

8600 1518–307

Report-Group Description Entry

5. If a SUPPRESS statement is not executed, or the report group is not printable, or
the DETAIL report group is not processed as a result of a GENERATE report-name
statement, then no further processing of the report group occurs.
Body Group Processing

When a CONTROL HEADING, CONTROL FOOTING, or DETAIL report is processed,
interruption of a previously described processing of that body group may be necessary
after determining that the body group is to be printed. A page advance is executed (and
PAGE FOOTING and PAGE HEADING report groups are processed) before the body
group is actually printed.
Control Break Processing

During control break processing, the values of control data items used to detect a given
control break are known as prior values. The following rules apply to prior values:
1. During control break processing of a CONTROL FOOTING report group, any
references to control data items in a USE procedure or SOURCE clause associated
with the CONTROL FOOTING report group are supplied with the prior values.
2. When a TERMINATE statement is executed, the prior control-data-item values are
made available to SOURCE clause or USE procedure references in CONTROL
FOOTING and REPORT FOOTING report groups as if a control break were detected
in the highest control data-name.
3. All other data item references in report groups and USE procedures access the
current values contained in the data items at the time the report group is processed.
Other Information

The description of a report must include at least one body group.
The DETAIL phrase specifies a report group that is processed when a corresponding
GENERATE statement is executed.
In CONTROL FOOTING, PAGE HEADING, PAGE FOOTING, and REPORT FOOTING
report groups, SOURCE clauses and USE statements must not reference any of the
following: group data items containing a control data item, data items subordinate to a
control data item, a redefinition or renaming of any part of a control data item.
In PAGE HEADING and PAGE FOOTING report groups, SOURCE clauses and USE
statements must not reference control data-names.

8600 1518–307

14–23

Report-Group Description Entry

Report-Group Description Entry Format 2
This format describes a single line of the report group. This entry must contain at least
one of the optional clauses.

level-number [ data-name-1 ]
Ú
³
³
³
À
[

LINE NUMBER IS
ïïïï

ä
ã
æ

integer-1

[ ON NEXT PAGE ]
ïïïïïïïïï
PLUS integer-2
ïïïï

å
â
ç

¿
³
³
³
Ù

[ USAGE IS ] DISPLAY ]
ïïïïï
ïïïïïïï

level-number

The level-number is any integer between 02 and 48, inclusive.
data-name-1

This entry is optional. You can use this entry only to qualify a sum-counter reference, if
this option is present.
A Format 2 entry must contain at least one of the optional clauses.
LINE NUMBER Clause
NEXT PAGE Clause

Refer to Report-Group Description Entry Format 1 for information on these clauses.
integer-1
integer-2

Refer to Report-Group Description Entry Format 1 for information on these integers.
USAGE Clause

A USAGE clause specifies the format of a data item in computer storage.
You can use the USAGE clause at either the elementary or 01-level. However, the
USAGE of all report groups and their elementary items must be the same as the USAGE
for the file on which the report is written. Refer to “USAGE Clause” in Section 4 for a
more detailed description of this clause.
The USAGE IS DISPLAY clause indicates that the format of the data is a standard data
format. If the USAGE is not specified for an elementary item, or for any group to which
the item belongs, the usage is implicitly DISPLAY.

14–24

8600 1518–307

Report-Group Description Entry

Report-Group Description Entry Format 3
This format describes the single, printable items for a line, and describes a line that
contains only one printable item.
Format 3 entries must define elementary data items.

level number [ data-name-1]
ä
ã
æ

PICTURE
ïïïïïïï
PIC
ïïï

[

[ USAGE IS ] DISPLAY ]
ïïïïï
ïïïïïïï

Ú
³
³
³
À
Ú
³
³
³
À
[
Ú
³
³
³
À
[
ä
³
³
³
³
ã
³
³
³
³
³
³
æ

[

ä
ã
æ

å
â
ç

IS character-string

ä LEADING å
SIGN IS ] ã ïïïïïïï â SEPARATE CHARACTER
æ TRAILING ç ïïïïïïïï
ïïïïïïïï
¿
JUSTIFIED å
³
ïïïïïïïïï â RIGHT ³
JUST
ç
³
ïïïï
Ù

¿
³
³
³
Ù

BLANK WHEN ZERO ]
ïïïïï
ïïïï
ä integer-1 [ on NEXT PAGE ] å
LINE NUMBER IS ã
ïïïïïïïïï
â
æ PLUS integer-2
ç
ïïïï
COLUMN NUMBER IS integer-3 ]
ïïïïïï
SOURCE IS identifier-1
ïïïïïï
VALUE IS literal-1
ïïïïï
{ SUM identifier-2
[ , identifier-3
ïïï
[ UPON data-name-2 [ , data-name-3
ïïïï
Ú
³ RESET ON ä data-name-4 å
³ ïïïïï
ã
â
³
æ FINAL
ç
À
ïïïïï

¿
³
³
³
Ù

]...
] ... ] } ...
¿
³
³
³
Ù

å
³
³
³
³
â
³
³
³
³
³
³
ç

[ GROUP INDICATE ]
ïïïïï

8600 1518–307

14–25

Report-Group Description Entry

level-number

The level-number is any integer between 02 and 49, inclusive.
data-name-1

This entry is optional. If present, you can only use this entry to qualify a sum-counter
reference.
PICTURE Clause
Refer to the PICTURE clause under “Data Description Entry Format 1” in Section 4 for a
more detailed description of this clause.
USAGE Clause
In a Format 3 entry, the USAGE clause must define a printable item.
Refer to the USAGE clause under “Report-Group Description Entry Format 2” earlier in
this section for information on this clause.
SIGN Clause
The SIGN clause specifies the position and the mode of representation of the operational
sign when it is necessary to describe these properties explicitly.
Refer to the SIGN clause under “Data Description Entry Format 1” in Section 4 for
detailed information.
JUSTIFIED Clause
The JUSTIFIED clause permits alternate (nonstandard) positioning of data in a receiving
data item.
Refer to the JUSTIFIED clause under “Data Description Entry Format 1” in Section 4 for
detailed information.
BLANK WHEN ZERO Clause
The BLANK WHEN ZERO clause fills an item with spaces when its value is zero.
Refer to the BLANK WHEN ZERO clause under “Data Description Entry Format 1” in
Section 4 for detailed information.
LINE NUMBER Clause
Refer to “Report-Group Description Entry Format 1” earlier in this section for information
on this clause.

14–26

8600 1518–307

Report-Group Description Entry

COLUMN NUMBER Clause
The COLUMN NUMBER clause identifies a printable item and specifies the columnnumber position of the item on the print line. You can specify this clause only at the
elementary level. When you use this clause, it must appear in, or be subordinate to, an
entry that contains a LINE NUMBER clause.
integer-3

This must be greater than 0 (zero). Integer-3 specifies the leftmost character position of
the printable item. In a given print line, you must define printable items in ascending
column-number order, so that each character defined occupies a unique position.
Details of COLUMN NUMBER Clause

The COLUMN NUMBER clause indicates that the following are to be printed with the
leftmost character position indicated by integer-3:

•

The object of a SOURCE clause

•

The object of a VALUE clause

•

The sum counter defined by a SUM clause

The first or leftmost character of a print line is column number one.
The absence of a COLUMN NUMBER clause indicates that the entry is not printed.
Space characters are automatically provided for all positions of a print line that are not
occupied by printable items.
SOURCE Clause
The SOURCE clause identifies the sending data item that is moved to an associated
printable item defined in a report-group description entry.
identifier-1

This can be defined in any section of the Data Division. If identifier-1 is a Report Section
item, it can only be PAGE-COUNTER, LINE-COUNTER, or a sum counter of the report in
which the SOURCE clause appears.
Identifier-1 specifies the sending data item of the implicit MOVE statement that is
executed to move identifier-1 to the printable item. You must define identifier-1 so that it
conforms to the rules for sending items in the MOVE statement.
The print lines of a report group are formatted immediately before presentation of the
report group. At that time, the implicit MOVE statements specified by SOURCE clauses
are executed.
VALUE Clause
The VALUE clause defines the value of Report Section printable items. Refer to the
VALUE clause under “Data Description Entry Format 1” in Section 4 for a more detailed
discussion.

8600 1518–307

14–27

Report-Group Description Entry

SUM Clause
The SUM clause establishes a sum counter and names the data items to be summed.
identifier-2
identifier-3

You must define identifier-2 and identifier-3 as numeric data items. When defined in the
Report Section, identifier-2 and identifier-3 must be the names of sum counters.
UPON

If UPON is omitted, then you must define any identifiers in the associated SUM clause
that are themselves sum counters, in the following two ways:

•

In the same report group that contains this SUM clause

•

In a report group at a lower level in the control hierarchy of this report

If you specify the UPON phrase, any identifiers in the associated SUM clause must not
be sum counters.
data-name-2
data-name-3

These must be names of DETAIL report groups described in the same report as the
CONTROL FOOTING report group in which the SUM clause appears. You can qualify
data-name-2 and data-name-3 by a report name.
data-name-4

This must be one of the data-names specified in the CONTROL clause for this report.
Data-name-4 must not be a lower-level control than the associated control for the report
group in which the RESET phrase appears.
FINAL

If this is specified in the RESET phrase, FINAL must also appear in the CONTROL clause
for this report.
Details of SUM Clause

A SUM clause can appear only in the description of a CONTROL FOOTING report group.
The highest permissible qualifier of a sum counter is the report-name.
The SUM clause establishes a sum counter. The sum counter is a numeric data item
with an operational sign. At execution time, each of the values identifier-1, identifier-2,
and so forth is added directly into the sum counter. This addition is performed under the
rules of the ADD statement.

14–28

8600 1518–307

Report-Group Description Entry

The size of the sum counter is equal to the number of receiving character positions
specified by the PICTURE clause that accompanies the SUM clause in the description of
the elementary item.
Only one sum counter exists for an elementary report entry, regardless of the number of
SUM clauses you specify in the elementary report entry.
If the elementary report entry for a printable item contains a SUM clause, the sum
counter serves as a source data item. The data contained in the sum counter is moved,
according to the rules of the MOVE statement, to the printable item for printing.
If the data-name appears as the subject of an elementary report entry that contains a
SUM clause, the data-name is the name of the sum counter, not the name of the
printable item that the entry can also define.
Procedure Division statements can alter the contents of sum counters.
Addition of the identifiers into sum counters is performed during execution of
GENERATE and TERMINATE statements. Each individual addend is added into the sum
counter at a time that depends on the characteristics of the addend. The following three
categories of sum-counter incrementing describe the characteristics of the addends and
the timing of the addition process:

•

Subtotaling
When the addend is not a sum counter, the accumulation into a sum counter of such
an addend is called subtotaling. If the SUM clause contains the UPON phrase, the
addends are subtotaled when a GENERATE statement for the designated DETAIL
report group is executed. If the SUM clause does not contain the UPON phrase, the
addends that are not sum counters are subtotaled when any GENERATE data-name
statement is executed for the report in which the SUM clause appears.

•

Crossfooting
When the addend is a sum counter defined in the same CONTROL FOOTING report
group, the accumulation of that addend into the sum counter is termed crossfooting.
Crossfooting occurs when a control break takes place and at the time the CONTROL
FOOTING report group is processed. Crossfooting is performed according to the
sequence in which sum counters are defined in the CONTROL FOOTING report
group. Thus, all crossfooting into the first sum counter defined in the CONTROL
FOOTING report group is completed first. Then, all crossfooting into the second sum
counter defined in the CONTROL FOOTING report group is completed. This
procedure is repeated until all crossfooting operations are completed.

•

Rolling forward
When the addend is a sum counter defined in a lower-level CONTROL FOOTING
report group, the accumulation of that addend into the sum counter is termed rolling
forward. A sum counter in a lower-level CONTROL FOOTING report group is rolled
forward when a control break occurs and at the time that the lower-level CONTROL
FOOTING report group is processed.

8600 1518–307

14–29

Report-Group Description Entry

Subtotaling is accomplished only during execution of GENERATE statements after any
control break is processed but before the DETAIL report group is processed.
Crossfooting and rolling forward are accomplished during the processing of CONTROL
FOOTING report groups.
The UPON phrase enables selective subtotaling for the DETAIL report groups named in
the phrase.
If two or more identifiers specify the same addend, the addend is added into the sum
counter as many times as the addend is referenced in the SUM clause. Two or more
data-names can specify the same DETAIL report group. When a GENERATE data-name
statement for such a DETAIL report group is given, the incrementing occurs as many
times as data-names appear in the UPON phrase.
In the absence of an explicit RESET phrase, a sum counter is set to 0 at the time the
CONTROL FOOTING report group with which the sum counter is defined is processed. If
you specify an explicit RESET phrase, the sum counter is set to 0 at the time the
designated level of the control hierarchy is processed. Sum counters are initially set to 0
during execution of the INITIATE statement for the report containing the sum counter.
GROUP INDICATE Clause
The GROUP INDICATE clause indicates that this elementary item is to be produced only
on the first occurrence of the item after any control or page break.
The GROUP INDICATE clause can appear only in a DETAIL report group at the
elementary-item level within an entry that defines a printable item.
If you specify a GROUP INDICATE clause, it causes the SOURCE or VALUE clauses to
be ignored, and spaces to be provided, except in the following cases:

•

On the first printing of the DETAIL report group in the report

•

On the first printing of the DETAIL report group after a page advance

•

On the first printing of the DETAIL report group after every control break

If the report-description entry specifies neither a PAGE clause nor a CONTROL clause,
then a GROUP INDICATE printable item is printed the first time the DETAIL is printed
after the INITIATE statement is executed. Thereafter, spaces are supplied for indicated
items with SOURCE or VALUE clauses.

14–30

8600 1518–307

Report-Group Description Entry

Table 14–2 shows the permissible clause combinations for a Format 3 entry. The table is
read from left to right along the selected row.
In the following table, the M indicates that the clause is mandatory, the P indicates that
the clause is permitted but not required, and a blank indicates the clause is not
permitted.
Table 14–2. Permissible Clause Combinations
in Format 3 Report Group Description Entries

PIC

Column

Source

Sum

Value

Just

Blank
When
Zero

Group
Indicate

Usage

Line

Sign

8600 1518–307

P
P
P
M

14–31

Procedure Division

Procedure Division
You can use the statements described in the following pages with Report Writer. The
statements are listed in alphabetical order.

CLOSE Statement
The CLOSE statement terminates the processing of a reel/unit of a file or a file with
optional rewind and lock or removal where applicable. All reports associated with a report
file that have been initiated must end with the execution of a TERMINATE statement
before a CLOSE statement is executed for that report file.
The availability of the phrases within the CLOSE statement is dependent on the level of
the Sequential I-O module supported by the implementation.

CLOSE
ïïïïï

ä
³
³
³
ã
³
³
³
æ

Ú
³
³
³
file-name-1 ³
³
³
³
À

ä REEL å
ã ïïïï â [ FOR REMOVAL ]
æ UNIT ç
ïïïïïïï
ïïïï
ä NO REWIND å
WITH ã ïï ïïïïïï â
æ LOCK
ç
ïïïï

¿
³
³
³
³
³
³
³
Ù

å
³
³
³
â
³
³
³
ç

. . .

file-name-1

This is a user-defined word that specifies the name of the file to be closed.
The specified file must be in an open mode.
Files referenced in the CLOSE statement can have different organizations and access
modes.
REEL
UNIT

These are equivalent.
The reel or unit is closed and rewound.
Treatment of sequential mass storage files is logically equivalent to the treatment of a
file on tape or similar sequential medium.
Treatment of a file contained in a multiple file tape environment is logically equivalent to
the treatment of a sequential single-reel/unit file, if the file is contained on one reel.
The REEL or UNIT phrase and the NO REWIND option cannot be specified together in a
CLOSE statement.

14–32

8600 1518–307

Procedure Division

FOR REMOVAL

This option is used for sequential single-reel/unit files and multi-reel/unit files. The
reel/unit is closed, and the system waits for the next reel/unit.
NO REWIND

The file is closed, and the current reel/unit is left in its current position.
The NO REWIND option and the REEL or UNIT phrase cannot be specified together in a
CLOSE statement.
LOCK

8600 1518–307

14–33

Procedure Division

GENERATE Statement
The GENERATE statement links the Procedure Division to the Report Writer (described in
the Report Section of the Data Division ) at process time.

GENERATE identifier
ïïïïïïïï

identifier

This represents a TYPE DETAIL report group or an RD entry.
Details
If identifier represents the name of a TYPE DETAIL report group, the GENERATE
statement performs all automatic operations in the Report Writer and produces an output
DETAIL report group on the output medium at process time. This type of reporting is
called detail reporting.
If identifier represents the name of a report description (RD) entry, the GENERATE
statement performs all automatic operations of the Report Writer, and updates the
FOOTING report groups in a particular report description, without producing a DETAIL
report group associated with the report. In this case, all sum counters associated with
the report description are algebraically incremented. This type of reporting is called
summary reporting. For summary reporting, no more than one TYPE DETAIL report
group and at least one body group must be present, and the CONTROL clause must be
specified for the report.
A GENERATE statement implicitly produces the following automatic operations, if
defined, in both detail and summary reporting:

14–34

•

Steps and tests LINE-COUNTER and/or PAGE-COUNTER to produce appropriate
PAGE FOOTING and/or PAGE HEADING report groups

•

Recognizes any specified control breaks to produce appropriate CONTROL FOOTING
or CONTROL HEADING reporting groups

•

Accumulates all specified identifiers into the sum counters, resets the sum counters
on an associated control break, and performs an updating procedure between
control-break levels for each set of sum counters

•

Executes any specified routines defined by a USE statement before generation of
the associated report groups

8600 1518–307

Procedure Division

During execution of the first GENERATE statement, the following report groups
associated with the report, if specified, are produced in the following order:

•

REPORT HEADING report group

•

PAGE HEADING report group

•

All CONTROL HEADING report groups, in the following order:

•

−

Final

−

Major

−

Minor

The DETAIL report group, if specified in the GENERATE statement

If a control break is recognized at the time of execution of a GENERATE statement (other
than the first statement executed for a report), all CONTROL FOOTING report groups
specified for the report are produced from the minor report group up to, and including,
the report group specified for the identifier that caused the control break. Next, the
CONTROL HEADING report groups specified for the report from the report group
specified for the identifier that caused the control breakdown to the minor report group
are produced in that order. The DETAIL report group specified in the GENERATE
statement is then produced.
Data is moved to the data item in the report-group description entry of the Report
Section. This data is edited under the control of the Report Writer according to the same
rules for movement and editing described for the MOVE statement.
GENERATE statements for a report can be executed only after an INITIATE statement
for the report has been executed and before a TERMINATE statement for the report has
been executed.

8600 1518–307

14–35

Procedure Division

INITIATE Statement
The INITIATE statement begins processing of a report.

INITIATE { report-name-1 } ...
ïïïïïïïï

report-name-1

You must define each report-name by a report-description entry in the Report Section of
the Data Division.
Details
The INITIATE statement resets all data-name entries that contain SUM clauses
associated with the report.
The PAGE-COUNTER register, if specified, is set to 1 during execution of the INITIATE
statement. If a starting value other than 1 is desired for the associated PAGE-COUNTER,
you can reset the counter after execution of the INITIATE statement is completed.
The LINE-COUNTER register, if specified, is set to 0 before or during execution of the
INITIATE statement.
The INITIATE statement does not open the file with which the report is associated;
however, the associated file must be open at the time the INITIATE statement is
executed.
A second INITIATE statement for a particular report-name cannot be executed unless a
TERMINATE statement has been executed for that report-name after execution of the
first INITATE statement.

14–36

8600 1518–307

Procedure Division

OPEN Statement
The OPEN statement initiates the processing of report files.

OPEN
ïïïï

ä
ã
æ

OUTPUT { file-name-1 [ WITH NO REWIND ] } ...
ïïïïïï
ïïïïïïïïï
EXTEND { file-name-2 } ...
ïïïïïï

å
â ...
ç

OUTPUT

The file-name in a file description entry for a file must be equivalent to the file-name used
when the file was created.
If you specify more than one file-name in an OPEN statement, the result is the same as if
you had written separate OPEN statements for each file.
The minimum and maximum record sizes for a file are established at the time the file is
created and cannot be subsequently changed.
EXTEND

This option enables you to write additional records to the end of a sequential file.
The EXTEND option can be used only with the following:

•

Sequential single reel/unit files

•

Files for which the LINAGE clause has not been specified

This option requires file-name-2 to be a previously created file (that is, already in the disk
or pack directory, or on tape).
When you specify the EXTEND option, execution of the OPEN statement positions the
file immediately after the last logical record for that file (that is, the last record written in
the file). Subsequent WRITE statements that reference the file add records to the file as
though the file had been opened with the OUTPUT phrase.

8600 1518–307

14–37

Procedure Division

For an optional file that is unavailable, the successful execution of an OPEN statement
with an EXTEND phrase creates the file as if the following statements had been
executed:
OPEN OUTPUT file-name.
CLOSE file-name.
NO REWIND

This option can be used only with the following:

•

Sequential single reel/unit files

•

Sequential files that are wholly contained in a single reel of tape within a multiple-file
tape environment

These phrases are ignored if they do not apply to the storage medium on which the file
resides.
If the medium on which the file resides permits rewinding, the following rules apply:

•

If you do not specify EXTEND or NO REWIND, execution of the OPEN statement
causes the file to be positioned at its beginning.

•

Details
Refer to “OPEN Statement” in Section 7 for additional information.

14–38

8600 1518–307

Procedure Division

SUPPRESS Statement
The SUPPRESS statement causes the report writer control system (RCWS) to inhibit the
presentation of a report group named in the USE procedure.

SUPPRESS PRINTING
ïïïïïïïï
Details
The SUPPRESS statement can only appear in a USE BEFORE REPORTING procedure.
The SUPPRESS statement must be executed each time the presentation of the report
group is to be inhibited. When you execute the SUPPRESS statement, the RCWS is
instructed to inhibit the processing of the following report group functions:

•

The presentation of the print lines of the report group

•

The processing of all LINE clauses in the report group

•

The processing of the NEXT GROUP clause in the report group

•

The adjustment of LINE-COUNTER

8600 1518–307

14–39

Procedure Division

TERMINATE Statement
The TERMINATE statement terminates the processing of a report.

TERMINATE { report-name-1 } ...
ïïïïïïïïï

report-name-1

You must define each report-name given in a TERMINATE statement by a report
description (RD) entry in the Report Section of the Data Division.
Details
The TERMINATE statement produces all CONTROL FOOTING groups associated with
this report as if a control break had just occurred at the highest level and completes the
Report Writer functions for the named reports. The TERMINATE statement also
produces the last PAGE FOOTING and the REPORT FOOTING report groups associated
with this report.
If no GENERATE statements have been executed for a report during the interval
between the execution of an INITATE statement and a TERMINATE statement for the
same report, associated FOOTING groups are not produced.
Appropriate PAGE HEADING and/or PAGE FOOTING report groups are prepared in their
respective order for the report description.
You cannot execute a second TERMINATE statement for a particular report unless a
second INITIATE statement has been executed for a report-name. If a TERMINATE
statement has been executed for a report, a GENERATE statement for that report must
not be executed unless an intervening INITIATE statement for that report is executed.
The associated file must be open at the time the TERMINATE statement is executed.
The TERMINATE statement does not close the file with which the report is associated.
You must specify a CLOSE statement. The TERMINATE statement performs Report
Writer functions for individually described reports analogous to the input/output functions
that the CLOSE statement performs for individually described files.
SOURCE clauses used in the CONTROL FOOTING FINAL or REPORT FOOTING report
groups refer to the values of the items at execution time of the TERMINATE statement.

14–40

8600 1518–307

Procedure Division

USE AFTER STANDARD EXCEPTION PROCEDURE Statement
The USE AFTER STANDARD EXCEPTION PROCEDURE statement specifies procedures
for input-output error handling that are in addition to the standard procedures provided by
the input-output control system.

ä EXCEPTION å
USE AFTER STANDARD ã ïïïïïïïïï â PROCEDURE
ïïïïïïïïï
æ ERROR
ç ïïïïïïïïï
ïïïïï
ä { file-name-1 } ... å
³
³
ON
ã
OUTPUT
â
³
ïïïïïï
³
æ
EXTEND
ç
ïïïïïï

USE AFTER

The USE AFTER statement is never executed itself; it merely defines the conditions
calling for the execution of the USE procedures.
A USE AFTER statement must immediately follow a section header in the declaratives
section and must appear in a sentence by itself. The remainder of the section must
consist of any number of procedural paragraphs that define the procedures to be used.
ERROR
EXCEPTION

The words ERROR and EXCEPTION are synonymous and can be used interchangeably.
file-name-1

The OUTPUT and EXTEND phrases can each be specified only once in the declaratives
portion of a given Procedure Division.

8600 1518–307

14–41

Procedure Division

Details
Declarative procedures can be included in any COBOL source program whether or not
the program contains, or is contained in, another program. Refer to Section 5 for
information about declarative procedures and compiler-directing statements.
A declarative is invoked when any of the conditions described in the USE AFTER
statement that prefaces the declarative occur while the program is being executed. The
declarative is invoked only if it exists in the separately compiled program that contains
the statement that caused the qualifying condition. If the declarative does not exist in the
separately compiled program, the declarative is not executed.
A declarative procedure must not reference any nondeclarative procedures.
Procedure-names associated with a USE AFTER statement can be referenced in a
different declarative section, or in a nondeclarative procedure only with a PERFORM
statement.
The procedures associated with the USE AFTER statement are executed by the inputoutput control system after completing the standard error retry routine if the execution of
the input-output routine was unsuccessful. However, an AT END phrase can take
precedence.
The following rules concern the execution of the procedures associated with the USE
AFTER statement:

•

If you specify file-name-1, the associated procedure is executed when the condition
described in the USE AFTER statement occurs to the file.

•

If you specify OUTPUT, the associated procedure is executed for any file that is open
in the output mode, or that is in the process of being opened in the output mode
when the condition described in the USE AFTER statement occurs. Those files
referenced by file-name-1 in another USE AFTER statement that specifies the same
condition are not executed.

•

If you specify EXTEND, the associated procedure is executed for any sequential file
that is open in the EXTEND mode, or that is in the process of being opened in the
EXTEND mode when the condition described in the USE AFTER statement occurs.
Those sequential files referenced by file-name-1 in another USE AFTER statement
that specifies the same condition are not executed.

14–42

8600 1518–307

Procedure Division

USE BEFORE REPORTING Statement
This statement specifies Procedure Division statements that are executed just before a
report group named in the Report Section of the Data Division is presented.

USE BEFORE REPORTING identifier-1
ïïïïïïïïïïïïïïïïïïïï

USE BEFORE REPORTING

The USE BEFORE REPORTING statement is never executed itself; it merely defines the
conditions calling for the execution of the USE procedures.
This statement must immediately follow a section header in the declaratives portion of
the Procedure Division and must appear in a sentence by itself. The remainder of the
section must consist of any number of procedural paragraphs that define the procedures
to be used.
A USE BEFORE REPORTING procedure must not alter the value of any control data item.
The GENERATE, INITIATE, or TERMINATE statements must not appear in a paragraph
within a USE BEFORE REPORTING procedure. A PERFORM statement in a USE
BEFORE REPORTING procedure must not have GENERATE, INITIATE, or TERMINATE
statements in its range.
identifier-1

Identifier-1 must be a reference to a report group. It must not appear in more than one
USE BEFORE REPORTING statement.
Details
Declarative procedures can be included in any source program whether or not the
program contains, or is contained in, another program. A declarative is invoked just
before the named report group is produced during the execution of the program. The
report group is named by identifier-1 in the USE BEFORE REPORTING statement that
prefaces the declaratives.
A declarative procedure must not make a reference to any nondeclarative procedures.
Procedure-names associated with a USE BEFORE REPORTING statement can be
referenced in a different declarative section, or in a nondeclarative procedure only with a
PERFORM statement.
In the USE BEFORE REPORTING statement, the designated procedures are executed by
the report writer control system (RWCS) just before the named report group is produced.
In a USE procedure, a statement cannot be executed if it would cause the execution of a
USE procedure that had previously been invoked and had not yet returned the control to
the invoking routine.

8600 1518–307

14–43

Report Writer Examples

Report Writer Examples
The data file input of the following program (Example 1) uses the Report Writer program
to produce the report shown in Example 2. The output file is shown in example 3.
Example 1
IDENTIFICATION DIVISION.
PROGRAM-ID. FED-SCHOOL-SYSTEM.
AUTHOR. BERKOWITZ.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT PENNI ASSIGN TO SORT DISK.
SELECT INFILE ASSIGN TO DISK.
SELECT REPORTFILE ASSIGN TO PRINTER.
DATA DIVISION.
FILE SECTION.
FD INFILE BLOCK CONTAINS 30 RECORDS.
01 IN-REC
PICTURE X(84).
SD PENNI.
01 FROMM.
02 FILLER
PICTURE XX.
02 STUDENT.
03 NAME-L
PICTURE X(30).
03 NAME-F
PICTURE X(10).
02 FILLER
PICTURE XX.
02 GRADE
PICTURE 99.
02 FILLER
PICTURE XX.
02 ROOM
PICTURE 999.
02 FILLER
PICTURE 99.
02 MONTHH
PICTURE 99.
02 DAYY
PICTURE 99.
02 YR
PICTURE 99.
02 FILLER
PICTURE X(2).
02 TAL
PICTURE 9.
02 FILLER
PICTURE X(22).
FD REPORTFILE
REPORT IS ABS-REPORT.
WORKING-STORAGE SECTION.
77 SAVED-MONTH
PICTURE 99 VALUE IS 0.
77 CONTINUED
PICTURE X(11) VALUE IS SPACE.
77 ABSS PIC X(8) VALUE "ABSENCES".
77 CA PIC X(19)
VALUE "CUMULATIVE ABSENCES".
77 TAL-CTR BINARY PIC 9999.
77 MTHIX
PICTURE 99.

14–44

8600 1518–307

Report Writer Examples

HEAD-1.
02 FILLER PIC X(22) VALUE SPACES.
02 HEAD-LINE PIC X(74) VALUE " MONTH
DAY
"GRADE
ROOM
NAME ".
02 FILLER PIC X(36) VALUE SPACES.
01 MONTH-TABLE.
02 MONTH-1.
03 FILLER PICTURE A(9) VALUE IS "JANUARY ".
03 FILLER PICTURE A(9) VALUE IS "FEBRUARY ".
03 FILLER PICTURE A(9) VALUE IS "MARCH
".
03 FILLER PICTURE A(9) VALUE IS "APRIL
".
03 FILLER PICTURE A(9) VALUE IS "MAY
".
03 FILLER PICTURE A(9) VALUE IS "JUNE
".
03 FILLER PICTURE A(9) VALUE IS "JULY
".
03 FILLER PICTURE A(9) VALUE IS "AUGUST
".
03 FILLER PICTURE A(9) VALUE IS "SEPTEMBER".
03 FILLER PICTURE A(9) VALUE IS "OCTOBER ".
03 FILLER PICTURE A(9) VALUE IS "NOVEMBER ".
03 FILLER PICTURE A(9) VALUE IS "DECEMBER ".
03 FILLER PICTURE A(9) VALUE SPACES.
02 MONTH-2 REDEFINES MONTH-1.
03 MONTHNAME PICTURE A(9) OCCURS 13 TIMES.
REPORT SECTION.
RD ABS-REPORT
CONTROLS ARE FINAL, MONTHH, DAYY, GRADE
PAGE LIMIT IS 56 LINES
HEADING 2
FIRST DETAIL 10
LAST DETAIL 45
FOOTING 55.
*
* THE FOLLOWING LINES PRODUCE THE REPORT HEADING.
* SEE <--1 IN SAMPLE REPORT WRITER REPORT.
*
01 TYPE IS REPORT HEADING.
02 LINE NUMBER IS 2
COLUMN 57
PIC X(17)
VALUE "FED SCHOOL SYSTEM".
*
* THE FOLLOWING LINES PRODUCE THE PAGE HEADING.
* SEE <--2 IN SAMPLE REPORT WRITER REPORT.
*
01 PAGE-HEAD
TYPE IS PAGE HEADING.
02 LINE NUMBER IS 3 COLUMN 52
PIC X(26)
VALUE "STUDENT ABSENTEEISM REPORT".
02 LINE NUMBER IS 6.
03 COLUMN IS 56
PIC X(9)
SOURCE IS MONTHNAME OF MONTH-2(MONTHH).
03 COLUMN IS 66
PIC X(8)
SOURCE IS ABSS.
03 COLUMN IS 76
PIC X(11)
SOURCE IS CONTINUED.
02 LINE IS 8.
03 COLUMN IS 1
PIC X(132)
SOURCE HEAD-1.
*

8600 1518–307

14–45

Report Writer Examples

* THE FOLLOWING LINES PRODUCE THE DETAIL LINES.
* SEE <--3 IN SAMPLE REPORT WRITER REPORT.
*
01 DETAIL-LINE TYPE IS DETAIL LINE NUMBER IS PLUS 1.
02 COLUMN IS 24 GROUP INDICATE PIC X(9)
SOURCE IS MONTHNAME OF MONTH-2(MONTHH).
02 COLUMN IS 41 GROUP INDICATE PICTURE IS 99
SOURCE IS DAYY.
02 COLUMN IS 54 GROUP INDICATE PIC 99 SOURCE IS GRADE.
02 COLUMN IS 67 PIC 999 SOURCE IS ROOM.
02 COLUMN IS 80 PIC X(20) SOURCE IS NAME-L.
02 COLUMN IS 101 PIC X(10) SOURCE IS NAME-F.
*
* THE FOLLOWING LINES PRODUCE THE CONTROL FOOTING GRADE.
* SEE <--4 IN SAMPLE REPORT WRITER REPORT.
*
01 TYPE IS CONTROL FOOTING GRADE.
02 LINE NUMBER IS PLUS 2.
03 COLUMN 1 PIC X(132) VALUE SPACE.
*
* THE FOLLOWING LINES PRODUCE THE CONTROL FOOTING DAYY.
* SEE <--5 IN SAMPLE REPORT WRITER REPORT.
*
01 TESTER
TYPE IS CONTROL FOOTING DAYY.
02 LINE NUMBER IS PLUS 2.
03 COLUMN 2 PIC X(12)
VALUE "ABSENCES FOR".
03 COLUMN 24 PICTURE Z9 SOURCE SAVED-MONTH.
03 COLUMN 26 PICTURE X VALUE "-".
03 COLUMN 27 PICTURE 99 SOURCE DAYY.
03 NO-ABS
COLUMN 49
PIC 999
SUM TAL.
03 COLUMN 65 PIC X(19) SOURCE CA.
03 COLUMN 85 PIC 999 SUM TAL RESET ON FINAL.
02 LINE PLUS 1 COLUMN 24
PIC X(84)
VALUE ALL "*".
* THE FOLLOWING LINES PRODUCE THE CONTROL FOOTING MONTHH.
* SEE <--6 IN SAMPLE REPORT WRITER REPORT.
*
01 TYPE CONTROL FOOTING MONTHH
LINE PLUS 2 NEXT GROUP NEXT PAGE.
02 COLUMN 42 PIC X(28) VALUE "TOTAL NUMBER OF ABSENCES FOR".
02 COLUMN IS 72 PIC X(9)
SOURCE MONTHNAME OF MONTH-2(SAVED-MONTH).
02 COLUMN 83 PIC XXX VALUE "WAS".
02 TOT
COLUMN 87 PIC 999
SUM NO-ABS.
*
* THE FOLLOWING LINES PRODUCE THE PAGE FOOTING.
* SEE <--7 IN SAMPLE REPORT WRITER REPORT.
*
01 TYPE PAGE FOOTING LINE PLUS 1.
02 COLUMN 59
PICTURE X(12) VALUE "REPORT-PAGE-".
02 COLUMN 71
PICTURE 99 SOURCE PAGE-COUNTER.
*

14–46

8600 1518–307

Report Writer Examples

* THE FOLLOWING LINES PRODUCE THE REPORT FOOTING.
* SEE <--8 IN SAMPLE REPORT WRITER REPORT.
*
01
TYPE REPORT FOOTING.
02 LINE PLUS 1 COLUMN 59 PICTURE A(13)
VALUE "END OF REPORT".
PROCEDURE DIVISION.
DECLARATIVES.
PAGE-HEAD-RTN SECTION.
USE BEFORE REPORTING PAGE-HEAD.
TEST-CONT.
IF MONTHH = SAVED-MONTH MOVE "(CONTINUED)" TO CONTINUED
ELSE MOVE SPACES TO CONTINUED
MOVE MONTHH TO SAVED-MONTH.
END DECLARATIVES.
SORTING SECTION.
SORTER.
SORT PENNI
ON ASCENDING KEY
MONTHH, DAYY, GRADE, ROOM, STUDENT
USING INFILE
OUTPUT PROCEDURE IS REPORTER.
DISPLAY MONTHH.
MOVE MONTHH TO MTHIX.
END-OF-THE-SORT.
STOP RUN.
REPORTER SECTION.
INITIATE-REPORT.
OPEN OUTPUT REPORTFILE.
INITIATE ABS-REPORT.
UNWIND-THE-SORT.
RETURN PENNI RECORD AT END
TERMINATE ABS-REPORT STOP RUN.
GENERATE DETAIL-LINE GO TO UNWIND-THE-SORT.
STOP RUN.

8600 1518–307

14–47

Report Writer Examples

Example 2: Input File
The input data file called INFILE results in the output shown in example 3.
CODDINGTON
MILLSTEIN
BURKLAND
MCCOY
LUBASCH
JOFFEE
EAGLE
DANIELSON
HUBERT
WONG
CODDINGTON
CARROLL
HANSON
AUSTIN

KIMBERLY
SANDRA
JOSEPH
JUDY
DANIEL
JOHN
MIKE
FRED
THOMAS
SUSIE
DARIN
JENNIFER
KAREN
EUGENE

03
03
03
01
01
01
05
05
03
03
02
02
02
02

125
121
121
142
142
142
153
153
115
111
103
102
102
101

091288
091288
091288
091088
091088
091088
090788
090788
090788
090788
090788
090788
090788
090788

1
1
1
1
1
1
1
1
1
1
1
1
1
1

Example 3: Output File
FED SCHOOL SYSTEM
STUDENT ABSENTEEISM REPORT

<--1
<--2

SEPTEMBER ABSENCES

<--2

MONTH

DAY

GRADE

ROOM

NAME

<--2

SEPTEMBER

101
102
102
103

AUSTIN
CARROLL
HANSON
CODDINGTON

EUGENE
JENNIFER
KAREN
DARIN

SEPTEMBER

111
115

WONG
HUBERT

SUSIE
THOMAS

SEPTEMBER

153
153

DANIELSON
EAGLE

FRED
MIKE

ABSENCES FOR
9-07
008
CUMULATIVE ABSENCES 008
*****************************************************************
SEPTEMBER
10
01
142
JOFFEE
JOHN
142
LUBASCH
DANIEL
142
MCCOY
JUDY

14–48

<--3
<--3
<--3
<--3
<--4
<--3
<--3
<--4
<--3
<--3
<--4
<--5
<--5
<--3
<--3
<--3
<--4

8600 1518–307

Report Writer Examples

ABSENCES FOR
9-10
003
CUMULATIVE ABSENCES 011
****************************************************************
SEPTEMBER
12
03
121
BURKLAND
JOSEPH
121
MILLSTEIN
SANDRA
125
CODDINGTON KIMBERLY

<--5
<--5
<--3
<--3
<--3
<--4

ABSENCES FOR
9-12
003
CUMULATIVE ABSENCES 014
****************************************************************

<--5
<--5

TOTAL NUMBER OF ABSENCES FOR SEPTEMBER WAS 014
REPORT-PAGE-01
END OF REPORT

8600 1518–307

<--6
<--7
<--8

14–49

Report Writer Examples

14–50

8600 1518–307

Section 15
Compiler Operations
Note: Although this section is not highlighted, all of the information is relative to Unisys
extensions to COBOL ANSI-85.
This section describes COBOL compiler operations. It contains three parts.
Input and Output Data Flow
This part of the section discusses the flow of data to and from the COBOL compiler. It
also describes the input and output files of the compiler.
Compiling and Executing a COBOL Program
This part of the section summarizes how to:

•

Create an object code file using the compiler

•

Execute the object code file generated by the compiler

•

Prevent abnormal terminations caused by stack overflows

Compiler Control Options
This part of the section describes the compiler control options that are available in
COBOL85. It contains:

•

General material about using any compiler option

•

Reference material about each compiler option, in order of option name

8600 1518–307

15–1

Input and Output Data Flow

Input and Output Data Flow
The source code of a program can be submitted to the COBOL compiler in the form of
disk files or magnetic tape files. When more than one file is used for input, the compiler
merges the files using the sequence numbers of the records in the files. The compiler
also merges files according to any COPY statements included in the source code.
The primary output of the COBOL compiler is an object code file. The compiler can also
generate several optional output files. The available optional files include:

•

Updated symbolic file

•

Error message file

•

Printed listing containing the source records and compiler control records used by
the compiler

Figure 15–1 shows the flow of data during a COBOL compile.

Figure 15–1. COBOL Compiler Input and Output Files

15–2

8600 1518–307

Input and Output Data Flow

COBOL Compiler Files
The following tables list the logical input and output files used by the compiler. The
values for the file attributes INTNAME, KIND, INTMODE, MAXRECSIZE, BLOCKSIZE,
and FILETYPE are listed for each file. You can change the values of certain attributes by
using a file equation when you initiate the compiler. For more information on file
attributes, refer to the File Attributes Programming Reference Manual.
Each type of input and output file is discussed in the paragraphs following the tables.
Table 15–1. Compiler Input Files

INTNAME

CARD

Initiation

KIND

WFL

READER

CANDE

DISK

SOURCE

WFL and CANDE

COPY files

INTMODE

MAXRECSIZE
and
BLOCKSIZE

FILETYPE

EBCDIC

Taken from
physical file

DISK

EBCDIC

Taken from
physical file

WFL and CANDE

DISK

EBCDIC

Taken from
physical file

INCLUDE files

WFL and CANDE

DISK

EBCDIC

Taken from
physical file

INITIALCCI

WFL and CANDE

DISK

EBCDIC

Taken from
physical file

Note: COPY and INCLUDE are not internal file names. Rather, COPY files are files used
with the COBOL COPY statement. INCLUDE files are files used with the INCLUDE
compiler option.
Table 15–2. Compiler Output Files

INTNAME

Initiation

KIND

INTMODE

MAXRECSIZE

BLOCKSIZE

FILETYPE

CODE

WFL/CANDE

DISK

HEX

30 words

270 words

—

NEWSOURCE

WFL/CANDE

DISK

EBCDIC

15 words

450 words

—

LINE

WFL /CANDE

PRINTER

EBCDIC

22 words

—

ERRORFILE

WFL

DISK

EBCDIC

12 words

—

CANDE

REMOTE

WFL/CANDE

DISK

EBCDIC

510 words

XREFFILE

8600 1518–307

15–3

Input and Output Data Flow

Input Files
The compiler can receive input from a primary file (named CARD), a secondary file
(named SOURCE), or from files in the COBOL library that are accessed through a COPY
statement. Input received from more than one file is merged according to sequence
numbers or according to instructions in the COPY statement.
The EXTMODE (character type) of the input files can be EBCDIC or ASCII. The
MAXRECSIZE of the files must be large enough for a minimum of 72 characters. The
attributes MAXRECSIZE and BLOCKSIZE need not be explicitly defined; the values for
these attributes are taken from the physical file (FILETYPE=8).

CARD File
The file named CARD is the primary input file of the compiler. It must be present for each
compilation. The default KIND attribute of the CARD file depends on how the compiler is
initiated.

•

Initiated through WFL: If no file equate statements are used, the CARD file is
assumed to be a card reader file.

•

Initiated through CANDE: If no file equate statements are used, the CARD file is
assumed to be a disk file.

SOURCE File
The file named SOURCE is the secondary input file of the COBOL compiler. It is an
optional file. If no file equate statements are used, the SOURCE file is assumed to be a
disk file (regardless of how the compiler is initiated).
The SOURCE file is used only for input if the MERGE option is TRUE. When MERGE is
TRUE, records from the SOURCE file are merged with those of the CARD file on the
basis of sequence numbers. If a record from the CARD file and a record from the
SOURCE file have the same sequence number, the CARD file record is used and the
SOURCE file record is ignored. Refer to “MERGE Option” later in this section for more
information.

COPY Library Files
The COBOL compiler can obtain additional source input from files in the COBOL library.
The compiler incorporates records from library files in response to a COPY statement in
the CARD or SOURCE file. Input from library files is added to input from the CARD and
SOURCE files, as directed by the COPY statement.
For more information, refer to the “COPY Statement” in Section 6.

15–4

8600 1518–307

Input and Output Data Flow

INCLUDE Files
The COBOL compiler can be directed to use alternate sources of source language input
through the INCLUDE compiler option. When the compiler encounters an INCLUDE
option, input from the file containing the INCLUDE option is suspended and all or a
specified portion of the INCLUDE file is processed by the compiler. When the compiler
completes processing of the INCLUDE file, input from the file containing the INCLUDE
option resumes.
For more information, refer to “INCLUDE Option” in this section.

INITIALCCI File
The INITIALCCI file is an optional input file used to specify the initial settings of compiler
options. Different initial settings can be invoked depending on whether the compilation
originates from CANDE or from WFL.
Each user can use a customized INITIALCCI file, or a system-wide global INITIALCCI file
can be used. The compiler searches for the INITIALCCI file using the standard usercode
and family name conventions. If the file is not found, the compiler proceeds without it.
The INTNAME attribute of the INITIALCCI file is INITIALCCI. The file can be file-equated
at compilation time. The FILEKIND attribute of the INITIALCCI file does not need to
match the FILEKIND attribute of the program being compiled.
Ú
³
³
³
³
³
À

ä
³
ã
³
æ

mnemonic-name
BATCH
INTERACTIVE

å
³
â
³
ç

¿
³
³
³
³
³
Ù

compiler-control-record

The following is a summary of the components of an INITIALCCI record:
mnemonic-name
BATCH
INTERACTIVE

These optional identifiers specify how the compiler-control-record is processed. If a
mnemonic-name is specified, and it matches a valid file kind recognized by the system,
then the compiler-control-record that follows is used only when a source file with that file
kind is being compiled. If the mnemonic-name does not match a valid file kind, the entire
record, including the compiler-control-record, is handled as a comment.
The keyword BATCH specifies that the compiler-control-record is used only when the
compilation originates through WFL.
The keyword INTERACTIVE specifies that the compiler-control-record is used only when
the compilation originates through CANDE.

8600 1518–307

15–5

Input and Output Data Flow

compiler-control-record

This can be any valid compiler control record. If an optional identifier followed by a colon
is specified (a mnemonic-name, or the keywords INTERACTIVE or BATCH), then the
compiler-control-record is used only under the conditions described earlier. If an optional
identifier does not precede the compiler-control-record, then the compiler-control-record
is used for all compilations, regardless of the source language, or how the compilation
originated. Compiler control records can begin with a currency sign ($), but it is not
required. Note that the currency sign is optional only in the INITIALCCI file. For more
information on compiler control records, refer to “Compiler Control Options” later in this
section.
Before the INITIALCCI file is read, all compiler control options are set to their default
values. The INCLUDE compiler control option is not permitted in the INITIALCCI file.
The following is an example of an INITIALCCI file:
COBOL85:
INTERACTIVE:
BATCH:

SET OPTIMIZE XREFFILES RESET BOUNDS
ERRORLIMIT = 20 OPTION (SET USEROPTION)
ERRORLIMIT = 50 SET ERRORLIST
RESET LIST
TARGET = LEVEL4
PAGESIZE = 122
% USE LASER PRINTER
SET NEW

This INITIALCCI file has the following effects:

•

If the primary input source file is a COBOL85 source file, the OPTIMIZE and
XREFFILES compiler options are set to TRUE, and the BOUNDS compiler option is
set to FALSE.

•

If the compilation originated through CANDE, the ERRORLIMIT compiler option is set
to 20, and the user option USEROPTION is set to TRUE.

•

If the compilation originated through WFL, the ERRORLIMIT compiler option is set to
50, and the ERRORLIST option is set to TRUE.

•

For all compilations, the LIST compiler option is set to FALSE, the TARGET compiler
option is set to LEVEL4, the PAGESIZE compiler option is set to 122, and the NEW
compiler option is set to TRUE.

As shown by the PAGESIZE entry in the preceding example, the percent sign character
can be used to delimit a comment. The compiler ignores all characters that follow a
percent sign character.

15–6

8600 1518–307

Input and Output Data Flow

Controlling Compiler Input
The following general capabilities are available for controlling the source language input
processed by the compiler:

•

Redirecting compiler input to an alternate source

•

Ignoring defined blocks of source language input based on evaluation of a condition

The INCLUDE compiler option instructs the compiler to temporarily redirect compiler
input to a specified alternate source. The compiler uses the alternate source as input
until either the alternate source is exhausted or a specified range within the alternate
source is exceeded. Such a range can be a single sequence number, or a sequence
number range. Also, the specified range can be a string that identifies an area of the
alternate source previously demarcated with the COPYBEGIN and COPYEND compiler
options. For more information, refer to the INCLUDE, COPYBEGIN, COPYEND, SEARCH,
and TITLE compiler options later in this section.
The IF, ELSE IF, ELSE and END compiler options are “conditional compilation phrases.”
These phrases define areas of the source language input that are compiled only if a given
condition is true. For example, program debug code can be conditionally compiled based
on the setting of a user option as shown in the following example:
$ OPTION (SET USERDEBUG)
.
.
.
$ IF USERDEBUG
MOVE ERROR-CODE TO DEBUG-CODE.
PERFORM WRITE-DEBUG-INFO.
$ ELSE
PERFORM NONFATAL-ERR-RECOVERY.
$ END
The IF, ELSE, ELSE IF, and END compiler options are discussed in “Conditional
Compilation Options” later in this section.

8600 1518–307

15–7

Input and Output Data Flow

Output Files
The COBOL compiler creates from one to four files, depending on the options used
during compilation. The four possible output files are:

•

Object code file (named CODE)

•

Updated symbolic file (named NEWSOURCE)

•

Line printer compilation listing (named LINE)

•

Error message listing (named ERRORFILE)

CODE File
The COBOL compiler generates the file named CODE, unless the compiler is directed to
check for syntax only. The file CODE contains the executable object code of the
program.
The status of this file after compilation depends on directions in the COMPILE statement
and on the presence of syntax errors. This file can be:

•

Stored permanently

•

Executed and then discarded

•

Discarded after compilation

Refer to the COMPILE statement in the Work Flow Language (WFL) Programming
Reference Manual and the CANDE Operations Reference Manual.

NEWSOURCE File
The file named NEWSOURCE is produced only if the NEW option is TRUE. It is an
updated source file that contains actual compiled source input from the CARD and
SOURCE input files. If no file equate statements are used, the NEWSOURCE file is
created on disk. For more information, refer to “NEW Option” later in this section.

15–8

8600 1518–307

Input and Output Data Flow

LINE File
The file named LINE is always produced unless the LIST option is set to FALSE. The
default value of the LIST option differs depending on how the compiler is initiated.

•

Initiated through CANDE: the default value of LIST is FALSE. The LIST option must
be set to TRUE before the LINE file can be produced.

•

Initiated through WFL: the default value of LIST is TRUE, and the LINE file is
produced.

If no file equate statements are used, the LINE file is written to a printer.
The content of the LINE file depends on the CODE option. The minimum amount of
information in the LINE file is:

•

Program source code used as input to the compiler

•

Code segmentation information

•

Error messages and error count (if syntax errors have occurred)

ERRORFILE File
The file named ERRORFILE (External name ERRORS) is produced only if the ERRORLIST
option is TRUE. The default value of the ERRORLIST option and the default KIND
attribute of the ERRORFILE file depend on how the compiler is initiated, as shown in the
following table:

Then the
Default value of
ERRORLIST is . . .

And the ERRORFILE is . . .

Through
CANDE

TRUE

Produced.

Through WFL

FALSE

If the compiler
is initiated . . .

If a file equate statement is used, the error
file is written to a printer; otherwise, the
error file is written to the remote station that
initiated the compiler.
Not produced.

ERRORFILE has a copy of every source record that contains a syntax error, followed by
all syntax errors that occurred for the record. If no syntax errors occur during compilation,
ERRORFILE is not produced (regardless of the ERRORLIST option).

8600 1518–307

15–9

Using System Support Libraries

Using System Support Libraries
The following system support libraries are available for creating COBOL85 programs:

Library Name

Provides support for . . .

SLICESUPPORT

Intrinsics, error and warning message handling, and other
miscellaneous compile and runtime support.

COBOL85SUPPORT

Certain types of Inter Program Communication (IPC) at run
time.

Be sure that the release level of each support library is greater than or equal to the
release level of the COBOL85 compiler used to create executing code files.

15–10

8600 1518–307

Compiling and Executing COBOL Programs

Compiling and Executing COBOL Programs
There are three ways to compile or execute a COBOL program. The method you use
depends on decisions made at your installation. The three methods are:

•

Through WFL

•

Through CANDE

•

From the ODT

The following paragraphs briefly summarize all three methods.

Compiling and Executing through WFL
Work Flow Language (WFL) is a job control language that lets you compile or execute
programs. It also enables you to pass files between programs and perform other job
control functions.
WFL is a powerful tool that can significantly streamline your data processing operations.
Before using WFL, however, become familiar with the WFL language and how it is used
at your installation. For detailed information on WFL, refer to the Work Flow Language
(WFL) Programming Reference Manual.
WFL provides both the Compile and Run functions. Procedures for using WFL vary
greatly from site to site, but the following examples provide a brief overview of how WFL
functions with the COBOL85 compiler. Procedures at your installation might be
significantly different.
Examples of WFL Job Files
The following are sample WFL statements that illustrate the syntax used to compile a
program:
?BEGIN JOB EXAMPLE;
COMPILE < program title> WITH COBOL85 LIBRARY;
COMPILER DATA CARD

?END JOB;
WFL permits many different compilation options. For more information, refer to the WFL
Reference Manual.
To run an existing compiled program in WFL, you must create a WFL job file. To create a
WFL job file, simply create a WFL job file with a job header, followed by a RUN
statement, and finally an END JOB statement.
?BEGIN JOB RUN/A/PROGRAM;
RUN SAMPLE/PROGRAM;
?END JOB;

8600 1518–307

15–11

Compiling and Executing COBOL Programs

Compiling and Executing through CANDE
CANDE provides an easy, flexible way to create, edit, and execute COBOL programs.
To create a COBOL file, enter the MAKE command (abbreviated as M) and designate the
file type as COBOL. You can then enter the needed source code. To modify an existing
COBOL file, use the GET command (abbreviated as G) with the correct file name to
retrieve the file. You can then edit the existing code.
When you finish editing or entering code, you can compile the code with the COMPILE
command (abbreviated as C). To compile on your system, enter C, followed by WITH
COBOL85. To use specific compiler options, enter the complete COMPILE command.
Syntax for the COMPILE command is provided in the CANDE Reference Manual.
When the code begins to compile, you receive a beginning of task (BOT) message and
any syntax errors. When compilation is finished, an end of task (EOT) message is
displayed.
If the compilation finishes without syntax errors, you can use the RUN command
(abbreviated as R) to run the program. You can also enter R before compiling the
program. This will compile the program and then execute it. (This option is normally used
only when you are certain there are no syntax errors in the program.)
When you create a file with the file type “C85”, you will use the COBOL85 compiler or
default compiler. This way, you don't need to specify the compiler name along with the
compile command.
To compile and run a COBOL program through CANDE, follow these steps:

Step

CANDE Command

MAKE C85

Description

CANDE recognizes C85 as a valid file kind for
the MAKE command.

—or—

15–12

GET
G

This is the command to retrieve an existing file.

COMPILE
C
—or—

This compiles the current workfile.

C WITH COBOL85

This explicitly compiles a file with the
COBOL85, regardless of the file kind of the file.

RUN
R

This executes the current workobject (object
code file produced by compiling the current
workfile).

8600 1518–307

Compiling and Executing COBOL Programs

Compiling and Executing from the ODT
Compiling and executing a COBOL program from the ODT is different from working in
CANDE or through a user-created WFL deck. When you compile or run from the ODT,
the MCP converts the commands entered through the ODT into the appropriate WFL
commands using the WFL Formatter.
To compile from the ODT, identify the source file name and the compiler name in the
COMPILE command, as in the following examples:
Unsecured ODT
COMPILE WITH COBOL85 LIBRARY;
FILE CARD (TITLE = );
Secured ODT
USER = /;
COMPILE WITH COBOL85 LIBRARY;
FILE CARD (TITLE = , KIND = DISK);
In the preceding examples, the WITH COBOL85 LIBRARY option directs the system to
use the COBOL85 compiler and to save the resultant code file. The FILE CARD syntax
element is a file equate statement that identifies to the compiler the name of the source
file and the file's location.
To execute an existing program from the ODT, enter the program name as part of the
RUN command. If the program does not explicitly define its files, use a file equate
statement to associate the files in the program with the correct existing files. The
following are examples of the appropriate syntax to execute a program from the ODT:
Unsecured ODT
RUN
Secured ODT
USER = /; RUN

Displaying the Compiling Progress
A user can view the compiling progress by entering the ?HI command for the compiler
mix number at any time during compilation. The compiler responds with the same
information provided by the ?CS command, augmented with the program name specified
in the PROGRAM-ID paragraph. When compiling a multi-program symbol file, such as
BINDSTREAM, the ?HI command is useful in determining which program is currently
being compiled. Refer to “BINDSTREAM Option” later in this section.

8600 1518–307

15–13

Compiling and Executing COBOL Programs

Preventing Stack Overflows
The size of a process stack is controlled by the STACKLIMIT task attribute. When a
process cannot proceed further without exceeding the limit established by this attribute,
the system discontinues the process and returns the error message STACK OVERFLOW.
The STACKLIMIT task attribute defaults to a value of 6000 words. It is unlikely that any
process stack will reach this size if it is running as intended. The STACK OVERFLOW
error usually indicates that a process has entered into an infinite loop of procedure calls.
Because each procedure call adds an activation record to the process stack, the process
stack quickly exceeds the STACKLIMIT value.
If a process receives a STACK OVERFLOW error, and you determine that the process
was running as intended, then you can remedy the problem by assigning a higher value
to the STACKLIMIT task attribute before initiating the process. The highest value
STACKLIMIT can be set to is approximately 64000 words.
Because a process stack is built exclusively in save memory, the save memory
restrictions also effectively limit the size of the process stack. For more information, refer
to the Task Management Programming Reference Manual.

15–14

8600 1518–307

Types of Compiler Control Options

Types of Compiler Control Options
Compiler control options are divided into the following types:

•

Boolean

•

Boolean Title

•

Boolean Class

•

Enumerated

•

Immediate

•

String

•

User-defined

•

Value

Boolean Compiler Options
A Boolean option is either enabled (set to TRUE) or disabled (set to FALSE). When
enabled, the compiler applies the option to all subsequent processing until the option is
disabled. The following is a list of the available Boolean options. Where a synonym exists
for an option, it is shown in parentheses.
ANSI

ANSICLASS

ASCII

AUTOINSERT

BINARYCOMP

BINARYEXTENDED

BINDINFO

BINDSTREAM

BOUNDS

CODE

COMMON

CONCURRENTEXECUTION

CORRECTOK

CORRECTSUPR

DELETE(VOIDT)

FS4XCONTINUE

FREE

INCLNEW

LIBRARYLOCK

LIBRARYPROG

LINEINFO

LIST

LISTDOLLAR

LISTINCL (INCLLIST)

LISTINITIALCCI

LISTOMITTED
(LISTO)

LISTP

LIST1

LOCALTEMP

MAP (STACK)

MUSTLOCK

NEWSEQERR

OMIT

OPT1

OPT2

OPT3

OPT4

OPTION

OWN

SEPARATE

SEQUENCE (SEQ)

SHOWOBSOLETE

SHOWWARN

STRICTPICTURE

SUMMARY (TIME)

TEMPORARY

UDMTRACK

VOID

WARNFATAL

WARNSUPR

XREF

8600 1518–307

15–15

Types of Compiler Control Options

Boolean Title Compiler Options
A Boolean title option sets the value of a Boolean option and optionally associates a file
name with the option. The following is a list of the available Boolean title options:
ERRORLIST (ERRLIST)
LIBRARY
MERGE
NEW
XREFFILES

Boolean Class Compiler Options
A Boolean class option is a logical grouping of related Boolean options into a single
Boolean option. An action performed against the class option affects all of the
subordinate options, while an action performed against one of the subordinate options
affects only that subordinate option and none of the others that comprise the class. For
example, the OPTIMIZE compiler option is a class option. The GAMBLE, GRAPH, LEVEL,
TIMING, UNRAVEL, and VECTOR_OPS subordinate options comprise the OPTIMIZER.
An action can be performed against the OPTIMIZE option altering the setting of all of the
subordinate options. The following shows the OPTIMIZE option being set to FALSE.
$ RESET OPTIMIZE
Also, an action can be performed against the LEVEL subordinate option (for example)
without affecting the other subordinate options (the GAMBLE, GRAPH, TIMING,
UNRAVEL, and VECTOR_OPS subordinate options retain their setting). The following
shows the LEVEL subordinate option of the OPTIMIZE option being set to TRUE.
$ SET OPTIMIZE (LEVEL)
An action can be performed against the class option, and a different action performed
against subordinate options in the same compiler control record (CCR). The following
shows the OPTIMIZE option being set to FALSE, but the LEVEL subordinate option being
set to TRUE.
$ RESET OPTIMIZE (SET LEVEL)

15–16

8600 1518–307

Types of Compiler Control Options

The following is a list of the available Boolean class options:
ANSICLASS

FARHEAP

BOUNDS

OPTIMIZE

COMPATIBILITY

Enumerated Compiler Options
An enumerated option is an option whose setting is limited to a predetermined set of
symbolic values. A symbolic value is a keyword that represents value meaningful to the
compiler. For example, the STRINGS compiler option is an enumerated option. The set of
values to which the STRINGS compiler option can be set is limited to the symbolic values
EBCDIC and ASCII. The following is a list of the available enumerated options:
MEMORY_MODEL

STRINGS

SHARING

TARGET

Immediate Compiler Options
An immediate option is applied by the compiler when the option is encountered in source
code. The function performed by an immediate option is independent of any subsequent
processing by the compiler. Immediate options can have associated parameters. The
following immediate options are available:
BINDER_MATCH

ELSE

END (END IF)

ELSE IF

PAGE

8600 1518–307

15–17

Types of Compiler Control Options

String Compiler Options
A string option is an option to which a string is associated. The string can be delimited by
either single or double quotation marks, so long as they are used consistently. A string
delimited at the beginning by a single quotation mark must be delimited at the end by a
single quotation mark. An example of a string option is the FOOTING compiler option
used to specify a string to be placed at the bottom of each page of the listing. The
following is a list of the available string options:
COPYBEGIN

MODULEFILE

COPYEND

NEWID

FOOTING

LI_SUFFIX

TITLE

MODULEFAMILY

User-Defined Compiler Options
Users can define compiler control options in addition to the standard options that are
listed under “Types of Compiler Control Options.” A user-defined option is a Boolean
option that can be manipulated through the SET, RESET, and POP options. To create a
user-defined option, the user declares the option implicitly by using it in a DOLLAR ($)
statement. The first 31 characters of a user-defined option must be unique.

Value Compiler Options
A value option stores a specific value that the compiler uses when applying the option.
The following is a list of the available value options:
ERRORLIMIT (LIMIT)

PAGEWIDTH

FEDLEVEL

Sequence Base

LEVEL

Sequence Increment

IPCMEMORY

VERSION

PAGESIZE
The INCLUDE option is a specially handled option, and is described later in this section.

15–18

8600 1518–307

Syntax for Compiler Control Options

Syntax for Compiler Control Options
There are two ways to specify compiler control options:

•

On compiler control records (CCRs)

•

By using commands at compile time

These two methods are discussed in the following two sections.

Compiler Control Records
Compiler control records (CCRs) are source code records with a currency sign ($) in
column 7 and an optional $ in column 8. You can enable, disable, or change the value of
an option by inserting a CCR into the source code of the program. A CCR contains a
compiler control option and its parameters (if any).
Occasionally, the value of an option may take effect prematurely because of the
compiler’s look-ahead processing of source records. When this occurs, the value of an
option is applied to a source record that preceded it. To prevent this premature effect,
use the semicolon (;) to inhibit the compiler’s look-ahead processing. If a source line is
followed by a CCR, and you want to isolate the source line from the semicolon between
the source line and the CCR, you can place the semicolon at the end of the source line or
insert it on a line between the source line of interest and the CCR.
Generally, CCRs can be inserted at any point in the source code of a program. Some
specific CCRs must be included at the beginning of the source code, before the
Identification Division of the program, or before the first syntactical item in a separately
compiled program. (CCRs that must be included at the beginning are noted in the option
descriptions on the following pages.)
The compiler retains the setting of a compiler option for the duration of the compilation,
unless the setting of the option is explicitly changed. This means that if the source
language input file contains sequential programs to be compiled separately, then the
compiler retains the settings of compiler options from one program to the next. To
prevent this from occurring, you must explicitly change the setting of compiler options
between the separate programs (that is, between the END PROGRAM statement of one
program and the first syntactical element of the next program).
Frequently, a CCR contains more than one option. All options on a CCR follow the
currency sign ($). At least one space must follow each option. No option can continue
past column 72 of a CCR.

8600 1518–307

15–19

Syntax for Compiler Control Options

The general syntax used for all compiler control records (CCRs) is shown in the following
syntax diagrams and discussed on subsequent pages.

$ [ $ ]

Ú
³
³
³
À

SET
RESET
POP

¿
³
³
³
Ù

[ option-name ]

[ option-parameters ]

...

or
$ [ $ ]

[ SET ]

{ Boolean-option-name } = { Boolean-expression }...

CCRs must have a currency sign ($) in column 7 and may have an optional $ in column 8.
The $ determines how the CCR is affected by the NEW compiler control option.
The NEW option directs the compiler to create a new source file (named NEWSOURCE).
NEWSOURCE contains all of the source code records used during compilation.

•

If a CCR has a $ (currency sign) in column 7, but not in column 8, then the CCR is not
included in the new source file created by the NEW option. For example, frequently a
MERGE option is not included in the newly generated source code. A CCR with only
one $ is called a temporary CCR.

•

If a CCR has a $ in columns 7 and 8, the CCR is included in the source code created
by NEW. This is called a permanent CCR.

A CCR with a $ and no following options has no effect except in the following special
cases:

•

When the MERGE option is TRUE

•

When a record in the primary input file (named CARD) contains a blank CCR

•

When a record in the secondary input file (named SOURCE) has the same sequence
number as the blank CCR in the primary input file

In any of these cases, the record in the secondary input file is ignored.
SET

SET saves the current setting of each option of the CCR and sets each option to TRUE
(enabled or ON). This option has a register that stores the last 47 settings of the option.
The option can also be set to the value of an optional Boolean-expression.
RESET

RESET saves the current setting of each option of the CCR and sets each option to
FALSE (disabled or OFF). This option has a register that stores the last 47 settings of the
option.

15–20

8600 1518–307

Syntax for Compiler Control Options

POP

POP discards the current setting of each option of the CCR and sets each option to its
previous setting. This option has a register that stores the last 47 settings of the option.
If no previous setting exists, POP sets the option to FALSE.
option-name

This element represents the name of any valid COBOL85 compiler control option. The
option can be a Boolean option, a value option, or an immediate option.
Boolean-option-name

This element represents the name of a Boolean compiler control option. A Boolean
option can only be set to TRUE (enabled, ON), or FALSE (disabled, OFF). A list of the
Boolean options is included earlier in this section.
When the SET option action indicator is used, a Boolean option can be assigned the value
of Boolean-expression.
Boolean-expression

This element represents an expression that can be evaluated as a Boolean value
according to the standard rules of Boolean algebra.
A Boolean-expression can be simple (for example, the value of a different Boolean
option), or it can be modified by the standard Boolean operators AND, OR, or NOT. You
can even nest Boolean-expressions within other Boolean-expressions by enclosing them
in parentheses. Complicated Boolean-expressions should be examined to make certain
that they yield the correct value in all situations.

Boolean-Expression Syntax

{Boolean-factor}

8600 1518–307

Ú
³
³
³
À

ä AND å
ã ïïï â
æ OR ç
ïï

Boolean-factor

¿
³
³
³
Ù

...

15–21

Syntax for Compiler Control Options

Boolean-Factor Syntax
ä
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
æ

ä NOT å
³ ïïï ³
ã ^ â
³
³
æ ! ç

Boolean-factor

TRUE
ïïïï
FALSE
ïïïïï
(Boolean-expression)
Boolean-condition
enumerated-condition
integer-condition

å
³
³
³
³
³
³
³
â
³
³
³
³
³
³
ç

Boolean-Condition Syntax

ä
ã
æ

Boolean-option-name
Boolean-class-option-name
Boolean-class-option-name (Boolean-subordinate-option-name)

Ú
³
³
³
³
³
³
³
³
À

ä
³
³
ã
³
³
³
æ

ä = å
ã
â
æ == ç
ä ^= å
ã != â
æ < >ç

å
³
³
â
³
³
³
ç

Boolean-factor

å
â
ç

¿
³
³
³
³
³
³
³
³
Ù

Boolean-class-option-name

This element represents the name of a Boolean class compiler control option. A Boolean
class option can be set to TRUE or reset to FALSE. In addition, it possesses subordinate
options which can be set or reset. To specify a subordinate option, you place the option
name in parentheses following the Boolean class option, as in $SET OPTIMIZE (LEVEL).
Boolean-subordinate-option-name

This element represents the name of a Boolean subordinate option. It must be
subordinate to the Boolean class option.

15–22

8600 1518–307

Syntax for Compiler Control Options

Enumerated-Condition Syntax
ä
³
³
³
ã
³
³
³
æ

enumerated-option-name

ä
ã
æ

^= å
!= â
< > ç

å
³
³
³
â
³
³
³
ç

å
â
ç

enumerated-constant

enumerated-option-name

This element represents the name of an enumerated option.
enumerated-constant

This element represents the symbolic value of the preceding enumerated option.

Integer-Condition Syntax

integer-option-name

ä
³
³
³
³
ã
³
³
³
³
æ

<
< =
>
> =
=
ä
ã
æ

^= å
!= â
< > ç

å
³
³
³
³
â
³
³
³
³
ç

ä
ã
æ

integer-option-name
integer-constant

å
â
ç

integer-option-name

This element represents the name of a value option that takes an unsigned integer value.
integer-constant

This element represents an unsigned integer constant. affect any nonsettable options of
the CCR. If an option action indicator is not specified, the SET action is assumed.

8600 1518–307

15–23

Syntax for Compiler Control Options

Conditional Compilations Options
Conditional compilations options are used to conditionally include or omit certain source
records in the compilation. Compiler control options encountered in the source language
input between any IF, ELSE IF, ELSE, or END compiler control options are always
processed in the normal fashion, regardless of the value of the Boolean-expression of the
IF option.
ä
³
ã
³
æ

IF boolean-expression
ïï
[ ELSE
[ IF boolean-expression ] ]
ïïïï
ïï
END [ IF ]
ïïï

å
³
â
³
ç

Type: Immediate
If the Boolean-expression in the IF option is TRUE, the records between the IF and a
subsequent ELSE IF, ELSE, or END compiler control option are compiled, and all records
between any subsequent ELSE IF or ELSE, and END compiler control options are
ignored. Similarly, if the IF compiler control option is FALSE, but a subsequent ELSE IF
option is TRUE, then the records between the ELSE IF and subsequent ELSE or END are
compiled, with the other records ignored. If the IF and ELSE IF options resolve to FALSE,
the records between the ELSE (if specified) and END options are compiled.
For the syntax of boolean-expression, refer to “Syntax for Compiler Control Options”
earlier in this section. The following are examples of conditional compilations.
The IF Option
Program debug source language input can be compiled only if a user option called
USERDEBUG is set to TRUE, as in the following example:
$ OPTION (SET USERDEBUG)
.
.
.
$ IF USERDEBUG
MOVE SPACES TO DEBUG-LOCATION.
MOVE "GETTING NEXT ENTRY FROM LIST".
PERFORM DEBUGGER.
$ END
MOVE NEXT-LIST-ENTRY TO WORK-ITEM.
.
.
.

15–24

8600 1518–307

Syntax for Compiler Control Options

The IF and ELSE Options
The behavior of a program can be modified through the setting of a user option, as in the
following example:
$ OPTION (RESET OLDFORMAT)
.
.
.
DATA DIVISION.
FILE SECTION.
FD ACCOUNT-FILE BLOCK CONTAINS 3 RECORDS.
* SUPPORT BOTH THE OLD FORMAT AND THE NEW FORMAT FOR NOW
* FIRST THE OLD FORMAT
$ IF OLDFORMAT
01 MAJ-ACCT-INFO.
05 ACCT-NUMBER.
07 BRANCH
PIC 9999.
07 DISTRICT
PIC 999.
07 PIN
PIC 99.
05 ASSOC-FILE-NO
PIC 999.
05 CURRENT-STATE
PIC X(2).
05 LAST-ACCESS-DATE
PIC X(6).
05 EXPIRATION-DATE
PIC X(6).
* THE NEW FORMAT CONTAINS THE FOLLOWING CHANGES
*
PIN EXPANDED FROM 2 TO 4 DIGITS
*
ASSOC-FILE-NO EXPANDED FROM 3 TO 4 DIGITS
$ ELSE
01 MAJ-ACCT-INFO.
05 ACCT-NUMBER.
07 BRANCH
9999.
07 DISTRICT
999.
07 PIN
9999.
05 ASSOC-FILE-NO
9999.
05 CURRENT-STATE
PIC X(2).
05 LAST-ACCESS-DATE
PIC X(6).
05 EXPIRATION-DATE
PIC X(6).
$ END
.
.
.

8600 1518–307

15–25

Syntax for Compiler Control Options

The IF and ELSE IF Options
A series of condition tests can be used to alter the behavior of a program, as in the
following example:
$ OPTION (SET ALPHA RESET USER1 USER2 USER3)
.
.
.
*
* USE USER OPTIONS TO DETERMINE THE SECURITY LEVEL OF THIS VERSION
*
$ IF ALPHA
PERFORM ALPHA-INITIALIZE.
$ ELSE IF USER1
PERFORM STANDARD-INITIALIZE THROUGH LEVEL-ONE-USER.
$ ELSE IF USER2
PERFORM STANDARD-INITIALIZE THROUGH LEVEL-TWO-USER.
$ ELSE IF USER3
PERFORM STANDARD-INITIALIZE THROUGH LEVEL-THREE-USER.
$ END
.
.
.

For more information on conditional compilation, refer to “Controlling Compiler Input”
earlier in this section.

Setting Compiler Options When Initiating the Compiler
You can set compiler options at compile time by including the TASKSTRING task attribute
with the command you use to initiate compiling.
This method of setting options can be used instead of, or in addition to, any compiler
control records (CCRs) in the INITIALCCI file and/or in the program source. The
COBOL85 compiler interprets the value of the TASKSTRING task attribute as if it were a
compiler control option, acting on it after the INITIALCCI file but before any CCRs in the
program source.
Here is an example of setting the LIST option at compile time. This example uses
CANDE, although use of this method is not limited to CANDE.
COMPILE; COMPILER TASKSTRING = "LIST"
For further discussion of the TASKSTRING task attribute, refer to the Task Attributes
Programming Reference Manual.

15–26

8600 1518–307

Compiler Options

Compiler Options
The following pages describe the compiler control options available in the COBOL85
compiler. Syntax diagrams are included for those options that have parameters or more
than one valid name. Diagrams are not included for options where the syntax is the same
as the option name.
Some options cause a file to be created or direct the compiler to use a specific file. The
compiler supplies default values for the names and locations of these files. You can
override the default values by using a file equate statement when the compiler is
initiated. For example:
FILE CODE = ON DISK

ANSI Option
Note: Setting $ANSI is effectively equivalent to setting $ANSICLASS(ALL). It is
recommended that you use the $ANSICLASS option instead of the $ANSI option. The
$ANSICLASS option is intended to supercede the $ANSI option in a future release.
Type: Boolean
Default: FALSE
The ANSI option affects the placement of the flagging warnings that contain
nonconforming or obsolete syntax. When ANSI is set, all flagging warnings point to the
specific clause, statement, or header that contains the nonconforming or obsolete
syntax. When ANSI is reset, all flagging warnings point to the specific nonconforming or
obsolete syntax in the source program line.
The ANSI option also affects processing of the ACCEPT statement and the COPY
statement. For details, refer to “ACCEPT Statement” and “COPY Statement” in
Section 6.
The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler uses ANSI COBOL74 rules in
situations where differences exist.

SET

TRUE

The compiler uses ANSI COBOL85 rules whenever
it encounters a situation where the ANSI COBOL85
rules differ from previous versions of COBOL.

8600 1518–307

15–27

Compiler Options

ANSICLASS Option
It is recommended that you use the $ANSICLASS option instead of the $ANSI option.
The $ANSICLASS option is intended to supercede the $ANSI option in a future release.
Type: Boolean Class

ANSICLASS
ïïïïïïïïï

Ú
³
³
³
³
³
³
³
³
³
³
³
³
³
³ (
³ ï
³
³
³
³
³
³
³
³
³
³
³
³
À

ä
³
³
³
³
³
³
³
³
³
³
³
³
ã
³
³
³
³
³
³
³
³
³
³
³
³
æ

ALL
å
ïïï
³
ACCEPT
³
ïïïïïï
³
COPY
³
ïïïï
³
FLAGGING
³
ïïïïïïïï
³
FS14
³
ïïïï
³
FS24
³
ïïïï
³
FS43
³
ïïïï
â
FS44
³
ïïïï
³
FS46
³
ïïïï
³
FS48
³
ïïïï
³
PARAMETERERROR
³
ïïïïïïïïïïïïïï
³
REDEFINES
³
ïïïïïïïïï
³
REDEFINESPARAMETER³
ïïïïïïïïïïïïïïïïïï³
ç

. . .

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
) ³
ï ³
³
³
³
³
³
³
³
³
³
³
³
³
Ù

The ANSICLASS option provides various suboptions that you can set to

•

Affect the processing of the ACCEPT and COPY statements

•

Determine which I/O error conditions will be flagged with warnings

•

Affect the placement of flagging warnings that contain nonconforming or
obsolete syntax
The options that begin with “FS” describe semantic errors which were not detected
by the COBOL74 compiler. Because these suboptions can increase the amount of
processor time required to execute certain I/O statements, users migrating from
COBOL74 should determine if the benefit of detecting these errors is worth the cost
of performance.

The $ANSICLASS suboptions are described in the following list. Note that all suboptions
except ALL are boolean-valued.

15–28

8600 1518–307

Compiler Options

ALL
Default Value: Not applicable
When set, the ALL suboption implies the inclusion of all of the suboptions available for
the ANSICLASS option.
ACCEPT
Default Value: False (RESET)
When set, the ACCEPT suboption affects the processing of the ACCEPT statement. For
details, refer to “ACCEPT Statement” in Section 6.
COPY
Default Value: False (RESET)
When set, the COPY suboption affects the processing of a COPY statement that
includes the REPLACING phrase. For details, refer to the discussion of continuation lines
and additional lines that accompanies the COPY statement in Section 6.
FLAGGING
Default Value: False (RESET)
When set, the FLAGGING suboption causes all flagging warnings to point to the specific
clause, statement, or header that contains obsolete syntax or nonconforming syntax.
When reset, flagging warnings point only to the source program line that contains
obsolete or nonconforming syntax.
FS14
Default Value: False (RESET)
The FS14 suboption must be set for the compiler to detect the I/O errors defined by file
status value 14. For more information about this file status value, refer to “I-O Status
Codes” in Section 3.
Users migrating from COBOL74 might want to reset this suboption, as COBOL74 did not
provide this functionality.
Note that setting this suboption can increase the amount of processor time used to
execute certain READ statements.
COBOL85 users can improve performance of all I/O statements acting upon either a
sequential file declared with an actual key, or a relative file declared with a relative key,
by declaring the appropriate key as follows:
77 USERSKEY

8600 1518–307

REAL.

15–29

Compiler Options

FS24
Default Value: False (RESET)
The FS24 suboption must be set for the compiler to detect the I/O errors defined by file
status value 24. For details on this file status value, see “I-O Status Codes” in Section 3.
Users migrating from COBOL74 might want to reset this suboption, as COBOL74 did not
provide this functionality.
Note that setting this suboption can increase the amount of processor time used to
execute certain WRITE statements.
COBOL85 users can improve the performance of all I/O statements acting upon either a
sequential file declared with an actual key, or a relative file declared with a relative key,
by declaring the appropriate key as follows:
77 USERSKEY

REAL.

FS43
Default Value: False (RESET)
The FS43 suboption must be set for the compiler to detect the I/O errors defined by file
status value 43. For more information about this file status value, refer to “I-O Status
Codes” in Section 3.
Note that setting this suboption can increase the amount of processor time used to
execute certain DELETE and REWRITE statements.
FS44
Default Value: False (RESET)
The FS44 suboption must be set for the compiler to detect the I/O errors defined by file
status value 44. For more information about this file status value, refer to “I-O Status
Codes” in Section 3.
Note that setting this suboption can increase the amount of processor time used to
execute certain WRITE and REWRITE statements.
FS46
Default Value: False (RESET)
The FS46 suboption must be set for the compiler to detect the I/O errors defined by file
status value 46. For more information about this file status value, refer to “I-O Status
Codes” in Section 3.
Note that setting this suboption can increase the amount of processor time used to
execute certain READ statements.

15–30

8600 1518–307

Compiler Options

FS48
Default Value: False (RESET)
The FS48 suboption must be set for the compiler to detect the I/O errors defined by file
status value 48. For details on this file status value, see “I-O Status Codes” in Section 3.
Setting this suboption can increase the amount of processor time used to execute
certain WRITE statements.
PARAMETERERROR
Default Value: False (RESET)
When set, the PARAMETERERROR suboption changes compiler message 213:
FORMAL PARAMETER ERROR from a warning to an error message. This change
enables stricter checking of incompatible parameter types within ANSI-85 COBOL and
conforms to the COBOL85 parameter checking scheme. When reset, checking is
released to conform to the COBOL74 parameter checking scheme.
The COBOL85 compiler originally supported a different parameter mapping scheme for
ANSI-85 COBOL specifications. In order to support migration, the COBOL85 compiler
has been enhanced to allow a parameter mapping scheme more similar to A Series
COBOL74. The compile-time checking for this parameter mapping scheme, however,
was not put into place as syntax error checking.
REDEFINES
Default Value: False (RESET)
When set, the REDEFINES suboption causes no warnings to be issued on REDEFINES
items. When reset, a warning message is emitted for a 01 REDEFINES item whose size
is different from the redefined item and for a 02 or higher REDEFINES item whose size is
smaller than the redefined item.
REDEFINESPARAMETER
Default Value: False (RESET)
When set, the REDEFINESPARAMETER suboption changes the following error
messages, which are too stringent within ANSI-85 COBOL, to warning messages

•

966: PARAMETER WITH REDEFINES IS ILLEGAL

•

1062: A REDEFINED PARAMETER IS ILLEGAL

•

1063: A PARAMETER FROM AN IMPLICIT REDEFINITION IS ILLEGAL

This change enables all parameters that are with or of REDEFINES to be passed. When a
parameter is redefined, it is possible that the actual parameter length could be different.
This difference is due to the way A Series handles some types. If the redefined item is of
a different length than the REDEFINES item, the extra data becomes accessible in the
callee. As the entire record is sent to the callee with no length restriction, A Series data
corruption can result.

8600 1518–307

15–31

Compiler Options

ASCII Option
Type: Boolean
Default: FALSE
This option controls the default character type used for the compilation. The following
table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

Sets the default character type to EBCDIC.

SET

TRUE

Sets the default character type to ASCII.

The default character type is assumed for all strings when a character type has not been
explicitly specified. The default character type is also used as the default value of the
INTMODE file attribute.
Unless overridden by the ASCII option or the STRINGS = ASCII option, the default
character type is EBCDIC.
STRINGS = ASCII is a synonym for the ASCII option.

AUTOINSERT Option
Type: Boolean
Default: TRUE
This option controls whether or not the Unisys extension described as Automatic
insertion editing under the material associated with the PICTURE clause is to be enabled.
Refer to “Automatic simple insertion editing” in Section 4 of this manual.

Option Setting

Value

Description

RESET

FALSE

Automatic simple insertion editing disabled

SET

TRUE

Automatic simple insertion editing enabled

Although the default setting for the AUTOINSERT option is TRUE, the option itself is
scheduled for deimplementation in a future software release. Upon deimplementation,
the default behavior will be as if the option were RESET.
It is recommended that this option be RESET. For those programs in which simple
insertion of arbitrary symbols using the PICTURE string is needed, use Manual insertion
editing and the (I) symbol as described in the material associated with the PICTURE
clause.

15–32

8600 1518–307

Compiler Options

Manual insertion editing and Automatic insertion editing cannot both occur in the same
PICTURE character string. AUTOINSERT and STRICTPICTURE cannot both be set to
TRUE at the same time.

BINARYCOMP Option
Type: Boolean
Default: FALSE
This option controls how the compiler handles COMPUTATIONAL data items. The
following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

COMPUTATIONAL data items are treated as
COMPUTATIONAL data items. This inhibits the use
of COMPUTATIONAL data items as actual
parameters in calls to procedures written in
languages other than COBOL.

SET

TRUE

COMPUTATIONAL data items are treated as if they
were declared USAGE BINARY EXTENDED.

BINARYEXTENDED Option
Type: Boolean
Default: FALSE
This option controls how the compiler handles BINARY data items. The following table
describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

BINARY data items are treated as BINARY data
items.

SET

TRUE

BINARY data items are treated as if they were
declared as USAGE IS BINARY EXTENDED. If the
TRUNCATED phrase is explicitly specified as
USAGE IS BINARY TRUNCATED, that binary item is
treated as BINARY.

For more information about BINARY EXTENDED data items, refer to “USAGE IS
BINARY” in Section 4.

8600 1518–307

15–33

Compiler Options

BINDER_MATCH Option
ä
ã
æ

å
BINDER_MATCH = (string-1,string-2) . . . â
ç

Type: Immediate
Default: Not applicable
This option verifies that object code files being bound with the Binder are compiled with
the same set of compile-time options. Setting the BINDER_MATCH option adds string-1
and string-2 to the object code file.
String-1 can contain a maximum of 255 characters. This string must not begin with a star
(*).
String-2 specifies the value of string-1.
The strings must match in casing of alphabetic characters. For example, an uppercase
letter “A” does match a lowercase letter “a.”
You can specify a maximum of 200 BINDER_MATCH occurrences. A maximum of
10,000 characters is allowed for the total number of name and value strings.
When the Binder encounters a BINDER_MATCH option in one program that has an
identical first string as a BINDER_MATCH option in the other program, Binder verifies
that the second strings are also identical. If the second strings are different, then
different values were used for the same compile-time option in the two programs. Binder
prints an error message and the bind is aborted.
Note that having two BINDER_MATCH options in the same file with the same first string
and different second strings causes an error at the time of compilation.

15–34

8600 1518–307

Compiler Options

BINDINFO Option
Type: Boolean
Default: FALSE
This option controls whether information used for program binding is placed in the output
object code file. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

Binder information is not placed in the object code file.

SET

TRUE

Binder information is placed in the object code file.

The BINDINFO option does not affect programs compiled with the LEVEL options set to
3 or higher.
This option must be included in the source code before the Identification Division of the
program.
If the program is a HOST program and an external procedure is to be bound in, this
option must be set. COBOL74 users must set this option for HOST program files.

BINDSTREAM Option
Type: Boolean
Default: False
This option controls whether or not the symbolic file to be compiled contains a definition
program and a list of multi-procedure programs separated by a LIBRARY option. The
following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The symbolic file to be compiled does not contain a
definition program and a list of multi-procedure
programs separated by a LIBRARY option.

RESET

TRUE

The symbolic file to be compiled contains a definition
program and a list of multi-procedure programs
separated by a LIBRARY option.

When the BINDSTREAM option is set, a code file title must be specified for each
LIBRARY option.
Example
$BINDSTREAM

$LIBRARY "OBJECT/1"

8600 1518–307

15–35

Compiler Options

$LIBRARY "OBJECT/2"

$LIBRARY "OBJECT/N"

When the preceding symbolic is compiled, multiple multi-procedure code files
(OBJECT/1, OBJECT/2, ..., OBJECT/N) are created for binding purposes.
A definition program contains the declaration of global data items that can be shared by a
list of multi-procedure programs.
Data items declared in the definition program with or without the COMMON clause are
treated as data items declared in the WORKING-STORAGE SECTION with the
COMMON clause. These data items are matched by name and type to the global
directory of the host.
The VALUE clause is not allowed in the definition program if the associated data item is
not a condition name.
A data item in the definition program that is referenced in a subprogram is declared at lex
level 2. Data items declared in a subprogram is declared at the appropriate lex level as
specified in the LEVEL option for the subprogram. If the LEVEL option is set to 2 in the
subprogram, then the lex level is treated as 3.
If a data item of the definition program is referenced in a subprogram, the data item is
included in the code file, otherwise it is ignored.

15–36

8600 1518–307

Compiler Options

BOUNDS Option
Type: Boolean Class
Default: True (SET) for INDEX, True (SET) for STACK, True (SET) for SUBSCRIPT

BOUNDS
ïïïïïï

Ú
³
³
³
³
³
³
³
À

(
ï

ä
³
ã
³
æ

INDEX
ïïïïï
STACK
ïïïïï
SUBSCRIPT
ïïïïïïïïï

å
³
â
³
ç

. . . )
ï

¿
³
³
³
³
³
³
³
Ù

The BOUNDS option provides suboptions that you can use to control the checking of the
upper bounds of indexes and subscripts

Caution
Unpredictable results may be obtained if BOUNDS(INDEX) is FALSE and a
subscript or index is not valid. Results may include data corruption as well as
abnormal program termination.

The effect of this option depends on the following considerations:

•

An index or subscript, or an expression (constant or variable) used as a subscript, is
valid if its value is not less than 1 and not greater than the number of elements in the
table.

•

The value of the subscript or index can be known or unknown at compile time:

•

−

If the subscript is a literal or a constant expression, then the value of the
subscript is known at compile time. Otherwise the value of the subscript or
index is unknown at compile time.

−

The value of an index is always treated as unknown at compile time.

The size of the table can be known or unknown at compile time:

−

If the OCCURS clause does not include the DEPENDING ON phrase, then the
number of elements in the table is known at compile time.

−

If the OCCURS clause includes the DEPENDING ON phrase, then the number of
elements in the table is unknown at compile time.

8600 1518–307

15–37

Compiler Options

•

Some bounds-checking is done regardless of the setting of the respective BOUNDS
option:

−

If both the number of elements in the table and the value of the subscript are
known at compile time, and the value of the subscript is greater than the number
of elements in the table, then the compiler produces a syntax error message.

−

If the value of the subscript is known at compile time, and it exceeds the
maximum number of elements specified in the OCCURS clause, then the
compiler produces a syntax error message. This validation is done without
reference to the setting of the BOUNDS option.

Other bounds-checking is done only if the appropriate BOUNDS option is set to
TRUE:

−

If the value of the subscript or index, or the number of elements in the table, or
both, are unknown at compile time, and if, when these values are computed at
execution time, the subscript or index is greater than the number of elements in
the table, then the program terminates abnormally. This validation is done only if
the BOUNDS option is set to TRUE.

When the appropriate BOUNDS option is set to TRUE for a program that has OCCURS
clauses, the compiled program will have extra code to deal with subscripting and will use
additional processor resources.
INDEX
This option controls whether the compiler checks for range violations when index names
are used to access tables.
STACK
This option controls whether the boundaries of the software stack are checked at
execution time. Refer to “MEMORY_MODEL Option” in this section for details on the
software stack.
SUBSCRIPT
The option controls whether the compiler checks for range violations when subscripts
are used to access tables.
Examples
The following examples illustrate the use of the BOUNDS option:
$SET BOUNDS

Range checking is active and provided for all suboptions that are not currently disabled.
$RESET BOUNDS

Range checking is inactive.

15–38

8600 1518–307

Compiler Options

$RESET BOUNDS(INDEX)

No range checking features are active, and the INDEX option is specifically disabled. If
the BOUNDS option is set later by itself, the INDEX option is still disabled.
$SET BOUNDS(INDEX)

The INDEX option is enabled, all other options are unaffected, and range checking is
active for all enabled options.
$SET BOUNDS(INDEX RESET SUBSCRIPT)

The INDEX option is enabled, the SUBSCRIPT option is disabled, and range checking is
provided for all enabled suboptions.
$SET BOUNDS(SET INDEX RESET SUBSCRIPT)

The INDEX option is enabled, the SUBSCRIPT option is disabled, and range checking is
provided for all enabled suboptions.
$RESET BOUNDS(SET INDEX)

No range checking is active, although the INDEX option is enabled. If BOUNDS is set
again later, then range checking is active and provided for indexes and any other options
that are enabled.

CALL MODULE Option
Type: Boolean
Default: FALSE
This option causes the object code file produced by the compilation to contain the code
necessary to enable it to be called by a CALL MODULE statement. For more information,
refer to Format 7 of the CALL Statement in Section 6.

C68MOVEWARN Option
Type: Boolean
Default: FALSE
This option issues a warning message for MOVE statements in which one of the
operands is a group item and the other operand is an elementary numeric item. The
warning messages produced by the C68MOVEWARN option are not suppressed by the
WARNSUPR option.
The C68MOVEWARN option is useful for migrating programs from COBOL(68) to
COBOL85 because it identifies the MOVE statements that are expecting the results
contrary to the requirements of the COBOL-1985 standard.

8600 1518–307

15–39

Compiler Options

CALLNESTED Option
Type: Boolean
Default: FALSE
This option governs the declaration of a nested program as either an internal or external
call. For a program with many nested programs, the number of cells allocated on the D2
stack may exceed the hardware limit of the D2 stack size. D2 stack cells are needed only
if the called program is an external call. They are not needed if the call is to an internal
nested program.
However, because the calls are usually seen before the actual declaration of the nested
program, the compiler cannot distinguish a specific call to an internal or an external
program. CALLNESTED is only applicable to CALL “literal”. CALLNESTED can be SET
and RESET throughout the program. The following table describes the effects of this
option:

Option Setting

Value

Description

RESET

FALSE

Calls of this type are assumed to be external.

SET

TRUE

Calls of this type are assumed to be internal.

CODE Option
Type: Boolean
Default: FALSE
This option controls whether the printed listing of the compiled program contains the
generated object code. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The generated object code is not included in the
printed listing of the compiled program.

SET

TRUE

The generated object code is included in the printed
listing of the compiled program.

Note: If the $OPTIMIZE option is set, the code displayed will not have any relation to
the source lines because the optimizer moves code in order to achieve optimization.

15–40

8600 1518–307

Compiler Options

COMMON Option
This option causes all data items in Working-Storage to be COMMON except those
specifically declared LOCAL or OWN. The COMMON option is ignored for host files, or if
the compilation is at level 2. (COBOL74 users using the GLOBAL option must use the
COMMON option for binding purposes.) This option has no effect on the Environment
Division or File Section.

COMPATIBILITY Option
Type: Boolean Class
Default: True (SET) for EBCDICFILES, false (RESET) for FIGCONST, false (RESET) for
UNSTRING, false (RESET) for COMMONVALUEWARN, false (RESET) for TAPEIOERROR

COMPATIBILITY
ïïïïïïïïïïïïï

Ú
³
ä EBCDICFILES
³
³ ïïïïïïïïïïï
³ ( ã FIGCONST
³ ï ³ ïïïïïïïï
³
³ UNSTRING
³
³ ïïïïïïïï
³
³ COMMONVALUEWARN
³
³ ïïïïïïïïïïïïïïï
³
æ TAPEIOERROR
À
ïïïïïïïïïïï

¿
å
³
³
³
â ...) ³
³
ï ³
³
³
³
³
³
³
³
³
ç
³
Ù

EBCDICFILES

This option specifies whether EBCDIC or hex files will be created.
In previous releases, the value of the INTMODE attribute of a file created by a COBOL85
program would vary depending on the USAGE clause of the first 01 level entry under the
FD statement.
The COBOL85 compiler now, by default, always creates files with an INTMODE value of
EBCDIC, regardless of the USAGE clause.
Resetting the suboption with
COMPATIBILITY (RESET EBCDICFILES)
will still create hex files (INTMODE=HEX) and word files (INTMODE=SINGLE) if the first
01 level entry under the FD statement is a hex item (for example, USAGE COMP) or a
word item (for example, USAGE REAL).
This option is intended to facilitate migration. It is recommended that the default setting
be used.

8600 1518–307

15–41

Compiler Options

FIGCONST

When set, the FIGCONST option affects the processing of the MOVE statement for the
figurative constants HIGH-VALUE, LOW-VALUE, and ALL "literal" to numeric data items
of usage COMP or DISPLAY. For details, see Format 1 of the MOVE Statement in
Section 7, “Compiler Operations.”
UNSTRING

When set, UNSTRING INTO ignores the implied decimal point. If you
reset this option to the default setting, the UNSTRING INTO obeys the
normal MOVE rules. For details, see Format 1 of the MOVE Statement in Section 7,
“Compiler Operations.”
This option should be used only for EVA 85 migration programs which assume the
implied decimal point is ignored.
COMMONVALUEWARN

When set, the COMMONVALUEWARN option emits a warning once for a VALUE clause
on a COMMON item in a bindable sub-program. When this option is false, every affected
item will be flagged.
This option should be set for all EVA 85 migration programs.
TAPEIOERROR

The compiler control option COMPATIBILITY(TAPEIOERROR) permits a COBOL85 code
file to perform input and output operations on tape files in a fashion similar to COBOL74.
When the option is set, COBOL85 masquerades its I-O operations as though it were
COBOL74. This permits I-O to continue in COBOL74 fashion after what would otherwise
be a permanent and disabling error. Setting the option prevents a COBOL85 program
from returning file status codes 43 through 49 for tape files.
The option can be set universally in the INITIALCCI file for your compiling environment or
it can be set in individual programs. If all tape files in a given program are to be affected
by the option, it can be set at the start of the program. If only selected tape files in a
program are to be affected, the option must be set and reset around the SELECT clause
of the file in the program ENVIRONMENT DIVISION.
The option can be manipulated as shown in the following examples:
$ SET COMPATIBILITY(TAPEIOERROR)
This option sets the IOERROR suboption, while enabling any other suboptions that
were already set.
$ SET COMPATIBILITY(SET TAPEIOERROR)
This option, like the preceding option, sets the IOERROR suboption, while enabling
any other suboptions that were already set.

15–42

8600 1518–307

Compiler Options

$ SET COMPATIBILITY(RESET TAPEIOERROR)
This option resets the IOERROR suboption, while enabling any other suboptions that
were already set.
$ RESET COMPATIBILITY(TAPEIOERROR)
This option resets the IOERROR suboption, while disabling all other suboptions that
were already set.
$ RESET COMPATIBILITY
This option disables any suboptions that were already set.
$ SET COMPATIBILITY
This option enables any suboptions that were already set.

8600 1518–307

15–43

Compiler Options

Copy Boundary Options

COPYBEGIN
ïïïïïïïïï

ä 'name-string' å
ã
â
æ "name-string" ç

COPYEND
ïïïïïïï

ä 'name-string' å
ã
â
æ "name-string" ç

Type: String
The COPYBEGIN and COPYEND options delimit a symbolic subfile. The name-string
associates a symbolic name with that subfile. A symbolic subfile consists of all records
situated between a COPYBEGIN CCR and a COPYEND CCR with matching symbolic
names (name-strings). Source code file records delimited by COPYBEGIN and COPYEND
CCRs can be included by other programs with the name-string range option of the
INCLUDE compiler option. Symbolic subfiles can be nested within one another, and they
can overlap one another. The symbolic names are matched without regard to case.
The maximum length of a name-string is 30 characters.
The following example illustrates the use of the INCLUDE compiler option in conjunction
with the COPYBEGIN and COPYEND options.
A source code file contains the following INCLUDE option:
$ INCLUDE LOCALDEFINES = '(GAS)LOCAL/DEFINES ON RDLS' ('LOCAL_FAIL_DEFINE')
The file (GAS)LOCAL/DEFINES ON RDLS contains the following COPYBEGIN and
COPYEND options:
WORKING-STORAGE SECTION.
$ COPYBEGIN 'LOCAL_FAIL_DEFINE'
01 LOCAL-FAIL-DEFINE.
03 REC-TYPE.
05 MAJOR-TYPE
05 MINOR-TYPE
03 CAUSE-CODE
03 SYS-JULIAN-DATE.
05 DAY
05 YEAR
03 SYS-TIME
03 LOCAL-TEXT
$ COPYEND 'LOCAL_FAIL_DEFINE'

PIC 99.
PIC 99.
PIC 9(4).
PIC
PIC
PIC
PIC

999.
99.
X(6).
X(50).

When the INCLUDE option is encountered in the first file, all records situated
between the $ COPYBEGIN 'LOCAL_FAIL_DEFINE' CCR and the
$ COPYEND 'LOCAL_FAIL_DEFINE' CCR in the second file are included in the first file.

15–44

8600 1518–307

Compiler Options

CONCURRENTEXECUTION Option
This option is for internal use in the system software only.

CORRECTOK Option
Type: Boolean
Default: FALSE
This option controls whether the compiler corrects certain minor syntax errors. The
following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not perform any automatic
syntax correction.

SET

TRUE

The compiler corrects certain minor syntax errors
and issues warning messages instead of error
messages.

CORRECTSUPR Option
Type: Boolean
Default: FALSE
This option controls whether the compiler issues warning messages pertaining to minor
syntax errors it has encountered and corrected. The compiler can be directed to correct
certain minor syntax errors with the CORRECTOK option. The following table describes
the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler produces warning messages that
pertain to automatically corrected syntax errors.

SET

TRUE

The compiler suppresses the warning messages
that pertain to automatically corrected syntax
errors.

8600 1518–307

15–45

Compiler Options

CURRENCYSIGN Option
Type: String
ä å ä 'currency sign character' å
CURRENCYSIGN ã=â ã
â
ïïïïïïïïïïïï æ ç æ "currency sign character" ç

This option alters the default currency sign in the program for floating insertion editing
without requiring the explicit specification of the CURRENCY SIGN clause.
This option must be included in the source code before the Data Division of the program
to be in effect.
The currency sign character must be nonnumeric and is limited to a single character. For
more information, refer to the CURRENCY SIGN Clause of the SPECIAL-NAME
Paragraph in Section 3.
If both the CURRENCY SIGN clause and the CURRENCYSIGN compiler control option are
specified, the currency sign specified with the CURRENCY SIGN clause is used in the
program.

15–46

8600 1518–307

Compiler Options

DELETE Option
Type: Boolean
Default: FALSE
The DELETE option controls whether the compiler incorporates source language records
from the secondary input file (SOURCE) into the compiled program when the MERGE
option is TRUE.
If the MERGE option is FALSE, the DELETE option is ignored.
The following table describes the effects of this option:

Option

Value

Description

RESET

FALSE

Source language records from the secondary input file
are incorporated into the compiled program when the
MERGE option is TRUE.

SET

TRUE

Source language records from the secondary input file
are discarded when the MERGE option is TRUE.
The discarded source language records are not included
in the output symbolic file (NEWSOURCE) if the NEW
option is TRUE.

The DELETE option can appear only on a CCR in the primary source language file (CARD).
The DELETE option and the VOIDT option are synonymous.

ELSE and ELSE IF Options
Type: Immediate
The ELSE and ELSE IF options are conditional compilation options. For information on
conditional compilation options, refer to “Conditional Compilation Options” and
“Controlling Compiler Input” earlier in this section.

8600 1518–307

15–47

Compiler Options

EMBEDDEDKANJI Option
Type: Boolean
Default: FALSE
This option controls the processing of an EBCDIC literal in which a double octet literal is
embedded.
The EMBEDDEDKANJI option causes the compiler to ignore the quote (hex '7F')
character in an EBCDIC literal and treat it as part of the double octet character code
whenever it is surrounded by SDO (hex '2B') and EDO (hex '2C') delimiters.
The EMBEDDEDKANJI option is useful only for the users of double octet character sets
that contain hex '7F' as part of the character code. Use of this option should be limited to
such users due to the impact of the option on EBCDIC literal scanning.

END Option
Type: Immediate
The END option is a conditional compilation option. For information on conditional
compilation options, refer to “Conditional Compilation Options” and “Controlling
Compiler Input” earlier in this section.

15–48

8600 1518–307

Compiler Options

ERRORLIMIT Option
ä
ã
æ

ERRORLIMIT
ïïïïïïïïïï
LIMIT
ïïïïï

å
â
ç

limitvalue

Type: Value
Default: 10 for compilations originating from CANDE; otherwise, 150
This option determines the maximum number of errors that the compiler can detect
before compilation is terminated.
When the error limit is exceeded, the compiler creates a listing of the errors and informs
you that compilation was terminated because of an excess number of errors.
If the NEW option is TRUE and the error limit is exceeded, the new symbolic file
(NEWSOURCE) is purged.

ERRORLIST Option

ä
ã
æ

ERRORLIST
ïïïïïïïïï
ERRLIST
ïïïïïïï

å
â
ç

Ú
³
³
³
³
³
À

ä
³
ã
³
æ

ä 'file-title' å
ã
â
æ "file-title" ç
Boolean-expression

å
³
â
³
ç

¿
³
³
³
³
³
Ù

Type: Boolean Title
Default: TRUE for CANDE-originated compilations; otherwise, FALSE
This option controls whether the compiler creates an error message listing file. The
following table describes the effects of this option:

Setting

Value

Description

RESET

FALSE

The compiler does not create an error message listing file.

SET

TRUE

The compiler creates an error message listing file.

•
•

8600 1518–307

If no file title is specified, the error file is named ERRORFILE.
If you compile with CANDE, the error file is automatically file
equated to the remote device from which the compiler was
initiated.

15–49

Compiler Options

Syntax
file title

Specifies an alternate file title for the error file. You can qualify the file-title with a
usercode and/or location, so long as a foreign host is not specified.
Boolean-expression

Creates the file title according to an expression that can be evaluated as a Boolean value
according to the standard rules of Boolean algebra
For details about the syntax of a Boolean-expression, refer to “Syntax for Compiler
Control Options” in this section.
Error Message Listing
When a syntax error is detected in the source input, two lines of text are inserted in the
ERRORFILE. These two lines show

•

The source record that contained the error

•

An error message

•

A pointer to the item in the record where the error occurred

If a syntax error occurs before the ERRORLIST compiler option in the source file, the
error message listing does not include information pertaining to that error.
Example
000100$$SET ERRLIST="(CHARLIE)ERR/BIT ON QUAL"
This statement creates an error file under the CHARLIE usercode if any syntax error
occurred during compilation. If the location or file title is invalid, a default file title is used.

15–50

8600 1518–307

Compiler Options

FARHEAP Option

FARHEAP
ïïïïïïï

Ú
³
ä
³
³
³
³
³
³
³
³
³
³
³
ä SET
å ³
³ ( ã ïïï
â ã
³ ï æ RESET ç ³
³
³
³
³
³
³
³
³
³
³
³
æ
À

ä
³
= ã
³
æ

FIRSTFIT å
³
ALLOCMEMORY
BESTFIT â
ïïïïïïïïïïï
ïïïïïïï ³
FASTFIT ç
ïïïïïïï
ä TRUE å
INSTALLMEMORY = ã ïïïï â
ïïïïïïïïïïïï
æ FALSE ç
RESIZEMEMORY
ïïïïïïïïïïïï

ä TRUE å
= ã ïïïï â
æ FALSE ç

STACKSIZE = size
ïïïïïïïïï

å
³
³
³
³
³
³
â
³
³
³
³
³
³
ç

... )
ï

¿
³
³
³
³
³
³
³
³
³
³
³
³
³
³
³

Type: Boolean Class
Default: FALSE
The FARHEAP option enables a program or library to select the far heap memory
management mechanism instead of the default heap memory management mechanism.
The FARHEAP option must appear before any program text.
You must set the FARHEAP option when a separately compiled COBOL85 module is
bound into a C language program that uses the far heap management mechanism.
The FARHEAP option is not currently used by the COBOL85 compiler. This syntax is
provided for use when binding a COBOL85 program with a C language program. Refer to
the C Programming Reference Manual for more information.

8600 1518–307

15–51

Compiler Options

FEDLEVEL Option

FEDLEVEL
ïïïïïïïï

ä
³
³
³
ã
³
³
³
æ

1
ï
2
ï
3
ï
4
5
ï

å
³
³
³
â
³
³
³
ç

Type: Value
Default: 4
The FEDLEVEL option causes the compiler to produce nonfatal warnings for constructs
not available at the level at which the program was compiled. For example, if FEDLEVEL
is set to 2, all constructs allowed only for level 3 and higher produce warnings.
The FEDLEVEL option measures compliance with the U.S. Government COBOL
standards as specified in the Federal Information Processing Standards (FIPS) Publication
21-2 for COBOL dated March 18, 1986.
FEDLEVEL provides the following levels of compliance:

Value

Description

Minimum level

Intermediate level

High level

Extensions to ANSI standard

If the FEDLEVEL option is set to 5, the program-name specified in the PROGRAM-ID
clause is used as the entry-point-name for the program; otherwise, the entry-point-name
is PROCEDUREDIVISION. The option FEDLEVEL = 5 should not be used in programs
that are explicitly declared to be libraries. This option is retained to ease the migration
from ANSI COBOL74 to ANSI COBOL85, for programs using the interprogram
communication (IPC) facility to call a library program.
All warnings appear under the source program line with an indication of the beginning
location of the nonconforming language element. However, if the ANSI compiler control
option is set, the warning points only to the start of the source line.
FEDLEVEL warning messages are not printed if the WARNSUPR option is TRUE.

15–52

8600 1518–307

Compiler Options

FOOTING Option

FOOTING
ïïïïïïï

ä
ã
æ

=
+=

å
â
ç

ä 'footing text'
ã
æ "footing text"

å
â
ç

Type: String
This option specifies a string of characters to be placed in the footer of each output
listing page. Only the final value declared in the program as the footing appears on the
output listing. If the LIST option is FALSE, the FOOTING option is ignored.
FOOTING =

Assigns a character string to the footer of each output listing page.
FOOTING +=

Appends a character string to a previously defined footing string.
'footing text'
"footing text"

Either apostrophes (' ') or quotation marks (" ") may enclose the footing text.

8600 1518–307

15–53

Compiler Options

FREE Option
Type: Boolean
Default: TRUE for CANDE-originated compilations; otherwise, FALSE
This option controls whether COBOL margin restrictions are enforced during the
compilation. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

COBOL margin restrictions are enforced by the
compiler.

SET

TRUE

Most COBOL margin restrictions are ignored by the
compiler outside of the Identification Division.
Violations of COBOL margin restrictions are not
considered syntax errors.

Note: When the FREE option is on, the margin restrictions in the Data Division,
Environment Division, and Procedure Division are not enforced. But the Identification
Division still has its margin restriction. This restriction is released as soon as one of the
other three divisions are encountered.
Any division that follows the Identification Division should still follow margin restrictions.
For example:
$ SET FREE
IDENTIFICATION DIVISION.
PROGRAM-ID
.
.
.
* The following division is free from margin restrictions
DATA DIVISION.
.
.
.
* The following division is free from margin restrictions
PROCEDURE DIVISION.
.
.
.

15–54

8600 1518–307

Compiler Options

FS4XCONTINUE Option
Type: Boolean
Default: False
This option controls whether a program is terminated or is allowed to continue after a file
status value of 41, 42, 43, 44, 46, 47, 48, or 49 is returned. The following table describes
the effects of this option:
Option Setting

Value

Description

RESET

FALSE

When a file status value in the 4x range is returned, the
program executes any applicable use routines, and the
task is terminated with an I-DS.

SET

TRUE

When a file status value in the 4x range is returned, the
program executes any applicable use routines and
continues executing.

Even with the FS4XCONTINUE option set, one of the following conditions must be met
for a program to continue executing after a failed I/O request:

•

The FILE STATUS clause is declared (Environment Division).

•

A USE routine is specified.

•

An alternate statement to perform in case of an unsuccessful I/O is declared in the
syntax of the I/O statement (refer to each I/O statement for details).

For the meanings of the file status codes, refer to “I-O Status Codes” in Section 3.

INCLNEW Option
Type: Boolean
Default: FALSE
This option controls whether source language records included during the compilation
through use of the INCLUDE option are written to the updated symbolic file
(NEWSOURCE). If the NEW option is FALSE, the INCLNEW option is ignored. The
following table describes the effects of the INCLNEW option when the NEW option is
TRUE:
Option Setting

Value

Description

RESET

FALSE

If the NEW option is TRUE, the updated symbolic file
(NEWSOURCE) does not contain any source language
records included through use of the INCLUDE option.

SET

TRUE

If the NEW option is TRUE, included source language
records are written to the updated symbolic file
(NEWSOURCE).

8600 1518–307

15–55

Compiler Options

INCLUDE Option

INCLUDE
ïïïïïïï

ä
ã
æ

internal file name [ [=] "file title" ]
"file title"

Ú
³
³
³
³
³
³
³
À

sequence number

Ú
³
³
³
³
À

( "symbolic name" )

Ú
³ ³
³ TO
À

å
â
ç

Ú
³
³
³
³
³
³
À

¿
³
³ sequence number
³
Ù

DISK
EDITOR_DISK
EDITOR
DISKPACK
PACK
EDITOR_PACK
¿
³
³
³
³
Ù

¿
³
³
³
³
³
³
Ù

¿
³
³
³
³
³
³
³
Ù

Type: Special
This option instructs the compiler to temporarily accept input from a specified alternate
source. The compiler uses the alternate source as input until the alternate source is
exhausted or a specified range within the alternate source is exceeded.
file title
The alternate source for compiler input can be specified by a file title, an internal filename, or a combination of an internal file-name and a file title. If the INCLUDE compiler
option specifies a file title, then the compiler examines the partial file-names specified by
the SEARCH compiler option (if available) to construct the file title or file titles used for
the included file.
If an internal file-name is specified, the compiler assigns the internal file name to the
INTNAME file attribute of the file. Use of internal file names for included files permits file
equation of files at compilation time. If both an internal file name and a file title are
specified, then any compilation time file equation overrides the file equation of the
INCLUDE compiler option.
If only an internal file name is specified, and file equation is not used, the compiler uses
specifications supplied by the SEARCH compiler option to construct the file title or file
titles used for the included file.
Device name
The device names (DISK, EDITOR_DISK, EDITOR, PACK, DISKPACK, EDITOR_PACK )
are included only to facilitate the migration of code from V Series to ClearPath and
A Series platforms. Including these names has no effect on the compiler.

15–56

8600 1518–307

Compiler Options

File range
The specification of a range within the included file can be a single sequence number or a
sequence number range. Also, it can be a symbolic name that identifies a symbolic
subfile. The symbolic name can contain a maximum of 30 characters. A symbolic subfile
consists of all records situated between a COPYBEGIN compiler option and a COPYEND
compiler option with matching symbolic names.
Additional details
The following special characters have meaning when they occur at the beginning of the
file title specification of an INCLUDE option:

•

/ (slash)

•

> (greater than symbol)

A slash character (/) instructs the compiler to use only the file title specification when
searching for the included file. The partial file names specified in the SEARCH option (if
applicable) are not applied to the file title specification. For example, if the file title was
specified as INCLUDE DEFINES ="/LOCAL/DEFINE", the compiler would search for the
included file using the following file title:
()LOCAL/DEFINES ON
A greater-than symbol (>) instructs the compiler to skip one partial file name in the partial
file name list specified by the SEARCH option. More than one greater than symbol may
be concatenated to skip more than one partial file title. Two greater-than symbols (>>)
would cause the compiler to skip two partial file names in the partial file name list, and
begin forming file title combinations with the third entry. For example, a program might
contain the following CCRs:
$ SET SEARCH ="SYSTEM/= ON LOCALPACK; (USER)SOURCE/="
$ SET SEARCH+= ";*SYSTEM/= ON EXTERNALS"
.
.
.
$ INCLUDE DEFINES = ">LOCAL/DEFINES"
Based on these specifications, the compiler would search for the included file using the
following file title combinations.
(USER)SOURCE/LOCAL/DEFINES
*SYSTEM/LOCAL/DEFINES ON EXTERNALS
For more information about the COPYBEGIN and COPYEND compiler options, refer to
“Copy Boundary Options” earlier in this section.

8600 1518–307

15–57

Compiler Options

INLINEPERFORM Option
This option causes the next PERFORM statement and all nested PERFORM statements
to be replaced, if possible, by in-line code when the OPTIMIZE option is set. A warning
message is displayed if it is not possible for the PERFORM statement to be in-lined.
If you set the INLINEPERFORM option, a PERFORM statement might not be in-lined for
the following reasons:

15–58

•

The INLINEPERFORM option performs a PERFORM statement (nested PERFORM)
that cannot be in-lined.

•

The INLINEPERFORM option executes a GO TO statement that may not end up at
the PERFORM statement return point (the end of the last performed paragraph).

•

Another PERFORM statement overlaps with an earlier PERFORM statement but has
a different PERFORM statement return point.

•

The amount of code that needs to be duplicated to replace the PERFORM statement
is deemed excessive (approximately 400 statements).

8600 1518–307

Compiler Options

IPCMEMORY Option
$IPCMEMORY = integer-value

Type: Value
Default: 5000
This option controls the amount of memory you can declare to support the array used to
process nested program calls at run time. Statistics printed on the output listing
summary show the total memory value required for the array.
The specified size value should be reasonably close to the value of the memory required
as reported in the summary statistics. If the IPCMEMORY size is not declared large
enough to handle all the nested programs contained within the main program, then a
compiler message is emitted. If the size value is specified to be larger than the known
required array size to support 254 nested programs (74213 bytes), then the size is
minimized by the compiler.
Example
The following example shows an output listing summary:
$SET LIST IPCMEMORY=74214
0001000

IDENTIFICATION DIVISION.

000200
000300

PROGRAM-ID. NEST-255.
ENVIRONMENT DIVISION.

---------------------------------------------------------------------------NESTED PROGRAM STATISTICS FOR
NEST-255
-------------------------------------------MEMORY ALLOCATED FOR PROGRAM (X)
MEMORY ALLOCATED FOR PROGRAM-IDS (Y)
MEMORY ALLOCATED FOR COMMON PROGRAMS (Z)
TOTAL MEMORY REQUIRED (X+Y+Z)

1537
7629
64772
73938

ACTUAL IPCMEMORY REQUESTED

74213 BYTES

006100

8600 1518–307

99%
99%
99%
99%

of
of
of
of

1538
7650
65025
74213

BYTES
BYTES
BYTES
BYTES

*END PROGRAM NEST-255.

15–59

Compiler Options

LEVEL Option
LEVEL = lexicographical-level
ïïïïï
Type: Value
Default: 2
This option specifies the lexicographical level at which the program is compiled.
Programs compiled at the default lexicographical level of 2 can only serve as the host file
during a binding operation.
The lexicographical level must be an integer greater than 1 and less than or equal to 14.
The level option must appear prior to the Identification Division.

LIBRARY Option
{
{
{

LIBRARY

}
}
}

[
[
[

{ 'file-title'
{
{ "file-title"

} ]
} ]
} ]

The file-title specifies an alternative file title for the code file. You can qualify the file-title
with a usercode and/or location as long as a foreign host is not specified.
When the BINDSTREAM option is set, a file-title must be specified. Multiple LIBRARY
options are allowed in a stacked program. Refer to “BINDSTREAM Option” for more
information.
Type: Boolean Title
Default: FALSE
This option, when set, directs the compiler to generate a multi-procedure code file for
binding. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

A separate executable object code file that does not
contain binding information is generated for each
program unit found in the source file.

SET

TRUE

A single non-executable object code file that
contains binding information for each program unit
found in the source file is generated.

LIBRARY must be included in the source code before the Identification Division of the
program. The resultant object code file can be bound to a host file through the use of the
Binder utility.

15–60

8600 1518–307

Compiler Options

LIBRARYLOCK Option
Type: Boolean
Default: FALSE
When TRUE, the LIBRARYLOCK option provides the locking needed to maintain private
library data integrity.
Note: This option has no effect unless used with the LIBRARYPROG compiler control
option.
For information on specifying the way a program is shared when it is called as a library,
refer to the “SHARING” option.

LIBRARYPROG Option
Type: Boolean
Default: FALSE
This option is used to compile COBOL74-type libraries with COBOL85 code. The
following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The resulting object code file must be executed
as a stand-alone program, and cannot be
executed by a library call from another program.

SET

TRUE

The resulting object code file cannot be executed
as a stand-alone program, but can be executed
only when called by another program.

LIBRARYPROG must be included in the source code before the Identification Division of
the program. LIBRARYPROG must be set to TRUE in a program that is called by another
program. However, LIBRARYPROG should not be used if that program is declared
explicitly to be a library.
After it is set to TRUE, the option remains TRUE throughout compilation. If the source
language input consists of separately compiled programs, be careful to ensure that this
option is set appropriately for each program unit.
Note: Using this option to compile COBOL85-type libraries results in a syntax error.

8600 1518–307

15–61

Compiler Options

LINEINFO Option
Type: Boolean
Default: TRUE for CANDE-originated compilations; otherwise, FALSE
This option controls whether source language sequence numbers are included in the
object code file. Setting this option gives you the convenience of investigating lines of
code by sequence number rather than by code address if your program terminates
abnormally. Note that you must set or reset the LINEINFO option before program text.
If the LINEINFO option is set and the program terminates abnormally, the compiler
displays the source language sequence number associated with the point of program
termination. Sequence number 0 (zero) refers to special code generated by the compiler.
The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not include source language
sequence numbers in the object code file.

SET

TRUE

The compiler includes source language sequence
numbers in the object code file.

LIST Option
LIST
ïïïï

[

Boolean-expression

]

Type: Boolean
Default: FALSE for CANDE-originated compilations; otherwise, TRUE
This option controls whether the compiler creates a compilation listing of the program.
The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not produce a compilation listing
of the program.

SET

TRUE

The compiler produces a compilation listing of the
program in a file named LINE. The minimum content
of this listing includes the source language, a
compilation summary, and any error messages.

Boolean-expression

15–62

8600 1518–307

Compiler Options

LISTDOLLAR Option
LISTDOLLAR
ïïïïïïïïïï

[ = Boolean expression ]

Type: Boolean
Default: FALSE
This option controls whether temporary CCRs are included in the compilation listing of
the program (the file named LINE). Temporary CCRs use a $ (currency sign) in column 7,
and no $ (currency sign) in column 8. The following table shows the effects of this
option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not include temporary CCRs in
the compilation listing of the program.

SET

TRUE

If LIST is TRUE, the compiler includes all temporary
CCRs in the compilation listing of the program.

If you use the currency sign to specify this compiler option, place it in columns 9 through
72. The synonym LIST$ is no longer valid, and if specified causes erroneous results.

8600 1518–307

15–63

Compiler Options

LISTINCL Option
ä
ã
æ

LISTINCL
ïïïïïïïï
INCLLIST
ïïïïïïïï

å
â
ç

[ = Boolean-expression ]

Type: Boolean
Default: FALSE
This option controls whether the compiler places source language records included with
the INCLUDE option in the compilation listing of the program (the file named LINE). The
following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The included records are not contained in the
compilation listing.

SET

TRUE

If the LISTINCL option is TRUE, then the
compilation listing contains source language
records included through use of the INCLUDE
option.

If the LIST option is FALSE, then the LISTINCL option is ignored.

LISTINITIALCCI Option
Type: Boolean
Default: FALSE
This option controls whether the compilation listing includes the contents of the
INITIALCCI file used for the compilation (the file named LINE). The following table
describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The contents of the INITIALCCI file are not included
in the compilation listing.

SET

TRUE

If the LIST option is TRUE, then the compilation
listing includes the contents of the INITIALCCI file.

If the LIST option is FALSE, then the LISTINITIALCCI option is ignored.

15–64

8600 1518–307

Compiler Options

LISTIPCMEMORY Option
Type: Boolean
Default: TRUE
The nested program statistics for each nested program are included in the compilation
listing by default.
To suppress the nested program statistics from the list output, RESET the
LISTIPCMEMORY option.
Include the LISTIPCMEMORY option in the source code only once, before the
Identification Division of the first nested program. This action will SET/RESET the printing
of the nested program statistics for all the nested programs in the source code.
For more information, refer to the IPCMEMORY option earlier in this section.

LISTOMITTED Option
ä LISTOMITTED
ã ïïïïïïïïïïï
æ LISTO
ïïïïï

å
â
ç

Type: Boolean
Default: FALSE
This option controls whether the compiler includes in the compilation listing any source
language input that was omitted because of the OMIT option. More information on the
OMIT option is included later in this subsection. The following table describes the effects
of this option:

Option Setting

Value

Description

RESET

FALSE

The compilation listing does not include source
language records omitted through use of the
OMIT option.

SET

TRUE

The compilation listing includes source language
records omitted through use of the OMIT option.

8600 1518–307

15–65

Compiler Options

LISTP Option
Type: Boolean
Default: FALSE
This option controls whether the compiler lists source language records that originate
from the primary input file. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not generate a listing of source
language records that originated from the primary
input file.

SET

TRUE

The compiler generates a listing of source language
records that originated from the primary input file.

If the LIST option is TRUE, the LISTP option has no effect.

LIST1 Option
Type: Boolean
Default: FALSE
This option controls whether the compiler produces a listing during the first pass. The
following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not generate a listing during the
first pass through the source input records.

SET

TRUE

The compiler generates a listing during the first
pass through the source input records.

If the LIST option is TRUE, the LISTP option has no effect.

15–66

8600 1518–307

Compiler Options

LI_SUFFIX Option

LI_SUFFIX
ïïïïïïïïï

ä = å
ã
â
æ += ç

ä 'lininfo suffix' å
ã
â
æ "lineinfo suffix" ç

Type: String
This option specifies a string to be associated with the sequence numbers of the
program. The syntax LI_SUFFIX = "lineinfo suffix" or LI_SUFFIX = 'lineinfo suffix'
assigns a string of characters to the lineinfo string. The syntax LI_SUFFIX += "lineinfo
suffix" or LI_SUFFIX += 'lineinfo suffix' appends a string of characters to a previously
defined lineinfo string. This option is meaningful only when the LINEINFO compiler
option is set to TRUE.
If a program failure occurs and the LINEINFO compiler option was set when the program
was compiled, a series of sequence numbers are displayed identifying the sequence
number at which the program or programs failed. If the LI_SUFFIX compiler option was
used, the string associated with the program is displayed following the sequence
number. This permits easy identification of the program or library associated with the
displayed sequence number.
For best results, the LI_SUFFIX option should be set within a program before any nested
programs are specified. For nested programs, this means after IDENTIFICATION
DIVISION and before END PROGRAM.

8600 1518–307

15–67

Compiler Options

LOCALTEMP Option
Type: Boolean
Default: True
The LOCALTEMP option specifies where temporary arrays are to be created by the
compiler.
Allocating temporary arrays locally within a program is ideal for optimizing subprogram
memory usage and reducing the use of lexicographic level 2 stack cells. There is,
however, a performance penalty when local temporary arrays are used.
Each time a program containing a local array is entered and the array is first used, the
system performs a p-bit interrupt to allocate space in memory for the local array and
assign it to the program. The time required to enter and exit a program containing a local
array is roughly twenty times longer than the time required to enter and exit the same
program without the local array. Thus, local temporary arrays should be avoided in
subprograms that are expected to be entered very frequently.
The LOCALTEMP option defaults to TRUE, causing temporary arrays to be allocated
locally in the program. Resetting this option to FALSE causes the temporary arrays to be
allocated globally at lexicographic level 2.
This option must be included in the source code before the Identification Division of the
program.

LOCALTEMPWARN Option
Type: Boolean
Default: False
The LOCALTEMPWARN option enables the compiler to emit the following warning
against a statement when the statement causes the compiler to generate a local array
temporary.
A LOCAL ARRAY TEMPORARY HAS BEEN GENERATED FOR THIS STATEMENT, WHICH MAY
CAUSE AN INITIAL PBIT TO OCCUR. TO AVOID A PERFORMANCE PROBLEM CAUSED BY THE
PBIT, RESET THE LOCALTEMP CCI OR MODIFY THE STATEMENT.

15–68

8600 1518–307

Compiler Options

LONGLIMIT Option
LONGLIMIT
ïïïïïïïïï

limitvalue

Type: Value
Default: 10922 (Equivalent to 64KB)
This option specifies the maximum permissible size in words of an unpaged array.
Unpaged arrays (sometimes called LONG arrays) provide greater efficiency in accessing
elements at the expense of increased actual memory usage at any given instant. Arrays
that are less than or equal to the LONGLIMIT are not paged, while all other arrays are
paged.
The limitvalue must be in the range from 171 words through 10922 words. In addition, an
individual site may have a system-wide LONG array limit that is less than the LONGLIMIT
setting. Setting the LONGLIMIT greater than the site limit causes the object program to
abnormally terminate at run-time.

MAPONELINE Option
Type: Boolean
Default: FALSE
This option controls whether the MAP information should be on one line in the output
listing. The MAP option must be set together with the MAPONELINE option.
If the default (FALSE) is used, the MAP option is not affected.

8600 1518–307

15–69

Compiler Options

MAP or STACK Option
Type: Boolean
Default: FALSE
This option controls whether the compiler includes information on variable allocation in
the output listing. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The output listing generated by the compiler does
not contain any information concerning the
allocation of variables.

SET

TRUE

The output listing generated by the compiler
contains information concerning the allocation of
variables in the object program.

MAP and STACK are synonymous.

MEMORY_MODEL Option

MEMORY_MODEL
ïïïïïïïïïïïï

ä
³
³
ã
³
³
æ

TINY
ïïïï
SMALL
ïïïïï
LARGE
ïïïïï
HUGE
ïïïï

å
³
³
â
³
³
ç

Type: Enumerated
Default: TINY
The MEMORY_MODEL option is not currently used by the COBOL85 compiler. This
syntax is provided for use when binding a COBOL85 program with a C language
program. Refer to the C Programming Reference Manual for more information.

15–70

8600 1518–307

Compiler Options

MERGE Option
Type: Boolean Title
Default: FALSE
This option controls whether the compiler merges the source language records of the
primary input file (CARD) with source language records from a secondary input file
(SOURCE). This option must be included in the source code before the Identification
Division of the program. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not merge primary source records
(CARD) with secondary source records (SOURCE).
The compiler ignores the secondary input file
(SOURCE).

SET

TRUE

The compiler merges primary source records (CARD)
with secondary source records (SOURCE). After
MERGE is set to TRUE, it remains TRUE throughout
compilation; any attempt to change it is treated as an
error and ignored.

Syntax

MERGE
ïïïïï

Ú
³
³
³
³
³
³
³
À

[ = ]

ä
³
³
ã
³
³
æ

ä
ã
æ

'file title'
"file title"

å
â
ç

Boolean-expression

å
³
³
â
³
³
ç

¿
³
³
³
³
³
³
³
Ù

file title

Specifies an alternate file title for the secondary input file, SOURCE. The file title must be
a string. The device name can be DISK or TAPE.
If a file title is not specified, the name “SOURCE” is assumed. File equate statements
can override the default values.
Boolean-expression

8600 1518–307

15–71

Compiler Options

MODULEFAMILY Option

MODULEFAMILY

ä 'family-name' å
= ã
â
æ "family-name" ç

Type: String
This option specifies a default family-name to be used with the CALL MODULE
statement.

MODULEFILE Option

MODULEFILE =

ä 'file-name' å
ã
â
æ "file-name" ç

Type: String
This option specifies the file name to be used when the MODULEFILE option is used in
the CALL MODULE statement.

15–72

8600 1518–307

Compiler Options

MUSTLOCK Option

MUSTLOCK
ïïïïïïïï

Ú
³
³
³
À

ä TRUE å
ã ïïïï â
æ FALSE ç
ïïïïï

¿
³
³
³
Ù

Type: Boolean
Default: TRUE
This option enables you to specify whether the compiler is to generate code to ensure
that a record has been locked by the current user before attempting to write to the
record. Set this option to TRUE to enhance file integrity when multiple programs access
a file concurrently.
When the MUSTLOCK option is set to TRUE, and the phrase “VALUE OF
BUFFERSHARING IS SHARED” is declared in the File Description (FD) Entry for the file,
code is emitted before a write operation to verify that the user has locked the record that
is to be written. If the record is not locked,

•

The write operation does not occur.

•

A file status value is established.

•

Control passes to the statement specified in the INVALID KEY clause.

Related Information
The following table provides references for additional information related to this
statement:

For Information About . . .

Refer To . . .

Locking a record

“LOCKRECORD Statement” in Section 7.

Unlocking a record

“UNLOCKRECORD Statement” in Section
8.

Performing write operations on shared
files

“WRITE Statement” in Section 8.

8600 1518–307

15–73

Compiler Options

NEW Option

NEW
ïïï

Ú
³
³
³
³
³
À

[ = ]

ä
³
ã
³
æ

ä 'file title' å
ã
â
æ "file title" ç
Boolean-expression

å
³
â
³
ç

¿
³
³
³
³
³
Ù

Type: Boolean Title
Default: FALSE
This option controls whether the compiler creates a new source language symbolic file
(NEWSOURCE). This option must be included in the source code before the Identification
Division of the program. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not create a new source language
symbolic file.

SET

TRUE

The compiler creates a new source language
symbolic file (NEWSOURCE). The new symbolic file
contains all source language records used during
compilation. After NEW is set to TRUE, it remains
TRUE throughout compilation. Any attempt to change
this option is treated as an error and ignored.

Syntax
file title

Specifies an alternate file name for the new source language symbolic file. The file title
must be a string. If no file title is specified, the name NEWSOURCE is assumed. A file
equate statement can override this default value.
Boolean-expression

Creates the file title according to an expression that can be evaluated as a Boolean value
according to the standard rules of Boolean algebra.
For details about the syntax of Boolean-expression, refer to “Syntax for Compiler Control
Options” in this section.
Source language records discarded by the DELETE or VOID options are not included in
the NEWSOURCE file. Input records omitted by the OMIT option and permanent CCRs
(with a $ in columns 7 and 8) are included.

15–74

8600 1518–307

Compiler Options

NEWID Option
NEWID [ = ] new-id string
ïïïïï
Type: String
This option specifies a string of characters to be placed by the compiler in the rightmost
eight character positions of each source language record.
The columns 73-80 in the NEWSOURCE and the listing are replaced by this NEWID.

NEWSEQERR Option
Type: Boolean
Default: FALSE
This option controls whether sequence errors in the new source language symbolic file
(NEWSOURCE) cause the compiler not to lock the NEWSOURCE file upon compilation
completion. A sequence error occurs when the sequence number of a record of the
NEWSOURCE file is not greater than the sequence number of the preceding record.
If the NEW option is FALSE, then the NEWSEQERR option is ignored.
The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler locks the new source language
symbolic file regardless of whether sequence errors
were encountered while writing the file.

SET

TRUE

The compiler does not lock the new source language
symbolic file (NEWSOURCE). A message is displayed
on the Operator Display Terminal (ODT) and is printed
on the printer listing.

8600 1518–307

15–75

Compiler Options

OMIT Option
Type: Boolean
Default: FALSE
This option controls whether the compiler ignores all source language records, except for
other compiler control records. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler uses all source language records in
compilation.

SET

TRUE

The compiler ignores all source language records
from the primary source file (CARD) and, if the
MERGE option is TRUE, from the secondary source
file (SOURCE). Ignored records are not used in
compilation.

The OMIT option can appear on a CCR in either the primary (CARD) or the
secondary(SOURCE) source language input. While the OMIT option is TRUE, CCRs
encountered in the source language input are processed in the normal fashion.
If the NEW option is TRUE, the omitted records are carried forward to the output
symbolic file (NEWSOURCE). If the LISTOMITTED option is TRUE, the records are
included in the compilation listing (LINE). Otherwise, the records are not included.

15–76

8600 1518–307

Compiler Options

OPT1 Option
Type: Boolean
Default: FALSE
This option specifies whether a numeric data item in the Working-Storage Section is
treated internally as a binary item for the performance gain purpose. The following use of
the OPT1 option sets the internal run-time performance tuning usage of the compiler:
$SET
01

OPT1
ARITH-DATA.
03 OP-1
03 OP-2
$RESET OPT1

PIC 9(11).
PIC 9(20).

The OPT1 option must not appear before the Identification Division in the source
program. The OPT1 option affects only integer items of DISPLAY, COMPUTATIONAL, or
PACKED-DECIMAL usage that are declared in the Working-Storage Section.
The total number of data items that are optimized with the OPT1 option cannot exceed
256; otherwise, a table overflow error message is displayed to the user.
The numeric data item affected by the OPT1 option is referenced in the Procedure
Division only in a numeric context. Thus, the numeric data item can be the operand of an
arithmetic statement or it can be used as a subscript. However, the numeric data item
cannot be used as an item of a STRING statement.
An integer item with the OPT1 option set is mapped internally to a compiler- created
integer stack cell, in addition to its original EBCDIC (for DISPLAY) or HEX (for
COMPUTATIONAL or PACKED-DECIMAL) field. The hidden integer stack cell is in the
format of a single word, if the picture size is 9(11) or less, or in the format of a double
word, if the picture size is greater than 9(11).
Whenever the OPT1 integer item is used in a statement (limited to numeric context), the
hidden integer stack cell is used directly without updating the original field.
If a data item that contains or overlaps an OPT1 data item is used in a statement (limited
to the MOVE statement only), one of the following occurs:

•

If the data item is the source, there is an implicit move from the hidden cell to the
original field immediately before the move of the data item.

•

If the data item is the destination, there is an implicit move from the original field to
the hidden integer stack cell immediately after the move.

8600 1518–307

15–77

Compiler Options

OPT2 Option
Type: Boolean
Default: FALSE
This option specifies that a COBOL85 source program consists entirely of uppercase
characters. Programs that are in uppercase characters only will compile faster due to the
overhead that is eliminated by the compiler not having to search for lowercase characters
and transform the lowercase characters to uppercase.
You must place the OPT2 option anywhere in the source after the Identification Division
header line. An OPT2 option placed before the Identification Division header line is
ignored.
If the OPT2 option is set and lowercase letters appear in the source, the error message
“Illegal Character” is issued for each lowercase letter that is found.

OPT3 Option
Type: Boolean
Default: FALSE
This option enables you to declare a constant in the Data Division. For example, the
following use of the OPT3 option sets the data item CONST-1:
$SET OPT3
01
CONST-1
$RESET OPT3

PIC 999 VALUE 1.

When OPT3 is set, the data item CONST-1 is treated as a constant rather than as a
regular data item. Thus, CONST-1 always has the value of 1, and can be used only as a
sending-only (or reference-only) operand, and not as a receiving operand. This will
improve run-time performance.
OPT3 can be applied to any data category; however, you must ensure that the data is not
used as a receiving operand.
Though the main use of the OPT3 option is for elementary data items, OPT3 can also be
used for alphanumeric group data items that contain only nested group items and FILLER
alphanumeric data items with VALUE clauses. This enables the INSPECT...CONVERTING
statement to identify the data items as translate-table constants and to avoid generating
a run-time call to build the translate table. Following is an example.
$ SET OPT3
01 XLATE-IN.
05 FILLER PIC X(128) VALUE
@000102030405060708090A0B0C0D0E0F101112131415161718191A1B
@1C1D1E1F202122232425262728292A2B2C2D2E2F3031323334353637
@38393A3B3C3D3E3F404142434445464748494A4B4C4D4E4F50515253
@5455565758595A5B5C5D5E5F606162636465666768696A6B6C6D6E6F

15–78

8600 1518–307

Compiler Options

@707172737475767778797A7B7C7D7E7F@.
FILLER PIC X(128) VALUE
@808182838485868788898A8B8C8D8E8F909192939495969798999A9B
@9C9D9E9FA0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7
@B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7C8C9CACBCCCDCECFD0D1D2D3
@D4D5D6D7D8D9DADBDCDDDEDFE0E1E2E3E4E5E6E7E8E9EAEBECEDEEEF
@F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF@.
01 XLATE-OUT.
:
$ RESET OPT3
05

OPT4 Option
Type: Boolean
Default: FALSE
This option specifies whether or not the compiler is enabled to use a word copy
descriptor optimization for short character data items. The optimization is permitted
when the option has the default value of FALSE.
This optimization can provide a performance boost and is not an issue under normal
conditions. However, for some COBOL subprograms generated in Enterprise Application
Environment (formerly LINC), this optimization can cause problems. The OPT4 option is
provided to disable the optimization in these cases.
Example
$SET OPT4
01 MYDATA COMMON.
03 MD-ALFA1 PIC X(10).
03 MD-ALFA2 PIC X(1).
03 MD-ALFA2 PIC X(2).
$RESET OPT4

8600 1518–307

15–79

Compiler Options

OPTIMIZE Option
Ú
³
ä
³
³
³
³
³
³
³
ä SET
å ³
OPTIMIZE ³ ( ã ïïï
â ã
ïïïïïïïï ³ ï æ RESET ç ³
³
ïïïïï
³
³
³
³
³
³
æ
À

GAMBLE
ïïïïïï
GRAPH
ïïïïï
LEVEL =
ïïïïï
MAX_VECTOR_OPS = maximum
ïïïïïïïïïïïïïï
TIMING
ïïïïïï
UNRAVEL
ïïïïïïï

¿
å
³
³
³
³
³
³
³
³
³
â ... ) ³
³
ï ³
³
³
³
³
³
³
ç
³
Ù

Type: Boolean class
Default: FALSE
This option controls the optimizations performed before code generation. The compiler
examines this option at the beginning of each procedure to determine the optimizations
to be performed on that procedure. Thus, although the setting of the OPTIMIZE option
can be changed at any time, only its setting at the beginning of the procedure is
significant.
Because this is a Boolean class option, setting the option sets all of the suboptions, and
resetting the option resets all of the suboptions. You can also set and reset each
suboption individually. For details, refer to “Boolean Class Compiler Options” earlier in
this section.
The six subordinate options available within the OPTIMIZE option are described as
follows:
GAMBLE

This suboption allows the compiler to make certain assumptions to perform the following
optimizations:

•

The associative law applied to floating-point types (that is, changing a division to a
multiplication by a reciprocal)

•

The associative law applied to integer types (that is, changing a subtraction to an
addition by an inverse)

•

Conditionally executed invariant expressions moved outside of loops

•

Indexes assumed to be within bounds

•

Variable “strides” assumed to be positive

This option should be reset if the COBOL85 program utilizes display data items
containing undigits or data with zones other than hex F.

15–80

8600 1518–307

Compiler Options

GRAPH

This option causes a graph of the optimized procedure to be written to the output listing.
LEVEL

This option controls the amount of effort expended by the compiler in optimizing a
procedure. In general, the higher the level, the greater the optimization effort. Higher
levels tend to yield reduced run time at the expense of increased compilation time. The
level must range from 0 to 10.
MAX_VECTOR_OPS = maximum

This option enables you to specify the maximum number of vector operators allowed per
statement. The default is 3. If the target machine has vector operators and $OPTIMIZE is
set, the compiler generates vector operators. A single source statement can cause
multiple vector operators to be generated. Whether executing multiple vector operators
is faster than the original loop depends on the number of iterations of the loop and the
particular vector operators involved.
TIMING

This option causes statistics regarding the optimization phase of the compilation to be
gathered and written to the output listing.
UNRAVEL

This option allows loops to be unraveled and certain functions to be generated as in-line
code.
Examples
OPTIMIZE (SET GAMBLE UNRAVEL, RESET LEVEL)
OPTIMIZE (SET GAMBLE, RESET LEVEL, SET UNRAVEL)

8600 1518–307

15–81

Compiler Options

OPTION Option
OPTION
ïïïïïï

{ ( [option action] option name ... ) }

Type: Boolean
Default: FALSE
This option declares a user-defined compiler control option. A user option can be
manipulated exactly like any other Boolean option using the SET, RESET and POP option
actions. Also, it can be used in option expressions to assign values to standard Boolean
options or to other user options.
An initial setting for the user option can be specified by using the SET, RESET, and POP
option actions within the parentheses. For example, the following declares the user
options SECURITY1 and SECURITY2 and sets the initial value of SECURITY1 to TRUE,
and the initial value of SECURITY2 to FALSE:
$ SET OPTION (SET SECURITY1 RESET SECURITY2)
If an initial value is not specified, the initial value is supplied by the option action
associated with the OPTION compiler option. For example, the preceding example could
have been specified using either one of the following formats:
Example Format 1
$ SET OPTION (SECURITY1 RESET SECURITY2)
Example Format 2
$ RESET OPTION (SECURITY2 SET SECURITY1)

15–82

8600 1518–307

Compiler Options

OWN Option
Type: Boolean
Default: FALSE
This option specifies whether data items in the Working-Storage Section are to assume
the declaration OWN. The following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

All data items in the Working-Storage Section except
those items explicitly declared COMMON or OWN
are considered to be LOCAL data items.

SET

TRUE

All data items in the Working-Storage Section except
those items explicitly declared COMMON or LOCAL
are considered to be OWN data items.

The OWN option and the COMMON option cannot both be TRUE.
The OWN option is ignored if the compilation is at lexicographical level 2.

PAGE Option
Type: Immediate
This option directs the compiler to begin printing on a new page in the output compilation
listing (LINE).
The PAGE option is ignored if the LIST option is FALSE.
If the OMIT option is TRUE and the LISTOMITTED option is FALSE, the PAGE option is
ignored.

PAGESIZE Option
PAGESIZE
ïïïïïïïï

pagesize value

Type: Value
Default: 58
This option specifies the number of lines printed on each page of the output compilation
listing (LINE).
The PAGESIZE option is ignored if the LIST option is FALSE.

8600 1518–307

15–83

Compiler Options

PAGEWIDTH Option
PAGEWIDTH
ïïïïïïïïï

pagewidth value

Type: Value
Default: 132
This option specifies the number of characters printed on each line of the output
compilation listing (LINE).
The PAGEWIDTH option is ignored if the LIST option is FALSE.

RPW (Report Writer) Option
Type: Boolean
Default: FALSE
RPW controls whether the compiler identifies COBOL language constructs that are
Report Writer elements as determined by the ANSI Standards Committee. The following
table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not print warning messages
identifying RPW elements.

SET

TRUE

The compiler prints warning messages to identify
RPW elements. Warning messages are not printed
if the WARNSUPR option is TRUE.

SDFPLUSPARAMETERS Option
This option is for internal use in the system software only.

15–84

8600 1518–307

Compiler Options

SEARCH Option

SEARCH
ïïïïïï

ä
ã
æ

å
â
+= ç

ä
³
³
ã
³
³
æ

'partial file title'
"partial file title"
'$[ - ]'
"$[ - ]"

å
³
³
â
³
³
ç

Type: String
This option specifies partial file names to be used when searching for included files. The
partial file names represent alternate file directories under which the included file might
reside. The syntax SEARCH = "partial file title" or 'partial file title' assigns a string of
characters to the list of partial file names. The syntax SEARCH += "partial file title" or
SEARCH += 'partial file title' appends a string of characters to a previously defined list
of partial file names.
The following table describes two special constructs for specifying partial file names in
the SEARCH option:

Construct

Meaning

The compiler replaces this with the name of the primary source input file
(CARD) followed by the characters /=. For example, if the primary source
input file is named UTILITY/ACCOUNT/FIXUP, the partial file name
UTILITY/ACCOUNT/FIXUP/= is added to the list of partial file names used
in searching for included files.

The compiler replaces this with a partial name of the primary source input
file (CARD) followed by the characters /=. The partial name is formed by
removing the last file name node of the primary source input file. For
example, if the primary source input file is named
UTILITY/ACCOUNT/FIXUP, the file name node FIXUP is removed, and the
partial file name UTILITY/ACCOUNT/= is added to the list of partial file
names used in searching for included files.

The partial file titles specified by the SEARCH compiler option are used to form the file
titles searched for when the following condition exists:

•

An INTNAME is not specified in the INCLUDE option, or if one is specified, a file
equation has not been applied to the INTNAME.

When this condition exists, the compiler performs the following actions on the TITLE file
attribute of the included file:

•

Translates all lowercase characters to their uppercase equivalents.

•

Replaces all backslashes (\) and periods (.) with slashes (/).

8600 1518–307

15–85

Compiler Options

If partial file names have been specified with the SEARCH option, these partial file names
are combined with the TITLE file attribute of the included file to form file titles. The
compiler then searches for the included file using these generated file titles. For
example, a program might contain the following CCRs:
$ SET SEARCH = "SYSTEM/= ON LOCALPACK; (USER)SOURCE/="
$ SET SEARCH+= ";*SYSTEM/= ON EXTERNALS"
.
.
.
$ INCLUDE DEFINES = "LOCAL/DEFINES."
If a file title has not been applied to the file identified by the internal name “DEFINES”
through file equation, the compiler attempts to find the file by combining the partial file
names specified by the SEARCH option with the TITLE file attribute specified by the
INCLUDE option. The following file titles would be searched for in the order listed. The
first file title to match the file title of an existing file is used as the file title of the included
file.
SYSTEM/LOCAL/DEFINES ON LOCALPACK
(USER)SOURCE/LOCAL/DEFINES
*SYSTEM/LOCAL/DEFINES ON EXTERNALS
If the file is not present under any of these names, the compiler attempts to use the
TITLE file attribute itself to find the file. If this fails, the compiler attempts a file OPEN
operation to change the status of the compilation to WAITING, and displays a NO FILE
message. For more information, refer to “INCLUDE Option” earlier in this section.

SEPARATE Option
Type: Boolean
Default: FALSE
This option controls the resultant object code file produced by the compiler. The
following table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

A separate executable object code file that does not
contain binding information will be generated for
each program unit found in the source file.

SET

TRUE

A separate non-executable object code file that
contains binding information will be generated for
each program unit found in the source file.

SEPARATE must be included in the source code before the Identification Division of the
program. When this option is set, the resultant object code file can be bound to a host
file through use of the Binder utility.

15–86

8600 1518–307

Compiler Options

SEQUENCE or SEQ Option
Type: Boolean
Default: FALSE
This option controls whether new sequence numbers are generated for the new source
language symbolic file (NEWSOURCE). New sequence numbers do not affect the
compilation listing file (LINE). The following table describes the effects of this option:
Option
Setting

Value

Description

RESET

FALSE

The compiler does not generate new sequence
numbers.

SET

TRUE

The compiler assigns the current sequence base to the
current source language record and increments the
sequence base by the sequence increment. If the
resulting sequence base exceeds 999999, the
compiler disables the SEQ option, and produces a
sequence error.

The sequence base and sequence increment used by the compiler when assigning new
sequence numbers can be specified using the Sequence Base option and Sequence
Increment option described next.

Sequence Base Option
sequence number

[ + sequence increment ]

Type: Value
Default: 100
This option specifies the sequence base used by the compiler when the SEQUENCE
option is TRUE. The compiler uses the specified sequence base with the sequence
increment to assign new sequence numbers to source language records. The sequence
increment is specified using the Sequence Increment option described next.

Sequence Increment Option
+ sequence increment

Type: Value
Default: 100
This option specifies the sequence increment used by the compiler when the
SEQUENCE option is TRUE. The compiler uses the specified sequence increment with
the sequence base to assign new sequence numbers to source language records. The
sequence base is specified using the Sequence Base option described earlier in this
section.

8600 1518–307

15–87

Compiler Options

SHARING Option

SHARING
ïïïïïïï

ä
³
³
ã
³
³
æ

DONTCARE
ïïïïïïïï
PRIVATE
ïïïïïïï
SHAREDBYRUNUNIT
ïïïïïïïïïïïïïï
SHAREDBYALL
ïïïïïïïïïïï

å
³
³
â
³
³
ç

Type: Enumerated
Default: SHAREDBYRUNUNIT
This option specifies how programs that call this library share access to this library. The
SHARING option must be included in the source program before the Identification
Division.
Note: This option has no effect unless used with the LIBRARYPROG compiler option.
The following table describes the available settings for the SHARING option:

Option Setting

Description

DONTCARE

The operating system determines the sharing.

PRIVATE

A copy of the library is invoked for each user (calling program).
Any changes made to global items in the library by the actions
of the user are visible only to that user of the library.

SHAREDBYRUNUNIT

SHAREDBYALL

All simultaneous users share the same instance of the library.

If the library is called by a COBOL74 or COBOL85 program, the library services only one
user at a time, regardless of the value of the sharing option. If you have a complex
environment where multiple libraries are linked together and you are using a COBOL74
type library, set the SHARING option to PRIVATE and the LIBRARYLOCK option to TRUE
to ensure data integrity.

15–88

8600 1518–307

Compiler Options

SHOWOBSOLETE Option
Type: Boolean
Default: FALSE
This option controls whether the compiler identifies COBOL language elements that are
considered obsolete by the ANSI standards committee. The following table describes the
effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not print warning messages
identifying obsolete COBOL language elements.

SET

TRUE

The compiler prints warning messages identifying
obsolete COBOL language elements. These warning
messages are not printed if the WARNSUPR option
is TRUE.

SHOWWARN Option
SHOWWARN

[ = Boolean expression]

Type: Boolean
Default: FALSE
This option controls whether the compiler issues warnings and error messages to the
CANDE terminal during compilation. The following table describes the effects of this
option:

Option Setting

Value

Description

RESET

FALSE

The compiler lists only error messages to the CANDE
terminal.

SET

TRUE

The compiler lists warnings as well as error
messages to the CANDE terminal.

STACK Option
This is a synonym for the MAP compiler option. See the “MAP or STACK Option” earlier
in this section.

8600 1518–307

15–89

Compiler Options

STATISTICS Option

STATISTICS

Ú
³
³
³
ä SET
å
³ ( ã ïïï
â
³ ï æ RESET ç
³
ïïïïï
³
³
À

ä
³
³
ã
³
³
æ

BLOCK
ïïïïï
PBITS
ïïïïï
SYSTEM
ïïïïïï
TERSE
ïïïïï

å
³
³
â ...)
³
ï
³
ç

¿
³
³
³
³
³
³
³
³
Ù

Type: Boolean
Default: False (RESET) for STATISTICS option, False (RESET) for BLOCK, False (RESET)
for PBITS, False (RESET) for SYSTEM, and False (RESET) for TERSE
This option causes timing statistics to be gathered for each paragraph. The option is
examined at the beginning of each paragraph and, if enabled, statistics are gathered for
that paragraph. Although the option setting can be changed at any time, only the setting
at the beginning of a paragraph is significant. At program termination, the statistics
information is printed out to the TASKFILE.
The statistics include the number of times the nested program is called and the amount
of time spent in the nested program, both inclusive and exclusive of the amount of time
spent in the nested programs called by that nested program.
The STATISTICS option can be used with individual subprograms of a bound program.
When the bound program terminates, statistics are printed independently for each
subprogram compiled with the option.
The four suboptions available within the STATISTICS option are described as follows:
BLOCK

If the BLOCK suboption is set, statistics are gathered for each execution path in the
code. These statistics include the number of times each execution path is executed. The
sequence number that is listed is the start of an execution path. All sequence numbers
within the code that are not listed are included in the most recently listed sequence
number, since these lines of code share the same execution path. Complex statements
can be composed of several different execution paths, which are represented by the
same sequence number being listed more than once.
PBITS

If the PBITS suboption is set, statistics are gathered about the initial pbits occurring in
the program.

15–90

8600 1518–307

Compiler Options

SYSTEM

If the SYSTEM suboption is set, SLICESUPPORT functions and MCP calls are tracked
separately. These items are preceded by “S:” and “M:” as follows:

•

M: -- Indicates that the item is an MCP function that was added by the compiler.

•

S: -- Indicates that the item is a SLICESUPPORT function that was added by the
compiler.

TERSE

If the TERSE suboption is set, paragraphs that are not called are not listed in the
statistics output.

STRINGS Option

STRINGS
ïïïïïïï

ä
ã
æ

ASCII
ïïïïï
EBCDIC
ïïïïïï

å
â
ç

Type: Enumerated
Default: EBCDIC
This option specifies the default character type used for the compilation. The following
table describes the effects of this option.

Option Setting

Description

ASCII

Sets the default character type to ASCII

EBCDIC

Sets the default character type to EBCDIC

8600 1518–307

15–91

Compiler Options

STRICTPICTURE Option
Type: Boolean
Default: FALSE
This option determines whether the compiler enforces a strict interpretation of the ANSI
rules for PICTURE character string formation.

Option Setting

Value

Description

RESET

FALSE

Allow non-ANSI PICTURE strings

SET

TRUE

Disallow non-ANSI PICTURE strings

If this option is SET, the compiler allows only those symbols and combinations of
symbols that are allowed by ANSI to comprise a PICTURE character string. The compiler
issues syntax errors for those symbols and combinations of symbols that do not conform
to ANSI standards. Neither of the Unisys extensions to simple insertion editing, Manual
insertion editing and Automatic insertion editing, is allowed in this case.
If this option is RESET, the compiler allows non-ANSI symbols in PICTURE character
strings. The choice of whether Automatic insertion editing or Manual insertion editing is
allowed in this case is determined by the setting of the AUTOINSERT option.
STRICTPICTURE and AUTOINSERT cannot both be set to true at the same time.

SUMMARY Option
Type: Boolean
Default: FALSE
This option controls whether the compiler produces a summary listing containing
information about the compilation. The following table describes the effects of this
option:

Option Setting

Value

Description

RESET

FALSE

The compiler omits the summary listing.

SET

TRUE

The compiler produces a summary listing
containing the source language records used for
the compilation, any error messages produced
by the compilation, and a summary of the level
of usage of some of the internal tables of the
compiler.

TIME is a synonym for SUMMARY.

15–92

8600 1518–307

Compiler Options

TADS Option

TADS

Ú
³
ä
Ú
¿
³
³
³ ' ³
³
³ REMOTE [=] ³
³ file indentifier
³
³ ïïïïïï
³ " ³
³ ( ã
À
Ù
³ ï ³ FREQUENCY
³
³ ïïïïïïïïï
³
æ RESOURCE = < resource value>
³
ïïïïïïïï
À

Ú
¿
³ ' ³
³
³
³ " ³
À
Ù

¿
å
³
³
³
³
³
³
³
â ...) ³
³
ï ³
³
³
ç
³
³
Ù

Type: Boolean class
Default: FALSE
When the TADS option is set to TRUE, special debugging code and tables are generated
as part of the object program. The tables are generated to support the symbolic
debugging environment of the COBOL85 Test and Debug System (TADS). For more
information on TADS, refer to the COBOL ANSI-85 Test and Debug System (TADS)
Programming Reference Manual.
The TADS option must be set before the first source statement or declaration of a
program.
The three suboptions available within the TADS option are described as follows:
REMOTE

The REMOTE suboption enables TADS to share a REMOTE file with the program being
tested. Sharing a file might be necessary because only one REMOTE input file can be
open for each station. The file must have been assigned to REMOTE, and must be
opened INPUT-OUTPUT. The record size must not be less than 72.
FREQUENCY

The FREQUENCY suboption enables TADS to accept the test coverage and frequency
analysis commands during a test session. The test coverage and frequency analysis
commands provide statistics on the execution of specified statements. The commands
are: CLEAR, COVERAGE, FREQUENCY, MERGE and SAVE.
The CLEAR, COVERAGE, and FREQUENCY commands are accepted when the TADS
compiler control option is specified as follows:
$ SET TADS (FREQUENCY)
Refer to the COBOL ANSI-85 Test and Debug System (TADS) Programming Reference
Manual for detailed information on the test coverage and frequency analysis commands.

8600 1518–307

15–93

Compiler Options

RESOURCE

The RESOURCE suboption determines the amount of resources to be used for TADS
conditions. Increasing the should improve the performance of TADS
conditions, while causing more D1 stack cells and saved memory to be used.
The can range from 20 to 2000 and has a default value of 100. The
RESOURCE suboption should appear before any program text. Bound programs must
have identical values for the RESOURCE suboption.

TARGET Option
TARGET = target-1 [ ( target-2 [ ,target-3 . . .] ) ]
ïïïïïï
Type: Enumerated
Default: Installation-defined
This option designates a specific computer system or group of systems as the target for
which the generated object code is to be optimized. This option can be used to specify all
machines on which the code file needs to run.
TARGET must appear in the source before the Identification Division of the program.
Specification of a secondary target is optional. If specified, a secondary target must be
enclosed in parentheses. If more than one secondary target is specified, then the
additional targets must be separated from each other by a comma and the entire list
must be enclosed in parentheses.
If a secondary target is specified, the compiler does not generate any operators that are
valid for the system or systems identified by the primary target but invalid for the system
or systems identified by the secondary target.
See the COMPILERTARGET system command in the System Commands Operations
Reference Manual for a complete list of the target values that are allowed.
Examples
TARGET=THIS
The compiler optimizes the object code file for the system on which it is compiled.
TARGET=THIS (ALL)
The compiler optimizes the object code file for the system on which it is compiled, but it
does not generate any operators that are invalid for other machines.

15–94

8600 1518–307

Compiler Options

TEMPORARY Option
Type: Boolean
Default: FALSE
This option controls whether the object program, when called as a library, functions as a
temporary or permanent library and is provided to ease migration from COBOL74 to
COBOL85. The TEMPORARY compiler option should not be used if a program is
declared explicitly to be a library. If a program is not declared explicitly to be a library but
will be called as a library by other programs, then the LIBRARYPROG, TEMPORARY, and
FEDLEVEL options should be specified.
A temporary library remains available as long as there are users of the library. A
permanent library remains available until it is explicitly terminated. The following table
describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

Depending on the setting of the SHARING attribute of
the library, the library can be either temporary or
permanent. If SHARING is set to DONTCARE, then the
object program functions as a permanent library when
called as a library by another program. If SHARING is
set to SHAREDBYRUNUNIT or PRIVATE, then the
object program functions as a temporary library when
called as a library by another program.

SET

TRUE

The object program functions as a temporary library
when called as a library by another program. A
temporary library remains available as long as there are
users of the library.

8600 1518–307

15–95

Compiler Options

TITLE Option

TITLE
ïïïïï

ä = å
ã
â
æ += ç

ä 'file title' å
ã
â
æ "file title" ç

Type: String
Default: The name of the compiler
This option specifies a string of characters to be printed in the upper left corner of each
output listing page. Only the final value declared in the program as the title appears on
the output listing. If the LIST option is FALSE, the TITLE option is ignored.
TITLE =

Assigns a string of characters to the header of each output listing page.
TITLE +=

Appends a string of characters to a previously defined title string.
'file title'
"file title"

Either apostrophes (' ') or quotation marks (" ") may enclose the file title.

UDMTRACK Option
Type: Boolean
Default: FALSE
When set to true, the UDMTRACK option loads tracking information in the Universal
Repository DMSII Model (UDM) for any of the databases loaded in the UDM. When set
to false, no tracking information is loaded into the UDM. Note that the loading is done by
a WFL job called DATABASE/WFL/UDM using a stream file created by COBOL.

15–96

8600 1518–307

Compiler Options

VERSION Option

VERSION
ïïïïïïï

ä
ã
æ

version.cycle.patch
+version.+cycle.patch

å
â
ç

Type: Value
Default: 00.000.0000
This option specifies a version number. Version numbers are used to manage software
development. The VERSION option specifies an initial version number, replaces an
existing version number, or updates to an existing version number.
Replacement or updating of existing version numbers occurs when all of the following
conditions exist:

•

The NEW option is TRUE.

•

A VERSION option appears in the secondary input file (SOURCE).

•

The update form of the VERSION option appears in the primary input file (CARD).

•

The sequence number of the VERSION option in the primary input file (CARD) is less
than or equal to the sequence number of the VERSION option in the secondary input
file (SOURCE).

When all these conditions are satisfied, the VERSION option specification from the
secondary input file is updated with the values specified by the VERSION option from the
primary input file. The updated VERSION option record is placed in the updated symbolic
file (NEWSOURCE).

8600 1518–307

15–97

Compiler Options

VOID Option
Type: Boolean
Default: FALSE
This option controls whether the compiler ignores all source language input from both
the primary input source file and the secondary input source file. Once the VOID option is
SET, it can be RESET only by a CCR in the primary input file (CARD). The following table
describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler processes all source language input.

SET

TRUE

The compiler ignores all source language input from
both the primary input source file and the secondary
input source file. The compiler processes only CCRs.
The ignored source input is neither listed in the
compilation listing nor included in the updated
symbolic file, regardless of the values of the LIST
option and the NEW option.

WARNFATAL Option
Type: Boolean Class
Default: FALSE for the class, FALSE for MSG suboption

WARNFATAL [ ( MSG ( msg-number-list ) ... ) ]
ïïïïïïïïï

This option controls the treatment of warning messages that might be flagged as errors.
The suboption, MSG, for WARNFATAL is described in the following explanation.
MSG

The MSG suboption provides a way to designate a set of active warnings that might
beflagged as errors. It is used to add to, or subtract from the active set. An
MSG-number-list is a list of unsigned integers and the word ALL, separated by commas
or spaces. The word ALL can be used to activate or deactivate all messages for flagging.
Message numbers are activated for flagging by the SET action and deactivated by
RESET.

15–98

8600 1518–307

Compiler Options

Option Setting

Value

Description

Class SET

TRUE

Active warnings are flagged as errors.

Class RESET

FALSE

No warnings are flagged as errors.

Suboption SET

List

Adds the list of warnings to the list of active warnings.

Suboption RESET

List

Deletes the list of warnings from the list of active
warnings.

Examples
The following examples illustrate the use of the WARNFATAL option.
$SET

WARNFATAL(MSG(ALL))
WARNFATAL is set and all warnings will be flagged as errors.

$SET

WARNFATAL(SET MSG(ALL) RESET MSG(385))
WARNFATAL is set and all messages are active except 385, so all but
it will be errors, rather than warnings.

$RESET WARNFATAL(SET MSG(103,820,553))
WARNFATAL is reset, although messages 103, 820 and 553 are armed for
flagging once WARNFATAL is set.
$SET

WARNFATAL(RESET MSG(107))
WARNFATAL is now set, and message 107 is marked as inactive for
flagging.

$RESET WARNFATAL(MSG(385))
WARNFATAL is reset and message 385 is marked as inactive for
flagging.
$SET

8600 1518–307

WARNFATAL
WARNFATAL is enabled and any active messages will be flagged.

15–99

Compiler Options

WARNSUPR Option
Type: Boolean
Default: FALSE
The warning suppress option controls the display of warning messages. The following
table describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler prints warning messages.

SET

TRUE

The compiler suppresses printing of warning
messages.

The WARNSUPR option does not affect the printing of messages related to syntax
errors.

XREF Option
Type: Boolean
Default: FALSE
This option is used in conjunction with the XREFFILES option to control whether crossreference information is collected and printed by the compiler. The following table
describes the effects of this option:

Option Setting

15–100

Value

Description

RESET

FALSE

If the XREFFILES option is TRUE, the compiler
generates cross-reference information with the
output stored in disk files. If the XREFFILES option is
FALSE, the compiler does not generate crossreference information.

SET

TRUE

The compiler generates cross-reference information.
The information is written to the output listing. If a
syntax error occurs during compilation, a crossreference listing is not produced. If both the XREF
and XREFFILES options are TRUE, then crossreference information is both printed and stored in
disk files.

8600 1518–307

Compiler Options

The cross-reference information consists of an alphabetized list of user-defined words
that appear in the program. For each user-defined word, the compiler provides the
following information:

•

The type of data item named by each user-defined word

•

The sequence number of the source input record on which the user-defined word is
declared

•

The sequence number of the source input record on which the data item is declared

•

The sequence numbers of the input records on which the user-defined word is
accessed

If your program contains INCLUDE or COPY files, the sequence numbers take the form
fff:nnnnnn where “fff” is the number of the INCLUDE file and “nnnnnn” is the actual
sequence number in the file. For example, sequence numbers that are referenced in the
third INCLUDE or COPY file are listed as 3:nnnnnn. The file numbers for INCLUDE and
COPY files are printed in the summary.
The XREF option should be included in the source code before the end of the
Identification Division of the program.

8600 1518–307

15–101

Compiler Options

XREFFILES Option

XREFFILES
ïïïïïïïïï

[ = ]

ä
³
ã
³
æ

ä
ã
æ

'file title'
"file title"

å
â
ç

Boolean-expression

å
³
â
³
ç

¿
³
³
³
³
³
Ù

Type: Boolean Title
Default: FALSE
This option controls whether cross-reference information is collected and saved in disk
files by the compiler. For more information on cross-reference information generated by
the compiler, refer to the XREF option, earlier in this section. The following table
describes the effects of this option:

Option Setting

Value

Description

RESET

FALSE

The compiler does not generate cross-reference
information.

SET

TRUE

The compiler generates cross-reference information
with the output directed to disk files for use by the
Editor and SYSTEM/INTERACTIVEXREF. If both the
XREF option and the XREFFILES option are TRUE, then
output is both printed and stored in disk files for use by
the Editor and SYSTEM/INTERACTIVEXREF.

When the XREFFILES option is true, the following disk files are produced:
XREFFILES/

COBOL ANSI 85 Programming Reference Manual, Volume 1 COBOL85 Vol

86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003 86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003

86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003 manual pdf -FilePursuit

86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003 86001518-307_COBOL_ANSI-85_Programming_Reference_Manual_Volume_1_Basic_Implementation_Feb2003

COBOL85 Vol 1 COBOL85 Vol 1

Navigation menu

Versions of this User Manual:

Views

Navigation