This is gnucobpg.info, produced by makeinfo version 4.8 from
gnucobpg.texi.
This manual documents GNU COBOL 2.1, 23NOV2013 build.
GNU-COBOL Copyright 2002-2007 Keisuke Nishida
Copyright 2007-2012 Roger While
Copyright 2013-2013 Ron Norman (RWCS for GNU COBOL)
Document Copyright 2009-2014 Gary L. 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 "Introduction", no
Front-Cover Texts, and no Back-Cover Texts. A copy of the license
is included in the section entitled "GNU Free Documentation
License".
INFO-DIR-SECTION GNU-COBOL
START-INFO-DIR-ENTRY
* Prog Guide: (gnucobpg) GNU COBOL Programmer's Guide
END-INFO-DIR-ENTRY
File: gnucobpg.info, Node: Top, Next: Introduction, Up: (dir)
GNU COBOL Programmer's Guide
****************************
This manual documents the 23NOV2013 build of GNU COBOL 2.1.
* Menu:
List of Chapters and Appendices:
* 1: Introduction.
* 2: CDF - Compiler Directing Facility.
* 3: IDENTIFICATION DIVISION.
* 4: ENVIRONMENT DIVISION.
* 5: DATA DIVISION.
* 6: PROCEDURE DIVISION.
* 7: Report Writer Usage Notes.
* 8: Interfacing With The OS.
* 9: Sub-Programming.
* 10: Programming Style Suggestions.
* A: Appendix A - Glossary of Terms.
* B: Appendix B - Reserved Word List.
* C: Appendix C - GNU Free Documentation License.
* D: Appendix D - Summary of Document Changes.
* :INDEX.
Full Contents:
* 1: Introduction.
* 1.1: Additional Reference Sources.
* 1.2: Introducing COBOL.
* 1.2.1: Why YOU Should Learn COBOL.
* 1.2.2: Programmer Productivity.
* 1.3: So What is GNU COBOL?.
* 1.3.1: Language Reserved Words.
* 1.3.2: User-Defined Words.
* 1.3.3: Case Insensitivity.
* 1.3.4: Readability of Programs.
* 1.3.5: Divisions Organize Programs.
* 1.3.6: Copybooks.
* 1.3.7: Structured Data.
* 1.3.8: Files.
* 1.3.9: Table Handling.
* 1.3.10: Sorting and Merging Data.
* 1.3.11: String Manipulation Features.
* 1.3.12: Screen Formatting Features.
* 1.3.12.1: A Sample Screen.
* 1.3.12.2: Color Palette and Video Attributes.
* 1.3.13: Report Writer Features.
* 1.3.14: Data Initialization.
* 1.3.15: Syntax Diagram Conventions.
* 1.3.16: Format of Program Source Lines.
* 1.3.17: Program Structure.
* 1.3.18: Comments.
* 1.3.19: Literals.
* 1.3.19.1: Numeric Literals.
* 1.3.19.2: Alphanumeric Literals.
* 1.3.19.3: Figurative Constants.
* 1.3.20: Punctuation.
* 1.3.21: LENGTH OF.
* 1.3.22: Interfacing to Other Environments.
* 2: CDF - Compiler Directing Facility.
* 2.1: COPY.
* 2.2: REPLACE.
* 2.3: >>DEFINE.
* 2.4: >>IF.
* 2.5: >>SET.
* 2.6: >>SOURCE.
* 2.7: >>TURN.
* 3: IDENTIFICATION DIVISION.
* 4: ENVIRONMENT DIVISION.
* 4.1: CONFIGURATION SECTION.
* 4.1.1: SOURCE-COMPUTER.
* 4.1.2: OBJECT-COMPUTER.
* 4.1.3: REPOSITORY.
* 4.1.4: SPECIAL-NAMES.
* 4.1.4.1: Alphabet-Name-Clause.
* 4.1.4.2: Class-Definition-Clause.
* 4.1.4.3: Switch-Definition-Clause.
* 4.1.4.4: Symbolic-Characters-Clause.
* 4.2: INPUT-OUTPUT SECTION.
* 4.2.1: SELECT.
* 4.2.1.1: ORGANIZATION SEQUENTIAL.
* 4.2.1.2: ORGANIZATION LINE SEQUENTIAL.
* 4.2.1.3: ORGANIZATION RELATIVE.
* 4.2.1.4: ORGANIZATION INDEXED.
* 4.2.2: SAME RECORD AREA.
* 4.2.3: MULTIPLE FILE.
* 5: DATA DIVISION.
* 5.1: Data Definition Principles.
* 5.2: FILE SECTION.
* 5.2.1: File/Sort-Description.
* 5.2.2: FILE-SECTION-Data-Item.
* 5.3: WORKING-STORAGE SECTION.
* 5.4: LOCAL-STORAGE SECTION.
* 5.5: LINKAGE SECTION.
* 5.6: REPORT SECTION.
* 5.6.1: Report Group Definitions.
* 5.6.2: REPORT SECTION Data Items.
* 5.7: SCREEN SECTION.
* 5.8: Special Data Items.
* 5.9.1: 01-Level Constants.
* 5.9.2: 66-Level Data Items.
* 5.9.3: 77-Level Data Items.
* 5.9.4: 78-Level Data Items.
* 5.9.5: 88-Level Data Items.
* 5.9: Data Description Clauses.
* 5.8.1: ANY LENGTH.
* 5.8.2: AUTO.
* 5.8.3: AUTO-SKIP.
* 5.8.4: AUTOTERMINATE.
* 5.8.5: BACKGROUND-COLOR.
* 5.8.6: BASED.
* 5.8.7: BEEP.
* 5.8.8: BELL.
* 5.8.9: BLANK.
* 5.8.10: BLANK WHEN ZERO.
* 5.8.11: BLINK.
* 5.8.12: COLUMN.
* 5.8.13: CONSTANT.
* 5.8.14: EMPTY-CHECK.
* 5.8.15: EXTERNAL.
* 5.8.16: ERASE.
* 5.8.17: FALSE.
* 5.8.18: FOREGROUND-COLOR.
* 5.8.19: FROM.
* 5.8.20: FULL.
* 5.8.21: GLOBAL.
* 5.8.22: GROUP INDICATE.
* 5.8.23: HIGHLIGHT.
* 5.8.24: JUSTIFIED.
* 5.8.25: LEFTLINE.
* 5.8.26: LENGTH-CHECK.
* 5.8.27: LINE.
* 5.8.28: LOWLIGHT.
* 5.8.29: NEXT GROUP.
* 5.8.30: NO-ECHO.
* 5.8.31: OCCURS.
* 5.8.32: OVERLINE.
* 5.8.33: PICTURE.
* 5.8.34: PRESENT WHEN.
* 5.8.35: PROMPT.
* 5.8.36: REDEFINES.
* 5.8.37: RENAMES.
* 5.8.38: REQUIRED.
* 5.8.39: REVERSE-VIDEO.
* 5.8.40: SECURE.
* 5.8.41: SIGN.
* 5.8.42: SOURCE.
* 5.8.43: SUM.
* 5.8.44: SYNCRONIZED.
* 5.8.45: TO.
* 5.8.46: TYPE.
* 5.8.47: UNDERLINE.
* 5.8.48: USAGE.
* 5.8.49: USING.
* 5.8.50: VALUE.
* 6: PROCEDURE DIVISION.
* 6.1: PROCEDURE DIVISION USING.
* 6.2: PROCEDURE DIVISION CHAINING.
* 6.3: PROCEDURE DIVISION RETURNING.
* 6.4: PROCEDURE DIVISION Sections and Paragraphs.
* 6.5: DECLARATIVES.
* 6.6: Table References.
* 6.7: Qualification of Data Names.
* 6.8: Reference Modifiers.
* 6.9: Arithmetic Expressions.
* 6.10: Conditional Expressions.
* 6.10.1: Condition Names.
* 6.10.2: Class Conditions.
* 6.10.3: Sign Conditions.
* 6.10.4: Switch-Status Conditions.
* 6.10.5: Relation Conditions.
* 6.10.6: Combined Conditions.
* 6.10.7: Negated Conditions.
* 6.11: Use of Periods.
* 6.12: Use of VERB/END-VERB Constructs.
* 6.13: Concurrent Access to Files.
* 6.13.1: File Sharing.
* 6.13.2: Record Locking.
* 6.14: Common Clauses on Executable Statements.
* 6.14.1: AT END + NOT AT END.
* 6.14.2: CORRESPONDING.
* 6.14.3: INVALID KEY + NOT INVALID KEY.
* 6.14.4: ON EXCEPTION + NOT ON EXCEPTION.
* 6.14.5: ON OVERFLOW + NOT ON OVERFLOW.
* 6.14.6: ON SIZE ERROR + NOT ON SIZE ERROR.
* 6.14.7: ROUNDED.
* 6.15: Special Registers.
* 6.16: Intrinsic Functions.
* 6.17: GNU COBOL Statements.
* 7: Report Writer Usage Notes.
* 7.1: RWCS Lexicon.
* 7.2: The Anatomy of a Report.
* 7.3: The Anatomy of a Report Page.
* 7.4: How RWCS Builds Report Pages.
* 7.5: Control Hierarchy.
* 7.6: An Example.
* 7.6.1: Data.
* 7.6.2: Program.
* 7.6.3: Generated Report Pages.
* 7.7: Control Hierarchy (Revisited).
* 7.8: Turning PHYSICAL Page Formatting Into LOGICAL Formatting.
* 8: Interfacing With The OS.
* 8.1: Compiling Programs.
* 8.1.1: cobc - The GNU COBOL Compiler.
* 8.1.2: Compilation Time Environment Variables.
* 8.1.3: Locating Copybooks.
* 8.1.4: Compiler Configuration Files.
* 8.2: Running Programs.
* 8.2.1: Direct Execution.
* 8.2.2: Executing Dynamically-Loadable Libraries.
* 8.2.2.1: cobcrun - Command-line Execution.
* 8.2.2.2: Dynamically Loaded Subprograms.
* 8.2.3: Run Time Environment Variables.
* 8.2.4: Program Arguments.
* 8.3: Built-In System Subroutines.
* 8.4: Binary Truncation.
* 9: Sub-Programming.
* 9.1: Subprogram Types.
* 9.2: Independent vs Contained vs Nested Subprograms.
* 9.3: Alternate Entry Points.
* 9.4: Dynamic vs Static Subprograms.
* 9.5: Subprogram Execution Flow.
* 9.5.1: Subroutine Execution Flow.
* 9.5.2: User-Defined Function Execution Flow.
* 9.6: Sharing Data Between Calling and Called Programs.
* 9.6.1: Subprogram Arguments.
* 9.6.1.1: Calling Program Considerations.
* 9.6.1.2: Called Program Considerations.
* 9.6.2: GLOBAL Data Items.
* 9.6.3: EXTERNAL Data Items.
* 9.7: Recursive Subprograms.
* 9.8: Combining GNU COBOL and C Programs.
* 9.9.1: GNU COBOL Run-Time Library Requirements.
* 9.9.2: String Allocation Differences Between GNU COBOL and C.
* 9.9.3: Matching C Data Types with GNU COBOL USAGEs.
* 9.9.4: GNU COBOL Main Programs CALLing C Subprograms.
* 9.9.5: C Main Programs Calling GNU COBOL Subprograms.
* 10: Programming Style Suggestions.
* 10.1: Marking Changes in Programs.
* 10.2: Data Item Coding and Naming Conventions.
* 10.3: Table Subscripting versus Table Indexing.
* 10.4: Copybook Naming Conventions and Usage.
* 10.5: PROCEDURE DIVISION Sections Versus Paragraphs.
* 10.6: COMPUTE Versus ADD-SUBTRACT-MULTIPLY-DIVIDE.
* A: Appendix A - Glossary of Terms.
* B: Appendix B - Reserved Word List.
* C: Appendix C - GNU Free Documentation License.
* D: Appendix D - Summary of Document Changes.
File: gnucobpg.info, Node: Introduction, Next: CDF - Compiler Directing Facility, Prev: Top, Up: Top
1. Introduction
***************
This document describes the syntax, semantics and usage of the COBOL
programming language as implemented by the current version of GNU
COBOL, formerly known as OpenCOBOL.
The principal developers of GNU COBOL are Keisuke Nishida and Roger
While. They may be contacted through the GNU COBOL website -
sourceforge.net/projects/open-cobol.
This document was intended to serve as a full-function reference and
user's guide suitable for both those readers learning COBOL for the
first time as well as those already familiar with some dialect of the
COBOL language.
* Menu:
* 1.1: Additional Reference Sources.
* 1.2: Introducing COBOL.
* 1.2.1: Why YOU Should Learn COBOL.
* 1.2.2: Programmer Productivity.
* 1.3: So What is GNU COBOL?.
* 1.3.1: Language Reserved Words.
* 1.3.2: User-Defined Words.
* 1.3.3: Case Insensitivity.
* 1.3.4: Readability of Programs.
* 1.3.5: Divisions Organize Programs.
* 1.3.6: Copybooks.
* 1.3.7: Structured Data.
* 1.3.8: Files.
* 1.3.9: Table Handling.
* 1.3.10: Sorting and Merging Data.
* 1.3.11: String Manipulation Features.
* 1.3.12: Screen Formatting Features.
* 1.3.12.1: A Sample Screen.
* 1.3.12.2: Color Palette and Video Attributes.
* 1.3.13: Report Writer Features.
* 1.3.14: Data Initialization.
* 1.3.15: Syntax Diagram Conventions.
* 1.3.16: Format of Program Source Lines.
* 1.3.17: Program Structure.
* 1.3.18: Comments.
* 1.3.19: Literals.
* 1.3.19.1: Numeric Literals.
* 1.3.19.2: Alphanumeric Literals.
* 1.3.19.3: Figurative Constants.
* 1.3.20: Punctuation.
* 1.3.21: LENGTH OF.
* 1.3.22: Interfacing to Other Environments.
File: gnucobpg.info, Node: Additional Reference Sources, Next: Introducing COBOL, Up: Introduction
1.1. Additional Reference Sources
=================================
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
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 - .
File: gnucobpg.info, Node: Introducing COBOL, Prev: Additional Reference Sources, Up: Introduction
1.2. 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 a good thing and sometimes they aren't. The thing to
remember about COBOL is this -- it was designed to solve business
problems.
COBOL, first introduced to the programming public in 1959, was the very
first programming language to become standardized (in 1960). This
meant that a standard-compliant COBOL program written on computer "A"
made by company "B" would be able to be compiled and executed on
computer "X" made by company "Y" with very few, if any, changes. 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 "(CO)mmon (B)usiness (O)riented (L)anguage". 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.
* Menu:
* 1.2.1: Why YOU Should Learn COBOL.
* 1.2.2: Programmer Productivity.
File: gnucobpg.info, Node: Why YOU Should Learn COBOL, Next: Programmer Productivity, Up: Introducing COBOL
1.2.1. Why YOU Should Learn COBOL
---------------------------------
Despite statements from industry "insiders", the COBOL programming
language is not dead, even though newer and so-called "modern"
languages like Java, C#, .NET, Ruby on Rails and so on appear to have
become the languages of choice in the Information Technology world.
These languages have become popular because they address the following
desired requirements for "modern" programming:
1. They conform to the principles of Object-Oriented Programming
(OOP). This is desired for one major reason -- it facilitates
"code reusability", thus improving the productivity of programmers
by allowing them to re-use previously written (and debugged) code
in new applications. For one reason or another, COBOL is
perceived as being weak in this regard. It isn't (especially
today), as we'll see in the next section, but perception is
important.
2. Those languages aren't limited to mainframe computers, as COBOL is
perceived to be. Some, like .NET and Ruby, aren't even available
on mainframes. The "modern" programming languages were designed
and intended for use on the full variety of computer platforms,
from shirt-pocket computers (i.e. smartphones) up to the most
massive of supercomputers.
There are several excellent commercially available COBOL
implementations available for non-mainframe systems (Micro Focus
COBOL, AccuCOBOL, NetCOBOL and Elastic COBOL, just to name a few),
including Windows and UNIX/Linux systems. These aren't cheap,
however.
3. Universities love the "Modern" languages. In the U.S., 73% of
colleges lack even one COBOL course on their curricula. COBOL, it
appears, is no longer "cool" enough for students to fill a
classroom.
Just because COBOL doesn't traditionally support objects, classes, and
the like doesn't mean that its "procedural" approach to computing isn't
valuable -- after all, it runs 70% of the worlds business transactions,
and does so:
* Using programs that, for the most part, are much more
self-documenting than would be the case with any other programming
language.
* Effortlessly providing arithmetic accuracy to 31 digits, with
performance approaching that of well-written assembly-language
programs. Don't think this isn't critically important to banks,
investment houses and any business interested in tracking
revenues, expenses and profits (duh - like ALL of them).
* Integrating well with non-COBOL infrastructures such as XML, SOA,
MQ, almost any DBMS, Transaction Processing platforms,
Queue-Management facilities and other programming languages.
* By running on almost as many different computing platforms as Java
can. You can't run COBOL programs in your smartphone, but
desktops, workstations, midframes/servers, mainframes and
supercomputers are all fair game.
Today's IT managers and business leaders are faced with a challenging
dilemma -- how do you maintain the enourmous COBOL codebase that is
still running their businesses when academia has all but abandoned the
language they need their people to use to keep the wheels rolling? The
problem is compounded by the fact that those programmers that are
skilled in COBOL are retiring and taking their knowledge with them. In
some markets, this appears to be having an inflationary effect on the
cost of resources (COBOL programmers) whose supply is becoming smaller
and smaller. The pressure to update applications to make use of more
up-to-date graphical user interfaces is also perceived as a reason to
abandon COBOL in favor of GUI-friendly languages such as Java.
Businesses are addressing the COBOL challenge in different ways:
1. By undertaking so-called "modernization projects", where existing
applications are either rewritten in "modern" languages or
replaced outright with purchased packages. Most of these
businesses are using such activities as an excuse to abandon
"expensive" mainframes in favor of (presumably) less-expensive
"open systems" (midframe/server) solutions.
Many times these businesses are finding the cost of the
system/networking engineering, operational management and
monitoring and risk management (i.e. disaster recovery)
infrastructures necessary to support truly mission-critical
applications to be so high that the "less-expensive" solution
really isn't; in these cases the mainframe may remain the best
option, thus leaving COBOL in play and businesses seeking another
solution for at least part of their application base.
2. Training their own COBOL programmers. Since colleges,
universities and technical schools have lost interest in doing so,
many businesses have undertaken the task of "growing their own"
new crop of COBOL programmers. Fear of being pidgeon-holed into a
niche technology is a factor inhibiting many of today's
programmers from willingly volunteering for such training.
3. By moving the user-interface onto the desktop; such efforts
involve running modern-language front-end clients on user desktops
(or laptops or smartphones, etc.) with COBOL programs provideing
server functionality on mainframe or midframe platforms, providing
all the database and file "heavy lifting" on the back-end.
Solutions like this provide users with the user-interfaces they
want/need while still leveraging COBOL's strengths on (possibly)
downsized legacy mainframe or midframe systems.
It's probably a true that an IT professional can no longer afford to
allow COBOL to be the only wrench in their toolbox, but with a massive
codebase still in production now and for the foreseeable future, adding
COBOL to a multi-lingual curriculum vitae (CV) and/or resume (yes --
they ARE different) is not a bad thing at all. Knowing COBOL as well
as the language du-jour will make you the smartest person in the room
when the discussion of migrating the current "legacy" environment to a
"modern" implementation comes around.
You'll find COBOL an easy language to learn and a FAR EASIER language
to master than many of the "modern" languages.
The whole reason you're reading this is that you've discovered GNU
COBOL -- another implementation of COBOL in addition to those mentioned
earlier. The distinguishing characteristic of GNU COBOL versus those
others is that GNU COBOL is open-source and therefore FREE. It is
community-enhanced and community-supported. Later in this document
(*note So What is GNU COBOL?::), you'll begin to learn more about this
COBOL implementation's capabilities.
File: gnucobpg.info, Node: Programmer Productivity, Prev: Why YOU Should Learn COBOL, Up: Introducing COBOL
1.2.2. Programmer Productivity
------------------------------
Throughout the history of computer programming, the search for new ways
to improve of the productivity of programmers has been a major
consideration. Other than hobbyists, programming is an activity
performed for money, and businesses abhor spending anything more than
is absolutely necessary; even government agencies try to spend as
little money on projects as is absolutely necessary.
The amount of programming necessary to accomplish a given task --
including rework needed by any errors found during testing (testing is
sometimes jokingly defined as: "that time during which an application
is actually in production, allowing users to discover the problems") 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.
Sometimes the quest for improved programmer productivity (and therefore
reduced programming expense) has taken the form of introducing new
features in programming languages, or even new languages altogether.
Sometimes it has resulted in new ways of using the existing languages.
While many technological and procedural developments have made
evolutionary improvements to programmer productivity, each of the
following three events has been responsible for revolutionary
improvements:
* The development of so-called "higher-level" programming languages
that enable a programmer to specify in a single statement of the
language an action that would have required many more separate
statements in a prior programming language. The standardization
of such languages, making them usable on a wide variety of
computers and operating systems, was a key aspect of this
development. COBOL was a pioneering development in this area,
being a direct descendant of the very first higher-level language
(FLOW-MATIC, developed by US Naval Lieutenant Grace Hopper) and
the first to become standardized.
* The establishment of programming techniques that make programs
easier to read and therefore easier to understand. 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 program in order
how to best adapt it to changing business requirements. The
foremost development in this area was structured programming.
Introduced in the late 1970s, this approach to programming spawned
new programming languages (PASCAL, ALGOL, PL/1 and so forth)
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 to facilitate 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 (OOP) has been the
industry "poster child" for code reusability. By enabling program
logic and the data structures that logic manipulates to be
encapsulated into easily stored and retrieved (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 languages and only
these, by and large, it's no surprise that -- today --
object-oriented programming languages are the darlings of the
industry.
The reality is, however, that good programmers have been
practicing code reusability for more than a half-century. Up
until recently, COBOL programmers have had some of the best code
reusability tools available -- they've been doing it with
copybooks and subprograms rather than classes, methods and
attributes but the net results have been similar. With the
COBOL2002 standard and proposed COBOL20xx standard, the COBOL
programming language has become just as "object-oriented" as the
"modern" languages, while preserving the ability to support,
modify, compile and execute "legacy" COBOL programs as well.
While GNU COBOL supports few of the OOP programming constructs defined
by the COBOL2002 and COBOL20xx standards, it supports every aspect of
the ANSI85 standard and therefore fully meets the needs of points #1
and #2, above. With it's supported feature set (*note So What is GNU
COBOL?::), it provides significant programmer productivity
capabilities.
File: gnucobpg.info, Node: So What is GNU COBOL?, Up: Introduction
1.3. So What is GNU COBOL?
==========================
GNU COBOL is an open source COBOL compiler and runtime environment,
written using the C programming language. GNU COBOL is typically
distributed in source-code form, and must then be built for your
computer's operating system using the system's C compiler and loader.
While originally developed for the UNIX and Linux operating systems,
GNU COBOL has also been successfully built for OSX computers or Windows
computers utilizing the UNIX-emulation features of such tools as Cygwin
and MinGW.
The MinGW approach is a personal favorite with the author of this
manual because it creates a GNU COBOL compiler and runtime library that
require only a single MinGW DLL to be available for the GNU COBOL
compiler, runtime library and user programs. That DLL is freely
distributable under the terms of the GNU General Public License. A
MinGW build of GNU COBOL 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 GNU COBOL
programs and record locking on certain types of files, is sacrificed
however as the underlying operating system routines needed to implement
them aren't available to Windows and aren't provided by MinGW.
GNU COBOL has also been built as a truly native Windows application
utilizing Microsoft's freely-downloadable Visual Studio Express package
to provide the C compiler and linker/loader. This approach does not
lend itself well to a "portable" distribution.
The GNU COBOL compiler generates C code from your COBOL programs; that
C code is then automatically compiled and linked using your system's C
compiler (typically, but not limited to, "gcc").
GNU COBOL fully supports much of the ANSI85 standard for COBOL (the
only major exclusion is the Communications Module) and also supports
some of the components of the COBOL2002 standard, such as the "SCREEN
SECTION" (*note SCREEN SECTION::), table-based "SORT" (*note Table
SORT::) and user-defined functions.
* Menu:
* 1.3.1: Language Reserved Words.
* 1.3.2: User-Defined Words.
* 1.3.3: Case Insensitivity.
* 1.3.4: Readability of Programs.
* 1.3.5: Divisions Organize Programs.
* 1.3.6: Copybooks.
* 1.3.7: Structured Data.
* 1.3.8: Files.
* 1.3.9: Table Handling.
* 1.3.10: Sorting and Merging Data.
* 1.3.11: String Manipulation Features.
* 1.3.12: Screen Formatting Features.
* 1.3.12.1: A Sample Screen.
* 1.3.12.2: Color Palette and Video Attributes.
* 1.3.13: Report Writer Features.
* 1.3.14: Data Initialization.
* 1.3.15: Syntax Diagram Conventions.
* 1.3.16: Format of Program Source Lines.
* 1.3.17: Program Structure.
* 1.3.18: Comments.
* 1.3.19: Literals.
* 1.3.19.1: Numeric Literals.
* 1.3.19.2: Alphanumeric Literals.
* 1.3.19.3: Figurative Constants.
* 1.3.20: Punctuation.
* 1.3.21: LENGTH OF.
* 1.3.22: Interfacing to Other Environments.
File: gnucobpg.info, Node: Language Reserved Words, Next: User-Defined Words, Up: So What is GNU COBOL?
1.3.1. Language Reserved Words
------------------------------
COBOL programs consist of a sequence of words and symbols. Words,
which consist of sequences of letters (upper- and/or lower-case),
digits, dashes ("-") and/or underscores ("_") may have a pre-defined,
specific, meaning to the compiler or may be invented by the programmer
for his/her purposes.
The GNU COBOL language specification defines over 700 'Reserved Words' --
words to which the compiler assigns a special meaning.
Programmers may use a reserved word as part of a word they are creating
themselves, but may not create their own word as an exact duplicate
(without regard to case) of a COBOL reserved word.
*Note Appendix B - Reserved Word List::, for a complete list of GNU
COBOL reserved words.
File: gnucobpg.info, Node: User-Defined Words, Next: Case Insensitivity, Prev: Language Reserved Words, Up: So What is GNU COBOL?
1.3.2. User-Defined Words
-------------------------
When you write GNU COBOL programs, you'll need to create a variety of
words to represent various aspects of the program, the program's data
and the external environment in which the program will run. This will
include internal names by which data files will be referenced, data
item names and names of executable logic procedures.
User-defined words may be composed from the characters "A" through "Z"
(upper- and/or lower-case), "0" through "9", dash ("-") and underscore
("_"). User-defined words may neither start nor end with hyphen or
underscore characters.
Other programming language provide the programmer with a similar
capability of creating their own words (names) for parts of a program;
COBOL is somewhat unusual when compared to other languages in that
user-defined words may start with a digit.
With the exception of logic procedure names, which may consist entirely
of nothing but digits, user-defined words must contain at least one
letter.
File: gnucobpg.info, Node: Case Insensitivity, Next: Readability of Programs, Prev: User-Defined Words, Up: So What is GNU COBOL?
1.3.3. Case Insensitivity
-------------------------
All COBOL implementations allow the use of both upper and lowercase
letters in program coding. GNU COBOL is completely insensitive to the
case used when writing reserved words or user-defined names. Thus,
"AAAAA", "aaaaa", "Aaaaa" and "AaAaA" are all the same word as far as
GNU COBOL is concerned.
The only time the case used does matter is within quoted character
strings, where character values will be exactly as coded.
By convention throughout this document, COBOL reserved words will be
shown entirely in UPPERCASE while those words that were created by a
programmer will be represented by tokens in mixed or lower case.
This isn't a bad practice to use in actual programs, as it leads to
programs where it is much easier to distinguish reserved words from
user-defined ones!
File: gnucobpg.info, Node: Readability of Programs, Next: Divisions Organize Programs, Prev: Case Insensitivity, Up: So What is GNU COBOL?
1.3.4. Readability of Programs
------------------------------
The most vociferous critics of COBOL frequently focus on the wordiness
of the language, often citing the case of a so-called "Hello World"
program as the "proof" that COBOL is so much more tedious to program in
than more "modern" languages. This tedium is cited as such a
significant impact to programmer productivity that, in their opinions,
COBOL can't go away quickly enough.
Here are two different "Hello World" applications -- one written in
Java and the second in GNU COBOL. First, the Java version:
Class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello World!");
}
}
And here is the same program, written in GNU COBOL:
IDENTIFICATION DIVISION.
PROGRAM-ID. HelloWorld.
PROCEDURE DIVISION.
DISPLAY "Hello World!".
Both of the above programs could have been written on a single line, if
desired, and both languages allow a programmer to use (or not use)
indentation as they see fit to improve program readability. Sounds
like a tie so far.
Let's look at how much more "wordy" COBOL is than Java. Count the
characters in the two programs. The Java program has 95 (not counting
carriage returns and any indentation). The COBOL program has 89
(again, not counting carriage returns and indentation)! Technically,
it could have been only 65 because the "IDENTIFICATION DIVISION."
header is actually optional. Clearly, "Hello World" doesn't look any
more concise in Java than it does in COBOL.
Let's look at a different problem. Surely a program that asks a user
to input a positive integer, generates the sum of all positive integers
from 1 to that number and then prints the result will be MUCH shorter
and MUCH easier to understand when coded in Java than in COBOL, right?
You can be the judge. First, the Java version:
import java.util.Scanner;
public class sumofintegers {
public static void main(String[] arg) {
System.out.println("Enter a positive integer");
Scanner scan=new Scanner(System.in);
int n=scan.nextInt();
int sum=0;
for (int i=1;i<=n;i++) {
sum+=i;
}
System.out.println("The sum is "+sum);
}
}
And now for the COBOL version:
IDENTIFICATION DIVISION.
PROGRAM-ID. SumOfIntegers.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 n BINARY-LONG.
01 i BINARY-LONG.
01 sum BINARY-LONG VALUE 0.
PROCEDURE DIVISION.
DISPLAY "Enter a positive integer"
ACCEPT n
PERFORM VARYING i FROM 1 BY 1 UNTIL i > n
ADD i TO sum
END-PERFORM
DISPLAY "The sum is " sum.
My familiarity with COBOL may be prejudicing my opinion, but it doesn't
appear to me that the Java code is any simpler than the COBOL code. In
case you're interested in character counts, the Java code comes in at
278 (not counting indentation characters). The COBOL code is 298 (274
without the "IDENTIFICATION DIVISION." header).
Despite what you've seen here, the more complex the programming logic
being implemented, the more concise the Java code will appear to be,
even compared to 2002-standard COBOL. That conciseness comes with a
price though -- program code readability. Java (or C or C++ or C#)
programs are generally intelligible only to trained programmers. COBOL
programs can, however, be quite understandable by non-programmers.
This is actually a side-effect of the "wordiness" of the language,
where COBOL statements use natural English words to describe their
actions. This inherent readability has come in handy many times
throughout my career when I've had to learn obscure business (or legal)
processes by reading the COBOL program code that supports them.
The "modern" languages, like Java, also have their own "boilerplate"
infrastructure overhead that must be coded in order to write the logic
that is necessary in the program. Take for example the "public static
void main(String[] arg)" and "import java.util.Scanner;" statements.
The critics tend to forget about this when they criticize COBOL for
it's structural "overhead".
When it first was developed, COBOL's easily-readable syntax made it
profoundly different from 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:
EXT = PRICE * IQTY
INVTOT = INVTOT + EXT
With its original limitation on the length of variable names (one- to
six-character names comprised of a letter followed by up to five
letters and/or digits), it's implicit rule that variable were
automatically created as real (floating-point) unless their name
started with a letter in the range I-N, and its use of algebraic
notation to express actions being taken, FORTRAN wasn't a particularly
readable language, even for programmers. Compare this with the
equivalent COBOL code:
MULTIPLY price BY quantity GIVING extended-amount
ADD 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, and COBOL introduced a more formula-based
syntactical capability for arithmetic operations, but FORTRAN was never
as readable as COBOL.
Because of its inherent readability, 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++, C# or Java
program.
Those that argue that it is too boring / wasteful / time-consuming /
insulting (pick one) to have to code a COBOL program "from scratch" are
clearly ignorant of the following facts:
* Many systems have program-development tools available to ease the
task of coding programs; those tools that 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 editor and you've got a good
start to the program...
* Legend has it that there's actually only been ONE program ever
written in COBOL, and all programs ever "written" thereafter were
simply derivatives of that one. Although this is clearly intended
as a (probably) bad joke, it is nevertheless close to the very
simple truth that many programers"reuse" existing COBOL programs
when creating new ones. There's certainly nothing preventing this
from happening with programs written in other languages, but it
does seem to happen more in COBOL shops. It's ironic that "code
reusability" is one of the arguments used to justify the existence
of the "modern" languages.
File: gnucobpg.info, Node: Divisions Organize Programs, Next: Copybooks, Prev: Readability of Programs, Up: So What is GNU COBOL?
1.3.5. Divisions Organize Programs
----------------------------------
COBOL programs are structured into four major areas of coding, each
with its 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 paragraph 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 this manual describes the
various divisions, sections, paragraphs and statements that may
comprise any COBOL program.
File: gnucobpg.info, Node: Copybooks, Next: Structured Data, Prev: Divisions Organize Programs, Up: So What is GNU COBOL?
1.3.6. Copybooks
----------------
A 'Copybook' is a segment of program code that may be utilized by
multiple programs simply by having those programs use the "COPY"
statement (*note COPY::) to import that code. This code may define
files, data structures or procedural code.
Today's current programming languages have a statement (usually, this
statement is named "import", "include" or "#include") that performs
this same function. What makes the COBOL copybook feature different
than the "include" facility in newer languages, however, is the fact
that the "COPY" statement can edit the imported source code as it is
being copied. This capability makes copybook libraries extremely
valuable to making code reusable.
File: gnucobpg.info, Node: Structured Data, Next: Files, Prev: Copybooks, Up: So What is GNU COBOL?
1.3.7. Structured Data
----------------------
A contiguous area of storage within the memory space of a program that
may be referenced, by name, in a COBOL program is referred to as a
'Data Item'. Other programming languages use the term variable,
property or attribute to describe the same thing.
COBOL introduced the concept of structured data. The principle of
structured data in COBOL is based on the idea of being able to group
related and contiguously-allocated data items together into a single
aggregate data item, called a 'Group Item'. For example, a
35-character 'Employee-Name' group item might consist of a 20-character
'Last-Name' followed by a 14-character 'First-Name' and a 1-character
'Middle-Initial'.
A data item that isn't itself formed from other data items is referred
to in COBOL as an 'Elementary Item'. In the previous example,
'Last-Name', 'First-Name' and 'Middle-Initial' are all elementary
items.
File: gnucobpg.info, Node: Files, Next: Table Handling, Prev: Structured Data, Up: So What is GNU COBOL?
1.3.8. Files
------------
One of COBOLs strengths is the wide variety of data files it is capable
of accessing. GNU COBOL programs, like those created with other COBOL
implementations, need to have the structure of any files they will be
reading and/or writing described to them. The highest-level
characteristic of a file's structure is defined by specifying the
organization of the file, as follows:
"ORGANIZATION LINE SEQUENTIAL"
These are files with the simplest of all internal structures.
Their contents are structured simply as a series of identically-
or differently-sized 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, OSX) GNU COBOL build. A
truly native Windows build would use a carriage-return, line-feed
(hexadecimal 0D0A) sequence.
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 to by a GNU COBOL program, the delimiter
sequence will be automatically appended to each data record as it
is written to the file. A "WRITE" (*note WRITE::) to this type of
file will be done as if a "BEFORE ADVANCING 1 LINE" clause were
specified on the "WRITE", if no "ADVANCING" clause is coded.
When the file is read, the GNU COBOL runtime system will strip the
trailing delimiter sequence from each record. The data will be
padded (on the right) with spaces if the data just read is shorter
than the area described for data records in the program. If the
data is too long, it will be truncated and the excess will be
lost.
These files should not be defined to contain any exact binary data
fields because the contents of 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.
"LINE ADVANCING"
These are files with an internal structure similar to that of a
line sequential file. These files are defined (without an
explicit "ORGANIZATION" specification) using the "LINE ADVANCING"
clause on their "SELECT" statement (*note SELECT::).
When this kind of file is written to by a GNU COBOL program, an
end-of-record delimiter sequence will be automatically added to
each data record as it is written to the file. A "WRITE" to this
type of file will be done as if an "AFTER ADVANCING 1 LINE" clause
were specified on the "WRITE", if no "ADVANCING" clause is coded.
Like line sequential files, these files should not be defined to
contain any exact binary data fields because the contents of 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 SEQUENTIAL"
These files also have a simple internal structure. Their contents
are structured simply as an arbitrarily-long sequence of data
characters. This sequence of characters will be treated as a
series of fixed-length records simply by logically splitting the
sequence of characters up into fixed-length segments, each as long
as the maximum record size defined in the program. There are no
special end-of-record delimiter characters in the file and when
the file is written to by a GNU COBOL program, no delimiter
sequence is appended to the data.
Records in this type of file are all the same physical length,
except possibly for the very last record in the file, which may be
shorter than the others. If variable-length logical records are
defined to the program, the space occupied by each physical record
in the file will occupy the space described by the longest record
description in the program.
So, if a file contains 1275 characters of data, and a program
defines the structure of that file as containing 100-character
records, then the file contents will consist of twelve (12)
100-character records with a final record containing only 75
characters.
It would appear that it should be possible to locate and process
any record in the file directly simply by calculating its starting
character position based upon the program-defined record size.
Even so, however, records must be still be read 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 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 padded
(to the right) with spaces.
Care must be taken that programs reading such a file describe
records whose length is exactly the same as that used by the
program that created the file. For example, the following shows
the contents of a "SEQUENTIAL" file created by a program that
wrote five 6-character records to it. The "A", "B", ... values
reflect the records that were written to the file:
`AAAAAABBBBBBCCCCCCDDDDDDEEEEEE'
Now, assume that another program reads this file, but describes
10-character records rather than 6. Here are the records that
program will read:
`AAAAAABBBB'
`BBCCCCCCDD'
`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" the same record sizes and layouts
by coding a "COPY" statement (*note COPY::) to import the record
layout(s) rather than hand-coding them.
These files can contain exact binary data fields. This is
possible because -- since there is no character sequence that
constitutes an end-of-record delimiter -- the contents of record
fields are irrelevant to the reading process.
"ORGANIZATION RELATIVE"
The contents of these files consist of a series of fixed-length
data records prefixed with a four-byte record header. The record
header contains the length of the data, 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 are defined to the program, the
space occupied by each physical record in the file will occupy the
maximum possible space, and the logical record length field will
contaoin the number of bytes of data in the record that are
actually in use.
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
have first read or written records 1-99. The GNU COBOL 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 a GNU COBOL program, no delimiter
sequence is appended to the data, 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 end well if the GNU
COBOL runtime library interprets 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 that multiple programs accessing that file
will "see" the same record sizes and layouts by coding a "COPY"
statement (*note COPY::) to import the record layout(s) rather
than hand-coding them.
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 INDEXED"
This is the most advanced file structure available to GNU COBOL
programs. It's not possible to describe the physical structure of
such files because that structure will vary depending upon which
advanced file-management facility was included into the GNU COBOL
build you will be using (Berkeley Database [BDB], VBISAM, etc.).
We will -- instead -- discuss the logical structure of 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 case with 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 be converted to a record number so that the data record
for any given primary key value can be directly read, written
and/or deleted. Additionally, the index data structure is defined
in such a manner 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 binary-searchable 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 actual mechanism used will depend upon the
advanced file-management package was included into your GNU COBOL
implementation when it was built.
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
to record 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 the alternate
key field is described to the GNU COBOL compiler.
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 will
take 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 a GNU COBOL program using a
"SELECT" statement (*note SELECT::). In addition to defining a name 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 and
sharing attributes.
A file description in the "FILE SECTION" (*note FILE SECTION::) will
define 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.
File: gnucobpg.info, Node: Table Handling, Next: Sorting and Merging Data, Prev: Files, Up: So What is GNU COBOL?
1.3.9. Table Handling
---------------------
Other programming languages have arrays, COBOL has tables. They're
basically the same thing. There are two special statements that exist
in the COBOL language -- "SEARCH" (*note SEARCH::) and "SEARCH ALL"
(*note SEARCH ALL::) -- that make finding data in a table easy.
The first can search a table sequentially, stopping only when either a
table entry matching one of any number of search conditions is found,
or when all table entries have been checked against the search criteria
and none matched any of those criteria.
The second can perform an extremely fast search against a table sorted
by and searched against a key field contained 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 a desired
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 binary search of a table containing 32,768 entries will
be able to locate a particular entry or determine the entry doesn't
exist by looking at no more than fifteen (15) entries! The algorithm
is explained in detail in the documentation of the "SEARCH ALL"
statement (*note SEARCH ALL::).
Finally, COBOL has the ability to perform in-place sorts of the data
that is found in a table.
File: gnucobpg.info, Node: Sorting and Merging Data, Next: String Manipulation Features, Prev: Table Handling, Up: So What is GNU COBOL?
1.3.10. Sorting and Merging Data
--------------------------------
The COBOL language includes a powerful "SORT" statement (*note SORT::)
that can sort large amounts of data according to arbitrarily complex
key structures. This data may originate from within the program or may
be contained in one or more external files. The sorted data may be
written automatically to one or more output files or may be processed,
record-by-record in the sorted sequence.
A companion statement -- "MERGE" (*note MERGE::) -- can combine the
contents of multiple files together, provided those files are all
pre-sorted in a similar manner according to the same key structure.
The resulting output will consist of the contents of all of the input
files, merged together and sequenced according to the common key
structure(s). The output generated by a "MERGE" statement may be
written automatically to one or more output files or may be processed
internally by the program.
A special form of the "SORT" statement also exists just to sort the
data that resides in a table. This is particularly useful if you wish
to use "SEARCH ALL" against the table.
File: gnucobpg.info, Node: String Manipulation Features, Next: Screen Formatting Features, Prev: Sorting and Merging Data, Up: So What is GNU COBOL?
1.3.11. String Manipulation Features
------------------------------------
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.
COBOL is no exception, although it does include some very powerful
string manipulation capabilities; GNU COBOL actually has even more
string-manipulation capabilities than many other COBOL implementations.
The following summarizes GNU COBOL's string-processing capabilities:
Concatenate two or more strings:
* "CONCATENATE" intrinsic function (*note CONCATENATE::).
* "STRING" statement (*note STRING::).
Conversion of a numeric time or date to a formatted character string:
* "LOCALE-TIME" intrinsic function (*note LOCALE-TIME::).
* "LOCALE-DATE" intrinsic function (*note LOCALE-DATE::).
Convert a binary value to its corresponding character in the program's
characterset:
* "CHAR" intrinsic function (*note CHAR::). Add 1 to argument
before invoking the function; the description of the "CHAR"
intrinsic function presents a technique utilizing the "MOVE"
statement that will accomplish the same thing without the need of
adding 1 to the numeric argument value first.
Convert a character string to lower-case:
* "LOWER-CASE" intrinsic function (*note LOWER-CASE::).
* "C$TOLOWER" built-in system subroutine (*note C$TOLOWER::).
* "CBL_TOLOWER" built-in system subroutine (*note CBL_TOLOWER::).
Convert a character string to upper-case:
* "UPPER-CASE" intrinsic function (*note UPPER-CASE::).
* "C$TOUPPER" built-in system subroutine (*note C$TOUPPER::).
* "CBL_TOUPPER" built-in system subroutine (*note CBL_TOUPPER::).
Convert a character string to only printable characters:
* "C$PRINTABLE" built-in system subroutine (*note C$PRINTABLE::).
Convert a character to its numeric value in the program's
characterset:
* "ORD" intrinsic function (*note ORD::). Subtract 1 from the
result; the description of the "ORD" intrinsic function presents a
technique utilizing the "MOVE" statement that will accomplish the
same thing without the need of adding 1 to the numeric argument
value first.
Count occurrences of substrings in a larger string:
* "INSPECT" statement (*note INSPECT::) with the "TALLYING" clause.
Decode a formatted numeric string back to a numeric value:
* "NUMVAL" intrinsic function (*note NUMVAL::).
* "NUMVAL-C" intrinsic function (*note NUMVAL-C::).
Determine the length of a string or data-item capable of storing
strings:
* "LENGTH" intrinsic function (*note LENGTH::).
* "BYTE-LENGTH" intrinsic function (*note BYTE-LENGTH::).
Extract a substring from a string based on its starting character
position and length:
* Use of a reference modifier on the string field - *Note Reference
Modifiers::.
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:
* "MOVE" statement (*note MOVE::) with picture-symbol editing
applied to the receiving field:
Justification (left, right or centered) of a string field:
* "C$JUSTIFY" built-in system subroutine (*note C$JUSTIFY::).
Monoalphabetic substitution of one or more characters in a string with
different characters:
* "INSPECT" statement (*note INSPECT::) with the "CONVERTING".
* "TRANSFORM" statement (*note TRANSFORM::).
* "SUBSTITUTE" intrinsic function (*note SUBSTITUTE::).
* "SUBSTITUTE-CASE" intrinsic function (*note SUBSTITUTE-CASE::).
Parse a string, breaking it up into substrings based upon one or more
delimiting character sequences(1):
* "UNSTRING" statement (*note UNSTRING::).
Removal of leading or trailing spaces from a string:
* "TRIM" intrinsic function (*note TRIM::).
Substitution of a single substring with another of the same length,
based upon the substrings starting character position and length:
* "MOVE" statement (*note MOVE::) with a reference modifier on the
"receiving" field (*note Reference Modifiers::).
Substitution of one or more substrings in a string with replacement
substrings of the same length, regardless of where they occur:
* "INSPECT" statement (*note INSPECT::) with a "REPLACING" clause.
* "SUBSTITUTE" intrinsic function (*note SUBSTITUTE::).
* "SUBSTITUTE-CASE" intrinsic function (*note SUBSTITUTE-CASE::).
Substitution of one or more substrings in a string with replacement
substrings of a potentially different length, regardless of where they
occur:
* "SUBSTITUTE" intrinsic function (*note SUBSTITUTE::).
* "SUBSTITUTE-CASE" intrinsic function (*note SUBSTITUTE-CASE::).
---------- Footnotes ----------
(1) These delimiters may be single characters, multiple-character
strings or multiple consecutive occurrences of either
File: gnucobpg.info, Node: Screen Formatting Features, Prev: String Manipulation Features, Up: So What is GNU COBOL?
1.3.12. Screen Formatting Features
----------------------------------
The COBOL2002 standard formalizes extensions to the COBOL language that
allow for the definition and processing of text-based screens, as is a
typical function on mainframe and midframe computers as well as on many
point-of-sale (i.e. "cash register") systems. GNU COBOL implements
virtually all the screen-handling features described by COBOL2002.
These features allow fields to be displayed at specific row/column
positions, various colors and video attributes to be assigned to screen
fields and the pressing of specific function keys (F1, F2, ...) to be
detectable. All of this takes place through the auspices of the
"SCREEN SECTION" (*note SCREEN SECTION::) and special formats of the
"ACCEPT" statement (*note ACCEPT::) and the "DISPLAY" statement (*note
DISPLAY::).
The COBOL2002 standard, and therefore GNU COBOL, only covers textual
user interface (TUI) screens (those comprised of ASCII characters
presented using a variety of visual attributes) and not the
more-advanced graphical user interface (GUI) screen design and
processing capabilities built into most modern operating systems.
There are subroutine-based packages available that can do full GUI
presentation -- most of which may be called by GNU COBOL programs, with
a moderate research time investment (Tcl/Tk, for example) -- but none
are currently included with GNU COBOL.
* Menu:
* 1.3.12.1: A Sample Screen.
* 1.3.12.2: Color Palette and Video Attributes.
File: gnucobpg.info, Node: A Sample Screen, Next: Color Palette and Video Attributes, Up: Screen Formatting Features
1.3.12.1. A Sample Screen
.........................
A Sample Screen Produced by a GNU COBOL Program:
================================================================================
GCic (2014/01/02 11:24) GNU COBOL 2.1 23NOV2013 Interactive Compilation
+------------------------------------------------------------------------------+
: Filename: GCic.cbl :
: Folder: E:\Programs\GCic\2013-11-23 :
+------------------------------------------------------------------------------+
Set/Clr Switches Via F1-F9; Set Config Via F12; ENTER Key Compiles; ESC Quits
+------------------------------------------------------------------------------+
: F1 Assume WITH DEBUGGING MODE F6 >"FUNCTION" Is Optional : Current :
: F2 Procedure+Statement Trace F7 >Enable All Warnings : Config: :
: F3 Make a Library (DLL) F8 Source Is Free-Format : DEFAULT :
: F4 Execute If Compilation OK F9 >No COMP/BINARY Truncation : :
: F5 Listing Off : :
+------------------------------------------------------------------------------+
Extra "cobc" Switches, If Any ("-save-temps=xxx" Prevents Listings):
+------------------------------------------------------------------------------+
: ____________________________________________________________________________ :
: ____________________________________________________________________________ :
+------------------------------------------------------------------------------+
Program Execution Arguments, If Any:
+------------------------------------------------------------------------------+
: ____________________________________________________________________________ :
: ____________________________________________________________________________ :
+------------------------------------------------------------------------------+
GCic for Windows/MinGW Copyright (C) 2009-2014, Gary L. Cutler, GPL
================================================================================
The above screen was produced by the GNU COBOL Interactive Compiler, or
GCic. *Note GCic: (gnucobsp.info)GCic, for the source and
cross-reference listing of this program. PDF versions of this document
will include an actual graphical image of this sample screen.
Screens are defined in the screen section of the data division. Once
defined, screens are used at run-time via the "ACCEPT" and "DISPLAY"
statements.
File: gnucobpg.info, Node: Color Palette and Video Attributes, Prev: A Sample Screen, Up: Screen Formatting Features
1.3.12.2. Color Palette and Video Attributes
............................................
GNU COBOL supports the following visual attribute specifications in the
"SCREEN SECTION" (*note SCREEN SECTION::):
Color
Eight (8) different colors may be specified for both the
background (screen) and foreground (text) color of any row/column
position on the screen. Colors are specified by number, although
a copybook supplied with all GNU COBOL distributions
("screenio.cpy") defines COB-COLOR-xxxxxx names for the various
colors so they may be specified as a more meaningful name rather
than a number. The eight colors, by number, with the constant
nams defined in screenio.cpy, are as follows:
0. Black: COB-COLOR-BLACK
1. Blue: COB-COLOR-BLUE
2. Green: COB-COLOR-GREEN
3. Cyan (Turquoise): COB-COLOR-CYAN
4. Red: COB-COLOR-RED
5. Magenta: COB-COLOR-MAGENTA
6. Yellow: COB-COLOR-YELLOW
7. White: COB-COLOR-WHITE
Text Brightness
There are three possible brightness levels supported for text --
lowlight (dim), normal and highlight (bright). Not all GNU COBOL
implementations will support all three (some treat lowlight the
same as normal). The deciding factor as to whether two or three
levels are supported lies with the version of the "curses" package
that is being used. This is a utility screen-IO package that is
included into the GNU COBOL run-time library when the GNU COBOL
software is built.
As a general rule of thumb, Windows implementations support two
levels while Unix ones support all three.
Blinking
This too is a video feature that is dependent upon the "curses"
package built into your version of GNU COBOL. If blinking is
enabled in that package, text displayed in fields defined in the
screen section as being blinking will endlessly cycle between the
brightest possible setting (highlight) and an "invisible" setting
where the text color matches that of the field background color.
A Windows build, which generally uses the "pcurses" package, will
uses a brighter-than-normal background color to signify
"blinking".
Reverse Video
This video attribute simply swaps the foreground and background
colors and display options.
Field Outlining
It is possible, if supported by the "curses" package being used,
to draw borders on the top, left and/or bottom edges of a field.
Secure Input
If desired, screen fields used as input fields may defined as
"secure" fields, where each input character (regardless of what
was actually typed) will appear as an asterisk (*) character. The
actual character whose key was pressed will still be stored into
the field in the program, however. This is very useful for
password or account number fields.
Prompt Character
Input fields may have any character used as a fill character.
These fill characters provide a visual indication of the size of
the input field, and will automatically be transformed into spaces
when the input field is propcessed by the program. If no such
character is defined for an input field, an underscore ("_") will
be assumed.
*Note Colors: (gnucobsp.info)Colors, for a source and cross-reference
listing of a program (Colors.cbl) that can be used to display a test
screen illustrating all available video formatting options.
File: gnucobpg.info, Node: Report Writer Features, Next: Data Initialization, Up: So What is GNU COBOL?
1.3.13. Report Writer Features
------------------------------
GNU COBOL includes an implementation of the Report Writer Control
System, or RWCS. This is a standardized, optional add-on feature to
the COBOL language which automates much of the mechanics involved in
the generation of printed reports by:
1. Controlling the pagination of reports, including:
A. The automatic production of a one-time notice on the first
page of the report (report heading).
B. The production of zero or more header lines at the top of
every page of the report (page heading).
C. The production of zero or more footer lines at the bottom of
every page of the report (page footing).
D. The automatic numbering of printed pages.
E. The formatting of those report lines that make up the main
body of the report (detail).
F. Full awareness of where the "pen" is about to "write" on the
current page, automatically forcing an eject to a new page,
along with the automatic generation of a page footer to close
the old page and/or a page header to begin the new one.
G. The production of a one-time notice at the end of the last
page of a report (report footing).
2. Performing special reporting actions based upon the fact that the
data being used to generate the report has been sorted according
to one or more key fields:
A. Automatically suppressing the presentation of one or more
fields of data from the detail group when the value(s) of the
field(s) duplicate those of the previously generated detail
group. Fields such as these are referred to as
group-indicate fields.
B. Automatically causing suppressed detail group-indicate fields
to re-appear should a detail group be printed on a new page.
C. Recognizing when control fields on the report -- fields tied
to those that were used as "SORT" statement (*note SORT::)
keys -- have changed. This is known as a control break. The
RWCS can automatically perform the following reporting
actions when a control break occurs:
* Producing a footer, known as a control footing after the
detail lines that shared the same old value for the
control field.
* Producing a header, known as a control heading before
the detail lines that share the same new value for the
control field.
3. Perform data summarization, as follows:
A. Automatically generating subtotals in control and/or report
footings, summarizing values of any fields in the detail
group.
B. Automatically generating crossfoot totals in detail groups.
These would be sums of two or more values presented in the
detail group.
The "REPORT SECTION" (*note REPORT SECTION::) documentation explores
the description of reports and the "PROCEDURE DIVISION" (*note
PROCEDURE DIVISION::) chapter documents the various language statements
that actually produce reports. Before reading these, you might find it
helpful to read *Note Report Writer Usage Notes::, which is dedicated
to putting the pieces together for you.
File: gnucobpg.info, Node: Data Initialization, Next: Syntax Diagram Conventions, Prev: Report Writer Features, Up: So What is GNU COBOL?
1.3.14. Data Initialization
---------------------------
There are three ways in which data division data gets initialized.
1. When a program or subprogram is first executed, much of the data
in it's data division will be initialized as follows:
* Alphanumeric and alphabetic (i.e. text) data items will be
initialized to "SPACES".
* Numeric data items will be initialized to a value of "ZERO".
* Data items with an explicit "VALUE" (*note VALUE::) clause in
their definition will be initialized to that specific value.
The various sections of the data division each have their own
rules as to when the actions described above will occur -- consult
the documentation on those sections for additional information.
These default initialization rules can vary quite substantially
from one COBOL implementation to another. For example, it is
quite common for data division storage to be initialized to all
binary zeros except for those data items where "VALUE" clauses are
present. Take care when working with applications originally
developed for another COBOL implementation to ensure that GNU
COBOL's default initialization rules won't prove disruptive.
2. A programmer may use the "INITIALIZE" statement (*note
INITIALIZE::) to intitialize any group or elementary data item at
any time. This statement provides far more initialization options
than just the simple rules stated above.
3. When the "ALLOCATE" statement (*note ALLOCATE::) statement is used
to allocate a data item or to simply allocate an area of storage
of a size specified on the "ALLOCATE", that allocation may occur
with or without initialization, as per the programmer's needs.
File: gnucobpg.info, Node: Syntax Diagram Conventions, Next: Format of Program Source Lines, Prev: Data Initialization, Up: So What is GNU COBOL?
1.3.15. Syntax Diagram Conventions
----------------------------------
Syntax of the GNU COBOL language will be described in special "syntax
diagrams" using the following syntactical-description techniques:
MANDATORY-RESERVED-WORD
~~~~~~~~~~~~~~~~~~~~~~~
Reserved words of the COBOL language will appear in UPPERCASE.
When they appear underlined, as this one is, they are required
reserved words.
OPTIONAL-RESERVED-WORD
When reserved words appear without underlining, as this one is,
they are optional; such reserved words are available in the
language syntax merely to improve readability -- their presence or
absence has no effect upon the program.
ABBREVIATION
~~~~
When only a portion of a reserved word is underlined, it indicates
that the word may either be coded in its full form or may be
abbreviated to the portion that is underlined.
substitutable-items
Generic terms representing user-defined substitutable items will
be shown entirely in lowercase in syntax diagrams. When such
items are referenced in text, they will appear as
.
Complex-Syntax-Clause
Items appearing in Mixed Case within a syntax diagram represent
complex clauses of other syntax elements that may appear in that
position. Some COBOL syntax gets quite complicated, and using a
convention such as this significantly reduces the complexity of a
syntax diagram. When such items are referenced in text, they will
appear as <>.
[ ]
Square bracket metacharacters on syntax diagrams document language
syntax that is optional. The [] characters themselves should not
be coded. If a syntax diagram contains "a [b] c", the "a" and "c"
syntax elements are mandatory but the "b" element is optional.
|
Vertical bar metacharacters on syntax diagrams document simple
choices. The | character itself should not be coded. If a syntax
diagram contains "a|b|c", exactly one of the items "a", "b" or "c"
must be selected.
{ xxxxxx }
{ yyyyyy }
{ zzzzzz }
A vertical list of items, bounded by multiple brace characters, is
another way of signifying a choice between a series of items where
exactly one item must be selected. This form is used to show
choices when one or more of the selections is more complex than
just a single word, or when there are too many choices to present
horizontally with "|" metacharacters.
| xxxxxx |
| yyyyyy |
| zzzzzz |
A vertical list of items, bounded by multiple vertical bar
characters, signifies a choice between a series of items where one
or more of the choices could be selected.
...
The ... metacharacter sequence signifies that the syntax element
immediately preceeding it may be repeated. The ... sequence
itself should not be coded. If a syntax diagram contains "a b...
c", syntax element "a" must be followed by at least one "b"
element (possibly more) and the entire sequence must be terminated
by a "c" syntax element.
{ }
The braces ({}) metacharacters may be used to group a sequence of
syntax elements together so that they may be treated as a single
entity. The {} characters themselves should not be coded. These
are typically used in combination with the "|" or "..."
metacharacters.
$*^()-+=:"'<,>./
Any of these characters appearing within a syntax diagram are to
be interpreted literally, and are characters that must be coded --
where allowed -- in the statement whose format is being described.
Note that a "." character is a literal character that must be
coded on a statement whereas a "..." symbol is the metacharacter
sequence described above.
File: gnucobpg.info, Node: Format of Program Source Lines, Next: Program Structure, Prev: Syntax Diagram Conventions, Up: So What is GNU COBOL?
1.3.16. Format of Program Source Lines
--------------------------------------
Prior to the COBOL2002 standard, source statements in COBOL programs
were structured around 80-column punched cards. This means that each
source line in a COBOL program consisted of five different "areas",
defined by their column number(s).
As of the COBOL2002 standard, a second mode now exists for COBOL source
code statements -- in this mode of operation, COBOL statements may each
be up to 255 characters long, with no specific requirements as to what
should appear in which columns.
Of course, in keeping with the long-standing COBOL tradition of
maintaining backwards compatibility with older standards, programmers
(and, of course, compliant COBOL compilers) are capable of working in
either mode. It is even possible to switch back and forth in the same
program. The terms 'Fixed Format Mode' and 'Free Format Mode' are
used to refer to these two modes of source code formatting.
The GNU COBOL compiler (cobc) supports both of these source line format
modes, defaulting to Fixed Format Mode lacking any other information.
The compiler can be instructed to operate in either mode in any of the
following four ways:
1. Using a compiler option switch -- use the "-fixed" switch to start
in Fixed Format Mode (remember that this is the default) or the
"-free" switch to start in Free Format Mode.
2. You may use the "SOURCEFORMAT AS FIXED" and "SOURCEFORMAT AS FREE"
clauses of the ">>SET" CDF directive (*note >>SET::) within your
source code to switch to Fixed or Free Format Mode, respectively.
3. You may use the ">>FORMAT IS FIXED" and "FORMAT IS FREE" clauses
of the ">>DEFINE" CDF directive (*note >>DEFINE::) within your
source code to switch to Fixed or Free Format Mode, respectively.
4. You may use the ">>SOURCE" CDF directive (*note >>SOURCE::) to
switch to Free Format Mode (">>SOURCE FORMAT IS FREE") or Fixed
Format Mode (">>SOURCE FORMAT IS FIXED".
Using methods 2-4 above, you may switch back and forth between the two
formats at will.
The last three options above are all equivalent; all three are
supported by GNU COBOL so that source code compatibility may be
maintained with a wide variety of other COBOL implementations. With
all three, if the compiler is currently in Fixed Format Mode, the ">>"
must begin in column 8 or beyond, provided no part of the directive
extends past column 72. If the compiler is currently in Free Format
Mode, the ">>" may appear in any column, provided no part of the
directive extends past column 255.
Depending upon which source format mode the compiler is in, you will
need to follow various rules for the format mode currently in effect.
These rules are presented in the upcoming paragraphs.
The following discussion presents the various components of every GNU
COBOL source line record when the compiler is operating in Fixed Format
Mode. Remember that this is the default mode for the GNU COBOL
compiler.
1-6 - Sequence Number Area
Historically, back in the days when punched-cards were used to
submit COBOL program source to a COBOL compiler, this part of a
COBOL statement was reserved for a six-digit sequence number.
While the contents of this area are ignored by COBOL compilers, it
existed so that a program actually punched on 80-character cards
could -- if the card deck were dropped on the floor -- be run
through a card sorter machine and restored to it's proper
sequence. Of course, this isn't necessary today; if truth be
told, it hasn't been necessary for a long time.
*Note Marking Changes in Programs::, for discussion of a valuable
use to which the sequence number area may be put today.
7 - Indicator Area
Column 7 serves as an indicator in which one of five possible
values will appear -- space, "D" (or "d"), "-" (dash), "/" or "*".
The meanings of these characters are as follows:
space
No special meaning -- this is the normal character that will
appear in this area.
D/d
The line contains a valid GNU COBOL statement that is
normally treated as a comment unless the program is being
compiled in debugging mode.
*
The line is a comment.
/
The line is a comment that will also force a page eject in
the compilation listing. While GNU COBOL will honor such a
line as a comment, it will not form-feed any generated
listing.
-
The line is a continuation of the previous line. These are
needed only when an alphanumeric literal (quoted character
string), reserved word or user-defined word are being split
across lines.
8-11 - Area "A"
Language DIVISION, SECTION and paragraph section headers must
begin in Area A, as must the level numbers 01, 77 in data
description entries and the "FD" and "SD" file and SORT
description headers.
12-72 - Area "B"
All other COBOL programming language components are coded in these
columns.
73-80 - Program Name Area
This is another obsolete area of COBOL statements. This part of
every statement also hails back to the day when programs were
punched on cards; it was expected that the name of the program (or
at least the first 8 characters of it) would be punched here so
that -- if a dropped COBOL source deck contained more than one
program -- that handy card sorter machine could be used to first
separate the cards by program name and then sort them by sequence
number. Today's COBOL compilers (including GNU COBOL) simply
ignore anything past column 72.
*Note Marking Changes in Programs::, for discussion of a valuable
use to which the program name area may be put today.
File: gnucobpg.info, Node: Program Structure, Next: Comments, Prev: Format of Program Source Lines, Up: So What is GNU COBOL?
1.3.17. Program Structure
-------------------------
Complete GNU COBOL Program Syntax
=======================================================================
[ IDENTIFICATION DIVISION. ]
~~~~~~~~~~~~~~~~~~~~~~~
PROGRAM-ID|FUNCTION-ID. name-1 [ Program-Options ] .
~~~~~~~~~~ ~~~~~~~~~~~
[ ENVIRONMENT DIVISION. ]
~~~~~~~~~~~ ~~~~~~~~
[ CONFIGURATION SECTION. ]
~~~~~~~~~~~~~ ~~~~~~~
[ SOURCE-COMPUTER. Compilation-Computer-Specification . ]
~~~~~~~~~~~~~~~
[ OBJECT-COMPUTER. Execution-Computer-Specification . ]
~~~~~~~~~~~~~~~
[ REPOSITORY. Function-Specification... . ]
~~~~~~~~~~
[ SPECIAL-NAMES. Program-Configuration-Specification . ]
~~~~~~~~~~~~~
[ INPUT-OUTPUT SECTION. ]
~~~~~~~~~~~~ ~~~~~~~
[ FILE-CONTROL. General-File-Description... . ]
~~~~~~~~~~~~
[ I-O-CONTROL. File-Buffering-Specification... . ]
~~~~~~~~~~~
[ DATA DIVISION. ]
~~~~~~~~~~~~~
[ FILE SECTION. Detailed-File-Description... . ]
~~~~~~~~~~~~
[ WORKING-STORAGE SECTION. Permanent-Data-Definition... . ]
~~~~~~~~~~~~~~~ ~~~~~~~
[ LOCAL-STORAGE SECTION. Temporary-Data-Definition... . ]
~~~~~~~~~~~~~ ~~~~~~~
[ LINKAGE SECTION. Subprogram-Argument-Description... . ]
~~~~~~~ ~~~~~~~
[ REPORT SECTION. Report-Description... . ]
~~~~~~ ~~~~~~~
[ SCREEN SECTION. Screen-Layout-Definition... . ]
~~~~~~ ~~~~~~~
PROCEDURE DIVISION [ { USING Subprogram-Argument... } ]
~~~~~~~~~ ~~~~~~~~ { ~~~~~ }
{ CHAINING Main-Program-Argument... }
~~~~~~~~
[ RETURNING identifier-1 ] .
[ DECLARATIVES. ] ~~~~~~~~~
~~~~~~~~~~~~
[ Event-Handler-Routine... . ]
[ END DECLARATIVES. ]
~~~ ~~~~~~~~~~~~
General-Program-Logic
[ Nested-Subprogram... ]
[ END PROGRAM|FUNCTION name-1 ]
~~~ ~~~~~~~ ~~~~~~~~
=======================================================================
Each program consists of up to four 'Divisions' (major groupings of
sections, paragraphs and descriptive or procedural coding that all
relate to a common purpose), named Identification, Environment, Data
and Procedure.
1. Not all divisions are needed in every program, but they must be
specified in the order shown when they are used.
2. The following points pertain to the identification division
* The "IDENTIFICATION DIVISION." header is always optional.
3. The following points pertain to the environment division:
* If both optional sections of this division are coded, they
must be coded in the sequence shown.
* Each of these sections consists of a series of specific
paragraphs ("SOURCE-COMPUTER" and "OBJECT-COMPUTER", for
example). Each of these paragraphs serves a specific
purpose. If no code is required for the purpose one of the
paragraphs serves, the entire paragraph may be omitted.
* If none of the paragraphs within one of the sections are
coded, the section header itself may be omitted.
* The paragraphs within each section may only be coded in that
section, but may be coded in any order.
* If none of the sections within the environment division are
coded, the "ENVIRONMENT DIVISION." header itself may be
omitted.
4. The following points pertain to the data division:
* The data division consists of six optional sections -- when
used, those sections must be coded in the order shown in the
syntax diagram.
* Each of these sections consists of code which serves a
specific purpose. If no code is required for the purpose one
of those sections serves, the entire section, including it's
header, may be omitted.
* If none of the sections within the data division are coded (a
highly unlikely, but theoretically possible circumstance),
the "DATA DIVISION." header itself may be omitted.
5. The following points pertain to the procedure division:
* As with the other divisions, the procedure division may
consist of sections and those sections may -- in turn --
consist of paragraphs. Unlike the other divisions, however,
section and paragraph names are defined by the programmer,
and there may not be any defined at all if the programmer so
wishes.
* Each Event-Handler-Routine will be a separate section devoted
to trapping a particular run-time event. If there are no
such sections coded, the "DECLARATIVES." and "END
DECLARATIVES." lines may be omitted.
6. A single file of COBOL source code may contain:
* A portion of a program; these files are known as copybooks
* A single program. In this case, the "END PROGRAM" or "END
FUNCTION" statement is optional.
* Multiple programs, separated from one another by "END
PROGRAM" or "END FUNCTION" statements. The final program in
such a source code file need not have an "END PROGRAM" or
"END FUNCTION" statement.
7. Subprogram "B" may be nested inside program "A" by including
program B's source code at the end of program A's procedure
division without an intervening "END PROGRAM A." or "END FUNCTION
A." statement. For now, that's all that will be said about
nesting. *Note Independent vs Contained vs Nested Subprograms::,
for more information.
8. Regardless of how many programs comprise a single GNU COBOL source
file, only a single output executable program will be generated
from that source file when the file is compiled.
File: gnucobpg.info, Node: Comments, Next: Literals, Prev: Program Structure, Up: So What is GNU COBOL?
1.3.18. Comments
----------------
The following information describes how comments may be imbedded into
GNU COBOL program source to provide documentation.
Comment Type Source Mode -- Description
-------------------------------------------------------------------
Blank Lines FIXED -- Blank lines may be inserted as desired.
FREE -- Blank lines may be inserted as desired.
Full-line FIXED -- An entire source line will be treated as a
comments comment (and will be ignored by the compiler) by
coding an asterisk ("*") in column seven (7).
FREE -- An entire source line will be treated as a
comment (and will be ignored by the compiler) by
coding the sequence "*>", starting in any column,
as the first non-blank characters on the line.
Full-line FIXED -- An entire source line will be treated as a
comments comment by coding a slash ("/") in column seven
with (7). Many COBOL compilers will also issue a
form-feed form-feed in the program listing so that the "/"
line is at the top of a new page. The GNU COBOL
compiler does not support this form-feed behavior.
The GNU COBOL Interactive Compiler, or GCic, does
support this form-feed behavior when it generates
program source listings! *Note GCic:
(gnucobsp.info)GCic, for the source and
cross-reference listing (produced by GCic) of this
program -- you can see the effect of "/" there.
FREE -- There is no Free Source Mode equivalent to
"/".
Partial-line FIXED -- Any text following the character sequence
comments "*>" on a source line will be treated as a comment.
The "*" must appear in column seven (7) or beyond.
FREE -- Any text following the character sequence
"*>" on a source line will be treated as a comment.
The "*" may appear in any column.
Comments FIXED -- By coding a "D" in column 7 (upper- or
that may be lower-case), an otherwise valid GNU COBOL source
treated as line will be treated as a comment by the compiler.
code,
typically FREE -- By specifying the character sequence ">>D"
for (upper- or lower-case) as the first non-blank
debugging characters on a source line, an otherwise valid GNU
purposes COBOL source line will be treated as a comment by
the compiler.
Debugging statements may be compiled either by
specifying the "-fdebugging-line" switch on the GNU
COBOL compiler or by adding the "WITH DEBUGGING
MODE" clause to the "SOURCE-COMPUTER" paragraph.
File: gnucobpg.info, Node: Literals, Prev: Comments, Up: So What is GNU COBOL?
1.3.19. Literals
----------------
Literals are constant values that will not change during the execution
of a program. There are two fundamental types of literals -- numeric
and alphanumeric.
* Menu:
* 1.3.17.1: Numeric Literals.
* 1.3.17.2: Alphanumeric Literals.
* 1.3.17.3: Figurative Constants.
File: gnucobpg.info, Node: Numeric Literals, Next: Alphanumeric Literals, Up: Literals
1.3.19.1. Numeric Literals
..........................
A numeric literal is a numeric constant which may be used as an array
subscript, as a value in arithmetic expressions, or in 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.317 or -2.95.
* Floating-point values using "Enn" notation such as 9.92E25,
representing 9.92 x 10^25 (10 raised to the 25th power) or
5.7E-14, representing 5.7 x 10^-14 (10 raised to the -14th power).
Both the mantissa (the number before the E) and the exponent (the
number after the E) may be explicitly specified as positive (with
a +), negative (with a -) or unsigned (and therefore implicitly
positive). A floating-point literal's value must be within the
range -1.7 x 10^308 to +1.7 x 10^308 with no more than 15 decimal
digits of precision.
* Hexadecimal numeric literals such as H"1F" (31 decimal), h'22' (34
decimal) or H'DEAD' (57005 decimal). The H character may either
be upper- or lower-case and either single quote (') or
double-quote (") characters may be used in a hexadecimal literal,
provided both aren't used in the same literal. Hexadecimal
numeric literals are limited to a maximum of sixteen hexadecimal
digits (a 64-bit value).
File: gnucobpg.info, Node: Alphanumeric Literals, Next: Figurative Constants, Prev: Numeric Literals, Up: Literals
1.3.19.2. Alphanumeric Literals
...............................
An alphanumeric literal is a character string suitable for display on a
computer screen, printing on a report, transmission through a
communications connection or storage in alphanumeric or alphabetic data
items.
An alphanumeric literal is not valid for use in arithmetic expressions
unless it is first converted to it's numeric computational equivalent;
there are three numeric conversion intrinsic functions built into GNU
COBOL that can perform this conversion -- "NUMVAL" (*note NUMVAL::),
"NUMVAL-C" (*note NUMVAL-C::) and "NUMVAL-F" (*note NUMVAL-F::).
Alphanumeric literals may take any of the following forms:
* A sequence of characters enclosed by a pair of single-quote (') or
double-quote (") characters constitutes a string literal. The
double-quote character (") may be used as a data character within
an apostrophe-delimited string literal, and an apostrophe may be
used as a data character within a double-quote-delimited string
literal. If an apostrophe character must be included as a data
character within an apostrophe-delimited string literal, express
that character as two consecutive apostrophes ("). If a
double-quote character must be included as a data character within
a double-quote-delimited string litaral, express that character as
two consecutive double-quotes ("").
* A literal formed according to the same rules as for a string
literal (above), but prefixed with the letter "Z" (upper- or
lower-case) constitutes a zero-delimited string literal. These
literals differ from ordinary string literals in that they will be
explicitly terminated with a byte of hexadecimal value 00. These
'Zero-Delimited Alphanumeric Literals' are easily passable to C
subprograms, as this is the convention C uses to store character
strings.
* A 'Hexadecimal Alphanumeric Literal' such as X"4A4B4C" (4A4B4C16 =
the ASCII string 'JKL'), x'20' (an ASCII space) or X'30313233'
(3031323316 = the ASCII string '0123'). The "X" character may
either be upper- or lower-case and 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 is represented 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:
1. If you are using Fixed Format Mode, 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 by coding
another quote or apostrophe (whichever was used to begin the
literal originally). The continuation line must also have a
hyphen (-) coded in the indicator area (column 7). Here is an
example (the scale is just for column number reference):
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
01 LONG-LITERAL-VALUE-DEMO PIC X(60) VALUE "This is a long l
- "ong literal that
- " must be continu
- "ed.".
2. Regardless of whether the compiler is operating in Fixed or Free
Format Mode, GNU COBOL allows alphanumeric literals to be broken
up into separate fragments. These fragments have their own
beginning and ending quote/apostrophe characters and are "glued
together" at compilation time using "&" characters. No
continuation indicator is needed. Here's an example:
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
01 LONG-LITERAL-VALUE-DEMO PIC X(60) VALUE "This is a" &
" long literal that must " &
"be continued.".
If your program is using Free Format Mode, 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 and both reserved
and user-defined words can be split across lines too (using the first
technique). The continuation of numeric literals and
user-defined/reserved words is provided merely to provide compatibility
with older COBOL versions and programs, but should not be used with new
programs -- it just makes for ugly-looking programs.
File: gnucobpg.info, Node: Figurative Constants, Prev: Alphanumeric Literals, Up: Literals
1.3.19.3. Figurative Constants
..............................
Figurative constants are reserved words that may be used as literals
anywhere the figurative constant's value could be interpreted as an
arbitrarily long sequence of the characters in question. When a
specific length is required, such as would be the case with an argument
to a subprogram, a figurative constant may not be used. Thus, the
following are valid uses of figurative constants:
05 FILLER PIC 9(10) VALUE ZEROS.
...
MOVE SPACES TO Employee-Name
But this is not:
CALL "SUBPGM" USING SPACES
The following are the GNU COBOL figurative constants and their
respective equivalent values.
"ZERO"
This figurative constant has a value of numeric 0 (zero). "ZEROS"
and "ZEROES" are both synonyms of "ZERO".
"SPACE"
This figurative constant has a value of one or more space
characters. "SPACES" is a synonym of "SPACE".
"QUOTE"
This figurative constant has a value of one or more double-quote
characters ("). "QUOTES" is a synonym of "QUOTE".
"LOW-VALUE"
This figurative constant has a value of one or more of whatever
character occupies the lowest position in the program's collating
sequence as defined in the "OBJECT-COMPUTER" (*note
OBJECT-COMPUTER::) paragraph or -- if no such specification was
made -- in whatever default characterset the program is using
(typically, this is the ASCII characterset). "LOW-VALUES" is a
synonym of "LOW-VALUE".
When the characterset in use is ASCII with no collating sequence
modifications, the "LOW-VALUES" figurative constant value is the
ASCII "NUL" character. Because charactersets can be redefined,
however, you should not rely on this fact -- use the "NULL"
figurative constant instead.
"HIGH-VALUE"
This figurative constant has a value of one or more of whatever
character occupies the highest position in the program's collating
sequence as defined in the "OBJECT-COMPUTER" paragraph or -- if no
such specification was made -- in whatever default characterset
the program is using (typically, this is the ASCII characterset).
"HIGH-VALUES" is a synonym of "HIGH-VALUE".
"NULL"
A character comprised entirely of zero-bits (regardless of the
programs collating sequence).
Programmers may create their own figurative constants via the "SYMBOLIC
CHARACTERS" (*note Symbolic-Characters-Clause::) clause of the
"SPECIAL-NAMES" (*note SPECIAL-NAMES::) paragraph.
File: gnucobpg.info, Node: Punctuation, Next: LENGTH OF, Up: So What is GNU COBOL?
1.3.20. Punctuation
-------------------
A comma (",") or a semicolon (";") may be inserted into a GNU COBOL
program to improve readability at any spot where white space would be
legal, except of course within alphanumeric literals (unless you
actually mean for those characters to be part of the alphanumeric
literal's value). These characters are always optional.
The use of comma characters can cause confusion to a COBOL compiler if
the "DECIMAL POINT IS COMMA" clause is used in the "SPECIAL-NAMES"
(*note SPECIAL-NAMES::) paragraph, as might be the case in Europe. 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" in effect -- actually be
interpreted as a subroutine call with 1 argument (the non-integer
numeric literal whose value is 1 and 2 tenths). For this reason, it is
best to always follow a comma with a space.
The period character (".") is used to terminate statements in the
identification, environment and data divisions and sentences in the
procedure division. Syntax diagrams describing code in the first three
divisions will explicitly show where periods need to occur.
The rules for where and when periods are needed in the procedure
division are somewhat complicated. *Note Use of Periods::, for the
details.
File: gnucobpg.info, Node: LENGTH OF, Next: Interfacing to Other Environments, Prev: Punctuation, Up: So What is GNU COBOL?
1.3.21. LENGTH OF
-----------------
LENGTH OF Syntax
=======================================================================
LENGTH OF numeric-literal-1 | identifier-1
~~~~~~
=======================================================================
Alphanumeric literals and identifiers may optionally be prefixed with
the "LENGTH OF" clause. The compile-time value generated by this
clause will be the number of bytes in the alphanumeric literal or the
defined size (in bytes) of the identifier.
1. The reserved word "OF" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
Here is an example. The following two GNU COBOL statements both
display the same result (27):
01 Demo-Identifier PIC X(27).
...
DISPLAY LENGTH OF "This is a LENGTH OF Example"
DISPLAY LENGTH OF Demo-Identifier
2. The "LENGTH OF" clause on a literal or identifier reference may
generally be used anywhere a numeric literal might be specified,
with the following exceptions:
* As part of the "FROM" clause of a "WRITE" (*note WRITE::) or
"RELEASE" statement (*note RELEASE::).
* As part of the "TIMES" clause of a "PERFORM" statement (*note
PERFORM::).
File: gnucobpg.info, Node: Interfacing to Other Environments, Prev: LENGTH OF, Up: So What is GNU COBOL?
1.3.22. Interfacing to Other Environments
-----------------------------------------
Through the "CALL" statement, COBOL programs may invoke other COBOL
programs serving as subprograms. This is quite similar to
cross-program linkage capabilities provided by other languages. In GNU
COBOL's case, the "CALL" facility is powerful enough to be tailored to
the point where a GNU COBOL program can communicate with operating
system, database management and run-time library APIs, even if they
weren't written in COBOL themselves. *Note GNU COBOL Main Programs
CALLing C Subprograms::, for an example of how a GNU COBOL program
could invoke a C-language subprogram, passing information back and
forth between the two.
The fact that GNU COBOL supports a full-featured two-way interface with
C-language programs means that -- even if you cannot access a library
API directly -- you could always do so via a small C "wrapper" program
that is "CALL"ed by a GNU COBOL program.
File: gnucobpg.info, Node: CDF - Compiler Directing Facility, Next: IDENTIFICATION DIVISION, Prev: Introduction, Up: Top
2. CDF - Compiler Directing Facility
************************************
The Compiler Directing Facility, or CDF, is a means of controlling the
compilation of GNU COBOL programs. CDF provides a mechanism for
dynamically setting or resetting certain compiler switches, introducing
new source code from one or more source code libraries, making dynamic
source code modifications and conditionally processing or ignoring
source statements altogether. This is accomplished via a series of
special CDF statements and directives that will appear in the program
source code.
When the compiler is operating in Fixed Format Mode, all CDF statements
must begin in column eight (8) or beyond.
There are two types of supported CDF statements in GNU COBOL -- Text
Manipulation Statements and Compiler Directives.
The CDF text manipulation statements "COPY" and "REPLACE" are used to
introduce new code into programs either with or without changes, or may
be used to modify existing statements already in the program. Text
manipulation statements are always terminated with a period.
CDF directives, denoted by the presence of a ">>" character sequence as
part of the statement name itself, are used to influence the process of
program compilation.
Compiler directives are never terminated with a period.
* Menu:
* 2.1: COPY.
* 2.2: REPLACE.
* 2.3: >>DEFINE.
* 2.4: >>IF.
* 2.5: >>SET.
* 2.6: >>SOURCE.
* 2.7: >>TURN.
File: gnucobpg.info, Node: COPY, Next: REPLACE, Up: CDF - Compiler Directing Facility
2.1. COPY
=========
CDF COPY Statement Syntax
=======================================================================
COPY copybook-name
~~~~
[ IN|OF library-name ]
~~ ~~
[ SUPPRESS PRINTING ]
~~~~~~~~
[ REPLACING { Phrase-Clause | String-Clause }... ] .
~~~~~~~~~
=======================================================================
CDF COPY Phrase-Clause Syntax
=======================================================================
{ ==pseudo-text-1== } BY { ==pseudo-text-2== }
{ identifier-1 } ~~ { identifier-2 }
{ literal-1 } { literal-2 }
{ word-1 } { word-2 }
=======================================================================
CDF COPY String-Clause Syntax
=======================================================================
[ LEADING|TRAILING ] ==partial-word-1== BY ==partial-word-2==
~~~~~~~ ~~~~~~~~ ~~
=======================================================================
1. "COPY" statements are used to import copybooks (*note Copybooks::)
into a program.
2. "COPY" statements may be used anywhere within a COBOL program
where the code contained within the copybook would be
syntactically valid.
3. The optional "SUPPRESS" clause (with or without the optional
"PRINTING" reserved word) is valid syntactically but is
non-functional. It is supported to facilitate compatibility with
source code written for other versions of COBOL.
4. There is no difference between the use of the word "IN" and the
word "OF" -- use the one you prefer.
5. A period is absolutely mandatory at the end of every "COPY"
statement, even if the statement occurs within the scope of
another one where a period might appear disruptive, such as within
the scope of an "IF" (*note IF::) statement. This mandatory
period at the end of the statement will not, however, affect the
statement scope in which the "COPY" occurs.
6. Both and may be null.
7. All "COPY" statements are located and the contents of the
corresponding copybooks inserted into the program source code
before the actual compilation process begins. If a copybook
contains a "COPY" statement, the copybook insertion process will
be repeated to resolve the imbedded "COPY". This will continue
until no unresolved "COPY" statements remain. At that point,
actual program compilation will begin.
8. *Note Locating Copybooks::, for the specific rules on how
copybooks are located by the compiler.
9. The optional "REPLACING" clause allows for one or more of either
of the following kinds of text replacements to be made:
<>
Replacement of one or more complete reserved words,
user-defined identifiers or literals; the following points
apply to this option:
* This option cannot be used to replace part of a word,
identifier or literal.
* Whatever preceeds the "BY" will be referred to here as
the search string.
* Single-item search strings can be specified by coding
the "", "" or "" being
replaced.
* Multiple-item search strings can be specified using the
"====" option. For example, to replace
all occurrences of "UPON PRINTER", you would specify
"==UPON PRINTER==".
* The replacement string, which follows the "BY", may be
specified using any of the four options.
* If the replacement string is a multiple-item phrase or
is to be deleted altogether, you must use the
"====" option. If "" is
null (in other words, the replacement text is specified
as "===="), all encountered occurrences of the search
string will be deleted.
<>
Using this, you may replace character sequences that occur at
the beginning ("LEADING") or end ("TRAILING") of reserved or
user-defined words. For example, to change all words of the
form "0100-xxxxxx" to "020-xxxxxx", code "LEADING ==0100-==
BY ==020-==". To simply remove all "0100-" prefixes from
words, code "LEADING ==0100-== BY ====".
File: gnucobpg.info, Node: REPLACE, Next: >>DEFINE, Prev: COPY, Up: CDF - Compiler Directing Facility
2.2. REPLACE
============
CDF REPLACE Statement (Format 1) Syntax
=======================================================================
REPLACE [ ALSO ] { Phrase-Clause | String-Clause }... .
~~~~~~~ ~~~~
=======================================================================
CDF REPLACE Statement (Format 2) Syntax
=======================================================================
REPLACE [ LAST ] OFF .
~~~~~~~ ~~~~ ~~~
=======================================================================
CDF REPLACE Phrase-Clause Syntax
=======================================================================
{ ==pseudo-text-1== } BY { ==pseudo-text-2 }
~~
=======================================================================
CDF REPLACE String-Clause Syntax
=======================================================================
[ LEADING|TRAILING ] ==partial-word-1== BY ==partial-word-2==
~~~~~~~ ~~~~~~~~ ~~
=======================================================================
1. The "REPLACE" statement provides a mechanism for changing all or
part of one or more GNU COBOL statements.
2. A period is absolutely mandatory at the end of every "REPLACE"
statement (either format), even if the statement occurs within the
scope of another one where a period might appear disruptive (such
as within the scope of an "IF" (*note IF::) statement; the period
will not, however, affect the statement scope in which the
"REPLACE" occurs.
3. The following points apply to Format 1 of the "REPLACE"
statement:
A. Format 1 of the "REPLACE" statement can be used to make
changes to program source code in much the same way as the
"REPLACING" option of the "COPY" statement can, via these
options:
<>
Replace one or more complete reserved words,
user-defined identifiers or literals; the following
points apply to this option:
* This option cannot be used to replace part of a
word, identifier or literal.
* Whatever preceeds the "BY" will be referred to here
as the search string.
* Search strings on "REPLACE" are always specified
using the "====" option. For
example, to replace all occurrences of "UPON
PRINTER", you would specify "==UPON PRINTER==".
* The replacement string, which follows the "BY", is
specified using the "====" option.
If "" is null (in other words, the
replacement text is specified as "===="), all
encountered occurrences of the search string will
be deleted.
<>
Using this, you may replace character sequences that
occur at the beginning ("LEADING") or end ("TRAILING")
of reserved or user-defined words. For example, to
change all words of the form "0100-xxxxxx" to
"020-xxxxxx", code "LEADING ==0100-== BY ==020-==". To
simply remove all "0100-" prefixes from words, code
"LEADING ==0100-== BY ====".
B. Once a Format 1 "REPLACE" statement is encountered in the
currently-compiling source file, Replace Mode becomes active,
and the change(s) specified by that statement will be
automatically made on all subsequent source statements the
compiler reads from the file.
C. Replace Mode remains in-effect -- continuing to make source
code changes -- until another Format 1 "REPLACE" is
encountered, the end of currently compiling program source
file is reached or a Format 2 "REPLACE" statement is
encountered.
D. When a Format 1 "REPLACE" statement with the "ALSO" keyword
is encountered without Replace Mode being currently active,
the effect will be as if the "ALSO" had not been specified.
If Replace Mode already was in effect, the effect will be to
"push" the current change specification(s) onto the top of a
stack and add the specification(s) of the new statement to
those that were already in effect.
E. When a Format 1 "REPLACE" without the "ALSO" keyword is
encountered, any stacked change specification(s), if any,
will be discarded and the currently in-effect change
specification(s), if any, will be replaced by those of the
new statement.
F. When the end of the currently-compiling source file is
reached, Replace Mode is deactivated and any stacked replace
specifications will be discarded -- compilation of the next
source file (if any) will begin with Replace Mode inactive
and no change specification(s) on the stack.
4. The following points apply to Format 2 of the "REPLACE"
statement:
A. If Replace Mode is currently inactive, the Format 2 REPLACE
statement will be ignored.
B. If Replace Mode is currently active, a "REPLACE OFF." will
deactivate Replace Mode and discard any replace
specification(s) on the stack. The compiler will henceforth
operate as if no "REPLACE" had ever been encountered, until
such time as another Format 1 "REPLACE" is encountered.
C. If Replace Mode is currently active, a "REPLACE LAST OFF."
will replace the current replace specification(s) with those
popped off the top of the stack. If there were no replace
specification(s) on the stack, the effect will be as if a
"REPLACE OFF." had been coded.
File: gnucobpg.info, Node: >>DEFINE, Next: >>IF, Prev: REPLACE, Up: CDF - Compiler Directing Facility
2.3. >>DEFINE
=============
CDF >>DEFINE Directive Syntax
=======================================================================
>>DEFINE [ CONSTANT ] cdf-variable-1 AS { OFF }
~~~~~~~~ ~~~~~~~~ { ~~~ }
{ literal-1 [ OVERRIDE ] }
{ ~~~~~~~~ }
{ PARAMETER [ OVERRIDE ] }
~~~~~~~~~ ~~~~~~~~
=======================================================================
Use the ">>DEFINE" CDF directive to create CDF variables and
(optionally) assign them either literal or environment variable
values.
1. The reserved word "AS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. CDF variables defined in this way become undefined once an "END
PROGRAM" or "END FUNCTION" directive is encountered in the input
source.
3. The ">>DEFINE" CDF directive is one way to create CDF variables
that may be processed by other CDF statements such as ">>IF"
(*note >>IF::). The ">>SET" CDF directive (*note >>SET::)
provides another way to create them.
4. CDF variable names follow the rules for standard GNU COBOL
user-defined names, and may not duplicate any CDF reserved word.
CDF variable names may duplicate COBOL reserved words, provided
the "CONSTANT" option is not specified, but such names are not
recommended.
5. The "CONSTANT" option is valid only in conjunction with
. When "CONSTANT" is specified, the CDF variable that
is created may be used within your regular COBOL code as if it
were a literal value. Without this option, the CDF variable may
only be referenced on other CDF statements. The "OFF" option is
used to create a variable without assigning it any value.
6. The "PARAMETER" option is used to create a variable whose value is
that of the environment variable of the same name. Note that this
value assignment occurs at compilation time, not program execution
time.
7. In the absence of the "OVERRIDE" option, must not
yet have been defined. When the "OVERRIDE" option is specified,
will be created with the specified value, if it
had not yet been defined. If it had already been defined, it will
be redefined with the new value.
File: gnucobpg.info, Node: >>IF, Next: >>SET, Prev: >>DEFINE, Up: CDF - Compiler Directing Facility
2.4. >>IF
=========
CDF >>IF Directive Syntax
=======================================================================
>>IF CDF-Conditional-Expression-1
~~~~ [ Program-Source-Lines-1 ]
[ >>ELIF CDF-Conditional-Expression-2
~~~~~~ [ Program-Source-Lines-2 ] ]...
[ >>ELSE
~~~~~~ [ Program-Source-Lines-3 ] ]
>>END-IF
~~~~~~~~
=======================================================================
CDF-Conditional-Expression Syntax
=======================================================================
{ cdf-variable-1 } IS [ NOT ] { DEFINED }
{ literal-1 } ~~~ { ~~~~~~~ }
{ SET }
{ ~~~ }
{ CDF-RelOp { cdf-variable-2 } }
{ { literal-2 } }
=======================================================================
CDF-RelOp Syntax
=======================================================================
>= or GREATER THAN OR EQUAL TO
~~~~~~~ ~~ ~~~~~
> or GREATER THAN
~~~~~~~
<= or LESS THAN OR EQUAL TO
~~~~ ~~ ~~~~~
< or LESS THAN
~~~~
= or EQUAL TO
~~~~~
<> or EQUAL TO (with "NOT")
~~~~~
=======================================================================
The ">>IF" CDF directive causes the GNU COBOL compiler to process or
ignore COBOL source statements, CDF text-manipulation statements and/or
CDF directives depending upon the value of one or more conditional
expressions based upon CDF variables.
1. The reserved words "IS", "THAN" and "TO" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. Each ">>IF" directive must be terminated by an ">>END-IF" directive.
3. There may be any number of ">>ELIF" clauses following an ">>IF",
including zero.
4. There may no more than one ">>ELSE" clause following an ">>IF".
When ">>ELSE" is used, it must follow the ">>IF" and all ">>ELIF"
clauses.
5. Only one of the <> block of statements
that lie within the scope of the ">>IF"-">>END-IF" may be
processed by the compiler. Which one (if any) that gets processed
will be decided as follows:
A. Each <> will be evaluated, in
turn, in the sequence in which they are coded in the >>IF
statement and any ">>ELIF" clauses that may be present until
one evaluates to TRUE. Once one of them evaluates to TRUE,
the <> block of code that corresponds
to the TRUE <> will be one that
is processed. All others within the ">>IF"-">>END-IF" scope
will be ignored.
B. If no <> evaluates to TRUE, and
there is an ">>ELSE" clause, the <>
block of statements following the ">>ELSE" clause will be
processed by the compiler and all others within the
">>IF"-">>END-IF" scope will be ignored.
C. If no <> evaluates to TRUE and
there is no ">>ELSE" clause, then none of the
<> block of statements within the
">>IF"-">>END-IF" scope will be processed by the compiler.
D. If the > statement block selected for
processing is empty, no error results -- there will just be
no code generated from the ">>IF"-">>END-IF" structure.
6. A <> block may contain any valid COBOL or
CDF code.
7. The following points pertain to any
<>:
A. The "DEFINED" option tests for whether has
been defined, but not yet assigned a value (">>DEFINE ...
OFF"); use the "NOT" option to test for the variable not
being defined.
B. The "SET" option tests for whether has been
given a value, either via a ">>SET" statement or via a
">>DEFINE" without the "OFF" option.
C. Two CDF variables, two literals or a single CDF variable and
a single literal may be compared against each other using a
relational operator. Unlike the standard GNU COBOL "IF"
statement (*note IF::), multiple comparisons cannot be
"AND"ed or "OR"ed together; you may nest a second ">>IF"
inside the first, however, to simulate an "AND" and an "OR"
may be simulated via the ">>ELIF" option.
D. The "<>" symbol stands for "NOT EQUAL TO".
File: gnucobpg.info, Node: >>SET, Next: >>SOURCE, Prev: >>IF, Up: CDF - Compiler Directing Facility
2.5. >>SET
==========
CDF >>SET Directive Syntax
=======================================================================
>>SET { [ CONSTANT ] cdf-variable-1 [ AS literal-1 ] }
~~~~~ { ~~~~~~~~ ~~ }
{ SOURCEFORMAT AS FIXED|FREE }
{ ~~~~~~~~~~~~ ~~~~~ ~~~~ }
{ NOFOLDCOPYNAME }
{ ~~~~~~~~~~~~~~ }
{ FOLDCOPYNAME AS UPPER|LOWER }
~~~~~~~~~~~~ ~~~~~ ~~~~~
=======================================================================
The ">>SET" CDF directive provides an alternate means of performing the
actions of the ">>DEFINE" and ">>SOURCE" directives, as well as a means
of controlling the compiler's "-free" switch, "-fixed" switch and
"-ffold-copy" switch from within program source code.
1. The reserved word "AS" is optional (only on the "SOURCEFORMAT" and
"FOLDCOPYNAME" clauses) and may be included, or not, at the
discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. CDF variables defined in this way become undefined once an "END
PROGRAM" or "END FUNCTION" directive is encountered in the input
source.
3. The "FOLDCOPYNAME" option provides the equivalent of specifying
the compiler "-ffold-copy=xxx" switch, where "xxx" is either
"UPPER" or "LOWER".
4. The "NOFOLDCOPYNAME" option turns off the effect of either the
">>SET FOLDCOPYNAME" statement or the compiler "-ffold-copy=xxx"
switch.
5. If the "CONSTANT" option is used, must also be used.
This option provides another means of defining constants that may
be used anywhere in the program that a literal could be
specified.
6. The remaining options of the ">>SET" CDF directive provide
equivalent functionality to the ">>DEFINE" and ">>SOURCE"
directives, as follows:
A. ">>SET " == ">>DEFINE AS
OFF"
B. ">>SET AS " == ">>DEFINE
AS "
C. ">>SET CONSTANT AS " == ">>DEFINE
CONSTANT AS "
D. ">>SET SOURCEFORMAT AS FIXED" == ">>SOURCE FORMAT IS FIXED"
E. ">>SET SOURCEFORMAT AS FREE" == ">>SOURCE FORMAT IS FREE"
File: gnucobpg.info, Node: >>SOURCE, Next: >>TURN, Prev: >>SET, Up: CDF - Compiler Directing Facility
2.6. >>SOURCE
=============
CDF >>SOURCE Directive Syntax
=======================================================================
>>SOURCE FORMAT IS FIXED|FREE
~~~~~~~~ ~~~~~ ~~~~
=======================================================================
The ">>SOURCE" CDF directive puts the compiler into "FIXED" or "FREE"
source-code format mode. This, in effect, provides yet another
mechanism for controlling the compiler's "-free" switch and "-fixed"
switch.
1. The reserved words "FORMAT" and "IS" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. You may switch between "FIXED" and "FREE" mode as desired.
3. You may also use the ">>SET" CDF directive to perform this
function.
4. If the compiler is already in the specified mode, this statement
will have no effect.
File: gnucobpg.info, Node: >>TURN, Prev: >>SOURCE, Up: CDF - Compiler Directing Facility
2.7. >>TURN
===========
CDF >>TURN Directive Syntax
=======================================================================
>>TURN { exception-name-1 [ file-name-1 ]... }...
~~~~~~
{ OFF }
{ ~~~ }
{ CHECKING ON [ WITH LOCATION ] }
~~~~~~~~ ~~ ~~~~~~~~
The ">>TURN" CDF directive is syntactically recognized but is otherwise
non-functional.
=======================================================================
File: gnucobpg.info, Node: IDENTIFICATION DIVISION, Next: ENVIRONMENT DIVISION, Prev: CDF - Compiler Directing Facility, Up: Top
3. IDENTIFICATION DIVISION
**************************
IDENTIFICATION DIVISION Syntax
=======================================================================
[ IDENTIFICATION DIVISION. ]
~~~~~~~~~~~~~~ ~~~~~~~~
{ PROGRAM-ID. } program-id [ AS literal-1 ] [ Type-Clause ] .
{ ~~~~~~~~~~ }
{ FUNCTION-ID. }
~~~~~~~~~~~
[ AUTHOR. comment-1. ]
~~~~~~
[ DATE-COMPILED. comment-2. ]
~~~~~~~~~~~~~
[ DATE-WRITTEN. comment-3. ]
~~~~~~~~~~~~
[ INSTALLATION. comment-4. ]
~~~~~~~~~~~~
[ REMARKS. comment-5. ]
~~~~~~~
[ SECURITY. comment-6. ]
~~~~~~~~
The "AUTHOR", "DATE-COMPILED", "DATE-WRITTEN", "INSTALLATION", "REMARKS" and
"SECURITY" paragraphs are supported by GNU COBOL only to provide
compatibility with programs written for the ANS1974 (or earlier)
standards. As of the ANS1985 standard, these clauses have become
obsolete and should not be used in new programs.
=======================================================================
PROGRAM-ID Type Clause Syntax
=======================================================================
IS [ COMMON ] [ INITIAL|RECURSIVE PROGRAM ]
~~~~~~ ~~~~~~~ ~~~~~~~~~
=======================================================================
The identification division provides basic identification of the
program by giving it a name and optionally defining some high-level
characteristics via the eight pre-defined paragraphs that may be
specified.
1. The paragraphs shown above may be coded in any sequence.
2. The reserved words "AS", "IS" and "PROGRAM" are optional and may
be included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
3. A Type Clause may be coded only when "PROGRAM-ID" is specified.
If one is coded, either "COMMON", "COMMON INITIAL" or "COMMON
RECURSIVE" must be specified.
4. While the actual "IDENTIFICATION DIVISION" header is optional, the
"PROGRAM-ID" / "FUNCTION-ID" paragraphs are not; only one or the
other, however, may be coded.
5. The compiler's "-Wobsolete" switch will cause the GNU COBOL
compiler to issue warnings messages if these (or any other
obsolete syntax) is used in a program.
6. If specified, must be an actual alphanumeric literal
and may not be a figurative constant.
7. The "PROGRAM-ID" and "FUNCTION-ID" paragraphs serve to identify
the program to the external (i.e. operating system) environment.
If there is no "AS" clause present, the will serve as
that external identification. If there is an "AS" clause
specified, that specified literal will serve as the external
identification. For the remainder of this document, that
"external identification" will be referred to as the primary
entry-point name.
8. The "INITIAL", "COMMON" and "RECURSIVE" words are used only within
subprograms serving as subroutines. Their purposes are as
follows:
A. "COMMON" should be used only within subprograms that are
nested subprograms. A nested subprogram declared as "COMMON"
may be called from any nested program in the source file
being compiled, not just those "above" it in the nesting
structure.
B. The "RECURSIVE" clause, if any, will cause the compiler to
generate different object code for the subprogram that will
enable it to invoke itself and to properly return back to the
program that invoked it.
User-defined functions (i.e. "FUNCTION-ID") are always
recursive.
C. 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.
File: gnucobpg.info, Node: ENVIRONMENT DIVISION, Next: DATA DIVISION, Prev: IDENTIFICATION DIVISION, Up: Top
4. ENVIRONMENT DIVISION
***********************
ENVIRONMENT DIVISION Syntax
=======================================================================
ENVIRONMENT DIVISION.
~~~~~~~~~~~ ~~~~~~~~
[ CONFIGURATION SECTION. ]
~~~~~~~~~~~~~ ~~~~~~~~
[ SOURCE-COMPUTER. Compilation-Computer-Specification . ]
~~~~~~~~~~~~~~~
[ OBJECT-COMPUTER. Execution-Computer-Specification . ]
~~~~~~~~~~~~~~~
[ REPOSITORY. Function-Specification... . ]
~~~~~~~~~~
[ SPECIAL-NAMES. Program-Configuration-Specification . ]
~~~~~~~~~~~~~
[ INPUT-OUTPUT SECTION. ]
~~~~~~~~~~~~ ~~~~~~~
[ FILE-CONTROL. General-File-Description... . ]
~~~~~~~~~~~~
[ I-O-CONTROL. File-Buffering Specification... . ]
~~~~~~~~~~~
=======================================================================
This division defines the external computer environment in which the
program will be operating. This includes defining any files that the
program may be .
* If both optional sections of this division are coded, they must be
coded in the sequence shown.
* The paragraphs within the sections may be coded in any order.
* These sections consist of a series of specific, pre-defined,
paragraphs ("SOURCE-COMPUTER" and "OBJECT-COMPUTER", for example),
each of which serves a specific purpose. If no code is required
for the purpose one of the paragraphs serves, the entire paragraph
may be omitted.
* If any of the paragraphs within one of the sections are coded, the
section header itself must be coded.
* If none of the paragraphs within one of the sections are coded,
the section header itself may be omitted.
* If none of the sections within the environment division are coded,
the "ENVIRONMENT DIVISION." header itself may be omitted.
* Menu:
* 4.1: CONFIGURATION SECTION.
* 4.1.1: SOURCE-COMPUTER.
* 4.1.2: OBJECT-COMPUTER.
* 4.1.3: REPOSITORY.
* 4.1.4: SPECIAL-NAMES.
* 4.1.4.1: Alphabet-Name-Clause.
* 4.1.4.2: Class-Definition-Clause.
* 4.1.4.3: Switch-Definition-Clause.
* 4.1.4.4: Symbolic-Characters-Clause.
* 4.2: INPUT-OUTPUT SECTION.
* 4.2.1: SELECT.
* 4.2.1.1: ORGANIZATION SEQUENTIAL.
* 4.2.1.2: ORGANIZATION LINE SEQUENTIAL.
* 4.2.1.3: ORGANIZATION RELATIVE.
* 4.2.1.4: ORGANIZATION INDEXED.
* 4.2.2: MULTIPLE FILE.
* 4.2.3: SAME RECORD AREA.
File: gnucobpg.info, Node: CONFIGURATION SECTION, Up: ENVIRONMENT DIVISION
4.1. CONFIGURATION SECTION
==========================
CONFIGURATION SECTION Syntax
=======================================================================
CONFIGURATION SECTION.
~~~~~~~~~~~~~ ~~~~~~~
[ SOURCE-COMPUTER. Compilation-Computer-Specification . ]
~~~~~~~~~~~~~~~
[ OBJECT-COMPUTER. Execution-Computer-Specification . ]
~~~~~~~~~~~~~~~
[ REPOSITORY. Function-Specification... . ]
~~~~~~~~~~
[ SPECIAL-NAMES. Program-Configuration-Specification . ]
~~~~~~~~~~~~~
=======================================================================
This section defines the computer system upon which the program is
being compiled and executed and also specifies any special
environmental configuration or compatibility characteristics.
1. The four paragraphs in this section may be specified in any
order.
2. The configuration section is not allowed in a nested subprogram --
nested programs will inherit the configuration section settings of
their parent program.
3. If none of the features provided by the configuration section are
required by a program, the entire "CONFIGURATION SECTION." header
may be omitted from the program.
* Menu:
* 4.1.1: SOURCE-COMPUTER.
* 4.1.2: OBJECT-COMPUTER.
* 4.1.3: REPOSITORY.
* 4.1.4: SPECIAL-NAMES.
* 4.1.4.1: Alphabet-Name-Clause.
* 4.1.4.2: Class-Definition-Clause.
* 4.1.4.3: Switch-Definition-Clause.
* 4.1.4.4: Symbolic-Characters-Clause.
File: gnucobpg.info, Node: SOURCE-COMPUTER, Next: OBJECT-COMPUTER, Up: CONFIGURATION SECTION
4.1.1. SOURCE-COMPUTER
----------------------
SOURCE-COMPUTER Syntax
=======================================================================
SOURCE-COMPUTER. computer-name [ WITH DEBUGGING MODE ] .
~~~~~~~~~~~~~~~ ~~~~~~~~~ ~~~~
=======================================================================
This paragraph defines the computer upon which the program is being
compiled and provides one way in which debugging code imbedded within
the program may be activated.
1. The reserved word "WITH" is optional and may be included, or not,
at the discretion of the programmer. The presence or absence of
this word has no effect upon the program.
2. This paragraph is not allowed in a nested subprogram -- nested
programs will inherit the "SOURCE-COMPUTER" settings of their
parent program.
3. The value specified for is irrelevant, provided it
is a valid COBOL word that does not match any GNU COBOL reserved
word. The value may include spaces. This need
not match the used with the "OBJECT-COMPUTER"
paragraph, if any.
4. The "DEBUGGING MODE" clause, if present, will inform the compiler
that debugging lines (those with a "D" in column 7 if Fixed Source
Mode is in effect, or those prefixed with a ">>D" if Free Source
Mode is in effect) -- normally treated as comments -- are to be
compiled.
5. Even without the "DEBUGGING MODE" clause, it is still possible to
compile debugging lines. Debugging lines may also be compiled by
specifying the "-fdebugging-line" switch to the GNU COBOL
compiler.
File: gnucobpg.info, Node: OBJECT-COMPUTER, Next: REPOSITORY, Prev: SOURCE-COMPUTER, Up: CONFIGURATION SECTION
4.1.2. OBJECT-COMPUTER
----------------------
OBJECT-COMPUTER Syntax
=======================================================================
OBJECT-COMPUTER. [ computer-name ]
~~~~~~~~~~~~~~~
[ MEMORY SIZE IS integer-1 WORDS|CHARACTERS ]
~~~~~~ ~~~~ ~~~~~ ~~~~~~~~~~
[ PROGRAM COLLATING SEQUENCE IS alphabet-name-1 ]
~~~~~~~~~
[ SEGMENT-LIMIT IS integer-2 ]
~~~~~~~~~~~~~
[ CHARACTER CLASSIFICATION IS { locale-name-1 } ]
~~~~~~~~~~~~~~ { LOCALE }
{ ~~~~~~ }
{ USER-DEFAULT }
{ ~~~~~~~~~~~~ }
{ SYSTEM-DEFAULT }
~~~~~~~~~~~~~~
.
The "MEMORY SIZE" and "SEGMENT-LIMIT" clauses are syntactically
recognized but are otherwise non-functional.
=======================================================================
This paragraph describes the computer upon which the program will
execute.
1. The , if specified, must immediately follow the
"OBJECT-COMPUTER" paragraph name. The remaining clauses may be
coded in any sequence.
2. The reserved words "CHARACTER", "IS", "PROGRAM" and "SEQUENCE" are
optional and may be included, or not, at the discretion of the
programmer. The presence or absence of these words has no effect
upon the program.
3. The value specified for , if any, is irrelevant
provided it is a valid COBOL word that does not match any GNU
COBOL reserved word. The may include spaces.
This need not match the used with the
"SOURCE-COMPUTER" paragraph, if any.
4. The "OBJECT-COMPUTER" paragraph is not allowed in a nested
subprogram -- nested programs will inherit the "OBJECT-COMPUTER"
settings of their parent program.
5. The "COLLATING SEQUENCE" clause allows you to specify a customized
character collating sequence to be 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 be
altered from that defined by the computer's native characterset.
The you specify needs to be defined in the
"SPECIAL-NAMES" (*note SPECIAL-NAMES::) paragraph.
6. If no "COLLATING SEQUENCE" clause is specified, the collating
sequence implied by the characterset native to the computer
(usually ASCII) will be used.
7. The optional "CLASSIFICATION" clause may be used to specify a
locale for the environment in which the program will be executing,
for the purpose of influencing the uppercase and lowercase
mappings of characters for the "UPPER-CASE" (*note UPPER-CASE::)
and "LOWER-CASE" (*note LOWER-CASE::) intrinsic functions and the
classification of characters for the "ALPHABETIC",
"ALPHABETIC-LOWER" and "ALPHABETIC-UPPER" class tests. The
definitions of these classes will be taken from the cultural
convention specification ("LC_CTYPE") from the specified locale.
The meanings of the four locale specifications are as follows:
A. references a "LOCALE" (*note SPECIAL-NAMES::)
definition.
B. The keyword "LOCALE" refers to the current locale (in effect
at the time the program is executed)
C. The keyword "USER-DEFAULT" references the default locale
specified for the user currently executing this program.
D. The keyword "SYSTEM-DEFAULT" denotes the default locale
specified for the computer upon which the program is
executing.
8. Absence of a "CLASSIFICATION" clause will cause character
classification to occur according to the rules for the computer's
native characterset (ASCII, EBCDIC, ...).
File: gnucobpg.info, Node: REPOSITORY, Next: SPECIAL-NAMES, Prev: OBJECT-COMPUTER, Up: CONFIGURATION SECTION
4.1.3. REPOSITORY
-----------------
REPOSITORY Syntax
=======================================================================
REPOSITORY.
~~~~~~~~~~
FUNCTION { function-prototype-name-1 [ AS literal-1 ] }...
~~~~~~~~ { ~~ }
{ intrinsic-function-name-1 [ AS literal-2 ] }
{ ~~ }
{ intrinsic-function-name-2 INTRINSIC }
{ ALL INTRINSIC ~~~~~~~~~ }
~~~ ~~~~~~~~~
=======================================================================
The REPOSITORY paragraph provides a way to control access to the
various built-in intrinsic functions and any user defined functions
that your program will be using.
1. The "REPOSITORY" paragraph is not allowed in a nested subprogram
-- nested programs will inherit the "REPOSITORY" settings of their
parent program.
2. The "INTRINSIC" clause allows you to flag one or more (or "ALL")
built-in intrinsic functions as being usable without the need to
code the keyword "FUNCTION" in front of the function names.
3. As an alternative to using the "ALL INTRINSIC" clause, you may
instead compile your GNU COBOL programs using the
"-fintrinsics=ALL" switch.
4. The option is required to specify the
name of a user-defined function your program will be using.
Optionally, should you desire, you may specify an alias name by
which you will reference that user-defined function. Should you
wish, you may also use the "AS" clause to provide an alias name
for a built-in intrinsic function.
5. The following example enables all intrinsic functions to be
specified without the use of the "FUNCTION" keyword, (2) names two
user-defined functions named "MY-FUNCTION-1" and "MY-FUNCTION-2"
that will be used by the program and (3) specifies the alias names
"SIGMA" for the intrinsic function "STANDARD-DEVIATION" and "MF2"
for "MY-FUNCTION-2".
REPOSITORY.
FUNCTION ALL INTRINSIC.
FUNCTION MY-FUNCTION-1.
FUNCTION MY-FUNCTION-2 AS "MF2".
FUNCTION STANDARD-DEVIATION AS "SIGMA".
*A special note about user-defined functions* -- because you must name
a user-defined function that your program will be using in the
"REPOSITORY" paragraph, you may always reference that function from
your program's procedure division without needing to use the "FUNCTION"
keyword.
File: gnucobpg.info, Node: SPECIAL-NAMES, Prev: REPOSITORY, Up: CONFIGURATION SECTION
4.1.4. SPECIAL-NAMES
--------------------
SPECIAL-NAMES Syntax
=======================================================================
SPECIAL-NAMES.
~~~~~~~~~~~~~
[ CALL-CONVENTION integer-1 IS mnemonic-name-1 ]
~~~~~~~~~~~~~~~
[ CONSOLE IS CRT ]
~~~~~~~ ~~~
[ CRT STATUS IS identifier-1 ]
~~~ ~~~~~~
[ CURRENCY SIGN IS literal-1 ]
~~~~~~~~ ~~~~
[ CURSOR IS identifier-2 ]
~~~~~~
[ DECIMAL-POINT IS COMMA ]
~~~~~~~~~~~~~ ~~~~~
[ EVENT STATUS IS identifier-3 ]
~~~~~ ~~~~~~
[ LOCALE locale-name-1 IS literal-2 ]...
~~~~~~
[ NUMERIC SIGN IS TRAILING SEPARATE ]
~~~~~~~ ~~~~ ~~~~~~~~ ~~~~~~~~
[ SCREEN CONTROL IS identifier-4 ]
~~~~~~ ~~~~~~~
[ device-name-1 IS mnemonic-name-2 ]...
[ feature-name-1 IS mnemonic-name-3 ]...
[ Alphabet-Clause ]...
[ Class-Definition-Clause ]...
[ Switch-Definition-Clause ]...
[ Symbolic-Characters-Clause ]...
.
The "EVENT STATUS" and "SCREEN CONTROL" clauses are syntactically
recognized but are otherwise non-functional.
=======================================================================
<>, <>,
<> and <>
are discussed in detail in the next four sections.
The "SPECIAL-NAMES" paragraph provides a means for specifying various
program and operating environment configuration options.
1. The various clauses that may be specified within the
"SPECIAL-NAMES" paragraph may be coded in any order.
2. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
3. The "SPECIAL-NAMES" paragraph is not allowed in a nested
subprogram -- nested programs will inherit the "SPECIAL-NAMES"
settings of their parent program.
4. Only the final clause specified within this paragraph should be
terminated with a period.
5. The "CALL-CONVENTION" clause allows a decimal integer,
representing a series of ON/OFF switch settings, to be associated
with a mnemonic name which may then be coded on a "CALL" statement
(*note CALL::). The switch settings defined by this mnemonic will
then control how the linkage to a subroutine invoked by the "CALL"
statement that references will be handled.
6. The "CONSOLE IS CRT" clause, if specified, will cause a "DISPLAY"
statement lacking an explict "UPON" clause to be treated as a
"DISPLAY screen-data-item" statement (*note DISPLAY
screen-data-item::), and any "ACCEPT" statement lacking a "FROM"
clause to be treated as a "ACCEPT screen-data-item" statement
(*note ACCEPT screen-data-item::).
7. If the "CRT STATUS" clause is not specified, an implicit
"COB-CRT-STATUS" identifier (with a "PICTURE 9(4)") will be
allocated for the purpose of receiving screen "ACCEPT" statuses.
If "CRT STATUS" is specified, then must be defined
in the program as a "PICTURE 9(4)" field.
8. The "CURRENCY SIGN" clause may be used to redefine the character
to be used as a currency sign in a "PICTURE" (*note PICTURE::)
clause. The default currency sign is a dollar-sign ($). You may
specify any character except "0"-"9", "A"-"Z", "a"-"z", "+", "-",
",", ".", "*", "/", ";", "(", ")", "=", "\", quote (") or space.
9. The "CURSOR IS" clause allows you to specify a 4- or 6-character
data item into which the cursor screen location at the time a
screen "ACCEPT" is satisfied. The value will be returned as rrcc
or rrrccc, depending upon the length of the specified
, where rr and rrr represent the row number
(starting at zero) and cc and ccc represent the column number
(also starting at zero). There is no default data item allocated
for this data if the "CURSOR IS" clause is not specified, and it
is the programmer's responsibility to define if the
clause is specified.
10. The "DECIMAL POINT IS COMMA" clause reverses the definition of the
"," and "." characters when they are used as "PICTURE" editing
symbols and within numeric literals. This can have unwanted
side-effects - see *Note Punctuation::.
11. The "LOCALE" clause may be used to associate external OS-defined
locale names () with an internal name ()
that may then be referenced within the program. Locale names are
defined by the Operating System and/or C compiler GNU COBOL will
be utilizing on your computer.
12. The following is the list of possible locale codes, for example,
that would be available on a Windows computer running a GNU COBOL
version that was built utilizing the MinGW Unix-emulator and the
GNU C compiler (gcc):
*A*
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
*B*
ba_R, be_BY, bg_BG, bn_IN bo_BT, bo_CN, br_FR, bs_Cyrl_BA,
bs_Latn_BA
*C*
ca_ES, cs_CZ, cy_GB
*D*
da_DK, de_AT, de_CH, de_DE, de_LI, de_LU, dsb_DE, dv_MV
*E*
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
*F*
fa_IR, fi_FI, fil_PH, fo_FO, fr_BE, fr_CA, fr_CH, fr_FR,
fr_LU, fr_MC, fy_NL
*G*
ga_IE, gbz_AF, gl_ES, gsw_FR, gu_IN
*H*
ha_Latn_NG, he_IL, hi_IN, hr_BA, hr_HR, hu_HU, hy_AM
*I*
id_ID, ig_NG, ii_CN, is_IS, it_CH, it_IT, iu_Cans_CA,
iu_Latn_CA
*J*
ja_JP
*K*
ka_GE, kh_KH, kk_KZ, kl_GL, kn_IN, ko_KR, kok_IN, ky_KG
*L*
lb_LU, lo_LA, lt_LT, lv_LV
*M*
mi_NZ, mk_MK, ml_IN, mn_Cyrl_MN, mn_Mong_CN moh_CA, mr_IN,
ms_BN, ms_MY, mt_MT
*N*
nb_NO, ne_NP, nl_BE, nl_NL, nn_NO, ns_ZA
*O*
oc_FR, or_IN
*P*
pa_IN, pl_PL, ps_AF, pt_BR, pt_PT
*Q*
qut_GT, quz_BO, quz_EC, quz_PE
*R*
rm_CH, ro_RO, ru_RU, rw_RW
*S*
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_FI, sms_FI, sq_AL,
sr_Cyrl_BA, sr_Cyrl_CS, sr_Latn_BA, sr_Latn_CS, sv_FI, sv_SE,
sw_KE syr_SY
*T*
ta_IN, te_IN, tg_Cyrl_TJ, th_TH tk_TM, tmz_Latn_DZ, tn_ZA,
tr_IN, tr_TR, tt_RU
*U*
ug_CN, uk_UA, ur_PK, uz_Cyrl_UZ, uz_Latn_UZ
*V*
vi_VN
*W*
wen_DE, wo_SN
*X*
xh_ZA
*Y*
yo_NG
*Z*
zh_CN, zh_HK, zh_MO, zh_SG, zh_TW, zu_ZA
13. The "NUMERIC SIGN TRAILING SEPARATE" specification causes all
signed numeric "USAGE DISPLAY" data items to be created as if the
"SIGN IS TRAILING SEPARATE CHARACTER" clause was included in their
definitions.
14. The " IS " clause allows you to
specify an alternate name () for one of the
built-in GNU COBOL device name . The list of
device names built-into GNU COBOL, and the physical device
associated with that name, are as follows:
"CONSOLE"
This is the (screen-mode) display of the PC or Unix system.
"STDIN"
"SYSIN"
"SYSIPT"
These devices (they are all synonymous) represent standard
system input (pipe 0). On a PC or UNIX system, this is
typically the keyboard. The contents of a file may be
delivered to a GNU COBOL program for access via one of these
device names by adding the sequence "0< filename" to the end
of the programs execution command.
"PRINTER"
"STDOUT"
"SYSLIST"
"SYSLST"
"SYSOUT"
These devices (they are all synonymous) represent standard
system output (pipe 1). On a PC or UNIX system, this is
typically the display. Output sent to one of these devices
by a GNU COBOL program can be sent to a file by adding the
sequence "1> filename" to the end of the programs execution
command.
"STDERR"
"SYSERR"
These devices (they are synonymous) represent standard system
error output (pipe 2). On a PC or UNIX system, this is
typically the display. Output sent to one of these devices
by a GNU COBOL program can be sent to a file by adding the
sequence "2> filename" to the end of the programs execution
command.
15. The " IS " clause allow for
mnemonic names to be assigned to up to the 13 printer channel
(i.e. vertical page positioning) position feature names "Cnn"
(nn=01-12) and "CSP". Once a channel position has been assigned a
mnemonic name, statements of the form "WRITE AFTER
ADVANCING " may be coded to write the specified
print record at the channel position assigned to
.
Printers supporting channel positioning are generally
mainframe-type line printers. When writing to printers that do
not support channel positioning, a formfeed will be issued to the
printer.
The "CSP" positioning option stands for "No Spacing". Testing on
a MinGW build of GNU COBOL shows that this too results in a
formfeed being issued.
* Menu:
* 4.1.4.1: Alphabet-Name-Clause.
* 4.1.4.2: Class-Definition-Clause.
* 4.1.4.3: Switch-Definition-Clause.
* 4.1.4.4: Symbolic-Characters-Clause.
File: gnucobpg.info, Node: Alphabet-Name-Clause, Next: Class-Definition-Clause, Up: SPECIAL-NAMES
4.1.4.1. Alphabet-Name-Clause
.............................
SPECIAL-NAMES Alphabet-Clause Syntax
=======================================================================
ALPHABET alphabet-name-1 IS { ASCII }
~~~~~~~~ { ~~~~~ }
{ EBCDIC }
{ ~~~~~~ }
{ NATIVE }
{ ~~~~~~ }
{ STANDARD-1 }
{ ~~~~~~~~~~ }
{ STANDARD-2 }
{ ~~~~~~~~~~ }
{ Literal-Clause... }
=======================================================================
SPECIAL-NAMES ALPHABET Literal-Clause Syntax
=======================================================================
literal-1 [ { THRU|THROUGH literal-2 } ]
{ ~~~~ ~~~~~~~ }
{ {ALSO literal-3}... }
~~~~
=======================================================================
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 option.
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. The reserved words "THRU" and "THROUGH" are interchangeable.
3. GNU COBOL considers "ASCII", "STANDARD-1" and "STANDARD-2" to be
interchangeable.
4. "NATIVE" specifies the system default characterset.
5. The following points apply to using the specifications
to compose a custom characterset:
A. The values are either integers or alphanumeric
quoted characters. These represent a single character in the
"NATIVE" characterset, either by it's actual text value
(alphanumeric quoted character) or by ordinal position in the
"NATIVE" characterset (integer),
B. The sequence in which characters are defined in this clause
specifies the relative order those characters should have
when comparisons are made using this alphabet.
C. Character positions in this list do not affect the actual
binary storage values used for the characters -- binary
values will still be those of the "NATIVE" characterset.
D. You may specify any of the figurative constants "SPACE",
"SPACES", "ZERO", "ZEROS", "ZEROES", "QUOTE", "QUOTES",
"HIGH-VALUE", "HIGH-VALUES", "LOW-VALUE" or "LOW-VALUES" for
any of the , or
specifications.
6. Once you have defined an alphabet name, that alphabet name may be
used on specifications in "CODE-SET", "COLLATING SEQUENCE", or
"SYMBOLIC CHARACTERS" clauses elsewhere in the program.
File: gnucobpg.info, Node: Class-Definition-Clause, Next: Switch-Definition-Clause, Prev: Alphabet-Name-Clause, Up: SPECIAL-NAMES
4.1.4.2. Class-Definition-Clause
................................
SPECIAL-NAMES Class-Definition-Clause Syntax
=======================================================================
CLASS class-name-1 IS { literal-1 [ THRU|THROUGH literal-2 ] }...
~~~~~ ~~~~ ~~~~~~~
=======================================================================
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. The reserved words "THRU" and "THROUGH" are interchangeable.
3. Both and must be alphanumeric literals of
length 1.
4. The literal(s) specified on this clause define the possible
characters that may be found in a data item's value in order to be
considered part of the class.
5. For example, the following defines a class called "Hexadecimal",
the definition of which specifies the only characters that may be
present in an alphanumeric 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'
6. Once class "Hexadecimal" has been defined, program code could then
use a statement such as "IF input-item IS Hexadecimal" to
determine if the value of characters in a data item are valid
according to that class.
File: gnucobpg.info, Node: Switch-Definition-Clause, Next: Symbolic-Characters-Clause, Prev: Class-Definition-Clause, Up: SPECIAL-NAMES
4.1.4.3. Switch-Definition-Clause
.................................
SPECIAL-NAMES Switch-Definition-Clause Syntax
=======================================================================
switch-name-1 [ IS mnemonic-name-1 ]
[ ON STATUS IS condition-name-1 ]
~~
[ OFF STATUS IS condition-name-2 ]
~~~
=======================================================================
The switch-definition clause associates a condition-name with a
run-time execution switch so that the status of that switch may be
tested from within a program.
1. The reserved words "IS" and "STATUS" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. The valid names are "SWITCH-n" (n=0-15).
3. If the program is compiled with the "-fsyntax-extension" switch,
the switch names "SWn" (n=0-15) are also valid; they correspond to
"SWITCH-0" through "SWITCH-15", respectively.
4. At execution time, each switch will be associated with a "COB_SWITCH_n"
run-time environment variable (*note Run Time Environment
Variables::), where "n" will have the value "0" through "15". Any
of these sixteen environment variables that have the value "ON"
(regardless of upper- or lower-case value) will be considered to
be set "on". Any of these sixteen environment variables having no
value at all or a value other than "ON" will be considered "OFF".
5. Each specified switch must have at least one of a "IS
", "ON STATUS" or an "OFF STATUS" option defined
for it, otherwise there will be no way to reference the switch
from within a GNU COBOL program.
6. The "IS " syntax provides a means for setting the
switch to either an ON or OFF value via the "SET" statement (*note
SET::).
7. The "ON STATUS" and "OFF STATUS" syntax provides a way of
associating a condition-name with either the on or off status of
the switch, so that status may be tested at execution time via the
"IF" statement (*note IF::).
File: gnucobpg.info, Node: Symbolic-Characters-Clause, Prev: Switch-Definition-Clause, Up: SPECIAL-NAMES
4.1.4.4. Symbolic-Characters-Clause
...................................
SPECIAL-NAMES-Symbolic-Characters-Clause Syntax
=======================================================================
SYMBOLIC CHARACTERS
~~~~~~~~
{ symbolic-character-1... IS|ARE integer-1... }...
[ IN alphabet-name-1 ]
~~
=======================================================================
This clause may be used to define your own figurative constants.
1. The reserved words "ARE", "CHARACTERS" and "IS" are optional and
may be included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. There must be exactly as many values specified as
there are names.
3. Each symbolic character name will be associated with the
corresponding th character in the alphabet named in the
"IN" clause. The integer values are selecting characters from the
alphabet by their ordinal position and not by their numeric value;
thus, an integer of 15 will select the 15th character in the
specified alphabet, regardless of the actual numeric value of the
bit pattern that constitutes that character.
4. If no is specified, the systems native
characterset will be assumed.
5. The following two code examples define the same set of figurative
constant names for five ASCII control characters (assuming that
ASCII is the system's native characterset). The two examples are
identical in their effects, even though the manner in which the
figurative constants are defined is different.
SYMBOLIC CHARACTERS NUL IS 1 SYMBOLIC CHARACTERS NUL SOH BEL DC1 DC2
SOH IS 2 ARE 1 2 8 18 19
BEL IS 8
DC1 IS 18
DC2 IS 19
File: gnucobpg.info, Node: INPUT-OUTPUT SECTION, Up: ENVIRONMENT DIVISION
4.2. INPUT-OUTPUT SECTION
=========================
INPUT-OUTPUT SECTION Syntax
=======================================================================
[ INPUT-OUTPUT SECTION. ]
~~~~~~~~~~~~ ~~~~~~~
[ FILE-CONTROL. ]
~~~~~~~~~~~~
[ SELECT-Statement... ]
[ I-O-CONTROL. ]
~~~~~~~~~~~
[ MULTIPLE-FILE-Statement ]
[ SAME-RECORD-Statement ]
=======================================================================
The "INPUT-OUTPUT" section provides for the definition of any files the
program will be accessing as well as control of the I/O buffering
process against those files through the "FILE-CONTROL" and
"I-O-CONTROL" paragraphs, respectively.
1. As the diagram shows, there are three types of statements that may
occur in the two paragraphs of this section. If none of the
statements are coded in a particular paragraph, the paragraph
itself may be omitted, otherwise it is required.
2. If neither paragraph is coded, the "INPUT-OUTPUT SECTION." header
itself may be omitted, otherwise it is normally required.
3. If the compiler "config" file you are using has
"relaxed-syntax-check" set to "yes", the "FILE-CONTROL" and
"I-O-CONTROL" paragraphs may be specified without the
"INPUT-OUTPUT SECTION." header having been coded.
4. If both statement types are coded in the "I-O-CONTROL" paragraph,
the order in which those statements are coded is irrelevant.
* Menu:
* 4.2.1: SELECT.
* 4.2.1.1: ORGANIZATION SEQUENTIAL.
* 4.2.1.2: ORGANIZATION LINE SEQUENTIAL.
* 4.2.1.3: ORGANIZATION RELATIVE.
* 4.2.1.4: ORGANIZATION INDEXED.
* 4.2.2: SAME RECORD AREA.
* 4.2.3: MULTIPLE FILE.
File: gnucobpg.info, Node: SELECT, Up: INPUT-OUTPUT SECTION
4.2.1. SELECT
-------------
SELECT Statement Syntax
=======================================================================
SELECT [ [ NOT ] OPTIONAL ] file-name-1
~~~~~~ ~~~ ~~~~~~~~
[ ASSIGN { TO } [{ EXTERNAL }] [{ DISC|DISK }] [{ identifier-1 }] ]
~~~~~~ { USING } { ~~~~~~~~ } { ~~~~ ~~~~ } { word-1 }
{ DYNAMIC } { DISPLAY } { literal-1 }
~~~~~~~ { ~~~~~~~ }
{ KEYBOARD }
{ ~~~~~~~~ }
{ LINE ADVANCING }
{ ~~~~ ~~~~~~~~~ }
{ PRINTER }
{ ~~~~~~~ }
{ RANDOM }
{ ~~~~~~ }
{ TAPE }
~~~~
[ COLLATING SEQUENCE IS alphabet-name-1 ]
~~~~~~~~~
[ FILE|SORT ] STATUS IS identifier-2 [ identifier-3 ] ]
~~~~ ~~~~ ~~~~~~
[ LOCK MODE IS { MANUAL|AUTOMATIC } ]
~~~~ { ~~~~~~ ~~~~~~~~~ }
{ EXCLUSIVE [ WITH { LOCK ON MULTIPLE RECORDS } ] }
~~~~~~~~~ { ~~~~ ~~ ~~~~~~~~ ~~~~~~~ }
{ LOCK ON RECORD }
[ ORGANIZATION-Clause ] { ~~~~ ~~ ~~~~~~ }
{ ROLLBACK }
[ RECORD DELIMITER IS STANDARD-1 ] ~~~~~~~~
~~~~~~ ~~~~~~~~~ ~~~~~~~~~~
[ RESERVE integer-1 AREAS ]
~~~~~~~
[ SHARING WITH { ALL OTHER } ]
~~~~~~~ { ~~~ }
{ NO OTHER }
{ ~~ }
{ READ ONLY }
. ~~~~ ~~~~
The "COLLATING SEQUENCE", "RECORD DELIMITER", "RESERVE" and "ALL OTHER" clauses
are syntactically recognized but are otherwise non-functional.
=======================================================================
The "SELECT" statement creates a definition of a file and links that
COBOL definition to the external operating system environment.
1. The reserved words "AREAS", "IS", "MODE", "OTHER", "SEQUENCE",
"TO", "USING" and "WITH" are optional and may be included, or not,
at the discretion of the programmer. The presence or absence of
these words has no effect upon the program.
2. After , the various clauses may be coded in any
sequence.
3. A period must follow the last coded clause.
4. The "OPTIONAL" clause, to be used only for files that will be used
to provide input data to the program, indicates the file may or
may not actually be available at run-time. Attempts to "OPEN" an
"OPTIONAL" file when the file does not exist will receive a
special non-fatal file status value (see status 05 in the list of
file status values below) indicating the file is not available; a
subsequent attempt to "READ" that file will return an "AT END"
(end-of-file) condition. Optionally, files may be designated as
"NOT OPTIONAL", if desired. This is useful when specifying the
compiler's "-foptional-file" switch, which automatically makes all
files "OPTIONAL" except for those explicitly declared as "NOT
OPTIONAL".
5. The value that you specify will be the name by which
you will reference the file within your program. This name should
be formed according to the rules for user-defined names (*note
User-Defined Words::).
6. The optional "ASSIGN" clause specifies how -- at runtime, when
is opened -- either a logical device (STDIN, STDOUT)
or a file anywhere in one of the currently-mounted filesystems
will be associated with , as follows:
A. There are three components to the "ASSIGN" clause -- a
<> specification ("EXTERNAL", "DYNAMIC" or neither), a
<> (the list of device choices) and a <>
(shown as a choice between , and
).
B. "ASSIGN TO DISC ''" will be assumed if there is
no "ASSIGN" clause on a "SELECT".
C. If an "ASSIGN" clause is coded without a <>, the
device "DISC" will be assumed.
D. If a <> clause is coded, the COBOL file
will be attached to a data file within any
filesystem that is mounted and available to the executing
program at the time is opened. How that file
is identified varies, depending upon the specified
<>, as follows:
a. If is coded, the value of the literal will
serve as the File Location String that will identify the
data file.
b. If is coded, the value of the identifier
will serve as the File Location String that will
identify the data file.
c. If (a syntactically valid word not duplicating
that of a reserved or user-defined word) is coded, and a
<> of "EXTERNAL" is specified, itself
will serve as the File Location String that will
identify the data file. If, however, a <> of
"EXTERNAL" was not specified, the compiler will create a
"PIC X(1024)" data item named within the
program; the contents of that data item at the time the
progrem opens will then serve as the File
Location String that will identify the data file.
d. File Location Strings will be discussed shortly.
E. If no <> is coded, will be attached to
a logical device or a file based upon the specified (or
implied) <>, as follows:
a. "DISC" or "DISK" will assume an attachment to a file
named in whatever directory is current at
the time the file is opened.
b. "DISPLAY" will assume an attachment to the "STDOUT"
logical device; these files should only be used for
output.
c. "KEYBOARD" will assume an attachment to the "STDIN"
logical device; these files should only be used for
input.
d. "PRINTER" will assume an attachment to the "LPT1"
logical device/port; these files should only be used for
output.
e. "RANDOM" or "TAPE" will behave exactly as "DISC" does.
These two additional <>s are provided to
facilitate the compilation of COBOL source from other
COBOL implementations.
F. The "LINE ADVANCING" device requires that a <> be
specified; these files should only be used for output. A
COBOL Line Advancing file will allow carriage-control
characters such as line-feeds and form-feeds to be written to
the attached operating system file, via the "ADVANCING"
clause of the "WRITE" statement (*note WRITE::).
G. File Location Strings are used (at runtime) to identify the
path and filename to the data file that must be attached to
when that file is opened.
H. If the compiler "config" file you used to compile the program
with had a "filename-mapping" value of "yes", the GNU COBOL
runtime system will first attempt to identify a
currently-defined environment variable whose value will serve
as the data file's path and filename, as follows:
a. If the compiler "config" file (*note Compiler
Configuration Files::) you used to compile the program
specified "mf" as the "assign-clause" value, then the
File Locator String will be interpreted according to
Microfocus COBOL rules -- namely, everything before the
last "-" in the File Locator String will be ignored; the
characters after the last "-" will be treated as the
base of an environment variable name. If there is no
"-" character in the File Locator String then the entire
File Locator String will serve as the base of an
environment variable name. This is the default behavior
for every config file except "ibm".
b. If, on the other hand, the compiler "config" file you
used to compile the program specified "mf" as the
"assign-clause" value, then the File Locator String will
be interpreted according to according to IBM COBOL rules
-- namely, the File Locator String is expected to be of
theform "S-xxx" or "AS-xxx", in which case the "xxx"
will be treated as the base of an environment variable
name. If there is no "-" character in the File Locator
String then the entire File Locator String will serve as
the base of an environment variable name.
c. Once an environment variable name base (let's refer to
it as "bbbb") has been determined, the runtime system
will look for the first one of the following environment
variables that exists, in this sequence:
DD_bbbb
dd_bbbb
bbbb
Windows systems are case-insensitive with regard to
environment variables, so there is no difference between
the first two when using a GNU COBOL implementation
built for either Windows/MinGW or native Windows.
If an environment variable was found, it's value will
serve as the path and filename to the data file.
I. If no environment variable was found, or the "config" file
used to compile the program had a "filename-mapping" value of
"no", then the File Locator String value will serve as the
path and filename to the data file.
J. Paths and filenames may be specified on an absolute
("C:\Data\datafile.dat", "/Data/datafile.dat", ...) or
relative-to-the-current-directory ("Data\datafile.dat",
"Data/datafile.dat", ...) basis.
There may not even be a path ("datafile.dat"), in which case
the file must be in the current directory.
7. The "FILE STATUS" or "SORT STATUS" clause (they are both
equivalent and only one or the other, if any, should be specified)
is used to specify the name of a two-digit numeric data item into
which an I/O status code will be saved after every I/O verb that
is executed against the file. This does not actually allocate the
data item -- you must define the item yourself somewhere in the
data division.
Possible status codes that can be returned to a "FILE STATUS" data
item are as follows:
Code Explanation
---------------------------------------------------------------------
00 Success
02 Success (Duplicate Record Key Written)
05 Success (Optional File Not Found)
07 Success (No Unit)
10 End of file reached if reading forward or beginning-of-file
reached if reading backward
14 Out of key range
21 Key invalid
22 Attempt to duplicate key value
23 Key not found
30 Permanent I/O error
31 Inconsistent filename
34 Boundary violation
35 File not found
37 Permission denied
38 Closed with lock
39 Conflicting attribute
41 File already open
42 File not open
43 Read not done
44 Record overflow
46 Read error
47 "OPEN INPUT" denied (insufficient permissions to read file)
48 "OPEN OUTPUT" denied (insufficient permissions to write to
file)
49 "OPEN I-O" denied (insufficient permissions to read and/or
write file)
51 Record locked
52 End of page
57 "LINAGE" specifications invalid
61 File sharing failure
91 File not available
8. The "SHARING" clause defines the conditions under which the
program will be willing (or not) to allow other programs executing
at the same time to access the file. *Note File Sharing::, for
the details.
9. The "LOCK" clause defines how concurrent access to the file will
be managed on a record-by-record basis. *Note Record Locking::,
for the details.
10. A "SELECT" statement without an "ORGANIZATION" explicitly coded
will be handled as if the following ORGANIZATION clause had been
specified:
ORGANIZATION IS SEQUENTIAL
ACCESS MODE IS SEQUENTIAL
* Menu:
* 4.2.1.1: ORGANIZATION SEQUENTIAL.
* 4.2.1.2: ORGANIZATION LINE SEQUENTIAL.
* 4.2.1.3: ORGANIZATION RELATIVE.
* 4.2.1.4: ORGANIZATION INDEXED.
File: gnucobpg.info, Node: ORGANIZATION SEQUENTIAL, Next: ORGANIZATION LINE SEQUENTIAL, Up: SELECT
4.2.1.1. ORGANIZATION SEQUENTIAL
................................
ORGANIZATION SEQUENTIAL Clause Syntax
=======================================================================
[ ORGANIZATION|ORGANISATION IS ] RECORD BINARY SEQUENTIAL
~~~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~~~~~
[ ACCESS MODE IS SEQUENTIAL ]
~~~~~~ ~~~~~~~~~~
=======================================================================
Files declared as "ORGANIZATION SEQUENTIAL" will consist of records
with no explicit end-of-record delimiter character sequences; records
in such files are "delineated" by a calculated byte-offset (based on
the maximum record length) into the file.
1. The reserved words "BINARY", "IS", "MODE" and "RECORD" are
optional and may be included, or not, at the discretion of the
programmer. The presence or absence of these words has no effect
upon the program.
2. The reserved words "ORGANIZATION" and "ORGANISATION" are
interchangeable.
3. The phrase "ORGANIZATION IS" (and it's internationalized
alternative, "ORGANISATION IS") is optional to provide
compatibility with those (few) COBOL implementations that consider
"ORGANIZATION" to be optional. Most COBOL implementations do
require the word "ORGANIZATION", so it should be used in new
programs.
4. These files cannot be prepared with any standard text-editing or
word processing software as all such programs will imbed delimiter
characters at the end of records (use "ORGANIZATION IS LINE
SEQUENTIAL" instead).
5. These files may contain either "USAGE DISPLAY" or "USAGE
COMPUTATIONAL" (of any variety) data since no binary data sequence
can be accidentally interpreted as an end-of-record delimiter.
6. While records in a "ORGANIZATION SEQUENTIAL" file may be defined
as having variable-length records, the file will be structured in
such a manner as to reserve space for each record equal to the
size of the largest possible record, based on the file's
description in the "FILE SECTION".
7. The "ACCESS MODE SEQUENTIAL" clause is optional because, if
absent, it will be assumed anyway for this type of file. The
internal structure of these files is such that they can only be
processed in a sequential manner; in order to read the 100th
record in such a file, for example, you first must read records 1
through 99.
8. Sequential files are processed using the following statements:
* "CLOSE" (*note CLOSE::)
* "COMMIT" (*note COMMIT::)
* "DELETE" (*note DELETE::)
* "MERGE" (*note MERGE::)
* "OPEN" (*note OPEN::)
* "READ" (*note READ::)
* "REWRITE" (*note REWRITE::)
* "SORT" (*note SORT::)
* "UNLOCK" (*note UNLOCK::)
* "WRITE" (*note WRITE::)
File: gnucobpg.info, Node: ORGANIZATION LINE SEQUENTIAL, Next: ORGANIZATION RELATIVE, Prev: ORGANIZATION SEQUENTIAL, Up: SELECT
4.2.1.2. ORGANIZATION LINE SEQUENTIAL
.....................................
ORGANIZATION LINE SEQUENTIAL Clause Syntax
=======================================================================
[ ORGANIZATION|ORGANISATION IS ] LINE SEQUENTIAL
~~~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~ ~~~~~~~~~~
[ ACCESS MODE IS SEQUENTIAL ]
~~~~~~ ~~~~~~~~~~
[ PADDING CHARACTER IS literal-1 | identifier-1 ]
~~~~~~~
The "PADDING CHARACTER" clause is syntactically recognized but is
otherwise non-functional.
=======================================================================
Files declared as "ORGANIZATION LINE SEQUENTIAL" will consist of
records terminated by an end-of-record delimiter character or character
sequence.
1. The reserved words "CHARACTER", "IS" and "MODE" are optional and
may be included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. The reserved words "ORGANIZATION" and "ORGANISATION" are
interchangeable.
3. The phrase "ORGANIZATION IS" (and it's internationalized
alternative, "ORGANISATION IS") is optional to provide
compatibility with those (few) COBOL implementations that consider
that word to be optional. Most COBOL implementations do require
the word "ORGANIZATION", so it should be used in new programs.
4. This is the only "ORGANIZATION" valid for files that are assigned
to the "PRINTER" device.
5. These files may be created with any standard text-editing or word
processing software capable of writing text files. Such files
should not contain any "USAGE COMPUTATIONAL" or "BINARY" (of any
variety) data since such fields could accidentally contain byte
sequences that could be interpreted as an end-of-record
delimiter.
6. Both fixed- and variable-length record formats are supported.
7. The end-of-record delimiter sequence will be X'0A' (an ASCII
line-feed character) or a X'0D0A' (an ASCII carriage-return +
line-feed sequence). The former is used on Unix implementations
of GNU COBOL (including Windows/MinGW, Windows/Cygwin and OSX
implementations) while the latter would be used with native
Windows implementations.
8. When reading a "LINE SEQUENTIAL" file, records in excess of the
size implied by the file's description in the "FILE SECTION" will
be truncated while records shorter than that size will be padded
to the right with "SPACES".
9. The "ACCESS MODE SEQUENTIAL" clause is optional because, if
absent, it will be assumed anyway for this type of file. The
internal structure of these files is such that the data can only
be processed in a sequential manner; in order to read the 100th
record in such a file, for example, you first must read records 1
through 99.
10. Files assigned to "PRINTER" or "CONSOLE" should be specified as
"ORGANIZATION LINE SEQUENTIAL".
11. Line Sequential files are processed using the following
statements:
* "CLOSE" (*note CLOSE::)
* "COMMIT" (*note COMMIT::)
* "DELETE" (*note DELETE::)
* "MERGE" (*note MERGE::)
* "OPEN" (*note OPEN::)
* "READ" (*note READ::)
* "REWRITE" (*note REWRITE::)
* "SORT" (*note SORT::)
* "UNLOCK" (*note UNLOCK::)
* "WRITE" (*note WRITE::)
File: gnucobpg.info, Node: ORGANIZATION RELATIVE, Next: ORGANIZATION INDEXED, Prev: ORGANIZATION LINE SEQUENTIAL, Up: SELECT
4.2.1.3. ORGANIZATION RELATIVE
..............................
ORGANIZATION RELATIVE Clause Syntax
=======================================================================
[ ORGANIZATION|ORGANISATION IS ] RELATIVE
~~~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~~~
[ ACCESS MODE IS { SEQUENTIAL } ]
~~~~~~ { ~~~~~~~~~~ }
{ DYNAMIC }
{ ~~~~~~~ }
{ RANDOM }
~~~~~~
[ RELATIVE KEY IS identifier-1 ]
~~~~~~~~
=======================================================================
These files are files with an internal organization such that records
may be processed in a sequential manner based upon their physical
location in the file or in a random manner by allowing records to be
read, written or updated by specifying the relative record number in
the file.
1. The reserved words "IS", "KEY" and "MODE" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. The reserved words "ORGANIZATION" and "ORGANISATION" are
interchangeable.
3. The phrase "ORGANIZATION IS" (and it's internationalized
alternative, "ORGANISATION IS") is optional to provide
compatibility with those (few) COBOL implementations that consider
that word to be optional. Most COBOL implementations do require
the word "ORGANIZATION", so it should be used in new programs.
4. "ORGANIZATION RELATIVE" files cannot be assigned to the "CONSOLE",
"DISPLAY", "LINE ADVANCING" or "PRINTER" devices.
5. The "RELATIVE KEY" clause is optional only if "ACCESS MODE
SEQUENTIAL" is specified.
6. While an "ORGANIZATION RELATIVE" file may be defined as having
variable-length records, the file will be structured in such a
manner as to reserve space for each record equal to the size of
the largest possible record as defined by the file's description
in the "FILE SECTION".
7. "ACCESS MODE SEQUENTIAL", the default "ACCESS MODE" if none is
specified, indicates that the records of the file will be
processed in a sequential manner, according to their physical
sequence in the file.
8. "ACCESS MODE RANDOM" means that records will be processed in
random sequence by specifying their record number in the file
every time the file is read or written.
9. "ACCESS MODE DYNAMIC" indicates the program may switch back and
forth between "SEQUENTIAL" and "RANDOM" mode during execution.
The file starts out initially in "SEQUENTIAL" mode when first
opened but the program may use the "START" statement (*note
START::) to switch between sequential and random access.
10. The "RELATIVE KEY" data item is a numeric data item that cannot be
defined as a field within records of this file. Its purpose is to
return the current relative record number of a relative file that
is being processed in "SEQUENTIAL" access mode and to serve as a
key that specifies the relative record number to be read or
written when processing a relative file in "RANDOM" access mode.
11. Relative files are processed using the following statements:
* "CLOSE" (*note CLOSE::)
* "COMMIT" (*note COMMIT::)
* "DELETE" (*note DELETE::)
* "MERGE" (*note MERGE::), "ACCESS MODE RANDOM" not allowed
* "OPEN" (*note OPEN::)
* "READ" (*note READ::)
* "REWRITE" (*note REWRITE::)
* "SORT" (*note SORT::), "ACCESS MODE RANDOM" not allowed
* "START" (*note START::)
* "UNLOCK" (*note UNLOCK::)
* "WRITE" (*note WRITE::)
File: gnucobpg.info, Node: ORGANIZATION INDEXED, Prev: ORGANIZATION RELATIVE, Up: SELECT
4.2.1.4. ORGANIZATION INDEXED
.............................
ORGANIZATION INDEXED Clause Syntax
=======================================================================
[ ORGANIZATION|ORGANISATION IS ] INDEXED
~~~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~~
[ ACCESS MODE IS { SEQUENTIAL } ]
~~~~~~ { ~~~~~~~~~ }
{ DYNAMIC }
{ ~~~~~~~ }
{ RANDOM }
~~~~~~
[ RECORD KEY IS identifier-1
~~~~~~
[ =|{SOURCE IS} identifier-2 ] ]
~~~~~~
[ ALTERNATE RECORD KEY IS identifier-3
~~~~~~~~~ ~~~~~~
[ =|{SOURCE IS} identifier-4 ]
~~~~~~
[ WITH DUPLICATES ] ]...
~~~~~~~~~~
The "SOURCE" clause is syntactically recognized but is otherwise
non-functional. It is supported to provide compatibility with COBOL
source written for other COBOL implementations.
=======================================================================
Indexed files, like relative files, may have their records processed in
either a sequential or random manner. Unlike relative files, however,
the actual location of a record in an indexed file is calculated
automatically based upon the value(s) of one or more alphanumeric
fields within records of the file. For example, an indexed file
containing product data might use the product identification code as a
record 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 reserved words "IS", "KEY" and "MODE" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. The reserved words "ORGANIZATION" and "ORGANISATION" are
interchangeable.
3. The phrase "ORGANIZATION IS" (and it's internationalized
alternative, "ORGANISATION IS") is optional to provide
compatibility with those (few) COBOL implementations that consider
that word to be optional. Most COBOL implementations do require
the word "ORGANIZATION", so it should be used in new programs.
4. "ORGANIZATION INDEXED" files cannot be assigned to "CONSOLE",
"DISPLAY", "KEYBOARD", "LINE ADVANCING" or "PRINTER".
5. "ACCESS MODE SEQUENTIAL", the default "ACCESS MODE" if none is
specified, indicates that the records of the file will be
processed in a sequential manner with respect to the values of the
"RECORD KEY" or the "ALTERNATE RECORD KEY" most-recently
referenced on a "START" statement (*note START::).
6. "ACCESS MODE RANDOM" means that records will be processed in
random sequence by accessing the record with specific record key
or alternate record key values.
7. "ACCESS MODE DYNAMIC" allows the file will be processed either in
"RANDOM" or "SEQUENTIAL" mode; the program may switch between the
two modes as needed. The "START" statement is used to make the
switch between modes.
8. The "PRIMARY KEY" clause defines the field within the record used
to provide the primary access to records within the file. No two
records in the file will be allowed to have the same "PRIMARY KEY"
field value.
9. The "ALTERNATE RECORD KEY" clause, if used, defines an additional
field within the record that provides an alternate means of
directly accessing records or an additional field by which the
file's contents may be processed sequentially. You have the
choice of allowing records to have duplicate alternate key values,
if necessary.
10. There may be multiple "ALTERNATE RECORD KEY" clauses, each
defining an additional alternate key for the file.
11. Indexed files are processed using the following statements:
* "CLOSE" (*note CLOSE::)
* "COMMIT" (*note COMMIT::)
* "DELETE" (*note DELETE::)
* "MERGE" (*note MERGE::), "ACCESS MODE RANDOM" not allowed
* "OPEN" (*note OPEN::)
* "READ" (*note READ::)
* "REWRITE" (*note REWRITE::)
* "SORT" (*note SORT::), "ACCESS MODE RANDOM" not allowed
* "START" (*note START::)
* "UNLOCK" (*note UNLOCK::)
* "WRITE" (*note WRITE::)
File: gnucobpg.info, Node: MULTIPLE FILE, Prev: SAME RECORD AREA, Up: INPUT-OUTPUT SECTION
4.2.2. MULTIPLE FILE
--------------------
I-O-CONTROL MULTIPLE FILE Syntax
=======================================================================
MULTIPLE FILE TAPE CONTAINS
~~~~~~~~
{ file-name-1 [ POSITION integer-1 ] }...
~~~~~~~~
.
The "MULTIPLE FILE TAPE" clause is obsolete and is therefore recognized
but not functional.
=======================================================================
File: gnucobpg.info, Node: SAME RECORD AREA, Next: MULTIPLE FILE, Up: INPUT-OUTPUT SECTION
4.2.3. SAME RECORD AREA
-----------------------
I-O-CONTROL SAME AREA Syntax
=======================================================================
SAME { SORT-MERGE } AREA FOR file-name-1... .
~~~~ { ~~~~~~~~~~ }
{ SORT }
{ ~~~~ }
{ RECORD }
~~~~~~
The "SAME SORT-MERGE" and "SAME SORT" clauses are syntactically
recognized but are otherwise non-functional.
=======================================================================
The "SAME RECORD AREA" clause allows you to specify that multiple files
should share the same input and output memory buffers.
1. The reserved words "AREA" and "FOR" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. This statement must be terminated with a period.
3. While coding only a single file name (the repeated
item) is syntactically valid, this statement will have no effect
upon the program unless at least two files are specified.
4. The effect of this statement will be to cause the specified files
to share the same I/O buffer in memory. These buffers can
sometimes get quite large, and by having multiple files share the
same buffer memory you may significantly cut down the amount of
memory the program is using (thus making "room" for more
procedural code or data). If you do use this feature, take care
to ensure that no more than one of the specified files are ever
OPEN simultaneously.
File: gnucobpg.info, Node: DATA DIVISION, Next: PROCEDURE DIVISION, Prev: ENVIRONMENT DIVISION, Up: Top
5. DATA DIVISION
****************
DATA DIVISION Syntax
=======================================================================
DATA DIVISION.
~~~~ ~~~~~~~~
[ FILE SECTION.
~~~~ ~~~~~~~
{ File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ]
{ { 01-Level-Constant } }
{ { 78-Level-Constant } }
{ 01-Level-Constant }
{ 78-Level-Constant }
[ WORKING-STORAGE SECTION.
~~~~~~~~~~~~~~~ ~~~~~~~
[ { WORKING-STORAGE-SECTION-Data-Item } ]... ]
{ 01-Level-Constant }
{ 78-Level-Constant }
[ LOCAL-STORAGE SECTION.
~~~~~~~~~~~~~ ~~~~~~~
[ { LOCAL-STORAGE-SECTION-Data-Item } ]... ]
{ 01-Level-Constant }
{ 78-Level-Constant }
[ LINKAGE SECTION.
~~~~~~~ ~~~~~~~
[ { LINKAGE-SECTION-Data-Item } ]... ]
{ 01-Level-Constant }
{ 78-Level-Constant }
[ REPORT SECTION.
~~~~~~ ~~~~~~~
{ Report-Description [ { Report-Group-Definition } ]... }... ]
{ { 01-Level-Constant } }
{ { 78-Level-Constant } }
{ 01-Level-Constant }
{ 78-Level-Constant }
[ SCREEN SECTION.
~~~~~~ ~~~~~~~
[ { SCREEN-SECTION-Data-Item } ]... ]
{ 01-Level-Constant }
{ 78-Level-Constant }
=======================================================================
All data used by any COBOL program must be defined in one of the six
sections of the data division, depending upon the purpose of the data.
1. If no data will be described in one of the data division sections,
that section header may be omitted.
2. If no data division sections are needed, the "DATA DIVISION."
header itself may be omitted.
3. If more than one section is needed in the data division (a common
situation), the sections must be coded in the sequence they are
presented above.
* Menu:
* 5.1: Data Definition Principles.
* 5.2: FILE SECTION.
* 5.2.1: File/Sort-Description.
* 5.2.2: FILE-SECTION-Data-Item.
* 5.3: WORKING-STORAGE SECTION.
* 5.4: LOCAL-STORAGE SECTION.
* 5.5: LINKAGE SECTION.
* 5.6: REPORT SECTION.
* 5.6.1: Report Group Definitions.
* 5.6.2: REPORT SECTION Data Items.
* 5.7: SCREEN SECTION.
* 5.8: Special Data Items.
* 5.8.1: 01-Level Constants.
* 5.8.2: 66-Level Data Items.
* 5.8.3: 77-Level Data Items.
* 5.8.4: 78-Level Data Items.
* 5.8.5: 88-Level Data Items.
* 5.9: Data Description Clauses.
File: gnucobpg.info, Node: Data Definition Principles, Next: FILE SECTION, Up: DATA DIVISION
5.1. Data Definition Principles
===============================
GNU COBOL data items, like those of other COBOL implementations, are
described in a hierarchical manner. This accommodates the fact that
data items frequently need to be able to be broken up into subordinate
items. Take for example, the following logical layout of a portion of
a data item named "Employee":
Employee
| Additional
:----------------:----------------:--> Data Items ...
| |
Employee-name Employment-Dates
| |
:---------:-------------: :-------:-------:
| | | | |
Last-Name First-Name Middle-Initial From-Date To-Date
| |
:----:----: :----:----:
| | | | | |
Year Month Day Year Month Day
The "Employee" data item consists of two subordinate data items -- an
"Employee-Name" and an "Employment-Dates" data item (presumably there
would be a lot of others too, but we don't care about them right now).
As the diagram shows, each of those data items are, in turn, broken
down into subordinate data items. This hierarchy of data items can get
rather "deep", and GNU COBOL, like other COBOL implementations, can
handle up to 49 levels of such hierarchical structures.
As was presented earlier (*note Structured Data::), a data item that is
broken down into other data items is referred to as a group item, while
one that isn't broken down is called an elementary item.
COBOL uses the concept of a "level number" to indicate the level at
which a data item occurs in a data structure such as the example shown
above. When these data items are defined, they are all defined
together with a number in the range 1-49 specified in front of their
names. Over the years, a convention has come to exist among COBOL
programmers that level numbers are always coded as two-digit numbers --
they don't have to be specified as two-digit numbers, but every example
you see in this document will take that approach!
The data item at the top, also referred to as a "record", always has a
level number of 01. After that, you may assign level numbers as you
wish (01-02-03-04..., 01-05-10-15..., etc.), as long as you follow
these simple rules:
1. Every data item at the same "level" of a hierarchy diagram such as
the one you see here (if you were to make one, which you rarely --
if ever -- will, once you get used to this concept) must have the
same level number.
2. Every new level uses a level number that is strictly greater than
the one used in the parent (next higher) level.
3. When describing data hierarchies, you may never use a level number
greater than 49 (except for 66, 77, 78 and 88 which have very
special meanings -- see *note Special Data Items::).
So, the definition of these data items in a GNU COBOL program would go
something like this:
01 Employee
05 Employee-Name
10 Last-Name
10 First-Name
10 Middle-Initial
05 Employment-Dates
10 From-Date
15 Year
15 Month
15 Day
10 To-Date
15 Year
15 Month
15 Day
The indentation is purely at the discretion of the programmer to make
things easier for humans to read (the compiler couldn't care less).
Historically, COBOL implementations that required Fixed Format Mode
source programs required that the "01" level number begin in Area A and
that everything else begins in Area B. GNU COBOL only requires that
all data definition syntax occur in columns 8-72. In Free Format Mode,
of course, there aren't even those limitations.
Did you notice that there are two each of "Year", "Month" and "Day"
data names defined? Thet's perfectly legal, provided that each can be
uniquely "qualified" so as to be distinct from the other. Take for
example the "Year" items. One is defined as part of the "From-Date"
data item while the other is defined as part of the "To-Date" data
item. In COBOL, we would actually code references to these two data
items as either "Year OF From-Date" and "Year OF To-Date" or "Year IN
From-Date" and "Year IN To-Date" (COBOL allows either "IN" or "OF" to
be used). Since these references would clarify any confusion to us as
to which "Year" might be referenced, the GNU COBOL compiler won't be
confused either.
The coding example shown above is incomplete -- it only describes the
data item names and their hierarchical relationships to one other. In
addition, any valid data item definitions will also need to describe
what type of data is to be contained in a data item (Numeric?
Alphanumeric? Alphabetic?), how much data can be held in the data item
and a multitude of other characteristics.
When group items are being defined, subordinate items may be assigned a
"name" of "FILLER". There may be any number of "FILLER" items defined
within a group item. A data item named "FILLER" cannot be referenced
directly; these items are generally used to specify an unused portion
of the total storage allocated to a group item. Note that it is
possible that the name of the group item itself might be specified as
"FILLER" if there is no need to ever refer directly to the group
structure itself.
File: gnucobpg.info, Node: FILE SECTION, Prev: Data Definition Principles, Up: DATA DIVISION
5.2. FILE SECTION
=================
FILE SECTION Syntax
=======================================================================
[ FILE SECTION.
~~~~ ~~~~~~~
{ File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ]
{ { 01-Level-Constant } }
{ { 78-Level-Constant } }
{ 01-Level-Constant }
{ 78-Level-Constant }
=======================================================================
Every file that has been referenced by a "SELECT" statement (*note
SELECT::) must also be described in the file section of the data
division.
Files destined for use as sort/merge work files must be described with
a Sort/Merge File Description ("SD") while every other file is
described with a File Description ("FD"). Each of these descriptions
will almost always be followed with at least one record description.
* Menu:
* 5.2.1: File/Sort-Description.
* 5.2.2: FILE-SECTION-Data-Item.
File: gnucobpg.info, Node: File/Sort-Description, Next: FILE-SECTION-Data-Item, Up: FILE SECTION
5.2.1. File/Sort-Description
----------------------------
File/Sort-Description Syntax
=======================================================================
FD|SD file-name-1 [ IS EXTERNAL|GLOBAL ]
~~ ~~ ~~~~~~~~ ~~~~~~
[ BLOCK CONTAINS [ integer-1 TO ] integer-2 CHARACTERS|RECORDS ]
~~~~~ ~~ ~~~~~~~~~~ ~~~~~~~
[ CODE-SET IS alphabet-name-1 ]
~~~~~~~~
[ DATA { RECORD IS } identifier-1... ]
~~~~ { ~~~~~~ }
{ RECORDS ARE }
~~~~~~~
[ LABEL { RECORD IS } OMITTED|STANDARD ]
~~~~~ { ~~~~~~ } ~~~~~~~ ~~~~~~~~
{ RECORDS ARE }
~~~~~~~
[ LINAGE IS integer-3 | identifier-2 LINES
~~~~~~
[ LINES AT BOTTOM integer-4 | identifier-3 ]
~~~~~~
[ LINES AT TOP integer-5 | identifier-4 ]
~~~
[ WITH FOOTING AT integer-6 | identifier-5 ] ]
~~~~~~~
[ RECORD { CONTAINS [ integer-7 TO ] integer-8 CHARACTERS } ]
~~~~~~ { ~~ }
{ IS VARYING IN SIZE }
{ ~~~~~~~ }
{ [ FROM [ integer-7 TO ] integer-8 CHARACTERS }
{ ~~ }
{ DEPENDING ON identifier-6 ] }
~~~~~~~~~
[ RECORDING MODE IS recording-mode ]
~~~~~~~~~
[ { REPORT IS } report-name-1... ]
{ ~~~~~~ }
{ REPORTS ARE }
~~~~~~~
[ VALUE OF implementor-name-1 IS literal-1 | identifier-7 ] .
~~~~~ ~~
The "BLOCK CONTAINS", "DATA RECORD", "LABEL RECORD", "RECORDING MODE" and
"VALUE OF" clauses are syntactically recognized but are obsolete and
non-functional. These clauses should not be coded in new programs.
=======================================================================
1. The reserved words "ARE", "AT", "CHARACTERS" ("RECORD" clause
only), "CONTAINS", "FROM", "IN", "IS", "ON" and "WITH" are
optional and may be included, or not, at the discretion of the
programmer. The presence or absence of these words has no effect
upon the program.
2. The terms "RECORD IS" and "RECORDS ARE" are interchangeable.
3. The terms "REPORT IS" and "REPORTS ARE" are interchangeable.
4. Only files intended for use as work files for either the "SORT"
(*note SORT::) or "MERGE" (*note MERGE::) statements should be
coded with an SD -- all others should be defined with a FD.
5. The sequence in which files are defined via "FD" or "SD", as
compared to the sequence in which their "SELECT" statements were
coded, is irrelevant.
6. The name specified as must exactly match the name
specified on the file's "SELECT" statement.
7. The "CODE-SET" clause allows a custom alphabet, defined in the
"SPECIAL-NAMES" (*note SPECIAL-NAMES::) paragraph, to be
associated with a file. This clause is valid only when used with
sequential or line sequential files.
8. The "LINAGE" clause may only be specified in the "FD" of a
sequential or line sequential file. If used with a sequential
file, the organization of that file will be implicitly changed to
line sequential. The various components of the "LINAGE" clause
define the layout of printed pages as follows:
* "LINES AT TOP" -- the number of unused (i.e. left blank)
lines at the top of every page. The default if this if not
specified is zero.
* "LINES AT BOTTOM" -- the number of unused (i.e. left blank)
lines at the bottom of every page. The default if this if
not specified is zero.
* "LINAGE IS n LINES" -- the total number of used/usable lines
on the page.
* The sum of the previous three specifications should be the
total number of possible lines available on one printed
page.
* "FOOTING AT" -- the line number beyond which nothing may be
printed except for any footing that is to appear on every
page. The default for this if not specified is zero, meaning
there will be no footings. This value cannot be larger than
the "LINAGE IS n LINES" value.
9. This page structure -- once defined -- can be automatically
enforced by the "WRITE" statement (*note WRITE::).
10. Specifying a "LINAGE" clause in an "FD" will cause the
"LINAGE-COUNTER" special register to be created for the file.
This automatically-created data item will always contain the
current relative line number on the page being prepared which will
serve as the starting point for a "WRITE" statement.
11. The "RECORD CONTAINS" and "RECORD IS VARYING" clauses are ignored
(with a warning message issued) when used with line sequential
files. With other file organizations, these mutually-exclusive
clauses define the length of data records within the file. The
data item specified as must be defined within one
of the record descriptions of .
12. The "REPORT IS" clause announces to the compiler that the file
will be dedicated to the Report Writer Control System (RWCS); the
clause names one or more reports, each to be described in the
report section. The following special rules apply when the
"REPORT" clause is used:
A. The clause may only be specified in the "FD" of a sequential
or line sequential file. If used with a sequential file, the
organization of that file will be implicitly changed to line
sequential.
B. The "FD" cannot be followed by record descriptions --
detailed descriptions of data to be printed to the file will
be defined in the "REPORT SECTION" (*note REPORT SECTION::).
C. If a "LINAGE" clause is also specified, Values specified for
"LINAGE IS" and "FOOTING AT" will be ignored. The values of
"LINES AT BOTTOM" and "LINES AT TOP", if any, will be
honored.
13. The following special rules apply only to sort/merge work files:
A. Sort/merge work files should be assigned to "DISK" (or
"DISC") on their "SELECT" statements.
B. Sorts and merges will be performed in memory, if the amount
of data being sorted allows.
C. Should actual disk work files be necessary due to the amount
of data being sorted or merged, they will be automatically
allocated to disk in a folder defined by:
* The "TMPDIR" run-time environment variable (*note Run
Time Environment Variables::)
* The "TMP" run-time environment variable
* The "TEMP" run-time environment variable
(in that order)
D. These disk files will be automatically purged upon "SORT" or
"MERGE" termination. They will also be purged if the program
terminates abnormally before the "SORT" or "MERGE" finishes.
Should you ever need to know, temporary sort/merge work files
will be named "cob*.tmp".
E. If you specify a specific filename in the sort/merge work
file's "SELECT", it will be ignored.
14. *Note Data Description Clauses::, for information on the
"EXTERNAL" and "GLOBAL" options.
File: gnucobpg.info, Node: FILE-SECTION-Data-Item, Prev: File/Sort-Description, Up: FILE SECTION
5.2.2. FILE-SECTION-Data-Item
-----------------------------
FILE-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ]
~~~~~~ ~~~~~~ ~~~~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~
[ DEPENDING ON identifier-2 ]
~~~~~~~~~
[ ASCENDING|DESCENDING KEY IS identifier-3 ]
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY identifier-4 ] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE [CHARACTER] ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ] . [ FILE-SECTION-Data-Item ]...
~~~~~
The "LEFT" and "RIGHT" (SYNCRONIZED) clauses are syntactically
recognized but are otherwise non-functional.
=======================================================================
Every sort file description ("SD" or "FD") must be followed by at least
one 01-level data item, except for file descriptions containing the
"REPORT IS" clause. These 01-level data items, in turn, may be broken
down into subordinate group and elementary items. An 01-level data
item defined here in the file section is also known as a 'Record', even
if it is an elementary item, provided that elementary item lacks the
"CONSTANT" attribute.
1. The reserved words "BY", "IS", "KEY", "ON" and "WHEN" are optional
and may be included, or not, at the discretion of the programmer.
The presence or absence of these words has no effect upon the
program.
2. The reserved words "SYNCRONIZED" and "SYNCRONIZED" are
interchangeable. Both may be abbreviated to "SYNC".
3. The reserved word "PICTURE" may be abbreviated to "PIC".
4. As the syntax diagram shows, the definition of a
<> is a recursive one in that there may be
any number of such specifications coded following a FD or SD. The
first such specification must have a level number of 01, and will
describe a specific format of data record within the file.
Specifications that follow that one may have level numbers greater
than 01, in which case they are defining a hierarchical breakdown
of the record. The definition of a record is terminated when one
of the following occurs:
* Another 01-level item is found -- this signifies the start of
another record layout for the file.
* Another "FD" or "SD" is found -- this marks the completion of
the detailed description of the file and begins another.
* A division or section header is found -- this also marks the
completion of the detailed description of the file and
signifies the end of the file section as well.
5. Every <> description must be terminated
with a period.
6. If there are multiple record descriptions present for a given "FD"
or "SD", the one with the longest length will define the size of
the record buffer into which a "READ" statement (*note READ::) or
a "RETURN" statement (*note RETURN::) will deliver data read from
the file and from which a "WRITE" statement (*note WRITE::) or
"RELEASE" statement (*note RELEASE::) statement will obtain the
data to be written to the file.
7. The various 01-level record descriptions for a file description
implicitly share that one common record buffer (thus, they provide
different ways to view the structure of data that can exist within
the file). Record buffers can be shared between files by using
the "SAME RECORD AREA" (*note SAME RECORD AREA::) clause.
8. The only valid level numbers are 01-49, 66, 77, 78 and 88. Level
numbers 66, 77, 78 and 88 all have special uses -- *Note Special
Data Items::, for details.
9. Not specifying an or "FILLER" immediately after the
level number has the same effect as if "FILLER" were specified. A
data item named "FILLER" cannot be referenced directly; these
items are generally used to specify an unused portion of the total
storage allocated to a group item or to describe a group item
whose contents which will only be referenced using the names of
those items that belong to it.
10. "EXTERNAL" cannot be combined with "GLOBAL" or "REDEFINES".
11. File section data buffers (and therefore all 01-level record
layouts defined in the file section) are initialized to all binary
zeros when the program is loaded into storage.
12. *Note Data Description Clauses::, for information on the usage of
the various data description clauses.
File: gnucobpg.info, Node: WORKING-STORAGE SECTION, Next: LOCAL-STORAGE SECTION, Up: DATA DIVISION
5.3. WORKING-STORAGE SECTION
============================
WORKING-STORAGE-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1 | FILLER ] [ IS GLOBAL | EXTERNAL ]
~~~~~~ ~~~~~~ ~~~~~~~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~
[ DEPENDING ON identifier-2 ]
~~~~~~~~~
[ ASCENDING|DESCENDING KEY IS identifier-3 ]
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY identifier-4 ] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ WORKING-STORAGE-SECTION-Data-Item ]...
~~~~~ ~~~
The "LEFT" and "RIGHT" (SYNCRONIZED) clauses are syntactically
recognized but are otherwise non-functional.
=======================================================================
The working-storage section is used to describe data items that are not
part of files, screens or reports and whose data values persist
throughout the execution of the program.
1. The reserved words "BY", "CHARACTER", "IS", "KEY", "ON", "RIGHT"
(JUSTIFIED), "TIMES" and "WHEN" are optional and may be included,
or not, at the discretion of the programmer. The presence or
absence of these words has no effect upon the program.
2. The reserved words "SYNCRONIZED" and "SYNCRONISED" are
interchangeable. Both may be abbreviated as "SYNC".
3. The reserved word "PICTURE" may be abbreviated to "PIC".
4. The reserved word "JUSTIFIED" may be abbreviated to "JUST".
5. As the syntax diagram shows, the definition of a
<> is a recursive one in that
there may be any number of such specifications coded following one
another. The first such specification must have a level number of
01. Specifications that follow that one may have level numbers
greater than 01, in which case they are defining a hierarchical
breakdown of a record. The definition of a record is terminated
when one of the following occurs:
* Another 01-level item is found -- this signifies the end of
the definition of one record and the start of a another.
* A 77-level item is found -- this signifies the end of the
definition of the record and begins the definition of a
special data item; *Note 77-Level Data Items::, for more
information.
* A division or section header is found -- this also marks the
completion of a record and signifies the end of the
working-storage section as well.
6. Every <> description must be
terminated with a period.
7. The only valid level numbers are 01-49, 66, 77, 78 and 88. Level
numbers 01 through 49 are used to define data items that may be
part of a hierarchical structure. Level number 01 can also be
used to define a constant -- an item with an unchangable value
specified at compilation time.
8. Level numbers 66, 77, 78 and 88 all have special uses -- *Note
Special Data Items::, for details.
9. Not specifying an or "FILLER" immediately after the
level number has the same effect as if "FILLER" were specified. A
data item named "FILLER" cannot be referenced directly; these
items are generally used to specify an unused portion of the total
storage allocated to a group item or to describe a group item
whose contents which will only be referenced using the names of
those items that belong to it.
10. Data items defined within the working-storage section are
automatically initialized once -- as the program in which the data
is defined is loaded into memory. Subprograms may be loaded into
memory more than once (see the "CANCEL" statement (*note
CANCEL::)), in which case initialization will happen each time
they are loaded. *Note Data Initialization::, for a discussion of
the initialization rules.
11. *Note Data Description Clauses::, for information on the usage of
the various data description clauses.
File: gnucobpg.info, Node: LOCAL-STORAGE SECTION, Next: LINKAGE SECTION, Prev: WORKING-STORAGE SECTION, Up: DATA DIVISION
5.4. LOCAL-STORAGE SECTION
==========================
LOCAL-STORAGE-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ]
~~~~~~ ~~~~~~ ~~~~~~~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~
[ DEPENDING ON identifier-2 ]
~~~~~~~~~
[ ASCENDING|DESCENDING KEY IS identifier-3 ]
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY identifier-4 ] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ LOCAL-STORAGE-SECTION-Data-Item ]...
~~~~~ ~~~
The "LEFT" and "RIGHT" (SYNCRONIZED) clauses are syntactically
recognized but are otherwise non-functional.
=======================================================================
The local-storage section is similar to working-storage, but describes
data within a subprogram that will be dynamically allocated and
initialized (automatically) each time the subprogram is executed.
*Note Data Initialization::, for the rules of data ititialization.
1. The reserved words "BY", "CHARACTER" "IS", "KEY", "ON", "RIGHT"
(JUSTIFIED), "TIMES" and "WHEN" are optional and may be included,
or not, at the discretion of the programmer. The presence or
absence of these words has no effect upon the program.
2. The reserved words "SYNCRONIZED" and "SYNCRONISED" are
interchangeable. Both may be abbreviated as "SYNC".
3. The reserved word "PICTURE" may be abbreviated to "PIC".
4. The reserved word "JUSTIFIED" may be abbreviated to "JUST".
5. As the syntax diagram shows, the definition of a
<> is a recursive one in that
there may be any number of such specifications coded following one
another. The first such specification must have a level number of
01. Specifications that follow that one may have level numbers
greater than 01, in which case they are defining a hierarchical
breakdown of a record. The definition of a record is terminated
when one of the following occurs:
* Another 01-level item is found -- this signifies the end of
the definition of one record and the start of a another.
* A division or section header is found -- this also marks the
completion of a record and signifies the end of the
local-storage section as well.
6. Every <> description must be
terminated with a period.
7. The only valid level numbers are 01-49, 66, 77, 78 and 88. Level
numbers 01 through 49 are used to define data items that may be
part of a hierarchical structure. Level number 01 can also be
used to define a constant -- an item with an unchangable value
specified at compilation time.
8. Level numbers 66, 77, 78 and 88 all have special uses -- *Note
Special Data Items::, for details.
9. Not specifying an or "FILLER" immediately after the
level number has the same effect as if "FILLER" were specified. A
data item named "FILLER" cannot be referenced directly; these
items are generally used to specify an unused portion of the total
storage allocated to a group item or to describe a group item
whose contents which will only be referenced using the names of
those items that belong to it.
10. Local-storage cannot be used in nested subprograms.
11. *Note Data Description Clauses::, for information on the usage of
the various data description clauses.
File: gnucobpg.info, Node: LINKAGE SECTION, Next: REPORT SECTION, Prev: LOCAL-STORAGE SECTION, Up: DATA DIVISION
5.5. LINKAGE SECTION
====================
LINKAGE-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ]
~~~~~~ ~~~~~~ ~~~~~~~~
[ ANY LENGTH ]
~~~ ~~~~~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~
[ DEPENDING ON identifier-3 ]
~~~~~~~~~
[ ASCENDING|DESCENDING KEY IS identifier-4 ]
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY identifier-5 ] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-6 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ] . [ LINKAGE-SECTION-Data-Item ]...
~~~~~
The "LEFT" and "RIGHT" (SYNCRONIZED) clauses are syntactically
recognized but are otherwise non-functional.
=======================================================================
The linkage section describes data within a subprogram that serves as
either input arguments to or output results from the subprogram.
1. The reserved words "BY", "CHARACTER", "IS", "KEY", "ON" and "WHEN"
are optional and may be included, or not, at the discretion of the
programmer. The presence or absence of these words has no effect
upon the program.
2. The reserved words "SYNCRONIZED" and ""SYNCRONISED"" are
interchangeable. Both may be abbreviated as "SYNC".
3. The reserved word "PICTURE" may be abbreviated to "PIC".
4. The reserved word "JUSTIFIED" may be abbreviated to "JUST".
5. As the syntax diagram shows, the definition of a
<> is a recursive one in that there may
be any number of such specifications coded following one another.
The first such specification must have a level number of 01.
Specifications that follow that one may have level numbers greater
than 01, in which case they are defining a hierarchical breakdown
of a record. The definition of a record is terminated when one of
the following occurs:
* Another 01-level item is found -- this signifies the end of
the definition of one record and the start of a another.
* A division or section header is found -- this also marks the
completion of a record and signifies the end of the linkage
section as well.
6. Every <> description must be terminated
with a period.
7. The only valid level numbers are 01-49, 66, 77, 78 and 88. Level
numbers 01 through 49 are used to define data items that may be
part of a hierarchical structure. Level number 01 can also be
used to define a constant -- an item with an unchangable value
specified at compilation time.
8. Level numbers 66, 77, 78 and 88 all have special uses -- *Note
Special Data Items::, for details.
9. It is expected that:
A. A linkage section should occur only within a subprogram. The
compiler will not prevent its use in a main program,
however.
B. All 01-level data items described within a subprogram's
linkage section should appear in a "PROCEDURE DIVISION USING"
(*note PROCEDURE DIVISION USING::) or as arguments on an
"ENTRY" statement.
C. Each 01-level data item described within a subprogram's
linkage section should correspond to an argument passed on a
"CALL" statement (*note CALL::) or an argument on a function
call to the subprogram.
10. Not specifying an or "FILLER" immediately after the
level number has the same effect as if "FILLER" were specified. A
data item named "FILLER" cannot be referenced directly; these
items are generally used to specify an unused portion of the total
storage allocated to a group item or to describe a group item
whose contents which will only be referenced using the names of
those items that belong to it. In the linkage section, 01-level
data items cannot be named "FILLER".
11. No storage is allocated for data defined in the linkage section;
the data descriptions there are merely defining storage areas that
will be passed to the subprogram by a calling program. Therefore,
any discussion of the default initialization of such data is
irrelevant. It is possible, however, to manually allocate linkage
section data items that aren't subprogram arguments via the
"ALLOCATE" statement (*note ALLOCATE::) statement. In such cases,
initialization will take place as per the documentation of that
statement.
12. *Note Data Description Clauses::, for information on the usage of
the various data description clauses.
File: gnucobpg.info, Node: REPORT SECTION, Prev: LINKAGE SECTION, Up: DATA DIVISION
5.6. REPORT SECTION
===================
REPORT SECTION Syntax
=======================================================================
[ REPORT SECTION.
~~~~~~ ~~~~~~~
{ Report-Description [ { Report-Group-Definition } ]... }... ]
{ { 01-Level-Constant } }
{ { 78-Level-Constant } }
{ 01-Level-Constant }
{ 78-Level-Constant }
=======================================================================
Report-Description (RD) Syntax
=======================================================================
RD report-name [ IS GLOBAL ]
~~ ~~~~~~
[ CODE IS literal-1 | identifier-1 ]
~~~~
[ { CONTROL IS } { FINAL }... ]
{ ~~~~~~~ } { ~~~~~ }
{ CONTROLS ARE } { identifier-2 }
~~~~~~~~
[ PAGE [ { LIMIT IS } ] [ { literal-2 } LINES ]
~~~~ { ~~~~~ } { identifier-3 } ~~~~
{ LIMITS ARE }
~~~~~~
[ literal-3 | identifier-4 COLUMNS|COLS ]
~~~~~~~ ~~~~
[ HEADING IS literal-4 | identifier-5 ]
~~~~~~~
[ FIRST DE|DETAIL IS literal-5 | identifier-6 ]
~~~~~ ~~ ~~~~~~
[ LAST CH|{CONTROL HEADING} IS literal-6 | identifier-7 ]
~~~~ ~~ ~~~~~~~ ~~~~~~~
[ LAST DE|DETAIL IS literal-7 | identifier-8 ]
~~~~ ~~ ~~~~~~
[ FOOTING IS literal-8 | identifier-9 ] ] .
~~~~~~~
The "CODE IS" and "COLUMNS" clauses are syntactically recognized but
are otherwise non-functional.
=======================================================================
This section describes the layout of printed reports as well as many of
the functional aspects of the generation of reports that will be
produced via the Report Writer Control System.
1. The reserved words "ARE" and "IS" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. The phrases "CONTROL IS" and "CONTROLS ARE" are interchangeable,
as are the "PAGE LIMIT" and "PAGE LIMITS" phrases.
3. The reserved word "LINES" may be abbreviated as "LINE".
4. The reserved word "COLUMNS" may be abbreviated as "COLS".
5. Each report referenced on a "REPORT IS" clause (*note
File/Sort-Description::) must be described with a report
description ("RD").
6. *Note GLOBAL::, for information on the "GLOBAL" option.
7. Please see *Note Report Writer Features::, if you have not read it
already. This will familiarize you with the Report Writer
terminology that will follow.
8. The following rules pertain to the "PAGE LIMITS" clause:
A. If no "PAGE LIMITS" clause is specified, the entire report
will be generated as if it consists of a single arbitrarily
long page.
B. All literals ( through ) must be
numeric with non-zero positive integer values.
C. All identifiers ( through ) must
be numeric, unedited with non-zero positive integer values.
D. Any value specified for | will
define the total number of available lines on any report
page, not counting any unused margins at the top and/or
bottom of the page (defined by the "LINES AT TOP" and "LINES
AT BOTTOM" values specified on the "LINAGE" clause of the
"FD" this "RD" is linked to -- *note
File/Sort-Description::).
E. Any value specified for | will be
ignored.
F. The "HEADING" clause defines the first line number at which a
report heading or page heading may be presented.
G. The "FIRST DETAIL" clause defines the first line at which a
detail group may be presented.
H. The "LAST CONTROL" HEADING clause defines the last line at
which any line of a control heading may be presented.
I. The "LAST DETAIL" clause defines the last line at which any
line of a detail group may be presented.
J. The "FOOTING" clause defines the last line at which any line
of a control footing group may be presented.
K. The following rules establish default values for the various
"PAGE LIMIT" clauses, assuming there is one:
* "HEADING" -- the default is one (1)
* "FIRST DETAIL" -- the HEADING value is used
* "LAST CONTROL HEADING" -- the value from "LAST DETAIL"
or, if that is absent, the value from "FOOTING" or, if
that too is absent, the value from "PAGE LIMIT"
* "LAST DETAIL" -- the value from "FOOTING" or, if that is
absent, the value from "PAGE LIMIT"
* "FOOTING" -- the value from "LAST DETAIL" or, if that is
absent, the value from "PAGE LIMIT"
L. For the values specified on a "PAGE LIMIT" clause to be
valid, all of the following must be true:
* "HEADING" not > "FIRST DETAIL"
* "FIRST DETAIL" not > "LAST CONTROL HEADING"
* "LAST CONTROL HEADING" not > "LAST DETAIL"
* "LAST DETAIL" not > "FOOTING"
9. The following rules pertain to the "CONTROL" clause:
A. If there is no "CONTROL" clause, the report will contain no
control breaks; this implies that there can be no "CONTROL
HEADING" or "CONTROL FOOTING" report groups defined for this
"RD".
B. Include the reserved word "FINAL" if you want to include a
special control heading before the first detail line is
generated ("CONTROL HEADING FINAL") or after the last detail
line is generated ("CONTROL FOOTING FINAL").
C. If you specify "FINAL", it must be the first control break
named in the "RD".
D. Any specifications included on the "CONTROL"
clause are referencing data names defined in any data
division section except for the report section.
E. There must be a "CONTROL HEADING" and/or "CONTROL FOOTING"
report group defined in the report section for each
.
F. At execution time:
* Each time a "GENERATE" statement (*note GENERATE::) is
executed against a detail report group defined for this
"RD", the RWCS will check the contents of each
data item; whenever an 's
value has changed since the previous GENERATE, a control
break condition will be in effect for that
.
* Once the list of control breaks has been determined, the
"CONTROL FOOTING" for each having a
control break (if any such report group is defined) will
be presented.
* Next, the "CONTROL HEADING" for each
having a control break (if any such report group is
defined) will be presented.
* The "CONTROL FOOTING" and "CONTROL HEADING" report
groups will be presented in the sequence in which they
are listed on the "CONTROL" clause.
* Only after this processing has occurred will the detail
report group specified on the "GENERATE" be presented.
10. Each "RD" will have the following allocated for it:
A. The "PAGE-COUNTER" special register (*note Special
Registers::), which will contain the current report page
number.
* This register will be set to a value of 1 when an
"INITIATE" statement (*note INITIATE::) is executed for
the report and will be incremented by 1 each time the
RWCS starts a new page of the report.
* References to "PAGE-COUNTER" within the report section
will be implicitly qualified with the name of the report
to which the report group referencing the register
belongs.
* References to "PAGE-COUNTER" in the procedure division
must be qualified with the appropriate report name if
there are multiple "RD"s defined.
B. The "LINE-COUNTER" special register, which will contain the
current line number on the current page.
11. The "RD" must be followed by at least one 01-level report group
definition.
* Menu:
* 5.6.1: Report Group Definitions.
* 5.6.2: REPORT SECTION Data Items.
File: gnucobpg.info, Node: Report Group Definitions, Next: REPORT SECTION Data Items, Up: REPORT SECTION
5.6.1. Report Group Definitions
-------------------------------
Report-Group-Definition Syntax
=======================================================================
01 [ identifier-1 ]
[ LINE NUMBER IS { integer-1 [ [ ON NEXT PAGE ] } ]
~~~~ { ~~~~ ~~~~ }
{ +|PLUS integer-1 }
{ ~~~~ }
{ ON NEXT PAGE }
~~~~ ~~~~
[ NEXT GROUP IS { [ +|PLUS ] integer-2 } ]
~~~~ ~~~~~ { ~~~~ }
{ NEXT|{NEXT PAGE}|PAGE }
~~~~ ~~~~ ~~~~ ~~~~
[ TYPE IS { RH|{REPORT HEADING} } ]
~~~~ { ~~ ~~~~~~ ~~~~~~~ }
{ PH|{PAGE HEADING} }
{ ~~ ~~~~ ~~~~~~~ }
{ CH|{CONTROL HEADING} FINAL|identifier-2 }
{ ~~ ~~~~~~~ ~~~~~~~ ~~~~~ }
{ DE|DETAIL }
{ ~~ ~~~~~~ }
{ CF|{CONTROL FOOTING} FINAL|identifier-2 }
{ ~~ ~~~~~~~ ~~~~~~~ ~~~~~ }
{ PF|{PAGE FOOTING} }
{ ~~ ~~~~ ~~~~~~~ }
{ RF|{REPORT FOOTING} }
~~ ~~~~~~ ~~~~~~~
. [ REPORT-SECTION-Data-Item ]...
=======================================================================
The syntax shown here documents how a report group is defined to a
report. This syntax is valid only in the report section, and only then
after an "RD".
1. The reserved words "IS", "NUMBER" and "ON" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. The "RH" and "REPORT HEADING" terms are interchangeable, as are
"PH" and "PAGE HEADING", "CH" and "CONTROL HEADING", "DE" and
"DETAIL", "CF" and "CONTROL FOOTING", "PF" and "PAGE FOOTING" as
well as "RF" and "REPORT FOOTING".
3. The report group being defined will be a part of the most-recently
coded "RD".
4. The "TYPE" (*note TYPE::) clause specifies the type of report
group being defined.
5. The level number used for a report group definition must be 01.
6. The optional specification assigns a name to this
report group so that the group may be referenced either by a
GENERATE statement or on a "USE BEFORE REPORTING".
7. No two report groups in the same report ("RD") may named with the
same . There may, however, be multiple
definitions in different reports. In such
instances, references to must be qualified by the
report name.
8. There may only be one report heading, report footing, final
control heading, final control footing, page heading and page
footing defined per report.
9. Report group declarations must be followed by at least one
<> with a level number in the range
02-49.
10. *Note Data Description Clauses::, for information on the usage of
the various data description clauses.
File: gnucobpg.info, Node: REPORT SECTION Data Items, Prev: Report Group Definitions, Up: REPORT SECTION
5.6.2. REPORT SECTION Data Items
--------------------------------
REPORT-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1 ]
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ COLUMN [ { NUMBER IS } ] [ +|PLUS ] integer-1 ]
~~~ { ~~~~~~ } ~~~~
{ NUMBERS ARE }
~~~~~~~
[ GROUP INDICATE ]
~~~~~ ~~~~~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] } ]
~~~~ { +|PLUS integer-2 ~~~~ ~~~~ }
{ ~~~~ }
{ ON NEXT PAGE }
~~~~ ~~~~
[ OCCURS [ integer-3 TO ] integer-4 TIMES
~~~~~~ ~~
[ DEPENDING ON identifier-2 ]
~~~~~~~~~
[ STEP integer-5 ]
~~~~
[ VARYING identifier-3 FROM { identifier-4 } BY { identifier-5 } ]
~~~~~~~ ~~~~ { integer-6 } ~~ { integer-7 }
[ PICTURE IS picture-string ]
~~~
[ PRESENT WHEN condition-name ]
~~~~~~~ ~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ { SOURCE IS literal-1|identifier-6 [ ROUNDED ] } ]
{ ~~~~~~ ~~~~~~~ }
{ SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ] }
{ ~~~ { literal-2 } { ~~~~~ ~~~~~ } }
{ VALUE IS [ ALL ] literal-3 { UPON identifier-9 } }
~~~~~ ~~~ ~~~~
. [ REPORT-SECTION-Data-Item ]...
=======================================================================
Data item descriptions describing the report lines and fields that make
up the substance of a report group immediately follow the definition of
that group.
1. The reserved words "IS", "NUMBER", "OF", "ON", "RIGHT", "TIMES"
and "WHEN" (BLANK) are optional and may be included, or not, at
the discretion of the programmer. The presence or absence of
these words has no effect upon the program.
2. The reserved word "COLUMN" may be abbreviated as "COL".
3. The reserved word "JUSTIFIED" may be abbreviated as "JUST".
4. The reserved word "PICTURE" may be abbreviated as "PIC".
5. The "SOURCE" (*note SOURCE::), "SUM" (*note SUM::) and "VALUE"
(*note VALUE::) clauses, valid only on an elementary item, are
mutually-exclusive of each other.
6. Group items (those without "PICTURE" clauses) are frequently used
to describe entire lines of a report, while elementary items
(those with a picture clause) are frequently used to describe
specific fields of information on the report. When this coding
convention is being used, group items will have "LINE" (*note
LINE::) clauses and no "COLUMN" (*note COLUMN::) clauses while
elementary items will be specified the other way around.
7. *Note Data Description Clauses::, for information on the usage of
the various data description clauses.
File: gnucobpg.info, Node: SCREEN SECTION, Next: Special Data Items, Up: DATA DIVISION
5.7. SCREEN SECTION
===================
SCREEN-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1 | FILLER ]
~~~~~~
[ AUTO | AUTO-SKIP | AUTOTERMINATE ] [ BELL | BEEP ]
~~~~ ~~~~~~~~~ ~~~~~~~~~~~~~ ~~~~ ~~~~
[ BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1 | identifier-2 ]
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
[ BLANK LINE|SCREEN ] [ ERASE EOL|EOS ]
~~~~~ ~~~~ ~~~~~~ ~~~~~ ~~~ ~~~
[ BLANK WHEN ZERO ] [ JUSTIFIED RIGHT ]
~~~~~ ~~~~ ~~~~
[ BLINK ] [ HIGHLIGHT | LOWLIGHT ] [ REVERSE-VIDEO ]
~~~~~ ~~~~~~~~~ ~~~~~~~~ ~~~~~~~~~~~~~
[ COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ]
~~~ ~~~~
[ FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-3 | identifier-4 ]
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
[ { FROM literal-1 | identifier-5 } ]
{ ~~~~ }
{ TO identifier-5 }
{ ~~ }
{ USING identifier-5 }
{ ~~~~~ }
{ VALUE IS [ ALL ] literal-1 }
~~~~~ ~~~
[ FULL | LENGTH-CHECK ] [ REQUIRED | EMPTY-CHECK ] [ SECURE | NO-ECHO ]
~~~~ ~~~~~~~~~~~~ ~~~~~~~~ ~~~~~~~~~~~ ~~~~~~ ~~~~~~~
[ LEFTLINE ] [ OVERLINE ] [ UNDERLINE ]
~~~~~~~~ ~~~~~~~~ ~~~~~~~~~
[ LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ]
~~~~ ~~~~
[ OCCURS integer-5 TIMES ]
~~~~~~
[ PICTURE IS picture-string ]
~~~
[ PROMPT [ CHARACTER IS literal-2 | identifier-7 ]
~~~~~~ ~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
. [ SCREEN-SECTION-Data-Item ]...
=======================================================================
The screen section describes the screens to be displayed during
terminal/console I-O.
1. The reserved words "CHARACTER" ("SEPARATE" clause), "IS",
"NUMBER", "RIGHT", "TIMES" and "WHEN" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. The reserved word "COLUMN" may be abbreviated as "COL".
3. The reserved word "PICTURE" may be abbreviated as "PIC".
4. The following sets of reserved words are interchangeable:
* "AUTO", "AUTO-SKIP" and "AUTOTERMINATE"
* "BACKGROUND-COLOR" and "BACKGROUND-COLOUR"
* "BELL" and "BEEP"
* "FOREGROUND-COLOR" and "FOREGROUND-COLOUR"
* "FULL" and "LENGTH-CHECK"
* "REQUIRED" and "EMPTY-CHECK"
* "SECURE" and "NO-ECHO"
5. Data items defined in the screen section describe input, output or
combination screen layouts to be used with "ACCEPT
screen-data-item" statement (*note ACCEPT screen-data-item::) or
"DISPLAY screen-data-item" statement (*note DISPLAY
screen-data-item::) statements. These screen layouts may define
the entire available screen area or any subset of it.
6. The term 'available screen area' is a nebulous one in those
environments where command-line shell sessions are invoked within
a graphical user-interface environment, as will be the case on
Windows, OSX and most Unix/Linux systems -- these environments
allow command-line session windows to exist with a variable number
of available screen rows and columns. When you are designing GNU
COBOL screens, you need to do so with an awareness of the logical
screen row/column geometry the program will be executing within.
7. Data items with level numbers 01 (Constants), 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.
8. Without "LINE" (*note LINE::) or "COLUMN" (*note COLUMN::)
clauses, screen section fields will display on the console window
beginning at whatever line/column coordinate is stated or implied
by the "ACCEPT screen-data-item" or "DISPLAY screen-data-item"
statement that presents the screen item. After a field is
presented to the console window, the next field will be presented
immediately following that field.
9. A "LINE" clause explicitly stated in the definition of a screen
section data item will override any "LINE" clause included on the
"ACCEPT screen-data-item" or "DISPLAY screen-data-item" statement
that presents that data item to the screen. The same is true of
"COLUMN" clauses.
10. The Tab and Back-Tab (Shift-Tab on most keyboards) keys will
position the cursor from field to field in the line/column
sequence in which the fields occur on the screen at execution
time, regardless of the sequence in which they were defined in the
screen section.
11. *Note Data Description Clauses::, for information on the usage of
the various data description clauses.
File: gnucobpg.info, Node: Special Data Items, Prev: SCREEN SECTION, Up: DATA DIVISION
5.8. Special Data Items
=======================
* Menu:
* 5.8.1: 01-Level Constants.
* 5.8.2: 66-Level Data Items.
* 5.8.3: 77-Level Data Items.
* 5.8.4: 78-Level Data Items.
* 5.8.5: 88-Level Data Items.
File: gnucobpg.info, Node: 01-Level Constants, Next: 66-Level Data Items, Up: Special Data Items
5.8.1. 01-Level Constants
-------------------------
01-Level-Constant Syntax
=======================================================================
01 constant-name-1 CONSTANT [ IS GLOBAL ]
~~~~~~~~ ~~~~~~
{ AS { literal-1 } } .
{ { { BYTE-LENGTH } OF { identifier-1 } } }
{ { { ~~~~~~~~~~~ } { usage-name } } }
{ { { LENGTH } } }
{ ~~~~~~ }
{ FROM CDF-variable-name-1 }
~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *SCREEN*
The 01-level constant is one of four types of compilation-time
constants that can be declared within a program. The other three types
are ">>DEFINE" CDF directive (*note >>DEFINE::) constants, ">>SET" CDF
directive (*note >>SET::) constants and 78-level constants (*note
78-Level Data Items::).
1. The reserved words "AS", "IS" and "OF" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. *Note GLOBAL::, for information on the "GLOBAL" option.
3. This particular type of constant declaration provides the ability
to determine the length of a data item or the storage size
associated with a particular numeric "USAGE" (*note USAGE::) type
-- something not possible with the other types of constants.
4. Constants defined in this way become undefined once an "END
PROGRAM" or "END FUNCTION" is encountered in the input source.
5. Data descriptions of this form do not actually allocate any
storage -- they merely define a name () that may
be used anywhere a numeric literal ("BYTE-LENGTH" or "LENGTH" options)
or a literal of the same type as may be used.
6. The name may not be referenced on a CDF
directive.
7. Care must be taken that does not duplicate any
other data item name that has been defined in the program as
references to that data item name will refer to the constant and
not the data item. The GNU COBOL compiler will not issue a
warning about this condition.
8. The value specified for may be any "USAGE" that does
not use a "PICTURE" (*note PICTURE::) clause. These would be any
of "BINARY-C-LONG", "BINARY-CHAR", "BINARY-DOUBLE", "BINARY-LONG",
"BINARY-SHORT", "COMP-1" (or "COMPUTATIONAL-1"), "COMP-2" (or
"COMPUTATIONAL-2"), "FLOAT-DECIMAL-16", "FLOAT-DECIMAL-34",
"FLOAT-LONG", "FLOAT-SHORT", "POINTER", or "PROGRAM-POINTER".
9. The "BYTE-LENGTH" clause will produce a numeric value for
identical to that which would be returned by the
"BYTE-LENGTH" intrinsic function executed against
or a data item declared with a "USAGE" of .
10. The "LENGTH" clause will produce a numeric value for
identical to that which would be returned by the
"LENGTH" intrinsic function executed against or a
data item declared with a "USAGE" of .
Here is the listing of a GNU COBOL program that uses 01-level constants
to display the length (in bytes) of the various picture-less usage
types.
IDENTIFICATION DIVISION.
PROGRAM-ID. USAGELengths.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Len-BINARY-C-LONG CONSTANT AS LENGTH OF BINARY-C-LONG.
01 Len-BINARY-CHAR CONSTANT AS LENGTH OF BINARY-CHAR.
01 Len-BINARY-DOUBLE CONSTANT AS LENGTH OF BINARY-DOUBLE.
01 Len-BINARY-LONG CONSTANT AS LENGTH OF BINARY-LONG.
01 Len-BINARY-SHORT CONSTANT AS LENGTH OF BINARY-SHORT.
01 Len-COMP-1 CONSTANT AS LENGTH OF COMP-1.
01 Len-COMP-2 CONSTANT AS LENGTH OF COMP-2.
01 Len-FLOAT-DECIMAL-16 CONSTANT AS LENGTH OF FLOAT-DECIMAL-16.
01 Len-FLOAT-DECIMAL-34 CONSTANT AS LENGTH OF FLOAT-DECIMAL-34.
01 Len-FLOAT-LONG CONSTANT AS LENGTH OF FLOAT-LONG.
01 Len-FLOAT-SHORT CONSTANT AS LENGTH OF FLOAT-SHORT.
01 Len-POINTER CONSTANT AS LENGTH OF POINTER.
01 Len-PROGRAM-POINTER CONSTANT AS LENGTH OF PROGRAM-POINTER.
PROCEDURE DIVISION.
000-Main.
DISPLAY "On this system, with this build of GNU COBOL, the"
DISPLAY "PICTURE-less USAGEs have these lengths (in bytes):"
DISPLAY " "
DISPLAY "BINARY-C-LONG: " Len-BINARY-C-LONG
DISPLAY "BINARY-CHAR: " Len-BINARY-CHAR
DISPLAY "BINARY-DOUBLE: " Len-BINARY-DOUBLE
DISPLAY "BINARY-LONG: " Len-BINARY-LONG
DISPLAY "BINARY-SHORT: " Len-BINARY-SHORT
DISPLAY "COMP-1: " Len-COMP-1
DISPLAY "COMP-2: " Len-COMP-2
DISPLAY "FLOAT-DECIMAL-16: " Len-FLOAT-DECIMAL-16
DISPLAY "FLOAT-DECIMAL-34: " Len-FLOAT-DECIMAL-34
DISPLAY "FLOAT-LONG: " Len-FLOAT-LONG
DISPLAY "FLOAT-SHORT: " Len-FLOAT-SHORT
DISPLAY "POINTER: " Len-POINTER
DISPLAY "PROGRAM-POINTER: " Len-PROGRAM-POINTER
STOP RUN
.
The output of this program, on a Windows 7 system with a 32-bit MinGW
build of GNU COBOL is:
On this system, with this build of GNU COBOL, the
PICTURE-less USAGEs have these lengths (in bytes):
BINARY-C-LONG: 4
BINARY-CHAR: 1
BINARY-DOUBLE: 8
BINARY-LONG: 4
BINARY-SHORT: 2
COMP-1: 4
COMP-2: 8
FLOAT-DECIMAL-16: 8
FLOAT-DECIMAL-34: 16
FLOAT-LONG: 8
FLOAT-SHORT: 4
POINTER: 4
PROGRAM-POINTER: 4
File: gnucobpg.info, Node: 66-Level Data Items, Next: 77-Level Data Items, Prev: 01-Level Constants, Up: Special Data Items
5.8.2. 66-Level Data Items
--------------------------
66-Level-Data-Item Syntax
=======================================================================
66 identifier-1 RENAMES identifier-2 [ THRU|THROUGH identifier-3 ] .
~~~~~~~ ~~~~ ~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*
A 66-level data item regroups previously defined items by specifying
alternative, possibly overlapping, groupings of elementary data items.
1. The reserved words "THRU" and "THROUGH" are interchangeable.
2. A level-66 data item cannot rename a level-66, level-01, level-77,
or level-88 data item.
3. There may be multiple level-66 data items that rename data items
contained within the same 01-level record description.
4. All "RENAMES" entries associated with one logical record must
immediately follow that record's last data description entry.
File: gnucobpg.info, Node: 77-Level Data Items, Next: 78-Level Data Items, Prev: 66-Level Data Items, Up: Special Data Items
5.8.3. 77-Level Data Items
--------------------------
77-Level-Data-Item Syntax
=======================================================================
77 identifier-1 [ IS GLOBAL|EXTERNAL ]
~~~~~~ ~~~~~~~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ VALUE IS [ ALL ] literal-1 ] .
~~~~~ ~~~
The "LEFT" and "RIGHT" (SYNCRONIZED) clauses are syntactically
recognized but are otherwise non-functional.
=======================================================================
This syntax is valid in the following sections:
*WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*
The intent of a 77-level item is to be able to create a stand-alone
elementary data item.
1. The reserved words "CHARACTER", "IS", "RIGHT" (JUSTIFIED) and
"WHEN" are optional and may be included, or not, at the discretion
of the programmer. The presence or absence of these words has no
effect upon the program.
2. The reserved word "JUSTIFIED" may be abbreviated as "JUST", the
reserved word "PICTURE" may be abbreviated as "PIC" and the
reserved words "SYNCRONIZED" and "SYNCRONISED" may be abbreviated
as "SYNC".
3. New programs requiring a stand-alone elementary item should be
coded to use a level number of 01 rather than 77.
4. *Note Data Description Clauses::, for information on the usage of
the various data description clauses.
File: gnucobpg.info, Node: 78-Level Data Items, Next: 88-Level Data Items, Prev: 77-Level Data Items, Up: Special Data Items
5.8.4. 78-Level Data Items
--------------------------
78-Level-Constant Syntax
=======================================================================
78 constant-name-1 VALUE IS literal-1 .
~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *SCREEN*
The 78-level constant is one of four types of compilation-time
constants that can be declared within a program. The other three types
are ">>DEFINE" CDF directive (*note >>DEFINE::) constants, ">>SET" CDF
directive (*note >>SET::) constants and 01-level constants (*note
01-Level Constants::).
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. Constants defined in this way become undefined once an "END
PROGRAM" or "END FUNCTION" is encountered in the input source.
3. Data descriptions of this form do not actually allocate any
storage -- they merely define a name () that may
be used anywhere a literal of the same type as may be
used.
4. The name may not be referenced on a CDF
directive.
5. Care must be taken that does not duplicate any
other data item name that has been defined in the program as
references to that data item name will refer to the constant and
not the data item. The GNU COBOL compiler will not issue a
warning about this condition.
File: gnucobpg.info, Node: 88-Level Data Items, Prev: 78-Level Data Items, Up: Special Data Items
5.8.5. 88-Level Data Items
--------------------------
88-Level-Data-Item Syntax
=======================================================================
88 condition-name-1 { VALUE IS } {literal-1 [ THRU|THROUGH literal-2 ]}...
{ ~~~~~ } ~~~~ ~~~~~~~
{ VALUES ARE }
~~~~~~
[ WHEN SET TO FALSE IS literal-3 ] .
~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *REPORT*, *SCREEN*
Condition names are Boolean (i.e. TRUE / FALSE) data items that receive
their TRUE and FALSE values based upon the values of the non 88-level
data item whose definition they immediately follow.
1. The reserved words "ARE", "IS", "SET" and "TO" are optional and
may be included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. The reserved words "THRU" and "THROUGH" are interchangeable.
3. Condition names are always defined subordinate to another (non
88-level) data item. That data item must be an elementary item.
Whenever the parent data item assumes one of the values specified
on the 88-level item's "VALUE" (*note VALUE::) clause,
will take on the value of TRUE.
4. Condition names do not occupy any storage.
5. The optional "THROUGH" clause allows a range of possible TRUE
values to be specified.
6. Whenever the parent data item assumes any value except one of the
values specified on 's "VALUE" clause,
will take on the value of FALSE.
7. Executing the statement "SET TO TRUE" will
cause 's parent data item to take on the first
value specified on 's "VALUE" clause.
8. Executing the statement "SET TO FALSE" will
cause 's parent data item to take on the value
specified on 's "FALSE" clause. If
does not have a "FALSE" clause, the "SET"
(*note SET::) statement will generate an error message at
compilation time.
9. *Note Condition Names::, for more information.
File: gnucobpg.info, Node: Data Description Clauses, Up: DATA DIVISION
5.9. Data Description Clauses
=============================
* Menu:
* 5.9.1: ANY LENGTH.
* 5.9.2: AUTO.
* 5.9.3: AUTO-SKIP.
* 5.9.4: AUTOTERMINATE.
* 5.9.5: BACKGROUND-COLOR.
* 5.9.6: BASED.
* 5.9.7: BEEP.
* 5.9.8: BELL.
* 5.9.9: BLANK.
* 5.9.10: BLANK WHEN ZERO.
* 5.9.11: BLINK.
* 5.9.12: COLUMN.
* 5.9.13: CONSTANT.
* 5.9.14: EMPTY-CHECK.
* 5.9.15: ERASE.
* 5.9.16: EXTERNAL.
* 5.9.17: FALSE.
* 5.9.18: FOREGROUND-COLOR.
* 5.9.19: FROM.
* 5.9.20: FULL.
* 5.9.21: GLOBAL.
* 5.9.22: GROUP INDICATE.
* 5.9.23: HIGHLIGHT.
* 5.9.24: JUSTIFIED.
* 5.9.25: LEFTLINE.
* 5.9.26: LENGTH-CHECK.
* 5.9.27: LINE.
* 5.9.28: LOWLIGHT.
* 5.9.29: NEXT GROUP.
* 5.9.30: NO-ECHO.
* 5.9.31: OCCURS.
* 5.9.32: OVERLINE.
* 5.9.33: PICTURE.
* 5.9.34: PRESENT WHEN.
* 5.9.35: PROMPT.
* 5.9.36: REDEFINES.
* 5.9.37: RENAMES.
* 5.9.38: REQUIRED.
* 5.9.39: REVERSE-VIDEO.
* 5.9.40: SECURE.
* 5.9.41: SIGN IS.
* 5.9.42: SOURCE.
* 5.9.43: SUM OF.
* 5.9.44: SYNCRONIZED.
* 5.9.45: TO.
* 5.9.46: TYPE.
* 5.9.47: UNDERLINE.
* 5.9.48: USAGE.
* 5.9.49: USING.
* 5.9.50: VALUE.
File: gnucobpg.info, Node: ANY LENGTH, Next: AUTO, Up: Data Description Clauses
5.9.1. ANY LENGTH
-----------------
ANY LENGTH Attribute Syntax
=======================================================================
ANY LENGTH
~~~ ~~~~~~
=======================================================================
This syntax is valid in the following sections:
*LINKAGE*
Data items declared with the "ANY LENGTH" attribute have no fixed
compile-time length. Such items may only be defined in the linkage
section of a subprogram as they may only serve as subroutine argument
descriptions. These items must have a "PICTURE" (*note PICTURE::)
clause that specifies exactly one A, X or 9 symbol.
1. The "ANY LENGTH" and "BASED" (*note BASED::) clauses cannot be
used together in the same data item description.
File: gnucobpg.info, Node: AUTO, Next: AUTO-SKIP, Prev: ANY LENGTH, Up: Data Description Clauses
5.9.2. AUTO
-----------
AUTO Attribute Syntax
=======================================================================
AUTO
~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
A field whose description includes this attribute will cause the cursor
to automatically advance to the next input-enabled field of a screen if
the field is completely filled with input data.
1. The "AUTO", "AUTO-SKIP" (*note AUTO-SKIP::) and "AUTOTERMINATE"
(*note AUTOTERMINATE::) clauses are interchangeable, and may not
be used together in the same data item description.
File: gnucobpg.info, Node: AUTO-SKIP, Next: AUTOTERMINATE, Prev: AUTO, Up: Data Description Clauses
5.9.3. AUTO-SKIP
----------------
AUTO-SKIP Attribute Syntax
=======================================================================
AUTO-SKIP
~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
A field whose description includes this attribute will cause the cursor
to automatically advance to the next input-enabled field of a screen if
the field is completely filled with input data.
1. The "AUTO" (*note AUTO::), "AUTO-SKIP" and "AUTOTERMINATE" (*note
AUTOTERMINATE::) clauses are interchangeable, and may not be used
together in the same data item description.
File: gnucobpg.info, Node: AUTOTERMINATE, Next: BACKGROUND-COLOR, Prev: AUTO-SKIP, Up: Data Description Clauses
5.9.4. AUTOTERMINATE
--------------------
AUTOTERMINATE Attribute Syntax
=======================================================================
AUTOTERMINATE
~~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
A field whose description includes this attribute will cause the cursor
to automatically advance to the next input-enabled field of a screen if
the field is completely filled with input data.
1. The "AUTO" (*note AUTO::), "AUTO-SKIP" (*note AUTO-SKIP::) and
"AUTOTERMINATE" clauses are interchangeable, and may not be used
together in the same data item description.
File: gnucobpg.info, Node: BACKGROUND-COLOR, Next: BASED, Prev: AUTOTERMINATE, Up: Data Description Clauses
5.9.5. BACKGROUND-COLOR
-----------------------
BACKGROUND-COLOR Attribute Syntax
=======================================================================
BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1 | identifier-1
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause is used to specify the screen background color of the
screen data item or the default screen background color of subordinate
items if used on a group item.
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. The reserved words "BACKGROUND-COLOR" and "BACKGROUND-COLOUR" are
interchangeable.
3. You specify colors by number (0-7), or by using the constant names
provided in the "screenio.cpy" copybook (which is provided with
all GNU COBOL source distributions).
4. Colors may also be specified using a numeric non-edited identifier
whose value is in the range 0-7.
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: BASED, Next: BEEP, Prev: BACKGROUND-COLOR, Up: Data Description Clauses
5.9.6. BASED
------------
BASED Attribute Syntax
=======================================================================
BASED
~~~~~
=======================================================================
This syntax is valid in the following sections:
*WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*
Data items declared with "BASED" are allocated no storage at
compilation time. At run-time, the "ALLOCATE" (*note ALLOCATE::) or
"SET ADDRESS" (*note SET ADDRESS::) statements are used to allocate
space for and (optionally) initialize such items.
1. The "BASED" and "ANY LENGTH" (*note ANY LENGTH::) clauses cannot
be used together in the same data item description.
2. The "BASED" clause may only be used on level 01 and level 77 data
items.
File: gnucobpg.info, Node: BEEP, Next: BELL, Prev: BASED, Up: Data Description Clauses
5.9.7. BEEP
-----------
BEEP Attribute Syntax
=======================================================================
BEEP
~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
1. The "BEEP" and "BELL" (*note BELL::) clauses are interchangeable,
and may not be used together in the same data item description.
2. Use this clause to cause an audible tone to occur when the screen
item is DISPLAYed.
File: gnucobpg.info, Node: BELL, Next: BLANK, Prev: BEEP, Up: Data Description Clauses
5.9.8. BELL
-----------
BELL Attribute Syntax
=======================================================================
BELL
~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
1. The "BEEP" (*note BEEP::) and "BELL" clauses are interchangeable,
and may not be used together in the same data item description.
2. Use this clause to cause an audible tone to occur when the screen
item is DISPLAYed.
File: gnucobpg.info, Node: BLANK, Next: BLANK WHEN ZERO, Prev: BELL, Up: Data Description Clauses
5.9.9. BLANK
------------
BLANK Attribute Syntax
=======================================================================
BLANK LINE|SCREEN
~~~~~ ~~~~ ~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause will blank out either the entire screen (BLANK SCREEN) or
just the line upon which data is about to be displayed (BLANK LINE).
1. Blanked-out areas will have their foreground and background colors
set to the attributes of the field containing the "BLANK" clause.
2. This clause is useful when one screen section item is being
displayed over the top of a previously-displayed one.
File: gnucobpg.info, Node: BLANK WHEN ZERO, Next: BLINK, Prev: BLANK, Up: Data Description Clauses
5.9.10. BLANK WHEN ZERO
-----------------------
BLANK-WHEN-ZERO Attribute Syntax
=======================================================================
BLANK WHEN ZERO
~~~~~ ~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *REPORT*, *SCREEN*
This clause will cause that item's value to be automatically
transformed into spaces if a value of 0 is ever MOVEd to the item.
1. The reserved word "WHEN" is optional and may be included, or not,
at the discretion of the programmer. The presence or absence of
this word has no effect upon the program.
2. This clause may only be used on a PIC 9 data item with a "USAGE"
(*note USAGE::) of "DISPLAY".
File: gnucobpg.info, Node: BLINK, Next: COLUMN, Prev: BLANK WHEN ZERO, Up: Data Description Clauses
5.9.11. BLINK
-------------
BLINK Attribute Syntax
=======================================================================
BLINK
~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
The "BLINK" clause modifies the visual appearance of the displayed
field by making the field contents blink.
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: COLUMN, Next: CONSTANT, Prev: BLINK, Up: Data Description Clauses
5.9.12. COLUMN
--------------
COLUMN (REPORT SECTION) Clause Syntax
=======================================================================
COLUMN [ { NUMBER IS } ] [ +|PLUS ] integer-1 ]
~~~ { NUMBERS ARE } ~~~~
=======================================================================
COLUMN (SCREEN SECTION) Clause Syntax
=======================================================================
COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ]
~~~ ~~~~
=======================================================================
This syntax is valid in the following sections:
*REPORT*, *SCREEN*
The "COLUMN" clause provides the means of stating in which column a
field should be presented on the console window (screen section) or a
report (report section).
1. The reserved words "ARE", "IS", "NUMBER" and "NUMBERS" are
optional and may be included, or not, at the discretion of the
programmer. The presence or absence of these words has no effect
upon the program.
2. The reserved word "COLUMN" may be abbreviated as "COL".
3. The line location of a report section or screen section field will
be determined by the "LINE" (*note LINE::) clause.
4. The value of must be 1 or greater.
5. If is used to specify either an absolute or
relative column position, must be defined as a
numeric item of any "USAGE" (*note USAGE::) other than
"COMPUTATIONAL-1" or "COMPUTATIONAL-2", without editing symbols.
The value of at the time the screen data item is
presented must be 1 or greater. Note that a "COMPUTATIONAL-1" or
"COMPUTATIONAL-2" identifier will be accepted by the compiler, but
will produce unpredictable results at run-time.
6. The column coordinate of a field may be stated on an absolute
basis (i.e. "COLUMN 5") or on a relative basis based upon the end
of the previously-presented field (i.e. "COLUMN PLUS 1").
7. The symbol "+" may be used in lieue of the word "PLUS", if
desired; if symbol "+" is used, however, there must be at least
one space separating it from . Failure to include this
space will cause the symbol "+" sign to be simply treated as part
of and will treat the "COLUMN" clause as an absolute
column specification rather than a relative one.
8. Using relative column positioning ("COLUMN PLUS") has slightly
different behavior depending upon the section in which the clause
is used, as follows:
A. When used on a report section data item, "COLUMN PLUS" will
position the start of the new field's value such that there
are blank columns between the end of the previous
field and the beginning of this field.
If a report data item's description includes the "SOURCE"
(*note SOURCE::), "SUM" (*note SUM::) or "VALUE" (*note
VALUE::) clause but has no "COLUMN" clause, "COLUMN PLUS 1"
will be assumed.
B. When used on a screen section data item, "COLUMN PLUS" will
position the new field so that it begins exactly
or characters past the last character of the
previous field. Thus, "COLUMN PLUS 1" will leave no blank
positions between the end of the previous field and the start
of this one.
If a screen data item's description includes the "FROM"
(*note FROM::), "TO" (*note TO::), "USING" (*note USING::) or
"VALUE" (*note VALUE::) clause but has no "COLUMN" clause,
the new screen field will begin at the column coordinate of
the last character of the previous field.
File: gnucobpg.info, Node: CONSTANT, Next: EMPTY-CHECK, Prev: COLUMN, Up: Data Description Clauses
5.9.13. CONSTANT
----------------
CONSTANT Attribute Syntax
=======================================================================
CONSTANT
~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *SCREEN*
This option signifies that the 01-level data item in whose declaration
"CONSTANT" is specified will be treated as a symbolic name for a
literal value, useable wherever a literal of the appropriate type could
be used.
1. The value of a data item defined as a constant cannot be changed
at run-time. In fact, it is not syntactically acceptable to use
such a data item as the destination field of any procedure
division statement that stores a value.
2. *Note 01-Level Constants::, for additional information.
File: gnucobpg.info, Node: EMPTY-CHECK, Next: ERASE, Prev: CONSTANT, Up: Data Description Clauses
5.9.14. EMPTY-CHECK
-------------------
EMPTY-CHECK Attribute Syntax
=======================================================================
EMPTY-CHECK
~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause forces the user to enter data into the field it is
specified on (or into all subordinate input-capable fields if
"EMPTY-CHECK" is specified on a group item).
1. The "EMPTY-CHECK" and "REQUIRED" (*note REQUIRED::) clauses are
interchangeable, and may not be used together in the same data
item description.
2. In order to take effect, the user must first move the cursor into
the field having this clause in its definition.
3. The "ACCEPT screen-data-item" statement (*note ACCEPT
screen-data-item::) will ignore the Enter key and any other
cursor-moving keystrokes that would cause the cursor to move to
another screen item unless data has been entered into the field.
Function keys will still be allowed to terminate the "ACCEPT".
4. In order to be functional, this attribute must be supported by the
underlying 'curses' package your GNU COBOL implementation was
built with. As of this time, the 'PDCurses' package (used for
native Windows or MinGW builds) does not support "EMPTY-CHECK".
File: gnucobpg.info, Node: ERASE, Next: EXTERNAL, Prev: EMPTY-CHECK, Up: Data Description Clauses
5.9.15. ERASE
-------------
ERASE Clause Syntax
=======================================================================
ERASE EOL|EOS
~~~~~ ~~~ ~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
"ERASE" will blank-out screen contents from the location where the
screen data item whose description contains this clause will be
displayed, forward until the end of the screen ("ERASE EOS") or line
("ERASE EOL") prior to displaying the screen data item.
1. Erased areas will have their foreground and background colors set
to the attributes of the field containing the "ERASE" clause.
2. This clause is useful when one screen section item is being
displayed over the top of a previously-displayed one.
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: EXTERNAL, Next: FALSE, Prev: ERASE, Up: Data Description Clauses
5.9.16. EXTERNAL
----------------
EXTERNAL Attribute Syntax
=======================================================================
EXTERNAL
~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*
This clause marks a data item description, "FD" or "SD" *note
File/Sort-Description:: as being sharable with other programs executed
from the same execution thread.
1. By specifying the "EXTERNAL" clause on either an FD or an SD, the
file description is capable of being shared between all programs
executed from the same execution thread, provided an "EXTERNAL"
clause is coded with the file's description in each program
requiring it. This sharing allows the file to be opened, read
and/or written and closed in different programs. This sharing
applies to the record descriptions subordinate to the file
description too.
2. By specifying the "EXTERNAL" clause on the description of a data
item, the data item is capable of being shared between all
programs executed from the same execution thread, provided the
data item is coded (with an "EXTERNAL" clause) in each program
requiring it.
3. The following points apply to the specification of "EXTERNAL" in a
data item's definition:
A. The "EXTERNAL" clause may only be specified at the 77 or 01
level.
B. An "EXTERNAL" item must have a data name and that name cannot
be "FILLER".
C. "EXTERNAL" cannot be combined with "BASED" (*note BASED::),
"GLOBAL" (*note GLOBAL::) or "REDEFINES" (*note
REDEFINES::).
File: gnucobpg.info, Node: FALSE, Next: FOREGROUND-COLOR, Prev: EXTERNAL, Up: Data Description Clauses
5.9.17. FALSE
-------------
FALSE Clause Syntax
=======================================================================
WHEN SET TO FALSE IS literal-1
~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *REPORT*, *SCREEN*
This clause, which may only appear on the definition of a level-88
condition name, is used to specify the value of the data item that
serves as the parent of the level-88 condition name that will force the
condition name to assume a value of FALSE.
1. The reserved words "IS", "SET", "TO" and "WHEN" are optional and
may be included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. *Note 88-Level Data Items::, or *Note Condition Names::, for more
information.
File: gnucobpg.info, Node: FOREGROUND-COLOR, Next: FROM, Prev: FALSE, Up: Data Description Clauses
5.9.18. FOREGROUND-COLOR
------------------------
FOREGROUND-COLOR Attribute Syntax
=======================================================================
FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-1 | identifier-1
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause is used to specify the color of text within a screen data
item or the default text color of subordinate items if used on a group
item.
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. The reserved words "FOREGROUND-COLOR" and "FOREGROUND-COLOUR" are
interchangeable.
3. You specify colors by number (0-7), or by using the constant names
provided in the "screenio.cpy" copybook (which is provided with
all GNU COBOL source distributions).
4. Colors may also be specified using a numeric non-edited identifier
whose value is in the range 0-7.
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: FROM, Next: FULL, Prev: FOREGROUND-COLOR, Up: Data Description Clauses
5.9.19. FROM
------------
FROM Clause Syntax
=======================================================================
FROM literal-1 | identifier-5
~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause is used to specify either the data item a screen section
field is to obtain it's value from when the screen is displayed, or a
literal that will specify the value of that same field.
1. The "FROM", "TO" (*note TO::), "USING" (*note USING::) and "VALUE"
(*note VALUE::) clauses are mutually-exclusive in any screen
section data itsm's definition.
File: gnucobpg.info, Node: FULL, Next: GLOBAL, Prev: FROM, Up: Data Description Clauses
5.9.20. FULL
------------
FULL Attribute Syntax
=======================================================================
FULL
~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
The "FULL" clause forces the user to enter data into the field it is
specified on (or into all subordinate input-capable fields if specified
on a group item) sufficient to fill every character position of the
field.
1. The "FULL" and "LENGTH-CHECK" (*note LENGTH-CHECK::) clauses are
interchangeable, and may not be used together in the same data
item description.
2. In order for this clause to take effect at execution time, the
user must move the cursor into the field having this clause in its
definition.
3. The "ACCEPT screen-data-item" statement (*note ACCEPT
screen-data-item::) will ignore the Enter key and any other
cursor-moving keystrokes that would cause the cursor to move to
another screen item unless the proper amount of data has been
entered into the field. Function keys will still be allowed to
terminate the "ACCEPT", however.
4. In order to be functional, this attribute must be supported by the
underlying 'curses' package your GNU COBOL implementation was
built with. As of this time, the 'PDCurses' package (used for
native Windows or MinGW builds) does not support "FULL".
File: gnucobpg.info, Node: GLOBAL, Next: GROUP INDICATE, Prev: FULL, Up: Data Description Clauses
5.9.21. GLOBAL
--------------
GLOBAL Attribute Syntax
=======================================================================
GLOBAL
~~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *REPORT*
This clause marks a data item, 01-level constant, "FD" (*note
File/Sort-Description::), "SD" (*note File/Sort-Description::) or an
"RD" (*note REPORT SECTION::) as being sharable with any nested
subprograms.
1. By specifying the "GLOBAL" clause on the description of a file or
a report, that description is capable of being shared between a
program and any nested subprograms within it, provided the "FD",
"SD" or "RD" is coded (with a "GLOBAL" clause) in each nested
subprogram requiring it. This sharing allows the file to be
opened, read and/or written and closed or the report to be
initiated or terminated in those programs. Separately compiled
programs may not share a "GLOBAL" file description, but they may
share an "EXTERNAL" (*note EXTERNAL::) file description. This
sharing applies to the record descriptions subordinate to the file
description and the report groups subordinate to the "RD" also.
2. By specifying the "GLOBAL" clause on the description of a data
item, the data item is capable of being shared between a program
and any nested subprograms within it, provided the data item is
coded (with a "GLOBAL" clause) in each program requiring it.
3. The following points apply to the specification of "GLOBAL" in a
data item's definition:
A. The "GLOBAL" clause may only be specified at the 77 or 01
level.
B. A "GLOBAL" item must have a data name and that name cannot be
"FILLER".
C. "GLOBAL" cannot be combined with "EXTERNAL" (*note
EXTERNAL::), "REDEFINES" (*note REDEFINES::) or "BASED"
(*note BASED::).
File: gnucobpg.info, Node: GROUP INDICATE, Next: HIGHLIGHT, Prev: GLOBAL, Up: Data Description Clauses
5.9.22. GROUP INDICATE
----------------------
GROUP-INDICATE Attribute Syntax
=======================================================================
GROUP INDICATE
~~~~~ ~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*REPORT*
The "GROUP INDICATE" clause specifies that the data item in whose
definition the clause appears will be presented only in very limited
circumstances.
1. This clause may only appear within a "DETAIL" report group (*note
TYPE::).
2. When this clause is present, the data item in question will be
presented only under the following circumstances:
A. On the first presentation of the detail group following the
"INITIATE" (*note INITIATE::) of the report.
B. On the first presentation of the detail group after every new
page is started.
C. On the first presentation of the detail group after any
control break occurs.
File: gnucobpg.info, Node: HIGHLIGHT, Next: JUSTIFIED, Prev: GROUP INDICATE, Up: Data Description Clauses
5.9.23. HIGHLIGHT
-----------------
HIGHLIGHT Attribute Syntax
=======================================================================
HIGHLIGHT
~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause controls the intensity of text ("FOREGROUND-COLOR" (*note
FOREGROUND-COLOR::)) by setting that intensity to its highest of three
possible settings.
1. This clause, along with "LOWLIGHT" (*note LOWLIGHT::), are
intended to provide a three-level intensity scheme ("LOWLIGHT" ...
nothing (Normal) ... "HIGHLIGHT").
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: JUSTIFIED, Next: LEFTLINE, Prev: HIGHLIGHT, Up: Data Description Clauses
5.9.24. JUSTIFIED
-----------------
JUSTIFIED Attribute Syntax
=======================================================================
JUSTIFIED RIGHT
~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *REPORT*, *SCREEN*
The presence of a "JUSTIFIED RIGHT" clause in a data item's definition
alters the manner in which data is stored into the field from the
default 'left-justified, space filled' behavior to 'right justified,
space filled'.
1. The reserved word "RIGHT" is optional and may be included, or not,
at the discretion of the programmer. The presence or absence of
this word has no effect upon the program.
2. The reserved word "JUSTIFIED" may be abbreviated as "JUST".
3. This clause is valid only on alphabetic (PIC A) or alphanumeric
(PIC X) data items.
4. The presence or absence of this clause influences the behavior of
the "MOVE" (*note MOVE::) statement as well as the "FROM" (*note
FROM::), "SOURCE" (*note SOURCE::) and "USING" (*note USING::)
data item description clauses.
5. If the value being stored into the field is the same length as the
receiving field, the presence or absence of the "JUSTIFIED RIGHT"
clause on that field's description is irrelevant.
6. The following examples illustrate the behavior of the presence and
absence of the "JUSTIFIED RIGHT" clause when the field size is
different than that of the value being stored. In these examples,
the symbol b represents a space.
When the value is shorter than the field size...
Without JUSTIFIED With JUSTIFIED
----------------------------------------------------------------------
01 A PIC X(6). 01 A PIC X(6) JUSTIFIED RIGHT.
MOVE "ABC" TO A MOVE "ABC" TO A
Result is 'ABCbbb' Result is 'bbbABC'
When the value is longer than the field size...
Without JUSTIFIED With JUSTIFIED
----------------------------------------------------------------------
01 A PIC X(6). 01 A PIC X(6) JUSTIFIED RIGHT.
MOVE "ABCDEFGHI" TO A MOVE "ABCDEFGHI" TO A
Result is 'ABCDEF' Result is 'DEFGHI'
File: gnucobpg.info, Node: LEFTLINE, Next: LENGTH-CHECK, Prev: JUSTIFIED, Up: Data Description Clauses
5.9.25. LEFTLINE
----------------
LEFTLINE Attribute Syntax
=======================================================================
LEFTLINE
~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
The "LEFTLINE" clause will introduce a vertical line at the left edge
of a screen field.
1. The "LEFTLINE", "OVERLINE" (*note OVERLINE::) and "UNDERLINE"
(*note UNDERLINE::) clauses may be used in any combination in a
single field's description.
2. This clause is essentially non-functional when used within Windows
command shell (cmd.exe) environments and running programs compiled
using a GNU COBOL implementation built using 'PDCurses' (such as
Windows/MinGW builds).
3. Whether or not this clause operates on Cygwin or UNIX/Linux/OSX
systems will depend upon the video attribute capabilities of the
terminal output drivers and 'curses' software being used.
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: LENGTH-CHECK, Next: LINE, Prev: LEFTLINE, Up: Data Description Clauses
5.9.26. LENGTH-CHECK
--------------------
LENGTH-CHECK Attribute Syntax
=======================================================================
LENGTH-CHECK
~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
The "LENGTH-CHECK" clause forces the user to enter data into the field
it is specified on (or into all subordinate input-capable fields if
specified on a group item) sufficient to fill every character position
of the field.
1. The "FULL" (*note FULL::) and "LENGTH-CHECK" clauses are
interchangeable, and may not be used together in the same data
item description.
2. In order for this clause to take effect at execution time, the
user must move the cursor into the field having this clause in its
definition.
3. The "ACCEPT screen-data-item" statement (*note ACCEPT
screen-data-item::) will ignore the Enter key and any other
cursor-moving keystrokes that would cause the cursor to move to
another screen item unless the proper amount of data has been
entered into the field. Function keys will still be allowed to
terminate the "ACCEPT", however.
4. In order to be functional, this attribute must be supported by the
underlying 'curses' package your GNU COBOL implementation was
built with. As of this time, the 'PDCurses' package (used for
native Windows or MinGW builds) does not support "LENGTH-CHECK".
File: gnucobpg.info, Node: LINE, Next: LOWLIGHT, Prev: LENGTH-CHECK, Up: Data Description Clauses
5.9.27. LINE
------------
LINE (REPORT SECTION) Clause Syntax
=======================================================================
LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] }
~~~~ { ~~~~ ~~~~ }
{ +|PLUS integer-2 }
{ ~~~~ }
{ ON NEXT PAGE }
~~~~ ~~~~
=======================================================================
LINE (SCREEN SECTION) Clause Syntax
=======================================================================
[ LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ]
~~~~ ~~~~
=======================================================================
This syntax is valid in the following sections:
*REPORT*, *SCREEN*
This clause provides a means of explicitly stating on which line a
field should be presented on the console window (screen section) or on
a report (report section).
1. The reserved words "IS", "NUMBER" and "ON" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. The following points document the use of format 1 of the "LINE"
clause:
A. The column location of a report item will be determined by
the "COLUMN" (*note COLUMN::) clause.
B. The value of must be 1 or greater.
C. The report line number upon which the data item containing
this clause along with any subordinate data items will be
presented may be stated on an absolute basis (i.e. "LINE 5")
or on a relative basis based upon the previously-displayed
line (i.e. "LINE PLUS 1").
D. The symbol "+" may be used in lieue of the word "PLUS", if
desired; if "+" is used, however, there must be at least one
space separating it from . Failure to include
this space will cause the "+" to be simply treated as part of
and will treat the LINE clause as an absolute
line specification rather than a relative one.
E. The optional "NEXT PAGE" clause specifies that -- regardless
of whether or not the report group containing this clause
could fit on the report page being currently generated, the
report group will be forced to appear on a new page.
3. The following points document the use for format 2 of the "LINE"
clause:
A. The column location of a screen section field is determined
by the "COLUMN" (*note COLUMN::) clause.
B. The value of must be 1 or greater.
C. If is used to specify either an absolute or
relative column position, must be defined as a
numeric item of any "USAGE" (*note USAGE::) other than
"COMPUTATIONAL-1" or "COMPUTATIONAL-2", without editing
symbols. The value of at the time the screen
data item is presented must be 1 or greater. Note that a
"COMPUTATIONAL-1" or "COMPUTATIONAL-2" identifier will be
accepted by the compiler, but will produce unpredictable
results at run-time.
D. The screen line number upon which the data item containing
this clause along with any subordinate data items will be
displayed may be stated on an absolute basis (i.e. "LINE 5")
or on a relative basis based upon the previously-displayed
line (i.e. "LINE PLUS 1").
E. The symbol "+" may be used in lieue of the word "PLUS", if
desired; if "+" is used, however, there must be at least one
space separating it from . Failure to include
this space will cause the "+" to be simply treated as part of
and will treat the "LINE" clause as an absolute
line specification rather than a relative one.
F. If a screen data item's description includes the "FROM"
(*note FROM::), "TO" (*note TO::), "USING" (*note USING::) or
"VALUE" (*note VALUE::) clause but has no LINE clause, the
"current screen line" will be assumed.
File: gnucobpg.info, Node: LOWLIGHT, Next: NEXT GROUP, Prev: LINE, Up: Data Description Clauses
5.9.28. LOWLIGHT
----------------
LOWLIGHT Attribute Syntax
=======================================================================
LOWLIGHT
~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
The "LOWLIGHT" clause controls the intensity of text
("FOREGROUND-COLOR") by setting that intensity to its lowest of three
possible settings.
1. This clause, along with "HIGHLIGHT" (*note HIGHLIGHT::), are
intended to provide a three-level intensity scheme ("LOWLIGHT" ...
nothing (Normal) ... "HIGHLIGHT"). In environments such as a
Windows console where only two levels of intensity are supported,
"LOWLIGHT" is the same as leaving this clause off altogether.
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: NEXT GROUP, Next: NO-ECHO, Prev: LOWLIGHT, Up: Data Description Clauses
5.9.29. NEXT GROUP
------------------
NEXT-GROUP Clause Syntax
=======================================================================
NEXT GROUP IS { [ +|PLUS ] integer-2 }
~~~~ ~~~~~ { ~~~~ }
{ NEXT|{NEXT PAGE}|PAGE }
~~~~ ~~~~ ~~~~ ~~~~
=======================================================================
This syntax is valid in the following sections:
*REPORT*
This clause defines any rules for where the next group to be presented
on a report will begin, line-wise, with respect to the last line of the
group in which this clause appears.
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. The terms "NEXT", "NEXT PAGE" and "PAGE" are interchangeable.
3. A report group must contain at least one "LINE NUMBER" clause in
order to also contain a "NEXT GROUP" clause.
4. If the "RD" (*note REPORT SECTION::) in which the report group
containing a "NEXT GROUP" clause does not contain a "PAGE LIMITS"
clause, only the "PLUS integer-1" option may be specified.
5. The "NEXT PAGE" option cannot be used in a "PAGE FOOTING".
6. The "NEXT GROUP" option cannot be specified in either a "REPORT
HEADING" or a "PAGE HEADING".
7. The effects of "NEXT GROUP" will be in addition to any line
spacing defined by the next-presented group's "LINE NUMBER"
clause.
File: gnucobpg.info, Node: NO-ECHO, Next: OCCURS, Prev: NEXT GROUP, Up: Data Description Clauses
5.9.30. NO-ECHO
---------------
NO-ECHO Attribute Syntax
=======================================================================
NO-ECHO
~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
The "NO-ECHO" clause will cause all data entered into the field to
appear on the screen as asterisks.
1. The "NO-ECHO" and "SECURE" (*note SECURE::) clauses are
interchangeable, and may not be used together in the same data
item description.
2. This clause may only be used on a field allowing data entry (a
field containing either the "USING" (*note USING::) or "TO" (*note
TO::) clause).
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: OCCURS, Next: OVERLINE, Prev: NO-ECHO, Up: Data Description Clauses
5.9.31. OCCURS
--------------
OCCURS (REPORT SECTION) Clause Syntax
=======================================================================
OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~
[ DEPENDING ON identifier-1 ]
~~~~~~~~~
[ STEP integer-3 ]
~~~~
[ VARYING identifier-2 FROM { identifier-3 } BY { identifier-4 } ]
~~~~~~~ ~~~~ { integer-4 } ~~ { integer-5 }
=======================================================================
OCCURS (SCREEN SECTION) Clause Syntax
=======================================================================
OCCURS integer-2 TIMES
~~~~~~
=======================================================================
OCCURS (All Other Sections Clause Syntax
=======================================================================
OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~
[ DEPENDING ON identifier-1 ]
~~~~~~~~~
[ ASCENDING|DESCENDING KEY IS identifier-5... ]...
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY identifier-6 ]
~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *REPORT*, *SCREEN*
The "OCCURS" clause is used to create a data structure called a table,
where entries in that structure repeat multiple times.
1. The reserved words "BY" (INDEXED), "IS", "KEY", "ON" and "TIMES"
are optional and may be included, or not, at the discretion of the
programmer. The presence or absence of these words has no effect
upon the program.
2. The value of specifies how many entries will be
allocated in the table.
3. The following is an example of how a table might be defined:
05 QUARTERLY-REVENUE OCCURS 4 TIMES PIC 9(7)V99.
This will allocate the following:
QUARTERLY-REVENUE(1)
QUARTERLY-REVENUE(2)
QUARTERLY-REVENUE(3)
QUARTERLY-REVENUE(4)
Each occurrence is referenced using the subscript syntax (a
numeric literal, arithmetic expression or numeric identifier
enclosed within parenthesis) shown above.
4. The "OCCURS" clause may be used at the group level too, in which
case the entire group structure repeats, as follows:
05 GRP OCCURS 3 TIMES.
10 A PIC X(1).
10 B PIC X(1).
10 C PIC X(1).
This would allow references to any of the following:
GRP(1) - includes A(1), B(1) and C(1)
GRP(2) - includes A(2), B(2) and C(2)
GRP(3) - includes A(3), B(3) and C(3)
or each A,B,C item could be referenced as follows:
A(1) - Character #1 of GRP(1)
B(1) - Character #2 of GRP(1)
C(1) - Character #3 of GRP(1)
A(2) - Character #1 of GRP(2)
B(2) - Character #2 of GRP(2)
C(2) - Character #3 of GRP(2)
A(3) - Character #1 of GRP(3)
B(3) - Character #2 of GRP(3)
C(3) - Character #3 of GRP(3)
5. The optional "DEPENDING ON" clause can be added to an "OCCURS" to
create a variable-length table. In such cases, the value of
specifies what the minimum number of entries in the
table will be while specifies the maximum. Such
tables will be allocated out to the maximum size specified as
. At execution time the value of will
determine how many of the table elements are accessible.
6. See the documentation of the "SEARCH" (*note SEARCH::), "SEARCH
ALL" (*note SEARCH ALL::) and "SORT" (*note SORT::) statements for
explanations of the "KEY" and "INDEXED BY" clauses.
7. The "OCCURS" clause cannot be specified in a data description
entry that has a level number of 01, 66, 77, or 88, although it is
valid in data items described subordinate to an 01-level data
item.
8. The following points apply to an "OCCURS" used in the report
section:
A. The optional "STEP" clause defines an incrementation value
that will be added to any absolute "LINE" (*note LINE::) or
"COLUMN" (*note COLUMN::) number specifications that may be
part of or subordinate to this data item's definition.
B. The optional "VARYING" clause defines an identifier that may
be used as a subscript for the multiple occurrences of this
or any subordinate data item should the "SOURCE" (*note
SOURCE::) or "SUM" (*note SUM::) clause(s) on this or
subordinate data items reference entries within the table.
The data item is dynamically created as needed
and cannot be referenced outside the scope of the report data
item definition.
C. The following two examples illustrate two different ways a
report could include four quarters worth of sales figures in
it's detail lines -- one doing things 'the hard way' and one
using the advanced "OCCURS" capabilities of "STEP" and
"VARYING". Both assume the definition of the following table
exists in working-storage:
05 SALES OCCURS 4 TIMES PIC 9(7)V99.
First, the "Hard Way":
10 COL 7 PIC $(7)9.99 SOURCE SALES(1).
10 COL 17 PIC $(7)9.99 SOURCE SALES(2).
10 COL 27 PIC $(7)9.99 SOURCE SALES(3).
10 COL 37 PIC $(7)9.99 SOURCE SALES(4).
And then using "STEP" and "VARYING":
10 COL 7 OCCURS 4 TIMES STEP 10 VARYING QTR FROM 1 BY 1
PIC $(7)9.99 SOURCE SALES(QTR).
File: gnucobpg.info, Node: OVERLINE, Next: PICTURE, Prev: OCCURS, Up: Data Description Clauses
5.9.32. OVERLINE
----------------
OVERLINE Attribute Syntax
=======================================================================
OVERLINE
~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
The "OVERLINE" clause will introduce a horizontal line at the top edge
of a screen field.
1. The "LEFTLINE" (*note LEFTLINE::), "OVERLINE" and "UNDERLINE"
(*note UNDERLINE::) clauses may be used in any combination in a
single field's description.
2. This clause is essentially non-functional when used within Windows
command shell (cmd.exe) environments and running programs compiled
using a GNU COBOL implementation built using 'PDCurses' (such as
Windows/MinGW builds).
3. Whether or not this clause operates on Cygwin or UNIX/Linux/OSX
systems will depend upon the video attribute capabilities of the
terminal output drivers and 'curses' software being used.
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: PICTURE, Next: PRESENT WHEN, Prev: OVERLINE, Up: Data Description Clauses
5.9.33. PICTURE
---------------
PICTURE Clause Syntax
=======================================================================
PICTURE IS picture-string
~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *REPORT*, *SCREEN*
The picture clause defines the class (numeric, alphabetic or
alphanumeric), size and format of the data that may be contained by the
data item being defined. Sometimes this role is assisted by the
"USAGE" (*note USAGE::) clause, and in a few instances will be assumed
entirely by that clause.
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. The reserved word "PICTURE" may be abbreviated as "PIC". Most
programmers prefer to use the latter.
3. A picture clause may only be specified on an elementary item.
4. A is a sequence of the special symbols "$", "*",
"+", ",", "-", ".", "/", "0" (zero), "9", "A", "B", "CR", "DB",
"S", "V", "X" and "Z".
5. In general, each picture symbol represents either a single
character in storage or a single decimal digit. There are a few
exceptions, and they will be discussed as needed.
6. When a contains a repeated sequence of symbols --
"PIC 9999/99/99" -- for example, the repetition can be specified
using a parenthetic repeat count, as in "PIC 9(4)/9(2)/9(2)".
Using repeat counts is optional and their use (or not) is entirely
at the discretion of the programmer. Many programmers use
repetition for small sequences ("PIC XXX") and repeat counts for
larger ones ("PIC 9(9)".
7. This first set of picture symbols defines the basic data type of a
data item. Each symbol represents a single character's worth of
storage.
"A"
Defines storage reserved for a single alphabetic character
("A"-"Z", "a"-"z").
"N"
Defines storage reserved for a single character in the
computer's 'National Characterset'. Support for national
charactersets in GNU COBOL is currently only partially
implemented, and the compile- and run-time effect of using
the "N" picture symbol is the same as if "X(2)" had been
coded, with the additional effect that such a field will
qualify as a "NATIONAL" or "NATIONAL-EDITED" field on an
"INITIALIZE" (*note INITIALIZE::) statement.
"X"
Defines storage reserved for a single alphanumeric character
(any character).
"9"
Defines storage reserved for a single numeric digit character
("0"-"9").
Typically, only one kind of each of those symbols is used in the
same picture clause, but that isn't a requirement. Data items
that, of the three symbols above, use nothing but "A" picture
symbols are known as 'Alphabetic Data Items' while those that use
"9" picture symbols without any "A" or "X" symbols (or those that
have a "USAGE" without a "PICTURE") are known as 'Numeric Data
Items'. All other data items are referred to as 'Alphanumeric
Data Items'.
If you need to allocate space for a data item whose format is two
letters followed by five digits followed by three letters, you
could use the "AA99999AAA", "A(2)9(5)A(3)"
"XXXXXXXXXX" or "X(10)". There is absolutely no functional
difference whatsoever between the four -- none of them provide any
functionality the others do not. The first two probably make for
better documentation of the expected field contents, but they
don't provide any run-time enforcement capabilities.
As far as enforcement goes, however, both alphabetic and numeric
picture strings do provide for both compile-time and run-time
enforcement capabilities. In the case of compilation enforcement,
the compiler can issue warning messages if you attempt to specify
a non-numeric value for a numeric data item or if you attempt to
"MOVE" (*note MOVE::) a non-numeric data item to one that is
numeric. Similar capabilities exist for alphabetic data items.
At run-time, you may use a special class test (*note Class
Conditions::) to determine if the contents of a data item are
entirely numeric or entirely alphabetic.
8. The following picture symbols may be used with numeric data
items.
"P"
Defines an implied digit position that will be considered to
be a zero when the data item is referenced at run-time. This
symbol is used to allow data items that will contain very
large values to be allocated using less storage by assuming a
certain number of trailing zeros (one per "P") to exist at
the end of values.
The "P" symbol is not allowed in conjunction with "N".
The "P" symbol may only be used at the beginning or end of a
picture clause.
"P" is a repeatable symbol.
All computations and "MOVE" (*note MOVE::) operations
involving such a data item will behave as if the zeros were
actually there.
For example, let's say you need to allocate a data item that
contains however many millions of dollars of revenue your
company has in gross revenues this year:
01 Gross-Revenue PIC 9(9).
In which case 9 characters 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 are always going to be 0), you
could define the field as:
01 Gross-Revenue PIC 9(3)P(6).
Whenever Gross-Revenue is referenced in calculations, or
whenever its value is moved to another data item, the value
of Gross-Revenue will be treated as if it is nnn000000, where
'nnn' is the actual value in storage.
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
A "DISPLAY" (*note DISPLAY::) of a data item containing "P"
symbols is a little strange. The value displayed will be
what is actually in storage, but the total size of the
displayed value will be as if the "P" symbols had been "9"s.
Thus, after the above statement established a value for
Gross-Revenue, a "DISPLAY Gross-Revenue" would produce output
of '000000128'.
"S"
This symbol, if used, must be the very first symbol in the
"PICTURE" value. A "S" indicates that the data item is
"Signed", meaning that negative values are possible for this
data item. Without an "S", any negative values stored into
this data item via a "MOVE" or arithmetic statement will have
the negative sign stripped from it (in effect becoming the
absolute value).
The "S" symbol is not allowed in conjunction with "N".
The "S" symbol may only occur once in a picture string.
*Note SIGN IS::, for further discussion of how negative
values may be stored in a numeric data item.
"V"
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 "V" symbol is not allowed in conjunction with "N".
The "V" symbol may only occur once in a picture string.
9. Any editing symbols introduced past this point will, if coded in
the picture clause of an otherwise numeric data item, transform
that data item from a numeric to a 'Numeric Edited' data item.
Numeric edited data items are treated as alphanumeric and may not
serve either as table subscripts or as source arguments on an
arithmetic statement.
10. The following are the fixed insertion editing symbols that may be
specified in a picture string. Each of these editing symbols will
insert a special character into the field value at the position it
is specified in the picture string. These editing symbols will
each introduce one extra character into the total field size for
each occurrence of the symbol in the picture string.
"B"
The "B" editing symbol introduces a blank into the field
value for each occurrence.
Multiple "B" symbols may be coded.
The following example will format a ten digit number
(presumably a telephone number) into a "### ### ####"
layout:
...
05 Phone-Number PIC 9(3)B9(3)B9(4).
...
MOVE 5185551212 TO Phone-Number
DISPLAY Phone-Number
This code will display "518 555 1212".
"0"
The "0" (zero) editing symbol introduces one "0" character
into the field value for each occurrence in the picture
string.
Multiple "0" symbols may be coded.
Here's an example:
...
05 Output-Item PIC 909090909.
...
MOVE 12345 TO Output-Item
DISPLAY Output-Item
The above will display "102030405".
"/"
The "/" editing symbol inserts one "/" character into the
field value for each occurrence in the picture string.
Multiple "/" symbols may be coded.
This editing symbol is most-frequently used to format dates,
as follows:
...
05 Year-Month-Day PIC 9(4)/9(2)/9(2).
...
MOVE 20140207 TO Year-Month-Day
DISPLAY Year-Month-Day
This example displays "2014/02/07".
11. The following are the numeric formatting symbols that may be
specified in a picture string. Each of these editing symbols will
insert special characters into the field value to present numbers
in a "friendly" format. These editing symbols will each introduce
one extra character into the total field size for each occurrence
of the symbol in the picture string. Numeric fields whose picture
clause contains these characters may neither be used as source
fields in any calculation nor may they serve as source fields for
the transfer of data values to any data item other than an
alphanumeric field.
"."
The "." symbol inserts a decimal point into a numeric field
value. When the contents of a numeric data item sending
field are moved into a receiving data item whose picture
clause contains the "." editing symbol, implied ("V") or
actual decimal point in the sending data item or literal,
respectively, will be aligned with the "." symbol in the
receiving field. Digits are then transferred from the
sending to the receiving field outward from the sending
field's "V" or ".", truncating sending digits if there aren't
enough positions in the receiving field. Any digit positions
in the receiving field that don't receive digits from the
sending field, if any, will be set to 0.
The "." symbol is not allowed in conjunction with "N".
An example will probably help:
...
05 Source-Field PIC 9(2)V9 VALUE 7.2.
05 Dest-Field PIC 9(5).9(2).
...
MOVE 1234567.89 TO Dest-Field
DISPLAY Dest-Field
MOVE 19 TO Dest-Field
DISPLAY Dest-Field
MOVE Source-Field TO Dest-Field
DISPLAY Dest-Field
The example will display three results -- "34567.89",
"00019.00" and "00007.20".
Both data item definitions appear to have two decimal points
in their picture clauses. They actually don't, because the
last character of every data item definition is always a
period -- the period that ends the definition.
","
The "," symbol serves as a thousands separator. Many times,
you'll see large numbers formatted with these symbols -- for
example, 123,456,789. This can be accomplished easily by
adding thousands separator symbols to a picture string.
Thousands separator symbols that aren't needed will behave as
if they were "9"s.
The "," symbol is not allowed in conjunction with "N".
Here's an example:
...
05 My-Lottery-Winnings PIC 9(3),9(3),9(3).
...
MOVE 12345 TO My-Lottery-Winnings
DISPLAY My-Lottery-Winnings
The value "0000012,345" (a very disappointing one for my
retirement plans, but a good thousands separator demo) will
be displayed. Notice how, since the first comma wasn't
needed due to the meager amount I won, it behaved like
another "9".
If desired, you may reverse the roles of the "." and "," editing
symbols by specifying "DECIMAL POINT IS COMMA" in the
"SPECIAL-NAMES" (*note SPECIAL-NAMES::) paragraph.
12. The following are insertion symbols. They are used to insert an
extra character (two in the case of "CR" and "DB") to signify the
sign (positive or negative) of the numeric value that is moved
into the field whose picture string contains one of these symbols,
or the fact that the data item represents a currency (money)
amount. Only one of the "+", "-", "CR" or "DB" symbols may be
used in a picture clause. In this context, when any of these
symbols are used in a , they must be at the end.
The "+", "-" and/or currency symbols may also be used as floating
editing symbols at the beginning of the -- a
subject that will be covered in the next numbered paragraph.
"+"
If the value of the numeric value moved into the field is
positive (0 or greater), a "+" character will be inserted.
If the value is negative (less than 0), a "-" character is
inserted.
The "+" symbol is not allowed in conjunction with "N".
"-"
If the value of the numeric value moved into the field is
positive (0 or greater), a space will be inserted. If the
value is negative (less than 0), a "-" character is
inserted.
The "-" symbol is not allowed in conjunction with "N".
"CR"
This symbol is coded as the two characters "C" and "R". If
the value of the numeric value moved into the field is
positive (0 or greater), two spaces will be inserted. If the
value is negative (less than 0), the characters "CR" (credit)
are inserted.
The "CR" symbol is not allowed in conjunction with "N".
"DB"
This symbol is coded as the two characters "D" and "B". If
the value of the numeric value moved into the field is
positive (0 or greater), two spaces will be inserted. If the
value is negative (less than 0), the characters "DB" (debit)
are inserted.
The "DB" symbol is not allowed in conjunction with "N".
"$"
Regardless of the value moved into the field, this symbol
will insert the currency symbol into the data item's value in
the position where it occurs in the (*note
SPECIAL-NAMES::).
The "$" symbol is not allowed in conjunction with "N".
13. These editing symbols are known as floating replacement symbols.
These symbols may occur in sequences before any "9" editing
symbols in the of a numeric data item. Using
these symbols transforms that numeric data item into a numerid
edited data item, which can no longer be used in calculations or
subscripts.
14. Each of the following symbols behave like a "9", until such point
as all digits in the numeric value are exhausted and leading zeros
are about to be inserted. In effect, these editing symbols define
what should happen to those leading zero.
"$"
Of those currency symbols that correspond to character
positions in which leading zeros reside, the right-most will
have its "0" value replaced by the currency symbol in-effect
for the program (*note SPECIAL-NAMES::). Any remaining
leading zero values occupying positions described by this
symbol will be replaced by spaces.
The "$" symbol is not allowed in conjunction with "N".
Any currency symbol coded to the right of a "." will be
treated exactly like a "9".
"*"
This symbol is referred to as a check protection symbol. All
check-protection symbols that correspond to character
positions in which leading zeros reside will have their "0"
values replaced by "*".
The "*" symbol is not allowed in conjunction with "N".
Any check-suppression symbol coded to the right of a "." will
be treated exactly like a "9".
"+"
Of those "+" symbols that correspond to character positions
in which leading zeros reside, the right-most will have its
"0" value replaced by a "+" if the value in the data item is
zero or greater or a "-" otherwise. Any remaining leading
zero values occupying positions described by this symbol will
be replaced by spaces. You cannot use both "+" and "-" in
the same .
The "+" symbol is not allowed in conjunction with "N".
Any "+" symbol coded to the right of a "." will be treated
exactly like a "9".
"-"
Of those "-" symbols that correspond to character positions
in which leading zeros reside, the right-most will have its
"0" value replaced by a space if the value in the data item
is zero or greater or a "-" otherwise. Any remaining leading
zero values occupying positions described by this symbol will
be replaced by spaces. You cannot use both "+" and "-" in
the same .
The "-" symbol is not allowed in conjunction with "N".
Any "-" symbol coded to the right of a "." will be treated
exactly like a "9".
"Z"
All "Z" symbols that correspond to character positions in
which leading zeros reside will have their "0" values
replaced by spaces.
Any zero-suppression symbol coded to the right of a "." will
be treated exactly like a "9".
"Z" and "*" should not be coded in the same
"+" and "-" should not be coded in the same
When multiple floating symbols are coded, even if there is only
one of them used they will all be considered floating and will all
be able to assume each other's properties. For example, if a data
item has a "PIC +$ZZZZ9.99" , and a value of 1 is
moved to that field at run-time, the resulting value will be (the
b symbol represents a space) "bbbb+$1.00". This is not consistent
with many other COBOL implementations, where the result would have
been "+$bbbb1.00".
Most other COBOL implementations reject the use of multiple
occurrences of multiple floating editing symbols. For example,
they would reject s such as "+++$$$9.99",
"$$$ZZZ9.99" and so on. GNU COBOL accepts these. Programmers
creating GNU COBOL programs should avoid such s if
there is any liklihood that those programs may be used with other
COBOL implementations.
File: gnucobpg.info, Node: PRESENT WHEN, Next: PROMPT, Prev: PICTURE, Up: Data Description Clauses
5.9.34. PRESENT WHEN
--------------------
PRESENT-WHEN Clause Syntax
=======================================================================
PRESENT WHEN condition-name
~~~~~~~ ~~~~
=======================================================================
This syntax is valid in the following sections:
*REPORT*
This clause names an existing "Condition Name" (*note Condition
Names::) that will serve as a switch controlling the presentation or
suppression of a report group.
1. If the specified condition-name has a value of FALSE when a
"GENERATE" statement (*note GENERATE::) causes a report group to
be presented, the presentation of that group will be suppressed.
2. If the condition-name has a value of TRUE, the group will be
presented.
3. *Note Condition Names::, for more information.
File: gnucobpg.info, Node: PROMPT, Next: REDEFINES, Prev: PRESENT WHEN, Up: Data Description Clauses
5.9.35. PROMPT
--------------
PROMPT Clause Syntax
=======================================================================
PROMPT [ CHARACTER IS literal-1 | identifier-1 ]
~~~~~~ ~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause defines the character that will be used as the
fill-character for any input fields on the screen.
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. The default prompt character, should no "CHARACTER" specification
be coded, or should the "PROMPT" clause be absent altogether, is
an underscore ("_").
3. Prompt characters will be automatically transformed into spaces
upon input.
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: REDEFINES, Next: RENAMES, Prev: PROMPT, Up: Data Description Clauses
5.9.36. REDEFINES
-----------------
REDEFINES Clause Syntax
=======================================================================
REDEFINES identifier-1
~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*
The "REDEFINES" clause causes the data item in who's definition the
"REDEFINES" clause is specified (hereafter referred to as the redefines
object) to occupy the same physical storage space as
(hereafter referred to as the redefines subject).
1. The following rules must all be followed in order to use
REDEFINES:
A. The level number of both the subject and object data items
must be the same.
B. The level numbers of both the subject and object data items
cannot be 66, 78 or 88.
C. If "n" represents the level number of the object, then no
other data items with level number "n" may be defined between
the subject and object data items unless they too are
"REDEFINES" of the subject.
D. If "n" represents the level number of the object, then no
other data items with a level number numerically less than
"n" may be defined between the subject and object data
items.
E. The total allocated size of the subject data item must be the
same as the total allocated size of the object data item.
F. No "OCCURS" (*note OCCURS::) clause may be part of the
definition of either the subject or object data items.
Either or both, however, may be group items that contain data
items with "OCCURS" clauses.
G. No "VALUE" (*note VALUE::) clause may be defined on the
object data item, and no data items subordinate to the object
data item may have "VALUE" clauses, with the exception of
level-88 condition names.
File: gnucobpg.info, Node: RENAMES, Next: REQUIRED, Prev: REDEFINES, Up: Data Description Clauses
5.9.37. RENAMES
---------------
RENAMES Clause Syntax
=======================================================================
RENAMES identifier-1 [ THRU|THROUGH identifier-2
~~~~~~~ ~~~~ ~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*
The "RENAMES" clause regroups previously defined items by specifying
alternative, possibly overlapping, groupings of elementary data items.
1. The reserved words "THRU" and "THROUGH" are interchangeable.
2. You must use the level number 66 for data description entries that
contain the "RENAMES" clause.
3. The and data items, along with all
data items defined between those two data items in the program
source, must all be contained within the same 01-level record
description.
4. *Note 66-Level Data Items::, for additional information on the
RENAMES clause.
File: gnucobpg.info, Node: REQUIRED, Next: REVERSE-VIDEO, Prev: RENAMES, Up: Data Description Clauses
5.9.38. REQUIRED
----------------
REQUIRED Attribute Syntax
=======================================================================
REQUIRED
~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause forces the user to enter data into the field it is
specified on (or into all subordinate input-capable fields if
"REQUIRED" is specified on a group item).
1. The "EMPTY-CHECK" (*note EMPTY-CHECK::) and "REQUIRED" clauses are
interchangeable, and may not be used together in the same data
item description.
2. In order to take effect, the user must first move the cursor into
the field having this clause in its definition.
3. The "ACCEPT screen-data-item" statement (*note ACCEPT
screen-data-item::) will ignore the Enter key and any other
cursor-moving keystrokes that would cause the cursor to move to
another screen item unless data has been entered into the field.
Function keys will still be allowed to terminate the "ACCEPT".
4. In order to be functional, this attribute must be supported by the
underlying 'curses' package your GNU COBOL implementation was
built with. As of this time, the 'PDCurses' package (used for
native Windows or MinGW builds) does not support "REQUIRED".
File: gnucobpg.info, Node: REVERSE-VIDEO, Next: SECURE, Prev: REQUIRED, Up: Data Description Clauses
5.9.39. REVERSE-VIDEO
---------------------
REVERSE-VIDEO Attribute Syntax
=======================================================================
REVERSE-VIDEO
~~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
The "REVERSE-VIDEO" attribute swaps the specified or implied
"FOREGROUND-COLOR" (*note FOREGROUND-COLOR::) and "BACKGROUND-COLOR"
(*note BACKGROUND-COLOR::) attributes for the field whose definition
contains this clause (or all subordinate fields if used on a group
item).
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: SECURE, Next: SIGN IS, Prev: REVERSE-VIDEO, Up: Data Description Clauses
5.9.40. SECURE
--------------
SECURE Attribute Syntax
=======================================================================
SECURE
~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause will cause all data entered into the field to appear on the
screen as asterisks.
1. The "NO-ECHO" (*note NO-ECHO::) and "SECURE" clauses are
interchangeable, and may not be used together in the same data
item description.
2. This clause may only be used on a field allowing data entry (a
field containing either the "USING" (*note USING::) or "TO" (*note
TO::) clause).
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: SIGN IS, Next: SOURCE, Prev: SECURE, Up: Data Description Clauses
5.9.41. SIGN IS
---------------
SIGN-IS Clause Syntax
=======================================================================
SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *REPORT*, *SCREEN*
This clause, allowable only for "USAGE DISPLAY" numeric data items,
specifies how an "S" symbol will be interpreted in a data item's
picture clause.
1. The reserved words "CHARACTER" and "IS" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. Without the "SEPARATE CHARACTER" option, the sign of the data
item's value will be encoded by transforming the last ("TRAILING")
or first ("LEADING") digit as follows:
First/Last Digit Value For Value for
Positive Negative
------------------------------------------------------
0 0 p
1 1 q
2 2 r
3 3 s
4 4 t
5 5 u
6 6 v
7 7 w
8 8 x
9 9 y
3. If the "SEPARATE CHARACTER" clause is used, then an actual "+" or
"-" character will be inserted into the field's value as the first
("LEADING") or last ("TRAILING") character. Note that having this
character imbedded within the data item's storage does not prevent
the data item from being used as a source field in arithmetic
operations.
4. When "SEPARATE CHARACTER" is specified, the "S" symbol in the data
item's "PICTURE" must be counted when determining the data item's
size.
5. Neither the presence of an encoded digit (see above) nor an actual
"+" or "-" character imbedded within the data item's storage
prevents the data item from being used as a source field in
arithmetic operations.
File: gnucobpg.info, Node: SOURCE, Next: SUM OF, Prev: SIGN IS, Up: Data Description Clauses
5.9.42. SOURCE
--------------
SOURCE Clause Syntax
=======================================================================
SOURCE IS literal-1 | identifier-1 [ ROUNDED ]
~~~~~~ ~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*REPORT*
This clause logically attaches a report section data item to another
data item defined elsewhere in the data division.
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. When the report group containing this clause is presented, the
value of the specified numeric literal or identifier will be
automatically moved to the report data item prior to
presentation.
3. The specified identifier may be defined anywhere in the data
division, but if it is defined in the report section it may only
be "PAGE-COUNTER", "LINE-COUNTER" or a "SUM" (*note SUM::)
counter.
4. The "PICTURE" (*note PICTURE::) of the report data item must be
such that it would be legal to "MOVE" (*note MOVE::) the specified
literal or identifier to a data item with that "PICTURE".
5. The "ROUNDED" option comes into play should the number of digits
to the right of an actual or assumed decimal point be different
between the specified literal or identifier value (the "source
value") and the "PICTURE" specified for the field in whose
definition the "SOURCE" clause appears (the "target field").
Without "ROUNDED", excess digits in the source value will simply
be truncated to fit the target field. With "ROUNDED", the source
value will be arithmetically rounded to fit the target field.
*Note ROUNDED::, for information on the "NEAREST-AWAY-FROM-ZERO"
rounding rule, which is the one that will apply.
File: gnucobpg.info, Node: SUM OF, Next: SYNCRONIZED, Prev: SOURCE, Up: Data Description Clauses
5.9.43. SUM OF
--------------
SUM-OF Clause Syntax
=======================================================================
SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ]
~~~ { literal-2 } { ~~~~~ ~~~~~ }
{ UPON identifier-9 }
~~~~
=======================================================================
This syntax is valid in the following sections:
*REPORT*
The "SUM" clause establishes a summation counter whose value will be
arithmetically calculated whenever the field is presented.
1. The reserved words "OF" and "ON" are optional and may be included,
or not, at the discretion of the programmer. The presence or
absence of these words has no effect upon the program.
2. The "SUM" clause may only appear in a "CONTROL FOOTING" report
group.
3. If the data item in which the "SUM" clause appears has been
assigned it's own identifier name, and that name is not "FILLER",
then that data item is referred to as a sum counter.
4. All data items must be non-edited numeric in
nature.
5. If any data item is defined in the report section,
it must be a sum counter.
6. Any data items that are sum counters must either be
defined in the same report group as the data item in which this
"SUM" clause appears or they must be defined in a report data item
that exists at a lower level in this report's control hierarchy.
*Note Control Hierarchy::, for additional information.
7. The "PICTURE" of the report data item in who's description this
"SUM" clause appears in must be such that it would be legal to
"MOVE" (*note MOVE::) the specified or
value to a data item with that "PICTURE".
8. The following points apply to the "UPON" option:
A. The data item must be the name of a detail
group specified in the same report as the control footing
group in which this "SUM" clause appears.
B. The presence of an "UPON" clause limits the "SUM" clause to
adding the specified numeric literal or identifier value into
the sum counter only when a "GENERATE "
statement is executed.
C. If there is no "UPON" clause specified, the value of
or will be added into the sum
counter whenever a "GENERATE" (*note GENERATE::) of any
detail report group in the report is executed.
D. If there is only a single detail group in the report's
definition, the "UPON" clause is meaningless.
9. The following points apply to the "RESET" option:
A. If the "RESET" option is coded, "FINAL" or
(whichever is coded on the "RESET") must be one of the
report's control breaks specified on the "CONTROLS" clause.
B. If there is no "RESET" option coded, the sum counter will be
reset back to zero after each time the control footing
containing the "SUM" clause is presented. This is the
typical behavior that would be expected.
C. If, however, you want to reset the "SUM" counter only when
the control footing for a control break higher in the control
hierarchy is presented, specify that higher control break on
the "RESET" option.
File: gnucobpg.info, Node: SYNCRONIZED, Next: TO, Prev: SUM OF, Up: Data Description Clauses
5.9.44. SYNCRONIZED
-------------------
SYNCRONIZED Syntax
=======================================================================
SYNCRONIZED|SYNCHRONISED [ LEFT|RIGHT ]
~~~~ ~~~~ ~~~~ ~~~~~
The "LEFT" and "RIGHT" (SYNCRONIZED) clauses are syntactically
recognized but are otherwise non-functional.
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*
This optional clause optimizes the storage of binary numeric items to
store them in such a manner as to make it as fast as possible for the
CPU to fetch them.
1. The reserved words "SYNCRONIZED" and "SYNCHRONISED" are
interchangeable, and may be abbreviated as "SYNC".
2. If the "SYNCRONIZED" clause is coded on anything but a numeric
data item with a "USAGE" (*note USAGE::) that specifies storage of
data in a binary form, the "SYNCRONIZED" clause will be ignored.
3. Synchronization is performed (by the compiler) 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.
File: gnucobpg.info, Node: TO, Next: TYPE, Prev: SYNCRONIZED, Up: Data Description Clauses
5.9.45. TO
----------
TO Clause Syntax
=======================================================================
TO identifier-5
~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause logically attaches a screen section data item to another
data item defined elsewhere in the data division.
1. The "TO" clause is used to define a data-entry field with no
initial value; when a value is entered, it will be saved to the
specified identifier.
2. The "FROM" (*note FROM::), "TO", "USING" (*note USING::) and
"VALUE" (*note VALUE::) clauses are mutually-exclusive in any
screen section data itsm's definition.
File: gnucobpg.info, Node: TYPE, Next: UNDERLINE, Prev: TO, Up: Data Description Clauses
5.9.46. TYPE
------------
TYPE Clause Syntax
=======================================================================
[ TYPE IS { RH|{REPORT HEADING} } ]
~~~~ { ~~ ~~~~~~ ~~~~~~~ }
{ PH|{PAGE HEADING} }
{ ~~ ~~~~ ~~~~~~~ }
{ CH|{CONTROL HEADING} FINAL|identifier-2 }
{ ~~ ~~~~~~~ ~~~~~~~ ~~~~~ }
{ DE|DETAIL }
{ ~~ ~~~~~~ }
{ CF|{CONTROL FOOTING} FINAL|identifier-2 }
{ ~~ ~~~~~~~ ~~~~~~~ ~~~~~ }
{ PF|{PAGE FOOTING} }
{ ~~ ~~~~ ~~~~~~~ }
{ RF|{REPORT FOOTING} }
~~ ~~~~~~ ~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*REPORT*
This clause defines the type of report group that is being defined for
a report.
1. This clause is required on any 01-level data item definitions
(other than 01-level constants) in the report section. This
clause is invalid on any other report section data item
definitions.
2. There may be a maximum of one (1) report group per "RD" defined
with a "TYPE" of "REPORT HEADING", "PAGE HEADING", "PAGE FOOTING"
and "REPORT FOOTING".
3. There must be either a "CONTROL HEADING" or a "CONTROL FOOTING" or
both specified for each entry specified on the "CONTROLS ARE"
clause of the "RD".
4. The various report groups that constitute a report may be defined
in any order.
5. *Note RWCS Lexicon::, for a description of the seven different
types of report groups.
File: gnucobpg.info, Node: UNDERLINE, Next: USAGE, Prev: TYPE, Up: Data Description Clauses
5.9.47. UNDERLINE
-----------------
UNDERLINE Attribute Syntax
=======================================================================
UNDERLINE
~~~~~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
The "UNDERLINE" clause will introduce a horizontal line at the bottom
edge of a screen field.
1. The "LEFTLINE" (*note LEFTLINE::), "OVERLINE" (*note OVERLINE::)
and "UNDERLINE" clauses may be used in any combination in a single
field's description.
2. This clause is essentially non-functional when used within Windows
command shell (cmd.exe) environments and running programs compiled
using a GNU COBOL implementation built using 'PDCurses' (such as
Windows/MinGW builds).
3. Whether or not this clause operates on Cygwin or UNIX/Linux/OSX
systems will depend upon the video attribute capabilities of the
terminal output drivers and 'curses' software being used.
*Note Color Palette and Video Attributes::, for more information on
screen colors and video attributes.
File: gnucobpg.info, Node: USAGE, Next: USING, Prev: UNDERLINE, Up: Data Description Clauses
5.9.48. USAGE
-------------
USAGE Clause Syntax
=======================================================================
USAGE IS data-item-usage
~~~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *REPORT*
The "USAGE" clause defines the format that will be used to store the
value of a data item.
1. The reserved word "IS" is optional and may be included, or not, at
the discretion of the programmer. The presence or absence of this
word has no effect upon the program.
2. The following table summarizes the various USAGE specifications
available in GNU COBOL.
BINARY
~~~~~~
Range of Values: Defined by the quantity of "9"s and
the presence or absence of an "S" in
the "PICTURE"
Storage Format: Compatible Binary Integer
Negative Values Allowed?: If "PICTURE" contains "S"
"PICTURE" Used?: Yes
BINARY-C-LONG [ SIGNED ]
~~~~~~~~~~~~~
Same as "BINARY-DOUBLE SIGNED"
BINARY-C-LONG UNSIGNED
~~~~~~~~~~~~~ ~~~~~~~~
Range of Values: Typically 0 to 4,294,967,295
Storage Format: Native Binary Integer
Negative Values Allowed?: No
"PICTURE" Used?: No
BINARY-CHAR [ SIGNED ]
~~~~~~~~~~~
Range of Values: -128 to 127
Storage Format: Native Binary Integer
Negative Values Allowed?: Yes
"PICTURE" Used?: No
BINARY-CHAR UNSIGNED
~~~~~~~~~~~ ~~~~~~~~
Range of Values: 0 to 255
Storage Format: Native Binary Integer
Negative Values Allowed?: No
"PICTURE" Used?: No
BINARY-DOUBLE [ SIGNED ]
~~~~~~~~~~~~~
Range of Values: -9,223,372,036,854,775,808 to
9,223,372,036,854,775,807
Storage Format: Native Binary Integer
Negative Values Allowed?: Yes
"PICTURE" Used?: No
BINARY-DOUBLE UNSIGNED
~~~~~~~~~~~~~ ~~~~~~~~
Range of Values: 0 to 18,446,744,073,709,551,615
Storage Format: Native Binary Integer
Negative Values Allowed?: No
"PICTURE" Used?: No
BINARY-INT
~~~~~~~~~~
Same as "BINARY-LONG SIGNED"
BINARY-LONG [ SIGNED ]
~~~~~~~~~~~
Range of Values: -2,147,483,648 – 2,147,483,647
Storage Format: Native Binary Integer
Negative Values Allowed?: Yes
"PICTURE" Used?: No
BINARY-LONG UNSIGNED
~~~~~~~~~~~ ~~~~~~~~
Range of Values: 0 to 4,294,967,295
Storage Format: Native Binary Integer
Negative Values Allowed?: No
"PICTURE" Used?: No
BINARY-LONG-LONG
~~~~~~~~~~~~~~~~
Same as "BINARY-DOUBLE SIGNED"
BINARY-SHORT [ SIGNED ]
~~~~~~~~~~~~
Range of Values: -32,768 to 32,767
Storage Format: Native Binary Integer
Negative Values Allowed?: Yes
"PICTURE" Used?: No
BINARY-SHORT UNSIGNED
~~~~~~~~~~~~ ~~~~~~~~
Range of Values: 0 to 65,535
Storage Format: Native Binary Integer
Negative Values Allowed?: No
"PICTURE" Used?: No
COMPUTATIONAL
~~~~
Same as "BINARY"
COMP[UTATIONAL]-1
~~~~ ~~
Same as "FLOAT-SHORT"
COMP[UTATIONAL]-2
~~~~ ~~
Same as "FLOAT-LONG"
COMP[UTATIONAL]-3
~~~~ ~~
Same as "PACKED-DECIMAL"
COMP[UTATIONAL]-4
~~~~ ~~
Same as "BINARY"
COMP[UTATIONAL]-5
~~~~ ~~
Range of Values: Depends on number of "9"s in the
"PICTURE" and the "binary-size"
setting of the configuration file
used to compile the program
Storage Format: Native Binary Integer
Negative Values Allowed?: If "PICTURE" contains "S"
"PICTURE" Used?: Yes
COMP[UTATIONAL]-6
~~~~ ~~
Range of Values: Defined by the quantity of "9"s and
the presence or absence of an "S" in
the "PICTURE"
Storage Format: Unsigned Packed Decimal
Negative Values Allowed?: No
"PICTURE" Used?: Yes
COMP[UTATIONAL]-X
~~~~ ~~
Range of Values: If used with "PIC X", allocates one
byte of storage per "X"; range of
values is 0 to max storable in that
many bytes. If used with "PIC 9",
range of values depends on number of
"9"s in PICTURE
Storage Format: Native unsigned (X) or signed (9)
Binary
Negative Values Allowed?: If "PICTURE" 9 and contains "S"
"PICTURE" Used?: Yes
DISPLAY
~~~~~~~
Range of Values: Depends on "PICTURE" – One character
per X, A, 9, period, $, Z, 0, *, S
(if "SEPARATE CHARACTER" specified),
+, - or B symbol in "PICTURE"; Add 2
more bytes if the "DB" or "CR"
editing symbol is used
Storage Format: Characters
Negative Values Allowed?: If "PICTURE" contains "S"
"PICTURE" Used?: Yes
FLOAT-DECIMAL-16
~~~~~~~~~~~~~~~~
Range of Values: 9.999999999999999×10^384 to
9.999999999999999×10^384
Storage Format: Native IEEE 754 Decimal64
Floating-point
Negative Values Allowed?: Yes
"PICTURE" Used?: No
FLOAT-DECIMAL-34
~~~~~~~~~~~~~~~~
Range of Values: -9.99999...×10^6144 to
9.99999...×10^6144
Storage Format: Native IEEE 754 Decimal128
Floating-point
Negative Values Allowed?: Yes
"PICTURE" Used?: No
FLOAT-LONG
~~~~~~~~~~
Range of Values: Approximately
-1.797693134862316×10^308 to
1.797693134862316×10^308
Storage Format: Native IEEE 754 Binary64
Floating-point
Negative Values Allowed?: Yes
"PICTURE" Used?: No
FLOAT-SHORT
~~~~~~~~~~~
Range of Values: Approximately -3.4028235×10^38 to
3.4028235×10^38
Storage Format: Native IEEE 754 Binary32
Negative Values Allowed?: Yes
"PICTURE" Used?: No
INDEX
~~~~~
Range of Values: 0 to maximum address possible (32 or
64 bits)
Storage Format: Native Binary Integer
Negative Values Allowed?: No
"PICTURE" Used?: No
NATIONAL
~~~~~~~~
"USAGE NATIONAL", while syntactically recognized, is not
supported by GNU COBOL
PACKED-DECIMAL
~~~~~~~~~~~~~~
Range of Values: Defined by the quantity of "9"s and
the presence or absence of an "S" in
the PICTURE
Storage Format: Signed Packed Decimal
Negative Values Allowed?: If "PICTURE" contains "S"
"PICTURE" Used?: No
POINTER
~~~~~~~
Range of Values: 0 to maximum address possible (32 or
64 bits)
Storage Format: Native Binary Integer
Negative Values Allowed?: No
"PICTURE" Used?: No
PROCEDURE-POINTER
~~~~~~~~~~~~~~~~~
Same as "PROGRAM-POINTER"
PROGRAM-POINTER
~~~~~~~~~~~~~~~
Range of Values: 0 to maximum address possible (32 or
64 bits)
Storage Format: Native Binary Integer
Negative Values Allowed?: No
"PICTURE" Used?: No
SIGNED-INT
~~~~~~~~~~
Same as "BINARY-LONG SIGNED"
SIGNED-LONG
~~~~~~~~~~~
Same as "BINARY-DOUBLE SIGNED"
SIGNED-SHORT
~~~~~~~~~~~~
Same as "BINARY-SHORT SIGNED"
UNSIGNED-INT
~~~~~~~~~~~~
Same as "BINARY-LONG UNSIGNED"
UNSIGNED-LONG
~~~~~~~~~~~~~
Same as "BINARY-DOUBLE UNSIGNED"
UNSIGNED-SHORT
~~~~~~~~~~~~~~
Same as "BINARY-SHORT UNSIGNED"
3. Binary data (integer or floating-point) 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 least-significant 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 least-significant 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 binary storage across
computer systems.
Some CPUs – such as the Intel/AMD i386/x64 architecture processors
used in most Windows PCs – prefer to process binary data stored in
a little-endian format. Since that format is more efficient on
those systems, it is referred to as the "native" binary format.
On a system supporting only one format of binary storage
(generally, that would be big-endian), the terms 'most-efficient'
and 'native format' are synonymous.
4. Data items that have the "UNSIGNED" attribute explicitly coded, or
"DISPLAY", "PACKED-DECIMAL", "COMP-5", "COMP-X" items that do not
have an "S" symbol in their picture clause cannot preserve
negative values that may be stored into them. Storing a negative
value into such a field will actually result in the sign being
stripped, essentially saving the absolute value in the data item.
5. Packed-decimal (i.e. "USAGE PACKED-DECIMAL", "USAGE COMP-3" or
"USAGE COMP-6") data is stored as a series of bytes such that each
byte contains two 4-bit fields, referred to as 'nibbles' (since
they comprise half a "byte", they're just "nibbles" -- don't
groan, I don't just make this stuff up!). Each nibble represents
a "9" in the "PICTURE" and each holds a single decimal digit
encoded as its binary value (0 = 0000, 1 = 0001, ... , 9 = 1001).
The last byte of a "PACKED-DECIMAL" or "COMP-3" data item will
always have its left nibble corresponding to the last "9" in the
"PICTURE" and its right nibble reserved as a sign indicator. This
sign indicator is always present regardless of whether or not the
"PICTURE" included an "S" symbol.
The first byte of the data item will contain an unused left nibble
if the "PICTURE" had an even number of "9" symbols in it.
The sign indicator will have a value of a hexadecimal A thru F.
Traditional packed decimal encoding rules call for hecadecimal
values of F, A, C or E ("FACE") in the sign nibble to indicate a
positive value and B or D to represent a negative value
(hexadecimal digits 0-9 are undefined). Testing with a Windows
MinGW/GNU COBOL implementation shows that -– in fact -– hex digit
D represents a negative number and any other hexadecimal digit
denotes a positive number. Therefore, a "PIC S9(3) COMP-3"
packed-decimal field with a value of -15 would be stored
internally as a hexadecimal 015D in GNU COBOL.
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.
"USAGE COMP-6" does not allow for negative values, therefore no
sign nibble will be allocated. A "USAGE COMP-6" data item
containing an odd number of "9" symbols in its "PICTURE" will
leave its leftmost nibble unused.
6. The "USAGE" specifications "FLOAT-DECIMAL-16" and
"FLOAT-DECIMAL-34" will encode data using IEEE 754 "Decimal64" and
"Decimal128" format, respectively. The former allows for up to 16
digits of exact precision while the latter offers 34. The phrase
"exact precision" is used because the traditional binary
renderings of decimal real numbers in a floating-point format
("FLOAT-LONG" and "FLOAT-SHORT", for example) only yield an
approximation of the actual value because many decimal fractions
cannot be precisely rendered in binary. The Decimal64 and
Decimal128 renderings, however, render decimal real numbers in
encoded decimal form in much the same way that "PACKED-DECIMAL"
renders a decimal integer in digit-by-digit decimal form. The
exact manner in which this rendering is performed is complex
(Wikipedia has an excellent article on the subject – just search
for "Decimal64").
7. GNU COBOL stores "FLOAT-DECIMAL-16" and "FLOAT-DECIMAL-34" data
items using either Big-Endian or Little-Endian form, whichever is
native to the system.
8. The "USAGE" specifications "FLOAT-LONG" and "FLOAT-SHORT" use the
IEEE 754 "Binary64" and "Binary32" formats, respectively. These
are binary encodings of real decimal numbers, and as such cannot
represent every possible value between the minimum and maximum
values in the range for those usages. Wikipedia has an excellent
article on the Binary64 and Binary32 encoding schemes – just
search on "Binary32" or "Binary64".
GNU COBOL stores "FLOAT-LONG" and "FLOAT-SHORT" data items using
either Big-Endian or Little-Endian form, whichever is native to
the system.
9. A "USAGE" clause specified at the group item level will apply that
"USAGE" to all subordinate data items, except those that
themselves have a "USAGE" clause.
10. The only "USAGE" that is allowed in the report section is "USAGE
DISPLAY".
File: gnucobpg.info, Node: USING, Next: VALUE, Prev: USAGE, Up: Data Description Clauses
5.9.49. USING
-------------
USING Clause Syntax
=======================================================================
USING identifier-1
~~~~~
=======================================================================
This syntax is valid in the following sections:
*SCREEN*
This clause logically attaches a screen section data item to another
data item defined elsewhere in the data division.
1. When the screen item whose definition this clause is part of is
displayed, the value currently in will be
automatically moved into the screen item first.
2. When the screen item whose definition this clause is part of (or
its parent) is accepted, the current contents of the screen item
will be saved back to at the conclusion of the
"ACCEPT".
3. The "FROM" (*note FROM::), "TO" (*note TO::), "USING" and "VALUE"
(*note VALUE::) clauses are mutually-exclusive in any screen
section data itsm's definition.
File: gnucobpg.info, Node: VALUE, Prev: USING, Up: Data Description Clauses
5.9.50. VALUE
-------------
VALUE (Condition Names) Clause Syntax
=======================================================================
{ VALUE IS } {literal-1 [ THRU|THROUGH literal-2 ]}...
{ ~~~~~ } ~~~~ ~~~~~~~
{ VALUES ARE }
~~~~~~
=======================================================================
VALUE (Other Data Items) Syntax
=======================================================================
VALUE IS [ ALL ] literal-1
~~~~~ ~~~
=======================================================================
This syntax is valid in the following sections:
*FILE*, *WORKING-STORAGE*, *LOCAL-STORAGE*, *LINKAGE*, *REPORT*, *SCREEN*
The "VALUE" clause is used to define condition names or to assign
values (at compilation time) to data items.
1. The reserved words "ARE" and "IS" are optional and may be
included, or not, at the discretion of the programmer. The
presence or absence of these words has no effect upon the
program.
2. This clause cannot be specified on the same data item as a "FROM"
(*note FROM::), "TO" (*note TO::) or "USING" (*note USING::)
clause.
3. The following points apply to using the "VALUE" clause in the
definition of a condition name:
A. The clauses "VALUE IS" and "VALUES ARE" are interchangeable.
B. The reserved words "THRU" and "THROUGH" are interchangeable.
C. *Note 88-Level Data Items::, for a discussion of how this
format of "VALUE" is used to create condition names.
D. *Note Condition Names::, for a discussion of how condition
names are used.
4. The following points apply to using the "VALUE" clause in the
definition of any other data item:
A. In this context, "VALUE" specifies an initial
compilation-time value that will be assigned to the storage
occupied by the data item in the program object code
generated by the compiler.
B. The "VALUE" clause is ignored on "EXTERNAL" (*note
EXTERNAL::) data items or on any data items defines as
subordinate to an "EXTERNAL" data item.
C. This format of the "VALUE" clause may not be used anywhere in
the description of an 01 item (or any of it's subordinate
items) serving as an "FD" or "SD" record description.
D. If the optional "ALL" clause is used, it may only be used
with an alphanumeric literal value; the value will be
repeated as needed to completely fill the data item. Here
are some examples with and without "ALL" (the symbol b
denotes a space):
PIC X(5) VALUE "A" *> Abbbb
PIC X(5) VALUE ALL "A" *> AAAAA
PIC 9(3) VALUE 1 *> 001
PIC 9(3) VALUE ALL "1" *> 111
E. When used in the definition of a screen data item:
a. A figurative constant may not be supplied as
.
b. Any "FROM" (*note FROM::), "TO" (*note TO::) or "USING"
(*note USING::) clause in the same data item's
definition will be ignored.
c. If there is no picture clause specified, the size of the
screen data item will be the length of the
value.
d. If there is no picture clause and the "ALL" option is
specified, the "ALL" option will be ignored.
F. Giving a table an initial, compile-time value 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 GNU
COBOL may find interesting. So, here are the three standard
approaches:
a. Don't bother worrying about it at compile-time. Use the
"INITIALIZE" (*note INITIALIZE::) 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:
05 SHIRT-SIZES VALUE "S 14M 15L 16XL17".
10 SHIRT-SIZE-TBL OCCURS 4 TIMES.
15 SST-SIZE PIC X(2).
15 SST-NECK PIC 9(2).
c. Initialize tables of almost any size at compilation time
by utilizing the "REDEFINES" (*note REDEFINES::)
clause:
05 SHIRT-SIZE-VALUES.
10 PIC X(4) VALUE "S 14".
10 PIC X(4) VALUE "M 15".
10 PIC X(4) VALUE "L 16".
10 PIC X(4) VALUE "XL17".
05 SHIRT-SIZES REDEFINES SHIRT-SIZE-VALUES.
10 SHIRT-SIZE-TBL OCCURS 4 TIMES.
15 SST-SIZE PIC X(2).
15 SST-NECK PIC 9(2).
Admittedly, this table is much more verbose than the one
shown with a group "VALUE". What is good about this
initialization technique, however, is that you can have
as many "FILLER" and "VALUE" items as you need for a
larger table, and those values can be as long as
necessary!
G. Many COBOL compilers do not allow the use of "VALUE" and
"OCCURS" (*note OCCURS::) on the same data item;
additionally, they don't allow a "VALUE" clause on a data
item subordinate to an "OCCURS". GNU COBOL, however, has
neither of these restrictions!
Observe the following example, which illustrates a fourth
manner in which tables may be initialized in GNU COBOL:
05 X OCCURS 6 TIMES.
10 A PIC X(1) VALUE '?'.
10 B PIC X(1) VALUE '%'.
10 N 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. The "FROM" (*note FROM::), "TO" (*note TO::), "USING" (*note
USING::) and "VALUE" clauses are mutually-exclusive in any screen
section data itsm's definition.
File: gnucobpg.info, Node: PROCEDURE DIVISION, Next: Report Writer Usage Notes, Prev: DATA DIVISION, Up: Top
6. PROCEDURE DIVISION
*********************
PROCEDURE DIVISION Syntax
=======================================================================
PROCEDURE DIVISION [ { USING Subprogram-Argument... } ]
~~~~~~~~~ ~~~~~~~~ { ~~~~~ }
{ CHAINING Main-Program-Argument... }
~~~~~~~~
[ RETURNING identifier-1 ] .
[ DECLARATIVES. ] ~~~~~~~~~
~~~~~~~~~~~~
[ Event-Handler-Routine... . ]
[ END DECLARATIVES. ]
~~~ ~~~~~~~~~~~~
General-Program-Logic
[ Nested-Subprogram... ]
[ END PROGRAM|FUNCTION name-1 ]
~~~ ~~~~~~~ ~~~~~~~~
=======================================================================
The PROCEDURE DIVISION of any GNU COBOL program marks the point where
all executable code is written.
* Menu:
* 6.1: PROCEDURE DIVISION USING.
* 6.2: PROCEDURE DIVISION CHAINING.
* 6.3: PROCEDURE DIVISION RETURNING.
* 6.4: PROCEDURE DIVISION Sections and Paragraphs.
* 6.5: DECLARATIVES.
* 6.6: Table References.
* 6.7: Qualification of Data Names.
* 6.8: Reference Modifiers.
* 6.9: Arithmetic Expressions.
* 6.10: Conditional Expressions.
* 6.10.1: Condition Names.
* 6.10.2: Class Conditions.
* 6.10.3: Sign Conditions.
* 6.10.4: Switch-Status Conditions.
* 6.10.5: Relation Conditions.
* 6.10.6: Combined Conditions.
* 6.10.7: Negated Conditions.
* 6.11: Use of Periods.
* 6.12: Use of VERB/END-VERB Constructs.
* 6.13: Concurrent Access to Files.
* 6.13.1: File Sharing.
* 6.13.2: Record Locking.
* 6.14: Common Clauses on Executable Statements.
* 6.14.1: AT END + NOT AT END.
* 6.14.2: CORRESPONDING.
* 6.14.3: INVALID KEY + NOT INVALID KEY.
* 6.14.4: ON EXCEPTION + NOT ON EXCEPTION.
* 6.14.5: ON OVERFLOW + NOT ON OVERFLOW.
* 6.14.6: ON SIZE ERROR + NOT ON SIZE ERROR.
* 6.14.7: ROUNDED.
* 6.15: Special Registers.
* 6.16: Intrinsic Functions.
* 6.17: GNU COBOL Statements.
File: gnucobpg.info, Node: PROCEDURE DIVISION USING, Next: PROCEDURE DIVISION CHAINING, Up: PROCEDURE DIVISION
6.1. PROCEDURE DIVISION USING
=============================
PROCEDURE DIVISION Subprogram-Argument Syntax
=======================================================================
[ BY { REFERENCE [ OPTIONAL ] } ] identifier-1
{ ~~~~~~~~~ ~~~~~~~~ }
{ VALUE [ [ UNSIGNED ] SIZE IS { AUTO } ] }
~~~~~ ~~~~~~~~ ~~~~ { ~~~~ }
{ DEFAULT }
{ ~~~~~~~ }
{ integer-1 }
=======================================================================
The "USING" clause defines the arguments that will be passed to a GNU
COBOL program which is serving as a subprogram.
1. The reserved words "BY" and "IS" are optional and may be included,
or not, at the discretion of the programmer. The presence or
absence of these words have no effect upon the program.
2. The "USING" clause should only be used on the procedure division
header of subprograms (subroutines or user-defined functions).
3. The calling program will pass zero or more data items, known as
arguments, to this subprogram -- there must be exactly as many
data items specified on the USING clause as the
maximum number of arguments the subprogram will ever be passed.
4. If a subprogram does not expect any arguments, it should not have
a "USING" clause specified on it's procedure division header.
5. The order in which arguments are defined on the "USING" clause
must correspond to the order in which those arguments will be
passed to the subprogram by the calling program.
6. The identifiers specified on the "USING" clause must be defined in
the linkage section of the subprogram. No storage is actually
allocated for those identifiers in the subprogram as the actual
storage for them will exist in the calling program.
7. A GNU COBOL subprogram expects that all arguments to it will be
one of two things:
* The memory address of the actual data item (allocated in the
calling program) that is being passed to the subprogram.
* A numeric, full-word, binary value (i.e. "USAGE BINARY-LONG"
(*note USAGE::)) which is the actual argument being passed to
the subprogram.
In the case of the former, the "USING" clause on the procedure
division header should describe the argument via the "BY REFERENCE" clause
-- in the latter case, a "BY VALUE" specification should be coded.
This allows the code generated by the compiler to properly
reference the subprogram arguments at run-time.
8. "BY REFERENCE" is the assumed default for the first "USING"
argument should no "BY" clause be specified for it. Subsequent
arguments will assume the "BY" specification of the argument prior
to them should they lack a "BY" clause of their own.
9. Changes made by a subprogram to the value of an argument specified
on the "USING" clause will "be visible" to the calling program
only if "BY REFERENCE" was explicitly specified or implicitly
assumed for the argument on the subprogram's procedure division
header and the argument was passed to the subprogram "BY
REFERENCE" by the calling program. *Note Subprogram Arguments::,
for additional information on the mechanics of how arguments are
passed to subprograms.
10. The optional "SIZE" clause allows you to specify the number of
bytes a "BY VALUE" argument will occupy, with "SIZE DEFAULT"
specifying 4 bytes (this is the default if no "SIZE" clause is
used), "SIZE AUTO" specifying the size of the argument in the
calling program and "SIZE " specifying a specific byte
count.
11. The optional "UNSIGNED" keyword, legal only if "SIZE AUTO" or
"SIZE " are coded, will add the "unsigned" attribute to
the argument's specification in the C-language function header
code generated for the subprogram. While not of any benefit when
the calling program is a GNU COBOL program, this can improve
compatibility with a C-language calling program.
12. The "OPTIONAL" keyword, legal only on "BY REFERENCE" arguments,
allows calling programs to code "OMITTED" for that corresponding
argument when they call this subprogram. *Note CALL::. for
additional information on this feature.
File: gnucobpg.info, Node: PROCEDURE DIVISION CHAINING, Next: PROCEDURE DIVISION RETURNING, Prev: PROCEDURE DIVISION USING, Up: PROCEDURE DIVISION
6.2. PROCEDURE DIVISION CHAINING
================================
PROCEDURE DIVISION Main-Program-Argument Syntax
=======================================================================
[ BY REFERENCE ] [ OPTIONAL ] identifier-1
~~~~~~~~~ ~~~~~~~~
=======================================================================
The "CHAINING" term provides one mechanism a programmer may use to
retrieve command-line arguments passed to a program at execution time.
1. "PROCEDURE DIVISION CHAINING" may only be coded in a main program
(that is, the first program executed when a compiled GNU COBOL
compilation unit is executed). It cannot be used in any form of
subprogram.
2. The "CHAINING" clause defines arguments that will be passed to a
main program from the operating system. The argument identifiers
specified on the CHAINING clause will be populated by character
strings comprised of the parameters specified to the program on
the command line that executed it, as follows:
A. When a GNU COBOL program is excecuted from a command-line,
the complete command line text will be broken into a series
of "tokens", where each token is identified as being a word
separated from the others in the command text by at least one
space. For example, if the command line was
`/usr/local/myprog THIS IS A TEST', there will be five tokens
identified by the operating system -- "/usr/local/myprog",
"THIS", "IS", "A" and "TEST".
B. Multiple space-delimited tokens may be treated as a single
token by enclosing them in quotes. For example, there are
only three tokens generated from the command line
`C:\Pgms\myprog.exe "THIS IS A" TEST' --
"C:\Pgms\myprog.exe", "THIS IS A" and "TEST". When quote
characters are used to create multi-word tokens, the quote
characters themselves are stripped from the token's value.
C. Once tokens have been identified, the first (the command)
will be discarded; the rest will be stored into the
"CHAINING" arguments when the program begins execution, with
the 2nd token going to the 1st argument, the 3rd token going
to the 2nd argument and so forth.
D. If there are more tokens than there are arguments, the excess
tokens will be discarded.
E. If there are fewer tokens than there are arguments, the
excess arguments will be initialized as if the "INITIALIZE
" (*note INITIALIZE::) statement were
executed.
F. All identifiers specified on the CHAINING clause should be
defined as PIC X, PIC A, group items (which are treated
implicitly as PIC X) or as PIC 9 USAGE DISPLAY. The use of
USAGE BINARY (or the like) data items as CHAINING arguments
is not recommended as all command-line tokens will be
retained in their original character form as they are moved
into the argument data items.
G. If an argument identifier is smaller in storage size than the
token value to be stored in it, the right-most excess
characters of the token value will be truncated as the value
is moved in. Any JUSTIFIED RIGHT clause on such an argument
identifier will be ignored.
H. If an argument is larger in storage size than the token value
to be stored in it, the token value will be moved into the
argument identifier in a left-justified manner. Un-modified
byte positions in the identifier will be space filled, unless
the argument identifier is defined as PIC 9 USAGE DISPLAY, in
which case unmodified bytes will be filled with "0"
characters from the systems native characterset.
This behavior when the argument is defined as "PIC 9" may be
unacceptable, as an argument defined as "PIC 9(3)" but passed
in a value of "1" from the command line will receive a value
of "100", not "001". Consider defining "numeric" command
line arguments as "PIC X" and then using the "NUMVAL"
intrinsic function (*note NUMVAL::) function to determine the
proper numeric value.
File: gnucobpg.info, Node: PROCEDURE DIVISION RETURNING, Next: PROCEDURE DIVISION Sections and Paragraphs, Prev: PROCEDURE DIVISION CHAINING, Up: PROCEDURE DIVISION
6.3. PROCEDURE DIVISION RETURNING
=================================
PROCEDURE DIVISION RETURNING Syntax
=======================================================================
RETURNING identifier-1
~~~~~~~~~
=======================================================================
The RETURNING clause on the PROCEDURE DIVISION header documents that
the subprogram in which the clause appears will be returning a numeric
value back to the program that called it.
1. The "RETURNING" clause is optional within a subroutine, as not all
subroutines return a value to their caller.
2. The "RETURNING" clause is mandatory within a user-defined
function, as all such must return a numeric result.
3. The data item should be defined as a USAGE
BINARY-LONG data item.
4. Main programs that wish to "pass back" a return code value to the
operating system when they exit do not use RETURNING - they do so
simply by MOVEing a value to the "RETURN-CODE" special register.
5. This is not the only mechanism that a subprogram may use to pass a
value back to it's caller. Other possibilities are:
A. The subprogram may modify any argument that is specified as
"BY REFERENCE" on it's PROCEDURE DIVISION header. Whether
the calling program can actually "see" any modifications
depends upon how the calling program passed the argument to
the subprogram. *Note CALL::, for more information.
B. A data item with the "GLOBAL" (*note GLOBAL::) attribute
specified in it's description in the calling program is
automatically visible to and updatable by a subprogram nested
with the calling program. *Note Independent vs Contained vs
Nested Subprograms::, for more information on subprogram
nesting.
C. A data item defined with the "EXTERNAL" (*note EXTERNAL::)
attribute in a subprogram and the calling program (same name
in both programs) is automatically visible to and updatable
by both programs, even if those programs are compiled
separately from ona another.
File: gnucobpg.info, Node: PROCEDURE DIVISION Sections and Paragraphs, Next: DECLARATIVES, Prev: PROCEDURE DIVISION RETURNING, Up: PROCEDURE DIVISION
6.4. PROCEDURE DIVISION Sections and Paragraphs
===============================================
The procedure division is the only one of the COBOL divisions that
allows you to create your own sections and paragraphs. These are
collectively referred to as 'Procedures', and the names you create for
those sections and paragraphs are called 'Procedure Names'.
Procedure names are optional in the procedure division and -- when used
-- are named entirely according to the needs and whims of the
programmer.
Procedure names may be up to thirty one (31) characters long and may
consist of letters, numbers, dashes and underscores. A procedure name
may neither begin nor end with a dash (-) or underscore (_) character.
This means that "Main", "0100-Read-Transaction" and "17" are all
perfectly valid procedure names.
There are three circumstances under which the use of certain GNU COBOL
statements or options will require the specification of procedures.
These situations are:
1. When "DECLARATIVES" (*note DECLARATIVES::) are specified.
2. When the "ENTRY" statement (*note ENTRY::) is being used.
3. When any procedure division statement that references procedures
is used. These statements are:
* "ALTER "
* "GO TO "
* "MERGE ... OUTPUT PROCEDURE "
* "PERFORM "
* "SORT ... INPUT PROCEDURE " and/or "SORT ...
INPUT PROCEDURE "
File: gnucobpg.info, Node: DECLARATIVES, Next: Table References, Prev: PROCEDURE DIVISION Sections and Paragraphs, Up: PROCEDURE DIVISION
6.5. DECLARATIVES
=================
DECLARATIVES Syntax
=======================================================================
section-name-1 SECTION.
USE { [ GLOBAL ] AFTER STANDARD { EXCEPTION } PROCEDURE ON { INPUT } }
~~~ { ~~~~~~ { ~~~~~~~~~ } { ~~~~~ } }
{ { ERROR } { OUTPUT } }
{ ~~~~~ { ~~~~~~ } }
{ { I-O } }
{ FOR DEBUGGING ON { procedure-name-1 } { ~~~ } }
{ ~~~~~~~~~ { ALL PROCEDURES } { EXTEND } }
{ { ~~~ ~~~~~~~~~~ } { ~~~~~~ } }
{ { REFERENCES OF identifier-1 } { file-name-1 } }
{ }
{ [ GLOBAL ] BEFORE REPORTING identifier-2 }
{ ~~~~~~ ~~~~~~ ~~~~~~~~~ }
{ }
{ AFTER EC|{EXCEPTION CONDITION} }
~~ ~~~~~~~~~ ~~~~~~~~~
The "AFTER EXCEPTION CONDITION" and "AFTER EC" clauses are
syntactically recognized but are otherwise non-functional.
=======================================================================
The "DECLARATIVES" area of the procedure division allows the programmer
to define a series of "trap" procedures (referred to as declarative
procedures) capable of intercepting certain events that may occur at
program execution time. The syntax diagram above shows the format of a
single such procedure.
1. The reserved words "AFTER", "FOR", "ON", "PROCEDURE" and
"STANDARD" are optional and may be included, or not, at the
discretion of the programmer. The presence or absence of these
words has no effect upon the program.
2. "EC" and "EXCEPTION CONDITION" are interchangeable.
3. The declaratives area may contain any number of declarative
procedures, but no two declarative procedures should be coded to
trap the same event.
4. The following points apply to the "USE BEFORE REPORTING" clause:
A. must be a report group.
B. At run-time, the declaratives procedure will be executed
prior to the processing of the specified report group's
presentation; within the procedure you may take either of the
following actions:
* You may adjust the value(s) of any items referenced in
"SUM" (*note SUM::) or "SOURCE" (*note SOURCE::) clauses
in the report group.
* You may execute the "SUPPRESS" (*note SUPPRESS::)
statement to squelch the presentation of the specified
report group altogether. Note that you will be
suppressing this one specific instance of that group's
presentation and not all of them.
5. The following points apply to the "USE FOR DEBUGGING" clause:
A. This clause allows you to define a declarative procedure that
will be invoked whenever...
* ... is referenced on any statement.
* ... is executed.
* ...any procedure is executed ("ALL PROCEDURES").
B. A "USE FOR DEBUGGING" declarative procedure will be ignored
at compilation time unless "WITH DEBUGGING MODE" is specified
in the "SOURCE-COMPUTER" (*note SOURCE-COMPUTER::) paragraph.
Neither the compiler's "-fdebugging-line" switch nor
"-debug" switch will activate this feature.
C. Any "USE FOR DEBUGGING" declarative procedures will be
ignored at execution time unless the "COB_SET_DEBUG" run-time
environment variable (*note Run Time Environment Variables::)
has been set to a value of "Y", "y" or "1".
D. The typical use of a "USE FOR DEBUGGING" declarative
procedure is to display the "DEBUG-ITEM" special register,
which will be implicitly and automatically created in your
program for you if "WITH DEBUGGING MODE" is active.
The structure of DEBUG-ITEM will be as follows:
01 DEBUG-ITEM.
05 DEBUG-LINE PIC X(6).
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-NAME PIC X(31).
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-SUB-1 PIC S9(4) SIGN LEADING SEPARATE.
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-SUB-2 PIC S9(4) SIGN LEADING SEPARATE.
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-SUB-3 PIC S9(4) SIGN LEADING SEPARATE.
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-CONTENTS PIC X(31).
where...
"DEBUG-LINE"
... is the program line number of the statement that
triggered the declaratives procedure.
"DEBUG-NAME"
... is the procedure name or identifier name that
triggered the declaratives procedure.
"DEBUG-SUB-1"
... is the first subscript value (if any) for the
reference of the identifier that triggered the
declaratives procedure.
"DEBUG-SUB-2"
... is the second subscript value (if any) for the
reference of the identifier that triggered the
declaratives procedure.
"DEBUG-SUB-3"
... is the third subscript value (if any) for the
reference of the identifier that triggered the
declaratives procedure.
"DEBUG-CONTENTS"
... is a (brief) statement of the manner in which the
procedure that triggered the declaratives procedure was
executed or the first 31 characters of the value of the
identifier whose reference triggered the declaratives
procedure (the value after the statement was executed).
6. The "USE AFTER STANDARD ERROR PROCEDURE" clause defines a
declarative procedure invoked any time a failure is encountered
with the specified I/O type (or against the specified file(s)).
7. The "GLOBAL" (*note GLOBAL::) option, if used, allows a
declarative procedure to be used across the program containing the
"USE" statement and any subprograms nested within that program.
8. Declarative procedures may not reference any other procedures
defined outside the scope of DECLARATIVES.
File: gnucobpg.info, Node: Table References, Next: Qualification of Data Names, Prev: DECLARATIVES, Up: PROCEDURE DIVISION
6.6. Table References
=====================
COBOL uses parenthesis to specify the subscripts used to reference
table entries (tables in COBOL are what other programming languages
refer to as arrays).
For example, observe the following data structure which defines 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-CHARACTER PIC X(1).
If the structure contains the following grid of characters:
A B C D
E F G H
I J K L
Then "GRID-CHARACTER (2, 3)" references the "G" and "GRID-CHARACTER (3,
2)" references the "J".
Subscripts may be specified as numeric (integer) literals, numeric
(integer) data items, data items created with any of the picture-less
integer "USAGE" (*note USAGE::) specifications, "USAGE INDEX" data
items or arithmetic expressions resulting in a non-zero integer value.
In the above examples, a comma is used as a separator character between
the two subscript values; semicolons (";") are also valid subscript
separator characters, as are spaces! The use of a comma or semicolon
separator in such a situation is technically optional, but by
convention most COBOL programmers use one or the other. The use of no
separator character (other than a space) is not recommended, even
though it is syntactically correct, as this practice can lead to
programmer-unfriendly code. It isn't too difficult to read and
understand "GRID-CHARACTER(2 3)", but it's another story entirely when
trying to comprehend "GRID-CHARACTER(I + 1 J / 3)" (instead of
"GRID-CHARACTER(I + 1, J / 3)"). The compiler accepts it, but too much
of this would make my head hurt.
File: gnucobpg.info, Node: Qualification of Data Names, Next: Reference Modifiers, Prev: Table References, Up: PROCEDURE DIVISION
6.7. Qualification of Data Names
================================
COBOL allows data names to be duplicated within a program, provided
references to those data names may be made in 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 EMPLOYEE. 01 CUSTOMER.
05 MAILING-ADDRESS. 05 MAILING-ADDRESS.
10 STREET PIC X(35). 10 STREET PIC X(35).
10 CITY PIC X(15). 10 CITY PIC X(15).
10 STATE PIC X(2). 10 STATE PIC X(2).
10 ZIP-CODE. 10 ZIP-CODE.
15 ZIP-CODE-5 PIC 9(5). 15 ZIP-CODE-5 PIC 9(5).
15 FILLER PIC X(4). 15 FILLER PIC X(4).
Now, let's deal with the problem of setting the CITY portion of an
EMPLOYEEs MAILING-ADDRESS to "Philadelphia". Clearly, "MOVE
'Philadelphia' TO CITY" cannot work because the compiler will be unable
to determine which of the two CITY fields you are referring to.
In an attempt to correct the problem, we could qualify the reference to
CITY as "MOVE 'Philadelphia' TO CITY OF MAILING-ADDRESS".
Unfortunately that too is insufficient because it still insufficiently
specifies which CITY is being referenced. To truly identify which
specific CITY you want, you'd have to code "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 quite so specific; COBOL allows
intermediate and unnecessary qualification levels to be omitted. This
allows "MOVE 'Philadelphia' TO CITY OF EMPLOYEE" to do the job nicely.
If you need to qualify a reference to a table, do so by coding
something like " OF ( subscript(s) )".
The reserved word "IN" may be used in lieu of "OF".
File: gnucobpg.info, Node: Reference Modifiers, Next: Arithmetic Expressions, Prev: Qualification of Data Names, Up: PROCEDURE DIVISION
6.8. Reference Modifiers
========================
Reference Modifier (Format 1) Syntax
=======================================================================
identifier-1 [ OF|IN identifier-2 ] [ (subscript...) ] (start:[ length ])
~~ ~~
=======================================================================
Reference Modifier (Format 2) Syntax
=======================================================================
intrinsic-function-reference (start:[ length ])
=======================================================================
The COBOL '85 standard introduced the concept of a reference modifier
to facilitate references to only a portion of a data item; GNU COBOL
fully supports reference modification.
The 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