\input texinfo   @comment -*-texinfo-*-
@comment %**start of header
@comment *********************************************************************
@comment ** DOCUMENT HEADER                                                 **
@comment *********************************************************************
@comment ** SPECIAL INSTRUCTIONS WHEN RUNNING "MAKEINFO":                   **
@comment ** --------------------------------------------------------------- **
@comment ** Use the command "makeinfo --no-split gnucobpr.texi" to build    **
@comment ** an INFO file from this source.                                  **
@comment **                                                                 **
@comment ** Unfortunately, every version of MAKEINFO the author has tried   **
@comment ** produces a corrupted TAG TABLE at the end of the INFO file,     **
@comment ** making it impossible to gain access to nodes past the first     **
@comment ** several chapters.  If, however, you manually edit the generated **
@comment ** INFO file and DELETE the entire TAG TABLE from the end of the   **
@comment ** file (including the "Tag Table" and "End Tag Table" lines) the  **
@comment ** INFO file will be fine.  It will take a little longer for an    **
@comment ** INFO reader to locate a node (a millisecond or two) but the     **
@comment ** extra time will be unnoticeable.                                **
@comment *********************************************************************
@comment ** SPECIAL INSTRUCTIONS WHEN RUNNING "TEXI2PDF":                   **
@comment ** --------------------------------------------------------------- **
@comment ** Use the command "texi2pdf -q -c gnucobpr-xx.texi" to build a    **
@comment ** PDF (xx="a4" or "letter")                                       **
@comment *********************************************************************
@comment
@setfilename gnucobpr.info
@set CHAPNAME Contents
@finalout
@include Macros.texi
@comment tex-style @paragraphindent 0
@set BUILD 15 January 2024 at 22:00 GMT.
@set VERSION 3.2 - Final
@comment %**end of header
@setchapternewpage odd
@comment *********************************************************************
@comment ** COPYING POLICY STATEMENT                                        **
@comment *********************************************************************
@copying
This manual documents GnuCOBOL @value{VERSION}, @value{BUILD} build.

@*Document  Copyright 2009-2014 Gary L. Cutler, FSF (Free Software Foundation).
@*Updates:  Copyright 2014-2024 Vincent B. Coen, Gary L. Cutler & FSF.
@quotation

The authors and copyright holders of the COBOL programming language itself used herein:


FLOW-MATIC (trademark for Sperry Rand Corporation) Programming for the Univac(R) I & II. Data Automation Systems copyrighted 1958, 1959, by Sperry Rand Corporation; IBM commercial translator form F28-8013, copyrighted 1959 by IBM; FACT DSI27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell,
have specifically authorised the use of this material in whole or in part of the COBOL specifications. Such authorisation extends to the reproduction & use of COBOL specifications in programming manuals or similar publications.

@end quotation
@quotation
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".

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

@end quotation
@end copying
@dircategory GNU-COBOL
@direntry
* GNU-COBOL: (gnucobpr)        GnuCOBOL Programmer's Reference
@end direntry
@comment *********************************************************************
@comment ** TITLE PAGE (WHEN GENERATING PDF VIA TeX)                        **
@comment *********************************************************************
@titlepage
@title GnuCOBOL Programmer's Reference
@subtitle For Version @value{VERSION} [@value{BUILD}], for 3.3 and 4.0 (partial & tentative only).
@author Gary L. Cutler (@email{cutlergl@@gmail.com}).
@author For updates Vincent B. Coen (@email{vbcoen@@gmail.com}).
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@page
@comment *********************************************************************
@comment ** TABLE OF CONTENTS (WHEN GENERATING PDF VIA TeX)                 **
@comment *********************************************************************
@headings off
@oddheading GnuCOBOL @value{VERSION} [@value{BUILD}] Programmer's Reference @| @| @thispage
@oddfooting @today{} @| @| @value{CHAPNAME}
@evenheading @thispage @| @| GnuCOBOL @value{VERSION} [@value{BUILD}] Programmer's Reference
@evenfooting @value{CHAPNAME} @| @| @today{}
@contents
@comment *********************************************************************
@comment ** TOP NODE POINT (Ignore if running TeX)                          **
@comment *********************************************************************
@c jkl @ifinfo
@node Top
@top GnuCOBOL Programmer's Reference
This manual documents the @value{BUILD} build of GnuCOBOL @value{VERSION}.
@menu
List of Chapters and Appendices:

* Introduction.
* COBOL Fundamentals.
* CDF - Compiler Directing Facility.
* IDENTIFICATION DIVISION.
* ENVIRONMENT DIVISION.
* DATA DIVISION.
* PROCEDURE DIVISION.
* Functions.
* Report Writer Usage.
* Interfacing With The OS.
* Sub-Programming.
* Programming Style Suggestions.
* Programming for XFD.
* Appendix A - Glossary of Terms.
* Appendix B - Reserved Word List.
* Appendix C1 - Grouped Word Lists by feature and function.
* Appendix C2 - Intrinsic Functions.
* Appendix C3 - System routines.
* Appendix C4 - System names.
* Appendix D - GNU Free Documentation License.
* Appendix E - Summary of Document Changes.
@comment* F4: Appendix F4 - Summary of Compiler Changes to v4
@comment* F3: Appendix F3 - Summary of Compiler Changes to v3.1.1
@comment* F2: Appendix F2 - Summary of Compiler Changes after GnuCOBOL Compiler v2.2.
@comment* F1: Appendix F1 - Summary of Compiler Changes since 2009 and version v1-1.
* INDEX.

Full Contents:

@detailmenu
* Introduction.
* Additional Reference Sources.
* Introducing COBOL.
* Why YOU Should Learn COBOL.
* Programmer Productivity.
* So What is GnuCOBOL?.

* COBOL Fundamentals.
* The COBOL Language - The Basics.
* Language Reserved Words.
* User-Defined Words.
* Case Insensitivity.
* Readability of Programs.
* Divisions Organize Programs.
* Copybooks.
* Structured Data.
* Files.
* Table Handling.
* Sorting and Merging Data.
* String Manipulation.
* Screen Formatting Features.
* A Sample Screen.
* Color Palette and Video Attributes.
* Report Writer Features.
* Data Initialization.
* Syntax Diagram Conventions.
* Format of Program Source Lines.
* Program Structure.
* Comments.
* Literals.
* Numeric Literals.
* Alphanumeric Literals.
* Figurative Constants.
* Punctuation.
* Interfacing to Other Environments.
* The COBOL Language - Advanced Techniques.
* Table References.
* Qualification of Data Names.
* Reference Modifiers.
* Arithmetic Expressions.
* Conditional Expressions.
* Condition Names.
* Class Conditions.
* Sign Conditions.
* Switch-Status Conditions.
* Relation Conditions.
* Combined Conditions.
* Negated Conditions.
* Use of Periods.
* Use of VERB/END-VERB Constructs.
* Concurrent Access to Files.
* File Sharing.
* Record Locking.

* CDF - Compiler Directing Facility.
* >>CALL-CONVENTION.
* COPY.
* REPLACE.
* >>DEFINE.
* >>IF.
* >>SET.
* >>SOURCE.
* >>TURN.
* >>D.
* >>DISPLAY.
* >>PAGE.
* >>LISTING.
* >>LEAP-SECONDS.
* $ Directives.

* IDENTIFICATION DIVISION.

* ENVIRONMENT DIVISION.
* CONFIGURATION SECTION.
* SOURCE-COMPUTER.
* OBJECT-COMPUTER.
* SPECIAL-NAMES.
* Alphabet-Name-Clause.
* Class-Definition-Clause.
* Switch-Definition-Clause.
* Symbolic-Characters-Clause.
* REPOSITORY.
* INPUT-OUTPUT SECTION.
* SELECT.
* ORGANIZATION SEQUENTIAL.
* ORGANIZATION LINE SEQUENTIAL.
* ORGANIZATION RELATIVE.
* ORGANIZATION INDEXED.
* SAME RECORD AREA.
* MULTIPLE FILE.

* DATA DIVISION.
* Data Definition Principles.
* FILE SECTION.
* File/Sort-Description.
* FILE-SECTION-Data-Item.
* WORKING-STORAGE SECTION.
* LOCAL-STORAGE SECTION.
* LINKAGE SECTION.
* REPORT SECTION.
* Report Group Definitions.
* REPORT SECTION Data Items.
* SCREEN SECTION.
* Special Data Items.
* 01-Level Constants.
* 66-Level Data Items.
* 77-Level Data Items.
* 78-Level Data Items.
* 88-Level Data Items.
* Data Description Clauses.
* ANY LENGTH.
* ANY NUMERIC.
* AUTO.
* AUTO-SKIP.
* AUTOTERMINATE.
* BACKGROUND-COLOR.
* BEFORE TIME.
* BASED.
* BEEP.
* BELL.
* BLANK.
* BLANK WHEN ZERO.
* BLINK.
* COLUMN.
* CONSTANT.
* EMPTY-CHECK.
* EXTERNAL.
* ERASE.
* FALSE.
* FOREGROUND-COLOR.
* FROM.
* FULL.
* GLOBAL.
* GROUP INDICATE.
* HIGHLIGHT.
* JUSTIFIED.
* LEFTLINE.
* LENGTH-CHECK.
* LINE.
* LOWER.
* LOWLIGHT.
* NEXT GROUP.
* NO-ECHO.
* NO UPDATE.
* OCCURS.
* OVERLINE.
* PICTURE.
* PRESENT WHEN.
* PROMPT.
* PROTECTED.
* REDEFINES.
* RENAMES.
* REQUIRED.
* REVERSE-VIDEO.
* SAME.
* SCROLL DOWN.
* SCROLL UP.
* SECURE.
* SIGN.
* SIZE.
* SOURCE.
* SUM.
* SYNCHRONIZED.
* TIME OUT
* TO.
* TYPE.
* TYPEDEF.
* UNDERLINE.
* UPDATE.
* UPPER.
* USAGE.
* USING.
* VALUE.

* PROCEDURE DIVISION.
* PROCEDURE DIVISION USING.
* PROCEDURE DIVISION CHAINING.
* PROCEDURE DIVISION RETURNING.
* PROCEDURE DIVISION Sections and Paragraphs.
* DECLARATIVES.
* Common Clauses on Executable Statements.
* AT END + NOT AT END.
* CORRESPONDING.
* INVALID KEY + NOT INVALID KEY.
* ON EXCEPTION + NOT ON EXCEPTION.
* ON OVERFLOW + NOT ON OVERFLOW.
* ON SIZE ERROR + NOT ON SIZE ERROR.
* ROUNDED.
* Special Registers.
* GnuCOBOL Statements.

* Functions.
* Intrinsic Functions.
* Built-In System Subroutines.

* Report Writer Usage.
* RWCS Lexicon.
* The Anatomy of a Report.
* The Anatomy of a Report Page.
* How RWCS Builds Report Pages.
* Control Hierarchy.
* An Example.
* Data.
* Program.
* Generated Report Pages.
* Control Hierarchy (Revisited).
* Turning PHYSICAL Page Formatting Into LOGICAL Formatting.

* Interfacing With The OS.
* Compiling Programs.
* cobc - The GnuCOBOL Compiler.
* cobc option -Xref an example.
* Cross Reference listing using cobxref.
* Compilation Time Environment Variables.
* Predefined Compilation Variables.
* Locating Copybooks.
* Compiler Configuration Files.
* Running Programs.
* Direct Execution.
* Executing Dynamically-Loadable Libraries.
* cobcrun - Command-line Execution.
* Dynamically Loaded Subprograms.
* Run Time Environment Variables.
* General instructions
* General Environment
* Call Environment
* File I/O
* Screen I/O
* Report I/O
* File I/O Environment Variables and/or dictionary file

* Program Arguments.
* Binary Truncation.

* Sub-Programming.
* Subprogram Types.
* Independent vs Contained vs Nested Subprograms.
* Alternate Entry Points.
* Dynamic vs Static Subprograms.
* Subprogram Execution Flow.
* Subroutine Execution Flow.
* User-Defined Function Execution Flow.
* Sharing Data Between Calling and Called Programs.
* Subprogram Arguments.
* Calling Program Considerations.
* Called Program Considerations.
* GLOBAL Data Items.
* EXTERNAL Data Items.
* Recursive Subprograms.
* Combining GnuCOBOL and C Programs.
* GnuCOBOL Run-Time Library Requirements.
* String Allocation Differences Between GnuCOBOL and C.
* Matching C Data Types with GnuCOBOL USAGE's.
* GnuCOBOL Main Programs CALLing C Subprograms.
* C Main Programs Calling GnuCOBOL Subprograms.

* Programming Style Suggestions.
* Marking Changes in Programs.
* Data Item Coding and Naming Conventions.
* Table Subscripting versus Table Indexing.
* Copybook Naming Conventions and Usage.
* PROCEDURE DIVISION Sections Versus Paragraphs.
* COMPUTE Versus ADD-SUBTRACT-MULTIPLY-DIVIDE.

* Programming for XFD.
* GnuCobol use SQL for files.

* Appendix A - Glossary of Terms.

* Appendix B - Reserved Word List.

* Appendix C1 - Grouped Word Lists by feature and function.
* Appendix C2 - Intrinsic Functions.
* Appendix C3 - System routines.
* Appendix C4 - System names.
* Appendix C5 - Exceptions.
* Appendix D - GNU Free Documentation License.
* Appendix E - Summary of Document Changes.
@comment* F4:  Appendix F4 - Summary of Compiler Changes to v4
@comment* F3:  Appendix F3 - Summary of Compiler Changes to v3.1.1
@comment* F2:  Appendix F2 - Summary of Compiler Changes after GnuCOBOL Compiler v2.2.
@comment* F1:  Appendix F1 - Summary of Compiler Changes since 2009 and version v1-1.

@end detailmenu
@end menu
@c jkl @end ifinfo
@settitle GnuCOBOL Programmer's Reference
@comment Above to force TOC on odd page so a blank page on even side.
@comment *********************************************************************
@comment ** Document Body                                                   **
@comment *********************************************************************
@include 1.texi
@include 2.texi
@include 3.texi
@include 4.texi
@include 5.texi
@include 6.texi
@include 7.texi
@include 8.texi
@include 9.texi
@include 10.texi
@include 11.texi
@include 12.texi
@include 13.texi
@include A.texi
@include B.texi
@include C.texi
@include D.texi
@comment@include E.texi
@include updates.texi
@comment@include F4.texi
@comment@include F3.texi
@comment@include F2.texi
@comment@include F1.texi
@comment *********************************************************************
@comment ** Index                                                           **
@comment *********************************************************************
@node INDEX
@unnumbered Index
@set CHAPNAME Index
@printindex cp
@ifhtml
@html
<p> <a href="https://validator.w3.org/check?uri=referer"><img
      src="https://www.w3.org/Icons/valid-html401"
      alt="Valid HTML 4.01 Transitional" height="31" width="88"></a> </p>
@end html
@end ifhtml
@bye
