.. |_| unicode:: 0xA0
:trim:
.. role:: small-caps
:class: small-caps
.. include:: <isonum.txt>
.. index:: single:DATA DIVISION
.. _DATAADIVISION:
6 DATA DIVISION
===============
DATA DIVISION Syntax
::
DATA DIVISION.
~~~~ ~~~~~~~~
[ FILE SECTION.
~~~~ ~~~~~~~
{ File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ]
{ { 01-Level-Constant } }
{ { 78-Level-Constant } }
{ 01-Level-Constant }
{ 78-Level-Constant }
[ WORKING-STORAGE SECTION.
~~~~~~~~~~~~~~~ ~~~~~~~
[ { WORKING-STORAGE-SECTION-Data-Item } ]... ]
{ 01-Level-Constant }
{ 78-Level-Constant }
[ LOCAL-STORAGE SECTION.
~~~~~~~~~~~~~ ~~~~~~~
[ { LOCAL-STORAGE-SECTION-Data-Item } ]... ]
{ 01-Level-Constant }
{ 78-Level-Constant }
[ LINKAGE SECTION.
~~~~~~~ ~~~~~~~
[ { LINKAGE-SECTION-Data-Item } ]... ]
{ 01-Level-Constant }
{ 78-Level-Constant }
[ REPORT SECTION.
~~~~~~ ~~~~~~~
{ Report-Description [ { Report-Group-Definition } ]... }... ]
{ { 01-Level-Constant } }
{ { 78-Level-Constant } }
{ 01-Level-Constant }
{ 78-Level-Constant }
[ SCREEN SECTION.
~~~~~~ ~~~~~~~
[ { SCREEN-SECTION-Data-Item } ]... ]
{ 01-Level-Constant }
{ 78-Level-Constant }
All data used by any COBOL program must be defined in one of the six sections of the data division, depending upon the purpose of the data.
#.
If no data will be described in one of the data division sections, that section header may be omitted.
#.
If no data division sections are needed, the \ :code:`DATA DIVISION.`\ header itself may be omitted.
#.
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.
.. index:: single:Data Definition Principles
.. _DataADefinitionAPrinciples:
6.1 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`\ :
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 ( :ref:`StructuredAData`), a data item that is broken down into other data items is referred to as a group item, while one that isn't broken down is called an elementary item.
COBOL uses the concept of a \ *level*\ number to indicate the level at which a data item occurs in a data structure such as the example shown above. When these data items are defined, they are all defined together with a number in the range 1-49 specified in front of their names. Over the years, a convention has come to exist among COBOL programmers that level numbers are always coded as two-digit numbers --- they don't \ *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 \ *record*\ , always has a level number of 01. After that, you may assign level numbers as you wish (01--02--03--04..., 01--05--10--15..., etc.), as long as you follow these simple rules:
#.
Every data item at the same \ *level*\ of a hierarchy diagram such as the one you see here (if you were to make one, which you rarely will, if ever, once you get used to this concept) must have the same level number.
#.
Every new level uses a level number that is strictly greater than the one used in the parent (next higher) level.
#.
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 ( :ref:`SpecialADataAItems`).
So, the definition of these data items in a GnuCOBOL program would go something like this:
::
01 Employee
05 Employee-Name
10 Last-Name
10 First-Name
10 Middle-Initial
05 Employment-Dates
10 From-Date
15 Year
15 Month
15 Day
10 To-Date
15 Year
15 Month
15 Day
The indentation is purely at the discretion of the programmer to make things easier for humans to read (the compiler couldn't care less). Historically, COBOL implementations that required Fixed Format Mode source programs required that the \ :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.
.. index:: single:FILLER
When group items are being defined, subordinate items may be assigned the "name"
\ \ :code:`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.
.. index:: single:FILE SECTION
.. _FILEASECTION:
6.2 FILE SECTION
----------------
FILE SECTION Syntax
::
[ FILE SECTION.
~~~~ ~~~~~~~
{ File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ]
{ { 01-Level-Constant } }
{ { 78-Level-Constant } }
{ 01-Level-Constant }
{ 78-Level-Constant }
Every file that has been referenced by a \ :code:`SELECT`\ statement ( :ref:`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.
.. index:: single:File/Sort-Description
.. _FileASort-Description:
6.2.1 File/Sort-Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~
File/Sort-Description Syntax
::
FD|SD file-name-1 [ IS EXTERNAL|GLOBAL ]
~~ ~~ ~~~~~~~~ ~~~~~~
[ BLOCK CONTAINS [ integer-1 TO ] integer-2 CHARACTERS|RECORDS ]
~~~~~ ~~ ~~~~~~~~~~ ~~~~~~~
[ CODE-SET IS alphabet-name-1 ]
~~~~~~~~
[ DATA { RECORD IS } identifier-1... ]
~~~~ { ~~~~~~ }
{ RECORDS ARE }
~~~~~~~
[ LABEL { RECORD IS } OMITTED|STANDARD ]
~~~~~ { ~~~~~~ } ~~~~~~~ ~~~~~~~~
{ RECORDS ARE }
~~~~~~~
[ LINAGE IS integer-3 | identifier-2 LINES
~~~~~~
[ LINES AT BOTTOM integer-4 | identifier-3 ]
~~~~~~
[ LINES AT TOP integer-5 | identifier-4 ]
~~~
[ WITH FOOTING AT integer-6 | identifier-5 ] ]
~~~~~~~
[ RECORD { CONTAINS [ integer-7 TO ] integer-8 CHARACTERS } ]
~~~~~~ { ~~ }
{ IS VARYING IN SIZE }
{ ~~~~~~~ }
{ [ FROM [ integer-7 TO ] integer-8 CHARACTERS }
{ ~~ }
{ DEPENDING ON identifier-6 ] }
~~~~~~~~~
[ RECORDING MODE IS recording-mode ]
~~~~~~~~~
[ { REPORT IS } report-name-1... ]
{ ~~~~~~ }
{ REPORTS ARE }
~~~~~~~
[ VALUE OF implementor-name-1 IS literal-1 | identifier-7 ] .
~~~~~ ~~
.. index:: single:VALUE OF
.. index:: single:RECORDING MODE
.. index:: single:LABEL RECORD
.. index:: single:DATA RECORD
.. index:: single:BLOCK CONTAINS
The
\ \ :code:`BLOCK CONTAINS`\ ,
\ \ :code:`DATA RECORD`\ ,
\ \ :code:`LABEL RECORD`\ ,
\ \ :code:`RECORDING MODE`\ and
\ \ :code:`VALUE OF`\
clauses are syntactically recognized but are obsolete and non-functional. These clauses should not be coded in new programs.
#.
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.
#.
The terms \ :code:`RECORD IS`\ and \ :code:`RECORDS ARE`\ are interchangeable.
#.
The terms \ :code:`REPORT IS`\ and \ :code:`REPORTS ARE`\ are interchangeable.
#.
Only files intended for use as work files for either the \ :code:`SORT`\ ( :ref:`SORT`) or \ :code:`MERGE`\ ( :ref:`MERGE`) statements should be coded with an SD --- all others should be defined with a FD.
#.
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.
#.
The name specified as <file-name-1> must exactly match the name specified on the file's \ :code:`SELECT`\ statement.
.. index:: single:CODE-SET
#.
The
\ \ :code:`CODE-SET`\ clause allows a custom alphabet, defined in the \ :code:`SPECIAL-NAMES`\ ( :ref:`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.
#.
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:
.. index:: single:LINES AT TOP
* \ LINES AT TOP
Number of unused (\ *i.e.*\ left blank) lines at the top of every page. The default if this if not specified is zero.
.. index:: single:LINES AT BOTTOM
* \ LINES AT BOTTOM
Number of unused (\ *i.e.*\ left blank) lines at the bottom of every page. The default if this if not specified is zero.
.. index:: single:LINAGE IS n LINES
* \ LINAGE IS n LINES
Total number of used/usable lines on the page.
* The sum of the previous three specifications should be the total number of possible lines available on one printed page.
.. index:: single:FOOTING AT
* \ 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 <n> LINES`\ value.
#.
This page structure --- once defined --- can be automatically enforced by the \ :code:`WRITE`\ statement ( :ref:`WRITE`).
.. index:: single:Special Registers, LINAGE-COUNTER
.. index:: single:LINAGE-COUNTER Special Register
#.
Specifying a \ :code:`LINAGE`\ clause in an \ :code:`FD`\ will cause the
\ \ \ :code:`LINAGE-COUNTER`\ special register to be created for the file. This automatically-created data item will always contain the current relative line number on the page being prepared which will serve as the starting point for a \ :code:`WRITE`\ statement.
.. index:: single:RECORD IS VARYING
.. index:: single:RECORD CONTAINS
#.
The
\ \ :code:`RECORD CONTAINS`\ and
\ \ :code:`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 <identifier-6> must be defined within one of the record descriptions of <file-name-1>.
.. index:: single:REPORT IS
#.
The
\ \ :code:`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:
#.
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.
#.
The \ :code:`FD`\ cannot be followed by record descriptions. Detailed descriptions of data to be printed to the file will be defined in the \ :code:`REPORT SECTION`\ ( :ref:`REPORTASECTION`).
#.
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.
#. The following special rules apply only to sort/merge work files:
#.
Sort/merge work files should be assigned to \ :code:`DISK`\ (or \ :code:`DISC`\ ) on their \ :code:`SELECT`\ statements.
#.
Sorts and merges will be performed in memory, if the amount of data being sorted allows.
#.
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:
.. index:: single:Environment Variables, TMPDIR
.. index:: single:TMPDIR Environment Variable
*
The
\ \ run-time environment variable ( :ref:`RunATimeAEnvironmentAVariables`)
.. index:: single:Environment Variables, TMP
.. index:: single:TMP Environment Variable
*
The
\ \ run-time environment variable
.. index:: single:Environment Variables, TEMP
.. index:: single:TEMP Environment Variable
*
The
\ \ run-time environment variable
(in that order).
#.
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`.
#.
If you specify a specific filename in the sort/merge work file's \ :code:`SELECT`\ , it will be ignored.
#. :ref:`DataADescriptionAClauses`, for information on the \ :code:`EXTERNAL`\ and \ :code:`GLOBAL`\ options.
.. index:: single:FILE-SECTION-Data-Item
.. _FILE-SECTION-Data-Item:
6.2.2 FILE-SECTION-Data-Item
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FILE-SECTION-Data-Item Syntax
::
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ]
~~~~~~ ~~~~~~ ~~~~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~ UNBOUNDED
~~~~~~~~~
[ DEPENDING ON identifier-2 ]
~~~~~~~~~
[ STEP identifier-6 ]
[ ASCENDING|DESCENDING KEY IS identifier-3 ]
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY identifier-4 ] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE [CHARACTER] ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ] . [ FILE-SECTION-Data-Item ]...
~~~~~
The \ :code:`LEFT`\ and \ :code:`RIGHT`\ (SYNCHRONIZED) clauses are syntactically recognized but are otherwise non-functional.
.. index:: single:CONSTANT
.. index:: single:Record
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
\ \ *Record*\ , even if it is an elementary item, provided that elementary item lacks the
\ \ :code:`CONSTANT`\ attribute.
#.
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.
#.
The reserved words \ :code:`SYNCHRONIZED`\ and \ :code:`SYNCHRONISED`\ are interchangeable. Both may be abbreviated to \ :code:`SYNC`\ .
#.
The reserved word \ :code:`PICTURE`\ may be abbreviated to \ :code:`PIC`\ .
#.
As the syntax diagram shows, the definition of a <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:
* Another 01-level item is found
signifies the start of another record layout for the file.
* Another \ :code:`FD`\ or \ :code:`SD`\ is found
marks the completion of the detailed description of the file and begins another.
* 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.
#.
Every FILE-SECTION-Data-Item description must be terminated with a period.
#.
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 \ :code:`READ`\ statement ( :ref:`READ`) or a \ :code:`RETURN`\ statement ( :ref:`RETURN`) will deliver data read from the file and from which a \ :code:`WRITE`\ statement ( :ref:`WRITE`) or \ :code:`RELEASE`\ statement ( :ref:`RELEASE`) statement will obtain the data to be written to the file.
#.
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 \ :code:`SAME RECORD AREA`\ ( :ref:`SAMEARECORDAAREA`) clause.
#.
The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 66, 77, 78 and 88 all have special uses --- :ref:`SpecialADataAItems`, for details.
#.
Not specifying an <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.
#.
\ :code:`EXTERNAL`\ cannot be combined with \ :code:`GLOBAL`\ or \ :code:`REDEFINES`\ .
#.
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.
#.
:ref:`DataADescriptionAClauses`, for information on the usage of the various data description clauses.
.. index:: single:WORKING-STORAGE SECTION
.. _WORKING-STORAGEASECTION:
6.3 WORKING-STORAGE SECTION
---------------------------
WORKING-STORAGE-SECTION-Data-Item Syntax
::
level-number [ identifier-1 | FILLER ] [ IS GLOBAL | EXTERNAL ]
~~~~~~ ~~~~~~ ~~~~~~~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~ UNBOUNDED
~~~~~~~~~
[ DEPENDING ON identifier-2 ]
~~~~~~~~~
[ ASCENDING|DESCENDING KEY IS identifier-3 ]
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY identifier-4 ] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ WORKING-STORAGE-SECTION-Data-Item ]...
~~~~~ ~~~
The \ :code:`LEFT`\ and \ :code:`RIGHT`\ (SYNCHRONIZED) clauses are syntactically recognized but are otherwise non-functional.
The working-storage section is used to describe data items that are not part of files, screens or reports and whose data values persist throughout the execution of the program.
#.
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.
#.
The reserved words \ :code:`SYNCHRONIZED`\ and \ :code:`SYNCHRONISED`\ are interchangeable. Both may be abbreviated as \ :code:`SYNC`\ .
#.
The reserved word \ :code:`PICTURE`\ may be abbreviated to \ :code:`PIC`\ .
#.
The reserved word \ :code:`JUSTIFIED`\ may be abbreviated to \ :code:`JUST`\ .
#.
As the syntax diagram shows, the definition of a \ :code:`<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:
*
Another 01-level item is found --- this signifies the end of the definition of one record and the start of a another.
*
A 77-level item is found --- this signifies the end of the definition of the record and begins the definition of a special data item; :ref:`77-LevelADataAItems`, for more information.
*
A division or section header is found --- this also marks the completion of a record and signifies the end of the working-storage section as well.
#.
Every \ :code:`<WORKING-STORAGE-SECTION-Data-Item>`\ description must be terminated with a period.
#.
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.
#.
Level numbers 66, 77, 78 and 88 all have special uses --- :ref:`SpecialADataAItems`, for details.
#.
Not specifying an <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.
#.
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 \ :code:`CANCEL`\ statement ( :ref:`CANCEL`)), in which case initialization will happen each time they are loaded. :ref:`DataAInitialization`, for a discussion of the initialization rules.
#.
:ref:`DataADescriptionAClauses`, for information on the usage of the various data description clauses.
.. index:: single:LOCAL-STORAGE SECTION
.. _LOCAL-STORAGEASECTION:
6.4 LOCAL-STORAGE SECTION
-------------------------
LOCAL-STORAGE-SECTION-Data-Item Syntax
::
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ]
~~~~~~ ~~~~~~ ~~~~~~~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~ UNBOUNDED
~~~~~~~~~
[ DEPENDING ON identifier-2 ]
~~~~~~~~~
[ ASCENDING|DESCENDING KEY IS identifier-3 ]
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY identifier-4 ] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ LOCAL-STORAGE-SECTION-Data-Item ]...
~~~~~ ~~~
The \ :code:`LEFT`\ and \ :code:`RIGHT`\ (SYNCHRONIZED) clauses are syntactically recognized but are otherwise non-functional.
The local-storage section is similar to working-storage, but describes data within a subprogram that will be dynamically allocated and initialized (automatically) each time the subprogram is executed. :ref:`DataAInitialization`, for the rules of data initialization.
#.
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.
#.
The reserved words \ :code:`SYNCHRONIZED`\ and \ :code:`SYNCHRONISED`\ are interchangeable. Both may be abbreviated as \ :code:`SYNC`\ .
#.
The reserved word \ :code:`PICTURE`\ may be abbreviated to \ :code:`PIC`\ .
#.
The reserved word \ :code:`JUSTIFIED`\ may be abbreviated to \ :code:`JUST`\ .
#.
As the syntax diagram shows, the definition of a \ :code:`<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:
*
Another 01-level item is found --- this signifies the end of the definition of one record and the start of a another.
*
A division or section header is found --- this also marks the completion of a record and signifies the end of the local-storage section as well.
#.
Every \ :code:`<LOCAL-STORAGE-SECTION-Data-Item>`\ description must be terminated with a period.
#.
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.
#.
Level numbers 66, 77, 78 and 88 all have special uses --- :ref:`SpecialADataAItems`, for details.
#.
Not specifying an <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.
#.
Local-storage cannot be used in nested subprograms.
#.
:ref:`DataADescriptionAClauses`, for information on the usage of the various data description clauses.
.. index:: single:LINKAGE SECTION
.. _LINKAGEASECTION:
6.5 LINKAGE SECTION
-------------------
LINKAGE-SECTION-Data-Item Syntax
::
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ]
~~~~~~ ~~~~~~ ~~~~~~~~
[ ANY LENGTH ]
~~~ ~~~~~~
[ ANY NUMERIC ]
~~~ ~~~~~~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
~~~~~~ ~~
[ DEPENDING ON identifier-3 ]
~~~~~~~~~
[ ASCENDING|DESCENDING KEY IS identifier-4 ]
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY identifier-5 ] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-6 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ] . [ LINKAGE-SECTION-Data-Item ]...
~~~~~
The \ :code:`LEFT`\ and \ :code:`RIGHT`\ (SYNCHRONIZED) clauses are syntactically recognized but are otherwise non-functional.
The linkage section describes data within a subprogram that serves as either input arguments to or output results from the subprogram.
#.
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.
#.
The reserved words \ :code:`SYNCHRONIZED`\ and "\ :code:`SYNCHRONISED`\ " are interchangeable. Both may be abbreviated as \ :code:`SYNC`\ .
#.
The reserved word \ :code:`PICTURE`\ may be abbreviated to \ :code:`PIC`\ .
#.
The reserved word \ :code:`JUSTIFIED`\ may be abbreviated to \ :code:`JUST`\ .
#.
As the syntax diagram shows, the definition of a \ :code:`<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:
*
Another 01-level item is found --- this signifies the end of the definition of one record and the start of a another.
*
A division or section header is found --- this also marks the completion of a record and signifies the end of the linkage section as well.
#.
Every \ :code:`<LINKAGE-SECTION-Data-Item>`\ description must be terminated with a period.
#.
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.
#.
Level numbers 66, 77, 78 and 88 all have special uses --- :ref:`SpecialADataAItems`, for details.
#.
It is expected that:
#.
A linkage section should occur only within a subprogram. The compiler will not prevent its use in a main program, however.
#.
All 01-level data items described within a subprogram's linkage section should appear in a \ :code:`PROCEDURE DIVISION USING`\ ( :ref:`PROCEDUREADIVISIONAUSING`) or as arguments on an \ :code:`ENTRY`\ statement.
#.
Each 01-level data item described within a subprogram's linkage section should correspond to an argument passed on a \ :code:`CALL`\ statement ( :ref:`CALL`) or an argument on a function call to the subprogram.
#.
Not specifying an <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`\ .
#.
No storage is allocated for data defined in the linkage section; the data descriptions there are merely defining storage areas that will be passed to the subprogram by a calling program. Therefore, any discussion of the default initialization of such data is irrelevant. It \ *is*\ possible, however, to manually allocate linkage section data items that aren't subprogram arguments via the \ :code:`ALLOCATE`\ statement ( :ref:`ALLOCATE`) statement. In such cases, initialization will take place as per the documentation of that statement.
#.
:ref:`DataADescriptionAClauses`, for information on the usage of the various data description clauses.
.. index:: single:REPORT SECTION
.. _REPORTASECTION:
6.6 REPORT SECTION
------------------
REPORT SECTION Syntax
::
[ REPORT SECTION.
~~~~~~ ~~~~~~~
{ Report-Description [ { Report-Group-Definition } ]... }... ]
{ { 01-Level-Constant } }
{ { 78-Level-Constant } }
{ 01-Level-Constant }
{ 78-Level-Constant }
Report-Description (RD) Syntax
::
RD report-name [ IS GLOBAL ]
~~ ~~~~~~
[ CODE IS literal-1 | identifier-1 ]
~~~~
[ { CONTROL IS } { FINAL }... ]
{ ~~~~~~~ } { ~~~~~ }
{ CONTROLS ARE } { identifier-2 }
~~~~~~~~
[ PAGE [ { LIMIT IS } ] [ { literal-2 } LINES ]
~~~~ { ~~~~~ } { identifier-3 } ~~~~
{ LIMITS ARE }
~~~~~~
[ literal-3 | identifier-4 COLUMNS|COLS ]
~~~~~~~ ~~~~
[ HEADING IS literal-4 | identifier-5 ]
~~~~~~~
[ FIRST DE|DETAIL IS literal-5 | identifier-6 ]
~~~~~ ~~ ~~~~~~
[ LAST CH|{CONTROL HEADING} IS literal-6 | identifier-7 ]
~~~~ ~~ ~~~~~~~ ~~~~~~~
[ LAST DE|DETAIL IS literal-7 | identifier-8 ]
~~~~ ~~ ~~~~~~
[ FOOTING IS literal-8 | identifier-9 ] ] .
~~~~~~~
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.
#.
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.
#.
The phrases \ :code:`CONTROL IS`\ and \ :code:`CONTROLS ARE`\ are interchangeable, as are the \ :code:`PAGE LIMIT`\ and \ :code:`PAGE LIMITS`\ phrases.
#.
The reserved word \ :code:`LINES`\ may be abbreviated as \ :code:`LINE`\ .
#.
The reserved word \ :code:`COLUMNS`\ may be abbreviated as \ :code:`COLS`\ .
#.
Each report referenced on a \ :code:`REPORT IS`\ clause ( :ref:`FileASort-Description`) must be described with a report description (\ :code:`RD`\ ).
#.
:ref:`GLOBAL`, for information on the \ :code:`GLOBAL`\ option.
#.
Please see :ref:`ReportAWriterAFeatures`, if you have not read it already. It will familiarize you with the Report Writer terminology that follows.
.. index:: single:PAGE LIMITS
#.
The following rules pertain to the
\ \ :code:`PAGE LIMITS`\ clause:
#.
If no \ :code:`PAGE LIMITS`\ clause is specified, the entire report will be generated as if it consists of a single arbitrarily long page.
#.
All literals (<literal-2> through <literal-8>) must be numeric with non-zero positive integer values.
#.
All identifiers (<identifier-2> through <identifier-8>) must be numeric, unedited with non-zero positive integer values.
#.
Any value specified for <literal-2> or <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 --- :ref:`FileASort-Description`).
#.
Any value specified for <literal-3> or <identifier-3> will be ignored.
.. index:: single:HEADING
#.
The
\ \ :code:`HEADING`\ clause defines the first line number at which a report heading or page heading may be presented.
.. index:: single:FIRST DETAIL
#.
The
\ \ :code:`FIRST DETAIL`\ clause defines the first line at which a detail group may be presented.
.. index:: single:LAST CONTROL
#.
The
\ \ :code:`LAST CONTROL`\ \ :code:`HEADING`\ clause defines the last line at which any line of a control heading may be presented.
.. index:: single:LAST DETAIL
#.
The
\ \ :code:`LAST DETAIL`\ clause defines the last line at which any line of a detail group may be presented.
.. index:: single:FOOTING
#.
The
\ \ :code:`FOOTING`\ clause defines the last line at which any line of a control footing group may be presented.
#.
The following rules establish default values for the various \ :code:`PAGE LIMIT`\ clauses, assuming there is one:
* \ :code:`HEADING`\
default is one (1)
* \ :code:`FIRST DETAIL HEADING`\
value is used
* \ :code:`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`\
* \ :code:`LAST DETAIL`\
value from \ :code:`FOOTING`\ or, if that is absent, the value from \ :code:`PAGE LIMIT`\
* \ :code:`FOOTING`\
value from \ :code:`LAST DETAIL`\ or, if that is absent, the value from \ :code:`PAGE LIMIT`\
#.
For the values specified on a \ :code:`PAGE LIMIT`\ clause to be valid, all of the following must be true:
*
\ :code:`FIRST DETAIL`\ :math:`\leq` \ :code:`HEADING`\
*
\ :code:`LAST CONTROL HEADING`\ :math:`\leq` \ :code:`FIRST DETAIL`\
*
\ :code:`LAST DETAIL`\ :math:`\leq` \ :code:`LAST CONTROL HEADING`\
*
\ :code:`FOOTING`\ :math:`\leq` \ :code:`LAST DETAIL`\
.. index:: single:CONTROL
#.
The following rules pertain to the
\ \ :code:`CONTROL`\ clause:
#.
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`\ .
.. index:: single:FINAL
#.
Include the reserved word
\ \ :code:`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`\ ).
#.
If you specify \ :code:`FINAL`\ , it must be the first control break named in the \ :code:`RD`\ .
#.
Any <identifier-9> specifications included on the \ :code:`CONTROL`\ clause are referencing data names defined in any data division section except for the report section.
#.
There must be a \ :code:`CONTROL HEADING`\ and/or \ :code:`CONTROL FOOTING`\ report group defined in the report section for each <identifier-9>.
#.
At execution time:
*
Each time a \ :code:`GENERATE`\ statement ( :ref:`GENERATE`) is executed against a detail report group defined for this \ :code:`RD`\ , the RWCS will check the contents of each <identifier-2> data item; whenever an <identifier-9>'s value has changed since the previous \ :code:`GENERATE`\ , a control break condition will be in effect for that <identifier-2>.
*
Once the list of control breaks has been determined, the \ :code:`CONTROL FOOTING`\ for each <identifier-2> having a control break (if any such report group is defined) will be presented.
*
Next, the \ :code:`CONTROL HEADING`\ for each <identifier-2> having a control break (if any such report group is defined) will be presented.
*
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.
*
Only after this processing has occurred will the detail report group specified on the \ :code:`GENERATE`\ be presented.
#. Each \ :code:`RD`\ will have the following allocated for it:
.. index:: single:Special Registers, PAGE-COUNTER
.. index:: single:PAGE-COUNTER Special Register
#.
The
\ \ \ :code:`PAGE-COUNTER`\ special register ( :ref:`SpecialARegisters`), which will contain the current report page number.
*
This register will be set to a value of 1 when an \ :code:`INITIATE`\ statement ( :ref:`INITIATE`) is executed for the report and will be incremented by 1 each time the RWCS starts a new page of the report.
*
References to \ :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.
*
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.
.. index:: single:Special Registers, LINE-COUNTER
.. index:: single:LINE-COUNTER Special Register
#. The
\ \ \ :code:`LINE-COUNTER`\ special register, which will contain the current line number on the current page.
#. The \ :code:`RD`\ must be followed by at least one 01-level report group definition.
.. index:: single:Report Group Definitions
.. _ReportAGroupADefinitions:
6.6.1 Report Group Definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Report-Group-Definition Syntax
::
01 [ identifier-1 ]
[ LINE NUMBER IS { integer-1 [ [ ON NEXT PAGE ] } ]
~~~~ { ~~~~ ~~~~ }
{ +|PLUS integer-1 }
{ ~~~~ }
{ ON NEXT PAGE }
~~~~ ~~~~
[ NEXT GROUP IS { [ +|PLUS ] integer-2 } ]
~~~~ ~~~~~ { ~~~~ }
{ NEXT|{NEXT PAGE}|PAGE }
~~~~ ~~~~ ~~~~ ~~~~
[ TYPE IS { RH|{REPORT HEADING} } ]
~~~~ { ~~ ~~~~~~ ~~~~~~~ }
{ PH|{PAGE HEADING} }
{ ~~ ~~~~ ~~~~~~~ }
{ CH|{CONTROL HEADING} FINAL|identifier-2 }
{ ~~ ~~~~~~~ ~~~~~~~ ~~~~~ }
{ DE|DETAIL }
{ ~~ ~~~~~~ }
{ CF|{CONTROL FOOTING} FINAL|identifier-2 }
{ ~~ ~~~~~~~ ~~~~~~~ ~~~~~ }
{ PF|{PAGE FOOTING} }
{ ~~ ~~~~ ~~~~~~~ }
{ RF|{REPORT FOOTING} }
~~ ~~~~~~ ~~~~~~~
. [ REPORT-SECTION-Data-Item ]...
The syntax shown here documents how a report group is defined to a report. This syntax is valid only in the report section, and only then after an \ :code:`RD`\ .
#.
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.
#.
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`\ .
#.
The report group being defined will be a part of the most-recently coded \ :code:`RD`\ .
#.
The \ :code:`TYPE`\ ( :ref:`TYPE`) clause specifies the type of report group being defined.
#.
The level number used for a report group definition must be 01.
#.
The optional <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`\ .
#.
No two report groups in the same report (\ :code:`RD`\ ) may named with the same <identifier-1>. There may, however, be multiple <identifier-1> definitions in different reports. In such instances, references to <identifier-1> must be qualified by the report name.
#.
There may only be one report heading, report footing, final control heading, final control footing, page heading and page footing defined per report.
#.
Report group declarations must be followed by at least one \ :code:`<REPORT-SECTION-Data-Item>`\ with a level number in the range 02-49.
#.
:ref:`DataADescriptionAClauses`, for information on the usage of the various data description clauses.
.. index:: single:REPORT SECTION Data Items
.. _REPORTASECTIONADataAItems:
6.6.2 REPORT SECTION Data Items
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
REPORT-SECTION-Data-Item Syntax
::
level-number [ identifier-1 ]
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ COLUMN [ { NUMBER IS } ] [ +|PLUS ] integer-1 ]
~~~ { ~~~~~~ } ~~~~
{ NUMBERS ARE }
~~~~~~~
[ GROUP INDICATE ]
~~~~~ ~~~~~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] } ]
~~~~ { +|PLUS integer-2 ~~~~ ~~~~ }
{ ~~~~ }
{ ON NEXT PAGE }
~~~~ ~~~~
[ OCCURS [ integer-3 TO ] integer-4 TIMES
~~~~~~ ~~ UNBOUNDED
~~~~~~~~~
[ DEPENDING ON identifier-2 ]
~~~~~~~~~
[ STEP integer-5 ]
~~~~
[ VARYING identifier-3 FROM { identifier-4 } BY { identifier-5 } ]
~~~~~~~ ~~~~ { integer-6 } ~~ { integer-7 }
[ PICTURE IS picture-string ]
~~~
[ PRESENT WHEN condition-name ]
~~~~~~~ ~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ { SOURCE IS literal-1|identifier-6 [ ROUNDED ] } ]
{ ~~~~~~ ~~~~~~~ }
{ SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ] }
{ ~~~ { literal-2 } { ~~~~~ ~~~~~ } }
{ VALUE IS [ ALL ] literal-3 { UPON identifier-9 } }
~~~~~ ~~~ ~~~~
. [ REPORT-SECTION-Data-Item ]...
Data item descriptions describing the report lines and fields that make up the substance of a report group immediately follow the definition of that group.
#.
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.
#.
The reserved word \ :code:`COLUMN`\ may be abbreviated as \ :code:`COL`\ .
#.
The reserved word \ :code:`JUSTIFIED`\ may be abbreviated as \ :code:`JUST`\ .
#.
The reserved word \ :code:`PICTURE`\ may be abbreviated as \ :code:`PIC`\ .
#.
The \ :code:`SOURCE`\ ( :ref:`SOURCE`), \ :code:`SUM`\ ( :ref:`SUM`) and \ :code:`VALUE`\ ( :ref:`VALUE`) clauses, valid only on an elementary item, are mutually-exclusive of each other.
.. index:: single:PICTURE
#.
Group items (those without
\ \ :code:`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 \ :code:`LINE`\ ( :ref:`LINE`) clauses and no \ :code:`COLUMN`\ ( :ref:`COLUMN`) clauses while elementary items will be specified the other way around.
#.
:ref:`DataADescriptionAClauses`, for information on the usage of the various data description clauses.
.. index:: single:SCREEN SECTION
.. _SCREENASECTION:
6.7 SCREEN SECTION
------------------
SCREEN-SECTION-Data-Item Syntax
::
level-number [ identifier-1 | FILLER ]
~~~~~~
[ AUTO | AUTO-SKIP | AUTOTERMINATE ] [ BELL | BEEP ]
~~~~ ~~~~~~~~~ ~~~~~~~~~~~~~ ~~~~ ~~~~
[ BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1 | identifier-2 ]
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
[ BEFORE TIME | BASED ]
~~~~~~ ~~~~ ~~~~~
[ BLANK LINE|SCREEN ] [ ERASE EOL|EOS ]
~~~~~ ~~~~ ~~~~~~ ~~~~~ ~~~ ~~~
[ BLANK WHEN ZERO ] [ JUSTIFIED RIGHT ]
~~~~~ ~~~~ ~~~~
[ BLINK ] [ HIGHLIGHT | LOWLIGHT ] [ REVERSE-VIDEO ]
~~~~~ ~~~~~~~~~ ~~~~~~~~ ~~~~~~~~~~~~~
[ COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ]
~~~ ~~~~
[ CONSTANT | EMPTY CHECK ]
~~~~~~~ ~~~~~ ~~~~~
[ FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-3 | identifier-4 ]
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
[ { FROM literal-1 | identifier-5 } ]
{ ~~~~ }
{ TO identifier-5 }
{ ~~ }
{ USING identifier-5 }
{ ~~~~~ }
{ VALUE IS [ ALL ] literal-1 }
~~~~~ ~~~
[ FULL | LENGTH-CHECK ] [ REQUIRED | EMPTY-CHECK ] [ SECURE | NO-ECHO ]
~~~~ ~~~~~~~~~~~~ ~~~~~~~~ ~~~~~~~~~~~ ~~~~~~ ~~~~~~~
[ LEFTLINE ] [ OVERLINE ] [ UNDERLINE ]
~~~~~~~~ ~~~~~~~~ ~~~~~~~~~
[ LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ]
~~~~ ~~~~
[ NO-ECHO | NO UPDATE ]
~~~~~~~ ~~ ~~~~~
[ OCCURS integer-5 TIMES ]
~~~~~~
[ PICTURE IS picture-string ]
~~~
[ PROMPT [ CHARACTER IS literal-2 | identifier-7 ]
~~~~~~ ~~~~~~~~~
[ SCROLL DOWN | SCROLL UP | SIZE | TIME OUT ]
~~~~~~ ~~~~ ~~~~~~ ~~ ~~~~ ~~~~ ~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ UPDATE ]
~~~~~~
. [ SCREEN-SECTION-Data-Item ]...
The screen section describes the screens to be displayed during terminal/console I-O.
#.
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.
#.
The reserved word \ :code:`COLUMN`\ may be abbreviated as \ :code:`COL`\ .
#.
The reserved word \ :code:`PICTURE`\ may be abbreviated as \ :code:`PIC`\ .
#.
The following sets of reserved words are interchangeable:
*
\ :code:`AUTO`\ , \ :code:`AUTO-SKIP`\ and \ :code:`AUTOTERMINATE`\
*
\ :code:`BACKGROUND-COLOR`\ and \ :code:`BACKGROUND-COLOUR`\
*
\ :code:`BELL`\ and \ :code:`BEEP`\
*
\ :code:`FOREGROUND-COLOR`\ and \ :code:`FOREGROUND-COLOUR`\
*
\ :code:`FULL`\ and \ :code:`LENGTH-CHECK`\
*
\ :code:`REQUIRED`\ and \ :code:`EMPTY-CHECK`\
*
\ :code:`SECURE`\ and \ :code:`NO-ECHO`\
#.
Data items defined in the screen section describe input, output or combination screen layouts to be used with \ :code:`ACCEPT data-item`\ statement ( :ref:`ACCEPTAdata-item`) or \ :code:`DISPLAY data-item`\ statement ( :ref:`DISPLAYAdata-item`) statements. These screen layouts may define the entire available screen area or any subset of it.
#.
The term \ *available screen area*\ is a nebulous one in those environments where command-line shell sessions are invoked within a graphical user-interface environment, as will be the case on Windows, OSX and most Unix/Linux systems --- these environments allow command-line session windows to exist with a variable number of available screen rows and columns. When you are designing GnuCOBOL screens, you need to do so with an awareness of the logical screen row/column geometry the program will be executing within.
#.
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.
#.
Without \ :code:`LINE`\ ( :ref:`LINE`) or \ :code:`COLUMN`\ ( :ref:`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 \ :code:`DISPLAY data-item`\ statement that presents the screen item. After a field is presented to the console window, the next field will be presented immediately following that field.
#.
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 \ :code:`DISPLAY data-item`\ statement that presents that data item to the screen. The same is true of \ :code:`COLUMN`\ clauses.
#.
The \ :code:`Tab`\ and \ :code:`Back-Tab`\ (\ :code:`Shift`\ -\ :code:`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.
#.
:ref:`DataADescriptionAClauses`, for information on the usage of the various data description clauses.
.. index:: single:Special Data Items
.. _SpecialADataAItems:
6.8 Special Data Items
----------------------
.. index:: single:01-Level Constants
.. _01-LevelAConstants:
6.8.1 01-Level Constants
~~~~~~~~~~~~~~~~~~~~~~~~
01-Level-Constant Syntax
::
01 constant-name-1 CONSTANT [ IS GLOBAL ]
~~~~~~~~ ~~~~~~
{ AS { literal-1 } }
{ { arithmetic-expression-1 } }
{ { { BYTE-LENGTH } OF { identifier-1 } } }
{ { { ~~~~~~~~~~~ } { usage-name } } }
{ { { LENGTH } } }
{ ~~~~~~ }
{ FROM CDF-variable-name-1 }
~~~~
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 \ :code:`>>DEFINE`\ CDF directive ( :ref:`AADEFINE`) constants, \ :code:`>>SET`\ CDF directive ( :ref:`AASET`) constants, 78-level constants ( :ref:`78-LevelADataAItems` and arithmetic-expression-1).
#.
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.
#.
:ref:`GLOBAL`, for information on the \ :code:`GLOBAL`\ option.
#.
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 \ :code:`USAGE`\ ( :ref:`USAGE`) type --- something not possible with the other types of constants.
#.
Constants defined in this way become undefined once an \ :code:`END PROGRAM`\ or \ :code:`END FUNCTION`\ is encountered in the input source.
.. index:: single:LENGTH
.. index:: single:BYTE-LENGTH
#.
Data descriptions of this form do not actually allocate any storage --- they merely define a name (<constant-name-1>) that may be used anywhere a numeric literal (see
\ \ :code:`BYTE-LENGTH`\ or
\ \ :code:`LENGTH`\ options) or a literal of the same type as <literal-1> may be used.
#.
The <constant-name-1> name may not be referenced on a CDF directive.
#.
Care must be taken that <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.
#.
The value specified for <usage-name> may be any \ :code:`USAGE`\ that does not use a \ :code:`PICTURE`\ ( :ref:`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`\ .
#.
The \ :code:`BYTE-LENGTH`\ clause will produce a numeric value for <constant-name-1> identical to that which would be returned by the \ :code:`BYTE-LENGTH`\ intrinsic function executed against <identifier-1> or a data item declared with a \ :code:`USAGE`\ of <usage-name>.
#.
The \ :code:`LENGTH`\ clause will produce a numeric value for <constant-name-1> identical to that which would be returned by the \ :code:`LENGTH`\ intrinsic function executed against <identifier-1> or a data item declared with a \ :code:`USAGE`\ of <usage-name>.
Here is usage examples of the option arithmetic-expression
::
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.
Here is another example of using the option arithmetic-expression.
::
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.
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.
::
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.
The output of this program, on a Windows 7 system with a 32-bit MinGW build of GnuCOBOL is:
::
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.
.. index:: single:66-Level Data Items
.. _66-LevelADataAItems:
6.8.2 66-Level Data Items
~~~~~~~~~~~~~~~~~~~~~~~~~
66-Level-Data-Item Syntax
::
66 identifier-1 RENAMES identifier-2 [ THRU|THROUGH identifier-3 ] .
~~~~~~~ ~~~~ ~~~~~~~
This syntax is valid in the following sections:
\ :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.
#.
The reserved words \ :code:`THRU`\ and \ :code:`THROUGH`\ are interchangeable.
#.
A level-66 data item cannot rename a level-66, level-01, level-77, or level-88 data item.
#.
There may be multiple level-66 data items that rename data items contained within the same 01-level record description.
#.
All \ :code:`RENAMES`\ entries associated with one logical record must immediately follow that record's last data description entry.
.. index:: single:77-Level Data Items
.. _77-LevelADataAItems:
6.8.3 77-Level Data Items
~~~~~~~~~~~~~~~~~~~~~~~~~
77-Level-Data-Item Syntax
::
77 identifier-1 [ IS GLOBAL|EXTERNAL ]
~~~~~~ ~~~~~~~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ VALUE IS [ ALL ] literal-1 ] .
~~~~~ ~~~
The \ :code:`LEFT`\ and \ :code:`RIGHT`\ (SYNCHRONIZED) clauses are syntactically recognized but are otherwise non-functional.
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.
#.
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.
#.
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`\ .
#.
New programs requiring a stand-alone elementary item should be coded to use a level number of 01 rather than 77.
#.
:ref:`DataADescriptionAClauses`, for information on the usage of the various data description clauses.
.. index:: single:78-Level Data Items
.. _78-LevelADataAItems:
6.8.4 78-Level Data Items
~~~~~~~~~~~~~~~~~~~~~~~~~
78-Level-Constant Syntax
::
78 constant-name-1 VALUE IS ( literal-1 )
~~~~~
{ arithmetic-expression-1 }
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 \ :code:`>>DEFINE`\ CDF directive ( :ref:`AADEFINE`) constants, \ :code:`>>SET`\ CDF directive ( :ref:`AASET`) constants and 01-level constants ( :ref:`01-LevelAConstants`).
#.
The reserved word \ :code:`IS`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
#.
Constants defined in this way become undefined once an \ :code:`END PROGRAM`\ or \ :code:`END FUNCTION`\ is encountered in the input source.
#.
Data descriptions of this form do not actually allocate any storage --- they merely define a name (<constant-name-1>) that may be used anywhere a literal of the same type as <literal-1> may be used.
#.
The <constant-name-1> name may not be referenced on a CDF directive.
#.
Care must be taken that <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.
#.
See in 6.8.1 for examples of using the option arithmetic-expression.
.. index:: single:88-Level Data Items
.. _88-LevelADataAItems:
6.8.5 88-Level Data Items
~~~~~~~~~~~~~~~~~~~~~~~~~
.. index:: single:Condition Names
88-Level-Data-Item Syntax
::
88 condition-name-1 { VALUE IS } {literal-1 [ THRU|THROUGH literal-2 ]}...
{ ~~~~~ } ~~~~ ~~~~~~~
{ VALUES ARE }
~~~~~~
[ WHEN SET TO FALSE IS literal-3 ] .
~~~~~
This syntax is valid in the following sections:
\ :code:`FILE`\ , \ :code:`WORKING-STORAGE`\ , \ :code:`LOCAL-STORAGE`\ , \ :code:`LINKAGE`\ , \ :code:`REPORT`\ , \ :code:`SCREEN`\
Condition names are Boolean (\ *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.
#.
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.
#.
The reserved words \ :code:`THRU`\ and \ :code:`THROUGH`\ are interchangeable.
#.
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 \ :code:`VALUE`\ ( :ref:`VALUE`) clause, <condition-name-1> will take on the value of \ :code:`TRUE`\ .
#.
Condition names do not occupy any storage.
#.
The optional \ :code:`THROUGH`\ clause allows a range of possible \ :code:`TRUE`\ values to be specified.
#.
Whenever the parent data item assumes any value \ *except*\ one of the values specified on <condition-name-1>'s \ :code:`VALUE`\ clause, <condition-name-1> will take on the value of FALSE.
#.
Executing the statement \ :code:`SET <condition-name-1> TO TRUE`\ will cause <condition-name-1>'s parent data item to take on the first value specified on <condition-name-1>'s \ :code:`VALUE`\ clause.
#.
Executing the statement \ :code:`SET <condition-name-1> TO FALSE`\ will cause <condition-name-1>'s parent data item to take on the value specified on <condition-name-1>'s \ :code:`FALSE`\ clause. If <condition-name-1> does not have a \ :code:`FALSE`\ clause, the \ :code:`SET`\ ( :ref:`SET`) statement will generate an error message at compilation time.
#.
:ref:`ConditionANames`, for more information.
.. index:: single:Data Description Clauses
.. _DataADescriptionAClauses:
6.9 Data Description Clauses
----------------------------
.. index:: single:ANY LENGTH
.. _ANYALENGTH:
6.9.1 ANY LENGTH
~~~~~~~~~~~~~~~~
ANY LENGTH Attribute Syntax
::
ANY LENGTH
~~~ ~~~~~~
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 \ :code:`PICTURE`\ ( :ref:`PICTURE`) clause that specifies exactly one A, X, U or 1 symbol.
#.
The \ :code:`ANY LENGTH`\ and \ :code:`BASED`\ ( :ref:`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.
.. index:: single:ANY NUMERIC
.. _ANYANUMERIC:
6.9.2 ANY NUMERIC
~~~~~~~~~~~~~~~~~
ANY NUMERIC Attribute Syntax
::
ANY NUMERIC
~~~ ~~~~~~~
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 \ :code:`PICTURE`\ ( :ref:`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.
#.
The \ :code:`ANY NUMERIC`\ and \ :code:`BASED`\ ( :ref:`BASED`) clauses cannot be used together in the same data item description.
.. index:: single:AUTO
.. _AUTO:
6.9.3 AUTO
~~~~~~~~~~
AUTO Attribute Syntax
::
AUTO
~~~~
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.
#.
The \ :code:`AUTO`\ , \ :code:`AUTO-SKIP`\ ( :ref:`AUTO-SKIP`) and \ :code:`AUTOTERMINATE`\ ( :ref:`AUTOTERMINATE`) clauses are interchangeable, and may not be used together in the same data item description.
.. index:: single:AUTO-SKIP
.. _AUTO-SKIP:
6.9.4 AUTO-SKIP
~~~~~~~~~~~~~~~
AUTO-SKIP Attribute Syntax
::
AUTO-SKIP
~~~~~~~~~
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.
#.
The \ :code:`AUTO`\ ( :ref:`AUTO`), \ :code:`AUTO-SKIP`\ and \ :code:`AUTOTERMINATE`\ ( :ref:`AUTOTERMINATE`) clauses are interchangeable, and may not be used together in the same data item description.
.. index:: single:AUTOTERMINATE
.. _AUTOTERMINATE:
6.9.5 AUTOTERMINATE
~~~~~~~~~~~~~~~~~~~
AUTOTERMINATE Attribute Syntax
::
AUTOTERMINATE
~~~~~~~~~~~~~
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.
#.
The \ :code:`AUTO`\ ( :ref:`AUTO`), \ :code:`AUTO-SKIP`\ ( :ref:`AUTO-SKIP`) and \ :code:`AUTOTERMINATE`\ clauses are interchangeable, and may not be used together in the same data item description.
.. index:: single:BACKGROUND-COLOR
.. _BACKGROUND-COLOR:
6.9.6 BACKGROUND-COLOR
~~~~~~~~~~~~~~~~~~~~~~
BACKGROUND-COLOR Attribute Syntax
::
BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1 | identifier-1
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
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.
#.
The reserved word \ :code:`IS`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
#.
The reserved words \ :code:`BACKGROUND-COLOR`\ and \ :code:`BACKGROUND-COLOUR`\ are interchangeable.
#.
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).
#.
Colors may also be specified using a numeric non-edited identifier whose value is in the range 0-7.
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.e.*\
::
DISPLAY "Name: " BACKGROUND-COLOR COB-YELLOW
NAME-VAR BACKGROUND-COLOR COB-BLACK
END-DISPLAY
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:BEFORE TIME
.. _BEFOREATIME:
6.9.7 BEFORE TIME
~~~~~~~~~~~~~~~~~
BEFORE TIME Attribute Syntax
::
BEFORE TIME
~~~~~~ ~~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
This clause is used to specify time sequence etc, etc, etc. NEEDS CONTENT HERE.
.. index:: single:BASED
.. _BASED:
6.9.8 BASED
~~~~~~~~~~~
BASED Attribute Syntax
::
BASED
~~~~~
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 \ :code:`ALLOCATE`\ ( :ref:`ALLOCATE`) or \ :code:`SET ADDRESS`\ ( :ref:`SETAADDRESS`) statements are used to allocate space for and (optionally) initialize such items.
#.
The \ :code:`BASED`\ and \ :code:`ANY LENGTH`\ ( :ref:`ANYALENGTH`) clauses cannot be used together in the same data item description.
#.
The \ :code:`BASED`\ clause may only be used on level 01 and level 77 data items.
.. index:: single:BEEP
.. _BEEP:
6.9.9 BEEP
~~~~~~~~~~
BEEP Attribute Syntax
::
BEEP
~~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
#.
The \ :code:`BEEP`\ and \ :code:`BELL`\ ( :ref:`BELL`) clauses are interchangeable, and may not be used together in the same data item description.
#.
Use this clause to cause an audible tone to occur when the screen item is \ :code:`DISPLAY`\ ed.
.. index:: single:BELL
.. _BELL:
6.9.10 BELL
~~~~~~~~~~~
BELL Attribute Syntax
::
BELL
~~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
#.
The \ :code:`BEEP`\ ( :ref:`BEEP`) and \ :code:`BELL`\ clauses are interchangeable, and may not be used together in the same data item description.
#.
Use this clause to cause an audible tone to occur when the screen item is \ :code:`DISPLAY`\ ed.
.. index:: single:BLANK
.. _BLANK:
6.9.11 BLANK
~~~~~~~~~~~~
BLANK Attribute Syntax
::
BLANK LINE|SCREEN
~~~~~ ~~~~ ~~~~~~
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`\ ).
#.
Blanked-out areas will have their foreground and background colors set to the attributes of the field containing the \ :code:`BLANK`\ clause.
#.
This clause is useful when one screen section item is being displayed over the top of a previously-displayed one.
.. index:: single:BLANK WHEN ZERO
.. _BLANKAWHENAZERO:
6.9.12 BLANK WHEN ZERO
~~~~~~~~~~~~~~~~~~~~~~
BLANK-WHEN-ZERO Attribute Syntax
::
BLANK WHEN ZERO
~~~~~ ~~~~
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.
#.
The reserved word \ :code:`WHEN`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
#.
This clause may only be used on a \ :code:`PIC 9`\ data item with a \ :code:`USAGE`\ ( :ref:`USAGE`) of \ :code:`DISPLAY`\ .
.. index:: single:BLINK
.. _BLINK:
6.9.13 BLINK
~~~~~~~~~~~~
BLINK Attribute Syntax
::
BLINK
~~~~~
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.
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:COLUMN
.. _COLUMN:
6.9.14 COLUMN
~~~~~~~~~~~~~
COLUMN (REPORT SECTION) Clause Syntax
::
COLUMN [ { NUMBER IS } ] [ +|PLUS ] integer-1 ]
~~~ { NUMBERS ARE } ~~~~
COLUMN (SCREEN SECTION) Clause Syntax
::
COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ]
~~~ ~~~~
This syntax is valid in the following sections:
\ :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).
#.
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.
#.
The reserved word \ :code:`COLUMN`\ may be abbreviated as \ :code:`COL`\ .
#.
The line location of a report section or screen section field will be determined by the \ :code:`LINE`\ ( :ref:`LINE`) clause.
#.
The value of <integer-1> must be 1 or greater.
#.
If <identifier-1> is used to specify either an absolute or relative column position, <identifier-1> must be defined as a numeric item of any \ :code:`USAGE`\ ( :ref:`USAGE`) other than \ :code:`COMPUTATIONAL-1`\ or \ :code:`COMPUTATIONAL-2`\ , without editing symbols. The value of <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.
#.
The column coordinate of a field may be stated on an absolute basis (\ *i.e.*\ \ :code:`COLUMN 5`\ ) or on a relative basis based upon the end of the previously-presented field (\ *i.e.*\ \ :code:`COLUMN PLUS 1`\ ).
#.
The symbol '\ :code:`+`\ ' may be used in lieu of the word \ :code:`PLUS`\ , if desired; if symbol '\ :code:`+`\ ' is used, however, there must be at least one space separating it from <integer-1>. Failure to include this space will cause the symbol '\ :code:`+`\ ' sign to be simply treated as part of <integer-1> and will treat the \ :code:`COLUMN`\ clause as an absolute column specification rather than a relative one.
#.
Using relative column positioning (\ :code:`COLUMN PLUS`\ ) has slightly different behaviour depending upon the section in which the clause is used, as follows:
#.
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 <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 \ :code:`SOURCE`\ ( :ref:`SOURCE`), \ :code:`SUM`\ ( :ref:`SUM`) or \ :code:`VALUE`\ ( :ref:`VALUE`) clause but has no \ :code:`COLUMN`\ clause, \ :code:`COLUMN PLUS 1`\ will be assumed.
#.
When used on a screen section data item, \ :code:`COLUMN PLUS`\ will position the new field so that it begins exactly <integer-1> or <identifier-1> characters past the \ *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 \ :code:`FROM`\ ( :ref:`FROM`), \ :code:`TO`\ ( :ref:`TO`), \ :code:`USING`\ ( :ref:`USING`) or \ :code:`VALUE`\ ( :ref:`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.
.. index:: single:CONSTANT
.. _CONSTANT:
6.9.15 CONSTANT
~~~~~~~~~~~~~~~
CONSTANT Attribute Syntax
::
CONSTANT
~~~~~~~~
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.
#.
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.
#.
:ref:`01-LevelAConstants`, for additional information.
.. index:: single:EMPTY-CHECK
.. _EMPTY-CHECK:
6.9.16 EMPTY-CHECK
~~~~~~~~~~~~~~~~~~
EMPTY-CHECK Attribute Syntax
::
EMPTY-CHECK
~~~~~~~~~~~
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).
#.
The \ :code:`EMPTY-CHECK`\ and \ :code:`REQUIRED`\ ( :ref:`REQUIRED`) clauses are interchangeable, and may not be used together in the same data item description.
#.
In order to take effect, the user must first move the cursor into the field having this clause in its definition.
#.
The \ :code:`ACCEPT data-item`\ statement ( :ref:`ACCEPTAdata-item`) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item \ *unless*\ data has been entered into the field. Function keys will still be allowed to terminate the \ :code:`ACCEPT`\ .
#.
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`\ .
.. index:: single:ERASE
.. _ERASE:
6.9.17 ERASE
~~~~~~~~~~~~
ERASE Clause Syntax
::
ERASE EOL|EOS
~~~~~ ~~~ ~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
.. index:: single:EOL
.. index:: single:EOS
\ :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`\ )
#.
Erased areas will have their foreground and background colors set to the attributes of the field containing the \ :code:`ERASE`\ clause.
#.
This clause is useful when one screen section item is being displayed over the top of a previously-displayed one.
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:EXTERNAL
.. _EXTERNAL:
6.9.18 EXTERNAL
~~~~~~~~~~~~~~~
EXTERNAL Attribute Syntax
::
EXTERNAL
~~~~~~~~
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`\ :ref:`FileASort-Description` as being shareable with other programs executed from the same execution thread.
#.
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 \ *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.
#.
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.
#.
The following points apply to the specification of \ :code:`EXTERNAL`\ in a data item's definition:
#.
The \ :code:`EXTERNAL`\ clause may only be specified at the 77 or 01 level.
#.
An \ :code:`EXTERNAL`\ item must have a data name and that name cannot be \ :code:`FILLER`\ .
#.
\ :code:`EXTERNAL`\ cannot be combined with \ :code:`BASED`\ ( :ref:`BASED`), \ :code:`GLOBAL`\ ( :ref:`GLOBAL`) or \ :code:`REDEFINES`\ ( :ref:`REDEFINES`).
.. index:: single:FALSE
.. _FALSE:
6.9.19 FALSE
~~~~~~~~~~~~
FALSE Clause Syntax
::
WHEN SET TO FALSE IS literal-1
~~~~~
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`\ .
#.
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.
#.
:ref:`88-LevelADataAItems`, or :ref:`ConditionANames`, for more information.
.. index:: single:FOREGROUND-COLOR
.. _FOREGROUND-COLOR:
6.9.20 FOREGROUND-COLOR
~~~~~~~~~~~~~~~~~~~~~~~
FOREGROUND-COLOR Attribute Syntax
::
FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-1 | identifier-1
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
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.
#.
The reserved word \ :code:`IS`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
#.
The reserved words \ :code:`FOREGROUND-COLOR`\ and \ :code:`FOREGROUND-COLOUR`\ are interchangeable.
#.
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).
#.
Colors may also be specified using a numeric non-edited identifier whose value is in the range 0-7.
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:FROM
.. _FROM:
6.9.21 FROM
~~~~~~~~~~~
FROM Clause Syntax
::
FROM literal-1 | identifier-5
~~~~
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.
#. The \ :code:`FROM`\ , \ :code:`TO`\ ( :ref:`TO`), \ :code:`USING`\ ( :ref:`USING`) and \ :code:`VALUE`\ ( :ref:`VALUE`) clauses are mutually-exclusive in any screen section data item's definition.
.. index:: single:FULL
.. _FULL:
6.9.22 FULL
~~~~~~~~~~~
FULL Attribute Syntax
::
FULL
~~~~
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.
#.
The \ :code:`FULL`\ and \ :code:`LENGTH-CHECK`\ ( :ref:`LENGTH-CHECK`) clauses are interchangeable, and may not be used together in the same data item description.
#.
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.
#.
The \ :code:`ACCEPT data-item`\ statement ( :ref:`ACCEPTAdata-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.
#.
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`\ .
.. index:: single:GLOBAL
.. _GLOBAL:
6.9.23 GLOBAL
~~~~~~~~~~~~~
GLOBAL Attribute Syntax
::
GLOBAL
~~~~~~
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`\ ( :ref:`FileASort-Description`), \ :code:`SD`\ ( :ref:`FileASort-Description`) or an \ :code:`RD`\ ( :ref:`REPORTASECTION`) as being shareable with any nested subprograms.
#.
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 \ :code:`EXTERNAL`\ ( :ref:`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.
#.
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.
#.
The following points apply to the specification of \ :code:`GLOBAL`\ in a data item's definition:
#.
The \ :code:`GLOBAL`\ clause may only be specified at the 77 or 01 level.
#.
A \ :code:`GLOBAL`\ item must have a data name and that name cannot be \ :code:`FILLER`\ .
#.
\ :code:`GLOBAL`\ cannot be combined with \ :code:`EXTERNAL`\ ( :ref:`EXTERNAL`), \ :code:`REDEFINES`\ ( :ref:`REDEFINES`) or \ :code:`BASED`\ ( :ref:`BASED`).
.. index:: single:GROUP INDICATE
.. _GROUPAINDICATE:
6.9.24 GROUP INDICATE
~~~~~~~~~~~~~~~~~~~~~
GROUP-INDICATE Attribute Syntax
::
GROUP INDICATE
~~~~~ ~~~~~~~~
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.
#.
This clause may only appear within a \ :code:`DETAIL`\ report group ( :ref:`TYPE`).
#.
When this clause is present, the data item in question will be presented only under the following circumstances:
#.
On the first presentation of the detail group following the \ :code:`INITIATE`\ ( :ref:`INITIATE`) of the report.
#.
On the first presentation of the detail group after every new page is started.
#.
On the first presentation of the detail group after any control break occurs.
.. index:: single:HIGHLIGHT
.. _HIGHLIGHT:
6.9.25 HIGHLIGHT
~~~~~~~~~~~~~~~~
HIGHLIGHT Attribute Syntax
::
HIGHLIGHT
~~~~~~~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
This clause controls the intensity of text (\ :code:`FOREGROUND-COLOR`\ ( :ref:`FOREGROUND-COLOR`)) by setting that intensity to its highest of three possible settings.
#.
This clause, along with \ :code:`LOWLIGHT`\ ( :ref:`LOWLIGHT`), are intended to provide a three-level intensity scheme (\ :code:`LOWLIGHT`\ ... nothing (Normal) ... \ :code:`HIGHLIGHT`\ ).
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:JUSTIFIED
.. _JUSTIFIED:
6.9.26 JUSTIFIED
~~~~~~~~~~~~~~~~
JUSTIFIED Attribute Syntax
::
JUSTIFIED RIGHT
~~~~
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:
::
01 A PIC X(12) JUST RIGHT VALUE 'ABC'.
Will show content as 'ABC' with NO justification taken place.
#.
The reserved word \ :code:`RIGHT`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
#.
The reserved word \ :code:`JUSTIFIED`\ may be abbreviated as \ :code:`JUST`\ .
#.
This clause is valid only on alphabetic (\ :code:`PIC A`\ ) or alphanumeric (\ :code:`PIC X`\ ) data items.
#.
The presence or absence of this clause influences the behaviour of the \ :code:`MOVE`\ ( :ref:`MOVE`) statement as well as the \ :code:`FROM`\ ( :ref:`FROM`), \ :code:`SOURCE`\ ( :ref:`SOURCE`) and \ :code:`USING`\ ( :ref:`USING`) data item description clauses.
#.
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.
#.
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 \ *b*\ represents a space.
When the value is \ *shorter*\ than the field size:
* Without \ :code:`JUSTIFIED`\ With \ :code:`JUSTIFIED`\
*
::
01 A PIC X(6).
MOVE 'ABC' TO A
::
01 A PIC X(6) JUSTIFIED RIGHT.
MOVE 'ABC' TO A
* Result Result
* \ :code:`ABC<bbb>`\ \ :code:`<bbb>ABC`\
When the value is \ *longer*\ than the field size:
* Without \ :code:`JUSTIFIED`\ With \ :code:`JUSTIFIED`\
*
::
01 A PIC X(6).
MOVE 'ABCDEFGHI' TO A
::
01 A PIC X(6) JUSTIFIED RIGHT.
MOVE 'ABCDEFGHI' TO A
* Result Result
*
\ :code:`ABCDEF`\
\ :code:`DEFGHI`\
.. index:: single:LEFTLINE
.. _LEFTLINE:
6.9.27 LEFTLINE
~~~~~~~~~~~~~~~
LEFTLINE Attribute Syntax
::
LEFTLINE
~~~~~~~~
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.
#.
The \ :code:`LEFTLINE`\ , \ :code:`OVERLINE`\ ( :ref:`OVERLINE`) and \ :code:`UNDERLINE`\ ( :ref:`UNDERLINE`) clauses may be used in any combination in a single field's description.
#.
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).
#.
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.
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:LENGTH-CHECK
.. _LENGTH-CHECK:
6.9.28 LENGTH-CHECK
~~~~~~~~~~~~~~~~~~~
LENGTH-CHECK Attribute Syntax
::
LENGTH-CHECK
~~~~~~~~~~~~
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.
#.
The \ :code:`FULL`\ ( :ref:`FULL`) and \ :code:`LENGTH-CHECK`\ clauses are interchangeable, and may not be used together in the same data item description.
#.
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.
#.
The \ :code:`ACCEPT data-item`\ statement ( :ref:`ACCEPTAdata-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.
#.
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`\ .
.. index:: single:LINE
.. _LINE:
6.9.29 LINE
~~~~~~~~~~~
LINE (REPORT SECTION) Clause Syntax
::
LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] }
~~~~ { ~~~~ ~~~~ }
{ +|PLUS integer-2 }
{ ~~~~ }
{ ON NEXT PAGE }
~~~~ ~~~~
LINE (SCREEN SECTION) Clause Syntax
::
[ LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ]
~~~~ ~~~~
This syntax is valid in the following sections:
\ :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).
#.
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.
#.
The following points document the use of format 1 of the \ :code:`LINE`\ clause:
#.
The column location of a report item will be determined by the \ :code:`COLUMN`\ ( :ref:`COLUMN`) clause.
#.
The value of <integer-1> must be 1 or greater.
#.
The report line number upon which the data item containing this clause along with any subordinate data items will be presented may be stated on an absolute basis (\ *i.e.*\ \ :code:`LINE 5`\ ) or on a relative basis based upon the previously-displayed line (\ *i.e.*\ \ :code:`LINE PLUS 1`\ ).
#.
The symbol '\ :code:`+`\ ' may be used in lieu of the word \ :code:`PLUS`\ , if desired; if '\ :code:`+`\ ' is used, however, there must be at least one space separating it from <integer-1>. Failure to include this space will cause the '\ :code:`+`\ ' to be simply treated as part of <integer-1> and will treat the LINE clause as an absolute line specification rather than a relative one.
.. index:: single:NEXT PAGE
#.
The optional
\ \ :code:`NEXT PAGE`\ clause specifies that --- regardless of whether or not the report group containing this clause \ *could*\ fit on the report page being currently generated, the report group will be \ *forced*\ to appear on a new page.
#. The following points document the use for format 2 of the \ :code:`LINE`\ clause:
#.
The column location of a screen section field is determined by the \ :code:`COLUMN`\ ( :ref:`COLUMN`) clause.
#.
The value of <integer-1> must be 1 or greater.
#.
If <identifier-1> is used to specify either an absolute or relative column position, <identifier-1> must be defined as a numeric item of any \ :code:`USAGE`\ ( :ref:`USAGE`) other than \ :code:`COMPUTATIONAL-1`\ or \ :code:`COMPUTATIONAL-2`\ , without editing symbols. The value of <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.
#.
The screen line number upon which the data item containing this clause along with any subordinate data items will be displayed may be stated on an absolute basis (\ *i.e.*\ \ :code:`LINE 5`\ ) or on a relative basis based upon the previously-displayed line (\ *i.e.*\ \ :code:`LINE PLUS 1`\ ).
#.
The symbol '\ :code:`+`\ ' may be used in lieu of the word \ :code:`PLUS`\ , if desired; if '\ :code:`+`\ ' is used, however, there must be at least one space separating it from <integer-1>. Failure to include this space will cause the '\ :code:`+`\ ' to be simply treated as part of <integer-1> and will treat the \ :code:`LINE`\ clause as an absolute line specification rather than a relative one.
#.
If a screen data item's description includes the \ :code:`FROM`\ ( :ref:`FROM`), \ :code:`TO`\ ( :ref:`TO`), \ :code:`USING`\ ( :ref:`USING`) or \ :code:`VALUE`\ ( :ref:`VALUE`) clause but has no LINE clause, the "current screen line" will be assumed.
.. index:: single:LOWER
.. _LOWER:
6.9.30 LOWER
~~~~~~~~~~~~
LOWER Attribute Syntax
::
LOWER
~~~~~
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.
.. index:: single:LOWLIGHT
.. _LOWLIGHT:
6.9.31 LOWLIGHT
~~~~~~~~~~~~~~~
LOWLIGHT Attribute Syntax
::
LOWLIGHT
~~~~~~~~
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.
#.
This clause, along with \ :code:`HIGHLIGHT`\ ( :ref:`HIGHLIGHT`), are intended to provide a three-level intensity scheme (\ :code:`LOWLIGHT`\ ... nothing (Normal) ... \ :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.
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:NEXT GROUP
.. _NEXTAGROUP:
6.9.32 NEXT GROUP
~~~~~~~~~~~~~~~~~
NEXT-GROUP Clause Syntax
::
NEXT GROUP IS { [ +|PLUS ] integer-2 }
~~~~ ~~~~~ { ~~~~ }
{ NEXT|{NEXT PAGE}|PAGE }
~~~~ ~~~~ ~~~~ ~~~~
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 \ *last*\ line of the group in which this clause appears.
#.
The reserved word \ :code:`IS`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
.. index:: single:PAGE
.. index:: single:NEXT PAGE
.. index:: single:NEXT
#.
The terms
\ \ :code:`NEXT`\ ,
\ \ :code:`NEXT PAGE`\ and
\ \ :code:`PAGE`\ are interchangeable.
#.
A report group must contain at least one \ :code:`LINE NUMBER`\ clause in order to also contain a \ :code:`NEXT GROUP`\ clause.
#.
If the \ :code:`RD`\ ( :ref:`REPORTASECTION`) 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.
#.
The \ :code:`NEXT PAGE`\ option cannot be used in a \ :code:`PAGE FOOTING`\ .
#.
The \ :code:`NEXT GROUP`\ option cannot be specified in either a \ :code:`REPORT HEADING`\ or a \ :code:`PAGE HEADING`\ .
#.
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.
.. index:: single:NO-ECHO
.. _NO-ECHO:
6.9.33 NO-ECHO
~~~~~~~~~~~~~~
NO-ECHO Attribute Syntax
::
NO-ECHO
~~~~~~~
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.
#.
If \ :code:`NO-ECHO`\ is present then the \ :code:`PROMPT`\ clause is ignored.
#.
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.
#.
The \ :code:`NO-ECHO`\ and \ :code:`SECURE`\ ( :ref:`SECURE`) clauses may not be used together in the same data item description.
#.
This clause may only be used on a field allowing data entry (a field containing either the \ :code:`USING`\ ( :ref:`USING`) or \ :code:`TO`\ ( :ref:`TO`) clause).
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:NO UPDATE
.. _NOAUPDATE:
6.9.34 NO UPDATE
~~~~~~~~~~~~~~~~
NO-UPDATE Attribute Syntax
::
NO UPDATE
~~ ~~~~~~
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 ??.
.. index:: single:OCCURS
.. _OCCURS:
6.9.35 OCCURS
~~~~~~~~~~~~~
OCCURS Clause Syntax
::
GENERAL FORMAT.
Format 1 (fixed-table):
OCCURS integer-2 TIMES
~~~~~~
Format 2 (occurs-depending-table):
OCCURS [ integer-1 TO ] { integer-2 TIMES } [ DEPENDING ON identifier-1 ]
~~~~~~ ~~ { UNBOUNDED } ~~~~~~~~~
[ ASCENDING|DESCENDING KEY IS identifier-5 ... ] ...
~~~~~~~~~ ~~~~~~~~~~
[ INDEXED BY index-name-1 ... ]
~~~~~~~
REPORT SECTION.
Format 3
OCCURS [ integer-1 TO ] integer-2 TIMES [ DEPENDING ON identifier-1 ]
~~~~~~ ~~ ~~~~~~~~~
[ STEP integer-3 ]
~~~~
[ VARYING identifier-2 FROM { identifier-3 } BY { identifier-4 } ]
~~~~~~~ ~~~~ { integer-4 } ~~ { integer-5 }
SCREEN SECTION.
Format 4
OCCURS integer-2 TIMES
~~~~~~
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.
#.
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.
#.
The value of <integer-2> specifies how many entries will be allocated in the table.
#.
The following is an example of how a table might be defined:
::
05 QUARTERLY-REVENUE OCCURS 4 TIMES PIC 9(7)V99.
This will allocate the following:
::
QUARTERLY-REVENUE(1)
QUARTERLY-REVENUE(2)
QUARTERLY-REVENUE(3)
QUARTERLY-REVENUE(4)
Each occurrence is referenced using the subscript syntax (a numeric literal, arithmetic expression or numeric identifier enclosed within parenthesis) shown above.
#.
The \ :code:`OCCURS`\ clause may be used at the group level too, in which case the entire group structure repeats, as follows:
::
05 GRP OCCURS 3 TIMES.
10 A PIC X(1).
10 B PIC X(1).
10 C PIC X(1).
This would allow references to any of the following:
::
GRP(1) includes A(1), B(1) and C(1)
GRP(2) includes A(2), B(2) and C(2)
GRP(3) includes A(3), B(3) and C(3)
or each A,B,C item could be referenced as follows:
::
A(1) character #1 of GRP(1)
B(1) character #2 of GRP(1)
C(1) character #3 of GRP(1)
A(2) character #1 of GRP(2)
B(2) character #2 of GRP(2)
C(2) character #3 of GRP(2)
A(3) character #1 of GRP(3)
B(3) character #2 of GRP(3)
C(3) character #3 of GRP(3)
.. index:: single:DEPENDING ON
#.
The optional
\ \ :code:`DEPENDING ON`\ clause can be added to an \ :code:`OCCURS`\ to create a variable-length table. In such cases, the value of <integer-1> specifies what the minimum number of entries in the table will be while <integer-2> specifies the maximum. Such tables will be allocated out to the maximum size specified as <integer-2>. At execution time the value of <identifier-1> will determine how many of the table elements are accessible.
.. index:: single:INDEXED BY
.. index:: single:KEY
#.
See the documentation of the \ :code:`SEARCH`\ ( :ref:`SEARCH`), \ :code:`SEARCH ALL`\ ( :ref:`SEARCHAALL`) and \ :code:`SORT`\ ( :ref:`SORT`) statements for explanations of the
\ \ :code:`KEY`\ and
\ \ :code:`INDEXED BY`\ clauses.
#.
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 \ *subordinate*\ to an 01-level data item.
#.
The following points apply to an \ :code:`OCCURS`\ used in the report section:
.. index:: single:STEP
#.
The optional
\ \ :code:`STEP`\ clause defines an incrementation value that will be added to any absolute \ :code:`LINE`\ ( :ref:`LINE`) or \ :code:`COLUMN`\ ( :ref:`COLUMN`) number specifications that may be part of or subordinate to this data item's definition.
.. index:: single:VARYING
#.
The optional
\ \ :code:`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 \ :code:`SOURCE`\ ( :ref:`SOURCE`) or \ :code:`SUM`\ ( :ref:`SUM`) clause(s) on this or subordinate data items reference entries within the table. The <identifier-2> data item is dynamically created as needed and cannot be referenced outside the scope of the report data item definition.
#.
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:
\ :code:`05 SALES OCCURS 4 TIMES PIC 9(7)V99.`\
First, the "Hard Way":
::
10 COL 7 PIC $(7)9.99 SOURCE SALES(1).
10 COL 17 PIC $(7)9.99 SOURCE SALES(2).
10 COL 27 PIC $(7)9.99 SOURCE SALES(3).
10 COL 37 PIC $(7)9.99 SOURCE SALES(4).
And then using \ :code:`STEP`\ and \ :code:`VARYING`\ :
::
10 COL 7 OCCURS 4 TIMES STEP 10 VARYING QTR FROM 1 BY 1
PIC $(7)9.99 SOURCE SALES(QTR).
.. index:: single:OVERLINE
.. _OVERLINE:
6.9.36 OVERLINE
~~~~~~~~~~~~~~~
OVERLINE Attribute Syntax
::
OVERLINE
~~~~~~~~
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.
#.
The \ :code:`LEFTLINE`\ ( :ref:`LEFTLINE`), \ :code:`OVERLINE`\ and \ :code:`UNDERLINE`\ ( :ref:`UNDERLINE`) clauses may be used in any combination in a single field's description.
#.
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).
#.
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.
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:PICTURE
.. _PICTURE:
6.9.37 PICTURE
~~~~~~~~~~~~~~
PICTURE Clause Syntax
::
PICTURE IS picture-string
~~~
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 \ :code:`USAGE`\ ( :ref:`USAGE`) clause, and in a few instances will be assumed entirely by that clause.
#.
The reserved word \ :code:`IS`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
#.
The reserved word \ :code:`PICTURE`\ may be abbreviated as \ :code:`PIC`\ . Most programmers prefer to use the latter.
#.
A picture clause may only be specified on an elementary item.
#.
A <picture-string> is a sequence of the special symbols '\ :code:`$`\ ', '\ :code:`\*`\ ', '\ :code:`+`\ ', '\ :code:`,`\ ', '\ :code:`-`\ ', '\ :code:`.`\ ', '\ :code:`/`\ ', '\ :code:`0`\ ' (zero), '\ :code:`1`\ ', '\ :code:`9`\ ', '\ :code:`A`\ ', '\ :code:`B`\ ', \ :code:`CR`\ , \ :code:`DB`\ , '\ :code:`S`\ ', '\ :code:`V`\ ', '\ :code:`P`\ ', '\ :code:`X`\ ' and '\ :code:`Z`\ '.
#.
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.
#.
When a <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)`\ .
#.
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.
* '\ :code:`A`\ '
Defines storage reserved for a single alphabetic character ('\ :code:`A`\ '-'\ :code:`Z`\ ', '\ :code:`a`\ '-'\ :code:`z`\ ').
.. index:: single:National Character set
* '\ :code:`N`\ '
Defines storage reserved for a single character in the computer's
\ \ *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 '\ :code:`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 \ :code:`INITIALIZE`\ ( :ref:`INITIALIZE`) statement.
* '\ :code:`X`\ '
Defines storage reserved for a single alphanumeric character (any character).
* '\ :code:`9`\ '
Defines storage reserved for a single numeric digit character ('\ :code:`0`\ '-'\ :code:`9`\ ').
.. index:: single:Alphanumeric Data Items
.. index:: single:Numeric Data Items
.. index:: single:Alphabetic Data Items
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 '\ :code:`A`\ ' picture symbols are known as
\ \ *Alphabetic Data Items*\ while those that use '\ :code:`9`\ ' picture symbols without any '\ :code:`A`\ ' or '\ :code:`X`\ ' symbols (or those that have a \ :code:`USAGE`\ without a \ :code:`PICTURE`\ ) are known as
\ \ *Numeric Data Items*\ . All other data items are referred to as
\ \ *Alphanumeric Data Items*\ .
If you need to allocate space for a data item whose format is two letters followed by five digits followed by three letters, you could use the <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 \ *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 \ :code:`MOVE`\ ( :ref:`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 ( :ref:`ClassAConditions`) to determine if the contents of a data item are entirely numeric or entirely alphabetic.
#. '\ :code:`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.
#.
The following picture symbols may be used with numeric data items.
* '\ :code:`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 '\ :code:`P`\ ') to exist at the end of values.
The '\ :code:`P`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
The '\ :code:`P`\ ' symbol may only be used at the beginning or end of a picture clause.
'\ :code:`P`\ ' is a repeatable symbol.
All computations and \ :code:`MOVE`\ ( :ref:`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:
\ :code:`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:
\ :code:`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:`<nnn>000000`\ , where \ :code:`<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 '\ :code:`P`\ 's were '\ :code:`9`\ 's:
::
MOVE 128000000 TO Gross-Revenue
A \ :code:`DISPLAY`\ ( :ref:`DISPLAY`) of a data item containing '\ :code:`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 '\ :code:`P`\ ' symbols had been '\ :code:`9`\ 's. Thus, after the above statement established a value for Gross-Revenue, a \ :code:`DISPLAY Gross-Revenue`\ would produce output of '\ :code:`000000128`\ '.
* '\ :code:`S`\ '
This symbol, if used, must be the very first symbol in the \ :code:`PICTURE`\ value. A '\ :code:`S`\ ' indicates that the data item is \ :code:`Signed`\ , meaning that negative values are possible for this data item. Without an '\ :code:`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 '\ :code:`S`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
The '\ :code:`S`\ ' symbol may only occur once in a picture string. :ref:`SIGNAIS`, for further discussion of how negative values may be stored in a numeric data item.
* '\ :code:`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 '\ :code:`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 '\ :code:`V`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
The '\ :code:`V`\ ' symbol may only occur once in a picture string.
.. index:: single:Numeric Edited
#.
Any editing symbols introduced past this point will, if coded in the picture clause of an otherwise numeric data item, transform that data item from a numeric to a
\ \ *Numeric Edited*\ data item. Numeric edited data items are treated as alphanumeric and may not serve either as table subscripts or as source arguments on an arithmetic statement.
#.
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.
* '\ :code:`B`\ '
The '\ :code:`B`\ ' editing symbol introduces a blank into the field value for each occurrence.
Multiple '\ :code:`B`\ ' symbols may be coded.
The following example will format a ten digit number (presumably a telephone number) into a '\ :code:`### ### ####`\ ' layout:
::
...
05 Phone-Number PIC 9(3)B9(3)B9(4).
...
MOVE 5185551212 TO Phone-Number
DISPLAY Phone-Number
This code will display '\ :code:`518 555 1212`\ '.
* '\ :code:`0`\ '
The '\ :code:`0`\ ' (zero) editing symbol introduces one "0" character into the field value for each occurrence in the picture string.
Multiple '\ :code:`0`\ ' symbols may be coded.
Here's an example:
::
...
05 Output-Item PIC 909090909.
...
MOVE 12345 TO Output-Item
DISPLAY Output-Item
The above will display '\ :code:`102030405`\ '.
* '\ :code:`/`\ '
The '\ :code:`/`\ ' editing symbol inserts one "/" character into the field value for each occurrence in the picture string.
Multiple '\ :code:`/`\ ' symbols may be coded.
This editing symbol is most-frequently used to format dates, as follows:
::
...
05 Year-Month-Day PIC 9(4)/9(2)/9(2).
...
MOVE 20140207 TO Year-Month-Day
DISPLAY Year-Month-Day
This example displays '\ :code:`2014/02/07`\ '.
#.
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.
* '\ :code:`.`\ '
The '\ :code:`.`\ ' 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 '\ :code:`.`\ ' editing symbol, implied ('\ :code:`V`\ ') or actual decimal point in the sending data item or literal, respectively, will be aligned with the '\ :code:`.`\ ' symbol in the receiving field. Digits are then transferred from the sending to the receiving field outward from the sending field's '\ :code:`V`\ ' or '\ :code:`.`\ ', 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 '\ :code:`.`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
An example will probably help:
::
...
05 Source-Field PIC 9(2)V9 VALUE 7.2.
05 Dest-Field PIC 9(5).9(2).
...
MOVE 1234567.89 TO Dest-Field
DISPLAY Dest-Field
MOVE 19 TO Dest-Field
DISPLAY Dest-Field
MOVE Source-Field TO Dest-Field
DISPLAY Dest-Field
The example will display three results --- '\ :code:`34567.89`\ ', '\ :code:`00019.00`\ ' and '\ :code:`00007.20`\ '.
Both data item definitions \ *appear*\ to have \ *two*\ decimal points in their picture clauses. They actually don't, because the last character of every data item definition is always a period --- the period that ends the definition.
* '\ :code:`,`\ '
The '\ :code:`,`\ ' 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 '\ :code:`9`\ 's.
The '\ :code:`,`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
Here's an example:
::
...
05 My-Lottery-Winnings PIC 9(3),9(3),9(3).
...
MOVE 12345 TO My-Lottery-Winnings
DISPLAY My-Lottery-Winnings
The value '\ :code:`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 '\ :code:`9`\ '.
If desired, you may reverse the roles of the '\ :code:`.`\ ' and '\ :code:`,`\ ' editing symbols by specifying \ :code:`DECIMAL POINT IS COMMA`\ in the \ :code:`SPECIAL-NAMES`\ ( :ref:`SPECIAL-NAMES`) paragraph.
#.
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 '\ :code:`+`\ ', '\ :code:`-`\ ', \ :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 <picture-string>, they must be at the end. The '\ :code:`+`\ ', '\ :code:`-`\ ' and/or currency symbols may also be used as floating editing symbols at the \ *beginning*\ of the <picture-string> --- a subject that will be covered in the next numbered paragraph.
* '\ :code:`+`\ '
If the value of the numeric value moved into the field is positive (0 or greater), a '\ :code:`+`\ ' character will be inserted. If the value is negative (less than 0), a '\ :code:`-`\ ' character is inserted.
The '\ :code:`+`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
* '\ :code:`-`\ '
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 '\ :code:`-`\ ' character is inserted.
The '\ :code:`-`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
* \ :code:`CR`\
This symbol is coded as the two characters '\ :code:`C`\ ' and '\ :code:`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 '\ :code:`N`\ '.
* \ :code:`DB`\
This symbol is coded as the two characters '\ :code:`D`\ ' and '\ :code:`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 '\ :code:`N`\ '.
* '\ :code:`$`\ '
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 <picture-string> ( :ref:`SPECIAL-NAMES`).
The '\ :code:`$`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
#.
These editing symbols are known as floating replacement symbols. These symbols may occur in sequences \ *before*\ any '\ :code:`9`\ ' editing symbols in the <picture-string> of a numeric data item. Using these symbols transforms that numeric data item into a numerid \ *edited*\ data item, which can no longer be used in calculations or subscripts.
#.
Each of the following symbols behave like a '\ :code:`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.
* '\ :code:`$`\ '
Of those currency symbols that correspond to character positions in which leading zeros reside, the right-most will have its '\ :code:`0`\ ' value replaced by the currency symbol in-effect for the program ( :ref:`SPECIAL-NAMES`). Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces.
The '\ :code:`$`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
Any currency symbol coded to the right of a '\ :code:`.`\ ' will be treated exactly like a '\ :code:`9`\ '.
* '\ :code:`\*`\ '
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 '\ :code:`0`\ ' values replaced by '\ :code:`\*`\ '.
The '\ :code:`\*`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
Any check-suppression symbol coded to the right of a '\ :code:`.`\ ' will be treated exactly like a '\ :code:`9`\ '.
* '\ :code:`+`\ '
Of those '\ :code:`+`\ ' symbols that correspond to character positions in which leading zeros reside, the right-most will have its '\ :code:`0`\ ' value replaced by a '\ :code:`+`\ ' if the value in the data item is zero or greater or a '\ :code:`-`\ ' otherwise. Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces. You cannot use both '\ :code:`+`\ ' and '\ :code:`-`\ ' in the same <picture-string>.
The '\ :code:`+`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
Any '\ :code:`+`\ ' symbol coded to the right of a '\ :code:`.`\ ' will be treated exactly like a '\ :code:`9`\ '.
* '\ :code:`-`\ '
Of those '\ :code:`-`\ ' symbols that correspond to character positions in which leading zeros reside, the right-most will have its '\ :code:`0`\ ' value replaced by a space if the value in the data item is zero or greater or a '\ :code:`-`\ ' otherwise. Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces. You cannot use both '\ :code:`+`\ ' and '\ :code:`-`\ ' in the same <picture-string>.
The '\ :code:`-`\ ' symbol is not allowed in conjunction with '\ :code:`N`\ '.
Any '\ :code:`-`\ ' symbol coded to the right of a '\ :code:`.`\ ' will be treated exactly like a '\ :code:`9`\ '.
* '\ :code:`Z`\ '
All '\ :code:`Z`\ ' symbols that correspond to character positions in which leading zeros reside will have their '\ :code:`0`\ ' values replaced by spaces.
Any zero-suppression symbol coded to the right of a '\ :code:`.`\ ' will be treated exactly like a '\ :code:`9`\ '.
'\ :code:`Z`\ ' and '\ :code:`\*`\ ' should not be coded in the same <picture-string>
'\ :code:`+`\ ' and '\ :code:`-`\ ' should not be coded in the same <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`\ <picture-string>, and a value of 1 is moved to that field at run-time, the resulting value will be (the \ *b*\ symbol represents a space) \ :code:`\ *bbbb*\ +$1.00`\ . This is not consistent with many other COBOL implementations, where the result would have been \ :code:`+$\ *bbbb*\ 1.00`\ .
Most other COBOL implementations reject the use of multiple occurrences of multiple floating editing symbols. For example, they would reject <picture-string>s such as \ :code:`+++$$$9.99`\ , \ :code:`$$$ZZZ9.99`\ and so on. GnuCOBOL accepts these. Programmers creating GnuCOBOL programs should avoid such <picture-string>s if there is any likelihood that those programs may be used with other COBOL implementations.
.. index:: single:PRESENT WHEN
.. _PRESENTAWHEN:
6.9.38 PRESENT WHEN
~~~~~~~~~~~~~~~~~~~
PRESENT-WHEN Clause Syntax
::
PRESENT WHEN condition-name
~~~~~~~ ~~~~
This syntax is valid in the following sections:
\ :code:`REPORT`\
This clause names an existing \ :code:`Condition Name`\ ( :ref:`ConditionANames`) that will serve as a switch controlling the presentation or suppression of a report group.
#.
If the specified condition-name has a value of FALSE when a \ :code:`GENERATE`\ statement ( :ref:`GENERATE`) causes a report group to be presented, the presentation of that group will be suppressed.
#.
If the condition-name has a value of \ :code:`TRUE`\ , the group will be presented.
#.
:ref:`ConditionANames`, for more information.
.. index:: single:PROMPT
.. _PROMPT:
6.9.39 PROMPT
~~~~~~~~~~~~~
PROMPT Clause Syntax
::
PROMPT [ CHARACTER IS literal-1 | identifier-1 ]
~~~~~~ ~~~~~~~~~
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.
#.
The reserved word \ :code:`IS`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
#.
The default prompt character, should no \ :code:`CHARACTER`\ specification be coded, or should the \ :code:`PROMPT`\ clause be absent altogether, is an underscore ('\ :code:`_`\ ').
#.
Prompt characters will be automatically transformed into spaces upon input.
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:PROTECTED
.. _PROTECTED:
6.9.40 PROTECTED
~~~~~~~~~~~~~~~~
PROTECTED Attribute Syntax
::
PROTECTED SIZE IS { identifier }
~~~~~~~~ ~~~~ { integer }
This syntax is valid in the following sections:
\ :code:`SCREEN`\
#.
The \ :code:`PROTECTED`\ extended clause will effect the specified field to be limited in size, regardless of the picture size. [#]_
#.
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).
#.
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.
#.
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.
#.
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.
#.
If the item is alphanumeric edited, then the size is set to the number of '\ :code:`A`\ ' or '\ :code:`X`\ ' positions specified in its \ :code:`PICTURE`\ clause.
#.
For all other data types, the field size is set to the size of the item (same as if \ :code:`CONVERT`\ were not specified).
#.
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.
#.
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.
.. index:: single:REDEFINES
.. _REDEFINES:
6.9.41 REDEFINES
~~~~~~~~~~~~~~~~
REDEFINES Clause Syntax
::
REDEFINES identifier-1
~~~~~~~~~
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 <identifier-1> (hereafter referred to as the redefines subject).
#.
The following rules must all be followed in order to use \ :code:`REDEFINES`\ :
#.
The level number of both the subject and object data items must be the same.
#.
The level numbers of both the subject and object data items cannot be 66, 78 or 88.
#.
If \ *N*\ represents the level number of the object, then no other data items with level number \ *N*\ may be defined between the subject and object data items unless they too are \ :code:`REDEFINES`\ of the subject.
#.
If \ *N*\ represents the level number of the object, then no other data items with a level number numerically less than \ *N*\ may be defined between the subject and object data items.
#.
The total allocated size of the subject data item must be the same as the total allocated size of the object data item.
#.
No \ :code:`OCCURS`\ ( :ref:`OCCURS`) clause may be part of the definition of either the subject or object data items. Either or both, however, may be group items that \ *contain*\ data items with \ :code:`OCCURS`\ clauses.
#.
No \ :code:`VALUE`\ ( :ref:`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.
.. index:: single:RENAMES
.. _RENAMES:
6.9.42 RENAMES
~~~~~~~~~~~~~~
RENAMES Clause Syntax
::
RENAMES identifier-1 [ THRU|THROUGH identifier-2
~~~~~~~ ~~~~ ~~~~~~~
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.
#.
The reserved words \ :code:`THRU`\ and \ :code:`THROUGH`\ are interchangeable.
#.
You must use the level number 66 for data description entries that contain the \ :code:`RENAMES`\ clause.
#.
The <identifier-1> and <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.
#.
:ref:`66-LevelADataAItems`, for additional information on the \ :code:`RENAMES`\ clause.
.. index:: single:REQUIRED
.. _REQUIRED:
6.9.43 REQUIRED
~~~~~~~~~~~~~~~
REQUIRED Attribute Syntax
::
REQUIRED
~~~~~~~~
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).
#.
The \ :code:`EMPTY-CHECK`\ ( :ref:`EMPTY-CHECK`) and \ :code:`REQUIRED`\ clauses are interchangeable, and may not be used together in the same data item description.
#.
In order to take effect, the user must first move the cursor into the field having this clause in its definition.
#.
The \ :code:`ACCEPT data-item`\ statement ( :ref:`ACCEPTAdata-item`) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item \ *unless*\ data has been entered into the field. Function keys will still be allowed to terminate the \ :code:`ACCEPT`\ .
#.
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`\ .
.. index:: single:REVERSE-VIDEO
.. _REVERSE-VIDEO:
6.9.44 REVERSE-VIDEO
~~~~~~~~~~~~~~~~~~~~
REVERSE-VIDEO Attribute Syntax
::
REVERSE-VIDEO
~~~~~~~~~~~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
The \ :code:`REVERSE-VIDEO`\ attribute swaps the specified or implied \ :code:`FOREGROUND-COLOR`\ ( :ref:`FOREGROUND-COLOR`) and \ :code:`BACKGROUND-COLOR`\ ( :ref:`BACKGROUND-COLOR`) attributes for the field whose definition contains this clause (or all subordinate fields if used on a group item).
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:SAME AS
.. _SAMEAAS:
6.9.45 SAME AS
~~~~~~~~~~~~~~
SAME-AS Clause Syntax
::
SAME AS data-name-1
~~~~ ~~
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.
#.
Data-name-1 is a data Item defined elsewhere in the same program.
#.
Data-name-1 shall not be subscripted.
#.
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.
#.
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.
#.
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.
#.
The description of data-name-1 shall not contain an OCCURS clause. However, items subordinate to data-name-1 may contain OCCURS clauses.
#.
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.
#.
If the subject of the entry is a level 77 item, data-name-1 shall reference an elementary item.
#.
A group item to which the subject of the entry is subordinate shall not contain a GROUP-USAGE, SIGN, or USAGE clause.
#.
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.
#.
If data-name-1 describes a group 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.
::
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.
.. index:: single:SCROLL DOWN
.. _SCROLLADOWN:
6.9.46 SCROLL DOWN
~~~~~~~~~~~~~~~~~~
SCROLL-DOWN Attribute Syntax
::
SCROLL DOWN
~~~~~~ ~~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
This clause will cause downward scrolling.
.. index:: single:SCROLL UP
.. _SCROLLAUP:
6.9.47 SCROLL UP
~~~~~~~~~~~~~~~~
SCROLL-UP Attribute Syntax
::
SCROLL UP
~~~~~~ ~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
This clause will cause upward scrolling. MORE HERE ??
.. index:: single:SECURE
.. _SECURE:
6.9.48 SECURE
~~~~~~~~~~~~~
SECURE Attribute Syntax
::
SECURE
~~~~~~
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.
#.
The \ :code:`NO-ECHO`\ and \ :code:`SECURE`\ clauses are interchangeable if If the dialect configuration -fno-echo-means-secure is active.
#.
The \ :code:`NO-ECHO`\ and \ :code:`SECURE`\ clauses may not be used together in the same data item description.
#.
This clause may only be used on a field allowing data entry (a field containing either the \ :code:`USING`\ ( :ref:`USING`) or \ :code:`TO`\ ( :ref:`TO`) clause).
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:SIGN IS
.. _SIGNAIS:
6.9.49 SIGN IS
~~~~~~~~~~~~~~
SIGN-IS Clause Syntax
::
SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
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 '\ :code:`S`\ ' symbol will be interpreted in a data item's picture clause.
#.
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.
.. index:: single:LEADING
.. index:: single:TRAILING
.. index:: single:SEPARATE CHARACTER
#.
\ *Without*\ the
\ \ :code:`SEPARATE CHARACTER`\ option, the sign of the data item's value will be encoded by transforming the last (see
\ \ :code:`TRAILING`\ ) or first (see
\ \ :code:`LEADING`\ ) digit as follows:
* First/Last Digit Value For Positive Value for Negative
* 0 0 p
* 1 1 q
* 2 2 r
* 3 3 s
* 4 4 t
* 5 5 u
* 6 6 v
* 7 7 w
* 8 8 x
* 9 9 y
#.
If the \ :code:`SEPARATE CHARACTER`\ clause \ *is*\ used, then an actual '\ :code:`+`\ ' or '\ :code:`-`\ ' 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.
#.
When \ :code:`SEPARATE CHARACTER`\ is specified, the '\ :code:`S`\ ' symbol in the data item's \ :code:`PICTURE`\ must be counted when determining the data item's size.
#.
Neither the presence of an encoded digit (see above) nor an actual '\ :code:`+`\ ' or '\ :code:`-`\ ' character embedded within the data item's storage prevents the data item from being used as a source field in arithmetic operations.
.. index:: single:SIZE
.. _SIZE:
6.9.50 SIZE
~~~~~~~~~~~
SIZE Clause Syntax
::
SIZE
~~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
This clause does WHAT EXACTLY ??????
.. index:: single:SOURCE
.. _SOURCE:
6.9.51 SOURCE
~~~~~~~~~~~~~
SOURCE Clause Syntax
::
SOURCE IS literal-1 | identifier-1 [ ROUNDED ]
~~~~~~ ~~~~~~~
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.
#.
The reserved word \ :code:`IS`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
#.
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.
.. index:: single:LINE-COUNTER
.. index:: single:PAGE-COUNTER
#.
The specified identifier may be defined anywhere in the data division, but if it is defined in the report section it may only be
\ \ :code:`PAGE-COUNTER`\ ,
\ \ :code:`LINE-COUNTER`\ or a \ :code:`SUM`\ ( :ref:`SUM`) counter.
#.
The \ :code:`PICTURE`\ ( :ref:`PICTURE`) of the report data item must be such that it would be legal to \ :code:`MOVE`\ ( :ref:`MOVE`) the specified literal or identifier to a data item with that \ :code:`PICTURE`\ .
#.
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"). \ *Without*\ \ :code:`ROUNDED`\ , excess digits in the source value will simply be truncated to fit the target field. \ *With*\ \ :code:`ROUNDED`\ , the source value will be arithmetically rounded to fit the target field. :ref:`ROUNDED`, for information on the \ :code:`NEAREST-AWAY-FROM-ZERO`\ rounding rule, which is the one that will apply.
.. index:: single:SUM OF
.. _SUMAOF:
6.9.52 SUM OF
~~~~~~~~~~~~~
SUM-OF Clause Syntax
::
SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ]
~~~ { literal-2 } { ~~~~~ ~~~~~ }
{ UPON identifier-9 }
~~~~
This syntax is valid in the following sections:
\ :code:`REPORT`\
The \ :code:`SUM`\ clause establishes a summation counter whose value will be arithmetically calculated whenever the field is presented.
#.
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.
#.
The \ :code:`SUM`\ clause may only appear in a \ :code:`CONTROL FOOTING`\ report group.
#.
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.
#.
All <identifier-7> data items must be non-edited numeric in nature.
#.
If any <identifier-7> data item is defined in the report section, it must be a sum counter.
#.
Any <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. :ref:`ControlAHierarchy`, for additional information.
#.
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 \ :code:`MOVE`\ ( :ref:`MOVE`) the specified <identifier-7> or <literal-2> value to a data item with that \ :code:`PICTURE`\ .
.. index:: single:UPON
#.
The following points apply to the
\ \ :code:`UPON`\ option:
#.
The data item <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.
#.
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 <identifier-9>`\ statement is executed.
#.
If there is no \ :code:`UPON`\ clause specified, the value of <identifier-7> or <literal-2> will be added into the sum counter whenever a \ :code:`GENERATE`\ ( :ref:`GENERATE`) of any detail report group in the report is executed.
#.
If there is only a single detail group in the report's definition, the \ :code:`UPON`\ clause is meaningless.
.. index:: single:RESET
#.
The following points apply to the
\ \ :code:`RESET`\ option:
#.
If the \ :code:`RESET`\ option is coded, \ :code:`FINAL`\ or <identifier-8> (whichever is coded on the \ :code:`RESET`\ ) must be one of the report's control breaks specified on the \ :code:`CONTROLS`\ clause.
#.
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.
#.
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.
.. index:: single:SYNCHRONIZED
.. _SYNCHRONIZED:
6.9.53 SYNCHRONIZED
~~~~~~~~~~~~~~~~~~~
SYNCHRONIZED Syntax
::
SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ]
~~~~ ~~~~ ~~~~ ~~~~~
The \ :code:`LEFT`\ and \ :code:`RIGHT`\ (SYNCHRONIZED) clauses are syntactically recognized but are otherwise non-functional.
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.
#.
The reserved words \ :code:`SYNCHRONIZED`\ and \ :code:`SYNCHRONISED`\ are interchangeable, and may be abbreviated as \ :code:`SYNC`\ .
#.
If the \ :code:`SYNCHRONIZED`\ clause is coded on anything but a numeric data item with a \ :code:`USAGE`\ ( :ref:`USAGE`) that specifies storage of data in a binary form, the \ :code:`SYNCHRONIZED`\ clause will be ignored.
#.
Synchronization is performed (by the compiler) as follows:
#.
If the binary item occupies one byte of storage, no synchronization is performed.
#.
If the binary item occupies two bytes of storage, the binary item is allocated at the next half-word boundary.
#.
If the binary item occupies four bytes of storage, the binary item is allocated at the next word boundary.
#.
If the binary item occupies eight bytes of storage, the binary item is allocated at the next word boundary.
.. index:: single:TIME OUT
.. _TIMEAOUT:
6.9.54 TIME OUT
~~~~~~~~~~~~~~~
TIME-OUT Clause Syntax
::
TIME OUT
~~~~ ~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
This clause will force a specific time for the data tp be entered.
.. index:: single:TO
.. _TO:
6.9.55 TO
~~~~~~~~~
TO Clause Syntax
::
TO identifier-5
~~
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.
#.
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.
#.
The \ :code:`FROM`\ ( :ref:`FROM`), \ :code:`TO`\ , \ :code:`USING`\ ( :ref:`USING`) and \ :code:`VALUE`\ ( :ref:`VALUE`) clauses are mutually-exclusive in any screen section data item's definition.
.. index:: single:TYPE
.. _TYPE:
6.9.56 TYPE
~~~~~~~~~~~
TYPE Clause Syntax
::
Format 1: All Sections other than REPORT
[ TYPE TO type-name-1 ]
~~~~
Format 2: REPORT SECTION Only
[ TYPE IS { RH|{REPORT HEADING} } ]
~~~~ { ~~ ~~~~~~ ~~~~~~~ }
{ PH|{PAGE HEADING} }
{ ~~ ~~~~ ~~~~~~~ }
{ CH|{CONTROL HEADING} FINAL|identifier-2 }
{ ~~ ~~~~~~~ ~~~~~~~ ~~~~~ }
{ DE|DETAIL }
{ ~~ ~~~~~~ }
{ CF|{CONTROL FOOTING} FINAL|identifier-2 }
{ ~~ ~~~~~~~ ~~~~~~~ ~~~~~ }
{ PF|{PAGE FOOTING} }
{ ~~ ~~~~ ~~~~~~~ }
{ RF|{REPORT FOOTING} }
~~ ~~~~~~ ~~~~~~~
The syntax is valid in all other sections than:
\ :code:`REPORT`\
As format 1
#.
The TYPE 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 \ :code:`TYPEDEF`\ ( :ref:`TYPEDEF`).
#.
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.
#.
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.
#.
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.
#.
The scoping rules for type names are similar to the scoping rules for data names.
#.
Reference modification is not allowed for an elementary item that is the subject of a TYPE clause.
#.
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.
#.
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.
#.
The subject of a TYPE clause cannot be renamed in whole, or in part and cannot be redefined explicitly or implicitly.
#.
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.
#.
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.
#.
The TYPE clause can be specified in a data description entry with the EXTERNAL, GLOBAL, OCCURS, TYPEDEF, and VALUE clauses.
#.
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.
#.
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.
#.
Figure 1. Example Showing How TYPEDEF and TYPE Clauses Can Be Used
::
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.
#.
Figure 2. Example Showing How TYPEDEF and TYPE Clauses Can Be Used
::
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.
This syntax is valid in the following sections:
\ :code:`REPORT`\
As Format 2
#.
This clause defines the type of report group that is being defined for a report.
#.
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.
#.
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`\ .
#.
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`\ .
#.
The various report groups that constitute a report may be defined in any order.
#.
:ref:`RWCSALexicon`, for a description of the seven different types of report groups.
.. index:: single:TYPEDEF
.. _TYPEDEF:
6.9.57 TYPEDEF
~~~~~~~~~~~~~~
TYPEDEF Clause Syntax
::
01 data-name-1 IS TYPEDEF
~~ ~~~~~~
This syntax is valid in the following sections FILE, WORKING-STORAGE, LOCAL-STORAGE and LINKAGE
#.
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.
#.
The TYPEDEF clause specifies that the data description entry is a type declaration.
#.
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.
#.
If a group item is specified, all subordinate items of the group become part of the type declaration.
#.
No storage is allocated for a type declaration.
#.
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.
#.
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.
#.
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).
#.
The following clauses cannot be specified along with TYPEDEF: EXTERNAL, GLOBAL, LIKE, OCCURS, REDEFINES.
#.
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.
#.
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.
#.
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.
#.
In FILE SECTION, a data description entry declared at level number 1 that includes a TYPEDEF clause is not a record description entry.
.. index:: single:UNDERLINE
.. _UNDERLINE:
6.9.58 UNDERLINE
~~~~~~~~~~~~~~~~
UNDERLINE Attribute Syntax
::
UNDERLINE
~~~~~~~~~
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.
#.
The \ :code:`LEFTLINE`\ ( :ref:`LEFTLINE`), \ :code:`OVERLINE`\ ( :ref:`OVERLINE`) and \ :code:`UNDERLINE`\ clauses may be used in any combination in a single field's description.
#.
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).
#.
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.
:ref:`ColorAPaletteAandAVideoAAttributes`, for more information on screen colors and video attributes.
.. index:: single:UPDATE
.. _UPDATE:
6.9.59 UPDATE
~~~~~~~~~~~~~
UPDATE Clause Syntax
::
UPDATE
~~~~~~
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.
.. index:: single:UPPER
.. _UPPER:
6.9.60 UPPER
~~~~~~~~~~~~
UPPER Clause Syntax
::
UPPER
~~~~~
This syntax is valid in the following sections:
\ :code:`SCREEN`\
The \ :code:`UPPER`\ clause force the accepted data to be in Upper Case.
.. index:: single:USAGE
.. _USAGE:
6.9.61 USAGE
~~~~~~~~~~~~
USAGE Clause Syntax
::
USAGE IS data-item-usage
~~~~~
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.
#.
The reserved word \ :code:`IS`\ is optional and may be omitted. The presence or absence of this word has no effect upon the program.
#.
The following table summarizes the various USAGE specifications available in GnuCOBOL.
| \ :code:`BINARY`\
| \ :code:`~~~~~~`\
*
Range of Values: Defined by the quantity of '\ :code:`9`\ 's and the presence or absence of an '\ :code:`S`\ ' in the \ :code:`PICTURE`\
*
Storage Format: Compatible Binary Integer
*
Negative Values Allowed?: If \ :code:`PICTURE`\ contains '\ :code:`S`\ '
*
\ :code:`PICTURE`\ Used?: Yes
| \ :code:`BINARY-C-LONG [ SIGNED ]`\
| \ :code:`~~~~~~~~~~~~~`\
*
Range of Values: Depending on the system hardware, the range is either 0 to 2^31 or 0 to 2^63.
| \ :code:`BINARY-C-LONG UNSIGNED`\
| \ :code:`~~~~~~~~~~~~~ ~~~~~~~~`\
*
Range of Values: Depending on the system hardware, the range is either 0 to 2^32 or 0 to 2^64.
*
Restrictions: 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).
| \ :code:`BINARY-CHAR [ SIGNED ]`\
| \ :code:`~~~~~~~~~~~`\
*
Range of Values: -128 -- 127
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: Yes
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`BINARY-CHAR UNSIGNED`\
| \ :code:`~~~~~~~~~~~ ~~~~~~~~`\
*
Range of Values: 0 -- 255
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: No
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`BINARY-DOUBLE [ SIGNED ]`\
| \ :code:`~~~~~~~~~~~~~`\
*
Range of Values: -9,223,372,036,854,775,808 -- 9,223,372,036,854,775,807
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: Yes
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`BINARY-DOUBLE UNSIGNED`\
| \ :code:`~~~~~~~~~~~~~ ~~~~~~~~`\
*
Range of Values: 0 -- 18,446,744,073,709,551,615
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: No
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`BINARY-INT`\
| \ :code:`~~~~~~~~~~`\
*
Same as \ :code:`BINARY-LONG SIGNED`\
| \ :code:`BINARY-LONG [ SIGNED ]`\
| \ :code:`~~~~~~~~~~~`\
*
Range of Values: -2,147,483,648 -- 2,147,483,647
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: Yes
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`BINARY-LONG UNSIGNED`\
| \ :code:`~~~~~~~~~~~ ~~~~~~~~`\
*
Range of Values: 0 -- 4,294,967,295
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: No
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`BINARY-LONG-LONG`\
| \ :code:`~~~~~~~~~~~~~~~~`\
*
Same as \ :code:`BINARY-DOUBLE SIGNED`\
| \ :code:`BINARY-SHORT [ SIGNED ]`\
| \ :code:`~~~~~~~~~~~~`\
*
Range of Values: -32,768 -- 32,767
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: Yes
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`BINARY-SHORT UNSIGNED`\
| \ :code:`~~~~~~~~~~~~ ~~~~~~~~`\
*
Range of Values: 0 -- 65,535
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: No
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`COMPUTATIONAL`\
| \ :code:`COMP`\
*
Same as \ :code:`BINARY`\
| \ :code:`COMPUTATIONAL-1`\
| \ :code:`COMP-1`\
*
Same as \ :code:`FLOAT-SHORT`\
| \ :code:`COMPUTATIONAL-2`\
| \ :code:`COMP-2`\
*
Same as \ :code:`FLOAT-LONG`\
| \ :code:`COMPUTATIONAL-3`\
| \ :code:`COMP-3`\
*
Same as \ :code:`PACKED-DECIMAL`\
| \ :code:`COMPUTATIONAL-4`\
| \ :code:`COMP-4`\
*
Same as \ :code:`BINARY`\
| \ :code:`COMPUTATIONAL-5`\
| \ :code:`COMP-5`\
*
Range of Values: Depends on number of '\ :code:`9`\ 's in the \ :code:`PICTURE`\ and the \ :code:`binary-size`\ setting of the configuration file used to compile the program
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: If \ :code:`PICTURE`\ contains '\ :code:`S`\ '
*
\ :code:`PICTURE`\ Used?: Yes
| \ :code:`COMPUTATIONAL-6`\
| \ :code:`COMP-6`\
*
Range of Values: Defined by the quantity of '\ :code:`9`\ 's and the presence or absence of an '\ :code:`S`\ ' in the \ :code:`PICTURE`\
*
Storage Format: Unsigned Packed Decimal
*
Negative Values Allowed?: No
*
\ :code:`PICTURE`\ Used?: Yes
| \ :code:`COMPUTATIONAL-X`\
| \ :code:`COMP-X`\
*
Range of Values: If used with \ :code:`PIC X`\ , allocates one byte of storage per '\ :code:`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 '\ :code:`9`\ 's in PICTURE
*
Storage Format: Native unsigned (X) or signed (9) Binary
*
Negative Values Allowed?: If \ :code:`PICTURE`\ 9 and contains '\ :code:`S`\ '
*
\ :code:`PICTURE`\ Used?: Yes
| \ :code:`DISPLAY`\
| \ :code:`~~~~~~~`\
*
Range of Values: 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
*
Storage Format: Characters
*
Negative Values Allowed?: If \ :code:`PICTURE`\ contains '\ :code:`S`\ '
*
\ :code:`PICTURE`\ Used?: Yes
| \ :code:`FLOAT-DECIMAL-16`\
| \ :code:`~~~~~~~~~~~~~~~~`\
*
Range of Values: -9.999999999999999 \* 10\ :sup:`383`\ -- 9.999999999999999 \* 10\ :sup:`384`\
*
Storage Format: Native IEEE 754 Decimal64 Floating-point
*
Negative Values Allowed?: Yes
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`FLOAT-DECIMAL-34`\
| \ :code:`~~~~~~~~~~~~~~~~`\
*
Range of Values: -9.99999... \* 10\ :sup:`6143`\ -- 9.99999... \* 10\ :sup:`6144`\
*
Storage Format: Native IEEE 754 Decimal128 Floating-point
*
Negative Values Allowed?: Yes
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`FLOAT-LONG`\
| \ :code:`~~~~~~~~~~`\
*
Range of Values: Approximately -1.797693134862316 \* 10\ :sup:`308`\ -- 1.797693134862316 \* 10\ :sup:`308`\
*
Storage Format: Native IEEE 754 Binary64 Floating-point
*
Negative Values Allowed?: Yes
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`FLOAT-SHORT`\
| \ :code:`~~~~~~~~~~~`\
*
Range of Values: Approximately -3.4028235 \* 10\ :sup:`38`\ -- 3.4028235 \* 10\ :sup:`38`\
*
Storage Format: Native IEEE 754 Binary32
*
Negative Values Allowed?: Yes
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`INDEX`\
| \ :code:`~~~~~`\
*
Range of Values: 0 to maximum address possible (32 or 64 bits)
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: No
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`NATIONAL`\
| \ :code:`~~~~~~~~`\
*
\ :code:`USAGE NATIONAL`\ , while syntactically recognized, is not supported by GnuCOBOL
| \ :code:`PACKED-DECIMAL`\
| \ :code:`~~~~~~~~~~~~~~`\
*
Range of Values: Defined by the quantity of '\ :code:`9`\ 's and the presence or absence of an '\ :code:`S`\ ' in the PICTURE
*
Storage Format: Signed Packed Decimal
*
Negative Values Allowed?: If \ :code:`PICTURE`\ contains '\ :code:`S`\ '
*
\ :code:`PICTURE`\ Used?: Yes
| \ :code:`POINTER`\
| \ :code:`~~~~~~~`\
*
Range of Values: 0 to maximum address possible (32 or 64 bits)
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: No
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`PROCEDURE-POINTER`\
| \ :code:`~~~~~~~~~~~~~~~~~`\
*
Same as \ :code:`PROGRAM-POINTER`\
| \ :code:`PROGRAM-POINTER`\
| \ :code:`~~~~~~~~~~~~~~~`\
*
Range of Values: 0 to maximum address possible (32 or 64 bits)
*
Storage Format: Native Binary Integer
*
Negative Values Allowed?: No
*
\ :code:`PICTURE`\ Used?: No
| \ :code:`SIGNED-INT`\
| \ :code:`~~~~~~~~~~`\
*
Same as \ :code:`BINARY-LONG SIGNED`\
| \ :code:`SIGNED-LONG`\
| \ :code:`~~~~~~~~~~~`\
*
Same as \ :code:`BINARY-DOUBLE SIGNED`\
| \ :code:`SIGNED-SHORT`\
| \ :code:`~~~~~~~~~~~~`\
*
Same as \ :code:`BINARY-SHORT SIGNED`\
| \ :code:`UNSIGNED-INT`\
| \ :code:`~~~~~~~~~~~~`\
*
Same as \ :code:`BINARY-LONG UNSIGNED`\
| \ :code:`UNSIGNED-LONG`\
| \ :code:`~~~~~~~~~~~~~`\
*
Same as \ :code:`BINARY-DOUBLE UNSIGNED`\
| \ :code:`UNSIGNED-SHORT`\
| \ :code:`~~~~~~~~~~~~~~`\
*
Same as \ :code:`BINARY-SHORT UNSIGNED`\
#.
| \ :code:`USAGE IS type-name-1`\
| \ :code:`~~~~~ ~~`\
#.
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 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.
#.
Binary data (integer or floating-point) can be stored in either a \ *Big-Endian*\ or \ *Little-Endian*\ form.
Big-endian data allocation calls for the bytes that comprise a binary item to be allocated such that the least-significant byte is the right-most byte. For example, a four-byte binary item having a value of decimal 20 would be big-endian allocated as 00000014 (shown in hexadecimal notation).
Little-endian data allocation calls for the bytes that comprise a binary item to be allocated such that the least-significant byte is the left-most byte. For example, a four-byte binary item having a value of decimal 20 would be little-endian allocated as 14000000 (shown in hexadecimal notation).
All CPUs are capable of \ *understanding*\ big-endian format, which makes it the \ *most compatible*\ form of binary storage across computer systems.
Some CPUs --- such as the Intel/AMD i386/x64 architecture processors used in most Windows PCs --- prefer to process binary data stored in a little-endian format. Since that format is more efficient on those systems, it is referred to as the \ *native*\ binary format.
On a system supporting only one format of binary storage (generally, that would be big-endian), the terms \ *most efficient*\ and \ *native*\ format are synonymous.
.. index:: single:UNSIGNED
#.
Data items that have the
\ \ :code:`UNSIGNED`\ attribute explicitly coded, or \ :code:`DISPLAY`\ , \ :code:`PACKED-DECIMAL`\ , \ :code:`COMP-5`\ , \ :code:`COMP-X`\ items that do not have an '\ :code:`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.
#.
Packed-decimal (\ *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 \ *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 '\ :code:`9`\ ' in the \ :code:`PICTURE`\ and each holds a single decimal digit encoded as its binary value (0 = 0000, 1 = 0001, ... , 9 = 1001).
The \ *last*\ byte of a \ :code:`PACKED-DECIMAL`\ or \ :code:`COMP-3`\ data item will always have its left nibble corresponding to the last '\ :code:`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 '\ :code:`S`\ ' symbol.
The \ *first*\ byte of the data item will contain an unused left nibble if the \ :code:`PICTURE`\ had an even number of '\ :code:`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 '\ :code:`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 '\ :code:`9`\ ' symbols in its \ :code:`PICTURE`\ will leave its leftmost nibble unused.
#.
The \ :code:`USAGE`\ specifications \ :code:`FLOAT-DECIMAL-16`\ and \ :code:`FLOAT-DECIMAL-34`\ will encode data using IEEE 754 \ *Decimal64*\ and \ *Decimal128*\ format, respectively. The former allows for up to 16 digits of exact precision while the latter offers 34. The phrase "exact precision" is used because the traditional binary renderings of decimal real numbers in a floating-point format (\ :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 \ *Decimal64*\ ).
#.
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.
#.
The \ :code:`USAGE`\ specifications \ :code:`FLOAT-LONG`\ and \ :code:`FLOAT-SHORT`\ use the IEEE 754 \ *Binary64*\ and \ *Binary32*\ formats, respectively. These are binary encodings of real decimal numbers, and as such cannot represent every possible value between the minimum and maximum values in the range for those usages. Wikipedia has an excellent article on the Binary64 and Binary32 encoding schemes --- just search on \ *Binary32*\ or \ *Binary64*\ .
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.
#.
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.
#.
The only \ :code:`USAGE`\ that is allowed in the report section is \ :code:`USAGE DISPLAY`\ .
.. index:: single:USING
.. _USING:
6.9.62 USING
~~~~~~~~~~~~
USING Clause Syntax
::
USING identifier-1
~~~~~
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.
#.
When the screen item whose definition this clause is part of is displayed, the value currently in <identifier-1> will be automatically moved into the screen item first.
#.
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 <identifier-1> at the conclusion of the \ :code:`ACCEPT`\ .
#.
The \ :code:`FROM`\ ( :ref:`FROM`), \ :code:`TO`\ ( :ref:`TO`), \ :code:`USING`\ and \ :code:`VALUE`\ ( :ref:`VALUE`) clauses are mutually-exclusive in any screen section data item's definition.
.. index:: single:VALUE
.. _VALUE:
6.9.63 VALUE
~~~~~~~~~~~~
VALUE (Condition Names) Clause Syntax
::
{ VALUE IS } {literal-1 [ THRU|THROUGH literal-2 ]}...
{ ~~~~~ } ~~~~ ~~~~~~~
{ VALUES ARE }
~~~~~~
[ WHEN SET TO FALSE IS literal-3 ]
~~~~~
VALUE (Other Data Items) Syntax
::
VALUE IS [ ALL ] literal-1
~~~~~ ~~~
VALUE (For Tables) Syntax
::
{ VALUE IS } {{literal-1}.. FROM ({subscript-1}..) [ TO ({subscript-2}.. )]}..
{ ~~~~~ } ~~~~ ~~
{ VALUES ARE }
~~~~~~
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.
#.
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.
#.
This clause cannot be specified on the same data item as a \ :code:`FROM`\ ( :ref:`FROM`), \ :code:`TO`\ ( :ref:`TO`) or \ :code:`USING`\ ( :ref:`USING`) clause.
#.
The following points apply to using the \ :code:`VALUE`\ clause in the definition of a condition name:
#.
The clauses \ :code:`VALUE IS`\ and \ :code:`VALUES ARE`\ are interchangeable.
#.
The reserved words \ :code:`THRU`\ and \ :code:`THROUGH`\ are interchangeable.
#.
:ref:`88-LevelADataAItems`, for a discussion of how this format of \ :code:`VALUE`\ is used to create condition names.
#.
:ref:`ConditionANames`, for a discussion of how condition names are used.
#. The following points apply to using the \ :code:`VALUE`\ clause in the definition of any other data 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.
#.
The \ :code:`VALUE`\ clause is ignored on \ :code:`EXTERNAL`\ ( :ref:`EXTERNAL`) data items or on any data items defines as subordinate to an \ :code:`EXTERNAL`\ data 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.
.. index:: single:ALL
#.
If the optional
\ \ :code:`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 \ *b*\ denotes a space):
::
PIC X(5) VALUE 'A' *> A\ *bbbb*\
PIC X(5) VALUE ALL 'A' *> AAAAA
PIC 9(3) VALUE 1 *> 001
PIC 9(3) VALUE ALL '1' *> 111
#.
When used in the definition of a screen data item:
#.
A figurative constant may not be supplied as <literal-1>.
#.
Any \ :code:`FROM`\ ( :ref:`FROM`), \ :code:`TO`\ ( :ref:`TO`) or \ :code:`USING`\ ( :ref:`USING`) clause in the same data item's definition will be ignored.
#.
If there is no picture clause specified, the size of the screen data item will be the length of the <literal-1> value.
#.
If there is no picture clause and the \ :code:`ALL`\ option is specified, the \ :code:`ALL`\ option will be ignored.
#.
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 \ *standard*\ approaches:
#.
Don't bother worrying about it at compile-time. Use the \ :code:`INITIALIZE`\ ( :ref:`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).
#.
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:
::
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).
#. Initialize tables of almost any size at compilation time by utilizing the \ :code:`REDEFINES`\ ( :ref:`REDEFINES`) clause:
::
05 SHIRT-SIZE-VALUES.
10 PIC X(4) VALUE "S 14".
10 PIC X(4) VALUE "M 15".
10 PIC X(4) VALUE "L 16".
10 PIC X(4) VALUE "XL17".
05 SHIRT-SIZES REDEFINES SHIRT-SIZE-VALUES.
10 SHIRT-SIZE-TBL OCCURS 4 TIMES.
15 SST-SIZE PIC X(2).
15 SST-NECK PIC 9(2).
Admittedly, this table is much more verbose than the one shown with a group \ :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!
#.
Many COBOL compilers do not allow the use of \ :code:`VALUE`\ and \ :code:`OCCURS`\ ( :ref:`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:
::
05 X OCCURS 6 TIMES.
10 A PIC X(1) VALUE '?'.
10 B PIC X(1) VALUE '%'.
10 N PIC 9(2) VALUE 10.
In this example, all six '\ :code:`A`\ ' items will be initialized to '\ :code:`?`\ ', all six '\ :code:`B`\ ' items will be initialized to '\ :code:`%`\ ' and all six '\ :code:`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.
#.
The \ :code:`FROM`\ ( :ref:`FROM`), \ :code:`TO`\ ( :ref:`TO`), \ :code:`USING`\ ( :ref:`USING`) and \ :code:`VALUE`\ clauses are mutually-exclusive in any screen section data item's definition.
#.
Format-3 (Table): The value clause for tables specifies the initial value of working-storage section and local-storage section data items.
::
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).
::
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.
.. [#] OR DOES IT? \ *author uncertain*\