Compaq COBOL
Reference Manual


Previous Contents Index

5.3.13 BLANK WHEN ZERO

Function

The BLANK WHEN ZERO clause replaces zeros with spaces when a data item's value is zero. In the context of the Screen Section, it displays spaces when the value of a screen item to be displayed on the screen is zero.


Syntax Rules

  1. The BLANK WHEN ZERO clause can be used only for a numeric or numeric edited elementary item.
  2. A data item or screen item containing the BLANK WHEN ZERO clause must be implicitly or explicitly described with DISPLAY usage.
  3. The syntax for a data item allows the spelling ZERO or ZEROES or ZEROS. The syntax for a screen item allows the spelling ZERO only.

General Rules

  1. The BLANK WHEN ZERO clause causes a data item or screen item to contain spaces when its value is zero.
  2. When the data item or screen item has a numeric PICTURE string, the BLANK WHEN ZERO clause makes the item's category numeric edited.
  3. The BLANK WHEN ZERO clause is ignored in the description of an input screen item.

Additional Reference

Section 6.8.10 statement in Chapter 6

5.3.14 BLINK

Function

The BLINK clause displays characters on the screen with the blink on character attribute.


Syntax Rule

The BLINK clause can be specified only in an elementary screen description entry.

General Rule

Blinking is only detectable when any of the following conditions are true:

Additional References

5.3.15 CODE

Function

The CODE clause specifies a two-character literal that identifies each print line as belonging to a specific report.


report-code

must be a two-character nonnumeric literal.

Syntax Rule

If the CODE clause is specified for any report in a file, it must be specified for all reports in that file.

General Rules

  1. When the CODE clause is specified, report-code is automatically placed in the first two character positions of each Report Writer logical record.
  2. The positions occupied by report-code are not included in the description of the print line, but are included in the logical record size.

Additional Reference

Section 5.3.3

Example

The following file contains three reports:


FILE SECTION. 
FD  REPORT-FILE 
    LABEL RECORDS ARE STANDARD 
    REPORTS ARE REPORT1 
                REPORT2 
                REPORT3. 
REPORT SECTION. 
RD  REPORT1 ...
    CODE "AA". 
 
RD  REPORT2...
    CODE "BB". 
 
RD  REPORT3...
    CODE "CC". 

5.3.16 COLUMN NUMBER

Function

In a report group description, the COLUMN NUMBER clause identifies a printable item and specifies the position of the item on a print line. In a screen description, the COLUMN NUMBER clause specifies the horizontal screen coordinate for a screen item.


column-num

is a positive integer greater than zero.

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. The COLUMN NUMBER clause can be specified only at the elementary level within a report group. The COLUMN NUMBER clause, if present, must appear in a Format 3 Report Group Description entry, or be subordinate to an entry that contains a LINE NUMBER clause in a Format 2 Report Group Description entry.
  2. A printable item is a data item whose size and content is specified by an elementary report entry.
  3. An elementary report entry contains a COLUMN NUMBER clause, a PICTURE clause, and a SOURCE, SUM, or VALUE clause.
  4. Each printable item within a given print line must be defined in ascending column number order such that each printable item occupies a unique sequence of contiguous character positions.

Syntax Rules (Screen Description)

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

General Rules (Report Description)

  1. The presence of a COLUMN NUMBER clause indicates that these items, if present, are to be presented on the print line:
    The absence of a COLUMN NUMBER clause indicates that the entry is not printable.
  2. Column number 1 is the leftmost position of the print line.
  3. column-num specifies the column number of the leftmost character position of the printable item.
  4. The Report Writer Control System supplies space characters for all positions of a print line not occupied by printable items.

General Rules (Screen Description)

  1. The COLUMN clause, in conjunction with the LINE clause, establishes the starting position for a screen item. This position is an offset from the starting screen coordinates specified in the ACCEPT or DISPLAY statement. The COLUMN clause specifies the horizontal coordinate.
  2. The COLUMN clause without the PLUS phrase specifies the absolute column position of the screen item.
  3. The COLUMN clause with the PLUS phrase specifies a column number relative to that at which the preceding item ends, regardless of whether or not the ACCEPT or DISPLAY statement displays the preceding item on the screen.
  4. A setting of COLUMN 1 is assumed in screen description entries that specify the LINE clause but omit the COLUMN clause.
  5. If both the LINE clause and the COLUMN clause are omitted, the following apply:

Additional References

Examples (Report Description)

  1. The following is an example of the COLUMN NUMBER clause in a LINE NUMBER clause:


      02     LINE 10 COLUMN 1 PIC X(11) VALUE "TOTAL ITEMS". 
     
                         1         2         3         4 
    column:     1234567890123456789012345678901234567890 
     
                TOTAL ITEMS 
    

  2. The following is an example of the COLUMN NUMBER clause subordinate to a LINE NUMBER clause:


      02     LINE 5 ON NEXT PAGE. 
        03      COLUMN 1  PIC X(10)        VALUE "(Id Number". 
        03      COLUMN 12 PIC 9999         VALUE 1234. 
        03      COLUMN 16 PIC X            VALUE ")". 
        03      COLUMN 18 PIC X(11)        VALUE "TOTAL SALES". 
        03 TSAL COLUMN 30 PIC $$$$,$$$.99- VALUE 123456.78. 
     
                          1         2         3         4 
    column:     123456789012345678901234567890123456789012345 
     
                (Id Number 1234) TOTAL SALES $123,456.78 
    

5.3.17 CONTROL

Function

The CONTROL clause establishes the levels of the control hierarchy for the report.


control-name

is any data-name in the Subschema, File, Working-Storage, or Linkage Section.

Syntax Rules

  1. control-name can be qualified.
  2. Each occurrence of control-name must identify a different data item.
  3. control-name must not have a variable-occurrence data item subordinate to it.
  4. If the associated report file connector is an external file connector, control-name must reference the same external data item in all programs in the run unit.

General Rules

  1. The word FINAL specifies the most major control item. From here, the hierarchy descends to control-name, which is the major control; to the next recurrence of control-name, which is an intermediate control; and so forth to the last recurrence of control-name, which is the minor control.
  2. A control break is a change in the value of a control-name.
  3. FINAL is used when the most inclusive control group in the report is not associated with a control-name.
  4. The first time a GENERATE statement is executed, the Report Writer Control System (RWCS) saves the values of all control data items associated with that report. After that, every time a GENERATE statement is executed, the RWCS tests those control data items to see if their values have changed. If so, a control break occurs. This control break is associated with the highest level control item whose value has changed.
  5. Control breaks cause the RWCS to present appropriate CONTROL HEADER and CONTROL FOOTING report groups for printing. Figure 5-8 shows the report groups the RWCS processes (X) when you define FINAL, major, intermediate, or minor control-name in a CONTROL HEADING or CONTROL FOOTING phrase in a Report Group Description entry. For example, if the value in a major control-name changes, the RWCS processes all major, intermediate, and minor control groups specified in CONTROL HEADING and CONTROL FOOTING report groups.

    Figure 5-8 Control Break Levels and Their Printed Report Groups


  6. The RWCS tests for a control break by comparing the contents of each control data item with the prior contents of each control data item that were saved when the previous GENERATE statement for the same report was executed. The RWCS applies the inequality relation test as follows:

Additional References

Examples

  1. This example prints a total record count from TOTAL-LINE at the end of the report because control is FINAL. It is a major control break and prints only once.


    WORKING-STORAGE SECTION. 
    01      RECORD-COUNT    PIC 9(9) VALUE 0. 
     
    REPORT SECTION. 
    RD      MASTER-REPORT...
            CONTROL IS FINAL. 
     
    01      DETAIL-LINE TYPE IS DETAIL...
     
    01      TOTAL-LINE  TYPE IS CONTROL FOOTING FINAL. 
       02   COLUMN 20 PIC X(17) VALUE "TOTAL RECORDS: ". 
       02   COLUMN 40 PIC ZZZ,ZZZ,ZZ9 SOURCE RECORD-COUNT. 
    PROCEDURE DIVISION. 
    BEGIN. 
        OPEN INPUT...
        OPEN OUTPUT...
        INITIATE MASTER-REPORT. 
    010-READ-FILE. 
        READ... AT END GO TO 999-EOJ. 
        GENERATE DETAIL-LINE. 
        ADD 1 TO RECORD-COUNT. 
        GO TO 010-READ-FILE. 
    999-EOJ. 
        TERMINATE MASTER-REPORT. 
        CLOSE...
        STOP RUN. 
    

  2. In the following example, a report defines four control totals in the control clause. The source of these control totals is in an input file---INPUT-FILE. The file is presorted in ascending sequence by MAJOR-CONTROL, INTERMEDIATE-CONTROL, and MINOR-CONTROL. The RWCS will monitor these fields in the input file for any changes. If a new record contains data different from the previous record read, the RWCS triggers a control break.
    In this example, if the value in MINOR-CONTROL changes, a break occurs and the RWCS processes the minor control report group CONTROL FOOTING MINOR-CONTROL. If the value in INTERMEDIATE-CONTROL changes, a break occurs and the RWCS processes the intermediate and minor control report groups CONTROL FOOTING INTERMEDIATE-CONTROL and CONTROL FOOTING MINOR-CONTROL. If the value in MAJOR-CONTROL changes, a break occurs and the RWCS processes the major, intermediate, and minor control report groups CONTROL FOOTING MAJOR-CONTROL, CONTROL FOOTING INTERMEDIATE-CONTROL, and CONTROL FOOTING MINOR-CONTROL.


    FILE SECTION. 
     
    FD      INPUT-FILE...
    01      INPUT-RECORD. 
        02    MAJOR-CONTROL           PIC...
        02    ...
        02    MINOR-CONTROL           PIC...
        02    ...
        02    INTERMEDIATE-CONTROL    PIC...
        02    ...
     
    FD      REPORT-FILE...
            REPORT IS SUMMARY-REPORT. 
    REPORT SECTION. 
    RD      SUMMARY-REPORT...
            CONTROLS ARE FINAL 
                         MAJOR-CONTROL 
                         INTERMEDIATE-CONTROL 
                         MINOR-CONTROL. 
     
    01  DETAIL-LINE TYPE IS DETAIL...
     
    01  TYPE IS CONTROL FOOTING FINAL ...
    01  TYPE IS CONTROL FOOTING MINOR-CONTROL...
    01  TYPE IS CONTROL FOOTING MAJOR-CONTROL...
    01  TYPE IS CONTROL FOOTING INTERMEDIATE-CONTROL...
    

5.3.18 Data-Name

Function

data-name specifies a data item that your program can explicitly reference. FILLER specifies an item that cannot be explicitly referenced.


data-name

Syntax Rules

  1. In the File, Working-Storage, and Linkage Sections, data-name or the key word FILLER (if present) must be the first word after the level-number in each data description entry.
  2. In the Report Section, data-name need not appear in a report group description entry and the key word FILLER must not be used.

General Rules

  1. If there is no data-name or FILLER clause, the compiler treats the data item as a FILLER item.
  2. The key word FILLER can name a data item. However, a program cannot explicitly refer to FILLER items.
  3. The key word FILLER can name a conditional variable. A program cannot refer to the conditional variable. However, it can refer to the value of the conditional variable by referring to its associated condition-names.
  4. In the Report Section, data-name must be used when:
    1. data-name represents a report group to be referred to by a GENERATE or a USE statement in the Procedure Division.
    2. Reference will be made to the sum counter in the Procedure Division or Report Section.
    3. The UPON phrase of the SUM clause references a DETAIL report group.
    4. data-name provides sum counter qualification.
  5. If this clause is omitted, the Report Writer Control System does not allow explicit references to the data item.

Examples

  1. Elementary FILLER items:
    In this example, the program can refer only to the group item, ITEMA.


    01  ITEMA. 
        03  FILLER PIC X(10) VALUE SPACES. 
        03  PIC X(2) VALUE "AB". 
        03  PIC 9 VALUE 6. 
    

  2. Group FILLER items:
    In this example, the program can refer to any elementary item. However, it cannot refer to the record or to the group item that contains ITEMC and ITEMD.


    01  FILLER. 
        03  ITEMA     PIC X(4). 
        03  ITEMB     PIC 9(7). 
        03  FILLER. 
            05  ITEMC PIC X. 
            05  ITEMD PIC 9(8)V99. 
        03  ITEME     PIC X. 
    

  3. Report Writer items:
    In this Report Writer example, the program can refer to DL-NAME and DETAIL-LINE, but not to the data beginning in LINE 10, COLUMN 25. Note that FILLER cannot be used in place of a Report Writer data-name.


    01  DETAIL-LINE TYPE IS DETAIL. 
        02  LINE 10. 
            03  DL-NAME     COLUMN 1   SOURCE INPUT-NAME. 
            03              COLUMN 25  SOURCE INPUT-ADDRESS. 
    

5.3.19 DATA RECORDS

Function

The DATA RECORDS clause documents the names of a file's record description entries.


rec-name

is the name of a data record. It must be defined by a level 01 data description entry subordinate to the file description entry.

Syntax Rule

The order of appearance of multiple rec-name entries is not significant.

General Rule

The DATA RECORDS clause is for documentation only.

5.3.20 ERASE

Function

The ERASE clause clears from the starting cursor position to the end of either the line or the screen.


Syntax Rule

The ERASE clause can be specified only for elementary screen description entries.

General Rules

  1. Blanking begins at the starting position of the screen item in whose description the ERASE EOL clause is included, and continues to the end of the line.
  2. Blanking begins at the starting position of the screen item in whose description the ERASE EOS clause is included, and continues through to the end of the screen.
  3. If you specify neither the BLANK nor the ERASE clause, only the particular character positions corresponding to the screen item are modified when the element is displayed. The rest of the screen content remains the same.
  4. The ERASE clause is ignored in an ACCEPT statement.

Additional References

Section 6.8.10 statement in Chapter 6

5.3.21 EXTERNAL

Function

The EXTERNAL clause specifies that a data item or a file connector in a defining program is common to other programs in the run unit if the program defines it identically. The group and elementary data items of an external data record and files associated with an external file connector are available to every program in the image that describes them.


Syntax Rules

  1. The EXTERNAL clause can appear only in file description entries or in record description entries in the Working-Storage Section.
  2. In a record description entry, only level numbers 01 and 77 can specify the EXTERNAL clause.
  3. A program and any program it contains, cannot define identical data-names if their data description entries or file description entries have EXTERNAL clauses.
  4. The VALUE clause or the REDEFINES clause cannot be in a data description entry that contains or is subordinate to, an entry that contains the EXTERNAL clause.
  5. When using the SAME RECORD AREA clause for several files, the Record Description entries or the file description entries for these files must not include the EXTERNAL clause.
  6. Entries that contain the EXTERNAL clause must be named.

General Rules

  1. Data in a record either subordinate to an external FD, or named by the subject of the EXTERNAL clause, is external. Any program in the image that describes and optionally redefines this data may access and process this data subject to the following general rules.
  2. If two or more programs in the image describe the same external data record, the associated data description entries (except the GLOBAL clause) must be identical. All subordinate data-names, data items, and redefinitions must also be identical.
  3. A program that describes an external data record can contain a Data Description entry that redefines the complete external record. This redefinition need not be the same in other programs in the image.
  4. Use of the EXTERNAL clause does not imply that the associated file-name or data-name is a global name.
  5. The file connector associated with a file description entry is an external file connector.
  6. If two or more programs in an image describe the same external file connector, the clauses associated with the description of that file must be functionally identical and any data items referenced by those clauses must be external.

Technical Notes

Additional References

Examples

In the following Working-Storage entries, the data items in RECORD-A are available to any program in the run unit that also describes RECORD-A and its data items. RECORD-B and the data items in it are not available to any other program.


01 RECORD-A EXTERNAL. 
    03  ITEMA  PIC X. 
    03  ITEMB  PIC X(22). 
    03  ITEMC  PIC 999. 
01 RECORD-B. 
    03  ITEMA  PIC X(12). 
    03  ITEMD  PIC X. 
    03  ITEME  PIC 9(18). 


Previous Next Contents Index