5 ENVIRONMENT DIVISION

ENVIRONMENT DIVISION Syntax

  ENVIRONMENT DIVISION.
  ~~~~~~~~~~~ ~~~~~~~~
[ CONFIGURATION SECTION. ]
  ~~~~~~~~~~~~~ ~~~~~~~~
[ SOURCE-COMPUTER.         Compilation-Computer-Specification . ]
  ~~~~~~~~~~~~~~~
[ OBJECT-COMPUTER.         Execution-Computer-Specification . ]
  ~~~~~~~~~~~~~~~
[ SPECIAL-NAMES.           Program-Configuration-Specification . ]
  ~~~~~~~~~~~~~
[ REPOSITORY.              Function-Specification... . ]
  ~~~~~~~~~~
[ INPUT-OUTPUT SECTION. ]
  ~~~~~~~~~~~~ ~~~~~~~
[ FILE-CONTROL.            General-File-Description... . ]
  ~~~~~~~~~~~~
[ I-O-CONTROL.             File-Buffering Specification... . ]
  ~~~~~~~~~~~

This division defines the external computer environment in which the program will be operating. This includes defining any files that the program may be .

  • If both optional sections of this division are coded, they must be coded in the sequence shown.

  • The paragraphs within the sections may be coded in any order.

  • These sections consist of a series of specific, pre-defined, paragraphs (SOURCE-COMPUTER and OBJECT-COMPUTER, for example), each of which serves a specific purpose. If no code is required for the purpose one of the paragraphs serves, the entire paragraph may be omitted.

  • If any of the paragraphs within one of the sections are coded, the section header itself must be coded.

  • If none of the paragraphs within one of the sections are coded, the section header itself may be omitted.

  • If none of the sections within the environment division are coded, the ENVIRONMENT DIVISION. header itself may be omitted.

5.1 CONFIGURATION SECTION

CONFIGURATION SECTION Syntax

  CONFIGURATION SECTION.
  ~~~~~~~~~~~~~ ~~~~~~~
[ SOURCE-COMPUTER. Compilation-Computer-Specification . ]
  ~~~~~~~~~~~~~~~
[ OBJECT-COMPUTER. Execution-Computer-Specification . ]
  ~~~~~~~~~~~~~~~
[ SPECIAL-NAMES.   Program-Configuration-Specification . ]
  ~~~~~~~~~~~~~
[ REPOSITORY.      Function-Specification... . ]
  ~~~~~~~~~~

This section defines the computer system upon which the program is being compiled and executed and also specifies any special environmental configuration or compatibility characteristics.

  1. The four paragraphs in this section may be specified in any order but if not in this order, a warning will be issued.

  2. The configuration section is not allowed in a nested subprogram. A nested program inherits the configuration section settings of its parent program.

  3. If none of the features provided by the configuration section are required by a program, the entire CONFIGURATION SECTION. header may be omitted from the program.

5.1.1 SOURCE-COMPUTER

SOURCE-COMPUTER Syntax

SOURCE-COMPUTER. computer-name [ WITH DEBUGGING MODE ] .
~~~~~~~~~~~~~~~                       ~~~~~~~~~ ~~~~

This paragraph defines the computer upon which the program is being compiled and provides one way in which debugging code embedded within the program may be activated.

  1. The reserved word WITH is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. This paragraph is not allowed in a nested subprogram. A nested program inherits the SOURCE-COMPUTER settings of its parent program.

  3. The value specified for <computer-name> is irrelevant, provided it is a valid COBOL word that does not match any GnuCOBOL reserved word. The <computer-name> value may include spaces. This need not match the <computer-name> used with the OBJECT-COMPUTER paragraph, if any.

  4. The DEBUGGING MODE clause, if present, will inform the compiler that debugging lines (those with a ‘D‘ in column 7 if Fixed Source Mode is in effect, or those prefixed with a >>D if Free Source Mode is in effect) — normally treated as comments — are to be compiled.

  5. Even without the DEBUGGING MODE clause, it is still possible to compile debugging lines. Debugging lines may also be compiled by specifying the -fdebugging-line switch to the GnuCOBOL compiler.

5.1.2 OBJECT-COMPUTER

OBJECT-COMPUTER Syntax

OBJECT-COMPUTER.  [ computer-name ]
~~~~~~~~~~~~~~~
[ MEMORY SIZE IS integer-1 WORDS|CHARACTERS ]
  ~~~~~~ ~~~~              ~~~~~ ~~~~~~~~~~
[ PROGRAM COLLATING SEQUENCE IS alphabet-name-1 ]
          ~~~~~~~~~
[ SEGMENT-LIMIT IS integer-2 ]
  ~~~~~~~~~~~~~
[ CHARACTER CLASSIFICATION IS { locale-name-1  } ]
            ~~~~~~~~~~~~~~    { LOCALE         }
                              { ~~~~~~         }
                              { USER-DEFAULT   }
                              { ~~~~~~~~~~~~   }
                              { SYSTEM-DEFAULT }
                                ~~~~~~~~~~~~~~
.

The MEMORY SIZE and SEGMENT-LIMITclauses are syntactically recognized but are otherwise non-functional. This paragraph describes the computer upon which the program will execute.

  1. The <computer-name>, if specified, must immediately follow the OBJECT-COMPUTER paragraph name. The remaining clauses may be coded in any sequence.

  2. The reserved words CHARACTER, IS, PROGRAM and SEQUENCE are optional and may be omitted. The presence or absence of these words has no effect on the program.

  3. The value specified for <computer-name>, if any, is irrelevant provided it is a valid COBOL word that does not match any GnuCOBOL reserved word. The <computer-name> may include spaces. This need not match the <computer-name> used with the SOURCE-COMPUTER paragraph, if any.

  4. The OBJECT-COMPUTER paragraph is not allowed in a nested subprogram. A nested program inherits the OBJECT-COMPUTER settings of its parent program.

  5. The COLLATING SEQUENCE clause allows you to specify a customized character collating sequence to be used when alphanumeric values are compared to one another. Data will still be stored in the character set native to the computer, but the logical sequence in which characters are ordered for comparison purposes can be altered from that defined by the computer’s native character set. The <alphabet-name-1> you specify needs to be defined in the SPECIAL-NAMES ( 5.1.3 SPECIAL-NAMES) paragraph.

  6. If no COLLATING SEQUENCE clause is specified, the collating sequence implied by the character set native to the computer (usually ASCII) will be used.

  7. The optional CLASSIFICATION clause may be used to specify a locale for the environment in which the program will execute, for the purpose of influencing the upper-case and lower-case mappings of characters for the UPPER-CASE ( 8.1.101 UPPER-CASE) and LOWER-CASE ( 8.1.51 LOWER-CASE) intrinsic functions and the classification of characters for the ALPHABETIC, ALPHABETIC-LOWER and ALPHABETIC-UPPER class tests. The definitions of these classes is taken from the cultural convention specification (LC_CTYPE) from the specified locale.

    The meanings of the four locale specifications are as follows:

    1. <locale-name-1> references a LOCALE ( 5.1.3 SPECIAL-NAMES) definition.

    2. The keyword LOCALE refers to the current locale (in effect at the time the program is executed)

    3. The keyword USER-DEFAULT references the default locale specified for the user currently executing this program.

    4. The keyword SYSTEM-DEFAULT denotes the default locale specified for the computer upon which the program is executing.

  8. Absence of a CLASSIFICATION clause will cause character classification to occur according to the rules for the computer’s native character set (ASCII, EBCDIC, etc.).

5.1.3 SPECIAL-NAMES

SPECIAL-NAMES Syntax

SPECIAL-NAMES.
~~~~~~~~~~~~~
 [ CALL-CONVENTION integer-1 IS mnemonic-name-1 ]
   ~~~~~~~~~~~~~~~
 [ CONSOLE IS CRT ]
   ~~~~~~~    ~~~
 [ CRT STATUS IS identifier-1 ]
   ~~~ ~~~~~~
 [ CURRENCY SIGN IS literal-1 ]
   ~~~~~~~~ ~~~~
 [ CURSOR IS identifier-2 ]
   ~~~~~~
 [ DECIMAL-POINT IS COMMA ]
   ~~~~~~~~~~~~~    ~~~~~
 [ EVENT STATUS IS identifier-3 ]
   ~~~~~ ~~~~~~
 [ LOCALE locale-name-1 IS literal-2 ]...
   ~~~~~~
 [ NUMERIC SIGN IS TRAILING SEPARATE ]
   ~~~~~~~ ~~~~    ~~~~~~~~ ~~~~~~~~
 [ SCREEN CONTROL IS identifier-4 ]
   ~~~~~~ ~~~~~~~
 [ device-name-1 IS mnemonic-name-2 ]...

 [ feature-name-1 IS mnemonic-name-3 ]...

 [ Alphabet-Clause ]...

 [ Class-Definition-Clause ]...

 [ Switch-Definition-Clause ]...

 [ Symbolic-Characters-Clause ]...
 .

The EVENT STATUS and SCREEN CONTROLclauses are syntactically recognized but are otherwise non-functional.

<Alphabet-Name-Clause>, <Class-Definition-Clause>,

<Switch-Definition-Clause> and <Symbolic-Characters-Clause>

are discussed in detail in the next four sections.

The SPECIAL-NAMES paragraph provides a means for specifying various program and operating environment configuration options.

  1. The various clauses that may be specified within the SPECIAL-NAMES paragraph may be coded in any order.

  2. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  3. The SPECIAL-NAMES paragraph is not allowed in a nested subprogram. A nested program inherits the SPECIAL-NAMES settings of its parent program.

  4. Only the final clause specified within this paragraph should be terminated with a period.

  5. The CALL-CONVENTION clause allows a decimal integer, representing a series of ON/OFF switch settings, to be associated with a mnemonic name which may then be coded on a CALL statement ( 7.8.5 CALL). The switch settings defined by this mnemonic will then control how the linkage to a subroutine invoked by the CALL statement that references <mnemonic-name-1> will be handled.

  6. The CONSOLE IS CRT clause, if specified, will cause a DISPLAY statement lacking an explicit UPON clause to be treated as a DISPLAY data-item statement ( 7.8.12.4 DISPLAY data-item), and any ACCEPT statement lacking a FROM clause to be treated as a ACCEPT data-item statement ( 7.8.1.4 ACCEPT data-item).

  7. If the CRT STATUS clause is not specified, an implicit COB-CRT-STATUS identifier (with a PICTURE 9(4)) will be allocated for the purpose of receiving screen ACCEPT statuses. If CRT STATUS is specified, then <identifier-1> must be defined in the program as a PICTURE 9(4) field.

  8. The CURRENCY SIGN clause may be used to redefine the character to be used as a currency sign in a PICTURE ( 6.9.37 PICTURE) clause. The default currency sign is a dollar-sign (’$‘). You may specify any character except 0-9, A-Z, a-z, +, -, ,, ., *, /, ;, (, ), =, \, quote (’"‘) or space.

  9. The CURSOR IS clause allows you to specify a 4- or 6-character data item into which the cursor screen location at the time a screen ACCEPT is satisfied. The value will be returned as rrcc or rrrccc, depending upon the length of the specified <identifier-2>, where rr and rrr represent the row number (starting at zero) and cc and ccc represent the column number (also starting at zero). There is no default data item allocated for this data if the CURSOR IS clause is not specified, and it is the programmer’s responsibility to define <identifier-2> if the clause is specified.

  10. The DECIMAL POINT IS COMMA clause reverses the definition of the ‘,‘ and ‘.‘ characters when they are used as PICTURE editing symbols and within numeric literals. This can have unwanted side-effects - see 2.1.20 Punctuation.

  11. The LOCALE clause may be used to associate external OS-defined locale names (<literal-2>) with an internal name (<locale-name-1>) that may then be referenced within the program. Locale names are defined by the Operating System and/or C compiler GnuCOBOL will be utilizing on your computer.

  12. The following is the list of possible locale codes, for example, that would be available on a Windows computer running a GnuCOBOL version that was built utilizing the MinGW Unix-emulator and the GNU C compiler (gcc):

    • A

      af_ZA, am_ET, ar_AE, ar_BH, ar_DZ, ar_EG, ar_IQ, ar_JO, ar_KW, ar_LB, ar_LY, ar_MA, ar_OM, ar_QA, ar_SA, ar_SY, ar_TN, ar_YE, arn_CL, as_IN, az_Cyrl_AZ, az_Latn_AZ

    • B

      ba_R, be_BY, bg_BG, bn_IN bo_BT, bo_CN, br_FR, bs_Cyrl_BA, bs_Latn_BA

    • C

      ca_ES, cs_CZ, cy_GB

    • D

      da_DK, de_AT, de_CH, de_DE, de_LI, de_LU, dsb_DE, dv_MV

    • E

      el_GR, en_029, en_AU, en_BZ, en_CA, en_GB, en_IE, en_IN, en_JM, en_MY en_NZ, en_PH, en_SG, en_TT, en_US, en_ZA, en_ZW, es_AR, es_BO, es_CL, es_CO, es_CR, es_DO, es_EC, es_ES, es_GT, es_HN, es_MX, es_NI, es_PA, es_PE, es_PR, es_PY, es_SV, es_US, es_UY es_VE, et_EE, eu_ES

    • F

      fa_IR, fi_FI, fil_PH, fo_FO, fr_BE, fr_CA, fr_CH, fr_FR, fr_LU, fr_MC, fy_NL

    • G

      ga_IE, gbz_AF, gl_ES, gsw_FR, gu_IN

    • H

      ha_Latn_NG, he_IL, hi_IN, hr_BA, hr_HR, hu_HU, hy_AM

    • I

      id_ID, ig_NG, ii_CN, is_IS, it_CH, it_IT, iu_Cans_CA, iu_Latn_CA

    • J

      ja_JP

    • K

      ka_GE, kh_KH, kk_KZ, kl_GL, kn_IN, ko_KR, kok_IN, ky_KG

    • L

      lb_LU, lo_LA, lt_LT, lv_LV

    • M

      mi_NZ, mk_MK, ml_IN, mn_Cyrl_MN, mn_Mong_CN moh_CA, mr_IN, ms_BN, ms_MY, mt_MT

    • N

      nb_NO, ne_NP, nl_BE, nl_NL, nn_NO, ns_ZA

    • O

      oc_FR, or_IN

    • P

      pa_IN, pl_PL, ps_AF, pt_BR, pt_PT

    • Q

      qut_GT, quz_BO, quz_EC, quz_PE

    • R

      rm_CH, ro_RO, ru_RU, rw_RW

    • S

      sa_IN, sah_RU, se_FI, se_NO se_SE, si_LK, sk_SK, sl_SI, sma_NO, sma_SE, smj_NO, smj_SE, smn_FI, sms_FI, sq_AL, sr_Cyrl_BA, sr_Cyrl_CS, sr_Latn_BA, sr_Latn_CS, sv_FI, sv_SE, sw_KE syr_SY

    • T

      ta_IN, te_IN, tg_Cyrl_TJ, th_TH tk_TM, tmz_Latn_DZ, tn_ZA, tr_IN, tr_TR, tt_RU

    • U

      ug_CN, uk_UA, ur_PK, uz_Cyrl_UZ, uz_Latn_UZ

    • V

      vi_VN

    • W

      wen_DE, wo_SN

    • X

      xh_ZA

    • Y

      yo_NG

    • Z

      zh_CN, zh_HK, zh_MO, zh_SG, zh_TW, zu_ZA

  13. The NUMERIC SIGN TRAILING SEPARATE specification causes all signed numeric USAGE DISPLAY data items to be created as if the SIGN IS TRAILING SEPARATE CHARACTER clause was included in their definitions.

  14. The <device-name-1> IS <mnemonic-name-2> clause allows you to specify an alternate name (<device-name-1>) for one of the built-in GnuCOBOL device name <mnemonic-name-2>. The list of device names built-into GnuCOBOL, and the physical device associated with that name, are as follows:

    • CONSOLE

      This is the (screen-mode) display of the PC or Unix system.

    • STDIN

    • SYSIN

    • SYSIPT

      These devices (they are all synonymous) represent standard system input (pipe 0). On a PC or UNIX system, this is typically the keyboard. The contents of a file may be delivered to a GnuCOBOL program for access via one of these device names by adding the sequence ‘0< filename‘ to the end of the programs execution command.

    • PRINTER

    • STDOUT

    • SYSLIST

    • SYSLST

    • SYSOUT

      These devices (they are all synonymous) represent standard system output (pipe 1). On a PC or UNIX system, this is typically the display. Output sent to one of these devices by a GnuCOBOL program can be sent to a file by adding the sequence ‘1> filename‘ to the end of the programs execution command.

    • STDERR

    • SYSERR

      These devices (they are synonymous) represent standard system error output (pipe 2). On a PC or UNIX system, this is typically the display. Output sent to one of these devices by a GnuCOBOL program can be sent to a file by adding the sequence ‘2> filename‘ to the end of the programs execution command.

  15. The <feature-name-1> IS <mnemonic-name-3> clause allow for mnemonic names to be assigned to up to the 13 printer channel (i.e. vertical page positioning) position feature names C<nn> (<nn>=01-12) and CSP. Once a channel position has been assigned a mnemonic name, statements of the form WRITE <record-name> AFTER ADVANCING <mnemonic-name-3> may be coded to write the specified print record at the channel position assigned to <mnemonic-name-3>.

    Printers supporting channel positioning are generally mainframe-type line printers. When writing to printers that do not support channel positioning, a formfeed will be issued to the printer.

    The CSP positioning option stands for “No Spacing”. Testing on a MinGW build of GnuCOBOL shows that this too results in a formfeed being issued.

5.1.3.1 Alphabet-Name-Clause

SPECIAL-NAMES Alphabet-Clause Syntax

ALPHABET alphabet-name-1 IS { ASCII             }
~~~~~~~~                    { ~~~~~             }
                            { EBCDIC            }
                            { ~~~~~~            }
                            { NATIVE            }
                            { ~~~~~~            }
                            { STANDARD-1        }
                            { ~~~~~~~~~~        }
                            { STANDARD-2        }
                            { ~~~~~~~~~~        }
                            { Literal-Clause... }

SPECIAL-NAMES ALPHABET Literal-Clause Syntax

literal-1 [ { THRU|THROUGH literal-2 } ]
            { ~~~~ ~~~~~~~           }
            { {ALSO literal-3}...    }
               ~~~~

The ALPHABET clause relates <alphabet-name-1> to a specified character code set or collating sequence, including one you define yourself using the <literal-1> option.

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. The reserved words THRU and THROUGH are interchangeable.

  3. GnuCOBOL considers ASCII, STANDARD-1 and STANDARD-2 to be interchangeable.

  4. NATIVE specifies the system default character set.

  5. The following points apply to using the <literal-n> specifications to compose a custom character set:

    1. The <literal-n> values are either integers or alphanumeric quoted characters. These represent a single character in the NATIVE character set, either by its actual text value (alphanumeric quoted character) or by ordinal position in the NATIVE character set (integer),

    2. The sequence in which characters are defined in this clause specifies the relative order those characters should have when comparisons are made using this alphabet.

    3. Character positions in this list do not affect the actual binary storage values used for the characters. Binary values will still be those of the NATIVE character set.

    4. You may specify any of the figurative constants SPACE, SPACES, ZERO, ZEROS, ZEROES, QUOTE, QUOTES, HIGH-VALUE, HIGH-VALUES, LOW-VALUE or LOW-VALUES for any of the <literal-1>, <literal-2> or <literal-3> specifications.

  6. Once you have defined an alphabet name, that alphabet name may be used on specifications in CODE-SET, COLLATING SEQUENCE, or SYMBOLIC CHARACTERS clauses elsewhere in the program.

5.1.3.2 Class-Definition-Clause

SPECIAL-NAMES Class-Definition-Clause Syntax

CLASS class-name-1 IS { literal-1 [ THRU|THROUGH literal-2 ] }...
~~~~~                               ~~~~ ~~~~~~~

  1. The reserved word IS is optional and may be omitted. The presence or absence of this word has no effect upon the program.

  2. The reserved words THRU and THROUGH are interchangeable.

  3. Both <literal-1> and <literal-2> must be alphanumeric literals of length 1.

  4. The literal(s) specified on this clause define the possible characters that may be found in a data item’s value in order to be considered part of the class.

  5. For example, the following defines a class called Hexadecimal, the definition of which specifies the only characters that may be present in an alphanumeric data item if that data item is to be part of the Hexadecimal class:

    CLASS Hexadecimal IS '0' THRU '9'
                     'A' THRU 'F'
                     'a' THRU 'f'

  6. Once class Hexadecimal has been defined, program code could then use a statement such as IF input-item IS Hexadecimal to determine if the value of characters in a data item are valid according to that class.

5.1.3.3 Switch-Definition-Clause

SPECIAL-NAMES Switch-Definition-Clause Syntax

switch-name-1 [ IS mnemonic-name-1 ]

  [ ON STATUS IS condition-name-1 ]
    ~~
  [ OFF STATUS IS condition-name-2 ]
    ~~~

The switch-definition clause associates a condition-name with a run-time execution switch so that the status of that switch may be tested from within a program.

  1. The reserved words IS and STATUS are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The valid <switch-name-1> names are SWITCH-n (<n> = 0-36).

  3. If the program is compiled with the -fsyntax-extension switch, the switch names SWn (<n> = 0-15) are also valid; they correspond to SWITCH-0 through SWITCH-15, respectively as well as SWITCH-16 through SWITCH-36, SWITCH 0 through SWITCH 26 and SWITCH A through SWITCH Z.

  4. At execution time, each switch will be associated with a run-time environment variable, where <n> will have the value ‘0‘ through ‘15‘. Any of these sixteen environment variables that have the value ON (regardless of upper- or lower-case value) will be considered to be set “on”. Any of these sixteen environment variables having no value at all or a value other than ON will be considered OFF.

  5. Each specified switch must have at least one of a IS <mnemonic-name-1>, ON STATUS or an OFF STATUS option defined for it, otherwise there will be no way to reference the switch from within a GnuCOBOL program.

  6. The IS <mnemonic-name-1> syntax provides a means for setting the switch to either an ON or OFF value via the SET statement ( 7.8.41 SET).

  7. The ON STATUS and OFF STATUS syntax provides a way of associating a condition-name with either the on or off status of the switch, so that status may be tested at execution time via the IF statement ( 7.8.23 IF).

5.1.3.4 Symbolic-Characters-Clause

SPECIAL-NAMES-Symbolic-Characters-Clause Syntax

SYMBOLIC CHARACTERS
~~~~~~~~
  { symbolic-character-1... IS|ARE integer-1... }...

  [ IN alphabet-name-1 ]
    ~~

This clause may be used to define your own figurative constants.

  1. The reserved words ARE, CHARACTERS and IS are optional and may be omitted. The presence or absence of these words has no effect upon the program.

ERROR: uninterpreted block “raggedright”

There must be exactly as many <integer-1> values specified as there are | | <symbolic-character-1> names.

  1. Each symbolic character name will be associated with the corresponding <integer-1>th character in the alphabet named in the IN clause. The integer values are selecting characters from the alphabet by their ordinal position and not by their numeric value; thus, an integer of 15 will select the 15th character in the specified alphabet, regardless of the actual numeric value of the bit pattern that constitutes that character.

  2. If no <alphabet-name-1> is specified, the systems native character set will be assumed.

  3. The following two code examples define the same set of figurative constant names for five ASCII control characters (assuming that ASCII is the system’s native character set). The two examples are identical in their effects, even though the way the figurative constants are defined is different.

    • Individually

      SYMBOLIC CHARACTERS NUL IS 1
                    SOH IS 2
                    BEL IS 8
                    DC1 IS 18
                    DC2 IS 19

    • Respectively

      SYMBOLIC CHARACTERS NUL SOH BEL DC1 DC2
                ARE   1   2   8  18  19

5.1.4 REPOSITORY

REPOSITORY Syntax

REPOSITORY.
~~~~~~~~~~
   FUNCTION { function-prototype-name-1 [ AS literal-1 ] }...
   ~~~~~~~~ {                             ~~             }
            { intrinsic-function-name-1 [ AS literal-2 ] }
            {                             ~~             }
            { intrinsic-function-name-2 INTRINSIC        }
            { ALL INTRINSIC             ~~~~~~~~~        }
              ~~~ ~~~~~~~~~

The REPOSITORY paragraph provides a way to control access to the various built-in intrinsic functions and any user defined functions that your program will be using.

  1. The REPOSITORY paragraph is not allowed in a nested subprogram. A nested program inherits the REPOSITORY settings of its parent program.

  2. The INTRINSIC clause allows you to flag one or more (or ALL) built-in intrinsic functions as being usable without the need to code the keyword FUNCTION in front of the function names.

  3. As an alternative to using the ALL INTRINSIC clause, you may instead compile your GnuCOBOL programs using the -fintrinsics=ALL switch.

  4. The <function-prototype-name-1> option is required to specify the name of a user-defined function your program will be using. Optionally, should you desire, you may specify an alias name by which you will reference that user-defined function. Should you wish, you may also use the AS clause to provide an alias name for a built-in intrinsic function.

  5. The following example

    • enables all intrinsic functions to be specified without the use of the FUNCTION keyword,

    • names two user-defined functions named MY-FUNCTION-1 and MY-FUNCTION-2 that will be used by the program and

    • specifies the alias names SIGMA for the intrinsic function STANDARD-DEVIATION and MF2 for MY-FUNCTION-2.

    REPOSITORY.
    FUNCTION ALL INTRINSIC
    FUNCTION MY-FUNCTION-1
    FUNCTION MY-FUNCTION-2 AS "MF2"
    FUNCTION STANDARD-DEVIATION AS "SIGMA".

A special note about user-defined functions — because you must name a user-defined function that your program will be using in the REPOSITORY paragraph, you may always reference that function from your program’s procedure division without needing to use the FUNCTION keyword.

5.2 INPUT-OUTPUT SECTION

INPUT-OUTPUT SECTION Syntax

[ INPUT-OUTPUT SECTION. ]
  ~~~~~~~~~~~~ ~~~~~~~
[ FILE-CONTROL. ]
  ~~~~~~~~~~~~
    [ SELECT-Statement... ]

[ I-O-CONTROL. ]
  ~~~~~~~~~~~
    [ MULTIPLE-FILE-Statement ]

    [ SAME-RECORD-Statement ]

The INPUT-OUTPUT section provides for the definition of any files the program will be accessing as well as control of the I/O buffering process against those files through the FILE-CONTROL and I-O-CONTROL paragraphs, respectively.

  1. As the diagram shows, there are three types of statements that may occur in the two paragraphs of this section. If none of the statements are coded in a particular paragraph, the paragraph itself may be omitted, otherwise it is required.

  2. If neither paragraph is coded, the INPUT-OUTPUT SECTION. header itself may be omitted, otherwise it is normally required.

  3. If the compiler configuration file ( 10.1.7 Compiler Configuration Files) you are using has relaxed-syntax-check set to ‘yes‘, the FILE-CONTROL and I-O-CONTROL paragraphs may be specified without the INPUT-OUTPUT SECTION header having been coded.

  4. If both statement types are coded in the I-O-CONTROL paragraph, the order in which those statements are coded is irrelevant.

5.2.1 SELECT

SELECT Statement Syntax

SELECT [ [ NOT ] OPTIONAL ] file-name-1
~~~~~~     ~~~   ~~~~~~~~
[ ASSIGN { TO    } [{ EXTERNAL }] [{ DISC|DISK      }] [{ identifier-1 }] ]
  ~~~~~~ { USING }  { ~~~~~~~~ }   { ~~~~ ~~~~      }   { word-1       }
                    { DYNAMIC  }   { DISPLAY        }   { literal-1    }
                      ~~~~~~~      { ~~~~~~~        }
                                   { KEYBOARD       }
                                   { ~~~~~~~~       }
                                   { LINE ADVANCING }
                                   { ~~~~ ~~~~~~~~~ }
                                   { PRINTER        }
                                   { ~~~~~~~        }
                                   { RANDOM         }
                                   { ~~~~~~         }
                                   { TAPE           }
                                     ~~~~
[ COLLATING SEQUENCE IS alphabet-name-1 ]
  ~~~~~~~~~
[ FILE|SORT ] STATUS IS identifier-2 [ identifier-3 ] ]
  ~~~~ ~~~~   ~~~~~~
[ LOCK MODE IS { MANUAL|AUTOMATIC                                } ]
  ~~~~         { ~~~~~~ ~~~~~~~~~                                }
               { EXCLUSIVE [ WITH { LOCK ON MULTIPLE RECORDS } ] }
                 ~~~~~~~~~        { ~~~~ ~~ ~~~~~~~~ ~~~~~~~ }
                                  { LOCK ON RECORD           }
                                  { ~~~~ ~~ ~~~~~~           }
                                  { ROLLBACK                 }
                                  { ~~~~~~~~                 }
[ ORGANIZATION Clause ]
  ~~~~~~~~~~~~
[ ORGANISATION Clause ]
  ~~~~~~~~~~~~
[ RECORD DELIMITER IS STANDARD-1 ]
  ~~~~~~ ~~~~~~~~~    ~~~~~~~~~~
[ RESERVE integer-1 AREAS ]
  ~~~~~~~
[ SHARING WITH { ALL OTHER } ]
  ~~~~~~~      { ~~~       }
               { NO OTHER  }
               { ~~        }
               { READ ONLY }
                 ~~~~ ~~~~

The COLLATING SEQUENCE, RECORD DELIMITER, RESERVE and ALL OTHER clauses are syntactically recognized but are otherwise non-functional. The SELECT statement creates a definition of a file and links that COBOL definition to the external operating system environment.

  1. The reserved words AREAS, IS, MODE, OTHER, SEQUENCE, TO, USING and WITH are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. After <file-name-1>, the various clauses may be coded in any sequence.

  3. A period must follow the last coded clause.

  4. The OPTIONAL clause, to be used only for files that will be used to provide input data to the program, indicates the file may or may not actually be available at run-time. Attempts to OPEN an OPTIONAL file when the file does not exist will receive a special non-fatal file status value (see status 05 in the list of file status values below) indicating the file is not available; a subsequent attempt to READ that file will return an AT END (end-of-file) condition. Optionally, files may be designated as NOT OPTIONAL, if desired. This is useful when specifying the compiler’s -foptional-file switch, which automatically makes all files OPTIONAL except for those explicitly declared as NOT OPTIONAL.

  5. The <file-name-1> value that you specify will be the name by which you will reference the file within your program. This name should be formed according to the rules for user-defined names ( 2.1.2 User-Defined Words).

  6. The optional ASSIGN clause specifies how — at runtime, when <file-name-1> is opened — either a logical device (STDIN, STDOUT) or a file anywhere in one of the currently-mounted file systems will be associated with <file-name-1>, as follows:

    1. There are three components to the ASSIGN clause:

      • <Type>

        EXTERNAL, DYNAMIC or neither

      • <Device>

        the list of device choices

      • <Locator>

        shown as a choice between <identifier-1>, <word-1> and <literal-1>.

    2. ASSIGN TO DISC <file-name-1> will be assumed if there is no ASSIGN clause on a SELECT.

    3. If an ASSIGN clause is coded without a <Device>, the device DISC will be assumed.

    4. If a <Locator> clause is coded, the COBOL file <file-name-1> will be attached to a data file within any file system that is mounted and available to the executing program at the time <file-name-1> is opened. How that file is identified varies, depending upon the specified <Locator>, as follows:

      1. If <literal-1> is coded, the value of the literal will serve as the File Location String that will identify the data file.

      2. If <identifier-1> is coded, the value of the identifier will serve as the File Location String that will identify the data file.

      3. If <word-1> (a syntactically valid word not duplicating a reserved or user-defined word) is coded, and a <Type> is EXTERNAL, then <word-1> itself will serve as the File Location String that will identify the data file. If, however, a <Type> of EXTERNAL was not specified, the compiler will create a PIC X(1024) data item named <word-1> within the program; the contents of that data item at the time the program opens <file-name-1> will then serve as the File Location String that will identify the data file.

      4. File Location Strings will be discussed shortly.

    5. If no <Locator> is coded, <file-name-1> will be attached to a logical device or a file based upon the specified (or implied) <Device>, as follows:

      1. DISC or DISK will assume an attachment to a file named <file-name-1> in whatever directory is current at the time the file is opened.

      2. DISPLAY will assume an attachment to the STDOUT logical device; these files should only be used for output.

      3. KEYBOARD will assume an attachment to the STDIN logical device; these files should only be used for input.

      4. PRINTER will assume an attachment to the LPT1 logical device/port; these files should only be used for output.

      5. RANDOM or TAPE will behave exactly as DISC does. These two additional <Device>s are provided to facilitate the compilation of COBOL source from other COBOL implementations.

    6. The LINE ADVANCING device requires that a <Locator> be specified; these files should only be used for output. A COBOL Line Advancing file will allow carriage-control characters such as line-feeds and form-feeds to be written to the attached operating system file, via the ADVANCING clause of the WRITE statement ( 7.8.52 WRITE).

    7. File Location Strings are used (at runtime) to identify the path and filename to the data file that must be attached to <file-name-1> when that file is opened.

    8. If the compiler configuration file ( 10.1.7 Compiler Configuration Files) you used to compile the program with had a filename-mapping value of yes, the GnuCOBOL runtime system will first attempt to identify a currently-defined environment variable whose value will serve as the data file’s path and filename, as follows:

      1. If the compiler configuration file ( 10.1.7 Compiler Configuration Files) ( 10.1.7 Compiler Configuration Files) you used to compile the program specified mf as the assign-clause value, then the File Locator String will be interpreted according to Microfocus COBOL rules — namely, everything before the last ‘-‘ in the File Locator String will be ignored; the characters after the last ‘-‘ will be treated as the base of an environment variable name. If there is no ‘-‘ character in the File Locator String then the entire File Locator String will serve as the base of an environment variable name. This is the default behaviour for every config file except ibm.

      2. If, on the other hand, the compiler configuration file ( 10.1.7 Compiler Configuration Files) you used to compile the program specified mf as the assign-clause value, then the File Locator String will be interpreted according to according to IBM COBOL rules — namely, the File Locator String is expected to be of the form S-<xxx> or AS-<xxx>, in which case the <xxx> will be treated as the base of an environment variable name. If there is no ‘-‘ character in the File Locator String then the entire File Locator String will serve as the base of an environment variable name.

      3. Once an environment variable name base (let’s refer to it as <bbbb>) has been determined, the runtime system will look for the first one of the following environment variables that exists, in this sequence:

        DD_<bbbb>
dd_<bbbb>
<bbbb>

        Windows systems are case-insensitive with regard to environment variables, so there is no difference between the first two when using a GnuCOBOL implementation built for either Windows/MinGW or native Windows.

        If an environment variable was found, its value will serve as the path and filename to the data file.

    9. If no environment variable was found, or the configuration file ( 10.1.7 Compiler Configuration Files) used to compile the program had a filename-mapping value of NO, then the File Locator String value will serve as the path and filename to the data file.

    10. Paths and file names may be specified on an absolute (C:\Data\datafile.dat, /Data/datafile.dat, …) or relative to the current directory (Data\datafile.dat, Data/datafile.dat, …) basis. If no directory name is included (datafile.dat), the file must be in the current directory.

  7. The FILE STATUS or SORT STATUS clause (they are both equivalent and only one or the other, if any, should be specified) is used to specify the name of a two-digit numeric data item into which an I/O status code will be saved after every I/O verb that is executed against the file. This does not actually allocate the data item — you must define the item yourself somewhere in the data division. Note that the following list is complete as of v3.2: but more can be added and any tests should include one for non zeros as a catch all. See the copy book file filestat.cpy (which may not include all of these listed status codes). See sample version lower down. Possible status codes that can be returned to a FILE STATUS data item are as follows:

    • 00

      Success

    • 02

      Success (Duplicate Record Key Written)

    • 04

      Success (Incomplete)

    • 05

      Success (Optional File Not Found)

    • 06

      Multiple records (in LS)

    • 07

      Success (No Unit)

    • 09

      Success LS Bad Data

    • 10

      End of file reached if reading forward or beginning-of-file reached if reading backward

    • 14

      Out of key range

    • 21

      Key invalid

    • 22

      Key already exists

    • 23

      Key not found

    • 24

      Key boundary violation

    • 30

      Permanent I/O error

    • 31

      Inconsistent filename

    • 34

      Boundary violation

    • 35

      File not found

    • 37

      Permission denied

    • 38

      Closed with lock

    • 39

      Conflicting attribute

    • 41

      File already open

    • 42

      File not open

    • 43

      Read not done

    • 44

      Record overflow

    • 46

      Read error

    • 47

      OPEN INPUT denied (insufficient permissions to read file)

    • 48

      OPEN OUTPUT denied (insufficient permissions to write to file)

    • 49

      OPEN I-O denied (insufficient permissions to read and/or write file)

    • 51

      Record locked

    • 52

      End of page

    • 57

      LINAGE bad specification (I-O linage)

    • 61

      File sharing failure

    • 71

      Bad character

    • 91

      File not available

  8. Sample copy book member, suggest that you copy this content to say FileStat-Msgs.cpy and save in your copy book folder.

    *>************************************************************
*> Author: Gary L. Cutler CutlerGL@gmail.com                 *
*>                                                           *
*> This copybook defines an EVALUATE statement capable of    *
*> translating two-digit FILE-STATUS codes to a message.     *
*>                                                           *
*> Use the REPLACING option to COPY to change the names of   *
*> the MSG and STATUS identifiers to                         *
*> the names your program needs.                             *
*> chg 09/08/23 vbc for missing statuses                     *
*> Chg 11/12/23 vbc for missing statuses, amended note above *
*>                  to allow for copybook expansion.         *
*>************************************************************
     EVALUATE STATUS
          WHEN 00 MOVE 'Success                  ' TO MSG
          WHEN 02 MOVE 'Success Duplicate        ' TO MSG
          WHEN 04 MOVE 'Success Incomplete       ' TO MSG
          WHEN 05 MOVE 'Success Optional, Missing' TO MSG
          when 06 move "Multiple Records LS"       to msg
          WHEN 07 MOVE 'Success No Unit          ' TO MSG
          when 09 move "Success LS Bad Data"       to msg
          WHEN 10 MOVE 'End Of File              ' TO MSG
          WHEN 14 MOVE 'Out Of Key Range         ' TO MSG
          WHEN 21 MOVE 'Key Invalid              ' TO MSG
          WHEN 22 MOVE 'Key Exists               ' TO MSG
          WHEN 23 MOVE 'Key Not Exists           ' TO MSG
          WHEN 24 MOVE 'Key Boundary violation   ' TO MSG
          WHEN 30 MOVE 'Permanent Error          ' TO MSG
          WHEN 31 MOVE 'Inconsistent Filename    ' TO MSG
          WHEN 34 MOVE 'Boundary Violation       ' TO MSG
          WHEN 35 MOVE 'File Not Found           ' TO MSG
          WHEN 37 MOVE 'Permission Denied        ' TO MSG
          WHEN 38 MOVE 'Closed With Lock         ' TO MSG
          WHEN 39 MOVE 'Conflict Attribute       ' TO MSG
          WHEN 41 MOVE 'Already Open             ' TO MSG
          WHEN 42 MOVE 'Not Open                 ' TO MSG
          WHEN 43 MOVE 'Read Not Done            ' TO MSG
          WHEN 44 MOVE 'Record Overflow          ' TO MSG
          WHEN 46 MOVE 'Read Error               ' TO MSG
          WHEN 47 MOVE 'Input Denied             ' TO MSG
          WHEN 48 MOVE 'Output Denied            ' TO MSG
          WHEN 49 MOVE 'I/O Denied               ' TO MSG
          WHEN 51 MOVE 'Record Locked            ' TO MSG
          WHEN 52 MOVE 'End-Of-Page              ' TO MSG
          WHEN 57 MOVE 'I/O Linage               ' TO MSG
          WHEN 61 MOVE 'File Sharing Failure     ' TO MSG
          WHEN 71 MOVE 'Bad Character            ' TO MSG
          WHEN 91 MOVE 'File Not Available       ' TO MSG
          WHEN OTHER
               MOVE "Unknown File Status         " TO MSG
     END-EVALUATE.

  9. One sample code defining and using this copy book in a free format program source.

    In Working-Storage section :

 01  WS-Wor-Areas.
     03  WS-Eval-Msg     pic x(25)       value spaces.
     03  Fs-Reply        pic xx.
     03  WS-No-Care      pic x.

 .....

 01  Error-Messages.
*> System Wide
     03  SL002          pic x(31) value "SL002 Note error and hit return".


In Procedure Division :

     rewrite  CUSTOMER-Record invalid key
              display "Rewrite Customer Rec " at line ws-23-lines col 1
              display CUSTOMER-FILE-STATUS  at line WS-23-Lines  col 22
              move    CUSTOMER-FILE-STATUS to FS-Reply
              perform evaluate-message
              display ws-Eval-Msg at line ws-23-lines col 25 beep
              display SL002       at line ws-lines col 1
              accept  WS-No-Care  at line ws-lines col 33
              display space    at line ws-23-lines col 1 with erase eos
     end-rewrite

*>
 Evaluate-Message        Section.
*>==============================
*>
 copy "FileStat-Msgs.cpy" replacing MSG by ws-Eval-Msg
                                    STATUS by fs-reply.
*>
 Eval-Msg-Exit.  exit section.
*>************   ************
*>

  10. The SHARING clause defines the conditions under which the program will be willing (or not) to allow other programs executing at the same time to access the file. 2.2.15 File Sharing, for the details.

  11. The LOCK clause defines how concurrent access to the file will be managed on a record-by-record basis. 2.2.16 Record Locking, for the details.

  12. For syntax details for the ORGANIZATION clause, see next group of paragraphs.

  13. A SELECT statement without an ORGANIZATION explicitly coded will be handled as if the following ORGANIZATION clause had been specified:

    ORGANIZATION IS SEQUENTIAL
ACCESS MODE IS SEQUENTIAL

5.2.1.1 ORGANIZATION SEQUENTIAL

ORGANIZATION SEQUENTIAL Clause Syntax

[ ORGANIZATION|ORGANISATION IS ] RECORD BINARY SEQUENTIAL
  ~~~~~~~~~~~~ ~~~~~~~~~~~~                    ~~~~~~~~~~
   [ ACCESS MODE IS SEQUENTIAL ]
     ~~~~~~         ~~~~~~~~~~

Files declared as ORGANIZATION SEQUENTIAL will consist of records with no explicit end-of-record delimiter character sequences; records in such files are “delineated” by a calculated byte-offset (based on the maximum record length) into the file.

  1. The reserved words BINARY, IS, MODE and RECORD are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The reserved words ORGANIZATION and ORGANISATION are interchangeable.

  3. The phrase ORGANIZATION IS (and its internationalized alternative, ORGANISATION IS) is optional to provide compatibility with those (few) COBOL implementations that consider ORGANIZATION to be optional. Most COBOL implementations do require the word ORGANIZATION, so it should be used in new programs.

  4. These files cannot be prepared with any standard text-editing or word processing software as all such programs will embed delimiter characters at the end of records (use ORGANIZATION IS LINE SEQUENTIAL instead).

  5. These files may contain either USAGE DISPLAY or USAGE COMPUTATIONAL (of any variety) data since no binary data sequence can be accidentally interpreted as an end-of-record delimiter.

  6. While records in a ORGANIZATION SEQUENTIAL file may be defined as having variable-length records, the file will be structured in such a manner as to reserve space for each record equal to the size of the largest possible record, based on the file’s description in the FILE SECTION.

  7. The ACCESS MODE SEQUENTIAL clause is optional because, if absent, it will be assumed anyway for this type of file. The internal structure of these files is such that they can only be processed in a sequential manner; in order to read the 100th record in such a file, for example, you first must read records 1 through 99.

  8. Sequential files are processed using the following statements:

5.2.1.2 ORGANIZATION LINE SEQUENTIAL

ORGANIZATION LINE SEQUENTIAL Clause Syntax

[ ORGANIZATION|ORGANISATION IS ] LINE SEQUENTIAL
  ~~~~~~~~~~~~ ~~~~~~~~~~~~      ~~~~ ~~~~~~~~~~
   [ ACCESS MODE IS SEQUENTIAL ]
     ~~~~~~         ~~~~~~~~~~
   [ PADDING CHARACTER IS literal-1 | identifier-1 ]
     ~~~~~~~

The PADDING CHARACTER clause is syntactically recognized but is otherwise non-functional. Files declared as ORGANIZATION LINE SEQUENTIAL will consist of records terminated by an end-of-record delimiter character or character sequence.

  1. The reserved words CHARACTER, IS and MODE are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The reserved words ORGANIZATION and ORGANISATION are interchangeable.

  3. The phrase ORGANIZATION IS (and its internationalized alternative, ORGANISATION IS) is optional to provide compatibility with those (few) COBOL implementations that consider that word to be optional. Most COBOL implementations do require the word ORGANIZATION, so it should be used in new programs.

  4. This is the only ORGANIZATION valid for files that are assigned to the PRINTER device.

  5. These files may be created with any standard text-editing or word processing software capable of writing text files. Such files MUST NOT contain any USAGE COMPUTATIONAL or BINARY (of any variety) data since such fields could accidentally contain byte sequences that could be interpreted as an end-of-record delimiter.

  6. Both fixed- and variable-length record formats are supported.

  7. The end-of-record delimiter sequence will be X'0A' (an ASCII line-feed character) or a X'0D0A' (an ASCII carriage-return + line-feed sequence). The former is used on Unix implementations of GnuCOBOL (including Windows/MinGW, Windows/Cygwin and OSX implementations) while the latter would be used with native Windows implementations.

  8. When reading a LINE SEQUENTIAL file, records in excess of the size implied by the file’s description in the FILE SECTION will be truncated while records shorter than that size will be padded to the right with SPACES.

  9. The ACCESS MODE SEQUENTIAL clause is optional because, if absent, it will be assumed anyway for this type of file. The internal structure of these files is such that the data can only be processed in a sequential manner; in order to read the 100th record in such a file, for example, you first must read records 1 through 99.

  10. Files assigned to PRINTER or CONSOLE should be specified as ORGANIZATION LINE SEQUENTIAL.

  11. Line Sequential files are processed using the following statements:

5.2.1.3 ORGANIZATION RELATIVE

ORGANIZATION RELATIVE Clause Syntax

[ ORGANIZATION|ORGANISATION IS ] RELATIVE
  ~~~~~~~~~~~~ ~~~~~~~~~~~~      ~~~~~~~~
   [ ACCESS MODE IS { SEQUENTIAL } ]
     ~~~~~~         { ~~~~~~~~~~ }
                    { DYNAMIC    }
                    { ~~~~~~~    }
                    { RANDOM     }
                      ~~~~~~
   [ RELATIVE KEY IS identifier-1 ]
     ~~~~~~~~

These files are files with an internal organization such that records may be processed in a sequential manner based upon their physical location in the file or in a random manner by allowing records to be read, written or updated by specifying the relative record number in the file.

  1. The reserved words IS, KEY and MODE are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The reserved words ORGANIZATION and ORGANISATION are interchangeable.

  3. The phrase ORGANIZATION IS (and its internationalized alternative, ORGANISATION IS) is optional to provide compatibility with those (few) COBOL implementations that consider that word to be optional. Most COBOL implementations do require the word ORGANIZATION, so it should be used in new programs.

  4. ORGANIZATION RELATIVE files cannot be assigned to the CONSOLE, DISPLAY, LINE ADVANCING or PRINTER devices.

  5. The RELATIVE KEY clause is optional only if ACCESS MODE SEQUENTIAL is specified.

  6. While an ORGANIZATION RELATIVE file may be defined as having variable-length records, the file will be structured in such a manner as to reserve space for each record equal to the size of the largest possible record as defined by the file’s description in the FILE SECTION.

  7. ACCESS MODE SEQUENTIAL, the default ACCESS MODE if none is specified, indicates that the records of the file will be processed in a sequential manner, according to their physical sequence in the file.

  8. ACCESS MODE RANDOM means that records will be processed in random sequence by specifying their record number in the file every time the file is read or written.

  9. ACCESS MODE DYNAMIC indicates the program may switch back and forth between SEQUENTIAL and RANDOM mode during execution. The file starts out initially in SEQUENTIAL mode when first opened but the program may use the START statement ( 7.8.43 START) to switch between sequential and random access.

  10. The RELATIVE KEY data item is a numeric data item that cannot be defined as a field within records of this file. Its purpose is to return the current relative record number of a relative file that is being processed in SEQUENTIAL access mode and to serve as a key that specifies the relative record number to be read or written when processing a relative file in RANDOM access mode.

  11. Relative files are processed using the following statements:

5.2.1.4 ORGANIZATION INDEXED

ORGANIZATION INDEXED Clause Syntax

[ ORGANIZATION|ORGANISATION IS ] INDEXED
  ~~~~~~~~~~~~ ~~~~~~~~~~~~      ~~~~~~~
   [ ACCESS MODE IS { SEQUENTIAL } ]
     ~~~~~~         { ~~~~~~~~~  }
                    { DYNAMIC    }
                    { ~~~~~~~    }
                    { RANDOM     }
                      ~~~~~~
   [ RECORD KEY IS { [ data-name-1       ]
     ~~~~~~
                   { [ record-key-name-1 ]
                     [ =|{SOURCE IS} data-name-2 ] ... ] }
                          ~~~~~~
   [ ALTERNATE RECORD KEY IS { [ data-name-3       ]
     ~~~~~~~~~ ~~~~~~
                             { [ record-key-name-2 ]
                               [ =|{SOURCE IS} data-name-4 ] ... ] }
                                    ~~~~~~
                             [ WITH DUPLICATES ] ]...
                                    ~~~~~~~~~~
                             [ SUPPRESS WHEN ALL literal     ]
                               ~~~~~~~~~~~~~~~~~
                             [ SUPPRESS WHEN SPACES | ZEROES ]
                               ~~~~~~~~~~~~~~~~~~~~   ~~~~~~

Indexed files, like relative files, may have their records processed in either a sequential or random manner. Unlike relative files, however, the actual location of a record in an indexed file is calculated automatically based upon the value(s) of one or more alphanumeric fields within records of the file. For example, an indexed file containing product data might use the product identification code as a record key. This means you may read, write or update the A6G4328th record or the Z8X7723th record directly, based upon the product id value of those records!

  1. The reserved words IS, KEY and MODE are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. The reserved words ORGANIZATION and ORGANISATION are interchangeable.

  3. The phrase ORGANIZATION IS (and its internationalized alternative, ORGANISATION IS) is optional to provide compatibility with those (few) COBOL implementations that consider that word to be optional. Most COBOL implementations do require the word ORGANIZATION, so it should be used in new programs.

  4. ORGANIZATION INDEXED files cannot be assigned to CONSOLE, DISPLAY, KEYBOARD, LINE ADVANCING or PRINTER.

  5. ACCESS MODE SEQUENTIAL, the default ACCESS MODE if none is specified, indicates that the records of the file will be processed in a sequential manner with respect to the values of the RECORD KEY or the ALTERNATE RECORD KEY most-recently referenced on a START statement ( 7.8.43 START).

  6. ACCESS MODE RANDOM means that records will be processed in random sequence by accessing the record with specific record key or alternate record key values.

  7. ACCESS MODE DYNAMIC allows the file will be processed either in RANDOM or SEQUENTIAL mode; the program may switch between the two modes as needed. The START statement is used to make the switch between modes.

  8. The RECORD KEY clause defines the field within the record used to provide the primary access to records within the file. No two records in the file will be allowed to have the same PRIMARY KEY field value. The SOURCE IS clause is for use with Split Keys.

  9. The ALTERNATE RECORD KEY clause, if used, defines an additional field within the record that provides an alternate means of directly accessing records or an additional field by which the file’s contents may be processed sequentially. You have the choice of allowing records to have duplicate alternate key values, if necessary.

  10. There may be multiple ALTERNATE RECORD KEY clauses, each defining an additional alternate key for the file.

  11. Usage of the SUPPRESS WHEN clause is used when Sparse Keys are required which may take the form for a literal or spaces or zeroes.

  12. Indexed files are processed using the following statements:

5.2.2 SAME RECORD AREA

I-O-CONTROL SAME AREA Syntax

SAME { SORT-MERGE } AREA FOR file-name-1... .
~~~~ { ~~~~~~~~~~ }
     { SORT       }
     { ~~~~       }
     { RECORD     }
       ~~~~~~

The SAME SORT-MERGE and SAME SORTclauses are syntactically recognized but are otherwise non-functional. The SAME RECORD AREA clause allows you to specify that multiple files should share the same input and output memory buffers.

  1. The reserved words AREA and FOR are optional and may be omitted. The presence or absence of these words has no effect upon the program.

  2. This statement must be terminated with a period.

  3. While coding only a single file name (the repeated <file-name-1> item) is syntactically valid, this statement will have no effect upon the program unless at least two files are specified.

  4. The effect of this statement will be to cause the specified files to share the same I/O buffer in memory. These buffers can sometimes get quite large, and by having multiple files share the same buffer memory you may significantly cut down the amount of memory the program is using (thus making “room” for more procedural code or data). If you do use this feature, take care to ensure that no more than one of the specified files are ever OPEN simultaneously.

5.2.3 MULTIPLE FILE

I-O-CONTROL MULTIPLE FILE Syntax

MULTIPLE FILE TAPE CONTAINS
~~~~~~~~
   { file-name-1 [ POSITION integer-1 ] }...
                   ~~~~~~~~
   .

The MULTIPLE FILE TAPE clause is obsolete and is therefore recognized but not functional.