# Compaq COBOL
Reference Manual

Previous | Contents | Index

## 6.8.15 GENERATE

Function

The GENERATE statement directs the Report Writer Control System (RWCS) to produce a report according to the Report Description entry (RD) in the Report Section of the Data Division.

> ### report-item

> names either a report-name in a Report Description entry, or the group-data-name of a TYPE IS DETAIL report group.

Syntax Rules

1. If report-item references a group-data-name, it must name a TYPE DETAIL report group. Group-data-name can be qualified by report-name.
2. If report-item references a report-name, its report description must contain:
   - A CONTROL clause
   - At least one CONTROL HEADING, DETAIL, or CONTROL FOOTING report group
   - No more than one DETAIL report group

General Rules

1. An INITIATE statement must be executed before a GENERATE statement is executed for a specific report.
2. The RWCS produces a summary report if all of the GENERATE statements for a report reference report-name. A summary report contains no TYPE IS DETAIL report groups.
3. The RWCS produces a detail report if a GENERATE statement references a DETAIL report group.
4. To detect and trigger control breaks for a specific report, the RWCS:
   - Saves the initial values within control data items as prior values when the GENERATE statement executes.
   - Compares the prior values to the current values of control data items when subsequent GENERATE statements execute. Only if the current values change does a control break occur. If a control break occurs, the current values are saved as prior values.
   - Repeats the preceding step until the last control break is processed.
5. The RWCS automatically processes any PAGE HEADING and PAGE FOOTING report groups when it must start a new page to present a CONTROL HEADING, DETAIL, or CONTROL FOOTING.
6. When the first GENERATE statement for a specific report is executed, the RWCS processes these report groups, if present in the report description, in this order:
   1. The REPORT HEADING report group.
   2. The PAGE HEADING report group.
   3. All CONTROL HEADING report groups from major to minor.
   4. For GENERATE group-data-name statements (detail reporting), the RWCS presents the specific DETAIL report group for processing.
   5. For GENERATE report-name statements (summary reporting), the RWCS does not present the DETAIL report group for processing; however, the RWCS does perform all other DETAIL report group functions.
7. When subsequent GENERATE statements are executed for a specific report, the RWCS:
   - Checks for control breaks. The rules governing the inequality of control data items are identical to the rules for relation conditions. If a control break occurs, the RWCS:
     1. Enables the CONTROL FOOTING USE procedures and CONTROL FOOTING SOURCE clauses. This allows program access to the control data item values that the RWCS uses to detect a given control break.
     2. Processes the CONTROL FOOTING report groups starting with the minor. Only CONTROL FOOTING report groups less major than the highest level at which a control break occurs are processed.
     3. Processes the CONTROL HEADING report groups in the order major to minor. Only the CONTROL HEADING report groups less major than the highest level at which a control break occurs are processed.
   - Processes the GENERATE statement. For GENERATE group-data-name statements (detail reporting), the RWCS processes the specific DETAIL report group. For GENERATE report-name statements (summary reporting), the RWCS does not present the DETAIL report group for processing; however, the RWCS does perform all other DETAIL report group functions.
8. No GENERATE statements can reference a file after executing a TERMINATE statement for the same file.

Additional References

- Section 5.3.50 clause in Chapter 5
- Section 6.8.42 statement

## 6.8.16 GO TO

Function

The GO TO statement transfers control from one part of the Procedure Division to another.

> ### proc-name

> is a procedure-name.

> ### num

> is the identifier of an elementary numeric item described with no positions to the right of the assumed decimal point.

Syntax Rules

1. A Format 1 GO TO statement that is in a consecutive sequence of imperative statements in a sentence must be the last statement in the sentence.
2. If an ALTER statement refers to a paragraph, the paragraph must consist of only a paragraph header followed by a Format 1 GO TO statement.
3. A Format 1 GO TO statement without proc-name can only be in a single-statement paragraph.

General Rules

Format 1

1. The GO TO statement transfers control to proc-name.
2. If there is no proc-name, the GO TO statement cannot execute before an ALTER statement changes its destination.

Format 2

3. The GO TO statement transfers control to the proc-name in the ordinal position indicated by the value of num.
   No transfer occurs, and control passes to the next executable statement if the value of num is one of the following:
   - Not greater than zero
   - Greater than the number of proc-names in the statement

Examples

1. Format 1:

       GO TO ENDING-ROUTINE.

2. Format 2:

       GO TO FRESHMAN
             SOPHOMORE
             JUNIOR
             SENIOR
               DEPENDING ON YEAR-LEVEL.
       MOVE ...

   Sample Results

   YEAR-LEVEL | Transfers to
   --- | ---
   1 | FRESHMAN label
   2 | SOPHOMORE label
   3 | JUNIOR label
   4 | SENIOR label
   5 | MOVE statement
   0 | MOVE statement
   -10 | MOVE statement

## 6.8.17 IF

Function

The IF statement evaluates a condition. The condition's truth value determines the program action that follows.

> ### stment-1

> is an imperative or conditional statement. An imperative statement can precede a conditional statement.

> ### stment-2

> is an imperative or conditional statement. An imperative statement can precede a conditional statement.

Syntax Rules

1. The ELSE NEXT SENTENCE phrase is optional if it immediately precedes a separator period.
2. If the END-IF phrase is specified, the NEXT SENTENCE phrase must not be specified.

General Rules

1. The scope of an IF statement ends with any of the following:
   - An END-IF phrase at the same nesting level
   - A separator period
   - An ELSE phrase associated with an IF statement at a higher nesting level
2. If the condition is true, the following control transfers occur:
   - If there is a stment-1, it executes.
     stment-1 can contain a procedure branching or conditional statement. Control then transfers according to the rules of the statement.
     Otherwise, the ELSE phrase (if any) is ignored. Control passes to the end of the IF statement.
   - If you use NEXT SENTENCE instead of stment-1, the ELSE phrase (if any) is ignored. Control passes to the next executable sentence.
3. If the condition is false, the following control transfers occur:
   - stment-1 or its substitute NEXT SENTENCE is ignored. If stment-2 is used, it executes.
     stment-2 can contain a procedure branching or conditional statement. Control then transfers according to the rules of the statement. Otherwise, control passes to the end of the IF statement.
   - If there is no ELSE phrase, stment-1 is ignored. Control passes to the end of the IF statement.
   - If the ELSE NEXT SENTENCE phrase is present, stment-1 is ignored. Control passes to the next executable sentence.
4. An IF statement can appear in either or both stment-1 and stment-2. In this case, the IF statement is considered nested, because its scope is entirely within the scope of another IF statement.
5. IF statements within IF statements are paired combinations, beginning with IF and ending with ELSE or END-IF; this pairing proceeds from left to right. Thus, an ELSE or END-IF phrase applies to the first preceding unpaired IF.

Additional References

- Section 6.1, Verbs, Statements, and Sentences
- Section 6.1.4, Scope of Statements
- Section 6.5, Conditional Expressions

Examples

1. No ELSE phrase:

       IF ITEMA < 20
         MOVE "X" TO ITEMB.

   ITEMA | ITEMB
   --- | ---
   4 | "X"
   35 | ?
   19 | "X"

2. With ELSE phrase:

       IF ITEMA > 10
         MOVE "X" TO ITEMB
       ELSE
         GO TO PROC-A.
       ADD ...

   ITEMA | Next Statement | ITEMB
   --- | --- | ---
   96 | ADD | "X"
   8 | PROC-A | ?

3. With NEXT SENTENCE phrase:
   (In each case, the next executable statement is the ADD statement.)

       IF ITEMA < 10 OR > 20
         NEXT SENTENCE
       ELSE
         MOVE "X" TO ITEMB.
       ADD ...

   ITEMA | ITEMB
   --- | ---
   5 | ?
   17 | "X"
   35 | ?

4. Nested IF statements:

       IF ITEMA > 10
         IF ITEMA = ITEMC
           MOVE "X" TO ITEMB
         ELSE
           MOVE "Y" TO ITEMB
       ELSE
         GO TO PROC-A.
       ADD ...

   Input Values |  | Output Value
   --- | --- | ---
   ITEMA | ITEMC | Next Statement | ITEMB
   12 | 6 | ADD | "Y"
   12 | 12 | ADD | "X"
   8 | 8 | PROC-A | ?

5. END-IF:
   (In this example, the initial value of ITEMD is 5.)

       IF ITEMA > 10
         IF ITEMA = ITEMC
           ADD 1 TO ITEMD
           MOVE "X" TO ITEMB
         END-IF
         ADD 1 TO ITEMD.

   ITEMA | ITEMC | ITEMB | ITEMD
   --- | --- | --- | ---
   4 | 6 | ? | 5
   15 | 6 | ? | 6
   13 | 13 | "X" | 7
   7 | 7 | ? | 5

## 6.8.18 INITIALIZE

Function

The INITIALIZE statement sets selected types of data fields to predetermined values.

> ### fld-name

> is the identifier of the receiving area data item.

> ### val

> is the sending area. It can be a literal or the identifier of a data item.

Syntax Rules

1. The phrase after the word REPLACING is the category phrase.
2. The category of the data item referred to by val must be consistent with that in the category phrase. The combination of categories must allow execution of a valid MOVE statement.
3. The same category cannot be repeated in a REPLACING phrase.
4. The description of fld-name or any item subordinate to it cannot contain the OCCURS clause DEPENDING phrase.
5. Neither fld-name nor val can be index data items.
6. fld-name cannot contain a RENAMES clause.

General Rules

1. The key word that follows the word REPLACING corresponds to a category of data. (See the section on Categories and Classes of Data in the Data Division chapter.)
2. fld-name can be an elementary or group item. If it is a group item, the INITIALIZE statement operates on the elementary items within the group item. For a table within a group item, INITIALIZE operates on the elementary items within the table.
3. Whether fld-name is an elementary item or a group item, if the REPLACING phrase is specified, all data movement operations occur as if they resulted from a series of MOVE statements with elementary item receiving areas:
   - If the receiving area is a group item, INITIALIZE affects only those subordinate elementary items whose category matches a category phrase. General Rule 6 describes the effect on elementary items when there is no REPLACING phrase.
   - INITIALIZE affects all eligible elementary items, including all occurrences of table items in the group.
   - If the receiving area is an elementary item, that item is initialized only if it matches a category phrase.
4. INITIALIZE does not affect index data items and FILLER data items.
5. INITIALIZE does not affect items subordinate to fld-name that contain a REDEFINES clause. Nor does it affect data items subordinate to those items. However, fld-name itself can have a REDEFINES clause or be subordinate to a data item that does.
6. When there is a REPLACING phrase, val is the sending field for each of the implicit MOVE statements.
7. When there is no REPLACING phrase, the sending field for the implicit MOVE statements is as follows:
   - SPACES, if the data item category is alphabetic, alphanumeric, or alphanumeric edited
   - ZEROS, if the data item category is numeric or numeric edited
8. INITIALIZE operates on each fld-name in the order it appears in the statement. When fld-name is a group item, INITIALIZE operates on its eligible subordinate elementary items in the order they are defined in the group.
9. If fld-name occupies the same storage area as val, the execution result of this statement is undefined. (See the section on Overlapping Operands and Incompatible Data.)

Additional References

- Section 6.8.22, MOVE statement
- Section 6.6.7, Overlapping Operands and Incompatible Data

Examples

In the examples' results, a hyphen (-) means that the value of the data item is unchanged; s represents the character space. The examples assume this data description:

    01  ITEMA.
        03  ITEMB      PIC X(4).
        03  ITEMC.
            05  ITEMD  PIC 9(5).
            05  ITEME  PIC $$$9.99.
            05  ITEMF  PIC XX/XX.
        03  ITEMG.
            05  ITEMH  PIC 999.
            05  ITEMI  PIC XX.
            05  ITEMJ  PIC 99.9.
        03  ITEMK      PIC X(4) JUSTIFIED RIGHT.

1. `INITIALIZE ITEMA.`
2. `INITIALIZE ITEMB ITEMG.`
3. `INITIALIZE ITEMA REPLACING ALPHANUMERIC BY "ABCDE".`
4. `INITIALIZE ITEMG REPLACING NUMERIC BY 9.`
5. `INITIALIZE ITEMA REPLACING NUMERIC-EDITED BY 16.`
6. `INITIALIZE ITEMA REPLACING ALPHANUMERIC-EDITED BY "ABCD".`
7. `INITIALIZE ITEMA REPLACING ALPHANUMERIC BY "99".`

| ITEMB | ITEMD | ITEME | ITEMF | ITEMH | ITEMI | ITEMJ | ITEMK
--- | --- | --- | --- | --- | --- | --- | --- | ---
1. | ssss | 00000 | ss$0.00 | ss/ss | 000 | ss | 00.0 | ssss
2. | ssss | -- | -- | -- | 000 | ss | 00.0 | --
3. | ABCD | -- | -- | -- | -- | AB | -- | BCDE
4. | -- | -- | -- | -- | 009 | -- | -- | --
5. | -- | -- | s$16.00 | -- | -- | -- | 16.0 | --
6. | -- | -- | -- | AB/CD | -- | -- | -- | --
7. | 99ss | -- | -- | -- | -- | 99 | -- | ss99

## 6.8.19 INITIATE

Function

The INITIATE statement causes the Report Writer Control System (RWCS) to begin processing a report.

> ### report-name

> names a report defined by a Report Description entry (RD) in the Report Section of the Data Division.

General Rules

1. The INITIATE statement does not automatically open a report file. The program must execute either an OPEN OUTPUT or an OPEN EXTEND statement before it can execute an INITIATE statement.
2. Upon execution of the INITIATE statement, the RWCS sets all sum counters, LINE-COUNTER, and PAGE-COUNTER to zero.
3. If the INITIATE statement has more than one report-name, the statement executes as if there were a separate INITIATE statement for each report-name.
4. A program must execute a TERMINATE statement before it can execute another INITIATE statement for the same report-name.

Additional Reference

Section 6.8.42, USE statement

## 6.8.20 INSPECT

Function

The INSPECT statement counts or replaces occurrences of single characters or groups of characters in a data item.

> ### src-string

> is the identifier of a group item or an elementary data item with DISPLAY usage. INSPECT operates on the contents of this data item.

> ### tally-ctr

> is the identifier of an elementary numeric data item.

> ### delim-val

> is the character-string that delimits the INSPECT operation. Its content restrictions are the same as those for compare-val.

> ### compare-val

> is the character-string INSPECT uses for comparison. It is a nonnumeric literal (or figurative constant other than ALL literal) or the identifier of an elementary alphabetic, alphanumeric, or numeric data item with DISPLAY usage.

> ### replace-char

> is the one-character item that replaces all characters. Its content restrictions are the same as those for compare-val.

> ### replace-val

> is the character-string that replaces occurrences of compare-val. Its content restrictions are the same as those for compare-val.

> ### compare-chars

> is the string that contains the individual characters that convert to those in convert-chars. It is the same kind of item as compare-val.

> ### convert-chars

> is the string that contains the individual characters to which the characters in compare-chars convert. It is the same kind of item as compare-val.

Syntax Rules

All Formats

1. If compare-val, delim-val, replace-char, or compare-chars is a figurative constant, it refers to an implicit one-character data item.
2. A compare-val of an ALL or LEADING phrase, and a CHARACTERS, FIRST, or CONVERTING phrase can have no more than one BEFORE and one AFTER phrase following it.

Format 2

3. The sizes of the data referred to by replace-val and compare-val must be equal. When replace-val is a figurative constant, its size equals that of the data referred to by compare-val.
4. When there is a CHARACTERS phrase, the size of the data referred to by delim-val must be one character.

Format 3

5. A Format 3 INSPECT statement is equivalent to a Format 1 statement followed by a Format 2 statement. Therefore, Syntax Rules 3 and 4 apply to the REPLACING clause of Format 3.

Format 4

6. The sizes of the data referred to by convert-chars and compare-chars must be equal. When convert-chars is a figurative constant, its size equals that of the data referred to by compare-chars.
7. The same character cannot appear more than once in the data referred to by compare-chars.

General Rules

All Formats

1. Inspection includes: (a) comparison, (b) setting boundaries for the BEFORE and AFTER phrases, and (c) tallying or replacing. Inspection starts at the leftmost character position of the src-string data item. It proceeds to the rightmost character position, as described in General Rules 3 to 5.
2. If src-string, compare-val, delim-val, replace-val, compare-chars, or convert-chars refers to a data item, the INSPECT statement treats the contents of the item according to the category implied by its data description.
   1. For an alphabetic or alphanumeric item---INSPECT treats the data item as a character-string.
   2. For an alphanumeric edited, numeric edited, or unsigned numeric item---INSPECT treats the data item as though:
      - The data item were redefined as alphanumeric.
      - The INSPECT statement were written to refer to the redefined data item. (See General Rule 2a.)
   3. For a signed numeric item---INSPECT treats the data item as though it were moved to an unsigned numeric data item of the same length. It then applies General Rule 2b.
3. If the size of src-string is zero characters, inspection does not occur.
4. If the size of compare-val is zero characters, compare-val does not match in any src-string comparison.
5. If any identifier is subscripted or is a function-identifier, the subscript or function-identifier is evaluated only once as the first operation in the execution of the INSPECT statement.
6. During inspection of src-string, each matched occurrence of compare-val is:
   1. Tallied (Formats 1 and 3)
   2. Replaced by replace-char or replace-val (Formats 2 and 3)
7. The comparison operation determines which occurrences of compare-val are tallied or replaced:
   1. INSPECT processes the operands of the TALLYING and REPLACING phrases in the order they appear, from left to right. The first compare-val is compared to the same number of contiguous characters, starting with the leftmost character position in src-string. compare-val and the compared characters in src-string match if they are equal, character for character. Otherwise, they do not match.
   2. If the comparison of the first compare-val does not produce a match, the comparison repeats for each successive compare-val until either:
      - A match results
      - There is no next compare-val
      When there is no next compare-val, INSPECT determines the leftmost character position in src-string for the next comparison. This position is to the immediate right of the leftmost character position for the preceding comparison. The comparison cycle starts again with the first compare-val.
   3. For each match, tallying, replacing, or both occur, as described in General Rules 9 to 17. INSPECT determines the leftmost character position in src-string for the next comparison. This position is to the immediate right of the rightmost character position that matched in the preceding comparison. The comparison cycle starts again with the first compare-val.
   4. Inspection ends when the rightmost character position of src-string has either:
      - Participated in a match
      - Served as the leftmost character position
   5. When the CHARACTERS phrase is present, INSPECT does not perform any comparison on the contents of src-string. The cycle described in General Rules 6a to 6d operates as if:
      - Inspection compares a one-character data item to each character in src-string
      - A match occurs for each comparison
8. The BEFORE phrase determines the character position in src-string that will be the final leftmost position in the comparison operation.
   1. Comparison occurs on src-string only:
      - From its leftmost character position
      - To, but not including, the first occurrence of delim-val
   2. The position of the first occurrence of delim-val in src-string is determined before the first comparison operation.
   3. If delim-val does not occur in src-string, the comparison operation proceeds as if there were no BEFORE phrase.
9. The AFTER phrase determines the character position in src-string that will be the first leftmost position in the comparison operation.
   1. Comparison occurs on src-string only:
      - From the character position to the immediate right of the rightmost character position of delim-val's first occurrence
      - To the rightmost position of src-string
   2. The position of the first occurrence of delim-val in src-string is determined before the first comparison operation.
   3. If delim-val is not in src-string, no match occurs, and inspection causes no tallying or replacement.

Previous | Next | Contents | Index