6 DATA DIVISION

DATA DIVISION Syntax

  DATA DIVISION.
  ~~~~ ~~~~~~~~
[ FILE SECTION.
  ~~~~ ~~~~~~~
  { File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ]
  {                         { 01-Level-Constant      }      }
  {                         { 78-Level-Constant      }      }
  { 01-Level-Constant                                       }
  { 78-Level-Constant                                       }
[ WORKING-STORAGE SECTION.
  ~~~~~~~~~~~~~~~ ~~~~~~~
  [ { WORKING-STORAGE-SECTION-Data-Item } ]... ]
    { 01-Level-Constant                 }
    { 78-Level-Constant                 }
[ LOCAL-STORAGE SECTION.
  ~~~~~~~~~~~~~ ~~~~~~~
  [ { LOCAL-STORAGE-SECTION-Data-Item } ]... ]
    { 01-Level-Constant               }
    { 78-Level-Constant               }
[ LINKAGE SECTION.
  ~~~~~~~ ~~~~~~~
  [ { LINKAGE-SECTION-Data-Item } ]... ]
    { 01-Level-Constant         }
    { 78-Level-Constant         }
[ REPORT SECTION.
  ~~~~~~ ~~~~~~~
  { Report-Description [ { Report-Group-Definition } ]... }... ]
  {                      { 01-Level-Constant       }      }
  {                      { 78-Level-Constant       }      }
  { 01-Level-Constant                                     }
  { 78-Level-Constant                                     }
[ SCREEN SECTION.
  ~~~~~~ ~~~~~~~
  [ { SCREEN-SECTION-Data-Item } ]... ]
    { 01-Level-Constant        }
    { 78-Level-Constant        }

All data used by any COBOL program must be defined in one of the six sections of the data division, depending upon the purpose of the data.

  1. If no data will be described in one of the data division sections, that section header may be omitted.

  2. If no data division sections are needed, the DATA DIVISION. header itself may be omitted.

  3. If more than one section is needed in the data division (a common situation), the sections must be coded in the sequence they are presented above.

6.1 Data Definition Principles

GnuCOBOL data items, like those of other COBOL implementations, are described in a hierarchical manner. This accommodates the fact that data items frequently need to be able to be broken up into subordinate items. Take for example, the following logical layout of a portion of a data item named Employee:

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 ( 2.1.7 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:

  1. Every data item at the same level of a hierarchy diagram such as the one you see here (if you were to make one, which you rarely will, if ever, once you get used to this concept) must have the same level number.

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

  3. When describing data hierarchies, you may never use a level number greater than 49 (except for 66, 77, 78 and 88 which have very special meanings ( 6.8 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.

6.2 FILE SECTION

FILE SECTION Syntax

[ FILE SECTION.
  ~~~~ ~~~~~~~
  { File/Sort-Description [ { FILE-SECTION-Data-Item } ]... }... ]
  {                         { 01-Level-Constant      }      }
  {                         { 78-Level-Constant      }      }
  { 01-Level-Constant                                       }
  { 78-Level-Constant                                       }

Every file that has been referenced by a SELECT statement ( 5.2.1 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.

6.2.1 File/Sort-Description

File/Sort-Description Syntax

FD|SD file-name-1 [ IS EXTERNAL|GLOBAL ]
~~ ~~                  ~~~~~~~~ ~~~~~~
[ BLOCK CONTAINS [ integer-1 TO ] integer-2 CHARACTERS|RECORDS ]
  ~~~~~                      ~~             ~~~~~~~~~~ ~~~~~~~
[ CODE-SET IS alphabet-name-1 ]
  ~~~~~~~~
[ DATA { RECORD IS   } identifier-1... ]
  ~~~~ { ~~~~~~      }
       { RECORDS ARE }
         ~~~~~~~
[ LABEL { RECORD IS   } OMITTED|STANDARD ]
  ~~~~~ { ~~~~~~      } ~~~~~~~ ~~~~~~~~
        { RECORDS ARE }
          ~~~~~~~
[ LINAGE IS integer-3 | identifier-2 LINES
  ~~~~~~
    [ LINES AT BOTTOM integer-4 | identifier-3 ]
               ~~~~~~
    [ LINES AT TOP integer-5 | identifier-4 ]
               ~~~
    [ WITH FOOTING AT integer-6 | identifier-5 ] ]
           ~~~~~~~
[ RECORD { CONTAINS [ integer-7 TO ] integer-8 CHARACTERS   } ]
  ~~~~~~ {                      ~~                          }
         { IS VARYING IN SIZE                               }
         {    ~~~~~~~                                       }
         {     [ FROM [ integer-7 TO ] integer-8 CHARACTERS }
         {                        ~~                        }
         {         DEPENDING ON identifier-6 ]              }
                   ~~~~~~~~~
[ RECORDING MODE IS recording-mode ]
  ~~~~~~~~~
[ { REPORT IS   } report-name-1... ]
  { ~~~~~~      }
  { REPORTS ARE }
    ~~~~~~~
[ VALUE OF implementor-name-1 IS literal-1 | identifier-7 ] .
  ~~~~~ ~~

The BLOCK CONTAINS, DATA RECORD, LABEL RECORD, RECORDING MODE and VALUE OFclauses are syntactically recognized but are obsolete and non-functional. These clauses should not be coded in new programs.

  1. The reserved words ARE, AT, CHARACTERS (RECORD clause only), CONTAINS, FROM, IN, IS, ON and WITH are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program.

  2. The terms RECORD IS and RECORDS ARE are interchangeable.

  3. The terms REPORT IS and REPORTS ARE are interchangeable.

  4. Only files intended for use as work files for either the SORT ( 7.8.42 SORT) or MERGE ( 7.8.27 MERGE) statements should be coded with an SD — all others should be defined with a FD.

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

  6. The name specified as <file-name-1> must exactly match the name specified on the file’s SELECT statement.

  7. The CODE-SET clause allows a custom alphabet, defined in the SPECIAL-NAMES ( 5.1.3 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.

  8. The LINAGE clause may only be specified in the FD of a sequential or line sequential file. If used with a sequential file, the organization of that file will be implicitly changed to line sequential. The various components of the LINAGE clause define the layout of printed pages as follows:

    • LINES AT TOP

      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> LINES value.

  9. This page structure — once defined — can be automatically enforced by the WRITE statement ( 7.8.52 WRITE).

  10. Specifying a LINAGE clause in an FD will cause the LINAGE-COUNTER special register to be created for the file. This automatically-created data item will always contain the current relative line number on the page being prepared which will serve as the starting point for a WRITE statement.

  11. The RECORD CONTAINS and RECORD IS VARYING clauses are ignored (with a warning message issued) when used with line sequential files. With other file organizations, these mutually-exclusive clauses define the length of data records within the file. The data item specified as <identifier-6> must be defined within one of the record descriptions of <file-name-1>.

  12. The REPORT IS clause announces to the compiler that the file will be dedicated to the Report Writer Control System (RWCS); the clause names one or more reports, each to be described in the report section. The following special rules apply when the REPORT clause is used:

    1. The clause may only be specified in the FD of a sequential or line sequential file. If used with a sequential file, the organization of that file will be implicitly changed to line sequential.

    2. The FD cannot be followed by record descriptions. Detailed descriptions of data to be printed to the file will be defined in the REPORT SECTION ( 6.6 REPORT SECTION).

    3. If a LINAGE clause is also specified, Values specified for LINAGE IS and FOOTING AT will be ignored. The values of LINES AT BOTTOM and LINES AT TOP, if any, will be honoured.

  13. The following special rules apply only to sort/merge work files:

    1. Sort/merge work files should be assigned to DISK (or DISC) on their SELECT statements.

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

    3. 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:

      (in that order).

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

    5. If you specify a specific filename in the sort/merge work file’s SELECT, it will be ignored.

  14. 6.9 Data Description Clauses, for information on the EXTERNAL and GLOBAL options.

6.2.2 FILE-SECTION-Data-Item

FILE-SECTION-Data-Item Syntax

level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ]
                              ~~~~~~        ~~~~~~ ~~~~~~~~
[ BLANK WHEN ZERO ]
  ~~~~~      ~~~~
[ JUSTIFIED RIGHT ]
  ~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
  ~~~~~~             ~~   UNBOUNDED
                          ~~~~~~~~~
       [ DEPENDING ON identifier-2 ]
         ~~~~~~~~~
       [ STEP identifier-6 ]
       [ ASCENDING|DESCENDING KEY IS identifier-3 ]
         ~~~~~~~~~ ~~~~~~~~~~
       [ INDEXED BY identifier-4 ] ]
         ~~~~~~~
[ PICTURE IS picture-string ]
  ~~~
[ REDEFINES identifier-5 ]
  ~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE [CHARACTER] ] ]
  ~~~~    ~~~~~~~ ~~~~~~~~   ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
  ~~~~        ~~~~           ~~~~ ~~~~~
[ USAGE IS data-item-usage ] . [ FILE-SECTION-Data-Item ]...
  ~~~~~

The 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.

  1. The reserved words BY, IS, KEY, ON and WHEN are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program.

  2. The reserved words SYNCHRONIZED and SYNCHRONISED are interchangeable. Both may be abbreviated to SYNC.

  3. The reserved word PICTURE may be abbreviated to PIC.

  4. As the syntax diagram shows, the definition of a <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 FD or SD is found

      marks the completion of the detailed description of the file and begins another.

    • A division or section header is found

      also marks the completion of the detailed description of the file and signifies the end of the file section as well.

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

  6. If there are multiple record descriptions present for a given FD or SD, the one with the longest length will define the size of the record buffer into which a READ statement ( 7.8.32 READ) or a RETURN statement ( 7.8.36 RETURN) will deliver data read from the file and from which a WRITE statement ( 7.8.52 WRITE) or RELEASE statement ( 7.8.34 RELEASE) statement will obtain the data to be written to the file.

  7. The various 01-level record descriptions for a file description implicitly share that one common record buffer (thus, they provide different ways to view the structure of data that can exist within the file). Record buffers can be shared between files by using the SAME RECORD AREA ( 5.2.2 SAME RECORD AREA) clause.

  8. The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 66, 77, 78 and 88 all have special uses — 6.8 Special Data Items, for details.

  9. Not specifying an <identifier-1> or FILLER immediately after the level number has the same effect as if FILLER were specified. A data item named FILLER cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item or to describe a group item whose contents which will only be referenced using the names of those items that belong to it.

  10. EXTERNAL cannot be combined with GLOBAL or REDEFINES.

  11. File section data buffers (and therefore all 01-level record layouts defined in the file section) are initialized to all binary zeros when the program is loaded into storage.

  12. 6.9 Data Description Clauses, for information on the usage of the various data description clauses.

6.3 WORKING-STORAGE SECTION

WORKING-STORAGE-SECTION-Data-Item Syntax

level-number [ identifier-1 | FILLER ] [ IS GLOBAL | EXTERNAL ]
                              ~~~~~~        ~~~~~~   ~~~~~~~~
[ BASED ]
  ~~~~~
[ BLANK WHEN ZERO ]
  ~~~~~      ~~~~
[ JUSTIFIED RIGHT ]
  ~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
  ~~~~~~             ~~   UNBOUNDED
                          ~~~~~~~~~
      [ DEPENDING ON identifier-2 ]
        ~~~~~~~~~
      [ ASCENDING|DESCENDING KEY IS identifier-3 ]
        ~~~~~~~~~ ~~~~~~~~~~
      [ INDEXED BY identifier-4 ] ]
        ~~~~~~~
[ PICTURE IS picture-string ]
  ~~~
[ REDEFINES identifier-5 ]
  ~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
  ~~~~    ~~~~~~~ ~~~~~~~~   ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
  ~~~~        ~~~~           ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
  ~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ WORKING-STORAGE-SECTION-Data-Item ]...
  ~~~~~      ~~~

The 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.

  1. The reserved words BY, CHARACTER, IS, KEY, ON, RIGHT (JUSTIFIED), TIMES and WHEN are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program.

  2. The reserved words SYNCHRONIZED and SYNCHRONISED are interchangeable. Both may be abbreviated as SYNC.

  3. The reserved word PICTURE may be abbreviated to PIC.

  4. The reserved word JUSTIFIED may be abbreviated to JUST.

  5. As the syntax diagram shows, the definition of a <WORKING-STORAGE-SECTION-Data-Item> is a recursive one in that there may be any number of such specifications coded following one another. The first such specification must have a level number of 01. Specifications that follow that one may have level numbers greater than 01, in which case they are defining a hierarchical breakdown of a record. The definition of a record is terminated when one of the following occurs:

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

    • A 77-level item is found — this signifies the end of the definition of the record and begins the definition of a special data item; 6.8.3 77-Level Data Items, for more information.

    • A division or section header is found — this also marks the completion of a record and signifies the end of the working-storage section as well.

  6. Every <WORKING-STORAGE-SECTION-Data-Item> description must be terminated with a period.

  7. The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 01 through 49 are used to define data items that may be part of a hierarchical structure. Level number 01 can also be used to define a constant — an item with an unchangeable value specified at compilation time.

  8. Level numbers 66, 77, 78 and 88 all have special uses — 6.8 Special Data Items, for details.

  9. Not specifying an <identifier-1> or FILLER immediately after the level number has the same effect as if FILLER were specified. A data item named FILLER cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item or to describe a group item whose contents which will only be referenced using the names of those items that belong to it.

  10. Data items defined within the working-storage section are automatically initialized once — as the program in which the data is defined is loaded into memory. Subprograms may be loaded into memory more than once (see the CANCEL statement ( 7.8.6 CANCEL)), in which case initialization will happen each time they are loaded. 2.1.14 Data Initialization, for a discussion of the initialization rules.

  11. 6.9 Data Description Clauses, for information on the usage of the various data description clauses.

6.4 LOCAL-STORAGE SECTION

LOCAL-STORAGE-SECTION-Data-Item Syntax

level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ]
                              ~~~~~~        ~~~~~~ ~~~~~~~~
[ BASED ]
  ~~~~~
[ BLANK WHEN ZERO ]
  ~~~~~      ~~~~
[ JUSTIFIED RIGHT ]
  ~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
  ~~~~~~             ~~   UNBOUNDED
                          ~~~~~~~~~
      [ DEPENDING ON identifier-2 ]
        ~~~~~~~~~
      [ ASCENDING|DESCENDING KEY IS identifier-3 ]
        ~~~~~~~~~ ~~~~~~~~~~
      [ INDEXED BY identifier-4 ] ]
        ~~~~~~~
[ PICTURE IS picture-string ]
  ~~~
[ REDEFINES identifier-5 ]
  ~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
  ~~~~    ~~~~~~~ ~~~~~~~~   ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
  ~~~~        ~~~~           ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
  ~~~~~
[ VALUE IS [ ALL ] literal-1 ] . [ LOCAL-STORAGE-SECTION-Data-Item ]...
  ~~~~~      ~~~

The 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. 2.1.14 Data Initialization, for the rules of data initialization.

  1. The reserved words BY, CHARACTER IS, KEY, ON, RIGHT (JUSTIFIED), TIMES and WHEN are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program.

  2. The reserved words SYNCHRONIZED and SYNCHRONISED are interchangeable. Both may be abbreviated as SYNC.

  3. The reserved word PICTURE may be abbreviated to PIC.

  4. The reserved word JUSTIFIED may be abbreviated to JUST.

  5. As the syntax diagram shows, the definition of a <LOCAL-STORAGE-SECTION-Data-Item> is a recursive one in that there may be any number of such specifications coded following one another. The first such specification must have a level number of 01. Specifications that follow that one may have level numbers greater than 01, in which case they are defining a hierarchical breakdown of a record. The definition of a record is terminated when one of the following occurs:

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

    • A division or section header is found — this also marks the completion of a record and signifies the end of the local-storage section as well.

  6. Every <LOCAL-STORAGE-SECTION-Data-Item> description must be terminated with a period.

  7. The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 01 through 49 are used to define data items that may be part of a hierarchical structure. Level number 01 can also be used to define a constant — an item with an unchangeable value specified at compilation time.

  8. Level numbers 66, 77, 78 and 88 all have special uses — 6.8 Special Data Items, for details.

  9. Not specifying an <identifier-1> or FILLER immediately after the level number has the same effect as if FILLER were specified. A data item named FILLER cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item or to describe a group item whose contents which will only be referenced using the names of those items that belong to it.

  10. Local-storage cannot be used in nested subprograms.

  11. 6.9 Data Description Clauses, for information on the usage of the various data description clauses.

6.5 LINKAGE SECTION

LINKAGE-SECTION-Data-Item Syntax

level-number [ identifier-1 | FILLER ] [ IS GLOBAL|EXTERNAL ]
                              ~~~~~~        ~~~~~~ ~~~~~~~~
[ ANY LENGTH ]
  ~~~ ~~~~~~
[ ANY NUMERIC ]
  ~~~ ~~~~~~~
[ BASED ]
  ~~~~~
[ BLANK WHEN ZERO ]
  ~~~~~      ~~~~
[ JUSTIFIED RIGHT ]
  ~~~~
[ OCCURS [ integer-1 TO ] integer-2 TIMES
  ~~~~~~             ~~
      [ DEPENDING ON identifier-3 ]
        ~~~~~~~~~
      [ ASCENDING|DESCENDING KEY IS identifier-4 ]
        ~~~~~~~~~ ~~~~~~~~~~
      [ INDEXED BY identifier-5 ] ]
        ~~~~~~~
[ PICTURE IS picture-string ]
  ~~~
[ REDEFINES identifier-6 ]
  ~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
  ~~~~    ~~~~~~~ ~~~~~~~~   ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
  ~~~~        ~~~~           ~~~~ ~~~~~
[ USAGE IS data-item-usage ] . [ LINKAGE-SECTION-Data-Item ]...
  ~~~~~

The 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.

  1. The reserved words BY, CHARACTER, IS, KEY, ON and WHEN are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program.

  2. The reserved words SYNCHRONIZED and “SYNCHRONISED“ are interchangeable. Both may be abbreviated as SYNC.

  3. The reserved word PICTURE may be abbreviated to PIC.

  4. The reserved word JUSTIFIED may be abbreviated to JUST.

  5. As the syntax diagram shows, the definition of a <LINKAGE-SECTION-Data-Item> is a recursive one in that there may be any number of such specifications coded following one another. The first such specification must have a level number of 01. Specifications that follow that one may have level numbers greater than 01, in which case they are defining a hierarchical breakdown of a record. The definition of a record is terminated when one of the following occurs:

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

    • A division or section header is found — this also marks the completion of a record and signifies the end of the linkage section as well.

  6. Every <LINKAGE-SECTION-Data-Item> description must be terminated with a period.

  7. The only valid level numbers are 01-49, 66, 77, 78 and 88. Level numbers 01 through 49 are used to define data items that may be part of a hierarchical structure. Level number 01 can also be used to define a constant — an item with an unchangeable value specified at compilation time.

  8. Level numbers 66, 77, 78 and 88 all have special uses — 6.8 Special Data Items, for details.

  9. It is expected that:

    1. A linkage section should occur only within a subprogram. The compiler will not prevent its use in a main program, however.

    2. All 01-level data items described within a subprogram’s linkage section should appear in a PROCEDURE DIVISION USING ( 7.1 PROCEDURE DIVISION USING) or as arguments on an ENTRY statement.

    3. Each 01-level data item described within a subprogram’s linkage section should correspond to an argument passed on a CALL statement ( 7.8.5 CALL) or an argument on a function call to the subprogram.

  10. Not specifying an <identifier-1> or FILLER immediately after the level number has the same effect as if FILLER were specified. A data item named FILLER cannot be referenced directly; these items are generally used to specify an unused portion of the total storage allocated to a group item or to describe a group item whose contents which will only be referenced using the names of those items that belong to it. In the linkage section, 01-level data items cannot be named FILLER.

  11. No storage is allocated for data defined in the linkage section; the data descriptions there are merely defining storage areas that will be passed to the subprogram by a calling program. Therefore, any discussion of the default initialization of such data is irrelevant. It is possible, however, to manually allocate linkage section data items that aren’t subprogram arguments via the ALLOCATE statement ( 7.8.3 ALLOCATE) statement. In such cases, initialization will take place as per the documentation of that statement.

  12. 6.9 Data Description Clauses, for information on the usage of the various data description clauses.

6.6 REPORT SECTION

REPORT SECTION Syntax

[ REPORT SECTION.
  ~~~~~~ ~~~~~~~
  { Report-Description [ { Report-Group-Definition } ]... }... ]
  {                      { 01-Level-Constant       }      }
  {                      { 78-Level-Constant       }      }
  { 01-Level-Constant                                     }
  { 78-Level-Constant                                     }

Report-Description (RD) Syntax

RD report-name [ IS GLOBAL ]
~~                  ~~~~~~
[ CODE IS literal-1 | identifier-1 ]
  ~~~~
[ { CONTROL IS   } { FINAL        }... ]
  { ~~~~~~~      } { ~~~~~        }
  { CONTROLS ARE } { identifier-2 }
    ~~~~~~~~
[ PAGE [ { LIMIT IS   } ] [ { literal-2    } LINES ]
  ~~~~   { ~~~~~      }     { identifier-3 } ~~~~
         { LIMITS ARE }
           ~~~~~~
      [ literal-3 | identifier-4 COLUMNS|COLS ]
                                 ~~~~~~~ ~~~~
      [ HEADING IS literal-4 | identifier-5 ]
        ~~~~~~~
      [ FIRST DE|DETAIL IS literal-5 | identifier-6 ]
        ~~~~~ ~~ ~~~~~~
      [ LAST CH|{CONTROL HEADING} IS literal-6 | identifier-7 ]
        ~~~~ ~~  ~~~~~~~ ~~~~~~~
      [ LAST DE|DETAIL IS literal-7 | identifier-8 ]
        ~~~~ ~~ ~~~~~~
      [ FOOTING IS literal-8 | identifier-9 ] ] .
        ~~~~~~~

This section describes the layout of printed reports as well as many of the functional aspects of the generation of reports that will be produced via the Report Writer Control System. It is important to maintain the order of these clauses and ensure that all fields defined or referenced with this section are actually defined in the WORKING-STORAGE SECTION and not elsewhere.

  1. The reserved words ARE and IS are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The phrases CONTROL IS and CONTROLS ARE are interchangeable, as are the PAGE LIMIT and PAGE LIMITS phrases.

  3. The reserved word LINES may be abbreviated as LINE.

  4. The reserved word COLUMNS may be abbreviated as COLS.

  5. Each report referenced on a REPORT IS clause ( 6.2.1 File/Sort-Description) must be described with a report description (RD).

  6. 6.9.23 GLOBAL, for information on the GLOBAL option.

  7. Please see 2.1.13 Report Writer Features, if you have not read it already. It will familiarize you with the Report Writer terminology that follows.

  8. The following rules pertain to the PAGE LIMITS clause:

    1. If no PAGE LIMITS clause is specified, the entire report will be generated as if it consists of a single arbitrarily long page.

    2. All literals (<literal-2> through <literal-8>) must be numeric with non-zero positive integer values.

    3. All identifiers (<identifier-2> through <identifier-8>) must be numeric, unedited with non-zero positive integer values.

    4. 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 TOP and LINES AT BOTTOM values specified on the LINAGE clause of the FD this RD is linked to — 6.2.1 File/Sort-Description).

    5. Any value specified for <literal-3> or <identifier-3> will be ignored.

    6. The HEADING clause defines the first line number at which a report heading or page heading may be presented.

    7. The FIRST DETAIL clause defines the first line at which a detail group may be presented.

    8. The LAST CONTROL HEADING clause defines the last line at which any line of a control heading may be presented.

    9. The LAST DETAIL clause defines the last line at which any line of a detail group may be presented.

    10. The FOOTING clause defines the last line at which any line of a control footing group may be presented.

    11. The following rules establish default values for the various PAGE LIMIT clauses, assuming there is one:

      • HEADING

        default is one (1)

      • FIRST DETAIL HEADING

        value is used

      • LAST CONTROL HEADING

        value from LAST DETAIL or, if that is absent, the value from FOOTING or, if that too is absent, the value from PAGE LIMIT

      • LAST DETAIL

        value from FOOTING or, if that is absent, the value from PAGE LIMIT

      • FOOTING

        value from LAST DETAIL or, if that is absent, the value from PAGE LIMIT

    12. For the values specified on a PAGE LIMIT clause to be valid, all of the following must be true:

      • FIRST DETAIL \(\leq\) HEADING

      • LAST CONTROL HEADING \(\leq\) FIRST DETAIL

      • LAST DETAIL \(\leq\) LAST CONTROL HEADING

      • FOOTING \(\leq\) LAST DETAIL

  9. The following rules pertain to the CONTROL clause:

    1. If there is no CONTROL clause, the report will contain no control breaks; this implies that there can be no CONTROL HEADING or CONTROL FOOTING report groups defined for this RD.

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

    3. If you specify FINAL, it must be the first control break named in the RD.

    4. Any <identifier-9> specifications included on the CONTROL clause are referencing data names defined in any data division section except for the report section.

    5. There must be a CONTROL HEADING and/or CONTROL FOOTING report group defined in the report section for each <identifier-9>.

    6. At execution time:

      • Each time a GENERATE statement ( 7.8.20 GENERATE) is executed against a detail report group defined for this RD, the RWCS will check the contents of each <identifier-2> data item; whenever an <identifier-9>’s value has changed since the previous GENERATE, a control break condition will be in effect for that <identifier-2>.

      • Once the list of control breaks has been determined, the CONTROL FOOTING for each <identifier-2> having a control break (if any such report group is defined) will be presented.

      • Next, the CONTROL HEADING for each <identifier-2> having a control break (if any such report group is defined) will be presented.

      • The CONTROL FOOTING and CONTROL HEADING report groups will be presented in the sequence in which they are listed on the CONTROL clause.

      • Only after this processing has occurred will the detail report group specified on the GENERATE be presented.

  10. Each RD will have the following allocated for it:

    1. The PAGE-COUNTER special register ( 7.7 Special Registers), which will contain the current report page number.

      • This register will be set to a value of 1 when an INITIATE statement ( 7.8.25 INITIATE) is executed for the report and will be incremented by 1 each time the RWCS starts a new page of the report.

      • References to PAGE-COUNTER within the report section will be implicitly qualified with the name of the report to which the report group referencing the register belongs.

      • References to PAGE-COUNTER in the procedure division must be qualified with the appropriate report name if there are multiple RDs defined.

    2. The

      LINE-COUNTER special register, which will contain the current line number on the current page.

  11. The RD must be followed by at least one 01-level report group definition.

6.6.1 Report Group Definitions

Report-Group-Definition Syntax

01 [ identifier-1 ]

[ LINE NUMBER IS { integer-1 [ [ ON NEXT PAGE ] } ]
  ~~~~           {                  ~~~~ ~~~~   }
                 { +|PLUS integer-1             }
                 {   ~~~~                       }
                 { ON NEXT PAGE                 }
                      ~~~~ ~~~~
[ NEXT GROUP IS { [ +|PLUS ] integer-2  } ]
  ~~~~ ~~~~~    {     ~~~~              }
                { NEXT|{NEXT PAGE}|PAGE }
                  ~~~~  ~~~~ ~~~~  ~~~~
[ TYPE IS { RH|{REPORT HEADING}                      } ]
  ~~~~    { ~~  ~~~~~~ ~~~~~~~                       }
          { PH|{PAGE HEADING}                        }
          { ~~  ~~~~ ~~~~~~~                         }
          { CH|{CONTROL HEADING} FINAL|identifier-2  }
          { ~~  ~~~~~~~ ~~~~~~~  ~~~~~               }
          { DE|DETAIL                                }
          { ~~ ~~~~~~                                }
          { CF|{CONTROL FOOTING} FINAL|identifier-2  }
          { ~~  ~~~~~~~ ~~~~~~~  ~~~~~               }
          { PF|{PAGE FOOTING}                        }
          {  ~~ ~~~~ ~~~~~~~                         }
          { RF|{REPORT FOOTING}                      }
            ~~  ~~~~~~ ~~~~~~~
. [ REPORT-SECTION-Data-Item ]...

The syntax shown here documents how a report group is defined to a report. This syntax is valid only in the report section, and only then after an RD.

  1. The reserved words IS, NUMBER and ON are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The RH and REPORT HEADING terms are interchangeable, as are PH and PAGE HEADING, CH and CONTROL HEADING, DE and DETAIL, CF and CONTROL FOOTING, PF and PAGE FOOTING as well as RF and REPORT FOOTING.

  3. The report group being defined will be a part of the most-recently coded RD.

  4. The TYPE ( 6.9.56 TYPE) clause specifies the type of report group being defined.

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

  6. The optional <identifier-1> specification assigns a name to this report group so that the group may be referenced either by a GENERATE statement or on a USE BEFORE REPORTING.

  7. No two report groups in the same report (RD) may named with the same <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.

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

  9. Report group declarations must be followed by at least one <REPORT-SECTION-Data-Item> with a level number in the range 02-49.

  10. 6.9 Data Description Clauses, for information on the usage of the various data description clauses.

6.6.2 REPORT SECTION Data Items

REPORT-SECTION-Data-Item Syntax

level-number [ identifier-1 ]

[ BLANK WHEN ZERO ]
  ~~~~~      ~~~~
[ COLUMN [ { NUMBER IS   } ] [ +|PLUS ] integer-1 ]
  ~~~      { ~~~~~~      }       ~~~~
           { NUMBERS ARE }
             ~~~~~~~
[ GROUP INDICATE ]
  ~~~~~ ~~~~~~~~
[ JUSTIFIED RIGHT ]
  ~~~~
[ LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] } ]
  ~~~~           { +|PLUS integer-2 ~~~~ ~~~~   }
                 {   ~~~~                       }
                 { ON NEXT PAGE                 }
                      ~~~~ ~~~~
[ OCCURS [ integer-3 TO ] integer-4 TIMES
  ~~~~~~             ~~   UNBOUNDED
                          ~~~~~~~~~
    [ DEPENDING ON identifier-2 ]
      ~~~~~~~~~
    [ STEP integer-5 ]
      ~~~~
    [ VARYING identifier-3 FROM { identifier-4 } BY { identifier-5 } ]
      ~~~~~~~              ~~~~ { integer-6    } ~~ { integer-7    }
[ PICTURE IS picture-string ]
  ~~~
[ PRESENT WHEN condition-name ]
  ~~~~~~~ ~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
  ~~~~    ~~~~~~~ ~~~~~~~~   ~~~~~~~~
[ { SOURCE IS literal-1|identifier-6 [ ROUNDED ]                   } ]
  { ~~~~~~                             ~~~~~~~                     }
  { SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ] }
  { ~~~    { literal-2    }      { ~~~~~    ~~~~~              }   }
  { VALUE IS [ ALL ] literal-3   { UPON identifier-9           }   }
    ~~~~~      ~~~                 ~~~~
. [ REPORT-SECTION-Data-Item ]...

Data item descriptions describing the report lines and fields that make up the substance of a report group immediately follow the definition of that group.

  1. The reserved words IS, NUMBER, OF, ON, RIGHT, TIMES and WHEN (BLANK) are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The reserved word COLUMN may be abbreviated as COL.

  3. The reserved word JUSTIFIED may be abbreviated as JUST.

  4. The reserved word PICTURE may be abbreviated as PIC.

  5. The SOURCE ( 6.9.51 SOURCE), SUM ( 8.1.92 SUM) and VALUE ( 6.9.63 VALUE) clauses, valid only on an elementary item, are mutually-exclusive of each other.

  6. Group items (those without PICTURE clauses) are frequently used to describe entire lines of a report, while elementary items (those with a picture clause) are frequently used to describe specific fields of information on the report. When this coding convention is being used, group items will have LINE ( 6.9.29 LINE) clauses and no COLUMN ( 6.9.14 COLUMN) clauses while elementary items will be specified the other way around.

  7. 6.9 Data Description Clauses, for information on the usage of the various data description clauses.

6.7 SCREEN SECTION

SCREEN-SECTION-Data-Item Syntax

level-number [ identifier-1 | FILLER ]
                              ~~~~~~

[ AUTO | AUTO-SKIP | AUTOTERMINATE ] [ BELL | BEEP ]
  ~~~~   ~~~~~~~~~   ~~~~~~~~~~~~~     ~~~~   ~~~~
[ BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1 | identifier-2 ]
  ~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
[ BEFORE TIME | BASED ]
  ~~~~~~ ~~~~   ~~~~~
[ BLANK LINE|SCREEN ] [ ERASE EOL|EOS ]
  ~~~~~ ~~~~ ~~~~~~     ~~~~~ ~~~ ~~~
[ BLANK WHEN ZERO ] [ JUSTIFIED RIGHT ]
  ~~~~~      ~~~~     ~~~~
[ BLINK ] [ HIGHLIGHT | LOWLIGHT ] [ REVERSE-VIDEO ]
  ~~~~~     ~~~~~~~~~   ~~~~~~~~     ~~~~~~~~~~~~~
[ COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ]
  ~~~                  ~~~~
[ CONSTANT | EMPTY CHECK ]
  ~~~~~~~    ~~~~~ ~~~~~
[ FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-3 | identifier-4 ]
  ~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
[ { FROM literal-1 | identifier-5 } ]
  { ~~~~                          }
  { TO identifier-5               }
  { ~~                            }
  { USING identifier-5            }
  { ~~~~~                         }
  { VALUE IS [ ALL ] literal-1    }
    ~~~~~      ~~~
[ FULL | LENGTH-CHECK ] [ REQUIRED | EMPTY-CHECK ] [ SECURE | NO-ECHO ]
  ~~~~   ~~~~~~~~~~~~     ~~~~~~~~   ~~~~~~~~~~~     ~~~~~~   ~~~~~~~
[ LEFTLINE ] [ OVERLINE ] [ UNDERLINE ]
  ~~~~~~~~     ~~~~~~~~     ~~~~~~~~~
[ LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ]
  ~~~~               ~~~~
[ NO-ECHO | NO UPDATE ]
  ~~~~~~~   ~~ ~~~~~
[ OCCURS integer-5 TIMES ]
  ~~~~~~
[ PICTURE IS picture-string ]
  ~~~
[ PROMPT [ CHARACTER IS literal-2 | identifier-7 ]
  ~~~~~~   ~~~~~~~~~
[ SCROLL DOWN | SCROLL UP | SIZE | TIME OUT ]
  ~~~~~~ ~~~~   ~~~~~~ ~~   ~~~~   ~~~~ ~~~


[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
  ~~~~    ~~~~~~~ ~~~~~~~~   ~~~~~~~~
[ UPDATE ]
  ~~~~~~
. [ SCREEN-SECTION-Data-Item ]...

The screen section describes the screens to be displayed during terminal/console I-O.

  1. The reserved words CHARACTER (SEPARATE clause), IS, NUMBER, RIGHT, TIMES and WHEN are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The reserved word COLUMN may be abbreviated as COL.

  3. The reserved word PICTURE may be abbreviated as PIC.

  4. The following sets of reserved words are interchangeable:

    • AUTO, AUTO-SKIP and AUTOTERMINATE

    • BACKGROUND-COLOR and BACKGROUND-COLOUR

    • BELL and BEEP

    • FOREGROUND-COLOR and FOREGROUND-COLOUR

    • FULL and LENGTH-CHECK

    • REQUIRED and EMPTY-CHECK

    • SECURE and NO-ECHO

  5. Data items defined in the screen section describe input, output or combination screen layouts to be used with ACCEPT data-item statement ( 7.8.1.4 ACCEPT data-item) or DISPLAY data-item statement ( 7.8.12.4 DISPLAY data-item) statements. These screen layouts may define the entire available screen area or any subset of it.

  6. The term available screen area is a nebulous one in those environments where command-line shell sessions are invoked within a graphical user-interface environment, as will be the case on Windows, OSX and most Unix/Linux systems — these environments allow command-line session windows to exist with a variable number of available screen rows and columns. When you are designing GnuCOBOL screens, you need to do so with an awareness of the logical screen row/column geometry the program will be executing within.

  7. Data items with level numbers 01 (Constants), 66, 78 and 88 may be used in the screen section; they have the same syntax, rules and usage as they do in the other data division sections.

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

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

  10. The Tab and Back-Tab (Shift-Tab on most keyboards) keys will position the cursor from field to field in the line/column sequence in which the fields occur on the screen at execution time, regardless of the sequence in which they were defined in the screen section.

  11. 6.9 Data Description Clauses, for information on the usage of the various data description clauses.

6.8 Special Data Items

6.8.1 01-Level Constants

01-Level-Constant Syntax

01 constant-name-1 CONSTANT [ IS GLOBAL ]
                   ~~~~~~~~      ~~~~~~
  { AS { literal-1                           } }
  {    { arithmetic-expression-1             } }
  {    { { BYTE-LENGTH } OF { identifier-1 } } }
  {    { { ~~~~~~~~~~~ }    { usage-name   } } }
  {    { { LENGTH      }                     } }
  {        ~~~~~~                              }
  { FROM CDF-variable-name-1                   }
    ~~~~

This syntax is valid in the following sections: 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 ( 3.4 >>DEFINE) constants, >>SET CDF directive ( 3.6 >>SET) constants, 78-level constants ( 6.8.4 78-Level Data Items and arithmetic-expression-1).

  1. The reserved words AS, IS and OF are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. 6.9.23 GLOBAL, for information on the GLOBAL option.

  3. This particular type of constant declaration provides the ability to determine the length of a data item or the storage size associated with a particular numeric USAGE ( 6.9.61 USAGE) type — something not possible with the other types of constants.

  4. Constants defined in this way become undefined once an END PROGRAM or END FUNCTION is encountered in the input source.

  5. Data descriptions of this form do not actually allocate any storage — they merely define a name (<constant-name-1>) that may be used anywhere a numeric literal (see BYTE-LENGTH or LENGTH options) or a literal of the same type as <literal-1> may be used.

  6. The <constant-name-1> name may not be referenced on a CDF directive.

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

  8. The value specified for <usage-name> may be any USAGE that does not use a PICTURE ( 6.9.37 PICTURE) clause. These would be any of BINARY-C-LONG, BINARY-CHAR, BINARY-DOUBLE, BINARY-LONG, BINARY-SHORT, COMP-1 (or COMPUTATIONAL-1), COMP-2 (or COMPUTATIONAL-2), FLOAT-DECIMAL-16, FLOAT-DECIMAL-34, FLOAT-LONG, FLOAT-SHORT, POINTER, or PROGRAM-POINTER.

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

  10. The LENGTH clause will produce a numeric value for <constant-name-1> identical to that which would be returned by the LENGTH intrinsic function executed against <identifier-1> or a data item declared with a USAGE of <usage-name>.

Here is usage examples of the option arithmetic-expression

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

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

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

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

IDENTIFICATION DIVISION.
PROGRAM-ID. Usage-Lengths.
DATA DIVISION.
WORKING-STORAGE SECTION.
01  Len-BINARY-C-LONG    CONSTANT AS LENGTH OF BINARY-C-LONG.
01  Len-BINARY-CHAR      CONSTANT AS LENGTH OF BINARY-CHAR.
01  Len-BINARY-DOUBLE    CONSTANT AS LENGTH OF BINARY-DOUBLE.
01  Len-BINARY-LONG      CONSTANT AS LENGTH OF BINARY-LONG.
01  Len-BINARY-SHORT     CONSTANT AS LENGTH OF BINARY-SHORT.
01  Len-COMP-1           CONSTANT AS LENGTH OF COMP-1.
01  Len-COMP-2           CONSTANT AS LENGTH OF COMP-2.
01  Len-FLOAT-DECIMAL-16 CONSTANT AS LENGTH OF FLOAT-DECIMAL-16.
01  Len-FLOAT-DECIMAL-34 CONSTANT AS LENGTH OF FLOAT-DECIMAL-34.
01  Len-FLOAT-LONG       CONSTANT AS LENGTH OF FLOAT-LONG.
01  Len-FLOAT-SHORT      CONSTANT AS LENGTH OF FLOAT-SHORT.
01  Len-POINTER          CONSTANT AS LENGTH OF POINTER.
01  Len-PROGRAM-POINTER  CONSTANT AS LENGTH OF PROGRAM-POINTER.
PROCEDURE DIVISION.
000-Main.
    DISPLAY "On this system, with this build of GnuCOBOL, the"
    DISPLAY "PICTURE-less USAGE's have these lengths (in bytes):"
    DISPLAY " "
    DISPLAY "BINARY-C-LONG:    " Len-BINARY-C-LONG
    DISPLAY "BINARY-CHAR:      " Len-BINARY-CHAR
    DISPLAY "BINARY-DOUBLE:    " Len-BINARY-DOUBLE
    DISPLAY "BINARY-LONG:      " Len-BINARY-LONG
    DISPLAY "BINARY-SHORT:     " Len-BINARY-SHORT
    DISPLAY "COMP-1:           " Len-COMP-1
    DISPLAY "COMP-2:           " Len-COMP-2
    DISPLAY "FLOAT-DECIMAL-16: " Len-FLOAT-DECIMAL-16
    DISPLAY "FLOAT-DECIMAL-34: " Len-FLOAT-DECIMAL-34
    DISPLAY "FLOAT-LONG:       " Len-FLOAT-LONG
    DISPLAY "FLOAT-SHORT:      " Len-FLOAT-SHORT
    DISPLAY "POINTER:          " Len-POINTER
    DISPLAY "PROGRAM-POINTER:  " Len-PROGRAM-POINTER
    STOP RUN.

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

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

    BINARY-C-LONG:    4
    BINARY-CHAR:      1
    BINARY-DOUBLE:    8
    BINARY-LONG:      4
    BINARY-SHORT:     2
    COMP-1:           4
    COMP-2:           8
    FLOAT-DECIMAL-16: 8
    FLOAT-DECIMAL-34: 16
    FLOAT-LONG:       8
    FLOAT-SHORT:      4
    POINTER:          4
    PROGRAM-POINTER:  4

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

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

BINARY-C-LONG:    8
BINARY-CHAR:      1
BINARY-DOUBLE:    8
BINARY-LONG:      4
BINARY-SHORT:     2
COMP-1:           4
COMP-2:           8
FLOAT-DECIMAL-16: 8
FLOAT-DECIMAL-34: 16
FLOAT-LONG:       8
FLOAT-SHORT:      4
POINTER:          8
PROGRAM-POINTER:  8

Spot the differences between 32 and 64 bit.

6.8.2 66-Level Data Items

66-Level-Data-Item Syntax

66 identifier-1 RENAMES identifier-2 [ THRU|THROUGH identifier-3 ] .
                ~~~~~~~                ~~~~ ~~~~~~~

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

A 66-level data item regroups previously defined items by specifying alternative, possibly overlapping, groupings of elementary data items.

  1. The reserved words THRU and THROUGH are interchangeable.

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

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

  4. All RENAMES entries associated with one logical record must immediately follow that record’s last data description entry.

6.8.3 77-Level Data Items

77-Level-Data-Item Syntax

77 identifier-1 [ IS GLOBAL|EXTERNAL ]
                     ~~~~~~ ~~~~~~~~
[ BASED ]
  ~~~~~
[ BLANK WHEN ZERO ]
  ~~~~~      ~~~~
[ JUSTIFIED RIGHT ]
  ~~~~
[ PICTURE IS picture-string ]
  ~~~
[ REDEFINES identifier-5 ]
  ~~~~~~~~~
[ SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ] ]
  ~~~~    ~~~~~~~ ~~~~~~~~   ~~~~~~~~
[ SYNCHRONIZED|SYNCHRONISED [ LEFT|RIGHT ] ]
  ~~~~        ~~~~           ~~~~ ~~~~~
[ USAGE IS data-item-usage ]
  ~~~~~
[ VALUE IS [ ALL ] literal-1 ] .
  ~~~~~      ~~~

The 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.

  1. The reserved words CHARACTER, IS, RIGHT (JUSTIFIED) and WHEN are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The reserved word JUSTIFIED may be abbreviated as JUST, the reserved word PICTURE may be abbreviated as PIC and the reserved words SYNCHRONIZED and SYNCHRONISED may be abbreviated as SYNC.

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

  4. 6.9 Data Description Clauses, for information on the usage of the various data description clauses.

6.8.4 78-Level Data Items

78-Level-Constant Syntax

78 constant-name-1 VALUE IS ( literal-1                           )
                   ~~~~~
                            { arithmetic-expression-1             }

This syntax is valid in the following sections: 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 ( 3.4 >>DEFINE) constants, >>SET CDF directive ( 3.6 >>SET) constants and 01-level constants ( 6.8.1 01-Level Constants).

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. Constants defined in this way become undefined once an END PROGRAM or END FUNCTION is encountered in the input source.

  3. Data descriptions of this form do not actually allocate any storage — they merely define a name (<constant-name-1>) that may be used anywhere a literal of the same type as <literal-1> may be used.

  4. The <constant-name-1> name may not be referenced on a CDF directive.

  5. 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.

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

6.8.5 88-Level Data Items

88-Level-Data-Item Syntax

88 condition-name-1 { VALUE IS   } {literal-1 [ THRU|THROUGH literal-2 ]}...
                    { ~~~~~      }              ~~~~ ~~~~~~~
                    { VALUES ARE }
                      ~~~~~~

  [ WHEN SET TO FALSE IS literal-3 ] .
                ~~~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN

Condition names are Boolean (i.e. TRUE / FALSE) data items that receive their TRUE and FALSE values based upon the values of the non 88-level data item whose definition they immediately follow.

  1. The reserved words ARE, IS, SET and TO are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The reserved words THRU and THROUGH are interchangeable.

  3. Condition names are always defined subordinate to another (non 88-level) data item. That data item must be an elementary item. Whenever the parent data item assumes one of the values specified on the 88-level item’s VALUE ( 6.9.63 VALUE) clause, <condition-name-1> will take on the value of TRUE.

  4. Condition names do not occupy any storage.

  5. The optional THROUGH clause allows a range of possible TRUE values to be specified.

  6. Whenever the parent data item assumes any value except one of the values specified on <condition-name-1>’s VALUE clause, <condition-name-1> will take on the value of FALSE.

  7. Executing the statement SET <condition-name-1> TO TRUE will cause <condition-name-1>’s parent data item to take on the first value specified on <condition-name-1>’s VALUE clause.

  8. Executing the statement SET <condition-name-1> TO FALSE will cause <condition-name-1>’s parent data item to take on the value specified on <condition-name-1>’s FALSE clause. If <condition-name-1> does not have a FALSE clause, the SET ( 7.8.41 SET) statement will generate an error message at compilation time.

  9. 2.2.5 Condition Names, for more information.

6.9 Data Description Clauses

6.9.1 ANY LENGTH

ANY LENGTH Attribute Syntax

ANY LENGTH
~~~ ~~~~~~

This syntax is valid in the following sections: LINKAGE

Data items declared with the ANY LENGTH attribute have no fixed compile-time length. Such items may only be defined in the linkage section of a subprogram as they may only serve as subroutine argument descriptions. These items must have a PICTURE ( 6.9.37 PICTURE) clause that specifies exactly one A, X, U or 1 symbol.

  1. The ANY LENGTH and BASED ( 6.9.8 BASED) clauses cannot be used together in the same data item description. The ANY LENGTH clause specifies that the length of the data item will be determined at runtime, the type is determined (and someday checked with EC-PROGRAM-ARGS) by the picture symbol.

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

6.9.2 ANY NUMERIC

ANY NUMERIC Attribute Syntax

ANY NUMERIC
~~~ ~~~~~~~

This syntax is valid in the following sections: LINKAGE

Data items declared with the ANY NUMERIC attribute has no fixed compile-time length. Such items may only be defined in the linkage section of a subprogram as they may only serve as subroutine argument descriptions. These items must have a PICTURE ( 6.9.37 PICTURE) clause that specifies exactly one 9 symbol. The ANY NUMERIC clause specifies that the length and the usage of the data item will be determined at runtime.

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

  1. The ANY NUMERIC and BASED ( 6.9.8 BASED) clauses cannot be used together in the same data item description.

6.9.3 AUTO

AUTO Attribute Syntax

AUTO
~~~~

This syntax is valid in the following sections: SCREEN

A field whose description includes this attribute will cause the cursor to automatically advance to the next input-enabled field of a screen if the field is completely filled with input data.

  1. The AUTO, AUTO-SKIP ( 6.9.4 AUTO-SKIP) and AUTOTERMINATE ( 6.9.5 AUTOTERMINATE) clauses are interchangeable, and may not be used together in the same data item description.

6.9.4 AUTO-SKIP

AUTO-SKIP Attribute Syntax

AUTO-SKIP
~~~~~~~~~

This syntax is valid in the following sections: SCREEN

A field whose description includes this attribute will cause the cursor to automatically advance to the next input-enabled field of a screen if the field is completely filled with input data.

  1. The AUTO ( 6.9.3 AUTO), AUTO-SKIP and AUTOTERMINATE ( 6.9.5 AUTOTERMINATE) clauses are interchangeable, and may not be used together in the same data item description.

6.9.5 AUTOTERMINATE

AUTOTERMINATE Attribute Syntax

AUTOTERMINATE
~~~~~~~~~~~~~

This syntax is valid in the following sections: SCREEN

A field whose description includes this attribute will cause the cursor to automatically advance to the next input-enabled field of a screen if the field is completely filled with input data.

  1. The AUTO ( 6.9.3 AUTO), AUTO-SKIP ( 6.9.4 AUTO-SKIP) and AUTOTERMINATE clauses are interchangeable, and may not be used together in the same data item description.

6.9.6 BACKGROUND-COLOR

BACKGROUND-COLOR Attribute Syntax

BACKGROUND-COLOR|BACKGROUND-COLOUR IS integer-1 | identifier-1
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~

This syntax is valid in the following sections: SCREEN

This clause is used to specify the screen background color of the screen data item or the default screen background color of subordinate items if used on a group item.

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. The reserved words BACKGROUND-COLOR and BACKGROUND-COLOUR are interchangeable.

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

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

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

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.7 BEFORE TIME

BEFORE TIME Attribute Syntax

BEFORE TIME
~~~~~~ ~~~~

This syntax is valid in the following sections: SCREEN

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

6.9.8 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 ( 7.8.3 ALLOCATE) or SET ADDRESS ( 7.8.41.3 SET ADDRESS) statements are used to allocate space for and (optionally) initialize such items.

  1. The BASED and ANY LENGTH ( 6.9.1 ANY LENGTH) clauses cannot be used together in the same data item description.

  2. The BASED clause may only be used on level 01 and level 77 data items.

6.9.9 BEEP

BEEP Attribute Syntax

BEEP
~~~~

This syntax is valid in the following sections: SCREEN

  1. The BEEP and BELL ( 6.9.10 BELL) clauses are interchangeable, and may not be used together in the same data item description.

  2. Use this clause to cause an audible tone to occur when the screen item is DISPLAYed.

6.9.10 BELL

BELL Attribute Syntax

BELL
~~~~

This syntax is valid in the following sections: SCREEN

  1. The BEEP ( 6.9.9 BEEP) and BELL clauses are interchangeable, and may not be used together in the same data item description.

  2. Use this clause to cause an audible tone to occur when the screen item is DISPLAYed.

6.9.11 BLANK

BLANK Attribute Syntax

BLANK LINE|SCREEN
~~~~~ ~~~~ ~~~~~~

This syntax is valid in the following sections: SCREEN

This clause will blank out either the entire screen (BLANK SCREEN) or just the line upon which data is about to be displayed (BLANK LINE).

  1. Blanked-out areas will have their foreground and background colors set to the attributes of the field containing the BLANK clause.

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

6.9.12 BLANK WHEN ZERO

BLANK-WHEN-ZERO Attribute Syntax

BLANK WHEN ZERO
~~~~~      ~~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN

This clause will cause that item’s value to be automatically transformed into spaces if a value of 0 is ever MOVEd to the item.

  1. The reserved word WHEN is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. This clause may only be used on a PIC 9 data item with a USAGE ( 6.9.61 USAGE) of DISPLAY.

6.9.14 COLUMN

COLUMN (REPORT SECTION) Clause Syntax

COLUMN [ { NUMBER IS   } ] [ +|PLUS ] integer-1 ]
~~~      { NUMBERS ARE }       ~~~~

COLUMN (SCREEN SECTION) Clause Syntax

COLUMN NUMBER IS [ +|PLUS ] integer-2 | identifier-3 ]
~~~                  ~~~~

This syntax is valid in the following sections: REPORT, SCREEN

The COLUMN clause provides the means of stating in which column a field should be presented on the console window (screen section) or a report (report section).

  1. The reserved words ARE, IS, NUMBER and NUMBERS are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The reserved word COLUMN may be abbreviated as COL.

  3. The line location of a report section or screen section field will be determined by the LINE ( 6.9.29 LINE) clause.

  4. The value of <integer-1> must be 1 or greater.

  5. 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 ( 6.9.61 USAGE) other than COMPUTATIONAL-1 or COMPUTATIONAL-2, without editing symbols. The value of <identifier-1> at the time the screen data item is presented must be 1 or greater. Note that a COMPUTATIONAL-1 or COMPUTATIONAL-2 identifier will be accepted by the compiler, but will produce unpredictable results at run-time.

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

  7. The symbol ‘+‘ may be used in lieu of the word PLUS, 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 the COLUMN clause as an absolute column specification rather than a relative one.

  8. Using relative column positioning (COLUMN PLUS) has slightly different behaviour depending upon the section in which the clause is used, as follows:

    1. When used on a report section data item, COLUMN PLUS will position the start of the new field’s value such that there are <integer-1> blank columns between the end of the previous field and the beginning of this field.

      If a report data item’s description includes the SOURCE ( 6.9.51 SOURCE), SUM ( 8.1.92 SUM) or VALUE ( 6.9.63 VALUE) clause but has no COLUMN clause, COLUMN PLUS 1 will be assumed.

    2. When used on a screen section data item, COLUMN PLUS will position the new field so that it begins exactly <integer-1> or <identifier-1> characters past the last character of the previous field. Thus, COLUMN PLUS 1 will leave no blank positions between the end of the previous field and the start of this one.

      If a screen data item’s description includes the FROM ( 6.9.21 FROM), TO ( 6.9.55 TO), USING ( 6.9.62 USING) or VALUE ( 6.9.63 VALUE) clause but has no COLUMN clause, the new screen field will begin at the column coordinate of the last character of the previous field.

6.9.15 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.

  1. The value of a data item defined as a constant cannot be changed at run-time. In fact, it is not syntactically acceptable to use such a data item as the destination field of any procedure division statement that stores a value.

  2. 6.8.1 01-Level Constants, for additional information.

6.9.16 EMPTY-CHECK

EMPTY-CHECK Attribute Syntax

EMPTY-CHECK
~~~~~~~~~~~

This syntax is valid in the following sections: SCREEN

This clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if EMPTY-CHECK is specified on a group item).

  1. The EMPTY-CHECK and REQUIRED ( 6.9.43 REQUIRED) clauses are interchangeable, and may not be used together in the same data item description.

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

  3. The ACCEPT data-item statement ( 7.8.1.4 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 the ACCEPT.

  4. 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 EMPTY-CHECK.

6.9.17 ERASE

ERASE Clause Syntax

ERASE EOL|EOS
~~~~~ ~~~ ~~~

This syntax is valid in the following sections: SCREEN

ERASE will blank-out screen contents from the location where the screen data item whose description contains this clause will be displayed, forward until the end of the screen (ERASE EOS)

  1. Erased areas will have their foreground and background colors set to the attributes of the field containing the ERASE clause.

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

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.18 EXTERNAL

EXTERNAL Attribute Syntax

EXTERNAL
~~~~~~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE

This clause marks a data item description, FD or SD 6.2.1 File/Sort-Description as being shareable with other programs executed from the same execution thread.

  1. By specifying the EXTERNAL clause on either an FD or an SD, the file description is capable of being shared between all programs executed from the same execution thread, provided an EXTERNAL clause is coded with the file’s description in each program requiring it. This sharing allows the file to be opened, read and/or written and closed in different programs. This sharing applies to the record descriptions subordinate to the file description too.

  2. By specifying the EXTERNAL clause on the description of a data item, the data item is capable of being shared between all programs executed from the same execution thread, provided the data item is coded (with an EXTERNAL clause) in each program requiring it.

  3. The following points apply to the specification of EXTERNAL in a data item’s definition:

    1. The EXTERNAL clause may only be specified at the 77 or 01 level.

    2. An EXTERNAL item must have a data name and that name cannot be FILLER.

    3. EXTERNAL cannot be combined with BASED ( 6.9.8 BASED), GLOBAL ( 6.9.23 GLOBAL) or REDEFINES ( 6.9.41 REDEFINES).

6.9.19 FALSE

FALSE Clause Syntax

WHEN SET TO FALSE IS literal-1
            ~~~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN

This clause, which may only appear on the definition of a level-88 condition name, is used to specify the value of the data item that serves as the parent of the level-88 condition name that will force the condition name to assume a value of FALSE.

  1. The reserved words IS, SET, TO and WHEN are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. 6.8.5 88-Level Data Items, or 2.2.5 Condition Names, for more information.

6.9.20 FOREGROUND-COLOR

FOREGROUND-COLOR Attribute Syntax

FOREGROUND-COLOR|FOREGROUND-COLOUR IS integer-1 | identifier-1
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~

This syntax is valid in the following sections: SCREEN

This clause is used to specify the color of text within a screen data item or the default text color of subordinate items if used on a group item.

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. The reserved words FOREGROUND-COLOR and FOREGROUND-COLOUR are interchangeable.

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

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

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.21 FROM

FROM Clause Syntax

FROM literal-1 | identifier-5
~~~~

This syntax is valid in the following sections: SCREEN

This clause is used to specify either the data item a screen section field is to obtain its value from when the screen is displayed, or a literal that will specify the value of that same field.

  1. The FROM, TO ( 6.9.55 TO), USING ( 6.9.62 USING) and VALUE ( 6.9.63 VALUE) clauses are mutually-exclusive in any screen section data item’s definition.

6.9.22 FULL

FULL Attribute Syntax

FULL
~~~~

This syntax is valid in the following sections: SCREEN

The FULL clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if specified on a group item) sufficient to fill every character position of the field.

  1. The FULL and LENGTH-CHECK ( 6.9.28 LENGTH-CHECK) clauses are interchangeable, and may not be used together in the same data item description.

  2. In order for this clause to take effect at execution time, the user must move the cursor into the field having this clause in its definition.

  3. The ACCEPT data-item statement ( 7.8.1.4 ACCEPT data-item) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item unless the proper amount of data has been entered into the field. Function keys will still be allowed to terminate the ACCEPT, however.

  4. 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 FULL.

6.9.23 GLOBAL

GLOBAL Attribute Syntax

GLOBAL
~~~~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, REPORT

This clause marks a data item, 01-level constant, FD ( 6.2.1 File/Sort-Description), SD ( 6.2.1 File/Sort-Description) or an RD ( 6.6 REPORT SECTION) as being shareable with any nested subprograms.

  1. By specifying the GLOBAL clause on the description of a file or a report, that description is capable of being shared between a program and any nested subprograms within it, provided the FD, SD or RD is coded (with a GLOBAL clause) in each nested subprogram requiring it. This sharing allows the file to be opened, read and/or written and closed or the report to be initiated or terminated in those programs. Separately compiled programs may not share a GLOBAL file description, but they may share an EXTERNAL ( 6.9.18 EXTERNAL) file description. This sharing applies to the record descriptions subordinate to the file description and the report groups subordinate to the RD also.

  2. By specifying the GLOBAL clause on the description of a data item, the data item is capable of being shared between a program and any nested subprograms within it, provided the data item is coded (with a GLOBAL clause) in each program requiring it.

  3. The following points apply to the specification of GLOBAL in a data item’s definition:

    1. The GLOBAL clause may only be specified at the 77 or 01 level.

    2. A GLOBAL item must have a data name and that name cannot be FILLER.

    3. GLOBAL cannot be combined with EXTERNAL ( 6.9.18 EXTERNAL), REDEFINES ( 6.9.41 REDEFINES) or BASED ( 6.9.8 BASED).

6.9.24 GROUP INDICATE

GROUP-INDICATE Attribute Syntax

GROUP INDICATE
~~~~~ ~~~~~~~~

This syntax is valid in the following sections: REPORT

The GROUP INDICATE clause specifies that the data item in whose definition the clause appears will be presented only in very limited circumstances.

  1. This clause may only appear within a DETAIL report group ( 6.9.56 TYPE).

  2. When this clause is present, the data item in question will be presented only under the following circumstances:

    1. On the first presentation of the detail group following the INITIATE ( 7.8.25 INITIATE) of the report.

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

    3. On the first presentation of the detail group after any control break occurs.

6.9.25 HIGHLIGHT

HIGHLIGHT Attribute Syntax

HIGHLIGHT
~~~~~~~~~

This syntax is valid in the following sections: SCREEN

This clause controls the intensity of text (FOREGROUND-COLOR ( 6.9.20 FOREGROUND-COLOR)) by setting that intensity to its highest of three possible settings.

  1. This clause, along with LOWLIGHT ( 6.9.31 LOWLIGHT), are intended to provide a three-level intensity scheme (LOWLIGHT … nothing (Normal) … HIGHLIGHT).

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.26 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.

  1. The reserved word RIGHT is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. The reserved word JUSTIFIED may be abbreviated as JUST.

  3. This clause is valid only on alphabetic (PIC A) or alphanumeric (PIC X) data items.

  4. The presence or absence of this clause influences the behaviour of the MOVE ( 7.8.28 MOVE) statement as well as the FROM ( 6.9.21 FROM), SOURCE ( 6.9.51 SOURCE) and USING ( 6.9.62 USING) data item description clauses.

  5. If the value being stored into the field is the same length as the receiving field, the presence or absence of the JUSTIFIED RIGHT clause on that field’s description is irrelevant.

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

    When the value is shorter than the field size:

    • Without JUSTIFIED With JUSTIFIED

    • 01  A PIC X(6).
MOVE 'ABC' TO A

      01  A PIC X(6) JUSTIFIED RIGHT.
MOVE 'ABC' TO A

    • Result Result

    • ABC<bbb> <bbb>ABC

    When the value is longer than the field size:

    • Without JUSTIFIED With JUSTIFIED

    • 01  A PIC X(6).
MOVE 'ABCDEFGHI' TO A

      01  A PIC X(6) JUSTIFIED RIGHT.
MOVE 'ABCDEFGHI' TO A

    • Result Result

    • ABCDEFDEFGHI

6.9.27 LEFTLINE

LEFTLINE Attribute Syntax

LEFTLINE
~~~~~~~~

This syntax is valid in the following sections: SCREEN

The LEFTLINE clause will introduce a vertical line at the left edge of a screen field.

  1. The LEFTLINE, OVERLINE ( 6.9.36 OVERLINE) and UNDERLINE ( 6.9.58 UNDERLINE) clauses may be used in any combination in a single field’s description.

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

  3. Whether or not this clause operates on Cygwin or UNIX/Linux/OSX systems will depend upon the video attribute capabilities of the terminal output drivers and “curses” software being used.

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.28 LENGTH-CHECK

LENGTH-CHECK Attribute Syntax

LENGTH-CHECK
~~~~~~~~~~~~

This syntax is valid in the following sections: SCREEN

The LENGTH-CHECK clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if specified on a group item) sufficient to fill every character position of the field.

  1. The FULL ( 6.9.22 FULL) and LENGTH-CHECK clauses are interchangeable, and may not be used together in the same data item description.

  2. In order for this clause to take effect at execution time, the user must move the cursor into the field having this clause in its definition.

  3. The ACCEPT data-item statement ( 7.8.1.4 ACCEPT data-item) will ignore the Enter key and any other cursor-moving keystrokes that would cause the cursor to move to another screen item unless the proper amount of data has been entered into the field. Function keys will still be allowed to terminate the ACCEPT, however.

  4. 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 LENGTH-CHECK.

6.9.29 LINE

LINE (REPORT SECTION) Clause Syntax

LINE NUMBER IS { integer-2 [ [ ON NEXT PAGE ] }
~~~~           {                  ~~~~ ~~~~   }
               { +|PLUS integer-2             }
               {   ~~~~                       }
               { ON NEXT PAGE                 }
                    ~~~~ ~~~~

LINE (SCREEN SECTION) Clause Syntax

[ LINE NUMBER IS [ +|PLUS ] integer-4 | identifier-6 ]
  ~~~~               ~~~~

This syntax is valid in the following sections: REPORT, SCREEN

This clause provides a means of explicitly stating on which line a field should be presented on the console window (screen section) or on a report (report section).

  1. The reserved words IS, NUMBER and ON are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The following points document the use of format 1 of the LINE clause:

    1. The column location of a report item will be determined by the COLUMN ( 6.9.14 COLUMN) clause.

    2. The value of <integer-1> must be 1 or greater.

    3. 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).

    4. The symbol ‘+‘ may be used in lieu of the word PLUS, 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.

    5. The optional NEXT PAGE clause specifies that — regardless of whether or not the report group containing this clause could fit on the report page being currently generated, the report group will be forced to appear on a new page.

  3. The following points document the use for format 2 of the LINE clause:

    1. The column location of a screen section field is determined by the COLUMN ( 6.9.14 COLUMN) clause.

    2. The value of <integer-1> must be 1 or greater.

    3. 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 ( 6.9.61 USAGE) other than COMPUTATIONAL-1 or COMPUTATIONAL-2, without editing symbols. The value of <identifier-1> at the time the screen data item is presented must be 1 or greater. Note that a COMPUTATIONAL-1 or COMPUTATIONAL-2 identifier will be accepted by the compiler, but will produce unpredictable results at run-time.

    4. 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).

    5. The symbol ‘+‘ may be used in lieu of the word PLUS, 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.

    6. If a screen data item’s description includes the FROM ( 6.9.21 FROM), TO ( 6.9.55 TO), USING ( 6.9.62 USING) or VALUE ( 6.9.63 VALUE) clause but has no LINE clause, the “current screen line” will be assumed.

6.9.30 LOWER

LOWER Attribute Syntax

LOWER
~~~~~

This syntax is valid in the following sections: SCREEN

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

6.9.31 LOWLIGHT

LOWLIGHT Attribute Syntax

LOWLIGHT
~~~~~~~~

This syntax is valid in the following sections: SCREEN

The LOWLIGHT clause controls the intensity of text (FOREGROUND-COLOR) by setting that intensity to its lowest of three possible settings.

  1. This clause, along with HIGHLIGHT ( 6.9.25 HIGHLIGHT), are intended to provide a three-level intensity scheme (LOWLIGHT … nothing (Normal) … HIGHLIGHT). In environments such as a Windows console where only two levels of intensity are supported, LOWLIGHT is the same as leaving this clause off altogether.

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.32 NEXT GROUP

NEXT-GROUP Clause Syntax

NEXT GROUP IS { [ +|PLUS ] integer-2  }
~~~~ ~~~~~    {     ~~~~              }
              { NEXT|{NEXT PAGE}|PAGE }
                ~~~~  ~~~~ ~~~~  ~~~~

This syntax is valid in the following sections: REPORT

This clause defines any rules for where the next group to be presented on a report will begin, line-wise, with respect to the last line of the group in which this clause appears.

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. The terms NEXT, NEXT PAGE and PAGE are interchangeable.

  3. A report group must contain at least one LINE NUMBER clause in order to also contain a NEXT GROUP clause.

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

  5. The NEXT PAGE option cannot be used in a PAGE FOOTING.

  6. The NEXT GROUP option cannot be specified in either a REPORT HEADING or a PAGE HEADING.

  7. The effects of NEXT GROUP will be in addition to any line spacing defined by the next-presented group’s LINE NUMBER clause.

6.9.33 NO-ECHO

NO-ECHO Attribute Syntax

NO-ECHO
~~~~~~~

This syntax is valid in the following sections: SCREEN

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

  1. If NO-ECHO is present then the PROMPT clause is ignored.

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

  3. The NO-ECHO and SECURE ( 6.9.48 SECURE) clauses may not be used together in the same data item description.

  4. This clause may only be used on a field allowing data entry (a field containing either the USING ( 6.9.62 USING) or TO ( 6.9.55 TO) clause).

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.34 NO UPDATE

NO-UPDATE Attribute Syntax

NO UPDATE
~~ ~~~~~~

This syntax is valid in the following sections: SCREEN

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

6.9.35 OCCURS

OCCURS Clause Syntax

GENERAL FORMAT.

 Format 1 (fixed-table):

 OCCURS integer-2 TIMES
 ~~~~~~

 Format 2 (occurs-depending-table):

 OCCURS [ integer-1 TO ] { integer-2 TIMES } [ DEPENDING ON identifier-1 ]
 ~~~~~~             ~~   { UNBOUNDED       }   ~~~~~~~~~

   [ ASCENDING|DESCENDING KEY IS identifier-5 ... ] ...
     ~~~~~~~~~ ~~~~~~~~~~
   [ INDEXED BY index-name-1 ... ]
     ~~~~~~~

 REPORT SECTION.

 Format 3

 OCCURS [ integer-1 TO ] integer-2 TIMES  [ DEPENDING ON identifier-1 ]
 ~~~~~~             ~~                      ~~~~~~~~~

   [ STEP integer-3 ]
     ~~~~
   [ VARYING identifier-2 FROM { identifier-3 } BY { identifier-4 } ]
     ~~~~~~~              ~~~~ { integer-4    } ~~ { integer-5    }


 SCREEN SECTION.

 Format 4

 OCCURS integer-2 TIMES
 ~~~~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN

The OCCURS clause is used to create a data structure called a table, where entries in that structure repeat multiple times.

  1. The reserved words BY (INDEXED), IS, KEY, ON and TIMES are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The value of <integer-2> specifies how many entries will be allocated in the table.

  3. The following is an example of how a table might be defined:

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

    This will allocate the following:

    QUARTERLY-REVENUE(1)
QUARTERLY-REVENUE(2)
QUARTERLY-REVENUE(3)
QUARTERLY-REVENUE(4)

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

  4. The OCCURS clause may be used at the group level too, in which case the entire group structure repeats, as follows:

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

    This would allow references to any of the following:

    GRP(1)   includes A(1), B(1) and C(1)
GRP(2)   includes A(2), B(2) and C(2)
GRP(3)   includes A(3), B(3) and C(3)

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

    A(1)   character #1 of GRP(1)
B(1)   character #2 of GRP(1)
C(1)   character #3 of GRP(1)
A(2)   character #1 of GRP(2)
B(2)   character #2 of GRP(2)
C(2)   character #3 of GRP(2)
A(3)   character #1 of GRP(3)
B(3)   character #2 of GRP(3)
C(3)   character #3 of GRP(3)

  5. The optional DEPENDING ON clause can be added to an OCCURS to create a variable-length table. In such cases, the value of <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.

  6. See the documentation of the SEARCH ( 7.8.39 SEARCH), SEARCH ALL ( 7.8.40 SEARCH ALL) and SORT ( 7.8.42 SORT) statements for explanations of the KEY and INDEXED BY clauses.

  7. The OCCURS clause cannot be specified in a data description entry that has a level number of 01, 66, 77, or 88, although it is valid in data items described subordinate to an 01-level data item.

  8. The following points apply to an OCCURS used in the report section:

    1. The optional STEP clause defines an incrementation value that will be added to any absolute LINE ( 6.9.29 LINE) or COLUMN ( 6.9.14 COLUMN) number specifications that may be part of or subordinate to this data item’s definition.

    2. The optional VARYING clause defines an identifier that may be used as a subscript for the multiple occurrences of this or any subordinate data item should the SOURCE ( 6.9.51 SOURCE) or SUM ( 8.1.92 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.

    3. 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 OCCURS capabilities of STEP and VARYING. Both assume the definition of the following table exists in working-storage:

      05 SALES OCCURS 4 TIMES PIC 9(7)V99.

      First, the “Hard Way”:

      10 COL 7  PIC $(7)9.99 SOURCE SALES(1).
10 COL 17 PIC $(7)9.99 SOURCE SALES(2).
10 COL 27 PIC $(7)9.99 SOURCE SALES(3).
10 COL 37 PIC $(7)9.99 SOURCE SALES(4).

      And then using STEP and VARYING:

      10 COL 7  OCCURS 4 TIMES STEP 10 VARYING QTR FROM 1 BY 1
          PIC $(7)9.99 SOURCE SALES(QTR).

6.9.36 OVERLINE

OVERLINE Attribute Syntax

OVERLINE
~~~~~~~~

This syntax is valid in the following sections: SCREEN

The OVERLINE clause will introduce a horizontal line at the top edge of a screen field.

  1. The LEFTLINE ( 6.9.27 LEFTLINE), OVERLINE and UNDERLINE ( 6.9.58 UNDERLINE) clauses may be used in any combination in a single field’s description.

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

  3. Whether or not this clause operates on Cygwin or UNIX/Linux/OSX systems will depend upon the video attribute capabilities of the terminal output drivers and “curses” software being used.

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.37 PICTURE

PICTURE Clause Syntax

PICTURE IS picture-string
~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN

The picture clause defines the class (numeric, alphabetic or alphanumeric), size and format of the data that may be contained by the data item being defined. Sometimes this role is assisted by the USAGE ( 6.9.61 USAGE) clause, and in a few instances will be assumed entirely by that clause.

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. The reserved word PICTURE may be abbreviated as PIC. Most programmers prefer to use the latter.

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

  4. A <picture-string> is a sequence of the special symbols ‘$‘, ‘*‘, ‘+‘, ‘,‘, ‘-‘, ‘.‘, ‘/‘, ‘0‘ (zero), ‘1‘, ‘9‘, ‘A‘, ‘B‘, CR, DB, ‘S‘, ‘V‘, ‘P‘, ‘X‘ and ‘Z‘.

  5. In general, each picture symbol represents either a single character in storage or a single decimal digit. There are a few exceptions, and they will be discussed as needed.

  6. When a <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 in PIC 9(4)/9(2)/9(2). Using repeat counts is optional and their use (or not) is entirely at the discretion of the programmer. Many programmers use repetition for small sequences (PIC XXX) and repeat counts for larger ones (PIC 9(9).

  7. This first set of picture symbols defines the basic data type of a data item. Each symbol represents a single character’s worth of storage.

    • ‘A‘

      Defines storage reserved for a single alphabetic character (’A‘-’Z‘, ‘a‘-’z‘).

    • ‘N‘

      Defines storage reserved for a single character in the computer’s National Character set. 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 if X(2) had been coded, with the additional effect that such a field will qualify as a NATIONAL or NATIONAL-EDITED field on an INITIALIZE ( 7.8.24 INITIALIZE) statement.

    • ‘X‘

      Defines storage reserved for a single alphanumeric character (any character).

    • ‘9‘

      Defines storage reserved for a single numeric digit character (’0‘-’9‘).

    Typically, only one kind of each of those symbols is used in the same picture clause, but that isn’t a requirement. Data items that, of the three symbols above, use nothing but ‘A‘ picture symbols are known as Alphabetic Data Items while those that use ‘9‘ picture symbols without any ‘A‘ or ‘X‘ symbols (or those that have a USAGE without a PICTURE) are known as Numeric Data Items. All other data items are referred to as Alphanumeric Data Items.

    If you need to allocate space for a data item whose format is two letters followed by five digits followed by three letters, you could use the <picture-string> AA99999AAA, A(2)9(5)A(3) XXXXXXXXXX or X(10). There is absolutely no functional difference whatsoever between the four — none of them provide any functionality the others do not. The first two probably make for better documentation of the expected field contents, but they don’t provide any run-time enforcement capabilities.

    As far as enforcement goes, however, both alphabetic and numeric picture strings do provide for both compile-time and run-time enforcement capabilities. In the case of compilation enforcement, the compiler can issue warning messages if you attempt to specify a non-numeric value for a numeric data item or if you attempt to MOVE ( 7.8.28 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 ( 2.2.6 Class Conditions) to determine if the contents of a data item are entirely numeric or entirely alphabetic.

  8. ‘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.

  9. The following picture symbols may be used with numeric data items.

    • ‘P‘

      Defines an implied digit position that will be considered to be a zero when the data item is referenced at run-time. This symbol is used to allow data items that will contain very large values to be allocated using less storage by assuming a certain number of trailing zeros (one per ‘P‘) to exist at the end of values.

      The ‘P‘ symbol is not allowed in conjunction with ‘N‘.

      The ‘P‘ symbol may only be used at the beginning or end of a picture clause.

      ‘P‘ is a repeatable symbol.

      All computations and MOVE ( 7.8.28 MOVE) operations involving such a data item will behave as if the zeros were actually there.

      For example, let’s say you need to allocate a data item that contains however many millions of dollars of revenue your company has in gross revenues this year:

      01  Gross-Revenue    PIC 9(9).

      In which case 9 characters of storage will be reserved. The values 000000000 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 <nnn>000000, where <nnn> is the actual value in storage.

      If you wanted to store the value 128 million into that field, you would do so as if the ‘P‘s were ‘9‘s:

      MOVE 128000000 TO Gross-Revenue

      A DISPLAY ( 7.8.12 DISPLAY) of a data item containing ‘P‘ symbols is a little strange. The value displayed will be what is actually in storage, but the total size of the displayed value will be as if the ‘P‘ symbols had been ‘9‘s. Thus, after the above statement established a value for Gross-Revenue, a DISPLAY Gross-Revenue would produce output of ‘000000128‘.

    • ‘S‘

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

      The ‘S‘ symbol is not allowed in conjunction with ‘N‘.

      The ‘S‘ symbol may only occur once in a picture string. 6.9.49 SIGN IS, for further discussion of how negative values may be stored in a numeric data item.

    • ‘V‘

      This symbol is used to define where an implied decimal-point (if any) is located in a numeric item. Just as there may only be a single decimal point in a number so may there be no more than one ‘V‘ in a PICTURE. Implied decimal points occupy no space in storage — they just specify how values are used. For example, if the value 1234 is in storage in a field defined as PIC 999V9, that value would be treated as 123.4 in any statements that referenced it.

      The ‘V‘ symbol is not allowed in conjunction with ‘N‘.

      The ‘V‘ symbol may only occur once in a picture string.

  10. 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.

  11. The following are the fixed insertion editing symbols that may be specified in a picture string. Each of these editing symbols will insert a special character into the field value at the position it is specified in the picture string. These editing symbols will each introduce one extra character into the total field size for each occurrence of the symbol in the picture string.

    • ‘B‘

      The ‘B‘ editing symbol introduces a blank into the field value for each occurrence.

      Multiple ‘B‘ symbols may be coded.

      The following example will format a ten digit number (presumably a telephone number) into a ‘### ### ####‘ layout:

      ...
    05 Phone-Number       PIC 9(3)B9(3)B9(4).
...
    MOVE 5185551212 TO Phone-Number
    DISPLAY Phone-Number

      This code will display ‘518 555 1212‘.

    • ‘0‘

      The ‘0‘ (zero) editing symbol introduces one “0” character into the field value for each occurrence in the picture string.

      Multiple ‘0‘ symbols may be coded.

      Here’s an example:

      ...
    05  Output-Item     PIC 909090909.
...
    MOVE 12345 TO Output-Item
    DISPLAY Output-Item

      The above will display ‘102030405‘.

    • ‘/‘

      The ‘/‘ editing symbol inserts one “/” character into the field value for each occurrence in the picture string.

      Multiple ‘/‘ symbols may be coded.

      This editing symbol is most-frequently used to format dates, as follows:

      ...
    05  Year-Month-Day   PIC 9(4)/9(2)/9(2).
...
    MOVE 20140207 TO Year-Month-Day
    DISPLAY Year-Month-Day

      This example displays ‘2014/02/07‘.

  12. The following are the numeric formatting symbols that may be specified in a picture string. Each of these editing symbols will insert special characters into the field value to present numbers in a “friendly” format. These editing symbols will each introduce one extra character into the total field size for each occurrence of the symbol in the picture string. Numeric fields whose picture clause contains these characters may neither be used as source fields in any calculation nor may they serve as source fields for the transfer of data values to any data item other than an alphanumeric field.

    • ‘.‘

      The ‘.‘ symbol inserts a decimal point into a numeric field value. When the contents of a numeric data item sending field are moved into a receiving data item whose picture clause contains the ‘.‘ editing symbol, implied (’V‘) or actual decimal point in the sending data item or literal, respectively, will be aligned with the ‘.‘ symbol in the receiving field. Digits are then transferred from the sending to the receiving field outward from the sending field’s ‘V‘ or ‘.‘, truncating sending digits if there aren’t enough positions in the receiving field. Any digit positions in the receiving field that don’t receive digits from the sending field, if any, will be set to 0.

      The ‘.‘ symbol is not allowed in conjunction with ‘N‘.

      An example will probably help:

      ...
05  Source-Field   PIC 9(2)V9 VALUE 7.2.
05  Dest-Field     PIC 9(5).9(2).
...
MOVE 1234567.89 TO Dest-Field
DISPLAY Dest-Field
MOVE 19 TO Dest-Field
DISPLAY Dest-Field
MOVE Source-Field TO Dest-Field
DISPLAY Dest-Field

      The example will display three results — ‘34567.89‘, ‘00019.00‘ and ‘00007.20‘.

      Both data item definitions appear to have two decimal points in their picture clauses. They actually don’t, because the last character of every data item definition is always a period — the period that ends the definition.

    • ‘,‘

      The ‘,‘ symbol serves as a thousands separator. Many times, you’ll see large numbers formatted with these symbols — for example, 123,456,789. This can be accomplished easily by adding thousands separator symbols to a picture string. Thousands separator symbols that aren’t needed will behave as if they were ‘9‘s.

      The ‘,‘ symbol is not allowed in conjunction with ‘N‘.

      Here’s an example:

      ...
05  My-Lottery-Winnings   PIC 9(3),9(3),9(3).
...
MOVE 12345 TO My-Lottery-Winnings
DISPLAY My-Lottery-Winnings

      The value ‘0000012,345‘ (a very disappointing one for my retirement plans, but a good thousands separator demo) will be displayed. Notice how, since the first comma wasn’t needed due to the meagre amount I won, it behaved like another ‘9‘.

    If desired, you may reverse the roles of the ‘.‘ and ‘,‘ editing symbols by specifying DECIMAL POINT IS COMMA in the SPECIAL-NAMES ( 5.1.3 SPECIAL-NAMES) paragraph.

  13. The following are insertion symbols. They are used to insert an extra character (two in the case of CR and DB) to signify the sign (positive or negative) of the numeric value that is moved into the field whose picture string contains one of these symbols, or the fact that the data item represents a currency (money) amount. Only one of the ‘+‘, ‘-‘, CR or DB symbols may be used in a picture clause. In this context, when any of these symbols are used in a <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 characters CR (credit) are inserted.

      The CR symbol is not allowed in conjunction with ‘N‘.

    • DB

      This symbol is coded as the two characters ‘D‘ and ‘B‘. If the value of the numeric value moved into the field is positive (0 or greater), two spaces will be inserted. If the value is negative (less than 0), the characters DB (debit) are inserted.

      The DB symbol is not allowed in conjunction with ‘N‘.

    • ‘$‘

      Regardless of the value moved into the field, this symbol will insert the currency symbol into the data item’s value in the position where it occurs in the <picture-string> ( 5.1.3 SPECIAL-NAMES).

      The ‘$‘ symbol is not allowed in conjunction with ‘N‘.

  14. 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 numerid edited data item, which can no longer be used in calculations or subscripts.

  15. 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 ( 5.1.3 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 they will all be considered floating and will all be able to assume each other’s properties. For example, if a data item has a PIC +$ZZZZ9.99 <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) *bbbb*+$1.00. This is not consistent with many other COBOL implementations, where the result would have been +$*bbbb*1.00.

    Most other COBOL implementations reject the use of multiple occurrences of multiple floating editing symbols. For example, they would reject <picture-string>s such as +++$$$9.99, $$$ZZZ9.99 and so on. GnuCOBOL accepts these. Programmers creating GnuCOBOL programs should avoid such <picture-string>s if there is any likelihood that those programs may be used with other COBOL implementations.

6.9.38 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 ( 2.2.5 Condition Names) that will serve as a switch controlling the presentation or suppression of a report group.

  1. If the specified condition-name has a value of FALSE when a GENERATE statement ( 7.8.20 GENERATE) causes a report group to be presented, the presentation of that group will be suppressed.

  2. If the condition-name has a value of TRUE, the group will be presented.

  3. 2.2.5 Condition Names, for more information.

6.9.39 PROMPT

PROMPT Clause Syntax

PROMPT [ CHARACTER IS literal-1 | identifier-1 ]
~~~~~~   ~~~~~~~~~

This syntax is valid in the following sections: SCREEN

This clause defines the character that will be used as the fill-character for any input fields on the screen.

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. The default prompt character, should no CHARACTER specification be coded, or should the PROMPT clause be absent altogether, is an underscore (’_‘).

  3. Prompt characters will be automatically transformed into spaces upon input.

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.40 PROTECTED

PROTECTED Attribute Syntax

PROTECTED SIZE IS { identifier }
~~~~~~~~  ~~~~    { integer    }

This syntax is valid in the following sections: SCREEN

  1. The PROTECTED extended clause will effect the specified field to be limited in size, regardless of the picture size. [1]

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

  3. If the SIZE phrase is not used, then the field length defaults to the size of the item being accepted or displayed. If the CONVERT phrase is used, however, then the size of the field depends on the data type of the item and the verb being used.

    1. If the DISPLAY verb is executing, then the size is the same as if the CONVERT phrase were not specified except for numeric items. For numeric items, the size is the number of digits in the item, plus one if it is not an integer, plus one if it is signed. The remaining cases cover the size when an ACCEPT statement is used.

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

    3. If the item is alphanumeric edited, then the size is set to the number of ‘A‘ or ‘X‘ positions specified in its PICTURE clause.

    4. For all other data types, the field size is set to the size of the item (same as if CONVERT were not specified).

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

  5. Note that you cannot supply the CONVERT phrase in the Screen Section. Thus the size of a Screen Section field is always the size of its screen entry unless the SIZE phrase is specified.

6.9.41 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).

  1. The following rules must all be followed in order to use REDEFINES:

    1. The level number of both the subject and object data items must be the same.

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

    3. If N represents the level number of the object, then no other data items with level number N may be defined between the subject and object data items unless they too are REDEFINES of the subject.

    4. 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.

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

    6. No OCCURS ( 6.9.35 OCCURS) clause may be part of the definition of either the subject or object data items. Either or both, however, may be group items that contain data items with OCCURS clauses.

    7. No VALUE ( 6.9.63 VALUE) clause may be defined on the object data item, and no data items subordinate to the object data item may have VALUE clauses, with the exception of level-88 condition names.

6.9.42 RENAMES

RENAMES Clause Syntax

RENAMES identifier-1 [ THRU|THROUGH identifier-2
~~~~~~~                ~~~~ ~~~~~~~

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

The RENAMES clause regroups previously defined items by specifying alternative, possibly overlapping, groupings of elementary data items.

  1. The reserved words THRU and THROUGH are interchangeable.

  2. You must use the level number 66 for data description entries that contain the RENAMES clause.

  3. The <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.

  4. 6.8.2 66-Level Data Items, for additional information on the RENAMES clause.

6.9.43 REQUIRED

REQUIRED Attribute Syntax

REQUIRED
~~~~~~~~

This syntax is valid in the following sections: SCREEN

This clause forces the user to enter data into the field it is specified on (or into all subordinate input-capable fields if REQUIRED is specified on a group item).

  1. The EMPTY-CHECK ( 6.9.16 EMPTY-CHECK) and REQUIRED clauses are interchangeable, and may not be used together in the same data item description.

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

  3. The ACCEPT data-item statement ( 7.8.1.4 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 the ACCEPT.

  4. 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 REQUIRED.

6.9.44 REVERSE-VIDEO

REVERSE-VIDEO Attribute Syntax

REVERSE-VIDEO
~~~~~~~~~~~~~

This syntax is valid in the following sections: SCREEN

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

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.45 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.

  1. Data-name-1 is a data Item defined elsewhere in the same program.

  2. Data-name-1 shall not be subscripted.

  3. 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.

  4. 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.

  5. 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.

  6. The description of data-name-1 shall not contain an OCCURS clause. However, items subordinate to data-name-1 may contain OCCURS clauses.

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

  8. If the subject of the entry is a level 77 item, data-name-1 shall reference an elementary item.

  9. A group item to which the subject of the entry is subordinate shall not contain a GROUP-USAGE, SIGN, or USAGE clause.

  10. 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.

  11. If data-name-1 describes a group item:

  12. 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.

6.9.46 SCROLL DOWN

SCROLL-DOWN Attribute Syntax

SCROLL DOWN
~~~~~~ ~~~~

This syntax is valid in the following sections: SCREEN

This clause will cause downward scrolling.

6.9.47 SCROLL UP

SCROLL-UP Attribute Syntax

SCROLL UP
~~~~~~ ~~

This syntax is valid in the following sections: SCREEN

This clause will cause upward scrolling. MORE HERE ??

6.9.48 SECURE

SECURE Attribute Syntax

SECURE
~~~~~~

This syntax is valid in the following sections: SCREEN

This clause will cause all data entered into the field to appear on the screen as asterisks.

  1. The NO-ECHO and SECURE clauses are interchangeable if If the dialect configuration -fno-echo-means-secure is active.

  2. The NO-ECHO and SECURE clauses may not be used together in the same data item description.

  3. This clause may only be used on a field allowing data entry (a field containing either the USING ( 6.9.62 USING) or TO ( 6.9.55 TO) clause).

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.49 SIGN IS

SIGN-IS Clause Syntax

SIGN IS LEADING|TRAILING [ SEPARATE CHARACTER ]
~~~~    ~~~~~~~ ~~~~~~~~   ~~~~~~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN

This clause, allowable only for USAGE DISPLAY numeric data items, specifies how an ‘S‘ symbol will be interpreted in a data item’s picture clause.

  1. The reserved words CHARACTER and IS are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. Without the SEPARATE CHARACTER option, the sign of the data item’s value will be encoded by transforming the last (see TRAILING) or first (see LEADING) digit as follows:

    • First/Last Digit Value For Positive Value for Negative

    • 0 0 p

    • 1 1 q

    • 2 2 r

    • 3 3 s

    • 4 4 t

    • 5 5 u

    • 6 6 v

    • 7 7 w

    • 8 8 x

    • 9 9 y

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

  4. When SEPARATE CHARACTER is specified, the ‘S‘ symbol in the data item’s PICTURE must be counted when determining the data item’s size.

  5. Neither the presence of an encoded digit (see above) nor an actual ‘+‘ or ‘-‘ character embedded within the data item’s storage prevents the data item from being used as a source field in arithmetic operations.

6.9.50 SIZE

SIZE Clause Syntax

SIZE
~~~~

This syntax is valid in the following sections: SCREEN

This clause does WHAT EXACTLY ??????

6.9.51 SOURCE

SOURCE Clause Syntax

SOURCE IS literal-1 | identifier-1 [ ROUNDED ]
~~~~~~                               ~~~~~~~

This syntax is valid in the following sections: REPORT

This clause logically attaches a report section data item to another data item defined elsewhere in the data division.

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. When the report group containing this clause is presented, the value of the specified numeric literal or identifier will be automatically moved to the report data item prior to presentation.

  3. The specified identifier may be defined anywhere in the data division, but if it is defined in the report section it may only be PAGE-COUNTER, LINE-COUNTER or a SUM ( 8.1.92 SUM) counter.

  4. The PICTURE ( 6.9.37 PICTURE) of the report data item must be such that it would be legal to MOVE ( 7.8.28 MOVE) the specified literal or identifier to a data item with that PICTURE.

  5. The ROUNDED option comes into play should the number of digits to the right of an actual or assumed decimal point be different between the specified literal or identifier value (the “source value”) and the PICTURE specified for the field in whose definition the SOURCE clause appears (the “target field”). Without ROUNDED, excess digits in the source value will simply be truncated to fit the target field. With ROUNDED, the source value will be arithmetically rounded to fit the target field. 7.6.7 ROUNDED, for information on the NEAREST-AWAY-FROM-ZERO rounding rule, which is the one that will apply.

6.9.52 SUM OF

SUM-OF Clause Syntax

SUM OF { identifier-7 }... [ { RESET ON FINAL|identifier-8 } ]
~~~    { literal-2    }      { ~~~~~    ~~~~~              }
                             { UPON identifier-9           }
                               ~~~~

This syntax is valid in the following sections: REPORT

The SUM clause establishes a summation counter whose value will be arithmetically calculated whenever the field is presented.

  1. The reserved words OF and ON are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The SUM clause may only appear in a CONTROL FOOTING report group.

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

  4. All <identifier-7> data items must be non-edited numeric in nature.

  5. If any <identifier-7> data item is defined in the report section, it must be a sum counter.

  6. 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 SUM clause appears or they must be defined in a report data item that exists at a lower level in this report’s control hierarchy. 9.5 Control Hierarchy, for additional information.

  7. The PICTURE of the report data item in who’s description this SUM clause appears in must be such that it would be legal to MOVE ( 7.8.28 MOVE) the specified <identifier-7> or <literal-2> value to a data item with that PICTURE.

  8. The following points apply to the UPON option:

    1. 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 SUM clause appears.

    2. The presence of an UPON clause limits the SUM clause to adding the specified numeric literal or identifier value into the sum counter only when a GENERATE <identifier-9> statement is executed.

    3. If there is no UPON clause specified, the value of <identifier-7> or <literal-2> will be added into the sum counter whenever a GENERATE ( 7.8.20 GENERATE) of any detail report group in the report is executed.

    4. If there is only a single detail group in the report’s definition, the UPON clause is meaningless.

  9. The following points apply to the RESET option:

    1. If the RESET option is coded, FINAL or <identifier-8> (whichever is coded on the RESET) must be one of the report’s control breaks specified on the CONTROLS clause.

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

    3. If, however, you want to reset the SUM counter only when the control footing for a control break higher in the control hierarchy is presented, specify that higher control break on the RESET option.

6.9.53 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.

  1. The reserved words SYNCHRONIZED and SYNCHRONISED are interchangeable, and may be abbreviated as SYNC.

  2. If the SYNCHRONIZED clause is coded on anything but a numeric data item with a USAGE ( 6.9.61 USAGE) that specifies storage of data in a binary form, the SYNCHRONIZED clause will be ignored.

  3. Synchronization is performed (by the compiler) as follows:

    1. If the binary item occupies one byte of storage, no synchronization is performed.

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

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

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

6.9.54 TIME OUT

TIME-OUT Clause Syntax

TIME OUT
~~~~ ~~~

This syntax is valid in the following sections: SCREEN

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

6.9.55 TO

TO Clause Syntax

TO identifier-5
~~

This syntax is valid in the following sections: SCREEN

This clause logically attaches a screen section data item to another data item defined elsewhere in the data division.

  1. The TO clause is used to define a data-entry field with no initial value; when a value is entered, it will be saved to the specified identifier.

  2. The FROM ( 6.9.21 FROM), TO, USING ( 6.9.62 USING) and VALUE ( 6.9.63 VALUE) clauses are mutually-exclusive in any screen section data item’s definition.

6.9.56 TYPE

TYPE Clause Syntax

Format 1: All Sections other than REPORT

[ TYPE TO type-name-1 ]
  ~~~~


Format 2:  REPORT SECTION Only

[ TYPE IS { RH|{REPORT HEADING}                      } ]
  ~~~~    { ~~  ~~~~~~ ~~~~~~~                       }
          { PH|{PAGE HEADING}                        }
          { ~~  ~~~~ ~~~~~~~                         }
          { CH|{CONTROL HEADING} FINAL|identifier-2  }
          { ~~  ~~~~~~~ ~~~~~~~  ~~~~~               }
          { DE|DETAIL                                }
          { ~~ ~~~~~~                                }
          { CF|{CONTROL FOOTING} FINAL|identifier-2  }
          { ~~  ~~~~~~~ ~~~~~~~  ~~~~~               }
          { PF|{PAGE FOOTING}                        }
          {  ~~ ~~~~ ~~~~~~~                         }
          { RF|{REPORT FOOTING}                      }
            ~~  ~~~~~~ ~~~~~~~

The syntax is valid in all other sections than: REPORT

As format 1

  1. The TYPE clause indicates that the data description of the subject of the entry is specified by a user-defined data type.

  2. The user defined data type is defined using the TYPEDEF clause, which is described in TYPEDEF clause TYPEDEF ( 6.9.57 TYPEDEF).

  3. 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.

  4. 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.

  5. 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.

  6. The scoping rules for type names are similar to the scoping rules for data names.

  7. Reference modification is not allowed for an elementary item that is the subject of a TYPE clause.

  8. 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.

  9. 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.

  10. The subject of a TYPE clause cannot be renamed in whole, or in part and cannot be redefined explicitly or implicitly.

  11. 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.

  12. 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.

  13. The TYPE clause can be specified in a data description entry with the EXTERNAL, GLOBAL, OCCURS, TYPEDEF, and VALUE clauses.

  14. 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.

  15. 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.

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

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

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

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

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

  17. Figure 2. Example Showing How TYPEDEF and TYPE Clauses Can Be Used

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

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

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

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

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

01 TEST-ARTI       TYPE ARTI-B-T.

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

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

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

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

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

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

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

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

This syntax is valid in the following sections: REPORT

As Format 2

  1. This clause defines the type of report group that is being defined for a report.

  2. 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.

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

  4. There must be either a CONTROL HEADING or a CONTROL FOOTING or both specified for each entry specified on the CONTROLS ARE clause of the RD.

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

  6. 9.1 RWCS Lexicon, for a description of the seven different types of report groups.

6.9.57 TYPEDEF

TYPEDEF Clause Syntax

01  data-name-1 IS TYPEDEF
                ~~ ~~~~~~

This syntax is valid in the following sections FILE, WORKING-STORAGE, LOCAL-STORAGE and LINKAGE

  1. 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.

  2. The TYPEDEF clause specifies that the data description entry is a type declaration.

  3. 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.

  4. If a group item is specified, all subordinate items of the group become part of the type declaration.

  5. No storage is allocated for a type declaration.

  6. 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.

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

  8. 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).

  9. The following clauses cannot be specified along with TYPEDEF: EXTERNAL, GLOBAL, LIKE, OCCURS, REDEFINES.

  10. 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.

  11. 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.

  12. 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.

  13. In FILE SECTION, a data description entry declared at level number 1 that includes a TYPEDEF clause is not a record description entry.

6.9.58 UNDERLINE

UNDERLINE Attribute Syntax

UNDERLINE
~~~~~~~~~

This syntax is valid in the following sections: SCREEN

The UNDERLINE clause will introduce a horizontal line at the bottom edge of a screen field.

  1. The LEFTLINE ( 6.9.27 LEFTLINE), OVERLINE ( 6.9.36 OVERLINE) and UNDERLINE clauses may be used in any combination in a single field’s description.

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

  3. Whether or not this clause operates on Cygwin or UNIX/Linux/OSX systems will depend upon the video attribute capabilities of the terminal output drivers and “curses” software being used.

2.1.12.2 Color Palette and Video Attributes, for more information on screen colors and video attributes.

6.9.59 UPDATE

UPDATE Clause Syntax

UPDATE
~~~~~~

This syntax is valid in the following sections: SCREEN

The UPDATE clause will display the existing data before allowing user to update it.

6.9.60 UPPER

UPPER Clause Syntax

UPPER
~~~~~

This syntax is valid in the following sections: SCREEN

The UPPER clause force the accepted data to be in Upper Case.

6.9.61 USAGE

USAGE Clause Syntax

USAGE IS data-item-usage
~~~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT

The USAGE clause defines the format that will be used to store the value of a data item.

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

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

    BINARY
    ~~~~~~

    • Range of Values: Defined by the quantity of ‘9‘s and the presence or absence of an ‘S‘ in the PICTURE

    • Storage Format: Compatible Binary Integer

    • Negative Values Allowed?: If PICTURE contains ‘S‘

    • PICTURE Used?: Yes

    BINARY-C-LONG [ SIGNED ]
    ~~~~~~~~~~~~~

    • Range of Values: Depending on the system hardware, the range is either 0 to 2^31 or 0 to 2^63.

    BINARY-C-LONG UNSIGNED
    ~~~~~~~~~~~~~ ~~~~~~~~

    • Range of Values: Depending on the system hardware, the range is either 0 to 2^32 or 0 to 2^64.

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

    BINARY-CHAR [ SIGNED ]
    ~~~~~~~~~~~

    • Range of Values: -128 – 127

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: Yes

    • PICTURE Used?: No

    BINARY-CHAR UNSIGNED
    ~~~~~~~~~~~ ~~~~~~~~

    • Range of Values: 0 – 255

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: No

    • PICTURE Used?: No

    BINARY-DOUBLE [ SIGNED ]
    ~~~~~~~~~~~~~

    • Range of Values: -9,223,372,036,854,775,808 – 9,223,372,036,854,775,807

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: Yes

    • PICTURE Used?: No

    BINARY-DOUBLE UNSIGNED
    ~~~~~~~~~~~~~ ~~~~~~~~

    • Range of Values: 0 – 18,446,744,073,709,551,615

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: No

    • PICTURE Used?: No

    BINARY-INT
    ~~~~~~~~~~

    • Same as BINARY-LONG SIGNED

    BINARY-LONG [ SIGNED ]
    ~~~~~~~~~~~

    • Range of Values: -2,147,483,648 – 2,147,483,647

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: Yes

    • PICTURE Used?: No

    BINARY-LONG UNSIGNED
    ~~~~~~~~~~~ ~~~~~~~~

    • Range of Values: 0 – 4,294,967,295

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: No

    • PICTURE Used?: No

    BINARY-LONG-LONG
    ~~~~~~~~~~~~~~~~

    • Same as BINARY-DOUBLE SIGNED

    BINARY-SHORT [ SIGNED ]
    ~~~~~~~~~~~~

    • Range of Values: -32,768 – 32,767

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: Yes

    • PICTURE Used?: No

    BINARY-SHORT UNSIGNED
    ~~~~~~~~~~~~ ~~~~~~~~

    • Range of Values: 0 – 65,535

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: No

    • PICTURE Used?: No

    COMPUTATIONAL
    COMP

    • Same as BINARY

    COMPUTATIONAL-1
    COMP-1

    • Same as FLOAT-SHORT

    COMPUTATIONAL-2
    COMP-2

    • Same as FLOAT-LONG

    COMPUTATIONAL-3
    COMP-3

    • Same as PACKED-DECIMAL

    COMPUTATIONAL-4
    COMP-4

    • Same as BINARY

    COMPUTATIONAL-5
    COMP-5

    • Range of Values: Depends on number of ‘9‘s in the PICTURE and the binary-size setting of the configuration file used to compile the program

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: If PICTURE contains ‘S‘

    • PICTURE Used?: Yes

    COMPUTATIONAL-6
    COMP-6

    • Range of Values: Defined by the quantity of ‘9‘s and the presence or absence of an ‘S‘ in the PICTURE

    • Storage Format: Unsigned Packed Decimal

    • Negative Values Allowed?: No

    • PICTURE Used?: Yes

    COMPUTATIONAL-X
    COMP-X

    • Range of Values: If used with PIC X, allocates one byte of storage per ‘X‘; range of values is 0 to max storable in that many bytes. If used with PIC 9, range of values depends on number of ‘9‘s in PICTURE

    • Storage Format: Native unsigned (X) or signed (9) Binary

    • Negative Values Allowed?: If PICTURE 9 and contains ‘S‘

    • PICTURE Used?: Yes

    DISPLAY
    ~~~~~~~

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

    • Storage Format: Characters

    • Negative Values Allowed?: If PICTURE contains ‘S‘

    • PICTURE Used?: Yes

    FLOAT-DECIMAL-16
    ~~~~~~~~~~~~~~~~

    • Range of Values: -9.999999999999999 * 10383 – 9.999999999999999 * 10384

    • Storage Format: Native IEEE 754 Decimal64 Floating-point

    • Negative Values Allowed?: Yes

    • PICTURE Used?: No

    FLOAT-DECIMAL-34
    ~~~~~~~~~~~~~~~~

    • Range of Values: -9.99999… * 106143 – 9.99999… * 106144

    • Storage Format: Native IEEE 754 Decimal128 Floating-point

    • Negative Values Allowed?: Yes

    • PICTURE Used?: No

    FLOAT-LONG
    ~~~~~~~~~~

    • Range of Values: Approximately -1.797693134862316 * 10308 – 1.797693134862316 * 10308

    • Storage Format: Native IEEE 754 Binary64 Floating-point

    • Negative Values Allowed?: Yes

    • PICTURE Used?: No

    FLOAT-SHORT
    ~~~~~~~~~~~

    • Range of Values: Approximately -3.4028235 * 1038 – 3.4028235 * 1038

    • Storage Format: Native IEEE 754 Binary32

    • Negative Values Allowed?: Yes

    • PICTURE Used?: No

    INDEX
    ~~~~~

    • Range of Values: 0 to maximum address possible (32 or 64 bits)

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: No

    • PICTURE Used?: No

    NATIONAL
    ~~~~~~~~

    • USAGE NATIONAL, while syntactically recognized, is not supported by GnuCOBOL

    PACKED-DECIMAL
    ~~~~~~~~~~~~~~

    • Range of Values: Defined by the quantity of ‘9‘s and the presence or absence of an ‘S‘ in the PICTURE

    • Storage Format: Signed Packed Decimal

    • Negative Values Allowed?: If PICTURE contains ‘S‘

    • PICTURE Used?: Yes

    POINTER
    ~~~~~~~

    • Range of Values: 0 to maximum address possible (32 or 64 bits)

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: No

    • PICTURE Used?: No

    PROCEDURE-POINTER
    ~~~~~~~~~~~~~~~~~

    • Same as PROGRAM-POINTER

    PROGRAM-POINTER
    ~~~~~~~~~~~~~~~

    • Range of Values: 0 to maximum address possible (32 or 64 bits)

    • Storage Format: Native Binary Integer

    • Negative Values Allowed?: No

    • PICTURE Used?: No

    SIGNED-INT
    ~~~~~~~~~~

    • Same as BINARY-LONG SIGNED

    SIGNED-LONG
    ~~~~~~~~~~~

    • Same as BINARY-DOUBLE SIGNED

    SIGNED-SHORT
    ~~~~~~~~~~~~

    • Same as BINARY-SHORT SIGNED

    UNSIGNED-INT
    ~~~~~~~~~~~~

    • Same as BINARY-LONG UNSIGNED

    UNSIGNED-LONG
    ~~~~~~~~~~~~~

    • Same as BINARY-DOUBLE UNSIGNED

    UNSIGNED-SHORT
    ~~~~~~~~~~~~~~

    • Same as BINARY-SHORT UNSIGNED

  3. USAGE IS type-name-1
    ~~~~~ ~~

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

    Example 1:

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

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

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

Example 2:

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

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

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

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

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

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

Example 3:

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

  5. Binary data (integer or floating-point) can be stored in either a Big-Endian or Little-Endian form.

    Big-endian data allocation calls for the bytes that comprise a binary item to be allocated such that the least-significant byte is the right-most byte. For example, a four-byte binary item having a value of decimal 20 would be big-endian allocated as 00000014 (shown in hexadecimal notation).

    Little-endian data allocation calls for the bytes that comprise a binary item to be allocated such that the least-significant byte is the left-most byte. For example, a four-byte binary item having a value of decimal 20 would be little-endian allocated as 14000000 (shown in hexadecimal notation).

    All CPUs are capable of understanding big-endian format, which makes it the most compatible form of binary storage across computer systems.

    Some CPUs — such as the Intel/AMD i386/x64 architecture processors used in most Windows PCs — prefer to process binary data stored in a little-endian format. Since that format is more efficient on those systems, it is referred to as the native binary format.

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

  6. Data items that have the UNSIGNED attribute explicitly coded, or DISPLAY, PACKED-DECIMAL, COMP-5, COMP-X items that do not have an ‘S‘ symbol in their picture clause cannot preserve negative values that may be stored into them. Storing a negative value into such a field will actually result in the sign being stripped, essentially saving the absolute value in the data item.

  7. Packed-decimal (i.e. USAGE PACKED-DECIMAL, USAGE COMP-3 or USAGE COMP-6) data is stored as a series of bytes such that each byte contains two 4-bit fields, referred to as nibbles (since they comprise half a “byte”, they’re just “nibbles” — don’t groan, I don’t just make this stuff up!). Each nibble represents a ‘9‘ in the PICTURE and each holds a single decimal digit encoded as its binary value (0 = 0000, 1 = 0001, … , 9 = 1001).

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

    The first byte of the data item will contain an unused left nibble if the PICTURE had an even number of ‘9‘ symbols in it.

    The sign indicator will have a value of a hexadecimal A 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-3 packed-decimal field with a value of -15 would be stored internally as a hexadecimal 015D in GnuCOBOL.

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

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

  8. The USAGE specifications FLOAT-DECIMAL-16 and FLOAT-DECIMAL-34 will encode data using IEEE 754 Decimal64 and Decimal128 format, respectively. The former allows for up to 16 digits of exact precision while the latter offers 34. The phrase “exact precision” is used because the traditional binary renderings of decimal real numbers in a floating-point format (FLOAT-LONG and FLOAT-SHORT, for example) only yield an approximation of the actual value because many decimal fractions cannot be precisely rendered in binary. The Decimal64 and Decimal128 renderings, however, render decimal real numbers in encoded decimal form in much the same way that PACKED-DECIMAL renders a decimal integer in digit-by-digit decimal form. The exact manner in which this rendering is performed is complex (Wikipedia has an excellent article on the subject — just search for Decimal64).

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

  10. The USAGE specifications FLOAT-LONG and FLOAT-SHORT use the IEEE 754 Binary64 and Binary32 formats, respectively. These are binary encodings of real decimal numbers, and as such cannot represent every possible value between the minimum and maximum values in the range for those usages. Wikipedia has an excellent article on the Binary64 and Binary32 encoding schemes — just search on Binary32 or Binary64.

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

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

  12. The only USAGE that is allowed in the report section is USAGE DISPLAY.

6.9.62 USING

USING Clause Syntax

USING identifier-1
~~~~~

This syntax is valid in the following sections: SCREEN

This clause logically attaches a screen section data item to another data item defined elsewhere in the data division.

  1. When the screen item whose definition this clause is part of is displayed, the value currently in <identifier-1> will be automatically moved into the screen item first.

  2. When the screen item whose definition this clause is part of (or its parent) is accepted, the current contents of the screen item will be saved back to <identifier-1> at the conclusion of the ACCEPT.

  3. The FROM ( 6.9.21 FROM), TO ( 6.9.55 TO), USING and VALUE ( 6.9.63 VALUE) clauses are mutually-exclusive in any screen section data item’s definition.

6.9.63 VALUE

VALUE (Condition Names) Clause Syntax

{ VALUE IS   } {literal-1 [ THRU|THROUGH literal-2 ]}...
{ ~~~~~      }              ~~~~ ~~~~~~~
{ VALUES ARE }
  ~~~~~~
    [ WHEN SET TO FALSE IS literal-3 ]
                  ~~~~~

VALUE (Other Data Items) Syntax

VALUE IS [ ALL ] literal-1
~~~~~      ~~~

VALUE (For Tables) Syntax

{ VALUE IS  } {{literal-1}.. FROM ({subscript-1}..) [ TO ({subscript-2}.. )]}..
{ ~~~~~     }                ~~~~                     ~~
{ VALUES ARE }
  ~~~~~~

This syntax is valid in the following sections: FILE, WORKING-STORAGE, LOCAL-STORAGE, LINKAGE, REPORT, SCREEN

The VALUE clause is used to define condition names or to assign values (at compilation time) to data items.

  1. The reserved words ARE and IS are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. This clause cannot be specified on the same data item as a FROM ( 6.9.21 FROM), TO ( 6.9.55 TO) or USING ( 6.9.62 USING) clause.

  3. The following points apply to using the VALUE clause in the definition of a condition name:

    1. The clauses VALUE IS and VALUES ARE are interchangeable.

    2. The reserved words THRU and THROUGH are interchangeable.

    3. 6.8.5 88-Level Data Items, for a discussion of how this format of VALUE is used to create condition names.

    4. 2.2.5 Condition Names, for a discussion of how condition names are used.

  4. The following points apply to using the VALUE clause in the definition of any other data item:

    1. In this context, VALUE specifies an initial compilation-time value that will be assigned to the storage occupied by the data item in the program object code generated by the compiler.

    2. The VALUE clause is ignored on EXTERNAL ( 6.9.18 EXTERNAL) data items or on any data items defines as subordinate to an EXTERNAL data item.

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

    4. If the optional ALL clause is used, it may only be used with an alphanumeric literal value; the value will be repeated as needed to completely fill the data item. Here are some examples with and without ALL (the symbol b denotes a space):

      PIC X(5) VALUE 'A'      *> A\ *bbbb*\
PIC X(5) VALUE ALL 'A'  *> AAAAA
PIC 9(3) VALUE 1        *> 001
PIC 9(3) VALUE ALL '1'  *> 111

    5. When used in the definition of a screen data item:

      1. A figurative constant may not be supplied as <literal-1>.

      2. Any FROM ( 6.9.21 FROM), TO ( 6.9.55 TO) or USING ( 6.9.62 USING) clause in the same data item’s definition will be ignored.

      3. If there is no picture clause specified, the size of the screen data item will be the length of the <literal-1> value.

      4. If there is no picture clause and the ALL option is specified, the ALL option will be ignored.

    6. 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:

      1. Don’t bother worrying about it at compile-time. Use the INITIALIZE ( 7.8.24 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).

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

        05  SHIRT-SIZES          VALUE "S 14M 15L 16XL17".
    10 SHIRT-SIZE-TBL    OCCURS 4 TIMES.
       15 SST-SIZE       PIC X(2).
       15 SST-NECK       PIC 9(2).

      3. Initialize tables of almost any size at compilation time by utilizing the REDEFINES ( 6.9.41 REDEFINES) clause:

        05  SHIRT-SIZE-VALUES.
    10 PIC X(4)          VALUE "S 14".
    10 PIC X(4)          VALUE "M 15".
    10 PIC X(4)          VALUE "L 16".
    10 PIC X(4)          VALUE "XL17".
05  SHIRT-SIZES          REDEFINES SHIRT-SIZE-VALUES.
    10 SHIRT-SIZE-TBL    OCCURS 4 TIMES.
       15 SST-SIZE       PIC X(2).
       15 SST-NECK       PIC 9(2).

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

    7. Many COBOL compilers do not allow the use of VALUE and OCCURS ( 6.9.35 OCCURS) on the same data item; additionally, they don’t allow a VALUE clause on a data item subordinate to an OCCURS. GnuCOBOL, however, has neither of these restrictions!

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

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

      In this example, all six ‘A‘ items will be initialized to ‘?‘, all six ‘B‘ items will be initialized to ‘%‘ and all six ‘N‘ items will be initialized to 10. It’s not clear exactly how many times this sort of initialization will be useful, but it’s there if you need it.

  5. The FROM ( 6.9.21 FROM), TO ( 6.9.55 TO), USING ( 6.9.62 USING) and VALUE clauses are mutually-exclusive in any screen section data item’s definition.

  6. 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.