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. Prototype-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-COMPUTERandOBJECT-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.
CONFIGURATION SECTION
CONFIGURATION SECTION Syntax
=======================================================================
CONFIGURATION SECTION.
~~~~~~~~~~~~~ ~~~~~~~
[ SOURCE-COMPUTER. Compilation-Computer-Specification . ]
~~~~~~~~~~~~~~~
[ OBJECT-COMPUTER. Execution-Computer-Specification . ]
~~~~~~~~~~~~~~~
[ SPECIAL-NAMES. Program-Configuration-Specification . ]
~~~~~~~~~~~~~
[ REPOSITORY. Prototype-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.
The four paragraphs in this section may be specified in any order but if not in this order, a warning will be issued.
The configuration section is not allowed in a nested subprogram. A nested program inherits the configuration section settings of its parent program.
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.
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.
The reserved word
WITHis optional and may be omitted. The presence or absence of this word has no effect upon the program.This paragraph is not allowed in a nested subprogram. A nested program inherits the
SOURCE-COMPUTERsettings of its parent program.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-COMPUTERparagraph, if any.The
DEBUGGING MODEclause, 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>>Dif Free Source Mode is in effect) — normally treated as comments — are to be compiled.Even without the
DEBUGGING MODEclause, it is still possible to compile debugging lines. Debugging lines may also be compiled by specifying the-fdebugging-lineswitch to the GnuCOBOL compiler.
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-LIMIT clauses are syntactically recognized but are otherwise non-functional.
=======================================================================
This paragraph describes the computer upon which the program will execute.
The <computer-name>, if specified, must immediately follow the
OBJECT-COMPUTERparagraph name. The remaining clauses may be coded in any sequence.The reserved words
CHARACTER,IS,PROGRAMandSEQUENCEare optional and may be omitted. The presence or absence of these words has no effect on the program.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-COMPUTERparagraph, if any.The
OBJECT-COMPUTERparagraph is not allowed in a nested subprogram. A nested program inherits theOBJECT-COMPUTERsettings of its parent program.The
COLLATING SEQUENCEclause 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 theSPECIAL-NAMES(see SPECIAL-NAMES) paragraph.If no
COLLATING SEQUENCEclause is specified, the collating sequence implied by the character set native to the computer (usually ASCII) will be used.The optional
CLASSIFICATIONclause 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 theUPPER-CASE(see UPPER-CASE) andLOWER-CASE(see LOWER-CASE) intrinsic functions and the classification of characters for theALPHABETIC,ALPHABETIC-LOWERandALPHABETIC-UPPERclass 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:
<locale-name-1> references a
LOCALE(see SPECIAL-NAMES) definition.The keyword
LOCALErefers to the current locale (in effect at the time the program is executed)The keyword
USER-DEFAULTreferences the default locale specified for the user currently executing this program.The keyword
SYSTEM-DEFAULTdenotes the default locale specified for the computer upon which the program is executing.
Absence of a
CLASSIFICATIONclause will cause character classification to occur according to the rules for the computer’s native character set (ASCII, EBCDIC, etc.).
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 [ WITH PICTURE SYMBOL literal-2 ] .]
~~~~~~~~ ~~~~~~~ ~~~~~~
[ CURSOR IS identifier-2 .]
~~~~~~
[ DECIMAL-POINT IS COMMA .]
~~~~~~~~~~~~~ ~~~~~
[ EVENT STATUS IS identifier-3 .]
~~~~~ ~~~~~~
[ LOCALE locale-name-1 IS literal-3 .]...
~~~~~~
[ NUMERIC SIGN IS TRAILING SEPARATE .]
~~~~~~~ ~~~~ ~~~~~~~~ ~~~~~~~~
[ SCREEN CONTROL IS identifier-4 .]
~~~~~~ ~~~~~~~
[ SYMBOLIC CONSTANT { identifier-5 IS literal-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 .]... .
=======================================================================
<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.
The various clauses that may be specified within the
SPECIAL-NAMESparagraph may be coded in any order.The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program.The
SPECIAL-NAMESparagraph is not allowed in a nested subprogram. A nested program inherits theSPECIAL-NAMESsettings of its parent program.Only the final clause specified within this paragraph should be terminated with a period.
The
CALL-CONVENTIONclause 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 aCALLstatement (see CALL). The switch settings defined by this mnemonic will then control how the linkage to a subroutine invoked by theCALLstatement that references <mnemonic-name-1> will be handled.The
CONSOLE IS CRTclause, if specified, will cause aDISPLAYstatement lacking an explicitUPONclause to be treated as aDISPLAY data-itemstatement (see DISPLAY data-item), and anyACCEPTstatement lacking aFROMclause to be treated as aACCEPT data-itemstatement (see ACCEPT data-item).If the
CRT STATUSclause is not specified, an implicitCOB-CRT-STATUSidentifier (with aPICTURE 9(4)) will be allocated for the purpose of receiving screenACCEPTstatuses. IfCRT STATUSis specified, then <identifier-1> must be defined in the program as aPICTURE 9(4)field.The
CURRENCY SIGNclause may be used to redefine the character to be used as a currency sign in aPICTURE(see PICTURE) clause. The default currency sign is a dollar-sign (‘$’). You may specify any character except0-9,A-Z,a-z,+,-,,,.,*,/,;,(,),=,\\, quote (‘"’) or space.The
CURSOR ISclause allows you to specify a 4- or 6-character data item into which the cursor screen location at the time a screenACCEPTis 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 theCURSOR ISclause is not specified, and it is the programmer’s responsibility to define <identifier-2> if the clause is specified. If identifier-2 refers to a data item that contains a valid screen position at the beginning of a ACCEPT statement, and that position corresponds to an input field, that position is used as the initial position for the cursor. This position may be at the beginning of an input field or at some offset within the input field.The
DECIMAL POINT IS COMMAclause reverses the definition of the ‘,’ and ‘.’ characters when they are used asPICTUREediting symbols and within numeric literals. This can have unwanted side-effects - see Punctuation.The
LOCALEclause may be used to associate external OS-defined locale names (<literal-3>) 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.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
Sample of use:
ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. ibmpc. OBJECT-COMPUTER. ibmpc CLASSIFICATION brazil. SPECIAL-NAMES. LOCALE brazil "pt_BR.UTF-8".The
NUMERIC SIGN TRAILING SEPARATEspecification causes all signed numericUSAGE DISPLAYdata items to be created as if theSIGN IS TRAILING SEPARATE CHARACTERclause was included in their definitions.The
device-name-1 IS mnemonic-name-2clause 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.
The
feature-name-1 IS mnemonic-name-3clause allow for mnemonic names to be assigned to up to the 13 printer channel (i.e. vertical page positioning) position feature namesCnn(nn=01-12) andCSP. Once a channel position has been assigned a mnemonic name, statements of the formWRITE record-name AFTER ADVANCING mnemonic-name-3may 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
CSPpositioning option stands for “No Spacing”. Testing on a MinGW build of GnuCOBOL shows that this too results in a formfeed being issued.The
SCREEN CONTROLIS identifier-4 must refer to a Working-Storage field defined as follows:01 identifier-4. 03 ACCEPT-CONTROL PIC 9. 03 CONTROL-VALUE PIC 999. 03 CONTROL-HANDLE USAGE HANDLE. 03 CONTROL-ID PIC X(2) COMP-X.The
SCREEN CONTROLclause is supported only as a definition but its use is currently incomplete. It will be fully usable when the "embedded-procedures" at the SCREEN SECTION entry level will be implemented.The
EVENT-STATUSis used to identify which data item is to receive information about screen events, identifier-3 must refer to a Working-Storage field defined as follows:01 identifier-3. 03 EVENT-TYPE PIC X(4) COMP-X. 03 EVENT-WINDOW-HANDLE USAGE HANDLE OF WINDOW. 03 EVENT-CONTROL-HANDLE USAGE HANDLE. 03 EVENT-CONTROL-ID PIC X(2) COMP-X. 03 EVENT-DATA-1 USAGE SIGNED-SHORT. 03 EVENT-DATA-2 USAGE SIGNED-LONG. 03 EVENT-ACTION PIC X COMP-X.The
EVENT STATUSclause is supported only as a definition but its use is currently incomplete. It will be fully usable when the "embedded-procedures" at the SCREEN SECTION entry level will be implemented.The
SYMBOLIC CONSTANTclause associates a name with a numeric or an alphanumeric literal (alphanumeric is a GnuCOBOL extension).>>SOURCE FREE ID DIVISION. PROGRAM-ID. PROG. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES. SYMBOLIC CONSTANT CONST-1 IS '<CONST-1>'. SYMBOLIC CONSTANT CONST-2 -1234.567890 CONST-3 IS '-CONST-3'. DATA DIVISION. WORKING-STORAGE SECTION. 01 wAAA PIC -Z(11)9.9(6). 01 wXXX PIC X(20)VALUE CONST-1. PROCEDURE DIVISION. DISPLAY CONST-1 ' ' CONST-2 ' ' wXXX ' ' CONST-3 compute wAAA = 100 * CONST-2 display wAAA accept omitted STOP RUN.
Alphabet-Name-Clause
SPECIAL-NAMES Alphabet-Clause Syntax
=======================================================================
ALPHABET alphabet-name-1
~~~~~~~~
{ [ FOR ALPHANUMERIC ] IS { ASCII } }
{ ~~~~~~~~~~~~ { ~~~~~ } }
{ { STANDARD-1 } }
{ { ~~~~~~~~~~ } }
{ { STANDARD-2 } }
{ { ~~~~~~~~~~ } }
{ { EBCDIC } }
{ { ~~~~~~ } }
{ { NATIVE } }
{ { ~~~~~~ } }
{ { {Literal-Clause}...} }
{ [ FOR NATIONAL ] IS { NATIVE } }
{ ~~~~~~~~ { ~~~~~~ } }
{ { {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.
The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program.The reserved words
THRUandTHROUGHare interchangeable.GnuCOBOL considers
ASCII,STANDARD-1andSTANDARD-2to be interchangeable.NATIVEspecifies the system default character set.The following points apply to using the <literal-n> specifications to compose a custom character set:
The <literal-n> values are either integers or alphanumeric quoted characters. These represent a single character in the
NATIVEcharacter set, either by its actual text value (alphanumeric quoted character) or by ordinal position in theNATIVEcharacter set (integer),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.
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
NATIVEcharacter set.You may specify any of the figurative constants
SPACE,SPACES,ZERO,ZEROS,ZEROES,QUOTE,QUOTES,HIGH-VALUE,HIGH-VALUES,LOW-VALUEorLOW-VALUESfor any of the <literal-1>, <literal-2> or <literal-3> specifications.
Once you have defined an alphabet name, that alphabet name may be used on specifications in
CODE-SET,COLLATING SEQUENCE, orSYMBOLIC CHARACTERSclauses elsewhere in the program. Here an example to show this in operation:>>SOURCE FREE identification division. program-id. TESTALPHABET. environment division. configuration section. *> ASCII collating sequence is: numeric < upper-case < lower-case *> but new ALPHABET is : lower-case < upper-case < numeric special-names. alphabet NEWSEQ for alphanumeric is "a" THRU "z" "A" THRU "Z" "0" THRU "9". input-output section. file-control. select SORTFILE assign to SORTWORKFILE. data division. file section. SD SORTFILE. 01 SORTRECORD. 02 SORTDATA PIC X(20). PROCEDURE DIVISION. sort SORTFILE on ascending key SORTDATA collating sequence is NEWSEQ input procedure is InputProc output procedure is OutputProc. display "** END OF SORTED DATA **" stop run. InputProc. perform until SORTDATA = space display "Type your data (max 20 CHARS, SPACE to SORT): " WITH NO ADVANCING accept SORTDATA release SORTRECORD end-perform. OutputProc. display SPACE display "** SORTED DATA **". perform with test after until exit return SORTFILE at end exit perform end-return display SORTDATA end-perform.
Class-Definition-Clause
SPECIAL-NAMES Class-Definition-Clause Syntax
=======================================================================
CLASS class-name-1 IS { literal-1 [ THRU|THROUGH literal-2 ] }...
~~~~~ ~~~~ ~~~~~~~
=======================================================================
The reserved word
ISis optional and may be omitted. The presence or absence of this word has no effect upon the program.The reserved words
THRUandTHROUGHare interchangeable.Both <literal-1> and <literal-2> must be alphanumeric literals of length 1.
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.
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 theHexadecimalclass:CLASS Hexadecimal IS '0' THRU '9' 'A' THRU 'F' 'a' THRU 'f'Once class
Hexadecimalhas been defined, program code could then use a statement such asIF input-item IS Hexadecimalto determine if the value of characters in a data item are valid according to that class.
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 |}
{ ~~~ }
{ {| 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.
The reserved words
ISandSTATUSare optional and may be omitted. The presence or absence of these words has no effect upon the program.The valid <switch-name-1> names are
SWITCH-n(n= 0-36).If the program is compiled with the
-fsyntax-extensionswitch, the switch namesSWn(n= 0-15) are also valid; they correspond toSWITCH-0throughSWITCH-15, respectively as well asSWITCH-16throughSWITCH-36,SWITCH 0throughSWITCH 26andSWITCH AthroughSWITCH Z.At execution time, each switch will be associated with a
COB_SWITCH_nrun-time environment variable, wherenwill have the value ‘0’ through ‘15’. Any of these sixteen environment variables that have the valueON(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 thanONwill be consideredOFF.Each specified switch must have at least one of a
IS mnemonic-name-1,ON STATUSor anOFF STATUSoption defined for it, otherwise there will be no way to reference the switch from within a GnuCOBOL program.The
IS mnemonic-name-1syntax provides a means for setting the switch to either anONorOFFvalue via theSETstatement (see SET).The
ON STATUSandOFF STATUSsyntax 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 theIFstatement (see IF).
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.
The reserved words
ARE,CHARACTERSandISare optional and may be omitted. The presence or absence of these words has no effect upon the program.There must be exactly as many <integer-1> values specified as there are <symbolic-character-1> names.
Each symbolic character name will be associated with the corresponding <integer-1>th character in the alphabet named in the
INclause. 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.If no <alphabet-name-1> is specified, the systems native character set will be assumed.
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
REPOSITORY
REPOSITORY Syntax
=======================================================================
REPOSITORY.
~~~~~~~~~~
[ { FUNCTION { { intrinsic-function-name-1 }...} INTRINSIC } ]
[ { ~~~~~~~~ { ALL } ~~~~~~~~~ } ]
[ { ~~~ } ]
[ { } ]
[ { FUNCTION function-prototype-name-1 [ AS literal-1 ] }...} .]
[ { ~~~~~~~~ ~~ } ]
[ { } ]
[ { PROGRAM program-prototype-name-1 [ AS literal-2 ] }...} ]
[ { ~~~~~~~ ~~ } ]
=======================================================================
The REPOSITORY paragraph allows specification of program and function prototype names. It also allows declaration of intrinsic-function-names that may be used without specifying the word FUNCTION.
The
REPOSITORYparagraph is not allowed in a nested subprogram. A nested program inherits theREPOSITORYsettings of its parent program.The
REPOSITORYname can be stand alone, i.e., with no sub clauses associated with it.All sub clauses must end with a period for the last occurance, see examples.
The
INTRINSICclause allows you to flag one or more (orALL) built-in intrinsic functions as being usable without the need to code the keywordFUNCTIONin front of the function names.As an alternative to using the
ALL INTRINSICclause, you may instead compile your GnuCOBOL programs using the-fintrinsics=ALLswitch.The <function-prototype-name-1> option is required to specify the name of a user-defined function your program will be using. Optionally, you may specify an alias name by which you will reference that user-defined function using
AS.The
ASclause in both cases above is to define the external name to be used for the internally (in COBOL) used function (e.g., a C function name, otherwise GnuCOBOL’s own name translation will apply and only user-functions created by GnuCOBOL modules FUNCTION-ID. will be usable).The following example
enables all intrinsic functions to be specified without the use of the
FUNCTIONkeyword,names two user-defined functions named
MY-FUNCTION-1andMY-FUNCTION-2that will be used by the program and
REPOSITORY. FUNCTION ALL INTRINSIC FUNCTION MY-FUNCTION-1 FUNCTION MY-FUNCTION-2 AS "MF2" Another more full example taken from the FAQs: >>SOURCE FREE IDENTIFICATION DIVISION. PROGRAM-ID. prog. ENVIRONMENT DIVISION. CONFIGURATION SECTION. REPOSITORY. PROGRAM recursion-test PROGRAM cancel-test. DATA DIVISION. WORKING-STORAGE SECTION. 01 num PIC 9 VALUE 0. PROCEDURE DIVISION. CALL recursion-test USING num DISPLAY "<" CALL cancel-test CALL cancel-test CANCEL cancel-test CALL cancel-test DISPLAY "<" . END PROGRAM prog. IDENTIFICATION DIVISION. PROGRAM-ID. recursion-test RECURSIVE. DATA DIVISION. LINKAGE SECTION. 01 x PIC 9. PROCEDURE DIVISION USING x. ADD 1 TO x DISPLAY x NO ADVANCING IF x = 1 CALL 'recursion-test' USING x END-IF. END PROGRAM recursion-test. IDENTIFICATION DIVISION. PROGRAM-ID. cancel-test. DATA DIVISION. WORKING-STORAGE SECTION. 01 x PIC 9 VALUE 1. PROCEDURE DIVISION. DISPLAY x NO ADVANCING ADD 1 TO x. END PROGRAM cancel-test.
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.
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.
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.
If neither paragraph is coded, the
INPUT-OUTPUT SECTION.header itself may be omitted, otherwise it is normally required.If the compiler configuration file (see Compiler Configuration Files) you are using has
relaxed-syntax-checkset to ‘yes’, theFILE-CONTROLandI-O-CONTROLparagraphs may be specified without theINPUT-OUTPUT SECTIONheader having been coded.If both statement types are coded in the
I-O-CONTROLparagraph, the order in which those statements are coded is irrelevant.
SELECT
SELECT Statement Syntax
=======================================================================
SELECT [ [ NOT ] OPTIONAL ] file-name-1
~~~~~~ ~~~ ~~~~~~~~
ASSIGN TO { [ device-1 ] { literal-1 | identifier-1 } }
~~~~~~ { ~~~~~~~~ }
{ [ EXTERNAL ] { device-1 } { identifier-1 } }
{ [ ~~~~~~~~ ] { ~~~~~~~~ } { word-1 } }
{ [ DYNAMIC ] }
{ ~~~~~~~ }
{ [ device-1 ] { USING } { identifier-1 } }
{ [ ~~~~~~~~ ] { ~~~~~ } { word-1 } }
{ { VARYING } }
{ ~~~~~~~ }
{ DISK FROM identifier-1 }
~~~~ ~~~~
[ ORGANIZATION | ORGANISATION Clause ]
~~~~~~~~~~~~ ~~~~~~~~~~~~
[ [ FILE | SORT ] STATUS IS identifier-2 [ identifier-3 ] ]
~~~~ ~~~~ ~~~~~~
[ LOCK MODE IS { MANUAL } [ WITH { LOCK ON [ MULTIPLE ] RECORDS } ] ]
~~~~ { ~~~~~~ } ~~~~ { ~~ ~~~~~~~~ ~~~~~~ }
{ AUTOMATIC } { ROLLBACK }
{ ~~~~~~~~~ } ~~~~~~~~
{ EXCLUSIVE } [ WITH MASS-UPDATE ]
~~~~~~~~~
[ RECORD DELIMITER IS { STANDARD-1 } ]
~~~~~~ ~~~~~~~~~ { ~~~~~~~~~~ }
{ LINE-SEQUENTIAL }
{ ~~~~~~~~~~~~~~~ }
{ BINARY-SEQUENTIAL }
{ ~~~~~~~~~~~~~~~~~ }
{ identifier-4 }
[ RESERVE { NO | integer-1 } [ AREA | AREAS ] ]
~~~~~~~ ~~ ~~~~ ~~~~~
[ SHARING WITH { ALL OTHER } ]
~~~~~~~ { ~~~ }
{ NO OTHER }
{ ~~ }
{ READ ONLY }
~~~~ ~~~~
[ COLLATING SEQUENCE { IS alphabet-name-1 [national-collating-sequence ] } ]
~~~~~~~~ { {FOR ALPHANUMERIC IS alphanumeric-collating-sequence} }
{ { ~~~~~~~~~~~~ } }
{ {FOR NATIONAL IS national-collating-sequence } }
~~~~~~~~
[ PADDING CHARACTER IS { identifier-6 | literal-6 } ]
~~~~~~~
[ NOMINAL KEY IS identifier-7 ]
~~~~~~~
[ FILE-LIMITS { IS } { { identifier-8 } { THROUGH } { identifier-9 } }... ]
~~~~~~~~~~ { ~~~ } { { literal-8 } { ~~~~~~~ } { literal-9 } }
{ ARE } { { THRU } }
~~~ ~~~~
[ TRACK-AREA IS { identifier-10 | literal-10 } CHARACTERS ]
~~~~~~~~~~
[ TRACK-LIMIT IS { integer-1 } TRACKS ]
~~~~~~~~~~~ ~~~~~
Where device-1 is:
{ CARD-PUNCH | CARD-READER }
{ ~~~~~~~~~~ ~~~~~~~~~~~ }
{ DISC | DISK }
{ ~~~~ ~~~~ }
{ INPUT | INPUT-OUTPUT }
{ ~~~~~ ~~~~~~~~~~~~ }
{ DISPLAY }
{ ~~~~~~~ }
{ MAGNETIC-TAPE | CASSETTE }
{ ~~~~~~~~~~~~~ ~~~~~~~~ }
{ KEYBOARD }
{ ~~~~~~~~ }
{ OUTPUT }
{ ~~~~~~ }
{ PRINT | PRINTER | PRINTER-1 }
{ ~~~~~ ~~~~~~~ ~~~~~~~~~ }
{ RANDOM }
{ ~~~~~~ }
{ LINE ADVANCING FILE }
{ ~~~~ ~~~~~~~~~ }
{ TAPE }
~~~~
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.
The reserved words
AREAS,IS,MODE,OTHER,SEQUENCE,TO,USINGandWITHare optional and may be omitted. The presence or absence of these words has no effect upon the program.After <file-name-1>, the various clauses may be coded in any sequence.
A period must follow the last coded clause.
The
OPTIONALclause, 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 toOPENanOPTIONALfile 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 toREADthat file will return anAT END(end-of-file) condition. Optionally, files may be designated asNOT OPTIONAL, if desired. This is useful when specifying the compiler’s-foptional-fileswitch, which automatically makes all filesOPTIONALexcept for those explicitly declared asNOT OPTIONAL.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 (see User-Defined Words).
The optional
ASSIGNclause 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:There are three components to the
ASSIGNclause:Type-
EXTERNAL,DYNAMICor neither Device-
the list of device choices
Locator-
shown as a choice between <identifier-1>, <word-1> and <literal-1>.
ASSIGN TO DISC file-name-1will be assumed if there is noASSIGNclause on aSELECT.If an
ASSIGNclause is coded without a <Device>, the deviceDISCwill be assumed.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:
If <literal-1> is coded, the value of the literal will serve as the File Location String that will identify the data file.
If <identifier-1> is coded, the value of the identifier will serve as the File Location String that will identify the data file.
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> ofEXTERNALwas not specified, the compiler will create aPIC 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.File Location Strings will be discussed shortly.
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:
DISCorDISKwill assume an attachment to a file named <file-name-1> in whatever directory is current at the time the file is opened.DISPLAYwill assume an attachment to theSTDOUTlogical device; these files should only be used for output.KEYBOARDwill assume an attachment to theSTDINlogical device; these files should only be used for input.PRINTERwill assume an attachment to theLPT1logical device/port; these files should only be used for output.RANDOMorTAPEwill behave exactly asDISCdoes. These two additional <Device>s are provided to facilitate the compilation of COBOL source from other COBOL implementations.
The
LINE ADVANCINGdevice 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 theADVANCINGclause of theWRITEstatement (see WRITE).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.
If the compiler configuration file (see Compiler Configuration Files) you used to compile the program with, had a
filename-mappingvalue ofyes, 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:If the compiler configuration file (see Compiler Configuration Files) you used to compile the program specified
mfas theassign-clausevalue, 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 exceptibm.If, on the other hand, the compiler configuration file (see Compiler Configuration Files) you used to compile the program specified
ibmas theassign-clausevalue, 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 formS-xxxorAS-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.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.
If no environment variable was found, or the configuration file (see Compiler Configuration Files) used to compile the program had a
filename-mappingvalue ofNO, then the File Locator String value will serve as the path and filename to the data file.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.
The
FILE STATUSorSORT STATUSclause (they are both equivalent and only one or the other, if any, should be specified) is used to specify the name of a two character alphanumeric 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 two examples lower down.Possible status codes that can be returned to a
FILE STATUSdata item are as follows.FILE STATUScodes are grouped into categories.First position of the code indicates the classification category.
Category:
0x SUCCESSOperation completed successfully.
Action: Continue processing.
Category:
1x AT ENDcondition with unsuccessful completionSequential READ reached end of file or top of file or optional file not present. A sequential READ statement was unsuccessfully executed as a result of an AT END.
Action: Exit READ loop; handle EOF. Use the AT END phrase in the READ statement to enable the program to detect whether an at end condition has occurred.
Category:
2x INVALID KEYcondition with unsuccessful completionThe statement was unsuccessfully executed as a result of an invalid key. Keyed operation failed: duplicate key, key not found, or sequence error. Use the INVALID KEY phrase in the input-output statement to enable the program to detect whether an invalid key condition has occurred.
Action: Check key and logic; handle duplicate or missing record.
Category:
3x PERMANENT ERRORcondition with unsuccessful completionThe statement was unsuccessfully executed as the result of an error that precluded further processing of the file. Any specified exception procedures are executed. The permanent error condition remains in effect for all subsequent input-output operations on the file unless an implementor-defined technique is invoked to correct the permanent error condition. Serious I/O or system error (e.g. disk failure, file not found at OPEN).
Action: Do not retry same op; log and recover or abend.
Category:
4x LOGICAL ERRORcondition with unsuccessful completionThe statement was unsuccessfully executed as a result of an improper sequence of input-output operations that were performed on the file or as a result of violating a limit defined by the user. Programmer or logic error (e.g. wrong OPEN mode, invalid request).
Action: Fix program logic.
Category:
5x RECORD OPERATION CONFLICTwith unsuccessful completionThe input-output statement was unsuccessfully executed as a result of the record being locked by another file connector.
Action: Fix program logic.
Category:
6x FILE SHARING CONFLICTwith unsuccessful completionThe statement was unsuccessfully executed as a result of the file being locked by another file connector.
Action: Fix program logic.
Category:
7x RECORD CONTENT ERRORwith unsuccessful completionThe statement was unsuccessfully executed as a result of the record content not conforming to specified requirements.
Category:
9x IMPLEMENTOR DEFINEDcondition with unsuccessful completionThe statement was unsuccessfully executed as a result of a condition that is specified by the implementor. COBOL runtime or implementer-defined error.
Action: Check documentation; possible bug or environment issue.
GnuCOBOL implements the
FILE STATUScodes defined in the ISO standard:+-------------------------------------------------------------------+ | GnuCOBOL FILE STATUS MAP | +---------------+---------------------------------------------------+ | 1st Byte: | 0 1 2 3 4 5 6 7 8 9 | +---------------+---------------------------------------------------+ | 2nd Byte: 0 | 00 10 30 | | 1 | 21 31 41 51 61 71 91 | | 2 | 02 22 42 52 | | 3 | 23 43 | | 4 | 04 14 24 34 44 | | 5 | 05 35 | | 6 | 06 46 | | 7 | 07 37 47 57 | | 8 | 38 48 | | 9 | 09 39 49 | +---------------+---------------------------------------------------+Complete list of all
FILE STATUScodes, followed by a detailed explanation of each code.+---------------------------------------------------+ | GnuCOBOL FILE STATUS LIST | +------+--------------------------------------------+ | | 0x SUCCESS | | 00 | SUCCESSFUL COMPLETION. NO ERROR. | | 02 | SUCCESS. DUPLICATE KEY. | | 04 | SUCCESS. RECORD LENGTH MISMATCH. | | 05 | SUCCESS. OPTIONAL FILE IS NOT PRESENT. | | 06 | SUCCESS. EOF NOT DETECTED FOR A LS FILE. | | 07 | FILE NOT ON TAPE. | | 09 | BAD CHARACTER ON A LS FILE. | | | 1x AT END | | 10 | END OF FILE. | | 14 | RELATIVE KEY OUT OF RANGE. | | | 2x INVALID KEY | | 21 | INDEX SEQUENCE ERROR. INVALID KEY. | | 22 | KEY ALREADY EXIST. DUPLICATE KEY. | | 23 | KEY NOT FOUND. | | 24 | BOUNDARY VIOLATION (on FILE). | | | 3x PERMANENT ERROR | | 30 | PERMANENT I/O ERROR. | | 31 | INCONSISTENT FILENAME. | | 34 | BOUNDARY VIOLATION (on DISK). | | 35 | FILE NOT FOUND. | | 37 | PERMISSION DENIED. | | 38 | OPEN ON A LOCKED FILE. | | 39 | CONFLICTING FILE ATTRIBUTES. | | | 4x LOGICAL ERROR | | 41 | FILE IS ALREADY OPEN. | | 42 | FILE IS NOT OPEN. | | 43 | READ NOT DONE. | | 44 | BOUNDARY VIOLATION (on RECORD) | | 46 | PRECEDING READ OR START FAILED. | | 47 | FILE NOT OPEN IN INPUT OR I-O MODE. | | 48 | FILE NOT OPEN IN OUTPUT OR I-O MODE. | | 49 | FILE NOT OPEN IN I-O MODE. | | | 5x RECORD OPERATION CONFLICT | | 51 | RECORD LOCKED. | | 52 | END OF PAGE. | | 57 | LINAGE BAD SPECIFICATION. | | | 6x FILE SHARING CONFLICT | | 61 | FILE SHARING FAILURE. | | | 7x RECORD CONTENT ERROR | | 71 | BAD CHARACTER ON A LINE SEQ.FILE. | | | 9x IMPLEMENTOR DEFINED | | 91 | FEATURE NOT AVAILABLE. | +------+--------------------------------------------+Code:
00 SUCCESSFUL COMPLETION. NO ERROR.Statements:
ALLMeaning: the statement was successfully executed and no further information is available concerning the input-output operation.
Code:
02 SUCCESS. DUPLICATE KEY.Statements:
READ, WRITE, REWRITEMeaning: This file status value applies only to INDEXED files with alternate keys that allow duplicates.
The statement was successfully executed but a duplicate key is detected:
a. For a READ statement with the NEXT phrase specified or implied, the key value for the current key of reference is equal to the value of the same key in the next record in the file.
b. For a READ statement with the PREVIOUS phrase specified, the key value for the current key of reference is equal to the value of the same key in the prior record in the file.
c. For a WRITE or a REWRITE statement, the record just written created a duplicate key value for at least one alternate record key for which duplicates are allowed.
Code:
04 SUCCESS. RECORD LENGTH MISMATCH.Statements:
READMeaning: A READ statement is successfully executed but the record from the file is shorter than the minimum length or longer than the maximum length of records allowed for that file. The size of the record just read does not agree with the size specified in the program FD File Description. The record is truncated or padded with spaces/zeros.
Code:
05 SUCCESS. OPTIONAL FILE IS NOT PRESENT.Statements:
OPEN, DELETE FILEMeaning: this condition exists because:
a. One of the following status occurred where the OPTIONAL clause in the SELECT statement is specified.
- The OPEN INPUT, OPEN I-O, or OPEN EXTEND was executed for a file, but the file has yet to be created.
- The OPEN INPUT was executed for a nonexistent file. In this case, the file is not created and AT END condition occurs
FILE STATUS 10during execution of the first READ statement.- The OPEN I-O or OPEN EXTEND was executed for a nonexistent file. In this case, the file is created.
b. For a DELETE FILE statement, the referenced file is not present, the execution of the statement is successful and the FILE STATUS is set to ‘05’.
Code:
06 SUCCESS. EOF NOT DETECTED FOR A LINE SEQ.FILE.Statements:
READMeaning: also named: Multiple record on Line Sequential file. A READ statement for a line sequential file has successfully executed but a line/record delimiter or the end-of-file has not been detected.
Code:
07 FILE NOT ON TAPE.Statements:
OPEN, CLOSEMeaning: you are using one of "tape" clauses: OPEN WITH NO REWIND o REVERSED, CLOSE WITH NO REWIND, CLOSE REEL/UNIT, CLOSE FOR REMOVAL but the file is not on tape. Note GnuCOBOL accepts tape clauses but does not support them.
Code:
09 BAD CHARACTER ON A LINE SEQ.FILE.Statements:
READMeaning: a READ statement for a LS LINE SEQUENTIAL file has successfully executed but the record contains one or more characters that are not in the implementor-defined character set for a LINE SEQUENTIAL file. You can disable this check for READ (and WRITE) at runtime by setting the variable:
COB_LS_VALIDATE=FALSEorCOB_LS_NULLS=TRUE. See alsoFILE STATUS 71.Code:
10 END OF FILE.Statements
READMeaning: a sequential READ statement is attempted and no next or prior record exists in the file because:
a. NEXT was specified or implied and the end of the file has been reached
b. PREVIOUS was specified and the beginning of the file has been reached
c. The first READ statement was executed for a non-existent optional input file. That is, a file with the OPTIONAL clause specified was opened in INPUT mode but the file was not created.
Code:
14 RELATIVE KEY OUT OF RANGE.Statements:
READMeaning: a sequential READ statement is attempted for a relative file and the number of digits in the relative record number (the key) is larger than the size of the relative key data item described for the file.
Code:
21 INDEX SEQUENCE ERROR. INVALID KEY.Statements:
DELETE, WRITE, REWRITEMeaning: this condition exists because:
a. A sequence error exists for a sequentially accessed indexed file or relative file.
b. The record key value has been changed between the successful execution of a READ statement and the execution of the next REWRITE statement for that file.
c. The ascending sequence requirements for successive record key values are violated.
Code:
22 KEY ALREADY EXIST. DUPLICATE KEY.Statements:
WRITE, REWRITEMeaning: this condition exists because an attempt is made either:
a. To WRITE a record that would create a duplicate key in a RELATIVE file.
b. To WRITE a record that would create a duplicate prime record key in an INDEXED file,
c. To WRITE or REWRITE a record that would create a duplicate alternate record key when the WITH DUPLICATES phrase is not specified for that alternate record key in an INDEXED file.
Code:
23 KEY NOT FOUND.Statements:
READ, DELETE, WRITE, REWRITE, STARTMeaning: this condition exists because an attempt is made :
a. To randomly access a key that does not exist in the file;
b. To execute a START or random READ statement on a file described as optional and the file is not present;
Code:
24 BOUNDARY VIOLATION (on FILE).Statements:
WRITE, REWRITE, SORT GIVING, MERGE GIVINGMeaning: this condition is for RELATIVE and INDEXED files only and exists because:
a. An attempt is made to WRITE outside the boundaries of a relative or INDEXED file. The implementor specifies the manner in which these boundaries are defined.
b. A sequential WRITE statement is attempted for a RELATIVE file and the number of significant digits in the relative record number is larger than the size of the relative key data item described for the file.
c. The disk is full (for Relative and Indexed files).
Code:
30 PERMANENT I/O ERROR.Statements:
ALLMeaning: a permanent error exists and no further information is available concerning the input-output operation. Generic file system error or severely corrupted file.
Action: check the operating system logs or folder permissions.
Code:
31 INCONSISTENT FILENAME.Statements:
OPENMeaning: this error indicates a discrepancy between the logical file definition in your GnuCOBOL code and the actual file on the disk. This error typically occurs for the following reasons:
a. Mismatched File Organization: The file already exists but was created with a different organization (for example, it is a SEQUENTIAL file, but your current program declares it as ORGANIZATION IS INDEXED).
b. Incompatible Record Format or Lengths: The record length or the key structure defined in your program’s FD (File Description) does not match the actual structure of the file stored on the system.
c. Incorrect Environment Variable Assignment: The file name mapped via the ASSIGN clause (or through environment variables like
DD_orCOB_FILE_PATH) points to an invalid object or the wrong file type.Code:
34 BOUNDARY VIOLATION (on DISK).Statements:
WRITE, REWRITE, SORT GIVING, MERGE GIVING, CLOSEMeaning: this condition is only for SEQUENTIAL and LINE SEQUENTIAL. This error typically occurs for an area shortage occurred during statement execution and the following reasons:
a. File Size Limit Exceeded: The file has reached the maximum size allowed by the operating system or the specific file system (for example, file size limits on FAT32).
b. User Quota Limits: The user account executing the program has exceeded its assigned disk space quota on the system.
c. The disk is full (for SEQUENTIAL and LINE SEQUENTIAL files). The hard drive, partition, or network drive where the program is trying to write has run out of free space.
Code:
35 FILE NOT FOUND.Statements:
OPEN, SORTMeaning: an OPEN statement with the INPUT, I-O, or EXTEND phrase is attempted on a file that is not described as optional and the file is not present. The path specified for the OPEN does not exist, or the filename is incorrect.
Action: check the associated variable or the literal name in the ASSIGN clause. If the file might not exist initially, use OPEN OPTIONAL.
Code
37 PERMISSION DENIED.Statements:
OPEN, SORT, DELETE FILEMeaning: an OPEN statement has been attempted on a file which does not support the open mode specified in the OPEN statement. A permanent error exists because of one of the following reasons:
a. for an OPEN statement:
- the EXTEND or OUTPUT phrase is specified but the file will not support WRITE operations.
- the I-O phrase is specified but the file will not support the input and output operations that are permitted for the organization of that file when opened in the I-O
- the INPUT phrase is specified but the file will not support READ operations.
b. an OPEN statement or DELETE FILE statement is attempted on a file and insufficient authority exists to access the file. The ability to detect this is processor dependent. Open or DELETE FILE permissions denied. Attempted on a protected or read-only file (as determined by the operating system) for writing.
Code:
38 OPEN ON A LOCKED FILE.Statements:
OPENMeaning: an OPEN statement has been tried for a file for which CLOSE WITH LOCK was executed before.
Code:
39 CONFLICTING FILE ATTRIBUTES.Statements:
OPEN, DELETE FILEMeaning: the OPEN or DELETE FILE statement is unsuccessful because a conflict has been detected between the file attributes and the attributes specified for that file in the source unit.
Discrepancy between the definition in the code (Organization SEQUENTIAL, RELATIVE, or INDEXED), the prime record key, the alternate record keys, the code set, the maximum record size, the record type (fixed or variable), and the blocking factor. and the actual file structure on disk. Regenerate the file with the correct structure, or update the ORGANIZATION IS and RECORD CONTAINS clauses in the COBOL source.
Code:
41 FILE IS ALREADY OPENED.Statements:
OPEN, DELETE FILEMeaning: an OPEN statement or a DELETE FILE statement has been tried for a file which is already open.
Code:
42 FILE IS NOT OPEN.Statements:
CLOSE, UNLOCKMeaning: A CLOSE or UNLOCK statement hase been tried for a file which is already closed or never opened.
Code:
43 READ NOT DONE.Statements:
DELETE, REWRITEMeaning: for a sequential accessed file only, the last input-output statement executed for the file through prior to the execution of a DELETE RECORD or REWRITE statement through the same file connector was not a successfully executed READ statement.
Action: issue a successful READ before invoking a REWRITE or DELETE on the same record.
Code:
44 BOUNDARY VIOLATION (on RECORD) / RECORD SIZE MISMATCH.Statements:
WRITE, REWRITEMeaning: an attempt was made to REWRITE a record to a file and the record was not the same size as the record being replaced. Or an attempt was made to WRITE or REWRITE a record that was larger than the largest or smaller than the smallest record allowed by the RECORD IS VARYING clause of the associated file.
Code:
46 PRECEDING READ OR START FAILED.Statements:
READMeaning: a sequential READ is attempted on a file open in the INPUT or I-O mode and no valid next record had been established because:
- The preceding READ or START statement was unsuccessful but did not cause an AT END condition.
- The preceding READ statement caused an AT END condition.
Code:
47 FILE NOT OPENED IN INPUT OR I-O MODE.Statements:
READ, STARTMeaning: the execution of a READ or START statement was attempted on a file not OPEN in INPUT or I-O mode.
Code:
48 FILE NOT OPENED IN OUTPUT OR I-O MODE.Statements:
WRITEMeaning: The execution of a WRITE statement was attempted on a file not open in the I-O, OUTPUT, or EXTEND mode.
Code:
49 FILE NOT OPENED IN I-O MODE.Statements:
DELETE, REWRITEMeaning: the execution of a DELETE or REWRITE statement was attempted on a file not open in the I-O mode.
Code:
51 RECORD LOCKED.Statements:
READMeaning: the statement is unsuccessful due to an attempt to access a record that is currently locked by another process.
Code:
52 END OF PAGE.Statements:
WRITEMeaning: a WRITE operation on a "print file" failed after End-Of-Page.
Code:
57 LINAGE BAD SPECIFICATION.Statements:
OPENMeaning: an OPEN operation failed because the LINAGE description was incorrect.
Code:
61 FILE SHARING FAILURE.Statements:
OPENMeaning: a file sharing conflict condition exists because an OPEN statement is attempted on a file and that file is already open by another process in a manner that conflicts with this request. The possible violations are as follows.
An attempt is made to OPEN a file:
a. that is currently open by another process in the
SHARING WITH NO OTHERmode.b. in the
SHARING WITH NO OTHERmode and the file is currently open by another process.c. for I-O or EXTEND and the file is currently open by another process in the
SHARING WITH READ ONLYmode.d. in the
SHARING WITH READ ONLYmode and the file is currently open by another process in the I-O or EXTEND mode.e. in the OUTPUT mode and the file is currently open by another process.
f. that has currently been locked by another process.
Code:
71 BAD CHARACTER ON A LINE SEQ.FILE.Statements:
WRITE, REWRITEMeaning: an attempt was made to WRITE or REWRITE a record to a LS LINE SEQUENTIAL file and the record area contains one or more characters not in the implementor-defined character set for the file. The WRITE or REWRITE operation was unsuccessful and the record area remains unchanged. You can disable this check for WRITE or REWRITE (and READ) at runtime by setting the variable:
COB_LS_VALIDATE=FALSEorCOB_LS_NULLS=TRUE. See alsoFILE STATUS 09.Code:
91 FEATURE NOT AVAILABLE.Statements:
OPEN, CLOSE, REWRITE, DELETEMeaning: for OPEN and CLOSE: means that the File I-O backend is not available (before 4.x his mostly means a GnuCOBOL compile-time configuration without-db, afterwards it could also mean that the shared object for the backend configured at runtime for the specific file cannot be loaded).
For REWRITE and for DELETE: means that File I-O statement isn’t supported for the file’s organization. This can happen if you run a statement that isn’t supported by the runtime but not caught by the compiler (previously REWRITE to LINE SEQUENTIAL, for example, which was only supported later; or DELETE on any SEQUENTIAL file (soon to be caught in 3.x also for RECORD SEQUENTIAL) or "more common" if an EXTFH call does this.
Note:
1. The value of the
FILE STATUScode is made available also through other ways.More info at the intrinsic function
EXCEPTION-STATUS(see EXCEPTION-STATUS) and its equivalentACCEPT FROM EXCEPTION STATUS(see ACCEPT FROM Runtime-Info).Other more info at the intrinsic function
EXCEPTION-FILE(see EXCEPTION-FILE) and at the intrinsic functionEXCEPTION-FILE-N(see EXCEPTION-FILE-N).2.
FILE STATUScategories are connected to some Exception names and Exception Conditions (Appendix F Exceptions)level EC-I-O 2 Input-output exception EC-I-O-WARNING NF 3 File status "0x" where x is nonzero EC-I-O-AT-END NF 3 File status "1x" EC-I-O-INVALID-KEY NF 3 File status "2x" EC-I-O-PERMANENT-ERROR Fatal 3 File status "3x" EC-I-O-LOGIC-ERROR Fatal 3 File status "4x" EC-I-O-RECORD-OPERATION NF 3 File status "5x" EC-I-O-FILE-SHARING NF 3 File status "6x" EC-I-O-RECORD-CONTENT Fatal 3 File status "7x" EC-I-O-IMP Imp 3 File status "9x"3. The
FILE STATUScode also determines whether theUSE AFTER STANDARD EXCEPTIONprocedure, intoDECLARATIVESsection (see DECLARATIVES), associated with that file is executed.If the
USE AFTER STANDARD EXCEPTIONprocedure associated with the file exists and theFILE STATUSis other than "succeed", the procedure is executed.Suggest that you copy this content to say
FILESTAT-MSGS.cpyand save in your copy book folder.*> **************************************************************** *> ** This copybook defines an EVALUATE statement capable of ** *> ** translating two-characters FILE-STATUS codes to a message. ** *> **************************************************************** EVALUATE F-STATUS WHEN 00 MOVE 'SUCCESSFUL COMPLETION. NO ERROR. ' TO MSG WHEN 02 MOVE 'SUCCESS. DUPLICATE KEY. ' TO MSG WHEN 04 MOVE 'SUCCESS. RECORD LENGTH MISMATCH. ' TO MSG WHEN 05 MOVE 'SUCCESS. OPTIONAL FILE IS NOT PRESENT. ' TO MSG WHEN 06 MOVE 'SUCCESS. EOF NOT DETECTED FOR A LS FILE.' TO MSG WHEN 07 MOVE 'FILE NOT ON TAPE. ' TO MSG WHEN 09 MOVE 'BAD CHARACTER ON A LS FILE. ' TO MSG WHEN 10 MOVE 'END OF FILE. ' TO MSG WHEN 14 MOVE 'RELATIVE KEY OUT OF RANGE. ' TO MSG WHEN 21 MOVE 'INDEX SEQUENCE ERROR. INVALID KEY. ' TO MSG WHEN 22 MOVE 'KEY ALREADY EXIST. DUPLICATE KEY. ' TO MSG WHEN 23 MOVE 'KEY NOT FOUND. ' TO MSG WHEN 24 MOVE 'BOUNDARY VIOLATION (on FILE). ' TO MSG WHEN 30 MOVE 'PERMANENT I/O ERROR. ' TO MSG WHEN 31 MOVE 'INCONSISTENT FILENAME. ' TO MSG WHEN 34 MOVE 'BOUNDARY VIOLATION (on DISK). ' TO MSG WHEN 35 MOVE 'FILE NOT FOUND. ' TO MSG WHEN 37 MOVE 'PERMISSION DENIED. ' TO MSG WHEN 38 MOVE 'OPEN ON A LOCKED FILE. ' TO MSG WHEN 39 MOVE 'CONFLICTING FILE ATTRIBUTES. ' TO MSG WHEN 41 MOVE 'FILE IS ALREADY OPEN. ' TO MSG WHEN 42 MOVE 'FILE IS NOT OPEN. ' TO MSG WHEN 43 MOVE 'READ NOT DONE. ' TO MSG WHEN 44 MOVE 'BOUNDARY VIOLATION (on RECORD) ' TO MSG WHEN 46 MOVE 'PRECEDING READ OR START FAILED. ' TO MSG WHEN 47 MOVE 'FILE NOT OPEN IN INPUT OR I-O MODE. ' TO MSG WHEN 48 MOVE 'FILE NOT OPEN IN OUTPUT OR I-O MODE. ' TO MSG WHEN 49 MOVE 'FILE NOT OPEN IN I-O MODE. ' TO MSG WHEN 51 MOVE 'RECORD LOCKED. ' TO MSG WHEN 52 MOVE 'END OF PAGE. ' TO MSG WHEN 57 MOVE 'LINAGE BAD SPECIFICATION. ' TO MSG WHEN 61 MOVE 'FILE SHARING FAILURE. ' TO MSG WHEN 71 MOVE 'BAD CHARACTER ON A LINE SEQ.FILE. ' TO MSG WHEN 91 MOVE 'FEATURE NOT AVAILABLE. ' TO MSG WHEN OTHER MOVE 'UNKNOWN FILE STATUS CODE. ' TO MSG END-EVALUATE.One sample code defining and using this copy book in a free format program source.
In Working-Storage section : 01 WS-Work-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 F-STATUS by fs-reply. Eval-Msg-Exit. exit section.And another from the pen of Vincent Coen:
In Working-Storage Section: *> Display Screen Positioning 03 WS-Env-Columns pic 999 value zero. 03 ws-Env-Lines pic 999 value zero. 03 ws-Lines pic 9(4) comp value zero. 03 ws-21-Lines pic 9(4) comp value zero. 03 ws-22-Lines pic 9(4) comp value zero. 03 ws-23-Lines pic 9(4) comp value zero. At start of program Procedure Division : AA010-Get-Screen-Attr. *> Set up for screen size accept WS-Env-Columns from Columns. accept WS-Env-Lines from lines. move WS-Env-Lines to WS-Lines. subtract 1 from ws-lines giving ws-23-lines. subtract 2 from ws-lines giving ws-22-lines. subtract 3 from ws-lines giving ws-21-lines. Near the bottom of code : ZZA-File-Status section. *> File Status Checking Routines using standard Cobol file status values only. move "Unknown" to WS-Sys-Message. evaluate s1 when "0" go to ZZA999-exit when "1" go to zza999-exit when "2" perform zza020-Check-Inv-Key-Status when "3" perform zza030-Check-Perm-Err-Status when "4" perform zza040-Look-Up-Error when "5" perform zza050-Look-Up-Error when "6" perform zza060-Look-Up-Error when "7" perform zza070-Look-Up-Error when "9" perform zza090-Look-Up-Error end-evaluate. move "Unknown error status" to WS-Sys-Message. go to zza998-Display-Message. *> Do not stop/accept as in batch mode Use zz997 instead to stop after a error msg. zza020-Check-Inv-Key-Status. evaluate s2 when "1" move "INDEX SEQUENCE ERROR. INVALID KEY. " to WS-Sys-Message when "2" move "KEY ALREADY EXIST. DUPLICATE KEY. " to WS-Sys-Message when "3" move "KEY NOT FOUND. " to WS-Sys-Message when "4" move "BOUNDARY VIOLATION (on FILE). " to WS-Sys-Message end-evaluate. zza030-Check-Perm-Err-Status. evaluate s2INCONSISTENT FILENAME. when "0" move "PERMANENT I/O ERROR. " to WS-Sys-Message when "1" move "INCONSISTENT FILENAME. " to WS-Sys-Message when "4" move "BOUNDARY VIOLATION (on DISK). " to WS-Sys-Message when "5" move "FILE NOT FOUND. " to WS-Sys-Message when "7" move "PERMISSION DENIED. " to WS-Sys-Message when "8" move "OPEN ON A LOCKED FILE. " to WS-Sys-Message when "9" move "CONFLICTING FILE ATTRIBUTES. " to WS-Sys-Message end-evaluate. zza040-Look-Up-Error. evaluate s2 when "1" move "FILE IS ALREADY OPEN. " to WS-Sys-Message when "2" move "FILE IS NOT OPEN. " to WS-Sys-Message when "3" move "READ NOT DONE. " to WS-Sys-Message when "4" move "BOUNDARY VIOLATION (on RECORD) " to WS-Sys-Message when "6" move "PRECEDING READ OR START FAILED. " to WS-Sys-Message when "7" move "FILE NOT OPEN IN INPUT OR I-O MODE. " to WS-Sys-Message when "8" move "FILE NOT OPEN IN OUTPUT OR I-O MODE." to WS-Sys-Message when "9" move "FILE NOT OPEN IN I-O MODE. " to WS-Sys-Message end-evaluate. zza050-Look-Up-Error. evaluate s2 when "1" move "RECORD LOCKED. " to WS-Sys-Message when "2" move "END OF PAGE. " to WS-Sys-Message when "7" move "LINAGE BAD SPECIFICATION. " to WS-Sys-Message end-evaluate. zza060-Look-Up-Error. evaluate s2 when "1" move "FILE SHARING FAILURE. " to WS-Sys-Message end-evaluate. zza070-Look-Up-Error. evaluate s2 when "1" move "BAD CHARACTER ON A LINE SEQ.FILE. " to WS-Sys-Message end-evaluate. zza090-Look-Up-Error. evaluate s2 when "1" move "FEATURE NOT AVAILABLE. " to WS-Sys-Message end-evaluate. zza997-Display-Message. if WS-Sys-Message not = spaces display WS-Sys-Message at line ws-23-Lines col 41 with foreground-color COB-COLOR-RED display "EL006 Press return to continue" at line ws-Lines col 01 accept Accept-Reply at line ws-Lines col 32 display space at line ws-23-Lines col 01 with erase eos. go to zza999-Exit. zza998-Display-Message. if WS-Sys-Message not = spaces display WS-Sys-Message at line ws-23-Lines col 41 with foreground-color COB-COLOR-RED. zza999-exit. exit section.The
SHARINGclause 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. See File Sharing, for the details.The
LOCKclause defines how concurrent access to the file will be managed on a record-by-record basis. See Record Locking, for the details.For syntax details for the
ORGANIZATIONclause, see next group of paragraphs.A
SELECTstatement without anORGANIZATIONexplicitly coded will be handled as if the following ORGANIZATION clause had been specified:ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL
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.
The reserved words
BINARY,IS,MODEandRECORDare optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved words
ORGANIZATIONandORGANISATIONare interchangeable.The phrase
ORGANIZATION IS(and its internationalized alternative,ORGANISATION IS) is optional to provide compatibility with those (few) COBOL implementations that considerORGANIZATIONto be optional. Most COBOL implementations do require the wordORGANIZATION, so it should be used in new programs.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 SEQUENTIALinstead).These files may contain either
USAGE DISPLAYorUSAGE COMPUTATIONAL(of any variety) data since no binary data sequence can be accidentally interpreted as an end-of-record delimiter.While records in a
ORGANIZATION SEQUENTIALfile 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 theFILE SECTION.The
ACCESS MODE SEQUENTIALclause 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.Sequential files are processed using the following statements:
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.
The reserved words
CHARACTER,ISandMODEare optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved words
ORGANIZATIONandORGANISATIONare interchangeable.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 wordORGANIZATION, so it should be used in new programs.This is the only
ORGANIZATIONvalid for files that are assigned to thePRINTERdevice.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 COMPUTATIONALorBINARY(of any variety) data since such fields could accidentally contain byte sequences that could be interpreted as an end-of-record delimiter.Both fixed- and variable-length record formats are supported.
The end-of-record delimiter sequence will be
X‘0A’(an ASCII line-feed character) or aX‘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.When reading a
LINE SEQUENTIALfile, records in excess of the size implied by the file’s description in theFILE SECTIONwill be truncated while records shorter than that size will be padded to the right withSPACES.The
ACCESS MODE SEQUENTIALclause 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.Files assigned to
PRINTERorCONSOLEshould be specified asORGANIZATION LINE SEQUENTIAL.Line Sequential files are processed using the following statements:
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.
The reserved words
IS,KEYandMODEare optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved words
ORGANIZATIONandORGANISATIONare interchangeable.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 wordORGANIZATION, so it should be used in new programs.ORGANIZATION RELATIVEfiles cannot be assigned to theCONSOLE,DISPLAY,LINE ADVANCINGorPRINTERdevices.The
RELATIVE KEYclause is optional only ifACCESS MODE SEQUENTIALis specified.While an
ORGANIZATION RELATIVEfile 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 theFILE SECTION.ACCESS MODE SEQUENTIAL, the defaultACCESS MODEif 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.ACCESS MODE RANDOMmeans that records will be processed in random sequence by specifying their record number in the file every time the file is read or written.ACCESS MODE DYNAMICindicates the program may switch back and forth betweenSEQUENTIALandRANDOMmode during execution. The file starts out initially inSEQUENTIALmode when first opened but the program may use theSTARTstatement (see START) to switch between sequential and random access.The
RELATIVE KEYdata 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 inSEQUENTIALaccess mode and to serve as a key that specifies the relative record number to be read or written when processing a relative file inRANDOMaccess mode.Relative files are processed using the following statements:
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 { = } {data-name-2}... }
{SOURCE IS}
~~~~~~
[ WITH [ NO ] DUPLICATES ]
~~ ~~~~~~~~~~
[ ALTERNATE RECORD KEY IS { data-name-3 } ]...
~~~~~~~~~ ~~~~~~ { record-key-name-2 { = } {data-name-4}...}
{SOURCE IS}
~~~~~~
[ WITH [ NO ] DUPLICATES ]
~~ ~~~~~~~~~~
[ SUPPRESS WHEN ALL literal-1 ]
~~~~~~~~ ~~~~ ~~~
[ 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!
The reserved words
IS,KEYandMODEare optional and may be omitted. The presence or absence of these words has no effect upon the program.The reserved words
ORGANIZATIONandORGANISATIONare interchangeable.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 wordORGANIZATION, so it should be used in new programs.ORGANIZATION INDEXEDfiles cannot be assigned toCONSOLE,DISPLAY,KEYBOARD,LINE ADVANCINGorPRINTER.ACCESS MODE SEQUENTIAL, the defaultACCESS MODEif none is specified, indicates that the records of the file will be processed in a sequential manner with respect to the values of theRECORD KEYor theALTERNATE RECORD KEYmost-recently referenced on aSTARTstatement (see START).ACCESS MODE RANDOMmeans that records will be processed in random sequence by accessing the record with specific record key or alternate record key values.ACCESS MODE DYNAMICallows the file will be processed either inRANDOMorSEQUENTIALmode; the program may switch between the two modes as needed. TheSTARTstatement is used to make the switch between modes.The
RECORD KEYclause 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 samePRIMARY KEYfield value. TheSOURCE ISclause is for use withSplit Keys.The
ALTERNATE RECORD KEYclause, 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.There may be multiple
ALTERNATE RECORD KEYclauses, each defining an additional alternate key for the file.Usage of the
SUPPRESS WHENclause is used whenSparse Keysare required which may take the form for a literal or spaces or zeroes.Indexed files are processed using the following statements:
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 SORT clauses 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.
The reserved words
AREAandFORare optional and may be omitted. The presence or absence of these words has no effect upon the program.This statement must be terminated with a period.
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.
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.
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.
=======================================================================