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
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.
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 Employee:
Employee
| Additional
:----------------:----------------:--> Data Items ...
| |
Employee-name Employment-Dates
| |
:---------:-------------: :-------:-------:
| | | | |
Last-Name First-Name Middle-Initial From-Date To-Date
| |
:----:----: :----:----:
| | | | | |
Year Month Day Year Month Day
The Employee data item consists of two subordinate data items — an Employee-Name and an Employment-Dates data item (presumably there would be a lot of others too, but we don’t care about them right now). As the diagram shows, each of those data items are, in turn, broken down into subordinate data items. This hierarchy of data items can get rather deep, and GnuCOBOL, like other COBOL implementations, can handle up to 49 levels of such hierarchical structures.
As was presented earlier (see Structured Data), a data item that is broken down into other data items is referred to as a group item, while one that isn’t broken down is called an elementary item.
COBOL uses the concept of a level number to indicate the level at which a data item occurs in a data structure such as the example shown above. When these data items are defined, they are all defined together with a number in the range 1-49 specified in front of their names. Over the years, a convention has come to exist among COBOL programmers that level numbers are always coded as two-digit numbers — they don’t 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 (see Special Data Items).
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 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 Year, Month and Day data names defined? That’s perfectly legal, provided that each can be uniquely qualified so as to be distinct from the other. Take for example the Year items. One is defined as part of the From-Date data item while the other is defined as part of the To-Date data item. In COBOL, we would actually code references to these two data items as either Year OF From-Date and Year OF To-Date or Year IN From-Date and Year IN To-Date (COBOL allows either IN or OF to be used). Since these references would clarify any confusion to us as to which Year might be referenced, the GnuCOBOL compiler won’t be confused either.
The coding example shown above is incomplete; it only describes the data item names and their hierarchical relationships to one other. In addition, any valid data item definitions will also need to describe what type of data is to be contained in a data item (Numeric? Alphanumeric? Alphabetic?), how much data can be held in the data item and a multitude of other characteristics.
When group items are being defined, subordinate items may be assigned the “name” FILLER. There may be any number of FILLER items defined within a group item. A data item named FILLER cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item. Note that it is possible that the name of the group item itself might be specified as FILLER if there is no need to ever refer directly to the group structure itself.
FILE SECTION
FILE SECTION Syntax
=======================================================================
[ FILE SECTION.
~~~~ ~~~~~~~
{ File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ]
{ { 01-Level-Constant } }
{ { 78-Level-Constant } }
{ 01-Level-Constant }
{ 78-Level-Constant }
=======================================================================
Every file that has been referenced by a SELECT statement (see SELECT) must also be described in the file section of the data division.
Files destined for use as sort/merge work files must be described with a Sort/Merge File Description (SD) while every other file is described with a File Description (FD). Each of these descriptions will almost always be followed with at least one record description.
File/Sort-Description
File/Sort-Description Syntax
=======================================================================
FD|SD file-name-1 [ IS EXTERNAL|GLOBAL ]
~~ ~~ ~~~~~~~~ ~~~~~~
[ BLOCK CONTAINS [ integer-1 TO ] integer-2 CHARACTERS|RECORDS ]
~~~~~ ~~ ~~~~~~~~~~ ~~~~~~~
[ CODE-SET IS alphabet-name-1 ]
~~~~~~~~
[ DATA { RECORD IS } identifier-1... ]
~~~~ { ~~~~~~ }
{ RECORDS ARE }
~~~~~~~
[ LABEL { RECORD IS } OMITTED|STANDARD ]
~~~~~ { ~~~~~~ } ~~~~~~~ ~~~~~~~~
{ RECORDS ARE }
~~~~~~~
[ LINAGE IS integer-3 | identifier-2 LINES
~~~~~~
[ LINES AT BOTTOM integer-4 | identifier-3 ]
~~~~~~
[ LINES AT TOP integer-5 | identifier-4 ]
~~~
[ WITH FOOTING AT integer-6 | identifier-5 ] ]
~~~~~~~
[ RECORD { CONTAINS [ integer-7 TO ] integer-8 CHARACTERS } ]
~~~~~~ ~~
{ IS VARYING IN SIZE }
~~~~~~~
{ [ FROM [ integer-7 TO ] integer-8 CHARACTERS }
~~
{ DEPENDING ON identifier-6 ] }
~~~~~~~~~
[ RECORDING MODE IS recording-mode ]
~~~~~~~~~
[ { REPORT IS } report-name-1... ]
{ ~~~~~~ }
{ REPORTS ARE }
~~~~~~~
[ VALUE OF implementor-name-1 IS literal-1 | identifier-7 ] .
~~~~~ ~~
The BLOCK CONTAINS, DATA RECORD, LABEL RECORD, RECORDING MODE and VALUE OF clauses are syntactically recognized but are obsolete and non-functional. These clauses should not be coded in new programs.
=======================================================================
The reserved words
ARE,AT,CHARACTERS(RECORDclause only),CONTAINS,FROM,IN,IS,ONandWITHare 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
RECORD ISandRECORDS AREare interchangeable.The terms
REPORT ISandREPORTS AREare interchangeable.Only files intended for use as work files for either the
SORT(see SORT) orMERGE(see MERGE) statements should be coded with an SD — all others should be defined with a FD.The sequence in which files are defined via
FDorSD, as compared to the sequence in which theirSELECTstatements were coded, is irrelevant.The name specified as <file-name-1> must exactly match the name specified on the file’s
SELECTstatement.The
CODE-SETclause allows a custom alphabet, defined in theSPECIAL-NAMES(see 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
LINAGEclause may only be specified in theFDof 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 theLINAGEclause define the layout of printed pages as follows:- 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.
- 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.
- 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.
- 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
LINAGE IS n LINESvalue.
This page structure — once defined — can be automatically enforced by the
WRITEstatement (see WRITE).Specifying a
LINAGEclause in anFDwill cause theLINAGE-COUNTERspecial 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 aWRITEstatement.The
RECORD CONTAINSandRECORD IS VARYINGclauses 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>.The
REPORT ISclause 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 theREPORTclause is used:The clause may only be specified in the
FDof 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
FDcannot be followed by record descriptions. Detailed descriptions of data to be printed to the file will be defined in theREPORT SECTION(see REPORT SECTION).If a
LINAGEclause is also specified, Values specified forLINAGE ISandFOOTING ATwill be ignored. The values ofLINES AT BOTTOMandLINES 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
DISK(orDISC) on theirSELECTstatements.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:
The
TMPDIRrun-time environment variable (see Run Time Environment Variables)The
TMPrun-time environment variableThe
TEMPrun-time environment variable
(in that order).
These disk files will be automatically purged upon
SORTorMERGEtermination. They will also be purged if the program terminates abnormally before theSORTorMERGEfinishes. Should you ever need to know, temporary sort/merge work files will be namedcob*.tmp.If you specify a specific filename in the sort/merge work file’s
SELECT, it will be ignored.
See Data Description Clauses, for information on the
EXTERNALandGLOBALoptions.implementor-name-1 can take the value: FILE-ID and is used to specify the external name of the file as literal-1 (only if this external name has not been specified in the corresponding SELECT clause). Example:
SELECT file1 ASSIGN TO DISK (without an external name ... ... FD File1 VALUE OF FILE-ID "file1.txt".
FILE-SECTION-Data-Item
FILE-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1 | FILLER ] [ IS GLOBAL ]
~~~~~~ ~~~~~~
[ BLANK WHEN ZERO|ZEROES|ZEROS ]
~~~~~ ~~~~ ~~~~~~ ~~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS integer-1 [ TO integer-2 ] TIMES [ DEPENDING ON identifier-2 ] ]
[ ~~~~~~ ~~ ~~~~~~~~~ ]
[ [ { ASCENDING|DESCENDING KEY IS { identifier-3 }...}...] ]
[ ~~~~~~~~~ ~~~~~~~~~~ ]
[ [ INDEXED BY { identifier-4 }...] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE [CHARACTER] ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ IS TYPEDEF ]
~~~~~~~
[ TYPE TO type-name-1 ]
~~~~
[ SAME AS identifier-6 ]
~~~~
[ IS SPECIAL-NAMES { special-names-item }...]
~~~~~~~~~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ FILE-SECTION-Data-Item ]...
~~~~~ ~~~
The LEFT and RIGHT (SYNCHRONIZED) clauses are syntactically recognized but are otherwise non-functional.
=======================================================================
Every sort file description (SD or FD) must be followed by at least one 01-level data item, except for file descriptions containing the REPORT IS clause. These 01-level data items, in turn, may be broken down into subordinate group and elementary items. An 01-level data item defined here in the file section is also known as a Record, even if it is an elementary item, provided that elementary item lacks the CONSTANT attribute.
The reserved words
BY,IS,KEY,ONandWHENare 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
SYNCHRONIZEDandSYNCHRONISEDare interchangeable. Both may be abbreviated toSYNC.The reserved word
PICTUREmay be abbreviated toPIC.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
FDorSDis 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
FDorSD, the one with the longest length will define the size of the record buffer into which aREADstatement (see READ) or aRETURNstatement (see RETURN) will deliver data read from the file and from which aWRITEstatement (see WRITE) orRELEASEstatement (see 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
SAME RECORD AREA(see SAME RECORD AREA) 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 — See Special Data Items, for details.
Not specifying an <identifier-1> or
FILLERimmediately after the level number has the same effect as ifFILLERwere specified. A data item namedFILLERcannot 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.EXTERNALcannot be combined withGLOBALorREDEFINES.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.
See Data Description Clauses, for information on the usage of the various data description clauses.
WORKING-STORAGE SECTION
WORKING-STORAGE-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1|FILLER ] [ IS GLOBAL|EXTERNAL [AS literal-2] ]
~~~~~~ ~~~~~~ ~~~~~~~~ ~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO|ZEROES|ZEROS ]
~~~~~ ~~~~ ~~~~~~ ~~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS integer-1 [ TO integer-2 ] TIMES [ DEPENDING ON identifier-2 ] ]
[ ~~~~~~ ~~ ~~~~~~~~~ ]
[ [ { ASCENDING|DESCENDING KEY IS { identifier-3 }...}...] ]
[ ~~~~~~~~~ ~~~~~~~~~~ ]
[ [ INDEXED BY { identifier-4 }...] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ IS TYPEDEF ]
~~~~~~~
[ TYPE TO type-name-1 ]
~~~~
[ SAME AS identifier-6 ]
~~~~
[ IS SPECIAL-NAMES { special-names-item }...]
~~~~~~~~~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ WORKING-STORAGE-SECTION-Data-Item ]...
~~~~~ ~~~
The LEFT and 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
BY,CHARACTER,IS,KEY,ON,RIGHT(JUSTIFIED),TIMESandWHENare 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
SYNCHRONIZEDandSYNCHRONISEDare interchangeable. Both may be abbreviated asSYNC.The reserved word
PICTUREmay be abbreviated toPIC.The reserved word
JUSTIFIEDmay be abbreviated toJUST.As the syntax diagram shows, the definition of a
WORKING-STORAGE-SECTION-Data-Itemis 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; See 77-Level Data Items, for more information.
A division or section header is found — this also marks the completion of a record and signifies the end of the working-storage section as well.
Every
WORKING-STORAGE-SECTION-Data-Itemdescription 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 — See Special Data Items, for details.
Not specifying an <identifier-1> or
FILLERimmediately after the level number has the same effect as ifFILLERwere specified. A data item namedFILLERcannot 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
CANCELstatement (see CANCEL)), in which case initialization will happen each time they are loaded. See Data Initialization, for a discussion of the initialization rules.See Data Description Clauses, for information on the usage of the various data description clauses.
LOCAL-STORAGE SECTION
LOCAL-STORAGE-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL [AS literal-2] ]
~~~~~~ ~~~~~~ ~~~~~~~~ ~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO|ZEROES|ZEROS ]
~~~~~ ~~~~ ~~~~~~ ~~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS integer-1 [ TO integer-2 ] TIMES [ DEPENDING ON identifier-2 ] ]
[ ~~~~~~ ~~ ~~~~~~~~~ ]
[ [ { ASCENDING|DESCENDING KEY IS { identifier-3 }...}...] ]
[ ~~~~~~~~~ ~~~~~~~~~~ ]
[ [ INDEXED BY { identifier-4 }...] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ IS TYPEDEF ]
~~~~~~~
[ TYPE TO type-name-1 ]
~~~~
[ SAME AS identifier-6 ]
~~~~
[ IS SPECIAL-NAMES { special-names-item }...]
~~~~~~~~~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ LOCAL-STORAGE-SECTION-Data-Item ]...
~~~~~ ~~~
The LEFT and 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. See Data Initialization, for the rules of data initialization.
The reserved words
BY,CHARACTERIS,KEY,ON,RIGHT(JUSTIFIED),TIMESandWHENare 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
SYNCHRONIZEDandSYNCHRONISEDare interchangeable. Both may be abbreviated asSYNC.The reserved word
PICTUREmay be abbreviated toPIC.The reserved word
JUSTIFIEDmay be abbreviated toJUST.As the syntax diagram shows, the definition of a
LOCAL-STORAGE-SECTION-Data-Itemis 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
LOCAL-STORAGE-SECTION-Data-Itemdescription 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 — See Special Data Items, for details.
Not specifying an <identifier-1> or
FILLERimmediately after the level number has the same effect as ifFILLERwere specified. A data item namedFILLERcannot 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.
See Data Description Clauses, for information on the usage of the various data description clauses.
LINKAGE SECTION
LINKAGE-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1|FILLER ] [ IS GLOBAL|EXTERNAL [AS literal-2] ]
~~~~~~ ~~~~~~ ~~~~~~~~ ~~
{ BASED }
{ ~~~~~ }
{ ANY LENGTH }
{ ~~~ ~~~~~~ }
{ ANY NUMERIC }
~~~ ~~~~~~~
[ BLANK WHEN ZERO|ZEROES|ZEROS ]
~~~~~ ~~~~ ~~~~~~ ~~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS integer-1 [ TO { integer-2 } ] TIMES [ DEPENDING ON identifier-2 ] ]
[ ~~~~~~ ~~ { UNBOUNDED } ~~~~~~~~~ ]
[ ~~~~~~~~~ ]
[ [ { 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 ]
~~~~~
[ IS TYPEDEF ]
~~~~~~~
[ TYPE TO type-name-1 ]
~~~~
[ SAME AS identifier-6 ]
~~~~
[ IS SPECIAL-NAMES { special-names-item }...]
~~~~~~~~~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ LINKAGE-SECTION-Data-Item ]...
~~~~~ ~~~
The LEFT and 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
BY,CHARACTER,IS,KEY,ONandWHENare 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
SYNCHRONIZEDandSYNCHRONISEDare interchangeable. Both may be abbreviated asSYNC.The reserved word
PICTUREmay be abbreviated toPIC.The reserved word
JUSTIFIEDmay be abbreviated toJUST.As the syntax diagram shows, the definition of a
LINKAGE-SECTION-Data-Itemis 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
LINKAGE-SECTION-Data-Itemdescription 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 — See Special Data Items, 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
PROCEDURE DIVISION USING(see PROCEDURE DIVISION USING) or as arguments on anENTRYstatement.Each 01-level data item described within a subprogram’s linkage section should correspond to an argument passed on a
CALLstatement (see CALL) or an argument on a function call to the subprogram.
Not specifying an <identifier-1> or
FILLERimmediately after the level number has the same effect as ifFILLERwere specified. A data item namedFILLERcannot 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 namedFILLER.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
ALLOCATEstatement (see ALLOCATE) statement. In such cases, initialization will take place as per the documentation of that statement.The reserved word
UNBOUNDEDcan be used to specify an unbounded table (a table with an unbounded maximum number of occurrences), and can be referenced anywhere that a table can be referenced.An unbounded group is a group that contains at least one unbounded table. It can be specified ONLY in the Linkage Section, and must be of type alphanumeric or national.
You can reference unbounded groups in COBOL syntax anywhere that an alphanumeric or national group can be referenced, with the following exceptions:
You cannot specify unbounded groups as a BY CONTENT argument in a CALL statement. You cannot specify unbounded groups as data-name-2 on the Procedure Division RETURNING phrase. You cannot specify unbounded groups as arguments to intrinsic functions, except as an argument to the LENGTH intrinsic function.
See Data Description Clauses, for information on the usage of the various data description clauses.
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 WORKING-STORAGE SECTION and not elsewhere.
The reserved words
AREandISare optional and may be omitted. The presence or absence of these words has no effect upon the program.The phrases
CONTROL ISandCONTROLS AREare interchangeable, as are thePAGE LIMITandPAGE LIMITSphrases.The reserved word
LINESmay be abbreviated asLINE.The reserved word
COLUMNSmay be abbreviated asCOLS.Each report referenced on a
REPORT ISclause (see File/Sort-Description) must be described with a report description (RD).See GLOBAL, for information on the
GLOBALoption.Please see Report Writer Features, if you have not read it already. It will familiarize you with the Report Writer terminology that follows.
The following rules pertain to the
PAGE LIMITSclause:If no
PAGE LIMITSclause 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
LINES AT TOPandLINES AT BOTTOMvalues specified on theLINAGEclause of theFDthisRDis linked to — see File/Sort-Description).Any value specified for <literal-3> or <identifier-3> will be ignored.
The
HEADINGclause defines the first line number at which a report heading or page heading may be presented.The
FIRST DETAILclause defines the first line at which a detail group may be presented.The
LAST CONTROLHEADINGclause defines the last line at which any line of a control heading may be presented.The
LAST DETAILclause defines the last line at which any line of a detail group may be presented.The
FOOTINGclause 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
PAGE LIMITclauses, assuming there is one:HEADING-
default is one (1)
FIRST DETAIL HEADING-
value is used
LAST CONTROL HEADING-
value from
LAST DETAILor, if that is absent, the value fromFOOTINGor, if that too is absent, the value fromPAGE LIMIT LAST DETAIL-
value from
FOOTINGor, if that is absent, the value fromPAGE LIMIT FOOTING-
value from
LAST DETAILor, if that is absent, the value fromPAGE LIMIT
For the values specified on a
PAGE LIMITclause to be valid, all of the following must be true:FIRST DETAIL≤HEADINGLAST CONTROL HEADING≤FIRST DETAILLAST DETAIL≤LAST CONTROL HEADINGFOOTING≤LAST DETAIL
The following rules pertain to the
CONTROLclause:If there is no
CONTROLclause, the report will contain no control breaks; this implies that there can be noCONTROL HEADINGorCONTROL FOOTINGreport groups defined for thisRD.Include the reserved word
FINALif you want to include a special control heading before the first detail line is generated (CONTROL HEADING FINAL) or after the last detail line is generated (CONTROL FOOTING FINAL).If you specify
FINAL, it must be the first control break named in theRD.Any <identifier-9> specifications included on the
CONTROLclause are referencing data names defined in any data division section except for the report section.There must be a
CONTROL HEADINGand/orCONTROL FOOTINGreport group defined in the report section for each <identifier-9>.At execution time:
Each time a
GENERATEstatement (see GENERATE) is executed against a detail report group defined for thisRD, the RWCS will check the contents of each <identifier-2> data item; whenever an <identifier-9>’s value has changed since the previousGENERATE, a control break condition will be in effect for that <identifier-2>.Once the list of control breaks has been determined, the
CONTROL FOOTINGfor each <identifier-2> having a control break (if any such report group is defined) will be presented.Next, the
CONTROL HEADINGfor each <identifier-2> having a control break (if any such report group is defined) will be presented.The
CONTROL FOOTINGandCONTROL HEADINGreport groups will be presented in the sequence in which they are listed on theCONTROLclause.Only after this processing has occurred will the detail report group specified on the
GENERATEbe presented.
Each
RDwill have the following allocated for it:The
PAGE-COUNTERspecial register (see Special Registers), which will contain the current report page number.This register will be set to a value of 1 when an
INITIATEstatement (see INITIATE) is executed for the report and will be incremented by 1 each time the RWCS starts a new page of the report.References to
PAGE-COUNTERwithin the report section will be implicitly qualified with the name of the report to which the report group referencing the register belongs.References to
PAGE-COUNTERin the procedure division must be qualified with the appropriate report name if there are multipleRDs defined.
The
LINE-COUNTERspecial register, which will contain the current line number on the current page.
The
RDmust be followed by at least one 01-level report group definition.
Report Group Definitions
Report-Group-Definition Syntax
=======================================================================
01 [ identifier-1 ]
[ LINE NUMBER IS { integer-1 [ [ ON NEXT PAGE ] } ]
~~~~ ~~~~ ~~~~
{ +|PLUS integer-1 }
~~~~
{ ON NEXT PAGE }
~~~~ ~~~~
[ NEXT GROUP IS { [ +|PLUS ] integer-2 } ]
~~~~ ~~~~~ ~~~~
{ NEXT|{NEXT PAGE}|PAGE }
~~~~ ~~~~ ~~~~ ~~~~
[ TYPE IS { RH|{REPORT HEADING} } ]
~~~~ ~~ ~~~~~~ ~~~~~~~
{ PH|{PAGE HEADING} }
~~ ~~~~ ~~~~~~~
{ CH|{CONTROL HEADING} FINAL|identifier-2 }
~~ ~~~~~~~ ~~~~~~~ ~~~~~
{ DE|DETAIL }
~~ ~~~~~~
{ CF|{CONTROL FOOTING} FINAL|identifier-2 }
~~ ~~~~~~~ ~~~~~~~ ~~~~~
{ PF|{PAGE FOOTING} }
~~ ~~~~ ~~~~~~~
{ RF|{REPORT FOOTING} }
~~ ~~~~~~ ~~~~~~~
. [ REPORT-SECTION-Data-Item ]...
=======================================================================
The syntax shown here documents how a report group is defined to a report. This syntax is valid only in the report section, and only then after an RD.
The reserved words
IS,NUMBERandONare optional and may be omitted. The presence or absence of these words has no effect upon the program.The
RHandREPORT HEADINGterms are interchangeable, as arePHandPAGE HEADING,CHandCONTROL HEADING,DEandDETAIL,CFandCONTROL FOOTING,PFandPAGE FOOTINGas well asRFandREPORT FOOTING.The report group being defined will be a part of the most-recently coded
RD.The
TYPE(see 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
GENERATEstatement or on aUSE BEFORE REPORTING.No two report groups in the same report (
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
REPORT-SECTION-Data-Itemwith a level number in the range 02-49.See Data Description Clauses, for information on the usage of the various data description clauses.
REPORT SECTION Data Items
REPORT-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1 ]
[ LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] } ]
~~~~ { +|PLUS integer-2 ~~~~ ~~~~ }
{ ~~~~ }
{ ON NEXT PAGE }
~~~~ ~~~~
[ { COLUMN } [ NUMBER ] [ LEFT ] [ IS ] { [ +|PLUS ] integer-1 } ]
{ ~~~~~~ } [ NUMBERS ] [ ~~~~ ] [ ARE ] { ~~~~ }
{ COL } [ RIGTH ] { {integer-2 }... }
{ ~~~ } [ ~~~~~ ]
{ COLUMNS } [ CENTER ]
{ ~~~~~~~ } ~~~~~~
{ COLS }
~~~~
[ GROUP INDICATE ]
~~~~~ ~~~~~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS [ integer-3 TO ] integer-4 TIMES
~~~~~~ ~~
[ DEPENDING ON identifier-2 ]
~~~~~~~~~
[ STEP integer-5 ]
~~~~
*** [ VARYING identifier-3 FROM { identifier-4 } BY { identifier-5 } ]
~~~~~~~ ~~~~ { integer-6 } ~~ { integer-7 } ***
[ PICTURE IS picture-string ]
~~~
[ PRESENT WHEN condition-name ]
~~~~~~~ ~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ BLANK WHEN ZERO ]
~~~~~ ~~~~
[ { 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 } }
~~~~~ ~~~ ~~~~
.
*** Options NOT IMPLEMENTED.
[ 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
IS,NUMBER,OF,ON,RIGHT,TIMESandWHEN(BLANK) are optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved word
COLUMNmay be abbreviated asCOL.The reserved word
JUSTIFIEDmay be abbreviated asJUST.The reserved word
PICTUREmay be abbreviated asPIC.The
SOURCE(see SOURCE),SUM(see SUM) andVALUE(see VALUE) clauses, valid only on an elementary item, are mutually-exclusive of each other.Group items (those without
PICTUREclauses) 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 haveLINE(see LINE) clauses and noCOLUMN(see COLUMN) clauses while elementary items will be specified the other way around.The reserved word
VARYINGis NOT implemented at least in version 3.2 and more possibly in later versions of the GnuCobol compiler at this time. There is no date when it might be. Any usage of such, will produce an error message when compiling.See Data Description Clauses, for information on the usage of the various data description clauses.
SCREEN SECTION
SCREEN-SECTION-Data-Item Syntax
=======================================================================
level-number [ identifier-1|FILLER ]
~~~~~~
[ BLANK { LINE|SCREEN } ]
~~~~~ ~~~~ ~~~~~~
[ ERASE { EOL|EOS } ]
[ ~~~~~ { ~~~ ~~~ } ]
[ { [TO END OF ] {LINE|SCREEN } } ]
~~~ ~~~~ ~~~~~~
[ LINE NUMBER IS [ { +|PLUS } ] integer-3|identifier-4 ]
[ ~~~~ [ { ~~~~ } ] ]
[ [ { -|MINUS } ] ]
~~~~~
[ COLUMN|POSITION NUMBER IS [ { +|PLUS } ] integer-4|identifier-5 ]
[ ~~~ ~~~ [ { ~~~~ } ] ]
[ [ { -|MINUS } ] ]
~~~~~
[ BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1|identifier-2 ]
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
[ FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-2|identifier-3 ]
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
[ AUTO|AUTO-SKIP|AUTOTERMINATE|TAB ]
~~~~ ~~~~~~~~~ ~~~~~~~~~~~~~ ~~~
[ BELL|BEEP ]
~~~~ ~~~~
[ BLANK WHEN ZERO|ZEROS|ZEROES ]
~~~~~ ~~~~ ~~~~~ ~~~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ BLINK ]
~~~~~
[ HIGHLIGHT|LOWLIGHT ]
~~~~~~~~~ ~~~~~~~~
[ REVERSE-VIDEO|REVERSED|REVERSE ]
~~~~~~~~~~~~~ ~~~~~~~~ ~~~~~~~
[ LEFTLINE ] [ OVERLINE ] [ UNDERLINE ]
~~~~~~~~ ~~~~~~~~ ~~~~~~~~~
[ PROMPT [ CHARACTER IS literal-1|identifier-10 ]
~~~~~~ ~~~~~~~~~
[ FROM literal-2|identifier-6 ]
~~~~
[ TO identifier-7 ]
~~
[ USING identifier-8 ]
~~~~~
[ [ VALUE IS ] literal-3 ]
~~~~~
[ INITIAL [ literal-4 ] ]
~~~~~~~
[ REQUIRED|EMPTY-CHECK ]
~~~~~~~~ ~~~~~~~~~~~
[ FULL|LENGTH-CHECK ]
~~~~ ~~~~~~~~~~~~
[ SECURE|NO-ECHO|NO ECHO|OFF | ]
~~~~~~ ~~~~~~~ ~~ ~~~~ ~~~~
[ CURSOR { identifier-9 } ]
~~~~~~
[ PICTURE IS picture-string ]
~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ OCCURS integer-5 TIMES ] .
~~~~~~
=======================================================================
The screen section describes the screens to be displayed during terminal/console I-O.
The reserved words
CHARACTER(SEPARATEclause),IS,NUMBER,RIGHT,TIMESandWHENare optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved word
COLUMNmay be abbreviated asCOL.The reserved word
PICTUREmay be abbreviated asPIC.The following sets of reserved words are interchangeable:
AUTO,AUTO-SKIPandAUTOTERMINATEBACKGROUND-COLORandBACKGROUND-COLOURBELLandBEEPFOREGROUND-COLORandFOREGROUND-COLOURFULLandLENGTH-CHECKREQUIREDandEMPTY-CHECKSECUREandNO-ECHO
Data items defined in the screen section describe input, output or combination screen layouts to be used with
ACCEPT data-itemstatement (see ACCEPT data-item) orDISPLAY data-itemstatement (see DISPLAY data-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
LINE(see LINE) orCOLUMN(see COLUMN) clauses, screen section fields will display on the console window beginning at whatever line/column coordinate is stated or implied by theACCEPT data-itemorDISPLAY data-itemstatement 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
LINEclause explicitly stated in the definition of a screen section data item will override anyLINEclause included on theACCEPT data-itemorDISPLAY data-itemstatement that presents that data item to the screen. The same is true ofCOLUMNclauses.The Tab and Back-Tab (Shift-Tab on most keyboards) keys will position the cursor from field to field in the line/column sequence in which the fields occur on the screen at execution time, regardless of the sequence in which they were defined in the screen section.
See Data Description Clauses, for information on the usage of the various data description clauses.
See details of ACCEPT data-item for more information regarding usage of CURSOR.
Use of the TAB phrase forces the user to finish the ACCEPT verb with a termination key. This is the standard mode for GnuCOBOL and other compilers but not for RM COBOL. TAB cannot be used together with the AUTO / AUTO-SKIP and AUTOTERMINATE clauses.
OCCURS. Have that as pending: the compiler supports that, but the runtime does not handle it yet.
The
INITIALclause indicates that at the time of ACCEPT of the SCREEN, the cursor will be positioned on this field.Example: >>source free IDENTIFICATION DIVISION. PROGRAM-ID. TESTINITIAL. DATA DIVISION. WORKING-STORAGE SECTION. 01 dummy-1 PIC X(10). 01 dummy-2 PIC X(10). 01 dummy-3 PIC X(10). SCREEN SECTION. 01 scr. 03 LINE + 1, PIC X(80) VALUE 'field.'. 03 LINE + 2, PIC X(10) TO dummy-1. 03 COL + 2, PIC X(10) TO dummy-2. 03 COL + 2, PIC X(10) TO dummy-3 INITIAL. PROCEDURE DIVISION. DISPLAY scr ACCEPT scr *> cursor is on field with INITIAL clause STOP RUN.
Special Data Items
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: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, 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 >>DEFINE CDF directive (see >>DEFINE) constants, >>SET CDF directive (see >>SET) constants, 78-level constants (see 78-Level Data Items and arithmetic-expression-1).
The reserved words
AS,ISandOFare optional and may be omitted. The presence or absence of these words has no effect upon the program.See GLOBAL, for information on the
GLOBALoption.This particular type of constant declaration provides the ability to determine the length of a data item or the storage size associated with a particular numeric
USAGE(see USAGE) type — something not possible with the other types of constants.Constants defined in this way become undefined once an
END PROGRAMorEND FUNCTIONis 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 numeric literal (see
BYTE-LENGTHorLENGTHoptions) 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
USAGEthat does not use aPICTURE(see PICTURE) clause. These would be any ofBINARY-C-LONG,BINARY-CHAR,BINARY-DOUBLE,BINARY-LONG,BINARY-SHORT,COMP-1(orCOMPUTATIONAL-1),COMP-2(orCOMPUTATIONAL-2),FLOAT-DECIMAL-16,FLOAT-DECIMAL-34,FLOAT-LONG,FLOAT-SHORT,POINTER, orPROGRAM-POINTER.The
BYTE-LENGTHclause will produce a numeric value for <constant-name-1> identical to that which would be returned by theBYTE-LENGTHintrinsic function executed against <identifier-1> or a data item declared with aUSAGEof <usage-name>.The
LENGTHclause will produce a numeric value for <constant-name-1> identical to that which would be returned by theLENGTHintrinsic function executed against <identifier-1> or a data item declared with aUSAGEof <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.
>>SOURCE FREE
IDENTIFICATION DIVISION.
PROGRAM-ID. TESTCONST.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 A CONSTANT 2.
01 B CONSTANT ( (3 + 4 / 2) * A). *> value = 10
01 CON CONSTANT (A ** B). *> value = 1024
01 MYDATA PIC X(CON).
PROCEDURE DIVISION.
DISPLAY A ' ' B ' ' CON
move all "1234567890" to MYDATA
move ">" to MYDATA(1:1)
move "<" to MYDATA(CON:1)
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.
66-Level Data Items
66-Level-Data-Item Syntax
=======================================================================
66 identifier-1 RENAMES identifier-2 [ THRU|THROUGH identifier-3 ] .
~~~~~~~ ~~~~ ~~~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE
A 66-level data item regroups previously defined items by specifying alternative, possibly overlapping, groupings of elementary data items.
The reserved words
THRUandTHROUGHare 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
RENAMESentries associated with one logical record must immediately follow that record’s last data description entry.
77-Level Data Items
77-Level-Data-Item Syntax
=======================================================================
77 identifier-1|FILLER [ IS GLOBAL|EXTERNAL ]
~~~~~~ ~~~~~~ ~~~~~~~~
[ BASED ]
~~~~~
[ BLANK WHEN ZERO|ZEROES|ZEROS ]
~~~~~ ~~~~ ~~~~~~ ~~~~~
[ JUSTIFIED RIGHT ]
~~~~
[ OCCURS integer-1 [ TO integer-2 ] TIMES [ DEPENDING ON identifier-2 ] ]
[ ~~~~~~ ~~ ~~~~~~~~~ ]
[ [ { ASCENDING|DESCENDING KEY IS { identifier-3 }...}...] ]
[ ~~~~~~~~~ ~~~~~~~~~~ ]
[ [ INDEXED BY { identifier-4 }...] ]
~~~~~~~
[ PICTURE IS picture-string ]
~~~
[ REDEFINES identifier-5 ]
~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
~~~~ ~~~~ ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
~~~~~
[ IS TYPEDEF ]
~~~~~~~
[ TYPE TO type-name-1 ]
~~~~
[ SAME AS identifier-6 ]
~~~~
[ IS SPECIAL-NAMES { special-names-item }...]
~~~~~~~~~~~~~
[ VALUE IS [ ALL ] literal-1 ] .
~~~~~ ~~~
The LEFT and RIGHT (SYNCHRONIZED) clauses are syntactically recognized but are otherwise non-functional.
=======================================================================
This syntax is valid in the following sections: WORKING-STORAGE, LOCAL-STORAGE, LINKAGE
The intent of a 77-level item is to be able to create a stand-alone elementary data item.
The reserved words
CHARACTER,IS,RIGHT(JUSTIFIED) andWHENare optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved word
JUSTIFIEDmay be abbreviated asJUST, the reserved wordPICTUREmay be abbreviated asPICand the reserved wordsSYNCHRONIZEDandSYNCHRONISEDmay be abbreviated asSYNC.New programs requiring a stand-alone elementary item should be coded to use a level number of 01 rather than 77.
See Data Description Clauses, for information on the usage of the various data description clauses.
78-Level Data Items
78-Level-Constant Syntax
=======================================================================
78 constant-name-1 [ IS GLOBAL ] VALUE IS
~~~~~~ ~~~~~
{ literal-1 [ { +|-|*|/|** } { literal-3 } ] }
{ identifier-1 [ { AND } { identifier-3 } ] }
{ arithmetic-expression-1 [ { ~~~ } { arithmetic-expression-2 } ] }
{ LENGTH OF { literal-2 } [ { OR } { LENGTH OF { literal-4 } } ] }
{ ~~~~~~ { identifier-2 } [ ~~ { ~~~~~~ { identifier-4 } } ] }
{ }
{ START OF identifier-5 }
{ ~~~~~ }
{ NEXT }
~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, SCREEN
The 78-level constant is one of four types of compilation-time constants that can be declared within a program. The other three types are >>DEFINE CDF directive (see >>DEFINE) constants, >>SET CDF directive (see >>SET) constants and 01-level constants (see 01-Level Constants).
The reserved word
ISis 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
END PROGRAMorEND FUNCTIONis 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.
NEXT gives the integer value representing the offset at which the next byte of storage that follows the previous data declaration.
Following a couple of sample programs: ID DIVISION. PROGRAM-ID. TEST78. DATA DIVISION. WORKING-STORAGE SECTION. 78 AAA VALUE (100 -1) + 100. 01 K PIC X(19). 01 A EXTERNAL PIC X(05) VALUE SPACE. 01 R EXTERNAL PIC X(08) VALUE SPACE. 78 BBB VALUE LENGTH OF A. 78 CCC VALUE LENGTH OF '1234'. 78 DDD VALUE LENGTH OF '1234567890' / LENGTH OF A. 78 EEE VALUE LENGTH OF '123' * 3. 78 FFF VALUE START OF R. 01 B EXTERNAL. 05 C PIC X(26) VALUE 'A'. 05 D PIC X(21) VALUE 'A'. 78 GGG VALUE NEXT. 78 HHH VALUE START OF A. 05 M PIC X(23) VALUE 'B'. PROCEDURE DIVISION. DISPLAY 'AAA= ' AAA DISPLAY 'BBB= ' BBB DISPLAY 'CCC= ' CCC DISPLAY 'DDD= ' DDD DISPLAY 'EEE= ' EEE DISPLAY 'FFF= ' FFF DISPLAY 'GGG= ' GGG DISPLAY 'HHH= ' HHH STOP RUN. >>SOURCE FREE IDENTIFICATION DIVISION. PROGRAM-ID. TESTCONST1. DATA DIVISION. WORKING-STORAGE SECTION. 78 wCONST VALUE 2 * (23 + 3) + (10 / 2) . 01 wCONST2 constant (23 + 3**32) . 01 wCONST3 constant (12 + wCONST2)**22 - wCONST. 78 wCONST4 value (wCONST + 1 AND wCONST3) OR 123 321 AND wCONST**2. 01 wCONST5 constant (wCONST4 OR wCONST2) AND 123 -321.23 AND wCONST4. 01 wCONST6 constant B'0001' AND B'1000'. 01 wVAR02 PIC 9(30)V99 value zero. 01 wVAR03 PIC 9(30)V99 value zero. 01 wVAR04 PIC 9(30)V99 value zero. 01 wVAR09 PIC 999 value wCONST4. PROCEDURE DIVISION. MAIN-PROCEDURE. DISPLAY "wCONST .........: " wCONST COMPUTE wVAR02 = (23 + 3**32) DISPLAY "wVAR02 .........: " wVAR02 DISPLAY "wCONST2 ........: " wCONST2 COMPUTE wVAR03 = (12 + wCONST2)**22 - wCONST DISPLAY "wVAR03 .........: " wVAR03 DISPLAY "wCONST3 ........: " wCONST3 DISPLAY "wCONST4 ........: " wCONST4 DISPLAY "wCONST5 ........: " wCONST5 DISPLAY "wVAR09 .........: " wVAR09 DISPLAY "wCONST6 ........: " wCONST6 accept omitted STOP RUN.
88-Level Data Items
88-Level-Data-Item Syntax
=======================================================================
88 condition-name-1 { VALUE IS } {literal-1 [ THRU|THROUGH literal-2 ]}...
{ ~~~~~ } ~~~~ ~~~~~~~
{ VALUES ARE }
~~~~~~
[ WHEN SET TO FALSE IS literal-3 ] .
~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN
Condition names are Boolean (i.e. TRUE / FALSE) data items that receive their TRUE and FALSE values based upon the values of the non 88-level data item whose definition they immediately follow.
The reserved words
ARE,IS,SETandTOare optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved words
THRUandTHROUGHare 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
VALUE(see VALUE) clause, <condition-name-1> will take on the value ofTRUE.Condition names do not occupy any storage.
The optional
THROUGHclause allows a range of possibleTRUEvalues to be specified.Whenever the parent data item assumes any value except one of the values specified on <condition-name-1>’s
VALUEclause, <condition-name-1> will take on the value of FALSE.Executing the statement
SET condition-name-1 TO TRUEwill cause <condition-name-1>’s parent data item to take on the first value specified on <condition-name-1>’sVALUEclause.Executing the statement
SET condition-name-1 TO FALSEwill cause <condition-name-1>’s parent data item to take on the value specified on <condition-name-1>’sFALSEclause. If <condition-name-1> does not have aFALSEclause, theSET(see SET) statement will generate an error message at compilation time.See Condition Names, for more information.
Data Description Clauses
Following table lists all the CLAUSES permitted in which SECTIONS of DATA DIVISION.
+----------------------------------+-------------------------------------------------+
| DATA | FILE WORKING LOCAL LINKAGE REPORT SCREEN |
| DESCRIPTION | SECTION STORAGE STORAGE SECTION SECTION SECTION |
| CLAUSES | SECTION SECTION |
+----------------------------------+-------------------------------------------------+
| 01. ANY LENGTH|NUMERIC | X |
| 02. AUTO|AUTO-SKIP|AUTOTERMINATE | X |
| 03. BACKGROUND-COLOR | X |
| 04. BASED | X X X |
| 05. BELL|BEEP | X |
| 06. BLANK | X |
| 07. BLANK WHEN ZERO | X X X X X X |
| 08. BLINK | X |
| 09. COLUMN|POSITION | X X |
| 10. CONSTANT | X X X X X |
| 11. ERASE | X |
| 12. EXTERNAL | X X X |
| 13. FALSE | X X X X X X |
| 14. FOREGROUND-COLOR | X |
| 15. FROM | X |
| 16. FULL|LENGTH-CHECK | X |
| 17. GLOBAL | X X X X |
| 18. GROUP INDICATE | X |
| 19. HIGHLIGHT | X |
| 20. INITIAL | X |
| 21. JUSTIFIED | X X X X X X |
| 22. LEFTLINE | X |
| 23. LINE | X X |
| 24. LOWLIGHT | X |
| 25. NEXT GROUP | X |
| 26. OCCURS | X X X X X X |
| 27. OVERLINE | X |
| 28. PICTURE | X X X X X X |
| 29. PRESENT WHEN | X |
| 30. PROMPT | X |
| 31. REDEFINES | X X X X |
| 32. RENAMES | X X X X |
| 33. REQUIRED|EMPTY-CHECK | X |
| 34. REVERSE-VIDEO | X |
| 35. SAME AS | X |
| 36. SECURE|NO-ECHO|NO ECHO|OFF | X |
| 37. SIGN | X X X X X X |
| 38. SOURCE | X |
| 39. SPECIAL-NAMES | X X |
| 40. SUM | X |
| 41. SYNCHRONIZED | X X X X |
| 42. TO | X |
| 43. TYPE | X X X X X X |
| 44. TYPEDEF | X X X X |
| 45. UNDERLINE | X |
| 45. USAGE | X X X X X |
| 46. USING | X |
| 47. VALUE | X X X X X X |
+----------------------------------+-------------------------------------------------+
ANY LENGTH
ANY LENGTH Attribute Syntax
=======================================================================
ANY LENGTH|NUMERIC
~~~ ~~~~~~ ~~~~~~~
=======================================================================
This syntax is valid in the following sections: LINKAGE
Data items declared with the ANY LENGTH or ANY NUMERIC 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.
ANY LENGTH items must have a PICTURE (see PICTURE) clause that specifies exactly one A, X, U or 1 symbol.
ANY NUMERIC items must have a PICTURE (see PICTURE) clause that specifies exactly one 9 symbol. ANY NUMERIC handles integers or fixed-point but no floating-point.
The
ANY LENGTHclause is COBOL ISO Standard, theANY NUMERICclause is a GnuCOBOL extension.The
ANY LENGTHorANY NUMERICandBASED(see BASED) clauses cannot be used together in the same data item description. TheANY LENGTHorANY NUMERICclause 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.
identification division.
program-id. prog1.
data division. working-storage section.
01 myitems.
03 myitem1 pic x(10).
03 myitem2 pic 9.
procedure division.
a-main1 section.
move 'hello' to myitem1 move 8 to myitem2
display 'a-main1 prog1'
display 'a-main1 myitem1 ' myitem1 display 'a-main1 myitem2 ' myitem2
call 'prog2' using "testlit"
display 'bye' accept myitem1.
goback. end program prog1.
identification division.
program-id. prog2.
data division. working-storage section.
01 myitems.
03 myitem1 pic x(10).
03 myitem2 pic 9.
linkage section.
01 testvar pic x ANY LENGTH.
procedure division using testvar.
a-main1 section.
move 'goodbye' to myitem1 move 4 to myitem2
display 'a-main1 prog2'
display 'a-main1 myitem1 ' myitem1 display 'a-main1 myitem2 ' myitem2
display '>' testvar '<' display 'goback to prog1'
goback. end program prog2.
AUTO
AUTO Attribute Syntax
=======================================================================
AUTO|AUTO-SKIP|AUTOTERMINATE
~~~~ ~~~~~~~~~ ~~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
A field whose description includes this attribute will cause the cursor to automatically advance to the next input-enabled field of a screen if the field is completely filled with input data.
The
AUTO,AUTO-SKIPandAUTOTERMINATEclauses are interchangeable, and may not be used together in the same data item description.The
AUTOclause is COBOL ISO Standard, theAUTO-SKIPandAUTOTERMINATEclauses are extensions.
BACKGROUND-COLOR
BACKGROUND-COLOR Attribute Syntax
=======================================================================
BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1 | identifier-1
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause is used to specify the screen background color of the screen data item or the default screen background color of subordinate items if used on a group item.
The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program.The reserved words
BACKGROUND-COLORandBACKGROUND-COLOURare interchangeable.You specify colors by number (0-7 and 8-15), or by using the constant names provided in the
screenio.cpycopybook (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 and 8-15.
For composite 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
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
BASED
BASED Attribute Syntax
=======================================================================
BASED
~~~~~
=======================================================================
This syntax is valid in the following sections: WORKING-STORAGE, LOCAL-STORAGE, LINKAGE
Data items declared with BASED are allocated no storage at compilation time. At run-time, the ALLOCATE (see ALLOCATE) or SET ADDRESS (see SET ADDRESS) statements are used to allocate space for and (optionally) initialize such items.
The
BASEDandANY LENGTH(see ANY LENGTH) clauses cannot be used together in the same data item description.The
BASEDclause may only be used on level 01 and level 77 data items.
BELL
BELL Attribute Syntax
=======================================================================
BELL|BEEP
~~~~ ~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
Use this clause to cause an audible tone to occur when the screen item is
DISPLAYed.The
BELLandBEEPclauses are interchangeable, and may not be used together in the same data item description.The
BELLclause is COBOL ISO Standard, theBEEPclause is an extension.See also following built-in system subroutines
CBL_ALARM_SOUND,CBL_BELL_SOUNDandX"E5".
BLANK
BLANK Attribute Syntax
=======================================================================
BLANK LINE|SCREEN
~~~~~ ~~~~ ~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause will blank out either the entire screen (BLANK SCREEN) or just the line upon which data is about to be displayed (BLANK LINE).
Blanked-out areas will have their foreground and background colors set to the attributes of the field containing the
BLANKclause.This clause is useful when one screen section item is being displayed over the top of a previously-displayed one.
BLANK WHEN ZERO
BLANK-WHEN-ZERO Attribute Syntax
=======================================================================
BLANK WHEN { ZERO | ZEROS | ZEROES }
~~~~~ ~~~~ ~~~~~~ ~~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN
This clause will cause that item’s value to be automatically transformed into spaces if a value of 0 is ever MOVEd to the item.
The reserved word
WHENis 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
PIC 9data item with aUSAGE(see USAGE) ofDISPLAY.
BLINK
BLINK Attribute Syntax
=======================================================================
BLINK
~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
The BLINK clause modifies the visual appearance of the displayed field by making the field contents blink.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
COLUMN
COLUMN (REPORT SECTION) Clause Syntax
=======================================================================
{ COLUMN } [ NUMBER ] [ LEFT ] [ IS ] { [ + | PLUS ] integer-1 }
{ ~~~~~~ } [ NUMBERS ] [ ~~~~ ] [ ARE ] { ~~~~ }
{ COL } [ RIGTH ] { {integer-2 }... }
{ ~~~ } [ ~~~~~ ]
{ COLUMNS } [ CENTER ]
{ ~~~~~~~ } ~~~~~~
{ COLS }
~~~~
=======================================================================
COLUMN (SCREEN SECTION) Clause Syntax
=======================================================================
COLUMN | POSITION NUMBER IS [ { + | PLUS } ] integer-2 | identifier-3
~~~ ~~~~~~~~ [ { ~~~~ } ]
[ { - | MINUS } ]
~~~~~
=======================================================================
This syntax is valid in the following sections: REPORT, SCREEN
The COLUMN clause provides the means of stating in which column a field should be presented on the console window (screen section) or a report (report section).
The reserved words
ARE,IS,NUMBERandNUMBERSare optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved word
COLUMNmay be abbreviated asCOL.The line location of a report section or screen section field will be determined by the
LINE(see 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
USAGE(see USAGE) other thanCOMPUTATIONAL-1orCOMPUTATIONAL-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 aCOMPUTATIONAL-1orCOMPUTATIONAL-2identifier 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.
COLUMN 5) or on a relative basis based upon the end of the previously-presented field (i.e.COLUMN PLUS 1).The symbol ‘
+’ may be used in lieu of the wordPLUS, if desired; if symbol ‘+’ is used, however, there must be at least one space separating it from <integer-1>. Failure to include this space will cause the symbol ‘+’ sign to be simply treated as part of <integer-1> and will treat theCOLUMNclause as an absolute column specification rather than a relative one.Using relative column positioning (
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,
COLUMN PLUSwill 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
SOURCE(see SOURCE),SUM(see SUM) orVALUE(see VALUE) clause but has noCOLUMNclause,COLUMN PLUS 1will be assumed.When used on a screen section data item,
COLUMN PLUSwill position the new field so that it begins exactly <integer-1> or <identifier-1> characters past the last character of the previous field. Thus,COLUMN PLUS 1will leave no blank positions between the end of the previous field and the start of this one.If a screen data item’s description includes the
FROM(see FROM),TO(see TO),USING(see USING) orVALUE(see VALUE) clause but has noCOLUMNclause, the new screen field will begin at the column coordinate of the last character of the previous field.
CONSTANT
CONSTANT Attribute Syntax
=======================================================================
CONSTANT
~~~~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, SCREEN
This option signifies that the 01-level data item in whose declaration CONSTANT is specified will be treated as a symbolic name for a literal value, 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.
See 01-Level Constants, for additional information.
ERASE
ERASE Clause Syntax
=======================================================================
ERASE { EOL|EOS }
~~~~~ { ~~~ ~~~ }
{ [TO END OF ] {LINE | SCREEN } }
~~~ ~~~~ ~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
ERASE will blank-out screen contents from the location where the screen data item whose description contains this clause will be displayed, forward until the end of the screen (ERASE EOS)
Erased areas will have their foreground and background colors set to the attributes of the field containing the
ERASEclause.This clause is useful when one screen section item is being displayed over the top of a previously-displayed one.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
EXTERNAL
EXTERNAL Attribute Syntax
=======================================================================
IS EXTERNAL
~~~~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE
This clause marks a data item description, FD or SD see File/Sort-Description as being shareable with other programs executed from the same execution thread.
By specifying the
EXTERNALclause on either anFDor anSD, the file description is capable of being shared between all programs executed from the same execution thread, provided anEXTERNALclause 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
EXTERNALclause 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 anEXTERNALclause) in each program requiring it.The following points apply to the specification of
EXTERNALin a data item’s definition:
FALSE
FALSE Clause Syntax
=======================================================================
WHEN SET TO FALSE IS literal-1
~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN
This clause, which may only appear on the definition of a level-88 condition name, is used to specify the value of the data item that serves as the parent of the level-88 condition name that will force the condition name to assume a value of FALSE.
The reserved words
IS,SET,TOandWHENare optional and may be omitted. The presence or absence of these words has no effect upon the program.See 88-Level Data Items, or See Condition Names, for more information.
FOREGROUND-COLOR
FOREGROUND-COLOR Attribute Syntax
=======================================================================
FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-1 | identifier-1
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause is used to specify the color of text within a screen data item or the default text color of subordinate items if used on a group item.
The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program.The reserved words
FOREGROUND-COLORandFOREGROUND-COLOURare interchangeable.You specify colors by number (0-7 and 8-15), or by using the constant names provided in the
screenio.cpycopybook (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 and 8-15.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
FROM
FROM Clause Syntax
=======================================================================
FROM literal-1|identifier-1
~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause is used to specify either the data item a screen section field is to obtain its value from when the screen is displayed, or a literal that will specify the value of that same field.
FULL
FULL Attribute Syntax
=======================================================================
FULL|LENGTH-CHECK
~~~~ ~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
The FULL clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if specified on a group item) sufficient to fill every character position of the field.
The
FULLandLENGTH-CHECKclauses are interchangeable, and may not be used together in the same data item description.The
FULLclause is COBOL ISO Standard, theLENGTH-CHECKclause is an extension.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
ACCEPT data-itemstatement (see ACCEPT data-item) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item unless the proper amount of data has been entered into the field. Function keys will still be allowed to terminate theACCEPT, 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
FULLandLENGTH-CHECK.
GLOBAL
GLOBAL Attribute Syntax
=======================================================================
IS GLOBAL
~~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, REPORT
This clause marks a data item, 01-level constant, FD (see File/Sort-Description), SD (see File/Sort-Description) or an RD (see REPORT SECTION) as being shareable with any nested subprograms.
By specifying the
GLOBALclause 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 theFD,SDorRDis coded (with aGLOBALclause) 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 aGLOBALfile description, but they may share anEXTERNAL(see EXTERNAL) file description. This sharing applies to the record descriptions subordinate to the file description and the report groups subordinate to theRDalso.By specifying the
GLOBALclause 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 aGLOBALclause) in each program requiring it.The following points apply to the specification of
GLOBALin a data item’s definition:
GROUP INDICATE
GROUP-INDICATE Attribute Syntax
=======================================================================
GROUP INDICATE
~~~~~ ~~~~~~~~
=======================================================================
This syntax is valid in the following sections: REPORT
The GROUP INDICATE clause specifies that the data item in whose definition the clause appears will be presented only in very limited circumstances.
This clause may only appear within a
DETAILreport group (see 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
INITIATE(see 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.
HIGHLIGHT
HIGHLIGHT Attribute Syntax
=======================================================================
HIGHLIGHT
~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause controls the intensity of text (FOREGROUND-COLOR (see FOREGROUND-COLOR)) by setting that intensity to its highest of three possible settings.
- This clause, along with
LOWLIGHT(see LOWLIGHT), are intended to provide a three-level intensity scheme (LOWLIGHT… nothing (Normal) …HIGHLIGHT).
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
INITIAL
INITIAL Attribute Syntax
=======================================================================
INITIAL [ literal-1 ]
~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause can only be used on screen fields that accept user input (those that have the USING clause or the TO clause). It forces the runtime to re-initialize that specific screen field to its defined VALUE (or empty if no value is set) every time the DISPLAY statement is executed. This ensures that the screen field does not retain data from a previous ACCEPT operation, which is critical when reusing forms or displaying the same screen section multiple times within a program.
The
INITIALclause guarantees that a field displays its initial value, not the last accepted value, wheneverDISPLAYis executed.When
DISPLAYacts on an item with theINITIALclause, GnuCOBOL ignores any data currently in the associated WORKING-STORAGE SECTION data item and uses theVALUEclause defined within the SCREEN SECTION definition. TheINITIALclause is typically used in conjunction with theVALUEclause in the SCREEN SECTION (which defines the default, literal value)When a screen item with the
INITIALphrase is displayed, GnuCOBOL ignores any data currently in the associated data item and uses theVALUEclause from the SCREEN SECTION definition.This clause is essential for applications that toggle between different input forms, ensuring that a user sees a "clean" form every time a specific
DISPLAYstatement is executed.
>>SOURCE FREE
IDENTIFICATION DIVISION.
PROGRAM-ID. TESTSCREENINITIAL.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CUSTOMER-NAME1 PIC X(10) value 'CUSTO1'.
01 CUSTOMER-NAME2 PIC X(10) value 'CUST02'.
01 CUSTOMER-NAME3 PIC X(10) value 'CUST03'.
01 CUSTOMER-NAME4 PIC X(10) value 'CUST04'.
SCREEN SECTION.
01 CUSTOMER-SCREEN AUTO.
03 wLABEL PIC X(30) LINE 2 COL 1 "first ACCEPT".
03 LINE 4 COL 1 VALUE "Name1.....: ".
03 ENTRY-NAME1 PIC X(10), LINE 4 COL 20 USING CUSTOMER-NAME1 INITIAL.
03 LINE 6 COL 1 VALUE "Name2.....: ".
03 ENTRY-NAME2 PIC X(10), LINE 6 COL 20 USING CUSTOMER-NAME2 INITIAL 'ENTRY02'.
03 LINE 8 COL 1 VALUE "Name3.....: ".
03 ENTRY-NAME3 PIC X(10), LINE 8 COL 20 USING CUSTOMER-NAME3 INITIAL VALUE 'ENTRY03'.
03 LINE 10 COL 1 VALUE "Name3.....: ".
03 ENTRY-NAME4 PIC X(10), LINE 10 COL 20 USING CUSTOMER-NAME4 INITIAL.
PROCEDURE DIVISION.
ACCEPT CUSTOMER-SCREEN
STOP RUN.
JUSTIFIED
JUSTIFIED Attribute Syntax
=======================================================================
JUSTIFIED RIGHT
~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN
The presence of a JUSTIFIED RIGHT clause in a data item’s definition alters the manner in which data is stored into the field from the default ‘left-justified, space filled’ 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
RIGHTis optional and may be omitted. The presence or absence of this word has no effect upon the program.The reserved word
JUSTIFIEDmay be abbreviated asJUST.This clause is valid only on alphabetic (
PIC A) or alphanumeric (PIC X) data items.The presence or absence of this clause influences the behaviour of the
MOVE(see MOVE) statement as well as theFROM(see FROM),SOURCE(see SOURCE) andUSING(see 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
JUSTIFIED RIGHTclause on that field’s description is irrelevant.The following examples illustrate the behaviour of the presence and absence of the
JUSTIFIED RIGHTclause when the field size is different than that of the value being stored. In these examples, the symbol b represents a space.
LEFTLINE
LEFTLINE Attribute Syntax
=======================================================================
LEFTLINE
~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
The LEFTLINE clause will introduce a vertical line at the left edge of a screen field.
The
LEFTLINE,OVERLINE(see OVERLINE) andUNDERLINE(see 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.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
LINE
LINE (REPORT SECTION) Clause Syntax
=======================================================================
{ LINE [ NUMBER ] [ IS ] } { integer-1 [ [ ON NEXT PAGE ] }
{ ~~~~ [ NUMBERS ] [ ARE ] } { ~~~~ ~~~~ }
{ LINES ARE } { +|PLUS integer-2 }...
~~~~~ { ~~~~ }
{ ON NEXT PAGE }
~~~~ ~~~~
=======================================================================
LINE (SCREEN SECTION) Clause Syntax
=======================================================================
LINE NUMBER IS [ { +|PLUS } ] integer-1 | identifier-1
~~~~ [ { ~~~~ } ]
[ { -|MINUS } ]
~~~~~
=======================================================================
This syntax is valid in the following sections: REPORT, SCREEN
This clause provides a means of explicitly stating on which line a field should be presented on the console window (screen section) or on a report (report section).
The reserved words
IS,NUMBERandONare 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
LINEclause:The column location of a report item will be determined by the
COLUMN(see 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.
LINE 5) or on a relative basis based upon the previously-displayed line (i.e.LINE PLUS 1).The symbol ‘
+’ may be used in lieu of the wordPLUS, if desired; if ‘+’ is used, however, there must be at least one space separating it from <integer-1>. Failure to include this space will cause the ‘+’ 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.The optional
NEXT PAGEclause 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
LINEclause:The column location of a screen section field is determined by the
COLUMN(see 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
USAGE(see USAGE) other thanCOMPUTATIONAL-1orCOMPUTATIONAL-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 aCOMPUTATIONAL-1orCOMPUTATIONAL-2identifier 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.
LINE 5) or on a relative basis based upon the previously-displayed line (i.e.LINE PLUS 1).The symbol ‘
+’ may be used in lieu of the wordPLUS, if desired; if ‘+’ is used, however, there must be at least one space separating it from <integer-1>. Failure to include this space will cause the ‘+’ to be simply treated as part of <integer-1> and will treat theLINEclause as an absolute line specification rather than a relative one.If a screen data item’s description includes the
FROM(see FROM),TO(see TO),USING(see USING) orVALUE(see VALUE) clause but has no LINE clause, the “current screen line” will be assumed.
LOWLIGHT
LOWLIGHT Attribute Syntax
=======================================================================
LOWLIGHT
~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
The LOWLIGHT clause controls the intensity of text (FOREGROUND-COLOR) by setting that intensity to its lowest of three possible settings.
- This clause, along with
HIGHLIGHT(see HIGHLIGHT), are intended to provide a three-level intensity scheme (LOWLIGHT… nothing (Normal) …HIGHLIGHT). In environments such as a Windows console where only two levels of intensity are supported,LOWLIGHTis the same as leaving this clause off altogether.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
NEXT GROUP
NEXT-GROUP Clause Syntax
=======================================================================
NEXT GROUP IS { [ + | PLUS ] integer-1 }
~~~~ ~~~~~ { ~~~~ }
{ NEXT | NEXT PAGE | PAGE }
~~~~ ~~~~ ~~~~ ~~~~
=======================================================================
This syntax is valid in the following sections: REPORT
This clause defines any rules for where the next group to be presented on a report will begin, line-wise, with respect to the last line of the group in which this clause appears.
The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program.The terms
NEXT,NEXT PAGEandPAGEare interchangeable.A report group must contain at least one
LINE NUMBERclause in order to also contain aNEXT GROUPclause.If the
RD(see REPORT SECTION) in which the report group containing aNEXT GROUPclause does not contain aPAGE LIMITSclause, only thePLUS integer-1option may be specified.The
NEXT PAGEoption cannot be used in aPAGE FOOTING.The
NEXT GROUPoption cannot be specified in either aREPORT HEADINGor aPAGE HEADING.The effects of
NEXT GROUPwill be in addition to any line spacing defined by the next-presented group’sLINE NUMBERclause.
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: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN but UNBOUNDED is ONLY for LINKAGE.
The OCCURS clause is used to create a data structure called a table, where entries in that structure repeat multiple times.
The reserved words
BY(INDEXED),IS,KEY,ONandTIMESare optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved word
UNBOUNDEDcan be used to specify an unbounded table (a table with an unbounded maximum number of occurrences), and can be referenced anywhere that a table can be referenced.An unbounded group is a group that contains at least one unbounded table. It can be specified ONLY in the Linkage Section, and must be of type alphanumeric or national.
You can reference unbounded groups in COBOL syntax anywhere that an alphanumeric or national group can be referenced, with the following exceptions:
You cannot specify unbounded groups as a BY CONTENT argument in a CALL statement. You cannot specify unbounded groups as data-name-2 on the Procedure Division RETURNING phrase. You cannot specify unbounded groups as arguments to intrinsic functions, except as an argument to the LENGTH intrinsic function.
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
OCCURSclause 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)The optional
DEPENDING ONclause can be added to anOCCURSto 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.See the documentation of the
SEARCH(see SEARCH) (Serial and Binary) andSORT(see SORT) statements for explanations of theKEYandINDEXED BYclauses.The COBOL standard says that the
OCCURSclause 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. GnuCOBOL supports, as a extension available in several compilers, theOCCURSclause at levels 01 and 77. Depending on -std, this may be downgraded to a warning or be without a diagnostic. Example, -std=ibm-strict and -std=cobol2002.Format 4 OCCURS (SCREEN SECTION).
Have that as pending: the compiler supports that, but the runtime does not handle it yet.
The following points apply to an
OCCURSused in the report section:The optional
STEPclause defines an incrementation value that will be added to any absoluteLINE(see LINE) orCOLUMN(see COLUMN) number specifications that may be part of or subordinate to this data item’s definition.The optional
VARYINGclause defines an identifier that may be used as a subscript for the multiple occurrences of this or any subordinate data item should theSOURCE(see SOURCE) orSUM(see 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
OCCURScapabilities ofSTEPandVARYING. Both assume the definition of the following table exists in working-storage:05 SALES OCCURS 4 TIMES PIC 9(7)V99.First, the “Hard Way”:
10 COL 7 PIC $(7)9.99 SOURCE SALES(1). 10 COL 17 PIC $(7)9.99 SOURCE SALES(2). 10 COL 27 PIC $(7)9.99 SOURCE SALES(3). 10 COL 37 PIC $(7)9.99 SOURCE SALES(4).And then using
STEPandVARYING:10 COL 7 OCCURS 4 TIMES STEP 10 VARYING QTR FROM 1 BY 1 PIC $(7)9.99 SOURCE SALES(QTR).
OVERLINE
OVERLINE Attribute Syntax
=======================================================================
OVERLINE
~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
The OVERLINE clause will introduce a horizontal line at the top edge of a screen field.
The
LEFTLINE(see LEFTLINE),OVERLINEandUNDERLINE(see 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.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
PICTURE
PICTURE Clause Syntax
=======================================================================
PICTURE IS picture-string [ LOCALE [ IS locale-name-1 ] SIZE IS integer-1 ]
~~~ ~~~~~~ ~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN
The picture clause defines the class (numeric, alphabetic or alphanumeric), size and format of the data that may be contained by the data item being defined. Sometimes this role is assisted by the USAGE (see USAGE) clause, and in a few instances will be assumed entirely by that clause.
The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program.A picture clause may only be specified on an elementary item.
A <picture-string> is a sequence of the special symbols ‘
$’, ‘*’, ‘+’, ‘,’, ‘-’, ‘.’, ‘/’, ‘0’ (zero), ‘1’, ‘9’, ‘A’, ‘B’,CR,DB, ‘N’, ‘U’, ‘S’, ‘V’, ‘P’, ‘X’ and ‘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 —
PIC 9999/99/99— for example, the repetition can be specified using a parenthetic repeat count, as inPIC 9(4)/9(2)/9(2). Other examples are:PIC Z(8)9same asPIC ZZZZZZZZ9,PIC +(8)9same asPIC ++++++++9. 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 asPIC XXXand repeat counts for larger ones asPIC 9(6).This first set of picture symbols defines the basic data type of a data item. Each symbol represents a single character’s worth of storage.
- ‘
A’ -
Defines storage reserved for a single alphabetic character (‘
A’-‘Z’, ‘a’-‘z’). - ‘
X’ -
Defines storage reserved for a single alphanumeric character (any character).
- ‘
9’ -
Defines storage reserved for a single numeric digit character (‘
0’-‘9’). - ‘
N’ -
Defines storage reserved for a single character in the computer’s National Character set. It is similar to alphanumeric, but using an extended character set, e.g. UTF-8. Support for national character sets in GnuCOBOL is currently only partially implemented, and the compile- and run-time effect of using the ‘
N’ picture symbol is the same as ifX(2)had been coded, with the additional effect that such a field will qualify as aNATIONALorNATIONAL-EDITEDfield on anINITIALIZE(see INITIALIZE) statement. - ‘
U’ -
PIC Ufrom the upcoming ISO COBOL 2027 standard is used for UTF-8 support, a single U may have more than one byte (for example Umlauts, Emoji, Kanji, ...). The two ways to define items:PIC U(n)= up to N UTF-8 characters (GnuCOBOL always reserves n*4 bytes) orPIC U BYTE-LENGTH m= exactly m bytes, up to m UTF-8 characters, but may contain less. While already usable for different things in GnuCOBOL, the support in the current version is limited/unfinished - the size is handled correctly and the data is handled on the byte-position only. There’s no explicit conversion between PIC U / X / N available (U and N are identical for most of ASCII 7 bit values, N is "compatible" in most of that range as well (with an additional low-value before/after the byte).
>>SOURCE FREE IDENTIFICATION DIVISION. PROGRAM-ID. TESTPICTUREU. DATA DIVISION. WORKING-STORAGE SECTION. 01 wU01 PIC U(06) VALUE ALl '*'. 01 wU02 PIC U(06) VALUE '12ABC'. PROCEDURE DIVISION. move '12' to wU01(1:2) move '34' to wU01(5:2) display '....+....1....+....2....+....3....+....4....+....5....+....6....+....7' display wU01 display function HEX-OF(wU01) display wU02 display function HEX-OF(wU02) accept omitted STOP RUN. OUTPUT: ....+....1....+....2....+....3....+....4....+....5....+....6....+....7 12**34****************** 31322A2A33342A2A2A2A2A2A2A2A2A2A2A2A2A2A2A2A2A2A 12ABC 313241424320202020202020202020202020202020202020Only one kind of each of those symbols is used in the same picture clause, but that isn’t a requirement. Data items that, of the three symbols above, use nothing but ‘
A’ picture symbols are known as Alphabetic Data Items while those that use ‘9’ picture symbols without any ‘A’ or ‘X’ symbols (or those that have aUSAGEwithout aPICTURE) 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>
AA99999AAA,A(2)9(5)A(3)XXXXXXXXXXorX(10). There is absolutely no functional difference whatsoever between the four — none of them provide any functionality the others do not. The first two probably make for better documentation of the expected field contents, but they don’t provide any run-time enforcement capabilities.As far as enforcement goes, however, both alphabetic and numeric picture strings do provide for both compile-time and run-time enforcement capabilities. In the case of compilation enforcement, the compiler can issue warning messages if you attempt to specify a non-numeric value for a numeric data item or if you attempt to
MOVE(see 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 (see Class Conditions) to determine if the contents of a data item are entirely numeric or entirely alphabetic.- ‘
‘
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. See also USAGE BIT in this document.Example of usage : WORKING-STORAGE SECTION. 01 wBIT PIC 1(4) value b'1111111111111'. PROCEDURE DIVISION. display wBIT ' ' function HEX-OF(wBIT) ' ' function BIT-OF(wBIT) move b'1001' to wBIT display wBIT ' ' function HEX-OF(wBIT) ' ' function BIT-OF(wBIT) the result will be: 8191 38313931 00111000001100010011100100110001 0009 30303039 00110000001100000011000000111001The following picture symbols may be used with numeric data items.
- ‘
P’ -
Defines an implied digit position that will be considered to be a zero when the data item is referenced at run-time. This symbol is used to allow data items that will contain very large values to be allocated using less storage by assuming a certain number of trailing zeros (one per ‘
P’) to exist at the end of values.The ‘
P’ symbol is not allowed in conjunction with ‘N’.The ‘
P’ symbol may only be used at the beginning or end of a picture clause.‘
P’ is a repeatable symbol.All computations and
MOVE(see MOVE) operations involving such a data item will behave as if the zeros were actually there.Let’s say you need to allocate a data item that contains however many millions of dollars of revenue your company has in gross revenues this year:
01 Gross-Revenue PIC 9(9).In which case 9 characters of storage will be reserved. The values 000000000 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:
01 Gross-Revenue PIC 9(3)P(6).Whenever Gross-Revenue is referenced in calculations, or whenever its value is moved to another data item, the value of Gross-Revenue will be treated as if it is
nnn000000, wherennnis the actual value in storage.If you wanted to store the value 128 million into that field, you would do so as if the ‘
P’s were’9’s:MOVE 128000000 TO Gross-RevenueA
DISPLAY(see DISPLAY) of a data item containing ‘P’ symbols is a little strange. The value displayed will be what is actually in storage, but the total size of the displayed value will be as if the ‘P’ symbols had been ‘9’s. Thus, after the above statement established a value for Gross-Revenue, aDISPLAY Gross-Revenuewould produce output of’128000000’. This is the actual three characters stored with six zeros appended. - ‘
S’ -
This symbol, if used, must be the very first symbol in the
PICTUREvalue. A ‘S’ indicates that the data item isSigned, meaning that negative values are possible for this data item. Without an ‘S’, any negative values stored into this data item via aMOVEor arithmetic statement will have the negative sign stripped from it (in effect becoming the absolute value).The ‘
S’ symbol is not allowed in conjunction with ‘N’.The ‘
S’ symbol may only occur once in a picture string. See SIGN, for further discussion of how negative values may be stored in a numeric data item. - ‘
V’ -
This symbol is used to define where an implied decimal-point (if any) is located in a numeric item. Just as there may only be a single decimal point in a number so may there be no more than one ‘
V’ in aPICTURE. Implied decimal points occupy no space in storage — they just specify how values are used. For example, if the value1234is in storage in a field defined asPIC 999V9, that value would be treated as 123.4 in any statements that referenced it.The ‘
V’ symbol is not allowed in conjunction with ‘N’.The ‘
V’ symbol may only occur once in a picture string.
- ‘
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.
- ‘
B’ -
The ‘
B’ editing symbol introduces a blank into the field value for each occurrence. Multiple ‘B’ symbols may be coded.The following example will format a ten digit number (presumably a telephone number) into a ‘
### ### ####’ layout:... 05 Phone-Number PIC 9(3)B9(3)B9(4). ... MOVE 5185551212 TO Phone-Number DISPLAY Phone-NumberThis code will display ‘
518 555 1212’. - ‘
0’ -
The ‘
0’ (zero) editing symbol introduces one “0” character into the field value for each occurrence in the picture string. Multiple ‘0’ symbols may be coded.Here’s an example:
... 05 Output-Item PIC 909090909. ... MOVE 12345 TO Output-Item DISPLAY Output-ItemThe above will display ‘
102030405’. - ‘
/’ -
The ‘
/’ editing symbol inserts one “/” character into the field value for each occurrence in the picture string. Multiple ‘/’ symbols may be coded.This editing symbol is most-frequently used to format dates, as follows:
... 05 Year-Month-Day PIC 9(4)/9(2)/9(2). ... MOVE 20140207 TO Year-Month-Day DISPLAY Year-Month-DayThis example displays ‘
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.
- ‘
.’ -
The ‘
.’ symbol inserts a decimal point into a numeric field value. When the contents of a numeric data item sending field are moved into a receiving data item whose picture clause contains the ‘.’ editing symbol, implied (‘V’) or actual decimal point in the sending data item or literal, respectively, will be aligned with the ‘.’ symbol in the receiving field. Digits are then transferred from the sending to the receiving field outward from the sending field’s ‘V’ or ‘.’, truncating sending digits if there aren’t enough positions in the receiving field. Any digit positions in the receiving field that don’t receive digits from the sending field, if any, will be set to 0. The ‘.’ symbol is not allowed in conjunction with ‘N’. An example will probably help:... 05 Source-Field PIC 9(2)V9 VALUE 7.2. 05 Dest-Field PIC 9(5).9(2). ... MOVE 1234567.89 TO Dest-Field DISPLAY Dest-Field MOVE 19 TO Dest-Field DISPLAY Dest-Field MOVE Source-Field TO Dest-Field DISPLAY Dest-FieldThe example will display three results — ‘
34567.89’, ‘00019.00’ and ‘00007.20’.Both data item definitions appear to have two decimal points in their picture clauses. They actually don’t, because the last character of every data item definition is always a period — the period that ends the definition.
- ‘
,’ -
The ‘
,’ symbol serves as a thousands separator. Many times, you’ll see large numbers formatted with these symbols — for example, 123,456,789. This can be accomplished easily by adding thousands separator symbols to a picture string. Thousands separator symbols that aren’t needed will be ignored, i.e., not used.The ‘
,’ symbol is not allowed in conjunction with ‘N’.Here’s an example:
... 05 My-Lottery-Winnings PIC 9(3),9(3),9(3). ... MOVE 12345 TO My-Lottery-Winnings DISPLAY My-Lottery-Winnings This produces 012,345The value ‘
12,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 is ignored.
If desired, you may reverse the roles of the ‘
.’ and ‘,’ editing symbols by specifyingDECIMAL POINT IS COMMAin theSPECIAL-NAMES(see SPECIAL-NAMES) paragraph.... 05 My-Lottery-Winnings PIC zzz,zzz,zz9. ... MOVE 12345 TO My-Lottery-Winnings DISPLAY My-Lottery-Winnings This produces 12,345 Notice that there is no leading zeros when using the picture Z.- ‘
The following are insertion symbols. They are used to insert an extra character (two in the case of
CRandDB) 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 ‘+’, ‘-’,CRorDBsymbols 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 ‘+’, ‘-’ 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.- ‘
+’ -
If the value of the numeric value moved into the field is positive (0 or greater), a ‘
+’ character will be inserted. If the value is negative (less than 0), a ‘-’ character is inserted. The ‘+’ symbol is not allowed in conjunction with ‘N’. - ‘
-’ -
If the value of the numeric value moved into the field is positive (0 or greater), a space will be inserted. If the value is negative (less than 0), a ‘
-’ character is inserted. The ‘-’ symbol is not allowed in conjunction with ‘N’. CR-
This symbol is coded as the two characters ‘
C’ and ‘R’. If the value of the numeric value moved into the field is positive (0 or greater), two spaces will be inserted. If the value is negative (less than 0), the charactersCR(credit) are inserted. TheCRsymbol is not allowed in conjunction with ‘N’. DB-
This symbol is coded as the two characters ‘
D’ and ‘B’. If the value of the numeric value moved into the field is positive (0 or greater), two spaces will be inserted. If the value is negative (less than 0), the charactersDB(debit) are inserted. TheDBsymbol is not allowed in conjunction with ‘N’. - ‘
$’ -
Regardless of the value moved into the field, this symbol will insert the currency symbol into the data item’s value in the position where it occurs in the <picture-string> (see SPECIAL-NAMES).
The ‘
$’ symbol is not allowed in conjunction with ‘N’.
- ‘
These editing symbols are known as floating replacement symbols. These symbols may occur in sequences before any ‘
9’ editing symbols in the <picture-string> of a numeric data item. Using these symbols transforms that numeric data item into a numeric edited data item, which can no longer be used in calculations or subscripts.Each of the following symbols behave like a ‘
9’, until such point as all digits in the numeric value are exhausted and leading zeros are about to be inserted. In effect, these editing symbols define what should happen to those leading zero.- ‘
$’ -
Of those currency symbols that correspond to character positions in which leading zeros reside, the right-most will have its ‘
0’ value replaced by the currency symbol in-effect for the program (see SPECIAL-NAMES). Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces.The ‘
$’ symbol is not allowed in conjunction with ‘N’.Any currency symbol coded to the right of a ‘
.’ will be treated exactly like a ‘9’. - ‘
*’ -
This symbol is referred to as a check protection symbol. All check-protection symbols that correspond to character positions in which leading zeros reside will have their ‘
0’ values replaced by ‘*’.The ‘
*’ symbol is not allowed in conjunction with ‘N’.Any check-suppression symbol coded to the right of a ‘
.’ will be treated exactly like a ‘9’. - ‘
+’ -
Of those ‘
+’ symbols that correspond to character positions in which leading zeros reside, the right-most will have its ‘0’ value replaced by a ‘+’ if the value in the data item is zero or greater or a ‘-’ otherwise. Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces. You cannot use both ‘+’ and ‘-’ in the same <picture-string>.The ‘
+’ symbol is not allowed in conjunction with ‘N’.Any ‘
+’ symbol coded to the right of a ‘.’ will be treated exactly like a ‘9’. - ‘
-’ -
Of those ‘
-’ symbols that correspond to character positions in which leading zeros reside, the right-most will have its ‘0’ value replaced by a space if the value in the data item is zero or greater or a ‘-’ otherwise. Any remaining leading zero values occupying positions described by this symbol will be replaced by spaces. You cannot use both ‘+’ and ‘-’ in the same <picture-string>.The ‘
-’ symbol is not allowed in conjunction with ‘N’.Any ‘
-’ symbol coded to the right of a ‘.’ will be treated exactly like a ‘9’. - ‘
Z’ -
All ‘
Z’ symbols that correspond to character positions in which leading zeros reside will have their ‘0’ values replaced by spaces.Any zero-suppression symbol coded to the right of a ‘
.’ will be treated exactly like a ‘9’.
‘
Z’ and ‘*’ should not be coded in the same <picture-string>‘
+’ and ‘-’ should not be coded in the same <picture-string>When multiple floating symbols are coded, even if there is only one of them used, only the last coded one will be considered floating. The leading floating symbols will be treated as fixed and will appear in the output in the position coded. For example, if a data item has a 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) +$bbbb1.00. This is consistent with many other COBOL implementations, where the result would also have been +$bbbb1.00.
- ‘
LOCALE and SIZE clause are checked but not implemented for GnuCOBOL 3.2
PRESENT WHEN
PRESENT-WHEN Clause Syntax
=======================================================================
PRESENT WHEN condition-name
~~~~~~~ ~~~~
=======================================================================
This syntax is valid in the following sections: REPORT
This clause names an existing Condition Name (see Condition Names) 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
GENERATEstatement (see GENERATE) causes a report group to be presented, the presentation of that group will be suppressed.If the condition-name has a value of
TRUE, the group will be presented.See Condition Names, for more information.
PROMPT
PROMPT Clause Syntax
=======================================================================
PROMPT [ CHARACTER IS literal-1 | identifier-1 ]
~~~~~~ ~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause defines the character that will be used as the fill-character for any input fields on the screen.
The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program.The default prompt character, should no
CHARACTERspecification be coded, or should thePROMPTclause be absent altogether, is an underscore (‘_’).Prompt characters will be automatically transformed into spaces upon input.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
REDEFINES
REDEFINES Clause Syntax
=======================================================================
REDEFINES identifier-1
~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE
The REDEFINES clause causes the data item in who’s definition the REDEFINES clause is specified (hereafter referred to as the redefines object) to occupy the same physical storage space as <identifier-1> (hereafter referred to as the redefines subject).
The following rules must all be followed in order to use
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
REDEFINESof 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
OCCURS(see 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 withOCCURSclauses.No
VALUE(see VALUE) clause may be defined on the object data item, and no data items subordinate to the object data item may haveVALUEclauses, with the exception of level-88 condition names.
RENAMES
RENAMES Clause Syntax
=======================================================================
RENAMES identifier-1 [ THRU|THROUGH identifier-2 ]
~~~~~~~ ~~~~ ~~~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE
The RENAMES clause regroups previously defined items by specifying alternative, possibly overlapping, groupings of elementary data items.
The reserved words
THRUandTHROUGHare interchangeable.You must use the level number 66 for data description entries that contain the
RENAMESclause.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.
See 66-Level Data Items, for additional information on the
RENAMESclause.
REQUIRED
REQUIRED Attribute Syntax
=======================================================================
REQUIRED|EMPTY-CHECK
~~~~~~~~ ~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if REQUIRED or EMPTY-CHECK is specified on a group item).
The
REQUIREDandEMPTY-CHECKclauses are interchangeable, and may not be used together in the same data item description.The
REQUIREDclause is COBOL ISO Standard, theEMPTY-CHECKclause is an extension.In order to take effect, the user must first move the cursor into the field having this clause in its definition.
The
ACCEPT data-itemstatement (see ACCEPT data-item) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item unless data has been entered into the field. Function keys will still be allowed to terminate theACCEPT.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
REQUIREDandEMPTY-CHECK.
REVERSE-VIDEO
REVERSE-VIDEO Attribute Syntax
=======================================================================
REVERSE-VIDEO|REVERSE|REVERSED
~~~~~~~~~~~~~ ~~~~~~~ ~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
The REVERSE-VIDEO attribute swaps the specified or implied FOREGROUND-COLOR (see FOREGROUND-COLOR) and BACKGROUND-COLOR (see BACKGROUND-COLOR) attributes for the field whose definition contains this clause (or all subordinate fields if used on a group item).
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
SAME AS
SAME-AS Clause Syntax
=======================================================================
SAME AS data-name-1
~~~~ ~~
=======================================================================
The syntax is valid in the following sections: WORKING-STORAGE
The 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.
SECURE
SECURE Attribute Syntax
=======================================================================
SECURE|NO-ECHO|NO ECHO|OFF
~~~~~~ ~~~~~~~ ~~~~~~~ ~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
The SECURE clause will cause all data entered into the field to appear on the screen as asterisks.
The NO-ECHO clause will cause all data entered into the field to appear on the screen as spaces.
The OFF clause is the same as the NO-ECHO clause and same of NO ECHO.
The
NO-ECHOandSECUREclauses are interchangeable if If the dialect configuration-fno-echo-means-secureis active.The
SECUREclause is COBOL ISO Standard, theNO-ECHOandNO ECHOandOFFclauses are extensions.The
NO-ECHOandSECUREclauses may not be used together in the same data item description.If
NO-ECHOorSECUREis present then thePROMPTclause is ignored.This clause may only be used on a field allowing data entry (a field containing either the
USING(see USING) orTO(see TO) clause).
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
SIGN
SIGN-IS Clause Syntax
=======================================================================
SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ]
~~~~ ~~~~~~~ ~~~~~~~~ ~~~~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN
This clause, allowable only for USAGE DISPLAY numeric data items, specifies how an ‘S’ symbol will be interpreted in a data item’s picture clause.
The reserved words
CHARACTERandISare optional and may be omitted. The presence or absence of these words has no effect upon the program.Without the
SEPARATE CHARACTERoption, the sign of the data item’s value will be encoded by transforming the last (seeTRAILING) or first (seeLEADING) 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
SEPARATE CHARACTERclause is used, then an actual ‘+’ or ‘-’ character will be inserted into the field’s value as the first (LEADING) or last (TRAILING) character. Note that having this character embedded within the data item’s storage does not prevent the data item from being used as a source field in arithmetic operations.When
SEPARATE CHARACTERis specified, the ‘S’ symbol in the data item’sPICTUREmust be counted when determining the data item’s size.Neither the presence of an encoded digit (see above) nor an actual ‘
+’ or ‘-’ character embedded within the data item’s storage prevents the data item from being used as a source field in arithmetic operations.
SOURCE
SOURCE Clause Syntax
=======================================================================
SOURCE IS { literal-1 } [ ROUNDED ]
~~~~~~ { identifier-1 } ~~~~~~~
=======================================================================
This syntax is valid in the following sections: REPORT
This clause logically attaches a report section data item to another data item defined elsewhere in the data division.
The reserved word
ISis 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.
The specified identifier may be defined anywhere in the data division, but if it is defined in the report section it may only be
PAGE-COUNTER,LINE-COUNTERor aSUM(see SUM) counter.The
PICTURE(see PICTURE) of the report data item must be such that it would be legal toMOVE(see MOVE) the specified literal or identifier to a data item with thatPICTURE.The
ROUNDEDoption 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 thePICTUREspecified for the field in whose definition theSOURCEclause appears (the “target field”). WithoutROUNDED, excess digits in the source value will simply be truncated to fit the target field. WithROUNDED, the source value will be arithmetically rounded to fit the target field. See ROUNDED, for information on theNEAREST-AWAY-FROM-ZEROrounding rule, which is the one that will apply.
SPECIAL-NAMES.
SPECIAL-NAMES Clause Syntax
=======================================================================
IS SPECIAL-NAMES { CURSOR }
~~~~~~~~~~~~~ { ~~~~~~ }
{ CRT STATUS }
{ ~~~~~~~~~~ }
{ SCREEN CONTROL }
{ ~~~~~~~~~~~~~~ }
{ EVENT STATUS }
~~~~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: DATA DIVISION
The SPECIAL-NAMES clause allows you to identify commonly used Special-Names items directly in the Data Division. Sample of use:
The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program. Next an example of usage.01 wCURPOS IS SPECIAL-NAMES CURSOR. 03 wCURSOR-ROW PIC 999. 03 wCURSOR-COL PIC 999. 01 wCRTSTAT IS SPECIAL-NAMES CRT STATUS PIC 9(5).
SUM
SUM-OF Clause Syntax
=======================================================================
SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ]
~~~ { literal-2 } { ~~~~~ ~~~~~ }
{ UPON identifier-9 }
~~~~
=======================================================================
This syntax is valid in the following sections: REPORT
The SUM clause establishes a summation counter whose value will be arithmetically calculated whenever the field is presented.
The reserved words
OFandONare optional and may be omitted. The presence or absence of these words has no effect upon the program.The
SUMclause may only appear in aCONTROL FOOTINGreport group.If the data item in which the
SUMclause appears has been assigned its own identifier name, and that name is notFILLER, 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
SUMclause appears or they must be defined in a report data item that exists at a lower level in this report’s control hierarchy. See Control Hierarchy, for additional information.The
PICTUREof the report data item in who’s description thisSUMclause appears in must be such that it would be legal toMOVE(see MOVE) the specified <identifier-7> or <literal-2> value to a data item with thatPICTURE.The following points apply to the
UPONoption: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
SUMclause appears.The presence of an
UPONclause limits theSUMclause to adding the specified numeric literal or identifier value into the sum counter only when aGENERATE identifier-9statement is executed.If there is no
UPONclause specified, the value of <identifier-7> or <literal-2> will be added into the sum counter whenever aGENERATE(see 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
UPONclause is meaningless.
The following points apply to the
RESEToption:If the
RESEToption is coded,FINALor <identifier-8> (whichever is coded on theRESET) must be one of the report’s control breaks specified on theCONTROLSclause.If there is no
RESEToption coded, the sum counter will be reset back to zero after each time the control footing containing theSUMclause is presented. This is the typical behaviour that would be expected.If, however, you want to reset the
SUMcounter only when the control footing for a control break higher in the control hierarchy is presented, specify that higher control break on theRESEToption.
SYNCHRONIZED
SYNCHRONIZED Syntax
=======================================================================
SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ]
~~~~ ~~~~ ~~~~ ~~~~~
The LEFT and RIGHT (SYNCHRONIZED) clauses are syntactically recognized but are otherwise non-functional.
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE
This optional clause optimizes the storage of binary numeric items to store them in such a manner as to make it as fast as possible for the CPU to fetch them.
The reserved words
SYNCHRONIZEDandSYNCHRONISEDare interchangeable, and may be abbreviated asSYNC.If the
SYNCHRONIZEDclause is coded on anything but a numeric data item with aUSAGE(see USAGE) that specifies storage of data in a binary form, theSYNCHRONIZEDclause 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.
TO
TO Clause Syntax
=======================================================================
TO identifier-1
~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause logically attaches a screen section data item to another data item defined elsewhere in the data division.
TYPE
TYPE Clause Syntax
=======================================================================
Format 1: All Sections other than REPORT SECTION
TYPE TO type-name-1
~~~~
Format 2: REPORT SECTION only
TYPE IS { CH|{CONTROL HEADING} [ ON|FOR ] { FINAL|identifier-1 } [ OR PAGE ] }
~~~~ { ~~ ~~~~~~~ ~~~~~~~ ~~~~~ }
{ RH|{REPORT HEADING} }
{ ~~ ~~~~~~ ~~~~~~~ }
{ PH|{PAGE HEADING} }
{ ~~ ~~~~ ~~~~~~~ }
{ DE|DETAIL }
{ ~~ ~~~~~~ }
{ CF|{CONTROL FOOTING} [ ON|FOR ] [ { FINAL|identifier-2 } [ OR PAGE ] ] }
{ ~~ ~~~~~~~ ~~~~~~~ [ ~~~~~ ] }
{ [ ALL ] }
{ ~~~ }
{ RF|{REPORT FOOTING} }
{ ~~ ~~~~~~ ~~~~~~~ }
{ PF|{PAGE FOOTING} }
~~ ~~~~ ~~~~~~~
=======================================================================
The syntax is valid in all other sections than: 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
TYPEDEF(see 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. 05 MAIN-FILE-NAME TYPE MAIN-FILE-NAME-T. 05 FILLER REDEFINES MAIN-FILE-NAME. 10 FILLER PIC 9999. 05 MAIN-FILE-NAME-2 TYPE MAIN-FILE-NAME-2T. 05 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.
As Format 2. This syntax is valid in the following sections: REPORT
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
RDdefined with aTYPEofREPORT HEADING,PAGE HEADING,PAGE FOOTINGandREPORT FOOTING.There must be either a
CONTROL HEADINGor aCONTROL FOOTINGor both specified for each entry specified on theCONTROLS AREclause of theRD.The various report groups that constitute a report may be defined in any order.
See RWCS Lexicon, for a description of the seven different types of report groups.
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.
UNDERLINE
UNDERLINE Attribute Syntax
=======================================================================
UNDERLINE
~~~~~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
The UNDERLINE clause will introduce a horizontal line at the bottom edge of a screen field.
The
LEFTLINE(see LEFTLINE),OVERLINE(see OVERLINE) andUNDERLINEclauses 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.
See Color Palette and Video Attributes, for more information on screen colors and video attributes.
USAGE
USAGE Clause Syntax
=======================================================================
USAGE IS data-item-usage
~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT
The USAGE clause defines the format that will be used to store the value of a data item.
The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program.The following tables summarize the USAGE specifications available in GnuCOBOL.
TABLE 1 +----------------------+--------------------------------+----------+---------+-------+ | USAGE | RANGE | STORAGE |NEGATIVE | PIC | | | OF VALUES | FORMAT |ALLOWED? | USED? | +----------------------+--------------------------------+----------+---------+-------+ |[ DISPLAY ] | Max Picture is 9(38) |Characters|if PIC | Yes | | ~~~~~~~ | or Picture X(2147483646) | |cont. 'S'| | +----------------------+--------------------------------+----------+---------+-------+ | DISPLAY-1 | While syntactically recognized |Characters| | Yes | | ~~~~~~~~~ | not yet supported by GnuCOBOL |(DBCS) | | PIC N | +----------------------+--------------------------------+----------+---------+-------+ |COMP | Defined by the quantity of |Compatible|if PIC 9 | Yes | |COMPUTATIONAL | '9's and the presence/absence |Binary |contains | | |BINARY | of an 'S' in the PICTURE |Integer |'S' | | |~~~~~~ | pic 9(01) to 9(04) size=2 bytes| | | | | | pic 9(05) to 9(09) size=4 bytes| | | | | | pic 9(10) to 9(18) size=8 bytes| | | | | | Negative number are represented| | | | | | as the two's complement of the | | | | | | positive number with the same | | | | | | absolute value. Max pic 9(18) | | | | +----------------------+--------------------------------+----------+---------+-------+ |COMP-1 | Approximately | Native | Yes | No | |COMPUTATIONAL-1 | -3.4028235 * 10**38 | IEEE 754 | | | |FLOAT-SHORT | to 3.4028235 * 10**38 | Binary32 | | | |~~~~~~~~~~~ | size = 4 bytes = 32bits: | Floating | | | |FLOAT | 1 sign; 8 exponent; 23 fraction| -point | | | |~~~~~ | | | | | |COMP-9(GCOS) | 32-bit IEEE Single Precision | | | | +----------------------+--------------------------------+----------+---------+-------+ |COMP-2 | Approximately | Native | Yes | No | |COMPUTATIONAL-2 | -1.797693134862316 * 10**308 | IEEE 754 | | | |FLOAT-LONG | to 1.797693134862316 * 10**308 | Binary64 | | | |~~~~~~~~~~ | size = 8 bytes = 64 bits: | Floating | | | |DOUBLE | 1 sign; 1 exponent; 62 fraction| -point | | | |~~~~~~ | | | | | |COMP-10,COMP-15(GCOS) | 64-bit IEEE Double Precision | | | | +----------------------+--------------------------------+----------+---------+-------+ |FLOAT-EXTENDED | While syntactically recognized | Native | Yes | No | |~~~~~~~~~~~~~~ | not yet supported by GnuCOBOL | IEEE 754 | | | | | | Binary128| | | | | 128-bit IEEE Quad Precision | Fl.point | | | +----------------------+--------------------------------+----------+---------+-------+ TABLE 1 - Continued +----------------------+--------------------------------+----------+---------+-------+ | USAGE | RANGE | STORAGE |NEGATIVE | PIC | | | OF VALUES | FORMAT |ALLOWED? | USED? | +----------------------+--------------------------------+----------+---------+-------+ |COMP-3 | Defined by the quantity of '9's| Signed |if PIC 9 | Yes | |COMPUTATIONAL-3 | and the presence or absence of | Packed |contains | | |PACKED-DECIMAL | an 'S' in the PICTURE | Decimal |'S' | | |~~~~~~~~~~~~~~ | Max picture is 9(38) | | | | +----------------------+--------------------------------+----------+---------+-------+ |COMP-4 | same as COMP |machine | | | |COMPUTATIONAL-4 | (is always Big Endian) |independnt| | | +----------------------+--------------------------------+----------+---------+-------+ |COMP-5 | [S]9(1) to [S]9(4) 2bytes | Native |if PIC 9 | Yes | |COMPUTATIONAL-5 | 0 to 65535 or -32768 to +32676 | Binary |contains | | | | [S]9(5) to [S]9(9) 4bytes | Integer |'S' | | | | 0 to 4,294,967,295 or | | | | | |-2,147,483,648 to +2,147,483,647|machine | | | | | [S]9(10) to [S]9(18) 8bytes |dependent | | | | | 0 to 18,446,744,073,709,551,615| | | | | |or -9,223,372,036,854,775,808 to| | | | | | +9,223,372,036,854,775,807 | | dependent | | +----------------------+--------------------------------+----------+---------+-------+ |COMP-6 | same as COMP-3 but unsigned | Unsigned | No | Yes | |COMPUTATIONAL-6 | 2 decimal digit x byte | Packed | | | | | Max picture is 9(38) | Decimal | | | +----------------------+--------------------------------+----------+---------+-------+ |COMP-X | If used with PIC X, allocates | Native |if PIC 9 | Yes | |COMPUTATIONAL-X | one byte of storage per 'X'; | unsigned |contains | | | | range of values is 0 to max | PIC (X) |'S' | | | | storable in that many bytes. | or signed| | | | | If used with PIC 9, range of | PIC (9) | | | | | values depends on number of | Binary | | | | | '9's in PICTURE | | | | | | Max picture is PIC 9(38) | | | | | | or PIC X(9999999999) | | | | +----------------------+--------------------------------+----------+---------+-------+ |COMP-N | PICTURE can only be all 9's or | |if PIC 9 | Yes | |COMPUTATIONAL-N | all X's | |contains | | | | A COMP-N data item is identical| |'S' | | | | to a COMP-X data item, except | | | | | | that the data is stored in the | | | | | | host machine's native format, | | | | | | instead of machine-independent | | | | | | format. | | | | +----------------------+--------------------------------+----------+---------+-------+ |COMP-0 | Not implemented | |if PIC 9 | Yes | |COMPUTATIONAL-0 | | |contains | | +----------------------+--------------------------------+----------+---------+-------+ The picture for a COMP-5 data item can specify integer and decimal positions as a scaling factor: a item with PICTURE S9999 COMP-5 (storage as 2bytes) has values from -32768 to +32768 a item with PICTURE S99V99 COMP-5 (storage as 2bytes) has values from -327.68 to +327.67. TABLE 2 +-------------------------+-----------------------------+----------+---------+-------+ | NUMERIC USAGE | RANGE | STORAGE |NEGATIVE | PIC | | WITHOUT PICTURE | OF VALUES | FORMAT |ALLOWED? | USED? | +-------------------------+-----------------------------+----------+---------+-------+ |BINARY-CHAR [SIGNED] | -128 (-2**7) to 127 (2**7)-1| Native | Yes | No | |~~~~~~~~~~~ | | Binary | | | | | same as S9(2) COMP-5 | Integer | | | +-------------------------+-----------------------------+----------+---------+-------+ |BINARY-CHAR UNSIGNED | 0 to 255 | Native | No | No | |~~~~~~~~~~~ ~~~~~~~~ | | Binary | | | | |(8 bit= from 0 to ((2**8)-1) | Integer | | | +-------------------------+-----------------------------+----------+---------+-------+ |BINARY-SHORT [SIGNED] | -32,768 (-2**15) | Native | Yes | No | |~~~~~~~~~~~~ | to 32,767 (2**15 -1) | Binary | | | |SIGNED-SHORT | 16 bit integer | Integer | | | |~~~~~~~~~~~~ | same as S9(4) COMP-5 | | | | +-------------------------+-----------------------------+----------+---------+-------+ |BINARY-SHORT UNSIGNED | 0 to 65,535 | Native | No | No | |~~~~~~~~~~~~ ~~~~~~~~ | | Binary | | | |UNSIGNED-SHORT | | Integer | | | |~~~~~~~~~~~~~~ | 16 bit=from 0 to ((2**16)-1)| | | | +-------------------------+-----------------------------+----------+---------+-------+ |BINARY-LONG [SIGNED] | -2,147,483,648 (-2**31) | Native | Yes | No | |~~~~~~~~~~~ | to 2,147,483,647 (2**31 -1)| Binary | | | |BINARY-INT [SIGNED] | | Integer | | | |~~~~~~~~~~ | 32 bit integer | | | | |SIGNED-INT | same as S9(9) COMP-5 | | | | |~~~~~~~~~~ | | | | | +-------------------------+-----------------------------+----------+---------+-------+ |BINARY-LONG UNSIGNED | 0 to 4,294,967,295 | Native | No | No | |~~~~~~~~~~~ ~~~~~~~~ | | Binary | | | |BINARY-INT UNSIGNED | | Integer | | | |~~~~~~~~~~ ~~~~~~~~ | | | | | |UNSIGNED-INT |32 bit= from 0 to ((2**32)-1)| | | | |~~~~~~~~~~~~ | | | | | +-------------------------+-----------------------------+----------+---------+-------+ |BINARY-LONG-LONG [SIGNED]| -9,223,372,036,854,775,808| Native | Yes | No | |~~~~~~~~~~~~~~~~ | (-2**63) | Binary | | | |BINARY-DOUBLE [SIGNED] | to 9,223,372,036,854,775,807| Integer | | | |~~~~~~~~~~~~~ | (2**63 -1) | | | | |SIGNED-LONG | 64 bit integer | | | | |~~~~~~~~~~~ | same as S9(18) COMP-5 | | | | +-------------------------+-----------------------------+----------+---------+-------+ |BINARY-LONG-LONG UNSIGNED| 0 to | Native | | | |~~~~~~~~~~~~~~~~ ~~~~~~~~| 18,446,744,073,709,551,615 | Binary | | | |BINARY-DOUBLE UNSIGNED | (2**64) | Integer | No | No | |~~~~~~~~~~~~~ ~~~~~~~~ | | | | | |UNSIGNED-LONG | | | | | |~~~~~~~~~~~~~ | | | | | +-------------------------+-----------------------------+----------+---------+-------+ TABLE 2 - Continued +----------------------+--------------------------------+----------+---------+-------+ | USAGE | RANGE | STORAGE |NEGATIVE | PIC | | | OF VALUES | FORMAT |ALLOWED? | USED? | +----------------------+--------------------------------+----------+---------+-------+ |BINARY-C-LONG [SIGNED]| Depending on the system HW the | | YES | No | |~~~~~~~~~~~~~ | range is either | | | | | | 0 to 2**31 or 0 to 2**63 | | | | +----------------------+--------------------------------+----------+---------+-------+ |BINARY-C-LONG UNSIGNED| Depending on the system HW the | | No | No | |~~~~~~~~~~~~~ ~~~~~~~~| range is either | | | | | | 0 to 2**32 or 0 to 2**64 | | | | | | This USAGE should only be used | | | | | | for direct CALLs into C and | | | | | | otherwise should not be used | | | | | | (it won't compile with any | | | | | | strict -std as it is a | | | | | | GnuCOBOL-only extension) | | | | +----------------------+--------------------------------+----------+---------+-------+ |FLOAT-DECIMAL-16 | -9.999999999999999 * 10**384 | Native | Yes | No | |~~~~~~~~~~~~~~~~ | to 9.999999999999999 * 10**384 | IEEE 754 | | | | | | Decimal64| | | | | | Floating | | | | | | -point | | | +----------------------+--------------------------------+----------+---------+-------+ |FLOAT-DECIMAL-34 | -9.99999... * 10**6144 |Native | Yes | No | |~~~~~~~~~~~~~~~~ | to 9.99999... * 10**6144 |IEEE 754 | | | | | |Decimal128| | | | | (n.33 9s after decimal point) | Floating | | | | | size=16 bytes | -point | | | +----------------------+--------------------------------+----------+---------+-------+ TABLE 3 +----------------------+--------------------------------+----------+---------+-------+ | OTHER USAGE | RANGE | STORAGE |NEGATIVE | PIC | | | OF VALUES | FORMAT |ALLOWED? | USED? | +----------------------+--------------------------------+----------+---------+-------+ |HANDLE OF [VARIANT] | | Native | Yes | No | |~~~~~~ [WINDOW] | Size is 4 bytes | Binary | | | | [SUBWINDOW] | | Integer | | | | [THREAD] | | | | | +----------------------+--------------------------------+----------+---------+-------+ |INDEX | 0 to maximum address possible | Native | No | No | |~~~~~ | (32 or 64 bits) | Binary | | | | | | Integer | | | +----------------------+--------------------------------+----------+---------+-------+ |POINTER | 0 to maximum address possible | Native | No | No | |~~~~~~~ | (32 or 64 bits: 4 or 8 bytes) | Binary | | | | | | Integer | | | +----------------------+--------------------------------+----------+---------+-------+ |PROGRAM-POINTER | 0 to maximum address possible | Native | No | No | |~~~~~~~~~~~~~~~ | (32 or 64 bits: 4 or 8 bytes) | Binary | | | |PROCEDURE-POINTER | | Integer | | | |~~~~~~~~~~~~~~~~~ | | | | | +----------------------+--------------------------------+----------+---------+-------+ |FUNCTION-POINTER | While syntactically recognized | -- | No | No | |~~~~~~~~~~~~~~~~ | it is not supported by GnuCOBOL| | | | +----------------------+--------------------------------+----------+---------+-------+ |NATIONAL | While syntactically recognized | -- | -- | Yes | |~~~~~~~~ | it is not supported by GnuCOBOL| | | PIC N | +----------------------+--------------------------------+----------+---------+-------+ |BIT | While syntactically recognized | -- | -- | Yes | |~~~ | it is not supported by GnuCOBOL| | | PIC 1 | +----------------------+--------------------------------+----------+---------+-------+ |type-name-1 | User defined DATA TYPE | -- | -- | -- | | | see also the TYPEDEF clause | | | | +----------------------+--------------------------------+----------+---------+-------+Computational items.
The
USAGE DISPLAYof numeric values store each digit represented by the corresponding character. APIC 999field that contains the value 456 is stored in 3 bytes, each one containing one digit. Machines can perform the computations significantly faster on base-2 (binary) numbers that base-10 numbers. If a number is stored in binary format, it can be used in computations directly. You can useUSAGE COMPUTATIONALorUSAGE COMPorBINARYto change the storage format from character/text to binary format.COMPUTATIONALis one of the most powerful and performance-critical data types in COBOL, representing numeric values in the computer’s native binary format rather than the traditional decimal representations that COBOL is known for. This data type provides significant advantages in terms of storage efficiency, computational speed, and memory utilization, making it indispensable for high-performance applications, system programming, and scenarios where processing millions of records requires optimal resource usage.COMPUTATIONALorCOMPis the only generic binaryUSAGEdefined by the ISO COBOL standard. But the standard does not mandate how the data should be stored; it leaves it up to the compiler implementer. This created the need to also define some otherUSAGE, example:COMP-1,COMP-2,COMP-3,COMP-4,COMP-5,COMP-6.By COBOL standard, this
USAGE COMPis an implementation depedent form. Usually one of the fastest native forms, but not that safe when transferring data between machines, even those compiled with the same version of GnuCOBOL, as it depends on hardware platform.Endianness or Byte Order.
There are two possible Byte Orders in which bytes can be stored in memory.
Either you store byte containing the most significant byte (MSB) as the leftmost byte (named Big Endian) or at the rightmost byte (named Little Endian).
IBM mainframe processors use Big Endian and Intel machines use Little Endian format to store numbers in memory. Big Endian machine store MSB in lower address in memory and Little Endian machine stores MSB in higher address in memory.
Example: To store the 4-byte hexadecimal number 0x12345678:
memory address: 01 02 03 04 Big-Endian: 12 34 56 78 (Stored as written) Little-Endian: 78 56 34 12 (Reversed)Big-Endian (BE)
In Big-Endian systems, the most significant byte (MSB) is stored at the lowest memory address. This format is often considered more human-readable because it matches how we write numbers.
Memory Address Stored Byte Address +0 0x12 (MSB) Address +1 0x34 Address +2 0x56 Address +3 0x78 (LSB)It is used in Networking protocols (TCP/IP), mainframes and legacy systems, File formats like JPEG and PNG, etc.
Little-Endian (LE)
In Little-Endian systems, the least significant byte (LSB) is stored at the lowest memory address. This layout aligns well with how CPUs perform arithmetic internally.
Memory Address Stored Byte Address +0 0x78 (LSB) Address +1 0x56 Address +2 0x34 Address +3 0x12 (MSB)It is used by Intel (x86), AMD, and most modern desktops, laptops and embedded MicroController Unit.
BE vs LE becomes critical for example, in the following cases: A) Networking TCP/IP: the internet uses Big Endian. Without proper byte conversion, data sent from a Little Endian system will be misinterpreted; B) Binary File Sharing: Opening a binary file created on a Big Endian system on a Little Endian machine can corrupt values unless handled correctly; C) Low-Level Programming: In C, assembly, or embedded systems, incorrect assumptions about byte order lead to subtle and dangerous bugs.
Without defined endianness, a computer trying to read data created by another might interpret the bytes in reverse order, leading to completely wrong numerical values or corrupted files. This is particularly critical in network communication between different types of machines, where one may be Little Endian (e.g., PC) and the other Big Endian (e.g., network server).
USAGE COMP.In the original ANSI COBOL standards,
COMP(short forCOMPUTATIONAL) was defined very loosely. It simply meant "a format efficient for calculation". Hardware vendors implementedUSAGE COMPdifferently to suit their own CPUs. IBM is Big Endian. By default, GnuCOBOL storesCOMPandBINARYdata in Big Endian order.USAGE COMP-4.Was specifically introduced by several vendors (and later adopted by IBM) to explicitly mean Binary Big Endian storage. Other compiler makers (like Micro Focus or Fujitsu) wanted their COBOL to be compatible with IBM’s. IBM decided that
COMP,COMP-4, and the keywordBINARYwould all point to the same internal binary representation. Because millions of lines of code were already written usingCOMPand others usingCOMP-4, compiler vendors kept both keywords to ensure that old programs would still compile without errors.COMP-4is machine-independent, binary number with the storage size (2, 4 or 8 bytes) dictated by the number of 9s in thePICTUREclause .COMPandCOMP-4andBINARYare simply synonyms. there is zero performance or functional difference between them.USAGE COMP-5.It is a "Native Binary Item" ( can be Big Endian or Little Endian). To overcome the limitations of
COMP, IBM introducedCOMP-5, which allows binary fields to behave like native binary integers. This means the value range is determined by the binary field size, not the number of ‘9s’ in the picture clause.COMPorCOMP-4truncates based on the decimal value defined in the picture clause, whileCOMP-5truncates based on the binary field size.COMP-5can contain values up to the capacity of the native binary representation (2, 4, or 8 bytes) rather than being limited to the value implied by the number of 9s in thePICTUREclause. Useful for interfacing with C or other languages. When you move or store numeric data into aCOMP-5item, truncation occurs at the binary field size rather than at the COBOLPICTUREsize limit.COMP-5is thus particularly useful for binary data items that originate in non-COBOL programs where the data might not conform to a COBOLPICTUREclause.COMPorCOMP-4orCOMP-5specifies the storage of half word, full word, or double word (2, 4, and 8 bytes, respectively). Even thoughPIC S9(4) COMP-4has a signed half-word storage, it limits the values to the range of -9999 through +9999 due to the four decimal places in thePICTUREclause. You can useCOMP-5to eliminate the limitation. For example,PIC S9(4) COMP-5has a half-word storage and allows the range of values of -32768 through +32767.If you need to write code that will compile on different machines, using
COMP-5(Native Binary) is often preferable to take advantage of the specific processor architecture (as Little Endian on Intel or Big endian on Mainframe).COMP-5is primarily used to communicate with external programs that expect native data storage. AVALUEclause for aCOMP-5data item is stored in a machine-independent format and is adjusted when it is loaded into the data item.The format of a
COMP-5data item is identical to aCOMP-4data item, except that the data is stored in a machine-dependent native format. For example, aPIC S9(4) COMP-5data item is equivalent to a 16-bit binary word on the host machine, and aPIC S9(4) COMP-5item is equivalent to a 32-bit word. Data stored in aCOMP-5field may not be transportable to other machines because different machines have different natural byte-orderings. On many machines (Mainframe, 68000, most RISC),COMP-5is identical toCOMP-4. On others (80x86, VAX), it is the same with the bytes in the reverse order.Level 01 and level 77 data items that are
COMP-5are automatically synchronized to an appropriate machine boundary, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.COMP,COMP-4,COMP-5: the leftmost bit indicates an operational sign 0: positive 1: negative A negative value is represented by twos complementin HEX notation:
+15 in PIC S9(9)V999 COMP/COMP-4 looks 000000000000000F -15 in PIC S9(9)V999 COMP/COMP-4 looks FFFFFFFFFFFFFFF1 (2s complement + 1)GnuCOBOL related COMPILER OPTIONS.
COMP-5always represents Native binary, so BE or LE will be depending upon the platform you use. Compiler flag determines whether plainCOMPwasCOMP-4orCOMP-5(native). The TRUNC(BIN) compiler option causes all binary data items (USAGE BINARY,COMP,COMP-4) to be handled as if they were declaredUSAGE COMP-5. This kind of compiler option will be available across all ANSI compliant platforms which support COBOL.-fbinary-byteorder=<value> binary byte order, may be one of: native, big-endian applies only to BINARY, COMP, and COMP-4 items.
-fbinary-size=<value> binary byte size - defines the allocated bytes according to PIC, may be one of: 2-4-8, 1-2-4-8, 1–8
-fno-trunc = Do not truncate binary fields according to PICTURE and allow numeric field overflow; non-ANSI behaviour
-fbinary-truncate = numeric truncation according to ANSI
Compiler dialect configuration options:
-fbinary-byteorder=<value> binary byte order, may be one of: native, big-endian ex: -fbinary-byteorder=big-endian The -fbinary-byteorder=big-endian compile option works for
BINARY,COMP, andCOMP-4items, but not forCOMP-5items.COMP-5data items are always stored in native format (Big or Little Endian).COMP-5is subject to external high order truncation when displayed by PICTURE and during PICTURE based MOVE instructions. The compiler option -fno-trunc can modify this behaviour and may display fields wider than the PICTURE.Compiler Configuration from config/default.conf.
# Numeric truncation according to ANSI binary-truncate: yesCompiler Configuration File
binary-size: 1-2-4-8A compile time test, using the Compiler Directive Facility is available with a predefined ENDIAN symbol. It will hold BIG or LITTLE at compile time.
>>IF ENDIAN = "BIG" big endian code >>END-IF ... >>IF ENDIAN = "LITTLE" little endian code >>END-IFSample Program
>>SOURCE FREE IDENTIFICATION DIVISION. PROGRAM-ID. TESTCOMP. *> demo of COMP, COMP-4, COMP-5 environment division. configuration section. repository. function all intrinsic. DATA DIVISION. WORKING-STORAGE SECTION. 01 wCOMP PIC 9(8) COMP . 01 wCOMP4 PIC 9(8) COMP-4. 01 wCOMP5 PIC 9(8) COMP-5. 01 sCOMP PIC s9(8) COMP . 01 sCOMP4 PIC s9(8) COMP-4. 01 sCOMP5 PIC s9(8) COMP-5. PROCEDURE DIVISION. move h'1234' to wCOMP wCOMP4 wCOMP5 display 'wCOMP ' wCOMP ' HEX ' hex-of(wCOMP) ' BIT ' bit-of(wCOMP) ' L ' length(wCOMP) display 'wCOMP4 ' wCOMP4 ' HEX ' hex-of(wCOMP4) ' BIT ' bit-of(wCOMP4) ' L ' length(wCOMP4) display 'wCOMP5 ' wCOMP5 ' HEX ' hex-of(wCOMP5) ' BIT ' bit-of(wCOMP5) ' L ' length(wCOMP5) display space move +789258 to sCOMP sCOMP4 sCOMP5 display 'sCOMP ' sCOMP ' HEX ' hex-of(sCOMP) ' BIT ' bit-of(sCOMP) ' L ' length(sCOMP) display 'sCOMP4 ' sCOMP4 ' HEX ' hex-of(sCOMP4) ' BIT ' bit-of(sCOMP4) ' L ' length(sCOMP4) display 'sCOMP5 ' sCOMP5 ' HEX ' hex-of(sCOMP5) ' BIT ' bit-of(sCOMP5) ' L ' length(sCOMP5) display space move -789258 to sCOMP sCOMP4 sCOMP5 display 'sCOMP ' sCOMP ' HEX ' hex-of(sCOMP) ' BIT ' bit-of(sCOMP) ' L ' length(sCOMP) display 'sCOMP4 ' sCOMP4 ' HEX ' hex-of(sCOMP4) ' BIT ' bit-of(sCOMP4) ' L ' length(sCOMP4) display 'sCOMP5 ' sCOMP5 ' HEX ' hex-of(sCOMP5) ' BIT ' bit-of(sCOMP5) ' L ' length(sCOMP5) display space move +15 to sCOMP sCOMP4 sCOMP5 display 'sCOMP ' sCOMP ' HEX ' hex-of(sCOMP) ' BIT ' bit-of(sCOMP) ' L ' length(sCOMP) display 'sCOMP4 ' sCOMP4 ' HEX ' hex-of(sCOMP4) ' BIT ' bit-of(sCOMP4) ' L ' length(sCOMP4) display 'sCOMP5 ' sCOMP5 ' HEX ' hex-of(sCOMP5) ' BIT ' bit-of(sCOMP5) ' L ' length(sCOMP5) display space move -15 to sCOMP sCOMP4 sCOMP5 display 'sCOMP ' sCOMP ' HEX ' hex-of(sCOMP) ' BIT ' bit-of(sCOMP) ' L ' length(sCOMP) display 'sCOMP4 ' sCOMP4 ' HEX ' hex-of(sCOMP4) ' BIT ' bit-of(sCOMP4) ' L ' length(sCOMP4) display 'sCOMP5 ' sCOMP5 ' HEX ' hex-of(sCOMP5) ' BIT ' bit-of(sCOMP5) ' L ' length(sCOMP5) accept omitted STOP RUN. Output: wCOMP 00004660 HEX 00001234 BIT 00000000000000000001001000110100 L 4 wCOMP4 00004660 HEX 00001234 BIT 00000000000000000001001000110100 L 4 wCOMP5 0000004660 HEX 34120000 BIT 00110100000100100000000000000000 L 4 sCOMP +00789258 HEX 000C0B0A BIT 00000000000011000000101100001010 L 4 sCOMP4 +00789258 HEX 000C0B0A BIT 00000000000011000000101100001010 L 4 sCOMP5 +0000789258 HEX 0A0B0C00 BIT 00001010000010110000110000000000 L 4 sCOMP -00789258 HEX FFF3F4F6 BIT 11111111111100111111010011110110 L 4 sCOMP4 -00789258 HEX FFF3F4F6 BIT 11111111111100111111010011110110 L 4 sCOMP5 -0000789258 HEX F6F4F3FF BIT 11110110111101001111001111111111 L 4 sCOMP +00000015 HEX 0000000F BIT 00000000000000000000000000001111 L 4 sCOMP4 +00000015 HEX 0000000F BIT 00000000000000000000000000001111 L 4 sCOMP5 +0000000015 HEX 0F000000 BIT 00001111000000000000000000000000 L 4 sCOMP -00000015 HEX FFFFFFF1 BIT 11111111111111111111111111110001 L 4 sCOMP4 -00000015 HEX FFFFFFF1 BIT 11111111111111111111111111110001 L 4 sCOMP5 -0000000015 HEX F1FFFFFF BIT 11110001111111111111111111111111 L 4
Data items that have the
UNSIGNEDattribute explicitly coded, orDISPLAY,PACKED-DECIMAL,COMP-5,COMP-Xitems that do not have an ‘S’ symbol in their picture clause cannot preserve negative values that may be stored into them. Storing a negative value into such a field will actually result in the sign being stripped, essentially saving the absolute value in the data item.Packed-decimal (i.e.
USAGE PACKED-DECIMAL,USAGE COMP-3orUSAGE COMP-6) data is stored as a series of bytes such that each byte contains two 4-bit fields, referred to as nibbles (since they comprise half a “byte”, they’re just “nibbles” — don’t groan, I don’t just make this stuff up!). Each nibble represents a ‘9’ in thePICTUREand each holds a single decimal digit encoded as its binary value (0 = 0000, 1 = 0001, … , 9 = 1001).The last byte of a
PACKED-DECIMALorCOMP-3data item will always have its left nibble corresponding to the last ‘9’ in thePICTUREand its right nibble reserved as a sign indicator. This sign indicator is always present regardless of whether or not thePICTUREincluded an ‘S’ symbol.The first byte of the data item will contain an unused left nibble if the
PICTUREhad an even number of ‘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
PIC S9(3) COMP-3packed-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 ‘
S’ in itsPICTURE, the absolute value of the negative number will actually be stored.USAGE COMP-6does not allow for negative values, therefore no sign nibble will be allocated. AUSAGE COMP-6data item containing an odd number of ‘9’ symbols in itsPICTUREwill leave its leftmost nibble unused.The
USAGEspecificationsFLOAT-DECIMAL-16andFLOAT-DECIMAL-34will encode data using IEEE 754 Decimal64 and Decimal128 format, respectively. The former allows for up to 16 digits of exact precision while the latter offers 34. The phrase “exact precision” is used because the traditional binary renderings of decimal real numbers in a floating-point format (FLOAT-LONGandFLOAT-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 thatPACKED-DECIMALrenders 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
FLOAT-DECIMAL-16andFLOAT-DECIMAL-34data items using either Big-Endian or Little-Endian form, whichever is native to the system.The
USAGEspecificationsFLOAT-LONGandFLOAT-SHORTuse 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
FLOAT-LONGandFLOAT-SHORTdata items using either Big-Endian or Little-Endian form, whichever is native to the system.A
USAGEclause specified at the group item level will apply thatUSAGEto all subordinate data items, except those that themselves have aUSAGEclause.The only
USAGEthat is allowed in the report section isUSAGE DISPLAY.USAGE BIT(not yet implemented [-Wpending]) is used to define Boolean data items. While standard COBOL typically handles data at the byte level, this specific clause allows you to manage individual bits, which is highly efficient for flags, switches, and logical states. You must use PIC 1 (or PIC 11...11 or PIC 1(n)) where each "1" represents a single bit.Boolean values are assigned using Boolean literals: B"1" or b"1" for true/on and B"0" or b"0" for false/off.
DATA DIVISION. WORKING-STORAGE SECTION. 01 SWITCH-FLAGS. 05 IS-ACTIVE PIC 1 USAGE BIT. 05 IS-VALID PIC 1 USAGE BIT. 05 IS-COMPLETE PIC 1 USAGE BIT. PROCEDURE DIVISION. MOVE B"1" TO IS-ACTIVE. IF IS-ACTIVE = B"1" DISPLAY "System is active." END-IF. USAGE and PIC 1: USAGE BIT PIC 1(8) value 11100101 HEX E5 one bit of 0 or 1 USAGE DISPLAY PIC 1(8) value 11100101 HEX 3131313030313031 one char.of 0 or 1GnuCOBOL provides built-in functions for complex bit operations:
B-AND,B-OR,B-XOR,B-NOT: perform bitwise logical operations.BOOLEAN-OF-INTEGER: Converts a numeric value into its binary bit representation.INTEGER-OF-BOOLEAN: Converts a sequence of bits back into a standard integer.Why use
USAGE BIT? It is primarily used for interoperability with other languages (like C or Java) that use bit-fields, or for memory optimization in large arrays of status flags.HANDLE OFare stored as 4 byte binary integers and behave like numbers when used. These data items are used to store the handle of a dynamically created object such as a floating window or a graphical control. They come in two forms: generic (when you omit the OF phrase), typed when you include the OF phrase. You may use HANDLE data items only when explicitly allowed, or as part of a MOVE statement, a CALL statement (as a parameter), or in a Boolean expression. The implementation of USAGE HANDLE in GnuCOBOL is currently not of practical use but is needed for a future implementation of the use of graphical "objects" such as floating windows or graphic controls.It’s main purpose is currently supporting migrations from ACUCOBOL-GT, as it is used in lots of "parsed and internally handled but not yet supported in the runtime" parts.
A example of usage follows using gnucobol v3.2 :
ID DIVISION. PROGRAM-ID. TESTHANDLE. DATA DIVISION. WORKING-STORAGE SECTION. 01 H0 usage HANDLE value 999999999. 01 H1 usage HANDLE OF VARIANT value 1. 01 H2 usage HANDLE OF SUBWINDOW value 2. 01 H3 usage HANDLE OF WINDOW value -123. 01 H4 usage HANDLE OF THREAD value -123. PROCEDURE DIVISION. DISPLAY H0 ' ' H1 ' ' H2 ' ' H3 ' ' H4 DISPLAY 'H1 ' FUNCTION HEX-OF(H1) STOP RUN. Output: +999999999 +000000001 +000000002 -000000123 -000000123 H1 01000000USAGE IS type-name-1~~~~~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
TYPEDEFclause.Example 1: 01 struct-1 TYPEDEF. 05 part-1 pic x(20). 05 part-2 pic x(10). 01 USHORT pic 9(04) comp-5 typedef. 01 a. 05 b USAGE struct-1. 05 x USAGE USHORT. 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.
USING
USING Clause Syntax
=======================================================================
USING identifier-1
~~~~~
=======================================================================
This syntax is valid in the following sections: SCREEN
This clause logically attaches a screen section data item to another data item defined elsewhere in the data division. It identifies data to be used both as the destination in an ACCEPT screen statement and the source for a DISPLAY screen statement.
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
ACCEPT.Specifying the USING clause is equivalent to specifying both the TO and FROM clauses, each specifying the same identifier. The
FROM(see FROM),TO(see TO),USINGandVALUE(see VALUE) clauses aren’t mutually-exclusive in any screen section data item’s definition.
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 ({subscrpt-1}...) [ TO ({subscrpt-2}...)]}...
{ ~~~~~ } ~~~~ ~~
{ VALUES ARE }
~~~~~~
=======================================================================
This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN
The VALUE clause is used to define condition names or to assign values (at compilation time) to data items.
The reserved words
AREandISare 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
FROM(see FROM),TO(see TO) orUSING(see USING) clause.The following points apply to using the
VALUEclause in the definition of a condition name:The clauses
VALUE ISandVALUES AREare interchangeable.The reserved words
THRUandTHROUGHare interchangeable.See 88-Level Data Items, for a discussion of how this format of
VALUEis used to create condition names.See Condition Names, for a discussion of how condition names are used.
The following points apply to using the
VALUEclause in the definition of any other data item:In this context,
VALUEspecifies 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
VALUEclause is ignored onEXTERNAL(see EXTERNAL) data items or on any data items defines as subordinate to anEXTERNALdata item.This format of the
VALUEclause may not be used anywhere in the description of an 01 item (or any of its subordinate items) serving as anFDorSDrecord description.If the optional
ALLclause 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 withoutALL(the symbol b denotes a space):PIC X(5) VALUE ‘A’ *> Abbbb PIC X(5) VALUE ALL ‘A’ *> AAAAA PIC 9(3) VALUE 1 *> 001 PIC 9(3) VALUE ALL ‘1’ *> 111When used in the definition of a screen data item:
A figurative constant may not be supplied as <literal-1>.
Any
FROM(see FROM),TO(see TO) orUSING(see 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
ALLoption is specified, theALLoption 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
INITIALIZE(see 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
VALUEclause 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
REDEFINES(see REDEFINES) clause:05 SHIRT-SIZE-VALUES. 10 PIC X(4) VALUE "S 14". 10 PIC X(4) VALUE "M 15". 10 PIC X(4) VALUE "L 16". 10 PIC X(4) VALUE "XL17". 05 SHIRT-SIZES REDEFINES SHIRT-SIZE-VALUES. 10 SHIRT-SIZE-TBL OCCURS 4 TIMES. 15 SST-SIZE PIC X(2). 15 SST-NECK PIC 9(2).Admittedly, this table is much more verbose than the one shown with a group
VALUE. What is good about this initialization technique, however, is that you can have as manyFILLERandVALUEitems 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
VALUEandOCCURS(see OCCURS) on the same data item; additionally, they don’t allow aVALUEclause on a data item subordinate to anOCCURS. 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 ‘
A’ items will be initialized to ‘?’, all six ‘B’ items will be initialized to ‘%’ and all six ‘N’ items will be initialized to 10. It’s not clear exactly how many times this sort of initialization will be useful, but it’s there if you need it.
The
FROM(see FROM),TO(see TO),USING(see USING) andVALUEclauses 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.