OpenCOBOL 1.1[06FEB2009 Version]

Programmer’s Guide
1st Edition, 17 September 2010
Gary Cutler
CutlerGL@gmail.com

OpenCOBOL Copyright © 2001-2010 Keisuke Nishida / Roger While
Under the terms of the GNU General Public License

Document Copyright © 2009,2010 Gary Cutler
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free
Documentation License [FDL], Version 1.3 or any later version published by the Free Software Foundation;with Invariant Section “What is OpenCOBOL?”, no Front-Cover Texts, and no Back-Cover Texts.

A copy of the FDL is included in the section entitled "GNU Free Documentation License".

17 September 2010

OpenCOBOL is an evolving tool.
While all reasonable attempts will be made to maintain the currency of the information in this document, neither theauthor of this document nor the authors of the OpenCOBOL software, extend any warranties of any kind by thisdocument or for the information contained therein.

Summary of Changes
Edition
1st

Date
17 September 2010

[06FEB2009]

Change Description
Introduced documentation for the hitherto undiscovered “COBCPY” environment variable (section
7.1.7 and 7.1.8).
Corrected “section 0” broken hyperlinks in the document.

1 April 2010

Documented a work-around for a potential 06FEB2009 compiler parsing problem with the“expression-1 CHARACTERS” clause on the ALLOCATE verb (section 6.6). The parsing problem will becorrected in a future OpenCOBOL 1.1 tarball, at which time the “work-around” documentation will
be removed.
Elaborated on the use of the GLOBAL clause in data item definitions (section 5.3).

24 March 2010

Corrected a problem with bogus footnote references in Figure 4-8

23 January 2010

OFFICIAL FIRST RELEASE
Corrected an error with the description of reference modifiers lacking a length specification.

Pre-publication review
July-September 200917 September 2010

Initial version – documents the 06 Feb 2009 build of OpenCOBOL 1.1

OpenCOBOL 1.1 Programmers Guide

Table of Contents

Table of Contents
FIGURES6

1. INTRODUCTION

1-1

1.1. What is OpenCOBOL?
1.2. Additional References and Documents
1.3. Introducing COBOL
1.3.1. “I Heard COBOL is a Dead Language!”
1.3.2. Programmer Productivity – The “Holy Grail”
1.3.3. Notable COBOL/OpenCOBOL Features
1.3.3.1. Basic Program Readability
1.3.3.2. COBOL Program Structure
1.3.3.3. Copybooks
1.3.3.4. Structured Data
1.3.3.5. Files
1.3.3.6. Table Handling
1.3.3.7. Sorting and Merging Data
1.3.3.8. String Manipulation
1.3.3.9. Textual-User Interface (TUI) Features
1.4. Syntax Description Conventions
1.5. Source Program Format
1.6. Use of Commas and Semicolons
1.7. Using COPY
1.8. Use of Literals
1.8.1. Numeric Literals
1.8.2. Alphanumeric Literals
1.9. Use of Figurative Constants
1.10. User-Defined Names
1.11. Use of LENGTH OF

1-1
1-1
1-1
1-2
1-3
1-4
1-4
1-5
1-5
1-5
1-5
1-8
1-8
1-8
1-10
1-10
1-11
1-11
1-12
1-12
1-12
1-13
1-13
1-14
1-14

2. GENERAL OPENCOBOL PROGRAM FORMAT

2-1

2.1. General Format for Nested Source Programs
2.2. General Format for Nested Source Functions

2-2
2-2

3. IDENTIFICATION DIVISION

3-1

4. ENVIRONMENT DIVISION

4-1

4.1. CONFIGURATION SECTION
4.1.1. SOURCE-COMPUTER Paragraph4.1.2. OBJECT-COMPUTER Paragraph4.1.3. REPOSITORY Paragraph4.1.4. SPECIAL-NAMES Paragraph4.2. INPUT-OUTPUT SECTION
4.2.1. FILE-CONTROL Paragraph4.2.1.1. ORGANIZATION SEQUENTIAL Files
4.2.1.2. ORGANIZATION RELATIVE Files
4.2.1.3. ORGANIZATION INDEXED Files
4.2.2. I-O-CONTROL Paragraph

4-1
4-1
4-1
4-2
4-3
4-5
4-6
4-8
4-8
4-9
4-10

5. DATA DIVISION

5-1

5.1. FD - File Description
5.2. SD - SORT Description
5.3. General Format for Data Descriptions
5.4. Condition Names
5.5. Constant Descriptions

5-2
5-3
5-4
5-15
5-16

06FEB2009 Version

1

OpenCOBOL 1.1 Programmers Guide

Table of Contents

5.6. Screen Descriptions

5-17

6. PROCEDURE DIVISION

6-1

6.1. General PROCEDURE DIVISION Components
6.1.1. Table References
6.1.2. Qualification of Data Names
6.1.3. Reference Modifiers
6.1.4. Expressions
6.1.4.1. Arithmetic Expressions
6.1.4.2. Conditional Expressions
6.1.5. Use of Periods (.)
6.1.6. Use of “VERB” / “END-VERB” Constructs
6.1.7. Intrinsic Functions
6.1.7.1. ABS(number)
6.1.7.2. ACOS(angle)
6.1.7.3. ANNUITY(interest-rate, number-of-periods)
6.1.7.4. ASIN(number)
6.1.7.5. ATAN(number)
6.1.7.6. BYTE-LENGTH(string)
6.1.7.7. CHAR(integer)
6.1.7.8. COMBINED-DATETIME(days, seconds)
6.1.7.9. CONCATENATE(string-1 [, string-2 ] …)
6.1.7.10. COS(number)
6.1.7.11. CURRENT-DATE
6.1.7.12. DATE-OF-INTEGER(integer)
6.1.7.13. DATE-TO-YYYYMMDD(yymmdd [, yy-cutoff ] )6.1.7.14. DAY-OF-INTEGER(integer)
6.1.7.15. DAY-TO-YYYYDDD(yyddd [, yy-cutoff])
6.1.7.16. E
6.1.7.17. EXCEPTION-FILE
6.1.7.18. EXCEPTION-LOCATION
6.1.7.19. EXCEPTION-STATEMENT
6.1.7.20. EXCEPTION-STATUS
6.1.7.21. EXP(number)
6.1.7.22. EXP10(number)
6.1.7.23. FRACTION-PART(number)
6.1.7.24. FACTORIAL(number)
6.1.7.25. INTEGER(number)
6.1.7.26. INTEGER-OF-DATE(date)
6.1.7.27. INTEGER-OF-DAY(date)
6.1.7.28. INTEGER-PART(number)
6.1.7.29. LENGTH(string)
6.1.7.30. LOCALE-DATE(date [, locale ] )6.1.7.31. LOCALE-TIME(time [, locale ] )6.1.7.32. LOCALE-TIME-FROM-SECS(seconds [, locale ] )6.1.7.33. LOG(number)
6.1.7.34. LOG10(number)
6.1.7.35. LOWER-CASE(string)
6.1.7.36. MAX(number-1 [, number-2 ] …)
6.1.7.37. MIN(number-1 [, number-2 ] …)
6.1.7.38. MEAN(number-1 [, number-2 ] …)
6.1.7.39. MEDIAN(number-1 [, number-2 ] …)
6.1.7.40. MIDRANGE(number-1 [, number-2 ] …)
6.1.7.41. MOD(value, modulus)
6.1.7.42. NUMVAL(string)
6.1.7.43. NUMVAL-C(string [, symbol ])6.1.7.44. ORD(char)

6-1
6-1
6-1
6-2
6-2
6-3
6-5
6-9
6-10
6-11
6-11
6-12
6-12
6-12
6-12
6-12
6-12
6-13
6-13
6-13
6-13
6-13
6-13
6-14
6-14
6-14
6-14
6-14
6-14
6-15
6-15
6-15
6-15
6-15
6-15
6-15
6-15
6-16
6-16
6-16
6-16
6-16
6-16
6-16
6-16
6-17
6-17
6-17
6-17
6-17
6-17
6-17
6-17
6-18

06FEB2009 Version

2

OpenCOBOL 1.1 Programmers Guide
6.1.7.45. ORD-MAX( char-1 [, char-2 ] … )6.1.7.46. ORD-MIN( char-1 [, char-2 ] … )6.1.7.47. PI
6.1.7.48. PRESENT-VALUE(rate,value-1 [, value-2 ] )6.1.7.49. RANDOM [ ( seed ) ]6.1.7.50. RANGE(number-1 [, number-2 ] …)
6.1.7.51. REM(number, divisor)
6.1.7.52. REVERSE(string)
6.1.7.53. SECONDS-FROM-FORMATTED-TIME(format,time)
6.1.7.54. SECONDS-PAST-MIDNIGHT
6.1.7.55. SIGN(number)
6.1.7.56. SIN(angle)
6.1.7.57. SQRT(number)
6.1.7.58. MEAN(number-1 [, number-2 ] …)
6.1.7.59. STORED-CHAR-LENGTH(string)
6.1.7.60. SUBSTITUTE(string,from-1,to-1 [, from-n,to-n ] )6.1.7.61. SUBSTITUTE-CASE(string,from-1,to-1 [, from-n,to-n ] )6.1.7.62. SUM(number-1 [, number-2 ] …)
6.1.7.63. TAN(angle)
6.1.7.64. TEST-DATE-YYYYMMDD(date)
6.1.7.65. TEST-DAY-YYYYDDD(date)
6.1.7.66. TRIM(string[ , LEADING|TRAILING ] )6.1.7.67. UPPER-CASE(string)
6.1.7.68. VARIANCE(number-1 [, number-2 ] …)
6.1.7.69. WHEN-COMPILED
6.1.7.70. YEAR-TO-YYYY (yy [, yy-cutoff])
6.1.8. Special Registers
6.1.9. Controlling Concurrent Access to Files
6.1.9.1. File Sharing
6.1.9.2. Record Locking
6.2. General Format of the PROCEDURE DIVISION
6.3. General Format for DECLARATIVES Entries
6.4. ACCEPT
6.4.1. ACCEPT Format 1 – Read from Console
6.4.2. ACCEPT Format 2 – Retrieve Command-Line Arguments
6.4.3. ACCEPT Format 3 – Retrieve Environment Variable Values
6.4.4. ACCEPT Format 4 – Retrieve Screen Data
6.4.5. ACCEPT Format 5 – Retrieve Date/Time
6.4.6. ACCEPT Format 6 - Retrieve Screen Size Data
6.4.7. ACCEPT Exception Handling6.5. ADD
6.5.1. ADD Format 1 – ADD TO
6.5.2. ADD Format 2 – ADD GIVING
6.5.3. ADD Format 3 – ADD CORRESPONDING
6.6. ALLOCATE
6.7. CALL
6.8. CANCEL
6.9. CLOSE
6.10. COMMIT
6.11. COMPUTE
6.12. CONTINUE
6.13. DELETE
6.14. DISPLAY
6.14.1. DISPLAY Format 1 – Upon Console
6.14.2. DISPLAY Format 2 – Access Command-Line Arguments
6.14.3. DISPLAY Format 3 – Access or Set Environment Variables
6.14.4. DISPLAY Format 4 – Screen Data
06FEB2009 Version

Table of Contents
6-18
6-18
6-18
6-18
6-18
6-19
6-19
6-19
6-19
6-19
6-19
6-19
6-19
6-20
6-20
6-20
6-20
6-20
6-20
6-20
6-20
6-20
6-21
6-21
6-21
6-21
6-21
6-22
6-22
6-23
6-24
6-25
6-26
6-26
6-26
6-27
6-28
6-29
6-29
6-30
6-31
6-31
6-32
6-32
6-33
6-34
6-36
6-37
6-38
6-39
6-40
6-41
6-42
6-42
6-42
6-42
6-43
3

OpenCOBOL 1.1 Programmers Guide
6.14.5. DISPLAY Exception Handling6.15. DIVIDE
6.15.1. DIVIDE Format 1 – DIVIDE INTO
6.15.2. DIVIDE Format 2 – DIVIDE INTO GIVING
6.15.3. DIVIDE Format 3 – DIVIDE BY GIVING
6.15.4. DIVIDE Format 4 – DIVIDE INTO REMAINDER
6.15.5. DIVIDE Format 5 – DIVIDE BY REMAINDER
6.16. ENTRY
6.17. EVALUATE
6.18. EXIT
6.19. FREE
6.20. GENERATE
6.21. GOBACK
6.22. GO TO
6.22.1. GO TO Format 1 – Simple GO TO
6.22.2. GO TO Format 2 – GO TO DEPENDING ON
6.23. IF6.24. INITIALIZE
6.25. INITIATE
6.26. INSPECT
6.27. MERGE
6.28. MOVE
6.28.1. MOVE Format 1 – Simple MOVE
6.28.2. MOVE Format 2 – MOVE CORRESPONDING
6.29. MULTIPLY
6.29.1. MULTIPLY Format 1 – MULTIPLY BY
6.29.2. MULTIPLY Format 2 – MULTIPLY GIVING
6.30. NEXT SENTENCE
6.31. OPEN
6.32. PERFORM
6.32.1. PERFORM Format 1 – Procedural
6.32.2. PERFORM Format 2 – Inline
6.33. READ
6.33.1. READ Format 1 – Sequential READ
6.33.2. READ Format 2 – Random Read
6.34. RELEASE
6.35. RETURN
6.36. REWRITE
6.37. ROLLBACK
6.38. SEARCH
6.38.1. SEARCH Format 1 –Sequential Search
6.38.2. SEARCH Format 2 –Binary, or Half-interval Search (SEARCH ALL)6.39. SET
6.39.1. SET Format 1 – SET ENVIRONMENT
6.39.2. SET Format 2 – SET Program-Pointer6.39.3. SET Format 3 – SET ADDRESS
6.39.4. SET Format 4 – SET Index
6.39.5. SET Format 5 – SET UP/DOWN
6.39.6. SET Format 6 – SET Condition Name
6.39.7. SET Format 7 – SET Switch
6.40. SORT
6.40.1. SORT Format 1 – File-based Sort
6.40.2. SORT Format 2 – Table Sort
6.41. START
6.42. STOP
6.43. STRING
6.44. SUBTRACT
06FEB2009 Version

Table of Contents
6-44
6-45
6-45
6-45
6-46
6-46
6-47
6-48
6-49
6-51
6-53
6-54
6-55
6-56
6-56
6-56
6-57
6-58
6-59
6-60
6-63
6-65
6-65
6-65
6-67
6-67
6-67
6-68
6-69
6-70
6-70
6-71
6-72
6-72
6-73
6-75
6-76
6-77
6-78
6-79
6-79
6-80
6-82
6-82
6-82
6-82
6-83
6-83
6-83
6-84
6-85
6-85
6-87
6-88
6-90
6-91
6-92
4

OpenCOBOL 1.1 Programmers Guide

Table of Contents

6.44.1. SUBTRACT Format 1 – SUBTRACT FROM
6.44.2. SUBTRACT Format 2 – SUBTRACT GIVING
6.44.3. SUBTRACT Format 3 – SUBTRACT CORRESPONDING
6.45. SUPPRESS
6.46. TERMINATE
6.47. TRANSFORM
6.48. UNLOCK
6.49. UNSTRING
6.50. WRITE

6-92
6-92
6-93
6-94
6-95
6-96
6-97
6-98
6-100

7. THE OPENCOBOL SYSTEM INTERFACE

7-1

7.1. Using the OpenCOBOL Compiler (cobc)
7.1.1. Introduction
7.1.2. Syntax and Options
7.1.3. Compiling Executable Programs
7.1.4. Dynamically-Loadable Subprograms
7.1.5. Static Subroutines
7.1.6. Combining COBOL and C Programs
7.1.6.1. OpenCOBOL Run-Time Library Requirements
7.1.6.2. String Allocation Differences Between OpenCOBOL and C
7.1.6.3. Matching C Data Types with OpenCOBOL USAGEs
7.1.6.4. OpenCOBOL Main Programs CALLing C Subprograms
7.1.6.5. C Main Programs CALLing OpenCOBOL Subprograms
7.1.7. Important Environment Variables
7.1.8. Locating Copybooks at Compilation Time
7.1.9. Using Compiler Configuration Files
7.2. Running OpenCOBOL Programs
7.2.1. Executing Programs Directly
7.2.2. Using the “cobcrun” Utility
7.2.3. Program Arguments
7.2.4. Important Environment Variables
7.3. Built-In Subroutines
7.3.1. “Call by Name” Routines
7.3.1.1. CALL “C$CHDIR” USING directory-path, result
7.3.1.2. CALL “C$COPY” USING src-file-path, dest-file-path, 0
7.3.1.3. CALL “C$DELETE” USING file-path, 0
7.3.1.4. CALL “C$FILEINFO” USING file-path, file-info
7.3.1.5. CALL “C$JUSTIFY” USING data-item, “justification-type”
7.3.1.6. CALL “C$MAKEDIR” USING dir-path
7.3.1.7. CALL “C$NARG” USING arg-count-result
7.3.1.8. CALL “C$PARAMSIZE” USING argument-number
7.3.1.9. CALL “C$SLEEP” USING seconds-to-sleep
7.3.1.10. CALL “C$TOLOWER” USING data-item, BY VALUE convert-length
7.3.1.11. CALL “C$TOUPPER” USING data-item, BY VALUE convert-length
7.3.1.12. CALL “CBL_AND” USING item-1, item-2, BY VALUE byte-length
7.3.1.13. CALL “CBL_CHANGE_DIR” USING directory-path
7.3.1.14. CALL “CBL_CHECK_FILE_EXIST” USING file-path, file-info
7.3.1.15. CALL “CBL_CLOSE_FILE” USING file-handle
7.3.1.16. CALL “CBL_COPY_FILE” USING src-file-path, dest-file-path
7.3.1.17. CALL “CBL_CREATE_DIR” USING dir-path
7.3.1.18. CALL “CBL_CREATE_FILE” USING file-path, 2, 0, 0, file-handle
7.3.1.19. CALL “CBL_DELETE_DIR” USING dir-path
7.3.1.20. CALL “CBL_DELETE_FILE” USING file-path
7.3.1.21. CALL “CBL_ERROR_PROC” USING function, program-pointer7.3.1.22. CALL “CBL_EXIT_PROC” USING function, program-pointer7.3.1.23. CALL “CBL_EQ” USING item-1, item-2, BY VALUE byte-length
7.3.1.24. CALL “CBL_FLUSH_FILE” USING file-handle

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

06FEB2009 Version

5

OpenCOBOL 1.1 Programmers Guide

Table of Contents

7.3.1.25. CALL “CBL_GET_CURRENT_DIR” USING BY VALUE 0, BY VALUE length, BY REFERENCE buffer
7.3.1.26. CALL “CBL_IMP” USING item-1, item-2, BY VALUE byte-length
7.3.1.27. CALL “CBL_NIMP” USING item-1, item-2, BY VALUE byte-length
7.3.1.28. CALL “CBL_NOR” USING item-1, item-2, BY VALUE byte-length
7.3.1.29. CALL “CBL_NOT” USING item-1, BY VALUE byte-length
7.3.1.30. CALL “CBL_OC_NANOSLEEP” USING nanoseconds-to-sleep
7.3.1.31. CALL “CBL_OPEN_FILE” file-path, access-mode, 0, 0, handle
7.3.1.32. CALL “CBL_OR” USING item-1, item-2, BY VALUE byte-length
7.3.1.33. CALL “CBL_READ_FILE” USING handle, offset, nbytes, flag, buffer
7.3.1.34. CALL “CBL_RENAME_FILE” USING old-file-path, new-file-path
7.3.1.35. CALL “CBL_TOLOWER” USING data-item, BY VALUE convert-length
7.3.1.36. CALL “CBL_TOUPPER” USING data-item, BY VALUE convert-length
7.3.1.37. CALL “CBL_WRITE_FILE” USING handle, offset, nbytes, 0, buffer
7.3.1.38. CALL “CBL_XOR” USING item-1, item-2, BY VALUE byte-length
7.3.1.39. CALL “SYSTEM” USING command
7.3.2. “Call by Number” Subroutines
7.3.2.1. CALL X”91” USING return-code, function-code, binary-variable-arg
7.3.2.2. CALL X”F4” USING byte, table
7.3.2.3. CALL X”F5” USING byte, table
7.3.2.4. Binary Truncation

7-22
7-23
7-23
7-23
7-24
7-24
7-24
7-24
7-25
7-25
7-25
7-26
7-26
7-26
7-26
7-27
7-27
7-28
7-28
7-29

8. SAMPLE PROGRAMS

8-1

8.1. FileStat-Msgs.cpy – File Status Values
8.2. COBDUMP – A Hex/Char Data Dump Subroutine
8.3. OCic – an OpenCOBOL Full-Screen Compiler Front-End
8.4. WINSYSTEM – Execute Windows Shell Commands (For Cygwin)

8-1
8-1
8-4
8-46

9. GLOSSARY OF TERMS

9-1

INDEX

I

GNU FREE DOCUMENTATION LICENSE

IX

FiguresFigure 1-1 - A Sample TUI Screen .................................................................................................................................. 1-10
Figure 1-2 - COPY Syntax ............................................................................................................................................... 1-12
Figure 1-3 - Figurative Constants ................................................................................................................................... 1-14
Figure 2-1 - General OpenCOBOL Program Format ......................................................................................................... 2-1
Figure 2-2 - General Format for Nested Source Programs .............................................................................................. 2-2
Figure 2-3 - General Format for Nested Source Functions .............................................................................................. 2-2
Figure 3-1 - IDENTIFICATION DIVISION Syntax ................................................................................................................ 3-1
Figure 4-1 - ENVIRONMENT DIVISION Syntax.................................................................................................................. 4-1
Figure 4-2 - CONFIGURATION SECTION Syntax ............................................................................................................... 4-1
Figure 4-3 - SOURCE-COMPUTER Paragraph Syntax ....................................................................................................... 4-1
Figure 4-4 - OBJECT-COMPUTER Paragraph Syntax......................................................................................................... 4-1
Figure 4-5 - REPOSITORY Paragraph Syntax .................................................................................................................... 4-2
Figure 4-6 - SPECIAL-NAMES Paragraph Syntax............................................................................................................... 4-3
Figure 4-7 - Locale Codes ................................................................................................................................................. 4-4
Figure 4-8 - Screen ACCEPT Key Codes ............................................................................................................................ 4-5
Figure 4-9 - INPUT-OUTPUT SECTION Syntax .................................................................................................................. 4-5
Figure 4-10 - FILE-CONTROL Paragraph Syntax ............................................................................................................... 4-6
Figure 4-11 - FILE-STATUS Values .................................................................................................................................... 4-7
Figure 4-12 - Additional FILE-CONTROL Syntax for SEQUENTIAL Files ............................................................................ 4-8
Figure 4-13 - Additional FILE-CONTROL Syntax for RELATIVE Files ................................................................................. 4-8
Figure 4-14 - Additional FILE-CONTROL Syntax for INDEXED Files .................................................................................. 4-9
Figure 4-15 - I-O-CONTROL Paragraph Syntax ............................................................................................................... 4-10
06FEB2009 Version

6

OpenCOBOL 1.1 Programmers Guide

Table of Contents

Figure 5-1 - General DATA DIVISION Format ................................................................................................................... 5-1
Figure 5-2 - FD Syntax ...................................................................................................................................................... 5-2
Figure 5-3- LINAGE-specified Page Structure .................................................................................................................. 5-3
Figure 5-4 - SD Syntax ...................................................................................................................................................... 5-3
Figure 5-5 - General Data Description Format ................................................................................................................ 5-4
Figure 5-6 - Data Class-Specification PICTURE Symbols (A/X/9) ...................................................................................... 5-5
Figure 5-7 - Numeric Option PICTURE Symbols (P/S/V) .................................................................................................. 5-6
Figure 5-8 - Sign-Encoding Characters ............................................................................................................................. 5-6
Figure 5-9 - Numeric Editing PICTURE Symbols ............................................................................................................... 5-7
Figure 5-10 - Summary of USAGE Specifications ........................................................................................................... 5-12
Figure 5-11 - Effect of the SYNCHRONIZED Clause ........................................................................................................ 5-14
Figure 5-12 - Level-88 Condition Name Description Syntax .......................................................................................... 5-15
Figure 5-13 - Level-78 Constant Description Syntax ...................................................................................................... 5-16
Figure 5-14 - SCREEN SECTION Data Item Description Syntax ...................................................................................... 5-17
Figure 5-15 - Screen Color Numbers.............................................................................................................................. 5-19
Figure 5-16 - LOWLIGHT / HIGHLIGHT Effect on Screen Colors ..................................................................................... 5-19
Figure 6-1 - Reference Modifier Syntax ........................................................................................................................... 6-2
Figure 6-2 – Unary - Operator Syntax .............................................................................................................................. 6-3
Figure 6-3 – Unary + Operator Syntax ............................................................................................................................. 6-3
Figure 6-4 - Exponentiation Operator Syntax .................................................................................................................. 6-3
Figure 6-5 - Exponentiation Operator Syntax .................................................................................................................. 6-3
Figure 6-6 - Division Operator Syntax .............................................................................................................................. 6-3
Figure 6-7 - Addition Operator Syntax............................................................................................................................. 6-4
Figure 6-8 - Subtraction Operator Syntax ........................................................................................................................ 6-4
Figure 6-9 - Class Condition Syntax ................................................................................................................................. 6-6
Figure 6-10 - Sign Condition Syntax ................................................................................................................................. 6-6
Figure 6-11 - Using Switch Conditions ............................................................................................................................. 6-7
Figure 6-12 - Relation Condition Syntax .......................................................................................................................... 6-8
Figure 6-13 - Combined Condition Syntax ....................................................................................................................... 6-8
Figure 6-14 - Negated Condition Syntax .......................................................................................................................... 6-9
Figure 6-15 - Special Registers ....................................................................................................................................... 6-21
Figure 6-16 - General PROCEDURE DIVISION Syntax ..................................................................................................... 6-24
Figure 6-17 - General DECLARATIVES Syntax ................................................................................................................. 6-25
Figure 6-18 - ACCEPT (Read from Console) Syntax ........................................................................................................ 6-26
Figure 6-19 - ACCEPT (Command Line Arguments) Syntax............................................................................................ 6-26
Figure 6-20 - ACCEPT (Environment Variable Values) Syntax ....................................................................................... 6-27
Figure 6-21 - ACCEPT (Retrieve Screen Data) Syntax..................................................................................................... 6-28
Figure 6-22 - ACCEPT (Retrieve Date/Time) Syntax ....................................................................................................... 6-29
Figure 6-23 - ACCEPT Options for DATE/TIME Retrieval ............................................................................................... 6-29
Figure 6-24 - ACCEPT (Retrieve Screen Size Data) Syntax ............................................................................................. 6-29
Figure 6-25 - ACCEPT Exception Handling ..................................................................................................................... 6-30
Figure 6-26 - ADD (TO) Syntax ....................................................................................................................................... 6-31
Figure 6-27 - A Sample Program Using ON SIZE ERROR ................................................................................................ 6-31
Figure 6-28 - ADD (GIVING) Syntax ................................................................................................................................ 6-32
Figure 6-29 - ADD (CORRESPONDING) Syntax ............................................................................................................... 6-32
Figure 6-30 - ALLOCATE Syntax...................................................................................................................................... 6-33
Figure 6-31 - CALL Syntax .............................................................................................................................................. 6-34
Figure 6-32 - CALL BY REFERENCE Can Sometimes have Unwanted Effects! ................................................................ 6-35
Figure 6-33 - CALL BY VALUE ......................................................................................................................................... 6-35
Figure 6-34 - CANCEL Syntax ......................................................................................................................................... 6-36
Figure 6-35 - CLOSE Syntax ............................................................................................................................................ 6-37
Figure 6-36 - COMMIT Syntax........................................................................................................................................ 6-38
Figure 6-37 - COMPUTE Syntax ..................................................................................................................................... 6-39
Figure 6-38 - CONTINUE Syntax ..................................................................................................................................... 6-40
Figure 6-39 - DELETE Syntax .......................................................................................................................................... 6-41
Figure 6-40 - DISPLAY (Upon Console) Syntax ............................................................................................................... 6-42
Figure 6-41 - DISPLAY (Access Command-line Arguments) Syntax................................................................................ 6-42
06FEB2009 Version

7

OpenCOBOL 1.1 Programmers Guide

Table of Contents

Figure 6-42 - DISPLAY (Access / Set Environment Variables) Syntax ............................................................................. 6-42
Figure 6-43 - DISPLAY (Screen Data) Syntax .................................................................................................................. 6-43
Figure 6-44 - Exception Handling (DISPLAY) Syntax....................................................................................................... 6-44
Figure 6-45 - DIVIDE INTO Syntax .................................................................................................................................. 6-45
Figure 6-46 - DIVIDE INTO GIVING Syntax ..................................................................................................................... 6-45
Figure 6-47 - DIVIDE BY GIVING Syntax ......................................................................................................................... 6-46
Figure 6-48 - DIVIDE INTO REMAINDER Syntax ............................................................................................................. 6-46
Figure 6-49 - DIVIDE BY REMAINDER Syntax ................................................................................................................. 6-47
Figure 6-50 - ENTRY Syntax............................................................................................................................................ 6-48
Figure 6-51 - EVALUATE Syntax ..................................................................................................................................... 6-49
Figure 6-52 - An EVALUATE Demo Program .................................................................................................................. 6-50
Figure 6-53 - EXIT Syntax ............................................................................................................................................... 6-51
Figure 6-54 - Using the EXIT Statement ......................................................................................................................... 6-51
Figure 6-55 - Using EXIT PARAGRAPH ............................................................................................................................ 6-51
Figure 6-56 - Using the EXIT PERFORM Statement ........................................................................................................ 6-51
Figure 6-57 - FREE Syntax .............................................................................................................................................. 6-53
Figure 6-58 - GENERATE Syntax ..................................................................................................................................... 6-54
Figure 6-59 - GOBACK Syntax ........................................................................................................................................ 6-55
Figure 6-60 - Simple GOTO Syntax................................................................................................................................. 6-56
Figure 6-61 - GOTO DEPENDING ON Syntax .................................................................................................................. 6-56
Figure 6-62 - GOTO DEPENDING ON vs IF vs EVALUATE................................................................................................ 6-56
Figure 6-63 - IF Syntax ................................................................................................................................................... 6-57
Figure 6-64 - INITIALIZE Syntax ...................................................................................................................................... 6-58
Figure 6-65 - INITIATE Syntax ........................................................................................................................................ 6-59
Figure 6-66 - INSPECT Syntax ......................................................................................................................................... 6-60
Figure 6-67 - An INSPECT TALLYING Example ................................................................................................................ 6-61
Figure 6-68 - MERGE Syntax .......................................................................................................................................... 6-63
Figure 6-69 - Simple MOVE Syntax ................................................................................................................................ 6-65
Figure 6-70 - MOVE CORRESPONDING Syntax .............................................................................................................. 6-65
Figure 6-71 - MULTIPLY BY Syntax ................................................................................................................................. 6-67
Figure 6-72 - MULTIPLY GIVING Syntax ......................................................................................................................... 6-67
Figure 6-73 - NEXT SENTENCE Syntax ............................................................................................................................ 6-68
Figure 6-74 - OPEN Syntax ............................................................................................................................................. 6-69
Figure 6-75 - Procedural PERFORM Syntax ................................................................................................................... 6-70
Figure 6-76 - Inline PERFORM Syntax ............................................................................................................................ 6-71
Figure 6-77 – READ (Sequential) Syntax ........................................................................................................................ 6-72
Figure 6-78 - READ (Random) Syntax ............................................................................................................................ 6-73
Figure 6-79 - RELEASE Syntax ........................................................................................................................................ 6-75
Figure 6-80 - RETURN Syntax ......................................................................................................................................... 6-76
Figure 6-81 - REWRITE Syntax ....................................................................................................................................... 6-77
Figure 6-82 - ROLLBACK Syntax ..................................................................................................................................... 6-78
Figure 6-83 - Sequential SEARCH Syntax ....................................................................................................................... 6-79
Figure 6-84 - Binary SEARCH (ALL) Syntax ..................................................................................................................... 6-80
Figure 6-85 - SET ENVIRONMENT Syntax....................................................................................................................... 6-82
Figure 6-86 - SET Program Pointer Syntax ..................................................................................................................... 6-82
Figure 6-87 - SET ADDRESS Syntax................................................................................................................................. 6-82
Figure 6-88 - SET Index Syntax ....................................................................................................................................... 6-83
Figure 6-89 - SET UP/DOWN Syntax .............................................................................................................................. 6-83
Figure 6-90 - SET Condition Name Syntax ..................................................................................................................... 6-83
Figure 6-91 - SET Switch Syntax ..................................................................................................................................... 6-84
Figure 6-92 - File-Based SORT Syntax ............................................................................................................................ 6-85
Figure 6-93 - Table SORT Syntax .................................................................................................................................... 6-87
Figure 6-94 - START Syntax ............................................................................................................................................ 6-88
Figure 6-95 - STOP Syntax .............................................................................................................................................. 6-90
Figure 6-96 - STRING Syntax .......................................................................................................................................... 6-91
Figure 6-97 - SUBTRACT FROM Syntax .......................................................................................................................... 6-92
Figure 6-98 - SUBTRACT GIVING Syntax ........................................................................................................................ 6-92
06FEB2009 Version

8

OpenCOBOL 1.1 Programmers Guide

Table of Contents

Figure 6-99 - SUBTRACT CORRESPONDING Syntax ........................................................................................................ 6-93
Figure 6-100 - SUPPRESS Syntax .................................................................................................................................... 6-94
Figure 6-101 - TERMINATE Syntax ................................................................................................................................. 6-95
Figure 6-102 - TRANSFORM Syntax ............................................................................................................................... 6-96
Figure 6-103 - The TRANSFORM Statement at Work .................................................................................................... 6-96
Figure 6-104 - UNLOCK Syntax ...................................................................................................................................... 6-97
Figure 6-105 - UNSTRING Syntax ................................................................................................................................... 6-98
Figure 6-106 - An UNSTRING Example ........................................................................................................................... 6-98
Figure 6-107 - WRITE Syntax ....................................................................................................................................... 6-100
Figure 7-1 - C/OpenCOBOL Data Type Matches .............................................................................................................. 7-4
Figure 7-2 - OpenCOBOL CALLing C ................................................................................................................................. 7-6
Figure 7-3 - C CALLing OpenCOBOL ................................................................................................................................. 7-7
Figure 7-4 - Compiler Environment Variables ................................................................................................................. 7-9
Figure 7-5 - Run-Time Environment Variables ............................................................................................................... 7-13
Figure 7-6 - A Binary Truncation Demo Program .......................................................................................................... 7-29
Figure 7-7 - A Non-Scientific Comparison of Numeric Data Item USAGE Performance ................................................ 7-31

06FEB2009 Version

9

OpenCOBOL 1.1 Programmers Guide

06FEB2009 Version

Table of Contents

10OpenCOBOL 1.1 Programmers Guide

Introduction

1. Introduction
1.1. What is OpenCOBOL?
This document describes the syntax, semantics and usage of the COBOL programming language as implemented by
the current version of OpenCOBOL.
OpenCOBOL is an open-source COBOL compiler and runtime environment. The OpenCOBOL compiler generates C
code which is automatically compiled and linked. While originally developed for UNIX operating systems, OpenCOBOL
can also be built for MacOS computers or Windows computers utilizing the UNIX-emulation features of such tools as
1
Cygwin and MinGW . It has also been built as a truly native Windows application utilizing Microsoft’s freelydownloadable Visual Studio Express package to provide the C compiler and linker/loader.
The principal developers of OpenCOBOL are Keisuke Nishida and Roger While. They may be contacted at the
OpenCOBOL website - www.opencobol.org.
This document was intended to serve as a full-function reference and user’s guide suitable for both those readerslearning COBOL for the first time as well as those already familiar with some dialect of the COBOL language. The
author of this document is Gary Cutler, who may be reached via postings at the www.opencobol.org forum, or byemail at CutlerGL@gmail.com.

1.2. Additional References and Documents
For those wishing to learn COBOL for the first time, I can strongly recommend the following resources.
If you like to hold a book in your hands, I strongly recommend “Murach’s Structured COBOL”, by Mike Murach, Anne
Prince and Raul Menendez (2000) - ISBN 9781890774059. Mike Murach and his various writing partners have been
writing outstanding COBOL textbooks for several decades, and this text is no exception. It’s an excellent book for
those familiar with the concepts of programming in other languages, but unfamiliar with COBOL.
Would you prefer a web-based tutorial? Try the University of Limerick (Ireland) COBOL web site http://www.csis.ul.ie/cobol/.

1.3. Introducing COBOL
If you already know a programming language, and that language isn’t COBOL, chances are that language is Java, C or
C++. You will find COBOL a much different programming language than those – sometimes those differences are agood thing and sometimes they aren’t. The thing to remember about COBOL is this – it was designed to solve businessproblems. It was designed to do that in the 1950s.
COBOL was the first programming language to become standardized such that a COBOL program written on computer“A” made by company “X” would be able to be compiled and executed on computer “B” made by company “Y”. This
may not seem like such a big deal today, but it was a radical departure from all programming languages that came
before it and even many that came after it.
The name “COBOL” actually says it all – COBOL is an acronym that stands for “COmmon Business Oriented Language”.
Note the fact that the word “common” comes before all others. The word “business” is a close second. Therein lies
the key to COBOL’s success.

1

The MinGW approach is a personal favorite with the author of this manual because it creates an OpenCOBOL
compiler and runtime that require only a single MinGW DLL to be available to OpenCOBOL tools and user
programs. That DLL is freely distributable under the terms of the GNU General Public License. A MinGW build of
OpenCOBOL fits easily on and runs from a 128MB flash drive with no need to install any software onto the
Windows computer that will be using it. Some functionality of the language, dealing with the sharing of files
between concurrently executing OpenCOBOL programs and record locking on certain types of files, is sacrificed
however.

06FEB2009 Version

Page 1-1

OpenCOBOL 1.1 Programmers Guide

Introduction

1.3.1. “I Heard COBOL is a Dead Language!”
Phoenician is a dead language. Mayan is a dead language. Latin is a dead language. What makes these languages
dead is the fact that no one speaks them anymore. COBOL is NOT a dead language, and despite pontifications thatcome down to us from the ivory towers of academia, it isn’t even on life support.
What made those other languages die is the fact that they became obsolete. As the peoples that spoke them wereoverrun or superseded by other populations that eventually replaced them, no one saw any need to speak theirlanguages. There was no good reason to keep on speaking a language whose creators had become irrelevant tohistory.
COBOL is different. Certainly, there were more people that “spoke” COBOL back in the 1980s than there are now.
Remember, however, the second word in COBOL’s acronym – business. Businesses are complex social and economic
organisms that exist for but a single purpose – to make money. One of the approaches businesses take to satisfy that
all-important survival trait is that they want to avoid expenses.
This avoidance of expense turns out to have been key to the survival of COBOL because those programmers of the
1980s (give or take a decade) were very busy programmers. Estimates are that as many as a several hundred billion
lines of COBOL code were written for businesses world-wide. Because of the first word in COBOL’s name (“Common”),
as businesses replaced their older, slower and less-reliable computer systems with newer, faster and more-reliable
ones, they found that the massive investment they had in their COBOL software inventory paid dividends by remaining
functional on those new systems - many times with no changes needed whatsoever!
Unwilling to endorse change merely for the sake of change, businesses replaced these billions and billions of lines of
COBOL code only when absolutely necessary and only when financially justifiable. That justification appeared to havethcome as the 20 century was nearing the end.
Written long before the end of the century was near, many of those COBOL applications used 2-digit years instead offour digit years because, when the programs were written, computer storage of any kind was expensive. Why should
millions and millions of bytes of storage be wasted by all those “19” sequences when the software can simply assume
them? Since their software would suddenly think the current year was “1900” after the stroke of midnight, Decemberst
31 1999, businesses knew they were going to have to do something about the “Y2K” (programmer “geek speak” for“Year 2000”) problem.
At last! Y2K was going to be the massive asteroid strike that finally killed off the COBOL dinosaur.
Unfortunately for those seeking the extinction of COBOL, that proved to be wishful thinking.
Always concerned with the bottom line, businesses actually analyzed the problems with their programs. Many
applications were replaced with newer and “better” versions that used more appropriate (translation: more politicallycorrect) languages and computer systems. BUT … many applications were not replaced. These were the absolutely
essential applications whose replacement would cripple the business if everything didn’t go absolutely perfectly.
These COBOL applications were modified to use 4-digit years instead of 2-digit ones. At the same time, many of themreceived cosmetic “face lifts” to make their computer/human interfaces more acceptable, frequently with the help of
modules developed in the newer languages.
The result is that even today, after the Y2K “extinction event”, there are, by industry estimates, over 40 billion lines ofst
COBOL code still running the businesses of the 21 century. A fact that is disturbing to some is that – just as tiny little
furry mammals evolved to cope with the original “extinction event” holocaust – COBOL has also evolved into a leaner
and meaner “animal” capable of competing in niches and providing services unthought-of back in 1968. That fact isconfirmed by the fact that those lines of COBOL code being tracked by industry analysts are actually growing at therate of about 4 billion a year.
Evolution, you see, is in COBOLs DNA. Over time, COBOL evolved in form and function, first via work done by theAmerican National Standards Institute (ANSI) and eventually through the efforts of the International Standards
Organization (ISO).

06FEB2009 Version

Page 1-2

OpenCOBOL 1.1 Programmers Guide

Introduction
2

The first widely-adopted standard for COBOL was published by ANSI in 1968 . Named the ANS68 standard, thisversion of COBOL was originally standardized for use primarily as the business programming tool of the US Defense
Department; it quickly was adopted by other Government agencies and private businesses alike.
Subsequent standards published in 1974 and 1985 (ANS74 and ANS85, respectively) added new features and evolved
the language toward adoption of the programmer-productivity tool of the time – “Structured Programming”.
st

As the 21 century dawned, programming had moved out of the board room and into the Game Room, the Living
Room and even the Kitchen; as computers became more and more inexpensive they appeared in games,
entertainment devices and appliances. Even the automobile became home to computers galore. These computersneed software, and that software is written in the so-called “modern” languages.
Combined with Y2K, these trends became the impetus for COBOL to evolve even newer features and capabilities. The
3
COBOL2002 standard introduced object-oriented features and syntax that make the language more programmerfriendly to those trained by today’s programming curricula. The COBOL20xx standard, currently under development,
carries the evolution forward to the point where a COBOL20xx implementation will be fully as “modern” as any otherprogramming language.
Through all this evolution, however, care was taken with each new standard to protect the investment businesses (oranyone, for that matter) had in COBOL software. Generally, a new COBOL standard – once implemented and adopted
by a business - required minimal, if any, changes to upgrade existing applications. When changes were necessary,
those changes could frequently be made using tools that mechanically upgraded entire libraries of source code withlittle or no need for human intervention.
The OpenCOBOL implementation of the COBOL language supports virtually the entire ANS85 standard as well as somesignificant features of the COBOL2002 standard, although the truly object-oriented features are not there (yet).

1.3.2. Programmer Productivity – The “Holy Grail”
Throughout the history of computer programming, the search for new ways to improve of the productivity of
programmers has been the all-important consideration. Sometimes this search has taken the form of introducing newfeatures in programming languages, or even new languages altogether, and sometimes it has evolved new ways ofusing the existing languages. Other than hobbyists, programming is an activity performed for money. Businesses
abhor spending anything more than is absolutely necessary. Even government agencies try to spend as little money4
on projects as is absolutely necessary .
The amount of programming necessary to accomplish a given task – including rework needed by any errors foundduring testing (testing: “that time during which an application is actually in production use attempting to serve thepurpose for which it was designed” ) is the measure of programmer productivity. Anything that reduces that effort
will therefore reduce the time spent in such activities therefore reducing the expense of same. When the expense of
programming is reduced, programmer productivity is increased.
While many technological and procedural developments have made evolutionary improvements to programmer
productivity, each of the following has been responsible for revolutionary improvements:
The development of so-called “higher-level” programming languages that enable a programmer to specify ina single statement of the language an action that would have required many more separate statements in aprior programming language. The standardization of such languages, making them usable on a wide variety

2

To that point, in 1968 the US Government made it a requirement that any computer system sold to them must run
a version of COBOL that adhered to the ANSI68 standard. The requirement that computers sold to the US
Government had to support the current COBOL standard remained for many, many years.

3“Popular” names for COBOL standards no longer include an organization’s name, and now use Y2K-compliant 4digit years.

4

This is a religious issue because it is an assertion that – sadly – must be taken purely on faith; there is,unfortunately, all too little real-world evidence to support it. It makes sense, so one can only hope it is true.

06FEB2009 Version

Page 1-3

OpenCOBOL 1.1 Programmers Guide

Introductionof computers and operating systems, is a COBOL was a pioneering development in this area, being one of thefirst higher-level languages.
The establishment of programming techniques that make programs easier to read and therefore easier tounderstand. Not only do such techniques reduce the amount of rework necessary simply to make a program
work as designed, but they also reduce the amount of time a programmer needs to study an existing programin order how to best adapt it to changing business requirements. The foremost development in this area wasstructured programming. Introduced in the late 1970s, this approach to programming spawned new
programming languages (PASCAL, ALGOL, PL/1) designed around it. With the ANSI85 standard, COBOL
embraced the principles espoused by structured programming mavens as well as any of the languages
designed strictly around it.
The establishment of programming techniques AND the introduction of programming language capabilities tofacilitate the reusability of program code. Anything that supports code reusability can have a profound
impact to the amount of time it takes to develop new applications or to make significant changes to existing
ones. In recent years, object-oriented programming has been the industry “poster child” for code reusability.
By enabling program logic and the data structures that logic manipulates encapsulated into easily stored andretrieved (and therefore “reusable”) modules called classes, the object-oriented languages such as Java, C++
and C# have become the favorites of academia. Since students are being trained in these technologies andonly these, by and large, it’s no surprise that – today - object-oriented programming languages are thedarlings of the industry.
The reality is, however, that good programmers have been practicing code reusability for more than a halfcentury. Up until recently, COBOL programmers have had some of the best code reusability tools available they’ve been doing it with copybooks (section 1.7) and subroutines (sections 6.7, 7.1.4 and 7.1.5) rather thanclasses, methods and attributes but the net results have been similar. With the COBOL2002 standard and theimprovements made by the COBOL20xx standard, the playing field is leveled in this regard.

1.3.3. Notable COBOL/OpenCOBOL Features
1.3.3.1. Basic Program Readability
When it first was developed, COBOL’s easily-readable syntax made it profoundly different to anything that had been
seen before. For the first time, it was possible to specify logic in a manner that was – at least to some extent –comprehensible even to non-programmers. Take for example, the following code written in FORTRAN – a language
developed only a year before COBOL:
E = P * Q
I = I + E

With its original limitation on the length of variable names (one letter or a letter followed by a number), and its use ofalgebraic notation to express actions being taken, FORTRAN wasn’t a particularly readable language, even byprogrammers. Compare this with the equivalent COBOL code:
MULTIPLY PRICE BY QUANTITY GIVING EXTENDED-AMOUNTADD EXTENDED-AMOUNT TO INVOICE-TOTAL

Clearly, even a non-programmer could at least conceptually understand what was going on! Over time, languages like
FORTRAN evolved more robust variable names, but FORTRAN was never as readable as COBOL.
The inherent readability of COBOL code was a blessing at first, but eventually it became considered as a curse. As
more and more people became at least informed about programming if not downright skilled, the syntax of COBOL
became one of the reasons the ivory-tower types wanted to see it eradicated.
I would MUCH rather be handed an assignment to make significant changes to a COBOL program about which I know
nothing than to be asked to do the same with a C, C++ or Java program.
Those that argue that it is too boring/wasteful/time-consuming/insulting (choose the word you prefer) to have tocode a COBOL program “from scratch” are clearly ignorant of the following facts:

06FEB2009 Version

Page 1-4

OpenCOBOL 1.1 Programmers Guide

Introduction

Many systems have program-development tools available to ease the task of coding programs; those toolsthat concentrate on COBOL are capable of providing templates for much of the “overhead” verbiage of any
program
Good programmers have – for decades – maintained their own skeleton “template” programs for a variety of
program types; simply load a template into a text edit and you’ve got a good start to the program
Legend has it that there’s actually only ever been ONE program ever written in COBOL – all programs everwritten after that sprang from that one!

1.3.3.2. COBOL Program Structure
COBOL programs are structured into four major areas of coding, each with it’s own purpose. These four areas are
known as DIVISIONS.
Each DIVISION may consist of a variety of SECTIONs and each SECTION consists of one or more PARAGRAPHs. A
PARARAPH consists of SENTENCEs, each of which consists of one or more STATEMENTs.
This hierarchical structure of program components standardizes the composition of all COBOL programs. Much of thismanual describes the various divisions, sections, paragraphs and statements that may comprise any COBOL program.
The four divisions, and their function, are described in section 2. Each division has its own chapter (sections 3, 4, 5 and6) and each of those chapters will describe the sections, et. al. available to programmers in each of those divisions.

1.3.3.3. Copybooks
A “copybook” is a segment of program code may be utilized by multiple programs simply by having that program use
the COPY statement (section 1.7) to import that code into the program. This code may define files, data structures orprocedural code.
Today’s current programming languages have a statement (usually, this statement is named “include” or “#include”)
that performs this same function. What makes the COBOL copybook feature different than the “include” facility incurrent languages, however, is the fact that the COBOL COPY statement can edit the imported source code as it isbeing copied. This capability enables copybook libraries extremely valuable to making code reusable.

1.3.3.4. Structured Data
COBOL introduced the concept of structured data back in the 1960s. Structured data is data which may be accessed
as a single item or may be broken down into sub-items based upon their character position of occurrence within the
structure. These structures called group items (page 9-2). At the bottom of any structure are data items that aren’t
broken down into sub-items. COBOL refers to these as elementary items (page 9-1).

1.3.3.5. Files
One of COBOLs main strengths is the wide variety of files it is capable of accessing. OpenCOBOL, like other COBOL
implementations, needs to have the structure of any files that it will be reading and/or writing described to it. The
highest-level characteristic of a file’s structure is defined by specifying the ORGANIZATION (section 4.2.1) of the file, as
follows:
ORGANIZATION IS
LINE SEQUENTIAL

These are files with the simplest of all internal structures. Their contents are structured simply
as a series of data records, each terminated by a special end-of-record delimiter character. An
ASCII line-feed character (hexadecimal 0A) is the end-of-record delimiter character used by any
UNIX or pseudo-UNIX (MinGW, Cygwin, MacOS) OpenCOBOL build. A truly native Windows
build would use a carriage-return, line-feed (hexadecimal 0D0A) sequence.
Records in this type of file need not be the same length.
Records must be read from or written to these files in a purely sequential manner. The only

06FEB2009 Version

Page 1-5

OpenCOBOL 1.1 Programmers Guide

Introduction

way to read (or write) record number 100 would be to have read (or written) records number 1
thru 99 first.
When the file is written by an OpenCOBOL program, the delimiter sequence will be
automatically appended to each data record as it is written to the file.
When the file is read, the OpenCOBOL runtime system will strip the trailing delimiter sequence
from each record and pad the data (to the right) with SPACES, if necessary, if the data just readis shorter than the area described for data records in the program. If the data is too long, it willbe truncated and the excess will be lost.
These files should not be defined to contain any exact binary data fields because the contentsof those fields could inadvertently have the end-of-record sequence as part of their values –this would confuse the runtime system when reading the file, and it would interpret that value
as an actual end-of-record sequence.
ORGANIZATION IS
RECORD BINARYSEQUENTIAL

These files also have a simple internal structure. Their contents are structured simply as aseries of fixed-length data records with no special end-of-record delimiter.
Records in this type of file are all the same physical length. If variable-length logical records aredefined to the program (section 5.3), the space occupied by each physical record in the file will
occupy the maximum possible space.
Records must be read from or written to these files in a purely sequential manner. The only
way to read (or write) record number 100 would be to have read (or written) records number 1
thru 99 first.
When the file is written by an OpenCOBOL program, no delimiter sequence is appended to thedata.
When the file is read, the data is transferred into the program exactly as it exists in the file. In
the event that a short record is read as the very last record, that record will be SPACE padded.
Care must be taken that programs reading such a file describe records whose length is exactly
the same as that used by the programs that created the file. For example, the following shows
the contents of a RECORD BINARY SEQUENTIAL file created by a program that wrote five 6character records to it. The “A”, “B”, … values and the background colors reflect the records
that were written to the file:
AAAAAABBBBBBCCCCCCDDDDDDEEEEEE
Now, assume that another program reads this file, but described 10-character records rather
than 6. Here are the records that program will read:
AAAAAABBBBBBCCCCCCDD
DDDDEEEEEE
There may be times where this is exactly what you were looking for. More often than not,however, this is not desirable behavior. Suggestion: use a copybook to describe the record
layouts of any file; this guarantees that multiple programs accessing that file will “see” thesame record sizes and layouts.
These files can contain exact binary data fields. The contents of record fields are irrelevant to
the reading process as there is no end-of-record delimiter.

ORGANIZATION IS
RELATIVE

The contents of these files consist of a series of fixed-length data records prefixed with a fourbyte USAGE COMP-5 (Figure 5-10) record header. The record header contains the length of thedata, in bytes. The byte-count does not include the four-byte record header.
Records in this type of file are all the same physical length. If variable-length logical records aredefined to the program (section 5.3), the space occupied by each physical record in the file will
occupy the maximum possible space.

06FEB2009 Version

Page 1-6

OpenCOBOL 1.1 Programmers Guide

Introduction

This file organization was defined to accommodate either sequential or random processing.
With a RELATIVE file, it is possible to read or write record 100 directly, without having to havefirst read or written records 1-99. The OpenCOBOL runtime system uses the program-defined
maximum record size to calculate a relative byte position in the file where the record header
and data begin, and then transfers the necessary data to or from the program.
When the file is written by an OpenCOBOL program, no delimiter sequence is appended to thedata, but a record-length field is added to the beginning of each physical record.
When the file is read, the data is transferred into the program exactly as it exists in the file.
Care must be taken that programs reading such a file describe records whose length is exactly
the same as that used by the programs that created the file. It won’t be a pretty site when the
OpenCOBOL runtime library ends up interpreting a four-byte ASCII character string as a record
length when it transfers data from the file into the program!
Suggestion: use a copybook to describe the record layouts of any file; this guarantees thatmultiple programs accessing that file will “see” the same record sizes and layouts.
These files can contain exact binary data fields. The contents of record fields are irrelevant to
the reading process as there is no end-of-record delimiter.
ORGANIZATION IS
INDEXED

This is the most advanced file structure available to OpenCOBOL programs. It’s not possible todescribe the physical structure of such files because that structure will vary depending uponwhich advanced file-management facility was included into the OpenCOBOL build you will beusing (Berkeley Database [BDB], VBISAM, etc.). We will – instead – discuss the logical structureof the file.
There will be multiple structures stored for an INDEXED file. The first will be a data component,
which may be thought of as being similar to the internal structure of a RELATIVE file. Data
records may not, however, be directly accessed by their record number as would be the casewith a RELATIVE file, nor may they be processed sequentially by their physical sequence in the
file.
The remaining structures will be one or more index components. An index component is a data
structure that (somehow) enables the contents of a field, called a primary key, within each data
record (a customer number, an employee number, a product code, a name, etc.) to beconverted to a record number so that the data record for any given primary key value can bedirectly read, written and/or deleted. Additionally, the index data structure is defined in such amanner as to allow the file to be processed sequentially, record-by-record, in ascending
sequence of the primary key field values. Whether this index structure exists as a binarysearchable tree structure (btree), an elaborate hash structure or something else is pretty much
irrelevant to the programmer – the behavior of the structure will be as it was just described.
The runtime system will not allow two records to be written to an indexed file with the same
primary key value.
The capability exists for an additional field to be defined as what is known as an alternate key.
Alternate key fields behave just like primary keys, allowing both direct and sequential access torecord data based upon the alternate key field values, with one exception. That exception is
the fact that alternate keys may be allowed to have duplicate values, depending upon how thealternate key field is described to the OpenCOBOL compiler (section 4.2.1.3).
There may be any number of alternate keys, but each key field comes with a disk space penalty
as well as an execution time penalty. As the number of alternate key fields increases, it willtake longer and longer to write and/or modify records in the file.
These files can contain exact binary data fields. The contents of record fields are irrelevant to
the reading process as there is no end-of-record delimiter.

All files are initially described to an OpenCOBOL program using a SELECT statement (section 4.2.1) coded in the FILECONTROL paragraph of the INPUT-OUTPUT SECTION of the ENVIRONMENT DIVISION. In addition to defining a name
06FEB2009 Version

Page 1-7

OpenCOBOL 1.1 Programmers Guide

Introduction

by which the file will be referenced within the program, the SELECT statement will specify the name and path by which
the file will be known to the operating system along with its ORGANIZATION, locking (section 6.1.9.2) and sharing(section 6.1.9.1) attributes.
A file description (section 5.1) in the FILE SECTION of the WORKING-STORAGE SECTION of the DATA DIVISION willdefine the structure of records within the file, including whether or not variable-length records are possible and – if so– what the minimum and maximum length might be. In addition, the file description entry can specify file I/O block
sizes.

1.3.3.6. Table Handling
Other programming languages have arrays, COBOL has tables. They’re basically the same thing. What makes COBOL
tables special are two special statements that exist in the COBOL language – SEARCH (section 6.38.1) and SEARCH ALL(section 6.38.2).
The first can search a table sequentially, stopping only when either a table entry matching one of any number ofsearch conditions is found, or when all table entries have been checked against the search criteria and none matchedany of those criteria.
The second can perform an extremely fast search against a table sorted by and searched against a “key” fieldcontained in each table entry. The algorithm used for such a search is a binary search (also known as a half-interval
search). This algorithm ensures that only a small number of entries in the table need to be checked in order to find adesired entry or to determine that the desired entry doesn’t exist in the table. The larger the table, the more effective
this search becomes. For example, a table containing 32,768 entries will be able to locate a particular entry or will
determine the entry doesn’t exist by looking at no more than fifteen (15) entries! The algorithm is explained in detailin the SEARCH ALL documentation (section 6.38.2).

1.3.3.7. Sorting and Merging Data
The COBOL language includes a powerful SORT statement (section 6.40.1) that can sort large amounts of dataaccording to arbitrarily complex key structures. This data may originate from within the program or may be containedin one or more external files. The sorted data may be written automatically to one or more output files or may beprocessed, record-by-record in the sorted sequence.
A special form of the SORT statement (section 6.40.2) also exists just to sort the data that resides in a table. This isparticularly useful if you wish to use SEARCH ALL against the table.
A companion statement – MERGE (section 6.27) – can combine the contents of multiple files together, provided thosefiles are all sorted in a similar manner according to the same key structure(s). The resulting output will consist of thecontents of all of the input files, merged together and sequenced according to the common key structure(s). The
output of a MERGE may be written automatically to one or more output files or may be processed internally by the
program.

1.3.3.8. String Manipulation
There have been programming languages designed specifically for the processing of text strings, and there have been
programming languages designed for the sole purpose of performing high-powered numerical computations. Most
programming languages fall somewhere in the middle, between these two extremes. COBOL is no exception,although it does include some very powerful string manipulation capabilities; OpenCOBOL actually has even more
string-manipulation capabilities than many other COBOL implementations. The following chart illustrates thecapabilities of OpenCOBOL with regard to strings:
Capability
Concatenate two or more strings
Conversion of a numeric time or date to aformatted character string
06FEB2009 Version

OpenCOBOL Feature Supporting that Capability
CONCATENATE Intrinsic Function (section 6.1.7.9)
STRING Statement (section 6.43)
LOCALE-TIME or LOCALE-DATE Intrinsic Functions (sections 6.1.7.31 and6.1.7.30), respectively
Page 1-8

OpenCOBOL 1.1 Programmers Guide
Capability
Convert a binary value to its corresponding
character in the program’s characterset

Convert a character string to lower-caseConvert a character string to upper-caseConvert a character to its numeric value inthe program’s characterset

Count occurrences of substrings in a larger
stringDecode a formatted numeric string back to
a numeric value (for example, decode“$12,342.19-“ to a -12342.19 value)
Determine the length of a string or dataitem capable of storing strings
Extract a substring of a string based on its
starting character position and length
Format a numeric item for output, including
thousands-separators (“,” in the USA),currency symbols (“$” in the USA), decimal
points, credit/debit symbols, leading or
trailing sign characters
Justification (Left, Right or Centered) of astring field
Monoalphabetic substitution of one ormore characters in a string with different
characters
Parse a string, breaking it up into substrings
based upon one or more delimiting
character sequences; these delimiters may
be single characters, multiple-character
strings or multiple consecutive occurrencesof either
Removal of leading or trailing spaces from astringSubstitution of a single substring withanother of the same length, based upon thesubstrings starting character position andlengthSubstitution of one or more substrings in astring with replacement substrings of thesame length, regardless of where theyoccur
Substitution of one or more substrings in astring with replacement substrings of a
06FEB2009 Version

Introduction

OpenCOBOL Feature Supporting that Capability
CHAR Intrinsic Function (section 6.1.7.7); add 1 to argument before
invoking the function; The description of the CHAR function shows atechnique that utilizes the MOVE statement that will accomplish thesame thing without the need of adding 1 to the numeric argument
value first
LOWER-CASE Intrinsic Function (section 6.1.7.35)
C$TOLOWER Built-in Subroutine (section 7.3.1.10)
CBL_TOLOWER Built-in Subroutine (section 7.3.1.35)
UPPER-CASE Intrinsic Function (section 6.1.7.67)
C$TOUPPER Built-in Subroutine (section 7.3.1.11)
CBL_TOUPPER Built-in Subroutine (section 7.3.1.36)
ORD Intrinsic Function (section 6.1.7); subtract 1 from the result; The
description of the ORD function shows a technique that utilizes the
MOVE statement that will accomplish the same thing without the needof adding 1 to the numeric argument value first
INSPECT Statement with TALLYING Option (section 6.26)
NUMVAL and NUMVAL-C Intrinsic Functions (sections 6.1.7.42 and6.1.7.43)
LENGTH or BYTE-LENGTH Intrinsic Functions (sections 6.1.7.29 and6.1.7.6)
MOVE Statement (section 6.28.1) with a reference modifier on the“sending” field
MOVE Statement (section 6.28) with picture-symbol editing applied to
the receiving field (section 5.3)

C$JUSTIFY built-in subroutine (section 7.3.1.5)
INSPECT Statement with CONVERTING Option (section 6.26)
TRANSFORM Statement (section 6.47)
SUBSTITUTE and SUBSTITUTE-CASE Intrinsic Functions (sections
6.1.7.60 and 6.1.7.61)
UNSTRING Statement (section 6.49)

TRIM Intrinsic Function (section 6.1.7.66)
MOVE Statement (section 6.28.1) with a reference modifier on the“receiving” field

INSPECT Statement with REPLACING Option (section 6.26)
SUBSTITUTE and SUBSTITUTE-CASE Intrinsic Functions (sections
6.1.7.60 and 6.1.7.61)
SUBSTITUTE and SUBSTITUTE-CASE Intrinsic Functions (sections
6.1.7.60 and 6.1.7.61)
Page 1-9

OpenCOBOL 1.1 Programmers Guide
Capability
different length, regardless of where theyoccur

Introduction
OpenCOBOL Feature Supporting that Capability

1.3.3.9. Textual-User Interface (TUI) Features
The COBOL2002 standard formalizes extensions to the COBOL language that allow for the definition and processing oftext-based screens. OpenCOBOL implements virtually all the screen-handling features described by COBOL2002.
Here is an example of such a screen as it might appear in the console window of a Windows computer:
Figure 1-1 - A Sample TUI Screen

5

Screens such as this are defined in the SCREEN SECTION of the DATA DIVISION (section 5.6). Once defined, screens reused at run-time via the ACCEPT (section 6.4.4) and DISPLAY (section 6.14.4) statements.
The COBOL2002 standard only covers textual-user interface (TUI) screens and not the more-advanced graphical-userinterface (GUI) screen design and processing capabilities built into most modern operating systems. There aresubroutine-based packages available that can do full GUI development, but none are open-source.

1.4. Syntax Description Conventions
Syntax of the OpenCOBOL language will be described in this manual with conventions familiar to COBOL programmers.
The following is a description of those syntactical-description techniques:
UPPERCASE

COBOL language keywords and implementation-dependent names (the so-called “reserved
words” of the COBOL language) will appear in uppercase.

UNDERLINING

reserved words that are underlined are required in whatever syntactical context they are
shown. If a reserved word is NOT underlined, it is optional and it’s presence or absence has
no effect on the program.

lowercase

Generic terms representing substitutable arguments will be shown in lowercase.

5

This screen comes from the program named OCic – a full-screen front-end to the OpenCOBOL compiler – thesourcs code of which is included as a sample in this manual. See section 8.3 for the listing of the program.

06FEB2009 Version

Page 1-10

OpenCOBOL 1.1 Programmers Guide

Introduction[ brackets ]Square brackets are used to enclose optional clauses. Any clauses not enclosed in square
brackets are mandatory.

choice-1 | choice-2

Simple choices may be indicated with a vertical bar separating them. Although not typicallyused in COBOL syntactical diagrams, this convention is an effective alternative that may be
used when square brackets would make a syntax diagram too complicated.

{ braces }Braces are used to enclose alternatives. Exactly one of the alternatives contained within
the braces must be selected.

{| selector |}Choice indicators are used to enclose alternatives where one or more of the enclosed
selections may be selected.

…

A three-dot sequence (called an “ellipsis”) may appear following brackets, braces, selectors
or lowercase entries to indicate that the syntax element preceding the ellipsis may occur
multiple times.

Shaded Areas

Shaded areas are used to highlight syntax elements that are recognized by the OpenCOBOL
compiler but will either have no effect on the generated code or will be rejected as being
unsupported. Such elements are either present in the OpenCOBOL language to facilitate
the porting of programs from other COBOL environments, reflect syntax elements that are
not yet fully implemented or syntax elements that have become obsolete.

1.5. Source Program Format
Traditional COBOL program source format allows programs to be coded using 80-character (maximum) lines with afixed format. As of the ANSI 2002 standard, a free-format source code format is defined where source code lines canbe up to 256 characters long with no fixed meanings assigned to specific column ranges.
OpenCOBOL provides the following four methods for specifying the format of source code input files:-fixedThis OpenCOBOL compiler switch specifies that all source input will be in
traditional (80-column) fixed format. THIS IS THE DEFAULT MODE.

-free

This OpenCOBOL compiler switch specifies that all source input will be in ANSI2002
free (256 column) format.

>>SOURCE FORMAT IS FREE

This source line, when encountered by the OpenCOBOL compiler, will switch thecompiler’s expectations into free format mode. The “>>” characters MUST begin incolumn 8 or beyond. Directives such as this and the next one may be used toswitch the compiler back and forth between free and fixed mode at will.

>>SOURCE FORMAT IS FIXEDThis source line, when encountered by the OpenCOBOL compiler, will switch thecompiler’s expectations into fixed format mode. Directives such as this and theprior one may be used to switch the compiler back and forth between free andfixed mode at will.

The following are special directives or characters that may be used in OpenCOBOL programs to signify various things.
“*” in column 7

Signifies the source line is a comment. This is valid only when in FIXED mode.

“D” in column 7

Signifies the source line is a valid OpenCOBOL statement that will be treated as a comment
unless the “–fdebugging-line” switch is specified to the OpenCOBOL compiler (in that
instance, the lines will be compiled). This is valid only when in FIXED mode.

“*>” in any column

Denotes the remainder of the source line is a comment. This may be used in either FREE or
FIXED mode, but if it is used in FIXED mode, the “*” should be in column 7 or beyond.

“>>D” in any column

Signifies the source line is a valid OpenCOBOL statement that will be treated as a comment
unless the “-fdebugging-line” switch is specified to the OpenCOBOL compiler (in that
instance, the lines will be compiled). This is valid when in FIXED or FREE mode, and must be
the first non-blank sequence on the source line. In FREE mode, this sequence may begin inany column. In FIXED mode, this sequence must begin in column 8 or beyond.

1.6. Use of Commas and Semicolons
06FEB2009 Version

Page 1-11

OpenCOBOL 1.1 Programmers Guide

Introduction

A comma character (“,”) or a semicolon (“;”) may be inserted into an OpenCOBOL program to improve readability at
any spot where white space would be legal (except, of course, within alphanumeric literals). These characters arealways optional. COBOL standards require that commas be followed by at least one space, when they’re used. Manymodern COBOL compilers (OpenCOBOL included) relax this rule, allowing the space to be omitted in most instances.
This can cause “confusion” to the compiler if the DECIMAL POINT IS COMMA clause is used (see section 4.1.4).
The following statement, which calls a subroutine passing it two arguments (the numeric constants 1 and 2):
CALL “SUBROUTINE” USING 1,2

would – with DECIMAL POINT IS COMMA – actually be interpreted as a subroutine call with ONE arguments (the datanon-integer numeric constant 1.2).
If you don’t already have it – develop the habit of coding a space after a comma used as punctuation! As analternative, consider using a semicolon as there is no possibility for “confusion”.

1.7. Using COPY
Figure 1-2 - COPY Syntax

COPY copybook-name

REPLACING== pseudo-text-1 ==identifier-1
literal-1
word-1BY== pseudo-text-2 ==identifier-2
literal-2
word-2...

.

COPY statements are used toimport copybooks (section
1.3.3.3) into a program.

OpenCOBOL completely supports the use of copybooks. These are separate source files containing ANY COBOLSYNTAX WHATSOEVER, including other COPY statements.
COPY statements may be used anywhere within a COBOL program where the code contained within the copybook
would be syntactically valid.
The syntax diagram above places great emphasis on a period at the end of the COPY statement and any REPLACING
clauses it may have. A period is absolutely mandatory at the end of every COPY statement, even if – to the eye of anexperienced COBOL programmer – it doesn’t seem like there should be a period.
All COPY statements are resolved and the contents of the corresponding copybooks inserted into the program sourcecode before the actual compilation process begins.
The optional “REPLACING” clause allows any reserved words (word-1, word-2), data items (identifier-1, identifier-2),
literals (literal-1, literal-2) or whitespace-delimited phrases to be replaced. Any number of such substitutions may bemade as a copybook is included into a program.
See section 7.1.8 - Locating Copybooks at Compilation Time – for the details as to exactly how the OpenCOBOL
compiler locates copybooks when programs are being compiled.

1.8. Use of Literals
Literals are constant values that will not change during the execution of a program. There are two fundamental typesof literals – numeric and alphanumeric.

1.8.1. Numeric Literals
Numeric literals are numeric constants which may be used as array subscripts, as values in arithmetic expressions, orin any procedural statement where a numeric value may be used. Numeric literals may take any of the following
forms:
Integers such as 1, 56, 2192 or -54.
Non-integer fixed point values such as 1.12 or -2.95.
Hexadecimal numeric literals such as H”1F” (1F16 = 3110), h’22’ (2216 = 3410) or H’DEAD’ (DEAD16 = 5700510).
The “H” character may either be upper- or lower-case and either single quote (‘) or double-quote (“)
06FEB2009 Version

Page 1-12

OpenCOBOL 1.1 Programmers Guide

Introduction

characters may be used. Hexadecimal numeric literals are limited to a maximum value of
H’FFFFFFFFFFFFFFF’ (a 64-bit value).

1.8.2. Alphanumeric Literals
Alphanumeric literals are character strings suitable for display on a computer screen, printing on a report,
transmission through a communications connection or storage in PIC X or PIC A data items (section 5.3). These are
NOT valid for use in arithmetic expressions unless they can first be converted to their numeric computational
equivalent (see the NUMVAL and NUMVAL-C intrinsic functions in section 6.1.7).
Alphanumeric literals may take any of the following forms:
Any sequence of characters enclosed by a pair of single-quote (‘) characters or a pair of double-quote (“)
characters constitutes a string literal. The double-quote character (“) may be used as a data character withinsuch a literal. If a single-quote character must be included as a data character, express that character as twoconsecutive single-quotes (‘’). The single-quote character (‘) may be used as a data character within such aliteral. If a double-quote character must be included as a data character, express that character as twoconsecutive double-quotes (“”).
A hexadecimal literal such as X”4A4B4C” (4A4B4C16 = the ASCII string ‘JKL’), x’20’ (2016 = a space) or
X’30313233’ (3031323316 = the ASCII string ‘0123’). The “X” character may either be upper- or lower-caseand either single quote (‘) or double-quote (“) characters may be used. These hexadecimal alphanumeric
literals should always consist of an even number of hexadecimal digits, because each character isrepresented by eight bits worth of data (2 hex digits). Hexadecimal alphanumeric literals may be of almost
unlimited length.
Alphanumeric literals too long to fit on a single line may be continued to the next line in one of two ways:
If you are using SOURCE FORMAT FIXED mode (section 1.5), the alphanumeric literal can be run right up to
and including column 72. The literal may then be continued on the next line anywhere after column 11 bycoding another quote or apostrophe (whichever was used to begin the literal originally). The continuationline must also have a hyphen (-) coded in column 7. Here is an example:
1
2
3
4
5
6
7
8
12345678901234567890123456789012345678901234567890123456789012345678901234567890
01 LONG-LITERAL-VALUE-DEMO
PIC X(60) VALUE “This is a long l“iteral that must“ be continued.”

Regardless of the current SOURCE FORMAT, OpenCOBOL allows alphanumeric literals to be broken up into
separate fragments. These fragments have their own beginning and ending quote/apostrophe charactersand are “glued together” using “&” characters. No continuation indicator is needed. Here’s an example:
1
2
3
4
5
6
7
8
12345678901234567890123456789012345678901234567890123456789012345678901234567890
01 LONG-LITERAL-VALUE-DEMO
PIC X(60) VALUE “This is a” &“ long literal that must “ &“be continued.”.

If your program is using free-form format, there’s less need to continue long alphanumeric literals because statements
may be as long as 255 characters.
Numeric literals may be split across lines just as alphanumeric literals are, using either of the above techniques andreserved words can be split across lines too (using the first technique). Numeric literals and reserved words don’t get
split very often though – it just makes for ugly-looking programs.

1.9. Use of Figurative Constants
Figurative constants are reserved words that may be used in lieu of certain literals. In general, a figurative constant
may be freely used anywhere its corresponding value could have been used; when used, their value is interpreted as if
it were prefixed with “ALL” (see section 5.3 for a discussion of “ALL”).
The following chart lists the OpenCOBOL figurative constants and their respective equivalent values.
06FEB2009 Version

Page 1-13

OpenCOBOL 1.1 Programmers Guide

Introduction

Figure 1-3 - Figurative Constants

Figurative
Constant
ZERO, ZEROS,ZEROESSPACE, SPACESQUOTE,QUOTES
LOW-VALUE,
LOW-VALUES

Type of
Literal
Numeric

Equivalent Value

Alphanumeric
Alphanumeric

Blank
Double-quote character(s)Alphanumeric

HIGH-VALUE,
HIGH-VALUES

Alphanumeric

NULL

Alphanumeric

The character whose value in the programs collating sequence is lowest. If a
program is using the ASCII collating sequence, this will represent a sequence ofcharacters comprised entirely of 0-bits.
The character whose value in the programs collating sequence is highest. If a
program is using the ASCII collating sequence, this will represent a sequence ofcharacters comprised entirely of 1-bits.
A character comprised entirely of zero-bits (regardless of the programs collating
sequence).

01.10. User-Defined Names
When you write OpenCOBOL programs, you’ll need to create a variety of names to represent various aspects of the
program, the programs data and the external environment in which the program is running.
User-defined names may be composed from the characters “A” through “Z” (upper- and/or lower-case), “0” through“9”, dash (“-“) and underscore (“_”). User-defined names may neither start nor end with hyphen or underscorecharacters.
With the exception of procedure names, user-defined names must contain at least one letter.
When user-defined names are created as names for data, they will be referenced in this document under the term
identifier.

1.11. Use of LENGTH OF
Alphanumeric literals and identifiers may optionally be prefixed with the clause “LENGTH OF”. In such cases, theliteral actually is a numeric literal with a value equal to the number of bytes in the alphanumeric literal. For example,
the following two OpenCOBOL statements both display the same result (27):01

Demo-Identifier

PIC X(27).

*> This is a 27-character data-item.
.
.
DISPLAY LENGTH OF “This is a LENGTH OF Example”
DISPLAY LENGTH OF Demo-Identifier
DISPLAY 27

The LENGTH OF clause on a literal or identifier reference may generally be used anywhere a numeric literal might bespecified, with the following exceptions:1.

In place of a literal on a DISPLAY statement.

2.

As part of a WRITE or RELEASE statement’s FROM clause.

3.

As part of the TIMES clause of a PERFORM.

06FEB2009 Version

Page 1-14

OpenCOBOL 1.1 Programmers Guide

General OpenCOBOL Program Format

2. General OpenCOBOL Program Format
Figure 2-1 - General OpenCOBOL Program Format{ [ IDENTIFICATION DIVISION . ]PROGRAM-ID. program-name-1 [ IS INITIAL PROGRAM ] .
[ ENVIRONMENT DIVISION . environment-division-content ][ DATA DIVISION. data-division-content ]COBOL programs are organized into
DIVISIONS – major groupings of language
statements that all relate to a common
purpose.
Not all divisions are needed in every
program, but they must be specified in
the order shown when they are used.

[ PROCEDURE DIVISION. procedure-division-content ][ nested-source-program | nested-source-function ] ...
[ END PROGRAM program-name-1 . ] } ...

1.

The OpenCOBOL compiler will compile the source code provided to it (a compilation unit) into a single executable
program. This source code can provided as a single program unit (a source code sequence defined by those
DIVISIONs required by the program unit, followed by an optional END PROGRAM clause) or as multiple program
units EACH consisting of the necessary DIVISIONs and a mandatory END PROGRAM clause. When multiple
program units are being compiled in a single compilation unit, the last program unit need not contain an END
PROGRAM clause – all others, however, must have one.

2.

Specifying multiple input files to the OpenCOBOL compiler defines a compilation unit that consists of thecontents of the specified files, compiled in the sequence in which the files are specified. The effect is the same as
if a single source file containing multiple program units were compiled, except that the individual source files
need not contain END PROGRAM clauses unless they contain multiple program units.

3.

Regardless of how many programs units comprise a single compilation unit, only a single output executable
program will be generated. The first program unit encountered in the compilation unit will serve as the main
program – all others must serve as subprograms, called by the main program or by one of the other program units
in the sequence.

4.

Here is a brief summary of the purpose of each DIVISION:
DIVISIONIDENTIFICATIONENVIRONMENTDATAPROCEDURE

06FEB2009 Version

PurposeThe IDENTIFICATION DIVISION (section 3) provides basic identification of the program by giving
it a program id (a name).
The ENVIRONMENT DIVISION (section 4) defines the external computer environment in which
the program will be operating. This includes defining any files that the program may beaccessing.
The DATA DIVISION (section 5) is used to define all data that will be processed by a program.
The PROCEDURE DIVISION (section 6) contains all executable program code.

Page 2-1

OpenCOBOL 1.1 Programmers Guide

General OpenCOBOL Program Format

2.1. General Format for Nested Source Programs
Figure 2-2 - General Format for Nested Source Programs[ IDENTIFICATION DIVISION . ]PROGRAM-ID. program-name-1 [ IS

INITIALCOMMONPROGRAM ] .

[ ENVIRONMENT DIVISION . environment-division-content ][ DATA DIVISION. data-division-content ][ PROCEDURE DIVISION. procedure-division-content ][ nested-source-program | nested-source-function ] ...
[ END PROGRAM program-name-1 . ]1.

Nested source programs areprogram units imbedded
inside other program units(they follow the PROCEDUREDIVISION of their “parent”
program unit and there is nointervening END PROGRAM
between the two). As suchthey serve as subprograms
available ONLY to the parent
program unit in which they6
are imbedded .

Nested source programs may themselves contain other nested programs. Care should be taken to include END
PROGRAM clauses between nested subprograms that should be considered at “equal levels” in the nesting
structure.

2.2. General Format for Nested Source Functions
Figure 2-3 - General Format for Nested Source Functions

FUNCTION-ID. function-name-1 [ IS

INITIALCOMMONPROGRAM ] .

User-defined functions aredefined in the OpenCOBOL
syntax but are not currently
supported.

[ ENVIRONMENT DIVISION . environment-division-content ]DATA DIVISION. data-division-content

PROCEDURE DIVISION[ USING data-item-1 ... ][ RETURNING data-item-n ].

procedure-division-content[ nested-source-program | nested-source-function ] ...

[ END FUNCTION function-name-1 . ]1.

Attempts to compile a user-defined function will be rejected with a message such as the following:
name:line: Error: FUNCTION-ID is not yet implemented

6

Of course, there are always exceptions to every rule. See the discussion of the COMMON clause to the
PROGRAM-ID paragraph on page 8.

06FEB2009 Version

Page 2-2

OpenCOBOL 1.1 Programmers Guide

IDENTIFICATION DIVISION

3. IDENTIFICATION DIVISION
Figure 3-1 - IDENTIFICATION DIVISION Syntax[ IDENTIFICATION DIVISION . ]PROGRAM-ID. program-name-1 [ IS

INITIALCOMMONPROGRAM ] .

The IDENTIFICATION DIVISION
provides basic identification of
the program by giving it aprogram id (a name).

1.

While the actual IDENTIFICATION DIVISION header is optional, the PROGRAM-ID clause is not.

2.

The PROGRAM-ID clause defines the name (program-name) by which other programs may refer to this one (i.e.
CALL “program-name”).

3.

Program names ARE case-sensitive. If the compilation unit is being created as a dynamically-loadable library file(by using the “-m” option on the OpenCOBOL compiler command), then the library filename created by thecompiler will exactly match the program-name. If the compilation unit is being created as an executable file (byusing the “-x” option on the OpenCOBOL compiler command) then the program-id may be any valid COBOL
identifier name because the executable filename will be the same as the source program filename without the“cbl” or “cob” extension.

4.

The INITIAL and COMMON clauses are used within subprograms. The COMMON clause should be used only
within subprograms that are nested source programs.

5.

The INITIAL clause, if specified, guarantees the subprogram will be in its initial (i.e. compiled) state each and every
time it is executed, not just the first time.

6.

The COMMON clause, if any, makes a nested source program (subprogram) unit available to the parent program
unit as well as to other nested source program units of that parent.

7.

Obsolete IDENTIFICATION DIVISION entries such as DATE-WRITTEN, DATE-COMPILED, AUTHOR, INSTALLATION,
SECURITY and REMARKS are normally ignored unless the “–Wobsolete” compilation switch is used; in such a case,warning messages will be generated but compilation will continue.

06FEB2009 Version

Page 3-1

OpenCOBOL 1.1 Programmers Guide

06FEB2009 Version

IDENTIFICATION DIVISION

Page 3-2

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION

4. ENVIRONMENT DIVISION
Figure 4-1 - ENVIRONMENT DIVISION Syntax
ENVIRONMENT DIVISION.
[ CONFIGURATION SECTION. ]The ENVIRONMENT DIVISION defines the external computer environment
in which the program will be operating. This includes defining any files
that the program may be accessing.

[ INPUT-OUTPUT SECTION. ]1.

If none of the features provided by the ENVIRONMENT DIVISION are required by a program, the ENVIRONMENTDIVISION need not be specified.

4.1. CONFIGURATION SECTION
Figure 4-2 - CONFIGURATION SECTION Syntax

The CONFIGURATION DIVISION defines the computer
system upon which the program is being compiled andexecuted and also specifies any special environmental
configuration or compatibility characteristics.

CONFIGURATION SECTION.
[ SOURCE-COMPUTER. source-computer-contents ][ OBJECT-COMPUTER. object-computer-contents ][ REPOSITORY. repository-contents ][ SPECIAL-NAMES. special-names-contents ]1.

The sequence in which the CONFIGURATION SECTION paragraphs are specified is irrelevant.

4.1.1. SOURCE-COMPUTER Paragraph
Figure 4-3 - SOURCE-COMPUTER Paragraph Syntax

SOURCE-COMPUTER. computer-name-1[ WITH DEBUGGING MODE ]The SOURCE-COMPUTER paragraph defines the computer uponwhich the program is being compiled.

.

1.

The value specified for computer-name-1 is irrelevant, provided it is a valid COBOL word that does not match any
OpenCOBOL reserved word.

2.

The optional WITH DEBUGGING MODE clause, if present, will be flagged as obsolete syntax (if using the “-W”, “Wobsolete” or “-Wall” compiler switches) and will have no effect on the program compilation.

3.

Debugging lines in your programs may be compiled, however, by specifying the “-fdebugging-line” switch to
the OpenCOBOL compiler. Section 1.5 discusses how debugging lines are specified in an OpenCOBOL program.

4.1.2. OBJECT-COMPUTER Paragraph
Figure 4-4 - OBJECT-COMPUTER Paragraph Syntax
OBJECT-COMPUTER. computer-name-2
MEMORY SIZE IS integer-1

WORDS
CHARACTERS

The OBJECT-COMPUTER paragraph describes thecomputer upon which the program will execute. This
paragraph is not merely documentation.

[ PROGRAM COLLATING SEQUENCE IS alphabet-name-1 ][ SEGMENT-LIMIT IS integer-2 ].

1.

The value specified for computer-name-2 is irrelevant, provided it is a valid COBOL word that does not match any
OpenCOBOL reserved word.

2.

The MEMORY SIZE and SEGMENT-LIMIT clauses are supported for compatibility purposes, but are non-functional
in OpenCOBOL.

06FEB2009 Version

Page 4-1

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION

3.

The PROGRAM COLLATING SEQUENCE clause allows you to specify a customized character collating sequence tobe used when alphanumeric values are compared to one another. Data will still be stored in the characterset
native to the computer, but the logical sequence in which characters are ordered for comparison purposes can bealtered from that inherent to the computer’s native characterset. The alphabet-name-1 you specify needs to be
defined in the SPECIAL-NAMES section (4.1.4).

4.

If no PROGRAM COLLATING SEQUENCE clause is specified, the collating sequence implied by the characterset
native to the computer (usually ASCII) will be used.

4.1.3. REPOSITORY Paragraph
Figure 4-5 - REPOSITORY Paragraph Syntax
REPOSITORY.
FUNCTION

function-name-1 …
ALL

INTRINSIC .

The REPOSITORY paragraph provides a mechanism forcontrolling access to the various built-in intrinsic
functions.

1.

You may flag one or more (or ALL) intrinsic functions as being usable without the need to code the keyword“FUNCTION” in front of the function names. See section 6.1.7 for more information about intrinsic functions.

2.

As an alternative to using the REPOSITORY paragraph, you may instead compile your OpenCOBOL programs using
the “-ffunctions-all” switch.

06FEB2009 Version

Page 4-2

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION

4.1.4. SPECIAL-NAMES Paragraph
Figure 4-6 - SPECIAL-NAMES Paragraph Syntax

The SPECIAL-NAMES paragraphprovides a means for specifying thecurrency sign, choosing the decimal
point, [specifying symboliccharacters,] relating implementernames to user-specified mnemonicnames, relating alphabet names tocharacter sets or collating
sequences, and relating class names
to sets of characters.

SPECIAL-NAMES.
[ CONSOLE IS CRT ]SYSINSYSIPTSYSOUTSYSLIST...
IS mnemonic-name-1
SYSLST
PRINTERSYSERRCONSOLESWITCH-1.
IS mnemonic-name-2.
SWITCH-8
ON STATUS IS condition-name-1
OFF STATUS IS condition-name-2
C01
.
.
C12

In short, this paragraph provides ameans of easily “configuring” a
COBOL program created in anothercomputing environment so that it
will compile with minimal changes
in an OpenCOBOL environment.

...

...

IS mnemonic-name-3

ALPHABET alphabet-name IS

NATIVESTANDARD-1
STANDARD-2
EBCDIC
literal-1...
THRU
THROUGH literal-2{ ALSO literal-3 } ...

...

SYMBOLIC CHARACTERS{ { symbolic-character-1 } ...
[ IN alphabet-name-2 ]CLASS class-name-1 IS literal-4

THRU
THROUGHIS
ARE

literal-5{ integer-1 } ... } …

...

...

[ LOCALE locale-name-1 IS identifier-1 ] ...
[ CURRENCY SIGN IS literal-6 ][ DECIMAL-POINT IS COMMA ][ CURSOR IS identifier-2 ][ CRT STATUS IS identifier-3 ][ SCREEN CONTROL IS identifier-4 ][ EVENT STATUS IS identifier-5 ].

1.

The CONSOLE IS CRT clause exists to provide source code compatibility with other versions of OpenCOBOL. It
allows the devices “CRT” and “CONSOLE” to be used interchangeably on DISPLAY (section 6.14.1) and ACCEPT(section 6.4.1) statements. This isn’t needed when coding OpenCOBOL programs “from scratch” because
OpenCOBOL already considers those two devices to be synonymous.

2.

The IS mnemonic-name-1 clause allows you to specify an alternate name for one of the built-in OpenCOBOL
device names specified before the “IS”.

3.

The external values of SWITCH-1 through SWITCH-8 are specified to a program using the environment variables
COB_SWITCH_1 through COB_SWITCH_8, respectively. A value of “ON” turns the switch on. Any other value(including the environment variable being undefined) turns the switch off. The ON STATUS and/or OFF STATUS
clauses define condition names that may be used to test whether a switch is set or not at run-time. See sections
6.1.4.2.1 and 6.1.4.2.4 for more information.

06FEB2009 Version

Page 4-3

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION

4.

The ALPHABET clause provides a means for relating a name to a specified character code set or collating
sequence, including those you define yourself using the “literal-1” option. You may specify an alphanumeric
literal for any of the literal-1, literal-2 or literal-3 specifications. You may also specify any of the figurative
constants SPACE[S], ZERO[[E]S], QUOTE[S], HIGH-VALUE[S} or LOW-VALUE[S].

5.

The SYMBOLIC CHARACTERS clause will be syntactically recognized but will be ignored. If you use the “-Wall” or“-W” compiler switches you will receive a warning message stating this feature is not yet implemented.

6.

User-defined classes are defined using the CLASS clause. The literal(s) specified on that clause define the possible
characters that may be found in a data item’s value in order to be considered part of the class. For example, thefollowing defines a class called “Hexadecimal”, the definition of which specifies the only characters that may bepresent in a data item if that data item is to be part of the “Hexadecimal” class:
CLASS Hexadecimal IS „0‟ THRU „9‟, „A‟ THRU „F‟, „a‟ THRU „f‟

See section 6.1.4.2.2 for an example of how this user-defined class might be used.
The LOCALE clause may be used to associate UNIX-standard locale names with an identifier defined in the DATADIVISION. Locale names may be any of the following:
Figure 4-7 - Locale Codes
af_ZA
am_ET
ar_AE
ar_BH
ar_DZ
ar_EG
ar_IQ
ar_JO
ar_KW
ar_LB
ar_LY
ar_MA
ar_OM
ar_QA
ar_SA
ar_SY
ar_TN
ar_YE
arn_CL
as_IN
az_Cyrl_AZ
az_Latn_AZ
ba_R
be_BY
bg_BG
bn_IN
bo_BT
bo_CN
br_FR
bs_Cyrl_BA
bs_Latn_BA
ca_ES
cs_CZ
cy_GB
da_DK
de_AT
de_CH
de_DE
de_LI
de_LU
dsb_DE

06FEB2009 Version

dv_MV
el_GR
en_029
en_AU
en_BZ
en_CA
en_GB
en_IE
en_IN
en_JM
en_MY
en_NZ
en_PH
en_SG
en_TT
en_US
en_ZA
en_ZW
es_AR
es_BO
es_CL
es_CO
es_CR
es_DO
es_EC
es_ES
es_GT
es_HN
es_MX
es_NI
es_PA
es_PE
es_PR
es_PY
es_SV
es_US
es_UY
es_VE
et_EE
eu_ES
fa_IR

fi_FI
fil_PH
fo_FO
fr_BE
fr_CA
fr_CH
fr_FR
fr_LU
fr_MC
fy_NL
ga_IE
gbz_AF
gl_ES
gsw_FR
gu_IN
ha_Latn_NG
he_IL
hi_IN
hr_BA
hr_HR
hu_HU
hy_AM
id_ID
ig_NG
ii_CN
is_IS
it_CH
it_IT
iu_Cans_CA
iu_Latn_CA
ja_JP
ka_GE
kh_KH
kk_KZ
kl_GL
kn_IN
ko_KR
kok_IN
ky_KG
lb_LU
lo_LA

lt_LT
lv_LV
mi_NZ
mk_MK
ml_IN
mn_Cyrl_MN
mn_Mong_CN
moh_CA
mr_IN
ms_BN
ms_MY
mt_MT
nb_NO
ne_NP
nl_BE
nl_NL
nn_NO
ns_ZA
oc_FR
or_IN
pa_IN
pl_PL
ps_AF
pt_BR
pt_PT
qut_GT
quz_BO
quz_EC
quz_PE
rm_CH
ro_RO
ru_RU
rw_RW
sa_IN
sah_RU
se_FI
se_NO
se_SE
si_LK
sk_SK
sl_SI

sma_NO
sma_SE
smj_NO
smj_SE
smn_FIsms_FI
sq_AL
sr_Cyrl_BA
sr_Cyrl_CS
sr_Latn_BA
sr_Latn_CS
sv_FI
sv_SE
sw_KE
syr_SY
ta_IN
te_IN
tg_Cyrl_TJ
th_TH
tk_TM
tmz_Latn_DZ
tn_ZA
tr_IN
tr_TR
tt_RU
ug_CN
uk_UA
ur_PK
uz_Cyrl_UZ
uz_Latn_UZ
vi_VN
wen_DE
wo_SN
xh_ZA
yo_NG
zh_CN
zh_HK
zh_MO
zh_SG
zh_TW
zu_ZA

Page 4-4

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION7.

The CURRENCY SIGN clause may be used to define any single character as the currency sign used in PICTURE
symbol editing (see Figure 5-9). The default currency sign is a dollar-sign ($).

8.

The DECIMAL POINT IS COMMA clause reverses the definition of the “,” and “.” characters when they are used as
PICTURE editing symbols (see Figure 5-9) and numeric literals. This can have unwanted side-effects – see section
1.6.

9.

The PICTURE of identifier-3 (CRT-STATUS) should be 9(4). This field will receive a 4-digit value indicating theruntime status of a screen ACCEPT. These status codes are as follows:
Figure 4-8 - Screen ACCEPT Key Codes

Code
0000
1001 - 1064
2001,2002
2003,2004,2006

Meaning
ENTER key pressed
F1 – F64
7
PgUp,PgDn
Up Arrow,Down Arrow,PrtSc
8(Print Screen)

Code
2005
8000
9000

Meaning,9
Esc
No data is available on screen ACCEPT
Fatal screen I/O error

The actual key pressed to generate a function key (Fn) will depend on the type of terminal device you’re using (PC,Macintosh, VT100, etc.) and what type of enhanced display driver was configured with the version of OpenCOBOL
you’re using. For example, on an OpenCOBOL built for a Windows PC using MinGW and PDCurses, F1-F12 are theactual F-keys on the PC keyboard, F13-F24 are entered by shifting the F-keys, F25-F36 are entered by holding Ctrl
while pressing an F-key and F37-F48 are entered by holding Alt while pressing an F-key. On the other hand, an
OpenCOBOL implementation built for Windows using Cygwin and NCurses treats the PCs F1-F12 keys as the actual
F1-F12, while shifted F-keys will enter F11-F20. With Cygwin/NCurses, Ctrl- and Alt-modified F-keys aren’t
recognized. Neither are Shift-F11 or Shift-F12.
Note that numeric keypad keys are not recognizable on Windows MinGW/PDCurses builds of OpenCOBOL,
regardless of NumLock settings. Windows Cygwin/NCurses builds recognize numeric keypad inputs properly.
Although not tested during the preparation of this documentation, I would expect native Windows builds using
PDCurses to behave as MinGW builds do and native Unix builds using NCurses to behave as do Cygwin builds.
10. If the CRT STATUS clause is not specified, an implicit COB-CRT-STATUS identifier (with a PICTURE of 9(4)) will beallocated for the purpose of receiving screen ACCEPT statuses.
11. While the SCREEN CONTROL and EVENT STATUS clauses are clearly noted at compilation time as being
unsupported, the CURSOR IS clause is not; currently, however, it appears to be non-functional at runtime.

4.2. INPUT-OUTPUT SECTION
Figure 4-9 - INPUT-OUTPUT SECTION Syntax
INPUT-OUTPUT SECTION.

The INPUT-OUTPUT section provides for the detailed
definition of any files the program will be accessing.

[ FILE-CONTROL. file-control-contents ][ I-O-CONTROL. Io-control-contents ]1.

If the compiler “config” file you are using has “relaxed-syntax-check” set to “yes”, the FILE-CONTROL and I-OCONTROL paragraphs may be specified without the INPUT-OUTPUT SECTION header having been specified. See
section 7.1.8 for more information on config files and their effect on programs.

7

These keys are available ONLY if the environment variable COB_SCREEN_EXCEPTIONS is set to any non-blank value
at runtime.

8

These keys are not detectable on Windows systems

9This key is available ONLY if the environment variable COB_SCREEN_ESC is set to any non-blank value at runtime(this is in addition to setting COB_SCREEN_EXCEPTIONS)

06FEB2009 Version

Page 4-5

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION

4.2.1. FILE-CONTROL Paragraph
Figure 4-10 - FILE-CONTROL Paragraph Syntax

The SELECT
statement of the
FILE-CONTROL
paragraph creates adefinition of a fileand links that
COBOL definition to
the external
operating system
environment.

FILE-CONTROL.
SELECT [ OPTIONAL ] file-name-1

ASSIGN TO
FILE
SORT

DISK
PRINTER

EXTERNAL
DYNAMICDISPLAY
literal-1
identifier-1

STATUS IS identifier-2 [ identifier-3 ][ COLLATING SEQUENCE IS alphabet-name-1 ]LOCK MODE IS
EXCLUSIVEMANUAL
AUTOMATICWITH LOCK ON MULTIPLE RECORDSWITH LOCK ON RECORD

...

...

WITH ROLLBACK[ RECORD DELIMITER IS STANDARD-1 ][ RESERVE integer-1 AREAS ]What is shown here
are those clauses of
the SELECT
statement that arecommon to all typesof files.
Upcoming sections
will discuss special
SELECT clauses that
only pertain tocertain types of files.

ALL OTHERSHARING WITHNO OTHERREAD ONLY[ organization-specific-clauses ].

1.

The COLLATING SEQUENCE, RECORD DELIMITER, RESERVE and SHARING WITH ALL OTHER clauses, as well as the
specification of a secondary FILE-STATUS field and LOCK MODE … WITH ROLLBACK, while syntactically recognized,
are not currently supported by OpenCOBOL.

2.

The OPTIONAL clause, to be used only for files that will be used to provide input data to the program, indicatesthe file may or may not actually be available at run-time. Attempts to OPEN (section 6.31) an OPTIONAL file when
the file does not exist will receive a special non-fatal file status value (see status 05 in #0 below) indicating the fileis not available; a subsequent attempt to READ that file (section 6.33) will return an end-of-file condition.

3.

The OpenCOBOL compiler parser tables actually allow the somewhat nonsensical statement:
SELECT My-File ASSIGN TO DISK DISPLAY.
…to be coded and successfully parsed. The effect will be the same as if this were coded:
SELECT My-File ASSIGN TO DISPLAY.
…which will be to create a file assigned to the PC screen.

4.

If the “literal-1” option is used on the ASSIGN clause, it defines the external link from the COBOL file to an
operating system file as follows:
If an environment variable named “DD_literal-1” exists, its value will be treated as the full path/filename of
the file. If not, then …

06FEB2009 Version

Page 4-6

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION

If an environment variable named “dd_literal-1” exists, its value will be treated as the full path/filename of
the file. If not, then …
If an environment variable named “literal-1”exists, its value will be treated as the full path/filename of the
file. If not, then…
The literal itself will be treated as the full path/filename to the file.
This behavior will be influenced by the “filename-mapping” setting in the config file you are using whencompiling your programs. The behavior stated above applies only if “filename-mapping: yes” is in-effect. If“filename-mapping: no” is used, only the last option (treating the literal itself as the full name of the file) is
possible. See section 7.1.8 for more information on config files and their effect on programs.
The PICTURE of identifier-2 (the FILE STATUS clause) should be 9(2). An I/O status code will be saved to thisidentifier after every I/O verb that is executed against the file. Possible status codes are as follows:
Figure 4-11 - FILE-STATUS Values

Status Value
00
02
05
07
10
14
21
22
23
30
31
34
35
37
38
39
41
42
43
44
46
47
48
49
51
52
57
61
91
6.

Meaning
Success
Success (Duplicate Record Key Written)
Success (Optional File Not Found)
Success (No Unit)
End of file
Out of key range
Key invalid
Attempt to duplicate key value
Key not found
Permanent I/O error
Inconsistent filename
Boundary violation
File not foundPermission denied
Closed with lock
Conflicting attribute
File already OPEN
File not OPEN
Read not done
Record overflow
READ error
OPEN INPUT denied
OPEN OUTPUT denied
OPEN I-O denied
Record locked
End of page
LINAGE specifications invalid
File sharing failure
File not available

The LOCK and SHARING clauses define the conditions under which this file will be usable by other programs
executing concurrently with this one. File locking and sharing is covered in section 6.1.9.

06FEB2009 Version

Page 4-7

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION

4.2.1.1. ORGANIZATION SEQUENTIAL Files
Figure 4-12 - Additional FILE-CONTROL Syntax for SEQUENTIAL Files
ORGANIZATION IS

RECORD BINARYLINE

SEQUENTIAL files are those whose internal structure(in COBOL, this is referred to as organization) is suchthat the data in those files can only be processed in athsequential manner; in order to read the 100 recordin such a file, you first must read records 1 through99.

SEQUENTIAL[ ACCESS MODE IS SEQUENTIAL ]PADDING CHARACTER IS

literal-1
identifier-1

1.

Files declared as ORGANIZATION RECORD BINARY SEQUENTIAL will consist of records with no explicit end-ofrecord delimiter character sequences; records in such files are “delineated” by a calculated byte-offset (based onrecord length) into the file . Such files cannot be prepared with any standard text-editing or word processing
software as all such programs will imbed delimiter characters. Such files may contain either USAGE DISPLAY or
USAGE COMPUTATIONAL (of any variety) data since no character sequence will be interpreted as an end-ofrecord delimiter.

2.

Specifying ORGANIZATION IS RECORD BINARY SEQUENTIAL is the same as specifying ORGANIZATION SEQUENTIAL.

3.

Files declared as ORGANIZATION LINE SEQUENTIAL will consist of records terminated by an ASCII line-feedcharacter (X”10”). When reading a LINE SEQUENTIAL file, records in excess of the size implied by the file’s FD willbe truncated while records shorter than that size will be padded to the right with the PADDING CHARACTER value.

4.

The default PADDING CHARACTER value is SPACE.

5.

While the PADDING CHARACTER clause is syntactically acceptable for all file ORGANIZATIONs, it only makes sensefor LINE SEQUENTIAL files as these are the only files where incoming records can ever be padded.

6.

Both fixed- and variable-length record formats are supported.

7.

Files ASSIGNed to PRINTER or CONSOLE should be specified as ORGANIZATION LINE SEQUENTIAL.

8.

See the discussion of the CLOSE(section 6.9), COMMIT (section 6.10), DELETE (section 6.13), MERGE (section
6.27), OPEN (section 6.31), READ(section 6.33), REWRITE(section 6.36), SORT (section 6.40.1), UNLOCK (section
6.48) and WRITE(section 6.50), verbs for information on how SEQUENTIAL files are processed.

4.2.1.2. ORGANIZATION RELATIVE Files
Figure 4-13 - Additional FILE-CONTROL Syntax for RELATIVE Files
ORGANIZATION IS RELATIVEACCESS MODE IS

SEQUENTIAL
DYNAMICRANDOM[ RELATIVE KEY IS identifier-1 ]RELATIVE files are files with an internal organization suchthat records may be processed in a sequential manner orin a random manner, where records may be read, written
and updated by specifying the relative record number inthe file.

1.

ORGANIZATION RELATIVE files cannot be assigned to CONSOLE or PRINTER.

2.

The RELATIVE KEY clause is optional only if ACCESS MODE SEQUENTIAL is specified.

3.

While records in a ORGANIZATION RELATIVE file may be defined as having variable-length records, the file will be
structured in such a manner as to reserve the maximum possible space for each record.

4.

An ACCESS MODE of SEQUENTIAL indicates that the records of the file will be processed in a sequential manner,
while an ACCESS MODE of RANDOM means that records will be processed in random sequence. The DYNAMICACCESS MODE indicates the file will be processed either in RANDOM or SEQUENTIAL mode, and may switch backand forth between the two when the program executes (see the START verb in section 6.41).

5.

The default ACCESS MODE is SEQUENTIAL.

06FEB2009 Version

Page 4-8

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION

6.

The RELATIVE KEY data item is a numeric data item that cannot be a field within records of this file. Its purpose isto return the current relative record number of a RELATIVE file that is being processed in SEQUENTIAL accessmode and to be a retrieval key that specifies the relative record number to be read or written when processing a
RELATIVE file in RANDOM access mode.

7.

See the discussion of the CLOSE(section 6.9), COMMIT (section 6.10), DELETE (section 6.13), MERGE (section
6.27), OPEN (section 6.31), READ(section 6.33), REWRITE(section 6.36), SORT (section 6.40.1), START (section
6.41), UNLOCK (section 6.48) and WRITE(section 6.50), verbs for information on how RELATIVE files are processed.

4.2.1.3. ORGANIZATION INDEXED Files
Figure 4-14 - Additional FILE-CONTROL Syntax for INDEXED Files

ORGANIZATION IS INDEXEDACCESS MODE IS

SEQUENTIAL
DYNAMICRANDOM

RECORD KEY IS identifier-1=
SOURCE IS

ALTERNATE RECORD KEY IS identifier-3[ WITH DUPLICATES ]identifier-2 ...
=SOURCE IS

identifier-4 ...

...

INDEXED files, like
RELATIVE files, may havetheir records processed
either sequentially or in arandom manner. Unlike
RELATIVE files, however,
the actual location of arecord in an INDEXED file isbased upon the value(s) of
one or more alphanumericfields within records of thefile.

For example, an INDEXED file containing product data might use the product identification code as a key. This means
you may read, write or update the “A6G4328”th record or the “Z8X7723”th record directly, based upon the product id
value of those records!
1.

The specification of so-called “split keys”, while syntactically recognized, are not currently supported by
OpenCOBOL.

2.

An ACCESS MODE of SEQUENTIAL indicates that the records of the file will be processed in a sequential mannerwith respect to the values of the RECORD KEY or an ALTERNATE RECORD KEY, while an ACCESS MODE of RANDOM
means that records will be processed in random sequence of a key field. The DYNAMIC ACCESS MODE indicatesthe file will be processed either in RANDOM or SEQUENTIAL mode, and may switch back and forth between thetwo when the program executes (see the START verb in section 6.41).

3.

The default ACCESS MODE is SEQUENTIAL.

4.

The PRIMARY KEY clause defines the field(s) within the record used to provide the primary access to records
within the file.

5.

The ALTERNATE RECORD KEY clause, if used, defines an additional field within the record that provides analternate means of directly accessing records or an additional field by which the file’s contents may be processedsequentially. You have the choice of allowing records to have duplicate alternate key values, if necessary.

6.

There may be multiple ALTERNATE RECORD KEY clauses, each defining an additional alternate key for the file.

7.

PRIMARY KEY values must be unique for all records within the value. ALTERNATE RECORD KEY values for records
within the file may have duplicate values if and only if the WITH DUPLICATES clause is specified for the alternate
key.

8.

See the discussion of the CLOSE(section 6.9), COMMIT (section 6.10), DELETE (section 6.13), MERGE (section
6.27), OPEN (section 6.31), READ(section 6.33), REWRITE(section 6.36), SORT (section 6.40.1), START (section
6.41), UNLOCK (section 6.48) and WRITE(section 6.50), verbs for information on how INDEXED files are processed.

06FEB2009 Version

Page 4-9

OpenCOBOL 1.1 Programmers Guide

ENVIRONMENT DIVISION

4.2.2. I-O-CONTROL Paragraph
Figure 4-15 - I-O-CONTROL Paragraph Syntax

The I-O-CONTROL Paragraph canbe used to optimize certain
aspects of file processing.

I-O-CONTROL.
SAMERECORD
SORT
SORT-MERGE

AREA FOR file-name-1 ...

MULTIPLE FILE TAPE CONTAINS
file-name-1 [ POSITION integer-1 ][ file-name-2 [ POSITION integer-2 ] ] ...

1.

The SAME SORT AREA and SAME SORT-MERGE AREA clauses are non-functional. The SAME RECORD AREA isfunctional, however.

2.

The SAME RECORD AREA clause allows you to specify that multiple files should share the same input and output
memory buffers. These buffers can sometimes get quite large, and by having multiple files share the same buffer
memory you get significantly cut down the amount of memory the program is using (thus making “room” formore procedural code or data). If you do use this feature, take care to ensure that no more than one of thespecified files are ever open simultaneously.

3.

The MULTIPLE FILE TAPE clause is obsolete and is therefore recognized but not otherwise supported.

06FEB2009 Version

Page 4-10

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

5. DATA DIVISION
Figure 5-1 - General DATA DIVISION Format

The DATA DIVISION is used to define all data that will be processed by aprogram. Depending upon the type of data and/or the manner in which
the data will be used, its definition will be specified in one of thesections shown in the syntax skeleton to the left.

DATA DIVISION .
FILE SECTION .
file-description
sort-description...

WORKING-STORAGE SECTION .
77-level-data-description
01-level-data-description
constant-description...

LOCAL-STORAGE SECTION .

77-level-data-description
01-level-data-description
constant-description...

LINKAGE SECTION .
77-level-data-description
01-level-data-description
constant-description...

REPORT SECTION .
[ report-description ] ...
SCREEN SECTION .
screen-description
constant-description

...

1.

Any SECTIONs that are declared must be specified in the order shown. If no DATA DIVISION sections are needed,
the DATA DIVISION header itself may be omitted.

2.

The REPORT SECTION is syntactically recognized but will – if used – be rejected as unsupported. OpenCOBOL does
not support the RWCS (it does support the LINAGE clause in an FD, however).

3.

The LOCAL-STORAGE SECTION is used in a manner identical to the WORKING-STORAGE SECTION with one
exception: data defined in the LOCAL-STORAGE SECTION is [re]initialized to its initial state every time the program(usually a subprogram) is executed while WORKING-STORAGE SECTION data is static—it remains in its last-usedstate until the program is CANCELed or the execution of the main program is terminated.

4.

LOCAL-STORAGE cannot be used in nested programs.

5.

The SCREEN SECTION allows you do define text-based screen layouts using conventions and syntax similar to what
you might expect to use if you were using the REPORT SECTION to lay out the structure of a report.

6.

Note that there is no COMMON-STORAGE SECTION in OpenCOBOL. This feature has actually been removed fromthe COBOL standard. Its functionality, however, has been replaced by the EXTERNAL and GLOBAL data item
attributes.

06FEB2009 Version

Page 5-1

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

5.1. FD - File Description
Figure 5-2 - FD Syntax

FD file-name

EXTERNAL
GLOBALCHARACTERS
BLOCK CONTAINS integer-1 [ TO integer-2 ] RECORDSCONTAINS integer-3 [ TO integer-4 ] CHARACTERS
IS VARYING IN SIZE[ FROM integer-5 [ TO integer-6 ] CHARACTERS
DEPENDING ON identifier-1

RECORD

RECORD IS
RECORDS ARELABELOMITTEDSTANDARD

literal-1
VALUE OF implementor-name-1 IS
identifier-2
RECORD IS
RECORDS ARE

DATA

identifier-3 …

[ RECORDING MODE IS recording-mode ]REPORT ISREPORTS ARE
LINAGE IS

There must be a detailed
description for every file
SELECTed in yourprogram. These detailed
descriptions will be
coded in the FILESECTION.
There are two types ofsuch descriptions – FDs
and SDs, used to describe
regular data files and sortwork files, respectively.
The FD provides adetailed description of
the record format(s) usedwith the file as well as
how those records are“bundled” into physicalblocks for processing
efficiency.

identifier-4 …

Integer-7
Identifier-4

LINES

Integer-8
WITH FOOTING AT Identifier-5
Integer-9
LINES AT TOP Identifier-6
LINES AT BOTTOM

integer-10
Identifier-7[ CODE-SET IS alphabet-name ].

01-level-data-description ...

1.

The CODE-SET clause, while syntactically recognized, is not currently supported by OpenCOBOL.

2.

The LABEL RECORD, DATA RECORD, RECORDING MODE and VALUE OF clauses are obsolete. If used, they will haveno impact on the generated code. The identifiers specified on the DATA RECORD clause will be verified as being
defined within the program, but the compiler won’t care whether they are actually specified as records of the fileor not.

3.

The COBOL programming language allows for the “blocking” of multiple logical data records into a single physicaldata record; an actual physical write to an output file being processed sequentially will occur when a memory
block is filled with new records (see the COMMIT verb in section 6.10). Similarly, when reading a file sequentially,
the first READ issued against the file will retrieve the first physical record (block), from which the first logical

06FEB2009 Version

Page 5-2

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

record will be retrieved and delivered to the program. Subsequent READ statements will retrieve successive
logical records from the buffer until it is exhausted, in which case another physical read is performed to acquire
the next physical record. The BLOCK CONTAINS clause in the FD allows all this processing to be performed in amanner that is completely transparent to the programmer.
4.

The RECORD CONTAINS and RECORD IS VARYING clauses are ignored (with a warning message issued) when usedwith LINE SEQUENTIAL files. With other file organizations these mutually-exclusive clauses define the length ofdata records within the file. These sizes are used by the BLOCK CONTAINS … RECORDS clause to calculate a block
size.

5.

The REPORT IS clause is syntactically recognized but will cause an error since the RWCS is not currently supported
by OpenCOBOL.

6.

The LINAGE clause can only be specified for ORGANIZATION RECORD BINARY SEQUENTIAL or ORGANIZATION LINE
SEQUENTIAL files. If used on an ORGANIZATION RECORD SEQUENTIAL file, the definition of that file will be
implicitly changed to LINE SEQUENTIAL.

7.

The LINAGE clause is used to specify the
logical boundaries (in terms of numbers oflines) of various areas on a printed page, as
shown in Figure 5-3.
The manner in which this page structure will
be utilized is discussed in section 6.50 (theWRITE statement).

Figure 5-3- LINAGE-specified Page Structure
Top Margin (unprintable)

Total # of linesthat exist on a
printed page

LINES AT TOP t
Default = 0

Page Body (printable)
Size (in lines): n – t – b

LINAGE IS n LINESWITH FOOTING AT f
Default = no page footer

Page Footing area (if any)
Bottom Margin (unprintable) -LINES AT BOTTOM b
Default = 0

8.

By specifying the EXTERNAL clause, the FD is capable of being shared between all program units (either separately
compiled or compiled in the same compilation unit) in a given execution thread, provided the FD is described(with an EXTERNAL clause) in each compilation unit requiring it. This sharing allows the file to be OPENed, read
and/or written and CLOSEd in different program units.

9.

By specifying the GLOBAL clause, the FD is capable of being shared between all program units in the same
compilation unit in a given execution thread, provided the FD is described (with a GLOBAL clause) in each program
unit requiring it. This sharing allows the file to be OPENed, read and/or written and CLOSEd in different program
units. Separately compiled programs cannot share a GLOBAL FD (but they can share an EXTERNAL FD).

5.2. SD - SORT Description
Figure 5-4 - SD Syntax

Sort work files (see sections 6.27 and 6.40.1) aredescribed using an SD, not an FD.

SD file-name
CONTAINS integer-3 [ TO integer-4 ] CHARACTERS
RECORDIS VARYING IN SIZE[ FROM integer-5 [ TO integer-6 ] CHARACTERS
DEPENDING ON identifier-1[ CODE-SET IS alphabet-name ] .
01-level-data-description ...

1.

The full “FD” syntax is actually available for a sort description, but only those syntax elements shown here aremeaningful.

2.

Sort files should be assigned to DISK.

06FEB2009 Version

Page 5-3

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

3.

Sorts will be performed in memory, if the amount of data being sorted allows.

4.

Should disk work files be necessary due to the amount of data being sorted, they will be automatically allocatedto disk in a folder defined by the TMPDIR, TMP or TEMP environment variables (see section 7.2.4). These disk files
WILL NOT be automatically purged upon program execution termination (normal or otherwise). Temporary sortwork files will be named “cob*.tmp”, in case you want to delete them yourself or from within your program uponsort termination.

5.

If you specify a specific filename in the sort file’s SELECT, it will be ignored.

5.3. General Format for Data Descriptions
Figure 5-5 - General Data Description Format

level-number

The syntax
skeleton shown
here describes
the manner inwhich data items
are defined in all
DATA DIVISION
sections except
the SCREENSECTION.

IS EXTERNALIS GLOBAL

identifier-1
FILLER[ REDEFINES identifier-2 ][ PICTURE IS picture-string ][ USAGE IS data-item-usage ][ JUSTIFIED RIGHT ][ BLANK WHEN ZERO ][ BASED ][ ANY LENGTH ][ RENAMES identifier-3 [ THRU identifier-4 ][ VALUE IS [ ALL ] literal-1 ]SIGN ISLEADINGTRAILINGSYNCHRONIZEDOCCURS[ SEPARATE CHARACTER ]
LEFT
RIGHT

integer-1 TIMES
integer-1 TO integer-2 TIMES DEPENDING ON identifier-5
ASCENDINGDESCENDING.
KEY IS identifier-6 ...

...

[ INDEXED BY identifier-7 ... ]1.

Not specifying an identifier name or FILLER immediately after the level number has the same effect as if FILLER
were specified.

2.

As with other COBOL implementations, level numbers are restricted to the following values, with the meanings
shown:
01 – a highest-level data item that may be complete in and of itself (also called an elementary item) or
may be broken down into sub-items (also called a group item). 01-level data items are also frequently
referred to as records or record descriptions.
02-49 – these level numbers are used to define data items that are subcomponents of a higher-level data
item (the numerically lower the level number, the higher the data item is in the overall hierarchy of thedata structure being defined – all structured data must begin with a single 01-level item). All levels 02-49
may be elementary items. All levels 02-48 may also be group items.

06FEB2009 Version

Page 5-4

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

66 – a regrouping of level 02-49 data – the RENAMES clause is the only one allowed for such items.
77 – a data item that is not broken down into sub-items and is not a sub-item of any other data (this is asomewhat obsolete convention as the same can be accomplished using level 01)
There are two additional level numbers (78 and 88) that have very special uses. These are described separately insections 5.5 (78) and 5.4 (88).
3.

Level-66 data items are merely re-groupings of consecutive data items in a structure that are re-grouped in such a
way as to define a group-item name (identifier-1) by which they all may be referenced.

4.

The PICTURE clause defines the class (numeric, alphabetic or alphanumeric) of the data that may be contained by
the data item being defined. A PICTURE also (sometimes in conjunction with USAGE) defines the amount ofstorage reserved for the data item. The three basic class-specification PICTURE symbols have the following uses:
Figure 5-6 - Data Class-Specification PICTURE Symbols (A/X/9)

Basic
Symbol9
A
X

Meaning and Usage
Defines a spot reserved for a single decimal digit. The actual amount of storage occupied will
depend on the specified USAGE.
Defines a place reserved for a single alphabetic character (“A”-“Z”, “a”-“z”). Each “A” represents asingle byte of storage.
Defines a place reserved for a single character of storage. Each “X” represents a single byte ofstorage.

These three symbols are used repeatedly in a PICTURE clause to define how many of each class of data may becontained within the field. For example:
PIC 9999

Allocates a data item that can store four-digit positive numbers (we’ll see shortly how negativevalues can be accounted for). If the USAGE of the field is DISPLAY (the default), four bytes ofstorage will be allocated and each byte may contain the character “0”, “1”, “2”, … , “8” or “9”.
There is no run-time enforcement of the fact that only digits are allowed. A compilation-time
WARNING will be issued if literal value that violates the digits-only rule is MOVEd to the field. A
run-time violation is detectable using a class condition test (see section 6.1.4.2.2).

PIC 9(4)Identical to the above – a repeat count enclosed within parenthesis can be used with any PICTURE
symbols that allows repetition.

PIC X(10)This data item can hold a string of any ten characters.

PIC A(10)This data item can hold a string of any ten letters. There is no enforcement of the fact that only
letters are allowed, but a violation is detectable via a class condition test (see section 6.1.4.2.2).

PIC AA9(3)AThis is exactly the same as specifying X(6), but it documents the fact that values should be twoletters followed by 3 digits followed by a single letter. There is no enforcement and no capabilityof detecting violations other than a “brute force” check by character position.

Data items containing “A” or “X” PICTURE symbols cannot be used in arithmetic calculations.
In addition to the above Figure 5-7 shows the numeric option PICTURE symbols that may be used with “PIC 9”
data items:

06FEB2009 Version

Page 5-5

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

Figure 5-7 - Numeric Option PICTURE Symbols (P/S/V)

Numeric
OptionSymbolP

Meaning and Usage

Defines an implied digit position that will be considered to be a 0 when the data item is referenced
at run-time. This symbol is used to allow data items that will contain very large values to beallocated using less storage by assuming a certain number of trailing zeros (one per “P”) to exist at
the end of values.
All computations and other operations performed against such a data item will behave as if thezeros were actually there.
When values are stored into such a field they will have the digit positions defined by the “P”
symbols stripped from the values as they are stored.
For example, let’s say you need to allocate a data item that contains however many millions ofdollars of revenue your company has in gross revenues this year:
01

Gross-Revenue

PIC 9(9).

In which case 9 bytes of storage will be reserved. The values 000000000 thru 999999999 will
represent the gross-revenues. But, if only the millions are tracked (meaning the last six digits arealways going to be 0), you could define the field as:
01

Gross-revenue

PIC 9(3)P(6).

Whenever Gross-Revenue is referenced in the program, the actual value in storage will be treatedas if each P symbol (6 of them, in this case) were a zero.
If you wanted to store the value 128 million into that field, you would do so as if the “P”s were
“9”s:MOVE 128000000 TO Gross-Revenue.

S

V

5.

This symbol, which if used must be the very first symbol in the PICTURE value, indicates thatnegative values are possible for this data item. Without an “S”, any negative values stored into thisdata item via a MOVE or arithmetic statement will have the negative sign stripped from it (in effectbecoming the absolute value).
This symbol is used to define where an implied decimal-point (if any) is located in a numeric item.
Just as there may only be a single decimal point in a number so may there be no more than one“V” in a PICTURE. Implied decimal points occupy no space in storage – they just specify how values
are used. For example, if the value “1234” is in storage in a field defined as PIC 999V9, that value
would be treated as 123.4 in any statements that referenced it.

The SIGN clause, allowable only for USAGE DISPLAY numeric data items, specifies how an “S” symbol will beinterpreted. Without the SEPARATE CHARACTER option, the sign of the data item’s value will be encoded bytransforming the last (TRAILING) or first (LEADING) digit as follows:
Figure 5-8 - Sign-Encoding CharactersFirst/Last
Digit
0
1
2
3
4
5
6
7
8
9

06FEB2009 Version

Encoded ValueFor POSITIVE
0
1
2
3
4
5
6
7
8
9

Encoded Value
For NEGATIVE
p
q
r
s
t
u
v
w
x
y

Page 5-6

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

If the SEPARATE CHARACTER clause is used, then an actual “+” or “-“ sign will be inserted into the field’s value as
the first (LEADING) or last (TRAILING) character.
6.

OpenCOBOL supports all standard COBOL PICTURE editing symbols, namely “$”, comma, asterisk (*), decimalpoint, CR, DB, + (plus), - (minus), “B”, “0” (zero) and “/”, as follows:
Figure 5-9 - Numeric Editing PICTURE Symbols

Editing
Symbol- (minus)

Meaning and Usage
This symbol must be used either at the very beginning of a PICTURE or at the very end. If “-“ is used, noneof “+”, “CR” or “DB” may be used. It is used to edit numeric values.
Multiple consecutive “-“ symbols are allowed only at the very beginning of the field. This is called afloating minus sign.
Each “-“ symbol will count as one character position in the size of the data item.
If only a single “-“ symbol is specified, that symbol will be “replaced” by a “-“ if the value moved to thefield is negative, or a SPACE otherwise.
If a floating minus sign is used, think of the editing process as if it worked like this:
1. Determine what the edited value would be if each “-“ were actually a “9”.
2. Locate the digit in the edited result that corresponds to the right-most “-“ and scan the edited value back to the leftfrom that point until you come to a “0” that has nothing but “0” characters to the left of it.
3. Replace that “0” with a “-“ if the value moved to the field is negative or a SPACE otherwise.
4. Replace all remaining “0” characters to the left of that position by SPACES.

Some examples (the symbol b denotes a space):
If this value…

10$…is moved to a field with… this value in storage will
this PICTURE…
result:
b017
17
-999
-017
-17
-999
bbbb265265-----99bbb-265-265-----99051b
51
999051-51
999This symbol must be only be used at the very beginning of a PICTURE except that a “+” or “-“ may appear
to the left of it. It is used to edit numeric values.
Multiple consecutive “$“ symbols are allowed. This is called a floating currency symbol.
Each “$“ symbol will count as one character position in the size of the data item.
If only a single “$“ symbol is specified, that symbol will be inserted into the edited value at that position
unless there are so many significant digits to the field value that the position occupied by the “$” is needed
to represent a leading non-zero digit. In such cases, the “$” will be treated as a “9”.
If a floating currency sign is used, think of the editing process as if it worked like this:
1. Determine what the edited value would be if each “$“ were actually a “9”.
2. Locate the digit in the edited result that corresponds to the right-most “$“ and scan the edited value back to the leftfrom that point until you come to a “0” that has nothing but “0” characters to the left of it.
3. Replace that “0” with a “$“.
4. Replace all remaining “0” characters to the left of that position by SPACES.

Some examples (the symbol b denotes a space):
If this value…
17
265

10

…is moved to a field withthis PICTURE…
$999$$$$$99… this value in storage will
result:$017
bbb$265

The default currency sign used is “$”. Other countries use different currency signs. The SPECIAL-NAMES paragraph(see section 4.1.4) allows any symbol to be defined as a currency symbol. If the currency sign is defined to thecharacter ‘#’, for example, then you would use the ‘#’ character as a PICTURE editing symbol.

06FEB2009 Version

Page 5-7

OpenCOBOL 1.1 Programmers Guide
Editing
Symbol* (asterisk)

DATA DIVISION
Meaning and Usage

This symbol must be only be used at the very beginning of a PICTURE except that a “+” or “-“ may appear
to the left of it. It is used to edit numeric values.
Multiple consecutive “*“ symbols are not only allowed, but are the typical usage. This is called a floating
check protection symbol.
Each “*“ symbol will count as one character position in the size of the data item.
Think of the editing process as if it worked like this:
1. Determine what the edited value would be if each “*“ were actually a “9”.
2. Locate the digit in the edited result that corresponds to the right-most “*“ and scan the edited value back to the leftfrom that point until you come to a “0” that has nothing but “0” characters to the left of it.
3. Replace that “0” with a “*“.
4. Replace all remaining “0” characters to the left of that position by “*” also.

An example:
If this value…

,
11(comma)…is moved to a field with… this value in storage will
this PICTURE…
result:****265265*****99
Each comma (,) in the PICTURE string represents a character position into which the character “,” will beinserted. This character position is counted in the size of the item. The “,” symbol is a “smart symbol”
capable of masquerading as the floating symbol to its left and right should there be insufficient digits ofprecision to the numeric value being edited to require the insertion of a “,” character.
For example (the symbol b denotes a space):
If this value…

. (period)11…is moved to a field with… this value in storage will
this PICTURE…
result:bbbbbbb$17
17$$,$$$,$99
bbbbbb$265
265$$,$$$,$99
bbbb$1,456
1456$$,$$$,$99
This symbol inserts a decimal point into the edited value at the point where an implied decimal point exists
in the value. It is used to edit numeric values. Note that the period specified at the end of every data
item definition IS NOT treated as an editing symbol!
An example:
01 Edited-Value
PIC 9(3).99.
01 Payment
PIC 9(3)V99 VALUE 152.19.
...
MOVE Payment TO Edited-Value.
DISPLAY Edited-Value.

/ (slash)Will display 152.19
This symbol – usually used when editing dates for printing – inserts a “/” character into the edited value.
The inserted “/” character will occupy a byte of storage in the edited result.
An example:01…

+ (plus)

Edited-Date

PIC 99/99/9999.

MOVE 08182009 TO Edited-Date.
DISPLAY Edited-Date.

The displayed value will be 08/18/2009.
This symbol must be used either at the very beginning of a PICTURE or at the very end. If “+“ is used, noneof “-”, “CR” or “DB” may be used. It is used to edit numeric values.
Multiple consecutive “+“ symbols are allowed only at the very beginning of the field. This is called afloating plus sign.
Each “+“ symbol will count as one character position in the size of the data item. If only a single “+“symbol is specified, that symbol will be replaced by a “-“ if the value moved to the field is negative, or a “+”

11

If DECIMAL-POINT IS COMMA is specified in the SPECIAL-NAMES paragraph, the meanings and usages of the “.”
and “,” characters will be reversed

06FEB2009 Version

Page 5-8

OpenCOBOL 1.1 Programmers Guide
Editing
SymbolDATA DIVISION
Meaning and Usageotherwise.
If a floating plus sign is used, think of the editing process as if it worked like this:
1. Determine what the edited value would be if each “+“ were actually a “9”.
2. Locate the digit in the edited result that corresponds to the right-most “+“ and scan the edited value back to the leftfrom that point until you come to a “0” that has nothing but “0” characters to the left of it.
3. Replace that “0” with a “-“ if the value moved to the field is negative or a “+” otherwise.
4. Replace all remaining “0” characters to the left of that position by SPACES.

Some examples (the symbol b denotes a space):
If this value…

0 (zero)B…is moved to a field with… this value in storage will
this PICTURE…
result:
+017
17
+999
-017
-17
+999
bbb+265265+++++99bbb-265-265+++++99
051+
51
999+
-51
999051This symbol inserts a “0” character into the edited value. The inserted “0” character will occupy a byte ofstorage in the edited result.
An example:
01 Edited-Phone-Number PIC 9(3)B9(3)B9(4).
…
MOVE 5185551212 TO Edited-Phone-Number.
DISPLAY Edited-Phone-Number.
The displayed value will be 518 555 1212.
This symbol inserts a SPACE character into the edited value. The inserted SPACE character will occupy abyte of storage in the edited result.
An example:
01…

Edited-Phone-Number

PIC 9(3)B9(3)B9(4).

MOVE 5185551212 TO Edited-Phone-Number.
DISPLAY Edited-Phone-Number.

CR

The displayed value will be 518 555 1212.
This symbol must be used only at the very end of a PICTURE. If “CR“ is used, none of “-”, “+” or “DB” may
be used. It is used to edit numeric values.
Multiple “CR“ symbols are not allowed in one PICTURE clause.
A “CR“ symbol will count as two character positions in the size of the data item.
If the value moved into the field is negative, the characters “CR” will be inserted into the edited value,otherwise two SPACES will be inserted.
Some examples (the symbol b denotes a space):
This value…

DB…is moved to a field with…resulting in this value inthis PICTURE…
storage:
17
99CR
17bb
-17
99CR
17CR
This symbol must be used only at the very end of a PICTURE. If “DB“ is used, none of “-”, “+” or “CR” may
be used. It is used to edit numeric values.
Multiple “DB“ symbols are not allowed in one PICTURE clause.
A “DB“ symbol will count as two character positions in the size of the data item.
If the value moved into the field is negative, the characters “DB” will be inserted into the edited value,otherwise two SPACES will be inserted.
Some examples (the symbol b denotes a space):
This value…

06FEB2009 Version…is moved to a field with…resulting in this value inPage 5-9

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

Editing
SymbolZ

Meaning and Usage
this PICTURE…
storage:
17
99DB
17bb
-17
99DB
17DB
This symbol must be only be used at the very beginning of a PICTURE except that a “+” or “-“ may appear
to the left of it. It is used to edit numeric values.
Multiple consecutive “Z“ symbols are not only allowed, but are the typical manner in which this editing
symbol is used. This is called a floating zero suppression.
Each “Z“ symbol will count as one character position in the size of the data item.
Think of the editing process as if it worked like this:
1. Determine what the edited value would be if each “Z“ were actually a “9”.
2. Locate the digit in the edited result that corresponds to the right-most “Z“ and scan the edited value back to the leftfrom that point until you come to a “0” that has nothing but “0” characters to the left of it.
3. Replace that “0” with a SPACE.
4. Replace all remaining “0” characters to the left of that position by SPACES.

Some examples (the symbol b denotes a space):
This value…
17
265…is moved to a field withthis PICTURE…
Z999
ZZZZZ99…resulting in this value instorage:b017
bbbb265

No more than one editing symbol may be used in a floating manner in the same PICTURE clause.
5.

Numeric data items containing editing symbols are referred to as numeric edited fields. Such data items may
receive values in the various arithmetic statements but may not be used as sources of data in those samestatements. The statements in question are ADD (section 6.5), COMPUTE(section 6.11), DIVIDE(section 6.15),
MULTIPLY (section 6.29) and SUBTRACT (section 6.44).

6.

By specifying the EXTERNAL clause, the data item being defined is capable of being shared between all program
units (either separately compiled or compiled in the same compilation unit) in a given execution thread, provided
the data item is described (with an EXTERNAL clause) in each compilation unit requiring it.

7.

By specifying the GLOBAL clause, the data item is capable of being shared between all program units in the same
compilation unit in a given execution thread, provided the data item is described with an GLOBAL clause in eachprogram unit requiring it and provided all program-units using GLOBAL are nested within the first program-unit
defining the data item with GLOBAL– see section 2.1 for a discussion of program unit nesting.

8.

The EXTERNAL clause may only be specified at the 77 or 01 level.

9.

An EXTERNAL item must have a data name (i.e. identifier-1) and that name cannot be FILLER.

10. EXTERNAL cannot be combined with GLOBAL, REDEFINES or BASED.
11. The VALUE clause is ignored on EXTERNAL data items or on any data items defines as subordinate to an EXTERNAL
data item.
12

12. The OCCURS clause is used to create a data structure called a table that repeats multiple times. For example:
05 QUARTLY-REVENUE OCCURS 4 TIMES PIC 9(7)V99.

Will allocate the following:
QUARTLY-REVENUE (1)QUARTLY-REVENUE (2)QUARTLY-REVENUE (3)QUARTLY-REVENUE (4)Each occurrence is referenced using the subscript syntax (a numeric literal, arithmetic expression or numeric
identifier enclosed within parenthesis) shown in the diagram. The OCCURS clause may be used at the group leveltoo, in which case the entire group structure repeats, as follows:

12

Other programming languages with which you might be familiar refer to this sort of structure as an array.

06FEB2009 Version

Page 5-10

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

05 X OCCURS 3 TIMES.
10 A
PIC X(1).
10 B
PIC X(1).
10 C
PIC X(1).

A (1)

X (1)
B (1)

C (1)

A (2)

X (2)
B (2)

C (2)

A (3)

X (3)
B (3)

C (3)

See sections 6.1.1 (Table References), 6.38 (SEARCH), 6.40 (SORT) as well as item #28 below for more information
about tables.
13. The optional DEPENDING ON clause can be added to an OCCURS to create a variable-length table. Such tables willbe allocated out to the maximum size specified as integer-2. At execution time the value of identifier-5 will
determine how many of the table elements are accessible.
14. The OCCURS clause cannot be specified in a data description entry that has a level number of 01, 66, 77, or 88.
15. VALUE specifies an initial compilation-time value that will be assigned to the storage occupied by the data item inthe program object code generated by the compiler. If the optional “ALL” clause is used, it may only be used withan alphanumeric literal value; the value will be repeated as needed to completely fill the data item. Here aresome examples with and without ALL:PIC X(5) VALUE “A” – will have the value “A”,SPACE,SPACE,SPACE,SPACEPIC X(5) VALUE ALL “A” – will have the value “A”,”A”,”A”,”A”,”A”
PIC 9(3) VALUE 1 – will have the value 001
PIC 9(3) VALUE ALL “1” – will have the value 111

16. The ASCENDING KEY, DESCENDING KEY and INDEXED BY clauses will be discussed in section 6.39 (SEARCH).
17. The BASED and ANY LENGTH clauses cannot be used together.
18. The JUSTIFIED RIGHT clause, valid only on an alphabetic (PIC A) or alphanumeric (PIC X) item, will cause values
shorter than the length of the data item to be right-justified and space-filled when they are MOVEd into the data
item.
19. Data items declared with BASED are allocated no storage at compilation time. At run-time, the ALLOCATE verb isused to allocate space for and (optionally) initialize such items.
20. Data items declared with the ANY LENGTH attribute have no fixed compile-time length. Such items may only be
defined in the LINKAGE SECTION as they may only serve as subroutine argument descriptions. ANY LENGTH items
must have a PICTURE clause that specifies exactly one A, X or 9 symbol.
21. The BLANK WHEN ZERO clause, when used on a numeric item, will cause that item’s value to be automaticallytransformed into SPACES if a value of 0 is ever MOVEd to the item.
22. The REDEFINES clause causes identifier-1 to occupy the same physical storage space as identifier-2, so that storage
may be defined in a different manner with a (probably) different structure. The following must all be true in order
to use REDEFINES:a.

The level number of identifier-2 must be the same as that of identifier-1.

b.

The level number of identifier-2 (and identifier-1) cannot be 66, 77, 78 or 88.

c.

If “n” represents the level number of identifier-2 (and identifier-1), then no other data items with level
number “n” may be defined between identifier-1 and identifier-2.

d.

The total allocated size of identifier-1 must be the same as the total allocated size of identifier-2.

e.

No OCCURS clause may be defined on identifier-2. There may – however – be items defined with OCCURS
clauses subordinate to identifier-2.

f.

No VALUE clause may be defined on identifier-2. No data items subordinate to identifier-2 may have VALUE
clauses, with the exception of level-88 condition names.

06FEB2009 Version

Page 5-11

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

23. The following table summarizes the various possible USAGE specifications:Figure 5-10 - Summary of USAGE Specifications

USAGE

Allocated Space (Bytes)

Storage
FormatAllowsnegative
Values?

Used
w/
PIC?

Identical To

BINARY

Depends on number of “9”s in PICTURE
and the ”binary-size” setting of theconfiguration file (section 7.1.8) used tocompile the program

Most-compatible If PICTURE– see #24
contains“S”

Yes

BINARY-CHAR or
BINARY-CHAR SIGNEDOne byte

Native – see #24

Yes

No

BINARY-CHAR UNSIGNEDOne byte

Native – see #24

No – see#25

No

BINARY-C-LONG or
BINARY-C-LONG SIGNED

Allocates the same amount of storage as Native – see #24
does the C language “long” data type onthat computer; typically this is 32 bits but
it could be 64 bits

Yes

No

BINARY-C-LONG UNSIGNED

Allocates the same amount of storage as Native – see #24
does the C language “long” data type onthat computer; typically this is 32 bits but
it could be 64 bits

No – see#25

No

BINARY-DOUBLE or
BINARY-DOUBLE SIGNED

Allocates a “traditional” double-word ofstorage (64 bits)

Native – see #24

Yes

No

BINARY-DOUBLE UNSIGNED

Allocates a “traditional” double-word ofstorage (64 bits)

Native – see #24

No – see#25

No

BINARY-LONG or
BINARY-LONG SIGNED

Allocates a word of storage (32 bits)

Native – see #24

Yes

No

SIGNED-LONG,
SIGNED-INT

BINARY-LONG UNSIGNED

Allocates a word of storage (32 bits)

Native – see #24

No – see#25

No

UNSIGNED-LONG,UNSIGNED-INT

BINARY-SHORT or
BINARY-SHORT SIGNED

Allocates a half-word of storage (16 bits)

Native – see #24

Yes

No

SIGNED-SHORTBINARY-SHORT UNSIGNED

Allocates a half-word of storage (16 bits)

Native – see #24

No – see#25

No

UNSIGNED-SHORTCOMPUTATIONAL

Depends on number of “9”s in PICTURE
and the ”binary-size” setting of theconfiguration file (section 7.1.8) used tocompile the program

Most-compatible If PICTURE– see #24
contains“S”

Yes

BINARY, COMPUTATIONAL-4

COMPUTATIONAL-1

Allocates a word of storage (32 bits)

Single-precision
floating-point

Yes

No

COMPUTATIONAL-2

Allocates a double-word of storage (64bits)

Double-precision Yes
floating-pointNo

COMPUTATIONAL-3

Allocates 4 bits per “9” in the PICTURE
plus a (trailing) 4-byte field for the sign,rounded up to the nearest byte,
SYNCHRONIZED RIGHT (see #27)

Packed decimal – If PICTURE
see #26
contains“S”

No

PACKED-DECIMALCOMPUTATIONAL-4

Depends on number of “9”s in PICTURE
and the ”binary-size” setting of theconfiguration file (section 7.1.8) used tocompile the program

Most-compatible If PICTURE– see #24
contains“S”

Yes

BINARY, COMPUTATIONALCOMPUTATIONAL-5

Depends on number of “9”s in PICTURE
and the ”binary-size” setting of theconfiguration file (section 7.1.8) used tocompile the program

If PICTURE
contains“S”

Yes

06FEB2009 Version

COMPUTATIONAL,COMPUTATIONAL-4

Page 5-12

OpenCOBOL 1.1 Programmers Guide

USAGE

Allocated Space (Bytes)

DATA DIVISION

Storage
FormatAllowsnegative
Values?

Most-compatible If PICTURE– see #24
contains
“S”

Used
w/
PIC?

Identical To

COMPUTATIONAL-X

Allocates bytes based upon the numberof “9”s in the PICTURE according to the”binary-size” setting of “1—8” in theconfiguration file used to compile theprogram. See section 7.1.8 for an
illustration of how a value of “1—8” for“binary-size” would work.

DISPLAY

Depends on PICTURE – One character13
Characters
per X, A, 9, period, $, Z, 0, *, S (ifSEPARATE CHARACTER specified), +, - orB symbol in PICTURE; Add 2 more bytes if
DB or CR symbol used

If PICTURE
contains
“S”

Yes

INDEX

Allocates a word of storage (32 bits)

No

No

NATIONAL

USAGE NATIONAL, while syntactically recognized, is not supported by OpenCOBOL

PACKED-DECIMAL

Allocates 4 bits per “9” in the PICTURE
plus a (trailing) 4-byte field for the sign,rounded up to the nearest byte,
SYNCHRONIZED RIGHT (see #27)

Packed decimal – If PICTURE
see #26
contains“S”

No

POINTER

Allocates a word of storage (32 bits)

Native – see #24

No

No

PROGRAM-POINTER

Allocates a word of storage (32 bits)

Native – see #24

No

No

SIGNED-INT

Allocates a word of storage (32 bits)

Native – see #24

Yes

No

BINARY-LONG-SIGNED,SIGNED-LONG

SIGNED-LONG

Allocates a word of storage (32 bits)

Native – see #24

Yes

No

BINARY-LONG SIGNED,SIGNED-INT

SIGNED-SHORT

Allocates a half-word of storage (16 bits)

Native – see #24

Yes

No

BINARY SHORT SIGNEDUNSIGNED-INT

Allocates a word of storage (32 bits)

Native – see #24

No – see#25

No

BINARY-LONG UNSIGNED,UNSIGNED-LONG

UNSIGNED-LONG

Allocates a word of storage (32 bits)

Native – see #24

No – see#25

No

BINARY-LONG UNSIGNED,UNSIGNED-INT

UNSIGNED-SHORT

Allocates a half-word of storage (16 bits)

Native – see #24

No – see#25

No

BINARY-SHORT UNSIGNEDNative – see #24

Yes

COMPUTATIONAL-3

24. Binary data can be stored in either a “Big-Endian” or “Little-Endian” form.
Big-endian data allocation calls for the bytes that comprise a binary item to be allocated such that the leastsignificant byte is the right-most byte. For example, a four-byte binary item having a value of decimal 20 would
be big-endian allocated as 00000014 (shown in hexadecimal notation).
Little-endian data allocation calls for the bytes that comprise a binary item to be allocated such that the leastsignificant byte is the left-most byte. For example, a four-byte binary item having a value of decimal 20 would be
little-endian allocated as 14000000 (shown in hexadecimal notation).
All CPUs are capable of “understanding” big-endian format, which makes it the “most-compatible” form of binarystorage across computer systems.
Some CPUs – such as the Intel/AMD i386/x64 architecture processors such as those used in most Windows PCs –prefer to process binary data stored in a little-endian format. Since that format is more efficient on thosesystems, it is referred to as the “native” binary format.

13

In this context, one character is the same as one byte, unless you’ve built yourself an OpenCOBOL system that uses
Unicode (unlikely), in which case 1 character = two bytes.

06FEB2009 Version

Page 5-13

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

On a system supporting only one format of binary storage (generally, that would be big-endian), the terms “mostefficient” format and “native format” are synonymous.
25. Binary data items that have the UNSIGNED attribute explicitly coded, or that do not have an “S” symbol in theirPICTURE clause cannot preserve negative values that may be stored into them. Attempts to store a negativevalue into such a field will actually result in the binary representation of the negative number actually being
interpreted as if it were a positive number. For example, on a computer running an Intel or AMD processor, thevalue of -3 expressed as a binary value would be 111111012. If that value is moved into a USAGE BINARY-CHAR
UNSIGNED field, it would actually be interpreted as 0111111012, or 253.
26. Packed-decimal (i.e. USAGE COMP-3 or USAGE PACKED-DECIMAL) data is stored as a series of bytes such thateach byte contains two 4-bit fields with each field representing a “9” in the PICTURE and storing a single decimal
digit. The last byte will always contain a single 4-bit digit (corresponding to a “9” and a 4-bit sign indicator (always
present, even if no “S” symbol is used). The first byte may contain an unused left-most 4-bit field, depending on
how many “9” symbols were used in the PICTURE. The sign indicator will have a value of a hexadecimal A thru F,
with values of A, C, E and F indicating a positive sign and B or D representing a negative value. Therefore, a PIC
S9(3) COMP-3 packed-decimal field with a value of -15 would be stored internally as a hexadecimal 015D (orperhaps a 015B). If you attempt to store a negative number into a packed decimal field that has no “S” in its
PICTURE, the absolute value of the negative number will actually be stored.
27. The SYNCHRONIZED clause (which may be abbreviated as SYNC) optimizes the storage of binary numeric items tostore them in such a manner as to make it as fast as possible for the CPU to fetch them. This synchronization is
performed as follows:a.

If the binary item occupies one byte of storage, no synchronization is performed.

b.

If the binary item occupies two bytes of storage, the binary item is allocated at the next half-word boundary.

c.

If the binary item occupies four bytes of storage, the binary item is allocated at the next word boundary.

d.

If the binary item occupies four bytes of storage, the binary item is allocated at the next word boundary.

Here’s an example of a group item’s storage allocation with and without using SYNCHRONIZED:
Figure 5-11 - Effect of the SYNCHRONIZED Clause

01

Group-Item-1.
05 A
05 B
05 C
05 D
05 E
05 F

01
PIC X(1).
USAGE BINARY-SHORT.
PIC X(2).
USAGE BINARY-LONG.
PIC X(3).
USAGE BINARY-DOUBLE.

Group-Item-2.
05 A
05 B
SYNC
05 C
05 D
SYNC
05 E
05 F
SYNC

PIC X(1).
USAGE BINARY-SHORT.
PIC X(2).
USAGE BINARY-LONG.
PIC X(3).
USAGE BINARY-DOUBLE.

½
½
½
½
½
½
Word Word Word Word Word Word Word Word Word Word Word Word Word

Group-Item-1
Group-Item-2

A
A

B

C
B

D
C

Bytes
Double
Word

E

F

D

E

F

Bytes
DoubleWord

Bytes
DoubleWord

DoubleWord

The grey blocks represent the unused “slack” bytes that are allocated in the Group-Item-2 structure because of
the SYNC clauses.
06FEB2009 Version

Page 5-14

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

The LEFT and RIGHT options to the SYNCHRONIZED clause are recognized for syntactical compatibility with other
COBOL implementations, but are otherwise non-functional.
28. Initializing a table is one of the trickier aspects of COBOL data definition. There are basically three standard
techniques and a fourth that people familiar with other COBOL implementations but new to OpenCOBOL may findinteresting. So, here are the three “standard” approaches:a.

Don’t bother worrying about it at compile-time. Use the INITIALIZE verb to initialize all data item occurrences
in a table (at run-time) to their data-type-specific default values (numerics: 0, alphabetic and alphanumerics:
SPACES).

b.

Initialize small tables at compile time by including a VALUE clause on the group item that serves as a “parent”
to the table, as follows:
05c.

SHIRT-SIZES
10 SHIRT-SIZE-TBL
15 SST-SIZE
15 SST-NECK

VALUE “S 14M 15L 16XL17”.
OCCURS 4 TIMES.
PIC X(2).
PIC 9(2).

Initialize tables of almost any size at compilation time by utilizing the REDEFINES clause:
05

05

SHIRT-SIZE-VALUES.
10 PIC X(4)10 PIC X(4)10 PIC X(4)10 PIC X(4)SHIRT-SIZES
10 SHIRT-SIZE-TBL
15 SST-SIZE
15 SST-NECK

VALUE “S 14”.
VALUE “M 15”.
VALUE “L 16”.
VALUE “XL17”.
REDEFINES SHIRT-SIZE-VALUES.
OCCURS 4 TIMES.
PIC X(2).
PIC 9(2).

Admittedly, the table shown in #28c is much more verbose than #28b. What is good about #28c, however, is thatyou can have as many FILLER/VALUE items as you need for a larger table (and those values can be as long asnecessary!
Many COBOL compilers do not allow the use of VALUE and OCCURS on the same data item; additionally, they
don’t allow a VALUE clause on a data item subordinate to an OCCURS. OpenCOBOL, however, has neither ofthese restrictions! Observe the following example, which illustrates the fourth manner in which tables may beinitialized in OpenCOBOL:
05

X
10 A
10 B
10 N

OCCURS 6 TIMES.
PIC X(1) VALUE „?‟.
PIC X(1) VALUE „%‟.
PIC 9(2) VALUE 10.

In this example, all six “A” items will be initialized to “?”, all six “B” items will be initialized to “%” and all six “N”
items will be initialized to 10. It’s not clear exactly how many times this sort of initialization will be useful, but it’s
there if you need it.

5.4. Condition Names
Figure 5-12 - Level-88 Condition Name Description Syntax

Condition names are
Boolean (i.e. “TRUE” /“FALSE”) data items.

88 condition-name-1

VALUE ISVALUES ARE

literal-1

THROUGH
THRU

literal-2

...

...

[ WHEN SET TO FALSE IS literal-3 ]1.

Condition names are always defined subordinate to another data item. That data item must be an elementary
item.

2.

Condition names do not occupy any storage.

3.

The VALUE(s) specified for the condition name specify the specific values and/or ranges of values of the parent
elementary data item that will cause the condition name to have a value of TRUE.

06FEB2009 Version

Page 5-15

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION4.

The optional FALSE clause defines an explicit value that will be assigned to the parent elementary data item
should the SET statement ever be used to set the condition-name-1 to FALSE. See section 6.39.6 for more
information on how the SET statement can be used to specify the TRUE/FALSE value of a condition name.

5.

See section 6.1.4.2.1 for a general discussion of condition names.

5.5. Constant Descriptions
Figure 5-13 - Level-78 Constant Description Syntax

78 identifier-1 VALUE IS literal-1 .
01 identifier-2 CONSTANT [ IS GLOBAL ] ASliteral-2
LENGTH OF identifier-3
BYTE-LENGTH OF identifier-4.

Data descriptions ofthese forms do not
actually allocate any
storage, but instead
are a means ofassociating a namewith an alphanumericor numeric literal.

1.

The two forms are essentially identical when defining a value of a literal. Defining a constant whose value is thelength of another item is – as you can see – possible only using the “01 CONSTANT” form.

2.

The GLOBAL clause, while recognized syntactically, is currently unsupported by OpenCOBOL and should generate
a compiler warning if used. As of the Feb 06 2009 packaging of OpenCOBOL 1.1, however, its use will actuallyabort the compiler.

06FEB2009 Version

Page 5-16

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

5.6. Screen Descriptions
Figure 5-14 - SCREEN SECTION Data Item Description Syntax

The syntax skeleton
shown here describes
how data items aredefined in the SCREENSECTION.

level-number

identifier-1
FILLER[ JUSTIFIED RIGHT ]These data items areused via special formsof the ACCEPT (section
6.4) and DISPLAY(section 6.14.4) verbs
to create TUI (that is“Textual User
Interface” programs.

[ BLANK WHEN ZERO ][ OCCURS integer-1 TIMES ][ BELL | BEEP ][ AUTO | AUTO-SKIP | AUTOTERMINATE ][ UNDERLINE ][ OVERLINE ][ SECURE ][ REQUIRED ][ FULL ][ PROMPT ][ REVERSE-VIDEO ][ BLANK LINE | SCREEN ][ ERASE EOL | EOS ]LEADING
SIGN IS TRAILING[ SEPARATE CHARACTER ]LINE NUMBER IS [ PLUS ]integer-2
identifier-2

COLUMN NUMBER IS [ PLUS ]integer-3
identifier-3

FOREGROUND-COLOR IS

integer-4
identifier-4

BACKGROUND-COLOR IS

integer-5
identifier-5

PICTURE IS picture-string

VALUE IS literal-1

HIGHLIGHTLOWLIGHT[ BLINK ]USING identifier-6
identifier-7
FROM
literal-2
TO identifier-8.

1.

Data items with level numbers 66, 78 and 88 may be used in the SCREEN SECTION; they have the same syntax,
rules and usage as they do in the other DATA DIVISION sections.

2.

Use the BELL or BEEP clauses (they are synonymous) to cause an audible tone to occur when the screen item is
DISPLAYed.

06FEB2009 Version

Page 5-17

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

3.

The AUTO clause (the three forms are all equivalent) will cause the cursor to automatically advance to the next
input-enabled field if the field having the AUTO clause is completely filled.

4.

The UNDERLINE and OVERLINE clauses are essentially non-functional on Windows systems as those video
attributes are not currently supported by the Windows console window API. The UNDERLINE clause will have aneffect, however, as it will make the foreground color of the field blue regardless of the value specified (or implied)by the FOREGROUND-COLOR attribute. Whether or not these clauses operate on UNIX systems will depend upon
the video attributes of the terminal output device being used.

5.

The SECURE attribute may only be used on a field allowing data entry (USING or TO). This attribute will cause alldata entered into the field to appear as asterisks.

6.

The REQUIRED and FULL attributes, while syntactically acceptable, are non-functional.

7.

The PROMPT attribute is superfluous in OpenCOBOL as its behavior is assumed on all input fields.

8.

The REVERSE-VIDEO attribute reverses the meaning of the specified or implied FOREGROUND-COLOR andBACKGROUND-COLOR attributes.

9.

The BLANK clause will blank-out the screen or line from the point indicated by any LINE and/or COLUMN clause on
the data item. In addition, the console window foreground and background colors will be set to whatever is
specified on the item. Use of this clause ANYWHERE within an 01-level item (or its subordinate items, if any) willcause ALL displayed fields ANYWHERE within that 01-level item (or its subordinate items) to be invisible.

14

10. The ERASE clause will erase the remainder of the console window’s current line (EOL) or the console window
screen (EOS) starting at the end of the field having the ERASE clause to be erased and to have its colors set to theforeground and background colors in effect for the field containing the ERASE clause.
11. Without LINE or COLUMN clauses, SCREEN SECTION fields will display on the console window beginning at
whatever line/column coordinate is stated or implied by the ACCEPT or DISPLAY statement that presents thescreen item. After a field is presented to the console window, the next field will be presented immediately
following that field.
The LINE and COLUMN clauses provide a means of explicitly stating where a field should be presented on the
console window. Coordinates may be stated on an absolute basis (i.e. “LINE 1 COLUMN 5”) or on a relative basis
based upon the end of the previously-presented field (i.e. “LINE PLUS 2 COLUMN PLUS 1”). Identifiers or literals
may be used to define the absolute or relative position. If identifiers are used, they must be PIC 9 items without
editing symbols (any numeric USAGE is allowed except for COMPUTATIONAL-1 or COMPUTATIONAL-2. Note thateither of these floating-point USAGE specifications will be accepted, but will produce unpredictable results.
Fields do not need to be defined in LINE/COLUMN sequence of their presentation, unless of course you’re relying
on the implicit positioning of screen items by not using LINE and COLUMN.
The TAB and BACK-TAB (Shift-TAB) keys will position the cursor from field to field in the line/column sequence inwhich the fields occur on the console window, regardless of the sequence in which they were defined in the
SCREEN SECTION.
You may abbreviate COLUMN as COL, if you wish.

14

The PROMPT attribute is used to specify that empty input fields will be marked by a non-blank character to ensure
they’re visible. This functionality is ALWAYS on for all editable screen fields in OpenCOBOL (an underscorecharacter is used).

06FEB2009 Version

Page 5-18

OpenCOBOL 1.1 Programmers Guide

DATA DIVISION

12. The FOREGROUND-COLOR and BACKGROUND-COLOR clauses are used to specify the color of text (foreground) or
the screen (background). You specify colors by number (0-7) according to the following:
Figure 5-15 - Screen Color Numbers

Integer
0
1
2
3
4
5
6
7

Color
Black
Blue
Green
Cyan
Red
Magenta
Yellow
White

13. The HIGHLIGHT and LOWLIGHT options control the intensity of text (foreground). This is intended to provide athree-level intensity scheme (LOWLIGHT, nothing-specified, HIGHLIGHT), but the Windows console only supports
two-levels, so LOWLIGHT is the same as leaving this clause off altogether. Using this modifier to the
FOREGROUND-COLOR attribute, you can actually have sixteen text colors, not just eight, as follows:
Figure 5-16 - LOWLIGHT / HIGHLIGHT Effect on Screen Colors

FOREGROUND-COLOR integer
0
1
2
3
4
5
6
7

LOWLIGHT
Black
Dark Blue / Indigo
Dark Green
Dark Cyan
Dark Red
Dark Magenta
Gold / Brown
Light GreyHIGHLIGHT
Dark Grey
Bright Blue
Bright Green
Bright Cyan
Bright Red
Bright Magenta
Yellow
White

14. The BLINK attribute modifies the visual appearance of the BACKGROUND-COLOR specification. The Windows
console does not support blinking, so the visual effect of BLINK in the Windows version of OpenCOBOL is toprovide the same sixteen colors to the BACKGROUND-COLOR palette as are possible with FOREGROUND-COLOR
combined with LOWLIGHT/HIGHLIGHT.
15. Foreground and background color attributes are inheritable from other fields. They are not inherited from theprior field encountered but rather from parent data items (data items with numerically lower level numbers).
Observe the following…
78 Black
VALUE 0.
78 Blue
VALUE 1.
78 Green
VALUE 2.
78 White
VALUE 7.
...
02 XYZ BACKGROUND-COLOR Black FOREGROUND-COLOR Green ...
05 ABC BACKGROUND-COLOR Blue FOREGROUND-COLOR White ...
05 DEF (no BACKGROUND-COLOR or FOREGROUND-COLOR specified) ...

The color of field DEF will be Green-on-White (inherited from XYZ)
16. The VALUE clause is used to define fixed text that cannot be changed.
17. The FROM clause is used to define a field whose contents should come from the specified literal or identifier.
18. The TO clause is used to define a data-entry field with no initial value; when a value is entered, it will be saved tothe specified identifier.
19. The USING clause is a combination of “FROM identifier” and “TO identifier”.

06FEB2009 Version

Page 5-19

OpenCOBOL 1.1 Programmers Guide

06FEB2009 Version

DATA DIVISION

Page 5-20

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6. PROCEDURE DIVISION
6.1. General PROCEDURE DIVISION Components
6.1.1. Table References
COBOL uses parenthesis to specify the subscripts used to reference table entries (tables in COBOL are what otherprogramming languages refer to as arrays).
For example, observe the following data structure which simulates a 4 column by 3 row grid of characters:
01

GRID.
05 GRID-ROW OCCURS 3 TIMES.
10 GRID-COLUMN OCCURS 4 TIMES.
15 GRID-CHARACTERPIC X(1).

A reference to the GRID-CHARACTER shaded in the following diagram:

Would be coded as:
GRID-CHARACTER (2, 3)
Subscripts may be specified as numeric (integer) literals, PIC 9 (integer) data items, USAGE INDEX data items orarithmetic expressions resulting in an integer value involving any combination of these. The ability to use fullarithmetic expressions as table (array) subscripts, while common in many languages, is rare in the COBOL universe.
See section 6.1.4.1 for a discussion of arithmetic expressions.

6.1.2. Qualification of Data Names
COBOL allows data names to be duplicated within a program, provided references to those data names may be madein such a manner as to make those references unique through a process known as qualification.
To see qualification at work, observe the following segments of two data records defined in a COBOL program:
01

01

EMPLOYEE.
05 MAILING-ADDRESS.
10 STREET
10 CITY
10 STATE
10 ZIP-CODE.
15 ZIP-CODE-5
15 FILLERCUSTOMER.
05 MAILING-ADDRESS.
10 STREET
10 CITY
10 STATE
10 ZIP-CODE.
15 ZIP-CODE-5
15 FILLER

PIC X(35).
PIC X(15).
PIC X(2).
PIC 9(5).
PIC X(4).
PIC X(35).
PIC X(15).
PIC X(2).
PIC 9(5).
PIC X(4).

Now, let’s deal with the problem of setting the CITY portion of an EMPLOYEEs MAILING-ADDRESS to “Philadelphia”.
Clearly, the following cannot work because the compiler will be unable to determine which of the two CITY fields you
are referring to:
MOVE “Philadelphia” TO CITY.

We could qualify the reference to CITY as follows, in an attempt to correct the problem:
MOVE “Philadelphia” TO CITY OF MAILING-ADDRESS.

06FEB2009 Version

Page 6-1

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

Unfortunately that too is insufficient because it is still insufficient to identify specifically which CITY is beingreferenced. To truly identify which specific CITY you want, you’d have to code the following:
MOVE “Philadelphia” TO CITY OF MAILING-ADDRESS OF EMPLOYEE.

Now there can be no confusion as to which CITY is being changed. Fortunately, you don’t need to be so specific;
COBOL allows intermediate qualification levels to be omitted. This allows you to specify:
MOVE “Philadelphia” TO CITY OF EMPLOYEE.

If you need to qualify a reference to a table, do so as follows:
identifier-1 OF identifier-2 ( subscript …)
The reserved word “IN” may be used in lieu of “OF”.

6.1.3. Reference Modifiers
Figure 6-1 - Reference Modifier Syntax

identifier-1 [ OF identifier-2 ] [ ( subscript ... ) ]intrinsic-function-reference( start : [ length ] )The COBOL ’85 standard
introduced the concept of areference modifier tofacilitate references to only aportion of a data item;
OpenCOBOL fully supports
reference modification.

The start value indicates the starting character position being referenced (character position values start with 1, not 0
as is the case in some programming languages) and length specifies how many characters are wanted. If no length isspecified, a value equivalent to the remaining character positions from start to the end will be assumed.
Here are a few examples:
CUSTOMER-LAST-NAME (1:3)

references the first three characters of CUSTOMER-LAST-NAMECUSTOMER-LAST-NAME (4:)

references all character positions of CUSTOMER-LAST-NAME from the fourth
onward.

FUNCTION CURRENT-DATE (5:2)

references the current month (see the documentation of the CURRENT-DATE
intrinsic function on page 6-13 for details)

Hex-Digits (Nibble + 1:1)

Assuming that “Nibble” is a numeric data item with a value in the range 0-15, and
Hex-Digits is a PIC X(16) item with a value of “0123456789ABCDEF”, this converts
that numeric value to a hexadecimal digit.

Hex-Digits (Nibble + 1:)

Does the same as the above – if you leave out the length, 1 is assumed; YOU STILL
NEED THE “:” CHARACTER THOUGH.

Array-Element (6) (7:5)

References 5 characters in the 6 occurrence of Array-Element, starting at
character position 7.

thReference modification may be used anywhere an identifier is legal, including serving as the receiving field ofstatements like MOVE, STRING and ACCEPT, to name a few.

6.1.4. Expressions
OpenCOBOL, like other COBOL implementations, supports two basic types of expressions:
Arithmetic expressions, which calculate a numeric result
Conditional Expressions, which calculate a TRUE or FALSE value
Unlike other programming languages, which allow arithmetic values such as 0 and -1 to represent FALSE and TRUE,
respectively, COBOL treats logical TRUE/FALSE values as something different from 0/-1. OpenCOBOL adheres to thispolicy.
06FEB2009 Version

Page 6-2

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.1.4.1. Arithmetic Expressions
Arithmetic expressions are formed using following operators. In complex expressions composed of multiple
operators, a precedence of operation applies whereby those operations having a higher precedence are computed
first before operations with a lower precedence.
Precedence / Operation

Discussion

Figure 6-2 – Unary - Operator Syntax
ST

Precedence: 1 (Highest)--

numeric-literal-1
identifier-1( arith-expr-1 )The unary - operator returns the arithmetic
negation of its single argument, effectively
returning as its value the product of its argument
and -1.

Figure 6-3 – Unary + Operator Syntax
ST

Precedence: 1 (Highest)+

numeric-literal-1
identifier-1( arith-expr-1 )The unary + operator returns the value of its single
argument, effectively returning as its value theproduct of its argument and +1.

Figure 6-4 - Exponentiation Operator Syntax

Precedence: 2

numeric-literal-1
identifier-1( arith-expr-1 )ndnumeric-literal-2
identifier-2( arith-expr-2 )**The value of the left-hand argument raised to thepower indicated by the right-hand argument iscomputed. OpenCOBOL allows the “^” symbol to
be used in lieu of the “**” symbol.

Figure 6-5 - Exponentiation Operator Syntax

Precedence: 3

numeric-literal-1
identifier-1( arith-expr-1 )*rdnumeric-literal-2
identifier-2( arith-expr-2 )The product of the left-hand argument and theright-hand argument is computed.

Figure 6-6 - Division Operator Syntax

Precedence: 3

numeric-literal-1
identifier-1( arith-expr-1 )06FEB2009 Version/rd

numeric-literal-2
identifier-2( arith-expr-2 )The value of the left-hand argument divided by theright-hand argument is computed.

Page 6-3

OpenCOBOL 1.1 Programmers Guide
Precedence / Operation

PROCEDURE DIVISION
Discussion

Figure 6-7 - Addition Operator SyntaxthPrecedence: 4 (Lowest)

numeric-literal-1
identifier-1( arith-expr-1 )numeric-literal-2
identifier-2( arith-expr-2 )+The sum of the left-hand argument and the righthand argument is computed.

Figure 6-8 - Subtraction Operator SyntaxthPrecedence: 4 (Lowest)

numeric-literal-1
identifier-1( arith-expr-1 )–numeric-literal-2
identifier-2( arith-expr-2 )The value of the right-hand argument subtracted
from the left-hand argument is computed.

The COBOL standards require the use of at least one space before and after the exponentiation, multiplication,
division, addition and subtraction operators. This is the best policy to follow when coding expressions as it ensurescompatibility with other COBOL implementations and avoids the need to deal with the following special rules which
define the circumstances under which leading and/or trailing spaces may be omitted:
1.

OpenCOBOL does not actually require leading or trailing spaces around the exponentiation, multiplication ordivision operators.

2.

The ADDITION operator must be followed by a space if it is followed by an unsigned numeric literal. Failure
to do so (for example: “4+3”) will result in an “Invalid Expression” error because the compiler will treat the“+” as an attempt to specify a signed numeric literal, leaving the expression with no operator. In any othercircumstances, the leading and trailing spaces around the ADDITION operator are optional.

3.

The SUBTRACTION operator must be followed by a space if it is followed by an unsigned numeric literal.
Failure to do so (for example: “4-3”) will result in an “Invalid Expression” error because the compiler will treat
the “-” as an attempt to specify a signed numeric literal, leaving the expression with no operator.

4.

The SUBTRACTION operator must have a leading and/or trailing space if neither argument is a parenthesized
expression. Failure to include one or the other space (“3-Arg”, “Arga-Argb”, …) will cause the compiler tolook for a defined reserved word or user-defined name that (hopefully) doesn’t exist – generating a“‘identifier’ Undefined” error. If you are really unlucky, it actually WILL find such an identifier, which isalmost certain to cause runtime problems!

5.

If the argument of a UNARY PLUS operator is an unsigned numeric literal, the unary plus operator must be
followed by a space to avoid being treated as part of the numeric literal (thus making it a signed positive
numeric literal).

6.

If the argument of a UNARY NEGATION operator is an unsigned numeric literal, the unary negation operator
must be followed by a space to avoid being treated as part of the numeric literal (thus making it a signed
negative numeric literal).

06FEB2009 Version

Page 6-4

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

Here are some examples of arithmetic expressions (all of which involve numeric literals, to simplify the discussion).
Expression

Result

Notes

3*4+1

13

* has precedence over +2 ^ 3 * 4 - 1022

2 is 8, times 4 is 32, minus 10 is 22.

2 ** 3 * 4 - 10

22

Same as the above – OpenCOBOL allows either “^” or “**” to be used as the exponentiation
operator.

3 * (4 + 1)

15

Parenthesis provide for a recursive application of the arithmetic expression rules, allowing
arithmetic expressions to become components within other, more complex, arithmetic
expressions.

5 / 2.5 + 7 * 2– 1.1515.35

Integer and non-integer operands may be freely intermixed3

Of course, arithmetic expression operands may be numeric data items (any USAGE except DISPLAY, POINTER or
PROGRAM POINTER) as well as numeric literals.

6.1.4.2. Conditional Expressions
Conditional expressions are expressions which identify the conditions under which a program may make a decision
about processing to be performed. As such, conditional expressions produce a value of TRUE or FALSE.
There are seven types of conditional expressions, as follows, in increasing order of complexity.

6.1.4.2.1. Condition Names (Level-88 Items)
These are the simplest of all conditions. Observe the following code:
05

SHIRT-SIZE
88 LILLIPUTIAN
88 XS
88 S
88 M
88 L
88 XL
88 XXL88 HUMUNGOUS

PIC 99V9.
VALUE 0 THRU 12.5
VALUE 13 THRU 13.5.
VALUE 14, 14.5.
VALUE 15, 15.5.
VALUE 16, 16.5.
VALUE 17, 17.5.
VALUE 18, 18.5.
VALUE 19 THRU 99.9.

The condition names “LILLIPUTIAN”, “XS”, “S”, “M”, “L”, “XL”, “XXL” and “HUMONGOUS” will have TRUE or FALSE
values based upon the values within their parent data item (SHIRT-SIZE). So, a program wanting to test whether or
not the current SHIRT-SIZE value can be classified as “XL” could have that decision coded as a combined condition (themost complex type of conditional expression), as follows:
IF SHIRT-SIZE = 17 OR SHIRT-SIZE = 17.5

Or it could utilize the condition name XL as follows:
IF XL

6.1.4.2.2.

Class Conditions

06FEB2009 Version

Page 6-5

OpenCOBOL 1.1 Programmers Guide
Figure 6-9 - Class Condition Syntax

identifier-1 IS [ NOT ]NUMERICALPHABETIC
ALPHABETIC-LOWER
ALPHABETIC-UPPEROMITTEDclass-name-1

PROCEDURE DIVISIONClass conditions evaluate the type of data that iscurrently stored in a data item.

1. The NUMERIC class test considers only the characters “0”, “1”, … , “9” to be numeric; only a data item containing
nothing but digits will pass a IS NUMERIC class test. Spaces, decimal points, commas, currency signs, plus signs,
minus signs and any other characters except the digit characters will all fail “IS NUMERIC” class tests.
2. The ALPHABETIC class test considers only upper-case letters, lower-case letters and SPACES to be alphabetic innature.
3. The ALPHABETIC-LOWER and ALPHABETIC-UPPER class conditions consider only spaces and the respective type ofletters to be acceptable in order to pass such a class test.
4. Only data items whose USAGE is either explicitly or implicitly defined as DISPLAY may be used in NUMERIC or anyof the ALPHABETIC class conditions.
5. Some COBOL implementations disallow the use of group items or PIC A items with NUMERIC class conditions andthe use of PIC 9 items with ALPHABETIC class conditions. OpenCOBOL has no such restrictions.
6. The OMITTED class condition is used when it is necessary for a subroutine to determine whether or not a particularargument was passed to the subroutine. In such class conditions, identifier-1 must be a LINKAGE SECTION item
defined on the USING clause of the subprograms “PROCEDURE DIVISION” header. See section 6.7 for the method
to use when omitting arguments from a CALL to a subprogram.
7. The class-name-1 option allows you to test for a user-defined class. Here’s an example. First, assume the following
SPECIAL-NAMES definition of the user-defined class “Hexadecimal”:
SPECIAL-NAMES.
CLASS Hexadecimal IS „0‟ THRU „9‟, „A‟ THRU „F‟, „a‟ THRU „f‟.

Now observe the following code, which will execute the 150-Process-Hex-Value procedure if Entered-Value
contains nothing but valid hexadecimal digits:
IF Entered-Value IS Hexadecimal
PERFORM 150-Process-Hex-Value
END-IF

6.1.4.2.3.

Sign Conditions

Figure 6-10 - Sign Condition Syntax

identifier-1 IS [ NOT ]POSITIVE
NEGATIVE
ZERO

Sign conditions evaluate the numeric state of a PIC 9 data
item.

1. Only data items defined with some sort of numeric USAGE/PICTURE can be used for this type of class condition.
2. A POSTIVE or NEGATIVE class condition will be TRUE only if the value of identifier-1 is strictly greater than or lessthan zero, respectively. A ZERO class condition can be passed only if the value of identifier-1 is exactly zero.

06FEB2009 Version

Page 6-6

OpenCOBOL 1.1 Programmers Guide
6.1.4.2.4.

PROCEDURE DIVISION

Switch-Status Conditions

Figure 6-11 - Using Switch Conditions

Relevant sections of ‘testprog’…

Setting the switch andrunning the program…
$ COB_SWITCH_1=ON$ export COB_SWITCH_1$ testprog
Switch 1 Set$

06FEB2009 Version.
.
.
ENVIRONMENT DIVISION.
.
.
.
SPECIAL-NAMES.
SWITCH-1 IS External-Stat-1
ON STATUS IS OK-To-Display.
.
.
PROCEDURE DIVISION.
.
.
.
IF OK-To-Display
DISPLAY ‘Switch 1 Set’
END-DISPLAY
END-IF.
.
.

In the SPECIALNAMES paragraph(see section 4.1.4), an
external switch namecan be associatedwith one or morecondition names.
These condition
names may then be
used to test the
ON/OFF status of theexternal switch.
An example is shown
to the left.

Page 6-7

OpenCOBOL 1.1 Programmers Guide
6.1.4.2.5.

PROCEDURE DIVISION

Relation Conditions

Figure 6-12 - Relation Condition Syntax

These conditions
evaluate how two
different values“relate” to eachother.

IS EQUAL TOIS =EQUALSIS NOT EQUAL TO
IS NOT =IS GREATER THAN
IS >identifier-1
literal-1
arith-expr-1
index-name-1

identifier-2
literal-2
arith-expr2
index-name-2

IS LESS THANIS <IS GREATER THAN OR EQUAL TOIS >=IS NOT LESS THAN

IS LESS THAN OR EQUAL TOIS <=IS NOT GREATER THAN
1. When comparing one numeric value to another, the USAGE and number of significant digits in either value areirrelevant as the comparison is performed using the actual algebraic values.
2. When comparing strings, the comparison is made based upon the program’s collating sequence (see section 4.1.2).
When the two string arguments are of unequal length, the shorter is assumed to be padded (on the right) with asufficient number of SPACES as to make the two strings of equal length. String comparisons take place on acorresponding character-by-character basis until an unequal pair of characters is found. At that point, the relative
position of where each character in the pair falls in the collating sequence will determine which is greater (or less)than the other.

6.1.4.2.6.

Combined Conditions

Figure 6-13 - Combined Condition Syntax

condition-1

ANDOR

condition-2

A combined condition is one that computes a
TRUE/FALSE value from the TRUE/FALSE values of twoother conditions (which could – themselves – becombined conditions).

1. If either condition has a value of TRUE, the result of ORing the two together will result in a value of TRUE. Only
when ORing two FALSE conditions will a result of FALSE occur.
2. In order for AND to yield a value of TRUE, both conditions must have a value of TRUE. In all other circumstances,
AND produces a FALSE value.
3. When chaining multiple, similar conditions together with the same operator (OR/AND), and left or right arguments
having common operators and subjects, it is possible to abbreviate the program code. For example:
IF ACCOUNT-STATUS = 1 OR ACCOUNT-STATUS = 2 OR ACCOUNT-STATUS = 7

Could be abbreviated as:
IF ACCOUNT-STATUS = 1 OR 2 OR 7

06FEB2009 Version

Page 6-8

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

4. Just as multiplication takes precedence over addition in arithmetic expressions, so does AND take precedence over
OR in combined conditions. Use parenthesis to change this precedence, if necessary. For example:
FALSE OR TRUE AND TRUE

evaluates to TRUE

(FALSE OR FALSE) AND TRUE evaluates to FALSE
FALSE OR (FALSE AND TRUE) evaluates to TRUE

6.1.4.2.7.

Negated Conditions

Figure 6-14 - Negated Condition Syntax

A condition may be negated by prefixing it with the NOT
operator.

NOT condition

1. The NOT operator has the highest precedence of all logical operators, just as a unary minus sign (which negates a
numeric value) is the highest precedence arithmetic operator.
2. Parenthesis must be used to explicitly signify the sequence in which conditions are evaluated and processed if thedefault precedence isn’t desired. For example:
NOT TRUE AND FALSE AND NOT FALSE

evaluates to FALSE AND FALSE AND TRUE which evaluates to FALSENOT (TRUE AND FALSE AND NOT FALSE) evaluates to NOT (FALSE) which evaluates to TRUENOT TRUE AND (FALSE AND NOT FALSE) evaluates to FALSE AND (FALSE AND TRUE) which evaluates to

FALSE

6.1.5. Use of Periods (.)
All COBOL implementations distinguish between sentences and statements in the PROCEDURE DIVISION. A statement
is a single executable COBOL instruction. For example, these are all statements:
MOVE SPACES TO Employee-Address
ADD 1 TO Record-Counter
DISPLAY “Record-Counter=” Record-Counter

Some COBOL statements have a “scope of applicability” associated with them where one or more other statements
can be considered to be part of or related to the statement in question. An example of such a situation might be thefollowing, where the interest on a loan is being calculated and displayed - 4% interest if the loan balance is under$10000 and 4.5% otherwise:
IF Loan-Balance < 10000
MULTIPLY Loan-Balance BY 0.04 GIVING Interest
ELSE
MULTIPLY Loan-Balance BY 0.045 GIVING Interest
DISPLAY “Interest Amount = “ Interest

In this example, the “IF” statement actually has a scope that can include two sets of associated statements – one set
to be executed when the “IF” condition is TRUE and another if it is FALSE.
Unfortunately, there’s a problem with the above. A human being looking at that code will probably understand thatthe DISPLAY statement, because of its lack of indentation, is to be executed regardless of the TRUE/FALSE value of the“IF” condition. Unfortunately, the OpenCOBOL compiler (or any other COBOL compiler for that matter) won’t see itthat way because it really couldn’t care less what sort of indentation, if any, is used. In fact, the OpenCOBOL compiler
would be just as happy to see the code written like this:IF Loan-Balance < 10000 MULTIPLY Loan-balance BY 0.04
GIVING Interest ELSE MULTIPLY Loan-Balance BY 0.045
GIVING Interest DISPLAY “Interest Amount = “ Interest

So how then do we inform the compiler that the DISPLAY statement is outside the scope of the “IF”?
That’s where sentences come in.

06FEB2009 Version

Page 6-9

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISIONA COBOL sentence is defined as any arbitrarily long sequence of statements, followed by a period (.) character. The
period character is what terminates the scope of a set of statements. Therefore, our example needs to be coded likethis:
IF Loan-Balance < 10000
MULTIPLY Loan-Balance BY 0.04 GIVING Interest
ELSE
MULTIPLY Loan-Balance BY 0.045 GIVING Interest.
DISPLAY “Interest Amount = “ Interest

See the period at the end of the second MULTIPLY? That is what terminates the scope of the “IF”, thus making the
DISPLAY something that will be executed regardless of how the “Loan-Balance < 10000” test evaluated.

6.1.6. Use of “VERB” / “END-VERB” Constructs
Prior to the 1985 COBOL standard, using a period character was the only way to signal the end of a statement’s scope.
Unfortunately, this caused some problems.
Take a look at this code:
IF A = 1
IF B = 1
DISPLAY “A & B = 1”
ELSE
IF B = 1
DISPLAY “A NOT = 1 BUT B = 1”ELSE
DISPLAY “NEITHER A NOR B = 1”.

The problem with this code is the fact that the ELSE will be associated with the “IF B = 1” statement, not the “IF A = 1”
statement (remember – no COBOL compiler cares about how you indent your code). This sort of problem led to the15
following band-aid solution added to the COBOL language:
IF A = 1
IF B = 1
DISPLAY “A & B = 1”
ELSE
NEXT SENTENCEELSE
IF B = 1
DISPLAY “A NOT = 1 BUT B = 1”ELSE
DISPLAY “NEITHER A NOR B = 1”.

The NEXT SENTENCE statement (see section 6.30) informs COBOL that if the “B = 1” condition is false, control should
fall into the first statement that follows the next period.
With the 1985 standard for COBOL, a much more elegant solution was introduced. Those COBOL verbs (statements)that needed such a thing were allowed to use an “END-verb” construct to end their scope without disrupting thescope of any statements whose scope they might have been in. Any COBOL 85 compiler would have allowed thefollowing solution to our problem:
IF A = 1
IF B = 1
DISPLAY “A & B = 1”
END-IFELSE
IF B = 1
DISPLAY “A NOT = 1 BUT B = 1”ELSE
DISPLAY “NEITHER A NOR B = 1”.

15

Yes, I realize you could have changed the code to “IF A = 1 AND B = 1”, but that wouldn’t have allowed me to makemy case here

06FEB2009 Version

Page 6-10

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

This new facility made the period almost obsolete, as our program segment would probably be coded like this today:
IF A = 1
IF B = 1
DISPLAY “A & B = 1”
END-IFELSE
IF B = 1
DISPLAY “A NOT = 1 BUT B = 1”ELSE
DISPLAY “NEITHER A NOR B = 1”
END-IF
END-IF

COBOL (OpenCOBOL included) still requires that each PROCEDURE DIVISION paragraph contain at least once sentence
if there is any executable code in that paragraph, but a popular coding standard is now to simply code a single periodright before the end of each paragraph. Check out the “OCic” sample program in section 8.3 and you’ll see how thatwould be done.
The standard for the COBOL language shows the various “END-verb” specifications to be optional because using aperiod as a scope-terminator remains legal. Some statements have an “END-verb” scope-terminator defined for them
16
that they don’t appear to need.
If you will be porting existing code over to OpenCOBOL, you’ll find it an accommodating facility capable of conforming
to language and coding standards that code is likely to use. If you are creating new OpenCOBOL programs, however, I
would strongly counsel you to use the “END-verb” structures religiously in those programs.

6.1.7. Intrinsic Functions
OpenCOBOL supports a variety of “intrinsic functions” that may be used anywhere in the PROCEDURE DIVISION wherea literal is allowed. For example:
MOVE FUNCTION LENGTH(Employee-Last-Name) TO Employee-LN-Len.
Note how the word “FUNCTION” is part of the syntax when you use an intrinsic function. You can use intrinsic
functions without having to include the reserved word FUNCTION via settings in the REPOSITORY paragraph of the
CONFIGURATION SECTION. See section 4.1.3 for more information.
The following intrinsic functions, known to other “dialects” of COBOL, are defined to OpenCOBOL as reserved words
but are not otherwise implemented currently. Any attempts to use these functions will result in a compile-time error
message.
BOOLEAN-OF-INTEGERHIGHEST-ALGEBRAICNUMVAL-F

CHAR-NATIONALINTEGER-OF-BOOLEAN

STANDARD-COMPAREDISPLAY-OF

LOCALE-COMPARE

TEST-NUMVALEXCEPTION-FILE-N

LOWEST-ALGEBRAIC

TEST-NUMVAL-C

EXCEPTION-LOCATION-N

NATIONAL-OFTEST-NUMVAL-F

The supported intrinsic functions are listed in the following table, along with their syntax and usage notes. Rememberthat the keyword FUNCTION is required to be specified immediately before the function name in order to use thefunction, unless otherwise indicated via the REPOSITORY paragraph of the CONFIGURATION SECTION.

6.1.7.1. ABS(number)
Determines and returns the absolute value of the number (a PIC 9 item or numeric literal ) supplied as an argument.

16

STRING (section 6.43) and UNSTRING (section 6.49), for example – could it be there are plans in the works for a
future standard to introduce an option to such statements that would need a scope-terminator?

06FEB2009 Version

Page 6-11

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.1.7.2. ACOS(angle)
The ACOS function determines and returns the trigonometric arc-cosine, or inverse cosine, of the angle (a PIC 9 item
or numeric literal) supplied as an argument.

6.1.7.3. ANNUITY(interest-rate, number-of-periods)
This function returns a numeric value approximating the ratio of an annuity paid at the specified interest-rate (PIC 9
items or numeric literal) for each of the specified number-of-periods (PIC 9 items or numeric literal).
The interest-rate is the rate of interest paid at each payment. If you only have an annual interest rate and you wish tocompute annuity payments for monthly payments, divide the annual interest rate by 12 and use that value forinterest-rate on this function.
Multiply this result times the desired principal amount to determine the amount of each period’s payment.
A note for the financially challenged: an annuity is basically a reverse loan; an accountant would take the result of thisfunction multiplied by -1 to compute a loan payment you are making.

6.1.7.4. ASIN(number)
The ASIN function determines and returns the trigonometric arc-sine, or inverse sine, of the angle (a PIC 9 item or
numeric literal) supplied as an argument.

6.1.7.5. ATAN(number)
Use this function to determine and return the trigonometric arc-tangent, or inverse tangent, of the angle (a PIC 9 item
or numeric literal) supplied as an argument.

6.1.7.6. BYTE-LENGTH(string)
BYTE-length returns the length – in bytes – of the specified string (a group item, USAGE DISPLAY elementary item oralphanumeric literal). This intrinsic function is identical to the LENGTH function.

6.1.7.7. CHAR(integer)
This function returns the character in the ordinal position specified by the integer argument (a PIC 9 item or numeric
literal; no fractional part is allowed) from the collating sequence being used by the program.
th

For example, if the program is using the (default) ASCII characterset, CHAR(34) returns the 34 character in the ASCII
characterset – an exclamation-point (“!”). If you are using this function to convert a numeric value to its
corresponding ASCII character, you must use an argument value one greater than the numeric value.
If an argument whose value is less than 1 or greater than 256 is specified, the character in the program collating
sequence corresponding to a value of all zero bits is returned.
The following code is an alternative approach when you just wish to convert a number to its ASCII equivalent:
01
.
.
.

Char-Value.
05 Numeric-Value

USAGE BINARY-CHAR.

MOVE numeric-character-value TO Numeric-Value
The Char-Value item now has the corresponding ASCII character value

06FEB2009 Version

Page 6-12

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.1.7.8. COMBINED-DATETIME(days, seconds)
This function returns a 12-digit result, the first seven digits of which are the value of the days argument (a PIC 9 item
or a numeric literal) and the last five of which are the value of the seconds argument (a PIC 9 item or a numeric literal).
If a days value less than 1 or greater than 3067671 is specified, or if a seconds value less than 1 or greater than 86400
is specified, a value of 0 is returned and a runtime error will result.

6.1.7.9. CONCATENATE(string-1 [, string-2 ] …)This function concatenates the specified strings (group items, USAGE DISPLAY elementary items and/or alphanumeric
literals) together into a single string result.
If a numeric literal or PIC 9 identifier is specified as a string, decimal points will be removed and negative signs in PIC
S9 fields will be inserted as defined by the SIGN clause (or absence thereof) of the field. Numeric literals areprocessed as if SIGN IS TRAILING were in effect.

6.1.7.10. COS(number)
The COS function determines and returns the trigonometric cosine of the angle (a PIC 9 item or numeric literal)
supplied as an argument.

6.1.7.11. CURRENT-DATE
Returns the current date and time as the following 21-character structure:01

CURRENT-DATE-AND-TIME.
05 CDT-Year
05 CDT-Month05 CDT-Day
05 CDT-Hour
05 CDT-Minutes
05 CDT-Seconds
05 CDT-Hundredths-Of-Secs
05 CDT-GMT-Diff-Hours
05 CDT-GMT-Diff-Minutes

PIC 9(4).
PIC 9(2). *> 01-12
PIC 9(2). *> 01-31
PIC 9(2). *> 00-23
PIC 9(2). *> 00-59
PIC 9(2). *> 00-59
PIC 9(2). *> 00-99
PIC S9(2)SIGN LEADING SEPARATE.
PIC 9(2). *> 00 or 30

Since the CURRENT-DATE function has no arguments, no parenthesis should be specified.

6.1.7.12. DATE-OF-INTEGER(integer)
This function returns a calendar date in yyyymmdd format. The date is determined by adding the number of days
specified as integer (a PIC 9 item or numeric literal; cannot contain a fractional part) to December 31, 1600. For
example, DATE-OF-INTEGER(1) returns 16010101.
A value less than 1 or greater than 3067671 (9999/12/31) will return a result of 0.

6.1.7.13. DATE-TO-YYYYMMDD(yymmdd [, yy-cutoff ] )You can use this function to convert the six-digit date specified as yymmdd (a PIC 9 data item or a numeric literal) toan eight-digit format (yyyymmdd). The optional yy-cutoff (a PIC 9 data item or a numeric literal) argument is the year
cutoff used to delineate centuries; if the year component of the date meets or exceeds this cutoff value, the result willbe 19yymmdd; if the year component of the date is less than the cutoff value, the result will be 20yymmdd. The
default cutoff value if no second argument is given will be 50.

06FEB2009 Version

Page 6-13

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.1.7.14. DAY-OF-INTEGER(integer)
This function returns a calendar date in yyyyddd (i.e. Julian) format. The date is determined by adding the number ofdays specified as integer (a PIC 9 item or numeric literal; cannot contain a fractional part) to December 31, 1600. For
example, DATE-OF-INTEGER(1) returns 1601001.
A value less than 1 or greater than 3067671 (9999/12/31) will return a result of 0.

6.1.7.15. DAY-TO-YYYYDDD(yyddd [, yy-cutoff])
You can use this function to convert the five-digit date specified as yyddd (a PIC 9 data item or a numeric literal) to aseven-digit format (yyyyddd). The optional yy-cutoff argument (a PIC 9 data item or a numeric literal) is the year
cutoff used to delineate centuries; if the year component of the date meets or exceeds this cutoff value, the result willbe 19yyddd; if the year component of the date is less than the cutoff, the result will be 20yyddd. The default cutoff
value if no second argument is given will be 50.

6.1.7.16. E
This function returns the mathematical constant “E” (the base of natural logarithms). The maximum precision withwhich this value may be returned is 2.7182818284590452353602874713526625.
Since the E function has no arguments, no parenthesis should be specified.

6.1.7.17. EXCEPTION-FILE
This function returns I/O exception information from the most-recently executed input or output statement. The
information is returned to a structure resembling the following:
01

INPUT-OUTPUT-EXCEPTION.
05 IOE-FILE-STATUS
05 IOE-FILE-SELECT-NAME

PIC 9(2).
PIC X(32).

See
Figure 4-11 for information about possible file-status values.
The name returned after the file status information will be the “SELECT” name of the file, and it will be returned ONLY
if the returned file status value is not 00.
Since the EXCEPTION-FILE function has no arguments, no parenthesis should be specified.

6.1.7.18. EXCEPTION-LOCATIONThis function returns exception information from the most-recently failing statement. The information is returned toa 1023 character string in one of the following formats, depending on the nature of the failure:
program-id; paragraph OF section; statement-number
program-id; section; statement-number
program-id; paragraph; statement-number
program-id; statement-number
Since the EXCEPTION-LOCATION function has no arguments, no parenthesis should be specified.
The program must be compiled with the “-g” option for this function to return any meaningful information.
See section 6.5.1 for an example of this function at work.

6.1.7.19. EXCEPTION-STATEMENT
This function returns the most-recent COBOL statement that generated an exception condition.
06FEB2009 Version

Page 6-14

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

Since the EXCEPTION-STATEMENT function has no arguments, no parenthesis should be specified.
The program must be compiled with the “-g” option for this function to return any meaningful information.
See section 6.5.1 for an example of this function at work.

6.1.7.20. EXCEPTION-STATUS
This function returns the error type (as a text string) from the most-recent COBOL statement that generated an
exception condition.
Since the EXCEPTION-STATUS function has no arguments, no parenthesis should be specified.
See section 6.5.1 for an example of this function at work.

6.1.7.21. EXP(number)
Computes and returns the value of the mathematical constant “e” raised to the power specified by number (a PIC 9
item or numeric literal).

6.1.7.22. EXP10(number)
Computes and returns the value of 10 raised to the power specified by number (a PIC 9 item or numeric literal).

6.1.7.23. FRACTION-PART(number)This function returns that portion of number that occurs to the right of the decimal point. Number must be a numeric
data item or a numeric literal. FRACTION-PART(3.1415), for example, returns a value of 0.1415. This function isequivalent to the expression:
number – FUNCTION INTEGER-PART(number)

6.1.7.24. FACTORIAL(number)This function computes and returns the factorial value of number (a PIC 9 item or numeric literal).

6.1.7.25. INTEGER(number)
The INTEGER function returns the greatest integer value that is less than or equal to number (a PIC 9 item or numeric
literal).

6.1.7.26. INTEGER-OF-DATE(date)This function converts date (a PIC 9 item or numeric literal; cannot contain a fractional part) – presumed to be a
Gregorian calendar form standard date (YYYYMMDD) - to integer date form – that is, the number of days that havetranspired since 1600/12/31.

6.1.7.27. INTEGER-OF-DAY(date)This function converts date (a PIC 9 item or numeric literal; cannot contain a fractional part) – presumed to be a Juliancalendar form standard date (YYYYDDD) to integer date form – that is, the number of days that have transpired since
1600/12/31.

06FEB2009 Version

Page 6-15

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.1.7.28. INTEGER-PART(number)
Returns the integer portion of the value of number (a PIC 9 item or numeric literal).

6.1.7.29. LENGTH(string)
Returns the length – in bytes – of string (a group item, USAGE DISPLAY elementary item or alphanumeric literal). This
intrinsic function is identical to the BYTE-LENGTH function.

6.1.7.30. LOCALE-DATE(date [, locale ] )Converts the eight-digit date (a PIC 9 item or numeric literal; cannot contain a fractional part) from YYYYMMDD format
to the format appropriate to the current locale. On a Windows system, this will be the “short date” format as set
using Control Panel.
You may include an optional second argument to specify the locale name (group item or PIC X identifier) you’d like to
use for date formatting. If used, this second argument MUST be an identifier. Locale names are specified using UNIXstandard names. The complete list of supported locale names is shown in Figure 4-7.

6.1.7.31. LOCALE-TIME(time [, locale ] )Converts the four- (HHMM) or six-digit (HHMMSS) time (a PIC 9 item or numeric literal; cannot contain a fractionalpart) to a format appropriate to the current locale. On a Windows system, this will be the “time” format as set using
Control Panel.
You may include an optional locale name (a group item or PIC X identifier) you’d like to use for time formatting. Ifused, this second argument MUST be an identifier. Locale names are specified using UNIX-standard names. The
complete list of supported locale names is shown in Figure 4-7.

6.1.7.32. LOCALE-TIME-FROM-SECS(seconds [, locale ] )Converts the number of seconds since midnight (a PIC 9 item or numeric literal; cannot contain a fractional part) to aformat appropriate to the current locale. On a Windows system, this will be the “time” format as set using Control
Panel.
You may include an optional locale name (a group item or PIC X identifier) you’d like to use for time formatting. Ifused, this second argument MUST be an identifier. Locale names are specified using UNIX-standard names. The
complete list of supported locale names is shown in Figure 4-7.

6.1.7.33. LOG(number)
Computes and returns the natural logarithm (base “e”) of number (a PIC 9 item or numeric literal).

6.1.7.34. LOG10(number)
Computes and returns the base 10 logarithm of number (a PIC 9 item or numeric literal).

6.1.7.35. LOWER-CASE(string)This function returns the value of string (a group item, USAGE DISPLAY elementary item or alphanumeric literal),converted entirely to lower case.

06FEB2009 Version

Page 6-16

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.1.7.36. MAX(number-1 [, number-2 ] …)This function returns the maximum value from the specified list numbers (PIC 9 items and/or numeric literals).

6.1.7.37. MIN(number-1 [, number-2 ] …)This function returns the minimum value from the specified list numbers (PIC 9 items and/or numeric literals).

6.1.7.38. MEAN(number-1 [, number-2 ] …)This function returns the statistical mean value of the specified list numbers (PIC 9 items and/or numeric literals).

6.1.7.39. MEDIAN(number-1 [, number-2 ] …)This function returns the statistical median value of the specified list numbers (PIC 9 items and/or numeric literals).

6.1.7.40. MIDRANGE(number-1 [, number-2 ] …)
The MIDRANGE (middle range) function returns a numeric value that is the arithmetic mean (average) of the values ofthe minimum and maximum numbers (PIC 9 items and/or numeric literals).

6.1.7.41. MOD(value, modulus)
Returns value modulo modulus. Both arguments may be PIC 9 data items or numeric literals. Either (or both) may
have a non-integer value.
The result is determined according to the following formula:value - (modulus * FUNCTION INTEGER (value / modulus))

6.1.7.42. NUMVAL(string)
The NUMVAL function converts a string (a group item, USAGE DISPLAY elementary item or alphanumeric literal) to its
corresponding numeric value by parsing that string according to the rules for COBOL PICTURE editing. For example,17
the string “12,345.55” will be converted to a numeric value of 12345.55.

6.1.7.43. NUMVAL-C(string [, symbol ])This function performs a function similar to that of the NUMVAL function, but provides for the specification of aconverts a string (a group item, USAGE DISPLAY elementary item or alphanumeric literal) to its corresponding numericvalue by parsing that string according to the rules for COBOL PICTURE editing. The optional symbol character
represents the currency symbol (a group item, USAGE DISPLAY elementary item or alphanumeric literal) that occurs
within string. For example, the string “$12,345.55” will be converted to a numeric value of 12345.55 (“$” is the18
assumed default currency symbol).

17

The string parsing rules for NUMVAL and NUMVAL-C are quite loose, essentially ignoring any non-numeric or
invalid characters. Thus, both routines will generate a result of 1234 for “$1,234”, “******1234”, “xxxxx12xxxx34”
and so on.

06FEB2009 Version

Page 6-17

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.1.7.44. ORD(char)st

This function returns the ordinal position in the program characterset (usually ASCII) corresponding to the 1character of the char argument (a group item, USAGE DISPLAY elementary item or alphanumeric literal). For example,
thassuming the program is using the standard ASCII collating sequence, ORD(“!”) returns 34 because “!” is the 34 ASCII
character. If you are using this function to convert an ASCII character to its numeric value, you must subtract one fromthe result.
The following code is an alternative approach when you just wish to convert an ASCII character to its numericequivalent:01

Char-Value.
05 Numeric-Value

USAGE BINARY-CHAR.

.
.
.
MOVE “character” TO Char-Value
The Numeric-Value item now has the corresponding numeric value

6.1.7.45. ORD-MAX( char-1 [, char-2 ] … )stThis function returns the ordinal position in the argument list corresponding to the argument whose 1 character has
the highest position in the program collating sequence (usually ASCII). For example, assuming the program is using thestandard ASCII collating sequence, ORD-MAX(“Z”, “z", “!”) returns 2 because the ASCII character “z” occurs after “Z”
and “!” in the program collating sequence. Each char argument is a group item, USAGE DISPLAY elementary item oralphanumeric literal

6.1.7.46. ORD-MIN( char-1 [, char-2 ] … )stThis function returns the ordinal position in the argument list corresponding to the argument whose 1 character has
the lowest position in the program collating sequence (usually ASCII). For example, assuming the program is using thestandard ASCII collating sequence, ORD-MAX(“Z”, “z", “!”) returns 3 because the ASCII character “!” occurs before “Z”
and “z” in the program’s collating sequence. Each char argument is a group item, USAGE DISPLAY elementary item oralphanumeric literal

6.1.7.47. PI
This function returns the mathematical constant “PI”. The maximum precision with which this value may be returnedis 3.1415926535897932384626433832795029.
Since the PI function has no arguments, no parenthesis should be specified.

6.1.7.48. PRESENT-VALUE(rate,value-1 [, value-2 ] )The PRESENT-VALUE function returns a value that approximates the present value of a series of future period-end
amounts specified by the various value arguments at a discount rate specified by the rate argument. All arguments
are PIC 9 items and/or numeric literals.
The following formula summarizes the functions operation:

6.1.7.49. RANDOM [ ( seed ) ]The RANDOM function returns a non-integer value in the range 0 to 1 (for example, 0.123456789).
If seed is specified, it must be zero or a positive integer (specified as a PIC 9 item and/or numeric literal). It is used as
the seed value to generate a sequence of pseudo-random numbers.
If a subsequent reference specifies seed, a new sequence of pseudo-random numbers is started.
06FEB2009 Version

Page 6-18

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

If the first executed reference to this function does not specify a seed, the seed will be supplied by the compiler.
In each case, subsequent references without specifying a seed return the next number in the current sequence.

6.1.7.50. RANGE(number-1 [, number-2 ] …)
The RANGE function returns a value that is equal to the value of the maximum number in the argument list minus thevalue of the minimum number argument. All arguments are PIC 9 items and/or numeric literals.

6.1.7.51. REM(number, divisor)
This function returns a numeric value that is the remainder of number divided by divisor. Both arguments may be PIC
9 items and/or numeric literals.
The result is determined according to the following formula:number - (divisor * FUNCTION INTEGER-PART (number / divisor))

6.1.7.52. REVERSE(string)This function returns the byte-by-byte reversed value of the specified string (a group item, USAGE DISPLAY elementary
item or alphanumeric literal).

6.1.7.53. SECONDS-FROM-FORMATTED-TIME(format,time)
This function decodes a string whose value represents a formatted time and returns the total number of seconds thatstring represents. The time string must contain hours, minutes and seconds. The time argument may be specified as agroup item, USAGE DISPLAY elementary item or an alphanumeric literal.
The format argument is a string (a group item, USAGE DISPLAY elementary item or an alphanumeric literal)
documenting the format of time using “hh”, “mm” and “ss” to denote where the respective time information can befound. Any other characters found in format represent character positions that will be ignored. For example, aformat of “hhmmss” indicates that time will be treated as a six-digit value where the first two characters are thenumber of hours, the next two represent minutes and the last two represent seconds. Similarly, a format of“hh:mm:ss” states that time will be an eight-character string where characters 3 and 6 will be ignored.

6.1.7.54. SECONDS-PAST-MIDNIGHT
This function returns the current time of day expressed as the total number of elapsed seconds since midnight.

6.1.7.55. SIGN(number)
The SIGN function returns a -1 if the value of number (a PIC 9 item or numeric literal) is negative, a zero if the value of
number is exactly zero and a 1 if the value of number if greater than 0.

6.1.7.56. SIN(angle)
Determines and returns the trigonometric sine of the specified angle (a PIC 9 item or numeric literal).

6.1.7.57. SQRT(number)
The SQRT function returns a numeric value that approximates the square root of number (a PIC 9 item or numeric
literal with a non-negative value).

06FEB2009 Version

Page 6-19

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.1.7.58. MEAN(number-1 [, number-2 ] …)This function returns the statistical standard deviation of the specified list numbers (PIC 9 items and/or numeric
literals).

6.1.7.59. STORED-CHAR-LENGTH(string)
Returns the length – in bytes – of the specified string (a group item, USAGE DISPLAY elementary item or alphanumeric
literal) MINUS the total number of trailing spaces, if any.

6.1.7.60. SUBSTITUTE(string,from-1,to-1 [, from-n,to-n ] )This function parses the specified string, replacing all occurrences of the from-n strings with the corresponding to-nstrings. The from strings must match exactly with regard to value and case. The from strings do not have to be thesame length as the to strings. All arguments are group items, USAGE DISPLAY elementary items or alphanumeric
literals.
A null to string will be treated as a single SPACE.

6.1.7.61. SUBSTITUTE-CASE(string,from-1,to-1 [, from-n,to-n ] )The SUBSTITUTE-CASE function operates the same as the SUBSTITUTE function, except that from string matching is
performed without regard for case. All arguments are group items, USAGE DISPLAY elementary items or alphanumeric
literals.

6.1.7.62. SUM(number-1 [, number-2 ] …)
The SUM function returns a value that is the sum of the number arguments (PIC 9 items and/or numeric literals).

6.1.7.63. TAN(angle)
Determines and returns the trigonometric tangent of the specified angle (a PIC 9 item or numeric literal).

6.1.7.64. TEST-DATE-YYYYMMDD(date)
Determines if the supplied date (a PIC 9 item or numeric literal; cannot contain a fractional part) is a valid date of theform yyyymmdd and that the date is in the range 1601/01/01 to 9999/12/31. If it is value, a 0 value is returned. If it
isn’t, a value of 1 is returned.

6.1.7.65. TEST-DAY-YYYYDDD(date)
Determines if the supplied date (a PIC 9 item or numeric literal (cannot contain a fractional part) is a valid date of theform yyyyddd and that the date is in the range 1601001 to 9999365. If it is value, a 0 value is returned. If it isn’t, avalue of 1 is returned.

6.1.7.66. TRIM(string[ , LEADING|TRAILING ] )This function removes leading or trailing spaces from the specified string (a group item, USAGE DISPLAY elementary
item or alphanumeric literal). The second argument is specified as a keyword, not a quoted string or identifier. If nosecond argument is specified, both leading and trailing spaces will be removed.

06FEB2009 Version

Page 6-20

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.1.7.67. UPPER-CASE(string)This function returns the value of string (a group item, USAGE DISPLAY elementary item or alphanumeric literal),converted entirely to upper case.

6.1.7.68. VARIANCE(number-1 [, number-2 ] …)This function returns the statistical variance of the specified list numbers (PIC 9 items and/or numeric literals).

6.1.7.69. WHEN-COMPILED
This function returns date and time the program was compiled in the same format as the result returned by the
CURRENT-DATE function.
Since the WHEN-COMPILED function has no arguments, no parenthesis should be specified.

6.1.7.70. YEAR-TO-YYYY (yy [, yy-cutoff])
YEAR-TO-YYYY converts yy (a) - a two-digit year - to a four-digit format (yyyy). The optional yy-cutoff argument (also a
PIC 9 data item or numeric literal) is the year cutoff used to delineate centuries; if yy meets or exceeds this cutoff
value, the result will be 19yy; if yy is less than the cutoff, the result will be 20yy. The default cutoff value if no second
argument is given will be 50.

6.1.8. Special Registers
OpenCOBOL, like other COBOL dialects, includes a number of data items that are automatically available to a
programmer without the need to actually define them in the DATA DIVISION. COBOL refers to such items as registers
or special registers. The special registers available to an OpenCOBOL program are as follows:
Figure 6-15 - Special Registers

Register Name
LINAGE-COUNTER

Implied COBOL
18
PIC/USAGEBINARY-LONG
SIGNED

Usage
An occurrence of this register exists for each SELECTed filehaving a LINAGE clause (see section 5.1). If there are multiple
files whose FDs have a LINAGE clause, any explicit references
to this register will require qualification (using “OF filename”).
The value of this register will be the current logical line
number within the page body (see section 5.1 for a discussionof how the LINAGE clause structures logical pages).

NUMBER-OF-CALL-PARAMETERS

BINARY-LONG
SIGNED

DO NOT MODIFY THE CONTENTS OF THIS REGISTER.
This register contains the number of arguments passed to a
subprogram. Its value will be zero when referenced in a main
program.
See the C$NARG built-in subroutine documentation in section
7.3.1.7 for another way of retrieving the same data.

18

See section 5.3 for a description of the PICTURE / USAGE specifications

06FEB2009 Version

Page 6-21

OpenCOBOL 1.1 Programmers Guide
Register Name
RETURN-CODE

Implied COBOL
18
PIC/USAGEBINARY-LONG
SIGNEDPROCEDURE DIVISION
Usage
This register provides a numeric data item into which a
subroutine may MOVE a value prior to transferring control
back to the program that CALLed it, or into which a main
program may MOVE a value before returning control to theoperating system.
Many built-in subroutines (section 7.3) will return a value
using this register.

SORT-RETURN

BINARY-LONG
SIGNED

WHEN-COMPILED

See “Usage”

These values are – by convention – used to signify success(usually with a value of 0) or failure (usually with a non-zerovalue) of the process the program setting the RETURN-CODE
value was attempting to perform.
This register is used to report the success/fail status of a
RELEASE or RETURN statement. A value of 0 is reported on
success. A value of 16 denotes failure. An “AT END”
condition on a RETURN is not considered a failure.
This register contains the date and time the program wascompiled in the format “mm/dd/yyhh.mm.ss”. Note that
only a two-digit year is provided.

6.1.9. Controlling Concurrent Access to Files
The manipulation of data files is one of the COBOL language’s great strengths. There are features built-in to the
COBOL language to deal with the possibility that multiple programs may be attempting to access the same fileconcurrently. Multiple program concurrent access is dealt with in two ways – file sharing and record locking.
Not all OpenCOBOL implementations support file sharing and record-locking options. Whether they do or not
depends upon the operating system they were built for and the build options that were used when the specific
OpenCOBOL implementation was generated.

6.1.9.1. File Sharing
OpenCOBOL controls concurrent-file access at the highest level through the concept of file sharing, enforced when aprogram attempts to OPEN a file (see section 6.31). This is accomplished via a UNIX operating-system routine called19“fcntl()”. That module is not currently supported by Windows and is not present in the MinGW Unix-emulation
package. OpenCOBOL builds created using a MinGW environment will be incapable of supporting file-sharing controls– files will always be shared in such environments. An OpenCOBOL build created using the Cygwin environment on
Windows would have access to “fcntl()” and therefore will support file sharing. Of course, actual Unix builds of
20
OpenCOBOL, as well as MacOS builds , will have no issues using BDB because “fcntl()” is built-in to Unix.

Any limitations you impose on a successful OPEN will remain in place until your program either issues a CLOSE against
the file or terminates.
There are three ways in which concurrent access to a file may be controlled at the file level:

19

Windows has other means of providing equivalent functionality to “fcntl()”, but the BDB package was not coded toutilize them. The use of other advanced file I/O packages that support both the UNIX and Windows concurrentaccess routines (such as VBISAM) are currently under investigation by the author.

20

Apple Computer’s MacOS X operating system is based on an open-source version of UNIX and therefore includes
support of “fcntl()”.

06FEB2009 Version

Page 6-22

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

Sharing
OptionEffectALL
OTHER

When your program opens a file in this manner, no restrictions will be placed on other programs
attempting to OPEN the file after your program did. This is the default sharing mode.

NO
OTHER

When your program opens a file in this manner, your program announces that it is unwilling to allow
any other program to have any access to the file as long as you are using that file; OPEN attempts
made in other programs will fail with a file status of 37 (“PERMISSION DENIED”) until such time as you
CLOSE the file (see section 6.9).

READ
ONLY

Opening a file in this manner indicates you are willing to allow other programs to OPEN the file for
INPUT while you have it OPEN. If they attempt any other OPEN, their OPEN will fail with a file statusof 37.

Of course, your program may fail if someone else got to the file first and OPENed it with a sharing option that imposed
file-sharing limitations.

6.1.9.2. Record Locking
Record-locking is supported by advanced file-management software that provides a single point-of-control for accessto files (usually ORGANIZATION INDEXED files). One such runtime package capable of doing this is the Berkely
Database (BDB) package. The various I/O statements are capable of imposing limitations on the access – by otherconcurrently-executing programs – to the file record they just accessed. These limitations are syntactically imposed byplacing a lock on the record. Other records in the file remain available, assuming that file-sharing limitations imposedat OPEN-time didn’t prevent access to the entire file.
Locks remain in-effect until a program holding the lock terminates, Issues a CLOSE (section 6.9) against the file, issues
an UNLOCK (section 6.48) against the file, executes a COMMIT (section 6.10) or executes a ROLLBACK (section 6.37).
The record locking options (not all options are available to all statements) are as shown in the following table.
RecordLocking
Option
WITH LOCKWITH NOLOCKIGNORING
LOCK
WITH IGNORE
LOCK
WITH WAIT

EffectAccess to the record by other programs will be denied.
The record will not be locked. This is the default locking option in effect for all statements.
This option is possible only when reading records – it informs OpenCOBOL that any locks held byother programs should be ignored.
The two options shown are synonymous.
This option is possible only when reading records – it informs OpenCOBOL that the program is willingto wait for a lock held on the record being read to be released.
Without this option, an attempt to read a locked record will be immediately aborted and a file statusof 47 will be returned.
With this option, the program will wait for a pre-configured time for the lock to be released. If thelock is released within the preconfigured wait time, the read will be successful. If the pre-configured
wait time expires before the lock is released, the read attempt will be aborted and a 47 file status will
be issued.

If the OpenCOBOL build you are using was configured to use BDB, record locking will be available by using theexecution-time environment variable DB_HOME (see section 7.2.4).

06FEB2009 Version

Page 6-23

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.2. General Format of the PROCEDURE DIVISION
Figure 6-16 - General PROCEDURE DIVISION Syntax

USING
CHAINING

PROCEDURE DIVISION

argument-1 ...

[ RETURNING identifier-1 ] .
[ declaratives-entry ] ...
[ section-name -1 SECTION. ]paragraph-name-1.
[ procedural-statement-1 ] …

...

argument Format:
BY

REFERENCE
VALUE

The first (optional) segment of
the PROCEDURE DIVISION is a
special area known as“declaratives”. In this area, you
may define processing routinesthat are to be used as special“trap” routines executed only
when certain events occur. These
will be described in section 6.3.
The various sections andparagraphs in which theprocedural logic of your program
will be coded will follow any“declaratives”. The PROCEDUREDIVISION is the only one of the
COBOL divisions that allows you
to create your own sections andparagraphs.

SIZE IS AUTO
SIZE IS DEFAULT[ UNSIGNED ] SIZE IS integer-1[ OPTIONAL ]identifier-2
1.

The USING and RETURNING clauses define arguments to a program serving as a subroutine. All identifiers
specified on these clauses must be defined in the LINKAGE SECTION of the program in which the USING and/or
RETURNING clauses appear.

2.

The CHAINING clause should be used only by a program that will be invoked by another program via the CHAIN
verb. The identifiers specified with CHAINING clauses must be defined in the LINKAGE SECTION of the program inwhich the CHAINING clauses appear. Chaining, however, is currently syntactically supported by OpenCOBOL but
is otherwise non-functional. Attempts to use the CHAIN verb will be rejected.

3.

While intended for use with user-defined FUNCTIONs (which are not currently supported by OpenCOBOL), the
RETURNING clause can be used as a means of specifying and documenting an argument to a subprogram in which
a value is returned.

4.

The BY REFERENCE clause indicates that the program will be passed the address of the data item corresponding toa program argument; this program will be allowed to modify the contents of any BY REFERENCE argument. BY
REFERENCE is the assumed default for all USING/CHAINING arguments (CHAINING arguments must be BY
REFERENCE).

5.

The BY VALUE clause indicates the program will be passed a read-only copy of the data item from the calling
program that corresponds to the argument. The contents of BY VALUE arguments cannot be changed by the
subprograms receiving them.

6.

The USING mechanism is NOT how OpenCOBOL programs should retrieve their command-line arguments as is thecase in some mainframe implementations of COBOL. See the ACCEPT verb for information on how programcommand line arguments should be retrieved.

7.

The various SIZE clauses specify the size (in bytes) of received arguments. The SIZE IS AUTO clause (the default)
indicates that argument size will be determined automatically based upon the size of the item in the calling

06FEB2009 Version

Page 6-24

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

program. The remaining SIZE options allow you to force a specific size to be assumed, with SIZE IS DEFAULT being
the same as UNSIGNED SIZE IS 4.

6.3. General Format for DECLARATIVES Entries
Figure 6-17 - General DECLARATIVES Syntax

DECLARATIVES.
section-name-1 SECTION.

[ GLOBAL ] AFTER STANDARDUSEFOR DEBUGGING ON

EXCEPTIONERRORALL PROCEDURES
procedure-name-1[ GLOBAL ] BEFORE REPORTING identifier-1

paragraph-name-1.
statement-1 ...

PROCEDURE ONINPUTOUTPUT
I-O
EXTEND
file-name-1 ...
.
...

The
DECLARATIVES
area of the
PROCEDURE
DIVISION allows
the programmer
to define a seriesof “trap” routines
capable ofintercepting
certain events that
may occur at
program
execution time.

END DECLARATIVES.

1.

Since the RWCS is not currently supported by OpenCOBOL, the USE BEFORE REPORTING clause will be
syntactically recognized but rejected as being unsupported.

2.

The USE FOR DEBUGGING clause will be syntactically recognized but will be ignored. If you use the “-Wall” or“-W” compiler switches you will receive a warning message stating this feature is not yet implemented.

3.

The USE AFTER STANDARD ERROR PROCEDURE clause defines a routine invoked any time a failure is encounteredwith the specified I/O type (or against the specified file(s).

4.

The GLOBAL option, if used, allows a declaratives procedure to be used across all program units in the same
compilation unit.

5.

DECLARATIVES routines (of any type) may not reference any procedures outside the scope of the DECLARATIVES
area except for referencing them via the PERFORM statement.

06FEB2009 Version

Page 6-25

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.4. ACCEPT
6.4.1. ACCEPT Format 1 – Read from Console
Figure 6-18 - ACCEPT (Read from Console) Syntax

ACCEPT identifier[ FROM mnemonic-name ][ END-ACCEPT ]This format of the ACCEPT verb is used to read a value
from the console window and store it into a data item
(identifier).

1.

If the FROM clause is used, the specified mnemonic-name must be either SYSIN or CONSOLE, or a user-defined
mnemonic-name assigned to one of those two devices via the SPECIAL-NAMES paragraph. The devices SYSIN andCONSOLE may be used interchangeably and both reference the console window.

2.

If no FROM clause is specified, FROM CONSOLE is assumed.

6.4.2. ACCEPT Format 2 – Retrieve Command-Line Arguments
Figure 6-19 - ACCEPT (Command Line Arguments) Syntax

ACCEPT identifier
FROM

COMMAND-LINE
ARGUMENT-NUMBER
ARGUMENT-VALUE [ exception-handler ]This format of the ACCEPT verb is used
to retrieve arguments from theprograms command-line.

[ END-ACCEPT ]1.

When you accept from the COMMAND-LINE option, you will retrieve the entire set of arguments entered on thecommand line that executed the program, exactly as they were specified. Parsing that returned data into its
meaningful information will be your responsibility.

2.

By accepting from ARGUMENT-NUMBER, you will be asking the OpenCOBOL run-time system to parse thearguments from the command-line and return the number of arguments found. Parsing will be conductedaccording to the operating system’s rules, as follows:
Arguments will be separated by treating SPACES between characters as the delineators between
arguments. The number of spaces separating two non-blank values is irrelevant.
Strings enclosed in double-quote characters (“) will be treated as a single argument, regardless of how
many spaces (if any) might be imbedded within those quotation characters.
On Windows systems, single-quote, or apostrophe characters (‘) will be treated just like any other datacharacter and will NOT delineate strings.

3.

By accepting from ARGUMENT-VALUE, you will be asking the OpenCOBOL run-time system to parse thearguments from the command-line and return the arguments whose number is currently in the ARGUMENT21
NUMBER register . Parsing will be conducted according to the rules set forth in #2 above.

4.

The syntax and usage of the optional exception-handler is discussed in section 6.4.7.

21

Use format #2 of the DISPLAY statement to set ARGUMENT-NUMBER to the desired value

06FEB2009 Version

Page 6-26

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.4.3. ACCEPT Format 3 – Retrieve Environment Variable Values
Figure 6-20 - ACCEPT (Environment Variable Values) Syntax

ACCEPT identifier-1

This format of the ACCEPT verb is used toretrieve environment variable values.

ENVIRONMENT-VALUEFROMENVIRONMENT

Literal-1
Identifier-2[ exception-handler ][ END-ACCEPT ]1.

By accepting from ENVIRONMENT-VALUE, you will be asking the OpenCOBOL run-time system to retrieve the22value of the environment variable whose name is currently in the ENVIRONMENT-NAME register .

2.

A simpler approach to retrieving an environment variables value is to use “ACCEPT … FROM ENVIRONMENT”.
Using that form, you specify the environment variable to be retrieved right on the ACCEPT command itself.

3.

The syntax and usage of the optional exception-handler is discussed in section 6.4.7.

22

Use format #3 of the DISPLAY statement to set ENVIRONMENT-NAME to the desired environment variable name

06FEB2009 Version

Page 6-27

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.4.4. ACCEPT Format 4 – Retrieve Screen Data
Figure 6-21 - ACCEPT (Retrieve Screen Data) Syntax

ACCEPT identifier-1

AT LINE NUMBER

AT

COLUMNPOSITION

AT

integer-3
identifier-4

WITH

integer-1
identifier-2
NUMBER

COLUMNPOSITIONNUMBER

integer-2
identifier-3

AUTO | AUTO-SKIP | AUTOTERMINATE
BELL | BEEPREVERSE-VIDEOUNDERLINEOVERLINE
REQUIRED
FULL
PROMPT
SECUREUPDATEHIGHLIGHTLOWLIGHT
BLINK
integer-4
FOREGROUND-COLOR IS
identifier-5
BACKGROUND-COLOR IS
SCROLL

UP
DOWN

integer-2
identifier-3

BY

This format of
the ACCEPT verb
is used toretrieve datafrom aformatted
console window
screen using adata item
defined in the
SCREENSECTION.

...

integer-5
identifier-6
integer-6
identifier-7

LINES
LINE

[ exception-handler ][ END-ACCEPT ]1.

If identifier-1 is defined in the SCREEN SECTION, all cursor positioning (AT) and attribute specifications (WITH) aretaken from the SCREEN SECTION definition and anything specified on the ACCEPT will be ignored. Use the AT and
WITH options only when ACCEPTing a data item that was not defined in the SCREEN SECTION.

2.

The various AT clauses provide a means of positioning the cursor to a specific spot on the screen before thestscreen is read. The literal-3 / identifier-4 value must be a four-digit value with the 1 two digits indicating the line
where the cursor should be positioned and the last two digits being the column.

3.

Most of the WITH options were described in section 5.6, with the exception of the UPDATE and SCROLL options.
With the exception of SCROLL, WITH options should be specified only once.

4.

The UPDATE option which causes the current contents of identifier-1 to be displayed before a new value is
accepted.

5.

The SCROLL option will cause the entire contents of the screen to be scrolled UP or DOWN by the specified
number of lines before any value is displayed on the screen. It is possible to specify a SCROLL UP clause as well asa SCROLL DOWN clause. If no LINES specification is made, “1 LINE” will be assumed.

6.

The syntax and usage of the optional exception-handler is discussed in section 6.4.7.

06FEB2009 Version

Page 6-28

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.4.5. ACCEPT Format 5 – Retrieve Date/Time
Figure 6-22 - ACCEPT (Retrieve Date/Time) Syntax

ACCEPT identifier

FROM

This format of the ACCEPT verb is used to retrieve thecurrent system date and/or time and store it into a data
item.

DATE
DATE YYYYMMDDDAYDAY YYYYDDDDAY-OF-WEEK
TIME[ END-ACCEPT ]1.

The data retrieved from the system, and the format in which it is structured, will vary according to the following
chart:
ACCEPT Option
DATE

Data Returned
Current date in Gregorian form

01

DATE YYYYMMDDCurrent date in Gregorian form

01

DAY

Current date in Julian form

01

DAY YYYYDDDCurrent date in Julian form

01

DAY-OF-WEEK

Current day of the week

01

Current time

01

TIME

identifier-1 Format
CURRENT-DATE.
05 CD-YEAR
PIC 9(2).
05 CD-MONTH
PIC 9(2).
05 CD-DAY-OF-MONTH
PIC 9(2).
CURRENT-DATE.
05 CD-YEAR
PIC 9(4).
05 CD-MONTH
PIC 9(2).
05 CD-DAY-OF-MONTH
PIC 9(2).
CURRENT-DATE.
05 CD-YEAR
PIC 9(2).
05 CD-DAY-OF-YEAR
PIC 9(3).
CURRENT-DATE.
05 CD-YEAR
PIC 9(4).
05 CD-DAY-OF-YEAR
PIC 9(3).
CURRENT-DATE.
05 CD-DAY-OF-WEEK
PIC 9(1).
88 MONDAYVALUE 1.
88 TUESDAYVALUE 2.
88 WEDNESDAY VALUE 3.
88 THURSDAY VALUE 4.
88 FRIDAYVALUE 5.
88 SATURDAY VALUE 6.
88 SUNDAYVALUE 7.
CURRENT-TIME.
05 CT-HOURSPIC 9(2).
05 CT-MINUTESPIC 9(2).
05 CT-SECONDS
PIC 9(2).
06 CT-HUNDREDTHS-OF-SECS PIC 9(2).

Figure 6-23 - ACCEPT Options for DATE/TIME Retrieval

6.4.6. ACCEPT Format 6 - Retrieve Screen Size Data
Figure 6-24 - ACCEPT (Retrieve Screen Size Data) Syntax

ACCEPT identifier
FROM

This format of the ACCEPT verb is used to retrieve thedisplayable size (in character positions) of the console
window in which the program is executing.

LINES
COLUMNS[ END-ACCEPT ]06FEB2009 Version

Page 6-29

OpenCOBOL 1.1 Programmers Guide
1.

PROCEDURE DIVISION

In environments such as a Windows console window, where the logical size of the window may far exceed that ofthe physical console window, the size returned will be that of the physical console window.

6.4.7. ACCEPT Exception Handling
Figure 6-25 - ACCEPT Exception Handling

ON EXCEPTION
imperative-statement-1

NOT ON EXCEPTION
imperative-statement-2

06FEB2009 Version

The EXCEPTION and NOT EXCEPTION clauses available onsome formats of the ACCEPT verb allow you to specify
code to be executed specifically upon the failure or
success (respectively) of the ACCEPT. Since ACCEPT does
not set any sort of return code or status flag, this is the
only way to detect success and failure.

Page 6-30

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.5. ADD
6.5.1. ADD Format 1 – ADD TO
Figure 6-26 - ADD (TO) Syntax

ADD[ LENGTH OF ]literal-1
identifier-1

This format of the ADD statement generates
the arithmetic sum of all arguments thatappear before the TO (identifier-1 or literal-1)
and then adds that sum to each of theidentifiers listed after the TO (identifier-2).

...

TO { identifier-2 [ ROUNDED ] } ...
[ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ][ END-ADD ]1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Literal-1 must be a numeric literal.

3.

Should a non-integer result be generated and assigned to any of the identifier-2 data items that have the optional
ROUNDED keyword, the result saved into identifier-2 will be rounded according to the standard mathematicalrules for rounding values to the least-significant digit of precision. For example, if the PICTURE is 99V99 and theresult to be saved is 12.152, the saved value will be 12.15 whereas a result of 76.165 would save a value of 76.17.

4.

If the optional LENGTH OF clause is used on any literal-1 or identifier-1, the arithmetic value used during thecomputation process will be the length – in bytes – of the data item or literal, not the actual value of that data
item or literal.

5.

The optional ON SIZE ERROR clause allows you
to specify code that will be executed if theresult to be saved into an identifier-2 item
exceeds the capacity of that item. For
example, if the PICTURE is 99V99 and the result
to be saved is 101.43, a SIZE ERROR condition
would exist. Without an ON SIZE ERROR
clause, OpenCOBOL will store a value of 01.43
into the field. With an ON SIZE ERROR clause,the value of the identifier-2 item will beunchanged and imperative-statatement-1 will
be executed. As an illustration, observe thesmall demo program and output shown here.
It also illustrates some of the “EXCEPTION”
intrinsic functions (see section 6.1.7).

6.

Figure 6-27 - A Sample Program Using ON SIZE ERROR
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.

IDENTIFICATION DIVISION.
PROGRAM-ID. corrdemo.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Item-1
VALUE 1
PIC 99V99.
PROCEDURE DIVISION.
100-Main SECTION.
P1.
ADD 19 81.43 TO Item-1
ON SIZE ERRORDISPLAY 'Item-1:' Item-1
DISPLAY 'Error: ' FUNCTION EXCEPTION-STATUSDISPLAY 'Where: ' FUNCTION EXCEPTION-LOCATIONDISPLAY ' What: ' FUNCTION EXCEPTION-STATEMENT
END-ADD.
STOP RUN.

When executed, the program produces the following output:
Item-1:0100
Error: EC-SIZE-OVERFLOW
Where: corrdemo; P1 OF 100-Main; 9What: ADDThe NOT ON SIZE ERROR clause, if specified, will execute an imperative statement if the ADD statement did notencounter a field size overflow condition.

06FEB2009 Version

Page 6-31

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.5.2. ADD Format 2 – ADD GIVING
Figure 6-28 - ADD (GIVING) Syntax

ADD[ LENGTH OF ]literal-1
identifier-1...

[ TO identifier-2 ]GIVING { identifier-3 [ ROUNDED ] } ...

This format of the ADD statement generates
the arithmetic sum of all arguments thatappear before the TO (identifier-1 or literal1), adds that sum to the contents ofidentifier-2 (if any) and then replaces thecontents of the identifiers listed after the
GIVING (identifier-3) with that sum.

[ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ][ END-ADD ]1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Identifier-3 must be a numeric (edited or unedited) data item.

3.

Literal-1 must be a numeric literal.

4.

The contents of identifier-2 are not altered.

5.

The use and behavior of the ROUNDED, LENGTH OF, ON SIZE ERROR and NOT ON SIZE ERROR clauses is as
described in section 6.5.1 for Format 1 of the ADD statement.

6.5.3. ADD Format 3 – ADD CORRESPONDING
Figure 6-29 - ADD (CORRESPONDING) Syntax

ADD CORRESPONDING identifier-1 TO identifier-2 [ ROUNDED ][ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ]This format of the ADD statement
generates code equivalent to
individual ADD TO statements forcorresponding matches of data
items found subordinate to the two
identifiers.

[ END-ADD ]1.

The rules for identifying corresponding matches are as discussed in section 6.28.2 – MOVE CORRESPONDING.

2.

The use and behavior of the ROUNDED, ON SIZE ERROR and NOT ON SIZE ERROR clauses is as described in section
6.5.1 for Format 1 of the ADD statement.

06FEB2009 Version

Page 6-32

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.6. ALLOCATE
Figure 6-30 - ALLOCATE Syntax

ALLOCATE

expression-1 CHARACTERS
identifier-1

The ALLOCATE statement is used to dynamically allocate
memory at run-time.

[ INITIALIZED ][ RETURNING identifier-2 ]1.

If used, expression-1 must be an arithmetic expression with a non-zero positive integer value. To avoid confusing
the 06FEB2009 version of the syntax parser when using the “expression-1 CHARACTERS” option, enclose theexpression in parenthesis so it cannot be mistaken for the “identifier-1” option. This possibility of parser“confusion” will be corrected in a future OpenCOBOL 1.1 tarball.

2.

If used, identifier-1 should be an 01-level item defined with the BASED attribute in WORKING-STORAGE or LOCALSTORAGE. It can be an 01 item defined in the LINKAGE SECTION, but using such a data item is not recommended.

3.

If used, identifier-2 should be a USAGE POINTER data item.

4.

The optional RETURNING clause will return the address of the allocated memory block into the specified USAGE
POINTER item. When this option is used, OpenCOBOL will retain knowledge of the originally-requested size of theallocated memory block in case a FREE (section 6.19) statement is ever issued against that USAGE POINTER item.

5.

When the “identifier-1” option is used, INITIALIZE will initialize the allocated memory block according to the
PICTURE and (if any) VALUE clauses present in the definition of identifier-1 as if a INITIALIZE identifier-1 WITHFILLER ALL TO VALUE THEN TO DEFAULT were executed once identifier-1 was allocated. See section 6.24 for a
discussion of the INITIALIZE statement.

6.

When the “expression-1 CHARACTERS” option is used, INITIALIZE will initialize the allocated memory block tobinary zeros.

7.

If the INITIALIZE clause is not used, the initial contents of allocated memory will be left to whatever rules ofmemory allocation are in effect for the operating system the program is running under.

8.

There are two basic ways in which this statement is used. The simplest is:
ALLOCATE My-01-Item

With this form, a block of storage equal in size to the defined size of My-01-Item (which must have been definedwith the BASED attribute) will be allocated. The address of that block of storage will become the base address of
My-01-Item so that it and its subordinate data items become usable within the program.
A second (and equivalent) approach is:
ALLOCATE LENGTH OF My-01-Item CHARACTERS RETURNING The-Pointer.
SET ADDRESS OF My-01-Item TO The-Pointer.

With this form, the ALLOCATE statements allocates a block of memory exactly the size as would be needed for
My-01-Item; that address is returned into a pointer variable. The SET statement then “bases” the address of My01-Item to be the address of the memory block created by the ALLOCATE.
The only real functional difference between these two approaches is that – with the first – the INITIALIZED clause,
if any, will be honored.
9.

Referencing a BASED data item either before its storage has been ALLOCATEd or after its storage has been FREEd
23will lead to unpredictable results .

23

The COBOL standards like to use the term “unpredictable results” to indicate any sort of unexpected or undesirable
behavior – the results in this case probably are predictable though – the program will probably abort fromattempting to access an invalid address.

06FEB2009 Version

Page 6-33

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.7. CALL
Figure 6-31 - CALL Syntax

CALL

identifier-1
literal-1

USING

BY

RETURNING
GIVINGON

SIZE IS AUTO
SIZE IS DEFAULTUNSIGNED SIZE IS integer

identifier-2
literal-2

OMITTED

Identifier-3

EXCEPTION
OVERFLOWNOT ONREFERENCECONTENTVALUE...

The CALL
statement isused to transfer
control toanother
program, called asubprogram orsubroutine.

imperative-statement-1

EXCEPTION
OVERFLOW

imperative-statement-2[ END-CALL ]1.

The expectation is that the subprogram will eventually return control back to the CALLing program, at which point
the CALLing program will resume execution starting with the statement immediately following the CALL.
Subprograms are not required to return to their CALLers, however, and are free to halt program execution if they
wish.

2.

The EXCEPTION and OVERFLOW keywords may be used interchangeably.

3.

The RETURNING and GIVING keywords may be used interchangeably.

4.

The value of literal-1 or identifier-1 is the entry-point of the subprogram you wish to CALL. See sections 7.1.4 and7.1.5 for more information on how this entry-point is used.

5.

When you CALL a subroutine using identifier-1, you are forcing the runtime system to call a dynamically-loadable
module. See section 7.1.4 for information on dynamically-loadable modules.

6.

The optional ON EXCEPTION clause specifies code to be executed should the loading of a dynamically-loadable
module fail. By specifying ON EXCEPTION, the default behavior of generating an error message and halting the
program will be overridden – replaced by whatever logic you specify.

7.

The optional NOT ON EXCEPTION clause specifies code to be executed should the loading of a dynamicallyloadable module succeed.

8.

The USING clause defines a list of arguments that may be passed from the CALLing program to the subprogram.
The manner in which the arguments are passed depends upon the BY clause.

9.

If the subprogram being CALLed is an OpenCOBOL program, and if that program had the INITIAL attribute
specified on its PROGRAM-ID clause, all of the subprogram’s DATA DIVISION data will be restored to its initial
24
state each time the subprogram is executed . This [re]-initialization behavior will always apply to any data
defined in the subprogram’s LOCAL-STORAGE SECTION (if any), regardless of the use (or not) of INITIAL.

24

This is regardless of which entry-point within the subprogram is CALLed

06FEB2009 Version

Page 6-34

OpenCOBOL 1.1 Programmers Guide
10. BY REFERENCE (the default)passes the address of theargument to thesubprogram and will allow
the subprogram to changethat arguments value. Thiscan be dangerous when
passing a literal value as anargument.
11. BY CONTENT passes theaddress of a copy of theargument to thesubprogram. If thesubprogram changes thevalue of such an argument,
the original version of it
back in the CALLing program
remains unchanged.
Clearly, as Figure 6-32
shows, this is the safest way
to pass literal values to a
subprogram.

Figure 6-32 - CALL BY REFERENCE Can Sometimes have Unwanted Effects!
This program and subprogram…
Produce this
IDENTIFICATION DIVISION.
output…
PROGRAM-ID. testbed.
ENVIRONMENT DIVISION.
MAIN (Before CALL): lit=lit
DATA DIVISION.
MAIN (After CALL) : lit=XXX
PROCEDURE DIVISION.
000-Main.
DISPLAY "MAIN (Before CALL): lit=" "lit".
CALL "testsub" USING BY REFERENCE "lit".
DISPLAY "MAIN (After CALL) : lit=" "lit".
STOP RUN.
IDENTIFICATION DIVISION.
PROGRAM-ID. testsub.
Since the literal
ENVIRONMENT DIVISION.
was passed BYDATA DIVISION.
REFERENCE, it
LINKAGE SECTION.
was actually
01 Arg1
PIC X(3).
changed!
PROCEDURE DIVISION USING Arg1.
000-Main.
MOVE 'XXX' TO Arg1.
EXIT PROGRAM.
END PROGRAM testsub.
END PROGRAM testbed.

12. BY VALUE passes the address of the argument
as the argument. Check out the coding
example in Figure 6-33. Why would you want
this? The answer is simple – if the subprogramis written in OpenCOBOL, you probably
wouldn’t! This feature exists to provide
compatibility with C, C++ and other languages.
13. The RETURNING clause allows you to specify adata item into which the subroutine should
return a value. If you use this clause on the
CALL, the subroutine should include a
RETURNING clause on its PROCEDUREDIVISION header. Of course, a subroutine may
pass a value back in ANY argument passed BY
REFERENCE.
14. For additional information, see sections 6.8(CANCEL), 6.16 (ENTRY), 6.18 (EXIT) and 6.21
(GOBACK).

06FEB2009 Version

PROCEDURE DIVISION

Figure 6-33 - CALL BY VALUEThis program and subprogram…
IDENTIFICATION DIVISION.
PROGRAM-ID. testbed.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Item USAGE BINARY-LONG VALUE 256.
PROCEDURE DIVISION.
000-Main.
CALL "testsub1"
USING BY CONTENT "lit",
BY VALUE
Item.
Produce this
STOP RUN.
output…
END PROGRAM testbed.
IDENTIFICATION DIVISION.
Arg1=lit
PROGRAM-ID. testsub1.
The-Pointer=0x00000100
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 The-PointerUSAGE POINTER.
LINKAGE SECTION.
01 Arg1
PIC X(3).
01 Arg2
PIC X(4).
PROCEDURE DIVISION USING Arg1, Arg2.
000-Main.
SET The-Pointer TO ADDRESS OF Arg2.
DISPLAY "Arg1=" Arg1.
DISPLAY " The-Pointer=" The-Pointer.
EXIT PROGRAM.
END PROGRAM testsub1.

Page 6-35

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.8. CANCEL
Figure 6-34 - CANCEL Syntax

CANCEL1.

identifier-1
literal-1...

The CANCEL statement unloads the dynamically-loadable
module containing the entry-point specified as literal-1 or
identifier-1 from memory.

If the dynamically-loadable module unloaded by the CANCEL is subsequently re-executed, all DATA DIVISION
storage for that dynamically-loadable module will once again be in its initial state.

06FEB2009 Version

Page 6-36

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.9. CLOSE
Figure 6-35 - CLOSE Syntax

CLOSE

file-name-1

REEL
UNIT

FOR REMOVAL...

The CLOSE statement terminates
the programs access to thespecified file(s) or to the currently
mounted reel/unit of the file(s).

WITH LOCKWITH NO REWIND
1.

The CLOSE statement may only be executed against files that have been successfully OPENed.

2.

The REEL, UNIT and NO REWIND clauses are available only for ORGANIZATION SEQUENTIAL (either LINE orRECORD BINARY) SEQUENTIAL files. The words REEL and UNIT may be used interchangeably, and reflect a file thatis stored on or will be written to multiple removable tapes/disks. Not all systems support such devices, and
OpenCOBOL features to manipulate such multiple-unit files may not be functional on your system.

3.

The REEL and UNIT phrases are intended for use with files which have had MULTIPLE REEL or MULTIPLE UNIT
specified in their SELECT clause. If the run-time system does not recognize multi-unit files, the CLOSE REEL and
CLOSE UNIT statements will perform no function.

4.

Once a file has been closed, it cannot be accessed again until it has been successfully re-OPENed.

5.

A successful CLOSE without REEL or UNIT executed against a file that was OPENed in either OUTPUT or EXTEND
mode will write any remaining unwritten record buffers to the file; regardless of OPEN mode, any record locks
held for closed files will be released as well. A closed file will then be no longer available for subsequent READ,
WRITE, REWRITE, START or DELETE statements until it is once again OPENed.

6.

A CLOSE WITH LOCK option will prevent your program from re-opening the file again in the same program
execution.

7.

A successful CLOSE with REEL or UNIT will write any remaining unwritten record buffers to the closed files and will
release any record locks held for those files as well. The currently mounted reel/unit of the file will bedismounted and the next reel/unit requested. The file’s status remains OPEN.

06FEB2009 Version

Page 6-37

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.10. COMMIT
Figure 6-36 - COMMIT Syntax

COMMIT

The COMMIT statement performs an UNLOCK against
every currently-OPEN file.

1. See the UNLOCK statement (section 6.48) for additional details.

06FEB2009 Version

Page 6-38

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.11. COMPUTE
Figure 6-37 - COMPUTE Syntax

EQUAL=[ ON SIZE ERROR imperative-statement-1 ]COMPUTE { identifier-1 [ ROUNDED ] } ...

arithmetic-expression[ NOT ON SIZE ERROR imperative-statement-2 ][ END-COMPUTE ]The COMPUTE statement
provides a means of easily
performing complex
arithmetic operations with asingle statement, instead ofusing cumbersome andpossibly confusing sequencesof ADD, SUBTRACT,MULTIPLY and DIVIDE
statements.

1.

The word EQUAL and the equals-sign (=) may be used interchangeably.

2.

The ON SIZE ERROR, NOT ON SIZE ERROR and ROUNDED clauses are coded and operate the same as the clauses ofthe same name available to the ADD statement (see section 6.5.1).

06FEB2009 Version

Page 6-39

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.12. CONTINUE
Figure 6-38 - CONTINUE Syntax

CONTINUE
1.

The CONTINUE statement is a no-operation statement,
performing no action whatsoever.

The CONTINUE statement is often used with IF statements (section 6.23) as a place-holder for conditionallyexecuted code that is either not yet needed or not yet designed. The following two sentences are equivalent.
One uses CONTINUE statements to mark places where code may need to be inserted in the future.
“Minimalist” Coding(Specifying only what is necessary)

Coding With CONTINUE(Documenting where code might be needed someday)

IF A = 1
IF B = 1
DISPLAY „A=1 & B=1‟ END-DISPLAY
END-IFELSEIF A = 2
IF B = 2
DISPLAY „A=2 & B=2‟ END-DISPLAY
END-IF
END-IF
END-IFIF A = 1
IF B = 1
DISPLAY „A=1 & B=1‟ END-DISPLAYELSE
CONTINUE
END-IFELSEIF A = 2
IF B = 2
DISPLAY „A=2 & B=2‟ END-DISPLAYELSE
CONTINUE
END-IFELSE
CONTINUE
END-IF
END-IF

Coding such as this is generally a matter of personal preference or site coding standards. There is no difference inthe object code generated by the two, so there isn’t a run-time efficiency issue (just one of “coding efficiency”).
2.

Another IF-statement usage for CONTINUE is to avoid the use of NOT in the conditional expression coded on the
IF statement. This too is a personal and/or site standards issue. Here’s an example:
Without CONTINUE
IF Action-Flag NOT = „I‟ AND „U‟DISPLAY „Invalid Action-Flag‟
EXIT PARAGRAPH
END-IF

With CONTINUE
IF Action-Flag = „I‟ OR „U‟
CONTINUEELSEDISPLAY „Invalid Action-Flag‟
EXIT PARAGRAPH
END-IF

Because of the way COBOL (OpenCOBOL included) handles the abbreviation of conditional expressions, theconditional expression in the left-hand box is actually a short-hand version of the (not-so-intuitive):
IF Action-Flag NOT = „I‟ AND Action-Flag NOT = „U‟Many programmers would have coded the “IF” (incorrectly) as “ IF Action-Flag NOT = „I‟ OR „U‟” – thisis sure to cause run-time problems.
This causes many programmers to consider the code in the right-hand box to be more readable, even though it isa little longer.

06FEB2009 Version

Page 6-40

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.13. DELETE
Figure 6-39 - DELETE Syntax

DELETE file-name RECORD[ INVALID KEY imperative-statement-1 ][ NOT INVALID KEY imperative-statement-2 ]The DELETE statement logically deletes a record froman ORGANIZATION RELATIVE or ORGANIZATIONINDEXED file.

[ END-DELETE ]1.

The INVALID KEY and NOT INVALID KEY clauses cannot be specified for a file who’s ACCESS MODE IS SEQUENTIAL.

2.

The INVALID KEY clause provides the ability to react to a DELETE failure, while the NOT INVALID KEY clause gives
the program the capability of specifying actions to be taken if the DELETE succeeds.

3.

The ORGANIZATION of file-name must be RELATIVE or INDEXED.

4.

For RELATIVE or INDEXED files in the SEQUENTIAL access mode, the last input-output statement executed for filename prior to the execution of the DELETE statement must have been a successfully executed READ statement.
That READ will therefore identify the record to be deleted.

5.

If file-name is a RELATIVE file whose ACCESS MODE is either RANDOM or DYNAMIC, the record to be deleted isthe one whose relative record number is currently the value of the field specified as the files RELATIVE KEY.

6.

If file-name is an INDEXED file whose ACCESS MODE is RANDOM or DYNAMIC, the record to be deleted is the one
whose primary key is currently the value of the field specified as the RECORD KEY of the file.

7.

An INVALID KEY condition will exist, and can be dealt with via the INVALID KEY clause, if the record specified to bedeleted by the RELATIVE KEY or RECORD KEY value does not exist in an access mode RANDOM or DYNAMIC file.
This is a condition that cannot exist for ACCESS MODE SEQUENTIAL files because of rule #4. DELETE failures on
ACCESS MODE SEQUENTIAL files can only be “handled” via DECLARATIVES.

06FEB2009 Version

Page 6-41

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.14. DISPLAY
6.14.1. DISPLAY Format 1 – Upon Console
Figure 6-40 - DISPLAY (Upon Console) Syntax

identifier-1
literal-1

DISPLAY

This format of the DISPLAY statement displays the
specified identifier contents and/or literal values on theshell or console window from which the program wasstarted.

...

[ UPON mnemonic-name ]The displayed text will appear starting in column 1 of thenext available line. If all screen lines have previously had
text displayed to them, the screen will scroll upward oneline and the text will appear on the last line.

[ WITH NO ADVANCING ][ exception-handler ][ END-DISPLAY ]1. If no UPON clause is specified, UPON CONSOLE will be assumed.
2. The specified mnemonic-name must be CONSOLE, CRT, PRINTER or any user-defined mnemonic name associatedwith one of these devices within the SPECIAL-NAMES paragraph (see section 4.1.4). All such mnemonics specify
the same destination – the shell (UNIX) or console (Windows) window from which the program was run.
3. The NO ADVANCING clause, if used, will suppress the normal carriage-return / line-feed sequence that normally isadded to the end of any console display.

6.14.2. DISPLAY Format 2 – Access Command-Line Arguments
Figure 6-41 - DISPLAY (Access Command-line Arguments) Syntax

identifier-1
literal-1

DISPLAY... UPON

ARGUMENT-NUMBER
COMMAND-LINE[ exception-handler ][ END-DISPLAY ]1.

This form of the DISPLAY
statement may be used to specify
the command-line argument
number to be retrieved by asubsequent ACCEPT or to specify
a new value for the commandline arguments themselves.

Executing a DISPLAY … UPON COMMAND-LINE will influence subsequent ACCEPT … FROM COMMAND-LINEstatements (which will then return the DISPLAYed value), but will not influence subsequent ACCEPT … FROMARGUMENT-VALUE statements – these will continue to return the original program execution parameters.

6.14.3. DISPLAY Format 3 – Access or Set Environment Variables
Figure 6-42 - DISPLAY (Access / Set Environment Variables) Syntax

DISPLAY

identifier-1... UPON
literal-1[ exception-handler ]ENVIRONMENT-VALUEENVIRONMENT-NAME

This form of the DISPLAY
statement can be used to create
or modify environment variables.

[ END-DISPLAY ]1.

To create or change an environment variable will require two DISPLAY statements, which must be executed in thefollowing sequence:

06FEB2009 Version

Page 6-42

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISIONDISPLAY
environment-variable-name
END-DISPLAY

UPON ENVIRONMENT-NAMEDISPLAY
environment-variable-value
END-DISPLAY

UPON ENVIRONMENT-VALUE

2.

Environment variables created or changed from within OpenCOBOL programs will be available to any sub-shellprocesses spawned by that program (i.e. CALL “SYSTEM”) but will not be known to the shell or console windowthat started the OpenCOBOL program.

3.

Consider using SET ENVIRONMENT (section 6.39.1) in lieu of DISPLAY to set environment variables as it is much
simpler.

6.14.4. DISPLAY Format 4 – Screen Data
Figure 6-43 - DISPLAY (Screen Data) Syntax

identifier-1
literal-1

DISPLAY...

AT LINE NUMBER

integer-1
identifier-2

AT

COLUMNPOSITIONNUMBERAT

integer-4
identifier-5

WITH

This format of the
DISPLAY statement
presents data onto aformatted screen.

COLUMNPOSITIONNUMBER

integer-3
identifier-4

BELL | BEEPREVERSE-VIDEOUNDERLINEOVERLINE
HIGHLIGHTLOWLIGHT
BLINK
FOREGROUND-COLOR IS

integer-5
identifier-6

BACKGROUND-COLOR IS

integer-6
identifier-7

SCROLL

UP
DOWN

integer-2
identifier-3

BY

integer-6
identifier-7

...

LINES
LINE

[ exception-handler ][ END-DISPLAY ]1.

If identifier-1 is defined in the SCREEN SECTION, all cursor positioning (AT) and attribute specifications (WITH) aretaken from the SCREEN SECTION definition and anything specified on the DISPLAY will be ignored. Use the AT and
WITH options only when DISPLAYing a data item that was not defined in the SCREEN SECTION.

2.

The various AT clauses provide a means of positioning the cursor to a specific spot on the screen before the datastis presented to the screen. The literal-3 / identifier-4 value must be a four-digit value with the 1 two digits
indicating the line where the cursor should be positioned and the last two digits being the column.

3.

See section 6.4.4 (ACCEPT ACCEPT Format 4 – Retrieve Screen Data) for a description of the SCROLL option.

4.

The remaining “WITH” options were described in section 5.6.

06FEB2009 Version

Page 6-43

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.14.5. DISPLAY Exception Handling
Figure 6-44 - Exception Handling (DISPLAY) Syntax

ON EXCEPTION
imperative-statement-1

NOT ON EXCEPTION
imperative-statement-2

06FEB2009 Version

The EXCEPTION and NOT EXCEPTION clauses available on
all formats of the DISPLAY verb allow you to specify code
to be executed specifically upon the failure or success(respectively) of the DISPLAY. Since DISPLAY does not set
any sort of return code or status flag, this is the only way
to detect success and failure.

Page 6-44

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.15. DIVIDE
6.15.1. DIVIDE Format 1 – DIVIDE INTO
Figure 6-45 - DIVIDE INTO Syntax

DIVIDE

identifier-1
literal-1

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

[ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ][ END-DIVIDE ]This format of DIVIDE will divide a
specified value into one or moredata items, replacing each of thosedata items with the result of its oldvalue divided by the identifier-1 /literal-1 value. Any remainder
calculated as a result of the division
is discarded.

1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Literal-1 must be a numeric literal.

3.

The ON SIZE ERROR, NOT ON SIZE ERROR and ROUNDED clauses are coded and operate the same as the clauses ofthe same name available to the ADD statement (see section 6.5).

4.

If the identifier-1 / literal-1 value is zero, a SIZE ERROR condition will result. A SIZE ERROR will also occur if theresult of the division requires more digits of precision to the left of a decimal-point than are available in any of thereceiving fields.

6.15.2. DIVIDE Format 2 – DIVIDE INTO GIVING
Figure 6-46 - DIVIDE INTO GIVING Syntax

DIVIDE

identifier-1
literal-1

INTO

identifier-2
literal-2

GIVING { identifier-3 [ ROUNDED ] } ...

[ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ][ END-DIVIDE ]This format of DIVIDE will divide
a specified value (identifier-1 /literal-1) into another value(identifier-2 / literal-2) and willthen replace the contents of one
or more receiving data items(identifier-3 …) with the results ofthat division. Any remainder
calculated as a result of thedivision is discarded.

1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Identifier-3 must be a numeric (edited or unedited) data item.

3.

Literal-1 and literal-2 must be numeric literals.

4.

The ON SIZE ERROR, NOT ON SIZE ERROR and ROUNDED clauses are coded and operate the same as the clauses ofthe same name available to the ADD statement (see section 6.5).

5.

If the identifier-1 / literal-1 value is zero, a SIZE ERROR condition will result. A SIZE ERROR will also occur if theresult of the division requires more digits of precision to the left of a decimal-point than are available in any of thereceiving fields.

06FEB2009 Version

Page 6-45

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.15.3. DIVIDE Format 3 – DIVIDE BY GIVING
Figure 6-47 - DIVIDE BY GIVING Syntax

DIVIDE

identifier-1
literal-1

BY

identifier-2
literal-2This format of DIVIDE will divide a
specified value (identifier-1 /literal-1) by another value(identifier-2 / literal-2) and willthen replace the contents of one
or more receiving data items(identifier-3 …) with the results ofthat division. Any remainder
calculated as a result of thedivision is discarded.

GIVING { identifier-3 [ ROUNDED ] } ...

[ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ][ END-DIVIDE ]1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Identifier-3 must be a numeric (edited or unedited) data item.

3.

Literal-1 and literal-2 must be numeric literals.

4.

The ON SIZE ERROR, NOT ON SIZE ERROR and ROUNDED clauses are coded and operate the same as the clauses ofthe same name available to the ADD statement (see section 6.5).

5.

If the identifier-2 / literal-2 value is zero, a SIZE ERROR condition will result. A SIZE ERROR will also occur if theresult of the division requires more digits of precision to the left of a decimal-point than are available in any of thereceiving fields.

6.15.4. DIVIDE Format 4 – DIVIDE INTO REMAINDER
Figure 6-48 - DIVIDE INTO REMAINDER Syntax

DIVIDE

identifier-1
literal-1

INTO

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 ]This format of DIVIDE will divide a
specified value (identifier-1 / literal1) into another value (identifier-2 /literal-2) and will then replace thecontents of a single data item
(identifier-3) with the results of thatdivision. Any remainder calculated
as a result of the division is saved in
identifier-4.

1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Identifier-3 and identifier-4 must be numeric (edited or unedited) data items.

3.

Literal-1 and literal-2 must be numeric literals.

4.

The ON SIZE ERROR, NOT ON SIZE ERROR and ROUNDED clauses are coded and operate the same as the clauses ofthe same name available to the ADD statement (see section 6.5).
If the identifier-1 / literal-1 value is zero, a SIZE ERROR condition will result. A SIZE ERROR will also occur if theresult of the division requires more digits of precision to the left of a decimal-point than are available in any of thereceiving fields.

5.

06FEB2009 Version

Page 6-46

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.15.5. DIVIDE Format 5 – DIVIDE BY REMAINDER
Figure 6-49 - DIVIDE BY REMAINDER Syntax

DIVIDE

identifier-1
literal-1

BY

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 ]This format of DIVIDE will divide a
specified value (identifier-1 / literal-1)
by another value (identifier-2 / literal2) and will then replace the contents
of a single receiving data item
(identifier-3) with the results of thatdivision. Any remainder calculated asa result of the division is saved in
identifier-4.

1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Identifier-3 and identifier-4 must be umeric (edited or unedited) data items.

3.

Literal-1 and literal-2 must be numeric literals.

4.

The ON SIZE ERROR, NOT ON SIZE ERROR and ROUNDED clauses are coded and operate the same as the clauses ofthe same name available to the ADD statement (see section 6.5).

5.

If the identifier-2 / literal-2 value is zero, a SIZE ERROR condition will result. A SIZE ERROR will also occur if theresult of the division requires more digits of precision to the left of a decimal-point than are available in any of thereceiving fields.

06FEB2009 Version

Page 6-47

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.16. ENTRY
Figure 6-50 - ENTRY Syntax

The ENTRY statement is used todefine an alternate entry-point
into a subroutine, along withthe arguments that subroutine
will be expecting.

ENTRY literal-1
BY

USING

REFERENCECONTENTVALUE
SIZE IS AUTO
SIZE IS DEFAULTUNSIGNED SIZE IS integer...

identifier-1

1. You may not use an ENTRY statement in a nested subprogram (see section 2.1).
2. The USING clause matches up against the USING clause of any CALL statements that will be invoking thesubroutine.
3. The literal-1 value will specify the entry-point name of the subroutine. It must be specified exactly on CALL
statements (with regard to the use of upper- and lower-case letters) as it is specified on the ENTRY statement.

06FEB2009 Version

Page 6-48

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.17. EVALUATE
Figure 6-51 - EVALUATE Syntax
TRUE
FALSE
expression-1
identifier-1
literal-1

EVALUATE

WHEN[ ALSO

TRUE
FALSE
expression-2
identifier-2
literal-2

ANY
condition-1
TRUE
arith-expr-2
FALSE
identifier-3[ NOT ]
literal-3

ALSO

] ...

THROUGH
THRU

ANY
condition-2
TRUE
arith-expr-4
FALSE[ NOT ] identifier-5
literal-5

The EVALUATE
statement provides
a means of defining
processing thatshould take place
under a variety ofrelated circumstancesarith-expr-3
identifier-4
literal-4

THROUGH
THRU

arith-expr-5
identifier-6
literal-6

...

...

Imperative-statement-1[ WHEN OTHER ] imperative-statement-2 ][ END-EVALUATE ]1.

The reserved words THRU and THROUGH may be used interchangeably.

2.

When using THROUGH, the values connected by a THROUGH clause (arith-expr-n, identifier-n and/or literal-n)must be the same class. For example:

Legal:

Not Legal:(3 + Years-Of-Service) THROUGH 99“A” THRU “Z”
X’00’ THRU X’1F’
15.7 THROUGH 19.4

0 THRU “A”
Last-Name THRU Zip-Code (Assuming Last-Name is
PIC X and Zip-Code is PIC 9)

3.

The values specified after the EVALUATE verb but before the first WHEN clause are known as selection subjects
while the values specified on each WHEN clause are known as selection objects.

4.

Each WHEN clause must have the same number of selection objects as the EVALUATE verb has selection subjects.

5.

Each EVALUATE clause’s selection subject will be tested for equality to each WHEN clauses corresponding
selection object.

6.

The first WHEN clause found where all such equality tests described in rule #5 result in TRUE results will be theone whose imperative statement will be executed.

7.

If none of the WHEN clauses have all such equality tests as described in rule #5 resulting in TRUE results then theimperative statement associated with the WHEN OTHER clause (imperative-statement-2) will be executed. If
there is no WHEN OTHER clause, control will simply fall into the next statement following the EVALUATE
statement.

8.

Once a WHEN or WHEN OTHER clause’s imperative statement has been executed, control will fall into the next
statement following the EVALUATE statement.

9.

Using a selection object of ANY will cause an automatic match with whatever selection subject the ANY wasmatched against.

Here’s a “case study” that will illustrate the usefulness of the EVALUATE statement. A program is being developed tocompute the interest to be paid on accounts based upon their average daily balance [ADB]. The business rules for thisprocess are as follows:
1.

Interest-bearing checking accounts will receive no interest if their ADB is less than $1000. Interest-bearing
checking accounts with an ADB $1000 to $1499.99 will receive 1% of the ADB as interest. Those with an ADB of$1500 or more will receive 1.5% of the ADB as interest.

06FEB2009 Version

Page 6-49

OpenCOBOL 1.1 Programmers Guide
2.
3.
4.

PROCEDURE DIVISION

Statement savings accounts will receive 1.5% interest on an ADB up to $10000 and 1.75% for any ADB amounts
over $10000.
Platinum savings accounts receive 2% interest on their ADB, regardless of average balance amounts.
No other types of accounts receive interest.

Here’s a sample OpenCOBOL program that can be used to test an “EVALUATE” implementation of these businessrules. Output from the program is shown in the inset.
Figure 6-52 - An EVALUATE Demo Program>>SOURCE FORMAT FREE
Enter Account Type (c,s,p,other): c
IDENTIFICATION DIVISION.
Enter Ave Daily Balance (nnnnnnn.nn): 250
PROGRAM-ID. evaldemo.
Accrued Interest =0.00
ENVIRONMENT DIVISION.
Enter Account Type (c,s,p,other): c
DATA DIVISION.
Enter Ave Daily Balance (nnnnnnn.nn): 1250
WORKING-STORAGE SECTION.
Accrued Interest = 12.50
01 Account-TypePIC X(1).
Enter Account Type (c,s,p,other): c
88 Interest-Bearing-Checking VALUE 'c'.
Enter Ave Daily Balance (nnnnnnn.nn): 1899.99
88 Statement-Savings
VALUE 's'.
Accrued Interest = 28.50
88 Platinum-Savings
VALUE 'p'.
Enter Account Type (c,s,p,other): s
01 ADB-Char
PIC X(10).
Enter Ave Daily Balance (nnnnnnn.nn): 22000.00
01 Ave-Daily-Balance
PIC 9(7)V99.
Accrued Interest = 2430.00
01 Formatted-Amount
PIC Z(6)9.99.
Enter Account Type (c,s,p,other): p
01 Interest-Amount
PIC 9(7)V99.
Enter Ave Daily Balance (nnnnnnn.nn): 1.98
PROCEDURE DIVISION.
Accrued Interest =0.04
000-Main.
PERFORM FOREVERDISPLAY "Enter Account Type (c,s,p,other): " WITH NO ADVANCING
ACCEPT Account-Type
IF Account-Type = SPACESSTOP RUN
END-IFDISPLAY "Enter Ave Daily Balance (nnnnnnn.nn): " WITH NO ADVANCING
ACCEPT ADB-Char
MOVE FUNCTION NUMVAL(ADB-Char) TO Ave-Daily-Balance
EVALUATE TRUE ALSO Ave-Daily-Balance
WHEN Interest-Bearing-Checking ALSO 0.00 THRU 999.99
MOVE 0 TO Interest-Amount
WHEN Interest-Bearing-Checking ALSO 1000.00 THRU 1499.99
COMPUTE Interest-Amount ROUNDED = 0.01 * Ave-Daily-Balance
WHEN Interest-Bearing-Checking ALSO ANYCOMPUTE Interest-Amount ROUNDED = 0.015 * Ave-Daily-Balance
WHEN Statement-Savings ALSO 0.00 THRU 10000.00
COMPUTE Interest-Amount ROUNDED = 0.015 * Ave-Daily-Balance
WHEN Statement-Savings ALSO ANYCOMPUTE Interest-Amount ROUNDED = 0.015 * Ave-Daily-Balance+ 0.175 * (Ave-Daily-Balance - 10000)
WHEN Platinum-Savings ALSO ANYCOMPUTE Interest-Amount ROUNDED = 0.020 * Ave-Daily-Balance
WHEN OTHER
MOVE 0 TO Interest-Amount
END-EVALUATE
MOVE Interest-Amount TO Formatted-AmountDISPLAY "Accrued Interest = " Formatted-Amount
END-PERFORM.

06FEB2009 Version

Page 6-50

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.18. EXIT
Figure 6-53 - EXIT Syntax

EXIT

1.

PROGRAMPERFORM [ CYCLE ]SECTIONPARAGRAPH

When used without any of the optional clauses, the“EXIT” statement simply provides a common “GOTO” end point for a series of procedures. Figure 6-54
illustrates the use of the EXIT statement.

2.

When an EXIT statement is used, it must be the only
statement in the paragraph in which it occurs.

3.

The EXIT statement is a no-operation statement(much like the CONTINUE statement).

The EXIT statement is a multi-purpose statement; it may
provide a common end point for a series of procedures,exit an inline PERFORM, a paragraph or a section or it
may mark the logical end of a called program.

Figure 6-54 - Using the EXIT Statement01

Switches.
05 Input-File-Switch
PIC X(1).
88 EOF-On-Input-File VALUE „Y‟ FALSE „N‟.

.
.
.
SET EOF-On-Input-File TO FALSE.
PERFORM 100-Process-A-Transaction
UNTIL EOF-On-Input-File.
.
.
.
100-Process-A-Transaction.
READ Input-File AT END
SET EOF-On-Input-File TO TRUE
EXIT PARAGRAPH.
IF Input-Rec of Input-File = SPACES
EXIT PARAGRAPH. *> IGNORE BLANK RECORDS!

process the record just read4.

An EXIT PARAGRAPH statement transfers control to a point immediately past the end of the current paragraph,
while an EXIT SECTION statement causes control to pass to point immediately past the last paragraph in thecurrent section.
If the EXIT PARAGRAPH or EXIT SECTION resides in aparagraph within the scope of a procedural
PERFORM (section 6.32.1), control will be returnedback to the PERFORM for evaluation of any TIMES,VARYING and/or UNTIL clauses. It the EXIT
PARAGRAPH or EXIST SECTION resides outside thescope of a procedural PERFORM, control simply
transfers to the first executable statement in thenext paragraph (EXIT PARAGRAPH) or section (EXITSECTION).
Figure 6-55 shows how the example shown in Figure
6-54 could have been coded without a GO TO by
utilizing an EXIT PARAGRAPH statement.

Figure 6-55 - Using EXIT PARAGRAPH
01

Switches.
05 Input-File-Switch
PIC X(1).
88 EOF-On-Input-File VALUE „Y‟ FALSE „N‟.

.
.
.
SET EOF-On-Input-File TO FALSE.
PERFORM 100-Process-A-Transaction
UNTIL EOF-On-Input-File.
.
.
.
100-Process-A-Transaction.
READ Input-File AT END
SET EOF-On-Input-File TO TRUE
EXIT PARAGRAPH.
IF Input-Rec of Input-File = SPACES
EXIT PARAGRAPH. *> IGNORE BLANK RECORDS!

process the record just read5.

The EXIT PERFORM and EXIT PERFORM CYCLE statements are intended to be used in conjunction with an inline
PERFORM statement (section 6.32.2).

6.

An EXIT PERFORM CYCLE will terminate the current iteration of the inline PERFORM, giving control to any TIMES,VARYING and/or UNTIL clauses for them to determine if another cycle needs to be performed.

7.

An EXIT PERFORM will terminate the inline PERFORM
outright, transferring control to the first statement
following the PERFORM. Figure 6-56 shows the final
modification to the Figure 6-54 example; by using
Inline PERFORM and EXIT PERFORM statements we
can really streamline processing.

Figure 6-56 - Using the EXIT PERFORM Statement
PERFORM FOREVER
READ Input-File AT END
EXIT PERFORM
END-READ
IF Input-Rec of Input-File = SPACES
EXIT PERFORM CYCLE *> IGNORE BLANK RECORDS!
END-IF

process the record just readEND PERFORM

06FEB2009 Version

Page 6-51

OpenCOBOL 1.1 Programmers Guide
8.

PROCEDURE DIVISION

Finally, the EXIT PROGRAM statement terminates the execution of subroutine (i.e. a program that has been
CALLed by another), returning to the CALLing program at the statement following the CALL. If executed by a main
program, the EXIT PROGRAM statement is non-functional. The COBOL2002 standard has made a common
extension to the COBOL language - the GOBACK statement (section 6.21) - standard; the GOBACK statement
should be strongly considered as the preferred alternative to EXIT PROGRAM for new programs.

06FEB2009 Version

Page 6-52

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.19. FREE
Figure 6-57 - FREE Syntax

FREE { [ ADDRESS OF ] identifier-1 } ...

The FREE statement releases memory previously
allocated to the program by the ALLOCATE statement(section 6.6).

1.

Identifier-1 must be a USAGE POINTER data item or an 01-level data item with the BASED attribute.

2.

If identifier-1 is a USAGE POINTER data item and it contains a valid address, the FREE statement will release thememory block the pointer references. In addition, any BASED data items that the pointer was used to provide anaddress for will become un-based and therefore un-usable. If identifier-1 did not contain a valid address, noaction will be taken.

3.

If identifier-1 is a BASED data item and that data item is currently based (meaning it currently has memory
allocated for it), its memory is released and identifier-1 will become un-based and therefore un-usable. If
identifier-1 was not based, no action will be taken.

4.

The ADDRESS OF clause adds no special function to the FREE statement.

06FEB2009 Version

Page 6-53

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.20. GENERATE
Figure 6-58 - GENERATE Syntax

GENERATE

06FEB2009 Version

identifier-1
report-name-1

Although syntactically recognized by the OpenCOBOL
compiler, the GENERATE statement is non-functional
because the RWCS (COBOL Report Writer) is not currently
supported by OpenCOBOL.

Page 6-54

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.21. GOBACK
Figure 6-59 - GOBACK Syntax

The GOBACK statement is used to logically terminate an executing program.

GOBACK1.

If executed within a subroutine (i.e. a CALLed program), GOBACK will transfer control back to the CALLing
program, specifically to the statement following the CALL.

2.

If executed within a main program, GOBACK will act as a STOP RUN statement (section 6.42).

06FEB2009 Version

Page 6-55

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.22. GO TO
6.22.1. GO TO Format 1 – Simple GO TO
Figure 6-60 - Simple GOTO Syntax

GO TO procedure-name1.

This form of the GO TO statement unconditionally transfers control in a program
to the specified procedure-name.

If the specified procedure name is a SECTION, control will transfer to the first paragraph in that section.

6.22.2. GO TO Format 2 – GO TO DEPENDING ON
Figure 6-61 - GOTO DEPENDING ON Syntax

GO TO procedure-name-1 ...
DEPENDING ON identifier-1

This form of the GO TO statement will transfer control to any one of anumber of specified procedure names depending on the numeric value ofthe identifier specified on the statement.

1.

The PICTURE and/or USAGE of the specified identifier-1 must be such as to define it as a numeric, unedited,
preferably unsigned integer data item.

2.

If the value of identifier-1 has the value 1, control will be transferred to the 1 specified procedure name. If thendvalue is 2, control will transfer to the 2 procedure name, etc.

3.

If the value of identifier-1 is less than 1 or exceeds the total number of procedure names specified on the GO TO
statement, control will simply fall thru into the next statement following the GO TO.

4.

The following chart shows how GO TO DEPENDING ON may be used in a real application situation, and comparesit against the two alternatives – IF and EVALUATE.

st

Figure 6-62 - GOTO DEPENDING ON vs IF vs EVALUATEGOTO DEPENDING ON
GO TO PROCESS-ACCT-TYPE-1
PROCESS-ACCT-TYPE-2
PROCESS-ACCT-TYPE-3
DEPENDING ON ACCT-TYPE.
Code to handle invalid account typeGO TO DONE-WITH-ACCT-TYPE.
PROCESS-ACCT-TYPE-1.
Code to handle account type 1
GO TO DONE-WITH-ACCT-TYPE.
PROCESS-ACCT-TYPE-2.
Code to handle account type 2
GO TO DONE-WITH-ACCT-TYPE.
PROCESS-ACCT-TYPE-3.
Code to handle account type 3
DONE-WITH-ACCT-TYPE.

IFEVALUATE

IF ACCT-TYPE = 1
Code to handle account type 1
ELSE IF ACCT-TYPE = 2
Code to handle account type 2
ELSE IF ACCT-TYPE = 3
Code to handle account type 3
ELSE
Code to handle invalid account type
END-IF.

EVALUATE ACCT-TYPE
WHEN 1
Code to handle account type 1
WHEN 2
Code to handle account type 2
WHEN 3
Code to handle account type 3
WHEN OTHER
Code to handle invalid account type
END-EVALUATE.

There is no question that “modern programming philosophy” would prefer the EVALUATE approach. Aninteresting note is that the code generated by the IF and EVALUATE approaches is virtually identical. Sometimes,
NEW, while it might be considered BETTER, doesn’t always mean DIFFERENT!

06FEB2009 Version

Page 6-56

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.23. IF
Figure 6-63 - IF Syntax

IF conditional-expression THEN
imperative-statement-1

The IF statement is used to conditionally execute a single
imperative statement or to select one of two different
imperative statements based upon the TRUE/FALSE valueof a conditional expression.

[ ELSE imperative-statement-2 ][ END-IF ]1.

If conditional-expression evaluates to TRUE, imperative-statement-1 will be executed regardless of whether or not
an ELSE clause is present. Once imperative-statement-1 has been executed, control falls into the first statement
following the END-IF or to the first statement of the next sentence if there is no END-IF clause.

2.

If the optional ELSE clause is present and conditional-expression-1 evaluates to FALSE, then (and only then)imperative-statement-2 will be executed. Once imperative-statement-2 has been executed, control falls into thefirst statement following the END-IF or to the first statement of the next sentence if there is no END-IF clause.

3.

See section 6.1.5 for a discussion (and examples) of how periods (.) and END-IF statements are both similar to anddifferent from each other in the way they are capable of ending the scope of an IF statement.

06FEB2009 Version

Page 6-57

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.24. INITIALIZE
Figure 6-64 - INITIALIZE Syntax

The INITIALIZE
statement sets theelementary
item(s) specified
as identifier-1, or
those elementary
items subordinate
to group items
specified as
identifier-1 tospecific values.

INITIALIZE identifier-1 … [ WITH FILLER ]ALL
ALPHABETIC
ALPHANUMERICNUMERICALPHANUMERIC-EDITEDNUMERIC-EDITEDNATIONAL
NATIONAL-EDITED

THEN REPLACINGTO VALUEALL
ALPHABETIC
ALPHANUMERICNUMERICALPHANUMERIC-EDITEDNUMERIC-EDITEDNATIONAL
NATIONAL-EDITEDDATA BY [ LENGTH OF ]literal-1
identifier-2...

[ THEN TO DEFAULT ]1.

The list of data items eligible to be set to new values by this statement is:Every elementary item specified as identifier-1 …, PLUS…
Every elementary item defined subordinate to every group item specified as identifier-1 …, with the following
exceptions:
USAGE INDEX items are excluded.
Items with a REDEFINES as part of their definition are excluded; this means that items subordinate to them
are excluded as well. The identifier-1 items themselves may have a REDEFINES and may be subordinate to
an item that has a REDEFINES, however.
This list is referred to as the list of receiving fields.

2.

None of the identifier-1 fields may have the OCCUR DEPENDING ON clause (section 5.3) in their definition nor may
any items subordinate to the identifier-1 fields have an OCCURS DEPENDING ON.

3.

The optional WITH FILLER clause, if present, will allow FILLER items to be retained in the list of receiving fields(otherwise they will be excluded).

4.

If no TO VALUE or REPLACING clauses are specified, a DEFAULT clause will be assumed.

5.

If the optional REPLACING clause is specified, every possible MOVE of the sending field to every possible receiving
field must be legal in order for the INITIALIZE to by syntactically acceptable to the compiler.

6.

Initialization for each receiving field takes place by applying the first of the following rules that apply to the field:
If a TO VALUE clause exists, does the receiving field qualify as one of the data categories listed on the clause?
If it does, the data item will be initialized to it’s VALUE clause value.
If a REPLACING clause exists, does the receiving field qualify as one of the data categories listed on theclause? If it does, the receiving field will be initialized to the specified sending field value.
If a DEFAULT clause exists, initialize the field to a value appropriate to its USAGE (Alphanumeric and Numericinitialized to SPACES, Pointer and Program-Pointer initialized to NULL, all numeric and numeric-edited
initialized to ZERO).

06FEB2009 Version

Page 6-58

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.25. INITIATE
Figure 6-65 - INITIATE Syntax

INITIATE report-name-1 ...

06FEB2009 Version

Although syntactically recognized by the OpenCOBOL compiler, the INITIATE
statement is non-functional because the RWCS (COBOL Report Writer) is not
currently supported by OpenCOBOL.

Page 6-59

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.26. INSPECT
Figure 6-66 - INSPECT Syntax
INSPECTliteral-1
identifier-1
CHARACTERS
TALLYING identifier-2 FORALL
LEADINGTRAILING

literal-2
identifier-3

CHARACTERS
REPLACINGCONVERTINGALL
LEADINGFIRST
TRAILING
literal-5
identifier-6

literal-3
identifier-4

TO

BY

literal-4
identifier-5

BEFOREAFTERINITIALliteral-7
identifier-8

...

...

literal-6
identifier-7

This statement is used to perform various counting or data-alteration operations against strings.
1.

Identifier-1 and literal-1 must be explicitly or implicitly defined as alphanumeric USAGE DISPLAY data. Identifier-1
may be a group item.

2.

The specification of literal-1 prevents the use of either the REPLACING or CONVERTING clauses.

3.

To avoid confusion and/or conflicts, the TALLYING, REPLACING and CONVERTING clauses will be executed in theorder they are coded.

Additional rules for INSPECT vary, depending upon the clause(s) specified.
TALLYING clause rules:
The purpose of the TALLYING clause is to count how many occurrences of a string appear within identifier-1 orliteral-1.
1.

Identifier-2 must be an unedited numeric item.

2.

Identifier-3 and literal-2 must be explicitly or implicitly defined as alphanumeric USAGE DISPLAY data.
Identifier-3 may be a group item.

3.

Identifier-2 will be incremented by 1 each time the target string being searched for is found in identifier-1.
The target string will be:4.

a.

Any single character if the CHARACTERS option is used; this form basically just counts total charactersb.

ALL, all LEADING, only the FIRST or all TRAILING occurrences of Identifier-3 or literal-2.

Normally the entire literal-1 or identifier-1 string will be scanned. This behavior may be modified, however,using the optional BEFORE|AFTER clause to specify a starting and/or ending point based upon data found in
the string being scanned.

06FEB2009 Version

Page 6-60

OpenCOBOL 1.1 Programmers Guide
5.

Once an occurrence of the target
string is found and TALLYed, the
INSPECT TALLYING process will resume
from the end of the found occurrence.
This prevents the possibility ofcounting overlapping occurrences.
The example shows an 8-character
item whose value is “XXXXXXXX” usedas the object of an INSPECT TALLYING
that is looking for “XX” occurrences:

PROCEDURE DIVISION
Figure 6-67 - An INSPECT TALLYING Example
1

2

3

4

5

6

7

8

X X X X X X X X
Inspect-Item
01
01

Inspect-Item PIC X(8) VALUE “XXXXXXXX”.
Double-X-Counter PIC 9(2).
.
.
.
MOVE 0 TO Double-X-Counter
INSPECT Inspect-Item
TALLYING Double-X-Counter FOR ALL “XX“DISPLAY“Count=“ Double-X-Counter
END-DISPLAY
Generated
Count=04 Output

Only four (4) “XX” occurrences were found. Character positions 2-3, 4-5 and 6-7 – even though they are “XX”
occurrences – weren’t counted because they overlapped other occurrences.
REPLACING clause rules:
The purpose of the REPLACING clause is to replace occurrences of a substring within a string with a different
substring of the same length. If you need to replace one or more substrings with others of a different length,
consider using the SUBSTITUTE intrinsic function (section 6.1.7).
1.

Identifier-4 and literal-3 must be explicitly or implicitly defined as alphanumeric USAGE DISPLAY data.
Identifier-4 may be a group item.

2.

Identifier-5 and literal-4 must be explicitly or implicitly defined as alphanumeric USAGE DISPLAY data.
Identifier-5 may be a group item.

3.

Identifier-4 / literal-3 must be the same length as identifier-5 / literal-4.

4.

The substring specified before the “BY” will be referred to as the target string. The substring specified after
the “BY” will be referred to as the replacement string.

5.

Target strings are identified as:a.

Any sequence of characters as long as the length of the replacement string if the CHARACTERS option is
used

b.

ALL, all LEADING, only the FIRST or all TRAILING occurrences of Identifier-4 or literal-3.

6.

Normally the entire identifier-1 string will be scanned. This behavior may be modified, however, using theoptional BEFORE|AFTER clause to specify a starting and/or ending point based upon data found in the string
being scanned.

7.

Once an occurrence of the target string is found and replaced, the INSPECT REPLACING process will resume
from the end of the found occurrence. This prevents the possibility of replacing overlapping occurrences.
This is very similar to how TALLYING handled the possibility of overlapping occurrences.

CONVERTING clause rules:
The purpose of the CONVERTING clause is to perform a series of monoalphabetic substitutions against a data item.
1.

Identifier-5 and literal-6 must be explicitly or implicitly defined as alphanumeric USAGE DISPLAY data.
Identifier-5 may be a group item.

2.

Identifier-6 and literal-7 must be explicitly or implicitly defined as alphanumeric USAGE DISPLAY data.
Identifier-6 may be a group item.

3.

Identifier-5 / literal-6 must be the same length as identifier-6 / literal-7.

4.

The substring specified before the “TO” will be referred to as the target string. The substring specified after
the “TO” will be referred to as the replacement string.

06FEB2009 Version

Page 6-61

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION5.

The contents of identifier-1 will be scanned – character by character. For each character, if that character
appears in the target string, the corresponding character (by relative position) in the replacement string willthen replace that character in identifier-1.

6.

If the length of the replacement string exceeds that of the target string, the excess will be ignored.

7.

If the length of the target string exceeds that of the replacement string, the replacement string will beassumed to be padded to the right with SPACES to make up the difference.

8.

This INSPECT statement clause was introduced in the 1985 standard of COBOL, making the TRANSFORM verb
(section 6.47) obsolete.

06FEB2009 Version

Page 6-62

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.27. MERGE
Figure 6-68 - MERGE Syntax

MERGE sort-file
ON

ASCENDINGDESCENDING

KEY identifier-1 ...

...

The MERGE statement
combines two or more
identically sequenced files on aset of specified keys.

[ WITH DUPLICATES IN ORDER ][ COLLATING SEQUENCE IS alphabet-name-1 ]USING file-name-1 file-name-2 ...
GIVING file-name-3 ...
OUTPUT PROCEDURE IS procedure-name-1
THROUGH
THRU

procedure-name-2

1.

The sort-file named on the MERGE statement must be defined using a sort description (SD) in the FILE SECTION of
the DATA DIVISION. See section 5.2. This file is referred to in the remainder of this discussion as the “merge file”.

2.

File-name-1, file-name-2 and file-name-3 (if specified) must reference ORGANIZATION LINE SEQUENTIAL or
ORGANIZATION RECORD BINARY SEQUENTIAL files. These files must be defined using a file description (FD) in the
FILE SECTION of the DATA DIVISION. See section 5.1. The same file may be used for file-name-1 and file-name-2.

3.

The identifier-1 … field(s) must be defined as field(s) within a record of sort-file.

4.

The WITH DUPLICATES IN ORDER clause is supported for compatibility purposes, but is non-functional.

5.

The record descriptions of file-name-1, file-name-2, file-name-3 (if any) and sort-file are assumed to be identical inlayout and size. While the actual data names used for fields in these files’ records may differ, the structure ofrecords, PICTURE of fields, size of fields and USAGE of data should match field-by-field across all files.
A common programming technique when using the MERGE statement is to define the records of all files involvedon the MERGE as simple elementary items of the form “01 record-name PIC X(n).” where n is the record size. The
only file where records are actually described in detail would then be the sort-file.

6.

The following rules apply to the files named on the USING clause:a.

None of them may be OPEN at the time the MERGE is executed.

b.

Each of those files is assumed to be already sorted according to the specifications set forth on the MERGE
statement’s KEY clause.

c.

No two of those files may be referenced on a SAME RECORD AREA, SAME SORT AREA or SAME SORT-MERGE
25
AREA statement .

7.

As the MERGE begins execution, the first record in each of the USING files is read.

8.

As the MERGE statement executes, the current record from each of the USING files is inspected and compared toeach other according to the rules set forth by the KEY clause. The record that should be “next” in sequence(according to KEY) will be written to the merge file and the USING file from which that record came will be read sothat its next record is available. As end-of-file conditions are reached on USING files, those files will be excluded
from further MERGE processing – processing continues with the remaining USING files. This process will continue
until all USING files have been completely processed.

25

See section 4.2.2

06FEB2009 Version

Page 6-63

OpenCOBOL 1.1 Programmers Guide
9.

PROCEDURE DIVISION

Once the merge file has been populated, the merged data will be written to file-name-3 if the GIVING clause wasspecified, or will be processed by utilizing an OUTPUT PROCEDURE defined as procedure-name 1 or procedurename-1 THRU procedure-name-2.

10. When GIVING is specified, file-name-3 … must not be OPEN at the time the MERGE is executed.
11. When an OUTPUT PROCEDURE is used, merged records are manually read from the merge file – one at a time –using the RETURN statement (section 6.35).
12. A STOP RUN, EXIT PROGRAM or GOBACK executed within an OUTPUT PROCEDURE will terminate the currently
executing program as well as the MERGE.
13. A GO TO statement that transfers control out of the OUTPUT PROCEDURE will terminate the MERGE but allows
the program to continue executing from the point where the GO TO transferred control to. Once an OUTPUT
PROCEDURE has been aborted using a GO TO it cannot be resumed. You may, however, re-execute the MERGE
statement itself. Any records not yet RETURNed from the merge file will be lost if a MERGE is restarted in thismanner. USING A “GO TO” TO PREMATURELY TERMINATE A SORT, OR RE-STARTING A PREVIOUSLY-CANCELLED
MERGE IS NOT CONSIDERED GOOD PROGRAMMING STYLE AND SHOULD BE AVOIDED.
14. An OUTPUT PROCEDURE is terminated either implicitly by a fall-thru of control past the last statement ofprocedure-name-2 (or procedure-name-1 if there is no procedure-name-2) or explicitly via an EXIT SECTION / EXIT
PARAGRAPH executed in procedure-name-2 (or procedure-name-1 if there is no procedure-name-2). Once the
OUTPUT PROCEDURE terminates, the output phase – and the MERGE statement itself - is complete.
15. The scope of the OUTPUT PROCEDURE must not allow a file-based SORT (section 6.40.1), MERGE or RELEASE(section 6.34) statement to be executed.

06FEB2009 Version

Page 6-64

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.28. MOVE
6.28.1. MOVE Format 1 – Simple MOVE
Figure 6-69 - Simple MOVE Syntax

MOVE

literal-1
identifier-1

This statement moves a specific value to one or more
receiving data items.

TO identifier-2 ...

1. The MOVE statement will replace the contents of one or more receiving data items (identifier-2 …) with a newvalue.
2. The exact manner in which the new value is stored in each receiving data item will depend upon the PICTURE and
USAGE of each identifier-2 item.

6.28.2. MOVE Format 2 – MOVE CORRESPONDING
Figure 6-70 - MOVE CORRESPONDING Syntax

MOVE CORRESPONDING identifier-1 TO identifier-2 ...

This statement moves similarly-named elementary
items from one group item to another.

1.

The word CORRESPONDING may be abbreviated as CORR.

2.

Both identifier-1 and identifier-2 must be group items.

3.

Two data items subordinate to identifier-1 and identifier-2 are said to correspond if they meet the following
conditions:

4.

a.

They both have the same name, but that name is not FILLERb.

If they are not immediately subordinate to identifier-1 and identifier-2, then the items they ARE subordinate
to have the same name, but that name is not FILLER; if those items, in turn, are not identifier-1 and identifier2, then this rule continues to apply recursively upward through the structure of identifier-1 and identifier-2c.

They are both elementary items (ADD CORR,SUBTRACT CORR) or at least one of them is an elementary item
(MOVE CORR)d.

Neither potential corresponding candidate is a REDEFINES or RENAMES of another data iteme.

Neither potential corresponding candidate has an OCCURS clause (they MAY, however, contain subordinate
data items that contain an OCCURS clause)

When corresponding matches are established, the effect of a MOVE CORRESPONDING on those matches will be
as if a series of individual MOVEs were done – one for each match.

06FEB2009 Version

Page 6-65

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

The previous rules may be best understood with an example. Observe the following code:
IDENTIFICATION DIVISION.
PROGRAM-ID. corrdemo.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 X.
05 A
VALUE 'A'PIC X(1).
05 G1.
10 G2.
15 B
VALUE 'B'PIC X(1).
05 C.
10 FILLER VALUE 'C'
PIC X(1).
05 G3.
10 G4.
15 D
VALUE 'D'PIC X(1).
05 V1VALUE 'E'
PIC X(1).
05 E
REDEFINES V1 PIC X(1).
05 F
VALUE 'F'PIC X(1).
05 G
VALUE ALL 'G'.
10 G2
OCCURS 4 TIMES PIC X(1).
05 H
VALUE ALL 'H'
PIC X(4).
01 Y.
02 A
PIC X(1).
02 G1.
03 G2.
04 B
PIC X(1).
02 C
PIC X(1).
02 G3.
03 G5.
04 D
PIC X(1).
02 E
PIC X(1).
02 V2PIC X(1).
02 G
PIC X(4).
02 H
OCCURS 4 TIMES PIC X(1).
66 F
RENAMES V2.
PROCEDURE DIVISION.
100-Main.
MOVE ALL '-' TO Y.
DISPLAY ' Names: ' 'ABCDEFGGGGHHHH'.
DISPLAY 'Before: ' Y.
MOVE CORR X TO Y.
DISPLAY ' After: ' Y.
STOP RUN.

The DISPLAY statements produce the output:
Names: ABCDEFGGGGHHHH
Before: -------------After: ABC---GGGG----

OpenCOBOL had no problem establishing a “corresponding” relationship between the “A”, “B” and “C” data
items within the “X” and “Y” group items. Note that even though “X” uses a level numbering scheme of 0105-10-15 while “Y” uses 01-02-03-04, that fact makes no difference to the establishment of corresponding
matches.
The “G” items were found to match even though G OF X was the parent of a data item that contains an
OCCURS clauseNo match could be made with the “D” items because they violate rule #3b (look carefully at the four groupitem names).
No match could be made with the “E” items because E OF X violates rule #3d (REDEFINES).
No match could be made with the “F” items because E OF X violates rule #3d (RENAMES).
No match could be made with the “H” items because H OF Y contains an OCCURS clause, therefore violating
rule #3e.

06FEB2009 Version

Page 6-66

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.29. MULTIPLY
6.29.1. MULTIPLY Format 1 – MULTIPLY BY
Figure 6-71 - MULTIPLY BY Syntax

MULTIPLY

literal-1
identifier-1

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

This format of the MULTIPLY
statement generates arithmetic
products.

[ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ][ END-MULTIPLY ]1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Literal-1 must be a numeric literal.

3.

The value of identifier-1 or integer-1 multiplied by each individual identifier-2 will be computed and each of those
products in turn will be moved to the corresponding identifier-2 data item, replacing the old contents.

4.

The ON SIZE ERROR, NOT ON SIZE ERROR and ROUNDED clauses are coded and operate the same as the clauses ofthe same name available to the ADD statement (see section 6.5).

6.29.2. MULTIPLY Format 2 – MULTIPLY GIVING
Figure 6-72 - MULTIPLY GIVING Syntax

MULTIPLY

literal-1
identifier-1

BY

literal-2
identifier-2

This format of the MULTIPLY statement generates thearithmetic product of two values and then replaces thecontents of the identifiers listed after the GIVING(identifier-3 …) with that product.

GIVING { identifier-3 [ ROUNDED ] } ...
[ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ][ END-MULTIPLY ]1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Identifier-3 must be a numeric (edited or unedited) data item.

3.

Literal-1 and literal-2 must be numeric literals.

4.

The values of identifier-1 and identifier-2 are not altered.

5.

The ON SIZE ERROR, NOT ON SIZE ERROR and ROUNDED clauses are coded and operate the same as the clauses ofthe same name available to the ADD statement (see section 6.5).

06FEB2009 Version

Page 6-67

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.30. NEXT SENTENCE
Figure 6-73 - NEXT SENTENCE Syntax

NEXT SENTENCEThe NEXT SENTENCE statement is a means of “breakingout” of a series of nested “IF” statements.

1.

The NEXT SENTENCE statement is valid only when used within an “IF” statement.

2.

As its name implies, this statement causes control to transfer to the next sentence in the program.

3.

See section 6.1.5 for a discussion of why the NEXT SENTENCE statement is needed for COBOL programs that arecoded according to pre-1985 standards. You’ll also see why programs coded for 1985 (and beyond) standards
don’t need it.

4.

New OpenCOBOL programs should be coded to use the END-IF scope terminator for IF statements, whichinvalidates the use of NEXT SENTENCE in favor of the CONTINUE statement (section 6.12).

06FEB2009 Version

Page 6-68

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.31. OPEN
Figure 6-74 - OPEN Syntax

OPEN

The OPEN statement makes one or more files
described in your program available for use.

INPUT
OUTPUT
I-O
EXTENDSHARING WITH

ALL OTHERNO OTHERREAD ONLY

file-name-1 ...
WITHNO REWIND
LOCK

1.

Any file defined in an OpenCOBOL program must be successfully OPENed before it may be referenced on a CLOSE(section 6.9), DELETE (section 6.13), READ (section 6.33), START (section 6.41) or UNLOCK (section 6.48)
statement. Additionally, a file must be successfully OPENed for any of its record data names (or data elements
subordinate to those records) to be referenced on ANY statement.

2.

Any attempt to OPEN a file that is already OPEN will fail with a file status of 41 (“File Already OPEN”). This is a
fatal error that will terminate the program.

3.

Any OPEN failure (including “File Already OPEN”) may be trapped using DECLARATIVES (section 6.3) or an error
procedure (section 7.3.2), but when those trap routines exit the OpenCOBOL runtime system will terminate theprogram. Ultimately, you cannot recover from an OPEN failure.

4.

The INPUT, OUTPUT, I-O and EXTEND options inform OpenCOBOL of the manner in which you wish to use the file,
as follows:
OPEN
Mode
INPUT
OUTPUT
I-O
EXTEND

Effect
You may only read the existing contents of the file - only the CLOSE, READ, START and UNLOCK
statements will be allowed.
You may only write new content (which will completely replace any previous file contents) to the file- only the CLOSE, UNLOCK and WRITE statements will be allowed.
You may perform any operation you wish against the file - all file I/O statements will be allowed.
You may only write new content (which will be appended after any previously existing file content)
to the file - only the CLOSE, UNLOCK and WRITE statements will be allowed.

5.

The SHARING clause informs OpenCOBOL how you are willing to co-exist with any other OpenCOBOL programs
that may attempt to OPEN the same file after your program does. Sharing options were discussed in section
6.1.9.1.

6.

The WITH NO REWIND and WITH LOCK clauses are non-functional.
Devices that would be capable of supporting a WITH NO REWIND clause (tape drives) are pretty rare in theenvironments in which OpenCOBOL is intended to operate. No compiler or runtime message is issued if thisoption is used (it just won’t do anything).
The WITH LOCK option is treated a little differently – it’s officially “not implemented”, and will generate acompilation warning if it is used.

06FEB2009 Version

Page 6-69

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.32. PERFORM
6.32.1. PERFORM Format 1 – Procedural
Figure 6-75 - Procedural PERFORM Syntax
PERFORM procedure-name-1 [THROUGH
THRU

procedure-name-2 ]FOREVER
literal-1
identifier-1

TIMES

WITH TESTBEFOREAFTERVARYING identifier-3 FROM

literal-2
identifier-4

BY

literal-3
identifier-5

UNTIL conditional-expression -1
literal-4
identifier-6
UNTIL conditional-expression -2

AFTER identifier-4 FROM

BY

literal-5
identifier-7...

This format of the
PERFORM statement isused to transfer control to
one or more procedures
and to return control when
execution of the specified
procedure(s) is complete.
This invocation of theprocedure(s) can be donea single time, multiple
times, repeatedly until acondition becomes TRUE
or forever (with –presumably – some way of
breaking out of the controlof the PERFORM within theprocedure(s).

1.

The words THROUGH and THRU may be used interchangeably.

2.

Both procedure-name-1 and procedure-name-2 must be PROCEDURE DIVISION sections or paragraphs defined in
the same program unit as the PERFORM statement.

3.

If procedure-name-2 option is specified, it must follow procedure-name-1 in the program’s source code.

4.

The scope of the PERFORM is defined as being the statements within procedure-name-1, the statements withinprocedure-name-2 and all statements in all procedures defined between them.

5.

Without the FOREVER, TIMES or UNTIL clauses, the code within the scope of the PERFORM will be executed(once) and control will return to the statement following the PERFORM.

6.

The FOREVER option will repeatedly execute the code within the scope of the PERFORM with no conditions
defined on the PERFORM statement itself for termination of the repetition. It will be up to the programmer toinclude code within the scope of the PERFORM that will either halt the program (STOP RUN) or break out of the
PERFORM (EXIT PERFORM).

7.

The TIMES option will repeat the execution of the instructions within the scope of the PERFORM a fixed numberof times. Once that number of repetitions has concluded, control will fall into the next statement following the
PERFORM.

8.

The UNTIL clause will enable the statements within the scope of the PERFORM to be executed repeatedly until
such time as the value of conditional-expression-1 becomes TRUE.

9.

The optional WITH TEST clause will control whether the UNTIL test is performed BEFORE the scope of the
PERFORM is executed or AFTER. The default, if no WITH TEST clause is specified, is BEFORE.

10. The optional VARYING clause allows for the definition of a data item (identifier-3) that will have a unique numericvalue for each iteration of the execution of the statements within the scope of the PERFORM. The first time,
identifier-3 will have the value specified by the FROM clause. At the conclusion of each iteration, the value
defined by the BY clause will be added to identifier-3 before conditional-expression-1 is evaluated. The default BY
value, if no BY clause is specified, is 1.
11. If a VARYING clause has been used, you may also use any number of additional AFTER clauses to create asecondary loop situation where each AFTER will create an additional series of iterations, will define an additional
data item to be incremented during each iteration and will define an additional conditional expression to define
the termination of that series of iterations. Functionally, this is basically a way of nesting a
06FEB2009 Version

Page 6-70

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISIONPERFORM/VARYING/UNTIL within another PERFORM/VARYING/UNTIL without the need to code multiple
statements. An example will probably help.
Observe the following code which defines a twodimensional (3 row by 4 column) table and a pair ofnumeric data items to be used to subscript
references to each element of the table:
01

PERFORM-DEMO.
05 PD-ROW
10 PD-COL
15 PD
PD-Col-No
PD-Row-No

01
01

OCCURS 3 TIMES.
OCCURS 4 TIMESPIC X(1).
PIC 9 COMP.
PIC 9 COMP.

PD (1, 1)

PD (1, 2)

PD (1, 3)

PD (1, 4)

PD (2, 1)

PD (2, 2)

PD (2, 3)

PD (2, 4)

PD (3, 1)

PD (3, 2)

PD (3, 3)

PD (3, 4)Let’s say we want to PERFORM a routine (100-Visit-Each-PD) which will – in turn –access each PD data item in the sequence shown to the right. Here’s the PERFORM
code:
PERFORM 100-Visit-Each-PD WITH TEST AFTERVARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3
AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4.

1

4

7

10

2

5

8

11

3

6

9

12

1

2

3

4

5

6

7

8

9

10

11

12

But, perhaps you needed to “visit” each PD in thesequence shown to the left. If so, then here’s the PERFORM you need:PERFORM 100-Visit-Each-PD WITH TEST AFTERVARYING PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4
VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3.

6.32.2. PERFORM Format 2 – Inline
Figure 6-76 - Inline PERFORM Syntax

This format of the PERFORM
statement is identical inoperation to format 1, except
for the fact that the statementsthat comprise the scope of the
PERFORM are now specified inline with the PERFORM code
rather than in procedures
located elsewhere within the
program.

PERFORMFOREVER
literal-1
identifier-1

TIMES

WITH TESTBEFORE
AFTER
literal-2
identifier-4
UNTIL conditional-expression -1

BY

VARYING identifier-3 FROM

literal-4
identifier-6
UNTIL conditional-expression -2

AFTER identifier-4 FROM

BY

literal-3
identifier-5
literal-5
identifier-7...

imperative-statement-1 …
END-PERFORM

1.

The FOREVER, TIMES, WITH TEST, VARYING, BY, AFTER and UNTIL clauses have the same use and effect as thesame clauses on format 1 of the PERFORM statement.

2.

The distinguishing characteristic of this format versus format 1 is that – with this version of the PERFORM
statement – the code being executed is specified in-line (imperative-statement-1 …) rather than in a procedure.

‘

06FEB2009 Version

Page 6-71

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.33. READ
6.33.1. READ Format 1 – Sequential READ
Figure 6-77 – READ (Sequential) Syntax

READ file-name-1

NEXT
PREVIOUS

This form of the READ statement retrieves thenext (or previous) record from a file.

RECORD[ INTO identifier-1 ]IGNORING LOCKWITH LOCKWITH NO LOCKWITH IGNORE LOCKWITH WAIT[ AT END imperative-statement-1 ][ NOT AT END imperative-statement-2 ][ END-READ ]1.

File-name-1 must currently be OPEN (section 6.31) for INPUT or I-O.

2.

If the ACCESS MODE of file-name-1 is RANDOM, this format of the READ statement cannot be used.

3.

If the ACCESS MODE is SEQUENTIAL, this is the only format of READ that is available. In such cases, theNEXT/PRIOR clauses are truly optional.

4.

If the ACCESS MODE is DYNAMIC, this format of the READ statement may be used as well as format 2. The
following minimalist READ statement…
READ file-name-1…is perfectly legal according to both READ formats. For that reason, when ACCESS MODE DYNAMIC has been
specified and you want to tell the OpenCOBOL compiler that a statement such as the one above should betreated as a sequential READ, you must add either NEXT or PRIOR to the statement (otherwise it will betreated as a random READ).
5.

The next available record in file-name-1 is retrieved and the contents of that record stored into the 01-level
record structures subordinate to the file’s FD (section 5.1).

6.

The keywords NEXT and PREVIOUS specify in what direction of travel the reading process will take throughthe file. If neither NEXT nor PREVIOUS clause is specified, NEXT is assumed.

7.

The PREVIOUS option is available only for ORGANIZATION INDEXED files.

8.

The optional INTO clause will cause a copy of the just-read record’s contents to be MOVEd to identifier-1,
assuming the READ succeeded.

9.

See section 6.1.9.2 for a discussion of the record LOCK options.

10. The optional AT END clause will – if present – cause imperative-statement-1 to be executed if the READ
attempt fails due to a file status of 10 (end-of-file). The AT END clause WILL NOT DETECT OTHER NON-ZERO
FILE-STATUS VALUES. Use a DECLARATIVES routine (section 6.3) or an explicitly-declared file status field
tested after the READ to detect error conditions other than end-of-file.
11. The optional NOT AT END clause will – if present – cause imperative-statement-2 to be executed if the READ
attempt is successful.

06FEB2009 Version

Page 6-72

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.33.2. READ Format 2 – Random Read
Figure 6-78 - READ (Random) Syntax

READ file-name-1 RECORDThis form of the READ statement retrieves anarbitrary record from a file.

[ INTO identifier-1 ]IGNORING LOCKWITH LOCKWITH NO LOCKWITH IGNORE LOCKWITH WAIT[ KEY IS identifier-2 ][ INVALID KEY imperative-statement-3 ][ NOT INVALID KEY imperative-statement-4 ][ END-READ ]1.

File-name-1 must currently be OPEN (section 6.31) for INPUT or I-O.

2.

If the ACCESS MODE of file-name-1 is SEQUENTIAL, this format of the READ statement cannot be used.

3.

If the ACCESS MODE is RANDOM, this is the only format of READ that is available.

4.

If the ACCESS MODE is DYNAMIC, this format of the READ statement may be used as well as format 1. The
following minimalist READ statement…
READ file-name-1…is perfectly legal according to both READ formats. For that reason, when ACCESS MODE DYNAMIC has been
specified for a file, a READ statement such as the above will be automatically treated as a random READ.

5.

The optional KEY clause tells the compiler how a record is to be located in the file.
If the KEY clause is absent:
If the file is an ORGANIZATION RELATIVE file, the contents of the field declared as the file’s RELATIVE KEY will
be used to identify a record.
If the file is an ORGANIZATION RELATIVE file, the contents of the field declared as the file’s RELATIVE KEY will
be used to identify a record.
If the KEY clause is specified:
If the file is an ORGANIZATION RELATIVE file, the contents of identifier-2 will be used as the relative record
number of the record to be accessed. Identifier-2 does not have to be the RELATIVE KEY field of the file(although it could be if you wish).
If the file is an ORGANIZATION INDEXED file, identifier-2 must be the PRIMARY RECORD KEY or one of the
file’s ALTERNATE RECORD KEY fields (if any) – the current contents of that field will identify the record to beaccessed. If an alternate record key is used, and that key allows duplicate values, the record accessed will best
the 1 one having that key value.

6.

The record identified by rule #5 will be retrieved from file-name-1 and the contents of that record stored into the01-level record structures subordinate to the file’s FD (section 5.1).

7.

The optional INTO clause will cause a copy of the just-read record’s contents to be MOVEd to identifier-1,
assuming the READ succeeded.

8.

See section 6.1.9.2 for a discussion of the record LOCK options.

06FEB2009 Version

Page 6-73

OpenCOBOL 1.1 Programmers Guide
9.

PROCEDURE DIVISION

The optional INVALID KEY clause will – if present – cause imperative-statement-1 to be executed if the READ
attempt fails due to a file status of 23 (“Key Not Exists”). The INVALID KEY clause WILL NOT DETECT OTHER NONZERO FILE-STATUS VALUES. Use a DECLARATIVES routine (section 6.3) or an explicitly-declared file status field
tested after the READ to detect error conditions other than “Key Not Exists”.

10. The optional NOT INVALID KEY clause will – if present – cause imperative-statement-2 to be executed if the READ
attempt is successful.

06FEB2009 Version

Page 6-74

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.34. RELEASE
Figure 6-79 - RELEASE Syntax

RELEASE record-name-1 [ FROM

literal-1
identifier-1

The RELEASE statement adds a new record toa sort file.

]1.

The RELEASE statement is valid only within the INPUT PROCEDURE of a SORT statement. See section 6.40.1.

2.

Record-name-1 must be a record defined to a sort description (SD) entry. See section 5.2.

06FEB2009 Version

Page 6-75

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.35. RETURN
Figure 6-80 - RETURN Syntax

RETURN file-name-1 RECORDThe RETURN statement reads a record from a sort- or
merge file.

[ INTO identifier-1 ][ AT END imperative-statement-1 ][ NOT AT END imperative-statement-2 ][ END-RETURN ]1.

The RETURN statement is valid only within the OUTPUT PROCEDURE of a SORT (section 6.40.1) or MERGE (section
6.27) statement.

2.

File-name-1 must be a sort- or merge file defined with a sort description (SD) entry. See section 5.2.

3.

The INTO, AT END and NOT AT END clauses are used the same as with their READ statement (section 6.33)
equivalents.

06FEB2009 Version

Page 6-76

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.36. REWRITE
Figure 6-81 - REWRITE Syntax

The REWRITE statement replaces alogical record on a disk file.

REWRITE record-name-1[ FROM

literal-1
identifier-1]

WITH LOCKWITH NO LOCK[ INVALID KEY imperative-statement-3 ][ NOT INVALID KEY imperative-statement-4 ][ END-REWRITE ]1.

Record-name-1 must be defined as an 01-level record subordinate to the File Description (FD – see section 5.1) ofa file that is currently OPEN (section 6.31) for I-O.

2.

The optional FROM clause will cause literal-1 or identifier-1 to be implicitly MOVEd into record-name-1 prior towriting record-name-1 to the file.

3.

The REWRITE statement may not be used with ORGANIZATION IS LINE SEQUENTIAL files.

4.

See section 6.1.9.2 for a discussion of the record LOCK options.

5.

Rewriting a record does not cause the record contents of the file to be physically updated until the next block of
the file is read, a COMMIT statement (section 6.10) is issued or that file is closed.

6.

If the file has ORGANIZATION RECORD BINARY SEQUENTIAL:

7.

a.

The record to be rewritten will be the one retrieved by the most-recently executed READ (section 6.33) of the
file.

b.

The size of record-name-1 cannot be altered (see the RECORD CONTAINS / RECORD IS VARYING clauses in
section 5.1).

If the file has ORGANIZATION RELATIVE or ORGANIZATION INDEXED:a.

If the file has ACCESS MODE SEQUENTIAL, the record to be rewritten will be the one retrieved by the mostrecently executed READ (section 6.33) of the file. If the file has ACCESS MODE RANDOM or ACCESS MODEDYNAMIC, no READ is required before a record may be rewritten – the RELATIVE KEY / RECORD KEY definition
for the file will specify the record to be updated.

b.

The size of record-name-1 may be updated.

8.

The ON INVALID KEY clause will be triggered (thus executing imperative-statement-1) if an error occurred during
the REWRITE. Such errors might be actual I/O errors or “Key Not Exists” errors (file status 23), indicating norecord exists that satisfies the RELATIVE KEY or RECORD KEY clause requirements.

9.

The NOT ON INVALID KEY clause will be triggered, thus executing imperative-statement-2, if no error occurred
during the REWRITE.

06FEB2009 Version

Page 6-77

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.37. ROLLBACK
Figure 6-82 - ROLLBACK Syntax

ROLLBACK
1.

The ROLLBACK verb reverts changes made to all files
since the start of the program or since the last COMMIT.

OpenCOBOL does not (currently, at least) support file rollback. The OpenCOBOL ROLLBACK statement will havethe same effect as the COMMIT verb (section 6.10).

06FEB2009 Version

Page 6-78

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.38. SEARCH
6.38.1. SEARCH Format 1 –Sequential Search
Figure 6-83 - Sequential SEARCH Syntax

SEARCH table-name[ VARYING index-name-1 ][ AT END imperative-statement-1 ]The SEARCH statement is used tosequentially search a table,
stopping either once a specificvalue is located within the table orwhen the table has been
completely searched.

{ WHEN conditional-expression-1 imperative-statement-2 } …

[ END-SEARCH ]1.

The index-name-1 identifier specified on the VARYING clause must be USAGE INDEX.

2.

If no VARYING clause is specified, then the table being searched must have been created with an INDEXED BY
clause (see section 5.3).

3.

At the time the SEARCH statement is executed, the current value of index-name-1 (or the table’s defined INDEXEDBY index) will define the starting position in the table where the searching process will begin. Typically, one
initializes that index to a value of 1 before starting the SEARCH, as follows:
SET index-name-1 TO 1

4.

During the searching process, the conditional-expression-1 will be evaluated and – if TRUE – will cause imperativestatement-2 to be executed, after which control will fall into the next statement after the SEARCH.

5.

If multiple WHEN clauses exist, each conditional-expression-n will be evaluated in-turn and the first one that
evaluates to TRUE will cause the corresponding imperative-statement-n to be executed, after which control will
fall into the next statement after the SEARCH.

6.

If no conditional-expression-n evaluates to TRUE, the value of index-name-1 will be incremented by 1. If the valueof index-name-1 is still within the OCCURS scope of table-name, the WHEN clause(s) will again be re-evaluated.
This process will continue until a WHEN clause conditional-expression-n evaluates to TRUE or until the value ofindex-name-1 is no longer within the OCCURS scope of table-name.

7.

If no conditional-expression-n ever evaluates to TRUE and the value of index-name-1 is no longer within the
OCCURS scope of table-name, the imperative-statement-1 which is part of the AT END clause will be executed.
After this, control will fall into the next statement following the SEARCH. If there is no AT END clause, control
simply falls into the next statement following the SEARCH.

06FEB2009 Version

Page 6-79

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.38.2. SEARCH Format 2 –Binary, or Half-interval Search (SEARCH ALL)
Figure 6-84 - Binary SEARCH (ALL) Syntax

This format of the
SEARCH statement
performs a binary,or half-interval,
search against asorted table.

SEARCH ALL table-name[ AT END imperative-statement-1 ]WHEN key-data-item-1 ( index-name-1 )EQUALSIS EQUAL TO=

literal-1
identifier-1

AND key-data-item-2 ( index-name-1 )EQUALSIS EQUAL TO=

literal-2
identifier-2…

imperative-statement-2[ END-SEARCH ]1.

The definition of table-name must include the OCCURS, ASCENDING (and/or DESCENDING) KEY and INDEXED BY
clauses.

2.

In order for a table to be searchable via the SEARCH ALL statement, each of the following must be true:a.

The table meets the requirements of rule #1 above.

b.

Just because the table has one or more KEY clauses doesn’t mean the data is actually in that sequence in the26
table – the actual sequence of the data must agree with the KEY clause(s)!

c.

No two records in the table may have the same KEY field values. If the table has multiple KEY definitions,then no two records in the table may have the same combination of KEY field values.

If rule “a” is violated, the compiler will reject the SEARCH ALL. If rules “b” and/or “c” are violated, there will be no
message issued by the compiler, but the run-time results of a SEARCH ALL against the table will probably beincorrect.
3.

Key-data-item-1 and key-data-item-2 … (if any) must be defined as keys of table-name via ASCENDING KEY or
DESCENDING KEY clauses (see rule #1 above).

4.

Index-name-1 is the first INDEXED BY data item for table-name.

5.

The WHEN clause is mandatory, unlike format 1 of the SEARCH statement.

6.

There can only be one WHEN clause specified; there may be any number of AND clauses, but there cannot be
more WHEN & AND clauses than there are KEY fields to the table. Each WHEN/AND clause should reference a
different KEY field.

7.

The function of the WHEN, along with any ANDs, is to compare the key field(s) of the table, as indexed by the first
INDEXED BY item, against the specified literal and/or identifier values in order to locate the desired entry in thetable. The table’s index will be automatically varied by the SEARCH ALL statement in a manner designed torequire the minimum number of tests.

26

Of course, if the data sequence doesn’t agree with the KEY clause, you can easily make it that way using a table
SORT (see section SORT Format 2 – Table Sort)

06FEB2009 Version

Page 6-80

OpenCOBOL 1.1 Programmers Guide
8.

PROCEDURE DIVISION

The internal processing of the SEARCH ALL statement begins by setting internal “first” and “last” pointers to thest27
1 and last entry locations of the table. Processing then proceeds as follows :a.

The entry half-way between “first” and “last” is identified. We’ll call this the “current” entry, and will set its
table entry location is saved into index-name-1.

b.

The WHEN (along with any ANDs) is evaluated. This comparison of the keys against the target
literal/identifier values will have one of three possible outcomes:
i. If the key(s) and value(s) match, imperative-statement-2 is executed, after which control falls thru into
the next statement following the SEARCH ALL.
ii. If the key(s) are LESS THAN the value(s), then the table entry being searched for can only occur in the“current” to “last” range of the table, so a new “first” pointer value is set (it will be set to the “current”
pointer).
iii. If the key(s) are GREATER THAN the value(s), then the table entry being searched for can only occur inthe “first” to “current” range of the table, so a new “last” pointer value is set (it will be set to the“current” pointer).

c.

If the new “first” and “last” pointers are different than the old “first” and “last” pointers, there’s more left tobe searched, so return to step “a” and continue.

d.

If the new “first” and “last” pointers are the same as the old “first” and “last” pointers, the table has been
exhausted and the entry being searched for cannot be found; imperative-statement-1 is executed, after
which control falls thru into the next statement following the SEARCH ALL.

The net effect of the above algorithm is that only a fraction of the number of elements in the table need ever betested in order to decide whether or not a particular entry exists. This is because the SEARCH ALL discards half
the remaining entries in the table each time it checks an entry.
Computer scientists will compare these two search techniques as follows:
A sequential search (format 1) will need an average of n/2 tests and a worst case of n tests in order tofind an entry and n tests to identify that an entry doesn’t exist (n = the number of entries in the table).
A binary search (format 2) will need worst case of log2n tests in order to find an entry and log2n tests to
identify that an entry doesn’t exist (n = the number of entries in the table).
Here’s a more practical view of the difference. Let’s say that a table has 1,000 entries in it. With a sequential(format 1) search, on average, you’ll have to check 500 of them to find an entry and you’ll have to look at all 1,000of them to find that en entry doesn’t exist. With a binary search, express the number of entries as a binary
number (1,00010 = 11111010002) and count the number of digits in the result (10) -THAT is the worst-case numberof tests required to find an entry or to identify that it doesn’t exist. That’s quite an improvement.

27

This is a simplified view of the algorithm intended purely as a pedagogical tool – an actual implementation of it
requires a few additional picky little details to make it work (such as what to do when rule “a” identifies a “current”
entry of 12.5!)

06FEB2009 Version

Page 6-81

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.39. SET
6.39.1. SET Format 1 – SET ENVIRONMENT
Figure 6-85 - SET ENVIRONMENT Syntax

SET ENVIRONMENT

integer-1
identifier-1

This format of the SET statement provides
a straight-forward means of setting
environment values from within a program.

integer-2
identifier-2

TO

1. Environment variables created or changed from within OpenCOBOL programs will be available to any sub-shellprocesses spawned by that program (i.e. CALL “SYSTEM”) but will not be known to the shell or console windowthat started the OpenCOBOL program.
2. This is a much simpler and more readable means of setting environment variables than by using the DISPLAY
statement (section 6.14.3). For example, these two code sequences produce identical results:
DISPLAY“VARNAME” UPON ENVIRONMENT-NAME
END-DISPLAYDISPLAY“VALUE” UPON ENVIRONMENT-VALUE
END-DISPLAY

SET ENVIRONMENT “VARNAME” TO “VALUE”

6.39.2. SET Format 2 – SET Program-PointerFigure 6-86 - SET Program Pointer Syntax

SET program-pointer-1 TO ENTRY

This form of SET allows you to retrieve theaddress of a PROCEDURE DIVISION code module– specifically a declared entry-point into the
PROCEDURE DIVISION.

literal-1
identifier-1

1. If you have used other versions of COBOL before (particularly mainframe implementations), you’ve possibly seen
subroutine CALLs made passing a PROCEDURE DIVISION paragraph or SECTION name as an argument – that is notpossible in OpenCOBOL; instead, you need to know how to use this form of the SET statement.
2. The USAGE of program-pointer-1 must be PROGRAM-POINTER.
3. The literal-1 or identifier-1 value specified must name the PROGRAM-ID of the program or the entry-point namedon an ENTRY statement.
4. Once the address of a PROCEDURE DIVISION code area has been acquired in this way, the address could be passed
to a subroutine (usually written in C) for whatever use it needs it for. For examples of PROGRAM-POINTERS atwork, see sections 7.3.1.21 and 7.3.1.22.

6.39.3. SET Format 3 – SET ADDRESS
Figure 6-87 - SET ADDRESS Syntax

SET [ ADDRESS OF ]pointer-name-1
identifier-1

TO [ ADDRESS OF ]06FEB2009 Version…

This form of the SET statement can be used to workwith the addresses of data items rather than theircontents.

pointer-name-2
identifier-2

Page 6-82

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

1.

When the ADDRESS OF clause is used before the TO you will be using the SET to alter the address of a LINKAGE
SECTION or BASED data item. Without that clause you will be assigning an address to one or more USAGE
POINTER data items.

2.

When the ADDRESS OF clause is used after the TO, SET will be identifying the address of identifier-2 as the address
to be assigned to identifier-1 or stored in pointer-name-1. If the “ADDRESS OF” clause is absent after the TO, thecontents of pointer-name-2 will serve as the address to be assigned.

6.39.4. SET Format 4 – SET Index
Figure 6-88 - SET Index Syntax

SET index-name-1 TO

1.

literal-1
identifier-1

This SET statement assigns a value to a USAGE INDEX data
item.

The USAGE of index-name-1 should be INDEX, or index-name-1 must be identified in a table INDEXED BY clause.

6.39.5. SET Format 5 – SET UP/DOWN
Figure 6-89 - SET UP/DOWN Syntax

SETindex-name-1
pointer-1
BY [ LENGTH OF ]This format of SET is used to increment ordecrement the value of an index or pointer by aspecified amount.

UP
DOWN
literal-1
identifier-2function-reference 1

1.

The USAGE of index-name-1 must be INDEX. The USAGE of pointer-1 must be POINTER or PROGRAM-POINTER.

2.

The typical usage when an index-name-1 is specified is to set the value UP or DOWN by 1, since an index-name-1
is usually being used to sequentially walk through the elements of a table.

6.39.6. SET Format 6 – SET Condition Name
Figure 6-90 - SET Condition Name Syntax

SET { condition-name-1 } … TO

TRUE
FALSE

This format provides one method of specifying the TRUE /FALSE value of a level-88 condition name.

1.

By setting the specified condition name(s) to a TRUE or FALSE value, you will actually be assigning a value to theparent data item(s) to which the condition name data item(s) is subordinate to.

2.

When specifying TRUE, the value assigned to each parent data item will be the first VALUE specified on thecondition name’s definition.

3.

When specifying FALSE on the SET, the value assigned to each parent data item will be the value specified for the
FALSE clause of the condition name’s definition; if any condition-name-1 occurrence lacks a FALSE clause, the SET
statement will be rejected by the compiler.

06FEB2009 Version

Page 6-83

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.39.7. SET Format 7 – SET Switch
Figure 6-91 - SET Switch Syntax

SET { mnemonic-name-1 } … TO

1.

Use this SET statement type to turn a switch ON or OFF.

ON
OFF

Switches are defined using the SPECIAL-NAMES paragraph. See section 4.1.4 for additional information.

06FEB2009 Version

Page 6-84

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.40. SORT
6.40.1. SORT Format 1 – File-based Sort
Figure 6-92 - File-Based SORT Syntax

SORT sort-file
ON

ASCENDINGDESCENDING

KEY

identifier-1 ...

...

This format of the SORT
statement is designed tosort large volumes of dataaccording to one or more
key fields.

[ WITH DUPLICATES IN ORDER ][ COLLATING SEQUENCE IS alphabet-name-1 ]USING file-name-1 ...
INPUT PROCEDURE IS procedure-name-1
THROUGH
procedure-name-2
THRU
GIVING file-name-2 ...
OUTPUT PROCEDURE IS procedure-name-3
THROUGH
THRU

procedure-name-4

1.

The sort-file named on the SORT statement must be defined using a sort description (SD) in the FILE SECTION of
the DATA DIVISION. See section 5.2. This file is referred to as the “sort file”.

2.

If specified, file-name-1 and file-name-2 must reference ORGANIZATION LINE SEQUENTIAL or ORGANIZATION
RECORD BINARY SEQUENTIAL files. These files must be defined using a file description (FD) in the FILE SECTION of
the DATA DIVISION. See section 5.1. The same file may be used for file-name-1 and file-name-2.

3.

The identifier-1 … field(s) must be defined as field(s) within a record of sort-file.

4.

The WITH DUPLICATES IN ORDER clause is supported for compatibility purposes, but is non-functional.

5.

A sort file (see #1) is never OPENed or CLOSEd.

6.

The SORT statement works in three stages, as follows:
STAGE I (the input phase):a.

The data to be sorted is loaded into the sort file. This is accomplished either by taking the entire contents ofthe file(s) named on the USING clause or by utilizing an INPUT PROCEDURE defined as procedure-name 1 orprocedure-name-1 THRU procedure-name-2.

b.

When USING is specified, file-name-1 … must not be OPEN at the time the SORT is executed.

c.

When an INPUT PROCEDURE is used, records to be sorted are produced using whatever logic is necessary andare manually written to the sort file – one at a time – using the RELEASE statement (section 6.34).

d.

A STOP RUN, EXIT PROGRAM or GOBACK executed within an INPUT PROCEDURE will terminate the currently
executing program as well as the SORT.

e.

A GO TO statement that transfers control out of the INPUT PROCEDURE will terminate the SORT but allows
the program to continue executing from the point where the GO TO transferred control to. Once an INPUTPROCEDURE has been aborted using a GO TO it cannot be resumed. You may, however, re-execute the SORT

06FEB2009 Version

Page 6-85

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

statement itself. Any records previously RELEASEd to the sort file will be lost if a SORT is restarted in thismanner. USING A “GO TO” TO PREMATURELY TERMINATE A SORT, OR RE-STARTING A PREVIOUSLYCANCELLED SORT IS NOT CONSIDERED GOOD PROGRAMMING STYLE AND SHOULD BE AVOIDED.
f.

As data is loaded into the sort file, it is actually being buffered in dynamically-allocated memory. Only if the28
amount of data to be sorted exceeds the amount of available sort memory (128 MB) will actual disk files beallocated and utilized. These “sort work files” will be discussed again shortly.

g.

An INPUT PROCEDURE is terminated either implicitly by a fall-thru of control past the last statement ofprocedure-name-2 (or procedure-name-1 if there is no procedure-name-2) or explicitly via an EXIT SECTION /EXIT PARAGRAPH executed in procedure-name-2 (or procedure-name-1 if there is no procedure-name-2).
Once the INPUT PROCEDURE terminates, the input phase is complete.

h.

The scope of the INPUT PROCEDURE must not allow a file-based SORT, MERGE (section 6.27) or RETURN(section 6.35) statement to be executed.

STAGE 2 (the sort phase):a.

The sort will take place by arranging the data records in the sequence defined by the ASCENDING KEY and/or
DESCENDING KEY specification(s) on the SORT statement according to the COLLATING SEQUENCE specified on
the SORT (if any) or – if none was defined – the PROGRAM COLLATING SEQUENCE specified or implied by the
OBJECT-COMPUTER paragraph. Keys may be any supported data type and USAGE except for level-78 or level88 data items.

b.

For example, let’s assume we’re sorting a series of financial transactions. The SORT statement might look like
this:
SORT Sort-FileASCENDING KEY Transaction-Date
ASCENDING KEY Account-Number
DESCENDING KEY Transaction-Amount.
.
.

The effect of this statement will be to sort all transactions into ascending order of the date the transaction
took place (oldest first, newest last). Unless the business running this program is going out of business, there
are most-likely many transactions for any given date – therefore, within each grouping of transactions all withthe same date, transactions will be sub-sorted into ascending sequence of the account number thetransactions apply to. Since it’s quite possible there might be multiple transactions for an account on any
given date, a third level sub-sort will arrange all transactions for the same account on the same date into
descending sequence of the actual amount of the transaction (largest first, smallest last). If two or moresttransactions of $100.00 were recorded for account #12345 on the 31 of August 2009, there will be no way of
predicting exactly how those transactions are ordered relative to each other since there’s no additional“level” specified for sort keys.
c.

OpenCOBOL does not utilize a high-capacity, high-performance (and usually high expense) sorting package as
29
would be the case on a mainframe computer system, but the SORT algorithms used are more thanadequate for the task.

Stage 3 (the output phase):a.

Once the sort phase is complete, the sorted data will be written to file-name-2 if the GIVING clause wasspecified, or by utilizing an OUTPUT PROCEDURE defined as procedure-name 3 or procedure-name-3 THRU
procedure-name-4.

b.

When GIVING is specified, file-name-2 … must not be OPEN at the time the SORT is executed.

28

There is a runtime environment variable (COB_SORT_MEMORY) that you may use to allocate more or lessmemory to the sorting process. See section 7.2.4.

29

The OpenCOBOL sort routines are entirely self-contained in the OpenCOBOL run-time library

06FEB2009 Version

Page 6-86

OpenCOBOL 1.1 Programmers Guide

7.

PROCEDURE DIVISIONc.

When an OUTPUT PROCEDURE is used, sorted records are manually read from the sort file – one at a time –using the RETURN statement (section 6.35).

d.

A STOP RUN, EXIT PROGRAM or GOBACK executed within an OUTPUT PROCEDURE will terminate thecurrently executing program as well as the SORT.

e.

A GO TO statement that transfers control out of the OUTPUT PROCEDURE will terminate the SORT but allows
the program to continue executing from the point where the GO TO transferred control to. Once an OUTPUT
PROCEDURE has been aborted using a GO TO it cannot be resumed. You may, however, re-execute the SORT
statement itself. Any records not yet RETURNed from the sort file will be lost if a SORT is restarted in thismanner. USING A “GO TO” TO PREMATURELY TERMINATE A SORT, OR RE-STARTING A PREVIOUSLYCANCELLED SORT IS NOT CONSIDERED GOOD PROGRAMMING STYLE AND SHOULD BE AVOIDED.

f.

An OUTPUT PROCEDURE is terminated either implicitly by a fall-thru of control past the last statement ofprocedure-name-4 (or procedure-name-3 if there is no procedure-name-4) or explicitly via an EXIT SECTION /EXIT PARAGRAPH executed in procedure-name-4 (or procedure-name-3 if there is no procedure-name-4).
Once the OUTPUT PROCEDURE terminates, the output phase – and the SORT statement itself - is complete.

g.

The scope of the OUTPUT PROCEDURE must not allow a file-based SORT, MERGE (section 6.27) or RELEASE(section 6.34) statement to be executed.

Should disk work files be necessary due to the amount of data being sorted, they will be automatically allocatedto disk in a folder defined by the TMPDIR, TMP or TEMP environment variables (see section 7.2.4). These disk files
WILL NOT be automatically purged upon program execution termination (normal or otherwise). Temporary sortwork files will be named “cobxxxx.tmp”, in case you want to delete them yourself or from within your program
upon sort termination.

6.40.2. SORT Format 2 – Table Sort
Figure 6-93 - Table SORT Syntax

SORT table-name
ASCENDINGONDESCENDING

KEY identifier-1 ...

...

This format of the SORT statement
sorts relatively small quantities ofdata – namely data contained in a
DATA DIVISION table – according to
one or more key fields.

[ WITH DUPLICATES IN ORDER ][ COLLATING SEQUENCE IS alphabet-name-1 ]1.

The table-name data item must have an OCCURS clause.

2.

The identifier-1 … field(s), if any, must be defined as data items subordinate to table-name.

3.

The WITH DUPLICATES IN ORDER clause is supported for compatibility purposes, but is non-functional.

4.

The data within table-name will be sorted in-place (i.e. no sort file is required) according to the KEY
specification(s) made on the SORT statement.

5.

Currently, a table SORT with no KEY specification(s) made on the SORT statement is unsupported and will berejected by the compiler.

6.

The sort will take place by arranging the data records in the sequence defined by the ASCENDING KEY and/or
DESCENDING KEY specification(s) on the SORT statement according to the COLLATING SEQUENCE specified on the
SORT (if any) or – if none was defined – the PROGRAM COLLATING SEQUENCE specified or implied by the OBJECTCOMPUTER paragraph. Keys may be any supported data type and USAGE except for level-78 or level-88 data
items.

7. The SORT will be performed in-place within table-name – no sort file is required.
06FEB2009 Version

Page 6-87

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.41. START
Figure 6-94 - START Syntax

The START statement defines thelogical starting point within a file forsubsequent sequential read
operations.

START file-name-1
IS EQUAL TOIS =EQUALSIS GREATER THANIS >KEY ISIS GREATER THAN OR EQUAL TOIS >=IS NOT LESS THAN

identifier-1

IS LESS THANIS <IS LESS THAN OR EQUAL TOIS <=IS NOT GREATER THAN
[ INVALID KEY imperative-statement-3 ][ NOT INVALID KEY imperative-statement-4 ][ END-START ]1.

File-name-1 must be an ORGANIZATION RELATIVE or ORGANIZATION INDEXED file.

2.

File-name-1 must have been SELECTed with an ACCESS MODE DYNAMIC or ACCESS MODE SEQUENTIAL.

3.

File-name-1 must be OPEN (section 6.31) in either INPUT or I-O mode at the time the START is executed.

4.

If no KEY clause is specified, “KEY IS EQUAL TO identifier-1” will be assumed.

5.

If file-name-1 is an ORGANIZATION RELATIVE file, identifier-1 must be the RELATIVE KEY of the file. See section
4.2.1.2.

6.

If file-name-1 is an ORGANIZATION INDEXED file, identifier-1 must be the RECORD KEY or one of the ALTERNATE
RECORD KEY fields for the file. See section 4.2.1.3.

7.

After successful execution of a START statement, the internal record pointer into the file-name-1 data will bepositioned such that the next sequential READ statement executed against file-name-1 will read:a.

The FIRST record that satisfies the KEY clause specification if the relation check specified is EQUAL TO,
GREATER THAN or GREATER THAN OR EQUAL TO (or any of their syntactical equivalents).

b.

The LAST record that satisfies the KEY clause specification is the relation check specified is LESS THAN or LESS
THAN OR EQUAL TO (or any of their syntactical equivalents).

8.

The START statement only positions the file for a subsequent sequential READ – it does not actually populate filename-1s 01-level records with new data. You must issue a sequential READ after a successful START to actually
read the record that satisfies the KEY clause.

9.

The ON INVALID KEY clause will be triggered (thus executing imperative-statement-1) if an error occurred during
the START. Such errors might be actual I/O errors or “Key Not Exists” errors (file status 23), indicating no record
exists that satisfies the KEY clause requirements.

06FEB2009 Version

Page 6-88

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

10. The NOT ON INVALID KEY clause will be triggered, thus executing imperative-statement-2, if no error occurred
during the START.
11. Once the START statement has located the desired record (or not) and executed any specified imperativestatement-1 or imperative-statement-2 (or not), control transfers to the next statement following the START.

06FEB2009 Version

Page 6-89

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.42. STOP
Figure 6-95 - STOP Syntax

STOP

RUN

RETURNING
GIVING

literal-1
identifier-1

The STOP statement halts the
program, returning control to theoperating system.

literal-2
1.

The RETURNING and GIVING clauses may be used interchangeably.

2.

The literal-2 option is supported syntactically but will be rejected if used (with a WARNING), as it is obsolete.

3.

The optional RETURNING/GIVING clause allows the program to return a numeric return code to the operating
system. The return code value can be in the range -2147483648 to +2147483647.

4.

The two code snippets below are equivalent. They show two different ways a return code may be passed back to
the operating system:
STOP RUN RETURNING 16

06FEB2009 Version

MOVE 16 TO RETURN-CODE
STOP RUN

Page 6-90

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.43. STRING
Figure 6-96 - STRING Syntax

STRING
literal-1
identifier-1

DELIMITED BY

SIZE[ ALL ] literal-2
identifier-2…

The STRING statement isused to concatenate all or apart of multiple strings
together, forming a new
string.

INTO identifier-3[ WITH POINTER identifier-4 ][ ON OVERFLOW imperative-statement-1 ][ NOT ON OVERFLOW imperative-statement-2 ][ END-STRING ]1.

Literal-1, literal-2, identifier-1, identifier-2 and identifier-3 must be explicitly or implicitly defined as alphanumeric
USAGE DISPLAY data. Any of those identifiers may be group items.

2.

Identifier-4 must be a non-edited elementary integer numeric data item with a value greater than zero.

3.

Each literal-1 / identifier-1 will be known as the sending item while identifier-3 will be known as the receiving
item.

4.

For each sending item, the contents of the sending item will be copied – character-by-character – into thereceiving item; the first sending item will be copied into the receiving item beginning at the character position
specified by the WITH POINTER clause (character positions are numbered upward from 1); if no WITH POINTER
clause is specified, 1 will be assumed; the second sending item will be copied into the receiving item starting at
the next character position after the last character transferred by the first item, and so forth.

5.

Once the final character position of the receiving item has been filled, the STRING process will cease, regardless ofwhether or not there was more data to copy in the current sending item or even if there were more sending items
to be processed.

6.

If the DELIMITED BY SIZE option is specified for a sending item, the entire sending item will be copied. If no
DELIMITED BY clause is specified, DELIMITED BY SIZE is assumed.

7.

If a sending item has a DELIMITED BY clause without the SIZE option, the copying of the sending item will beterminated once the character sequence specified by identifier-2 or ALL literal-2 is found in the sending item.

8.

The receiving item (identifier-3) is neither initialized (to SPACES or any other value) at the start of a STRING
statement nor will it be SPACE filled should the total number of sending item characters copied into it be less thanits size. You may explicitly INITIALIZE (section 6.24) the receiving item yourself before executing the STRING if you
wish.

9.

If the value of identifier-4 is less than 1 or if the receiving item runs out of space before all sending items havebeen fully processed, an overflow condition results. If an ON OVERFLOW clause is present in such a case,imperative-statement-1 will be executed.

10. If there is no overflow condition and a NOT ON OVERFLOW clause is present, imperative-statement-2 will be
executed.
11. Once a STRING statement finishes and any imperative statements have been executed, control transfers to thenext statement following the STRING.

06FEB2009 Version

Page 6-91

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.44. SUBTRACT
6.44.1. SUBTRACT Format 1 – SUBTRACT FROM
Figure 6-97 - SUBTRACT FROM Syntax

SUBTRACT[ LENGTH OF ]literal-1
identifier-1...

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

This format of the ADD statement generates
the arithmetic sum of all arguments thatappear before the FROM (identifier-1 orliteral-1) and then subtracts that sum fromeach of the identifiers listed after the TO(identifier-2).

[ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ][ END-SUBTRACT ]1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Literal-1 must be a numeric literal.

3. The ROUNDED, ON SIZE ERROR and NOT ON SIZE ERROR clauses are used in the same way as they are on the ADD
statement (see section 6.5.1).

6.44.2. SUBTRACT Format 2 – SUBTRACT GIVING
Figure 6-98 - SUBTRACT GIVING Syntax

SUBTRACT[ LENGTH OF ]literal-1
identifier-1...

[ FROM identifier-2 ]GIVING { identifier-3 [ ROUNDED ] } ...
[ ON SIZE ERROR imperative-statement-1 ]This format of the SUBTRACT statement
generates the arithmetic sum of allarguments that appear before the FROM
(identifier-1 or literal-1), subtracts that sum
from the contents of identifier-2 and thenreplaces the contents of the identifiers listed
after the GIVING (identifier-3) with that
result.

[ NOT ON SIZE ERROR imperative-statement-2 ][ END-SUBTRACT ]1.

Identifier-1 and identifier-2 must be numeric unedited data items.

2.

Identifier-3 must be a numeric (edited or unedited) data item.

3.

Literal-1 must be a numeric literal.

4. The ROUNDED, ON SIZE ERROR and NOT ON SIZE ERROR clauses are used in the same way as they are on the ADD
statement (see section 6.5.1).

06FEB2009 Version

Page 6-92

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.44.3. SUBTRACT Format 3 – SUBTRACT CORRESPONDING
Figure 6-99 - SUBTRACT CORRESPONDING Syntax

SUBTRACT CORRESPONDING identifier-1 FROM identifier-2 [ ROUNDED ][ ON SIZE ERROR imperative-statement-1 ][ NOT ON SIZE ERROR imperative-statement-2 ][ END-SUBTRACT ]This format of the SUBTRACT
statement generates code
equivalent to individual
SUBTRACT FROM statements
for corresponding matches ofdata items found subordinate
to the two identifiers.

1. The rules for identifying corresponding matches are as discussed in section 6.28.2 – MOVE CORRESPONDING.
2. The ROUNDED, ON SIZE ERROR and NOT ON SIZE ERROR clauses are used in the same way as they are on the ADD
statement (see section 6.5.1).

06FEB2009 Version

Page 6-93

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.45. SUPPRESS
Figure 6-100 - SUPPRESS Syntax

SUPPRESS PRINTING

06FEB2009 Version

Although syntactically recognized by the OpenCOBOL compiler, the SUPPRESS
statement is non-functional because the RWCS (COBOL Report Writer) is not
currently supported by OpenCOBOL.

Page 6-94

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.46. TERMINATE
Figure 6-101 - TERMINATE Syntax

TERMINATE identifier-1 …

06FEB2009 Version

Although syntactically recognized by the OpenCOBOL compiler, the TERMINATE
statement is non-functional because the RWCS (COBOL Report Writer) is not
currently supported by OpenCOBOL.

Page 6-95

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.47. TRANSFORM
Figure 6-102 - TRANSFORM Syntax

TRANSFORM identifier-1 FROM

literal-1
identifier-2

TO

literal-2
identifier-3

The TRANSFORM statementscans a data item performing aseries of monoalphabetic
substitutions, defined by thearguments before and after the“TO” clause.

1. The literal-1 or identifier-2 specified before the “TO” clause defines those characters in identifier-1 that will be
replaced. This will be referred to as the target string.
2. The literal-2 or identifier-3 specified after the “TO” clause defines those characters in identifier-1 that will be
replacing the characters specified by literal-1 or identifier-2. This will be referred to as the replacement string.
3. The TRANSFORM verb was made obsolete in the 1985 standard of COBOL. Its function has been subsumed by the
INSPECT statement – specifically the CONVERTING clause (section 6.26).
4. The contents of identifier-1 will bescanned – character by character.
For each character, if that character
appears in the target string, thecorresponding character (by relative
position) in the replacement string
will then replace that character in
identifier-1.
5. If the length of the replacement
string exceeds that of the target
string, the excess will be ignored.
6. If the length of the target string
exceeds that of the replacement
string, the replacement string will beassumed to be padded to the rightwith SPACES to make up the
difference.

06FEB2009 Version

Figure 6-103 - The TRANSFORM Statement at Work

IDENTIFICATION DIVISION.
PROGRAM-ID. DEMOTRANSFORM.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Sample-Item PIC X(20) VALUE 'THIS IS A TEST'.
PROCEDURE DIVISION.
000-Main.
TRANSFORM Sample-Item
FROM 'ABCDEFGHIJKLMNOPQRSTUVWXYZ„
TO 'ZYXWVUTSRQPONMLKJIHGFEDCBA„DISPLAY
Sample-Item
END-DISPLAY
Here’s what the
GSRH RH Z GVHG
STOP RUN
program DISPLAYs…
.

Page 6-96

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.48. UNLOCK
Figure 6-104 - UNLOCK Syntax

UNLOCK file-name-1

RECORD
RECORDSThis statement syncs any as-yet unwritten file I/O buffers
to the specified file (if any) and releases any record locks
held for records belonging to the named file.

1.

If file-name-1 is a SORT file, no action will be taken.

2.

Not all OpenCOBOL implementations support locking. Whether they do or not depends upon the operating30
system they were built for and the build options that were used when OpenCOBOL was generated. When aprogram using one of those OpenCOBOL implementations issues an UNLOCK, it will ignored. There will be nocompiler message issued. Buffer syncing, if needed, will still occur.

30

The author of this manual – for example – uses an OpenCOBOL build for Windows that utilizes the MinGW
build/runtime environment and uses the Berkeley Database module for advanced file I/O. That OpenCOBOL build
does NOT support LOCKing. Generally speaking, UNIX builds will support record locking.

06FEB2009 Version

Page 6-97

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.49. UNSTRING
Figure 6-105 - UNSTRING Syntax

UNSTRING identifier-1
DELIMITED BY[ ALL ] literal-1
Identifier-2

OR[ ALL ] literal-2
Identifier-3…

INTO identifier-4 [ DELIMITER IN identifier-5 ] [ COUNT IN identifier-6 ][ identifier-7 [ DELIMITER IN identifier-8 ] [ COUNT IN identifier-9 ] ] …
[ WITH POINTER identifier-10 ]The UNSTRING
statement parses
a string, extracting
any number ofsubstrings from it.

[ TALLYING IN identifier-11 ][ ON OVERFLOW imperative-statement-1 ][ NOT ON OVERFLOW imperative-statement-2 ][ END-UNSTRING ]1.

Identifier-1 through identifier-5, identifier-7 and identifier-8 must be explicitly or implicitly defined asalphanumeric USAGE DISPLAY data. Any of those identifiers may be group items.

2.

Literal-1 and literal-2 must be alphanumeric literals.

3.

Identifier-6 and identifier-9 through identifier-11 must be elementary non-edited integer numeric items.

4.

Identifier-10 must have a value greater than 0.

5.

Identifier-1 is known as the source string. Identifier-4 and identifier-7 are known as the destination fields.

6.

The source string will be broken up into substrings starting from the character position indicated by identifier-10(or from position 1 if there is no WITH POINTER clause). If the initial value of identifier-10 is less than 1 or greaterthan the size of the source string, an “overflow” condition results. Overflow is discussed in item #13.

7.

Substrings are identified by using the various delimiter strings specified on the DELIMITED BY clause as intersubstring separators. Using the “ALL” option allows a delimiter sequence to be an arbitrarily long sequence ofoccurrences of the delimiter literal whereas its absence treats each occurrence as a separate delimiter.

8.

Two consecutive delimiter sequences will identify a null substring.

9.

Here is an example of how a source string will be parsed into substrings:
UNSTRING Input-Address
DELIMITED BY “,” OR “/”
INTO
Street-Address DELIMITER D1 COUNT C1
Apt-Number
DELIMITER D2 COUNT C2City
DELIMITER D3 COUNT C3
State
DELIMITER D4 COUNT C4
Zip-Code
DELIMITER D5 COUNT C5
END-UNSTRING

Figure 6-106 - An UNSTRING Example
Input-Address

1 1

M a i nSubstring #1

S t , , C a i r o / N Y , 1 2 4 1 3
Substring #3
Substring #2(null)

Substring #4

Substring #5

With the sample data shown, the UNSTRING statement will identify a total of five (5) substrings from the data.
The result of this identification will be as if the following MOVE statements were executed:
MOVE “11 Main St” TO Street-Address
MOVE “”TO Apt-Number31
MOVE “Cairo”
TO City
MOVE “NY”
TO State
MOVE “12413”
TO Zip-Code

If not enough substrings can get identified to populate all the destination fields, those for which no data can befound remain unchanged.

31

A MOVE of the null string has the same effect as a MOVE of SPACES

06FEB2009 Version

Page 6-98

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

If not enough destination fields are specified to receive all the substrings, the excess substrings are “thrownaway”. An “overflow” condition will exist, however. Overflow is discussed in item #13.
10. Each destination field may have an optional DELIMITER clause. If a DELIMITER clause is specified, identifier-5 (oridentifier-8) will have the delimiter character string used to identify the substring for the destination field MOVEd
to it. Using the example shown earlier, the following implied MOVEs will occur for the DELIMITER identifiers:
MOVE “,”TO D1MOVE “,”TO D2MOVE “/”TO D3
MOVE “,”TO D4MOVE SPACES TO D532

11. Each destination field may have an optional COUNT clause. If a COUNT clause is specified, identifier-6 (oridentifier-9) will have the size of the substring for the destination field MOVEd to it. Using the example shown
earlier, the following implied MOVEs will occur for the COUNT identifiers:
MOVE 10 TO C1MOVE 0 TO C2MOVE 5 TO C3MOVE 2 TO C4MOVE 5 TO C5

12. The TALLYING clause – if present – will be incremented by 1 each time a parsed substring is MOVEd to a
destination field. This field is NOT initialized to zero by UNSTRING, so you’ll want to do that yourself.
13. The optional ON OVERFLOW clause, if present, will trigger the execution of imperative-statement-1 if an overflow
condition occurs (see item #6 and #7). If the ON OVERFLOW clause triggers, the NOT ON OVERFLOW clause (ifany) will be ignored.
14. The optional NOT ON OVERFLOW clause, if present, will trigger the execution of imperative-statement-2 if nooverflow condition occurred (see item #6 and #7). If the NOT ON OVERFLOW clause triggers, the ON OVERFLOW
clause (if any) will be ignored.
15. Once the source string has been parsed, the appropriate destination fields have been updated (along with any
DELIMITER/COUNT fields), identifier-11 (TALLYING) has been incremented and any ON OVERFLOW or NOT ON
OVERFLOW imperative statement has been executed, control will fall into the next statement following the
UNSTRING.

32

The last substring always has a delimiter of null which – when MOVEd to the DELIMITER field - becomes SPACES.

06FEB2009 Version

Page 6-99

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

6.50. WRITE
Figure 6-107 - WRITE Syntax

The WRITE statement
writes a new record to
an OPEN file.

WRITE record-name-1
literal-1
identifier-1[ FROM]

WITH LOCKWITH NO LOCKAFTERBEFOREliteral-1
identifier-1
ADVANCING

LINE
LINES

mnemonic-name-1
PAGE

AT

END-OF-PAGEEOP

NOT AT

Imperative-statement-1

END-OF-PAGE
EOP

Imperative-statement-2[ INVALID KEY imperative-statement-3 ][ NOT INVALID KEY imperative-statement-4 ][ END-WRITE ]1.

Record-name-1 must be defined as an 01-level record subordinate to the File Description (FD – see section 5.1) ofa file that is currently OPEN (section 6.31) for OUTPUT, I-O or EXTEND.

2.

Literal-1 or identifier-1 must be explicitly or implicitly defined as alphanumeric USAGE DISPLAY data. Identifier-1
may be a group item.

3.

The optional FROM clause will cause literal-1 or identifier-1 to be implicitly MOVEd into record-name-1 prior towriting record-name-1 to the file.

4.

See section 6.1.9.2 for a discussion of the record LOCK options.

5.

The ADVANCING clause is intended for use with ORGANIZATION LINE SEQUENTIAL files that will have reports
written to them. Using this clause with any other ORGANIZATION will either be rejected outright by the compiler(ORGANIZATION IS RELATIVE or ORGANIZATION IS INDEXED) or may introduce unwanted characters into the file
(ORGANIZATION IS RECORD BINARY SEQUENTIAL).

6.

The ADVANCING n LINES clause will introduce the specified number of line-feed (X”10”) characters into the fileeither before the written record (AFTER ADVANCING) or after the written record (BEFORE ADVANCING).

7.

If no ADVANCING clause is specified on a WRITE to an ORGANIZATION LINE SEQUENTIAL file, AFTER ADVENCING 1
LINE will be assumed.

8.

The ADVANCING PAGE clause will introduce a form-feed (X”0C”) characters into the file either before the written
record (AFTER ADVANCING) or after the written record (BEFORE ADVANCING).

9.

If the file being written to contains a LINAGE clause (section 5.1) in its FD, an internal line counter will bemaintained by the runtime library and – when appropriate, the appropriate number of ASCII line-feed characters

06FEB2009 Version

Page 6-100

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

will be automatically written to the file to accommodate the LINES AT TOP and/or LINES AT BOTTOM specificationof the LINAGE definition.
10. The AT END-OF-PAGE and NOT AT END-OF-PAGE clauses are legal only for ORGANIZATION LINE SEQUENTIAL or
ORGANIZATION RECORD BINARY SEQUENTIAL files whose file descriptions contain a LINAGE clause (section 5.1).
11. The AT END-OF-PAGE clause will be triggered (thus executing imperative-statement-1) if an end-of-page condition
occurred during the WRITE. End-of-page conditions occur when a WRITE statement introduces a data line or linefeed character into the file at a line position that occurs within the Page Footer area (see Figure 5-3).
12. The NOT AT END-OF-PAGE clause will be triggered (thus executing imperative-statement-2) if no end-of-page
condition occurred during the WRITE.
13. The behavior of the combination of ADVANCING and AT END-OF-PAGE clauses needs to be understood in order to
get the desired results. To that end, here is the sequence of events that will occur with a WRITE statement thatinvolves these clauses:a.

If AFTER ADVANCING is specified:
If AFTER ADVANCING PAGE was specified, a form-feed character is written to the file and the internal
end-of-page switch is set
OTHERWISE the appropriate number of line-feed characters (ADVANCING n LINES) will be written to thefile; if the internal LINAGE counter shows that these line feeds have caused the maximum available
usable lines on a logical page to be exhausted, the internal end-of-page switch is set.

b.

The data record is written to the file. If the internal LINAGE counter shows that writing this record has caused
the maximum available usable lines on a logical page to be exhausted, the internal end-of-page switch is set.

c.

If BEFORE ADVANCING is specified:
If BEFORE ADVANCING PAGE was specified, a form-feed character is written to the file and the internal
end-of-page switch is set
OTHERWISE the appropriate number of line-feed characters (ADVANCING n LINES) will be written to thefile; if the internal LINAGE counter shows that these line feeds have caused the maximum available
usable lines on a logical page to be exhausted, the internal end-of-page switch is set.

d.

If the internal end-of-page switch is not set, imperative-statement-2 (if any) is executed
OTHERWISE (the internal end-of-page switch is set), imperative-statement-1 (if any) is executed

14. With the information from #13 above in mind, here’s a cute trick for letting the AT END-OF-PAGE clauseautomatically generate page headings on your reports:
FD

Report-File
LINAGE IS 66 LINES........WITH FOOTER AT 57........LINES AT TOP 3........LINES AT BOTTOM 3.
.
.
OPEN OUTPUT Report-FilePERFORM Generate-Page-Header.
.
.
WRITE Report-Rec AFTER ADVANCING 1 LINEAT END-OF-PAGE PERFORM Generate-Page-Header
END-WRITE.
.
.
CLOSE Report-File

15. The INVALID KEY and NOT INVALID KEY clauses are legal only on WRITE statements used against for
ORGANIZATION RELATIVE or ORGANIZATION INDEXED files.

06FEB2009 Version

Page 6-101

OpenCOBOL 1.1 Programmers Guide

PROCEDURE DIVISION

16. The ON INVALID KEY clause will be triggered (thus executing imperative-statement-3) if an error occurred during
the WRITE. Such errors might be actual I/O errors or “Key Exists” errors (file status 22), indicating you tried to
WRITE a record that already existed.
17. The NOT ON INVALID KEY clause will be triggered (thus executing imperative-statement-4) if no error occurred
during the WRITE.

06FEB2009 Version

Page 6-102

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

7. The OpenCOBOL System Interface
7.1. Using the OpenCOBOL Compiler (cobc)
7.1.1. Introduction
Program source files should have extensions of “.cob” or “.cbl”.
Program filenames should match exactly the specification of PROGRAM-ID (including case). The reason for this was
discussed in section 3.
Spaces cannot be included in PROGRAM-IDs and therefore should not be included in program filenames.
The OpenCOBOL compiler will translate your COBOL program into C source code, compile that C source code into
executable binary form using the “C” compiler specified when OpenCOBOL was built and link that executable binary
into either directly executable form, static-linkable form or dynamically-loadable executable form.
The OpenCOBOL compiler is named “cobc” (“cobc.exe” on a Windows system).

7.1.2. Syntax and Options
The following describes the syntax and option switches of the cobc command. This information may be displayed byentering the command “cobc --help”.
Usage: cobc [options] file...
Options:--help--version, -V--info, -i-v-x-m-std=<dialect>-I <directory>-L <directory>-l <lib>-A <options>-Q <options>-D <define>-conf=<file>--list-reserved--list-intrinsics--list-mnemonics-save-temps(=<dir>)-MT <target>-MF <file>-ext <extension>

Display this message
Display compiler version
Display compiler build information
Display the commands invoked by the compiler
Build an executable program
Build a dynamically loadable module (default)
Warnings/features for a specific dialect :cobol2002
Cobol 2002
cobol85
Cobol 85
ibm
IBM Compatible
mvs
MVS Compatible
bs2000
BS2000 Compatible
mf
Micro Focus Compatible
default
When not specified
See config/default.conf and config/*.conf
Use free source format
Use fixed source format (default)
Enable optimization
Produce debugging information in the output
Enable all run-time error checking
Place the output into <file>Combine all input files into a single
dynamically loadable module
Preprocess only; do not compile, assemble or link
Translation only; convert COBOL to C
Compile only; output assembly fileCompile and assemble, but do not link
Generate preprocessed program listing (.lst)
Generate cross reference through 'cobxref'(V. Coen's 'cobxref' must be in path)
Add <directory> to copy/include search path
Add <directory> to library search path
Link the library <lib>
Add <options> to the C compile phase
Add <options> to the C link phase
Pass <define> to the C compiler
User defined dialect configuration - See -std=
Display reserved words
Display intrinsic functions
Display mnemonic names
Save intermediate files (default current directory)
Set target file used in dependency list
Place dependency list into <file>
Add default file extension

-W
-Wall
-Wobsolete

Enable ALL warnings
Enable all warnings except as noted below
Warn if obsolete features are used-free-fixed-O, -O2, -Os-g-debug-o <file>
-b
-E
-C
-S
-c
-P
-Xref

06FEB2009 Version

Page 7-1

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface-Warchaic-Wredefinition-Wconstant-Wparentheses-Wstrict-typing-Wimplicit-define-Wcall-params-Wcolumn-overflow-Wterminator-Wtruncate-Wlinkage-Wunreachable

Warn if archaic features are used
Warn incompatible redefinition of data items
Warn inconsistent constantWarn lack of parentheses around AND within OR
Warn type mismatch strictly
Warn implicitly defined data items
Warn non 01/77 items for CALL params (NOT set with -Wall)
Warn text after column 72, FIXED format (NOT set with -Wall)
Warn lack of scope terminator END-XXX (NOT set with -Wall)
Warn possible field truncation (NOT set with -Wall)
Warn dangling LINKAGE items (NOT set with -Wall)
Warn unreachable statements (NOT set with -Wall)-ftrace-ftraceall-fsyntax-only-fdebugging-line-fsource-location-fimplicit-init-fsign-ascii-fsign-ebcdic-fstack-check-ffold-copy-lower-ffold-copy-upper-fwrite-after-fnotrunc-ffunctions-all-fmfcomment-fnull-param

Generate trace code (Executed SECTION/PARAGRAPH)
Generate trace code (Executed SECTION/PARAGRAPH/STATEMENTS)
Syntax error checking only; don't emit any output
Enable debugging lines ('D' in indicator column)
Generate source location code (Turned on by -debug or -g)
Do automatic initialization of the Cobol runtime system
Numeric display sign ASCII (Default on ASCII machines)
Numeric display sign EBCDIC (Default on EBCDIC machines)
PERFORM stack checking (Turned on by -debug or -g)
Fold COPY subject to lower case (Default no transformation)
Fold COPY subject to upper case (Default no transformation)
Use AFTER 1 for WRITE of LINE SEQUENTIAL (Default BEFORE 1)
Do not truncate binary fields according to PICTURE
Allow use of intrinsic functions without FUNCTION keyword'*' or '/' in column 1 treated as comment (FIXED only)
Pass extra NULL terminating pointers on CALL statements

As discussed in section 2, program compilation units may consist of multiple programs defined sequentially in a single
source file. By specifying multiple source files on the “cobc” command, it is possible for a single execution of the“cobc” command to process multiple compilation units.

7.1.3. Compiling Executable Programs
The simplest mode of compilation is to generate a single executable file from one or more OpenCOBOL source files:
cobc –x prog1.cbl prog2.cbl prog3.cbl
The main program must be the first program unit found in the “prog1.cbl” file. The remainder of “prog1.cbl” as well
as all of “prog2.cbl” and “prog3.cbl” must be subprograms or nested subprograms.
This will generate a single executable file (UNIX) or exe file (Windows) which has all required COBOL programs
included in the file. The dynamically-loadable runtime libraries for OpenCOBOL, GMP and BDB (or whatever other file
I/O module was built-in to the OpenCOBOL package you are using) are still required to be available at run-time,
however.

7.1.4. Dynamically-Loadable Subprograms
Subprograms that are to be dynamically loaded into memory at execution time must be compiled using the “ -m”
option on the cobc command, as follows:
cobc –m sprog1.cbl- orcobc –m sprog1.cbl sprog2.cbl sprog3.cbl
The first command above generates a single dynamically-loadable module while the second example generates three.
The following rules apply to dynamically-loaded modules and the subroutines contained within them:1.

A Dynamically-loadable module generated from a source file named “xxxxxxxx.cbl” or “xxxxxxxx.cob” will be
named “xxxxxxxx.so” on a UNIX system or “xxxxxxxx.dll” on a Windows system.

2.

Dynamically-loadable modules containing only a single subprogram are created from OpenCOBOL source files
having only a single program-unit. The PROGRAM-ID of that program unit must match exactly the filename(minus “.cbl” or “.cob”) of the source code as well the filename (minus the “.so” or “.dll”) of the dynamicallyloadable module.

06FEB2009 Version

Page 7-2

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

3.

Dynamically-loadable modules containing multiple subprograms are created from a single OpenCOBOL source filecontaining multiple program-units. The PROGRAM-ID of one of those program units must match exactly the
filename (minus “.cbl” or “.cob”) of the source code as well the filename (minus the “.so” or .dll”) of the
dynamically-loadable module. This PROGRAM-ID is known as the primary entry-point of the dynamically-loadable
module.

4.

When a program CALLs a subprogram that is contained within a dynamically-loadable modulea.

The OpenCOBOL runtime library performs a search of all currently-loaded dynamically-loadable modules
for the subprogram entry-point (the entry-point is the literal or identifier coded on the CALL statement(see section 6.7). That entry-point will have been defined as either a PROGRAM-ID (section 3) or ENTRY
point (section 6.16) within the source file that created the dynamically-loadable module.

b.

If the entry-point was found, control is transferred to there and the subprogram begins execution.

c.

If the entry-point was not found, the OpenCOBOL runtime library searches for a file named “xxxxxxxx.so”(UNIX) or “xxxxxxxx.dll” (Windows), where xxxxxxxx is the desired subroutine entry-point.
i. If a file was located, it is loaded and control is transferred to the entry-point within it so thesubprogram may begin execution.
ii. If a file was not located, an error message (“libcob: Cannot find module 'xxxxxxxx'”) is issued
and program execution is aborted.

5.

Rule #4 has a profound implication to subprogramming with dynamically-loadable modules containing multiple
entry-points – You must successfully CALL the primary entry-point of the module (see rule #3) before you can
CALL any other entry-points within the module.

It is also possible to generate main programs as dynamically-loadable libraries. Just use the “-m” option (as shownhere) rather than the “-x” option. To execute these main programs, you’ll need to utilize the cobcrun command, as
discussed in section 7.2.2.

7.1.5. Static Subroutines
You may also compile OpenCOBOL subroutines into assembler source code which can then be assembled and linked
with a main program when that main program is compiled. To create such an assembler source file, compile thesubprogram(s) as follows:
cobc –S sprog1.cbl(Note: “-S” is an uppercase-S)

This will create an assembler source file named “sprog1.s”. If you specify multiple input files, they’ll each create theirown “.s” files.
To compile a main program, assemble an assembler source file and static-link it all together:cobc –x mainprog.cbl sprog1.s
If multiple subprograms are needed, simply add their “.s” files to the command line. Any subprogram entry-points forwhich “.s” files were not specified will be CALLed at runtime as dynamically-loadable modules.

7.1.6. Combining COBOL and C Programs
Linkage between OpenCOBOL and C language programs is possible, but may require a little bit of special coding in one
program or the other in order to meaningfully pass data between them. The issues involved deal predominantly withthree topics, as follows. Each issue is discussed, with upcoming coding samples illustrating specifics as to how thoseissues are overcome in actual program code.

7.1.6.1. OpenCOBOL Run-Time Library Requirements
Like most other implementations of the COBOL language, OpenCOBOL utilizes a run-time library. When the firstprogram unit executed in a given execution sequence is an OpenCOBOL program, any run-time library initialization will
06FEB2009 Version

Page 7-3

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

be performed by that COBOL code in a manner that is transparent to the C-language programmer. If, however, a C
program unit is the first to execute, the burden of perform OpenCOBOL run-time library initialization falls upon the C
program.

7.1.6.2. String Allocation Differences Between OpenCOBOL and C
Both languages store strings as a fixed-length continuous sequence of characters.
COBOL stores these character sequences up to a specific quantity limit imposed by the PICTURE cause of the data
item. For example:
01

LastName

PIC X(15).

There is never an issue of exactly what the length of a string contained in a USAGE DISPLAY data item is – there arealways exactly how ever many characters as were allowed for by the PICTURE clause. In the example above,“LastName” will always contain exactly fifteen characters; of course, there may be anywhere from 0 to 15 trailing
SPACES as part of the current LastName value.
C actually has no “string” datatype – rather, it stores strings as an array of “char” datatype items where each elementof the array is a single character. Being an array, there is an upper limit to how many characters may be stored in agiven “string”. For example:
char lastName[15]; /* 15 chars: lastName[0] thru lastName[14] */C provides a robust set of string-manipulation functions to copy strings from one char array to another, search stringsfor certain characters, compare one char array to another, concatenate char arrays and so forth. To make thesefunctions possible, it was necessary to be able to define the logical end of a string. C accomplishes this via the
expectation that all strings (char arrays) will be terminated by a NULL character (x’00’). Of course, no one forces a
programmer to do this, but if [s]he ever expects to use any of the C standard functions to manipulate that string they
had better be doing it.
So, OpenCOBOL programmers expecting to pass strings to or receive strings from C programs had best be prepared todeal with the null-termination issue.

7.1.6.3. Matching C Data Types with OpenCOBOL USAGEs
This is pretty simple, the OpenCOBOL and C programmer must just be aware of the following correspondence
between C data types and COBOL USAGE specifications:Figure 7-1 - C/OpenCOBOL Data Type Matches

This COBOL USAGE…

Occupies thisspace…

Holds these numeric values…

And corresponds to this Cdata type…

1 byte0 to 255

unsigned char

BINARY-CHAR SIGNED

1 byte-128 to +127

signed char

BINARY-SHORT

2 bytes

0 to 65535

unsigned(no PICTURE allowed)
BINARY-CHAR
BINARY-CHAR UNSIGNEDBINARY-SHORT UNSIGNED

unsigned int
unsigned shortunsigned short int

BINARY-SHORT SIGNED

2 bytes-32768 to +32767

int
short
short int
signed int

06FEB2009 Version

Page 7-4

OpenCOBOL 1.1 Programmers Guide
This COBOL USAGE…
(no PICTURE allowed)

Occupies thisspace…

The OpenCOBOL System Interface
Holds these numeric values…

And corresponds to this Cdata type…
signed short
signed short int

BINARY-LONG

4 bytes

0 to 4294967295

unsigned long

BINARY-LONG UNSIGNEDBINARY-LONG SIGNED

unsigned long int
4 bytes-2147483648 to +2147483647

long
long int
signed long
signed long int

BINARY-C-LONG SIGNED

4 bytes or 8
bytes

-2147483648 to +2147483647

long

Or

(see the description of
USAGE BINARY-C-LONG in
Figure 5-10)-9223372036854775808 to+9223372036854775807
BINARY-DOUBLE

8 bytes

0 to 18446744073709551615

BINARY-DOUBLE UNSIGNEDBINARY-DOUBLE SIGNEDCOMPUTATIONAL-1

unsigned long longunsigned long long int

8 bytes

4 bytes-9223372036854775808 to+9223372036854775807
38-3.4 x 10 to +3.4 x 10

long long int
signed long long int

38

float

308

double(six decimal digits of precision)

COMPUTATIONAL-2

8 bytes-1.7 x 10308

to +1.7 x 10

(15 decimal digits of precision)

N/A (no OpenCOBOL
equivalent)

12 bytes-1.19 x 104932

to +1.19 x 104932

long double(18 decimal digits of precision)

There are other OpenCOBOL PICTURE/USAGE combinations that can define the same storage size and value range
combinations, but (with the exception of COMP-1 and COMP-2), these are the ANSI2002 standard specifications for Cprogram data compatibility and OpenCOBOL programmers should get used to using them when data is being sharedwith C programs (they’re good documentation too, highlighting the fact that the data will be “shared” with a Cprogram).
The minimum values shown for the various SIGNED integer USAGEs are appropriate for a computer system that uses
2s-complement representation for negative signed binary values (such as those CPUs typically found in Windows PCs).
A computer system using 1s-complement representation for negative signed binary values would have minimum
values that are 1 greater (-127 instead of -128, for example).

06FEB2009 Version

Page 7-5

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

7.1.6.4. OpenCOBOL Main Programs CALLing C Subprograms
Here are samples of an OpenCOBOL program that CALLs a C subprogram.
Figure 7-2 - OpenCOBOL CALLing C(maincob.cbl)
This OpenCOBOL MAIN PROGRAM…
IDENTIFICATION DIVISION.
PROGRAM-ID. maincob.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Arg1
PIC X(7).
01 Arg2
PIC X(7).
01 Arg3
USAGE BINARY-LONG.
PROCEDURE DIVISION.
000-Main.
DISPLAY 'Starting cobmain'.
MOVE 123456789 TO Arg3.
STRING 'Arg1'
X'00'
DELIMITED SIZE
INTO Arg1
END-STRING.
STRING 'Arg2'
X'00'
DELIMITED SIZE
INTO Arg2
END-STRING.
CALL 'subc' USING BY CONTENT
Arg1,
BY REFERENCE Arg2,
BY REFERENCE Arg3.
DISPLAY 'Back'.
DISPLAY 'Arg1=' Arg1.
DISPLAY 'Arg2=' Arg2.
DISPLAY 'Arg3=' Arg3.
DISPLAY 'Returned value='
RETURN-CODE.
STOP RUN.

(subc.c)…wants to CALL this C SUBPROGRAM#include <stdio.h>
int subc(char *arg1,
char *arg2,
unsigned long *arg3) {char nu1[7]="New1";
char nu2[7]="New2";
printf("Starting subc\n");printf("Arg1=%s\n",arg1);
printf("Arg2=%s\n",arg2);
printf("Arg3=%d\n",*arg3);
arg1[0]='X';
arg2[0]='Y';*arg3=987654321;
return 2;}

The idea is to pass two string and one full-word unsigned arguments to the subprogram, have the subprogram print
them out, change all three and pass a return code of 2 back to the caller . The caller will then re-display the threearguments (showing changes only to the two BY REFERENCE arguments), display the return code and halt. While
simple, these two programs illustrate the techniques required quite nicely.
Note how the COBOL program ensures that a null end-of-string terminator is present on both string arguments.
Since the C program is planning on making changes to all three arguments, it declares all three as pointers in the
33
function header and references the third argument as a pointer in the function body.

33

It actually had no choice for the two string (char array) arguments – they must be defined as pointers in thefunction even though the function code references them without the leading “*” that normally signifies pointers.

06FEB2009 Version

Page 7-6

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

These programs are compiled and executed as follows. The example assumes a UNIX system with an OpenCOBOL
build that uses the native C compiler on that system; the technique works equally well regardless of which C compiler
and which operating system you’re using.
$ cc –c subc.c$ cobc -x maincob.cbl subc.o$ maincob
Starting cobmain
Starting subc
Arg1=Arg1
Arg2=Arg2
Arg3=123456789
Back
Arg1=Arg1
Arg2=Yrg2
Arg3=+0987654321
Returned value=+000000002$

Remember that the null characters are actually in the OpenCOBOL “Arg1” and “Arg2” data items. They don’t appear
in the output, but they ARE there. When passing character strings to C programs, it’s probably a good idea to make anull-terminated copy of the string items and pass those copies to the C program.
As was discussed in section 6.7, an OpenCOBOL CALL to a subprogram will need to specify the BY CONTENT clause to
make an argument unchangeable by a subprogram if that subprogram is written in a language other than OpenCOBOL.
When the CALLing and CALLed programs are both OpenCOBOL, the BY VALUE will be a faster alternative to BY
CONTENT.

7.1.6.5. C Main Programs CALLing OpenCOBOL Subprograms
Now, the roles of the two languages in the previous section will be reversed, having a C main program execute an
OpenCOBOL subprogram.
Figure 7-3 - C CALLing OpenCOBOL(mainc.c)This C MAIN PROGRAM…
#include <libcob.h>#include <stdio.h>
int main (int argc, char **argv) {int returnCode;char arg1[7] = "Arg1";
char arg2[7] = "Arg2";
unsigned long arg3 = 123456789;
printf("Starting mainc...\n");cob_init (argc, argv);/* cob_init(0,NULL) if cmdline args not going
to COBOL */returnCode = subcob(arg1,arg2,&arg3);
printf("Back\n");printf("Arg1=%s\n",arg1);
printf("Arg2=%s\n",arg2);
printf("Arg3=%d\n",arg3);
printf("Returned value=%d\n",returnCode);
return returnCode;}(subcob.cbl)…wants to CALL this OpenCOBOL SUBPROGRAMIDENTIFICATION DIVISION.
PROGRAM-ID. subcob.
DATA DIVISION.
LINKAGE SECTION.
01 Arg1
PIC X(7).
01 Arg2
PIC X(7).
01 Arg3
USAGE BINARY-LONG.
PROCEDURE DIVISION USINGBY VALUE
Arg1,
BY REFERENCE Arg2,
BY REFERENCE Arg3.
000-Main.
DISPLAY 'Starting cobsub.cbl'.
DISPLAY 'Arg1=' Arg1.
DISPLAY 'Arg2=' Arg2.
DISPLAY 'Arg3=' Arg3.
MOVE 'X' TO Arg1 (1:1).
MOVE 'X' TO Arg2 (1:1).
MOVE 987654321 TO Arg3.
MOVE 2 TO RETURN-CODE.
GOBACK.

Since the C program is the one that will execute first, before the OpenCOBOL subroutine, the burden of initializing the
OpenCOBOL run-time environment lies with that C program; it will have to invoke the “cob_init” function, which ispart of the “libcob” library. The two required C statements are shown, highlighted in boldface.
The arguments to the “cob_init” routine are the argument count and value parameters passed to the main function
when the program began execution. By passing them into the OpenCOBOL subprogram, it will be possible for that
OpenCOBOL program to retrieve the command line or individual command-line arguments. If that won’t benecessary, “cob_init(0,NULL);” could be specified instead.

06FEB2009 Version

Page 7-7

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

Since the C program wants to allow “arg3” to be changed by the subprogram, it prefixes it with a “&” to force a CALLBY REFERENCE for that argument. Since “arg1” and “arg2” are strings (char arrays), they are automatically passed byreference.
Here’s the output of the compilation process as well as the program’s execution. The example assumes a Windows
system with an OpenCOBOL build that uses the GNU C compiler on that system; the technique works equally wellregardless of which C compiler and which operating system you’re using.
C:\Users\Gary\Documents\Programs> cobc -S subcob.cbl
C:\Users\Gary\Documents\Programs> gcc mainc.c subcob.s –o mainc.exe -llibcob
C:\Users\Gary\Documents\Programs> mainc.exe
Starting mainc...
Starting cobsub.cbl
Arg1=Arg1
Arg2=Arg2
Arg3=+0123456789
Back
Arg1=Xrg1
Arg2=Xrg2
Arg3=987654321
Returned value=2
C:\Users\Gary\Documents\Programs>
stNote that even though we told OpenCOBOL that the 1 argument was to be BY VALUE, it was treated as if it were BY
REFERENCE anyway. String (char array) arguments passed from C callers to OpenCOBOL subprograms will be
modifiable by the subprogram. It’s best to pass a copy of such data if you want to ensure that the subprogram doesn’tchange it.
The third argument is different, however. Since it’s not an array you have the choice of passing it either BY
34
35
REFERENCE or BY VALUE .

34

Use “&” with the argument in the C calling program; specify the argument as BY REFERENCE in the COBOL
subprogram

35

Don’t use “&” with the argument in the C calling program; specify the argument as BY VALUE in the COBOL
subprogram

06FEB2009 Version

Page 7-8

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

7.1.7. Important Environment Variables
The following chart documents the various environment variables that can play a role in the compilation of
OpenCOBOL programs.
Figure 7-4 - Compiler Environment Variables

Environment Variable
COB_CC

COB_CFLAGS36

COB_CONFIG_DIR

COB_COPY_DIR

COB_LDADD

36

COB_LDFLAGSCOB_LIBS

36

36

COBCPY

LD_LIBRARY_PATH36

Use
Set to the name of the C compiler you wish OpenCOBOL
to use.
USE THIS FEATURE AT YOUR OWN RISK – YOU SHOULD
ALWAYS USE THE C COMPILER YOUR OPENCOBOL
BUILD WAS GENERATED FOR
Set to any switches that you’d like to pass on to the Ccompiler from the cobc compiler (in addition to any thatcobc will specify). The default is “-Iprefix/include”,
where “prefix” is the path prefix specified when the
OpenCOBOL binaries you are using were created.
Set to the path to the folder where OpenCOBOL“config” files are kept. See section 7.1.9 for information
on how those config files are used.
If COPY modules your program needs are NOT stored in
the same directory as your program, set thisenvironment variable to the folder in which the COPY
modules may be found (IBM mainframe programmers
will recognize this as “SYSLIB”). See section 7.1.8 foradditional information on the use of COPY modules.
Set to any additional linker switches (ld) that can specify
where standard libraries that must be linked with theprogram can be found. The default is “” (null).
Set to any linker/loader (ld) switches that you’d like topass on to the C compiler from the cobc compiler (inaddition to any that cobc will specify). The default isnone.
Set to any linker switches (ld) that specify where
standard libraries that must be linked with the program
can be found. The default is “-Lprefix/lib -lcob” , where“prefix” is the path prefix specified when the
OpenCOBOL binaries you are using were created.
This environment variable provides an additional meansof specifying where COPY modules may be found by thecompiler (see also COB_COPY_DIR, above). See section
7.1.8 for additional information on the use of COPY
modules.
If you are planning on using static-linked subroutine
libraries, set this variable to the path to the directory
containing your libraries.

These switches are intended for use only in very special circumstances by very advanced users; their usage is
discouraged. A future release of OpenCOBOL will introduce a better way to pass switched to the C compiler and/or
the loader from the cobc command.

06FEB2009 Version

Page 7-9

OpenCOBOL 1.1 Programmers Guide
Environment Variable
TMPDIR
TMP(checked in this order)

The OpenCOBOL System Interface
Use
Set to a directory/folder appropriate to create
temporary files in. The intermediate working files
created by cobc will be created here (and deleted once
they’re no longer needed).
On a Windows system, the TMP environment variable isnormally set for you when you logon. If you wish to use
a different temporary folder, you may set TMPDIR
yourself and have no fear of disrupting other Windows
software that relies on TMP.

7.1.8. Locating Copybooks at Compilation TimeThe OpenCOBOL compiler will attempt to locate copybooks (source code modules brought into the compilation
process via the COPY statement) by searching for them in the following folders. The search will occur in the sequence
shown below, and will terminate once a copybook is found.
The folder in which the program being compiled resides.
The folder named on the “-I” compiler switch (see section 7.1.2)
Each of the folders named on the COBCPY environment variable (see section 7.1.7). A single folder may be
37
named or multiple folders may be specified, separated by a system-appropriate delimiter character. Whenmultiple folders are specified, they will be searched in the order they are named on the environment
variable.
The folder specified on the COB_COPY_DIR environment variable (see section 7.1.7).
As each of the above folders is searched for a copybook - “COPY XXXXXXXX.”, for example – the OpenCOBOL compiler
will attempt to locate the copybook file by any of the following names, in the sequence shown:
XXXXXXXX.CPYXXXXXXXX.CBLXXXXXXXX.COB
XXXXXXXX.cpy
XXXXXXXX.cbl
XXXXXXXX.cob
XXXXXXXX
The COPY command is case-sensitive on UNIX systems; “COPY copybookname” and “COPY COPYBOOKNAME” will both
fail to locate the “CopyBookName” copybook on a UNIX system. Windows implementations of OpenCOBOL may or
may not be similarly case sensitive with regard to copybook names, depending upon the Windows version and
OpenCOBOL build options – it is safest to simply treat the COPY command as case-sensitive in all environments.

7.1.9. Using Compiler Configuration Files
OpenCOBOL uses compiler configuration files to define various options that will control the compilation process.
These configuration files are specified using the “-conf” compilation switch or are found in the folder defined by the
COB_CONFIG_PATH environment variable.
The following is a verbatim listing of the “default” configuration file (the one used if you don’t specify the “ -conf”
switch), just to show you the types of settings that may appear:# COBOL compiler configuration-*- sh -*-# Value: any string
name: "OpenCOBOL"

37

If the OpenCOBOL compiler you are using was built to utilize a native Windows environment, use a semicolon (;).
If, however, the OpenCOBOL compiler was built for a Unix or Linux environment, or was built for a Windows
environment utilizing either the Cygwin or MinGW Unix “emulators”, use a colon character (:) as the separator.

06FEB2009 Version

Page 7-10

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface# Value: int
tab-width: 8
text-column: 72# Value: 'cobol2002', 'mf', 'ibm'#
assign-clause: mf# If yes, file names are resolved at run time using environment variables.
# For example, given ASSIGN TO "DATAFILE", the actual file name will be# 1. the value of environment variable 'DD_DATAFILE' or# 2. the value of environment variable 'dd_DATAFILE' or# 3. the value of environment variable 'DATAFILE' or# 4. the literal "DATAFILE"# If no, the value of the assign clause is the file name.
## Value: 'yes', 'no'filename-mapping: yes# Value: 'yes', 'no'pretty-display: yes# Value: 'yes', 'no'auto-initialize: yes# Value: 'yes', 'no'complex-odo: no# Value: 'yes', 'no'indirect-redefines: no# Binary byte size - defines the allocated bytes according to PIC# Value:signed unsigned bytes#------ -------- ----# '2-4-8'
1 - 4
2
#
5 - 9
4
#
10 - 18
8## '1-2-4-8'
1 - 2
1
#
3 - 4
2
#
5 - 9
4
#
10 - 18
8## '1--8'
1 - 2
1 - 2
1
#
3 - 4
3 - 4
2
#
5 - 6
5 - 7
3
#
7 - 9
8 - 9
4
#
10 - 1110 - 125#
12 - 14
13 - 146#
15 - 16
15 - 167#
17 - 18
17 - 18
8
binary-size: 1-2-4-8# Value: 'yes', 'no'binary-truncate: yes# Value: 'native', 'big-endian'binary-byteorder: big-endian# Value: 'yes', 'no'larger-redefines-ok: no# Value: 'yes', 'no'relaxed-syntax-check: no# Perform type OSVS - If yes, the exit point of any currently executing perform# is recognized if reached.
# Value: 'yes', 'no'perform-osvs: no# If yes, linkage-section items remain allocated# between invocations.
# Value: 'yes', 'no'sticky-linkage: no

06FEB2009 Version

Page 7-11

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface# If yes, allow non-matching level numbers# Value: 'yes', 'no'relax-level-hierarchy: no# not-reserved:# Value: Word to be taken out of the reserved words list
# (case independent)# Dialect features# Value: 'ok', 'archaic', 'obsolete', 'skip', 'ignore', 'unconformable'author-paragraph:obsoletememory-size-clause:
obsolete
multiple-file-tape-clause:
obsoletelabel-records-clause:
obsoletevalue-of-clause:
obsoletedata-records-clause:
obsolete
top-level-occurs-clause:skip
synchronized-clause:okgoto-statement-without-name:obsoletestop-literal-statement:
obsoletedebugging-line:
obsolete
padding-character-clause:
obsoletenext-sentence-phrase:archaic
eject-statement:
skip
entry-statement:
obsoletemove-noninteger-to-alphanumeric: error
odo-without-to:ok

7.2. Running OpenCOBOL Programs
7.2.1. Executing Programs Directly
OpenCOBOL programs compiled with the “-x” option will be generated as directly-executable programs. For
example, on a Windows system, the “-x” option will be generated as an “.exe” file.
These native executables are appropriate for execution as non-graphical user interface programs.
On a UNIX system this means the programs may be executed from a command shell such as bash, csh, ksh and soforth. When an OpenCOBOL program runs on a Windows system, it runs within a console window (i.e. “cmd.exe”).
Interactions between the program and the user will take place using the standard input, standard output and standard
error streams. Any SCREEN SECTION I/O performed by the program will take place within the command shell“window”.
Direct program execution syntax is as follows:[path]program [arguments]
For example:/usr/local/printaccount ACCT=6625378
Or…
C:\Users\Me\Documents\Programs\printaccount.exe ACCT=6625378

7.2.2. Using the “cobcrun” Utility
It is possible to generate executable modules for all OpenCOBOL programs, not just subroutines, by choosing to use
the “-m” option to specify the compiler output format even for main programs (as discussed in section 7.1.4, this is therecommended output format option for subroutines).
Some may prefer to compile their OpenCOBOL main programs into these dynamically-loadable modules in theinterests of using the same general compilation command for all programs without having to think “Is it a main
program or a subroutine?”.
Main programs compiled in this manner should be executed as follows:
06FEB2009 Version

Page 7-12

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface[path]cobcrun program [arguments]
Do not specify the “.so” or “.dll” extension on the program name. The “program” value must exactly match the
PROGRAM-ID of the main program (including upper- and lower-case letters).
For an example of the use of cobcrun:
cd /usr/local
cobcrun printaccount ACCT=6625378
Or…
cd C:\Users\Me\Documents\Programs
cobcrun printaccount.exe ACCT=6625378
Note how the cobcrun command does not allow a path to be specified with the program name –the directory in which
the programs dynamically loadable module exists must either be the current directory or must be defined in thecurrent PATH.

7.2.3. Program Arguments
Regardless of the manner in which a program is executed, any arguments specified to the program may be retrieved
via either of the following, documented in section 6.4.2:
ACCEPT … FROM COMMAND-LINE
ACCEPT … FROM ARGUMENT-VALUE

7.2.4. Important Environment Variables
The following chart documents the various environment variables that can play a role in the execution of OpenCOBOL
programs.
Figure 7-5 - Run-Time Environment Variables

Environment Variable

Use

COB_LIBRARY_PATH

At runtime, OpenCOBOL will attempt to locate and load
any application dynamically-loadable libraries from the
PATH and the directory in which the program
executable was found. If these library files could besomewhere else, specify the directory path using thisvariable.

COB_PRE_LOAD

If set to any non-null value, this variable will cause all
dynamically-loadable libraries to be loaded when the
program begins execution (rather than searching forand loading the module upon first use).

COB_SCREEN_ESC

If set to any non-blank value, this variable allows the
ACCEPT verb to detect the Esc key. See
Figure 4-8 for additional information.

COB_SCREEN_EXCEPTIONS

Setting this variable to any non-blank value will allow
the ACCEPT verb to detect the Esc, PgUp and PgDn keys.
See
Figure 4-8 for additional information.

06FEB2009 Version

Page 7-13

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

Environment Variable

Use

COB_SORT_MEMORY

The value of this variable (an integer) will be used todefine how much memory will be allocated for use insorting. If the value is 1048576 or greater, that value
will be used “as is” as the amount of memory (in bytes)
to allocate. If the value is less than 1048576. The
default sort memory amount is 128 MB.

COB_SWITCH_n(n=1 to 8); These environment variables correspond to
SWITCH-1 through SWITCH-8. Setting them to “ON” will
activate them; any other value turns them off. See
section 4.1.4 for more information.

COB_SYNC

If set to a value of upper- or lowercase “p”, this variable
will force a file commit every time a file is written to(ensuring that data is immediately written to the filerather than retained in memory until a future commit
occurs). This will slow-down update access to files, butwill provide for better integrity in the event of aprogram failure.

DB_HOME

If your OpenCOBOL build uses the Berkeley Database(BDB) package, use this environment variable to specify
the folder in which the lock management files to be
associated with all non-SORT files opened by the38
program will be stored . Having this variable defined
will activate record locking features on the READ
(section 6.33), REWRITE (section 6.36) and WRITE
39(section 6.50) statements .

PATH

The OpenCOBOL “bin” directory should be defined in
the PATH.

TMPDIR

Set to a directory/folder appropriate to create
temporary files in. This will be used by SORT and
MERGE to create temporary work files. You may also
use this folder for any temporary files your application
may require.

TMP
TEMP
(checked in this order)

Good form dictates that – if your application DOES
create temporary working files – it should clean-up
40
after itself. .

7.3. Built-In Subroutines38

ORGANIZATION INDEXED files will also have their data file allocated in the DB_HOME folder, if DB_HOME exists.

39

Even with DB_HOME, locking will not work with ORGANIZATION SEQUENTIAL (either type) or ORGANIZAIONRELATIVE files with OpenCOBOL builds created for Windows/MinGW. ORGANIZATION INDEXED locks will workwith Windows/MinGW and all locks will work for all file organizations with UNIX OpenCOBOL builds.

40

Take a look at the C$DELETE and CBL_DELETE_FILE built-in subroutines.

06FEB2009 Version

Page 7-14

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

7.3.1. “Call by Name” Routines
There are a number of built-in subroutines included with OpenCOBOL. Generally, these routines are intended tomatch those available in Micro Focus COBOL (CBL_...) or ACUCOBOL (C$...).
These routines, all executed via their UPPERCASE NAMES, are capable of performing the following functions:
Changing the current directory
Copying files
Creating a directory
Creating, Opening, Closing, Reading and Writing byte-stream files
Deleting directories (folders)
Deleting files
Determining how many arguments were passed to a subroutine
Getting file information (size and last-modification date/time)
Getting the length (in bytes) of an argument passed to a subroutine
Justifying a field left-, right- or center-aligned
Moving files (a destructive “copy”)
Putting the program ‘to sleep’, specifying the sleep time in seconds
Putting the program ‘to sleep’, specifying the sleep time in nanoseconds; CAVEAT: although you’ll
express the time in nanoseconds, Windows systems will only be able to sleep at a millisecond
granularity
Submitting a command to the shell environment appropriate for the version of OpenCOBOL you areusing for execution
The following table describes the various built-in subroutines. ALL SUBROUTINE ARGUMENTS ARE MANDATORY
EXCEPT WHERE EXPLICITLY NOTED TO THE CONTRARY. Any subroutine returning a value to RETURN-CODE could
utilize the RETURNING/GIVING clause on the CALL to return the result back to the full-word binary COMP-5 data itemof your choice. See section 6.7.

7.3.1.1. CALL “C$CHDIR” USING directory-path, result
This routine makes directory-path (an alphanumeric literal or identifier) the current directory.
The return code of the operation is returned both in the result argument (any non-edited numeric identifier) as well as
in the RETURN-CODE special register. The return code of the operation will be either 0=Success or 128=failure.
The directory change remains in effect until the program terminates (in which the original current directory at thetime the program was restarted will be automatically restored) or until another C$CHDIR is executed.
Also see CBL_CHANGE_DIR – section 7.3.1.13.

7.3.1.2. CALL “C$COPY” USING src-file-path, dest-file-path, 0
Use this subroutine to copy file src-file-path to dest-file-path as if it were done via the “CP” (Unix) or “COPY”(Windows) command.
Both file path arguments may be alphanumeric literals or identifiers.
The third argument is required, but is unused.

06FEB2009 Version

Page 7-15

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

If the attempt to copy the file fails (for example, it or the destination directory doesn't exist), RETURN-CODE will be set
to 128; on successful completion it will be set to 0.
Also see CBL_COPY_FILE – section 7.3.1.16.

7.3.1.3. CALL “C$DELETE” USING file-path, 0This routine deletes the file specified by the file-path argument (an alphanumeric literal or identifier) just as if thatwere done using the “RM” (Unix) or “ERASE” (Windows) command.
The second argument is required, but is unused.
If the attempt to delete the file fails (for example, it doesn't exist), RETURN-CODE will be set to 128; on successful
completion it will be set to 0.
Also see CBL_DELETE_FILE – section 7.3.1.20.

7.3.1.4. CALL “C$FILEINFO” USING file-path, file-info
41

With this routine you may retrieve the size of the file specified as the file-path argument (an alphanumeric literal or
identifier) and the date/time that file was last modified. The information is returned to the file-info argument, which
is defined as the following 16-byte area:
01

File-Info.
05 File-Size-In-Bytes
05 Mod-YYYYMMDD
05 Mod-HHMMSS00

PIC 9(18) COMP.
PIC 9(8) COMP. *> Modification Date
PIC 9(8) COMP. *> Modification TimeThe last two decimal digits in the modification time will always be 0.
If the subroutine is successful, a value of 0 will be returned in RETURN-CODE. Failure to retrieve the needed statistics
on the file will cause a RETURN-CODE value of 35 to be passed back. Supplying less than two arguments will generate
a 128 RETURN-CODE value.
Also see CBL_CHECK_FILE_EXIST – section 7.3.1.14.

7.3.1.5. CALL “C$JUSTIFY” USING data-item, “justification-type”
Use C$JUSTIFY to left, right or center-justify an alphabetic, alphanumeric or numeric edited data-item. The
justification-type argument indicates the type of the justification to be performed. The value of that argument will beinterpreted as follows:absentCxxx...
Rxxx...
Lxxx...
anything else

Treated the same as if it were "R"
If it begins with a capital "C", the value will be centeredIf it begins with a capital "R", the value will be right-justified, space-filled to the left
If it begins with a capital "L", the value will be left-justified, space-filled to the rightTreated as if it were "R"

7.3.1.6. CALL “C$MAKEDIR” USING dir-path
With this routine you may create a new directory – the name of which is supplied as the dir-path argument (analphanumeric literal or identifier).
Only the lowest-level directory (last) in the specified path can be created – all others must already exist. This
subroutine will NOT behave as a “mkdir –p” (Unix) or “mkdir /p” (Windows).

41

File size information may not be available in the particular OpenCOBOL build / Operating System combination you
are using and may therefore always be returned as zero.

06FEB2009 Version

Page 7-16

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

RETURN-CODE will be set to the return code of the operation; the value will be either 0=Success or 128=failure.
Also see CBL_CREATE_DIR- section 7.3.1.17.

7.3.1.7. CALL “C$NARG” USING arg-count-result
C$NARG returns the number of arguments passed to the subroutine that calls C$NARG back to the numeric field argcount-result.
When CALLed from a main program, the returned value will always be 0.
Also see the NUMBER-OF-CALL-PARAMETERS.register (section 6.1.8).

7.3.1.8. CALL “C$PARAMSIZE” USING argument-numberThis subroutine returns the size (in bytes) of the subroutine argument supplied using the argument-number parameter(a numeric literal or data item).
The size is returned in the RETURN-CODE special register.
If the specified argument does not exist, or an invalid argument number is specified, a value of 0 is returned.

7.3.1.9. CALL “C$SLEEP” USING seconds-to-sleep
C$SLEEP puts the program to sleep for the specified number of seconds. The seconds-to-sleep argument may be a
numeric literal or data item.
Sleep times less than 1 will be interpreted as 0, which immediately returns without any sleep delay.
Also see the CBL_OC_NANOSLEEP subroutine – section 7.3.1.30.

7.3.1.10. CALL “C$TOLOWER” USING data-item, BY VALUE convert-length
This routine will converts convert-length (a numeric literal or data item) leading characters of data-item (analphanumeric identifier) to lower-case.
The convert-length argument must be specified BY VALUE. It specifies how many (leading) characters in data-item will
be converted – any characters after that will remain unchanged.
If convert-length is negative or zero, no conversion will be performed.
Also see CBL_TOLOWER – section 7.3.1.35.

7.3.1.11. CALL “C$TOUPPER” USING data-item, BY VALUE convert-length
Use the C$TOUPPER subroutine to change the convert-length (a numeric literal or data item) leading characters ofdata-item (an alphanumeric identifier) to upper-case.
The convert-length argument must be specified BY VALUE. It specifies how many (leading) characters in data-item will
be converted – any characters after that will remain unchanged.
If convert-length is negative or zero, no conversion will be performed.
Also see CBL_TOUPPER – section 7.3.1.36.

7.3.1.12. CALL “CBL_AND” USING item-1, item-2, BY VALUE byte-length
This subroutine performs a bit-by-bit logical AND operation between the left-most 8*byte-length corresponding bits of
item-1 and item-2, storing the resulting bit string into item-2.

06FEB2009 Version

Page 7-17

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

Item-1 may be an alphanumeric literal or a data item. Item-2 must be a data item. The length of both item-1 anditem-2 must be at least 8*byte-length.
Byte-length may be a numeric literal or data item, and must be specified using BY VALUE.
The truth table shown to the right documents the “AND” process.
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE register.

Arg #1bit

Arg #2
bit

0
0
1
1

0
1
0
1

New
Arg #2bit
0001

7.3.1.13. CALL “CBL_CHANGE_DIR” USING directory-path
This routine makes directory-path (an alphanumeric literal or identifier) the current directory.
The directory change remains in effect until the program terminates (in which the original current directory at thetime the program was restarted will be automatically restored) or until another CBL_CHANGE_DIR (or C$CHDIR) is
executed.
The return code of the operation is returned in the RETURN-CODE special register. The return code of the operation
will be either 0=Success or 128=failure.
Also see C$CHDIR – section 7.3.1.1.

7.3.1.14. CALL “CBL_CHECK_FILE_EXIST” USING file-path, file-info
42

With this routine you may retrieve the size of the file specified as the file-path argument (an alphanumeric literal or
identifier) and the date/time that file was last modified. The information is returned to the file-info argument, which
is defined as the following 16-byte area:
01

Argument-2.
05 File-Size-In-Bytes
05 Mod-DD
05 Mod-MO
05 Mod-YYYY
05 Mod-HH
05 Mod-MM
05 Mod-SS
05 FILLER

PIC 9(18)
PIC 9(2)
PIC 9(2)
PIC 9(4)
PIC 9(2)
PIC 9(2)
PIC 9(2)
PIC 9(2)

COMP.
COMP.
COMP.
COMP.
COMP.
COMP.
COMP.
COMP.

*> Modification Time*> Modification Date*> This will always be 00

If the subroutine is successful, a value of 0 will be returned in RETURN-CODE. Failure to retrieve the needed statistics
on the file will cause a RETURN-CODE value of 35 to be passed back. Supplying less than two arguments will generate
a 128 RETURN-CODE value.
Also see C$FILEINFO - section 7.3.1.4.

7.3.1.15. CALL “CBL_CLOSE_FILE” USING file-handle
The CBL_CLOSE_FILE subroutine closes a bytestream file previously opened by either the CBL_OPEN_FILE or
CBL_CREATE_FILE subroutines.
If the file defined by the file-handle argument (a PIC X(4) USAGE COMP-X data item) was opened for output, an implicit
CBL_FLUSH_FILE will be performed before the file is closed.

42

File size information may not be available in the particular OpenCOBOL build / Operating System combination you
are using and may therefore always be returned as zero.

06FEB2009 Version

Page 7-18

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

If the subroutine is successful, a value of 0 will be returned in RETURN-CODE. Failure will cause a RETURN-CODE valueof -1 to be passed back.

7.3.1.16. CALL “CBL_COPY_FILE” USING src-file-path, dest-file-path
Use this subroutine to copy file src-file-path to dest-file-path as if it were done via the “CP” (Unix) or “COPY”(Windows) command.
Both file path arguments may be alphanumeric literals or identifiers.
If the attempt to copy the file fails (for example, it or the destination directory doesn't exist), RETURN-CODE will be set
to 128; on successful completion it will be set to 0.
Also see C$COPY – section 7.3.1.2.

7.3.1.17. CALL “CBL_CREATE_DIR” USING dir-path
With this routine you may create a new directory – the name of which is supplied as the dir-path argument (analphanumeric literal or identifier).
Only the lowest-level directory (last) in the specified path can be created – all others must already exist. This
subroutine will NOT behave as a “mkdir –p” (Unix) or “mkdir /p” (Windows).
RETURN-CODE will be set to the return code of the operation; the value will be either 0=Success or 128=failure.
Also see C$MAKEDIR – section 7.3.1.6.

7.3.1.18. CALL “CBL_CREATE_FILE” USING file-path, 2, 0, 0, file-handle
The CBL_CREATE_FILE subroutine creates the new file specified using the file-path argument and opens it for output
as a byte-stream file usable by CBL_WRITE_FILE..
Arguments 2, 3 and 4 should be coded as the constant values shown.

43

A file handle (PIC X(4) USAGE COMP-X) will be returned, for any subsequent CBL_WRITE_FILE or CBL_CLOSE_FILE calls.
The success or failure of the subroutine will be reported back in the RETURN-CODE register, with a RETURN-CODE
value of -1 indicating an invalid argument and a value of 0 indicating success.
Also see CBL_OPEN_FILE – section 7.3.1.31.

7.3.1.19. CALL “CBL_DELETE_DIR” USING dir-path
Delete an empty directory via CBL_DELETE_DIR.
The only argument – dir-path (an alphanumeric literal or identifier) – is the name of the directory to be deleted.
Only the lowest-level directory (last) in the specified path will be deleted, and that directory must be empty to bedeleted.
RETURN-CODE will be set to the return code of the operation; the value will be either 0=Success or 128=failure.

7.3.1.20. CALL “CBL_DELETE_FILE” USING file-path
This routine deletes the file specified by the file-path argument (an alphanumeric literal or identifier) just as if thatwere done using the “RM” (Unix) or “ERASE” (Windows) command.

43

CBL_CREATE_FILE is actually a special-case of the CBL_OPEN_FILE routine - see that routine for a description of
the meanings of arguments 2, 3 and 4.

06FEB2009 Version

Page 7-19

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

If the attempt to delete the file fails (for example, it doesn't exist), RETURN-CODE will be set to 128; on successful
completion it will be set to 0.
Also see C$DELETE – section 7.3.1.3.

7.3.1.21. CALL “CBL_ERROR_PROC” USING function, program-pointerThis routine registers a general error-handling routine.
The function argument must be a numeric literal or a 32-bit binary COMP-5 data item (USAGE BINARY-LONG, forexample) with a value of 0 or 1. A value of 0 means that you will be registering (“installing”) an error procedure whilea value of 1 indicates you’re deregistering (“uninstalling”) a previously-installed error procedure.
The program-pointer must be a USAGE PROGRAM-POINTER data item containing the address of your error procedure.
See section 6.39.2 for instructions on how to populate such a data item.
A success (0) or failure (non-0) result will be passed back in the RETURN-CODE register.
A custom error-handler routine, if any, will trigger when a runtime error condition is encountered. The code within
the handler will be executed and – once the handler issues an EXIT PROGRAM or a GOBACK - the system-standard
error handling routine will be executed.
Only one user-defined error procedure may be in effect at any time.
An error procedure may be defined by a main program or a subprogram, but regardless of from where it was
registered, it applies to the overall program compilation unit and will trigger when a runtime error occurs anywhere in
the executable program. If the error procedure was defined by a subprogram, that program must be loaded at thetime the error procedure is executed.
An error procedure should terminate using EXIT PROGRAM or GOBACK.
The following is a sample OpenCOBOL program that registers an error procedure. The output of that program isshown as well - as you can see, the error handler’s messages appear followed by the standard OpenCOBOL message.
IDENTIFICATION DIVISION.
PROGRAM-ID. demoerrproc.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
78 Err-Proc-Install
VALUE 0.
01 Current-Date
PIC X(8).
01 Current-TimePIC X(8).
01 Err-Proc-Address
USAGE PROCEDURE-POINTER.
01 Formatted-Date
PIC X(4)/X(2)/X(2).
01 Formatted-TimePIC X(2)/X(2)/X(2).
PROCEDURE DIVISION.
000-Register-Err-Proc.
SET Err-Proc-Address TO ENTRY "999-Err"
CALL "CBL_ERROR_PROC"USING Err-Proc-Install, Err-Proc-Address
END-CALLIF RETURN-CODE NOT = 0
DISPLAY 'Error: Could not‟ &„register Error Procedure'
END-IF.
Program output…
099-Now-Test-Err-Proc.
CALL "Tilt" END-CALL** A Runtime Error Has Occurred **GOBACK.
***
2009/08/28 10:35:10***
999-Err-Proc.
libcob: Cannot find module 'Tilt'
ENTRY "999-Err"
DISPLAY'** A Runtime Error Has Occurred **'END-DISPLAY
ACCEPT
Current-Date FROM DATE YYYYMMDD
END-ACCEPTACCEPT
Current-Time FROM TIME

06FEB2009 Version

Page 7-20

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

END-ACCEPTMOVE Current-Date TO Formatted-Date
MOVE Current-Time TO Formatted-Time
INSPECT Formatted-Time REPLACING ALL '/' BY ':'DISPLAY'***' Formatted-Date ' ' Formatted-Time 'END-DISPLAYGOBACK.

***'

7.3.1.22. CALL “CBL_EXIT_PROC” USING function, program-pointerThis routine registers a general exit-handling routine.
The function argument must be a numeric literal or a 32-bit binary COMP-5 data item (USAGE BINARY-LONG, forexample) with a value of 0 or 1. A value of 0 means that you will be registering (“installing”) an exit procedure while avalue of 1 indicates you’re deregistering (“uninstalling”) a previously-installed exit procedure.
The program-pointer must be a USAGE PROGRAM-POINTER data item containing the address of your exit procedure.
See section 6.39.2 for instructions on how to populate such a data item.
A success (0) or failure (non-0) result will be passed back in the RETURN-CODE register.
An exit procedure will trigger when a “STOP RUN” or its equivalent (i.e. “GOBACK” executed in a main program) is
executed. The exit procedure code will be executed and – once it issues an EXIT PROGRAM or a GOBACK, the systemstandard program termination routine will be executed.
Only one user-defined exit procedure may be in effect at any time.
An exit procedure may be defined by a main program or a subprogram, but regardless of from where it was registered,it applies to the overall program compilation unit and will trigger when a STOP RUN is executed anywhere in theexecutable program. If the exit procedure was defined by a subprogram, that program must be loaded at the time theexit procedure is executed.
An exit procedure should terminate using EXIT PROGRAM or a GOBACK.
The following is a sample OpenCOBOL program that registers an exit procedure. The output of that program is shownas well.
IDENTIFICATION DIVISION.
PROGRAM-ID. demoexitproc.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
78 Exit-Proc-Install
VALUE 0.
01 Current-Date
PIC X(8).
01 Current-TimePIC X(8).
01 Exit-Proc-Address
USAGE PROCEDURE-POINTER.
01 Formatted-Date
PIC XXXX/XX/XX.
01 Formatted-TimePIC XX/XX/XX.
PROCEDURE DIVISION.
000-Register-Exit-Proc.
SET Exit-Proc-Address TO ENTRY "999-Exit"
CALL "CBL_EXIT_PROC"USING Exit-Proc-Install, Exit-Proc-Address
END-CALLIF RETURN-CODE NOT = 0
DISPLAY 'Error: Could not register Exit Procedure'
END-IF.
Program output…
099-Now-Test-Exit-Proc.
DISPLAY
Executing a STOP RUN...
'Executing a STOP RUN...'*** STOP RUN has been executed
END-DISPLAYGOBACK***
2009/08/28 10:01:29.
999-Exit-Proc.
ENTRY "999-Exit"DISPLAY'*** STOP RUN has been executed ***'
END-DISPLAY

06FEB2009 Version

***
***

Page 7-21

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

ACCEPT
Current-Date FROM DATE YYYYMMDD
END-ACCEPTACCEPT
Current-Time FROM TIME
END-ACCEPTMOVE Current-Date TO Formatted-Date
MOVE Current-Time TO Formatted-Time
INSPECT Formatted-Time REPLACING ALL '/' BY ':'DISPLAY'***' Formatted-Date ' ' Formatted-Time 'END-DISPLAYGOBACK.

***'

7.3.1.23. CALL “CBL_EQ” USING item-1, item-2, BY VALUE byte-length
This subroutine performs a bit-by-bit test for equality between the left-most 8*byte-length corresponding bits of item1 and item-2, storing the resulting bit string into item-2.
Item-1 may be an alphanumeric literal or a data item. Item-2 must be a data item. The length of both item-1 anditem-2 must be at least 8*byte-length.
Byte-length may be a numeric literal or data item, and must be specified using BY VALUE.
The truth table shown to the right documents the “EQ” process.
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE register.

Arg #1bit

Arg #2
bit

0
0
1
1

0
1
0
1

New
Arg #2bit
1
00
1

7.3.1.24. CALL “CBL_FLUSH_FILE” USING file-handle
In Micro Focus COBOL, CALLing this subroutine flushes any as-yet unwritten memory buffers for the (output) filewhose file-handle is specified as the argument to disk.
This routine is non-functional in OpenCOBOL. It exists only to provide compatibility for applications that may havebeen developed for Micro Focus COBOL.

7.3.1.25. CALL “CBL_GET_CURRENT_DIR” USING BY VALUE 0, BY VALUE
length, BY REFERENCE bufferThis retrieves the fully-qualified pathname of the current directory, saving up to length characters of that name into
the specified buffer.
The first argument is unused, but must be specified. It must be specified BY VALUE.
The length argument must be specified BY VALUE.
The buffer argument must be specified BY REFERENCE.
The value specified for the length argument (a numeric literal or data item) should not exceed the actual length of thebuffer argument.
If the value specified for the length argument is LESS THAN the actual length of the buffer argument, the current
directory path will be left-justified and space filled within the first length bytes of buffer – any bytes in buffer afterthat point will be unchanged.
If the routine is successful, a value of 0 will be returned to the RETURN-CODE register. If the routine failed because ofsta problem with an argument (such as a negative or 0 length), a RETURN-CODE value of 128 will result. Finally, if the 1argument value is anything but zero, the routine will fail with a 129 RETURN-CODE.
06FEB2009 Version

Page 7-22

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

7.3.1.26. CALL “CBL_IMP” USING item-1, item-2, BY VALUE byte-length
This subroutine performs a bit-by-bit “implies” test between the left-most 8*byte-length corresponding bits of item-1
and item-2, storing the resulting bit string into item-2.
Item-1 may be an alphanumeric literal or a data item. Item-2 must be a data item. The length of both item-1 anditem-2 must be at least 8*byte-length.
Byte-length may be a numeric literal or data item, and must be specified using BY VALUE.
The truth table shown to the right documents the “IMP” process.
Any bits in item-2 after the 8*byte-length point will be unaffected.

Arg #1bit

Arg #2
bit

0
0
1
1

0
1
0
1

A result of zero will be passed back in the RETURN-CODE register.

New
Arg #2bit
1
1
0
1

7.3.1.27. CALL “CBL_NIMP” USING item-1, item-2, BY VALUE byte-length
This subroutine performs the negation of a bit-by-bit “implies” test between the left-most 8*byte-length
corresponding bits of item-1 and item-2, storing the resulting bit string into item-2.
Item-1 may be an alphanumeric literal or a data item. Item-2 must be a data item. The length of both item-1 anditem-2 must be at least 8*byte-length.
Byte-length may be a numeric literal or data item, and must be specified using BY VALUE.
The truth table shown to the right documents the “NIMP” process.
Any bits in item-2 after the 8*byte-length point will be unaffected.

Arg #1bit

Arg #2
bit

0
0
1
1

0
1
0
1

A result of zero will be passed back in the RETURN-CODE register.

New
Arg #2bit
00
1
0

7.3.1.28. CALL “CBL_NOR” USING item-1, item-2, BY VALUE byte-length
This subroutine performs the negation of a bit-by-bit “OR” test between the left-most 8*byte-length corresponding
bits of item-1 and item-2, storing the resulting bit string into item-2.
Item-1 may be an alphanumeric literal or a data item. Item-2 must be a data item. The length of both item-1 anditem-2 must be at least 8*byte-length.
Byte-length may be a numeric literal or data item, and must be specified using BY VALUE.
The truth table shown to the right documents the “NOR” process.
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE register.

06FEB2009 Version

Arg #1bit

Arg #2
bit

0
0
1
1

0
1
0
1

New
Arg #2bit
1
0
0
0Page 7-23

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

7.3.1.29. CALL “CBL_NOT” USING item-1, BY VALUE byte-length
This subroutine “flips” the left-most 8*byte-length bits of item-2, storing the resulting bit string into item-2.
Item-2 must be a data item. The length of item-2 must be at least 8*byte-length.
Byte-length may be a numeric literal or data item, and must be specified using BY VALUE.
The truth table shown to the right documents the “NOT” process.
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE register.

Old
Arg #2
bit
0
1

New
Arg #2bit
1
0

7.3.1.30. CALL “CBL_OC_NANOSLEEP” USING nanoseconds-to-sleep
CB_OC_NANOSLEEP puts the program to sleep for the specified number of nanoseconds.
The nanoseconds-to-sleep argument is a numeric literal or data item.
There are one BILLION nanoseconds in a second, so if you wanted to put the program to sleep for 1/4 second you'duse a nanoseconds-to-sleep value of 250000000.
Also see C$SLEEP – section 7.3.1.9.

7.3.1.31. CALL “CBL_OPEN_FILE” file-path, access-mode, 0, 0, handle.This routine opens an existing file for use as a byte-stream file usable by CBL_WRITE_FILE or CBL_READ_FILE.
The file-path argument is an alphanumeric literal or data-item.
The access-mode argument is a numeric literal or data item with a PIC X USAGE COMP-X (or USAGE BINARY-CHAR)
definition; it specifies how you wish to use the file, as follows:
1 = input (read-only)
2 = output (write-only)
3 = input and/or output
The third and fourth arguments would specify a locking mode and device specification, respectively, but they’re not
implemented in OpenCOBOL (currently, at least) – just specify each as 0.
The final argument – handle - is a PIC X(4) USAGE COMP-X item that will receive the handle to the file. That handle isused on all other byte-stream functions to reference this specific file.
A RETURN-CODE value of -1 indicates an invalid argument, while a value of 0 indicates success. A value of 35 means
the file does not exist.
Also see CBL_CREATE_FILE – section 7.3.1.18.

7.3.1.32. CALL “CBL_OR” USING item-1, item-2, BY VALUE byte-length
This subroutine performs a bit-by-bit “OR” test between the left-most 8*byte-length corresponding bits of item-1 anditem-2, storing the resulting bit string into item-2.
Item-1 may be an alphanumeric literal or a data item. Item-2 must be a data item. The length of both item-1 anditem-2 must be at least 8*byte-length.
Byte-length may be a numeric literal or data item, and must be specified using BY VALUE.
The truth table shown below documents the “OR” process.

06FEB2009 Version

Page 7-24

OpenCOBOL 1.1 Programmers Guide
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE register.

The OpenCOBOL System Interface
Arg #1bit

Arg #2
bit

0
0
1
1

0
1
0
1

New
Arg #2bit
0
1
1
1

7.3.1.33. CALL “CBL_READ_FILE” USING handle, offset, nbytes, flag, bufferThis routine reads nbytes of data starting at byte number offset from the byte-stream file defined by handle into thespecified buffer.
The handle argument (PIC X(4) USAGE COMP-X) must have been populated by a prior call to CBL_OPEN_FILE.
The offset argument (PIC X(8) USAGE COMP-X) defines the location in the file of the first byte to be read. The first
byte of a file is byte offset 0.
The nbytes argument (PIC X(4) USAGE COMP-X) specifies how many bytes (maximum) will be read.
If the flags argument is specified as 128, the size of the file (in bytes) will be returned into the file offset argument
44(argument 2) upon completion. The only other valid value for flags is 0. This argument may be specified either as anumeric literal or as a PIC X USAGE COMP-X data item.
Upon completion, RETURN-CODE will be set to 0 if the read was successful or to 10 if an “end-of-file” condition
occurred. If RETURN-CODE has a value of -1, a problem was identified with the subroutine arguments.

7.3.1.34. CALL “CBL_RENAME_FILE” USING old-file-path, new-file-path
You may use this subroutine to rename a file.
The file specified by old-file-path will be “renamed” to the name specified as new-file-path. Each argument may be analphanumeric literal or data item.
Despite what the name of this routine might make you believe, this routine is more than just a simple “rename” – itstndwill actually move the file supplied as the 1 argument to the file specified as the 2 argument. Think of it as a twostep sequence, first copying the old-file-path to the new-file-path and then a second step where the old-file-path isdeleted.
If the attempt to move the file fails (for example, it doesn't exist), RETURN-CODE will be set to 128; on successful
completion it will be set to 0.

7.3.1.35. CALL “CBL_TOLOWER” USING data-item, BY VALUE convert-length
This routine will converts convert-length (a numeric literal or data item) leading characters of data-item (analphanumeric identifier) to lower-case.
The convert-length argument must be specified BY VALUE. It specifies how many (leading) characters in data-item will
be converted – any characters after that will remain unchanged.
If convert-length is negative or zero, no conversion will be performed.
Also see C$TOLOWER – section 7.3.1.10.

44

Not all operating system/OpenCOBOL environments may be able to retrieve file sizes – in such cases, a value ofzero will be returned.

06FEB2009 Version

Page 7-25

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

7.3.1.36. CALL “CBL_TOUPPER” USING data-item, BY VALUE convert-length
Use C$TOUPPER to change the convert-length (a numeric literal or data item) leading characters of data-item (analphanumeric identifier) to upper-case.
The convert-length argument must be specified BY VALUE. It specifies how many (leading) characters in data-item will
be converted – any characters after that will remain unchanged.
If convert-length is negative or zero, no conversion will be performed.
Also see C$TOUPPER – section 7.3.1.11.

7.3.1.37. CALL “CBL_WRITE_FILE” USING handle, offset, nbytes, 0, bufferThis routine writes nbytes of data from the specified buffer to the byte-stream file defined by handle starting at byte
number offset.
The handle argument (PIC X(4) USAGE COMP-X) must have been populated by a prior call to CBL_OPEN_FILE.
The offset argument (PIC X(8) USAGE COMP-X) defines the location in the file of the first byte to be written to. The
first byte of a file is byte offset 0.
The nbytes argument (PIC X(4) USAGE COMP-X) specifies how many bytes (maximum) will be written.
The only allowable value or the flags argument is 0. This argument may be specified either as a numeric literal or as a
PIC X USAGE COMP-X data item.
Upon completion, RETURN-CODE will be set to 0 if the write was successful or to 30 if an I/O error condition occurred.
If RETURN-CODE has a value of -1, a problem was identified with the subroutine arguments.

7.3.1.38. CALL “CBL_XOR” USING item-1, item-2, BY VALUE byte-length
This subroutine performs a bit-by-bit exclusive “OR” test between the left-most 8*byte-length corresponding bits of
item-1 and item-2, storing the resulting bit string into item-2.
Item-1 may be an alphanumeric literal or a data item. Item-2 must be a data item. The length of both item-1 anditem-2 must be at least 8*byte-length.
Byte-length may be a numeric literal or data item, and must be specified using BY VALUE.
The truth table shown to the right documents the “XOR” process.
Any bits in item-2 after the 8*byte-length point will be unaffected.
A result of zero will be passed back in the RETURN-CODE register.

Arg #1bit

Arg #2
bit

0
0
1
1

0
1
0
1

New
Arg #2bit
01
1
0

7.3.1.39. CALL “SYSTEM” USING command
This subroutine submits the specified command (an alphanumeric literal or data item) to a command shell.
A shell will be opened subordinate to the OpenCOBOL program issuing the CALL to SYSTEM.
Output from the command (if any) will appear in the command window in which the OpenCOBOL program was
executed.
On a Unix system, the shell environment will be established using the default shell program. This is also true whenusing an OpenCOBOL build created with and for the Cygwin Unix emulator.
With native Windows Windows/MinGW builds, the shell environment will be the Windows console window commandprocessor (usually “cmd.exe”) appropriate for the version of Windows you’re using.
06FEB2009 Version

Page 7-26

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

To trap output from the executed command and process it within the OpenCOBOL program, use a pipe (>) to send thecommand output to a temporary file which you then READ from within the program once control returns.

7.3.2. “Call by Number” Subroutines
Early versions of Micro Focus COBOL allowed programmers to access various runtime library routines by using a single
two-digit hexadecimal number as the entry=point name. These were known as call-by-number routines. Over time,
Micro Focus COBOL evolved, replacing most of the call-by-number routines with ones accessible using a moreconventional call-by-name technique.
Most of the call-by-number routines have evolved into even more powerful call-by-name routines, many of which aresupported by OpenCOBOL and were already presented in section 7.3
Three of the original call-by-number routines never evolved call-by-name equivalents; OpenCOBOL supports theseroutines.

7.3.2.1. CALL X”91” USING return-code, function-code, binary-variable-arg
The original Micro Focus version of this routine is capable of providing a wide variety of functions – OpenCOBOL
supports just three of those functions:
Turning runtime switches (SWITCH-1, … , SWITCH-8) on
Turning runtime switches (SWITCH-1, … , SWITCH-8) off
45
Retrieving the number of arguments passed to a subroutine
The return-code argument must be a binary numeric data item (USAGE BINARY-CHAR is recommended). It will receivea value of 0 if the operation was successful, 1 otherwise.
The function code argument must be either a numeric literal or a binary numeric data item (USAGE BINARY-CHAR is
recommended).
The third argument – variable-arg – is defined differently depending upon the function-code value, as follows:
Value offunction-code

11

12

16

Action To Be Performed

Definition and usage of variable-arg

Sets and/or clears all eight of the
COBOL switches (SWITCH-1 through
SWITCH-8) that are available fordefinition within SPECIAL-NAMES
46(see section 4.1.4)

Variable-arg should be an OCCURS 8 TIMES array of USAGE
BINARY-CHAR.

Reads all eight of the COBOL
switches (SWITCH-1 through
SWITCH-8) that are available fordefinition within SPECIAL-NAMES(see section 4.1.4)
Retrieves the number of arguments
passed to the program executing
the CALL X”91”

Each occurrence that is set to a value of zero prior to the
CALL will cause the corresponding switch to be cleared.
Each occurrence set to 1 prior to the CALL will cause thecorresponding switch to be set.
Values other than 0 or 1 will be ignored.
This argument should be an OCCURS 8 TIMES array of
USAGE BINARY-CHAR.
st

Each of the 1 eight occurrences of the array will be set toeither 0 or 1 – 1 if the corresponding switch is set, 0
otherwise.
This argument should be a binary numeric data item (USAGE
BINARY-CHAR is recommended).
The number of arguments passed to the subroutine
executing the CALL X”91” will be stored here.

45

OpenCOBOL actually has two other ways to accomplish this task – the C$NARG subroutine (section 7.3.1.7) and the
NUMBER-OF-CALL-PARAMETERS special register (section 6.1.8); I recommend you use one of these methods
instead of the X”91” routine when coding new programs46

If you only wish to set and/or clear some of the switches, it is recommended that you first use function 12 to readthe current values of the switches and then change the variable-arg occurrences for the switch(es) you wish tochange before using function 11 to actually make the changes.

06FEB2009 Version

Page 7-27

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

7.3.2.2. CALL X”F4” USING byte, table
Routine X”F4” packs an 8-byte area containing 8 1-byte binary values of 0 or 1 into the corresponding bit positions of a
1-byte data item.
The byte data item need be only a single byte in size. If it is longer, the excess will be unaffected by this subroutine.
Table must be a data item at least 8 bytes long. If it is longer, the excess will be ignored by this subroutine. Typically,table is defined similarly to the following:
01

table.
05 each-byte OCCURS 8 TIMES USAGE BINARY-CHAR.

The following diagram illustrates how this subroutine works.

each-byte (1) each-byte (2) each-byte (3) each-byte (4) each-byte (5) each-byte (6) each-byte (7) each-byte (8)

byte
st

The colored squares represent the bits in the 1 8 bytes of array that will be packed into byte. The white squares
represent the bits in each each-byte that will be ignored.

7.3.2.3. CALL X”F5” USING byte, table
This routine unpacks each bit of a byte into an 8-byte area so they may be individually accessed and manipulated.
The byte data item need be only a single byte in size. If it is longer, the excess will be ignored by this subroutine.
Table must be a data item at least 8 bytes long. If it is longer, the excess will be unaffected by this subroutine.
Typically, table is defined similarly to the following:
01

table.
05 each-byte OCCURS 8 TIMES USAGE BINARY-CHAR.

The following diagram illustrates how this subroutine works.

each-byte (1) each-byte (2) each-byte (3) each-byte (4) each-byte (5) each-byte (6) each-byte (7) each-byte (8)byte
The colored squares represent each of the 8 bits in byte. The diagram shows how those bits will be “unpacked” intostthe rightmost bit of each of the 1 8 consecutive bytes of array. The white squares represent the remaining bits insteach of the 1 8 each-byte occurrences – all of which will be set to 0.

06FEB2009 Version

Page 7-28

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

7.3.2.4. Binary Truncation
By default, the OpenCOBOL compiler willtruncate binary data items to the precisionindicated by their PICTURE clause. For
example, the following data item will have 2
bytes of storage allocated for it:
01

Comp-5-Item

Figure 7-6 - A Binary Truncation Demo Program

PIC 9(3) COMP-5.

Because of truncation, even though this field
has enough bits allocated (16) to store values
from 0 to 65535, it will be limited to values of 0
to 999 because of its PICTURE.
Or is it?
Take a look at the small demo program shown
here. This program will perform three different
types of operations against a binary field,
displaying the results of each.
Here are the results when the program iscompiled (with truncation in-effect by default)
and executed:

Bin-Item-1=760 Disp-Item-1=032760
Bin-Item-1=765 Disp-Item-1=032765
Bin-Item-1=767 Disp-Item-1=032767
You can see that truncation affected the
DISPLAY statements but appears to have had
no impact whatsoever on the MOVE and ADD
statements. This is the hidden secret about
truncation in OpenCOBOL: it doesn’t reallytruncate the internally-stored values – it justtruncates the DISPLAY of them!

IDENTIFICATION DIVISION.
PROGRAM-ID. DEMOTRUNC.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Bin-Item-1

PIC 9(3)COMP-5VALUE 32760.
PIC 9(6).

01 Disp-Item-1
PROCEDURE DIVISION.
000-Main.
MOVE Bin-Item-1 TO Disp-Item-1
DISPLAY'Bin-Item-1=' Bin-Item-1' Disp-Item-1=' Disp-Item-1
END-DISPLAY
ADD 5
TO Bin-Item-1
MOVE Bin-Item-1 TO Disp-Item-1
DISPLAY'Bin-Item-1=' Bin-Item-1' Disp-Item-1=' Disp-Item-1
END-DISPLAY
MOVE 32767
TO Bin-Item-1
MOVE Bin-Item-1 TO Disp-Item-1
DISPLAY'Bin-Item-1=' Bin-Item-1' Disp-Item-1=' Disp-Item-1
END-DISPLAY
STOP RUN.

If that same program is recompiled without truncation (by adding the “ -fnotrunc” switch to the ‘cobc’ command),the results are as follows:
If this was all there was to the binary truncation issue it
wouldn’t be worth a section in this document. The fact is,however, that binary truncation has a significant effect on theperformance of OpenCOBOL programs. When binary
truncation is in effect, arithmetic operations performed
against all types of numeric data items (even USAGE DISPLAY) are slowed down.

Bin-Item-1=32760 Disp-Item-1=032760
Bin-Item-1=32765 Disp-Item-1=032765
Bin-Item-1=32767 Disp-Item-1=032767

Before continuing, it’s worth making the point that we’re NOT talking about astronomical performance degradations
here. Today’s computers are FAST, and a user sitting at the keyboard, running an OpenCOBOL program is unlikely to
notice. BUT … if you have an OpenCOBOL program that has to process large amounts of data, performing somesignificant “number crunching” against that data as it goes, the impact of truncation could become noticeable.

06FEB2009 Version

Page 7-29

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

The demo program shown in Figure 7-7 compares the performance of performing arithmetic operations (in a totally47
non-scientific, non-rigorous way) against USAGE DISPLAY, COMP, COMP-5 and BINARY-xxx numeric data. It was
actually my intent when I first wrote the program to merely demonstrate the relative performance differences
between the first three types of numeric data storage, and it certainly met that objective.
Imagine my surprise, however, when I discovered that the use of “ -fnotrunc” also made a significant difference!
Here’s what the program does:
There are four numeric data items in the program – one USAGE DISPLAY, one USAGE COMP, one USAGE
COMP-5 and one USAGE BINARY-LONG. Since the program was run on a computer with an Intel-architecture
processor (actually it’s an AMD, but results are identical with Intel) I wanted to see just how much more
efficient COMP-5 was over COMP.
Each data item will have 7 added to it ten million times. You’ll see why shortly.
The time (to one-one-hundredth of a second) will be retrieved before and after each test and the difference
between the two will be DISPLAYed. This is why the computations were done so many times – it was to makesure the timing was “measurable” with only a 1/100 second “stopwatch”.
OpenCOBOL is retrieving wall-clock time, not actual CPU-used time, so other activities taking place on the computer
had to be kept to a minimum while the tests were running. I also ran the tests multiple times, just to make sure I had
consistent results (I did). Like I mentioned earlier – this is not a rigorous, scientific benchmark of numeric
performance; it’s just a quick-and-dirty comparison.
Figure 7-7 shows the program and the test results received when executing both with and without the “-fnotrunc”
switch.
Here are the conclusions I drew from running these tests many times (30). The timings shown are average times fromall tests:
With truncation ON:
USAGE COMP has a significant performance advantage over USAGE DISPLAY
USAGE COMP-5 has an even greater performance advantage over USAGE COMP, than COMP did over
DISPLAY
USAGE BINARY-LONG (and presumably the other BINARY-xxx USAGEs as well) perform identically (within themeasurement tolerances of the test) with COMP-5; this should be no surprise since COMP-5 and BINARY-xxx
both allocate data the same way
With truncation OFF:
There was a huge drop in both USAGE DISPLAY and USAGE COMP timings.
The relative performance advantage of USAGE COMP over USAGE DISPLAY is even larger with truncation off
than it was with it on.
USAGE COMP-5 and USAGE BINARY-xxx appear to be virtually unaffected by the truncation on/off status,
although there was a .01 second increase in average execution time of those tests without truncation overthose with truncation. Given the number of times I ran the tests, it’s obvious that something makes COMP5/BINARY-xxx run slower without truncation than with it; that difference, however, is so miniscule that I
48
discount it as being statistically irrelevant .
My final observation is that I see absolutely no reason whatsoever why the “ -fnotrunc” option shouldn’t be used on
all OpenCOBOL compilations.
If you want to squeeze every last bit of performance out of your OpenCOBOL programs, don’t forget to investigate thevarious “–O” (optimization) switches. Actually run programs using various optimization switches (or not) and compare

47

USAGE BINARY-xxx is supposed to store numeric data identically to USAGE COMP-5, but I felt it couldn’t hurt tocheck.

48

Remember – that’s a .01 second difference over TEN MILLION iterations!

06FEB2009 Version

Page 7-30

OpenCOBOL 1.1 Programmers Guide

The OpenCOBOL System Interface

execution times, don’t just compare the generated C code because sometimes the differences can’t be “seen” at the C
source-code level.
Figure 7-7 - A Non-Scientific Comparison of Numeric Data Item USAGE Performance

IDENTIFICATION DIVISION.
PROGRAM-ID. DEMOMATH.
DATA DIVISION.
WORKING-STORAGE SECTION.
USAGE DISPLAY:
01 Begin-Time.
USAGE COMP:
05 BT-HH
PIC 9(2).
USAGE COMP-5:
05 BT-MM
PIC 9(2).
USAGE BINARY:
05 BT-SS
PIC 9(2).
05 BT-HU
PIC 9(2).
01 Binary-Item
BINARY-LONG SIGNED VALUE 0.
01 Comp-Item
COMP
PIC S9(9) VALUE 0.
01 Comp-5-Item
COMP-5 PIC S9(9) VALUE 0.
01 Display-ItemDISPLAY PIC S9(9) VALUE 0.
01 End-Time.
05 ET-HH
PIC 9(2).
05 ET-MM
PIC 9(2).
USAGE DISPLAY:
05 ET-SS
PIC 9(2).
USAGE COMP:
05 ET-HU
PIC 9(2).
USAGE COMP-5:
78 Repeat-CountVALUE 10000000.
USAGE BINARY:
01 Time-Diff
PIC ZZ9.99.
PROCEDURE DIVISION.
010-Test-Usage-DISPLAY.
ACCEPT Begin-Time FROM TIME END-ACCEPTPERFORM Repeat-Count TIMES ADD 7 TO Display-Item END-PERFORMPERFORM 100-Determine-Time-Diff
DISPLAY 'USAGE DISPLAY: ' Time-Diff ' SECONDS' END-DISPLAY.
020-Test-Usage-COMP.
ACCEPT Begin-Time FROM TIME END-ACCEPTPERFORM Repeat-Count TIMES ADD 7 TO Comp-Item END-PERFORMPERFORM 100-Determine-Time-Diff
DISPLAY 'USAGE COMP:' Time-Diff ' SECONDS' END-DISPLAY.
030-Test-Usage-COMP-5.
ACCEPT Begin-Time FROM TIME END-ACCEPTPERFORM Repeat-Count TIMES ADD 7 TO Comp-5-Item END-PERFORMPERFORM 100-Determine-Time-Diff
DISPLAY 'USAGE COMP-5: ' Time-Diff ' SECONDS' END-DISPLAY.
040-Test-Usage-BINARY.
ACCEPT Begin-Time FROM TIME END-ACCEPTPERFORM Repeat-Count TIMES ADD 7 TO Binary-Item END-PERFORMPERFORM 100-Determine-Time-Diff
DISPLAY 'USAGE BINARY: ' Time-Diff ' SECONDS' END-DISPLAY.
099-Done.
STOP RUN.
100-Determine-Time-Diff.
ACCEPT End-Time FROM TIME END-ACCEPTCOMPUTE Time-Diff =( (ET-HH * 360000 + ET-MM * 6000 + ET-SS * 100 + ET-HU)- (BT-HH * 360000 + BT-MM * 6000 + BT-SS * 100 + BT-HU) )/ 100.

06FEB2009 Version

Results with truncation
turned on (the default)
6.49 SECONDS
2.81 SECONDS
0.04 SECONDS
0.04 SECONDS

Results with truncation
turned off (“-fnotrunc”
used on ‘cobc’)

0.69 SECONDS
0.06 SECONDS
0.05 SECONDS
0.05 SECONDS

Page 7-31

OpenCOBOL 1.1 Programmers Guide

06FEB2009 Version

The OpenCOBOL System Interface

Page 7-32

OpenCOBOL 1.1 Programmers Guide

Sample Programs

8. Sample Programs
8.1. FileStat-Msgs.cpy – File Status Values
This copybook contains an EVALUATE statement to translate the two-digit file status codes that may be generated byfile I/O statements.
The copybook assumes that the file status data item name is “STATUS” and the error message data item is named“MSG”. By using the COPY statement’s REPLACING clause, however, you may use the data names you wish, as
follows:
COPY FileStat-Msgs
REPLACING STATUS BY Input-File-StatusMSG
BY Error-Message.

Here’s the FileStat-Msgs.cpy copybook:
EVALUATE STATUS
WHEN 00 MOVE 'SUCCESS
WHEN 02 MOVE 'SUCCESS DUPLICATE
WHEN 04 MOVE 'SUCCESS INCOMPLETE
WHEN 05 MOVE 'SUCCESS OPTIONAL
WHEN 07 MOVE 'SUCCESS NO UNIT
WHEN 10 MOVE 'END OF FILE
WHEN 14 MOVE 'OUT OF KEY RANGE
WHEN 21 MOVE 'KEY INVALID
WHEN 22 MOVE 'KEY EXISTS
WHEN 23 MOVE 'KEY NOT EXISTS
WHEN 30 MOVE 'PERMANENT ERROR
WHEN 31 MOVE 'INCONSISTENT FILENAME
WHEN 34 MOVE 'BOUNDARY VIOLATION
WHEN 35 MOVE 'FILE NOT FOUND
WHEN 37 MOVE 'PERMISSION DENIED
WHEN 38 MOVE 'CLOSED WITH LOCK
WHEN 39 MOVE 'CONFLICT ATTRIBUTE
WHEN 41 MOVE 'ALREADY OPEN
WHEN 42 MOVE 'NOT OPEN
WHEN 43 MOVE 'READ NOT DONE
WHEN 44 MOVE 'RECORD OVERFLOW
WHEN 46 MOVE 'READ ERROR
WHEN 47 MOVE 'INPUT DENIED
WHEN 48 MOVE 'OUTPUT DENIED
WHEN 49 MOVE 'I/O DENIED
WHEN 51 MOVE 'RECORD LOCKED
WHEN 52 MOVE 'END-OF-PAGE
WHEN 57 MOVE 'I/O LINAGE
WHEN 61 MOVE 'FILE SHARING FAILURE
WHEN 91 MOVE 'FILE NOT AVAILABLE
END-EVALUATE.

' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG' TO MSG

8.2. COBDUMP – A Hex/Char Data Dump SubroutineThis next sample program is a useful little utility subroutine to produce a formatted hexadecimal and character dumpof the data area passed to it.
If you follow the OpenCOBOL forums, you’ve undoubtedly heard about the CBL_OC_DUMP subroutine that was thewinning entry in an OpenCOBOL programming contest. It’s a great tool for producing data dumps, and it’ll probably
be in the official OpenCOBOL distribution one of these days.
For now though, I’ll keep using my good ol’ “COBDUMP” routine. It’s been my travelling companion from COBOL job
to COBOL job since 1971. Here it is, all tuned up for OpenCOBOL, with new tires and a fresh coat of paint:
IDENTIFICATION DIVISION.
PROGRAM-ID.
COBDUMP.
******************************************************************* This is an OpenCOBOL subroutine that will generate a**** formatted Hex/Char dump of a storage area. To use this**** subroutine, simply CALL it as follows:******** CALL "COBDUMP" USING <data-item>****[ <length> ]******** If specified, the <length> argument specifies how many**** bytes of <data-item> are to be dumped. If absent, all of**** <data-item> will be dumped (i.e. LENGTH(<data-item>) will**

06FEB2009 Version

Page 8-1

OpenCOBOL 1.1 Programmers Guide

Sample Programs** be assumed for <length>).
******** >>> Note that the subroutine name MUST be specified in <<< **** >>> UPPERCASE<<< ******** The dump is generated to STDERR, so you may pipe it to a**** file when you execute your program using "2> file".
******** AUTHOR:GARY L. CUTLER****
CutlerGL@gmail.com******** NOTE:
The author has a sentimental attachment to****this subroutine - it's been around since 1971 ****and it's been converted to and run on 10 dif- ****ferent operating system/compiler environments ******** DATE-WRITTEN: October 14, 1971************************************************************************* DATE CHANGE DESCRIPTION**** ====== ==================================================== **** GC1071 Initial coding - Univac Dept. of Defense COBOL '68**** GC0577 Converted to Univac ASCII COBOL (ACOB) - COBOL '74**** GC1182 Converted to Univac UTS4000 COBOL - COBOL '74 w/****
SCREEN SECTION enhancements**** GC0883 Converted to Honeywell/Bull COBOL - COBOL '74**** GC0983 Converted to IBM VS COBOL - COBOL '74**** GC0887 Converted to IBM VS COBOL II - COBOL '85**** GC1294 Converted to Micro Focus COBOL V3.0 - COBOL '85 w/****
extensions**** GC0703 Converted to Unisys Universal Compiling System (UCS) ****COBOL (UCOB) - COBOL '85**** GC1204 Converted to Unisys Object COBOL (OCOB) - COBOL 2002 **** GC0609 Converted to OpenCOBOL 1.1 - COBOL '85 w/ some COBOL ****2002 features**** GC0410 Enhanced to make 2nd argument (buffer length)****
optional*******************************************************************ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY.
FUNCTION ALL INTRINSIC.
DATA DIVISION.
WORKING-STORAGE SECTION.
78 Undisplayable-Char-Symbol
VALUE X'F9'.
01 Addr-PointerUSAGE POINTER.
01 Addr-Number
REDEFINES Addr-PointerUSAGE BINARY-LONG.
01

Addr-Sub

USAGE BINARY-CHAR.

01

Addr-Value

USAGE BINARY-LONG.

01

Buffer-Length

USAGE BINARY-LONG.

01

Buffer-Sub

01

Hex-Digits
05 Hex-Digit

01
01

Left-Nibble
Nibble01

Output-Detail.
05 OD-Addr.
10 OD-Addr-Hex
05 FILLER
05 OD-Byte
05 FILLER
05 OD-Hex
10 OD-Hex-1
10 OD-Hex-2
10 FILLER
05 OD-ASCIICOMP-5 PIC 9(4).
VALUE '0123456789ABCDEF'.
OCCURS 16 TIMES PIC X(1).
COMP-5 PIC 9(1).
REDEFINES Left-Nibble
BINARY-CHAR.

OCCURS 8 TIMES PIC X.
PIC X(1).
PIC Z(3)9.
PIC X(1).
OCCURS 16 TIMES.
PIC X.
PIC X.
PIC X.
OCCURS 16 TIMESPIC X.

01

Output-Sub

01

Output-Header-1.
05 FILLER
PIC X(80) VALUE'<-Addr-> Byte ' &'<---------------- Hexadecimal ----------------> ' &'<---- Char ---->'.

06FEB2009 Version

COMP-5 PIC 9(2).

Page 8-2

OpenCOBOL 1.1 Programmers Guide01

Output-Header-2.
05 FILLER
PIC X(80) VALUE'======== ==== ' &'=============================================== ' &'================'.

01

PIC-XX.
05 FILLER
05 PIC-X
PIC-Halfword

01
01

PIC-X10.
05 FILLER
05 PIC-X8

01

Right-Nibble

PIC X VALUE LOW-VALUES.
PIC X.
REDEFINES PIC-XX
PIC 9(4) COMP-X.
PIC X(2).
PIC X(8).
COMP-5 PIC 9(1).

LINKAGE SECTION.
01 Buffer

PIC X ANY LENGTH.

01

USAGE BINARY-LONG.

Buffer-Len

Sample Programs

PROCEDURE DIVISION USING Buffer, OPTIONAL Buffer-Len.
000-COBDUMP.
IF NUMBER-OF-CALL-PARAMETERS = 1
MOVE LENGTH(Buffer) TO Buffer-Length
ELSE
MOVE Buffer-Len
TO Buffer-Length
END-IF
MOVE SPACES TO Output-Detail
SET Addr-Pointer TO ADDRESS OF Buffer
PERFORM 100-Generate-Address
MOVE 0 TO Output-Sub
DISPLAY
Output-Header-1 UPON SYSERR
END-DISPLAYDISPLAY
Output-Header-2 UPON SYSERR
END-DISPLAYPERFORM VARYING Buffer-Sub FROM 1 BY 1
UNTIL Buffer-Sub > Buffer-Length
ADD 1
TO Output-Sub
END-ADDIF Output-Sub = 1
MOVE Buffer-Sub TO OD-Byte
END-IF
MOVE Buffer (Buffer-Sub : 1) TO PIC-X
IF (PIC-X < ' ')OR (PIC-X > '~')MOVE Undisplayable-Char-Symbol
TO OD-ASCII (Output-Sub)
ELSE
MOVE PIC-X
TO OD-ASCII (Output-Sub)
END-IFDIVIDE PIC-Halfword BY 16
GIVING Left-Nibble
REMAINDER Right-Nibble
END-DIVIDEADD 1 TO Left-Nibble
Right-Nibble
END-ADD
MOVE Hex-Digit (Left-Nibble)
TO OD-Hex-1 (Output-Sub)
MOVE Hex-Digit (Right-Nibble)
TO OD-Hex-2 (Output-Sub)
IF Output-Sub = 16
DISPLAY
Output-Detail UPON SYSERR
END-DISPLAY
MOVE SPACES TO Output-Detail
MOVE 0 TO Output-Sub
SET Addr-Pointer UP BY 16
PERFORM 100-Generate-Address
END-IF
END-PERFORM
IF Output-Sub > 0
DISPLAY
Output-Detail UPON SYSERR
END-DISPLAY
END-IF

06FEB2009 Version

Page 8-3

OpenCOBOL 1.1 Programmers Guide

Sample Programs

EXIT PROGRAM.
100-Generate-Address.
MOVE 8 TO Addr-Sub
MOVE Addr-Number TO Addr-Value
MOVE ALL '0' TO OD-Addr
PERFORM WITH TEST BEFORE UNTIL Addr-Value = 0
DIVIDE Addr-Value BY 16
GIVING Addr-Value
REMAINDER Nibble
END-DIVIDEADD 1 TO Nibble
MOVE Hex-Digit (Nibble)
TO OD-Addr-Hex (Addr-Sub)
SUBTRACT 1 FROM Addr-Sub
END-PERFORM.

8.3. OCic – an OpenCOBOL Full-Screen Compiler Front-End
This is more than a mere demonstration program – it’s also a very practical utility! The “OCic” (OpenCOBOL
Interactive Compiler) is a TUI program that may be used to connect the “cobc” compiler into a text editing frameworkso that – by simply pressing a keystroke sequence while editing an OpenCOBOL program – you may trigger acompilation of that program. The program is well documented (IMHO) and you should find it fairly easy to follow.
The OCic.cbl was written to work with a native Windows or Windows/MinGW build of OpenCOBOL as well as aWindows/Cygwin or UNIX build – I suspect it’ll work for MacOS, since that OS is actually a derivative of Linux, but suchcompatibility is untested.
An advantage to using OCic to compile your programs is its ability to generate source and/or cross-reference listings ofyour programs.
Source listings generated by OCic will show the original source code of your programs, with all indentation andcomments preserved. Additionally, any COPYed code will be included in the listing immediately following the COPY
statement that triggered its inclusion into your program.
Cross-reference listings will show all user-defined data items and procedures as well as intrinsic function and special
register references. In addition to showing the line numbers at which items were defined and referenced, thosereferences that MODIFY the contents of the data item will have an asterisk appended to them.
IDENTIFICATION DIVISION.
PROGRAM-ID. OCic.
******************************************************************* This program provides a Textual User Interface (TUI) to the **** process of compiling and (optionally) executing an OpenCOBOL**** program.
******** This programs execution syntax is as follows:******** ocic <program-path-and-filename> [ <switch>... ]******** Once executed, a display screen will be presented showing**** the compilation options that will be used. The user will**** have the opportunity to change options, specify new ones**** and specify any program execution arguments to be used if**** you select the "Execute" option. When you press the Enter **** key the program will be compiled.
******** The SCREEN SECTION contains an image of the screen.
******** The "010-Parse-Args" section in the PROCEDURE DIVISION has **** documentation on switches and their function.
************************************************************************* AUTHOR:GARY L. CUTLER****
CutlerGL@gmail.com****
Copyright (C) 2009-2010, Gary L. Cutler, GPL ******** DATE-WRITTEN: June 14, 2009************************************************************************* Note: Depending on which extended DISPLAY handler you're****using (PDCurses, Curses, ...), you may need to un****comment any source lines tagged with "SCROLL" in cols ****1-6 in order to have error messages scroll properly****in the OCic shell window.
********************************************************************* DATE CHANGE DESCRIPTION**

06FEB2009 Version

Page 8-4

OpenCOBOL 1.1 Programmers Guide

Sample Programs** ====== ==================================================== **** GC0609 Don't display compiler messages file if compilation ****Is successful. Also don't display messages if the****output file is busy (just put a message on the****screen, leave the OC screen up & let the user fix****
the problem & resubmit.
**** GC0709 When 'EXECUTE' is selected, a 'FILE BUSY' error will ****still cause the (old) executable to be launched.
****
Also, the 'EXTRA SWITCHES' field is being ignored.
****
Changed the title bar to lowlighted reverse video & ****the message area to highlighted reverse-video.
**** GC0809 Add a SPACE in from of command-line args when****
executing users program. Add a SPACE after the****-ftraceall switch when building cobc command.
**** GC0909 Convert to work on Cygwin/Linux as well as MinGW**** GC0310 Virtualized the key codes for S-F1 thru S-F7 as they ****differ depending upon whether PDCurses or NCurses is ****being used.
**** GC0410 Introduced the cross-reference and source listing****
features. Also fixed a bug in @EXTRA switch proces- ****sing where garbage will result if more than the****@EXTRA switch is specified.
*******************************************************************ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY.
FUNCTION ALL INTRINSIC.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT Bat-FileASSIGN TO Bat-File-Name
ORGANIZATION IS LINE SEQUENTIAL.
SELECT Cobc-Output

ASSIGN TO Cobc-Output-File
ORGANIZATION IS LINE SEQUENTIAL.

SELECT Source-CodeASSIGN TO File-Name
ORGANIZATION IS LINE SEQUENTIAL
FILE STATUS IS FSM-Status.

DATA DIVISION.
FILE SECTION.
FD Bat-File.
01 Bat-File-Rec

PIC X(2048).

FD
01

Cobc-Output.
Cobc-Output-Rec

PIC X(256).

FD
01

Source-Code.
Source-Code-Record

PIC X(80).

WORKING-STORAGE SECTION.
COPY screenio.
01

Bat-File-Name

PIC X(256).

Cmd

PIC X(512).

01

Cobc-Cmd

PIC X(256).

01

Cobc-Output-File

PIC X(256).

01

Command-Line-Args

PIC X(256).

01

Config-File

PIC X(12).

GC0310 01
GC0310
GC0310
GC0310
GC0310
GC0310
GC0310
GC0310Config-Keys.
05 CK-S-F1
05 CK-S-F2
05 CK-S-F3
05 CK-S-F4
05 CK-S-F5
05 CK-S-F6
05 CK-S-F7

PIC 9(4).
PIC 9(4).
PIC 9(4).
PIC 9(4).
PIC 9(4).
PIC 9(4).
PIC 9(4).

GC0909 01

Dir-Char

PIC X(1).

01

Dummy

PIC X(1).

01

Env-TEMPPIC X(256).

01

File-Name.
05 FN-Char

OCCURS 256 TIMES PIC X(1).

01

File-Status-Message.
05 FILLER

PIC X(13) VALUE 'Status Code: '.

GC0909 01

06FEB2009 Version

Page 8-5

OpenCOBOL 1.1 Programmers Guide
05 FSM-Status
05 FILLER
05 FSM-Msg
01
GC0909GC0609GC0609GC0609GC0809GC0809GC0809GC0709GC0709GC0709GC0809GC0809GC0809GC0809GC0909 01
GC090901

PIC 9(2).
PIC X(11) VALUE ', Meaning: '.
PIC X(25).

Flags.
05 F-Compilation-Succeeded PIC X(1).
88 88-Compile-OK
VALUE 'Y'.
88 88-Compile-OK-Warn
VALUE 'W'.
88 88-Compile-Failed
VALUE 'N'.
05 F-Complete
PIC X(1).
88 88-Complete
VALUE 'Y'.
88 88-Not-Complete
VALUE 'N'.
05 F-IDENT-DIVISIONPIC X(1).
88 88-1st-Prog-Complete VALUE 'Y'.
88 88-More-To-1st-Prog
VALUE 'N'.
05 F-LINKAGE-SECTIONPIC X(1).
88 88-Compile-As-Subpgm VALUE 'Y'.
88 88-Compile-As-Mainpgm VALUE 'N'.
05 F-No-Switch-Changes
PIC X(1).
88 88-No-Switch-Changes VALUE 'Y'.
88 88-Switch-Changes
VALUE 'N'.
05 F-Output-File-Busy
PIC X(1).
88 88-Output-File-Busy
VALUE 'Y'.
88 88-Output-File-Avail VALUE 'N'.
05 F-Source-Record-TypePIC X(1).
88 88-Source-Rec-Linkage VALUE 'L'.
88 88-Source-Rec-Ident
VALUE 'I'.
88 88-Source-Rec-IgnoCOB-COLOR-RED VALUE ' '.
05 F-Switch-Error
PIC X(1).
88 88-Switch-Is-Bad
VALUE 'Y'.
88 88-Switch-Is-Good
VALUE 'N'.
Horizontal-Line

PIC X(80).

I

USAGE BINARY-LONG.

01

J

USAGE BINARY-LONG.

GC0909 01

MS

USAGE BINARY-LONG.

GC0909 01

ML

USAGE BINARY-LONG.

OC-Compiled

PIC XXXX/XX/XXBXX/XX.

GC0909 01
GC0909GC0909GC0909GC0909OS-Type
88 OS-Unknown
88 OS-Windows
88 OS-Cygwin
88 OS-UNIX

USAGE BINARY-LONG.
VALUE 0.
VALUE 1.
VALUE 2.
VALUE 3.

GC0909 01

OS-Type-Literal

PIC X(7).

01Output-Message

PIC X(80).

01Path-Delimiter

PIC X(1).

01

Prog-Folder

PIC X(256).

01

Prog-Extension

PIC X(30).

01

Prog-File-Name

PIC X(40).

01

Prog-NamePIC X(31).

78

Selection-Char

VALUE '>'.

01

Switch-Display.
05 SD-Switch-And-Value
05 FILLER
05 SD-Description

PIC X(19).
PIC X(1).
PIC X(60).

0101

Switch-Keyword
88 Switch-Is-CONFIG
88 Switch-Is-DEBUG
88 Switch-Is-DLL
88 Switch-Is-EXECUTE
88 Switch-Is-EXTRA
88 Switch-Is-NOTRUNC
88 Switch-Is-TRACE
88 Switch-Is-SOURCE
88 Switch-Is-XREF

01

Switch-Keyword-And-Value

GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410Sample Programs

06FEB2009 Version

PIC X(12).
VALUE '@CONFIG', '@C'.
VALUE '@DEBUG', '@D'.
VALUE '@DLL'.
VALUE '@EXECUTE', '@E'.
VALUE '@EXTRA', '@EX'.
VALUE '@NOTRUNC', '@N'.
VALUE '@TRACE', '@T'.
VALUE '@SOURCE', '@S'.
VALUE '@XREF', '@X'.
PIC X(256).

Page 8-6

OpenCOBOL 1.1 Programmers Guide
01
01

Switch-Value.
05 SV-1
05 FILLER
Switch-Value-Alt

Sample Programs

PIC X(1).
PIC X(255).
REDEFINES Switch-ValuePIC X(256).

88 Valid-Config-Filename
VALUE 'BS2000', 'COBOL85', 'COBOL2002', 'DEFAULT','IBM','MF','MVS'.
01

GC0410
GC041001

Switches.
05 S-ARGS
05 S-CfgS.
10 S-Cfg-BS2000
10 S-Cfg-COBOL85
10 S-Cfg-COBOL2002
10 S-Cfg-DEFAULT
10 S-Cfg-IBM
10 S-Cfg-MF
10 S-Cfg-MVS
05 S-EXTRA
05 S-Yes-No-Switches.
10 S-DEBUG
10 S-DLL
10 S-XREF
10 S-SOURCE
10 S-EXECUTE
10 S-NOTRUNC
10 S-SUBROUTINE
10 S-TRACE
10 S-TRACEALL
Tally

PIC X(75) VALUE SPACES.
PIC X(1) VALUE ' '.
PIC X(1) VALUE ' '.
PIC X(1) VALUE ' '.
PIC X(1) VALUE Selection-Char.
PIC X(1) VALUE ' '.
PIC X(1) VALUE ' '.
PIC X(1) VALUE ' '.
PIC X(75) VALUE SPACES.
PIC X(1)PIC X(1)PIC X(1)PIC X(1)PIC X(1)PIC X(1)PIC X(1)PIC X(1)PIC X(1)

VALUE 'N'.
VALUE 'N'.
VALUE 'N'.
VALUE 'N'.
VALUE 'N'.
VALUE 'Y'.
VALUE 'A'.
VALUE 'N'.
VALUE 'N'.

USAGE BINARY-LONG.

SCREEN SECTION.
*>*> Here is the layout of the OCic screen.
*>*> Note that this program can utilize the traditional PC line-drawing characters,*> if they are available.
*>*> If this program is run on Windows, it must run with codepage 437 activated to*> display the line-drawing characters. With a native Windows build or a*> Windows/MinGW build, one could use the command "chcp 437" to set that codepage*> for display within a Windows console window (that should be the default, though).
*> With a Windows/Cygwin build, set the environment variable CYGWIN to a value of*> "codepage:oem" (this cannot be done from within the program though - you will*> have to use the "Computer/Advanced System Settings/Environment Variables" (Vista or*> Windows 7) function to define the variable. XP Users: use "My Computer/Properties/*> Advanced/Environment Variables".
*>*> To use OCic without the line-drawing characters, comment-out the first set of*> 78 "LD" items and uncomment the second.
*>*> The following sample screen layout shows how the screen looks with line-drawing*> characters disabled.
*>*>===================================================================================*> OCic (2010/04/02 11:36) - OpenCOBOL V1.1 Interactive Compilation
Windows 01*> +-----------------------------------------------------------------------------+ 02*> | Program: OCic
F-Key: Select Opt | 03*> | Folder:
E:\OpenCOBOL\Samples
Enter: Compile| 04*> | Filename: OCic.cbl
Esc:
Quit
| 05
*> +-----------------------------------------------------------------------------+ 06*>
On/Off Switches:
Configuration:07*> +---------------------------------------------------------+-------------------+ 08*> | F1
Compile debug lines
F8
Produce source listing | S-F1
BS2000| 09*> | F2
Always make DLLs
F9
Produce xref listing| S-F2COBOL85| 10*> | F3
Pgm is a SUBROUTINE| S-F3COBOL2002 | 11*> | F4
Execute if compile OK| S-F4 > Default| 12*> | F5 > No COMP/BINARY trunc| S-F5IBM| 13*> | F6
Trace procedures| S-F6MicroFocus | 14*> | F7
Trace proc + stmnts| S-F7
MVS| 15*> +---------------------------------------------------------+-------------------+ 16*>
Additional "cobc" Switches (if any):17*> +-----------------------------------------------------------------------------+ 18*> | -O2________________________________________________________________________ | 19*> +-----------------------------------------------------------------------------+ 20*>
Program Execution Arguments (if any):21*> +-----------------------------------------------------------------------------+ 22*> | ___________________________________________________________________________ | 23*> +-----------------------------------------------------------------------------+ 24*> OCic Copyright (C) 2009-2010, Gary L. Cutler, GPL
25*>===================================================================================*>12345678901234567890123456789012345678901234567890123456789012345678901234567890

06FEB2009 Version

Page 8-7

OpenCOBOL 1.1 Programmers Guide

Sample Programs

*>
1
2
3
4
5
6
7
8
*>
*> USE THESE CHARS FOR LINE-DRAWING IF YOU HAVE ACCESS TO PC-DOS CODEPAGE 437:*>
78 LD-UL-Corner
VALUE X"DA".
78 LD-LL-Corner
VALUE X"C0".
78 LD-UR-Corner
VALUE X"BF".
78 LD-LR-Corner
VALUE X"D9".
78 LD-Upper-T
VALUE X"C2".
78 LD-Lower-T
VALUE X"C1".
78 LD-Horiz-Line
VALUE X"C4".
78 LD-Vert-Line
VALUE X"B3".
*>*> USE THESE CHARS FOR LINE-DRAWING IF YOU DO NOT HAVE ACCESS TO PC-DOS CODEPAGE 437:*>*> 78 LD-UL-Corner
VALUE '+'.
*> 78 LD-LL-Corner
VALUE '+'.
*> 78 LD-UR-Corner
VALUE '+'.
*> 78 LD-LR-Corner
VALUE '+'.
*> 78 LD-Upper-T
VALUE '+'.
*> 78 LD-Lower-T
VALUE '+'.
*> 78 LD-Horiz-Line
VALUE '-'.
*> 78 LD-Vert-Line
VALUE '|'.
*>
01 Blank-Screen LINE 1 COLUMN 1 BLANK SCREEN.
01 Switches-Screen BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-WHITE AUTO.
*>*> GENERAL SCREEN FRAMEWORK*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-BLUE HIGHLIGHT.
05 LINE 02 COL 02
VALUE LD-UL-Corner.
05
PIC X(77) FROM Horizontal-Line.
05
COL 80VALUE LD-UR-Corner.
05 LINE 03 COL 02
05
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 04 COL 02
05
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 05 COL 02
05
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 06 COL 02
VALUE LD-LL-Corner.
05
PIC X(77) FROM Horizontal-Line.
05
COL 80VALUE LD-LR-Corner.
05 LINE 08 COL 02
VALUE LD-UL-Corner.
05
PIC X(57) FROM Horizontal-Line.
05
COL 60VALUE LD-Upper-T.
05
PIC X(19) FROM Horizontal-Line.
05
COL 80VALUE LD-UR-Corner.
05 LINE 09 COL 02
05
COL 6005
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 10 COL 02
05
COL 6005
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 11 COL 02
05
COL 6005
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 12 COL 02
05
COL 6005
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 13 COL 02
05
COL 6005
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 14 COL 02
05
COL 6005
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 15 COL 02
05
COL 6005
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

06FEB2009 Version

Page 8-8

OpenCOBOL 1.1 Programmers Guide

Sample Programs05 LINE 16 COL 02
VALUE LD-LL-Corner.
05
PIC X(57) FROM Horizontal-Line.
05
COL 60VALUE LD-Lower-T.
05
PIC X(19) FROM Horizontal-Line.
05
COL 80VALUE LD-LR-Corner.
05 LINE 18 COL 02
VALUE LD-UL-Corner.
05
PIC X(77) FROM Horizontal-Line.
05
COL 80VALUE LD-UR-Corner.
05 LINE 19 COL 02
05
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 20 COL 02
VALUE LD-LL-Corner.
05
PIC X(77) FROM Horizontal-Line.
05
COL 80VALUE LD-LR-Corner.
05 LINE 22 COL 02
VALUE LD-UL-Corner.
05
PIC X(77) FROM Horizontal-Line.
05
COL 80VALUE LD-UR-Corner.
05 LINE 23 COL 02
05
COL 80VALUE LD-Vert-Line.
VALUE LD-Vert-Line.

05 LINE 24 COL 02
VALUE LD-LL-Corner.
05
PIC X(77) FROM Horizontal-Line.
05
COL 80VALUE LD-LR-Corner.
*>*> TOP AND BOTTOM LINES*>
03 BACKGROUND-COLOR COB-COLOR-BLUE BLINKFOREGROUND-COLOR COB-COLOR-WHITE HIGHLIGHT.
GC041005 LINE 01 COL 01 VALUE ' OCic ('.
GC041005
PIC X(16) FROM OC-Compiled.
GC041005
VALUE ') OpenCOBOL 1.1 06FEB2009 ' &GC0410'Interactive Compilation'.
GC041005 LINE 25 COL 01 PIC X(81) FROM Output-Message.
*>*> LABELS*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-CYAN HIGHLIGHT.
05 LINE 07 COL 04 VALUE 'On/Off Switches:'.
05
COL 62 VALUE 'Configuration:'.
05 LINE 17 COL 04 VALUE 'Additional "cobc" Switches (if any'):'.
05 LINE 21 COL 04 VALUE 'Program Execution Arguments (if an'y):'.
*>*> TOP SECTION BACKGROUND*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-CYAN LOWLIGHT.
05 LINE 03 COL 04 VALUE 'Program: '.
05 LINE 04 COL 04 VALUE 'Folder:'.
05 LINE 05 COL 04 VALUE 'Filename: '.
05 LINE 03 COL 62 VALUE 'F-Key: Select Opt'.
05 LINE 04 COL 62 VALUE 'Enter: Compile'.
05 LINE 05 COL 62 VALUE 'Esc:
Quit
'.
*>
*> TOP SECTION PROGRAM INFO*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-WHITE HIGHLIGHT.
05 LINE 03 COL 14 PIC X(47) FROM Prog-Name.
05 LINE 04 COL 14 PIC X(47) FROM Prog-Folder.
05 LINE 05 COL 14 PIC X(47) FROM Prog-File-Name.
*>*> MIDDLE LEFT SECTION F-KEYS*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-WHITE HIGHLIGHT.
05 LINE 09 COL 04 VALUE 'F1'.
05 LINE 10 COL 04 VALUE 'F2'.
05 LINE 11 COL 04 VALUE 'F3'.
05 LINE 12 COL 04 VALUE 'F4'.
05 LINE 13 COL 04 VALUE 'F5'.
05 LINE 14 COL 04 VALUE 'F6'.
05 LINE 15 COL 04 VALUE 'F7'.
05 LINE 09 COL 32 VALUE 'F8'.
05 LINE 10 COL 32 VALUE 'F9'.
*>*> MIDDLE LEFT SECTION SWITCHES

06FEB2009 Version

Page 8-9

OpenCOBOL 1.1 Programmers Guide

Sample Programs*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-RED
HIGHLIGHT.
05 LINE 09 COL 07 PIC X(1) FROM S-DEBUG.
05 LINE 10 COL 07 PIC X(1) FROM S-DLL.
05 LINE 11 COL 07 PIC X(1) FROM S-SUBROUTINE.
05 LINE 12 COL 07 PIC X(1) FROM S-EXECUTE.
05 LINE 13 COL 07 PIC X(1) FROM S-NOTRUNC.
05 LINE 14 COL 07 PIC X(1) FROM S-TRACE.
05 LINE 15 COL 07 PIC X(1) FROM S-TRACEALL.
05 LINE 09 COL 35 PIC X(1) FROM S-SOURCE.
05 LINE 10 COL 35 PIC X(1) FROM S-XREF.
*>*> MIDDLE LEFT SECTION BACKGROUND*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-CYAN LOWLIGHT.
05 LINE 09 COL 09 VALUE 'Compile debug lines'.
05 LINE 10 COL 09 VALUE 'Always make DLLs'.
05 LINE 11 COL 09 VALUE 'Pgm is a SUBROUTINE'.
05 LINE 12 COL 09 VALUE 'Execute if compile OK '.
05 LINE 13 COL 09 VALUE 'No COMP/BINARY trunc '.
05 LINE 14 COL 09 VALUE 'Trace procedures'.
05 LINE 15 COL 09 VALUE 'Trace proc + stmnts'.
05 LINE 09 COL 37 VALUE 'Produce source listing'.
05 LINE 10 COL 37 VALUE 'Produce xref listing '.
*>*> MIDDLE RIGHT SECTION F-KEYS*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-WHITE HIGHLIGHT.
05 LINE 09 COL 62 VALUE 'S-F1'.
05 LINE 10 COL 62 VALUE 'S-F2'.
05 LINE 11 COL 62 VALUE 'S-F3'.
05 LINE 12 COL 62 VALUE 'S-F4'.
05 LINE 13 COL 62 VALUE 'S-F5'.
05 LINE 14 COL 62 VALUE 'S-F6'.
05 LINE 15 COL 62 VALUE 'S-F7'.
*>*> MIDDLE RIGHT SECTION SWITCHES*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-RED HIGHLIGHT.
05 LINE 09 COL 67 PIC X(1) FROM S-Cfg-BS2000.
05 LINE 10 COL 67 PIC X(1) FROM S-Cfg-COBOL85.
05 LINE 11 COL 67 PIC X(1) FROM S-Cfg-COBOL2002.
05 LINE 12 COL 67 PIC X(1) FROM S-Cfg-DEFAULT.
05 LINE 13 COL 67 PIC X(1) FROM S-Cfg-IBM.
05 LINE 14 COL 67 PIC X(1) FROM S-Cfg-MF.
05 LINE 15 COL 67 PIC X(1) FROM S-Cfg-MVS.
*>*> MIDDLE RIGHT SECTION BACKGROUND*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-CYAN LOWLIGHT.
05 LINE 09 COL 69 VALUE 'BS2000'.
05 LINE 10 COL 69 VALUE 'COBOL85'.
05 LINE 11 COL 69 VALUE 'COBOL2002 '.
05 LINE 12 COL 69 VALUE 'Default'.
05 LINE 13 COL 69 VALUE 'IBM'.
05 LINE 14 COL 69 VALUE 'MicroFocus'.
05 LINE 15 COL 69 VALUE 'MVS'.
*>*> FREE-FORM OPTIONS FIELDS*>
03 BACKGROUND-COLOR COB-COLOR-BLACK
FOREGROUND-COLOR COB-COLOR-WHITE HIGHLIGHT.
05 LINE 19 COL 04 PIC X(75) USING S-EXTRA.
05 LINE 23 COL 04 PIC X(75) USING S-ARGS.
/PROCEDURE DIVISION.
******************************************************************* Legend to procedure names:******** 00x-xxx
All MAIN driver procedures**** 0xx-xxx
All GLOBAL UTILITY procedures**** 1xx-xxx
All INITIALIZATION procedures**** 2xx-xxx
All CORE PROCESSING procedures**** 9xx-xxx
All TERMINATION procedures*******************************************************************DECLARATIVES.
000-File-Error SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON Source-Code.
000-Handle-Error.

06FEB2009 Version

Page 8-10

OpenCOBOL 1.1 Programmers Guide/

Sample Programs

COPY FileStat-Msgs
REPLACING STATUS BY FSM-StatusMSG
BY FSM-Msg.
MOVE SPACES TO Output-Message
IF FSM-Status = 35
DISPLAY'File not found: "'TRIM(File-Name,TRAILING)'"'
END-DISPLAYELSEDISPLAY'Error accessing file: "'TRIM(File-Name,TRAILING)'"'
END-DISPLAY
END-IF
GOBACK.
END DECLARATIVES.
000-Main SECTION.

GC0609GC0609GC0609GC0609GC0410
GC0410
GC0410
GC0410GC0709GC0709GC0609GC0609GC0609PERFORM 100-Initialization
SET 88-Not-Complete TO TRUEPERFORM UNTIL 88-Complete
PERFORM 200-Let-User-Set-Switches
PERFORM 210-Run-Compiler
IF (88-Compile-OK OR 88-Compile-OK-Warn)
AND (S-XREF NOT = SPACE OR S-SOURCE NOT = SPACE)PERFORM 220-Make-Listing
END-IF
IF (S-EXECUTE NOT = SPACES)
AND (88-Output-File-Avail)
PERFORM 230-Run-Program
END-IF
END-PERFORM.

009-Done.
PERFORM 900-Terminate.
* -- Control will NOT return/
010-Parse-Args SECTION.
******************************************************************* Process a sequence of KEYWORD=VALUE items. These are items **** specified on the command-line to provide the initial**** options shown selected on the screen. When integrating**** OCic into an edirot or framework, include these switches on **** the ocic.exe command the editor/framework executes. Any**** underlined choice is the default value for that switch.
******** @CONFIG=BS2000|COBOL85|COBOL2002|DEFAULT|IBM|MF|MVS****=======**** This switch specifies the default cobc compiler configura- **** tion file to be used******** @DEBUG=YES|NO
**
**
==
**
** This switch specifies whether (YES) or not (NO) debugging**** lines (those with a "D" in column 7) will be compiled.
******** @DLL=YES|NO
**
**
==
**
** Use this switch to force ALL compiled programs to be built **** as DLLs ("@DLL=YES"). When main programs are built as DLLs **** they must be executed using the cobcrun utility. When**** "@DLL=NO" is in effect, main programs are generated as**** actual "exe" files and only subprograms will be generated**** as DLLs.
******** @EXECUTE=YES|NO
**
**
==
**
** This switch specifies whether ("@EXECUTE=YES") or not**** ("@EXECUTE=NO") the program will be executed after it is**** successfully compiled.
******** @EXTRA=extra cobc argument(s)******** This switch allows you to specify additional cobc arguments **** that aren't managed by the other OC switches. If used,**** this must be the last switch specified on the command line, **** as everything that follows the "=" will be placed on the**

06FEB2009 Version

Page 8-11

OpenCOBOL 1.1 Programmers Guide

Sample Programs** cobc command generated by OC.
******** @NOTRUNC=YES|NO
**
**
===
**
** This switch specifies whether (YES) or not (NO) the sup**** pression of binary field truncation will occur. If a PIC**** 99 COMP field (one byte of storage), for example, is given **** the value 123, it may have its value truncated to 23 when**** DISPLAYed. Regardless of the NOTRUNC setting, internally**** the full precision of the field (allowing a maximum value**** of 255) will be preserved. Even though truncation - if it **** does occur - would appear to have a minimal disruption on**** program operation, it has a significant effect on program**** run-time speed.
******** @TRACE=YES|NO|ALL
**
**
==
**
** This switch controls whether or not code will be added to**** the object program to produce execution-time logic traces. **** A specification of "@TRACE=NO" means no such code will be**** produced. By specifying "@TRACE=YES", code will be genera- **** ted to display procedure names as they are entered. A**** "@TRACE=ALL" specification will generate not only procedure **** traces (as "@TRACE=YES" would) but also statement-level**** traces too! All trace output is written to STDERR, so**** adding a "2>file" to the execution of the program will pipe **** the trace output to a file. You may find it valuable to**** add your own DISPLAY statements to the debugging output via **** "DISPLAY xx UPON SYSERR" The SYSERR device corresponds to **** the Windows or UNIX STDERR device and will therefore honor **** any "2>file" placed at the end of your program's execution. **** Add a "D" in column 7 and you can control the generation or **** ignoring of these DISPLAY statements via the "@DEBUG"**** switch.
******
GC0410** @SOURCE=YES|NO**
GC0410**==**
GC0410** Use this switch to produce a source listing of the program, **GC0410** PROVIDED it compiles without errors.
******
GC0410** @XREF=YES|NO**
GC0410**==**
GC0410** Use this switch to produce a cross-reference listing of the **GC0410** program, PROVIDED it compiles without errors.
*******************************************************************
011-Init.
MOVE 1 TO I.
012-Extract-Kwd-And-Value.
PERFORM UNTIL I NOT < LENGTH(Command-Line-Args)
MOVE I TO J
UNSTRING Command-Line-Args
DELIMITED BY ALL SPACES
INTO Switch-Keyword-And-Value
WITH POINTER I
END-UNSTRING
IF Switch-Keyword-And-Value NOT = SPACESUNSTRING Switch-Keyword-And-Value
DELIMITED BY '='INTO Switch-Keyword, Switch-ValueEND-UNSTRINGPERFORM 030-Process-Keyword
END-IF
END-PERFORM.
019-Done.
EXIT.
******************************************************************* Since this program uses the SCREEN SECTION, it cannot do**** conventional console DISPLAY operations. This routine**** (which, I admit, is like using an H-bomb to hunt rabbits)**** will submit an "ECHO" command to the system to simulate a**** DISPLAY.
*******************************************************************
021-Build-And-Issue-Command.
DISPLAY
Output-Message
END-DISPLAY.

06FEB2009 Version

Page 8-12

OpenCOBOL 1.1 Programmers Guide/

Sample Programs

029-Done.
EXIT.

030-Process-Keyword SECTION.
******************************************************************* Process a single KEYWORD=VALUE item.
*******************************************************************
031-Init.
MOVE UPPER-CASE(Switch-Keyword) TO Switch-Keyword
SET 88-Switch-Is-Good TO TRUE.
032-Process.
EVALUATE TRUE
WHEN Switch-Is-EXTRA
GC0410MOVE J TO I
UNSTRING Command-Line-Args DELIMITED BY '='INTO Dummy, S-EXTRA
GC0410
WITH POINTER I
GC0410END-UNSTRING
MOVE LENGTH(Command-Line-Args) TO I
WHEN Switch-Is-CONFIG
MOVE 'CONFIG' TO Switch-Keyword
MOVE UPPER-CASE(Switch-Value)
TO Switch-ValueEVALUATE Switch-Value
WHEN 'BS2000'
MOVE SPACES TO S-CfgS
MOVE Selection-Char
TO S-Cfg-BS2000
WHEN 'COBOL85'
MOVE SPACES TO S-CfgS
MOVE Selection-Char
TO S-Cfg-COBOL85
WHEN 'COBOL2002'
MOVE SPACES TO S-CfgS
MOVE Selection-Char
TO S-Cfg-COBOL2002
WHEN 'DEFAULT'MOVE SPACES TO S-CfgS
MOVE Selection-Char
TO S-Cfg-DEFAULT
WHEN 'IBM'
MOVE SPACES TO S-CfgS
MOVE Selection-Char
TO S-Cfg-IBM
WHEN 'MF'
MOVE SPACES TO S-CfgS
MOVE Selection-Char
TO S-Cfg-MF
WHEN 'MVS'
MOVE SPACES TO S-CfgS
MOVE Selection-Char
TO S-Cfg-MVS
WHEN OTHER
MOVE 'An invalid /CONFIG switch value ' &'was specified on the command line ' &'- ignored'
TO Output-Message
END-EVALUATE
WHEN Switch-Is-DEBUG
MOVE 'DEBUG' TO Switch-Keyword
MOVE UPPER-CASE(Switch-Value)
TO Switch-ValuePERFORM 040-Process-Yes-No-Value
IF 88-Switch-Is-Good
MOVE SV-1 TO S-DEBUG
END-IF
GC0410
WHEN Switch-Is-DLL
GC0410MOVE 'DLL' TO Switch-Keyword
GC0410MOVE UPPER-CASE(Switch-Value)
GC0410TO Switch-Value
GC0410PERFORM 040-Process-Yes-No-Value
GC0410IF 88-Switch-Is-Good
GC0410MOVE SV-1 TO S-DLL
GC0410END-IF
WHEN Switch-Is-EXECUTE
MOVE 'EXECUTE' TO Switch-Keyword
MOVE UPPER-CASE(Switch-Value)
TO Switch-ValuePERFORM 040-Process-Yes-No-Value
IF 88-Switch-Is-Good
MOVE SV-1 TO S-EXECUTE
END-IF
WHEN Switch-Is-NOTRUNCMOVE 'NOTRUNC' TO Switch-Keyword
MOVE UPPER-CASE(Switch-Value)
TO Switch-ValuePERFORM 040-Process-Yes-No-Value
IF 88-Switch-Is-Good

06FEB2009 Version

Page 8-13

OpenCOBOL 1.1 Programmers Guide

GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410

GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410/Sample Programs

MOVE SV-1 TO S-NOTRUNC
END-IF
WHEN Switch-Is-SOURCE
MOVE 'SOURCE' TO Switch-Keyword
MOVE UPPER-CASE(Switch-Value)
TO Switch-ValuePERFORM 050-Process-Yes-No-All
IF 88-Switch-Is-Good
MOVE SV-1 TO S-SOURCE
END-IF
WHEN Switch-Is-TRACE
MOVE 'TRACE' TO Switch-Keyword
MOVE UPPER-CASE(Switch-Value)
TO Switch-ValuePERFORM 050-Process-Yes-No-All
IF 88-Switch-Is-Good
MOVE SV-1 TO S-TRACE
END-IF
WHEN Switch-Is-XREF
MOVE 'XREF' TO Switch-Keyword
MOVE UPPER-CASE(Switch-Value)
TO Switch-ValuePERFORM 050-Process-Yes-No-All
IF 88-Switch-Is-Good
MOVE SV-1 TO S-XREF
END-IF
WHEN OTHER
MOVE SPACES TO Output-Message
STRING '"'TRIM(Switch-Keyword)'" is not a valid switch ' &'- ignored'
DELIMITED SIZE
INTO Output-Message
END-STRINGSET 88-Switch-Is-Bad TO TRUE
END-EVALUATE.
039-Done.
EXIT.

040-Process-Yes-No-Value SECTION.
******************************************************************* Process a switch value of YES or NO*******************************************************************
042-Process.
EVALUATE SV-1
WHEN 'Y'
MOVE 'YES' TO Switch-Value
WHEN 'N'
MOVE 'NO' To Switch-Value
WHEN OTHER
MOVE SPACES TO Output-Message
STRING '*ERROR: "' TRIM(Switch-Value)'" is not a valid value for the "'TRIM(Switch-Keyword) '" switch'
DELIMITED SPACES
INTO Output-Message
END-STRINGSET 88-Switch-Is-Bad TO TRUE
END-EVALUATE.
049-Done.
EXIT.
/

050-Process-Yes-No-All SECTION.
******************************************************************* Process a switch value of YES, NO or ALL*******************************************************************
052-Process.
IF SV-1 = 'A'
MOVE 'ALL' TO Switch-ValueELSEPERFORM 040-Process-Yes-No-Value
END-IF.

/

059-Done.
EXIT.

06FEB2009 Version

Page 8-14

OpenCOBOL 1.1 Programmers Guide

Sample Programs

060-Process-Yes-No-Auto SECTION.
******************************************************************* Process a switch value of YES, NO or AUTO*******************************************************************/

061-Init.
IF SV-1 = 'A'PERFORM 070-Find-LINKAGE-SECTION
IF 88-Compile-As-Subpgm
MOVE 'Y' TO Switch-ValueELSE
MOVE 'N' TO Switch-Value
END-IFELSEPERFORM 040-Process-Yes-No-Value
END-IF.

070-Find-LINKAGE-SECTION SECTION.
******************************************************************* Determine if the program being compiled is a MAIN program*******************************************************************
071-Init.
OPEN INPUT Source-CodeSET 88-Compile-As-Mainpgm TO TRUE
SET 88-More-To-1st-Prog
TO TRUEPERFORM UNTIL 88-1st-Prog-Complete
READ Source-Code AT END
CLOSE Source-Code
EXIT SECTION
END-READCALL 'CHECKSOURCE' USING Source-Code-Record
F-Source-Record-Type
END-CALLIF 88-Source-Rec-Ident
SET 88-1st-Prog-Complete TO TRUE
END-IF
END-PERFORM.
072-Process-Source.
SET 88-Source-Rec-IgnoCOB-COLOR-RED TO TRUEPERFORM UNTIL 88-Source-Rec-Linkage
OR 88-Source-Rec-Ident
READ Source-Code AT END
CLOSE Source-Code
EXIT SECTION
END-READCALL 'CHECKSOURCE' USING Source-Code-Record
F-Source-Record-Type
END-CALL
END-PERFORM
CLOSE Source-Code
IF 88-Source-Rec-Linkage
SET 88-Compile-As-Subpgm TO TRUE
END-IF.
079-Done.
EXIT.
/

100-Initialization SECTION.
******************************************************************* Perform all program-wide initialization operations*******************************************************************
GC0909 101-Determine-OS-Type.
GC0909CALL 'GETOSTYPE'
GC0909END-CALL
GC0909MOVE RETURN-CODE TO OS-Type
GC0909EVALUATE TRUE
GC0909WHEN OS-Unknown
GC0909MOVE '\'TO Dir-Char
GC0909MOVE 'Unknown'
TO OS-Type-Literal
GC0310MOVE COB-SCR-F11 TO CK-S-F1
GC0310MOVE COB-SCR-F12 TO CK-S-F2
GC0310MOVE COB-SCR-F13 TO CK-S-F3
GC0310MOVE COB-SCR-F14 TO CK-S-F4
GC0310MOVE COB-SCR-F15 TO CK-S-F5
GC0310MOVE COB-SCR-F16 TO CK-S-F6
GC0310MOVE COB-SCR-F17 TO CK-S-F7
GC0909WHEN OS-Windows

06FEB2009 Version

Page 8-15

OpenCOBOL 1.1 Programmers Guide
GC0909GC0909GC0310
GC0310
GC0310
GC0310
GC0310
GC0310
GC0310
GC0909GC0909GC0410
GC0310
GC0310
GC0310
GC0310
GC0310
GC0310
GC0310
GC0909GC0909GC0410
GC0310
GC0310
GC0310
GC0310
GC0310
GC0310
GC0310
GC0909GC0909Sample Programs

MOVE '\'TO Dir-Char
MOVE 'Windows'
TO OS-Type-Literal
MOVE COB-SCR-F13 TO CK-S-F1
MOVE COB-SCR-F14 TO CK-S-F2
MOVE COB-SCR-F15 TO CK-S-F3
MOVE COB-SCR-F16 TO CK-S-F4MOVE COB-SCR-F17 TO CK-S-F5MOVE COB-SCR-F18 TO CK-S-F6
MOVE COB-SCR-F19 TO CK-S-F7
WHEN OS-Cygwin
MOVE '/'TO Dir-Char
MOVE 'Cygwin'
TO OS-Type-Literal
MOVE COB-SCR-F11 TO CK-S-F1
MOVE COB-SCR-F12 TO CK-S-F2
MOVE COB-SCR-F13 TO CK-S-F3
MOVE COB-SCR-F14 TO CK-S-F4MOVE COB-SCR-F15 TO CK-S-F5MOVE COB-SCR-F16 TO CK-S-F6
MOVE COB-SCR-F17 TO CK-S-F7
WHEN OS-UNIX
MOVE '/'TO Dir-Char
MOVE 'UNIX'
TO OS-Type-Literal
MOVE COB-SCR-F11 TO CK-S-F1
MOVE COB-SCR-F12 TO CK-S-F2
MOVE COB-SCR-F13 TO CK-S-F3
MOVE COB-SCR-F14 TO CK-S-F4MOVE COB-SCR-F15 TO CK-S-F5MOVE COB-SCR-F16 TO CK-S-F6
MOVE COB-SCR-F17 TO CK-S-F7
END-EVALUATE.
102-Set-Environment-Vars.
SET ENVIRONMENT 'COB_SCREEN_EXCEPTIONS' TO 'Y'
SET ENVIRONMENT 'COB_SCREEN_ESC'
TO 'Y'.

103-Generate-Cobc-Output-Fn.
ACCEPT Env-TEMP
FROM ENVIRONMENT "TEMP"END-ACCEPTMOVE SPACES TO Cobc-Output-File
STRING TRIM(Env-TEMP,TRAILING)
GC0909
Dir-Char
GC0909'OC-Messages.TXT'
DELIMITED SIZE
INTO Cobc-Output-File
END-STRING.
104-Generate-Banner-Line-Info.
MOVE WHEN-COMPILED (1:12) TO OC-Compiled
INSPECT OC-Compiled
REPLACING ALL '/' BY ':'AFTER INITIAL SPACE.
105-Establish-Switch-Settings.
ACCEPT Command-Line-Args
FROM COMMAND-LINE
END-ACCEPTMOVE TRIM(Command-Line-Args, Leading)
TO Command-Line-Args
MOVE 0 TO Tally
GC0410
INSPECT Command-Line-Args TALLYING Tally FOR ALL '@'IF Tally = 0
MOVE Command-Line-Args TO File-Name
MOVE SPACESTO Command-Line-Args
ELSE
GC0410
UNSTRING Command-Line-Args DELIMITED BY '@'INTO File-Name, Dummy
END-UNSTRING
INSPECT Command-Line-Args
GC0410
REPLACING FIRST '@' BY LOW-VALUESUNSTRING Command-Line-Args
DELIMITED BY LOW-VALUESINTO Dummy, Cmd
END-UNSTRING
MOVE SPACES TO Command-Line-Args
GC0410STRING '@' Cmd DELIMITED SIZE
INTO Command-Line-Args
END-STRING
END-IFIF File-Name = SPACES

06FEB2009 Version

Page 8-16

OpenCOBOL 1.1 Programmers Guide

Sample Programs

DISPLAY'No program filename was specified'
END-DISPLAYPERFORM 900-Terminate
END-IFPERFORM 010-Parse-Args
IF S-SUBROUTINE = 'A'
MOVE 'S' TO Switch-Keyword
MOVE 'A' TO Switch-ValuePERFORM 070-Find-LINKAGE-SECTION
IF 88-Compile-As-Subpgm
MOVE 'Y' TO S-SUBROUTINEELSEMOVE 'N' TO S-SUBROUTINE
END-IF
END-IF
INSPECT S-Yes-No-Switches REPLACING ALL 'Y' BY Selection-Char
INSPECT S-Yes-No-Switches REPLACING ALL 'N' BY ' '.
106-Determine-Folder-Path.
Move 256 TO I
GC0909IF OS-Cygwin AND File-Name (2:1) = ':'GC0909MOVE '\' TO Dir-Char
GC0909END-IFPERFORM UNTIL I = 0 OR FN-Char (I) = Dir-Char
SUBTRACT 1 FROM I
END-PERFORM
IF I = 0
MOVE SPACESTO Prog-Folder
MOVE File-Name TO Prog-File-Name
ELSE
MOVE '*' TO FN-Char (I)UNSTRING File-Name DELIMITED BY '*'INTO Prog-Folder
Prog-File-Name
END-UNSTRING
MOVE Dir-Char TO FN-Char (I)
END-IF
UNSTRING Prog-File-Name DELIMITED BY '.'INTO Prog-Name, Prog-Extension
END-UNSTRING
IF Prog-Folder = SPACESACCEPT Prog-Folder
FROM ENVIRONMENT 'CD'
END-ACCEPT
GC0909ELSE
GC0909CALL "CBL_CHANGE_DIR"
GC0909USING TRIM(Prog-Folder,TRAILING)
GC0909END-CALL
END-IF
GC0909IF OS-Cygwin AND File-Name (2:1) = ':'GC0909MOVE '/' TO Dir-Char
GC0909END-IF.
GC0909 107-Other.
GC0909MOVE ALL LD-Horiz-Line TO Horizontal-Line.
GC0410MOVE CONCATENATE(' OCic for ',GC0410
TRIM(OS-Type-Literal,Trailing),
GC0410' Copyright (C) 2009-2010, Gary L. Cutler,',
GC0410' GPL')
GC0410TO Output-Message.
GC0909.
GC0909109-Done.
EXIT.
/
200-Let-User-Set-Switches SECTION.
******************************************************************* Show the user the current switch settings and allow them to **** be changed.
*******************************************************************
201-Init.
SET 88-Switch-Changes TO TRUE.
202-Show-And-Change-Switches.
PERFORM UNTIL 88-No-Switch-Changes
ACCEPT
Switches-Screen
END-ACCEPTIF COB-CRT-STATUS > 0

06FEB2009 Version

Page 8-17

OpenCOBOL 1.1 Programmers Guide

GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0410
GC0310
GC0310
GC0310
GC0310
GC0310
GC0310
GC031006FEB2009 Version

Sample Programs

EVALUATE COB-CRT-STATUS
WHEN COB-SCR-F1
IF S-DEBUG = SPACEMOVE Selection-Char TO S-DEBUG
ELSE
MOVE ' ' TO S-DEBUG
END-IF
WHEN COB-SCR-F2
IF S-DLL = SPACEMOVE Selection-Char TO S-DLL
ELSE
MOVE ' ' TO S-DLL
END-IF
WHEN COB-SCR-F3
IF S-SUBROUTINE = SPACEMOVE Selection-Char TO S-SUBROUTINE
MOVE ' ' TO S-EXECUTE
ELSE
MOVE ' ' TO S-SUBROUTINE
END-IF
WHEN COB-SCR-F4
IF S-EXECUTE = SPACEAND S-SUBROUTINE = SPACEMOVE Selection-Char TO S-EXECUTE
ELSE
MOVE ' ' TO S-EXECUTE
END-IF
WHEN COB-SCR-F5
IF S-NOTRUNC = SPACEMOVE Selection-Char TO S-NOTRUNCELSEMOVE ' ' TO S-NOTRUNC
END-IF
WHEN COB-SCR-F6
IF S-TRACE = SPACEMOVE Selection-Char TO S-TRACE
MOVE ' ' TO S-TRACEALL
ELSE
MOVE ' ' TO S-TRACE
END-IF
WHEN COB-SCR-F7
IF S-TRACEALL = SPACEMOVE Selection-Char TO S-TRACEALL
MOVE ' ' TO S-TRACEELSE
MOVE ' ' TO S-TRACEALL
END-IF
WHEN COB-SCR-F8
IF S-SOURCE = SPACEMOVE Selection-Char TO S-SOURCE
ELSE
MOVE ' ' TO S-SOURCE
END-IF
WHEN COB-SCR-F9
IF S-XREF = SPACEMOVE Selection-Char TO S-XREF
ELSE
MOVE ' ' TO S-XREF
END-IF
WHEN COB-SCR-ESCPERFORM 900-Terminate
WHEN CK-S-F1
MOVE SPACESTO S-CfgS
MOVE Selection-Char TO S-Cfg-BS2000
WHEN CK-S-F2
MOVE SPACESTO S-CfgS
MOVE Selection-Char TO S-Cfg-COBOL85
WHEN CK-S-F3
MOVE SPACESTO S-CfgS
MOVE Selection-Char TO S-Cfg-COBOL2002
WHEN CK-S-F4MOVE SPACESTO S-CfgS
MOVE Selection-Char TO S-Cfg-DEFAULT
WHEN CK-S-F5MOVE SPACESTO S-CfgS
MOVE Selection-Char TO S-Cfg-IBM
WHEN CK-S-F6
MOVE SPACESTO S-CfgS
MOVE Selection-Char TO S-Cfg-MF
WHEN CK-S-F7
MOVE SPACESTO S-CfgS
MOVE Selection-Char TO S-Cfg-MVS
WHEN OTHER
MOVE 'An unsupported key was pressed'

Page 8-18

OpenCOBOL 1.1 Programmers Guide

Sample Programs

TO Output-Message
END-EVALUATEELSE
SET 88-No-Switch-Changes TO TRUE
END-IF
END-PERFORM.
209-Done.
EXIT.
/

210-Run-Compiler SECTION.
******************************************************************* Run the compiler using the switch settings we've prepared. *******************************************************************
211-Init.
MOVE SPACES TO Cmd
Cobc-Cmd
Output-Message
DISPLAY
Switches-Screen
END-DISPLAY
MOVE 1 TO IEVALUATE TRUE
WHEN S-Cfg-BS2000 NOT = SPACES
MOVE 'bs2000' TO Config-File
WHEN S-Cfg-COBOL85 NOT = SPACES
MOVE 'cobol85' TO Config-File
WHEN S-Cfg-COBOL2002 NOT = SPACES
MOVE 'cobol2002' TO Config-File
WHEN S-Cfg-IBM NOT = SPACES
MOVE 'ibm' TO Config-File
WHEN S-Cfg-MF NOT = SPACES
MOVE 'mf' TO Config-File
WHEN S-Cfg-MVS NOT = SPACES
MOVE 'mvs' TO Config-File
WHEN OTHER
MOVE 'default' TO Config-File
END-EVALUATE.
212-Build-Compile-Command.
MOVE SPACES TO Cobc-Cmd
STRING 'cobc -std='
TRIM(Config-File,TRAILING)' 'INTO Cobc-Cmd
WITH POINTER I
END-STRINGIF S-SUBROUTINE NOT = ' 'STRING '-m 'DELIMITED SIZE INTO Cobc-Cmd
WITH POINTER I
END-STRINGELSE
STRING '-x 'DELIMITED SIZE INTO Cobc-Cmd
WITH POINTER I
END-STRING
END-IFIF S-DEBUG NOT = ' 'STRING '-fdebugging-line 'DELIMITED SIZE INTO Cobc-Cmd
WITH POINTER I
END-STRING
END-IFIF S-NOTRUNC NOT = ' 'STRING '-fnotrunc 'DELIMITED SIZE INTO Cobc-Cmd
WITH POINTER I
END-STRING
END-IFIF S-TRACEALL NOT = ' 'GC0809STRING '-ftraceall 'DELIMITED SIZE INTO Cobc-Cmd
WITH POINTER I
END-STRING
END-IFIF S-TRACE NOT = ' 'STRING '-ftrace 'DELIMITED SIZE INTO Cobc-Cmd
WITH POINTER I
END-STRING
GC0909GC0909GC0909GC0909GC0909GC0909GC090906FEB2009 Version

Page 8-19

OpenCOBOL 1.1 Programmers Guide

Sample Programs

END-IF
GC0709GC0709GC0709GC0709GC0709GC0709GC0709GC0709GC0909GC0909GC0909GC0909IF S-EXTRA > SPACESSTRING ' 'TRIM(S-Extra,TRAILING)' 'DELIMITED SIZE INTO Cobc-Cmd
WITH POINTER I
END-STRING
END-IFSTRING TRIM(Prog-File-Name,TRAILING)
DELIMITED SIZE INTO Cobc-Cmd
WITH POINTER I
END-STRING.

213-Run-Compiler.
MOVE ' Compiling...' TO Output-Message
DISPLAY
Switches-Screen
END-DISPLAY
SET 88-Output-File-Avail TO TRUE
MOVE SPACES TO Cmd
STRING TRIM(Cobc-Cmd,TRAILING)' 2>'
TRIM(Cobc-Output-File,TRAILING)
DELIMITED SIZE
INTO Cmd
END-STRINGCALL 'SYSTEM'USING TRIM(Cmd,TRAILING)
END-CALL
GC0909IF RETURN-CODE = 0
GC0909SET 88-Compile-OK TO TRUE
GC0909ELSE
GC0909SET 88-Compile-Failed TO TRUE
GC0909END-IF
GC0909IF 88-Compile-OK
GC0909OPEN INPUT Cobc-Output
GC0909READ Cobc-Output
GC0909AT END
GC0909CONTINUE
GC0909NOT AT END
GC0909SET 88-Compile-OK-Warn TO TRUE
GC0909END-READ
GC0909CLOSE Cobc-Output
GC0909END-IF
GC0909MOVE SPACES TO Output-Message
IF 88-Compile-OK
GC0909MOVE ' Compilation Was Successful' TO Output-Message
GC0909DISPLAY
GC0909Switches-Screen
GC0909END-DISPLAY
GC0909CALL 'C$SLEEP'
GC0909USING 2
GC0909END-CALL
GC0909MOVE SPACES TO Output-Message
GC0609SET 88-Complete TO TRUE
ELSE
GC0909DISPLAY
GC0909Blank-Screen
GC0909END-DISPLAY
GC0909IF 88-Compile-OK-Warn
GC0909DISPLAY ' Compilation was successful, but ' &GC0909'warnings were generated:'
SCROLL*AT LINE 24 COLUMN 1
SCROLL*
WITH SCROLL UP 1 LINE
GC0909END-DISPLAY
GC0909ELSE
GC0909DISPLAY 'Compilation Failed:'
SCROLL*AT LINE 24 COLUMN 1
SCROLL*
WITH SCROLL UP 1 LINE
GC0909END-DISPLAY
GC0909END-IF
GC0609SET 88-Compile-Failed TO TRUE
GC0609SET 88-Complete TO TRUE
GC0909DISPLAY ' 'SCROLL*AT LINE 24 COLUMN 1
SCROLL*
WITH SCROLL UP 1 LINE
GC0909END-DISPLAY
GC0909OPEN INPUT Cobc-Output
GC0909PERFORM FOREVER
GC0909READ Cobc-Output AT END
GC0909EXIT PERFORM
GC0410
GC0410
GC0410
GC0410GC060906FEB2009 Version

Page 8-20

OpenCOBOL 1.1 Programmers Guide
GC0909GC0909SCROLL*SCROLL*
GC0909GC0909GC0909GC0909SCROLL*SCROLL*
GC0909GC0909SCROLL*SCROLL*
GC0909GC0909GC0909GC0909GC0909GC0909GC0909Sample Programs

END-READDISPLAY TRIM(Cobc-Output-Rec,TRAILING)
AT LINE 24 COLUMN 1
WITH SCROLL UP 1 LINE
END-DISPLAY
END-PERFORM
CLOSE Cobc-Output
DISPLAY ' 'AT LINE 24 COLUMN 1
WITH SCROLL UP 2 LINES
END-DISPLAYDISPLAY 'Press ENTER to close:'
AT LINE 24 COLUMN 1
WITH SCROLL UP 1 LINE
END-DISPLAY
ACCEPT Dummy
FROM CONSOLE
END-ACCEPTDISPLAY
Blank-Screen
END-DISPLAY
END-IF.
219-Done.
IF 88-Compile-Failed
PERFORM 900-Terminate
END-IF.

/
GC0410 220-Make-Listing SECTION.
GC0410*****************************************************************
GC0410** Generate a source and/or xref listing using XREF**
GC0410*****************************************************************
GC0410
GC0410 221-Init.
GC0410MOVE ' Generating cross-reference listing...'
GC0410TO Output-Message
GC0410DISPLAY
GC0410Switches-Screen
GC0410END-DISPLAY
GC0410CALL "CBL_DELETE_FILE"
GC0410
USING CONCATENATE(TRIM(Prog-Name,Trailing),".lst")
GC0410
END-CALL
GC0410MOVE 0 TO RETURN-CODE
GC0410.
GC0410
GC0410 213-Run-OCXref.
GC0410MOVE SPACES TO Output-Message
GC0410CALL 'LISTING'
GC0410
USING S-SOURCE
GC0410S-XREF
GC0410File-Name
GC0410ON EXCEPTION
GC0410MOVE ' LISTING module is not available'
GC0410TO Output-Message
GC0410MOVE 1 TO RETURN-CODE
GC0410
END-CALL
GC0410IF RETURN-CODE = 0
GC0410MOVE ' Listing generated'
GC0410TO Output-Message
GC0410IF OS-Windows OR OS-Cygwin
GC0410MOVE SPACES TO Cmd
GC0410STRING
GC0410'cmd /c 'GC0410
TRIM(Prog-Name,TRAILING)
GC0410'.lst'
GC0410DELIMITED SIZE INTO Cmd
GC0410END-STRING
GC0410CALL 'SYSTEM'
GC0410
USING TRIM(Cmd,TRAILING)
GC0410
END-CALL
GC0410END-IF
GC0410
ELSE
GC0410IF Output-Message = SPACES
GC0410MOVE ' Listing generation failed'
GC0410TO Output-Message
GC0410END-IF
GC0410END-IF
GC0410DISPLAY
GC0410Switches-Screen
GC0410END-DISPLAY
GC0410CALL 'C$SLEEP'
GC0410
USING 2

06FEB2009 Version

Page 8-21

OpenCOBOL 1.1 Programmers Guide
GC0410
GC0410/Sample Programs

END-CALL.

230-Run-Program SECTION.
******************************************************************* Run the compiled program*******************************************************************
232-Build-Command.
MOVE SPACES TO Cmd
MOVE 1 TO I
IF S-SUBROUTINE NOT = ' 'OR S-DLL NOT = ' 'STRING 'cobcrun ' DELIMITED SIZE
INTO Cmd
WITH POINTER I
END-STRING
END-IFIF Prog-Folder NOT = SPACES
GC0909IF OS-Cygwin AND Prog-Folder (2:1) = ':'GC0909STRING '/cygdrive/'
GC0909INTO Cmd
GC0909WITH POINTER I
GC0909END-STRING
GC0909STRING LOWER-CASE(Prog-Folder (1:1))
GC0909INTO Cmd
GC0909WITH POINTER I
GC0909END-STRING
GC0909PERFORM VARYING J FROM 3 BY 1
GC0909
UNTIL J > LENGTH(TRIM(Prog-Folder))GC0909IF Prog-Folder (J:1) = '\'GC0909STRING '/'GC0909INTO Cmd
GC0909WITH POINTER I
GC0909END-STRING
GC0909ELSE
GC0909STRING Prog-Folder (J:1)
GC0909INTO Cmd
GC0909WITH POINTER I
GC0909END-STRING
GC0909END-IF
GC0909END-PERFORM
GC0909ELSE
GC0410STRING '"' TRIM(Prog-Folder,TRAILING)
GC0909INTO Cmd
GC0909WITH POINTER I
GC0909END-STRING
GC0909END-IF
GC0909STRING Dir-Char
GC0909INTO Cmd
GC0909WITH POINTER I
GC0909END-STRING
GC0909ELSE
GC0909IF OS-Cygwin OR OS-UNIX
GC0909STRING './'
GC0909INTO Cmd
GC0909WITH POINTER I
GC0909END-STRING
GC0909END-IF
END-IF
GC0909STRING TRIM(Prog-Name,TRAILING)
GC0909INTO Cmd
GC0909WITH POINTER I
GC0909END-STRING
GC0909IF S-SUBROUTINE = ' 'GC0909AND S-DLL NOT = ' 'GC0909STRING '.exe' DELIMITED SIZE
INTO Cmd
WITH POINTER I
END-STRING
END-IFIF S-ARGS NOT = SPACES
GC0809STRING ' ' TRIM(S-ARGS,TRAILING)
INTO Cmd
WITH POINTER I
END-STRING
END-IFIF OS-Unknown OR OS-Windows
GC0410STRING '"&&pause'
INTO Cmd
WITH POINTER I
END-STRINGELSE
STRING ';echo "Press ENTER to close...";read'
GC0909GC090906FEB2009 Version

Page 8-22

OpenCOBOL 1.1 Programmers Guide

Sample Programs

INTO Cmd
WITH POINTER I
END-STRING
END-IF.
GC0909GC0909GC0909233-Run-Program.
DISPLAY
Blank-Screen
END-DISPLAYCALL 'SYSTEM'USING TRIM(Cmd,TRAILING)
END-CALLPERFORM 900-Terminate.
239-Done.
EXIT.

/

900-Terminate SECTION.
******************************************************************* Display a message and halt the program*******************************************************************
GC0909GC0909GC0909GC0909GC0909GC0909GC0909GC0909901-Display-Message.
IF Output-Message > SPACESDISPLAY
Switches-Screen
END-DISPLAYCALL 'C$SLEEP'USING 2
END-CALL
END-IFDISPLAY
Blank-Screen
END-DISPLAY.
909-Done.
GOBACK.
END PROGRAM OCic.

IDENTIFICATION DIVISION.
PROGRAM-ID. GETOSTYPE.
******************************************************************* This subprogram determine the OS type the program is run**** ning under, passing that result back in RETURN-CODE as fol- **** lows:
**
**
**
** 0:
Cannot be determined**** 1:
Native Windows or Windows/MinGW**** 2:
Cygwin**** 3:
UNIX/Linux/MacOS********************************************************************* DATE CHANGE DESCRIPTION**** ====== ==================================================== **** GC0909 Initial coding.
*******************************************************************ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY.
FUNCTION ALL INTRINSIC.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Env-Path
PIC X(1024).
01 Tally
USAGE BINARY-LONG.
PROCEDURE DIVISION.
000-Main SECTION.
010-Get-TEMP-Var.
MOVE SPACES TO Env-Path
ACCEPT Env-Path
FROM ENVIRONMENT "PATH"
ON EXCEPTIONMOVE 0 TO RETURN-CODE
GOBACK
END-ACCEPTIF Env-Path = SPACES
MOVE 0 TO RETURN-CODE
ELSE
MOVE 0 TO Tally
INSPECT Env-Path

06FEB2009 Version

Page 8-23

OpenCOBOL 1.1 Programmers Guide

Sample Programs

TALLYING Tally FOR ALL ";"IF Tally = 0 *> Must be some form of UNIX
MOVE 0 TO Tally
INSPECT Env-Path
TALLYING TALLY FOR ALL "/cygdrive/"
IF Tally = 0 *> UNIX/MacOS
MOVE 3 TO RETURN-CODE
ELSE *> Cygwin
MOVE 2 TO RETURN-CODE
END-IFELSE *> Assume Windows[/MinGW]
MOVE 1 TO RETURN-CODE
END-IF
END-IF
GOBACK.
END PROGRAM GETOSTYPE.
IDENTIFICATION DIVISION.
PROGRAM-ID. CHECKSOURCE.
******************************************************************* This subprogram will scan a line of source code it is given **** looking for "LINKAGE SECTION" or "IDENTIFICATION DIVISION". ******** ****NOTE********NOTE********NOTE********NOTE*** ******** These two strings must be found IN THEIR ENTIRETY within**** the 1st 80 columns of program source records, and cannot**** follow either a "*>" sequence OR a "*" in col 7.
********************************************************************* DATE CHANGE DESCRIPTION**** ====== ==================================================== **** GC0809 Initial coding.
*******************************************************************ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY.
FUNCTION ALL INTRINSIC.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Compressed-Src.
05 CS-Char
OCCURS 80 TIMES PIC X(1).
01

Flags.
05 F-Found-SPACEPIC X(1).
88 88-Skipping-SPACEVALUE 'Y'.
88 88-Not-Skipping-SPACE VALUE 'N'.

01

I

01 J
LINKAGE SECTION.
01 Argument-1.
02 A1-Char

USAGE BINARY-CHAR.
USAGE BINARY-CHAR.
OCCURS 80 TIMES PIC X(1).

01

Argument-2
PIC X(1).
88 88-A2-LINKAGE-SECTIONVALUE 'L'.
88 88-A2-IDENTIFICATION-DIVISION VALUE 'I'.
88 88-A2-Nothing-Special
VALUE ' '.
PROCEDURE DIVISION USING Argument-1, Argument-2.
000-Main SECTION.
010-Initialize.
SET 88-A2-Nothing-Special TO TRUE
IF A1-Char (7) = '*'GOBACK
END-IF.
020-Compress-Multiple-SPACES.
SET 88-Not-Skipping-SPACE TO TRUE
MOVE 0 TO JMOVE SPACES TO Compressed-Src
PERFORM VARYING I FROM 1 BY 1
UNTIL I > 80
IF A1-Char (I) = SPACE
IF 88-Not-Skipping-SPACEADD 1 TO JMOVE UPPER-CASE(A1-Char (I)) TO CS-Char (J)SET 88-Skipping-SPACE TO TRUE
END-IFELSE
SET 88-Not-Skipping-SPACE TO TRUE
ADD 1 TO J

06FEB2009 Version

Page 8-24

OpenCOBOL 1.1 Programmers Guide

Sample Programs

MOVE A1-Char (I) TO CS-Char (J)END-IF
END-PERFORM.
030-Scan-Compressed-Src.
PERFORM VARYING I FROM 1 BY 1
UNTIL I > 66
EVALUATE TRUE
WHEN CS-Char (I) = '*'IF Compressed-Src (I : 2) = '*>'GOBACK
END-IF
WHEN (CS-Char (I) = 'L') AND (I < 66)
IF Compressed-Src (I : 15) = 'LINKAGE SECTION'
SET 88-A2-LINKAGE-SECTION TO TRUE
GOBACK
END-IF
WHEN (CS-Char (I) = 'I') AND (I < 58)
IF Compressed-Src (I : 23) = 'IDENTIFICATION ' &'DIVISION'SET 88-A2-IDENTIFICATION-DIVISION TO TRUE
GOBACK
END-IF
END-EVALUATEEND-PERFORM.
099-Never-Found-Either-One.
GOBACK.
END PROGRAM CHECKSOURCE.
IDENTIFICATION DIVISION.
PROGRAM-ID. LISTING.
******************************************************************* This subprogram generates a cross-reference listing of an**** OpenCOBOL program.
******** Linkage:
CALL "LISTING" USING <source>****<xref>****<filename>
**
**
**
**
Where:****<source>is a PIC X(1) flag indicating****
whether or not a source listing ****should be produced (space=NO,****
non-space=yes)****<xref>
is a PIC X(1) flag indicating****
whether or not an xref listing ****should be produced (space=NO,****
non-space=yes)****<filename> is the [path]filename of the****
program being listed and/or****
xreffed in a PIC X(256) form.
************************************************************************* AUTHOR:GARY L. CUTLER****
CutlerGL@gmail.com****
Copyright (C) 2010, Gary L. Cutler, GPL******** DATE-WRITTEN: April 1, 2010************************************************************************* DATE CHANGE DESCRIPTION**** ====== ==================================================== **** GC0410 Initial coding*******************************************************************ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY.
FUNCTION ALL INTRINSIC.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT Expand-CodeASSIGN TO Expanded-Src-Filename
ORGANIZATION IS LINE SEQUENTIAL.
SELECT Report-FileASSIGN TO Report-Filename
ORGANIZATION IS LINE SEQUENTIAL.
SELECT Sort-FileASSIGN TO DISK.
SELECT Source-CodeASSIGN TO Src-Filename
ORGANIZATION IS LINE SEQUENTIAL.
DATA DIVISION.
FILE SECTION.
FD Expand-Code.

06FEB2009 Version

Page 8-25

OpenCOBOL 1.1 Programmers Guide
01
01

GC0410
GC0410
GC0410
GC0410

Expand-Code-Rec.
05 ECR-1
05 ECR-2-256
Expand-Code-Rec-Alt.
05 ECR-1-128
05 ECR-129-256

PIC X.
PIC X(256).
PIC X(128).
PIC X(128).

FD
01

Report-File.
Report-Rec

PIC X(135).

SD
01

Sort-File.
Sort-Rec.
05 SR-Prog-ID
05 SR-Token-UC
05 SR-Token
05 SR-Section
05 SR-Line-No-Def
05 SR-Reference.
10 SR-Line-No-Ref
10 SR-Ref-Flag

PIC X(15).
PIC X(32).
PIC X(32).
PIC X(15).
PIC 9(6).

FD
01

Source-Code.
Source-Code-Rec.
05 SCR-1-128.
10 FILLER
10 SCR-7
10 FILLER
05 SCR-129-256

PIC 9(6).
PIC X(1).

PIC X(6).
PIC X(1).
PIC X(121).
PIC X(128).

WORKING-STORAGE SECTION.
78 Line-Nos-Per-Rec

VALUE 8.

01

Cmd

PIC X(256).

01

Delim

PIC X(2).

01

Detail-Line-S.
05 DLS-Line-No
05 FILLER
05 DLS-Statement

PIC ZZZZZ9.
PIC X(1).
PIC X(128).

Detail-Line-X.
05 DLX-Prog-ID
05 FILLER
05 DLX-Token
05 FILLER
05 DLX-Line-No-Def
05 FILLER
05 DLX-Section
05 FILLER
05 DLX-Reference
10 DLX-Line-No-Ref
10 DLX-Ref-Flag
10 FILLER

PIC X(15).
PIC X(1).
PIC X(32).
PIC X(1).
PIC ZZZZZ9.
PIC X(1).
PIC X(15).
PIC X(1).
OCCURS Line-Nos-Per-Rec TIMES.
PIC ZZZZZ9.
PIC X(1).
PIC X(1).

01

Dummy

PIC X(1).

01

Env-TEMPPIC X(256).

01

Expanded-Src-Filename

PIC X(256).

01

Filename

PIC X(256).

01

Flags.
05 F-First-Record
05 F-In-Which-Pgm
88 In-Main-Module
88 In-Copybook
05 F-Last-Token-Ended-Sent
05 F-Processing-PICTURE
05 F-Token-Ended-Sentence

PIC X(1).
PIC X(1).
VALUE 'M'.
VALUE 'C'.
PIC X(1).
PIC X(1).
PIC X(1).

Group-Indicators.
05 GI-Prog-ID
05 GI-TokenPIC X(15).
PIC X(32).

01

01

01

Heading-1S.
05 FILLER
PIC X(125) VALUE"OpenCOBOL 1.1 06FEB2009 Source Listing - " &"OCic Copyright (C) 2009-2010, Gary L. Cutler, GPL".
05 H1S-Date
PIC 9999/99/99.

01

Heading-1X.
05 FILLER

06FEB2009 Version

Sample Programs

PIC X(125) VALUE

Page 8-26

OpenCOBOL 1.1 Programmers Guide

Sample Programs"OpenCOBOL 1.1 06FEB2009 Cross-Reference Listing - " &"OCic Copyright (C) 2009-2010, Gary L. Cutler, GPL".
05 H1X-Date
PIC 9999/99/99.
01

Heading-2

PIC X(135).

01

Heading-4S"Line
Statement".

PIC X(16) VALUE

01

Heading-4X"PROGRAM-ID"e Defined-

PIC X(96) VALUE
Identifier/Register/Function
References (* = Updated)".

Defn

Wher

01

Heading-5S
PIC X(135) VALUE"====== ====================================================="============================================================"===============".

01

Heading-5X
PIC X(135) VALUE"=============== ================================ ====== ===="=========== ================================================"===============".

01

Held-Reference

PIC X(100).

01

I

USAGE BINARY-LONG.

01

J

USAGE BINARY-LONG.

01

Lines-Left

USAGE BINARY-LONG.

01

Lines-Per-Page

USAGE BINARY-LONG.

01

Lines-Per-Page-ENV

PIC X(256).

01

Num-UserNames

USAGE BINARY-LONG.

01

PIC-X10

PIC X(10).

01

PIC-X32

PIC X(32).

01

PIC-X256

PIC X(256).

01

Program-Path

PIC X(256).

01

Report-Filename

PIC X(256).

01

Reserved-Words.
05 FILLER PIC X(33) VALUE "IABS".
05 FILLER PIC X(33) VALUE "VACCEPT".
05 FILLER PIC X(33) VALUE " ACCESS".
05 FILLER PIC X(33) VALUE "IACOS".
05 FILLER PIC X(33) VALUE " ACTIVE-CLASS".
05 FILLER PIC X(33) VALUE "VADD".
05 FILLER PIC X(33) VALUE " ADDRESS".
05 FILLER PIC X(33) VALUE " ADVANCING".
05 FILLER PIC X(33) VALUE "KAFTER".
05 FILLER PIC X(33) VALUE " ALIGNED".
05 FILLER PIC X(33) VALUE " ALL".
05 FILLER PIC X(33) VALUE "VALLOCATE".
05 FILLER PIC X(33) VALUE " ALPHABET".
05 FILLER PIC X(33) VALUE " ALPHABETIC".
05 FILLER PIC X(33) VALUE " ALPHABETIC-LOWER".
05 FILLER PIC X(33) VALUE " ALPHABETIC-UPPER".
05 FILLER PIC X(33) VALUE " ALPHANUMERIC".
05 FILLER PIC X(33) VALUE " ALPHANUMERIC-EDITED".
05 FILLER PIC X(33) VALUE " ALSO".
05 FILLER PIC X(33) VALUE "VALTER".
05 FILLER PIC X(33) VALUE " ALTERNATE".
05 FILLER PIC X(33) VALUE " AND".
05 FILLER PIC X(33) VALUE "IANNUITY".
05 FILLER PIC X(33) VALUE " ANY".
05 FILLER PIC X(33) VALUE " ANYCASE".
05 FILLER PIC X(33) VALUE " ARE".
05 FILLER PIC X(33) VALUE " AREA".
05 FILLER PIC X(33) VALUE " AREAS".
05 FILLER PIC X(33) VALUE " ARGUMENT-NUMBER".
05 FILLER PIC X(33) VALUE " ARGUMENT-VALUE".
05 FILLER PIC X(33) VALUE " AS".
05 FILLER PIC X(33) VALUE " ASCENDING".
05 FILLER PIC X(33) VALUE "IASIN".
05 FILLER PIC X(33) VALUE " ASSIGN".
05 FILLER PIC X(33) VALUE " AT".
05 FILLER PIC X(33) VALUE "IATAN".

--

06FEB2009 Version

Page 8-27

OpenCOBOL 1.1 Programmers Guide

Sample Programs

05 FILLER PIC X(33) VALUE " AUTHOR".
05 FILLER PIC X(33) VALUE " AUTO".
05 FILLER PIC X(33) VALUE " AUTO-SKIP".
05 FILLER PIC X(33) VALUE " AUTOMATIC".
05 FILLER PIC X(33) VALUE " AUTOTERMINATE".
05 FILLER PIC X(33) VALUE " BACKGROUND-COLOR".
05 FILLER PIC X(33) VALUE " BASED".
05 FILLER PIC X(33) VALUE " BEEP".
05 FILLER PIC X(33) VALUE " BEFORE".
05 FILLER PIC X(33) VALUE " BELL".
05 FILLER PIC X(33) VALUE " BINARY".
05 FILLER PIC X(33) VALUE " BINARY-C-LONG".
05 FILLER PIC X(33) VALUE " BINARY-CHAR".
05 FILLER PIC X(33) VALUE " BINARY-DOUBLE".
05 FILLER PIC X(33) VALUE " BINARY-LONG".
05 FILLER PIC X(33) VALUE " BINARY-SHORT".
05 FILLER PIC X(33) VALUE " BIT".
05 FILLER PIC X(33) VALUE " BLANK".
05 FILLER PIC X(33) VALUE " BLINK".
05 FILLER PIC X(33) VALUE " BLOCK".
05 FILLER PIC X(33) VALUE " BOOLEAN".
05 FILLER PIC X(33) VALUE " BOTTOM".
05 FILLER PIC X(33) VALUE "YBY".
05 FILLER PIC X(33) VALUE "IBYTE-LENGTH".
05 FILLER PIC X(33) VALUE "MC01".
05 FILLER PIC X(33) VALUE "MC02".
05 FILLER PIC X(33) VALUE "MC03".
05 FILLER PIC X(33) VALUE "MC04".
05 FILLER PIC X(33) VALUE "MC05".
05 FILLER PIC X(33) VALUE "MC06".
05 FILLER PIC X(33) VALUE "MC07".
05 FILLER PIC X(33) VALUE "MC08".
05 FILLER PIC X(33) VALUE "MC09".
05 FILLER PIC X(33) VALUE "MC10".
05 FILLER PIC X(33) VALUE "MC11".
05 FILLER PIC X(33) VALUE "MC12".
05 FILLER PIC X(33) VALUE "VCALL".
05 FILLER PIC X(33) VALUE "VCANCEL".
05 FILLER PIC X(33) VALUE " CF".
05 FILLER PIC X(33) VALUE " CH".
05 FILLER PIC X(33) VALUE " CHAINING".
05 FILLER PIC X(33) VALUE "ICHAR".
05 FILLER PIC X(33) VALUE " CHARACTER".
05 FILLER PIC X(33) VALUE " CHARACTERS".
05 FILLER PIC X(33) VALUE " CLASS".
05 FILLER PIC X(33) VALUE " CLASS-ID".
05 FILLER PIC X(33) VALUE "VCLOSE".
05 FILLER PIC X(33) VALUE "ICOB-CRT-STATUS".
05 FILLER PIC X(33) VALUE " CODE".
05 FILLER PIC X(33) VALUE " CODE-SET".
05 FILLER PIC X(33) VALUE " COL".
05 FILLER PIC X(33) VALUE " COLLATING".
05 FILLER PIC X(33) VALUE " COLS".
05 FILLER PIC X(33) VALUE " COLUMN".
05 FILLER PIC X(33) VALUE " COLUMNS".
05 FILLER PIC X(33) VALUE "ICOMBINED-DATETIME".
05 FILLER PIC X(33) VALUE " COMMA".
05 FILLER PIC X(33) VALUE " COMMAND-LINE".
05 FILLER PIC X(33) VALUE "VCOMMIT".
05 FILLER PIC X(33) VALUE " COMMON".
05 FILLER PIC X(33) VALUE " COMP".
05 FILLER PIC X(33) VALUE " COMP-1".
05 FILLER PIC X(33) VALUE " COMP-2".
05 FILLER PIC X(33) VALUE " COMP-3".
05 FILLER PIC X(33) VALUE " COMP-4".
05 FILLER PIC X(33) VALUE " COMP-5".
05 FILLER PIC X(33) VALUE " COMP-X".
05 FILLER PIC X(33) VALUE " COMPUTATIONAL".
05 FILLER PIC X(33) VALUE " COMPUTATIONAL-1".
05 FILLER PIC X(33) VALUE " COMPUTATIONAL-2".
05 FILLER PIC X(33) VALUE " COMPUTATIONAL-3".
05 FILLER PIC X(33) VALUE " COMPUTATIONAL-4".
05 FILLER PIC X(33) VALUE " COMPUTATIONAL-5".
05 FILLER PIC X(33) VALUE " COMPUTATIONAL-X".
05 FILLER PIC X(33) VALUE "VCOMPUTE".
05 FILLER PIC X(33) VALUE "ICONCATENATE".
05 FILLER PIC X(33) VALUE " CONDITION".
05 FILLER PIC X(33) VALUE "KCONFIGURATION".
05 FILLER PIC X(33) VALUE "MCONSOLE".
05 FILLER PIC X(33) VALUE " CONSTANT".
05 FILLER PIC X(33) VALUE " CONTAINS".
05 FILLER PIC X(33) VALUE " CONTENT".
05 FILLER PIC X(33) VALUE "VCONTINUE".
05 FILLER PIC X(33) VALUE " CONTROL".

06FEB2009 Version

Page 8-28

OpenCOBOL 1.1 Programmers Guide

Sample Programs

05 FILLER PIC X(33) VALUE " CONTROLS".
05 FILLER PIC X(33) VALUE "KCONVERTING".
05 FILLER PIC X(33) VALUE " COPY".
05 FILLER PIC X(33) VALUE " CORR".
05 FILLER PIC X(33) VALUE " CORRESPONDING".
05 FILLER PIC X(33) VALUE "ICOS".
05 FILLER PIC X(33) VALUE "KCOUNT".
05 FILLER PIC X(33) VALUE " CRT".
05 FILLER PIC X(33) VALUE " CURRENCY".
05 FILLER PIC X(33) VALUE "ICURRENT-DATE".
05 FILLER PIC X(33) VALUE " CURSOR".
05 FILLER PIC X(33) VALUE " CYCLE".
05 FILLER PIC X(33) VALUE "KDATA".
05 FILLER PIC X(33) VALUE " DATA-POINTER".
05 FILLER PIC X(33) VALUE " DATE".
05 FILLER PIC X(33) VALUE " DATE-COMPILED".
05 FILLER PIC X(33) VALUE " DATE-MODIFIED".
05 FILLER PIC X(33) VALUE "IDATE-OF-INTEGER".
05 FILLER PIC X(33) VALUE "IDATE-TO-YYYYMMDD".
05 FILLER PIC X(33) VALUE " DATE-WRITTEN".
05 FILLER PIC X(33) VALUE " DAY".
05 FILLER PIC X(33) VALUE "IDAY-OF-INTEGER".
05 FILLER PIC X(33) VALUE " DAY-OF-WEEK".
05 FILLER PIC X(33) VALUE "IDAY-TO-YYYYDDD".
05 FILLER PIC X(33) VALUE " DE".
05 FILLER PIC X(33) VALUE " DEBUGGING".
05 FILLER PIC X(33) VALUE " DECIMAL-POINT".
05 FILLER PIC X(33) VALUE " DECLARATIVES".
05 FILLER PIC X(33) VALUE " DEFAULT".
05 FILLER PIC X(33) VALUE "VDELETE".
05 FILLER PIC X(33) VALUE " DELIMITED".
05 FILLER PIC X(33) VALUE "KDELIMITER".
05 FILLER PIC X(33) VALUE " DEPENDING".
05 FILLER PIC X(33) VALUE " DESCENDING".
05 FILLER PIC X(33) VALUE " DESTINATION".
05 FILLER PIC X(33) VALUE " DETAIL".
05 FILLER PIC X(33) VALUE " DISABLE".
05 FILLER PIC X(33) VALUE " DISK".
05 FILLER PIC X(33) VALUE "VDISPLAY".
05 FILLER PIC X(33) VALUE "VDIVIDE".
05 FILLER PIC X(33) VALUE "KDIVISION".
05 FILLER PIC X(33) VALUE "KDOWN".
05 FILLER PIC X(33) VALUE " DUPLICATES".
05 FILLER PIC X(33) VALUE " DYNAMIC".
05 FILLER PIC X(33) VALUE "IE".
05 FILLER PIC X(33) VALUE " EBCDIC".
05 FILLER PIC X(33) VALUE " EC".
05 FILLER PIC X(33) VALUE "VELSE".
05 FILLER PIC X(33) VALUE " END".
05 FILLER PIC X(33) VALUE " END-ACCEPT".
05 FILLER PIC X(33) VALUE " END-ADD".
05 FILLER PIC X(33) VALUE " END-CALL".
05 FILLER PIC X(33) VALUE " END-COMPUTE".
05 FILLER PIC X(33) VALUE " END-DELETE".
05 FILLER PIC X(33) VALUE " END-DISPLAY".
05 FILLER PIC X(33) VALUE " END-DIVIDE".
05 FILLER PIC X(33) VALUE " END-EVALUATE".
05 FILLER PIC X(33) VALUE " END-IF".
05 FILLER PIC X(33) VALUE " END-MULTIPLY".
05 FILLER PIC X(33) VALUE " END-OF-PAGE".
05 FILLER PIC X(33) VALUE " END-PERFORM".
05 FILLER PIC X(33) VALUE " END-READ".
05 FILLER PIC X(33) VALUE " END-RETURN".
05 FILLER PIC X(33) VALUE " END-REWRITE".
05 FILLER PIC X(33) VALUE " END-SEARCH".
05 FILLER PIC X(33) VALUE " END-START".
05 FILLER PIC X(33) VALUE " END-STRING".
05 FILLER PIC X(33) VALUE " END-SUBTRACT".
05 FILLER PIC X(33) VALUE " END-UNSTRING".
05 FILLER PIC X(33) VALUE " END-WRITE".
05 FILLER PIC X(33) VALUE "VENTRY".
05 FILLER PIC X(33) VALUE "KENVIRONMENT".
05 FILLER PIC X(33) VALUE " ENVIRONMENT-NAME".
05 FILLER PIC X(33) VALUE " ENVIRONMENT-VALUE".
05 FILLER PIC X(33) VALUE " EO".
05 FILLER PIC X(33) VALUE " EOL".
05 FILLER PIC X(33) VALUE " EOP".
05 FILLER PIC X(33) VALUE " EOS".
05 FILLER PIC X(33) VALUE " EQUAL".
05 FILLER PIC X(33) VALUE "KEQUALS".
05 FILLER PIC X(33) VALUE " ERASE".
05 FILLER PIC X(33) VALUE " ERROR".
05 FILLER PIC X(33) VALUE " ESCAPE".
05 FILLER PIC X(33) VALUE "VEVALUATE".

06FEB2009 Version

Page 8-29

OpenCOBOL 1.1 Programmers Guide

Sample Programs

05 FILLER PIC X(33) VALUE " EXCEPTION".
05 FILLER PIC X(33) VALUE "IEXCEPTION-FILE".
05 FILLER PIC X(33) VALUE "IEXCEPTION-LOCATION".
05 FILLER PIC X(33) VALUE " EXCEPTION-OBJECT".
05 FILLER PIC X(33) VALUE "IEXCEPTION-STATEMENT".
05 FILLER PIC X(33) VALUE "IEXCEPTION-STATUS".
05 FILLER PIC X(33) VALUE " EXCLUSIVE".
05 FILLER PIC X(33) VALUE "VEXIT".
05 FILLER PIC X(33) VALUE "IEXP".
05 FILLER PIC X(33) VALUE "IEXP10".
05 FILLER PIC X(33) VALUE " EXTEND".
05 FILLER PIC X(33) VALUE " EXTERNAL".
05 FILLER PIC X(33) VALUE "IFACTORIAL".
05 FILLER PIC X(33) VALUE " FACTORY".
05 FILLER PIC X(33) VALUE " FALSE".
05 FILLER PIC X(33) VALUE "KFD".
05 FILLER PIC X(33) VALUE "KFILE".
05 FILLER PIC X(33) VALUE " FILE-CONTROL".
05 FILLER PIC X(33) VALUE " FILE-ID".
05 FILLER PIC X(33) VALUE " FILLER".
05 FILLER PIC X(33) VALUE " FINAL".
05 FILLER PIC X(33) VALUE " FIRST".
05 FILLER PIC X(33) VALUE " FLOAT-BINARY-16".
05 FILLER PIC X(33) VALUE " FLOAT-BINARY-34".
05 FILLER PIC X(33) VALUE " FLOAT-BINARY-7".
05 FILLER PIC X(33) VALUE " FLOAT-DECIMAL-16".
05 FILLER PIC X(33) VALUE " FLOAT-DECIMAL-34".
05 FILLER PIC X(33) VALUE " FLOAT-EXTENDED".
05 FILLER PIC X(33) VALUE " FLOAT-LONG".
05 FILLER PIC X(33) VALUE " FLOAT-SHORT".
05 FILLER PIC X(33) VALUE " FOOTING".
05 FILLER PIC X(33) VALUE " FOR".
05 FILLER PIC X(33) VALUE " FOREGROUND-COLOR".
05 FILLER PIC X(33) VALUE " FOREVER".
05 FILLER PIC X(33) VALUE " FORMAT".
05 FILLER PIC X(33) VALUE "MFORMFEED".
05 FILLER PIC X(33) VALUE "IFRACTION-PART".
05 FILLER PIC X(33) VALUE "VFREE".
05 FILLER PIC X(33) VALUE " FROM".
05 FILLER PIC X(33) VALUE " FULL".
05 FILLER PIC X(33) VALUE " FUNCTION".
05 FILLER PIC X(33) VALUE " FUNCTION-ID".
05 FILLER PIC X(33) VALUE " FUNCTION-POINTER".
05 FILLER PIC X(33) VALUE "VGENERATE".
05 FILLER PIC X(33) VALUE " GET".
05 FILLER PIC X(33) VALUE "KGIVING".
05 FILLER PIC X(33) VALUE " GLOBAL".
05 FILLER PIC X(33) VALUE "VGO".
05 FILLER PIC X(33) VALUE "VGOBACK".
05 FILLER PIC X(33) VALUE " GREATER".
05 FILLER PIC X(33) VALUE " GROUP".
05 FILLER PIC X(33) VALUE " GROUP-USAGE".
05 FILLER PIC X(33) VALUE " HEADING".
05 FILLER PIC X(33) VALUE " HIGH-VALUE".
05 FILLER PIC X(33) VALUE " HIGH-VALUES".
05 FILLER PIC X(33) VALUE " HIGHLIGHT".
05 FILLER PIC X(33) VALUE " I-O".
05 FILLER PIC X(33) VALUE " I-O-CONTROL".
05 FILLER PIC X(33) VALUE "KID".
05 FILLER PIC X(33) VALUE "KIDENTIFICATION".
05 FILLER PIC X(33) VALUE "VIF".
05 FILLER PIC X(33) VALUE " IGNORE".
05 FILLER PIC X(33) VALUE " IGNORING".
05 FILLER PIC X(33) VALUE " IN".
05 FILLER PIC X(33) VALUE " INDEX".
05 FILLER PIC X(33) VALUE "KINDEXED".
05 FILLER PIC X(33) VALUE " INDICATE".
05 FILLER PIC X(33) VALUE " INFINITY".
05 FILLER PIC X(33) VALUE " INHERITS".
05 FILLER PIC X(33) VALUE " INITIAL".
05 FILLER PIC X(33) VALUE " INITIALISED".
05 FILLER PIC X(33) VALUE "VINITIALIZE".
05 FILLER PIC X(33) VALUE " INITIALIZED".
05 FILLER PIC X(33) VALUE "VINITIATE".
05 FILLER PIC X(33) VALUE " INPUT".
05 FILLER PIC X(33) VALUE "KINPUT-OUTPUT".
05 FILLER PIC X(33) VALUE "VINSPECT".
05 FILLER PIC X(33) VALUE " INSTALLATION".
05 FILLER PIC X(33) VALUE "IINTEGER".
05 FILLER PIC X(33) VALUE "IINTEGER-OF-DATE".
05 FILLER PIC X(33) VALUE "IINTEGER-OF-DAY".
05 FILLER PIC X(33) VALUE "IINTEGER-PART".
05 FILLER PIC X(33) VALUE " INTERFACE".
05 FILLER PIC X(33) VALUE " INTERFACE-ID".

06FEB2009 Version

Page 8-30

OpenCOBOL 1.1 Programmers Guide

Sample Programs

05 FILLER PIC X(33) VALUE "KINTO".
05 FILLER PIC X(33) VALUE " INTRINSIC".
05 FILLER PIC X(33) VALUE " INVALID".
05 FILLER PIC X(33) VALUE " INVOKE".
05 FILLER PIC X(33) VALUE " IS".
05 FILLER PIC X(33) VALUE " JUST".
05 FILLER PIC X(33) VALUE " JUSTIFIED".
05 FILLER PIC X(33) VALUE " KEY".
05 FILLER PIC X(33) VALUE " LABEL".
05 FILLER PIC X(33) VALUE " LAST".
05 FILLER PIC X(33) VALUE " LEADING".
05 FILLER PIC X(33) VALUE " LEFT".
05 FILLER PIC X(33) VALUE " LEFT-JUSTIFY".
05 FILLER PIC X(33) VALUE "ILENGTH".
05 FILLER PIC X(33) VALUE " LESS".
05 FILLER PIC X(33) VALUE " LIMIT".
05 FILLER PIC X(33) VALUE " LIMITS".
05 FILLER PIC X(33) VALUE " LINAGE".
05 FILLER PIC X(33) VALUE "ILINAGE-COUNTER".
05 FILLER PIC X(33) VALUE " LINE".
05 FILLER PIC X(33) VALUE " LINE-COUNTER".
05 FILLER PIC X(33) VALUE " LINES".
05 FILLER PIC X(33) VALUE "KLINKAGE".
05 FILLER PIC X(33) VALUE "KLOCAL-STORAGE".
05 FILLER PIC X(33) VALUE " LOCALE".
05 FILLER PIC X(33) VALUE "ILOCALE-DATE".
05 FILLER PIC X(33) VALUE "ILOCALE-TIME".
05 FILLER PIC X(33) VALUE "ILOCALE-TIME-FROM-SECONDS".
05 FILLER PIC X(33) VALUE " LOCK".
05 FILLER PIC X(33) VALUE "ILOG".
05 FILLER PIC X(33) VALUE "ILOG10".
05 FILLER PIC X(33) VALUE " LOW-VALUE".
05 FILLER PIC X(33) VALUE " LOW-VALUES".
05 FILLER PIC X(33) VALUE " LOWER".
05 FILLER PIC X(33) VALUE "ILOWER-CASE".
05 FILLER PIC X(33) VALUE " LOWLIGHT".
05 FILLER PIC X(33) VALUE " MANUAL".
05 FILLER PIC X(33) VALUE "IMAX".
05 FILLER PIC X(33) VALUE "IMEAN".
05 FILLER PIC X(33) VALUE "IMEDIAN".
05 FILLER PIC X(33) VALUE " MEMORY".
05 FILLER PIC X(33) VALUE "VMERGE".
05 FILLER PIC X(33) VALUE " METHOD".
05 FILLER PIC X(33) VALUE " METHOD-ID".
05 FILLER PIC X(33) VALUE "IMIDRANGE".
05 FILLER PIC X(33) VALUE "IMIN".
05 FILLER PIC X(33) VALUE " MINUS".
05 FILLER PIC X(33) VALUE "IMOD".
05 FILLER PIC X(33) VALUE " MODE".
05 FILLER PIC X(33) VALUE "VMOVE".
05 FILLER PIC X(33) VALUE " MULTIPLE".
05 FILLER PIC X(33) VALUE "VMULTIPLY".
05 FILLER PIC X(33) VALUE " NATIONAL".
05 FILLER PIC X(33) VALUE " NATIONAL-EDITED".
05 FILLER PIC X(33) VALUE " NATIVE".
05 FILLER PIC X(33) VALUE " NEGATIVE".
05 FILLER PIC X(33) VALUE " NESTED".
05 FILLER PIC X(33) VALUE "VNEXT".
05 FILLER PIC X(33) VALUE " NO".
05 FILLER PIC X(33) VALUE " NOT".
05 FILLER PIC X(33) VALUE " NULL".
05 FILLER PIC X(33) VALUE " NULLS".
05 FILLER PIC X(33) VALUE " NUMBER".
05 FILLER PIC X(33) VALUE "INUMBER-OF-CALL-PARAMETERS".
05 FILLER PIC X(33) VALUE " NUMBERS".
05 FILLER PIC X(33) VALUE " NUMERIC".
05 FILLER PIC X(33) VALUE " NUMERIC-EDITED".
05 FILLER PIC X(33) VALUE "INUMVAL".
05 FILLER PIC X(33) VALUE "INUMVAL-C".
05 FILLER PIC X(33) VALUE " OBJECT".
05 FILLER PIC X(33) VALUE " OBJECT-COMPUTER".
05 FILLER PIC X(33) VALUE " OBJECT-REFERENCE".
05 FILLER PIC X(33) VALUE " OCCURS".
05 FILLER PIC X(33) VALUE " OF".
05 FILLER PIC X(33) VALUE " OFF".
05 FILLER PIC X(33) VALUE " OMITTED".
05 FILLER PIC X(33) VALUE " ON".
05 FILLER PIC X(33) VALUE " ONLY".
05 FILLER PIC X(33) VALUE "VOPEN".
05 FILLER PIC X(33) VALUE " OPTIONAL".
05 FILLER PIC X(33) VALUE " OPTIONS".
05 FILLER PIC X(33) VALUE " OR".
05 FILLER PIC X(33) VALUE "IORD".
05 FILLER PIC X(33) VALUE "IORD-MAX".

06FEB2009 Version

Page 8-31

OpenCOBOL 1.1 Programmers Guide

Sample Programs

05 FILLER PIC X(33) VALUE "IORD-MIN".
05 FILLER PIC X(33) VALUE " ORDER".
05 FILLER PIC X(33) VALUE " ORGANIZATION".
05 FILLER PIC X(33) VALUE " OTHER".
05 FILLER PIC X(33) VALUE " OUTPUT".
05 FILLER PIC X(33) VALUE " OVERFLOW".
05 FILLER PIC X(33) VALUE " OVERLINE".
05 FILLER PIC X(33) VALUE " OVERRIDE".
05 FILLER PIC X(33) VALUE " PACKED-DECIMAL".
05 FILLER PIC X(33) VALUE " PADDING".
05 FILLER PIC X(33) VALUE " PAGE".
05 FILLER PIC X(33) VALUE " PAGE-COUNTER".
05 FILLER PIC X(33) VALUE " PARAGRAPH".
05 FILLER PIC X(33) VALUE "VPERFORM".
05 FILLER PIC X(33) VALUE " PF".
05 FILLER PIC X(33) VALUE " PH".
05 FILLER PIC X(33) VALUE "IPI".
05 FILLER PIC X(33) VALUE "KPIC".
05 FILLER PIC X(33) VALUE "KPICTURE".
05 FILLER PIC X(33) VALUE " PLUS".
05 FILLER PIC X(33) VALUE "KPOINTER".
05 FILLER PIC X(33) VALUE " POSITION".
05 FILLER PIC X(33) VALUE " POSITIVE".
05 FILLER PIC X(33) VALUE " PRESENT".
05 FILLER PIC X(33) VALUE "IPRESENT-VALUE".
05 FILLER PIC X(33) VALUE " PREVIOUS".
05 FILLER PIC X(33) VALUE "MPRINTER".
05 FILLER PIC X(33) VALUE " PRINTING".
05 FILLER PIC X(33) VALUE "KPROCEDURE".
05 FILLER PIC X(33) VALUE " PROCEDURE-POINTER".
05 FILLER PIC X(33) VALUE " PROCEDURES".
05 FILLER PIC X(33) VALUE " PROCEED".
05 FILLER PIC X(33) VALUE " PROGRAM".
05 FILLER PIC X(33) VALUE "KPROGRAM-ID".
05 FILLER PIC X(33) VALUE " PROGRAM-POINTER".
05 FILLER PIC X(33) VALUE " PROMPT".
05 FILLER PIC X(33) VALUE " PROPERTY".
05 FILLER PIC X(33) VALUE " PROTOTYPE".
05 FILLER PIC X(33) VALUE " QUOTE".
05 FILLER PIC X(33) VALUE " QUOTES".
05 FILLER PIC X(33) VALUE " RAISE".
05 FILLER PIC X(33) VALUE " RAISING".
05 FILLER PIC X(33) VALUE "IRANDOM".
05 FILLER PIC X(33) VALUE "IRANGE".
05 FILLER PIC X(33) VALUE " RD".
05 FILLER PIC X(33) VALUE "VREAD".
05 FILLER PIC X(33) VALUE "VREADY".
05 FILLER PIC X(33) VALUE " RECORD".
05 FILLER PIC X(33) VALUE " RECORDING".
05 FILLER PIC X(33) VALUE " RECORDS".
05 FILLER PIC X(33) VALUE " RECURSIVE".
05 FILLER PIC X(33) VALUE "KREDEFINES".
05 FILLER PIC X(33) VALUE " REEL".
05 FILLER PIC X(33) VALUE " REFERENCE".
05 FILLER PIC X(33) VALUE " RELATIVE".
05 FILLER PIC X(33) VALUE "VRELEASE".
05 FILLER PIC X(33) VALUE "IREM".
05 FILLER PIC X(33) VALUE " REMAINDER".
05 FILLER PIC X(33) VALUE " REMARKS".
05 FILLER PIC X(33) VALUE " REMOVAL".
05 FILLER PIC X(33) VALUE "KRENAMES".
05 FILLER PIC X(33) VALUE "KREPLACING".
05 FILLER PIC X(33) VALUE "KREPORT".
05 FILLER PIC X(33) VALUE " REPORTING".
05 FILLER PIC X(33) VALUE " REPORTS".
05 FILLER PIC X(33) VALUE " REPOSITORY".
05 FILLER PIC X(33) VALUE " REPRESENTS-NOT-A-NUMBER".
05 FILLER PIC X(33) VALUE " REQUIRED".
05 FILLER PIC X(33) VALUE " RESERVE".
05 FILLER PIC X(33) VALUE " RESUME".
05 FILLER PIC X(33) VALUE " RETRY".
05 FILLER PIC X(33) VALUE "VRETURN".
05 FILLER PIC X(33) VALUE "IRETURN-CODE".
05 FILLER PIC X(33) VALUE "KRETURNING".
05 FILLER PIC X(33) VALUE "IREVERSE".
05 FILLER PIC X(33) VALUE " REVERSE-VIDEO".
05 FILLER PIC X(33) VALUE " REWIND".
05 FILLER PIC X(33) VALUE "VREWRITE".
05 FILLER PIC X(33) VALUE " RF".
05 FILLER PIC X(33) VALUE " RH".
05 FILLER PIC X(33) VALUE " RIGHT".
05 FILLER PIC X(33) VALUE " RIGHT-JUSTIFY".
05 FILLER PIC X(33) VALUE "VROLLBACK".
05 FILLER PIC X(33) VALUE " ROUNDED".

06FEB2009 Version

Page 8-32

OpenCOBOL 1.1 Programmers Guide

Sample Programs

05 FILLER PIC X(33) VALUE " RUN".
05 FILLER PIC X(33) VALUE " SAME".
05 FILLER PIC X(33) VALUE "KSCREEN".
05 FILLER PIC X(33) VALUE " SCROLL".
05 FILLER PIC X(33) VALUE "KSD".
05 FILLER PIC X(33) VALUE "VSEARCH".
05 FILLER PIC X(33) VALUE "ISECONDS-FROM-FORMATTED-TIME".
05 FILLER PIC X(33) VALUE "ISECONDS-PAST-MIDNIGHT".
05 FILLER PIC X(33) VALUE "KSECTION".
05 FILLER PIC X(33) VALUE " SECURE".
05 FILLER PIC X(33) VALUE " SECURITY".
05 FILLER PIC X(33) VALUE " SEGMENT-LIMIT".
05 FILLER PIC X(33) VALUE " SELECT".
05 FILLER PIC X(33) VALUE " SELF".
05 FILLER PIC X(33) VALUE " SENTENCE".
05 FILLER PIC X(33) VALUE " SEPARATE".
05 FILLER PIC X(33) VALUE " SEQUENCE".
05 FILLER PIC X(33) VALUE " SEQUENTIAL".
05 FILLER PIC X(33) VALUE "VSET".
05 FILLER PIC X(33) VALUE " SHARING".
05 FILLER PIC X(33) VALUE "ISIGN".
05 FILLER PIC X(33) VALUE " SIGNED".
05 FILLER PIC X(33) VALUE " SIGNED-INT".
05 FILLER PIC X(33) VALUE " SIGNED-LONG".
05 FILLER PIC X(33) VALUE " SIGNED-SHORT".
05 FILLER PIC X(33) VALUE "ISIN".
05 FILLER PIC X(33) VALUE " SIZE".
05 FILLER PIC X(33) VALUE "VSORT".
05 FILLER PIC X(33) VALUE " SORT-MERGE".
05 FILLER PIC X(33) VALUE "ISORT-RETURN".
05 FILLER PIC X(33) VALUE " SOURCE".
05 FILLER PIC X(33) VALUE " SOURCE-COMPUTER".
05 FILLER PIC X(33) VALUE " SOURCES".
05 FILLER PIC X(33) VALUE " SPACE".
05 FILLER PIC X(33) VALUE " SPACE-FILL".
05 FILLER PIC X(33) VALUE " SPACES".
05 FILLER PIC X(33) VALUE " SPECIAL-NAMES".
05 FILLER PIC X(33) VALUE "ISQRT".
05 FILLER PIC X(33) VALUE " STANDARD".
05 FILLER PIC X(33) VALUE " STANDARD-1".
05 FILLER PIC X(33) VALUE " STANDARD-2".
05 FILLER PIC X(33) VALUE "ISTANDARD-DEVIATION".
05 FILLER PIC X(33) VALUE "VSTART".
05 FILLER PIC X(33) VALUE " STATUS".
05 FILLER PIC X(33) VALUE "VSTOP".
05 FILLER PIC X(33) VALUE "ISTORED-CHAR-LENGTH".
05 FILLER PIC X(33) VALUE "VSTRING".
05 FILLER PIC X(33) VALUE "ISUBSTITUTE".
05 FILLER PIC X(33) VALUE "ISUBSTITUTE-CASE".
05 FILLER PIC X(33) VALUE "VSUBTRACT".
05 FILLER PIC X(33) VALUE "ISUM".
05 FILLER PIC X(33) VALUE " SUPER".
05 FILLER PIC X(33) VALUE "VSUPPRESS".
05 FILLER PIC X(33) VALUE "MSWITCH-1".
05 FILLER PIC X(33) VALUE "MSWITCH-2".
05 FILLER PIC X(33) VALUE "MSWITCH-3".
05 FILLER PIC X(33) VALUE "MSWITCH-4".
05 FILLER PIC X(33) VALUE "MSWITCH-5".
05 FILLER PIC X(33) VALUE "MSWITCH-6".
05 FILLER PIC X(33) VALUE "MSWITCH-7".
05 FILLER PIC X(33) VALUE "MSWITCH-8".
05 FILLER PIC X(33) VALUE " SYMBOLIC".
05 FILLER PIC X(33) VALUE " SYNC".
05 FILLER PIC X(33) VALUE " SYNCHRONIZED".
05 FILLER PIC X(33) VALUE "MSYSERR".
05 FILLER PIC X(33) VALUE "MSYSIN".
05 FILLER PIC X(33) VALUE "MSYSIPT".
05 FILLER PIC X(33) VALUE "MSYSLIST".
05 FILLER PIC X(33) VALUE "MSYSLST".
05 FILLER PIC X(33) VALUE "MSYSOUT".
05 FILLER PIC X(33) VALUE " SYSTEM-DEFAULT".
05 FILLER PIC X(33) VALUE " TABLE".
05 FILLER PIC X(33) VALUE "KTALLYING".
05 FILLER PIC X(33) VALUE "ITAN".
05 FILLER PIC X(33) VALUE " TAPE".
05 FILLER PIC X(33) VALUE "VTERMINATE".
05 FILLER PIC X(33) VALUE " TEST".
05 FILLER PIC X(33) VALUE "ITEST-DATE-YYYYMMDD".
05 FILLER PIC X(33) VALUE "ITEST-DAY-YYYYDDD".
05 FILLER PIC X(33) VALUE " THAN".
05 FILLER PIC X(33) VALUE " THEN".
05 FILLER PIC X(33) VALUE " THROUGH".
05 FILLER PIC X(33) VALUE " THRU".
05 FILLER PIC X(33) VALUE " TIME".

06FEB2009 Version

Page 8-33

OpenCOBOL 1.1 Programmers Guide

01

Sample Programs

05 FILLER PIC X(33) VALUE " TIMES".
05 FILLER PIC X(33) VALUE "KTO".
05 FILLER PIC X(33) VALUE " TOP".
05 FILLER PIC X(33) VALUE " TRAILING".
05 FILLER PIC X(33) VALUE " TRAILING-SIGN".
05 FILLER PIC X(33) VALUE "VTRANSFORM".
05 FILLER PIC X(33) VALUE "ITRIM".
05 FILLER PIC X(33) VALUE " TRUE".
05 FILLER PIC X(33) VALUE " TYPE".
05 FILLER PIC X(33) VALUE " TYPEDEF".
05 FILLER PIC X(33) VALUE " UNDERLINE".
05 FILLER PIC X(33) VALUE " UNIT".
05 FILLER PIC X(33) VALUE " UNIVERSAL".
05 FILLER PIC X(33) VALUE "VUNLOCK".
05 FILLER PIC X(33) VALUE " UNSIGNED".
05 FILLER PIC X(33) VALUE " UNSIGNED-INT".
05 FILLER PIC X(33) VALUE " UNSIGNED-LONG".
05 FILLER PIC X(33) VALUE " UNSIGNED-SHORT".
05 FILLER PIC X(33) VALUE "VUNSTRING".
05 FILLER PIC X(33) VALUE " UNTIL".
05 FILLER PIC X(33) VALUE "KUP".
05 FILLER PIC X(33) VALUE " UPDATE".
05 FILLER PIC X(33) VALUE " UPON".
05 FILLER PIC X(33) VALUE " UPPER".
05 FILLER PIC X(33) VALUE "IUPPER-CASE".
05 FILLER PIC X(33) VALUE " USAGE".
05 FILLER PIC X(33) VALUE "VUSE".
05 FILLER PIC X(33) VALUE " USER-DEFAULT".
05 FILLER PIC X(33) VALUE "KUSING".
05 FILLER PIC X(33) VALUE " VAL-STATUS".
05 FILLER PIC X(33) VALUE " VALID".
05 FILLER PIC X(33) VALUE " VALIDATE".
05 FILLER PIC X(33) VALUE " VALIDATE-STATUS".
05 FILLER PIC X(33) VALUE " VALUE".
05 FILLER PIC X(33) VALUE " VALUES".
05 FILLER PIC X(33) VALUE "IVARIANCE".
05 FILLER PIC X(33) VALUE "KVARYING".
05 FILLER PIC X(33) VALUE " WAIT".
05 FILLER PIC X(33) VALUE "VWHEN".
05 FILLER PIC X(33) VALUE "IWHEN-COMPILED".
05 FILLER PIC X(33) VALUE " WITH".
05 FILLER PIC X(33) VALUE " WORDS".
05 FILLER PIC X(33) VALUE "KWORKING-STORAGE".
05 FILLER PIC X(33) VALUE "VWRITE".
05 FILLER PIC X(33) VALUE "IYEAR-TO-YYYY".
05 FILLER PIC X(33) VALUE " YYYYDDD".
05 FILLER PIC X(33) VALUE " YYYYMMDD".
05 FILLER PIC X(33) VALUE " ZERO".
05 FILLER PIC X(33) VALUE " ZERO-FILL".
05 FILLER PIC X(33) VALUE " ZEROES".
05 FILLER PIC X(33) VALUE " ZEROS".
Reserved-Word-Table
REDEFINES Reserved-Words.
05 Reserved-Word
OCCURS 591 TIMESASCENDING KEY RW-Word
INDEXED RW-Idx.
10 RW-TypePIC X(1).
10 RW-Word
PIC X(32).

01

Saved-Section

PIC X(15).

01

Search-TokenPIC X(32).

01

Source-Line-No

PIC 9(6).

01

Src-Ptr

USAGE BINARY-LONG.

01

Syntax-Parsing-Items.
05 SPI-Current-Char
PIC X(1).
88 Current-Char-Is-Punct VALUE "=", "(", ")", "*", "/","&", ";", ",", "<", ">",":".
88 Current-Char-Is-Quote VALUE '"', "'".
88 Current-Char-Is-X
VALUE "x", "X".
88 Current-Char-Is-Z
VALUE "z", "Z".
05 SPI-Current-Division
PIC X(1).
88 In-IDENTIFICATION-DIVISION VALUE "I", "?".
88 In-ENVIRONMENT-DIVISIONVALUE "E".
88 In-DATA-DIVISIONVALUE "D".
88 In-PROCEDURE-DIVISIONVALUE "P".
05 SPI-Current-Line-No
PIC 9(6).
05 SPI-Current-Program-ID.
10 FILLER
PIC X(12).
10 SPI-CP-13-15
PIC X(3).
05 SPI-Current-Section.

06FEB2009 Version

Page 8-34

OpenCOBOL 1.1 Programmers Guide

Sample Programs

10 SPI-CS-1
PIC X(1).
10 SPI-CS-2-14.
15 FILLER
PIC X(10).
15 SPI-CS-11-14
PIC X(3).
10 SPI-CS-15
PIC X(1).
05 SPI-Current-TokenPIC X(32).
05 SPI-Current-Token-UC
PIC X(32).
05 SPI-Current-Verb
PIC X(12).
05 SPI-Next-Char
PIC X(1).
88 Next-Char-Is-Quote
VALUE '"', "'".
05 SPI-Prior-TokenPIC X(32).
05 SPI-Token-TypePIC X(1).
88 Token-Is-EOF
VALUE HIGH-VALUES.
88 Token-Is-Identifier
VALUE "I".
88 Token-Is-Key-Word
VALUE "K", "V".
88 Token-Is-Literal-Alpha
VALUE "L".
88 Token-Is-Literal-Number VALUE "N".
88 Token-Is-Verb
VALUE "V".
01

Tally

USAGE BINARY-LONG.

01

Todays-Date

PIC 9(8).

LINKAGE SECTION.
01 Produce-Source-Listing
01 Produce-Xref-Listing
01 Src-Filename

PIC X(1).
PIC X(1).
PIC X(256).

//

PROCEDURE DIVISION USING Produce-Source-Listing
Produce-Xref-Listing
Src-Filename.
000-Main SECTION.
001-Init.
PERFORM 100-Initialization
PERFORM 200-Execute-cobc
OPEN OUTPUT Report-File
IF Produce-Source-Listing NOT = SPACEPERFORM 500-Produce-Source-Listing
END-IFIF Produce-Xref-Listing NOT = SPACESORT Sort-FileASCENDING KEY
SR-Prog-ID
SR-Token-UC
SR-Line-No-Ref
INPUT PROCEDURE 300-Tokenize-Source
OUTPUT PROCEDURE 400-Produce-Xref-Listing
END-IF
CLOSE Report-File
GOBACK.

100-Initialization SECTION.
******************************************************************* Perform all program-wide initialization operations*******************************************************************
101-Establish-Working-Env.
MOVE TRIM(Src-Filename,Leading) TO Src-Filename
ACCEPT Env-TEMP
FROM ENVIRONMENT "TEMP"END-ACCEPTACCEPT Lines-Per-Page-ENVFROM ENVIRONMENT "OCXREF_LINES"
END-ACCEPTINSPECT Src-Filename REPLACING ALL "\" BY "/"INSPECT Env-TEMP REPLACING ALL "\" BY "/"MOVE Src-Filename TO Program-Path
MOVE Program-Path TO Heading-2
CALL "C$JUSTIFY"
USING Heading-2, "Right"
END-CALLMOVE LENGTH(TRIM(Src-Filename,Trailing)) TO I
MOVE 0 TO JPERFORM UNTIL Src-Filename(I:1) = '/'OR I = 0
SUBTRACT 1 FROM I
ADD
1 TO
J
END-PERFORM
UNSTRING Src-Filename((I + 1):J) DELIMITED BY "."INTO Filename, Dummy
END-UNSTRING
STRING TRIM(Env-TEMP,Trailing)"/"
TRIM(Filename,Trailing)".i"

06FEB2009 Version

Page 8-35

OpenCOBOL 1.1 Programmers Guide

Sample Programs

DELIMITED SIZE
INTO Expanded-Src-Filename
END-STRING
STRING Program-Path(1:I)
TRIM(Filename,Trailing)".lst"
DELIMITED SIZE
INTO Report-Filename
END-STRING
IF Lines-Per-Page-ENV NOT = SPACES
MOVE NUMVAL(Lines-Per-Page-ENV) TO Lines-Per-Page
ELSE
MOVE 60 TO Lines-Per-Page
END-IF
ACCEPT Todays-Date
FROM DATE YYYYMMDD
END-ACCEPTMOVE Todays-Date TO H1X-Date
H1S-Date
MOVE "????????????..." TO SPI-Current-Program-ID
MOVE SPACESTO SPI-Current-Verb
Held-Reference
MOVE "Y" TO F-First-Record.
/
200-Execute-cobc SECTION.
201-Build-Cmd.
STRING "cobc -E "TRIM(Program-Path, Trailing)" > "TRIM(Expanded-Src-Filename,Trailing)
DELIMITED SIZE
INTO Cmd
END-STRINGCALL "SYSTEM"USING Cmd
END-CALLIF RETURN-CODE NOT = 0
DISPLAY"Cross-reference terminated by previous errors"
UPON SYSERR
END-DISPLAYGOBACK
END-IF.
209-Exit.
EXIT.
/

300-Tokenize-Source SECTION.
301-Driver.
OPEN INPUT Expand-Code
MOVE SPACES TO Expand-Code-Rec
MOVE 256 TO Src-Ptr
MOVE 0 TO Num-UserNames
SPI-Current-Line-No
MOVE "?" TO SPI-Current-Division
PERFORM FOREVERPERFORM 310-Get-Token
IF Token-Is-EOF
EXIT PERFORM
END-IF
MOVE UPPER-CASE(SPI-Current-Token)
TO SPI-Current-Token-UC
IF Token-Is-Verb
MOVE SPI-Current-Token-UC TO SPI-Current-Verb
SPI-Prior-Token
IF Held-Reference NOT = SPACES
MOVE Held-Reference TO Sort-Rec
MOVE SPACESTO Held-Reference
RELEASE Sort-Rec
END-IF
END-IFEVALUATE TRUE
WHEN In-IDENTIFICATION-DIVISIONPERFORM 320-IDENTIFICATION-DIVISION
WHEN In-ENVIRONMENT-DIVISIONPERFORM 330-ENVIRONMENT-DIVISION
WHEN In-DATA-DIVISIONPERFORM 340-DATA-DIVISION
WHEN In-PROCEDURE-DIVISIONPERFORM 350-PROCEDURE-DIVISION
END-EVALUATE

06FEB2009 Version

Page 8-36

OpenCOBOL 1.1 Programmers Guide

Sample Programs

IF Token-Is-Key-Word
MOVE SPI-Current-Token-UC TO SPI-Prior-Token
END-IFIF F-Token-Ended-Sentence = "Y"AND SPI-Current-Division NOT = "I"
MOVE SPACES TO SPI-Prior-Token
SPI-Current-Verb
END-IF
END-PERFORM
CLOSE Expand-Code
EXIT SECTION.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
310-Get-Token.
*>-- Position to 1st non-blank character
MOVE F-Token-Ended-Sentence TO F-Last-Token-Ended-Sent
MOVE "N" TO F-Token-Ended-Sentence
PERFORM UNTIL Expand-Code-Rec(Src-Ptr : 1) NOT = SPACE
IF Src-Ptr > 255
READ Expand-Code AT END
IF Held-Reference NOT = SPACES
MOVE Held-Reference TO Sort-Rec
MOVE SPACESTO Held-Reference
RELEASE Sort-Rec
END-IFSET Token-Is-EOF TO TRUE
MOVE 0 TO SPI-Current-Line-No
EXIT PARAGRAPH
END-READ
IF ECR-1 = "#"PERFORM 311-Control-Record
ELSE
PERFORM 312-Expand-Code-Record
END-IFELSE
ADD 1 TO Src-Ptr
END-IF
END-PERFORM*>-- Extract token string
MOVE Expand-Code-Rec(Src-Ptr : 1)
TO SPI-Current-Char
MOVE Expand-Code-Rec(Src-Ptr + 1: 1) TO SPI-Next-Char
IF SPI-Current-Char = "."ADD 1 TO Src-Ptr
MOVE SPI-Current-Char TO SPI-Current-Token
MOVE SPACE TO SPI-Token-Type
MOVE "Y" TO F-Token-Ended-Sentence
EXIT PARAGRAPH
END-IFIF Current-Char-Is-Punct
AND SPI-Current-Char = "="AND SPI-Current-Division = "P"ADD 1 TO Src-Ptr
MOVE "EQUALS" TO SPI-Current-Token
MOVE "K"TO SPI-Token-Type
EXIT PARAGRAPH
END-IFIF Current-Char-Is-Punct *> So subscripts don't get flagged w/ "*"AND SPI-Current-Char = "("AND SPI-Current-Division = "P"
MOVE SPACES TO SPI-Prior-Token
END-IFIF Current-Char-Is-Punct
ADD 1 TO Src-Ptr
MOVE SPI-Current-Char TO SPI-Current-Token
MOVE SPACE TO SPI-Token-Type
EXIT PARAGRAPH
END-IFIF Current-Char-Is-Quote
ADD 1 TO Src-Ptr
UNSTRING Expand-Code-Rec
DELIMITED BY SPI-Current-Char
INTO SPI-Current-Token
WITH POINTER Src-Ptr
END-UNSTRING
IF Expand-Code-Rec(Src-Ptr : 1) = "."MOVE "Y" TO F-Token-Ended-Sentence
ADD 1 TO Src-Ptr
END-IFSET Token-Is-Literal-Alpha TO TRUE
EXIT PARAGRAPH
END-IFIF Current-Char-Is-X AND Next-Char-Is-QuoteADD 2 TO Src-Ptr

06FEB2009 Version

Page 8-37

OpenCOBOL 1.1 Programmers Guide

Sample Programs

UNSTRING Expand-Code-Rec
DELIMITED BY SPI-Next-Char
INTO SPI-Current-Token
WITH POINTER Src-Ptr
END-UNSTRING
IF Expand-Code-Rec(Src-Ptr : 1) = "."MOVE "Y" TO F-Token-Ended-Sentence
ADD 1 TO Src-Ptr
END-IFSET Token-Is-Literal-Number TO TRUE
EXIT PARAGRAPH
END-IFIF Current-Char-Is-Z AND Next-Char-Is-QuoteADD 2 TO Src-Ptr
UNSTRING Expand-Code-Rec
DELIMITED BY SPI-Next-Char
INTO SPI-Current-Token
WITH POINTER Src-Ptr
END-UNSTRING
IF Expand-Code-Rec(Src-Ptr : 1) = "."MOVE "Y" TO F-Token-Ended-Sentence
ADD 1 TO Src-Ptr
END-IFSET Token-Is-Literal-Alpha TO TRUE
EXIT PARAGRAPH
END-IFIF F-Processing-PICTURE = "Y"UNSTRING Expand-Code-Rec
DELIMITED BY ". " OR " "INTO SPI-Current-Token
DELIMITER IN Delim
WITH POINTER Src-Ptr
END-UNSTRINGIF Delim = ". "MOVE "Y" TO F-Token-Ended-Sentence
ADD 1 TO Src-Ptr
END-IFIF UPPER-CASE(SPI-Current-Token) = "IS"MOVE SPACE TO SPI-Token-Type
EXIT PARAGRAPH
ELSE
MOVE "N" TO F-Processing-PICTURE
MOVE SPACE TO SPI-Token-Type
EXIT PARAGRAPH
END-IF
END-IF
UNSTRING Expand-Code-Rec
DELIMITED BY ". " OR " " OR "=" OR "(" OR ")" OR "*"OR "/" OR "&" OR ";" OR "," OR "<"OR ">" OR ":"INTO SPI-Current-Token
DELIMITER IN Delim
WITH POINTER Src-Ptr
END-UNSTRINGIF Delim = ". "MOVE "Y" TO F-Token-Ended-Sentence
END-IFIF Delim NOT = ". " AND " "SUBTRACT 1 FROM Src-Ptr
END-IF*>-- Classify Token
MOVE UPPER-CASE(SPI-Current-Token) TO Search-Token
IF Search-Token = "EQUAL" OR "EQUALS"
MOVE "EQUALS" TO SPI-Current-Token
MOVE "K"TO SPI-Token-Type
EXIT PARAGRAPH
END-IF
SEARCH ALL Reserved-Word
WHEN RW-Word (RW-Idx) = Search-Token
MOVE RW-Type (RW-Idx) TO SPI-Token-Type
EXIT PARAGRAPH
END-SEARCH*>-- Not a reserved word, must be a user name
SET Token-Is-Identifier TO TRUE *> NEEDS EXPANSION!!!!
PERFORM 313-Check-For-Numeric-Token
IF Token-Is-Literal-Number
IF (F-Last-Token-Ended-Sent = "Y")AND (SPI-Current-Division = "D")MOVE "LEVEL #" TO SPI-Current-Token
MOVE "K"TO SPI-Token-Type
EXIT PARAGRAPH
ELSE
EXIT PARAGRAPH
END-IF

06FEB2009 Version

Page 8-38

OpenCOBOL 1.1 Programmers Guide

Sample Programs

END-IF
EXIT PARAGRAPH.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
311-Control-Record.
UNSTRING ECR-2-256
DELIMITED BY '"'INTO PIC-X10, PIC-X256, Dummy
END-UNSTRING
INSPECT PIC-X10 REPLACING ALL '"' BY SPACECOMPUTE I = NUMVAL(PIC-X10) - 1
IF TRIM(PIC-X256,Trailing) = TRIM(Program-Path,Trailing)
MOVE I TO SPI-Current-Line-No
SET In-Main-Module TO TRUE
IF Saved-Section NOT = SPACES
MOVE Saved-Section TO SPI-Current-Section
END-IFELSE
SET In-Copybook TO TRUE
IF Saved-Section = SPACES
MOVE SPI-Current-Section TO Saved-Section
END-IF
MOVE LENGTH(TRIM(PIC-X256,Trailing)) TO I
MOVE 0 TO JPERFORM UNTIL PIC-X256(I:1) = '/'OR I = 0
SUBTRACT 1 FROM I
ADD
1 TO
J
END-PERFORM
UNSTRING PIC-X256((I + 1):J) DELIMITED BY "."INTO Filename, Dummy
END-UNSTRING
MOVE "["TO SPI-CS-1
MOVE Filename TO SPI-CS-2-14
IF SPI-CS-11-14 NOT = SPACES
MOVE "..." TO SPI-CS-11-14
END-IF
MOVE "]"TO SPI-CS-15
END-IF
MOVE SPACES TO Expand-Code-Rec *> Force another READ
MOVE 256
TO Src-Ptr.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
312-Expand-Code-Record.
MOVE 1 TO Src-Ptr
IF In-Main-Module
ADD 1 To SPI-Current-Line-No
END-IF.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
313-Check-For-Numeric-Token.
MOVE SPI-Current-Token TO PIC-X32
INSPECT PIC-X32
REPLACING TRAILING SPACES BY "0"
IF PIC-X32 IS NUMERIC*> Simple Unsigned Integer
SET Token-Is-Literal-Number TO TRUE
EXIT PARAGRAPH
END-IFIF PIC-X32(1:1) = "+" OR "-"MOVE "0" TO PIC-X32(1:1)
END-IF
MOVE 0 TO Tally
INSPECT PIC-X32
TALLYING Tally FOR ALL "."IF Tally = 1
INSPECT PIC-X32 REPLACING ALL "." BY "0"
END-IFIF PIC-X32 IS NUMERICSET Token-Is-Literal-Number TO TRUE
EXIT PARAGRAPH
END-IF.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
320-IDENTIFICATION-DIVISION.
IF Token-Is-Key-Word AND SPI-Current-Token = "DIVISION"
MOVE SPI-Prior-Token TO SPI-Current-Division
EXIT PARAGRAPH
END-IFIF SPI-Prior-Token = "PROGRAM-ID"
MOVE SPACES TO SPI-Prior-Token
MOVE SPI-Current-Token TO SPI-Current-Program-ID
IF SPI-CP-13-15 NOT = SPACES
MOVE "..." TO SPI-CP-13-15
END-IF

06FEB2009 Version

Page 8-39

OpenCOBOL 1.1 Programmers Guide

Sample Programs

EXIT PARAGRAPH
END-IF.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
330-ENVIRONMENT-DIVISION.
IF Token-Is-Key-Word AND SPI-Current-Token = "DIVISION"
MOVE SPI-Prior-Token TO SPI-Current-Division
EXIT PARAGRAPH
END-IFIF Token-Is-Key-Word AND SPI-Current-Token = "SECTION"
MOVE SPI-Prior-Token TO SPI-Current-Section
EXIT PARAGRAPH
END-IFIF Token-Is-Identifier
PERFORM 361-Release-Ref
END-IF.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
340-DATA-DIVISION.
IF Token-Is-Key-Word AND SPI-Current-Token = "DIVISION"
MOVE SPI-Prior-Token TO SPI-Current-Division
EXIT PARAGRAPH
END-IFIF Token-Is-Key-Word AND SPI-Current-Token = "SECTION"
MOVE SPI-Prior-Token TO SPI-Current-Section
EXIT PARAGRAPH
END-IF
IF (SPI-Current-Token = "PIC" OR "PICTURE")
AND (Token-Is-Key-Word)
MOVE "Y" TO F-Processing-PICTURE
EXIT PARAGRAPH
END-IFIF Token-Is-Identifier
EVALUATE SPI-Prior-Token
WHEN "FD"PERFORM 360-Release-Def
MOVE SPACES TO SPI-Prior-Token
WHEN "SD"PERFORM 360-Release-Def
MOVE SPACES TO SPI-Prior-Token
WHEN "LEVEL #"PERFORM 360-Release-Def
MOVE SPACES TO SPI-Prior-Token
WHEN "INDEXED"PERFORM 360-Release-Def
MOVE SPACES TO SPI-Prior-Token
WHEN "USING"PERFORM 362-Release-Upd
MOVE SPACES TO SPI-Prior-Token
WHEN "INTO"PERFORM 362-Release-Upd
MOVE SPACES TO SPI-Prior-Token
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE
EXIT PARAGRAPH
END-IF.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
350-PROCEDURE-DIVISION.
IF SPI-Current-Section NOT = "PROCEDURE"
MOVE "PROCEDURE" TO SPI-Current-Section
END-IFIF Token-Is-Key-Word AND SPI-Current-Token = "DIVISION"
MOVE SPI-Prior-Token TO SPI-Current-Division
EXIT PARAGRAPH
END-IFIF SPI-Current-Verb = SPACES
IF Token-Is-Identifier
PERFORM 360-Release-Def
MOVE SPACES TO SPI-Prior-Token
END-IF
EXIT PARAGRAPH
END-IFIF NOT Token-Is-Identifier
EXIT PARAGRAPH
END-IFEVALUATE SPI-Current-Verb
WHEN "ACCEPT"PERFORM 351-ACCEPT
WHEN "ADD"PERFORM 351-ADD
WHEN "ALLOCATE"PERFORM 351-ALLOCATE

06FEB2009 Version

Page 8-40

OpenCOBOL 1.1 Programmers Guide

Sample Programs

WHEN "CALL"PERFORM 351-CALL
WHEN "COMPUTE"PERFORM 351-COMPUTE
WHEN "DIVIDE"PERFORM 351-DIVIDE
WHEN "FREE"PERFORM 351-FREE
WHEN "INITIALIZE"PERFORM 351-INITIALIZE
WHEN "INSPECT"PERFORM 351-INSPECT
WHEN "MOVE"PERFORM 351-MOVE
WHEN "MULTIPLY"PERFORM 351-MULTIPLY
WHEN "PERFORM"PERFORM 351-PERFORM
WHEN "SET"PERFORM 351-SET
WHEN "STRING"PERFORM 351-STRING
WHEN "SUBTRACT"PERFORM 351-SUBTRACT
WHEN "TRANSFORM"PERFORM 351-TRANSFORM
WHEN "UNSTRING"PERFORM 351-UNSTRING
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-ACCEPT.
EVALUATE SPI-Prior-Token
WHEN "ACCEPT"PERFORM 362-Release-Upd
MOVE SPACES TO SPI-Prior-Token
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-ADD.
EVALUATE SPI-Prior-Token
WHEN "GIVING"PERFORM 362-Release-Upd
WHEN "TO"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-ALLOCATE.
EVALUATE SPI-Prior-Token
WHEN "ALLOCATE"PERFORM 362-Release-Upd
MOVE SPACES TO SPI-Prior-Token
WHEN "RETURNING"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-CALL.
EVALUATE SPI-Prior-Token
WHEN "RETURNING"PERFORM 362-Release-Upd
WHEN "GIVING"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-COMPUTE.
EVALUATE SPI-Prior-Token
WHEN "COMPUTE"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE

06FEB2009 Version

Page 8-41

OpenCOBOL 1.1 Programmers Guide

Sample Programs.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-DIVIDE.
EVALUATE SPI-Prior-Token
WHEN "INTO"PERFORM 363-Set-Upd
MOVE Sort-Rec TO Held-Reference
WHEN "GIVING"IF Held-Reference NOT = SPACES
MOVE Held-Reference To Sort-Rec
MOVE SPACESTo Held-Reference
SR-Ref-Flag
RELEASE Sort-Rec
END-IFPERFORM 362-Release-Upd
WHEN "REMAINDER"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-FREE.
PERFORM 362-Release-Upd.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-INITIALIZE.
EVALUATE SPI-Prior-Token
WHEN "INITIALIZE"PERFORM 362-Release-Upd
WHEN "REPLACING"PERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-INSPECT.
EVALUATE SPI-Prior-Token
WHEN "INSPECT"PERFORM 364-Set-Ref
MOVE SPACES TO Held-Reference
MOVE SPACES TO SPI-Prior-Token
WHEN "TALLYING"PERFORM 362-Release-Upd
MOVE SPACES TO SPI-Prior-Token
WHEN "REPLACING"IF Held-Reference NOT = SPACES
MOVE Held-Reference TO Sort-Rec
MOVE SPACESTO Held-Reference
MOVE "*"TO SR-Ref-Flag
RELEASE Sort-Rec
END-IF
MOVE SPACES TO SPI-Prior-Token
WHEN "CONVERTING"IF Held-Reference NOT = SPACES
MOVE Held-Reference TO Sort-Rec
MOVE SPACESTO Held-Reference
MOVE "*"TO SR-Ref-Flag
RELEASE Sort-Rec
END-IF
MOVE SPACES TO SPI-Prior-Token
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-MOVE.
EVALUATE SPI-Prior-Token
WHEN "TO"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-MULTIPLY.
EVALUATE SPI-Prior-Token
WHEN "BY"PERFORM 363-Set-Upd
MOVE Sort-Rec TO Held-Reference
WHEN "GIVING"
MOVE Held-Reference TO Sort-Rec
MOVE SPACESTO Held-Reference
SR-Ref-Flag
RELEASE Sort-Rec

06FEB2009 Version

Page 8-42

OpenCOBOL 1.1 Programmers Guide

Sample Programs

PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-PERFORM.
EVALUATE SPI-Prior-Token
WHEN "VARYING"PERFORM 362-Release-Upd
MOVE SPACES TO SPI-Prior-Token
WHEN "AFTER"PERFORM 362-Release-Upd
MOVE SPACES TO SPI-Prior-Token
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-SET.
EVALUATE SPI-Prior-Token
WHEN "SET"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-STRING.
EVALUATE SPI-Prior-Token
WHEN "INTO"PERFORM 362-Release-Upd
WHEN "POINTER"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-SUBTRACT.
EVALUATE SPI-Prior-Token
WHEN "GIVING"PERFORM 362-Release-Upd
WHEN "FROM"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-TRANSFORM.
EVALUATE SPI-Prior-Token
WHEN "TRANSFORM"PERFORM 362-Release-Upd
MOVE SPACES TO SPI-Prior-Token
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
351-UNSTRING.
EVALUATE SPI-Prior-Token
WHEN "INTO"PERFORM 362-Release-Upd
WHEN "DELIMITER"PERFORM 362-Release-Upd
WHEN "COUNT"PERFORM 362-Release-Upd
WHEN "POINTER"PERFORM 362-Release-Upd
WHEN "TALLYING"PERFORM 362-Release-Upd
WHEN OTHERPERFORM 361-Release-Ref
END-EVALUATE.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
360-Release-Def.
MOVE SPACES TO Sort-Rec
MOVE SPI-Current-Program-ID TO SR-Prog-ID
MOVE SPI-Current-Token-UC
TO SR-Token-UC
MOVE SPI-Current-Token
TO SR-Token
MOVE SPI-Current-Section
TO SR-Section
MOVE SPI-Current-Line-No
TO SR-Line-No-Def

06FEB2009 Version

Page 8-43

OpenCOBOL 1.1 Programmers Guide

Sample Programs

MOVE 0TO SR-Line-No-Ref
RELEASE Sort-Rec.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
361-Release-Ref.
PERFORM 364-Set-Ref
RELEASE Sort-Rec.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
362-Release-Upd.
PERFORM 363-Set-Upd
RELEASE Sort-Rec.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
363-Set-Upd.
MOVE SPACES TO Sort-Rec
MOVE SPI-Current-Program-ID TO SR-Prog-ID
MOVE SPI-Current-Token-UC
TO SR-Token-UC
MOVE SPI-Current-Token
TO SR-Token
MOVE SPI-Current-Section
TO SR-Section
MOVE SPI-Current-Line-No
TO SR-Line-No-Ref
MOVE "*"TO SR-Ref-Flag.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
364-Set-Ref.
MOVE SPACES TO Sort-Rec
MOVE SPI-Current-Program-ID TO SR-Prog-ID
MOVE SPI-Current-Token-UC
TO SR-Token-UC
MOVE SPI-Current-Token
TO SR-Token
MOVE SPI-Current-Section
TO SR-Section
MOVE SPI-Current-Line-No
TO SR-Line-No-Ref.
/
400-Produce-Xref-Listing SECTION.
401-Init.
MOVE SPACESTO Detail-Line-X
Group-Indicators
MOVE 0TO I
Lines-Left.
402-Process-Sorted-Recs.
PERFORM FOREVER
RETURN Sort-File AT END
EXIT PERFORM
END-RETURNIF SR-Prog-ID NOT = GI-Prog-ID
OR SR-Token-UC NOT = GI-TokenIF Detail-Line-X NOT = SPACESPERFORM 410-Generate-Report-Line
END-IFIF SR-Prog-ID NOT = GI-Prog-ID
MOVE 0 TO Lines-Left
END-IF
MOVE SR-Prog-ID TO GI-Prog-ID
MOVE SR-Token-UC TO GI-Token
END-IFIF Detail-Line-X = SPACES
MOVE SR-Prog-ID
TO DLX-Prog-ID
MOVE SR-TokenTO DLX-Token
MOVE SR-Section
TO DLX-Section
IF SR-Line-No-Def NOT = SPACES
MOVE SR-Line-No-Def TO DLX-Line-No-Def
END-IF
END-IFIF SR-Reference > '000000'
ADD 1 TO I
IF I > Line-Nos-Per-Rec
PERFORM 410-Generate-Report-Line
MOVE 1 TO I
END-IF
MOVE SR-Line-No-Ref TO DLX-Line-No-Ref (I)MOVE SR-Ref-Flag
TO DLX-Ref-Flag(I)
END-IF
END-PERFORMIF Detail-Line-X NOT = SPACESPERFORM 410-Generate-Report-Line
END-IF
EXIT SECTION.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
410-Generate-Report-Line.
IF Lines-Left < 1
IF F-First-Record = "Y"

06FEB2009 Version

Page 8-44

OpenCOBOL 1.1 Programmers Guide

Sample Programs

MOVE "N" TO F-First-Record
WRITE Report-Rec FROM Heading-1X BEFORE 1
ELSE
MOVE SPACES TO Report-Rec
WRITE Report-Rec
BEFORE PAGE
MOVE SPACES TO Report-Rec
WRITE Report-Rec
BEFORE 1
WRITE Report-Rec FROM Heading-1X BEFORE 1
END-IF
WRITE Report-Rec FROM Heading-2 BEFORE 1
WRITE Report-Rec FROM Heading-4X BEFORE 1
WRITE Report-Rec FROM Heading-5X BEFORE 1
COMPUTE
Lines-Left = Lines-Per-Page - 4
END-COMPUTE
END-IF
WRITE Report-Rec FROM Detail-Line-X BEFORE 1
MOVE SPACES TO Detail-Line-X
MOVE 0 TO ISUBTRACT 1 FROM Lines-Left.
/
500-Produce-Source-Listing SECTION.
501-Generate-Source-Listing.
OPEN INPUT Source-Code
Expand-Code
MOVE 0 TO Source-Line-No
PERFORM FOREVER
READ Expand-Code AT END
EXIT PERFORM
END-READ
IF ECR-1 = "#"PERFORM 510-Control-Record
ELSE
PERFORM 520-Expand-Code-Record
END-IF
END-PERFORM
CLOSE Source-Code
Expand-Code
EXIT SECTION.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
510-Control-Record.
UNSTRING ECR-2-256
DELIMITED BY '"'INTO PIC-X10, PIC-X256, Dummy
END-UNSTRING
IF TRIM(PIC-X256,Trailing) = TRIM(Program-Path,Trailing) *> Main Pgm
SET In-Main-Module TO TRUE
IF Source-Line-No > 0
READ Expand-Code END-READ
END-IFELSE *> COPYSET In-Copybook TO TRUE
END-IF.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
520-Expand-Code-Record.
IF In-Main-Module
ADD 1 To SPI-Current-Line-No
READ Source-Code AT END NEXT SENTENCE END-READ
ADD 1 TO Source-Line-No
MOVE SPACESTO Detail-Line-S
MOVE Source-Line-No TO DLS-Line-No
MOVE SCR-1-128
TO DLS-Statement
GC0410IF SCR-7 = "/"GC0410MOVE 0 TO Lines-Left
GC0410END-IFPERFORM 530-Generate-Source-Line
IF SCR-129-256 NOT = SPACES
MOVE SPACESTO Detail-Line-S
MOVE SCR-129-256 TO DLS-Statement
PERFORM 530-Generate-Source-Line
END-IFELSEIF Expand-Code-Rec NOT = SPACES
MOVE SPACESTO Detail-Line-S
MOVE ECR-1-128
TO DLS-Statement
PERFORM 530-Generate-Source-Line
IF ECR-129-256 NOT = SPACES
MOVE SPACESTO Detail-Line-S
MOVE ECR-129-256 TO DLS-Statement
PERFORM 530-Generate-Source-Line
END-IF

06FEB2009 Version

Page 8-45

OpenCOBOL 1.1 Programmers Guide

Sample Programs

END-IF
END-IF.
*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
530-Generate-Source-Line.
IF Lines-Left < 1
IF F-First-Record = "Y"MOVE "N" TO F-First-Record
WRITE Report-Rec FROM Heading-1S BEFORE 1
ELSE
MOVE SPACES TO Report-Rec
WRITE Report-Rec
BEFORE PAGE
MOVE SPACES TO Report-Rec
WRITE Report-Rec
BEFORE 1
WRITE Report-Rec FROM Heading-1S BEFORE 1
END-IF
WRITE Report-Rec FROM Heading-2 BEFORE 1
WRITE Report-Rec FROM Heading-4S BEFORE 1
WRITE Report-Rec FROM Heading-5S BEFORE 1
COMPUTE
Lines-Left = Lines-Per-Page - 4
END-COMPUTE
END-IF
WRITE Report-Rec FROM Detail-Line-S BEFORE 1
MOVE SPACES TO Detail-Line-S
SUBTRACT 1 FROM Lines-Left.
END PROGRAM LISTING.

8.4. WINSYSTEM – Execute Windows Shell Commands (For Cygwin)
IDENTIFICATION DIVISION.
PROGRAM-ID.
WINSYSTEM.
******************************************************************* This is an OpenCOBOL subroutine that will submit a Windows **** command to the Windows "cmd.exe" command shell for proces- **** sing. This is needed if your OpenCOBOL version was built**** using Cygwin because the "SYSTEM" built-in subroutine will **** submit commands to the Cygwin shell rather than the Windows **** shell.
******** CALL "WINSYSTEM" USING <cmd>******** >>> Note that the subroutine name MUST be specified in <<< **** >>> upper-case<<< ********************************************************************* DATE CHANGE DESCRIPTION**** ====== ==================================================== **** GC0909 Initial coding*******************************************************************ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY.
FUNCTION ALL INTRINSIC.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Cmd-Len
USAGE BINARY-LONG.
01 Shell-Cmd
PIC X(1024).
LINKAGE SECTION.
01 CmdPIC X(1) ANY LENGTH.
PROCEDURE DIVISION USING Cmd.
000-Main.
CALL "C$PARAMSIZE" USING 1.
MOVE RETURN-CODE TO Cmd-Len.
MOVE SPACES TO Shell-Cmd.
STRING "cmd.exe /C "Cmd(1:Cmd-Len)
INTO Shell-Cmd
END-STRINGCALL "SYSTEM"

06FEB2009 Version

Page 8-46

OpenCOBOL 1.1 Programmers Guide

Sample Programs

USING TRIM(Shell-Cmd)
END-CALL.
099-Wave-Bye-Bye.
GOBACK.

06FEB2009 Version

Page 8-47

OpenCOBOL 1.1 Programmers Guide

Glossary of Terms

9. Glossary of Terms
There are many terms that are used throughout this document (as well as throughout ANY document dealing with the
COBOL language) that are used to make discussions of syntax and semantics more concise. The following is a list ofsuch terms and their definitions.
Alphanumeric
literalA string of characters enclosed within a pair of quotation marks (“) or apostrophes (‘). See section
1.8.

Collatingsequence

The sequence in which the characters that are acceptable to a computer are ordered for purposesof all types of sorting, merging, comparing, and processing. OpenCOBOL programs may utilize
standard character-set collating sequences (such as that defined by the ASCII or EBCDIC
charactersets) or programmer-defined custom sequences as specified in the OBJECT-COMPUTER
paragraph (section 4.1.2) and defined in the SPECIAL-NAMES paragraph (section 4.1.4).

Compilation unit

A single source file being compiled by the OpenCOBOL compiler. A compilation unit may containone or more program units.

Division

COBOL programs are broken into four major areas, called DIVISIONS. Divisions are used to collectprogram components oriented toward specific similar goals together in a single place. The COBOL
divisions are:
IDENTIFICATION DIVISION – names the program and, optionally, if it is a subprogram,defines it’s high-level data initialization policy and/or global availability to other programs
compiled in the same compilation unit.
ENVIRONMENT DIVISION – defines characteristics of the environment in which theprogram will be executed, such as files the program will be reading and/or writing, runtime switches that may be used to pass information into the program from the operating
system environment and any special options that may be needed in order for the
program to properly compile; typically, those special options are used to enable COBOL
programs created using some other version of COBOL to be compiled and executed
under a different version.
DATA DIVISION – provides detailed descriptions of the files, data and data structures the
program will be working with.
PROCEDURE DIVISION – contains the actual executable program code.

Dynamicallyloadable library

The OpenCOBOL compiler can create dynamically-loadable library files when compiling
subprograms as their own separate compilation units. On UNIX systems, these will be “.so” files
while on Windows systems these will be DLLs. Main programs can be created in this manner also.
The “-m” compiler switch is used to create dynamically-loadable libraries.

Dynamicallyloadable module

A synonym for Dynamically-loadable library.

Elementary Item

A data item described as not being further logically subdivided.

Entry-point

A spot in the PROCEDURE DIVISION where a program may begin execution when it is executedfrom the operating system or CALLed by another program. Every program has at least one entrypoint – known as the primary entry-point – which corresponds to the first executable statement in
the PROCEDURE DIVISION following the DECLARATIVES area, if any. Additional entry-points may
be defined via the ENTRY statement (see section 6.16).

Entry-point
name

Every entry-point has a name. That name must be unique for all program units that comprise an
executable program. Entry-point names are defined using a subroutine’s PROGRAM-ID clause (seesection 3) or via ENTRY statements coded in the subroutine’s PROCEDURE DIVISION (see section
6.16).

06FEB2009 Version

Page 9-1

OpenCOBOL 1.1 Programmers Guide

Glossary of Terms

Executable file

The OpenCOBOL compiler can create operating-system appropriate files that may be executed
directly from the operating system environment. On Windows systems, these will be “.exe” files
whereas on UNIX systems they will have no specific extensions. The “-x” compiler switch is used
to create executable files. Only main programs should be compiled in this manner.

Figurative
constants

OpenCOBOL, like other COBOL implementations, supports a number of reserved words that may
be used to represent a specific literal value. These are known as figurative constants. See section
1.9.

Group item

A group item is an identifier that is broken down into sub-items. For example, a MAILINGADDRESS might be broken down into STREET-ADDRESS, APARTMENT-NUMBER, CITY, STATE and
ZIP-CODE components.

Identifiers

These are data items a COBOL program will be working with. The vast majority of identifiers aredefined by the user (programmer) while a few are pre-defined by the OpenCOBOL compiler.
Identifiers pre-defined by the compiler are referred to as registers. Other programming languages
generally refer to identifiers as “variables”.

Imperative
statement

A sequence of one or more non-conditional OpenCOBOL statements or conditional OpenCOBOL
statements properly terminated with the correct “END-xxxx” trailer.

Level number

A user-defined word expressed as a 1- or 2-digit number that indicates the hierarchical position ofa data item or the special properties of a data description entry.
Level numbers in the range 1 through 49 indicate the position of a data item in the hierarchicalstructure of a logical record. Level numbers in the range 1 through 9 can be written either as asingle digit or as a zero followed by the significant digit.
Level numbers 66, 77, 78 and 88 identify special properties of a data description entry.
See sections 5.3, 5.4, 5.5 and 0.

Literal

A numeric literal or an alphanumeric literal.

Main program

An OpenCOBOL program that is to be executed directly from an operating system or shell event.
Main programs are not executed from other programs unless such execution is accomplished via
the CALL “SYSTEM” facility.

Numeric literal

A numeric constant. See section 1.8.

Primary Entrypoint

See entry-point.

Procedure

All executable code statements within a single PROCEDURE DIVISION paragraph or SECTION.

Procedure name

A programmer-defined SECTION or paragraph name in the PROCEDURE DIVISION assigned to aprocedure. Procedure names serve as a means by which a statement may refer to the statementsthat follow the procedure name.

Program unit

An OpenCOBOL main program or subprogram. Subprogram program units may be nested insideof other program units and a main program unit may be followed by any number of subprogram
program units in the same compilation unit.

Qualification

The process of establishing a unique reference to a data item whose name is duplicated in a
program. This takes the form of using the duplicated data name and the name of any of its parent
data items, connected by “OF” or “IN” such that the combination of those two data names is
unique within the program.

RecordThe most-inclusive, highest level, data item. The level number for a record is 01. A record can beeither an elementary item or a group item.

Registers

Special data items that are automatically defined for your use by the OpenCOBOL compiler. See
section 6.1.8.

06FEB2009 Version

Page 9-2

OpenCOBOL 1.1 Programmers Guide

Glossary of Terms

Reserved word

A COBOL word specified in the list of words that can be used in a COBOL source program, but thatmust not appear in the program as user-defined words or system names.

Sentence

Any number of COBOL statements, followed by a period.

Statement

A single COBOL instruction. Every statement starts with a verb which defines the overall action
the statement will take. Any additional syntax following the verb refines the actions that will betaken.

Subprogram orsubroutine

These two interchangeable terms refer to OpenCOBOL programs that are executed by anotherprogram. Typically this is done via the CALL statement from another OpenCOBOL program,
although OpenCOBOL may execute subprograms written in other languages and other language
programs may execute OpenCOBOL programs.

User-definednames

Either the name of an identifier or a procedure in the program. OpenCOBOL limits user-definednames to a maximum of 31 characters taken from the set of numeric digits, upper- and lower-caseletters, hyphens and underscores. A user-defined name may neither begin nor end with a hyphen
or underscore. User-defined names used as file names may additionally not begin with a digit
although - unlike many other programming languages - user-defined names used as identifiers orprocedure names may.

Verb

A single COBOL reserved-word which defines an action a COBOL program will take at execution
time. Every COBOL statement begins with a verb. Some verbs perform relatively simple actions(MOVE, STOP, SET, etc.) while others can perform extremely complex actions (SEARCH, SORT,MERGE, STRING, UNSTRING, etc.).

06FEB2009 Version

Page 9-3

OpenCOBOL 1.1 Programmers Guide

06FEB2009 Version

Glossary of Terms

Page 9-4

OpenCOBOL 1.1 Programmers Guide

Index

Index
*
* In Column 7, 1-11>>>D, 1-11>>SOURCE FORMAT, 1-11

A
ACCEPT, 5-18, 6-24
Command-Line Arguments, 6-26
CONSOLE, 6-26
Date/Time, 6-29
Environment, 6-27
Screen Data, 6-28
Screen Size, 6-29
ACCESS MODE, 4-8, 4-9
DYNAMIC, 6-42, 6-73, 6-74, 6-78, 6-89
RANDOM, 6-42, 6-73, 6-74, 6-78
SEQUENTIAL, 6-42, 6-78, 6-89
ADD
CORRESPONDING, 6-32
GIVING, 6-32
TO, 6-31
ADDRESS OF
FREE, 6-54
SET, 6-84
AFTER, 6-72
INSPECT, 6-61, 6-62
PERFORM VARYING, 6-71
PERFORM WITH TEST, 6-71
WRITE ADVANCING, 6-101
ALL
INSPECT, 6-61, 6-62
VALUE, 5-11
ALL PROCEDURES, 6-25
ALLOCATE, 5-11, 6-33
ALPHABET, 4-4
ALPHABETIC, 6-6
ALPHABETIC-LOWER, 6-6
ALPHABETIC-UPPER, 6-6
Alphanumeric Literal, 1-13
ALTER, 6-34
ALTERNATE RECORD KEY, 4-9, 6-89
ALTERNATE RECORD KEY fields, 6-74
ANY, 6-50
ANY LENGTH, 5-11
ARGUMENT-NUMBER, 6-26
ARGUMENT-VALUE, 6-26, 6-27
Arithmetic Expressions, 6-2
ASCENDING KEY
SORT, 6-87, 6-88
Table, 5-11, 6-81
ASSIGN, 4-6
AT
ACCEPT, 6-28

06FEB2009 Version

DISPLAY, 6-44
END (READ), 6-73
END-OF-PAGE, 6-102
AUTO, 5-18

B
BACKGROUND-COLOR, 5-18, 5-19
BACK-TAB, 5-18
BASED, 5-10, 5-11, 6-84
BEEP, 5-17
BEFORE
INSPECT, 6-61, 6-62
PERFORM WITH TEST, 6-71
WRITE ADVANCING, 6-101
BELL, 5-17
Big-Endian, 5-13
BLANK, 5-18
BLANK WHEN ZERO, 5-11
BLINK, 5-19
BLOCK CONTAINS, 5-3
BY
CONTENT, 7-7
PERFORM VARYING, 6-71, 6-72
REFERENCE, 6-24, 6-36, 7-6, 7-8
VALUE, 6-24, 7-8
BYTE-LENGTH, 5-16

C
C$CHDIR, 7-15
C$COPY, 7-15
C$DELETE, 7-15
C$FILEINFO, 7-16
C$JUSTIFY, 7-16
C$MAKEDIR, 7-16
C$NARG, 7-16, 7-27
C$PARAMSIZE, 7-17
C$SLEEP, 7-17
C$TOLOWER, 7-17
C$TOUPPER, 7-17
CALL, 6-6, 6-35, 7-3, 9-1
CANCEL, 5-1, 6-37
CBL_AND, 7-17
CBL_CHANGE_DIR, 7-18
CBL_CHECK_FILE_EXIST, 7-18
CBL_CLOSE_FILE, 7-18
CBL_COPY_FILE, 7-18
CBL_CREATE_DIR, 7-19
CBL_CREATE_FILE, 7-19
CBL_DELETE_DIR, 7-19
CBL_DELETE_FILE, 7-19
CBL_EQ, 7-22
CBL_ERROR_PROC, 7-19
CBL_EXIT_PROC, 7-21
CBL_FLUSH_FILE, 7-22
CBL_IMP, 7-22
CBL_NIMP, 7-23

Page i

OpenCOBOL 1.1 Programmers Guide
CBL_NOR, 7-23
CBL_NOT, 7-24
CBL_OC_NANOSLEEP, 7-24
CBL_OPEN_FILE, 7-19, 7-24
CBL_OR, 7-24
CBL_READ_FILE, 7-24, 7-25
CBL_RENAME_FILE, 7-25
CBL_TOUPPER, 7-25
CBL_WRITE_FILE, 7-19, 7-24, 7-26
CBL_XOR, 7-26
CHAIN, 6-24
CHAINING, 6-24
CHARACTERS, 6-62
CLASS, 4-4
CLOSE, 6-23, 6-38, 6-70
cobcrun, 7-12
CODE-SET, 5-2
COL, 5-18
Collating Sequence, 9-1
COLLATING SEQUENCE, 4-2, 4-6
COLUMN, 5-18
Column 7"*", 1-11"D", 1-11
COLUMNS, 6-29
Combined Conditions, 6-8
COMMAND-LINE, 6-26
comment, 1-11
COMMIT, 6-23, 6-39, 6-78
COMMON-STORAGE SECTION (Alternative To), 5-1
Compilation Unit, 2-1, 5-3, 5-10, 9-1
Compiler Switches
All Switches, 7-1-conf, 7-10
-fdebugging-line, 1-11
-ffunctions-all, 4-2-fixed, 1-11
-fnotrunc, 7-29
-free, 1-11
-g, 6-14, 6-15
-m, 7-2, 7-3, 7-12, 9-1-m, 3-1-S, 7-3-Wobsolete, 3-1-x, 7-3, 7-12, 9-2-x, 3-1
COMPUTE, 6-40
Condition Names, 6-5
Conditional Expressions, 6-2, 6-5
Conditions
Combined, 6-8
Level-88 Condition Names, 6-5
Negated, 6-9
Relation, 6-8
Switch Status, 6-7
Configuration Files, 7-10
CONFIGURATION SECTION, 4-1
CONSOLE, 6-43
CONSOLE IS CRT, 4-3
CONSTANT, 5-16
Constant Descriptions, 5-16

06FEB2009 Version

Index
CONTINUE, 6-41
CONVERTING, 6-61, 6-62, 6-97
CORRESPONDING, 6-32
COUNT, 6-100
CRT, 4-5, 6-43
CURRENCY SIGN, 4-5
CURSOR IS, 4-5

D
D In Column 7, 1-11
DATA DIVISION, 1-7, 1-10
DATA RECORD, 5-2
DATE, 6-29
DATE YYYYMMDD, 6-29
DAY, 6-29
DAY YYYYDDD, 6-29
DAY-OF-WEEK, 6-29
DEBUGGING MODE, 4-1
DECIMAL POINT IS COMMA, 4-5
DECLARATIVES, 6-25, 6-42, 6-70, 9-1
DEFAULT, 6-59
DELETE, 6-42, 6-70
DELIMITED BYSTRING, 6-92
UNSTRING, 6-99
DELIMITED BY SIZE, 6-92
DELIMITER, 6-100
DESCENDING KEY
SORT, 6-87, 6-88
Table, 5-11, 6-81
DISK, 5-3
DISPLAY, 5-18
Command-Line Arguments, 6-43
CONSOLE, 6-43
Environment, 6-43
Screen Data, 6-44
DIVIDE
BY/GIVING, 6-47
BY/REMAINDER, 6-48
INTO, 6-46
INTO/GIVING, 6-46
INTO/REMAINDER, 6-47
DIVISION, 9-1
DYNAMIC, 4-8, 4-9
Dynamically-Loadable Library, 3-1, 9-1

E
Elementary Item, 9-1
ELSE, 6-58
END PROGRAM, 2-1, 2-2
END-IF, 6-58
ENTRY, 6-49, 6-83, 7-3, 9-1
Entry Point, 9-1
ENVIRONMENT, 6-27
ENVIRONMENT DIVISION, 1-7, 4-1
Environment Variables
COB_CC, 7-9
COB_CFLAGS, 7-9
COB_CONFIG_DIR, 7-9

Page ii

OpenCOBOL 1.1 Programmers Guide
COB_CONFIG_PATH, 7-10
COB_COPY_DIR, 7-9, 7-10
COB_LDADD, 7-9
COB_LDFLAGS, 7-9
COB_LIBRARY_PATH, 7-13
COB_LIBS, 7-9
COB_PRE_LOAD, 7-13
COB_SCREEN_ESC, 4-5, 7-13
COB_SCREEN_EXCEPTIONS, 4-5, 7-13
COB_SORT_MEMORY, 7-13
COB_SWITCH_n, 4-4
COB_SWITCH_n, 7-13
COB_SYNC, 7-14
dd_literal-1, 4-7
DD_literal-1, 4-6
LD_LIBRARY_PATH, 7-9
literal-1, 4-7
PATH, 7-14
TEMP, 7-14
TMP, 7-10, 7-14
TMPDIR, 7-10, 7-14
ENVIRONMENT-NAME, 6-27
ENVIRONMENT-VALUE, 6-27
EOL, 5-18
EOS, 5-18
ERASE, 5-18
Error Procedure (user-defined), 6-70, 7-19
EVALUATE, 6-50
EVENT STATUS, 4-5
EXCEPTIONACCEPT, 6-30
CALL, 6-35
DISPLAY, 6-45
Executable File, 3-1, 9-2
EXIT, 6-52
PARAGRAPH, 6-52, 6-65
PERFORM, 6-52
PERFORM CYCLE, 6-52
PROGRAM, 6-65, 6-86, 6-88
SECTION, 6-52, 6-65
Simple, 6-52
Exit Procedure (user-defined), 7-21
Expressions
Arithmetic, 6-2
Conditional, 6-2, 6-5
EXTEND, 6-70, 6-101
EXTERNAL
Data Item Description, 5-1, 5-10
FD, 5-3

FFD, 6-101-fdebugging-line, 4-1
Figurative Constant, 1-14, 9-2
File Description, 6-101
FILE SECTION, 1-7
FILE STATUS, 4-7
FILE-CONTROL, 1-7, 4-6
FILLER, 5-4
FIRST

06FEB2009 Version

Index
INSPECT, 6-61, 6-62
-fixed, 1-11
fixed format, 1-11
FOREGROUND-COLOR, 5-18, 5-19
FOREVER, 6-71, 6-72
-free, 1-11
FREE, 6-54
free format, 1-11
FROM
PERFORM VARYING, 6-71
REWRITE, 6-78
Screen Item Description, 5-19
Screen Item Description, 5-19
WRITE, 6-101
FULL, 5-18
FUNCTION-ID, 2-2

G
GENERATE, 6-55
GIVING
CALL, 6-35
MERGE, 6-65
SORT, 6-87
STOP, 6-91
GLOBAL, 6-25
data item, 5-10
Data Item Description, 5-1
FD, 5-3
GO TO, 6-65, 6-71, 6-86, 6-88
DEPENDING ON, 6-57
Simple, 6-57
GOBACK, 6-53, 6-56, 6-65, 6-86, 6-88, 7-21
Group Item, 9-2

H
HIGHLIGHT, 5-19

I
IDENTIFICATION DIVISION, 3-1
Identifier, 9-2
IF, 6-58
IGNORING LOCK, 6-23
Imperative Statement, 9-2
INDEXED BY, 5-11, 6-81, 6-84
INITIAL, 6-35
INITIALIZE, 6-33
Verb, 6-59
INITIATE, 6-60
INPUT, 6-70
INPUT PROCEDURE, 6-76, 6-86
INPUT-OUTPUT SECTION, 1-7, 4-5
INSPECT, 6-61, 6-97
Intrinsic Functions (Supported)
ABS, 6-11
CHAR, 6-12
COMBINED-DATETIME, 6-13
CONCATENATE, 6-13
CURRENT-DATE, 6-13

Page iii

OpenCOBOL 1.1 Programmers Guide
DATE-OF-INTEGER, 6-13
DATE-TO-YYYYMMDD, 6-13
DAY-OF-INTEGER, 6-14
DAY-TO-YYYYDDD, 6-14
E, 6-14EXCEPTION-FILE, 6-14
EXCEPTION-LOCATION, 6-14
EXCEPTION-STATEMENT, 6-14
EXCEPTION-STATUS, 6-15
EXP, 6-15
EXP10, 6-15
FACTORIAL, 6-15
FRACTIONAL-PART, 6-15
INTEGER, 6-15
INTEGER-OF-DATE, 6-15
INTEGER-OF-DAY, 6-15
INTEGER-PART, 6-16
LENGTH, 6-16
LOCALE-DATE, 6-16
LOCALE-TIME, 6-16
LOCALE-TIME-FROM-SECS, 6-16
LOG, 6-16
LOG10, 6-16
LOWER-CASE, 6-16, 6-21
MAX, 6-17, 6-20, 6-21
MIDRANGE, 6-17
MOD, 6-17
NUMVAL, 1-13, 6-17
NUMVAL-C, 1-13, 6-17
ORD, 6-18
ORD-MAX, 6-18
PI, 6-18
PRESENT-VALUE, 6-18
RANDOM, 6-18
RANGE, 6-19
REM, 6-19
REVERSE, 6-19
SECONDS-FROM-FORMATTED-TIME, 6-19
SECONDS-PAST-MIDNIGHT, 6-19
SIGN, 6-19
SIN, 6-19
SQRT, 6-19
STORED-CHAR-LENGTH, 6-20
SUBSTITUTE, 6-20
SUM, 6-20
TAN, 6-20
TEST-DATE-YYYYMMDD, 6-20
TEST-DAY-YYYYDDD, 6-20
TRIM, 6-20
WHEN-COMPILED, 6-21
YEAR-TO-YYYY, 6-21
Intrinsic Functions (Unsupported)
BOOLEAN-OF-INTEGER, 6-11
CHAR-NATIONAL, 6-11
DISPLAY-OF, 6-11
EXCEPTION-FILE-N, 6-11
EXCEPTION-LOCATION-N, 6-11
HIGHEST-ALGEBRAIC, 6-11
INTEGER-OF-BOOLEAN, 6-11
LOCALE-COMPARE, 6-11
LOWEST-ALGEBRAIC, 6-11

06FEB2009 Version

Index
NATIONAL-OF, 6-11
NUMVAL-F, 6-11
STANDARD-COMPARE, 6-11
TEST-NUMVAL, 6-11
TEST-NUMVAL-C, 6-11
TEST-NUMVAL-F, 6-11
INVALID KEY
DELETE, 6-42
REWRITE, 6-78
START, 6-89
WRITE, 6-102
I-O, 6-70, 6-101
I-O-CONTROL, 4-10

J
JUSTIFIED RIGHT, 5-11

K
KEY (START), 6-89

L
LABEL RECORD, 5-2
LEADINGINSPECT, 6-61, 6-62
SIGN, 5-6
LENGTH, 5-16
LENGTH OF, 6-31
Use With Alphanumeric Literals, 1-14
Level01, 5-4
02-49, 5-4
66, 5-5, 5-17
77, 5-5
78, 5-16, 5-17
88, 5-17
Level Number, 9-2
LINAGE, 5-1, 5-3, 6-21, 6-101
LINE, 5-18
LINES
ACCEPT, 6-29
AT BOTTOM, 6-102
AT TOP, 6-102
WRITE ADVANCING, 6-101
LINKAGE SECTION, 6-24, 6-84
Literal, 9-2
Little-Endian, 5-13
LOCALE, 4-4
LOCAL-STORAGE SECTION, 5-1, 6-35
LOCK, 4-7
LOWLIGHT, 5-19

M
Main Program, 9-2
MEMORY SIZE, 4-2
MERGE, 6-64
MOVE, 5-11
CORRESPONDING, 6-66

Page iv

OpenCOBOL 1.1 Programmers Guide
Simple, 6-66
MULTIPLE FILE TAPE, 4-10
MULTIPLY
BY, 6-68
GIVING, 6-68

N
Negated Conditions, 6-9
NEGATIVE, 6-6
Nested Source Programs, 2-2, 3-1
NEXT, 6-73
NEXT SENTENCE, 6-69
NO ADVANCING, 6-43
NO REWIND, 6-38
NOT AT END, 6-73
NOT AT END-OF-PAGE, 6-102
NOT EXCEPTIONACCEPT, 6-30
DISPLAY, 6-45
NOT INVALID KEY
DELETE, 6-42
READ, 6-75
READ, 6-75
REWRITE, 6-78
START, 6-90
WRITE, 6-102
NOT ON OVERFLOWSTRING, 6-92
UNSTRING, 6-100
NOT ON SIZE ERROR
ADD, 6-31
COMPUTE, 6-40
DIVIDE, 6-46, 6-47, 6-48
MULTIPLY, 6-68
SUBTRACT, 6-93
NUMBER-OF-CALL-PARAMETERS, 7-16, 7-27
NUMERIC, 6-6
Numeric Literal, 1-12, 9-2

O
OBJECT-COMPUTER, 4-1
OCCURS, 5-10, 6-81
OFF STATUS, 4-4
OMITTED, 6-6
ON OVERFLOWSTRING, 6-92
UNSTRING, 6-100
ON SIZE ERROR
ADD, 6-31
COMPUTE, 6-40
DIVIDE, 6-46, 6-47, 6-48
MULTIPLY, 6-68
SUBTRACT, 6-93
ON STATUS, 4-4
OPEN, 6-70, 6-73, 6-74, 6-89, 6-101
OPTIONAL, 4-6
ORGANIZATIONINDEXED, 1-7, 4-9, 6-42, 6-73, 6-78, 6-89, 6-101, 6-102, 714

06FEB2009 Version

Index
LINE SEQUENTIAL, 1-5, 4-8, 5-3, 6-38, 6-64, 6-78, 6-86, 6101
RECORD BINARY SEQUENTIAL, 1-6, 4-8, 5-3, 6-38, 6-64, 678, 6-86, 6-101
RELATIVE, 1-6, 4-8, 6-42, 6-78, 6-89, 6-101, 6-102
OUTPUT, 6-70, 6-101
OUTPUT PROCEDURE, 6-77
MERGE, 6-65
SORT, 6-87
OVERFLOW
CALL, 6-35
OVERLINE, 5-18

P
PAGE
WRITE ADVANCING, 6-101
PERFORM, 6-25, 6-52
Inline, 6-72
Procedural, 6-71
POSITIVE, 6-6
PREVIOUS, 6-73
PRIMARY KEY, 4-9
PRIMARY RECORD KEY, 6-74
PRINTER, 4-8, 6-43
Procedure, 9-2
PROCEDURE DIVISION, 6-24
Procedure Name, 9-2
PROGRAM COLLATING SEQUENCE, 6-87, 6-88
Program Unit, 2-1, 9-2
PROGRAM-ID, 3-1, 7-3
PROGRAM-POINTER, 6-83
PROMPT, 5-18

Q
Qualification, 6-1, 9-2

R
RANDOM, 4-8, 4-9
READ, 6-42, 6-70, 6-73, 6-74, 6-78
Record, 9-2
RECORD CONTAINS, 5-3, 6-78
RECORD DELIMITER, 4-6
RECORD IS VARYING, 5-3, 6-78
RECORD KEY, 4-9, 6-42, 6-78, 6-89
RECORDING MODE, 5-2
REDEFINES, 5-10, 5-11
REEL, 6-38
Reference Modifier, 6-2
Registers, 9-2
Relation Conditions, 6-8
RELATIVE KEY, 4-8, 4-9, 6-42, 6-78, 6-89
RELEASE, 6-76, 6-86
REPLACING
INITIALIZE, 6-59
REPLACING (COPY), 1-12
REPLACING (INSPECT), 6-61, 6-62
REPORT IS, 5-3
REPORT SECTION, 5-1

Page v

OpenCOBOL 1.1 Programmers GuideREPOSITORY, 4-2, 6-11
REQUIRED, 5-18
RESERVE, 4-6
Reserved Word, 9-3
RETURN, 6-65, 6-77, 6-88
RETURN-CODE, 7-15, 7-16, 7-17, 7-18, 7-19, 7-20, 7-21, 7-22,
7-23, 7-24, 7-25, 7-26
RETURNING, 6-24, 6-33
CALL, 6-35
STOP, 6-91
REVERSE-VIDEO, 5-18
REWRITE, 6-78
ROLLBACK, 6-23, 6-79
ROUNDED, 6-31
ADD, 6-40
DIVIDE, 6-46, 6-47, 6-48
MULTIPLY, 6-68
SUBTRACT, 6-93

S
SAME RECORD AREA, 4-10, 6-64
SAME SORT AREA, 4-10, 6-64
SAME SORT-MERGE AREA, 4-10, 6-64
SCREEN CONTROL, 4-5
SCREEN SECTION, 1-10, 5-1
SCROLL, 6-28
SEARCH(Sequential), 6-80
ALL (Binary Search), 6-81
SECURE, 5-18
SEGMENT-LIMIT, 4-2
SELECT, 1-7
Sentence, 9-3
SEPARATE CHARACTER, 5-6
SEQUENTIAL, 4-8, 4-9
SET
Address, 6-83
Condition Name, 6-84
ENVIRONMENT, 6-83
Index, 6-84
Program-Pointer, 6-83
Switch, 6-85
UP/DOWN, 6-84
SHARING, 4-7, 6-70
SHARING WITH ALL OTHER, 4-6
Shift-TAB, 5-18
SIGN, 5-6
SIZE, 6-24
SIZE IS AUTO, 6-24
SORT
File, 6-86
Table, 6-88
SOURCE-COMPUTER, 4-1
Special Registers, 9-2
SPECIAL-NAMES, 4-3, 6-43, 7-27
Split Keys, 4-9
START, 4-8, 4-9, 6-70, 6-89
Statement, 9-3
STOP RUN, 6-56, 6-65, 6-71, 6-86, 6-88, 6-91, 7-21
STRING, 6-92

06FEB2009 Version

Index
Subprogram, 9-3
Subroutine, 9-3
Subscripts, 6-1
SUBTRACT
CORRESPONDING, 6-94
FROM, 6-93
GIVING, 6-93
SUPPRESS, 6-95
Switch Status Conditions, 6-7
SWITCH-n, 4-4, 7-27
SYMBOLIC CHARACTERS, 4-4
SYNCHRONIZED, 5-14
SYSTEM, 7-26

T
TAB, 5-18
TALLYING, 6-61
UNSTRING, 6-100
TERMINATE, 6-96
THROUGH, 6-50, 6-71
THRU, 6-50, 6-71
TIME, 6-29
TIMES, 6-52, 6-71, 6-72
TO
Screen Item Description, 5-19
TO VALUE, 6-59
TRAILING
INSPECT, 6-61, 6-62
SIGN, 5-6
TRANSFORM, 6-97

U
UNDERLINE, 5-18
UNIT, 6-38
UNLOCK, 6-23, 6-39, 6-70, 6-98
UNSTRING, 6-99
UNTIL, 6-52, 6-71, 6-72
UPDATE, 6-28
UPON, 6-43
USAGE
BINARY-CHAR, 7-4, 7-27
BINARY-CHAR SIGNED, 7-4
BINARY-CHAR UNSIGNED, 7-4
BINARY-C-LONG SIGNED, 7-5
BINARY-DOUBLE, 7-5
BINARY-DOUBLE SIGNED, 7-5
BINARY-DOUBLE UNSIGNED, 7-5
BINARY-LONG, 7-5
BINARY-LONG SIGNED, 7-5
BINARY-LONG UNSIGNED, 7-5
BINARY-SHORT, 7-4
BINARY-SHORT SIGNED, 7-4
BINARY-SHORT UNSIGNED, 7-4
COMPUTATIONAL-1, 7-5
COMPUTATIONAL-2, 7-5
DISPLAY, 6-5
INDEX, 6-84
POINTER, 6-5, 6-33, 6-84
PROGRAM POINTER, 6-5

Page vi

OpenCOBOL 1.1 Programmers Guide
PROGRAM-POINTER, 6-84, 7-19, 7-21
USE AFTER STANDARD ERROR PROCEDURE, 6-25
USE BEFORE REPORTING, 6-25
USE FOR DEBUGGING, 6-25
user-defined name, 9-3
User-Defined Name, 9-3
USING, 6-24
Screen Item Description, 5-19
USING (CALL), 6-35
USING (SORT), 6-86

V
VALUE, 5-10, 5-19
VALUE OF, 5-2
VARYING, 6-52, 6-71, 6-72
Verb, 9-3

W
WHEN, 6-50
WITH
DUPLICATES, 4-9

06FEB2009 Version

Index
DUPLICATES IN ORDER, 6-64, 6-86, 6-88
IGNORE LOCK, 6-23
LOCK, 6-23
CLOSE, 6-38, 6-70
NO LOCK, 6-23
NO REWIND
CLOSE, 6-70
POINTERSTRING, 6-92
UNSTRING, 6-99
TEST, 6-71, 6-72
WITH FILLER, 6-59
WITH WAIT, 6-23
WORKING-STORAGE SECTION, 1-7, 5-1
WRITE, 6-101

X
X"F4", 7-28
X"F5", 7-28
X”91”, 7-27

Page vii

OpenCOBOL 1.1 Programmers Guide

06FEB2009 Version

Index

Page viii

OpenCOBOL 1.1 Programmers Guide

GNU Free Documentation License

GNU Free Documentation License
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
<http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in thesense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it,either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being
considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in thesame sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs freedocumentation: a free program should come with manuals providing the same freedoms that the software does. But
this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter orwhether it is published as a printed book. We recommend this License principally for works whose purpose isinstruction or reference.
1. APPLICABILITY AND DEFINITIONSThis License applies to any manual or other work, in any medium, that contains a notice placed by the copyrightholder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-freelicense, unlimited in duration, to use that work under the conditions stated herein. The "Document", below,
refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept thelicense if you copy, modify or distribute the work in a way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copiedverbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with therelationship of the publishers or authors of the Document to the Document's overall subject (or to related matters)
and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook ofmathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historicalconnection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant
Sections, in the notice that says that the Document is released under this License. If a section does not fit the above
definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in thenotice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a
Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification
is available to the general public, that is suitable for revising the document straightforwardly with generic text editorsor (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, andthat is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input

06FEB2009 Version

Page ix

OpenCOBOL 1.1 Programmers Guide

GNU Free Documentation License

to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, hasbeen arranged to thwart or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" iscalled "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX
input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF
designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which
the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF
produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold,legibly, the material this License requires to appear in the title page. For works in formats which do not have any title
page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the
beginning of the body of the text.
The "publisher" means any person or entity that distributes copies of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ inparentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section namementioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve theTitle" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according tothis definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to theDocument. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards
disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on
the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that
this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced
in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technicalmeasures to obstruct or control the reading or further copying of the copies you make or distribute. However, you
may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also
follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering
more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers thatcarry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the backcover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must
present the full title with all words of the title equally prominent and visible. You may add other material on the
covers in addition.
Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these
conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as
fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include amachine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computernetwork location from which the general network-using public has access to download using public-standard network
protocols a complete Transparent copy of the Document, free of added material.
06FEB2009 Version

Page xOpenCOBOL 1.1 Programmers Guide

GNU Free Documentation License

If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies inquantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year
after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the
public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large
number of copies, to give them a chance to provide you with an updated version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above,
provided that you release the Modified Version under precisely this License, with the Modified Version filling the roleof the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of
it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those ofprevious versions (which should, if there were any, be listed in the History section of the Document). You may use
the same title as a previous version if the original publisher of that version gives permission.
B.

List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modificationsin the Modified Version, together with at least five of the principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you from this requirement.

C.

State on the Title page the name of the publisher of the Modified Version, as the publisher.

D. Preserve all the copyright notices of the Document.
E.

Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

F.

Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in the Addendum below.

G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I.

Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, newauthors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History"
in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title
Page, then add an item describing the Modified Version as stated in the previous sentence.

J.

Preserve the network location, if any, given in the Document for public access to a Transparent copy of theDocument, and likewise the network locations given in the Document for previous versions it was based on.
These may be placed in the "History" section. You may omit a network location for a work that was published atleast four years before the Document itself, or if the original publisher of the version it refers to gives permission.

K.

For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve inthe section all the substance and tone of each of the contributor acknowledgements and/or dedications given
therein.

L.

Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or
the equivalent are not considered part of the section titles.

M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections andcontain no material copied from the Document, you may at your option designate some or all of these sections asinvariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice.
06FEB2009 Version

Page xi

OpenCOBOL 1.1 Programmers Guide

GNU Free Documentation License

These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified
Version by various parties--for example, statements of peer review or that the text has been approved by anorganization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover
Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of
Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document alreadyincludes a cover text for the same cover, previously added by you or by arrangement made by the same entity you areacting on behalf of, you may not add another; but you may replace the old one, on explicit permission from theprevious publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity
for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in
section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of allof the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license
notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may bereplaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, makethe title of each such section unique by adding at the end of it, in parentheses, the name of the original author or
publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combinedwork.
In the combination, you must combine any sections Entitled "History" in the various original documents, forming one
section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled"Dedications". You must delete all sections Entitled "Endorsements".
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace
the individual copies of this License in the various documents with a single copy that is included in the collection,
provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided
you insert a copy of this License into the extracted document, and follow this License in all other respects regarding
verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a
volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is
not used to limit the legal rights of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is lessthan one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket theDocument within the aggregate, or the electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole aggregate.
8. TRANSLATION

06FEB2009 Version

Page xii

OpenCOBOL 1.1 Programmers Guide

GNU Free Documentation License

Translation is considered a kind of modification, so you may distribute translations of the Document under the termsof section 4.
Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may
include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections.
You may include a translation of this License, and all the license notices in the Document, and any Warranty
Disclaimers, provided that you also include the original English version of this License and the original versions of
those notices and disclaimers. In case of a disagreement between the translation and the original version of thisLicense or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4)
to Preserve its Title (section 1) will typically require changing the actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License.
Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights
under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a)provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently,
if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the
cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies
you of the violation by some reasonable means, this is the first time you have received notice of violation of thisLicense (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of thenotice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies orrights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of acopy of some or all of the same material does not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time
to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new
problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this License "or any later version" applies to it, youhave the option of following the terms and conditions either of that specified version or of any later version that has
been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version numberof this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If theDocument specifies that a proxy can decide which future versions of this License can be used, that proxy's publicstatement of acceptance of a version permanently authorizes you to choose that version for the Document.
11. RELICENSING"Massive Multiauthor Collaboration Site" (or "MMC Site") means any World Wide Web server that publishes
copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki thatanybody can edit is an example of such a server. A "Massive Multiauthor Collaboration" (or "MMC") contained in thesite means any set of copyrightable works thus published on the MMC site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons
Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as
future copyleft versions of that license published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or in part, as part of another Document.

06FEB2009 Version

Page xiii

OpenCOBOL 1.1 Programmers Guide

GNU Free Documentation License

An MMC is "eligible for relicensing" if it is licensed under this License, and if all works that were first published under
this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1)had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any
time before August 1, 2009, provided the MMC is eligible for relicensing.

06FEB2009 Version

Page xiv