Compaq COBOL
Reference Manual
Previous Contents Index

General Rules (Format 2)

  1. The USING, FROM, and TO phrases have meaning only when the screen item's name or a screen name in its hierarchy, is specified in an ACCEPT or DISPLAY statement.
  2. When data is to be transferred to the screen from one data item, possibly edited, and stored in a different data item, both the FROM and TO phrases must be used in the PICTURE clause of the screen item.
  3. When data is to be transferred to the screen, possibly modified, and stored in the same data item (as when reading, modifying, and rewriting records of a file), the USING phrase must be used in the PICTURE clause of the screen item.
  4. identifier-3, identifier-4, identifier-5, and literal-1 need not be the same length as the screen item containing the PICTURE clause.
  5. Transfers between identifier-3, identifier-4, identifier-5, and literal-1, on the one hand, and the screen item are made in accordance with the rules of the MOVE statement. (See the MOVE Statement in Chapter 6.)
  6. When the FROM phrase is specified:
    1. On DISPLAY statement execution, data is transferred from identifier-4 or literal-1, after being edited in accordance with character-string, and displayed on the screen. The display begins at the screen position defined either implicitly or explicitly by the LINE and COLUMN clauses and the starting screen coordinates specified in the DISPLAY statement.
    2. The FROM phrase has no meaning in the execution of an ACCEPT statement.
  7. When the TO phrase is specified:
    1. At ACCEPT statement completion, the data entered into the field on the screen is transferred to identifier-5, after being edited in accordance with the picture string specified for identifier-5.
    2. The TO phrase has no meaning in the execution of a DISPLAY statement.
  8. When the USING phrase, or the FROM and TO phrases are specified:
    1. On DISPLAY statement execution, data is transferred from identifier-3, identifier-4, or literal-1 as described in rule 11a above.
    2. On ACCEPT statement execution, data is transferred from identifier-3, identifier-4, or literal-1 as described in rule 11a above. At ACCEPT statement completion, the data entered into the screen item is transferred to identifier-3 or identifier-5 as described in rule 12a above.

Editing Rules

  1. There are two PICTURE clause editing methods: insertion editing and suppression and replacement editing. Each method has the following variations:
    Editing Method Variations in Each Method
    Insertion Simple insertion editing, special insertion editing, fixed insertion editing, or floating insertion editing
    Suppression and
    Replacement     		Zero suppression and replacement with spaces, or zero suppression and replacement with asterisks
  2. The types of editing that a program can perform on an item depend on the item's category:
    Category Types of Editing Valid Editing
    Characters
    Alphabetic None None
    Numeric None None
    Alphanumeric None None
    Alphanumeric Edited Simple insertion 0, B, and /
    Numeric Edited All All, subject to Editing Rule 3
  3. Floating insertion editing and editing by zero suppression and replacement are mutually exclusive. That is, a PICTURE clause can use one type of editing or the other, but not both.
    Furthermore, a PICTURE clause can use only one type of replacement symbol for zero suppression. The space (Z) and asterisk (*) symbols cannot appear in the same PICTURE clause.

Simple Insertion Editing

  1. A comma (,) space (B), zero (0), and slash (/) are symbols you can use in simple insertion editing. They indicate an item position to contain the character they represent. These symbols count toward the size of the item.
    If the comma is the last symbol in character-string, the PICTURE clause must be the last clause of the data description entry. In this case, a comma followed by a period (,.) are the last two characters of the data description entry. However, if the DECIMAL-POINT IS COMMA clause is in the SPECIAL-NAMES paragraph, the data description entry ends with two consecutive periods.

Special Insertion Editing

  1. The period (.) is the only symbol used in special insertion editing. It represents the item position to contain the actual decimal point; however, it also represents the decimal point for alignment purposes. Therefore, the assumed decimal point (V) and the actual decimal point (.) cannot be used in the same character-string. The period counts toward the size of the item.
    If the period is the last symbol in character-string, the PICTURE clause must be the last clause of the data description entry. In this case, the data description entry ends with two periods. However, if the DECIMAL-POINT IS COMMA clause is in the SPECIAL-NAMES paragraph, a comma followed by period (,.) are the last two characters of the data description entry.

Fixed Insertion Editing

  1. The currency symbol (cs) and the editing sign control symbols (+, --, CR, and DB) are the symbols used in fixed insertion editing. character-string can contain only one currency symbol and only one of the editing sign control symbols as fixed insertion characters.
    CR and DB each represent two character positions, which must be the two rightmost positions.
    The plus sign (+) and minus sign (-) must be either the leftmost or rightmost character position that counts toward the size of the item.
    The currency symbol (cs) must be the leftmost character position that counts toward the size of the item; however, a plus sign (+) or minus sign (-) can precede it.
    Fixed insertion editing causes the insertion symbol to occupy the same position in the edited item as in character-string. Table 5-9 shows that the results of using editing sign control symbols depend on the item's value.

    Table 5-9 Using Sign Control Symbols in Fixed Insertion Editing
      Result
    Editing Symbol in
    PICTURE Character-String     		Item
    Positive or Zero     		Item
    Negative
    + + --
    -- space --
    CR 2 spaces CR
    DB 2 spaces DB

Floating Insertion Editing

  1. The currency symbol (cs), the plus sign (+), and the minus sign (-) are the symbols used in floating insertion editing. They are mutually exclusive in character-string. That is, if any floating insertion symbol appears in character-string, no other floating insertion symbol can appear.
    To indicate floating insertion editing, you must use a string of at least two floating insertion symbols. You can include simple insertion symbols either within the floating string or immediately to the right of the floating string. These simple insertion symbols are treated as part of the floating string. That is, they appear in results only when the value of the item is large enough to include the position occupied by the simple insertion symbol. You can append the fixed insertion symbols CR or DB immediately to the right of a floating string.
    The leftmost symbol of the floating insertion string represents the leftmost position in which a floating insertion character can appear. This character position cannot be filled by a digit.
    The second floating symbol from the left represents the leftmost limit of the numeric data the item can store. Nonzero numeric characters can replace all symbols at or to the right of this limit.
    You can use the floating insertion symbol in only two ways. It can represent the following:
    1. Any or all leading numeric character positions to the left of the decimal point
      In this case, run-time results show a single insertion character in the position immediately preceding either the first nonzero digit in the item or the decimal point, whichever appears leftmost in the data. For example, an item whose PICTURE is $$$.99 and whose value is zero appears as $.00.
    2. All numeric character positions in the PICTURE character-string
      In this case, you must specify at least one insertion symbol to the left of the decimal point. When the item has a nonzero value, run-time results are the same as when all the insertion symbols are to the left of the decimal point. However, when the item has a zero value, run-time results show neither a floating insertion character nor the decimal point. For example, a item whose PICTURE is $$$.$$ and whose value is zero appears as spaces.
      If the floating insertion symbol is a plus sign (+) or minus sign (-), the actual character inserted depends on the value of the item. Table 5-10 shows the possible results of using editing sign control symbols in floating insertion editing.

    Table 5-10 Using Sign Control Symbols in Floating Insertion Editing
      Result
    Editing Symbol in
    PICTURE Character-String     		Item
    Positive or Zero     		Item
    Negative
    + + --
    -- space --

    To avoid truncation, the minimum size of character-string must be the sum of:

Zero Suppression and Replacement Editing

  1. One or more occurrences of the space symbol (Z) or the asterisk (*) define a floating suppression string, which can suppress leading zeros in numeric character positions. The space symbol (Z) causes spaces to replace the zeros; an asterisk (*) causes asterisks to replace the zeros.
    The suppression symbols are mutually exclusive. That is, character-string can contain either the space symbol (Z) or the asterisk (*), but not both.
    Each suppression symbol counts toward the size of the item.
    You can include simple insertion symbols either within the floating string or immediately to its right. These simple insertion symbols are treated as part of the floating string. That is, they appear in results only when the value of the item is large enough to include a position occupied by a simple insertion symbol.
    You can use zero suppression symbols to represent either:
    The following actions occur if the suppression symbols represent any or all leading numeric character positions to the left of the decimal point:
    The following events occur if the suppression symbols represent all numeric positions in character-string:
  2. The plus sign (+), minus sign (-), asterisk (*), space (Z), and currency symbol (cs) are mutually exclusive when they are used as floating replacement characters. That is, if any one of these symbols appears as a floating replacement character, none of the other symbols can appear as a floating replacement character in the same PICTURE clause.

PICTURE Symbol Precedence Rules

  1. character-string must contain either:
  2. Figure 5-10 summarizes the rules for combining symbols to form character-strings more complex than the basic possibilities listed in rule 1. The table shows that the use of one symbol in a character-string excludes the use of certain others before or after it.
    The table uses the following conventions:

Figure 5-10 PICTURE Symbol Precedence Rules

Additional References

Examples

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

5.3.38 RECORD

Function

The RECORD clause specifies the number of character positions in either a fixed- or variable-length record. If the number of character positions does not vary, the RECORD clause specifies the minimum and maximum number of character positions in a variable-length record.

shortest-rec

is an integer that specifies the minimum number of character positions in a variable-length record. Its value must be greater than or equal to zero.

longest-rec

is an integer greater than shortest-rec. It specifies the maximum number of character positions in a variable-length record or the size of a fixed-length record.

depending-item

is the data-name of an elementary unsigned integer data item in the Working-Storage or Linkage Section. It specifies the number of character positions for an output operation, and it contains the number of character positions after a successful input operation.

Syntax Rules

  1. No record description entry for a file can specify the following:
  2. In a sort-merge file description entry, the first shortest-rec character positions of the record must be large enough to include all keys specified in any SORT or MERGE statement for the sort or merge file.
  3. For an indexed file, the first shortest-rec character positions of the record must be large enough to include all record keys.
  4. If the DEPENDING ON phrase is present and if the associated file connector is an external file connector, depending-item must have the external attribute and must specify the same data-name in all file description entries associated with the external file connector.

General Rules

Both Formats

  1. The absence of a RECORD clause is the same as a Format 1 RECORD clause with no shortest-rec phrase and with longest-rec equal to the greatest number of character positions described for any of the file's records.
  2. The number of characters described by a record description entry is the sum of both of the following:
    If the record description entry contains a table definition, the sum includes the number of character positions in the maximum number of table elements.
  3. If the associated file connector is an external file connector, all file description entries in the run unit associated with that file connector must define the same values for shortest-rec and longest-rec. If the RECORD clause is not specified, all record description entries associated with this file connector must be the same length.

Format 1

  1. If there is no shortest-rec phrase, Format 1 specifies fixed-length records. longest-rec then specifies the number of character positions in each record of the file.
  2. If there is a shortest-rec phrase, Format 1 specifies variable-length records, the same as Format 2 without the DEPENDING phrase.
  3. For variable-length records:

Format 2

  1. Format 2 specifies variable-length records.
  2. If the clause does not contain shortest-rec, the minimum number of character positions in any of the file's records is the least number of character positions described by a record description entry for the file.
  3. If the clause does not contain longest-rec, the maximum number of character positions in any of the file's records is the greatest number of character positions described by a record description entry for the file.
  4. If there is a DEPENDING phrase, the program must set depending-item to the number of character positions in the record before executing a RELEASE, REWRITE, or WRITE statement for the file.
  5. After successful execution of a READ or RETURN statement for the file, the value of depending-item indicates the number of character positions in the accessed record.
  6. The depending-item value is not changed by executions of:
  7. For RELEASE, REWRITE, and WRITE statement execution, determining the number of character positions in the record depends partly upon whether or not the record contains a variable occurrence item (an item described by the OCCURS clause or one that is subordinate to another item so described). During execution of these statements, three rules determine the number of character positions in the record:

Additional References

5.3.39 RECORD KEY

Function

The RECORD KEY clause specifies the Prime Record Key access path to indexed file records.

rec-key

is the Record Key for the file. It is the data-name of a data item in a record description entry for the file. It can be qualified, but it cannot be a group item that contains a variable-occurrence data item. The data item must be described as one of the following:

seg-key

is a segmented-key name that represents the concatenation of one or more (up to eight) occurrences of seg.

seg

is the data-name of a data item in a record description entry for the file. It can be qualified, but it cannot be a group item that contains a variable-occurrence data item. The data item must be described as one of the following:

Syntax Rule

The RECORD KEY clause is required for indexed files. It can be in either the file description entry or in the file's Environment Division SELECT clause. However, it cannot be in both the SELECT clause and the file description entry for the same file.

General Rules

  1. seg-key is the concatenation of all specified key segments in the order specified.
  2. seg-key can be referenced only in a READ (Format 3) or START statement.
  3. The RECORD KEY clause specifies the Prime Record Key for a file.
  4. The order of keys, whether ASCENDING or DESCENDING, must be the same as the order used when the file was created.
  5. Each key can be specified as ASCENDING or DESCENDING (ASCENDING is the default). In an ASCENDING key, lower key values occur toward the beginning of the sorted file. In a DESCENDING key, higher key values occur toward the beginning of the sorted file.
  6. The data description of rec-key, or the segments of seg-key, and their relative locations in the record, must be the same as those used when the file was created.
  7. Only one record description entry for the file must describe rec-key or the segments of seg-key. The Prime Record Key has the same character positions in every record of the file.
  8. If the associated file connector is an external file connector, all File Description entries in the run unit that are associated with that file connector must define the same data description entry for rec-key or the segments of seg-key with the same relative location within the record.
  9. The DUPLICATES phrase specifies that two or more records in the file can have duplicate values in the same rec-key or the segments of seg-key. If there is no DUPLICATES phrase, two records cannot have the same value in corresponding Prime Record Key.
    On OpenVMS, if the program was compiled with the /CHECK=DUPLICATE_KEYS qualifier on the command line, and the duplicate key specification on a file's FD (in other words, specified in the WITH DUPLICATES phrase) does not match that of the actual file, a run-time diagnostic will be issued when an attempt is made to open the file with an OPEN statement. <>
    On Tru64 UNIX systems, DUPLICATES must match the specification for DUPLICATES when the file is created, unless the relaxed key check option is used. <>

Additional Reference

Section 5.3.8

Previous Next Contents Index