Compaq COBOL
Reference Manual

Function

The FILE STATUS clause specifies a data item to contain the status of an input/output operation.

file-stat

is the data-name of a two-character alphanumeric Working-Storage Section, or Linkage Section data item. file-stat is the file's FILE STATUS data item.

Syntax Rules

1. file-stat can be qualified.
2. The FILE STATUS clause can be in the file's SELECT clause or in its file description entry. However, it cannot be in both the SELECT clause and the file description entry for the same file.
3. If the FILE STATUS clause is associated with an external file connector, file-stat must reference the same data item in all programs in the run unit.

General Rule

After the execution of every I-O statement that refers to the specified file, a value is moved to file-stat. This value indicates the file's I-O status after the execution of the I-O statement.

Additional References

• Appendix C, File Status Values
• Section 6.6.8, I-O Status

Function

The FOREGROUND-COLOR clause specifies the foreground color for a screen item.

color-num

is an integer in the range 0--7 specifying a color as follows:

Color	Color Value	Color	Color Value
Black	0	Red	4
Blue	1	Magenta	5
Green	2	Yellow/Brown	6
Cyan	3	White	7

Syntax Rule

The FOREGROUND-COLOR clause can be specified in any screen description entry.

General Rules

1. The FOREGROUND-COLOR clause is effective only with color screens.
2. If the FOREGROUND-COLOR clause is omitted, the initial default foreground color is white.
3. If the clause is specified at group level, it applies to all subordinate screen items.
4. If the BLANK SCREEN clause is specified and the FOREGROUND-COLOR clause is specified or inherited, then when a DISPLAY statement displays the screen item, the specified color becomes the default foreground color. It remains the default foreground color until another screen item with this combination of options is displayed (whether in the same DISPLAY statement or in another).
5. If the HIGHLIGHT clause is also specified, foreground and background colors are brightened and lightened; for example, black may become grey and brown may become yellow.

Technical Note

The colors in the list above are supported only on terminals and workstations that support the ANSI Standard color sequences. ¹

Additional References

• Section 6.8.1 in Chapter 6
• Section 6.8.10 in Chapter 6 <>

Function

The FULL clause specifies that a screen item must be left either completely empty or it must be entirely filled with data.

Syntax Rules

1. If the FULL clause is specified in a screen description entry, the JUSTIFIED clause cannot be specified.
2. The FULL clause is valid only in the description of an input or update screen item.

General Rules

1. If the FULL clause is specified at group level, it applies to all subordinate input or update screen items.
2. The FULL clause is effective during the execution of any ACCEPT statement when the cursor enters the screen item. Until this clause is satisfied, the operator cannot leave the field and normal terminator keystrokes are rejected.
3. To satisfy the FULL clause for an alphanumeric screen item, either the field must contain all spaces, or both the first and last character positions must contain nonspace characters.
4. To satisfy the FULL clause for a numeric or numeric edited screen item, either the value must be zero or there must be no digit position in which zero suppression has taken effect.
5. For update fields, the FULL clause can be satisfied by the contents of the identifier or literal referenced in the FROM or USING phrase of the PICTURE clause, as well as by operator-keyed data.
6. The FULL clause is not effective if a function key terminates the accept operation.
7. Specifying the FULL and REQUIRED clauses together requires that the user must always entirely fill the field.
8. The FULL clause is ignored for an elementary output field.

Additional Reference

Section 6.8.1 statement in Chapter 6 <>

5.3.25 GLOBAL

Function

The GLOBAL clause specifies that data-name, file-name, or report-name is available to every program contained within the program that declares it.

Syntax Rules

1. The GLOBAL clause can appear only in file description entries, Report Description entries, a data description entry whose level number is 01, in the File or Working-Storage Section, or a data description entry whose level number is 77, in the Working-Storage Section.
2. In the same Data Division, the GLOBAL clause must not appear in Data Description entries that contain identical data-names.
3. If you use the SAME RECORD AREA clause for several files, the Record Description entries or the file description entries for these files must not include the GLOBAL clause.
4. Entries that contain the GLOBAL clause must be named.

General Rules

1. Any data-name, file-name, or report-name specifying the GLOBAL clause is a global name. All data items subordinate to a global data-name or file-name are global names. All condition-names associated with a global name are global names.
2. A statement in a program contained directly or indirectly within a program that describes a global name may reference the name without describing it again.
3. If the GLOBAL clause is used in a data description entry that contains the REDEFINES clause, the global attribute applies only to the subject of the REDEFINES clause.

Technical Note

Each global sequential file becomes a print format file.

Additional Reference

Section 6.2.6, Scope of Names

5.3.26 GROUP INDICATE

Function

The GROUP INDICATE clause specifies that the associated printable item is presented only on the first occurrence of its DETAIL report group after a control break or page advance.

Syntax Rule

The GROUP INDICATE clause must be specified only in a DETAIL report group entry that defines a printable item.

General Rules

1. If the program contains a GROUP INDICATE clause, the compiler suppresses printing of the printable item and supplies spaces, except:
   1. On the first presentation of the DETAIL report group
   2. On the first presentation of the DETAIL report group after every page advance
   3. On the first presentation of the DETAIL report group after every control break
2. If the program specifies neither the PAGE clause nor the CONTROL clause in a Report Description entry, then the first time a DETAIL report group is presented a GROUP INDICATE printable item is also presented. Thereafter, spaces are supplied for indicated items with SOURCE or VALUE clauses.

Additional Reference

Appendix D, Report Writer Presentation Rules and Tables

Example

The following example shows the effect of the GROUP INDICATE clause on a printable item (SOURCE I-NAME).

Function

The HIGHLIGHT clause specifies that the field is to appear on the screen with the highest intensity.

Syntax Rule

The HIGHLIGHT clause can be specified only for an elementary screen description entry.

Additional References

• Section 6.8.1 in Chapter 6
• Section 6.8.10 in Chapter 6 <>

Function

The JUSTIFIED clause specifies nonstandard data positioning in a screen item or another receiving item.

Syntax Rules

1. The JUSTIFIED clause can be used only for elementary items and alphanumeric data items. It cannot be used for index data items, numeric data items, or edited data items.
2. JUST is the abbreviated form of JUSTIFIED.

General Rules

1. If a COBOL statement transfers data to a receiving item whose data description contains the JUSTIFIED clause, the Run-Time System:
   • Truncates the excess leftmost characters if the sending item is larger than the receiving item.
   • Aligns the data at the rightmost character position of the receiving item if the sending item is smaller than the receiving item. (Spaces fill the excess leftmost character positions.)
2. If there is no JUSTIFIED clause, data movement follows the rules for aligning data in elementary items (Standard Alignment Rules).

Additional References

• Section 6.8.22 statement in Chapter 6
• Section 5.2.2, COBOL Standard Alignment Rules

Examples

The Procedure Division entry for the MOVE statement contains examples using this clause.

5.3.29 LABEL RECORDS

Function

The LABEL RECORDS clause specifies the presence or absence of labels.

General Rule

The LABEL RECORDS clause is for documentation only.

5.3.30 Level-Number

Function

The level-number shows the position of a data item or screen item within the hierarchical structure of a logical record or a report group or a screen description. It also identifies entries for condition-names and the RENAMES clause.

Syntax Rules

1. The level-number must be the first element in a data description entry or a screen description entry.
2. Data description entries that are subordinate to a file description (FD) entry have level-numbers 01 to 49, 66, or 88.
3. Data description entries in the Working-Storage and Linkage Sections have level-numbers 01 to 49, 66, 77, or 88.
4. Report group description entries in the Report Section have level-numbers 01 to 49 only. See the Section 5.3.5 entry for additional rules for Report Writer level-numbers.
5. Screen description entries in the Screen Section have level-numbers 01 to 49 only. See the Section 5.3.6 entry for additional rules for Screen Section level-numbers.

General Rules

1. The level-number 01 identifies the first entry in a record description, report group description, or screen description entry.
2. Multiple level 01 entries subordinate to a file description entry represent implicit redefinitions of the same area.
3. Multiple level 01 entries subordinate to a report description entry do not represent implicit redefinitions of the same area.
4. Level-number 66 identifies a RENAMES entry. It can be used only in a Format 2 data description entry.
5. Level-number 77 identifies a noncontiguous data item entry in the Working-Storage and Linkage Sections. The level 77 entry can have no subordinate data description entries except level 88 items.
6. Level-number 88 defines a condition-name associated with a conditional variable. It can be used only in a Format 3 data description entry.
7. Level-numbers 66, 77, and 88 do not imply a hierarchical position.

Additional References

• Section 5.3.3 entry
• Section 5.3.4 entry
• Section 5.3.5 entry
• Section 5.3.41 clause
• Section 1.2.1.1 in Section 1.2.1,COBOL Words
• Section 5.1.1, Record Description Entries
• Section 5.3.6 entry

Function

The LINAGE clause specifies the number of lines on a logical page. It can also specify the size of the logical page's top and bottom margins and the line where the footing area begins in the page body.

page-lines

is a positive integer or the data-name of an elementary unsigned integer numeric data item. Its value must be greater than zero. It specifies the number of lines that can be written or spaced on the logical page. If page-lines is a data-name, it can be qualified.

footing-line

is a positive integer or the data-name of an elementary unsigned integer numeric data item. Its value must be greater than zero, but cannot be greater than page-lines. footing-line specifies the line number where the footing area begins in the page body. If footing-line is a data-name, it can be qualified.

top-lines

is an integer or the data-name of an elementary unsigned integer numeric data item. Its value can be zero. top-lines specifies the number of lines in the top margin of the logical page. If top-lines is a data-name, it can be qualified.

bottom-lines

is an integer or the data-name of an elementary unsigned integer numeric data item. Its value can be zero. bottom-lines specifies the number of lines in the bottom margin of the logical page. If bottom-lines is a data-name, it can be qualified.

General Rules

1. The LINAGE clause specifies the number of lines on a logical page.
2. Logical page size is the sum of the values specified in all phrases except FOOTING. If there is no LINES AT TOP or LINES AT BOTTOM phrase, the default value of top-lines or bottom-lines is zero. If there is no FOOTING phrase, the default value of footing-line equals the value of page-lines.
3. Logical and physical page sizes are not necessarily the same.
4. The page body is the logical page area in which the program can write or space lines. Its size equals the value of page-lines.
5. The footing area is the area of the logical page between footing-line and page-lines, inclusive.
6. When the program opens the file by executing an OPEN statement with the OUTPUT phrase, it uses the values of page-lines, top-lines, and bottom-lines to define the logical page sections. When these values are integers, they apply to all logical pages the program writes to the file during its execution.
7. When page-lines, top-lines, and bottom-lines are data-names, their values affect OPEN and WRITE statement execution as follows:
   • When the program executes an OPEN statement with the OUTPUT phrase for the file, the values specify the number of lines in each of the associated sections of the first logical page.
   • When the program executes a WRITE statement with the ADVANCING PAGE phrase, or when a page overflow condition occurs, the values specify the number of lines in each of the associated sections of the next logical page.
8. The value of footing-line defines the footing area for the first logical page when the program executes an OPEN statement with the OUTPUT phrase for the file. The value defines the footing area for the next logical page when: (a) the program executes a WRITE statement with the ADVANCING PAGE phrase or, (b) a page overflow condition occurs.
9. For each file with a LINAGE clause, the program has a corresponding special register called LINAGE-COUNTER. At any time, the value in LINAGE-COUNTER is the line number in the current page body at which the device is positioned. Other open modes (Input, I-O, and Extend) are not permitted and have unpredictable results.
10. LINAGE-COUNTER is global if a file description entry specifies the GLOBAL clause and the LINAGE clause.
11. LINAGE-COUNTER is a 9-digit numeric special register. Procedure Division statements can refer to LINAGE-COUNTER but cannot change its value.
12. If the program has more than one LINAGE-COUNTER, all Procedure Division references to it must be qualified by file-name.
13. Execution of a WRITE statement for a file with the LINAGE clause changes the value of the associated LINAGE-COUNTER:
    • If the WRITE statement has the ADVANCING PAGE phrase, its execution resets LINAGE-COUNTER to one. (The resetting operation implicitly increments the value of LINAGE-COUNTER to exceed the value of page-lines.)
    • If the WRITE statement has the ADVANCING LINES phrase, its execution increments LINAGE-COUNTER by the value in the ADVANCING phrase.
    • If the WRITE statement does not have the ADVANCING phrase, it increments LINAGE-COUNTER by one.
14. Execution of an OPEN statement for the file sets its LINAGE-COUNTER to one.
15. Each logical page follows the preceding logical page with no spacing between them.
16. If the file connector associated with this file description entry is an external file connector, all file description entries in the run unit associated with this file connector must have the following features:
    • A LINAGE clause, if any file description entry has a LINAGE clause
    • The same corresponding integer values for page-lines, footing-lines, top-lines, and bottom-lines
    • The same corresponding external data items referenced by page-lines, footing-lines, top-lines, and bottom-lines

Technical Notes

• On OpenVMS, the LINAGE clause causes a file to be in print-file format. When a WRITE statement positions the file to the top of the next logical page, device positioning occurs by line spacing rather than by page ejection or form feed.
  The default DCL PRINT command causes the insertion of a form-feed character when a form nears the end of a page. Therefore, when the default PRINT command refers to a LINAGE file, unexpected page spacing can result.
  The /NOFEED compiler option to the PRINT command suppresses the insertion of form-feed characters and prints LINAGE files correctly. For example:

  $ PRINT/NOFEED full-file-name

• The /NOVFC compiler option can be used on OpenVMS Alpha to produce a Stream_LF record-formatted print file. The default (/VFC) behavior is to produce a VFC record-formatted file. <>
• Compaq COBOL on Tru64 UNIX systems writes LINAGE files with blank lines to simulate WRITE ADVANCING behavior. These blank lines would not be produced on an OpenVMS Alpha system. When you input a LINAGE file, you must compensate for the difference. For example, use an extra initial READ statement (on Tru64 UNIX systems) to skip over the leading blank line in the LINAGE file. <>

Additional References

• Section 5.3.25 clause
• Section 6.8.43 statement in Chapter 6

Example

The following example specifies a logical page whose size is 26 lines:

FD PRINT-FILE VALUE OF ID IS "REPORT1.LIS" LINAGE IS 16 LINES WITH FOOTING AT 13 LINES AT TOP 4 LINES AT BOTTOM 6.

In this example, the first line to which the page can be positioned is the fifth line. The end-of-page condition occurs when a WRITE statement causes the LINAGE-COUNTER value to be in the range 13 to 16. The page overflow condition occurs when a WRITE statement causes the LINAGE-COUNTER value to exceed 16.

Figure 5-9 shows the logical page areas resulting from the example.

Figure 5-9 Logical Page Areas Resulting from a LINAGE Clause

Function

The LINE NUMBER clause specifies vertical positioning information for a report group, or specifies the vertical screen coordinate for a screen item.

line-num

is a nonnegative integer. line-num represents an absolute line number on a logical page and establishes a print line for a Report Writer report group.

line-num-plus

is a positive integer. line-num-plus represents a relative line number on a logical page and establishes a print line for a Report Writer report group.

identifier-1

is an elementary unsigned numeric integer data item. It cannot be subscripted.

integer-1

is an unsigned integer value.

Syntax Rules (Report Description)

1. Neither line-num nor line-num-plus can exceed three significant digits.
   The PAGE clause defines the length of a logical page and the vertical subdivisions within which each report group is presented. Neither line-num nor line-num-plus may specify a line outside of the PAGE clause limits. See Section 5.3.36 clause for more information.
2. Within a given Report Group Description, an entry containing a LINE NUMBER clause must not contain a subordinate entry that also contains a LINE NUMBER clause.
3. Within a given Report Group Description, all absolute LINE NUMBER clauses must precede all relative LINE NUMBER clauses.
4. Within a given Report Group Description, successive absolute LINE NUMBER clauses must specify integers in ascending order. The integers need not be consecutive.
5. If a given Report Description (RD) does not contain a PAGE clause, the program may specify only relative LINE NUMBER clauses in any Report Group Description within that report.
6. Within a given Report Group Description, a NEXT PAGE phrase may appear only once. If present, it must be the first LINE NUMBER clause in that Report Group Description.
7. A LINE NUMBER clause with the NEXT PAGE phrase may appear only in the description of a CONTROL HEADING, DETAIL, CONTROL FOOTING, or REPORT FOOTING report group.
8. Every entry defining a printable item must either contain a LINE NUMBER clause or be subordinate to an entry that contains a LINE NUMBER clause. See the COLUMN NUMBER clause for more information.
9. The first LINE NUMBER clause in a PAGE FOOTING report group must define an absolute line-num value.
10. line-num-plus may be zero. If line-num-plus is zero, the line will be printed on the same line as the previous print line (overprint); however, line-num-plus cannot be zero for the first print line of a report group.

Syntax Rules (Screen Description)

1. The LINE clause can be specified only in an elementary screen description entry.
2. identifier-1 cannot be subscripted.

General Rules (Report Description)

1. To establish each print line for a report group, a program must specify the LINE NUMBER clause.
2. Before presenting the print line, the Report Writer Control System (RWCS) causes line positioning as specified by a LINE NUMBER clause.
3. The NEXT PAGE phrase defines the line number of a new page on which to present the report group.
4. For a complete specification on how to determine the first print line for a report group, see Appendix D, Report Writer Presentation Rules and Tables. A partial summary of these rules follows:
   If a relative clause is not the first LINE NUMBER clause in a report group, then the line number on which its print line is presented is determined by the sum of the following:
   • The line number from the previous print line of the report group
   • line-num-plus of the relative LINE NUMBER clause
   
   If the first LINE NUMBER clause in the Report Group Description entry is relative and a PAGE clause is specified, the first print line for the report group is determined as follows. See the Section 5.3.36 clause for the definitions of page-size, heading-line, first-detail-line, last-detail-line, and footing-line.
   1. REPORT HEADING
      The RWCS presents this group on a line number whose value is the sum of line-num of the first LINE NUMBER clause and heading-line minus 1.
   2. PAGE HEADING
      If a REPORT HEADING report group has been presented on the page on which this report group is to appear, the RWCS presents the PAGE HEADING relative to the final LINE-COUNTER setting of the REPORT HEADING.
      If no REPORT HEADING has been presented on the page, the RWCS presents this report group on the line number whose value is the sum of line-num of the first LINE NUMBER clause and heading-line minus 1.
   3. DETAIL, CONTROL HEADING, or CONTROL FOOTING
      If the value in LINE-COUNTER is less than first-detail-line, the RWCS presents the report group on first-detail-line.
      If the value in LINE-COUNTER is greater than or equal to first-detail-line and if this is the first body group to print on the page, the RWCS presents the report group on the line corresponding to the value in LINE-COUNTER.
      If the value in LINE-COUNTER is greater than or equal to first-detail-line and if this is not the first body group to print on the page, the RWCS presents the report group on the line whose value is the sum of LINE-COUNTER and line-num of the first LINE NUMBER clause of the current CONTROL HEADING, DETAIL, or CONTROL FOOTING report group.
   4. PAGE FOOTING
      Not applicable. The first LINE NUMBER clause of a PAGE FOOTING report group must contain an absolute line number reference.
   5. REPORT FOOTING
      If a PAGE FOOTING report group has been presented on the current page, the RWCS presents the REPORT FOOTING report group on the line whose value is the sum of the current value in LINE-COUNTER and line-num of the first LINE NUMBER clause of the REPORT FOOTING report group.
      If no PAGE FOOTING report group has been presented on the current page, the RWCS presents the REPORT FOOTING report group on the line whose value is the sum of footing-line and line-num of the first LINE NUMBER clause of the REPORT FOOTING report group.