Compaq COBOL
Reference Manual

General Rules (Screen Description)

1. The LINE clause, in conjunction with the COLUMN 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 LINE clause specifies the vertical coordinate.
2. The LINE clause without the PLUS phrase specifies the absolute line number.
3. The LINE clause with the PLUS phrase specifies a line 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. If the LINE clause is omitted, the following apply:
   • If no previous screen item is defined, LINE 1 is assumed.
   • If a previous screen item is defined, the ending line of that previous item is assumed.

Additional References

• Section 5.3.16 clause
• Section 5.3.36 clause
• Appendix D, Report Writer Presentation Rules and Tables
• Section 6.8.1 statement in Chapter 6
• Section 6.8.10 statement in Chapter 6

Function

The LOWLIGHT clause specifies that the field is to appear on the screen with the lowest intensity. When only two levels of intensity are available, normal intensity and LOWLIGHT will be the same.

Syntax Rule

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

Additional Reference

• Section 6.8.1 in Chapter 6
• Section 6.8.10 in Chapter 6

Function

The NEXT GROUP clause specifies information for the vertical positioning of the next report group on a logical page following the presentation of the last line of a report group.

next-group-line-num

is a positive, 1- to 3-digit integer value greater than zero. It represents an absolute line number on a logical page and establishes a print line for the next Report Writer report group.

next-group-line-num-plus

is a positive, 1- to 3-digit integer value. It represents a relative line number on a logical page and establishes a print line for the next Report Writer report group.

Syntax Rules

1. A Report Group entry must not contain a NEXT GROUP clause unless the description of that Report Group contains at least one LINE NUMBER clause.
2. next-group-line-num and next-group-line-num-plus must not exceed three significant digits.
3. If a Report Description entry omits the PAGE clause, all Report Group Description entries within that report can specify a relative NEXT GROUP clause only.
4. A PAGE FOOTING Report Group must not specify the NEXT PAGE phrase of the NEXT GROUP clause.
5. A PAGE HEADING and REPORT FOOTING Report Group must not specify the NEXT GROUP clause.

General Rules

1. Page positioning occurs after the presentation of the Report Group in which the NEXT GROUP clause appears.
2. To determine a new value for LINE-COUNTER, the Report Writer Control System (RWCS) uses the vertical positioning information from the NEXT GROUP clause along with information from the TYPE and PAGE clauses, and the value in LINE-COUNTER. See Appendix D, Report Writer Presentation Rules and Tables.
3. The RWCS ignores the NEXT GROUP clause on a CONTROL FOOTING Report group when it detects a control break at a level other than the highest level.
4. The NEXT GROUP clause of a CONTROL HEADING, DETAIL, and CONTROL FOOTING report group refers to the next CONTROL HEADING, DETAIL, and CONTROL FOOTING to be presented, and therefore can affect the location at which the next CONTROL HEADING, DETAIL, and CONTROL FOOTING report group is presented. See Appendix D.
5. The NEXT GROUP clause of a REPORT HEADING report group can affect the location at which the PAGE HEADING report group is presented. See Appendix D.
6. The NEXT GROUP clause of a PAGE FOOTING report group can affect the location at which the REPORT FOOTING report group is presented. See Appendix D.

Additional References

• General Rules (Report Description) (General Rule 4) of the Section 5.3.32 clause
• Appendix D, Report Writer Presentation Rules and Tables

Function

The OCCURS clause defines tables and provides the basis for subscripting and indexing. It eliminates the need for separate entries for repeated data items.

table-size

is an integer that specifies the exact number of occurrences of a table element.

min-times

is an integer that specifies the minimum number of occurrences of a table element. Its value must be greater than or equal to zero.

max-times

is an integer that specifies the maximum number of occurrences of a table element. Its value must be greater than min-times.

key-name

is the data-name of an entry that contains the OCCURS clause or an entry subordinate to it. key-name can be qualified. Each key-name after the first must name an entry subordinate to the entry that contains the OCCURS clause. The values in each key-name are the basis of the ascending or descending arrangement of the table's repeated data.

ind-name

is an index-name. It associates an index with the table and allows indexing in table element references.

depending-item

is the data-name of an elementary unsigned integer data item. Its value specifies the current number of occurrences. depending-item can be qualified.

Syntax Rules

1. The subject of the entry is the data-name that contains the OCCURS clause.
2. A key-name cannot contain an OCCURS clause. However, this rule does not apply to the first key-name if it is the subject of the entry.
3. There can be no OCCURS clauses between the data description entries for key-names and the subject of the entry.
4. In the OCCURS clause of the data description entry, key-name cannot be subscripted or indexed.
5. There must be an INDEXED BY phrase if any Procedure Division statements contain indexed references to the subject of the entry or to any of its subordinates.
6. The INDEXED BY phrase implicitly defines ind-name. The program cannot define ind-name elsewhere.
7. The subject of a Format 2 OCCURS clause can be followed, in the same record description, only by data description entries subordinate to it.
8. The OCCURS clause cannot be used in a data description entry that has the following:
   • A level-number of 01, 66, 77, or 88
   • A subordinate variable occurrence data item (Format 2 OCCURS clause)
9. The data item defined by depending-item cannot occupy any character position in the range delimited by the following:
   • The character position defined by the subject of the OCCURS clause
   • The last character position defined by the record description entry containing the OCCURS clause
10. Each ind-name must be a unique word in the program.
11. If the OCCURS clause is in a record description entry containing the GLOBAL clause, depending-item must refer to a global item described in the same Data Division.
12. If the OCCURS clause is in a record description entry containing the EXTERNAL clause, depending-item must refer to an external item described in the same Data Division.

General Rules

1. The OCCURS clause defines tables and provides the basis for subscripting and indexing.
2. Except for the OCCURS clause itself, all data description clauses associated with the subject of the OCCURS clause apply to each occurrence of the item.
3. Format 1 specifies that the subject of the entry has a fixed number of occurrences.
4. Format 2 specifies that the subject of the entry has a variable number of occurrences. min-times and max-times specify the minimum and maximum number of occurrences. Only the number of the subject's occurrences is variable; its size is fixed.
   The value of depending-item must fall in the range min-times to max-times.
   The contents of data items with occurrence numbers exceeding the current value of depending-item are unpredictable.
5. If a group item with a subordinate entry that has a Format 2 OCCURS clause is a sending item, the operation uses only the part of the table area specified by depending-item at the start of the operation.
   If the group is a receiving item, the part of the table used is determined by the location of depending-item. If depending-item is included in the group, then the operation uses the maximum length of the group. If depending-item is not included in the group, then the operation uses only the part of the table area specified by depending-item.
6. The KEY IS phrase indicates that the repeated data is arranged in ascending or descending order according to the values in the data items named by key-name. The rules for operand comparison determine the ascending or descending order. The position of each key-name in the list determines its significance. The first is the most significant, and the last is least significant.
7. If a Format 2 OCCURS clause is in a record description entry and the associated file description entry has the VARYING phrase of the RECORD clause, the records are variable length.
   If the RECORD clause does not have the DEPENDING ON phrase, the program must set the OCCURS clause depending-item to the number of occurrences before executing a RELEASE, REWRITE, or WRITE statement. The depending-item value determines the length of the record to be written.

Technical Note

If the subject of the OCCURS clause (or any of its subordinates) has the SYNCHRONIZED clause, the length of the subject of the OCCURS clause, or the group containing it, could increase. SYNCHRONIZED clause alignment can add fill bytes to the group containing the subject of the OCCURS clause and to the subject itself.

Additional References

• Section 6.8.31 statement in Chapter 6
• Section 5.2.3, Additional Alignment Rules for Record Allocation
• Comparison of Numeric Operands section in Chapter 6
• Comparison of Nonnumeric Operands section in Chapter 6

Examples

1. One-dimensional table:
   This record description entry describes a 20-character record. The record contains 10 occurrences of ITEMB, a 2-character data item.

   01 ITEMA. 03 ITEMB OCCURS 10 TIMES PIC XX.

2. Two-dimensional table:
   This record description entry describes a 320-character record. The record contains 8 occurrences of ITEMB, a 40-character data item. ITEMB contains 10 occurrences of ITEMC, a 4-character data item. Each ITEMC contains 2 data items: ITEMD and ITEME.

   01 ITEMA. 03 ITEMB OCCURS 8 TIMES. 05 ITEMC OCCURS 10 TIMES. 07 ITEMD PIC X. 07 ITEME PIC XXX.

   
   ITEMB (1) refers to a 40-character data item, the first 10 occurrences of ITEMC. Similarly, ITEMB (5) refers to the fifth group of 10 occurrences of ITEMC.
   ITEME (3,4) refers to ITEME in the fourth occurrence of ITEMC in the third occurrence of ITEMB:

   ---

   
3. Variable occurrence data item:
   When ITEMA is a receiving item, its size is 2128 characters. When it is a sending item, its size can vary from 70 to 2128 characters, depending on the value in ITEMC.
   Each ITEME is 42 characters long. Its size cannot change. The only effect of the value of ITEMC is to determine the number of ITEME occurrences.
   There are 10 occurrences of ITEMH and ITEMI in each occurrence of ITEME.

   01 ITEMA. 03 ITEMB PIC X(6). 03 ITEMC PIC 99. 03 ITEMD PIC X(20). 03 ITEME OCCURS 1 TO 50 TIMES DEPENDING ON ITEMC. 05 ITEMF PIC XX. 05 ITEMG OCCURS 10 TIMES. 07 ITEMH PIC X. 07 ITEMI PIC XXX.

Function

The PAGE clause defines the length of a logical page and the vertical subdivisions within which report groups are presented.

page-size

is a 1- to 3-digit integer. It defines the number of lines available on a logical page.

heading-line

is a 1- to 3-digit integer. It defines the first line number for a REPORT HEADING or PAGE HEADING report group on the logical page.

first-detail-line

is a 1- to 3-digit integer. It defines the first line number for a CONTROL HEADING, DETAIL, and CONTROL FOOTING report group on the logical page.

last-detail-line

is a 1- to 3-digit integer. It defines the last line number for a CONTROL HEADING or DETAIL report group on the logical page.

footing-line

is a 1- to 3-digit integer. It defines the last line number for a CONTROL HEADING or DETAIL report group on the logical page.

footing-line

is a 1- to 3-digit integer. It defines the last line number for a CONTROL FOOTING report group and the first line number for the PAGE FOOTING report group on the logical page.

Syntax Rules

1. The HEADING, FIRST DETAIL, LAST DETAIL, and FOOTING phrases may be written in any order.
2. page-size must not exceed three significant digits and must be greater than or equal to footing-line.
3. heading-line must be greater than or equal to one.
4. first-detail-line must be greater than or equal to heading-line.
5. last-detail-line must be greater than or equal to first-detail-line.
6. footing-line must be greater than or equal to last-detail-line.
7. The rules in Table 5-6 summarize the rules presented in Appendix D, Report Writer Presentation Rules and Tables. They indicate the vertical subdivision of the page in which each type of report group may appear when the PAGE clause is specified.
   1. To present a REPORT HEADING report group on a page by itself (NEXT GROUP NEXT PAGE), define the REPORT HEADING clause to be in the vertical subdivision of the page extending from heading-line to page-size, inclusive.
      To present a REPORT HEADING report group on a page with other report groups, define the REPORT HEADING clause to be in the vertical subdivision of the page extending from heading-line to first-detail-line minus one, inclusive.
   2. A PAGE HEADING clause must be defined in the vertical subdivision of the page extending from heading-line to first-detail-line minus one, inclusive.
   3. A CONTROL HEADING or DETAIL clause must be defined in the vertical subdivision of the page extending from first-detail-line to last-detail-line, inclusive.
   4. A CONTROL FOOTING clause must be defined in the vertical subdivision of the page extending from first-detail-line to footing-line, inclusive.
   5. A PAGE FOOTING clause must be defined in the vertical subdivision of the page extending from footing-line plus one to page-size, inclusive.
   6. To present a REPORT FOOTING report group on a page by itself, define the REPORT FOOTING clause in the vertical subdivision of the page extending from heading-line to page-size, inclusive.
      To present a REPORT FOOTING report group on a page with other report groups, define the REPORT FOOTING clause in the vertical subdivision of the page extending from footing-line plus one to page-size.
8. All report groups must be defined such that they can be presented on one logical page. The Report Writer Control System (RWCS) never splits a multiline report group across logical page boundaries.

General Rules

1. REPORT HEADING and PAGE HEADING report groups may not be presented on or beyond the first-detail-line.
2. PAGE FOOTING and REPORT FOOTING report groups must follow the footing-line.
3. If the PAGE clause is specified, the following implicit default values are assumed for any omitted phrases:
   1. If the HEADING phrase is omitted, heading-line equals one.
   2. If the FIRST DETAIL phrase is omitted, first-detail-line equals heading-line.
   3. If the LAST DETAIL and FOOTING phrases are both omitted, last-detail-line and footing-line equal page-size.
   4. If the FOOTING phrase is specified and the LAST DETAIL phrase is omitted, last-detail-line equals footing-line.
   5. If the LAST DETAIL phrase is specified and the FOOTING phrase is omitted, footing-line equals last-detail-line.
4. If the PAGE clause is omitted, the report consists of a single page of infinite length with relative line numbering.
5. If a REPORT HEADER report group is to appear on a page with other report groups, the first line following the heading report groups (REPORT HEADER and PAGE HEADER) must be blank.
6. If a REPORT FOOTING report group is to appear on a page with other report groups, the first line preceding the footing report groups (PAGE FOOTING and REPORT FOOTING) must be blank.

Additional References

• General Rules (Report Description) (General Rule 4) of the Section 5.3.32 clause
• Appendix D, Report Writer Presentation Rules and Tables

Table 5-6 shows the page regions established by the PAGE clause.

Table 5-6 Page Regions Established by the PAGE Clause

	Region Boundaries
Report Groups that Can Be Presented in a Region	First Line Number of the Region	Last Line Number of the Region	Line Positioning for the First Report Group Within the Region
Report Heading Described with NEXT GROUP NEXT PAGE Report Footing Described with LINE line-num NEXT PAGE	heading-line	page-size	LINE-NUMBER plus heading-line minus 1
Page Heading
Report Heading Not Described with NEXT GROUP NEXT PAGE	heading-line	first-detail-line minus 1	LINE-NUMBER plus heading-line minus 1
Control Heading	first-detail-line	last-detail-line	If LINE-COUNTER is greater than or equal to first-detail-line, position on LINE-COUNTER plus 1
Detail			If LINE-COUNTER is less than first-detail-line, position on first-detail-line
Control Footing	first-detail-line	footing-line	Same as preceding
Page Footing	footing line	page-size
Report Footing Not Described with LINE line-num NEXT PAGE	plus 1		LINE-NUMBER plus footing-line

5.3.37 PICTURE

Function

The PICTURE clause specifies the general characteristics and editing requirements of an elementary item, including an elementary screen item.

Syntax Rules (Both Formats)

1. You can use the PICTURE clause only for an elementary item.
2. character-string contains allowable combinations of characters in the COBOL character set. These characters are called the symbols of the PICTURE character-string.
3. character-string can contain from 1 to 255 symbols.
4. PIC is an abbreviation for PICTURE.
5. The asterisk (*), when used as a zero suppression symbol, and the BLANK WHEN ZERO clause cannot be used in the same entry.

Syntax Rule (Format 1)

6. The PICTURE clause is required for every elementary item except an item specified by the USAGE IS BINARY-CHAR, BINARY-SHORT, BINARY-LONG, BINARY-DOUBLE, COMP-1, COMP-2, FLOAT-SHORT, FLOAT-LONG, FLOAT-EXTENDED, POINTER, or INDEX clause and the subject of a RENAMES clause. Data description entries for these items cannot contain a PICTURE clause.

Syntax Rules (Format 2)

7. The PICTURE clause for a numeric screen item must either define a numeric edited item or must contain only "9"s and an optional "S".
8. Each PICTURE clause in a screen description entry must contain a FROM or a TO phrase, or both, or a USING phrase.
9. In a screen description entry, if the PICTURE clause is specified, the VALUE clause cannot be specified.
10. identifier-3, identifier-4, and identifier-5 must be defined in the File, Working-Storage, or Linkage Section.

General Rules (Both Formats)

1. The PICTURE clause categorizes a data item or screen item and determines what the item can contain. In the case of a PICTURE clause containing all Xs, the USAGE clause determines whether the item is alphanumeric or numeric. Table 5-7 shows the valid contents of both character-string and the item itself for each category. The general rules following this table supplement the information it contains.

   Table 5-7 Summary of PICTURE Clause Rules

   Category of Receiving Item	PICTURE of Receiving Item	Valid Contents of Sending Item	Examples
   Alphabetic	Must contain one or more As.	One or more alphabetic characters.	AA A(9)
   Numeric	Must contain at least one 9. May contain P's, one S, and one V. If USAGE IS COMP-5 or USAGE IS COMP-X, may contain all Xs.	One or more numeric characters.	S9(4)V99 9PPP SPP9
   Alphanumeric	Must contain combinations of As, Xs, and 9s. Can be all Xs. Cannot be all As or all 9s.	One or more characters in computer character set.	XX99XX AAXA(4)
   Alphanumeric Edited	Must contain at least one A or X. Must also contain at least one B, 0, or /. Can contain one or more 9s.	One or more characters in computer character set.	XXBXXB9(4) XX/99/00 9(6)/X
   Numeric Edited	Must contain at least one 0, B, /, Z, *, +, (comma), ., --, CR, DB, or cs. Can contain Ps, 9s, and one V. Must describe 1 to 31 digit positions, which can be represented by 9s, zero suppression symbols (Z, *), and floating insertion symbols (+, --, cs).	One or more numeric characters.	*,***.** ZZ,ZZZ/9(4) $$,$$$DB $9,999CR ZZZCR **.**

   Note COMP-1 and COMP-2 data items are numeric. However, their data description entries cannot have a PICTURE clause.

2. In an alphanumeric item definition, each character position is treated as if it were represented by an X, even though A or 9 may be specified.
3. Some PICTURE symbols represent character positions and some do not. An item's size is determined by adding up all the symbols that represent a character position. For example, a numeric item with a PICTURE of 999V99 has a size of five characters. The symbol V does not count toward the item's size.
4. character-string can contain a repeat count to represent consecutive occurrences of the following symbols: A, the comma (,), X, 9, P, Z, *, B, /, 0, +, --, and the currency symbol (cs). The repeat count must be an unsigned, nonzero integer enclosed in parentheses. For example, S9(6)V9(4) is equivalent to S999999V9999. However, character-string can contain no more than one of the following symbols: S, V, a period (.), CR, and DB.
5. The PICTURE clause symbols and their functions appear in Table 5-8.

   Table 5-8 PICTURE Clause Symbols

   Picture Clause Symbol	Function
   A	Represents a character position that can contain only an alphabetic character. An alphabetic character belongs to the set of characters: A to Z, a to z, and the space.
   	Can occur more than once.
   	Counts toward the size of the item.
   B	Represents a character position into which a space is inserted.
   	Can occur more than once.
   	Counts toward the size of the item.
   N	For USAGE IS DISPLAY, represents a character position that can contain any 2-byte character from the national character set. This is available only if /NATIONALITY=JAPAN or -nationality japan is specified.
   P	Specifies an assumed decimal scaling position, defining the location of the decimal point when one is not specified in character-string.
   	Can occur more than once, but only as a contiguous string of Ps at either the leftmost or rightmost end (not both) of character-string. The assumed decimal point character (V) is redundant when specified. However, when it is specified, V can appear to the left of the leftmost P or to the right of the rightmost P.
   	Does not count toward the size of the item. However, each P counts toward the maximum number of digit positions (31) in a numeric or numeric edited item.
   	Cannot be used if an explicit decimal point (.) appears in character-string.
   	In certain operations that refer to an item with P characters in character-string, the compiler treats each P position as if it contained the value zero. For example, an item with PICTURE 99PPP can have 100 unique values that range from 0 to 99,000 (0, 1000, 2000, ..., 99,000). An item with PICTURE PP9 can have 10 unique values (0, .001, .002, ... .009). These operations are any of the following: Any operation requiring a numeric sending operand A MOVE statement where the sending operand is numeric and its PICTURE character-string contains the symbol P A MOVE statement where the sending operand is numeric edited and its PICTURE character-string contains the symbol P, and the receiving operand is numeric or numeric edited A comparison operation where both operands are numeric
   	In all other operations, the compiler ignores the digit positions specified with the symbol P and does not count them toward the size of the operand.
   S	Indicates the presence of an operational sign, but does not specify the sign representation or position.
   	Can occur only once, as the leftmost character in character-string.
   	Does not count toward the size of the item unless the data or screen description entry contains a SIGN IS SEPARATE clause. If the SIGN clause does not appear in the item's data description, S is equivalent to SIGN IS TRAILING.
   V	Specifies the location of the assumed decimal point.
   	Can occur only once.
   	Does not count toward the size of the item.
   	Cannot be used if an explicit decimal point (.) appears in the PICTURE.
   X	For USAGE IS DISPLAY, represents a character position that can contain any character from the computer character set. For USAGE IS COMP-5 or USAGE IS COMP-X, represents a byte of computer storage.
   	Can occur more than once.
   	Counts toward the size of the item.
   Z	Represents a leading digit position that is replaced by a space when its value and the value of the digits to its left are zero.
   	Can occur more than once.
   	Counts toward the size of the item.
   	Use of Z excludes the use of the asterisk (*) for zero suppression and replacement.
   9	Represents a digit position that can contain only the digits 0 to 9.
   	Can occur more than once.
   	Counts toward the size of the item.
   0	Represents a character position into which 0 is inserted.
   	Can occur more than once.
   	Counts toward the size of the item.
   /	Represents a character position into which a slash (/) is inserted.
   	Can occur more than once.
   	Counts toward the size of the item.
   ,	Represents a character position into which a comma (,) is inserted. +
   	Can occur more than once.
   	Counts toward the size of the item.
   .	Represents a character position into which a decimal point (.) is inserted. It also represents the decimal point for alignment purposes. +
   	Can occur only once.
   	Counts toward the size of the item.
   	Cannot be used if V or P appears in character-string.
   + --	Represents the editing sign control symbols, the plus sign (+) and minus sign (-).
   	Each can occur more than once.
   	Each counts as one character toward the size of the item.
   	character-string can contain either a plus sign (+) or minus (-), but not both. Also, the use of either character excludes the use of both CR and DB.
   CR DB	Represents the editing sign control symbols, credit (CR) and debit (DB).
   	Each can occur only once, as the two rightmost character positions.
   	Each counts as two characters toward the size of the item.
   	character-string can contain either CR or DB, but not both. Also, the use of either excludes the use of the plus sign (+) and minus sign (-) as fixed insertion characters.
   *	Represents a leading digit position that is replaced by an asterisk (*) when its value and the values of all digit positions to its left are zero.
   	Can occur more than once.
   	Counts toward the size of the item.
   	Use of an asterisk (*) excludes the use of Z for zero suppression and replacement.
   cs	Represents a character position into which the currency symbol is inserted. This symbol is either the currency sign ($) or the character specified in the CURRENCY SIGN clause of the SPECIAL-NAMES paragraph or (on OpenVMS only) the character specified at DCL command level in the definition of the SYS$CURRENCY logical name.
   	Can occur more than once.
   	Counts as one character toward the size of the item.

   ---

   +When a program contains the DECIMAL POINT IS COMMA clause, the functions and rules for the period (.) and comma (,) are exchanged. In other words, the rules that apply to the period apply to the comma, and vice versa.
   

   ---