Identification Division

Data Division

Chapter 6: Environment Division

6.1 Environment Division

6.1.1 General Description

The Environment Division specifies a standard method of expressing those aspects of a data processing problem that are dependent upon the physical characteristics of a specific computer. This division allows specification of the configuration of the compiling computer and the object computer. In addition, information relative to input-output control, special hardware characteristics and control techniques may be given.

The Environment Division is optional in a COBOL source element.

ENVIRONMENT DIVISION.
[configuration-section]
[input-output-section]

6.1.2 Configuration Section

The Configuration Section is optional .

General Format

1. The CONFIGURATION SECTION header is optional only if it is the first statement in the program.

2. The Configuration Section must not be stated in a program that is contained within another program.

3. The Configuration Section must not be stated in a method definition.

4. The SOURCE-COMPUTER, OBJECT-COMPUTER and REPOSITORY paragraphs must not be stated in a factory definition or an object definition.

6.1.2.1 The Source-Computer Paragraph

Function

The SOURCE-COMPUTER paragraph identifies the computer on which the compilation unit is to be compiled.

General Format

General Rules

1. The source-computer-name is documentary only.

2. The WITH DEBUGGING MODE phrase is used to enable debugging code, in accordance with the Standard ANSI COBOL Debug Module. (See the section Environment Division in COBOL Debug in the chapter Debug Module in your Language Reference - Additional Topics.)

3. All clauses of the SOURCE-COMPUTER paragraph apply to the source unit in which they are explicitly or implicitly specified and to any source unit contained within that source unit.

6.1.2.2 The Object-Computer Paragraph

Function

The OBJECT-COMPUTER paragraph provides a means of describing the computer on which the runtime module created by the compiler is to be executed.

It is optional.

The MEMORY SIZE clause and SEGMENT-LIMIT clause are classed as an obsolete elements in the ANSI'85 standard and are scheduled to be deleted from the next full revision of the ANSI Standard.

All dialects within this COBOL implementation support the MEMORY-SIZE clause and SEGMENT-LIMIT clause for documentary purposes only. The FLAGSTD Compiler directive can be used to detect occurrences of this syntax.

Although they are part of the standard COBOL definition, the MEMORY-SIZE clause and SEGMENT-LIMIT clause are explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

Syntax Rules

1. Object-computer-name must be one COBOL word defined by the user.

2. The OBJECT-COMPUTER paragraph can consist of only the OBJECT-COMPUTER header.

General Rules

1. The computer-name provides a means for identifying equipment configuration, in which case the computer-name and its implied configurations are specified by the user. The configuration definition contains specific information concerning the memory size. The computer-name and the MEMORY-SIZE clause are documentary only.

2. If the PROGRAM COLLATING SEQUENCE clause is not specified, the NATIVE collating sequence is used. The appendix Character Sets and Collating Sequences lists both the full ASCII and EBCDIC collating sequences. Either can be chosen as the NATIVE collating-sequence by use of the NATIVE Compiler directive.

3. If the PROGRAM COLLATING SEQUENCE clause is specified, the program collating sequence is the collating sequence associated with the alphabet-name specified in that clause.

4. The program collating sequence established in the OBJECT-COMPUTER paragraph is used to determine the truth value of any nonnumeric comparisons:
   1. explicitly specified in relation conditions (see the section Relation Condition later in this chapter).

   2. explicitly specified in condition-name conditions; see the section Condition-Name Condition (Conditional Variable) later in this chapter.

5. The PROGRAM COLLATING SEQUENCE clause is also applied to any nonnumeric merge or sort keys unless the COLLATING SEQUENCE phrase of the respective SORT or MERGE statement is specified.

6. The PROGRAM COLLATING SEQUENCE clause has no effect on the ordering of indexed files.

7. The PROGRAM COLLATING SEQUENCE clause applies only to the source element in which it is specified

   and source elements contained within it

8. The SEGMENT-LIMIT clause is documentary only. (See the chapter Segmentation in your Language Reference - Additional Topics.)

6.1.2.3 The Special-Names Paragraph

Function

The SPECIAL-NAMES paragraph provides a means for specifying the currency sign, choosing the decimal point,

specifying symbolic-characters,

relating implementor-names to user-specified mnemonic-names, relating alphabet-names to character sets or collating sequences, and relating class-names to sets of characters.

You can select one of several pre-defined parameter passing conventions. Enhancements to the CALL statement and the PROCEDURE DIVISION header allow these parameter passing conventions to be used in inter-program communication.

Examples:

1. An example of using the CRT status key fields is provided in the Examples chapter in your Additional Topics.

General Format

Directives

1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section.
   • ALPHASTART - determines whether valid numeric literals used in the ALPHABET clause can begin with 0 or with 1.

   • CHARSET - impacts which alphabet is considered the native character set. This directive is ignored in some environments.

   • NATIVE - impacts which alphabet is considered the native character set.

   • SYMBSTART - determines whether valid numeric literals used in the SYMBOLIC CHARACTERS clause can begin with 0 or with 1.

Syntax Rules

1. The clauses in the SPECIAL-NAMES paragraph may appear in any order.

2. At the outer level of a class definition, the CURRENCY, CURSOR and CRT STATUS clauses must not be specified.

3. In the factory or object of a class definition, the only clauses that can be specified are the CURRENCY, CURSOR, and CRT STATUS clauses.

4. If the SPECIAL-NAMES paragraph is specified in an interface definition, the ALPHABET, CURRENCY and DECIMAL-POINT clauses are the only permitted clauses. The data-name-1 phrase of the CURRENCY clause must not be specified.

5. Mnemonic-names can be any COBOL user-defined word. At least one constituent character must be alphabetic.

6. Function-name refers to a system device or function used by your COBOL system.

   Function-name refers to an external switch if its name is one of UPSI-0 through UPSI-7.

7. If function-name references an external switch

   or the SWITCH-n or SWITCH option is used,

   the associated mnemonic-name cannot be specified anywhere

   except in the SET statement

   . At least one condition-name should be associated with it.

   No condition-name is required.

8. If function-name does not reference an external switch, the associated mnemonic-name can be specified only in the ACCEPT, DISPLAY, SEND or WRITE statements. A condition-name cannot be associated with such an implementor-name.

9. The literals specified in the literal phrase of the alphabet-name-1 clause:
   1. if numeric, must be unsigned integers and must have a value within the range of one (1) through the maximum number of characters in the native character set.

      The lowest valid values for numeric literals in the ALPHABET clause are sensitive to the ALPHASTART Compiler directive.

   2. if nonnumeric and associated with a THROUGH or ALSO phrase, must each be one character in length.

   3. cannot be specified as floating-point literals or DBCS literals.

10. If the literal phrase of the alphabet-name-1 clause is specified, a given character must not be specified more than once in an alphabet-name clause.

11. The words THRU and THROUGH are equivalent.

12. The words STANDARD-1 and ASCII are equivalent.

13. The reserved word IS is never required in the SPECIAL-NAMES paragraph.

14. The literals specified in the literal-4 phrase:
    1. if numeric, must be unsigned integers and must have a value within the range of one (1) through the maximum number of characters in the native character set.

    2. if nonnumeric and associated with a THROUGH phrase, must each be one character in length.

    3. cannot be specified as floating-point or DBCS literals.

15. Literal-1, ... literal-5 must not specify a symbolic-character figurative constant.

16. The same symbolic-character-1 must appear only once in a SYMBOLIC CHARACTERS clause.

17. The relationship between each symbolic-character-1 and the corresponding integer-1 is by position in the SYMBOLIC CHARACTERS clause. The first symbolic-character-1 is paired with the first integer-1, the second symbolic- character-1 is paired with the second integer-1; and so on throughout the SYMBOLIC CHARACTERS clause; the division into IS or ARE phrases is documentary only.

    The lowest valid value for integer-1 is sensitive to the SYMBSTART Compiler directive.

18. There must be a one-to-one correspondence between occurrences of symbolic-character-1 and occurrences of integer-1, both within each IS or ARE phrase and within the entire SYMBOLIC CHARACTERS clause.

19. The ordinal position specified by integer-1 must exist in the native character set. If the IN phrase is specified, the ordinal position must exist in the character set named by alphabet-name-2; alphabet-name-2 must be described in an ALPHABET clause.

20. Literal-6 must not be a figurative constant.

21. Integer-2 must be an unsigned integer in the range 0 to 65535.

22. Data-name-1 of the CURSOR IS clause must be declared in the Working-Storage section .

23. The CRT STATUS clause specifies a data item into which a status value is moved after each Format 4

    or 5

    ACCEPT statement. In some environments, it can be defined only in the first 64K of Working-Storage.

24. Data-name-2 must be described in the Working-Storage Section and must be three bytes long.

25. The CURSOR IS clause specifies the data item to contain the cursor address as used by the ACCEPT statement.

General Rules

1. Switches are set at run time by the operator, and the setting can be determined by testing the associated condition-names.

2. If mnemonic-name is associated with an external switch, the status of that switch can be altered by execution of a Format 1 SET statement (see the section The SET Statement in this chapter).

3. The alphabet-name-1 clause provides a means for relating a name to a specified character code set and/or collating sequence. When alphabet-name-1 is referenced in the PROGRAM COLLATING SEQUENCE clause (see the section The OBJECT-COMPUTER Paragraph) or the COLLATING SEQUENCE phrase of a SORT or MERGE statement (see the sections The SORT Statement or The MERGE Statement), the alphabet-name-1 clause specifies a collating sequence. When alphabet-name-1 is referenced in a CODE-SET clause in a file description entry (see the section The File Description - The Complete Entry Skeleton), the alphabet-name clause specifies a character code set.
   1. If the STANDARD-1

      or ASCII

      phrase is specified, the character code set or collating sequence identified is the American Standard Code for Information Interchange, as defined in American National Standard X3.4-1968.

      If the STANDARD-2 phrase is specified, the character code set identified is the International Reference Version of the ISO 7-bit code, as defined in International Standard 646, 7-bit Coded Character Set for Information Processing Interchange.

      If the EBCDIC phrase is specified, the character code set or collating sequence identified is EBCDIC.

      If the NATIVE phrase is specified, the native character code set or native collating sequence is used. The native collating sequence is either ASCII or EBCDIC, as specified by the NATIVE Compiler directive.)

      See the appendix Character Sets and Collating Sequences for details of the ASCII code-set and the ASCII and EBCDIC collating sequences and their correspondence.

   2. If the literal phrase is specified, alphabet-name-1 cannot be referenced in a CODE-SET clause (see the section The CODE-SET Clause). The character code set and/or collating sequence identified is that defined according to the following rules:
      1. The value of each literal specifies:
         1. The ordinal number of a character within the native character set, if the literal is numeric. This value must not exceed the value which represents the number of characters in the native character set.

         2. The actual character within the native character set, if the literal is nonnumeric. If the value of the nonnumeric literal contains multiple characters, each character in the literal, starting with the leftmost character, is assigned successive ascending positions in the collating sequence being specified.

      2. The order in which the literals appear in the ALPHABET clause specifies, in ascending sequence, the ordinal number of the character within the collating sequence being specified.

      3. Any characters within the native collating sequence which are not explicitly specified in the literal phrase, assume a position, in the collating sequence being specified, greater than any of the explicitly specified characters. The relative order within the set of these unspecified characters is unchanged from the native collating sequence.

      4. If a character code-set is being specified, for each character within the native character set that is not specified by the literal-1 phrase, the implementor defines the ordinal number within the character code-set being specified.

      5. If the THROUGH phrase is specified, the set of contiguous characters in the native character set, beginning with the character specified by the value of literal-1, and ending with the character specified by the value of literal-2, is assigned a successive ascending position in the collating sequence being specified. In addition, the set of contiguous characters specified by a given THROUGH phrase can specify characters of the native character set in either ascending or descending sequence.

      6. If the ALSO phrase is specified, the characters of the native character set specified by the value of literal-1, and literal-3 are assigned to the same position in the collating sequence being specified

         , or in the character code set that is used to represent the data

4. The character that has the highest ordinal position in the program collating sequence is associated with the figurative constant HIGH-VALUE

   except when this figurative constant is specified as a literal in the SPECIAL-NAMES paragraph

   If more than one character has the highest position in the program collating sequence, the last character specified is associated with the figurative constant HIGH-VALUE.

5. The character that has the lowest ordinal position in the program collating sequence is associated with the figurative constant LOW-VALUE

   except when this figurative constant is specified as a literal in the SPECIAL-NAMES paragraph

   If more than one character has the lowest position in the program collating sequence, the first character specified is associated with the figurative constant LOW-VALUE.

6. Floating-point literals cannot be used in a user-specified collating sequence.

7. When specified as literals in the SPECIAL-NAMES paragraph, the figurative constants HIGH-VALUE and LOW-VALUE are associated with those characters having the highest and lowest positions, respectively, in the native collating sequence.

8. The SYMBOLIC CHARACTERS clause is used to define user-defined words that can be used like figurative constants. If the IN phrase is not specified, symbolic-character-1 represents the character whose ordinal position in the native character set is specified by integer-1. If the IN phrase is specified, integer-1 specifies the ordinal position of the character that is represented in the character set named by alphabet-name-2.

9. The internal representation of symbolic-character-1 is the internal representation of the character that is represented in the native character set.

10. Literal-6, which appears in the CURRENCY SIGN IS literal clause, is used in the PICTURE clause to represent the currency symbol. The literal is limited to a single character and must not be one of the following characters:
    • digits 0 thorough 9;

    • uppercase alphabetic characters A, B, C, D, L, P, R, S, V, X, Z, or the space;

      C and R are allowed,

      L is allowed,

      E cannot be used,

      N cannot be used,

      G cannot be used,

      lowercase alphabetic characters a through z,

      (except e, f, g, h, i, j, k, m, n, o, q, t, u, w, y);

    • special characters *, +, -, ,, ., ;, (, ), ", / or, =.

    If this clause is not present, only the currency sign defined in the COBOL character set is used in the PICTURE clause. See the section Character Set in the chapter Concepts of the COBOL Language.

12. The DECIMAL-POINT IS COMMA clause means that the function of comma and period are exchanged in the character-string of the PICTURE clause and in numeric literals.

13. If the NUMERIC SIGN clause is specified, the default for signed numeric items is for the sign to be stored as a trailing separate character.

14. Wherever a mnemonic-name is allowed, you can use the function-name.

15. If function-name does not reference an external switch, it can be selected from the following list:

    TAB	Skip to Vertical Tabulation Position (inserts ASCII X"0B" in the output record as appropriate)	WRITE ADVANCING statement
    PRINTER	Printer	DISPLAY statement
    FORMFEED	Skip to new page (inserts ASCII X"0C" in the output record as appropriate)	WRITE ADVANCING statement
    COMMAND-LINE	Command transfer	ACCEPT and DISPLAY statements
    ARGUMENT-NUMBER	Command-Line argument number	ACCEPT and DISPLAY statements
    ARGUMENT-VALUE	Command-Line argument value	ACCEPT statement
    ENVIRONMENT-NAME	Environment-variable name	DISPLAY statement
    ENVIRONMENT-VALUE	Environment-variable value	ACCEPT and DISPLAY statements
    SYSERR	Standard error device	DISPLAY statement

    The following table reflects the support for function names offered by OS/VS COBOL, VS COBOL II and SAA in this COBOL system.

    Table 6-1: Function Names Support

    	OSVS	VSC2 Rel (2)	COBOL/370 or VSC2 Rel (3)/(4)	SAA L1
    SYSIN	y	y	y	y
    SYSIPT	U	U	y
    SYSOUT	y	y	y	y
    SYSLIST			y
    SYSLST	U	U	y
    SYSPCH	U	U	y
    SYSPUNCH	U	y	y
    CONSOLE	y	y	y	y
    C01	y	y	y	y
    C02	y	y	y
    C03	y	y	y
    C04	y	y	y
    C05	y	y	y
    C06	y	y	y
    C07	y	y	y
    C08	y	y	y
    C09	y	y	y
    C10	y	y	y
    C11	y	y	y
    C12	y	y	y
    S01	y	y	y
    S02	y	y	y
    S03		U	y
    S04		U	y
    S05		U	y
    CSP	y	y	y	y
    1 char rw literal	y
    AFP-5A			y

    y	Documented and accepted by mainframe compilers and the COBOL system.
    U	Undocumented but accepted by mainframe compiler.

16. The CLASS clause provides a means for relating a name to the specified set of characters listed in that clause. Class-name-1 can be referenced only in a class condition. The characters specified by the values of the literals in this clause define the exclusive set of characters which constitute class-name-1. The value of each literal specifies:
    1. the ordinal number of a character within the native character set, if the literal is numeric. This value must not exceed the value which represents the number of characters in the native character set.

    2. the actual character within the native character set, if the literal is nonnumeric. If the value of the nonnumeric literal contains multiple characters, each character in the literal is included in the set of characters identified by class-name-1.

    If the THROUGH phrase is specified, the contiguous characters in the native character set beginning with the character specified by the value of literal-4, and ending with the character specified by the value of literal-5, are included in the set of characters identified by class-name-1. Additionally, the contiguous characters specified by a given THROUGH phrase can specify characters of the native character set in ascending or descending sequence.

17. All clauses specified in the SPECIAL-NAMES paragraph for a sourced element also apply to source elements contained within that source element. The condition-names specified in the containing source element's SPECIAL-NAMES paragraph can be referenced from any contained source element.

18. The CALL-CONVENTION clause allows you to select one of several pre-defined parameter passing conventions which allow you to CALL subprograms written in languages other than COBOL, and which use different parameter passing conventions.

19. The CONSOLE IS CRT clause causes any ACCEPT or DISPLAY statement whose operand is not a screen-name, and that has no phrases specific to a particular format, to be treated as Format 5. If the CONSOLE IS CRT clause is not present, these statements are treated as the standard ANSI ACCEPT or DISPLAY.

20. The CURSOR IS clause specifies the data item to contain the cursor address used by the ACCEPT statement.
    1. At the start of an ACCEPT statement, if data-name-1 contains a value that is a valid character position on the screen, that position is used as the initial position for the cursor. Otherwise, data-name-1 is ignored, and the initial position for the cursor is the start of the first input field on the screen. At the end of an ACCEPT statement, if the position in data-name-1 has been used in that statement, data-name-1 is updated to show the position of the cursor at the termination of the ACCEPT statement.

    2. CURSOR IS has no effect on the positioning of fields on the screen.

    3. Data-name-1 must be 4 or 6 characters in length. If data-name-1 is 4 characters in length, the first two characters are interpreted as line number, and the second two as column number. If data-name-1 is 6 characters in length, the first three characters are interpreted as line number, and the second three as column number.

    4. The clause has no effect if data-name-1 contains an illegal position (for example, zeros, a nonnumeric value, or a value that is beyond the bottom of the screen).

    5. If data-name-1 contains a valid position that does not correspond to an input field being accepted by the current ACCEPT statement, the cursor is positioned to the next such field or, if there is none, to the first such field. The ordering of the fields is the order in which their descriptions appear in the Data Division.

21. The CRT STATUS clause specifies a 3-byte data item, into which a status value is moved after each Format 4 or Format 5 ACCEPT statement.

    If the CRT STATUS clause is specified in the SPECIAL-NAMES paragraph, every Format 4 or 5 ACCEPT statement (as described later in this chapter) places a value into data-name-2 to indicate the outcome of the ACCEPT operation. Data-name-2 consists of sta tus keys which are set to indicate possible conditions resulting from the completion of the operation. They are described below.

CRT Status Keys

CRT Status Key 1: The first byte of data-name-1 is CRT Status Key 1 and should be described as PICTURE 9 USAGE DISPLAY. It indicates the condition that caused the termination of the ACCEPT operation. The possible values are:

A terminator key is a key whose purpose is terminating ACCEPT operations (for example, Enter). A particular configuration option causes the field-tab key, when used in the final field of an ACCEPT, to act as a terminator key. Defining function keys is also a configuration option.

A termination that returns a value of "0" is called a normal termination.

If the ACCEPT statement contains an ON EXCEPTION phrase, any value in CRT Status Key 1, except " 0", will cause the execution of the imperative-statement in that phrase.

CRT Status Key 2: The second byte of data-name-1 is CRT Status Key 2 and contains a code giving further details of the condition that terminated the ACCEPT operation. Its format and possible values depend on the value in CRT Status Key 1, as shown in the following table.

Table 6-2: Valid Combinations of CRT Status Keys 1 and 2

See your COBOL system documentation on screen handling and user interfaces for an explanation of function key numbers.

CRT Status Key 3: The third byte of data-name-1 is CRT Status Key 3 and should be described as PICTURE 99 COMP-X or as PICTURE 99 COMP (with the NOIBMCOMP directive specified). If CRT Status Key 1 and CRT Status Key 2 are zero, then CRT Status Key 3 contains the raw keyboard code for the key that terminated the ACCEPT operation. Otherwise, the contents of CRT Status Key 3 are undefined.

Where a sequence of keystrokes rather than a single key has been configured to perform a single function, only the code for the first keystroke is returned.

6.1.2.4 REPOSITORY paragraph

The REPOSITORY paragraph allows specification of class names, interface names and property names that may be used within the scope of this environment division.

General Format

Directives

1. In addition to the Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section.
   • RDFPATH - specifies the location of the library for the repository files.

Syntax Rules

1. If any class-name-1, interface-name-2 or property-name-1 is specified more than once in the REPOSITORY paragraph, all the specifications for that name must be identical.

2. Literal-1, literal-2 and literal-3 must be nonnumeric literals and must not be figurative constants.

3. If the CLASS phrase is specified, class-name-2, class-name-3, and interface-name-1 must be:
   1. Parameters of a containing class definition or interface definition; or

   2. Defined in the same repository paragraph where class-name-1 is defined.

4. If class-name-1 is specified in the USING phrase of the CLASS-ID paragraph of a class definition containing this REPOSITORY paragraph or in the USING phrase of the INTERFACE-ID paragraph of an interface definition containing this REPOSITORY paragraph, the EXPANDS phrase must not be specified.

5. If the INTERFACE phrase is specified, class-name-4, interface-name-3 and interface-name-4 must be:
   1. Parameters of a containing class definition or interface definition; or

   2. Defined in the same repository paragraph where interface-name-2 is defined.

6. If interface-name-2 is specified in the USING phrase of the CLASS-ID paragraph of a class definition containing this REPOSITORY paragraph or in the USING phrase of the INTERFACE-ID paragraph of an interface definition containing this REPOSITORY paragraph, the EXPANDS phrase must not be specified.

7. If the specified class-name-1 is the name of the class definition in which this REPOSITORY paragraph is specified, references to class-name-1 are to that class definition and this class-specifier is ignored.

8. If the specified interface-name-2 is the name of the interface definition in which this REPOSITORY paragraph is specified, references to interface-name-2 are to that interface definition and this interface-specifier is ignored.

9. If the CLASS phrase is specified:
   1. If literal-1 is specified, there must be information in the external repository for the class literal-1.

   2. If literal-1 is not specified, there must be information in the external repository for the class class-name-1.

10. If the INTERFACE phrase is specified:
    1. If literal-2 is specified, there must be information in the external repository for the interface literal-2.

    2. If literal-2 is not specified, there must be information in the external repository for the interface interface-name-2.

11. If the PROPERTY phrase is specified:
    1. If literal-3 is specified, there must be information in the external repository for the property literal-3 that is part of one of the classes or interfaces that are declared in this REPOSITORY paragraph.

    2. If literal-3 is not specified, there must be information in the external repository for the property property-name-1 that is part of one of the classes or interfaces that are declared in this REPOSITORY paragraph.

General Rules

1. Class-name-1 is the name of a class that may be used throughout the scope of the containing environment division.

2. If the AS phrase is specified, literal-1 or literal-2 is the name by which the class or interface, respectively, is known to the operating environment. Literal-3 is the name known to the operating environment for a method that implements the named property. The AS phrase is required when the name of a class, interface or property does not follow the rules for formation of a user-defined word or when the name is case specific.

3. Class-name-3 and interface-name-1 are actual parameters for the parameterized class referenced by class-name-2.

4. Class-name-4 and interface-name-4 are actual parameters for the parameterized interface referenced by interface-name-3.

5. If the EXPANDS phrase is specified in a class-specifier, a class class-name-1 is created from the parameterized class class-name-2. The number of parameters in the USING phrase of the EXPANDS phrase of the class-specifier shall be the same as the number of parameters in the USING phrase of the CLASS-ID paragraph of class-name-2. The interface for class-name-1 is the interface specified for class-name-2 with the parameters of class-name-2 replaced by the parameters specified in the class-specifier.

   The class class-name-1 is created from the parameterized class class-name-2 by replacing each specification of the formal parameter by the corresponding actual parameter. This replacement is done after the processing of COPY and REPLACE statements.

6. The compiler uses the information specified for class-name-1 together with the external repository to determine the details of the class that is to be used. The repository information for the class must be in a file whose name is the externalized name of the class with the extension rdf. If the RDFPATH directive is specified, the file must be in the specified directory; otherwise, the file must be in the local directory where the .int and .idy files will be created.

7. Interface-name-2 is the name of an interface that may be used throughout the scope of the containing environment division.

8. If the EXPANDS is specified in an interface-specifier, an interface interface-name-2 is created from the parameterized interface interface-name-3. The number of parameters in the USING phrase of the EXPANDS phrase of the interface-specifier shall be the same as the number of parameters in the USING phrase of the INTERFACE-ID paragraph of interface-name-3. The interface for interface-name-2 is the interface specified for interface-name-3 with the parameters of interface-name-3 replaced by the parameters specified in the interface-specifier.

   The interface interface-name-2 is created from the parameterized interface interface-name-3 by replacing each specification of the formal parameter by the corresponding actual parameter. This replacement is done after the processing of COPY and REPLACE statements.

9. The compiler uses the information specified for interface-name-2 together with the external repository to determine the details of the interface that is to be used. The repository information for the interface must be in a file whose name is the externalized name of the interface with the extension rdf. If the RDFPATH directive is specified, the file must be in the specified directory; otherwise, the file must be in the local directory where the .int and .idy files will be created.

10. Property-name-1 is the name of an object property that may be used throughout the scope of the containing environment division.

6.1.3 Input-Output Section

INPUT-OUTPUT SECTION.
[ file-control-paragraph ]
[ i-o-control-paragraph ]

The FILE-CONTROL Paragraph

Function

The FILE-CONTROL paragraph names each file and allows specification of other file-related information.

General Format

6.1.3.1 The FILE-CONTROL Entry

Function

The FILE-CONTROL entry names a file and can specify other file-related information.

Although they are a part of the standard COBOL definition, the RECORD DELIMITER and RESERVE phrases and ellipses in the ASSIGN clause are explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Formats

Format 1 (Record Sequential Files)

Format 2 (Line Sequential Files)

Format 3 (Relative Files)

Format 4 (Indexed Files)

Format 5 (Sort-Merge Files)

Directives

1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section.
   • ASSIGN - determines how the literal, data-name, or external-file-reference is evaluated.

   • SEQUENTIAL - determines whether files defined as ORGANIZATION IS SEQUENTIAL are considered LINE SEQUENTIAL or RECORD SEQUENTIAL.

Syntax Rules

All Formats (All Files)

1. The SELECT clause must be specified first in the file control entry. The clauses which follow the SELECT clause can appear in any order.

2. Each file described in the Data Division must be named once, and only once, as file-name in the FILE-CONTROL paragraph. Each file specified in the file control entry must have a file description entry in the Data Division of the same factory, method, object or program.

3. If the ACCESS MODE clause is not specified, the ACCESS MODE IS SEQUENTIAL clause is implied.

4. Data-name-1 can be declared in the Data Division as an alphanumeric or group data item long enough to hold the external name of the file. If it is not explicitly declared within the source element, your COBOL system will declare it implicitly as an alphanumeric data item long enough to hold the maximum permissible size of file-name. If data-name-1 occurs in the FROM option, the data item must be explicitly declared in the Data Division.

5. The NOT OPTIONAL phrase has effect only when the file is opened input-output.

6. External-file-reference, data-name-1, or literal-1 specifies the external name of the file.

   If the EXTERNAL or DYNAMIC option is used, literal-1 must not be specified.

   If the DYNAMIC option is used, the word specified for the external file-name will be interpreted as external-file-reference.

7. Data-name-2 must be defined in the Data Division as a two-character, alphanumeric data item

   or a two-character numeric data item with USAGE DISPLAY

   and must not be defined in the File,

   LOCAL-STORAGE

   or Communication Sections of the Data Division.

8. Data-name-3 must be defined as a group item of 6 bytes in the Working-Storage or Linkage Section of the Data Division.

9. Data-name-4 must be defined in the Working-Storage Section as an alphanumeric data item.

10. All data-names can be qualified.

Format 1 (Record Sequential Files only)

11. Literal-2 must be a one-character nonnumeric literal.

12. Data-name-5 can be qualified. It must be defined in the Data Division as a one-character data item of category alphanumeric. It cannot be defined in the Communication, File or Report Sections of the Data Division.

13. Character-string must not be a reserved word, a user-defined word that is defined elsewhere, or a literal.

Formats 1 and 2 (Record and Line Sequential Files)

14. When the ORGANIZATION clause is not specified, sequential organization is assumed.

15. KEYBOARD means console input.

16. DISPLAY means console output.

17. PRINTER specifies the system's main printer.

18. PRINTER-1 specifies the system's second printer.

Format 3 (Relative Files)

19. If a relative file is to be referenced by a START statement, the RELATIVE KEY phrase must be specified for that file.

20. Data-name-5 must not be defined in a record description entry associated with that file-name.

21. The data item referenced by data-name-5 must be defined as an unsigned integer.

Format 4 (Indexed Files)

22. Split-key-name is a concatenation of one or more data items within a record associated with that file-name. It can be referenced only in START and READ statements.

23. The data items referenced by data-name-5 and data-name-8

    and any data-names referenced by split-key-name-1 and split-key-name-2

    must be defined within a record description entry associated with the file-name.

    Any of these data items can be defined as any supported data category. However, the key is still treated as an alphanumeric item for the input and output statements against the file named > in the SELECT clause.

24. Data-name-5 and data-name-8

    and any data-names referenced by split-key-name-1 and split-key-name-2

    cannot describe an item whose size is variable. See the section The OCCURS Clause in this chapter.

25. Data-name-8 cannot reference an item whose leftmost character position corresponds to the leftmost character position of the item referenced by data-name-5 or by another data-name-8 specified for the same file.

26. If the PASSWORD clause is specified, it must immediately follow its associated RECORD KEY or ALTERNATE RECORD KEY clause.

Format 5 (Sort-Merge Files)

27. Each sort or merge file described in the Data Division must be named once and once only as file-name in the FILE-CONTROL paragraph. Each sort or merge file specified in the file control entry must have a sort-merge file description entry in the Data Division.

28. Since file-name represents a sort or merge file, only the ASSIGN clause is permitted to follow file-name in the FILE-CONTROL paragraph.

General Rules

All Formats (All Files)

1. The ASSIGN clause specifies the association of the file referenced by file-name-1 to a storage medium. The first assignment takes effect,

   subsequent assignments within any one ASSIGN clause are documentary only.

2. The RESERVE clause allows the user to specify the required number of input-output areas.

   The RESERVE clause is documentary only, unless the COBOL system documentation specific to your operating system indicates otherwise.

3. The ORGANIZATION clause specifies the logical structure of a file. The file organization is established at the time a file is created and cannot subsequently be changed.

4. When the FILE STATUS clause is specified, a value will be moved by the run-time system into the data item specified by data-name-2 after the execution of every statement that references that file either explicitly or implicitly. This value indicates the status of execution of the statement. (See the section I/O Status later in this manual.)

   Data-name-3, if specified, is documentary only.

5. The PASSWORD clause is documentary only.

6. Use of the reserved word DYNAMIC in an ASSIGN clause indicates that the value of literal-1 or data-name-1 in that ASSIGN clause is the specified file's name in the external file-storage environment.

7. Use of the reserved word EXTERNAL in an ASSIGN clause indicates that external-file-reference identifies the specified file to the external environment for possible further mapping to an external file-storage environment-name. (See your COBOL system documentation on file handling for details on setting up external-file-name for your particular operating environment.)

   If external-file-reference contains the character "–", then only that part of the name following the last "–" is used to identify the file to the external environment.

8. The DISK option without external-file-reference, data-name-1 or literal-1 and without the FROM option, specifies a disk file whose name will be given in a VALUE OF FILE-ID clause in the file description for the file. If that file description contains no VALUE OF FILE-ID clause, the name of the disk file is assumed to be the same as file-name-1 (known as the internal file-name).

9. If any of the keywords DISK, KEYBOARD, DISPLAY, PRINTER or PRINTER-1 are followed by external-file-reference, data-name-1 or literal-1, that keyword is ignored.

10. The DISK option with the FROM option specifies a disk file whose name on the disk is the value of data-name-1. However, if when an OPEN statement is executed for that file, data-name-1 contains all spaces, the name of the disk file is assumed to be the same as file-name-1 (known as the internal-file-name).

11. The OPTIONAL phrase applies only to files opened in the INPUT, I/O or EXTEND mode. Its specification is required for files that are not necessarily present each time the runtime element is executed.
12. The SHARING clause specifies the sharing mode to be used for the file unless it is overridden by the SHARING phrase of the OPEN statement. This clause also specifies whether record locks have an effect. Additional details are specified in Sharing mode.

Formats 1, 3 and 4 (Record Sequential, Relative and Indexed files)

13. The LOCK MODE clause is an optional clause in the file control entry and is used to specify the locking technique used for the file.

    If this clause is omitted, opening the file causes it to become exclusive, with the exception of OPEN INPUT.

    When LOCK MODE IS EXCLUSIVE is specified, the run unit acquires a lock on the whole file when it opens the file.

    When LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL is specified, the file that the run unit opens is shareable. Files opened OUTPUT, and indexed and relative files opened EXTEND are, however, always exclusive.

14. The ROLLBACK clause requests transaction logging for a file under those COBOL systems that support that feature. See your COBOL system documentation on file handling for details of how it is implemented in your system.

    If the ROLLBACK clause is specified then WITH LOCK ON MULTIPLE RECORDS will automatically be in effect.

15. The WITH LOCK ON RECORD clause specifies single record locking for the file.

    The WITH LOCK ON MULTIPLE RECORDS clause specifies multiple record locking for the file. This clause must be present if multiple record locking is required.

16. If LOCK MODE IS AUTOMATIC WITH LOCK ON RECORD is specified for a file, a record lock is acquired by the execution of the READ statement and is released upon execution of a subsequent I/O operation on this file, with the exception of a START statement.

    If LOCK MODE IS AUTOMATIC WITH LOCK ON MULTIPLE RECORD is specified for a file, a record lock is acquired by the execution of the READ statement and is not released until a CLOSE, COMMIT, ROLLBACK or UNLOCK statement is executed, or until an individual lock is released by a DELETE statement.

17. If LOCK MODE IS MANUAL WITH LOCK ON RECORD is specified, a lock is acquired by a READ statement only if it includes the WITH LOCK phrase, and is released upon execution of a subsequent I/O operation on this file, with the exception of a START statement.

    If LOCK MODE IS MANUAL WITH LOCK ON MULTIPLE RECORDS is specified, a record lock is acquired by the READ WITH KEPT LOCK statement and is not released until a CLOSE, COMMIT, ROLLBACK or UNLOCK statement is executed.

18. When the lock mode is MANUAL or AUTOMATIC, single record locking is assumed unless the WITH LOCK ON MULTIPLE RECORDS phrase is included.

19. If a file is defined as EXTERNAL and the operating system file-name is assigned by means of a file-name, for example, by use of either the ASSIGN directive or keyword, using data-name-1 in the SELECT/ ASSIGN statement, or using Format 2 of the VALUE OF phrase of an FD, then the following rules should be followed:
    1. an identifier with the same name should be used to contain the physical file-name in all source elements which reference the file.

    2. the definition of the identifier which contains the physical file-name should also contain the EXTERNAL attribute.

    No violation of these rules will be detected at compile time, but, if any runtime element in the run unit violates these rules, the results at run time will be undefined.

    For further details of the effects of record locking, see your COBOL system documentation on file handling.

Format 1 (Record Sequential Files)

20. The MULTIPLE REEL or MULTIPLE UNIT phrase must be specified if it is possible or intended that the file can be closed by use of the CLOSE REEL or CLOSE UNIT statement.

21. Records in the file are accessed in the sequence specified by predecessor-successor record relationships which are established by the execution of WRITE statements when the file is created or extended.

22. Using the LINE ADVANCING FILE phrase causes a file suitable for a printer to be produced. This file will have an initial carriage-return character, and each record is written with AFTER ADVANCING 1 LINE as the default advancing phrase. See your COBOL system documentation on file handling for further details of the format.

23. The PADDING CHARACTER clause is documentary only.

    If the associated file connector is an external file connector, all PADDING CHARACTER clauses in a run unit which are associated with that file connector must have the same specification. If data-name-5 is external, it must reference an external data item.

    The RECORD DELIMITER clause is documentary only.

Format 2 (Line Sequential Files)

24. When LINE SEQUENTIAL ORGANIZATION is specified either implicitly or explicitly, the file is treated as consisting of fixed length records, each containing one line of data. The records are stored with trailing spaces removed. The definition of a line of data varies among different operating systems. Some terminate line "records" with one or both of the Carriage Return and Line Feed characters, and some pad out as fixed length records. Your COBOL system, therefore, always produces files which are compatible in this respect with the editor software in any operating system.

25. The LOCK MODE IS clause is documentary only.

Format 3 (Relative Files)

26. When access mode is sequential, records in the file are accessed in order of ascending relative record numbers of existing records in the file.

27. When access mode is random, the value of the RELATIVE KEY data item indicates the record to be accessed.

28. All records stored in a relative file are uniquely identified by relative record numbers, which also specify the record's logical ordinal position in the file. The first logical record has a relative record number of 1, and subsequent logical records have relative record numbers of 2, 3, 4, ... .

29. The data item specified by data-name-5 is used to communicate a relative record number between the user and the operating system.

Format 4 (Indexed Files)

30. When access mode is sequential, records in the file are accessed in order of ascending record key values within a given key of reference.

31. When access mode is random, the value of the record key data item indicates the record to be accessed.

32. The RECORD KEY clause specifies the record key that is the prime record key for the file. The values of the prime record key must be unique among records of the file. This prime record key provides an access path to records in an indexed file.

33. If the file has more than one record description entry, data-name-1 need be described only in one of these record description entries. The identical character positions referenced by data-name-1 in any one record description entry are implicitly referenced as keys for all other record description entries of that file.

34. If the associated file connector is an external file connector, all file description entries in the run unit which are associated with that file connector must specify the same data description entry for data-name-1 with the same relative location in the associated record.

35. The ALTERNATE RECORD KEY clause specifies a record key that is an alternative record key for the file. This alternate record key provides an alternative access path to records in an indexed file.

36. The data description of data-name-5

    or split-key-name-1

    and data-name-8

    or split-key-name-2,

    as well as of relative locations within a record, must be the same as that used when the file was created. The number of alternate keys for the file must also be the same as that used when the file was created. This checking is configurable in some environments. (See the KEYCHECK attribute in the Callable File Handler configuration file, which is documented in the section "Configuring the Callable File Handler" of the "Programmer's Guide to File Handling".)

37. The DUPLICATES phrase specifies that the value of the associated record key can be duplicated within any of the records in the file. If the DUPLICATES phrase is not specified, the value of the associated record key must not be duplicated among any of the records in the file.

38. For duplicate values, the correct duplicate entry must be located using sequential reads from the first duplicate entry.

39. The SUPPRESS phrase requests the use of a sparse key for an alternate index. Sparse keys are only available through the Callable File Handler and are not available on all systems (see your COBOL system documentation on file handling for details).

Format 5 (Sort-Merge Files)

40. The file-control entry names a sort or merge file and specifies the association of the file to a storage medium.

41. When the SORT STATUS clause is specified, a value is placed into the two-character data item specified by data-name-2 after the execution of each sort operation. This value indicates the status at completion of the operation.

    The resulting status of the sort operation is indicated by valid combinations of status keys 1 and 2. For explanations of status keys 1 and 2 and definitions of status, see the section I/O Status earlier in this chapter.

    The following combinations of status keys are possible. Status key 1=0 and status key 2=0 indicates successful completion. Status key 1=3 and status key 2=0 indicates a permanent error. If status key 1=9, status key 2 contains an operating system error message number.

    The FILE STATUS clause can be used instead of a SORT STATUS clause, but is treated as a synonym for it, when specified for a sort or merge file.

42. The ASSIGN clause is documentary only.

6.1.3.2 The I-O-CONTROL Paragraph

Function

The I-O-CONTROL paragraph specifies the points at which rerun is to be established, the memory area which is to be shared by different files, and for files with sequential organization the location of files on a multiple file reel.

The RERUN and MULTIPLE FILE TAPE clauses of the I-O-CONTROL paragraph are classed as obsolete elements in the ANSI'85 standard and are scheduled to be deleted from the next full revision of the ANSI Standard.

All dialects within this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

Although they are a part of the standard COBOL definition, the RERUN and MULTIPLE FILE TAPE clauses are explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

Syntax Rules

1. The I-O-CONTROL paragraph is optional.

2. When either the integer-1 RECORDS clause or the integer-2 CLOCK-UNITS clause is specified, character-string must be given in the RERUN clause.

3. In the SAME AREA clause, SORT and SORT-MERGE are equivalent.

4. If the SAME SORT AREA or SAME SORT-MERGE AREA clause is used, at least one of the file-names must represent a sort or merge file. Files that do not represent sort or merge files can also be named in the clause.

5. The two forms of the SAME clause (SAME AREA, SAME RECORD AREA) are considered separately in the following:

   More than one SAME clause can be included in a source element, subject to the following restrictions:

   1. A file-name must not appear in more than one SAME AREA clause.

   2. A file-name must not appear in more than one SAME RECORD AREA clause.

   3. If one or more file-names of a SAME AREA clause appear in a SAME RECORD AREA clause, all of the file-names in that SAME AREA clause must appear in the SAME RECORD AREA clause. However, additional file-names not appearing in that SAME AREA clause can also appear in that SAME RECORD AREA clause. The rule that only one of the files mentioned in a SAME AREA clause can be open at any one time takes precedence over the rule that all files mentioned in a SAME RECORD AREA clause can be open at any one time.

   4. A file-name that represents a SORT or MERGE file must not appear in a SAME AREA clause.

   5. A file-name that represents a sort or merge file must not appear in more than one SAME SORT AREA or SAME SORT-MERGE AREA clause.

   6. If a file-name that does not represent a sort or merge file appears in a SAME AREA clause and one or more SAME SORT AREA or SAME SORT-MERGE AREA clauses, all of the files named in that SAME AREA clause must be named in that SAME SORT AREA or SAME SORT-MERGE AREA clause(s).

6. The files referenced in the SAME AREA, SAME SORT AREA, SAME SORT-MERGE AREA, or SAME RECORD AREA clause need not all have the same organization or access.

7. Character-string must not be a reserved word, a literal or a user-name.

8. The END OF REEL/UNIT clause can only be used if file-name-2 is a sequential file.

9. More than one RERUN clause can be specified for a given file-name-2, subject to the following restrictions:
   1. When multiple integer-1 RECORD clauses are specified, no two of them can specify the same file-name-2.

   2. When multiple END OF REEL or END OF UNIT clauses are specified, no two of them can specify the same file-name-2.

10. Only one RERUN clause containing the CLOCK-UNITS clause can be specified.

11. Each clause in the I-O-CONTROL paragraph may optionally be followed by a period.

General Rules

1. The RERUN clause is documentary only.

2. The SAME AREA clause specifies that two or more files that do not represent sort or merge files are to use the same memory area during processing. The area being shared includes all storage area assigned to the files specified. It is not, therefore, valid to have more than one of the files open at the same time. (See Syntax Rule 5c.)

3. The SAME RECORD AREA clause specifies that two or more files are to use the same memory area for processing the current logical record. All of the files can be open at the same time. A logical record in the SAME RECORD AREA is considered as a logical record of each opened output file whose file-name appears in this SAME RECORD AREA clause and of the most recently read input file whose file-name appears in this SAME RECORD AREA clause. This is equivalent to an implicit redefinition of the area; that is, records are aligned on the leftmost character position.

4. The APPLY clause is documentary only.

5. The MULTIPLE FILE clause is documentary only.

6. If the SAME SORT AREA or SAME SORT-MERGE AREA clause is used, at least one of the file-names must represent a sort or merge file. Files that do not represent sort or merge files can also be named in the clause. This clause specifies that storage is shared as follows:
   1. The SAME SORT AREA or SAME SORT-MERGE AREA clause specifies a memory area which will be made available for use in sorting or merging each sort or merge file named. Thus any memory area allocated for the sorting or merging of a sort or merge file is available for reuse in sorting or merging any of the other sort or merge files.

   2. In addition, storage areas assigned to files that do not represent sort or merge files can be allocated as needed for sorting or merging the sort or merge files named in the SAME SORT AREA or SAME SORT-MERGE AREA clause.

   3. Files other than sort or merge files do not share a storage area. If the user wishes these files to share a storage area, he must also include in the source element a SAME AREA or SAME RECORD AREA clause naming these files.

   4. During the execution of a SORT or MERGE statement that refers to a sort or merge file named in this clause, any non-sort-merge files named in this clause must not be open.

Identification Division

Data Division