Compaq COBOL
Reference Manual

Function

The REDEFINES clause allows different data description entries to describe the same storage area.

other-data-item

is a data-name. It identifies the data description entry that first defines the storage area.

Note Level-number, data-name, and FILLER are not part of the REDEFINES clause. They are included in the general format only to clarify the relative position of the clause.

Syntax Rules

1. The subject of the REDEFINES clause is the data-name or FILLER in a Format 1 data description entry.
2. The REDEFINES clause must immediately follow its subject.
3. The level-numbers of the subject of the REDEFINES clause and other-data-item must be the same. However, they cannot be either 66 or 88.
4. The REDEFINES clause cannot be used in a level 01 entry in the File Section.
5. The data description entry for other-data-item cannot contain an OCCURS clause. However, other-data-item can be subordinate to an item whose data description entry contains an OCCURS clause. In that case, the reference to other-data-item in the REDEFINES clause cannot be subscripted or indexed.
6. Neither the original definition nor the redefinition can contain a variable occurrence data item.
7. If other-data-item is either an external record or anything other than a level 01 entry, the number of character positions it contains must be greater than or equal to the number in the subject of the REDEFINES clause. If other-data-item is a level 01 entry, and is not an external record, its description need not follow this rule; that is, other-data-item can contain fewer character positions than the subject of the REDEFINES clause.
8. Other-data-item cannot be qualified even if it is not unique. The reference to other-data-item is unique without qualification because of the placement of the REDEFINES clause.
9. A program can have multiple redefinitions of the same character positions. However, they must all refer to other-data-item, the data-name that originally defined the area.
10. The redefining entries cannot contain VALUE clauses except in condition-name entries.
11. No entry with a level-number lower than that of other-data-item can occur between the data description entry for other-data-item and the redefinition.
12. The entries redefining the storage area must immediately follow those that originally defined it. There can be no intervening entries that define additional storage areas.

General Rules

1. Storage allocation starts at the location of other-data-item. Storage allocation continues until it defines the number of character positions in the data item referred to by the subject of the REDEFINES clause.
2. If more than one data description entry defines the same character position, the program can refer to the character position using the data-name associated with any of those data description entries.

Additional References

• Section 5.3.4 entry
• Section 5.2.3, Additional Alignment Rules for Record Allocation

Example

This example shows the following:

• A sample program containing multiple redefinitions of the same area
• The results of the sample program statements
• The allowable subscripts and the contents for each data item in the program

Function

The RENAMES clause groups elementary items in alternative or overlapping ways.

new-name

is the data-name of the item being described. It identifies an alternate grouping of one or more items in a record.

rename-start

is the data-name of the leftmost data item in the area. It can be qualified.

rename-end

is the data-name of the rightmost data item in the area. It can be qualified.

Note Level-number 66 and new-name are not part of the RENAMES clause. They are in the general format only to clarify the relationship.

Syntax Rules

1. A logical record can have any number of RENAMES entries.
2. All RENAMES entries referring to data items in a logical record must immediately follow the last data description entry of the record description entry.
3. The program cannot qualify data-names with new-name.
4. The program can qualify new-name only by the names of the associated level 01, FD, or SD entries.
5. The data description entries for rename-start and rename-end:
   • Cannot have an OCCURS clause
   • Cannot be subordinate to an item whose data description entry has an OCCURS clause
6. rename-start and rename-end must be the names of elementary items or groups of elementary items in the same logical record. They cannot be the same data-name.
7. A level 66 entry cannot rename another level 66 entry. Nor can it rename a level 88, level 01, or level 77 entry.
8. None of the items in the range, including rename-start and rename-end, can be variable occurrence data items.
9. The words THRU and THROUGH are equivalent.
10. rename-end cannot be subordinate to rename-start. The beginning of rename-end cannot be to the left of the beginning of rename-start. The end of rename-end must be to the right of the end of rename-start.

General Rules

1. If rename-end is used, new-name includes all elementary items:
   • Starting with rename-start, if rename-start is an elementary item or the first elementary item in rename-start, or if rename-start is a group item
   • Ending with rename-end, if rename-end is an elementary item or the last elementary item in rename-end, or if rename-end is a group item
2. If rename-end is not used, all data attributes for rename-start become data attributes for new-name. In this case, you are renaming a single data item. If that item is a group item, new-name is also treated as a group item. If that item is an elementary item, new-name is also treated as an elementary item.

Additional Reference

Section 5.3.4

Example

In the following example, the box RESULTS displays the values given when using the RENAMES clause:

Function

The REPORT clause in a file description entry (FD) specifies the Report Description (RD) report names that comprise a report file.

Syntax Rules

1. Each report-name in the REPORT clause must be the subject of a Report Description entry (RD) in the Report Section of the same program. report-name can appear in only one REPORT clause.
2. report-names can appear in any order.
3. The file-name in a file description entry for a Report File can be referenced only by the OPEN statement with the OUTPUT or EXTEND phrase or by the CLOSE statement.

General Rules

1. More than one report-name in a REPORT clause indicates that the file contains more than one report.
2. After executing an INITIATE statement and before executing a TERMINATE statement for the same report file, the report file is under the control of the Report Writer Control System (RWCS). While a report file is under control of the RWCS, no input/output statement may reference that report file.
3. If the associated file connector is an external file connector, every file description entry in the run unit associated with that file connector must describe it as a report file.

Technical Note

On OpenVMS, the DCL PRINT command inserts a form-feed character when a form is within four lines from the bottom. This positions the report to the top of the next logical page.

Report Writer files are written in print format. Line spacing positions the report to the top of the next logical page.

Therefore, use the PRINT/NOFEED command to suppress the insertion of form-feed characters and to print your Report Writer files correctly. For example:

$ PRINT/NOFEED full-file-name <>

Additional References

• Section 5.3.1
• Section 5.3.3

Function

The REQUIRED clause specifies that in the context of an ACCEPT statement, the user must enter at least one character in the input or update field.

Syntax Rule

The REQUIRED clause cannot be specified in the description of a literal screen item.

General Rules

1. If the REQUIRED clause is specified at group level, it applies to each input and update screen item in that group.
2. The REQUIRED clause takes effect 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 this clause, alphanumeric screen items must contain at least one nonspace character, and numeric screen items must have a nonzero value.
4. For update fields, the REQUIRED 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.
5. The REQUIRED clause is not effective if a function key is used to terminate the accept operation.
6. The specification of the FULL and REQUIRED clauses together requires that the field must always be filled entirely by the user.
7. The REQUIRED clause is ignored for an output field.

Additional Reference

Section 6.8.1 statement in Chapter 6 <>

5.3.44 REVERSE-VIDEO (Alpha)

Function

The REVERSE-VIDEO clause specifies that the field is displayed with the default or specified foreground and background colors exchanged.

Syntax Rule

The REVERSE-VIDEO clause can be specified only for elementary screen items.

Additional Reference

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

Function

The SECURE clause suppresses the display of input characters on the screen.

Syntax Rule

The SECURE clause can only be specified for an input screen item.

General Rules

1. If the SECURE clause is specified at group level, it applies to each input screen item in that group.
2. When the SECURE clause is used, characters introduced for the input field do not appear on the screen, yet the cursor moves as usual.

Additional Reference

Section 6.8.1 statement in Chapter 6 <>

5.3.46 SIGN

Function

The SIGN clause specifies the operational sign's position and type of representation.

For screen description entries, the SIGN clause specifies the position of the sign character in the field. The sign character always occupies a separate position in the field, regardless of whether or not you specify SEPARATE.

Syntax Rules

Format 1

1. The SIGN clause can be used only in a numeric data description entry or screen description entry whose PICTURE contains the S symbol, or for a group item containing such entries.
2. The data items to which the SIGN clause applies must have display usage.
3. If a file description entry has a CODE-SET clause, all signed numeric data description entries associated with the file description entry must contain the SIGN IS SEPARATE clause.

General Rules

Both Formats

1. The SIGN clause specifies the operational sign's position and type of representation. It applies to a numeric data description entry or screen description entry or to each numeric data description entry or screen description entry subordinate to a group.
2. The SIGN clause applies only to numeric data description entries or screen description entries whose PICTURE clause contains the S symbol. S indicates the presence of an operational sign. However, S does not specify the sign's representation or, necessarily, its position.
3. If you specify the SIGN clause for both a group item and a group item subordinate to it, the SIGN clause for the subordinate group overrides the group item SIGN clause.
4. If you specify the SIGN clause for both a group item and an elementary numeric item subordinate to it, the SIGN clause for the elementary item overrides the group item SIGN clause.
5. A numeric data description entry or screen description entry to which no optional SIGN clause applies, but whose PICTURE contains an S symbol, has an operational sign.
   • The numeric data description entry is equivalent to an entry that contains the SIGN IS TRAILING clause without the SEPARATE CHARACTER phrase.
   • The screen description entry is equivalent to an entry that contains the SIGN IS TRAILING with the SEPARATE CHARACTER phrase.
6. If you specify the SEPARATE CHARACTER phrase (or it is implied):
   • The operational sign is the leading (or trailing) character of the elementary numeric data item. The sign does not share this position with a digit.
   • The S symbol in the PICTURE counts toward data or screen item size. That is, it represents a character position.
   • The operational sign for positive is the plus sign (+).
   • The operational sign for negative is the minus sign (-).
7. Every numeric data item whose PICTURE contains the S symbol is a signed numeric data item. If you specify the SIGN clause for such an item, necessary conversions for computations or comparisons occur automatically.

Format 1 (Data Description)

8. If you do not specify the SEPARATE CHARACTER phrase:
   • The operational sign is associated with the leading (or trailing) digit position of the elementary numeric item. The sign shares this character position with a digit.
   • The S symbol in the PICTURE does not count toward the size of the item. That is, it does not represent a character position.
   • The character in the operational sign position represents both a numeric digit and the item's algebraic sign. Table 5-11 shows the characters representing positive and negative signs for all numeric digits. Where more than one character appears, the first is the character generated as the result of machine operations.

     Table 5-11 Positive and Negative Signs for All Numeric Digits

     Digit Values	Positive Sign	Negative Sign
     0	{, [, ?, or 0	}, ], :, or !
     1	A or 1	J
     2	B or 2	K
     3	C or 3	L
     4	D or 4	M
     5	E or 5	N
     6	F or 6	O
     7	G or 7	P
     8	H or 8	Q
     9	I or 9	R

Function

The SOURCE clause identifies a data item to be sent to an associated printable item defined within a Report Group Description entry.

source-id

names an elementary item in the Data Division.

Syntax Rules

1. If source-id is a Report Section item it must be either:
   • A PAGE-COUNTER
   • A LINE-COUNTER
   • A sum counter that is part of the report within which the SOURCE clause appears
2. The Report Writer Control System (RWCS) moves the contents of source-id to the printable item. source-id definitions must conform to the rules for sending items in the MOVE statement.

General Rule

The RWCS executes implicit MOVE statements specified by the SOURCE clauses when it formats the print lines (just before it presents them).

Additional References

• Section 5.3.16 clause (printable item)
• Section 5.3.50 clause
• Section 6.8.22 statement in Chapter 6

Function

The SUM clause establishes a Report Writer sum counter and names the data items to be summed.

sum-name

names a numeric data item with an optional sign in the Subschema, File, Working-Storage, or Linkage Sections, or another sum counter in the Report Section.

detail-report-group-name

names a DETAIL report group.

control-foot-name

must reference a control-name in the report's CONTROL clause.

Syntax Rules

1. A SUM clause can appear only in the description of a CONTROL FOOTING report group.
2. If there is no UPON phrase, any sum-name in the SUM clause that is itself a sum counter must be defined either in the same report group that contains this SUM clause or in a report group at a lower level in the control hierarchy of this report.
   If there is an UPON phrase, sum-name must not reference a sum counter.
3. If the associated report file connector is an external file connector and if sum-name references a numeric data item in the Subschema, File, Working-Storage, or Linkage Sections, then sum-name must reference the same external data item in all programs in the run unit.
4. detail-report-group-name must be a control-name in a CONTROL clause and must be the name of a DETAIL report group described in the same report as the CONTROL FOOTING report group in which the SUM clause appears.
5. detail-report-group-name may be qualified by a report-name.
6. control-foot-name must not be at a lower control level than the associated control level for the report group in which the RESET phrase appears.
   If FINAL appears in the RESET phrase, FINAL must also appear in the CONTROL clause for this report.
7. The highest permissible qualifier for sum-name is the report-name.

General Rules

1. The SUM clause establishes a sum counter. At run time, the Report Writer Control System (RWCS) adds the value in each sum-name to the sum counter. This addition is consistent with the rules for arithmetic statements.
2. The UPON phrase provides for selective subtotalling. Subtotalling occurs each time the RWCS processes the DETAIL report group referenced by detail-report-group-name.
3. If there is a RESET phrase, the RWCS will set the sum counter to zero when the RWCS is processing the designated level of control hierarchy. If there is no RESET phrase, the RWCS will set the sum counter in the CONTROL FOOTING report group to zero when the RWCS processes that report group.
   The RWCS initially sets sum counters to zero during the execution of the INITIATE statement for the report containing the sum counter.
4. The size of the sum counter is equal to the number of receiving character positions defined in the PICTURE clause that accompanies the SUM clause in the description of the elementary item.
5. Only one sum counter exists for an elementary report entry, regardless of the number of SUM clauses specified in the elementary report entry.
6. If the elementary report entry for a printable item contains a SUM clause, the sum counter serves as a source data item. On a control break, the RWCS moves the data from the sum counter to the printable item for presentation according to the rules of the MOVE statement.
7. If a data-name appears as the subject of an elementary report entry that contains a SUM clause, the data-name is the name of the sum counter; the data-name is not the name of a printable item that the entry may also define.
8. Procedure Division statements can alter the contents of sum counters.
9. During the execution of GENERATE and TERMINATE statements, the RWCS adds the values in sum-name to a sum counter.
10. The RWCS adds each individual sum-name into the sum counter when it processes the CONTROL FOOTING report group defining the sum counter.

Technical Notes

• The three categories of sum counter accumulation are as follows:
  • Subtotalling
  • Crossfooting
  • Rolling forward
  
  Subtotalling occurs only during execution of GENERATE statements and after any control break processing but before processing of the DETAIL report group. Crossfooting and rolling forward occur during the processing of CONTROL FOOTING report groups.
• Subtotalling accumulates numeric data fields (sum-names) into a sum counter. sum-name must not reference a sum counter when subtotalling. If the SUM clause contains the UPON phrase, sum-names are subtotalled when a GENERATE statement executes for a DETAIL report group. If there is no UPON phrase, sum-names are subtotalled when any GENERATE data-name statement is executed for the report in which the SUM clause appears.
• Crossfooting accumulates sum counters (sum-name) from the same CONTROL FOOTING report group into another sum counter. It is a horizontal sum of sums.
  Crossfooting occurs when a control break takes place and when the CONTROL FOOTING report group is processed.
  Crossfooting is performed according to the sequence in which sum counters are defined within the CONTROL FOOTING report group. That is, all crossfooting into the first sum counter defined in the CONTROL FOOTING report group is completed, and then all crossfooting into the second sum counter defined in the CONTROL FOOTING report group is completed. This procedure repeats until all crossfooting operations are completed.
  When one of the sum-names is the sum counter defined by the Data Description entry in which that sum clause appears, the initial value of that sum counter is used in the summing operation.
• Rolling forward accumulates sum counters (sum-name) defined in lower level CONTROL FOOTING report groups into another sum counter. It is a vertical sum of sums. A sum counter in a lower level CONTROL FOOTING report group is rolled forward when a control break occurs and at the time the lower level CONTROL FOOTING report group is processed.
• If two or more sum-names specify the same sum counter, then the sum counter is added as many times as the sum counter is referenced in the SUM clause. It is permissible for two or more of the sum-names to specify the same DETAIL report group. When a GENERATE data-name statement for such a DETAIL report group is given, the incrementing occurs repeatedly, as many times as the sum-name appears in the UPON phrase.

Additional References

• Section 6.8.15 statement in Chapter 6
• Section 5.3.50 clause
• Section 6.6.1, Arithmetic Operations
• Section 6.6.7, Overlapping Operands and Incompatible Data