@comment *********************************************************************
@comment ** 6. DATA DIVISION                                                **
@comment *********************************************************************
@newchapter{DATA DIVISION}
@diagram{DATA DIVISION,DD-Overview-Info,DD-Overview-TeX,None}

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.
@enumerate
@item
If no data will be described in one of the data division sections, that section header may be omitted.

@item
If no data division sections are needed, the @code{DATA DIVISION.} header itself may be omitted.

@item
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.
@end enumerate
@menu
* Data Definition Principles.
* FILE SECTION.
@detailmenu
* File/Sort-Description.
* FILE-SECTION-Data-Item.
@end detailmenu
* WORKING-STORAGE SECTION.
* LOCAL-STORAGE SECTION.
* LINKAGE SECTION.
* REPORT SECTION.
@detailmenu
* Report Group Definitions.
* REPORT SECTION Data Items.
@end detailmenu
* SCREEN SECTION.
* Special Data Items.
@detailmenu
* 01-Level Constants.
* 66-Level Data Items.
* 77-Level Data Items.
* 78-Level Data Items.
* 88-Level Data Items.
@end detailmenu
* Data Description Clauses.
@end menu
@comment *********************************************************************
@comment ** 6.1 Data Definition Principles                                  **
@comment *********************************************************************
@newsection{Data Definition Principles}
GnuCOBOL 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 @code{Employee}:

@iftex
@center @image{hierarchy,6in,}
@end iftex
@ifnottex
@verbatim
                           Employee
                               |                     Additional
              :----------------:----------------:--> Data Items ...
              |                                 |
        Employee-name                    Employment-Dates
              |                                 |
    :---------:-------------:           :-------:-------:
    |         |             |           |               |
Last-Name First-Name Middle-Initial From-Date        To-Date
                                        |               |
                                   :----:----:     :----:----:
                                   |    |    |     |    |    |
                                 Year Month Day  Year Month Day
@end verbatim
@end ifnottex

The @code{Employee} data item consists of two subordinate data items --- an @code{Employee-Name} and an @code{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 @code{deep}, and GnuCOBOL, like other COBOL implementations, can handle up to 49 levels of such hierarchical structures.

As was presented earlier (@pxref{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 @i{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 @i{need} 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 @i{record}, always has a level number of 01.  After that, you may assign level numbers as you wish (01--02--03--04@dots{}, 01--05--10--15@dots{}, etc.), as long as you follow these simple rules:
@enumerate
@item
Every data item at the same @i{level} of a hierarchy diagram such as the one you see here (if you were to make one, which you rarely will, if ever, once you get used to this concept) must have the same level number.

@item
Every new level uses a level number that is strictly greater than the one used in the parent (next higher) level.

@item
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 (@pxref{Special Data Items}).
@end enumerate

So, the definition of these data items in a GnuCOBOL program would go something like this:
@verbatim
    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
@end verbatim

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 @code{01} level number begin in Area A and that everything else begins in Area B.  GnuCOBOL 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 @code{Year}, @code{Month} and @code{Day} data names defined?  That's perfectly legal, provided that each can be uniquely @code{qualified} so as to be distinct from the other.  Take for example the @code{Year} items.  One is defined as part of the @code{From-Date} data item while the other is defined as part of the @code{To-Date} data item.  In COBOL, we would actually code references to these two data items as either @code{Year OF From-Date} and @code{Year OF To-Date} or @code{Year IN From-Date} and @code{Year IN To-Date} (COBOL allows either @code{IN} or @code{OF} to be used).  Since these references would clarify any confusion to us as to which @code{Year} might be referenced, the GnuCOBOL 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 the ``name'' @
@syntaxidx{FILLER}.  There may be any number of @code{FILLER} items defined within a group item.  A data item named @code{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 @code{FILLER} if there is no need to ever refer directly to the group structure itself.
@comment *********************************************************************
@comment ** 6.2 FILE SECTION                                                **
@comment *********************************************************************
@page
@newsection{FILE SECTION}
@diagram{FILE SECTION,DD-FILE-SECTION,DD-FILE-SECTION,None}

Every file that has been referenced by a @statementref{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 (@code{SD}) while every other file is described with a File Description (@code{FD}).  Each of these descriptions will almost always be followed with at least one record description.
@menu
* File/Sort-Description.
* FILE-SECTION-Data-Item.
@end menu
@comment *********************************************************************
@comment ** 6.2.1 File/Sort-Description                                     **
@comment *********************************************************************
@page
@newsubsection{File/Sort-Description}
@diagram{File/Sort-Description,DD-FD-SD,DD-FD-SD,DD-FD-SD}
@enumerate
@item
The reserved words @code{ARE}, @code{AT}, @code{CHARACTERS} (@code{RECORD} clause only), @code{CONTAINS}, @code{FROM}, @code{IN}, @code{IS}, @code{ON} and @code{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.

@item
The terms @code{RECORD IS} and @code{RECORDS ARE} are interchangeable.

@item
The terms @code{REPORT IS} and @code{REPORTS ARE} are interchangeable.

@item
Only files intended for use as work files for either the @syntaxref{SORT} or @syntaxref{MERGE} statements should be coded with an SD --- all others should be defined with a FD.

@item
The sequence in which files are defined via @code{FD} or @code{SD}, as compared to the sequence in which their @code{SELECT} statements were coded, is irrelevant.

@item
 The name specified as @var{file-name-1} must exactly match the name specified on the file's @code{SELECT} statement.

@item
The
@syntaxidx{CODE-SET} clause allows a custom alphabet, defined in the @syntaxref{SPECIAL-NAMES} paragraph, to be associated with a file. This clause is valid only when used with sequential or line sequential files and usage can depend of the compiler version in use, platform used and other factors, see the NEWS file supplied with your version of the compiler for more details.

@item
The @code{LINAGE} clause may only be specified in the @code{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 @code{LINAGE} clause define the layout of printed pages as follows:
@table @asis
@item @plainidx{LINES AT TOP}
Number of unused (@i{i.e.} left blank) lines at the top of every page.  The default if this if not specified is zero.

@item @plainidx{LINES AT BOTTOM}
Number of unused (@i{i.e.} left blank) lines at the bottom of every page.  The default if this if not specified is zero.

@item @plainidx{LINAGE IS n LINES}
Total number of used/usable lines on the page.

@comment Because the next "item" is really a comment on the previous 3,
@comment it's set at the left of the table under the terms, not the definitions.
@item The sum of the previous three specifications should be the total number of possible lines available on one printed page.
@sp 1

@item @plainidx{FOOTING AT}
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 @code{LINAGE IS @var{n} LINES} value.
@end table

@item
This page structure --- once defined --- can be automatically enforced by the @statementref{WRITE}.

@item
Specifying a @code{LINAGE} clause in an @code{FD} will cause the
@register{LINAGE-COUNTER} 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 @statement{WRITE}.

@item
The
@syntaxidx{RECORD CONTAINS} and
@syntaxidx{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 @var{identifier-6} must be defined within one of the record descriptions of @var{file-name-1}.

@item
The
@syntaxidx{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 @code{REPORT} clause is used:
@enumerate A
@item
The clause may only be specified in the @code{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.

@item
The @code{FD} cannot be followed by record descriptions.  Detailed descriptions of data to be printed to the file will be defined in the @syntaxref{REPORT SECTION}.

@item
If a @code{LINAGE} clause is also specified, Values specified for @code{LINAGE IS} and @code{FOOTING AT} will be ignored.  The values of @code{LINES AT BOTTOM} and @code{LINES AT TOP}, if any, will be honoured.
@end enumerate
@item The following special rules apply only to sort/merge work files:
@enumerate A
@item
Sort/merge work files should be assigned to @code{DISK} (or @code{DISC}) on their @code{SELECT} statements.

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

@item
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:
@itemize @bullet
@item
The
@envvarruntimeref{TMPDIR}

@item
The
@envvarruntime{TMP}

@item
The
@envvarruntime{TEMP}
@end itemize
(in that order).

@item
These disk files will be automatically purged upon @code{SORT} or @code{MERGE} termination.  They will also be purged if the program terminates abnormally before the @code{SORT} or @code{MERGE} finishes.  Should you ever need to know, temporary sort/merge work files will be named @file{cob*.tmp}.

@item
If you specify a specific filename in the sort/merge work file's @code{SELECT}, it will be ignored.
@end enumerate
@item @xref{Data Description Clauses}, for information on the @code{EXTERNAL} and @code{GLOBAL} options.
@end enumerate
@comment *********************************************************************
@comment ** 6.2.2 FILE-SECTION-Data-Item                                    **
@comment *********************************************************************
@page
@newsubsection{FILE-SECTION-Data-Item}
@diagram{FILE-SECTION-Data-Item,DD-FS-Data-Item,DD-FS-Data-Item,DD-SYNC-LEFT-RIGHT}

Every sort file description (@code{SD} or @code{FD}) must be followed by at least one 01-level data item, except for file descriptions containing the @code{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
@define{Record}, even if it is an elementary item, provided that elementary item lacks the
@syntaxidx{CONSTANT} attribute.
@enumerate
@item
The reserved words @code{BY}, @code{IS}, @code{KEY}, @code{ON} and @code{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.

@item
The reserved words @code{SYNCHRONIZED} and @code{SYNCHRONISED} are interchangeable.  Both may be abbreviated to @code{SYNC}.

@item
The reserved word @code{PICTURE} may be abbreviated to @code{PIC}.

@item
As the syntax diagram shows, the definition of a @var{FILE-SECTION-Data-Item} 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:
@table @asis
@item Another 01-level item is found
signifies the start of another record layout for the file.

@item Another @code{FD} or @code{SD} is found
marks the completion of the detailed description of the file and begins another.

@item A division or section header is found
also marks the completion of the detailed description of the file and signifies the end of the file section as well.
@end table

@item
Every FILE-SECTION-Data-Item description must be terminated with a period.

@item
If there are multiple record descriptions present for a given @code{FD} or @code{SD}, the one with the longest length will define the size of the record buffer into which a @statementref{READ} or a @statementref{RETURN} will deliver data read from the file and from which a @statementref{WRITE} or @statementref{RELEASE} statement will obtain the data to be written to the file.

@item
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 @syntaxref{SAME RECORD AREA} clause.

@item
The only valid level numbers are 01-49, 66, 77, 78 and 88.  Level numbers 66, 77, 78 and 88 all have special uses --- @xref{Special Data Items}, for details.

@item
Not specifying an @var{identifier-1} or @code{FILLER} immediately after the level number has the same effect as if @code{FILLER} were specified.  A data item named @code{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.

@item
@code{EXTERNAL} cannot be combined with @code{GLOBAL} or @code{REDEFINES}.

@item
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.

@item
@xref{Data Description Clauses}, for information on the usage of the various data description clauses.
@end enumerate
@comment *********************************************************************
@comment ** 6.3 WORKING-STORAGE SECTION                                     **
@comment *********************************************************************
@page
@newsection{WORKING-STORAGE SECTION}
@diagram{WORKING-STORAGE-SECTION-Data-Item,DD-WSS-Data-Item,DD-WSS-Data-Item,DD-SYNC-LEFT-RIGHT}

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.
@enumerate
@item
The reserved words @code{BY}, @code{CHARACTER}, @code{IS}, @code{KEY}, @code{ON}, @code{RIGHT} (JUSTIFIED), @code{TIMES} and @code{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.

@item
The reserved words @code{SYNCHRONIZED} and @code{SYNCHRONISED} are interchangeable.  Both may be abbreviated as @code{SYNC}.

@item
The reserved word @code{PICTURE} may be abbreviated to @code{PIC}.

@item
The reserved word @code{JUSTIFIED} may be abbreviated to @code{JUST}.

@item
As the syntax diagram shows, the definition of a @code{@var{WORKING-STORAGE-SECTION-Data-Item}} 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:
@itemize @bullet

@item
Another 01-level item is found --- this signifies the end of the definition of one record and the start of a another.

@item
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; @xref{77-Level Data Items}, for more information.

@item
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.
@end itemize
@item
Every @code{@var{WORKING-STORAGE-SECTION-Data-Item}} description must be terminated with a period.

@item
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 unchangeable value specified at compilation time.

@item
Level numbers 66, 77, 78 and 88 all have special uses --- @xref{Special Data Items}, for details.

@item
Not specifying an @var{identifier-1} or @code{FILLER} immediately after the level number has the same effect as if @code{FILLER} were specified.  A data item named @code{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.

@item
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 @statementref{CANCEL}), in which case initialization will happen each time they are loaded.  @xref{Data Initialization}, for a discussion of the initialization rules.

@item
@xref{Data Description Clauses}, for information on the usage of the various data description clauses.
@end enumerate
@comment *********************************************************************
@comment ** 6.4 LOCAL-STORAGE SECTION                                       **
@comment *********************************************************************
@page
@newsection{LOCAL-STORAGE SECTION}
@diagram{LOCAL-STORAGE-SECTION-Data-Item,DD-LSS-Data-Item,DD-LSS-Data-Item,DD-SYNC-LEFT-RIGHT}

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.  @xref{Data Initialization}, for the rules of data initialization.
@enumerate
@item
The reserved words @code{BY}, @code{CHARACTER} @code{IS}, @code{KEY}, @code{ON}, @code{RIGHT} (JUSTIFIED), @code{TIMES} and @code{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.

@item
The reserved words @code{SYNCHRONIZED} and @code{SYNCHRONISED} are interchangeable.  Both may be abbreviated as @code{SYNC}.

@item
The reserved word @code{PICTURE} may be abbreviated to @code{PIC}.

@item
The reserved word @code{JUSTIFIED} may be abbreviated to @code{JUST}.

@item
As the syntax diagram shows, the definition of a @code{@var{LOCAL-STORAGE-SECTION-Data-Item}} 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:
@itemize @bullet
@item
Another 01-level item is found --- this signifies the end of the definition of one record and the start of a another.

@item
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.
@end itemize

@item
Every @code{@var{LOCAL-STORAGE-SECTION-Data-Item}} description must be terminated with a period.

@item
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 unchangeable value specified at compilation time.

@item
Level numbers 66, 77, 78 and 88 all have special uses --- @xref{Special Data Items}, for details.

@item
Not specifying an @var{identifier-1} or @code{FILLER} immediately after the level number has the same effect as if @code{FILLER} were specified.  A data item named @code{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.

@item
Local-storage cannot be used in nested subprograms.

@item
@xref{Data Description Clauses}, for information on the usage of the various data description clauses.
@end enumerate
@comment *********************************************************************
@comment ** 6.5 LINKAGE SECTION                                             **
@comment *********************************************************************
@page
@newsection{LINKAGE SECTION}
@diagram{LINKAGE-SECTION-Data-Item,DD-LS-Data-Item,DD-LS-Data-Item,DD-SYNC-LEFT-RIGHT}

The linkage section describes data within a subprogram that serves as either input arguments to or output results from the subprogram.
@enumerate
@item
The reserved words @code{BY}, @code{CHARACTER}, @code{IS}, @code{KEY}, @code{ON} and @code{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.

@item
The reserved words @code{SYNCHRONIZED} and ``@code{SYNCHRONISED}'' are interchangeable.  Both may be abbreviated as @code{SYNC}.

@item
The reserved word @code{PICTURE} may be abbreviated to @code{PIC}.

@item
The reserved word @code{JUSTIFIED} may be abbreviated to @code{JUST}.

@item
As the syntax diagram shows, the definition of a @code{@var{LINKAGE-SECTION-Data-Item}} 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:
@itemize @bullet

@item
Another 01-level item is found --- this signifies the end of the definition of one record and the start of a another.

@item
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.
@end itemize

@item
Every @code{@var{LINKAGE-SECTION-Data-Item}} description must be terminated with a period.

@item
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 unchangeable value specified at compilation time.

@item
Level numbers 66, 77, 78 and 88 all have special uses --- @xref{Special Data Items}, for details.

@item
It is expected that:
@enumerate A
@item
A linkage section should occur only within a subprogram.  The compiler will not prevent its use in a main program, however.

@item
All 01-level data items described within a subprogram's linkage section should appear in a @syntaxref{PROCEDURE DIVISION USING} or as arguments on an @statement{ENTRY}.

@item
Each 01-level data item described within a subprogram's linkage section should correspond to an argument passed on a @statementref{CALL} or an argument on a function call to the subprogram.
@end enumerate

@item
Not specifying an @var{identifier-1} or @code{FILLER} immediately after the level number has the same effect as if @code{FILLER} were specified.  A data item named @code{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 @code{FILLER}.

@item
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 @i{is} possible, however, to manually allocate linkage section data items that aren't subprogram arguments via the @statementref{ALLOCATE} statement.  In such cases, initialization will take place as per the documentation of that statement.

@item
@xref{Data Description Clauses}, for information on the usage of the various data description clauses.
@end enumerate
@comment *********************************************************************
@comment ** 6.6 REPORT SECTION                                              **
@comment *********************************************************************
@page
@newsection{REPORT SECTION}
@diagram{REPORT SECTION,DD-REPORT-SECTION,DD-REPORT-SECTION,None}
@diagram{Report-Description (RD),DD-RS-RD,DD-RS-RD,None}

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. It is important to maintain the order of these clauses and ensure that all fields defined or referenced with this section are actually defined in the @code{WORKING-STORAGE SECTION} and not elsewhere.
@enumerate
@item
The reserved words @code{ARE} and @code{IS} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The phrases @code{CONTROL IS} and @code{CONTROLS ARE} are interchangeable, as are the @code{PAGE LIMIT} and @code{PAGE LIMITS} phrases.

@item
The reserved word @code{LINES} may be abbreviated as @code{LINE}.

@item
The reserved word @code{COLUMNS} may be abbreviated as @code{COLS}.

@item
Each report referenced on a @code{REPORT IS} clause (@pxref{File/Sort-Description}) must be described with a report description (@code{RD}).

@item
@xref{GLOBAL}, for information on the @code{GLOBAL} option.

@item
Please see @ref{Report Writer Features}, if you have not read it already.  It will familiarize you with the Report Writer terminology that follows.

@item
The following rules pertain to the
@syntaxidx{PAGE LIMITS} clause:
@enumerate A
@item
If no @code{PAGE LIMITS} clause is specified, the entire report will be generated as if it consists of a single arbitrarily long page.

@item
All literals (@var{literal-2} through @var{literal-8}) must be numeric with non-zero positive integer values.

@item
All identifiers (@var{identifier-2} through @var{identifier-8}) must be numeric, unedited with non-zero positive integer values.

@item
Any value specified for @var{literal-2} or @var{identifier-2} 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 @code{LINES AT TOP} and @code{LINES AT BOTTOM} values specified on the @code{LINAGE} clause of the @code{FD} this @code{RD} is linked to --- @pxref{File/Sort-Description}).

@item
Any value specified for @var{literal-3} or @var{identifier-3} will be ignored.

@item
The
@syntaxidx{HEADING} clause defines the first line number at which a report heading or page heading may be presented.

@item
The
@syntaxidx{FIRST DETAIL} clause defines the first line at which a detail group may be presented.

@item
The
@syntaxidx{LAST CONTROL} @code{HEADING} clause defines the last line at which any line of a control heading may be presented.

@item
The
@syntaxidx{LAST DETAIL} clause defines the last line at which any line of a detail group may be presented.

@item
The
@syntaxidx{FOOTING} clause defines the last line at which any line of a control footing group may be presented.

@item
The following rules establish default values for the various @code{PAGE LIMIT} clauses, assuming there is one:
@table @code
@item HEADING
default is one (1)

@item FIRST DETAIL HEADING
value is used

@item LAST CONTROL HEADING
value from @code{LAST DETAIL} or, if that is absent, the value from @code{FOOTING} or, if that too is absent, the value from @code{PAGE LIMIT}

@item LAST DETAIL
value from @code{FOOTING} or, if that is absent, the value from @code{PAGE LIMIT}

@item FOOTING
value from @code{LAST DETAIL} or, if that is absent, the value from @code{PAGE LIMIT}
@end table

@item
For the values specified on a @code{PAGE LIMIT} clause to be valid, all of the following must be true:
@itemize @bullet

@item
@code{FIRST DETAIL} @leq{} @code{HEADING}

@item
@code{LAST CONTROL HEADING} @leq{} @code{FIRST DETAIL}

@item
@code{LAST DETAIL} @leq{} @code{LAST CONTROL HEADING}

@item
@code{FOOTING} @leq{} @code{LAST DETAIL}
@end itemize
@end enumerate

@item
The following rules pertain to the
@syntaxidx{CONTROL} clause:
@enumerate A
@item
If there is no @code{CONTROL} clause, the report will contain no control breaks; this implies that there can be no @code{CONTROL HEADING} or @code{CONTROL FOOTING} report groups defined for this @code{RD}.

@item
Include the reserved word
@syntaxidx{FINAL} if you want to include a special control heading before the first detail line is generated (@code{CONTROL HEADING FINAL}) or after the last detail line is generated (@code{CONTROL FOOTING FINAL}).

@item
If you specify @code{FINAL}, it must be the first control break named in the @code{RD}.

@item
Any @var{identifier-9} specifications included on the @code{CONTROL} clause are referencing data names defined in any data division section except for the report section.

@item
There must be a @code{CONTROL HEADING} and/or @code{CONTROL FOOTING} report group defined in the report section for each @var{identifier-9}.

@item
At execution time:
@itemize @bullet

@item
Each time a @statementref{GENERATE} is executed against a detail report group defined for this @code{RD}, the RWCS will check the contents of each @var{identifier-2} data item; whenever an @var{identifier-9}'s value has changed since the previous @code{GENERATE}, a control break condition will be in effect for that @var{identifier-2}.

@item
Once the list of control breaks has been determined, the @code{CONTROL FOOTING} for each @var{identifier-2} having a control break (if any such report group is defined) will be presented.

@item
Next, the @code{CONTROL HEADING} for each @var{identifier-2} having a control break (if any such report group is defined) will be presented.

@item
The @code{CONTROL FOOTING} and @code{CONTROL HEADING} report groups will be presented in the sequence in which they are listed on the @code{CONTROL} clause.

@item
Only after this processing has occurred will the detail report group specified on the @code{GENERATE} be presented.
@end itemize
@end enumerate
@item Each @code{RD} will have the following allocated for it:
@enumerate A
@item
The
@registerref{PAGE-COUNTER}, which will contain the current report page number.
@itemize @bullet
@item
This register will be set to a value of 1 when an @statementref{INITIATE} is executed for the report and will be incremented by 1 each time the RWCS starts a new page of the report.

@item
References to @code{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.

@item
References to @code{PAGE-COUNTER} in the procedure division must be qualified with the appropriate report name if there are multiple @code{RD}s defined.
@end itemize
@item The
@register{LINE-COUNTER}, which will contain the current line number on the current page.
@end enumerate
@item The @code{RD} must be followed by at least one 01-level report group definition.
@end enumerate
@menu
* Report Group Definitions.
* REPORT SECTION Data Items.
@end menu
@comment *********************************************************************
@comment ** 6.6.1 Report Group Definitions                                  **
@comment *********************************************************************
@page
@newsubsection{Report Group Definitions}
@diagram{Report-Group-Definition,DD-RS-Report-Group,DD-RS-Report-Group,None}

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 @code{RD}.
@enumerate
@item
The reserved words @code{IS}, @code{NUMBER} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The @code{RH} and @code{REPORT HEADING} terms are interchangeable, as are @code{PH} and @code{PAGE HEADING}, @code{CH} and @code{CONTROL HEADING}, @code{DE} and @code{DETAIL}, @code{CF} and @code{CONTROL FOOTING}, @code{PF} and @code{PAGE FOOTING} as well as @code{RF} and @code{REPORT FOOTING}.

@item
The report group being defined will be a part of the most-recently coded @code{RD}.

@item
The @syntaxref{TYPE} clause specifies the type of report group being defined.

@item
The level number used for a report group definition must be 01.

@item
The optional @var{identifier-1} specification assigns a name to this report group so that the group may be referenced either by a @code{GENERATE} statement or on a @code{USE BEFORE REPORTING}.

@item
No two report groups in the same report (@code{RD}) may named with the same @var{identifier-1}.  There may, however, be multiple @var{identifier-1} definitions in different reports.  In such instances, references to @var{identifier-1} must be qualified by the report name.

@item
There may only be one report heading, report footing, final control heading, final control footing, page heading and page footing defined per report.

@item
Report group declarations must be followed by at least one @code{@var{REPORT-SECTION-Data-Item}} with a level number in the range 02-49.

@item
@xref{Data Description Clauses}, for information on the usage of the various data description clauses.
@end enumerate
@comment *********************************************************************
@comment ** 6.6.2 REPORT SECTION Data Items                                 **
@comment *********************************************************************
@page
@newsubsection{REPORT SECTION Data Items}
@diagram{REPORT-SECTION-Data-Item,DD-RS-Data-Item-Info,DD-RS-Data-Item-TeX,None}

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.
@enumerate
@item
The reserved words @code{IS}, @code{NUMBER}, @code{OF}, @code{ON}, @code{RIGHT}, @code{TIMES} and @code{WHEN} (BLANK) are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved word @code{COLUMN} may be abbreviated as @code{COL}.

@item
The reserved word @code{JUSTIFIED} may be abbreviated as @code{JUST}.

@item
The reserved word @code{PICTURE} may be abbreviated as @code{PIC}.

@item
The @syntaxref{SOURCE}, @syntaxref{SUM} and @syntaxref{VALUE} clauses, valid only on an elementary item, are mutually-exclusive of each other.

@item
Group items (those without
@syntaxidx{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 @syntaxref{LINE} clauses and no @syntaxref{COLUMN} clauses while elementary items will be specified the other way around.

@item
@xref{Data Description Clauses}, for information on the usage of the various data description clauses.
@end enumerate
@comment *********************************************************************
@comment ** 6.7 SCREEN SECTION                                              **
@comment *********************************************************************
@page
@newsection{SCREEN SECTION}
@diagram{SCREEN-SECTION-Data-Item,DD-SS-Data-Item,DD-SS-Data-Item,None}

The screen section describes the screens to be displayed during terminal/console I-O.
@enumerate
@item
The reserved words @code{CHARACTER} (@code{SEPARATE} clause), @code{IS}, @code{NUMBER}, @code{RIGHT}, @code{TIMES} and @code{WHEN} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved word @code{COLUMN} may be abbreviated as @code{COL}.

@item
The reserved word @code{PICTURE} may be abbreviated as @code{PIC}.

@item
The following sets of reserved words are interchangeable:
@itemize @bullet

@item
@code{AUTO}, @code{AUTO-SKIP} and @code{AUTOTERMINATE}

@item
@code{BACKGROUND-COLOR} and @code{BACKGROUND-COLOUR}

@item
@code{BELL} and @code{BEEP}

@item
@code{FOREGROUND-COLOR} and @code{FOREGROUND-COLOUR}

@item
@code{FULL} and @code{LENGTH-CHECK}

@item
@code{REQUIRED} and @code{EMPTY-CHECK}

@item
@code{SECURE} and @code{NO-ECHO}
@end itemize

@item
Data items defined in the screen section describe input, output or combination screen layouts to be used with @statementref{ACCEPT data-item} or @statementref{DISPLAY data-item} statements.  These screen layouts may define the entire available screen area or any subset of it.

@item
The term @i{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 GnuCOBOL screens, you need to do so with an awareness of the logical screen row/column geometry the program will be executing within.

@item
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.

@item
Without @syntaxref{LINE} or @syntaxref{COLUMN} clauses, screen section fields will display on the console window beginning at whatever line/column coordinate is stated or implied by the @code{ACCEPT data-item} or @statement{DISPLAY data-item} that presents the screen item.  After a field is presented to the console window, the next field will be presented immediately following that field.

@item
A @code{LINE} clause explicitly stated in the definition of a screen section data item will override any @code{LINE} clause included on the @code{ACCEPT data-item} or @statement{DISPLAY data-item} that presents that data item to the screen.  The same is true of @code{COLUMN} clauses.

@item
The @key{Tab} and @key{Back-Tab} (@key{Shift}-@key{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.

@item
@xref{Data Description Clauses}, for information on the usage of the various data description clauses.
@end enumerate
@comment *********************************************************************
@comment ** 6.8 Special Data Items                                          **
@comment *********************************************************************
@page
@newsection{Special Data Items}
@menu
* 01-Level Constants.
* 66-Level Data Items.
* 77-Level Data Items.
* 78-Level Data Items.
* 88-Level Data Items.
@end menu
@comment *********************************************************************
@comment ** 6.8.1 01-Level Constants                                        **
@comment *********************************************************************
@newsubsection{01-Level Constants}
@diagram{01-Level-Constant,DD-01-Constant,DD-01-Constant,None}

This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{SCREEN}.

The 01-level constant is one of five types of compilation-time constants that can be declared within a program.  The other four types are  @directiveref{>>DEFINE} constants, @directiveref{>>SET} constants, 78-level constants (@pxref{78-Level Data Items} and arithmetic-expression-1).
@enumerate
@item
The reserved words @code{AS}, @code{IS} and @code{OF} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
@xref{GLOBAL}, for information on the @code{GLOBAL} option.

@item
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 @syntaxref{USAGE} type --- something not possible with the other types of constants.

@item
 Constants defined in this way become undefined once an @code{END PROGRAM} or @code{END FUNCTION} is encountered in the input source.

@item
Data descriptions of this form do not actually allocate any storage --- they merely define a name (@var{constant-name-1}) that may be used anywhere a numeric literal (see
@syntaxidx{BYTE-LENGTH} or
@syntaxidx{LENGTH} options) or a literal of the same type as @var{literal-1} may be used.

@item
 The @var{constant-name-1} name may not be referenced on a CDF directive.

@item
 Care must be taken that @var{constant-name-1} 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 GnuCOBOL compiler will not issue a warning about this condition.

@item
 The value specified for @var{usage-name} may be any @code{USAGE} that does not use a @syntaxref{PICTURE} clause.  These would be any of @code{BINARY-C-LONG}, @code{BINARY-CHAR}, @code{BINARY-DOUBLE}, @code{BINARY-LONG}, @code{BINARY-SHORT}, @code{COMP-1} (or @code{COMPUTATIONAL-1}), @code{COMP-2} (or @code{COMPUTATIONAL-2}), @code{FLOAT-DECIMAL-16}, @code{FLOAT-DECIMAL-34}, @code{FLOAT-LONG}, @code{FLOAT-SHORT}, @code{POINTER}, or @code{PROGRAM-POINTER}.

@item
 The @code{BYTE-LENGTH} clause will produce a numeric value for @var{constant-name-1} identical to that which would be returned by the @intrinsic{BYTE-LENGTH} executed against @var{identifier-1} or a data item declared with a @code{USAGE} of @var{usage-name}.

@item
 The @code{LENGTH} clause will produce a numeric value for @var{constant-name-1} identical to that which would be returned by the @intrinsic{LENGTH} executed against @var{identifier-1} or a data item declared with a @code{USAGE} of @var{usage-name}.
@end enumerate

Here is usage examples of the option arithmetic-expression

@verbatim

 78 wCONST VALUE 2 *  (23 + 3) + (10 / 2).
 01 wCONST2 constant (23 + 3)**2.
 01 wCONST3 constant (12 + wCONST2)**2 - wCONST.
 78 wCONST4 value    (12 + wCONST3)**2 - wCONST2.

@end verbatim

Here is another example of using the option arithmetic-expression.
@verbatim

       PROGRAM-ID. TESTCONST.
       ENVIRONMENT DIVISION.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 A   CONSTANT 2.
       01 B   CONSTANT ( (3 + 2) * A).
       01 CON CONSTANT (A ** B).
       01 MYDATA PIC X(CON).
       PROCEDURE DIVISION.
        DISPLAY CON
        ACCEPT omitted
        MOVE "123456789012345678901234567890" TO MYDATA
         DISPLAY MYDATA
        ACCEPT omitted
        GOBACK.

@end verbatim

Here is the listing of a GnuCOBOL program that uses 01-level constants to display the length (in bytes) of the various picture-less usage types.
@verbatim

       IDENTIFICATION DIVISION.
       PROGRAM-ID. Usage-Lengths.
       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 GnuCOBOL, the"
           DISPLAY "PICTURE-less USAGE's 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.

@end verbatim

The output of this program, on a Windows 7 system with a 32-bit MinGW build of GnuCOBOL is:
@verbatim

    On this system, with this build of GnuCOBOL, the
    PICTURE-less USAGE's 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

The output of this program, on a Linux X64 system running cobc (GnuCOBOL) 3.1.2.0 is:

On this system, with this build of GnuCOBOL, the
PICTURE-less USAGE's have these lengths (in bytes):

BINARY-C-LONG:    8
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:          8
PROGRAM-POINTER:  8

Spot the differences between 32 and 64 bit.

@end verbatim
@comment *********************************************************************
@comment ** 6.8.2 66-Level Data Items                                       **
@comment *********************************************************************
@page
@newsubsection{66-Level Data Items}
@diagram{66-Level-Data-Item,DD-66-Data-Item,DD-66-Data-Item,None}

This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}

A 66-level data item regroups previously defined items by specifying alternative, possibly overlapping, groupings of elementary data items.
@enumerate
@item
The reserved words @code{THRU} and @code{THROUGH} are interchangeable.

@item
A level-66 data item cannot rename a level-66, level-01, level-77, or level-88 data item.

@item
There may be multiple level-66 data items that rename data items contained within the same 01-level record description.

@item
All @code{RENAMES} entries associated with one logical record must immediately follow that record's last data description entry.
@end enumerate
@comment *********************************************************************
@comment ** 6.8.3 77-Level Data Items                                       **
@comment *********************************************************************
@page
@newsubsection{77-Level Data Items}
@diagram{77-Level-Data-Item,DD-77-Data-Item,DD-77-Data-Item,DD-SYNC-LEFT-RIGHT}
This syntax is valid in the following sections:
@code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}

The intent of a 77-level item is to be able to create a stand-alone elementary data item.
@enumerate
@item
The reserved words @code{CHARACTER}, @code{IS}, @code{RIGHT} (JUSTIFIED) and @code{WHEN} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved word @code{JUSTIFIED} may be abbreviated as @code{JUST}, the reserved word @code{PICTURE} may be abbreviated as @code{PIC} and the reserved words @code{SYNCHRONIZED} and @code{SYNCHRONISED} may be abbreviated as @code{SYNC}.

@item
New programs requiring a stand-alone elementary item should be coded to use a level number of 01 rather than 77.

@item
@xref{Data Description Clauses}, for information on the usage of the various data description clauses.
@end enumerate
@comment *********************************************************************
@comment ** 6.8.4 78-Level Data Items                                       **
@comment *********************************************************************
@page
@newsubsection{78-Level Data Items}
@diagram{78-Level-Constant,DD-78-Constant,DD-78-Constant,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{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 @directiveref{>>DEFINE} constants, @directiveref{>>SET} constants and 01-level constants (@pxref{01-Level Constants}).
@enumerate
@item
The reserved word @code{IS} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
Constants defined in this way become undefined once an @code{END PROGRAM} or @code{END FUNCTION} is encountered in the input source.

@item
 Data descriptions of this form do not actually allocate any storage --- they merely define a name (@var{constant-name-1}) that may be used anywhere a literal of the same type as @var{literal-1} may be used.

@item
 The @var{constant-name-1} name may not be referenced on a CDF directive.

@item
 Care must be taken that @var{constant-name-1} 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 GnuCOBOL compiler will not issue a warning about this condition.

@item
 See in 6.8.1 for examples of using the option arithmetic-expression.

@end enumerate
@comment *********************************************************************
@comment ** 6.8.5 88-Level Data Items                                       **
@comment *********************************************************************
@page
@newsubsection{88-Level Data Items}
@idx{Condition Names}
@diagram{88-Level-Data-Item,DD-88-Data-Item,DD-88-Data-Item,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{REPORT}, @code{SCREEN}

Condition names are Boolean (@i{i.e.} @code{TRUE} / @code{FALSE}) data items that receive their @code{TRUE} and @code{FALSE} values based upon the values of the non 88-level data item whose definition they immediately follow.
@enumerate
@item
The reserved words @code{ARE}, @code{IS}, @code{SET} and @code{TO} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words @code{THRU} and @code{THROUGH} are interchangeable.

@item
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 @syntaxref{VALUE} clause, @var{condition-name-1} will take on the value of @code{TRUE}.

@item
Condition names do not occupy any storage.

@item
The optional @code{THROUGH} clause allows a range of possible @code{TRUE} values to be specified.

@item
Whenever the parent data item assumes any value @i{except} one of the values specified on @var{condition-name-1}'s @code{VALUE} clause, @var{condition-name-1} will take on the value of FALSE.

@item
Executing the statement @code{SET @var{condition-name-1} TO TRUE} will cause @var{condition-name-1}'s parent data item to take on the first value specified on @var{condition-name-1}'s @code{VALUE} clause.

@item
Executing the statement @code{SET @var{condition-name-1} TO FALSE} will cause @var{condition-name-1}'s parent data item to take on the value specified on @var{condition-name-1}'s @code{FALSE} clause.  If @var{condition-name-1} does not have a @code{FALSE} clause, the @syntaxref{SET} statement will generate an error message at compilation time.

@item
@xref{Condition Names}, for more information.
@end enumerate
@comment *********************************************************************
@comment ** 6.9 Data Description Clauses                                    **
@comment *********************************************************************
@page
@newsection{Data Description Clauses}
@menu
* ANY LENGTH.
* ANY NUMERIC
* AUTO.
* AUTO-SKIP.
* AUTOTERMINATE.
* BACKGROUND-COLOR.
* BEFORE TIME.
* BASED.
* BEEP.
* BELL.
* BLANK.
* BLANK WHEN ZERO.
* BLINK.
* COLUMN.
* CONSTANT.
* EMPTY-CHECK.
* ERASE.
* EXTERNAL.
* 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 AS.
* SCROLL DOWN.
* SCROLL UP.
* SECURE.
* SIGN.
* SIZE.
* SOURCE.
* SUM.
* SYNCHRONIZED.
* TIME OUT
* TO.
* TYPE.
* TYPEDEF.
* UNDERLINE.
* UPDATE.
* UPPER.
* USAGE.
* USING.
* VALUE.

@end menu
@comment *********************************************************************
@comment ** 6.9.1 ANY LENGTH                                                **
@comment *********************************************************************
@newsubsection{ANY LENGTH}
@diagram{ANY LENGTH Attribute,DD-ANY-LENGTH,DD-ANY-LENGTH,None}
This syntax is valid in the following sections:
@code{LINKAGE}

Data items declared with the @code{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 @syntaxref{PICTURE} clause that specifies exactly one A, X, U or 1 symbol.
@enumerate
@item
The @code{ANY LENGTH} and @syntaxref{BASED} clauses cannot be used together in the same data item description. The @code{ANY LENGTH} clause specifies that the length of the data item will be determined at runtime, the type is determined (and someday checked with EC-PROGRAM-ARGS) by the picture symbol.

They are determined by checking the caller's definition, which therefore MUST be either a GnuCOBOL module or a C program that uses api functions to create COBOL fields.
@end enumerate

@comment *********************************************************************
@comment ** 6.9.1B ANY NUMERIC                                              **
@comment *********************************************************************
@page
@newsubsection{ANY NUMERIC}
@diagram{ANY NUMERIC Attribute,DD-ANY-NUMERIC,DD-ANY-NUMERIC,None}
This syntax is valid in the following sections:
@code{LINKAGE}

Data items declared with the @code{ANY NUMERIC} attribute has 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 @syntaxref{PICTURE} clause that specifies exactly one 9 symbol.
The ANY NUMERIC clause specifies that the length and the usage of the data item will be determined at runtime.

They are determined by checking the caller's definition, which therefore MUST be either a GnuCOBOL module or a C program that uses api functions to create COBOL fields.

@enumerate
@item
The @code{ANY NUMERIC} and @syntaxref{BASED} clauses cannot be used together in the same data item description.
@end enumerate

@comment *********************************************************************
@comment ** 6.9.2 AUTO                                                      **
@comment *********************************************************************
@page
@newsubsection{AUTO}
@diagram{AUTO Attribute,DD-AUTO,DD-AUTO,None}
This syntax is valid in the following sections:
@code{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.
@enumerate
@item
The @code{AUTO}, @syntaxref{AUTO-SKIP} and @syntaxref{AUTOTERMINATE} clauses are interchangeable, and may not be used together in the same data item description.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.3 AUTO-SKIP                                                 **
@comment *********************************************************************
@page
@newsubsection{AUTO-SKIP}
@diagram{AUTO-SKIP Attribute,DD-AUTO-SKIP,DD-AUTO-SKIP,None}
This syntax is valid in the following sections:
@code{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.
@enumerate
@item
The @syntaxref{AUTO}, @code{AUTO-SKIP} and @syntaxref{AUTOTERMINATE} clauses are interchangeable, and may not be used together in the same data item description.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.4 AUTOTERMINATE                                             **
@comment *********************************************************************
@page
@newsubsection{AUTOTERMINATE}
@diagram{AUTOTERMINATE Attribute,DD-AUTOTERMINATE,DD-AUTOTERMINATE,None}
This syntax is valid in the following sections:
@code{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.
@enumerate
@item
The @syntaxref{AUTO}, @syntaxref{AUTO-SKIP} and @code{AUTOTERMINATE} clauses are interchangeable, and may not be used together in the same data item description.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.5 BACKGROUND-COLOR                                          **
@comment *********************************************************************
@page
@newsubsection{BACKGROUND-COLOR}
@diagram{BACKGROUND-COLOR Attribute,DD-BACKGROUND-COLOR,DD-BACKGROUND-COLOR,None}
This syntax is valid in the following sections:
@code{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.
@enumerate
@item
The reserved word @code{IS} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
The reserved words @code{BACKGROUND-COLOR} and @code{BACKGROUND-COLOUR} are interchangeable.

@item
You specify colors by number (0-7), or by using the constant names provided in the @file{screenio.cpy} copybook (provided with all GnuCOBOL source distributions).

@item
Colors may also be specified using a numeric non-edited identifier whose value is in the range 0-7.
@end enumerate

For composite @code{DISPLAY}'s, the attributes are always only applied to the previous source-item but the following also allows a change by variable or literal @i{i.e.}

@verbatim
DISPLAY "Name: "   BACKGROUND-COLOR COB-YELLOW
         NAME-VAR  BACKGROUND-COLOR COB-BLACK
END-DISPLAY
@end verbatim

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.

@comment *********************************************************************
@comment ** 6.9.5B BEFORE TIME                                              **
@comment *********************************************************************
@page
@newsubsection{BEFORE TIME}
@diagram{BEFORE TIME Attribute,DD-BEFORE-TIME,DD-BEFORE-TIME,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause is used to specify time sequence etc, etc, etc. NEEDS CONTENT HERE.

@comment *********************************************************************
@comment ** 6.9.6 BASED                                                     **
@comment *********************************************************************
@page
@newsubsection{BASED}
@diagram{BASED Attribute,DD-BASED,DD-BASED,None}
This syntax is valid in the following sections:
@code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}

Data items declared with @code{BASED} are allocated no storage at compilation time.  At run-time, the @syntaxref{ALLOCATE} or @syntaxref{SET ADDRESS} statements are used to allocate space for and (optionally) initialize such items.
@enumerate
@item
The @code{BASED} and @syntaxref{ANY LENGTH} clauses cannot be used together in the same data item description.

@item
The @code{BASED} clause may only be used on level 01 and level 77 data items.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.7 BEEP                                                      **
@comment *********************************************************************
@page
@newsubsection{BEEP}
@diagram{BEEP Attribute,DD-BEEP,DD-BEEP,None}
This syntax is valid in the following sections:
@code{SCREEN}

@enumerate
@item
The @code{BEEP} and @syntaxref{BELL} clauses are interchangeable, and may not be used together in the same data item description.

@item
Use this clause to cause an audible tone to occur when the screen item is @code{DISPLAY}ed.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.8 BELL                                                      **
@comment *********************************************************************
@page
@newsubsection{BELL}
@diagram{BELL Attribute,DD-BELL,DD-BELL,None}
This syntax is valid in the following sections:
@code{SCREEN}
@enumerate
@item
The @syntaxref{BEEP} and @code{BELL} clauses are interchangeable, and may not be used together in the same data item description.

@item
Use this clause to cause an audible tone to occur when the screen item is @code{DISPLAY}ed.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.9 BLANK                                                     **
@comment *********************************************************************
@page
@newsubsection{BLANK}
@diagram{BLANK Attribute,DD-BLANK,DD-BLANK,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause will blank out either the entire screen (@code{BLANK SCREEN}) or just the line upon which data is about to be displayed (@code{BLANK LINE}).
@enumerate
@item
Blanked-out areas will have their foreground and background colors set to the attributes of the field containing the @code{BLANK} clause.

@item
This clause is useful when one screen section item is being displayed over the top of a previously-displayed one.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.10 BLANK WHEN ZERO                                          **
@comment *********************************************************************
@page
@newsubsection{BLANK WHEN ZERO}
@diagram{BLANK-WHEN-ZERO Attribute,DD-BLANK-WHEN-ZERO,DD-BLANK-WHEN-ZERO,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{REPORT}, @code{SCREEN}

This clause will cause that item's value to be automatically transformed into spaces if a value of 0 is ever @code{MOVE}d to the item.
@enumerate
@item
The reserved word @code{WHEN} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
This clause may only be used on a @code{PIC 9} data item with a @syntaxref{USAGE} of @code{DISPLAY}.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.11 BLINK                                                    **
@comment *********************************************************************
@page
@newsubsection{BLINK}
@diagram{BLINK Attribute,DD-BLINK,DD-BLINK,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{BLINK} clause modifies the visual appearance of the displayed field by making the field contents blink.
@enumerate
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.12 COLUMN                                                   **
@comment *********************************************************************
@page
@newsubsection{COLUMN}
@diagram{COLUMN (REPORT SECTION) Clause,DD-COLUMN-1,DD-COLUMN-1,None}
@diagram{COLUMN (SCREEN SECTION) Clause,DD-COLUMN-2,DD-COLUMN-2,None}
This syntax is valid in the following sections:
@code{REPORT}, @code{SCREEN}

The @code{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).
@enumerate
@item
The reserved words @code{ARE}, @code{IS}, @code{NUMBER} and @code{NUMBERS} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved word @code{COLUMN} may be abbreviated as @code{COL}.

@item
The line location of a report section or screen section field will be determined by the @syntaxref{LINE} clause.

@item
The value of @var{integer-1} must be 1 or greater.

@item
If @var{identifier-1} is used to specify either an absolute or relative column position, @var{identifier-1} must be defined as a numeric item of any @syntaxref{USAGE} other than @code{COMPUTATIONAL-1} or @code{COMPUTATIONAL-2}, without editing symbols.  The value of @var{identifier-1} at the time the screen data item is presented must be 1 or greater.  Note that a @code{COMPUTATIONAL-1} or @code{COMPUTATIONAL-2} identifier will be accepted by the compiler, but will produce unpredictable results at run-time.

@item
The column coordinate of a field may be stated on an absolute basis (@i{i.e.} @code{COLUMN 5}) or on a relative basis based upon the end of the previously-presented field (@i{i.e.} @code{COLUMN PLUS 1}).

@item
The symbol @samp{+} may be used in lieu of the word @code{PLUS}, if desired; if symbol @samp{+} is used, however, there must be at least one space separating it from @var{integer-1}.  Failure to include this space will cause the symbol @samp{+} sign to be simply treated as part of @var{integer-1} and will treat the @code{COLUMN} clause as an absolute column specification rather than a relative one.

@item
Using relative column positioning (@code{COLUMN PLUS}) has slightly different behaviour depending upon the section in which the clause is used, as follows:
@enumerate A
@item
When used on a report section data item, @code{COLUMN PLUS} will position the start of the new field's value such that there are @var{integer-1} blank columns between the end of the previous field and the beginning of this field.

If a report data item's description includes the @syntaxref{SOURCE}, @syntaxref{SUM} or @syntaxref{VALUE} clause but has no @code{COLUMN} clause, @code{COLUMN PLUS 1} will be assumed.

@item
When used on a screen section data item, @code{COLUMN PLUS} will position the new field so that it begins exactly @var{integer-1} or @var{identifier-1} characters past the @i{last} character of the previous field.  Thus, @code{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 @syntaxref{FROM}, @syntaxref{TO}, @syntaxref{USING} or @syntaxref{VALUE} clause but has no @code{COLUMN} clause, the new screen field will begin at the column coordinate of the last character of the previous field.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 6.9.13 CONSTANT                                                 **
@comment *********************************************************************
@page
@newsubsection{CONSTANT}
@diagram{CONSTANT Attribute,DD-CONSTANT,DD-CONSTANT,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{SCREEN}

This option signifies that the 01-level data item in whose declaration @code{CONSTANT} is specified will be treated as a symbolic name for a literal value, usable wherever a literal of the appropriate type could be used.
@enumerate
@item
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.

@item
@xref{01-Level Constants}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.14 EMPTY-CHECK                                              **
@comment *********************************************************************
@page
@newsubsection{EMPTY-CHECK}
@diagram{EMPTY-CHECK Attribute,DD-EMPTY-CHECK,DD-EMPTY-CHECK,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if @code{EMPTY-CHECK} is specified on a group item).
@enumerate
@item
The @code{EMPTY-CHECK} and @syntaxref{REQUIRED} clauses are interchangeable, and may not be used together in the same data item description.

@item
In order to take effect, the user must first move the cursor into the field having this clause in its definition.

@item
The @statementref{ACCEPT data-item} will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item @i{unless} data has been entered into the field.  Function keys will still be allowed to terminate the @code{ACCEPT}.

@item
In order to be functional, this attribute must be supported by the underlying ``curses'' package your GnuCOBOL implementation was built with.  As of this time, the ``PDCurses'' package (used for native Windows or MinGW builds) does not support @code{EMPTY-CHECK}.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.15 ERASE                                                    **
@comment *********************************************************************
@page
@newsubsection{ERASE}
@diagram{ERASE Clause,DD-ERASE,DD-ERASE,None}
This syntax is valid in the following sections:
@code{SCREEN}

@code{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 (@code{ERASE EOS})
@idx{EOS}
@idx{EOL}
@enumerate
@item
Erased areas will have their foreground and background colors set to the attributes of the field containing the @code{ERASE} clause.

@item
This clause is useful when one screen section item is being displayed over the top of a previously-displayed one.
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.16 EXTERNAL                                                 **
@comment *********************************************************************
@page
@newsubsection{EXTERNAL}
@diagram{EXTERNAL Attribute,DD-EXTERNAL,DD-EXTERNAL,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}

This clause marks a data item description, @code{FD} or @code{SD} @pxref{File/Sort-Description} as being shareable with other programs executed from the same execution thread.
@enumerate
@item
By specifying the @code{EXTERNAL} clause on either an @code{FD} or an @code{SD}, the file description is capable of being shared between all programs executed from the same execution thread, provided an @code{EXTERNAL} clause is coded with the file's description in @i{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.

@item
By specifying the @code{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 @code{EXTERNAL} clause) in each program requiring it.

@item
The following points apply to the specification of @code{EXTERNAL} in a data item's definition:
@enumerate A
@item
The @code{EXTERNAL} clause may only be specified at the 77 or 01 level.

@item
An @code{EXTERNAL} item must have a data name and that name cannot be @code{FILLER}.

@item
@code{EXTERNAL} cannot be combined with @syntaxref{BASED}, @syntaxref{GLOBAL} or @syntaxref{REDEFINES}.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 6.9.17 FALSE                                                    **
@comment *********************************************************************
@page
@newsubsection{FALSE}
@diagram{FALSE Clause,DD-FALSE,DD-FALSE,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{REPORT}, @code{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 @code{FALSE}.
@enumerate
@item
The reserved words @code{IS}, @code{SET}, @code{TO} and @code{WHEN} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
@xref{88-Level Data Items}, or @xref{Condition Names}, for more information.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.18 FOREGROUND-COLOR                                         **
@comment *********************************************************************
@page
@newsubsection{FOREGROUND-COLOR}
@diagram{FOREGROUND-COLOR Attribute,DD-FOREGROUND-COLOR,DD-FOREGROUND-COLOR,None}
This syntax is valid in the following sections:
@code{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.
@enumerate
@item
The reserved word @code{IS} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
The reserved words @code{FOREGROUND-COLOR} and @code{FOREGROUND-COLOUR} are interchangeable.

@item
You specify colors by number (0-7), or by using the constant names provided in the @file{screenio.cpy} copybook (which is provided with all GnuCOBOL source distributions).

@item
Colors may also be specified using a numeric non-edited identifier whose value is in the range 0-7.
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.19 FROM                                                     **
@comment *********************************************************************
@page
@newsubsection{FROM}
@diagram{FROM Clause,DD-FROM,DD-FROM,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause is used to specify either the data item a screen section field is to obtain its value from when the screen is displayed, or a literal that will specify the value of that same field.
@enumerate
@item The @code{FROM}, @syntaxref{TO}, @syntaxref{USING} and @syntaxref{VALUE} clauses are mutually-exclusive in any screen section data item's definition.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.20 FULL                                                     **
@comment *********************************************************************
@page
@newsubsection{FULL}
@diagram{FULL Attribute,DD-FULL,DD-FULL,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{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.
@enumerate
@item
The @code{FULL} and @syntaxref{LENGTH-CHECK} clauses are interchangeable, and may not be used together in the same data item description.

@item
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.

@item
The @statementref{ACCEPT 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 @code{ACCEPT}, however.

@item
In order to be functional, this attribute must be supported by the underlying ``curses'' package your GnuCOBOL implementation was built with.  As of this time, the ``PDCurses'' package (used for native Windows or MinGW builds) does not support @code{FULL}.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.21 GLOBAL                                                   **
@comment *********************************************************************
@page
@newsubsection{GLOBAL}
@diagram{GLOBAL Attribute,DD-GLOBAL,DD-GLOBAL,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{REPORT}

This clause marks a data item, 01-level constant, @code{FD} (@pxref{File/Sort-Description}), @code{SD} (@pxref{File/Sort-Description}) or an @code{RD} (@pxref{REPORT SECTION}) as being shareable with any nested subprograms.
@enumerate
@item
By specifying the @code{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 @code{FD}, @code{SD} or @code{RD} is coded (with a @code{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 @code{GLOBAL} file description, but they may share an @syntaxref{EXTERNAL} file description.  This sharing applies to the record descriptions subordinate to the file description and the report groups subordinate to the @code{RD} also.

@item
By specifying the @code{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 @code{GLOBAL} clause) in each program requiring it.

@item
The following points apply to the specification of @code{GLOBAL} in a data item's definition:
@enumerate A
@item
The @code{GLOBAL} clause may only be specified at the 77 or 01 level.

@item
A @code{GLOBAL} item must have a data name and that name cannot be @code{FILLER}.

@item
@code{GLOBAL} cannot be combined with @syntaxref{EXTERNAL}, @syntaxref{REDEFINES} or @syntaxref{BASED}.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 6.9.22 GROUP INDICATE                                           **
@comment *********************************************************************
@page
@newsubsection{GROUP INDICATE}
@diagram{GROUP-INDICATE Attribute,DD-GROUP-INDICATE,DD-GROUP-INDICATE,None}
This syntax is valid in the following sections:
@code{REPORT}

The @code{GROUP INDICATE} clause specifies that the data item in whose definition the clause appears will be presented only in very limited circumstances.
@enumerate
@item
This clause may only appear within a @code{DETAIL} report group (@pxref{TYPE}).

@item
When this clause is present, the data item in question will be presented only under the following circumstances:
@enumerate A
@item
On the first presentation of the detail group following the @syntaxref{INITIATE} of the report.

@item
On the first presentation of the detail group after every new page is started.

@item
On the first presentation of the detail group after any control break occurs.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 6.9.23 HIGHLIGHT                                                **
@comment *********************************************************************
@page
@newsubsection{HIGHLIGHT}
@diagram{HIGHLIGHT Attribute,DD-HIGHLIGHT,DD-HIGHLIGHT,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause controls the intensity of text (@syntaxref{FOREGROUND-COLOR}) by setting that intensity to its highest of three possible settings.
@enumerate
@item
This clause, along with @syntaxref{LOWLIGHT}, are intended to provide a three-level intensity scheme (@code{LOWLIGHT} @dots{} nothing (Normal) @dots{} @code{HIGHLIGHT}).
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.24 JUSTIFIED                                                **
@comment *********************************************************************
@page
@newsubsection{JUSTIFIED}
@diagram{JUSTIFIED Attribute,DD-JUSTIFIED,DD-JUSTIFIED,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{REPORT}, @code{SCREEN}

The presence of a @code{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' behaviour to 'right justified, space filled'. Unless you are using any of the IBM dialects, it has NO effect on the initial content of a variable, eg:
@verbatim
01  A PIC X(12) JUST RIGHT VALUE 'ABC'.

Will show content as 'ABC' with NO justification taken place.
@end verbatim

@enumerate
@item
The reserved word @code{RIGHT} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
The reserved word @code{JUSTIFIED} may be abbreviated as @code{JUST}.

@item
This clause is valid only on alphabetic (@code{PIC A}) or alphanumeric (@code{PIC X}) data items.

@item
The presence or absence of this clause influences the behaviour of the @syntaxref{MOVE} statement as well as the @syntaxref{FROM}, @syntaxref{SOURCE} and @syntaxref{USING} data item description clauses.

@item
If the value being stored into the field is the same length as the receiving field, the presence or absence of the @code{JUSTIFIED RIGHT} clause on that field's description is irrelevant.

@item
The following examples illustrate the behaviour of the presence and absence of the @code{JUSTIFIED RIGHT} clause when the field size is different than that of the value being stored.  In these examples, the symbol @i{b} represents a space.

@cartouche
When the value is @i{shorter} than the field size:

@multitable @columnfractions .5 .5
@headitem Without @code{JUSTIFIED} @tab With @code{JUSTIFIED}
@item
@verbatim
01  A PIC X(6).
MOVE 'ABC' TO A
@end verbatim
@tab
@verbatim
01  A PIC X(6) JUSTIFIED RIGHT.
MOVE 'ABC' TO A
@end verbatim
@end multitable

@multitable @columnfractions .5 .5
@headitem Result @tab Result
@item @code{ABC@var{bbb}} @tab @code{@var{bbb}ABC}
@end multitable
@end cartouche

@cartouche
When the value is @i{longer} than the field size:

@multitable @columnfractions .5 .5
@headitem Without @code{JUSTIFIED} @tab With @code{JUSTIFIED}
@item
@verbatim
01  A PIC X(6).
MOVE 'ABCDEFGHI' TO A
@end verbatim
@tab
@verbatim
01  A PIC X(6) JUSTIFIED RIGHT.
MOVE 'ABCDEFGHI' TO A
@end verbatim
@end multitable

@multitable @columnfractions .5 .5
@headitem Result @tab Result
@item
     @code{ABCDEF}
@tab @code{DEFGHI}
@end multitable
@end cartouche
@end enumerate
@comment *********************************************************************
@comment ** 6.9.25 LEFTLINE                                                 **
@comment *********************************************************************
@page
@newsubsection{LEFTLINE}
@diagram{LEFTLINE Attribute,DD-LEFTLINE,DD-LEFTLINE,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{LEFTLINE} clause will introduce a vertical line at the left edge of a screen field.
@enumerate
@item
The @code{LEFTLINE}, @syntaxref{OVERLINE} and @syntaxref{UNDERLINE} clauses may be used in any combination in a single field's description.

@item
This clause is essentially non-functional when used within Windows command shell (cmd.exe) environments and running programs compiled using a GnuCOBOL implementation built using ``PDCurses'' (such as Windows/MinGW builds).

@item
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.
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.26 LENGTH-CHECK                                             **
@comment *********************************************************************
@page
@newsubsection{LENGTH-CHECK}
@diagram{LENGTH-CHECK Attribute,DD-LENGTH-CHECK,DD-LENGTH-CHECK,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{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.
@enumerate
@item
The @syntaxref{FULL} and @code{LENGTH-CHECK} clauses are interchangeable, and may not be used together in the same data item description.

@item
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.

@item
The @statementref{ACCEPT 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 @code{ACCEPT}, however.

@item
In order to be functional, this attribute must be supported by the underlying ``curses'' package your GnuCOBOL implementation was built with.  As of this time, the ``PDCurses'' package (used for native Windows or MinGW builds) does not support @code{LENGTH-CHECK}.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.27 LINE                                                     **
@comment *********************************************************************
@page
@newsubsection{LINE}
@diagram{LINE (REPORT SECTION) Clause,DD-LINE-1,DD-LINE-1,None}
@diagram{LINE (SCREEN SECTION) Clause,DD-LINE-2,DD-LINE-2,None}
This syntax is valid in the following sections:
@code{REPORT}, @code{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).
@enumerate
@item
The reserved words @code{IS}, @code{NUMBER} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The following points document the use of format 1 of the @code{LINE} clause:
@enumerate A
@item
The column location of a report item will be determined by the @syntaxref{COLUMN} clause.

@item
The value of @var{integer-1} must be 1 or greater.

@item
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{i.e.} @code{LINE 5}) or on a relative basis based upon the previously-displayed line (@i{i.e.} @code{LINE PLUS 1}).

@item
The symbol @samp{+} may be used in lieu of the word @code{PLUS}, if desired; if @samp{+} is used, however, there must be at least one space separating it from @var{integer-1}.  Failure to include this space will cause the @samp{+} to be simply treated as part of @var{integer-1} and will treat the LINE clause as an absolute line specification rather than a relative one.

@item
The optional
@syntaxidx{NEXT PAGE} clause specifies that --- regardless of whether or not the report group containing this clause @i{could} fit on the report page being currently generated, the report group will be @i{forced} to appear on a new page.
@end enumerate
@item The following points document the use for format 2 of the @code{LINE} clause:
@enumerate A
@item
The column location of a screen section field is determined by the @syntaxref{COLUMN} clause.

@item
The value of @var{integer-1} must be 1 or greater.

@item
If @var{identifier-1} is used to specify either an absolute or relative column position, @var{identifier-1} must be defined as a numeric item of any @syntaxref{USAGE} other than @code{COMPUTATIONAL-1} or @code{COMPUTATIONAL-2}, without editing symbols.  The value of @var{identifier-1} at the time the screen data item is presented must be 1 or greater.  Note that a @code{COMPUTATIONAL-1} or @code{COMPUTATIONAL-2} identifier will be accepted by the compiler, but will produce unpredictable results at run-time.

@item
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{i.e.} @code{LINE 5}) or on a relative basis based upon the previously-displayed line (@i{i.e.} @code{LINE PLUS 1}).

@item
The symbol @samp{+} may be used in lieu of the word @code{PLUS}, if desired; if @samp{+} is used, however, there must be at least one space separating it from @var{integer-1}.  Failure to include this space will cause the @samp{+} to be simply treated as part of @var{integer-1} and will treat the @code{LINE} clause as an absolute line specification rather than a relative one.

@item
If a screen data item's description includes the @syntaxref{FROM}, @syntaxref{TO}, @syntaxref{USING} or @syntaxref{VALUE} clause but has no LINE clause, the ``current screen line'' will be assumed.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 6.9.27B LOWER                                                   **
@comment *********************************************************************
@page
@newsubsection{LOWER}
@diagram{LOWER Attribute,DD-LOWER,DD-LOWER,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause provides a means of explicitly stating that accepted data will be in lower case.

@comment *********************************************************************
@comment ** 6.9.28 LOWLIGHT                                                 **
@comment *********************************************************************
@page
@newsubsection{LOWLIGHT}
@diagram{LOWLIGHT Attribute,DD-LOWLIGHT,DD-LOWLIGHT,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{LOWLIGHT} clause controls the intensity of text (@code{FOREGROUND-COLOR}) by setting that intensity to its lowest of three possible settings.
@enumerate
@item
This clause, along with @syntaxref{HIGHLIGHT}, are intended to provide a three-level intensity scheme (@code{LOWLIGHT} @dots{} nothing (Normal) @dots{} @code{HIGHLIGHT}).  In environments such as a Windows console where only two levels of intensity are supported, @code{LOWLIGHT} is the same as leaving this clause off altogether.
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.29 NEXT GROUP                                               **
@comment *********************************************************************
@page
@newsubsection{NEXT GROUP}
@diagram{NEXT-GROUP Clause,DD-NEXT-GROUP,DD-NEXT-GROUP,None}
This syntax is valid in the following sections:
@code{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 @i{last} line of the group in which this clause appears.
@enumerate
@item
The reserved word @code{IS} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
The terms
@syntaxidx{NEXT},
@syntaxidx{NEXT PAGE} and
@syntaxidx{PAGE} are interchangeable.

@item
A report group must contain at least one @code{LINE NUMBER} clause in order to also contain a @code{NEXT GROUP} clause.

@item
If the @code{RD} (@pxref{REPORT SECTION}) in which the report group containing a @code{NEXT GROUP} clause does not contain a @code{PAGE LIMITS} clause, only the @code{PLUS integer-1} option may be specified.

@item
The @code{NEXT PAGE} option cannot be used in a @code{PAGE FOOTING}.

@item
The @code{NEXT GROUP} option cannot be specified in either a @code{REPORT HEADING} or a @code{PAGE HEADING}.

@item
The effects of @code{NEXT GROUP} will be in addition to any line spacing defined by the next-presented group's @code{LINE NUMBER} clause.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.30 NO ECHO                                                  **
@comment *********************************************************************
@page
@newsubsection{NO-ECHO}
@diagram{NO-ECHO Attribute,DD-NO-ECHO,DD-NO-ECHO,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{NO-ECHO} clause will cause all data entered into the field to appear on the screen as spaces.
@enumerate

@item
If @code{NO-ECHO} is present then the @code{PROMPT} clause is ignored.

@item
If the dialect configuration -fno-echo-means-secure is active all data entered into the field will appear on the screen as asterisks. In this case the @code{NO-ECHO} and @code{SECURE} clauses are interchangeable.

@item
The @code{NO-ECHO} and @syntaxref{SECURE} clauses may not be used together in the same data item description.

@item
This clause may only be used on a field allowing data entry (a field containing either the @syntaxref{USING} or @syntaxref{TO} clause).
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.30B NO UPDATE                                               **
@comment *********************************************************************
@page
@newsubsection{NO UPDATE}
@diagram{NO-UPDATE Attribute,DD-NO-UPDATE,DD-NO-UPDATE,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{NO UPDATE} clause forces the field to which this is applied will not be updated. ?? MORE ??.

@comment *********************************************************************
@comment ** 6.9.31 OCCURS                                                   **
@comment *********************************************************************
@page
@newsubsection{OCCURS}
@diagram{OCCURS Clause,DD-OCCURS-1,DD-OCCURS-1,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{REPORT}, @code{SCREEN}

The @code{OCCURS} clause is used to create a data structure called a table, where entries in that structure repeat multiple times.
@enumerate
@item
The reserved words @code{BY} (INDEXED), @code{IS}, @code{KEY}, @code{ON} and @code{TIMES} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The value of @var{integer-2} specifies how many entries will be allocated in the table.

@item
The following is an example of how a table might be defined:

@example
05 QUARTERLY-REVENUE OCCURS 4 TIMES PIC 9(7)V99.
@end example

This will allocate the following:

@example
QUARTERLY-REVENUE(1)
QUARTERLY-REVENUE(2)
QUARTERLY-REVENUE(3)
QUARTERLY-REVENUE(4)
@end example

Each occurrence is referenced using the subscript syntax (a numeric literal, arithmetic expression or numeric identifier enclosed within parenthesis) shown above.

@item
The @code{OCCURS} clause may be used at the group level too, in which case the entire group structure repeats, as follows:

@example
05 GRP OCCURS 3 TIMES.
    10 A     PIC X(1).
    10 B     PIC X(1).
    10 C     PIC X(1).
@end example

This would allow references to any of the following:

@example
GRP(1)   @r{includes A(1), B(1) and C(1)}
GRP(2)   @r{includes A(2), B(2) and C(2)}
GRP(3)   @r{includes A(3), B(3) and C(3)}
@end example

or each A,B,C item could be referenced as follows:

@example
A(1)   @r{character #1 of} GRP(1)
B(1)   @r{character #2 of} GRP(1)
C(1)   @r{character #3 of} GRP(1)
A(2)   @r{character #1 of} GRP(2)
B(2)   @r{character #2 of} GRP(2)
C(2)   @r{character #3 of} GRP(2)
A(3)   @r{character #1 of} GRP(3)
B(3)   @r{character #2 of} GRP(3)
C(3)   @r{character #3 of} GRP(3)
@end example

@item
The optional
@syntaxidx{DEPENDING ON} clause can be added to an @code{OCCURS} to create a variable-length table.  In such cases, the value of @var{integer-1} specifies what the minimum number of entries in the table will be while @var{integer-2} specifies the maximum.  Such tables will be allocated out to the maximum size specified as @var{integer-2}.  At execution time the value of @var{identifier-1} will determine how many of the table elements are accessible.

@item
See the documentation of the @syntaxref{SEARCH}, @syntaxref{SEARCH ALL} and @syntaxref{SORT} statements for explanations of the
@syntaxidx{KEY} and
@syntaxidx{INDEXED BY} clauses.

@item
The @code{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 @i{subordinate} to an 01-level data item.

@item
The following points apply to an @code{OCCURS} used in the report section:
@enumerate A
@item
The optional
@syntaxidx{STEP} clause defines an incrementation value that will be added to any absolute @syntaxref{LINE} or @syntaxref{COLUMN} number specifications that may be part of or subordinate to this data item's definition.

@item
The optional
@syntaxidx{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 @syntaxref{SOURCE} or @syntaxref{SUM} clause(s) on this or subordinate data items reference entries within the table.  The @var{identifier-2} data item is dynamically created as needed and cannot be referenced outside the scope of the report data item definition.

@item
The following two examples illustrate two different ways a report could include four quarters worth of sales figures in its detail lines --- one doing things 'the hard way' and one using the advanced @code{OCCURS} capabilities of @code{STEP} and @code{VARYING}.  Both assume the definition of the following table exists in working-storage:

@center @t{05 SALES OCCURS 4 TIMES PIC 9(7)V99.}

First, the ``Hard Way'':

@example
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).
@end example

And then using @code{STEP} and @code{VARYING}:

@example
10 COL 7  OCCURS 4 TIMES STEP 10 VARYING QTR FROM 1 BY 1
          PIC $(7)9.99 SOURCE SALES(QTR).
@end example
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 6.9.32 OVERLINE                                                 **
@comment *********************************************************************
@page
@newsubsection{OVERLINE}
@diagram{OVERLINE Attribute,DD-OVERLINE,DD-OVERLINE,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{OVERLINE} clause will introduce a horizontal line at the top edge of a screen field.
@enumerate
@item
The @syntaxref{LEFTLINE}, @code{OVERLINE} and @syntaxref{UNDERLINE} clauses may be used in any combination in a single field's description.

@item
This clause is essentially non-functional when used within Windows command shell (cmd.exe) environments and running programs compiled using a GnuCOBOL implementation built using ``PDCurses'' (such as Windows/MinGW builds).

@item
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.
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.33 PICTURE                                                  **
@comment *********************************************************************
@page
@newsubsection{PICTURE}
@diagram{PICTURE Clause,DD-PICTURE,DD-PICTURE,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{REPORT}, @code{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 @syntaxref{USAGE} clause, and in a few instances will be assumed entirely by that clause.
@enumerate
@item
The reserved word @code{IS} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
The reserved word @code{PICTURE} may be abbreviated as @code{PIC}.  Most programmers prefer to use the latter.

@item
A picture clause may only be specified on an elementary item.

@item
A @var{picture-string} is a sequence of the special symbols @samp{$}, @samp{*}, @samp{+}, @samp{,}, @samp{-}, @samp{.}, @samp{/}, @samp{0} (zero), @samp{1}, @samp{9}, @samp{A}, @samp{B}, @code{CR}, @code{DB}, @samp{S}, @samp{V}, @samp{P}, @samp{X} and @samp{Z}.

@item
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.

@item
When a @var{picture-string} contains a repeated sequence of symbols --- @code{PIC 9999/99/99} --- for example, the repetition can be specified using a parenthetic repeat count, as in @code{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 (@code{PIC XXX}) and repeat counts for larger ones (@code{PIC 9(9)}.

@item
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.
@table @asis
@item @samp{A}
Defines storage reserved for a single alphabetic character (@samp{A}-@samp{Z}, @samp{a}-@samp{z}).

@item @samp{N}
Defines storage reserved for a single character in the computer's
@define{National Character set}.  Support for national character sets in GnuCOBOL is currently only partially implemented, and the compile- and run-time effect of using the @samp{N} picture symbol is the same as if @code{X(2)} had been coded, with the additional effect that such a field will qualify as a @code{NATIONAL} or @code{NATIONAL-EDITED} field on an @syntaxref{INITIALIZE} statement.

@item @samp{X}
Defines storage reserved for a single alphanumeric character (any character).

@item @samp{9}
Defines storage reserved for a single numeric digit character (@samp{0}-@samp{9}).
@end table

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 @samp{A} picture symbols are known as
@define{Alphabetic Data Items} while those that use @samp{9} picture symbols without any @samp{A} or @samp{X} symbols (or those that have a @code{USAGE} without a @code{PICTURE}) are known as
@define{Numeric Data Items}.  All other data items are referred to as
@define{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 @var{picture-string} @code{AA99999AAA}, @code{A(2)9(5)A(3)} @code{XXXXXXXXXX} or @code{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 @i{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 @syntaxref{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 (@pxref{Class Conditions}) to determine if the contents of a data item are entirely numeric or entirely alphabetic.

@item @samp{1}
Defines storage for a single bit representing a boolean condition with a states of zero or 1, condition of off or on. Warning the level of implementation of this feature is compiler version specific starting with v3.1-RC-1.

@item
The following picture symbols may be used with numeric data items.
@table @asis
@item @samp{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 @samp{P}) to exist at the end of values.

The @samp{P} symbol is not allowed in conjunction with @samp{N}.

The @samp{P} symbol may only be used at the beginning or end of a picture clause.

@samp{P} is a repeatable symbol.

All computations and @syntaxref{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:

@t{01  Gross-Revenue    PIC 9(9).}

In which case 9 characters of storage will be reserved.  The values 000000000 through 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:

@t{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 @code{@var{nnn}000000}, where @code{@var{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 @samp{P}s were @samp{9}s:

@example
MOVE 128000000 TO Gross-Revenue
@end example

A @syntaxref{DISPLAY} of a data item containing @samp{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 @samp{P} symbols had been @samp{9}s.  Thus, after the above statement established a value for Gross-Revenue, a @code{DISPLAY Gross-Revenue} would produce output of @samp{000000128}.

@item @samp{S}
This symbol, if used, must be the very first symbol in the @code{PICTURE} value.  A @samp{S} indicates that the data item is @code{Signed}, meaning that negative values are possible for this data item.  Without an @samp{S}, any negative values stored into this data item via a @code{MOVE} or arithmetic statement will have the negative sign stripped from it (in effect becoming the absolute value).

The @samp{S} symbol is not allowed in conjunction with @samp{N}.

The @samp{S} symbol may only occur once in a picture string.  @xref{SIGN IS}, for further discussion of how negative values may be stored in a numeric data item.

@item @samp{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 @samp{V} in a @code{PICTURE}.  Implied decimal points occupy no space in storage --- they just specify how values are used.  For example, if the value @code{1234} is in storage in a field defined as @code{PIC 999V9}, that value would be treated as 123.4 in any statements that referenced it.

The @samp{V} symbol is not allowed in conjunction with @samp{N}.

The @samp{V} symbol may only occur once in a picture string.
@end table

@item
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
@define{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.

@item
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.
@table @asis

@item @samp{B}
The @samp{B} editing symbol introduces a blank into the field value for each occurrence.

Multiple @samp{B} symbols may be coded.

The following example will format a ten digit number (presumably a telephone number) into a @samp{### ### ####} layout:
@verbatim
    ...
        05 Phone-Number       PIC 9(3)B9(3)B9(4).
    ...
        MOVE 5185551212 TO Phone-Number
        DISPLAY Phone-Number
@end verbatim

This code will display @samp{518 555 1212}.

@item @samp{0}
The @samp{0} (zero) editing symbol introduces one ``0'' character into the field value for each occurrence in the picture string.

Multiple @samp{0} symbols may be coded.

Here's an example:
@verbatim
    ...
        05  Output-Item     PIC 909090909.
    ...
        MOVE 12345 TO Output-Item
        DISPLAY Output-Item
@end verbatim

The above will display @samp{102030405}.

@item @samp{/}
The @samp{/} editing symbol inserts one ``/'' character into the field value for each occurrence in the picture string.

Multiple @samp{/} symbols may be coded.

This editing symbol is most-frequently used to format dates, as follows:
@verbatim
    ...
        05  Year-Month-Day   PIC 9(4)/9(2)/9(2).
    ...
        MOVE 20140207 TO Year-Month-Day
        DISPLAY Year-Month-Day
@end verbatim

This example displays @samp{2014/02/07}.
@end table

@item
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.
@table @asis
@item @samp{.}
The @samp{.} 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 @samp{.} editing symbol, implied (@samp{V}) or actual decimal point in the sending data item or literal, respectively, will be aligned with the @samp{.} symbol in the receiving field.  Digits are then transferred from the sending to the receiving field outward from the sending field's @samp{V} or @samp{.}, 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 @samp{.} symbol is not allowed in conjunction with @samp{N}.

An example will probably help:
@verbatim
    ...
    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
@end verbatim

The example will display three results --- @samp{34567.89}, @samp{00019.00} and @samp{00007.20}.

Both data item definitions @i{appear} to have @i{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.

@item @samp{,}
The @samp{,} 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 @samp{9}s.

The @samp{,} symbol is not allowed in conjunction with @samp{N}.

Here's an example:
@verbatim
    ...
    05  My-Lottery-Winnings   PIC 9(3),9(3),9(3).
    ...
    MOVE 12345 TO My-Lottery-Winnings
    DISPLAY My-Lottery-Winnings
@end verbatim

The value @samp{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 meagre amount I won, it behaved like another @samp{9}.
@end table

If desired, you may reverse the roles of the @samp{.} and @samp{,} editing symbols by specifying @code{DECIMAL POINT IS COMMA} in the @syntaxref{SPECIAL-NAMES} paragraph.

@item
The following are insertion symbols.  They are used to insert an extra character (two in the case of @code{CR} and @code{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 @samp{+}, @samp{-}, @code{CR} or @code{DB} symbols may be used in a picture clause. In this context, when any of these symbols are used in a @var{picture-string}, they must be at the end.  The @samp{+}, @samp{-} and/or currency symbols may also be used as floating editing symbols at the @i{beginning} of the @var{picture-string} --- a subject that will be covered in the next numbered paragraph.
@table @asis
@item @samp{+}
If the value of the numeric value moved into the field is positive (0 or greater), a @samp{+} character will be inserted.  If the value is negative (less than 0), a @samp{-} character is inserted.

The @samp{+} symbol is not allowed in conjunction with @samp{N}.

@item @samp{-}
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 @samp{-} character is inserted.

The @samp{-} symbol is not allowed in conjunction with @samp{N}.

@item @code{CR}
This symbol is coded as the two characters @samp{C} and @samp{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 @code{CR} (credit) are inserted.

The @code{CR} symbol is not allowed in conjunction with @samp{N}.

@item @code{DB}
This symbol is coded as the two characters @samp{D} and @samp{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 @code{DB} (debit) are inserted.

The @code{DB} symbol is not allowed in conjunction with @samp{N}.

@item @samp{$}
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 @var{picture-string} (@pxref{SPECIAL-NAMES}).

The @samp{$} symbol is not allowed in conjunction with @samp{N}.
@end table
@item
These editing symbols are known as floating replacement symbols.  These symbols may occur in sequences @i{before} any @samp{9} editing symbols in the @var{picture-string} of a numeric data item.  Using these symbols transforms that numeric data item into a numerid @i{edited} data item, which can no longer be used in calculations or subscripts.

@item
Each of the following symbols behave like a @samp{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.
@table @asis
@item @samp{$}
Of those currency symbols that correspond to character positions in which leading zeros reside, the right-most will have its @samp{0} value replaced by the currency symbol in-effect for the program (@pxref{SPECIAL-NAMES}).  Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces.

The @samp{$} symbol is not allowed in conjunction with @samp{N}.

Any currency symbol coded to the right of a @samp{.} will be treated exactly like a @samp{9}.

@item @samp{*}
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 @samp{0} values replaced by @samp{*}.

The @samp{*} symbol is not allowed in conjunction with @samp{N}.

Any check-suppression symbol coded to the right of a @samp{.} will be treated exactly like a @samp{9}.

@item @samp{+}
Of those @samp{+} symbols that correspond to character positions in which leading zeros reside, the right-most will have its @samp{0} value replaced by a @samp{+} if the value in the data item is zero or greater or a @samp{-} otherwise.  Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces.  You cannot use both @samp{+} and @samp{-} in the same @var{picture-string}.

The @samp{+} symbol is not allowed in conjunction with @samp{N}.

Any @samp{+} symbol coded to the right of a @samp{.} will be treated exactly like a @samp{9}.

@item @samp{-}
Of those @samp{-} symbols that correspond to character positions in which leading zeros reside, the right-most will have its @samp{0} value replaced by a space if the value in the data item is zero or greater or a @samp{-} otherwise.  Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces.  You cannot use both @samp{+} and @samp{-} in the same @var{picture-string}.

The @samp{-} symbol is not allowed in conjunction with @samp{N}.

Any @samp{-} symbol coded to the right of a @samp{.} will be treated exactly like a @samp{9}.

@item @samp{Z}
All @samp{Z} symbols that correspond to character positions in which leading zeros reside will have their @samp{0} values replaced by spaces.

Any zero-suppression symbol coded to the right of a @samp{.} will be treated exactly like a @samp{9}.
@end table

@samp{Z} and @samp{*} should not be coded in the same @var{picture-string}

@samp{+} and @samp{-} should not be coded in the same @var{picture-string}

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 @code{PIC +$ZZZZ9.99} @var{picture-string}, and a value of 1 is moved to that field at run-time, the resulting value will be (the @i{b} symbol represents a space) @code{@i{bbbb}+$1.00}.  This is not consistent with many other COBOL implementations, where the result would have been @code{+$@i{bbbb}1.00}.

Most other COBOL implementations reject the use of multiple occurrences of multiple floating editing symbols.  For example, they would reject @var{picture-string}s such as @code{+++$$$9.99}, @code{$$$ZZZ9.99} and so on.  GnuCOBOL accepts these.  Programmers creating GnuCOBOL programs should avoid such @var{picture-string}s if there is any likelihood that those programs may be used with other COBOL implementations.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.34 PRESENT WHEN                                             **
@comment *********************************************************************
@page
@newsubsection{PRESENT WHEN}
@diagram{PRESENT-WHEN Clause,DD-PRESENT-WHEN,DD-PRESENT-WHEN,None}
This syntax is valid in the following sections:
@code{REPORT}

This clause names an existing @code{Condition Name} (@pxref{Condition Names}) that will serve as a switch controlling the presentation or suppression of a report group.
@enumerate
@item
If the specified condition-name has a value of FALSE when a @statementref{GENERATE} causes a report group to be presented, the presentation of that group will be suppressed.

@item
If the condition-name has a value of @code{TRUE}, the group will be presented.

@item
@xref{Condition Names}, for more information.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.35 PROMPT                                                   **
@comment *********************************************************************
@page
@newsubsection{PROMPT}
@diagram{PROMPT Clause,DD-PROMPT,DD-PROMPT,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause defines the character that will be used as the fill-character for any input fields on the screen.
@enumerate
@item
The reserved word @code{IS} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
The default prompt character, should no @code{CHARACTER} specification be coded, or should the @code{PROMPT} clause be absent altogether, is an underscore (@samp{_}).

@item
Prompt characters will be automatically transformed into spaces upon input.
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.36 PROTECTED                                                **
@comment *********************************************************************
@page
@newsubsection{PROTECTED}
@diagram{PROTECTED Attribute,DD-PROTECTED,DD-PROTECTED,None}
This syntax is valid in the following sections:
@code{SCREEN}
@enumerate

The @code{PROTECTED} extended clause will effect the specified field to be limited in size, regardless of the picture size.@footnote{OR DOES IT? @i{author uncertain}}

@item
The SIZE phrase specifies the size (length) of the field. After the @code{ACCEPT} or @code{DISPLAY} is finished, the cursor is placed immediately after the field defined by this clause, unless this would place the cursor outside of the current terminal window. In this case, the cursor is wrapped around to the beginning of the next line (scrolling the window if necessary).

@item
If the @code{SIZE} phrase is not used, then the field length defaults to the size of the item being accepted or displayed. If the @code{CONVERT} phrase is used, however, then the size of the field depends on the data type of the item and the verb being used.
@enumerate A
@item
If the @code{DISPLAY} verb is executing, then the size is the same as if the @code{CONVERT} phrase were not specified except for numeric items. For numeric items, the size is the number of digits in the item, plus one if it is not an integer, plus one if it is signed. The remaining cases cover the size when an @code{ACCEPT} statement is used.

@item
If the item is numeric or numeric edited, then the size is the number of digits in the item, plus one if it is not an integer, plus one if it is signed.

@item
If the item is alphanumeric edited, then the size is set to the number of @samp{A} or @samp{X} positions specified in its @code{PICTURE} clause.

@item
For all other data types, the field size is set to the size of the item (same as if @code{CONVERT} were not specified).
@end enumerate

@item
Note that the @code{OUTPUT} phrase changes the way in which the default field size is computed. See that heading above for details. Also note that the @code{OUTPUT} phrase affects only the way items are displayed on the screen; the internal format of accepted data is not affected.

@item
Note that you cannot supply the @code{CONVERT} phrase in the Screen Section. Thus the size of a Screen Section field is always the size of its screen entry unless the @code{SIZE} phrase is specified.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.37 REDEFINES                                                **
@comment *********************************************************************
@page
@newsubsection{REDEFINES}
@diagram{REDEFINES Clause,DD-REDEFINES,DD-REDEFINES,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}

The @code{REDEFINES} clause causes the data item in who's definition the @code{REDEFINES} clause is specified (hereafter referred to as the redefines object) to occupy the same physical storage space as @var{identifier-1} (hereafter referred to as the redefines subject).
@enumerate
@item
The following rules must all be followed in order to use @code{REDEFINES}:
@enumerate A
@item
The level number of both the subject and object data items must be the same.

@item
The level numbers of both the subject and object data items cannot be 66, 78 or 88.

@item
If @i{N} represents the level number of the object, then no other data items with level number @i{N} may be defined between the subject and object data items unless they too are @code{REDEFINES} of the subject.

@item
If @i{N} represents the level number of the object, then no other data items with a level number numerically less than @i{N} may be defined between the subject and object data items.

@item
The total allocated size of the subject data item must be the same as the total allocated size of the object data item.

@item
No @syntaxref{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 @i{contain} data items with @code{OCCURS} clauses.

@item
No @syntaxref{VALUE} clause may be defined on the object data item, and no data items subordinate to the object data item may have @code{VALUE} clauses, with the exception of level-88 condition names.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 6.9.38 RENAMES                                                  **
@comment *********************************************************************
@page
@newsubsection{RENAMES}
@diagram{RENAMES Clause,DD-RENAMES,DD-RENAMES,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}

The @code{RENAMES} clause regroups previously defined items by specifying alternative, possibly overlapping, groupings of elementary data items.
@enumerate
@item
The reserved words @code{THRU} and @code{THROUGH} are interchangeable.

@item
You must use the level number 66 for data description entries that contain the @code{RENAMES} clause.

@item
The @var{identifier-1} and @var{identifier-2} 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.

@item
@xref{66-Level Data Items}, for additional information on the @code{RENAMES} clause.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.39 REQUIRED                                                 **
@comment *********************************************************************
@page
@newsubsection{REQUIRED}
@diagram{REQUIRED Attribute,DD-REQUIRED,DD-REQUIRED,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if @code{REQUIRED} is specified on a group item).
@enumerate
@item
The @syntaxref{EMPTY-CHECK} and @code{REQUIRED} clauses are interchangeable, and may not be used together in the same data item description.

@item
In order to take effect, the user must first move the cursor into the field having this clause in its definition.

@item
The @statementref{ACCEPT data-item} will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item @i{unless} data has been entered into the field.  Function keys will still be allowed to terminate the @code{ACCEPT}.

@item
In order to be functional, this attribute must be supported by the underlying ``curses'' package your GnuCOBOL implementation was built with.  As of this time, the ``PDCurses'' package (used for native Windows or MinGW builds) does not support @code{REQUIRED}.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.40 REVERSE-VIDEO                                            **
@comment *********************************************************************
@page
@newsubsection{REVERSE-VIDEO}
@diagram{REVERSE-VIDEO Attribute,DD-REVERSE-VIDEO,DD-REVERSE-VIDEO,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{REVERSE-VIDEO} attribute swaps the specified or implied @syntaxref{FOREGROUND-COLOR} and @syntaxref{BACKGROUND-COLOR} attributes for the field whose definition contains this clause (or all subordinate fields if used on a group item).

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.

@comment *********************************************************************
@comment ** 6.9.41 SAME AS                                                  **
@comment *********************************************************************
@page
@newsubsection{SAME AS}
@diagram{SAME-AS Clause,DD-SAME-AS,DD-SAME-AS,None}
The syntax is valid in the following sections:
@code{WORKING-STORAGE}

The @code{SAME AS} causes a data item to inherit the same definition of another data item.

@enumerate
@item
Data-name-1 is a data Item defined elsewhere in the same program.
@item
Data-name-1 shall not be subscripted.
@item
A data description entry that specifies the SAME AS clause shall not be immediately followed by a subordinate data description entry or level 88 entry.
@item
Neither the description of data-name-1 nor the description of any data items subordinate to the subject of the entry shall directly or indirectly contain a SAME AS clause that references the subject of the entry or any group item to which this entry is subordinate.
@item
The description of data-name-1, including its subordinate data items, shall not contain a TYPE clause that references the record to which this entry is subordinate.
@item
The description of data-name-1 shall not contain an OCCURS clause. However, items subordinate to data-name-1 may contain OCCURS clauses.
@item
Data-name-1 shall reference an elementary item or a level 1 group item described in the file, working-storage, local-storage, or linkage section.
@item
If the subject of the entry is a level 77 item, data-name-1 shall reference an elementary item.
@item
A group item to which the subject of the entry is subordinate shall not contain a GROUP-USAGE, SIGN, or USAGE clause.
@item
The effect of the SAME AS clause is as though the data description identified by data-name-1 had been coded in place of the SAME AS clause, excluding the level number, name, and the EXTERNAL, GLOBAL, REDEFINES clauses specified for data-name-1; level numbers of subordinate items may be adjusted as described in general rule 2.
@item
If data-name-1 describes a group item:
@item
the subject of the entry is a group whose subordinate elements have the same names, descriptions, and hierarchy as the subordinate elements of data-name-1, the level numbers of items subordinate to that group are adjusted, if necessary, to preserve the hierarchy of data-name-1, level numbers in the resulting hierarchy may exceed 49.

@example

       IDENTIFICATION   DIVISION.
       PROGRAM-ID.      prog.
       DATA             DIVISION.

       WORKING-STORAGE  SECTION.
       01 MESSAGE-TEXT-2 EXTERNAL.
            02 MAIN-FILE-NAME     PIC X(50).
            02 FILLER REDEFINES MAIN-FILE-NAME.
                05 FILLER PIC 9999.
            02 MAIN-FILE-NAME-2.
                05 FILLER PIC 9999.
                05 DETAIL-NO PIC 9999.
           02 FILLER         SAME AS MAIN-FILE-NAME.
       77 OUTPUT-NAME     SAME AS DETAIL-NO GLOBAL.
       01 Z-MESSAGE-T2    SAME AS MAIN-FILE-NAME-2.
       01 Z-MESSAGE-T3.
             49 MT3                    SAME AS MESSAGE-TEXT-2.
             49 MT3-REN  REDEFINES MT3 SAME AS MESSAGE-TEXT-2.

       PROCEDURE DIVISION.
           DISPLAY MAIN-FILE-NAME OF MESSAGE-TEXT-2
           DISPLAY DETAIL-NO      OF Z-MESSAGE-T2
           DISPLAY MAIN-FILE-NAME OF MT3
           DISPLAY OUTPUT-NAME
           GOBACK.

@end example
@end enumerate
@comment *********************************************************************
@comment ** 6.9.41B SCROLL DOWN                                             **
@comment *********************************************************************
@page
@newsubsection{SCROLL DOWN}
@diagram{SCROLL-DOWN Attribute,DD-SCROLL-DOWN,DD-SCROLL-DOWN,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause will cause downward scrolling.
@comment *********************************************************************
@comment ** 6.9.41C SCROLL UP                                               **
@comment *********************************************************************
@page
@newsubsection{SCROLL UP}
@diagram{SCROLL-UP Attribute,DD-SCROLL-UP,DD-SCROLL-UP,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause will cause upward scrolling.  MORE HERE ??

@comment *********************************************************************
@comment ** 6.9.42 SECURE                                                   **
@comment *********************************************************************
@page
@newsubsection{SECURE}
@diagram{SECURE Attribute,DD-SECURE,DD-SECURE,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause will cause all data entered into the field to appear on the screen as asterisks.
@enumerate
@item
The @code{NO-ECHO} and @code{SECURE} clauses are interchangeable if If the dialect configuration -fno-echo-means-secure is active.

@item
The @code{NO-ECHO} and @code{SECURE} clauses may not be used together in the same data item description.

@item
This clause may only be used on a field allowing data entry (a field containing either the @syntaxref{USING} or @syntaxref{TO} clause).
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.43 SIGN IS                                                  **
@comment *********************************************************************
@page
@newsubsection{SIGN IS}
@diagram{SIGN-IS Clause,DD-SIGN-IS,DD-SIGN-IS,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{REPORT}, @code{SCREEN}

This clause, allowable only for @code{USAGE DISPLAY} numeric data items, specifies how an @samp{S} symbol will be interpreted in a data item's picture clause.
@enumerate
@item
The reserved words @code{CHARACTER} and @code{IS} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
@i{Without} the
@syntaxidx{SEPARATE CHARACTER} option, the sign of the data item's value will be encoded by transforming the last (see
@syntaxidx{TRAILING}) or first (see
@syntaxidx{LEADING}) digit as follows:

@multitable @columnfractions .25 .25 .25
@headitem First/Last Digit @tab Value For Positive @tab Value for Negative
@item 0 @tab 0 @tab p
@item 1 @tab 1 @tab q
@item 2 @tab 2 @tab r
@item 3 @tab 3 @tab s
@item 4 @tab 4 @tab t
@item 5 @tab 5 @tab u
@item 6 @tab 6 @tab v
@item 7 @tab 7 @tab w
@item 8 @tab 8 @tab x
@item 9 @tab 9 @tab y
@end multitable

@item
If the @code{SEPARATE CHARACTER} clause @i{is} used, then an actual @samp{+} or @samp{-} character will be inserted into the field's value as the first (@code{LEADING}) or last (@code{TRAILING}) character.  Note that having this character embedded within the data item's storage does not prevent the data item from being used as a source field in arithmetic operations.

@item
When @code{SEPARATE CHARACTER} is specified, the @samp{S} symbol in the data item's @code{PICTURE} must be counted when determining the data item's size.

@item
Neither the presence of an encoded digit (see above) nor an actual @samp{+} or @samp{-} character embedded within the data item's storage prevents the data item from being used as a source field in arithmetic operations.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.43B SIZE                                                    **
@comment *********************************************************************
@page
@newsubsection{SIZE}
@diagram{SIZE Clause,DD-SIZE,DD-SIZE,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause does WHAT EXACTLY ??????

@comment *********************************************************************
@comment ** 6.9.44 SOURCE                                                   **
@comment *********************************************************************
@page
@newsubsection{SOURCE}
@diagram{SOURCE Clause,DD-SOURCE,DD-SOURCE,None}
This syntax is valid in the following sections:
@code{REPORT}

This clause logically attaches a report section data item to another data item defined elsewhere in the data division.
@enumerate
@item
The reserved word @code{IS} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
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.

@item
The specified identifier may be defined anywhere in the data division, but if it is defined in the report section it may only be
@syntaxidx{PAGE-COUNTER},
@syntaxidx{LINE-COUNTER} or a @syntaxref{SUM} counter.

@item
The @syntaxref{PICTURE} of the report data item must be such that it would be legal to @syntaxref{MOVE} the specified literal or identifier to a data item with that @code{PICTURE}.

@item
The @code{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 @code{PICTURE} specified for the field in whose definition the @code{SOURCE} clause appears (the ``target field'').  @i{Without} @code{ROUNDED}, excess digits in the source value will simply be truncated to fit the target field.  @i{With} @code{ROUNDED}, the source value will be arithmetically rounded to fit the target field.  @xref{ROUNDED}, for information on the @code{NEAREST-AWAY-FROM-ZERO} rounding rule, which is the one that will apply.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.45 SUM OF                                                   **
@comment *********************************************************************
@page
@newsubsection{SUM OF}
@diagram{SUM-OF Clause,DD-SUM-OF-Info,DD-SUM-OF-TeX,None}
This syntax is valid in the following sections:
@code{REPORT}

The @code{SUM} clause establishes a summation counter whose value will be arithmetically calculated whenever the field is presented.
@enumerate
@item
The reserved words @code{OF} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The @code{SUM} clause may only appear in a @code{CONTROL FOOTING} report group.

@item
If the data item in which the @code{SUM} clause appears has been assigned its own identifier name, and that name is not @code{FILLER}, then that data item is referred to as a sum counter.

@item
All @var{identifier-7} data items must be non-edited numeric in nature.

@item
If any @var{identifier-7} data item is defined in the report section, it must be a sum counter.

@item
Any @var{identifier-7} data items that are sum counters must either be defined in the same report group as the data item in which this @code{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.  @xref{Control Hierarchy}, for additional information.

@item
The @code{PICTURE} of the report data item in who's description this @code{SUM} clause appears in must be such that it would be legal to @syntaxref{MOVE} the specified @var{identifier-7} or @var{literal-2} value to a data item with that @code{PICTURE}.

@item
The following points apply to the
@syntaxidx{UPON} option:
@enumerate A
@item
The data item @var{identifier-9} must be the name of a detail group specified in the same report as the control footing group in which this @code{SUM} clause appears.

@item
The presence of an @code{UPON} clause limits the @code{SUM} clause to adding the specified numeric literal or identifier value into the sum counter only when a @code{GENERATE @var{identifier-9}} statement is executed.

@item
If there is no @code{UPON} clause specified, the value of @var{identifier-7} or @var{literal-2} will be added into the sum counter whenever a @syntaxref{GENERATE} of any detail report group in the report is executed.

@item
If there is only a single detail group in the report's definition, the @code{UPON} clause is meaningless.
@end enumerate
@item
The following points apply to the
@syntaxidx{RESET} option:
@enumerate A
@item
If the @code{RESET} option is coded, @code{FINAL} or @var{identifier-8} (whichever is coded on the @code{RESET}) must be one of the report's control breaks specified on the @code{CONTROLS} clause.

@item
If there is no @code{RESET} option coded, the sum counter will be reset back to zero after each time the control footing containing the @code{SUM} clause is presented.  This is the typical behaviour that would be expected.

@item
If, however, you want to reset the @code{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 @code{RESET} option.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 6.9.46 SYNCHRONIZED                                              **
@comment *********************************************************************
@page
@newsubsection{SYNCHRONIZED}
@diagram{SYNCHRONIZED,DD-SYNCHRONIZED,DD-SYNCHRONIZED,DD-SYNC-LEFT-RIGHT}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{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.
@enumerate
@item
The reserved words @code{SYNCHRONIZED} and @code{SYNCHRONISED} are interchangeable, and may be abbreviated as @code{SYNC}.

@item
If the @code{SYNCHRONIZED} clause is coded on anything but a numeric data item with a @syntaxref{USAGE} that specifies storage of data in a binary form, the @code{SYNCHRONIZED} clause will be ignored.

@item
Synchronization is performed (by the compiler) as follows:
@enumerate A
@item
If the binary item occupies one byte of storage, no synchronization is performed.

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

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

@item
If the binary item occupies eight bytes of storage, the binary item is allocated at the next word boundary.
@end enumerate
@end enumerate
@iftex
The following illustrates the allocation of a group of data items both without and with the @code{SYNCHRONIZED} option.  The grey blocks represent the unused bytes that are allocated in the Group-Item-2 structure because of the @code{SYNC} clauses.
@sp 1
@image{synchronization,6in}
@end iftex
@comment *********************************************************************
@comment ** 6.9.46B TIME OUT                                                **
@comment *********************************************************************
@page
@newsubsection{TIME OUT}
@diagram{TIME-OUT Clause,DD-TIME-OUT,DD-TIME-OUT,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause will force a specific time for the data tp be entered.


@comment *********************************************************************
@comment ** 6.9.47 TO                                                       **
@comment *********************************************************************
@page
@newsubsection{TO}
@diagram{TO Clause,DD-TO,DD-TO,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause logically attaches a screen section data item to another data item defined elsewhere in the data division.
@enumerate
@item
The @code{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.

@item
The @syntaxref{FROM}, @code{TO}, @syntaxref{USING} and @syntaxref{VALUE} clauses are mutually-exclusive in any screen section data item's definition.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.48 TYPE                                                     **
@comment *********************************************************************
@page
@newsubsection{TYPE}
@diagram{TYPE Clause,DD-TYPE,DD-TYPE,None}
The syntax is valid in all other sections than:
@code{REPORT}

As format 1
@enumerate
@item
The TYPE clause indicates that the data description of the subject of the entry is specified by a user-defined data type.
@item
The user defined data type is defined using the TYPEDEF clause, which is described in TYPEDEF clause @syntaxref{TYPEDEF}.
@item
The following general rules apply: If type-name-1 (defined using the TYPEDEF clause) describes a group item, then the subject of the TYPE clause is a group item whose subordinate elements have the same names, descriptions, and hierarchies as the subordinate elements of type-name-1.
@item
Since the subject of the TYPE clause may have a level number as high as 49 and type-name-1 may be a group item with 49 levels, the number of levels of this hierarchy may exceed 49. In fact, since descriptions of type names may reference other type names, there is no limit to the number of levels in this hierarchy.
@item
If a VALUE clause is specified in the data description of the subject of the TYPE clause, any VALUE clause specified in the description of type-name-1 is ignored for this entry.
@item
The scoping rules for type names are similar to the scoping rules for data names.
@item
Reference modification is not allowed for an elementary item that is the subject of a TYPE clause.
@item
The description of type-name-1, including its subordinate data items, cannot contain a TYPE clause that references the record to which the subject of the TYPE clause (that references type-name-1), is subordinate.
@item
For example, A is a group item defined using the TYPEDEF clause. B is also a group item defined using the TYPEDEF clause, but which also includes a subordinate item of TYPE A. This being the case, the type definition for A cannot include items of TYPE B.
@item
The subject of a TYPE clause cannot be renamed in whole, or in part and cannot be redefined explicitly or implicitly.
@item
If the subject of a TYPE clause is subordinate to a group item, the data description of the group item cannot contain the USAGE clause.
@item
The TYPE clause cannot occur in a data description entry with the BLANK WHEN ZERO, FORMAT, JUSTIFIED, PICTURE, REDEFINES, RENAMES, SIGN, SYNCHRONIZED, or USAGE clause.
@item
The TYPE clause can be specified in a data description entry with the EXTERNAL, GLOBAL, OCCURS, TYPEDEF, and VALUE clauses.
@item
The essential characteristics of a type, which is identified by its type-name, are the relative positions and lengths of the elementary items defined in the type declaration, and the BLANK WHEN ZERO, JUSTIFIED, PICTURE, SIGN, SYNCHRONIZED, and USAGE clauses specified for each of these elementary items.
@item
The TYPE clause shall not be specified in the same data description entry with any clauses except BASED, CLASS, CONSTANT RECORD, DEFAULT, DESTINATION, entry-name, EXTERNAL, GLOBAL, INVALID, level-number, OCCURS, PRESENT WHEN, PROPERTY, TYPEDEF, VALIDATE-STATUS, VALUE, and VARYING.

@item
Figure 1. Example Showing How TYPEDEF and TYPE Clauses Can Be Used

@example

       IDENTIFICATION   DIVISION.
       PROGRAM-ID.      prog.
       DATA             DIVISION.
       WORKING-STORAGE  SECTION.
       01 MAIN-FILE-NAME-T     PIC X(50) IS TYPEDEF.
       01 DETAIL-NO-T             PIC 9999  IS TYPEDEF.
        01 MAIN-FILE-NAME-2T              IS TYPEDEF.
          05 FILLER    PIC 9999.
          05 DETAIL-NO TYPE TO DETAIL-NO-T.

       01  MESSAGE-TEXT-2T IS TYPEDEF.
         02 MAIN-FILE-NAME     TYPE MAIN-FILE-NAME-T.
         02 FILLER REDEFINES MAIN-FILE-NAME.
             05 FILLER PIC 9999.
         02 MAIN-FILE-NAME-2   TYPE MAIN-FILE-NAME-2T.
         02 FILLER                TYPE MAIN-FILE-NAME-T.

       01  MESSAGE-TEXT-2 EXTERNAL TYPE MESSAGE-TEXT-2T.
       77 OUTPUT-NAME TYPE TO DETAIL-NO-T GLOBAL.
       01 Z-MESSAGE-T2 TYPE MAIN-FILE-NAME-2T.
       01 Z-MESSAGE-T3.
          49 MT3                    TYPE MESSAGE-TEXT-2T.
          49 MT3-REN  REDEFINES MT3 TYPE MESSAGE-TEXT-2T.

       PROCEDURE DIVISION.
           DISPLAY MAIN-FILE-NAME OF MESSAGE-TEXT-2
           DISPLAY DETAIL-NO         OF Z-MESSAGE-T2
           DISPLAY MAIN-FILE-NAME OF MT3
           DISPLAY OUTPUT-NAME
           GOBACK.

@end example
@item
Figure 2. Example Showing How TYPEDEF and TYPE Clauses Can Be Used

@example

     DATA DIVISION.
     FILE SECTION.
     FD PRT-FILE.
     01 PRT-REC.
        05 PRT-RECORD                PIC X(132).
     01 INVE-TYP-T IS TYPEDEF        PIC S9(3) VALUE 0.
             88 INVE-TYP-BOOK             VALUE 4, 5.
        88 INVE-TYP-BOOK-001         VALUE 4.
        88 INVE-TYP-BOOK-002         VALUE 5.
        88 INVE-TYP-CLOTHES          VALUE 1, 2, 3.
        88 INVE-TYP-CLOTHES-SWEATERS VALUE 1.
        88 INVE-TYP-CLOTHES-SOCKS    VALUE 2.
        88 INVE-TYP-CLOTHES-PANTS    VALUE 3.

    FD DATA-IN.
    01 DATA-IN-REC.
       05 INVE-TYP          TYPE INVE-TYP-T.
       05 FILLER            PIC X(80).

    WORKING-STORAGE SECTION.
    01 ARTI-PRICE-T TYPEDEF PIC S9(4)V9(2) value 0.
    01 ARTI-COLOR-T TYPEDEF PIC S9(2) VALUE 1.
       88 ARTI-COLOR-BLUE   VALUE 1.
       88 ARTI-COLOR-RED    VALUE 2.
       88 ARTI-COLOR-GREEN  VALUE 3.

    01 ARTI-SIZE-T    TYPEDEF PIC S9(2) VALUE 10.
    01 ARTI-COUNTER-T TYPEDEF PIC S9(6) VALUE 0.

    01 ARTI-B-T TYPEDEF.
       05 ARTI-B-VALUE PIC s9(2).
          88 ARTI-B-BLUE  VALUE 1.
          88 ARTI-B-RED   VALUE 2.
          88 ARTI-B-GREEN VALUE 3.

    01 TEST-ARTI       TYPE ARTI-B-T.

    01 WORK-INVE-TYP  TYPE INVE-TYP-T.

    01 CLOTHING-ARTI IS TYPEDEF.
       05 CLOTHING-TYP    TYPE INVE-TYP-T.
       05 PRICE           TYPE ARTI-PRICE-T.
       05 COLOR           TYPE ARTI-COLOR-T.
       05 CLOTHING-SIZE   TYPE ARTI-SIZE-T.
       05 FILLER PIC X(70).

    01 SWEATERS TYPE CLOTHING-ARTI.
    01 SOCKS    TYPE CLOTHING-ARTI.
    01 PANTS    TYPE CLOTHING-ARTI.

    01 BOOK-ARTI IS TYPEDEF.
       05 BOOK-TYP     TYPE INVE-TYP-T.
       05 PRICE        TYPE ARTI-PRICE-T.
       05 FILLER       PIC X(20).
       05 BOOK-TITLE   PIC X(40).
       05 FILLER       PIC X(14).

    01 BOOK-001       TYPE BOOK-ARTI.
    01 BOOK-002       TYPE BOOK-ARTI.

    01 SWEATERS-COUNT TYPE ARTI-COUNTER-T.
    01 SOCKS-COUNT    TYPE ARTI-COUNTER-T.
    01 PANTS-COUNT    TYPE ARTI-COUNTER-T.

    01 BOOK-001-COUNT TYPE ARTI-COUNTER-T.
    01 BOOK-002-COUNT TYPE ARTI-COUNTER-T.

    01 CLOTHES-COUNT  TYPE ARTI-COUNTER-T.
    01 BOOK-COUNT     TYPE ARTI-COUNTER-T.

@end example
@end enumerate
This syntax is valid in the following sections:
@code{REPORT}

As Format 2
@enumerate
@item
This clause defines the type of report group that is being defined for a report.
@item
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.

@item
There may be a maximum of one (1) report group per @code{RD} defined with a @code{TYPE} of @code{REPORT HEADING}, @code{PAGE HEADING}, @code{PAGE FOOTING} and @code{REPORT FOOTING}.

@item
There must be either a @code{CONTROL HEADING} or a @code{CONTROL FOOTING} or both specified for each entry specified on the @code{CONTROLS ARE} clause of the @code{RD}.

@item
The various report groups that constitute a report may be defined in any order.

@item
@xref{RWCS Lexicon}, for a description of the seven different types of report groups.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.49 TYPEDEF                                                  **
@comment *********************************************************************
@page
@newsubsection{TYPEDEF}
@diagram{TYPEDEF Clause,DD-TYPEDEF,DD-TYPEDEF,None}
This syntax is valid in the following sections FILE, WORKING-STORAGE, LOCAL-STORAGE and LINKAGE
@enumerate
@item
The TYPEDEF clause identifies a type declaration which creates a user defined data type and is used to apply this user defined data type to the description of a data item.

@item
The TYPEDEF clause specifies that the data description entry is a type declaration.
@item
The TYPEDEF clause can only be specified for level 01 entries, which can also be group items, and for which the data-name format of the entry name clause is specified. If the TYPEDEF clause is specified for a data description, then that same data description must include a data-name, that is, it must not be specified with either an implicit or explicit FILLER clause.
@item
If a group item is specified, all subordinate items of the group become part of the type declaration.
@item
No storage is allocated for a type declaration.
@item
These type definitions act like templates that can then be used to define new data items using the TYPE clause or that can subsequently be referenced in a USAGE clause.
@item
The new data item acquires all the characteristics of the user-defined data type. If the user defined data type is a group item, then the new data item has subordinate elements of the same name, description, and hierarchy as those belonging to the user defined data type.
@item
All of the other data description clauses, if they are specified, are assumed by any data item that is defined using the user defined data type (within the TYPE or USAGE clause).
@item
The following clauses cannot be specified along with TYPEDEF: EXTERNAL, GLOBAL, LIKE, OCCURS, REDEFINES.
@item
If the TYPEDEF clause is specified for a group item, then subordinate items can be specified with OCCURS or REDEFINES clauses. TYPEDEF cannot be used with complex OCCURS DEPENDING ON. This means that you cannot specify an OCCURS DEPENDING ON clause within a table that is part of a TYPEDEF.
@item
The VALUE clause cannot be specified either in the data descriptions specifying the TYPEDEF clause or in any subordinate item except for condition-names (88 level entries) within the TYPEDEF structure.
@item
The TYPE clause can be specified in the same data description entry as the TYPEDEF clause but the description of the subject of the entry, including its subordinate items, shall not contain a TYPE clause that directly or indirectly references this type definition.
@item
In FILE SECTION, a data description entry declared at level number 1 that includes a TYPEDEF clause is not a record description entry.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.50 UNDERLINE                                                **
@comment *********************************************************************
@page
@newsubsection{UNDERLINE}
@diagram{UNDERLINE Attribute,DD-UNDERLINE,DD-UNDERLINE,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{UNDERLINE} clause will introduce a horizontal line at the bottom edge of a screen field.
@enumerate
@item
The @syntaxref{LEFTLINE}, @syntaxref{OVERLINE} and @code{UNDERLINE} clauses may be used in any combination in a single field's description.

@item
This clause is essentially non-functional when used within Windows command shell (cmd.exe) environments and running programs compiled using a GnuCOBOL implementation built using ``PDCurses'' (such as Windows/MinGW builds).

@item
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.
@end enumerate

@xref{Color Palette and Video Attributes}, for more information on screen colors and video attributes.
@comment *********************************************************************
@comment ** 6.9.50B UPDATE                                                  **
@comment *********************************************************************
@page
@newsubsection{UPDATE}
@diagram{UPDATE Clause,DD-UPDATE,DD-UPDATE,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{UPDATE} clause will display the existing data before allowing user to update it.

@comment *********************************************************************
@comment ** 6.9.50C UPPER                                                   **
@comment *********************************************************************
@page
@newsubsection{UPPER}
@diagram{UPPER Clause,DD-UPPER,DD-UPPER,None}
This syntax is valid in the following sections:
@code{SCREEN}

The @code{UPPER} clause force the accepted data to be in Upper Case.

@comment *********************************************************************
@comment ** 6.9.51 USAGE                                                    **
@comment *********************************************************************
@page
@newsubsection{USAGE}
@diagram{USAGE Clause,DD-USAGE,DD-USAGE,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{REPORT}

The @code{USAGE} clause defines the format that will be used to store the value of a data item.
@enumerate
@item
The reserved word @code{IS} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
The following table summarizes the various USAGE specifications available in GnuCOBOL.

@t{BINARY}@*@t{~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values:          @tab Defined by the quantity of @samp{9}s and the presence or absence of an @samp{S} in the @code{PICTURE}

@item
@tab Storage Format:           @tab Compatible Binary Integer

@item
@tab Negative Values Allowed?: @tab If @code{PICTURE} contains @samp{S}

@item
@tab @code{PICTURE} Used?:            @tab Yes

@end multitable

@t{BINARY-C-LONG [ SIGNED ]}@*@t{~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values:          @tab Depending on the system hardware, the range is either 0 to 2^31 or 0 to 2^63.
@end multitable

@t{BINARY-C-LONG UNSIGNED}@*@t{~~~~~~~~~~~~~ ~~~~~~~~}

@multitable @columnfractions 0.05 0.4 0.55
@item
@tab Range of Values:          @tab Depending on the system hardware, the range is either 0 to 2^32 or 0 to 2^64.

@item
@tab Restrictions:             @tab This USAGE should only be used for direct CALLs into C and otherwise should not be used (and it won't compile with any strict -std as it is a GnuCOBOL-only extension).
@end multitable


@t{BINARY-CHAR [ SIGNED ]}@*@t{~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab -128 -- 127

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab Yes

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{BINARY-CHAR UNSIGNED}@*@t{~~~~~~~~~~~ ~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab 0 -- 255

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab No

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{BINARY-DOUBLE [ SIGNED ]}@*@t{~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab -9,223,372,036,854,775,808 -- 9,223,372,036,854,775,807

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab Yes

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{BINARY-DOUBLE UNSIGNED}@*@t{~~~~~~~~~~~~~ ~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab 0 -- 18,446,744,073,709,551,615

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab No

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{BINARY-INT}@*@t{~~~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY-LONG SIGNED}
@end multitable

@t{BINARY-LONG [ SIGNED ]}@*@t{~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab -2,147,483,648 -- 2,147,483,647

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab Yes

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{BINARY-LONG UNSIGNED}@*@t{~~~~~~~~~~~ ~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab 0 -- 4,294,967,295

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab No

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{BINARY-LONG-LONG}@*@t{~~~~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY-DOUBLE SIGNED}
@end multitable

@t{BINARY-SHORT [ SIGNED ]}@*@t{~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab -32,768 -- 32,767

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab Yes

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{BINARY-SHORT UNSIGNED}@*@t{~~~~~~~~~~~~ ~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab 0 -- 65,535

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab No

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{COMPUTATIONAL}@*@t{COMP}
@comment t{COMP[UTATIONAL]}@*@t{~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY}
@end multitable

@t{COMPUTATIONAL-1}@*@t{COMP-1}
@comment t{COMP[UTATIONAL]-1}@*@t{~~~~                  ~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{FLOAT-SHORT}
@end multitable

@t{COMPUTATIONAL-2}@*@t{COMP-2}
@comment t{COMP[UTATIONAL]-2}@*@t{~~~~                  ~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{FLOAT-LONG}
@end multitable

@t{COMPUTATIONAL-3}@*@t{COMP-3}
@comment t{COMP[UTATIONAL]-3}@*@t{~~~~           ~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{PACKED-DECIMAL}
@end multitable

@t{COMPUTATIONAL-4}@*@t{COMP-4}
@comment t{COMP[UTATIONAL]-4}@*@t{~~~~           ~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY}
@end multitable

@t{COMPUTATIONAL-5}@*@t{COMP-5}
@comment t{COMP[UTATIONAL]-5}@*@t{~~~~           ~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab Depends on number of @samp{9}s in the @code{PICTURE} and the @code{binary-size} setting of the configuration file used to compile the program

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab If @code{PICTURE} contains @samp{S}

@item
@tab @code{PICTURE} Used?: @tab Yes
@end multitable

@t{COMPUTATIONAL-6}@*@t{COMP-6}
@comment t{COMP[UTATIONAL]-6}@*@t{~~~~           ~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab Defined by the quantity of @samp{9}s and the presence or absence of an @samp{S} in the @code{PICTURE}

@item
@tab Storage Format: @tab Unsigned Packed Decimal

@item
@tab Negative Values Allowed?: @tab No

@item
@tab @code{PICTURE} Used?: @tab Yes
@end multitable

@t{COMPUTATIONAL-X}@*@t{COMP-X}
@comment t{COMP[UTATIONAL]-X}@*@t{~~~~           ~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab If used with @code{PIC X}, allocates one byte of storage per @samp{X}; range of values is 0 to max storable in that many bytes.  If used with @code{PIC 9}, range of values depends on number of @samp{9}s in PICTURE

@item
@tab Storage Format: @tab Native unsigned (X) or signed (9) Binary

@item
@tab Negative Values Allowed?: @tab If @code{PICTURE} 9 and contains @samp{S}

@item
@tab @code{PICTURE} Used?: @tab Yes
@end multitable

@t{DISPLAY}@*@t{~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab Depends on @code{PICTURE} --- One character per X, A, 9, period, $, Z, 0, *, S (if @code{SEPARATE CHARACTER} specified), +, - or B symbol in @code{PICTURE}; Add 2 more bytes if the @code{DB} or @code{CR} editing symbol is used

@item
@tab Storage Format: @tab Characters

@item
@tab Negative Values Allowed?: @tab If @code{PICTURE} contains @samp{S}

@item
@tab @code{PICTURE} Used?: @tab Yes
@end multitable

@t{FLOAT-DECIMAL-16}@*@t{~~~~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab -9.999999999999999 * 10@sup{383} --  9.999999999999999 * 10@sup{384}

@item
@tab Storage Format: @tab Native IEEE 754 Decimal64 Floating-point

@item
@tab Negative Values Allowed?: @tab Yes

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{FLOAT-DECIMAL-34}@*@t{~~~~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab -9.99999... * 10@sup{6143} --  9.99999... * 10@sup{6144}

@item
@tab Storage Format: @tab Native IEEE 754 Decimal128 Floating-point

@item
@tab Negative Values Allowed?: @tab Yes

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{FLOAT-LONG}@*@t{~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab Approximately -1.797693134862316 * 10@sup{308} --  1.797693134862316 * 10@sup{308}

@item
@tab Storage Format: @tab Native IEEE 754 Binary64 Floating-point

@item
@tab Negative Values Allowed?: @tab Yes

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{FLOAT-SHORT}@*@t{~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab Approximately -3.4028235 * 10@sup{38} --  3.4028235 * 10@sup{38}

@item
@tab Storage Format: @tab Native IEEE 754 Binary32

@item
@tab Negative Values Allowed?: @tab Yes

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{INDEX}@*@t{~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab 0 to maximum address possible (32 or 64 bits)

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab No

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{NATIONAL}@*@t{~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab @code{USAGE NATIONAL}, while syntactically recognized, is not supported by GnuCOBOL
@end multitable

@t{PACKED-DECIMAL}@*@t{~~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab Defined by the quantity of @samp{9}s and the presence or absence of an @samp{S} in the PICTURE

@item
@tab Storage Format: @tab Signed Packed Decimal

@item
@tab Negative Values Allowed?: @tab If @code{PICTURE} contains @samp{S}

@item
@tab @code{PICTURE} Used?: @tab Yes
@end multitable

@t{POINTER}@*@t{~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab 0 to maximum address possible (32 or 64 bits)

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab No

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{PROCEDURE-POINTER}@*@t{~~~~~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{PROGRAM-POINTER}
@end multitable

@t{PROGRAM-POINTER}@*@t{~~~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.4 0.55

@item
@tab Range of Values: @tab 0 to maximum address possible (32 or 64 bits)

@item
@tab Storage Format: @tab Native Binary Integer

@item
@tab Negative Values Allowed?: @tab No

@item
@tab @code{PICTURE} Used?: @tab No
@end multitable

@t{SIGNED-INT}@*@t{~~~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY-LONG SIGNED}
@end multitable

@t{SIGNED-LONG}@*@t{~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY-DOUBLE SIGNED}
@end multitable

@t{SIGNED-SHORT}@*@t{~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY-SHORT SIGNED}
@end multitable

@t{UNSIGNED-INT}@*@t{~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY-LONG UNSIGNED}
@end multitable

@t{UNSIGNED-LONG}@*@t{~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY-DOUBLE UNSIGNED}
@end multitable

@t{UNSIGNED-SHORT}@*@t{~~~~~~~~~~~~~~}
@multitable @columnfractions 0.05 0.95

@item
@tab Same as @code{BINARY-SHORT UNSIGNED}
@end multitable

@item
@t{USAGE IS type-name-1}@*@t{~~~~~ ~~}


@item
This USAGE clause indicates that the data description of the subject of the entry is specified by a user-defined data type. The user-defined data type is defined using the TYPEDEF clause, which is described in TYPEDEF clause.

@example

Example 1:

01 struct-1     TYPEDEF.
    05  part-1  pic x(20).
    05  part-2  pic x(10).
01  a.
    05  b  USAGE struct-1.
    05  x  USAGE USHORT.
01 USHORT      pic 9(04) comp-5 typedef.

Which would be interpreted as if it had been coded as:

 01  a.
     05  b.
         10  part-1 pic x(20).
         10  part-2 pic x(10).
     05  x          pic 9(04) comp-5.

Example 2:

   IDENTIFICATION   DIVISION.
   PROGRAM-ID.      prog.
   DATA             DIVISION.
   WORKING-STORAGE  SECTION.
   01 MAIN-FILE-NAME-T     PIC X(50) IS TYPEDEF.
   01 DETAIL-NO-T             PIC 9999  IS TYPEDEF.
   01 MAIN-FILE-NAME-2T              IS TYPEDEF.
      05 FILLER               PIC 9999.
      05 DETAIL-NO            USAGE DETAIL-NO-T.

   01  MESSAGE-TEXT-2T        IS TYPEDEF.
     02 MAIN-FILE-NAME     USAGE MAIN-FILE-NAME-T.
     02 FILLER                REDEFINES MAIN-FILE-NAME.
         05 FILLER            PIC 9999.
     02 MAIN-FILE-NAME-2   USAGE MAIN-FILE-NAME-2T.
     02 FILLER                USAGE MAIN-FILE-NAME-T.

   01  MESSAGE-TEXT-2 EXTERNAL USAGE MESSAGE-TEXT-2T.

   77 OUTPUT-NAME              USAGE DETAIL-NO-T GLOBAL.

   01 Z-MESSAGE-T2             USAGE MAIN-FILE-NAME-2T.
   01 Z-MESSAGE-T3.
      49 MT3                   USAGE MESSAGE-TEXT-2T.
      49 MT3-REN REDEFINES MT3 USAGE MESSAGE-TEXT-2T.

   PROCEDURE DIVISION.
       DISPLAY MAIN-FILE-NAME OF MESSAGE-TEXT-2
       DISPLAY DETAIL-NO         OF Z-MESSAGE-T2
       DISPLAY MAIN-FILE-NAME OF MT3
       DISPLAY OUTPUT-NAME
       GOBACK.

Example 3:

   77  INT                     PIC S9(09)COMP-5 IS TYPEDEF.
   01  Z-RETURNCODE            USAGE INT VALUE 0.
   01  MESSAGE-TEXT-2                           IS TYPEDEF.
       02 MAIN-FILE-NAME    PIC X(50).
       02 FILLER               PIC X(79).
   01 Z-MESSAGE-T2 USAGE MESSAGE-TEXT-2.
   77 VIRMSG-TEXT              PIC  X(129) IS TYPEDEF.
   01  MESSAGE-TEXT-2                       IS TYPEDEF.
       02 MAIN-FILE-NAME    PIC X(50).
       02 FILLER               PIC X(79).
   01 Z-MESSAGE-TEXT           USAGE VIRMSG-TEXT.
   01 Z-MESSAGE-T2 REDEFINES Z-MESSAGE-TEXT USAGE MESSAGE-TEXT-2.
   01  W102-TYPE IS TYPEDEF.
       COPY SERVERFIELDS.
   01 T-A                      USAGE W102-TYPE.
   01 T-N                      USAGE W102-TYPE.

@end example

@item
Binary data (integer or floating-point) can be stored in either a @i{Big-Endian} or @i{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 @i{understanding} big-endian format, which makes it the @i{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 @i{native} binary format.

On a system supporting only one format of binary storage (generally, that would be big-endian), the terms @i{most efficient} and @i{native} format are synonymous.

@item
Data items that have the
@syntaxidx{UNSIGNED} attribute explicitly coded, or @code{DISPLAY}, @code{PACKED-DECIMAL}, @code{COMP-5}, @code{COMP-X} items that do not have an @samp{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.

@item
Packed-decimal (@i{i.e.} @code{USAGE PACKED-DECIMAL}, @code{USAGE COMP-3} or @code{USAGE COMP-6}) data is stored as a series of bytes such that each byte contains two 4-bit fields, referred to as @dfn{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 @samp{9} in the @code{PICTURE} and each holds a single decimal digit encoded as its binary value (0 = 0000, 1 = 0001, @dots{} , 9 = 1001).

The @i{last} byte of a @code{PACKED-DECIMAL} or @code{COMP-3} data item will always have its left nibble corresponding to the last @samp{9} in the @code{PICTURE} and its right nibble reserved as a sign indicator.  This sign indicator is always present regardless of whether or not the @code{PICTURE} included an @samp{S} symbol.

The @i{first} byte of the data item will contain an unused left nibble if the @code{PICTURE} had an even number of @samp{9} symbols in it.

The sign indicator will have a value of a hexadecimal A through F.  Traditional packed decimal encoding rules call for hexadecimal 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/GnuCOBOL implementation shows that --- in fact --- hex digit D represents a negative number and any other hexadecimal digit denotes a positive number.  Therefore, a @code{PIC S9(3) COMP-3} packed-decimal field with a value of -15 would be stored internally as a hexadecimal 015D in GnuCOBOL.

If you attempt to store a negative number into a packed decimal field that has no @samp{S} in its @code{PICTURE}, the absolute value of the negative number will actually be stored.

@code{USAGE COMP-6} does not allow for negative values, therefore no sign nibble will be allocated.  A @code{USAGE COMP-6} data item containing an odd number of @samp{9} symbols in its @code{PICTURE} will leave its leftmost nibble unused.

@item
The @code{USAGE} specifications @code{FLOAT-DECIMAL-16} and @code{FLOAT-DECIMAL-34} will encode data using IEEE 754 @i{Decimal64} and @i{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 (@code{FLOAT-LONG} and @code{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 @code{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 @i{Decimal64}).

@item
GnuCOBOL stores @code{FLOAT-DECIMAL-16} and @code{FLOAT-DECIMAL-34} data items using either Big-Endian or Little-Endian form, whichever is native to the system.

@item
The @code{USAGE} specifications @code{FLOAT-LONG} and @code{FLOAT-SHORT} use the IEEE 754 @i{Binary64} and @i{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 @i{Binary32} or @i{Binary64}.

GnuCOBOL stores @code{FLOAT-LONG} and @code{FLOAT-SHORT} data items using either Big-Endian or Little-Endian form, whichever is native to the system.

@item
A @code{USAGE} clause specified at the group item level will apply that @code{USAGE} to all subordinate data items, except those that themselves have a @code{USAGE} clause.

@item
The only @code{USAGE} that is allowed in the report section is @code{USAGE DISPLAY}.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.52 USING                                                    **
@comment *********************************************************************
@page
@newsubsection{USING}
@diagram{USING Clause,DD-USING,DD-USING,None}
This syntax is valid in the following sections:
@code{SCREEN}

This clause logically attaches a screen section data item to another data item defined elsewhere in the data division.
@enumerate
@item
When the screen item whose definition this clause is part of is displayed, the value currently in @var{identifier-1} will be automatically moved into the screen item first.

@item
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 @var{identifier-1} at the conclusion of the @code{ACCEPT}.

@item
The @syntaxref{FROM}, @syntaxref{TO}, @code{USING} and @syntaxref{VALUE} clauses are mutually-exclusive in any screen section data item's definition.
@end enumerate
@comment *********************************************************************
@comment ** 6.9.53 VALUE                                                    **
@comment *********************************************************************
@page
@newsubsection{VALUE}
@diagram{VALUE (Condition Names) Clause,DD-VALUE-1,DD-VALUE-1,None}
@diagram{VALUE (Other Data Items),DD-VALUE-2,DD-VALUE-2,None}
@diagram{VALUE (For Tables),DD-VALUE-3,DD-VALUE-3,None}
This syntax is valid in the following sections:
@code{FILE}, @code{WORKING-STORAGE}, @code{LOCAL-STORAGE}, @code{LINKAGE}, @code{REPORT}, @code{SCREEN}

The @code{VALUE} clause is used to define condition names or to assign values (at compilation time) to data items.
@enumerate
@item
The reserved words @code{ARE} and @code{IS} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
This clause cannot be specified on the same data item as a @syntaxref{FROM}, @syntaxref{TO} or @syntaxref{USING} clause.

@item
The following points apply to using the @code{VALUE} clause in the definition of a condition name:
@enumerate A
@item
The clauses @code{VALUE IS} and @code{VALUES ARE} are interchangeable.

@item
The reserved words @code{THRU} and @code{THROUGH} are interchangeable.

@item
@xref{88-Level Data Items}, for a discussion of how this format of @code{VALUE} is used to create condition names.

@item
@xref{Condition Names}, for a discussion of how condition names are used.
@end enumerate
@item  The following points apply to using the @code{VALUE} clause in the definition of any other data item:
@enumerate A
@item
In this context, @code{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.

@item
The @code{VALUE} clause is ignored on @syntaxref{EXTERNAL} data items or on any data items defines as subordinate to an @code{EXTERNAL} data item.

@item
This format of the @code{VALUE} clause may not be used anywhere in the description of an 01 item (or any of its subordinate items) serving as an @code{FD} or @code{SD} record description.

@item
If the optional
@syntaxidx{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 @code{ALL} (the symbol @i{b} denotes a space):

@example
PIC X(5) VALUE @samp{A}      *> A@i{bbbb}
PIC X(5) VALUE ALL @samp{A}  *> AAAAA
PIC 9(3) VALUE 1        *> 001
PIC 9(3) VALUE ALL @samp{1}  *> 111
@end example
@item
When used in the definition of a screen data item:
@enumerate a
@item
A figurative constant may not be supplied as @var{literal-1}.

@item
Any @syntaxref{FROM}, @syntaxref{TO} or @syntaxref{USING} clause in the same data item's definition will be ignored.

@item
If there is no picture clause specified, the size of the screen data item will be the length of the @var{literal-1} value.

@item
If there is no picture clause and the @code{ALL} option is specified, the @code{ALL} option will be ignored.
@end enumerate
@item
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 GnuCOBOL may find interesting.  So, here are the three @i{standard} approaches:
@enumerate a
@item
Don't bother worrying about it at compile-time.  Use the @syntaxref{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).

@item
Initialize small tables at compile time by including a @code{VALUE} clause on the group item that serves as a parent to the table, as follows:

@example
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).
@end example
@item Initialize tables of almost any size at compilation time by utilizing the @syntaxref{REDEFINES} clause:

@example
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).
@end example

Admittedly, this table is much more verbose than the one shown with a group @code{VALUE}.  What is good about this initialization technique, however, is that you can have as many @code{FILLER} and @code{VALUE} items as you need for a larger table, and those values can be as long as necessary!
@end enumerate

@item
Many COBOL compilers do not allow the use of @code{VALUE} and @syntaxref{OCCURS} on the same data item; additionally, they don't allow a @code{VALUE} clause on a data item subordinate to an @code{OCCURS}.  GnuCOBOL, however, has neither of these restrictions!

Observe the following example, which illustrates a fourth manner in which tables may be initialized in GnuCOBOL:

@example
05  X           OCCURS 6 TIMES.
    10 A        PIC X(1) VALUE '?'.
    10 B        PIC X(1) VALUE '%'.
    10 N        PIC 9(2) VALUE 10.
@end example

In this example, all six @samp{A} items will be initialized to @samp{?}, all six @samp{B} items will be initialized to @samp{%} and all six @samp{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.
@end enumerate

@item
The @syntaxref{FROM}, @syntaxref{TO}, @syntaxref{USING} and @code{VALUE} clauses are mutually-exclusive in any screen section data item's definition.

@item
Format-3 (Table): The value clause for tables specifies the initial value of working-storage section and local-storage section data items.

@example
Example 1: Table value clause

 03  Level-1      occurs 10 times.
     05  Level-2  occurs 3 times PIC X.
                     value "A" "B" "C" FROM (2 2) to (3 1)
                           "X" "Y" "Z" FROM (1 1) to (! 3)
                           space       FROM (3 2).

@end example

@example
Example 2: Table value clause with Initialize

  01  Group-Items.
      03                  value "Implicit Filler".
      03  filler   pic 1  value B"1".
      03  Var-Table   occurs 10 times
            pic 9   value 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, (1) to (10).
  . . .
   initialize Group-Items
             with filler
               All to value.

@end example


@end enumerate
@iftex
@sp 3
@center ------------------------------------------------------------
@center End of Chapter 6 --- DATA DIVISION
@end iftex
