PreviousData Division - Screen Section Procedure Division - Intrinsic FunctionsNext

Chapter 10: Procedure Division

10.1 Procedure Division

The Procedure Division is optional in a COBOL source program. In a program definition it contains procedures to be executed in the object program. These procedures can be declarative and/or nondeclarative. In a call prototype it contains no procedures, neither declarative nor nondeclarative, except that it may contain the ENTRY statement.

Declarative sections must be grouped at the beginning of the Procedure Division, as shown in General Format 1 below:

General Formats

Format 1

Format 2

Format 3
PROCEDURE DIVISION. 
[ DECLARATIVES. 
{ section-name SECTION. 
               declarative-sentence. 
[ sentence ] … [ paragraph-name. [ sentence ] … ] … } … 
END DECLARATIVES. ] 
[ { method-definition } … ]  

The generic term procedure-division-header is described in the next section, Procedure Division Header.

The declarative sentence shown above is a USE statement (see the section later in this chapter and the chapters Debug Module and Report Writer in your Language Reference - Additional Topics). It specifies when the section is to be executed.

A procedure comprises a paragraph or group of paragraphs, or a section or group of sections in the Procedure Division. If one paragraph is in a section, all must be.

This rule is not enforced.

A paragraph comprises a paragraph-name followed by a period and a space, and any number of sentences. It is terminated either immediately before the next paragraph-name or section-name or at the end of the Procedure Division, or, in the declaratives portion, with END DECLARATIVES.

A section comprises a section header followed by any number of paragraphs. It is terminated either immediately before the next section or at the end of the Procedure Division, or, in the declaratives portion, with END DECLARATIVES.

However, a section in the declaratives need not have a declarative-sentence; it can be invoked by a PERFORM statement. (See the section The PERFORM Statement later in this chapter for details of the PERFORM statement.)

Sentences that are not explicitly contained within a named paragraph as described above are considered to be contained within an unnamed implicit paragraph. Paragraphs that are not explicitly contained within a section are considered to be contained within an implicit, unnamed section.

In a program definition, execution begins with the first statement in the Procedure Division, excluding declaratives. Statements are then executed in the order in which they are written, except where some other order is indicated.

In a call prototype the Procedure Division is never executed.

This segment of the chapter deals with arithmetic and conditional expressions, common and input/output phrases, intrinsic functions and COBOL verbs.

The procedure-division-header is optional in Format 2 of the Procedure Division. However, it is only optional if there are no divisions coded before this and if the Procedure Division begins with a COBOL sentence (not a section header, paragraph header, or Declarative Section).

10.1.1 The PROCEDURE DIVISION Header

The Procedure Division is identified by and must begin with a header in one of the following formats:

General Formats

Format 1

Format 2

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section.

Syntax Rules

Syntax rules marked with an asterisk (*) are common to the Procedure Division header and the ENTRY statement. In these rules, where "Procedure Division header or ENTRY statement" are specified you should read "Procedure Division header" or "ENTRY statement" when applying the rules to the Procedure Division header or the ENTRY statement, respectively.

All Formats
  1. Mnemonic-name is necessary only if the object program is being invoked by another program and that program is using a calling convention other than that used as default by your COBOL system. Typically, the default COBOL calling convention is consistent with that used by a significant implementation of a non-COBOL language for the run-time environment.

    Mnemonic-name must be defined in the SPECIAL-NAMES paragraph. See the section The Special-Names Paragraph earlier in this chapter for details of how to do this and your COBOL system documentation on interfacing for details of which calling conventions are supported in your run time environment.

  2. CHAINING and USING are equivalent.

  3. * The USING phrase is necessary only if the object program, the called program, is being invoked by another program, the calling program, that passes parameters. If the calling program is COBOL, parameters are passed if the called program is invoked by the CALL statement

    or the CHAIN statement

    and that statement includes a USING phrase. If the calling program is not COBOL then see the documentation for that language to determine if parameters are passed.

  4. * The USING phrase of the Procedure Division header

    or ENTRY statement

    identifies the names used by the called program for any parameters passed to it by the calling program. If the calling program is COBOL, the parameters passed to a called program are identified in the USING phrase of the calling program's CALL

    or CHAIN

    statement. The correspondence between the two lists of names is established on a positional basis (see the CALL statement)

    , subject to any variation implied by mnemonic-name specified in the called program's Procedure Division header or the calling program's CALL statement

  5. * An item in the USING phrase can be the name of a data item with USAGE IS POINTER, provided that the corresponding item in the USING phrase of the CALL statement is also either the name of a USAGE IS POINTER data item or an ADDRESS special register.

    An item in the USING phrase can be the name of a data item with USAGE IS PROCEDURE-POINTER provided that the corresponding item in the USING phrase of the CALL statement is also the name of a USAGE IS PROCEDURE-POINTER data item.

Format 1
  1. * Data-name-1 must be defined as a level 01 or a level 77 entry in the Linkage Section

    File Section or Working-Storage Section

    of the called program. A particular user-defined word must not appear more than once as data-name-1.

    It may appear more than once.

    The data description entry for data-name-1 must not contain a REDEFINES clause.

    It may contain a REDEFINES clause.

    Data-name-1 may, however, be the object of a REDEFINES clause elsewhere in the Linkage Section.

  2. * Data-name-2 must be defined as a level 01 or a level 77 entry in the Linkage Section, File Section or Working-Storage Section of the called program.

Format 2
  1. * Format 2 can only be used in a program in which the EXTERNAL clause is specified in the PROGRAM-ID paragraph, that is a call prototype.

  2. * Data-name-1 and data-name-2 must be defined as 01 level records in the LINKAGE SECTION.

  3. * Typedef-name-1, typedef-name-2, and typedef-name-3 must be previously defined in the same source file as a programmer-defined usage by means of a TYPEDEF clause.

General Rules

General rules marked with an asterisk (*) are common to the Procedure Division header and the ENTRY statement. In these rules, where "Procedure Division header or ENTRY statement" are specified you should read "Procedure Division header" or "ENTRY statement" when applying the rules to the Procedure Division header or the ENTRY statement, respectively.

All Formats

  1. * Up to five data-names are permitted in the USING phrase of the Procedure Division header and in the USING phrase of the CALL statement.

    Up to sixty-two data-names are permitted in the USING phrase of the Procedure Division header, the USING phrase of the CALL statement

    and in the USING phrase of the ENTRY statement.

  2. * The BY REFERENCE and BY VALUE phrases are transitive across the parameters that follow them until another BY REFERENCE or BY VALUE phrase is encountered. If no BY REFERENCE or BY VALUE phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.

Format 1
  1. Mnemonic-name identifies the calling convention that this program will assume has been adopted by the calling program that invokes it, whether it is invoked by program-name or by entry-name. If the calling convention actually used is different to that implied by mnemonic-name, then the COBOL system may become corrupt.

  2. * If data-name-1 is defined as a level 01 or a level 77 entry in the File Section or Working-Storage Section then the object program operates as if a data item had been declared in the Linkage Section with the same data declaration as data-name-1 and the contents of that data item were moved to data-name-1 prior to executing the first statement in the called program. In an initial program, these values are overwritten by the initialization of the program's Working-Storage data and are therefore not available to the called program.

  3. * If the calling program is COBOL the following rules apply. If the calling program is not COBOL see your COBOL system documentation on interfacing for details of when you need to use the BY REFERENCE or BY VALUE clauses.

  4. * The sequence of appearance of the operands in the USING phrase of the Procedure Division header

    or ENTRY statement

    in the called program and in the corresponding USING phrase in the CALL statement

    or CHAIN statement or parameter list if the calling program is not COBOL

    in the calling program determines the correspondence between the data-names used by the called and calling programs. This correspondence is positional and not by name equivalence; the first operand in the called program's USING phrase corresponds to the first operand in the calling program's USING phrase or parameter list, the second to the second, etc.

    If the correspondence cannot be completed because the numbers of operands are different, then if the remaining unmatched operands are in the CALL statement they are ignored and if they are in the Procedure Division header or ENTRY statement then they must not be referenced within the called program. The positional correspondence may vary depending on the non-COBOL calling conventions implied by mnemonic-name.

    Any mismatch in the number of the operands specified in the USING phrases of the called and calling programs will only be apparent at run time and so the directive FLAG will not cause this extension to be flagged.

  5. * For each data item in the USING phrase of the Procedure Division header

    or ENTRY statement

    , if the reference to the corresponding data item in the CALL

    or CHAIN

    statement of the calling program declares the parameter to be passed by content or by reference then the BY REFERENCE phrase must be declared or implied in the called program.

    If the reference to the corresponding data item in the CALL statement of the calling program declares the parameter to be passed by value then the BY VALUE phrase must be declared or implied in the called program.

  6. * If the reference to the corresponding data item in the CALL

    or CHAIN

    statement of the calling program declares the parameter to be passed by content, the value of the item is moved when the CALL statement is executed and placed into a COBOL system-defined storage item possessing the attributes described in the general rules of the CALL statement. The object program then operates as if this COBOL system-defined storage item were passed by reference, occupying the same storage area as the corresponding data item in the called program. The data description of each COBOL system-defined data item corresponding to each parameter in the BY CONTENT phrase of the CALL statement must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding parameter in the USING phrase of the Procedure Division header

    or ENTRY statement.

  7. * If the reference to the corresponding data item in the CALL

    or CHAIN

    statement of the calling program declares the parameter to be passed by reference, the object program operates as if the data item in the called program occupies the same storage area as the data item in the calling program. The description of the data item in the called program must describe the same number of character positions as described by the description of the corresponding data item in the calling program.

  8. * If the reference to the corresponding data item in the CALL statement of the calling program declares the parameter to be passed by value, the value of the item is moved when the CALL statement is executed, and placed into a system area possessing the attributes described in the general rules of the CALL statement. The object program then operates as if this system area were passed by reference, occupying the same storage area as the corresponding data item in the called program. The data description of each system area corresponding to each parameter with the BY VALUE phrase of the CALL statement must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding parameter in the USING phrase of the Procedure Division header or ENTRY statement.

  9. * At all times in the called program, references to data-name-1

    and data-name-2

    are resolved in accordance with the description of the item given in the Linkage Section of the called program. If this description defines a greater number of character positions than the corresponding data item in the calling program, unpredictable results can occur. Failure to comply with this rule or exceeding the maximum allowed size of the system area for a particular run time environment may result in the system becoming catastrophically corrupt.

  10. * Data items defined in the Linkage Section of the called program may be referenced within the Procedure Division of that program if, and only if, they satisfy one of the following conditions:

    1. They are operands of the USING phrase of the Procedure Division header

      or ENTRY statement.

    2. They are subordinate to operands of the USING phrase of the Procedure Division header

      or ENTRY statement.

    3. They are defined with a REDEFINES or RENAMES clause, the object of which satisfies the above conditions.

    4. They are items subordinate to any item which satisfies the previous condition.

    5. They are condition-names or index-names associated with data items that satisfy any of the above conditions.

    6. A SET ADDRESS OF statement has been executed with that data item as the receiving item.

  11. * When a program is called and a BY REFERENCE operand in the USING phrase corresponds to a parameter in the calling program, a referential connection is established and endures until control is returned to the calling program. If the program is called a second time, without any intervening cancel of the program, and that same BY REFERENCE operand does not correspond to a parameter in the calling program, then you must not reference that operand unless the STICKY-LINKAGE Compiler directive is specified.

  12. If the USING phrase is specified, the INITIAL clause must not be present in any CD entry. (See the section The Communication Description - The Complete Entry Skeleton in the chapter Communication in your Language Reference - Additional Topics.)

Format 2
  1. * If a call prototype (program with the EXTERNAL clause in the PROGRAM-ID paragraph) contains a format 2 PROCEDURE DIVISION header and another program in the same source file includes a CALL literal statement referencing the program-name of this call prototype, then the following rules apply:

    1. If a call convention is specified in the CALL statement, it must match that specified (implicitly or explicitly) in the prototype. If no call convention is specified in the CALL statement, the call convention specified (implicitly or explicitly) in the prototype is used.

    2. The number of parameters specified in the CALL statement must equal the number of parameters specified in the prototype, except as allowed by the REPEATED phrase.

    3. For each parameter specified in the CALL statement, the following rules apply:

      1. If there is a BY REFERENCE or a BY CONTENT phrase associated with the parameter, the corresponding parameter in the prototype must be specified BY REFERENCE.

      2. If there is a BY VALUE phrase associated with the parameter, the corresponding parameter in the prototype must be specified BY VALUE.

      3. If the parameter in the CALL statement has no BY REFERENCE, BY CONTENT or BY VALUE phrase, the phrase specified (implicitly or explicitly) in the prototype is used.

      4. This rule overrides the rules that apply when no matching call prototype is found. In other words, when no call prototype is used, all parameters up to the first BY phrase are treated as if BY REFERENCE were specified and all parameters after any BY phrase, that do not themselves have an explicit BY phrase, use the last one in effect. However, when a matching call prototype is found, its definitions for the BY phrases take precedence.

      5. If the parameter in the prototype is of class numeric, or it is a pointer or index data-item, then the parameter in the CALL must have the same data definition.

      6. If the parameter in the prototype is of class alphanumeric, the parameter in the CALL must also be of class alphanumeric and be at least as long as the parameter in the prototype.

      7. If ANY is specified in the prototype, the parameter in the CALL statement can be of any class.

    4. If the CALL statement includes the GIVING or RETURNING clause, the prototype must also include the clause, and vice versa. The data definition of the data item specified in the CALL must be the same as that of the data item specified in the prototype.

    5. The DELIMITED BY SIZE phrase in the prototype can be used only for alphanumeric parameters. In this case, the corresponding parameter in the CALL statement is moved to an implicitly allocated data area, and a binary 0 (x"00") character is placed immediately following this copy of the data. If the BY SIZE phrase is omitted, the corresponding parameter in the CALL statement is moved to an implicitly allocated data area, and a binary 0 (x"00") character is placed immediately following the last non-space character in the copy data. The intention is to help in interfacing to languages such as C, which use null terminated text strings.

    6. The REPEATED phrase indicates that there must be at least integer-1 and no more than integer-2 repetitions of the final parameter. If integer-1 TO integer-2 is not specified, integer-1 will be taken as 0 and integer-2 as infinite.

10.1.2 Arithmetic Expressions

An arithmetic expression can be an identifier of a numeric elementary item, a numeric literal, such identifiers and literals separated by arithmetic operators, two arithmetic expressions separated by an arithmetic operator, or an arithmetic expression enclosed in parentheses. Any arithmetic expression can be preceded by a unary operator. The permissible combinations of variables, numeric literals, arithmetic operator and parentheses are given in Table 10-1.

  1. In the following discussion when a numeric data item is referenced, a floating-point data item can also be used.

  2. In the following discussion when a numeric literal is referenced, a floating-point literal can also be used.

    Those identifiers and literals appearing in an arithmetic expression must represent either numeric elementary items or numeric literals on which arithmetic can be performed.

    Table 10-1: Combination Of Symbols In Arithmetic Expressions

    First Symbol Second Symbol
    Variable * / ** + – Unary + – ( )
    Variable P P
    * / ** + – P P P
    Unary + – P P
    ( P P P
    ) P P

    P indicates a permissible pair of symbols
    indicates an invalid pair
    Variable indicates an identifier or literal

10.1.2.1 Arithmetic Operators

Five binary arithmetic operators and two unary arithmetic operators can be used in arithmetic expressions. They are represented by specific characters that must be preceded by a space and followed by a space.

Binary Arithmetic Operators
Meaning
+ Addition
Subtraction
* Multiplication
/ Division
** Exponentiation

Unary Arithmetic Operators
Meaning
+ The effect of multiplication by numeric literal +1
The effect of multiplication by numeric literal -1

10.1.2.2 Formation and Evaluation Rules

  1. Parentheses can be used in arithmetic expressions to specify the order in which elements are to be evaluated. Expressions within parentheses are evaluated first, and within nested parentheses, evaluation proceeds from the least inclusive set to the most inclusive set. When parentheses are not used, or parenthesized expressions are at the same level of inclusiveness, the following hierarchical order of execution is implied:

    1st Unary plus and minus
    2nd Exponentiation
    3rd Multiplication and division
    4th Addition and subtraction

  2. Parentheses are used either to eliminate ambiguities in logic where consecutive operations of the same hierarchical level appear or to modify the normal hierarchical sequence of execution in expressions where it is necessary to have some deviation from the normal precedence. When the sequence of execution is not specified by parentheses, the order of execution of consecutive operations of the same hierarchical level is from left to right.

  3. An arithmetic expression can only begin with the symbol "(", "+", "–", or a variable and can only end with a ")" or a variable. There must be a one-to-one correspondence between left and right parenthesis of an arithmetic expression such that each left parenthesis is to the left of its corresponding right parenthesis.

  4. Arithmetic expressions allow the user to combine arithmetic operations without the restrictions on composite of operands and/or receiving data items. See, for example, Syntax Rule 3 of The ADD Statement in this chapter.

10.1.3 Numeric Expressions

Arithmetic expressions may appear in a number of places in your COBOL program, notably in the COMPUTE, IF and SEARCH verbs, and reference modification.

These expressions are evaluated at run time to give a single numerical result. The operands of a numerical expression may be either numeric constants or numeric variables.

10.1.3.1 Evaluation of Numeric Expressions

Expressions are evaluated using the normal rules of precedence. Thus, in the expression:

 1 + 2 * 3 

the order of evaluation is:

  1. 2 * 3

    yielding an intermediate result of 6

As the expression is evaluated, one or more intermediate results is derived. Conceptually, each intermediate result is stored in a temporary data item, the value of which is determined by the parameter you select in the ARITHMETIC Compiler directive.

The Micro Focus COBOL system can evaluate each intermediate result using up to 18 integer and 18 decimal places. If you select the ARITHMETIC"MF" Compiler directive, intermediate results are not truncated, and thus this maximum accuracy is obtained. In this instance, each intermediate result has a picture of 9(18)V9(18).

The OS/VS COBOL, VS COBOL II, DOS/VS COBOL and COBOL/370 systems compute intermediate results to an accuracy determined by the pictures of the operands in the expressions. The rules, which are slightly different for each version of COBOL, are documented in appendices of the IBM VS COBOL for OS/VS manual and the VS COBOL II Application Programming Guide. Thus, each intermediate result has a picture of 9(n)V9(m). The maximum value of n+m is 30.

If you specify the OSVS or VSC2 options for intermediate results, this COBOL system will emulate the selected mainframe behaviour by truncating its results accordingly, with the following limitations:

10.1.4 Conditional Expressions

Conditional expressions identify conditions that are tested to enable the object program to select between alternate paths of control depending upon the truth value of the condition. Conditional expressions are specified in the

EVALUATE,

IF, PERFORM and SEARCH statements. Two categories of conditions are associated with conditional expressions: simple conditions and complex conditions. Each can be enclosed within any number of paired pare ntheses, in which case its category is not changed.

If the OSVS Compiler directive is set, reference modification cannot be used within a conditional expression.

10.1.4.1 Simple Conditions

The simple conditions are the relation, class, condition-name, switch-status, and sign conditions. A simple condition has a truth value of "true" or "false". The inclusion in parentheses of simple conditions does not change the simple truth value.

10.1.4.2 Relation Condition

A relation condition causes a comparison of two operands, each of which can be the data item referenced by an identifier, a literal or the value resulting from an arithmetic expression. A relation condition has a truth value of "true" if the relation exists between the operands. Comparison of two numeric operands is permitted regardless of the formats specified in their respective USAGE clauses. However, for all other comparisons the operands must have the same usage. If either of the operands is a group item, the nonnumeric comparison rules apply.

A nonnumeric literal can be enclosed in parentheses.

The general format of a relation condition is as follows:

Note that the required relational characters "<" , ">", and "=" are not underlined, to avoid confusion with other symbols such as " “ ".

Note that " = TO", "> THAN" and "< THAN" will be accepted.

The first operand (identifier-1, literal-1 or arithmetic-expression-1) is called the subject of the condition; the second operand (identifier-2 or literal-2 or arithmetic-expression-2) is called the object of the condition. The relation condition must contain at least one reference to a variable.

The relational operator specifies the type of comparison to be made in a relation condition. A space must precede and follow each reserved word comprising the relational operator. When used, "NOT" and the next key word or relation character are one relational operator that defines the comparison to be executed for truth value; for example, "NOT EQUAL" is a truth test for an "unequal" comparison; " NOT GREATER" is a truth test for an "equal" or "less" comparison. The meaning of the relational operators is as shown in Table 10-2.

The following relational operators are equivalent:

IS EQUAL TO and EQUALS;
IS NOT EQUAL TO and IS UNEQUAL TO;
IS GREATER THAN and EXCEEDS;
IS NOT GREATER THAN and IS LESS THAN OR EQUAL TO;
IS NOT LESS THAN and IS GREATER THAN OR EQUAL TO.

Table 10-2: Relational Operators

Comparison of Num eric Operands

For operands whose class is numeric a comparison is made with respect to the algebraic value of the operands. The length of the literal or arithmetic expression operands in terms of number of digits represented, is not significant. Zero is considered a unique value regardless of the sign.

Comparison of these operands is permitted regardless of the manner in which their usage is described. Unsigned numeric operands are considered positive for purposes of comparison.

Numeric edited items are of class alphanumeric, and comparisons involving them follow the rules for comparison of nonnumeric operands, as below.

Comparison of Nonnumeric Operands

For nonnumeric operands, or one numeric and one nonnumeric operand, a comparison is made with respect to a specified collating sequence of characters (see the section The OBJECT-COMPUTER Paragraph earlier in this chapter). If one of the operands is specified as numeric, it must be an integer data item or an integer literal and:

  1. If the nonnumeric operand is an elementary data item or a nonnumeric literal, the numeric operand is treated as though it were moved to an elementary alphanumeric data item of the same size as the numeric data item (in terms of standard data format characters), and the contents of this alphanumeric data item were then compared to the nonnumeric operand. (See the section The MOVE Statement in this chapter and the PICTURE character "P" in the section Symbols Used earlier in this chapter.)

  2. If the nonnumeric operand is a group item, the numeric operand is treated as though it were moved to a group item of the same size as the numeric data item (in terms of standard data format characters), and the contents of this group item were then compared to the nonnumeric operand. (See the section The MOVE Statement in this chapter, and the PICTURE character "P" in the section Symbols Used earlier in this chapter.)

  3. A non-integer numeric operand cannot be compared to a nonnumeric operand.

The size of an operand is the total number of standard data format characters in the operand.

Comparison of a numeric edited data item with figurative constants is allowed and is treated as an alphanumeric comparison.

Numeric and nonnumeric operands can be compared when their usage is not the same. The numeric operand is treated as if it were moved to a USAGE DISPLAY item of the same size (in terms of standard data format characters), and the contents of this were then compared to the nonnumeric operand.

There are two cases to consider:

  1. Operands of equal size - if the operands are of equal size, comparison effectively proceeds by comparing characters in corresponding character positions starting from the high order end and continuing until either a pair of unequal characters is encountered or the low order end of the operand is reached, whichever comes first. The operands are determined to be equal if all pairs of characters compare equally through the last pair, when the low order end is reached.

    The first encountered pair of unequal characters is compared to determine their relative position in the collating sequence. The operand that contains the character that is positioned higher in the collating sequence is considered to be the greater operand.

  2. Operands of unequal size - if the operands are of unequal size, comparison proceeds as though the shorter operand were extended on the right by sufficient spaces to make the operands of equal size.

Comparisons Involving Index-Names and/or Index Data Items

Relation tests can be made only between:

  1. Two index-names. The result is the same as if the corresponding occurrence numbers were compared.

  2. An index-name and a numeric data item or numeric literal. The occurrence number that corresponds to the value of the index-name is compared to the data item or literal.

  3. An index data item and an index-name or another index data item. The actual values are compared without conversion.

  4. An index-name can be compared with an arithmetic expression. The occurrence number that corresponds to the value of the index-name is compared to the computed value of the expression.

  5. The result of the comparison of an index data item with any data item or literal not specified above is undefined.

10.1.4.2.1 Comparisons Involving Data Items with USAGE POINTER

Two items whose USAGE is either implicitly or explicitly POINTER can be compared. Only the relational operators which test for exact equality or inequality are permitted in pointer com parisons.

General Format

Syntax Rules

  1. Identifier-1 and identifier-3 refer to an 01 or 77 level items in the Linkage Section.

  2. 2..Identifier-1 and identifier-3 can refer to any data items defined in the Data Division.

  3. Identifier-2 and identifier-4 refer to items with USAGE IS POINTER.

Only one operand in the comparison can be the figurative constant NULL.

General Rules

  1. The operands are equal if the two addresses are the same, otherwise they are unequal.

  2. This type of relation condition is allowed in IF, PERFORM, EVALUATE and SEARCH (Format 1) statements. It is not allowed in SEARCH (Format 2) statements (SEARCH ALL) because no meaningful ordering can be applied to pointer data items.

10.1.4.2.2 Comparisons Involving Data Items with USAGE PROCEDURE-POINTER

Two items whose USAGE is PROCEDURE-POINTER can be compared.

General Format

Syntax Rules

  1. Identifier-1 and identifier-2 refer to items with USAGE IS PROCEDURE-POINTER.

  2. Only one operand in the comparison can be the figurative constant NULL.

General Rules

  1. The operands are equal if the two addresses are the same, otherwise they are unequal.

  2. This type of relation condition is allowed in IF, PERFORM, EVALUATE and SEARCH (Format 1) statements. It is not allowed in SEARCH (Format 2) statements (SEARCH ALL) because no meaningful ordering can be applied to pointer data items.

10.1.4.2.3 Class Condition

Function

The class condition determines whether the operand is numeric, or alphabetic

or alphabetic-lower, or alphabetic-upper, or contains only the characters in the set of characters specified by the CLASS clause as defined in the SPECIAL-NAMES paragraph of the Environment Division.

General Format

Syntax Rules

  1. The class of an operand is determined as follows:

    1. An operand is numeric if it consists entirely of the characters 0,1, 2, 3, ... , 9, with or without an operational sign.

    2. An operand is alphabetic if it consists entirely of the uppercaseletters A, B, C, ... , Z, space,

      or the lowercase letters a, b, c, ... , z, space,

      or any combination of the uppercase

      and lowercase 

      letters and spaces.

    3. An operand is alphabetic-lower if it consists entirely of the lowercase letters a, b, c, ... , z, and space.

    4. An operand is alphabetic-upper if it consists entirely of the uppercase letters A, B, C, ... , Z, and space.

    5. An operand conforms to class-name-1 if it consists entirely of the characters listed in the definition of class-name-1 in the SPECIAL-NAMES paragraph.

  2. Identifier-1 must reference a data item whose usage is explicitly or implicitly DISPLAY, or in the case of the NUMERIC test, as one of: DISPLAY,

    COMPUTATIONAL, COMPUTATIONAL-X,

    COMPUTATIONAL-3

    COMPUTATIONAL-5

    or PACKED-DECIMAL.

  3. If identifier-1 is a function-identifier, it must reference an alphanumeric function.

General Rules

  1. When the class condition does not include the word NOT and identifier-1 is a zero-length group item, the result of the class test is always false.

    When used, NOT and the next key word specify one class condition that defines the class test to be executed for truth value; e.g. NOT NUMERIC is a truth test for determining that an operand is nonnumeric. When the class condition includes the word NOT and identifier-1 is a zero-length group item, the result of the class test is always true.

    The truth value of a class test involving a zero-length group item is reversed by the ZEROLENGTHFALSE Compiler directive.

  2. The NUMERIC test cannot be used with an item whose data description describes the item as alphabetic or as a group item composed of elementary items whose data description indicates the presence of operational sign(s). If the data description of the item being tested does not indicate the presence of an operational sign, the item being tested is determined to be numeric only if the contents are numeric and an operational sign is not present. If the data description of an elementary item being tested does indicate the presence of an operational sign, the item being tested is determined to be numeric only if the contents are numeric and a valid operational sign is present. Valid operational signs for data items described with the SIGN IS SEPARATE clause are the standard data format characters, "+" and "–"; valid operational signs for data items not described with the SIGN IS SEPARATE clause are described in the section Selection of Character Representation and Radix in the chapter Concepts of the COBOL Language.

    The NUMERIC test can be used with an item defined as a group item composed of elementary items whose data description indicates the presence of operational sign(s).

  3. The ALPHABETIC test cannot be used with an item whose data description describes the item as numeric. The item being tested is determined to be alphabetic only if the contents consist of any combination of the uppercase alphabetic characters "A" through "Z" and the space 

    and any combination of the lowercase alphabetic characters "a" through "z"

    and the space.

    The class condition cannot be used for external floating- point (USAGE DISPLAY) or internal floating-point (USAGE COMP-1 and USAGE COMP-2) items.

  4. The ALPHABETIC-LOWER test cannot be used with an item whose data description describes the item as numeric. The result of the test is true if the content of the data item referenced by identifier-1 consists entirely of the lowercase alphabetic characters "a" through "z" and space.

  5. The ALPHABETIC-UPPER test cannot be used with an item whose data description describes the item as numeric. The result of the test is true if the content of the data item referenced by identifier-1 consists entirely of the uppercase alphabetic characters "A" through "Z" and space.

  6. The class-name-1 test must not be used with an item whose data description describes the item as numeric.
10.1.4.2.4 Condition-Name Condition (Conditional Variable)

Function

In a condition-name condition, a conditional variable is tested to determine whether or not its value is equal to one of the values associated with a condition-name.

General Format

Syntax Rules

  1. Condition-names with DBCS and internal floating-point items are allowed.

  2. Condition-names with external floating-point items are allowed.

General Rules

  1. If the condition-name is associated with a value or range of values, then the conditional variable is tested to determine whether or not its value falls in this range, including the end values.

  2. The rules for comparing a conditional variable with a condition-name value are the same as those specified for relation conditions.

  3. The result of the test is true if one of the values corresponding to the condition-name equals the value of its associated conditional variable.

10.1.4.2.5 Switch-Status Condition

A switch-status condition determines the "on" or "off" status of one of the

nine

COBOL switches

named respectively SWITCH-0 through SWITCH-8.

The value of each of these switches ("on" or "off" ) is set by the operator at the start of execution of the COBOL object program. (See the discussion of run-time switches in your COBOL system documentation for details.) The switch and the "on" or "off" value associated with the condition must be named in the SPECIAL-NAMES paragraph of the Environment Division described earlier in this chapter.

General Format

The result of the test is true if the switch is set to the specified position corresponding to the condition-name.

It is only possible to use the Switch-Status Condition to test if a COBOL switch is set from within the program that set the switch.

10.1.4.2.6 Sign Condition

The sign condition determines whether or not the algebraic value of an arithmetic expression is less than, greater than, or equal to zero. The general format for a sign condition is as follows:

When used, "NOT" and the next keyword specify one sign condition that defines that algebraic test to be executed for truth value; for example, "NOT ZERO" is a truth test for a nonzero ( positive or negative) value. An operand is positive if its value is greater than zero, negative if its value is less than zero, and zero if its value is equal to zero. The arithmetic expression must contain at least one reference to a variable.

ZEROS or ZEROES can be used instead of ZERO in a sign test.

10.1.4.3 Complex Conditions

A complex condition is formed by combining simple conditions, combined conditions and/or complex conditions with logical connectors (logical operators "AND" and "OR" ) or negating these conditions with logical negation (the logical operator "NOT"). The truth value of a complex condition, whether parenthesized or not, is that truth value which results from the interaction of all the stated logical operators on the individual truth values of simple conditions, or the intermediate truth values of conditions logically connected or logically negated.

The logical operators and their meanings are:

Operator
Meaning
AND Logical conjunction; the truth value is "true" if both of the conjoined conditions are true; "false" if one or both of the conjoined conditions is false.
OR Logical inclusive OR; the truth value is "true" if one or both of the included conditions is true; "false" if both included conditions are false.
NOT Logical negation or reversal of truth value; the truth value is "true" if the condition is false; "false" if the condition is true.

The logical operators must be preceded by a space and followed by a space.

10.1.4.3.1 Negated Simple Condition

A simple condition is negated through the use of the logical operator "NOT". The negated simple condition effects the opposite truth value for a simple condition. Thus the truth value of a negated simple condition is "true" if and only if the truth value of the simple condition is "false" ; the truth value of a negated simple condition is "false" if and only if the truth value of the simple condition is "true". The inclusion in parentheses of a negated simple condition does not change the truth value.

General Format

10.1.4.3.2 Combined and Negated Combined Condition

A combined condition results from connecting conditions with one of the logical operators "AND" or "OR".

General Format

Syntax Rules

  1. Condition may be:

  2. Although parentheses need never be used when either "AND" or "OR" (but not both) is used exclusively in a combined condition, parentheses can be used to effect a final truth value when a mixture of "AND", "OR" and "NOT" is used.

General Rules

  1. In the absence of the relevant parenthesis in a complex condition, the precedence (that is, binding power) of the logical operators determines the conditions to which the specified logical operators apply and implies the equivalent parenthesis. The order of precedence is "NOT", "AND" , "OR". Thus, specifying "condition-1 OR NOT condition-2 AND condition-3" implies and is equivalent to specifying "condition-1 OR ((NOT condition-2) AND condition-3)".

  2. Where parentheses are used in a complex condition, precedence is used to determine the binding of conditions to logical operator. Parentheses can, therefore, be used to depart from the normal precedence of logical operators as specified above. Thus, the example complex condition above can be given a different meaning by specifying it as a "(condition-1 OR (NOT condition-2)) AND condition-3". (See the section Condition Evaluation Rules later in this chapter.)

Table 10-3 indicates the ways in which conditions and logical operators can be combined and parenthesized. There must be a one-to-one correspondence between left and right parentheses such that each left parenthesis is to the left of its corresponding right parenthesis.

Table 10-3: Combinations of Conditions, Logical Operators, and Parentheses

Element Permitted location in conditional expression Element can be preceded by only: Element can be followed by only:
simple-condition Any OR, NOT, AND, ( OR, AND, )
OR or AND Not first or last simple-condition, ) simple-condition, NOT, (
NOT Not last OR, AND, ( simple-condition, (
( Not last OR, NOT, AND, ( simple-condition, NOT, (
) Not first simple-condition, ) OR, AND, )

Thus, the element pair "OR NOT" is permissible while the pair "NOT OR" is not permissible; "NOT ( " is permissible while "NOT NOT" is not permissible.

10.1.4.4 Abbreviated Combined Relation Conditions

When simple or negated simple relation conditions are combined with logical connectives in a consecutive sequence such that a succeeding relation condition contains a subject or subject and relational operator that is common with the preceding relation condition, and no parentheses are used within such a consecutive sequence, any relation condition except the first can be abbreviated by:

General Format

Within a sequence of relation conditions both of the above forms of abbreviation can be used. The effect of using such abbreviations is as if the last preceding stated subject were inserted in place of the omitted subject, and the last stated relational operator were inserted in place of the omitted relational operator. The result of such implied insertion must comply with the rules of Table 10-3. This insertion of an omitted subject and/or relational operator terminates once a complete simple condition is encountered within a complex condition.

The order of evaluation of the conditions can be prioritized by the use of parentheses (see example below).

The interpretation applied to the use of the word "NOT" in an abbreviated combined relation condition is as follows:

  1. If NOT is immediately followed by the word GREATER, >, LESS, <, EQUAL, or =, excluding the relational operators GREATER THAN OR EQUAL TO, >=, LESS THAN OR EQUAL TO, and <=, then the word NOT is interpreted as part of the relational operator, otherwise:

  2. The "NOT" is interpreted as a logical operator and, therefore, the implied insertion of subject or relational operator results in a negated relation condition.

Some examples of abbreviated combined and negated combined relation conditions and expanded equivalents follow.

Abbreviated Combined Relation Condition
Expanded Equivalent
a > b AND NOT < c OR d
 
((a > b) AND (a NOT < c)) OR (a NOT < d)
 
a NOT EQUAL b OR c
 
(a NOT EQUAL b) OR (a NOT EQUAL c)
 
NOT a = b OR c
 
(NOT (a = b)) OR (a = c)
 
NOT (a GREATER b OR < c)
 
NOT ((a GREATER b) OR (a < c))
 
NOT (a NOT > b AND c AND NOT d
 
NOT ((((a NOT > b) AND (a NOT > c)) AND (NOT (a NOT > d))))
 
x > a OR y AND z
 
x > a OR (x > y AND x > z)
 
x > a OR (y AND z)
 
x > a OR (x > y AND x > z)
 
x > (a OR y) AND z
 
(x > a OR x > y) AND x > z
 
x ( = a OR > b)
 
x = a OR x > b
 
x = a AND ( > b OR < z )
 
x = a AND ( x > b OR x < z )
 
a EQUAL b OR NOT GREATER OR EQUAL c OR d
 
(a EQUAL b) OR (NOT (a GREATER OR EQUAL c)) OR (a GREATER OR EQUAL d)
 
a EQUAL b OR NOT >=c OR d
 
(a EQUAL b) OR (NOT (a >= c)) OR (a >= d)
 

10.1.4.4.1 Condition Evaluation Rules

Parentheses can be used to specify the order in which individual conditions of complex conditions are to be evaluated when it is necessary to depart from the implied evaluation precedence.

Conditions within parentheses are evaluated first, and, within nested parentheses, evaluation proceeds from the least inclusive condition to the most inclusive condition. When parentheses are not used, or parenthesized conditions are at the same level of inclusiveness, the following hierarchical order of logical evaluation is implied until the final truth value is determined:

  1. Values are established for arithmetic expressions and functions if and when the conditions containing them are evaluated. Similarly, negated conditions are evaluated if and when it is necessary to evaluate the complex condition that they represent. (See Formation And Evaluation Rules in the section Arithmetic Expressions in this chapter.)

  2. Truth values for simple conditions are established in the following order:

    relation (following the expansion of any abbreviated relation condition)
    class
    condition-name
    switch-status
    sign

  3. Truth values for negated conditions are established.

  4. Truth values for combined conditions are established: "AND" logical operators, followed by "OR" logical operators.

  5. Truth values for negated combined conditions are established.

  6. When the sequence of evaluation is not completely specified by parentheses, the order of evaluation of consecutive operations of the same hierarchical level is from left to right.

10.1.5 Common Phrases

In the statement descriptions that follow, several phrases appear frequently: the ROUNDED phrase, the ON SIZE ERROR phrase

the NOT ON SIZE ERROR phrase

and the CORRESPONDING phrase. Each of these phrases is discussed below.

In the following paragraphs, the term "resultant-identifier" refers to that identifier associated with the result of an arithmetic operation.

10.1.5.1 The ROUNDED Phrase

If, after decimal point alignment, the number of places in the fraction of the result of an arithmetic operation is greater than the number of places provided for the fraction of the resultant-identifier, truncation is relative to the size provided for the resultant-identifier. When rounding is requested, the absolute value of the resultant-identifier is increased by one whenever the most significant digit of the excess is greater than or equal to five.

When the low-order integer positions in a resultant-identifier are represented by the character "P" in the PICTURE for the resultant-identifier, rounding or truncation occurs relative to the rightmost integer position for which storage is allocated.

In a floating-point arithmetic operation, the ROUNDED phrase is treated as documentary; the result of a floating-point operation is always rounded.

10.1.5.2 The ON SIZE ERROR Phrase
diala.gifand NOT ON SIZE ERROR Phrase

If, after decimal point alignment, the absolute value of a result of an arithmetic operation exceeds the largest value that can be contained in the associated resultant-identifier, a size error condition exists. Division by zero always causes a size error condition. Note that the results of division by zero when no ON SIZE ERROR phrase is specified, are unpredictable. The size error condition applies only to the final results, except in MULTIPLY and DIVIDE statements, in which case the size error condition applies to the intermediate results as well.

Violation of the rules for the evaluation of exponentiation always terminates the arithmetic operation and always causes a size error condition.

If the ROUNDED phrase is specified, rounding takes place before checking for size error. When such a size error condition occurs, the subsequent action depends on whether or not the SIZE ERROR phrase is specified, as follows:

10.1.5.2.1 ON SIZE ERROR Phrase Not Specified

When a size error condition occurs, the value of those resultant- identifier(s) affected is undefined. Values of resultant-identifier(s) for which no size error condition occurs are unaffected by size errors that occur for other resultant-identifier(s) during execution of this operation.

After completion of the arithmetic operation, control is transferred to the end of the arithmetic statement and the NOT ON SIZE phrase, if specified, is ignored.

Results of division by zero, when no ON SIZE ERROR is specified, are unpredictable. You can avoid this by using the CHECKDIV Compiler directive and O run-time switch.

10.1.5.2.2 ON SIZE ERROR Phrase Specified

When a size error condition occurs, then the values of resultant- identifier(s) affected by the size errors are not altered. Values of resultant-identifier(s) for which no size error condition occurs are unaffected by size errors that occur for other resultant-identifier(s) during execution of this operation. After completion of the execution of this operation, the imperative statement in the SIZE ERROR phrase is executed.

For the ADD statement with the CORRESPONDING phrase and the SUBTRACT statement with the CORRESPONDING phrase, if any of the individual operations produces a size error condition, the imperative statement in the ON SIZE ERROR phrase is not executed until all of the individual additions or subtractions are completed.

If a size error condition occurs, any NOT ON SIZE ERROR phrase is ignored whether or not an ON SIZE ERROR phrase is specified.

When both ON SIZE ERROR and NOT ON SIZE ERROR phrases are specified, and the statement in the phrase that is executed does not contain any explicit transfer of control, then, if necessary, an implicit transfer of control is made after execution of the phrase to the end of the arithmetic statement.

10.1.5.2.3 The NOT ON SIZE ERROR Phrase

If the NOT ON SIZE ERROR phrase is specified for an arithmetic operation statement, and after execution of that statement a size error condition (as defined above) does not exist, then the NOT ON SIZE ERROR phrase is executed. The ON SIZE ERROR phrase, if specified, is ignored, and the imperative statement associated with it is not executed.

10.1.5.3 The CORRESPONDING Phrase

In the text that follows, d1 and d2 must each be identifiers that refer to group items. A pair of data items, one from d1 and one from d2 correspond if the following conditions exist:

  1. A data item in d1 and a data item in d2 are not designated by the key word FILLER and have the same data-name and the same qualifiers up to, but not including, d1 and d2.

  2. At least one of the data items is an elementary data item and the resulting move is legal according to the move rules in the case of a MOVE statement with the CORRESPONDING phrase, and both of the data items are elementary numeric data items in the case of the ADD statement with the CORRESPONDING phrase or the SUBTRACT statement with the CORRESPONDING phrase.

  3. The description of d1 and d2 must not contain level-number 66, 77,

    78

    or 88, the USAGE IS INDEX clause or the>

    USAGE IS OBJECT

    clause.

  4. A data item that is subordinate to d1 or d2 and contains a REDEFINES, RENAMES, OCCURS, USAGE IS INDEX

    , USAGE IS PROCEDURE-POINTER

    , USAGE IS POINTER 

    , or USAGE IS OBJECT

    clause is ignored, as well as those data items subordinate to the data item that contains the REDEFINES, RENAMES, OCCURS, USAGE IS INDEX

    , USAGE IS PROCEDURE-POINTER

    , USAGE IS POINTER

    , or USAGE IS OBJECT

    clause. However, d1 and d2 can have REDEFINES or OCCURS clauses or be subordinate to data items with REDEFINES or OCCURS clauses.

    Neither d1 or d2 can be reference modified.

  5. The name of each data item which satisfies the above conditions must be unique after application of the implied qualifiers.

10.1.5.4 Arithmetic Statements

The arithmetic statements are the ADD, COMPUTE, DIVIDE, MULTIPLY and SUBTRACT statements. Common features are as follows:

  1. The data descriptions of the operands need not be the same; any necessary conversion and decimal point alignment are supplied throughout the calculation.

  2. The maximum size of each operand is 18 decimal digits. The composite of operands, which is a hypothetical data item resulting from the superimposition of specified operands in a statement aligned on their decimal points (see the sections The ADD Statement, The DIVIDE Statement, The MULTIPLY Statement and The SUBTRACT Statement later in this chapter) must not contain more than 18 decimal digits.

10.1.5.5 Overlapping Operands

When a sending and a receiving item in a statement share a part of their storage areas,

yet are not defined by the same data description entry,

the result of the execution of such a statement is undefined.

Overlapping moves are detected at compile time only when the MOVE verb is used and neither operand uses reference modification or subscripting. Forward overlapping moves result in a warning message, if you set the Compiler directive WARNING"3". Any other types result in flagging messages, if you set the Compiler directive FLAG"dialect", where "dialect" is anything but OSVS. Other operations resulting in sending and receiving items sharing the same memory are not detected.

Although portability of COBOL source code is only guaranteed when no overlapping MOVE statements occur in your source program, this COBOL system does allow such statements. The behavior of such statements is sensitive to the BYTE-MODE-MOVE Compiler directive.

10.1.5.6 Multiple Results in Arithmetic Statements

The ADD, COMPUTE, DIVIDE, MULTIPLY and SUBTRACT statements can have multiple results. Such statements behave as though they had been written in the following way:

  1. A statement which accesses all data items that are part of the initial evaluation of the statement, performs all arithmetic necessary to arrive at the result to be stored in the receiving items, and stores that result in a temporary storage location.

  2. A sequence of statements transferring or combining the value of this temporary location with each single resultant data item. These statements are considered to be written in the same left-to-right sequence in which the multiple results are listed.

    The result of the statement:

     ADD a, b, c TO c, d (c), e

    is equivalent to:

     ADD a, b, c GIVING temp 
        ADD temp TO c 
        ADD temp TO d (c) 
        ADD temp TO e

    and the result of the statement:

     MULTIPLY a(i) BY i, a(i)

    is equivalent to:

     MOVE a(i) to temp
        MULTIPLY temp by i 
        MULTIPLY temp BY a(i)

    where temp is an interm ediate result item provided by your COBOL system.

10.1.5.7 Incompatible Data

Except for the class condition (see the section Class Condition in this chapter), when the contents of a data item are referenced in the Procedure Division and the contents of that data item are not compatible with the class specified for that data item by its PICTURE clause

or function definition

then the result of such a reference is undefined.

The results of referencing a numeric field that contains nonnumeric, or otherwise invalid data, are undefined. Such conditions may be detected, and give an error at run-time. This behavior is affected by the F run-time switch.

When an alphabetic field which contains non-alphabetic data is referenced, your program will continue execution, but results may be undefined.

10.1.5.8 Signed Receiving Items

When the receiving item in an arithmetic statement or a MOVE statement is a signed numeric or a signed numeric edited item, the sign is moved into the receiving item independently of any truncation of the absolute numeric data. It is possible, therefore, for the numeric value to be zero but for the sign to be negative.

10.1.6 File I/O Concepts

10.1.6.1 File Position Indicator

The file position indicator identifies the next record to be accessed within a given file during certain input-output sequences. The setting of the file position indicator is affected only by CLOSE, OPEN, START and READ statements. The file position indicator has no effect on files opened in the output or extend mode.

10.1.6.2 I/O Status

If the FILE STATUS clause is specified in a file control entry, a value is placed into the specified two-character data item during the execution of an OPEN, CLOSE, READ, WRITE, REWRITE, DELETE, UNLOCK or START statement before any applicable USE procedure is executed, to indicate to the COBOL program the status of that input-output operation.

The file status keys described in the following pages are for those files which conform fully to the ANSI standard and which use none of the extensions available with this COBOL system.

Use of extensions, for example, specifying a file as LINE SEQUENTIAL, affects the status keys returned. Additional information is provided under the relevant verbs.

10.1.6.2.1 Status Key 1

The leftmost character position of the FILE STATUS data item is known as status key 1 and is set to indicate one of the following conditions upon completion of the input-output operation on a file of any organization.

"0" - Successful completion
"1" - At end
"2" - Invalid key
"3" - Permanent error

"4"

- Logic error
"9" - Run-time system error message

The meaning of the above conditions is as follows:

"0" Successful completion. The input-output statement was successfully executed.
"1" At end. The sequential READ statement was unsuccessfully executed either because of an attempt to read a record when no next logical record exists in the file or because the first READ statement was executed for a file described with the OPTIONAL clause when that file was not available to the program at the time its associated OPEN statement was executed.
"2" Invalid key. The input-output statement on a non-sequential file was unsuccessfully executed because of one of the following:

Sequence error
Duplicate key
No record found
Boundary violation

"3" Permanent error. The input-output statement was unsuccessfully executed because of a boundary violation for a sequential file or because of an input-output error, such as a data check parity error or transmission error.
"4"

Logic error. The input-output statement was unsuccessfully executed, either because an improper sequence of input-output operations was performed on the file, or because a limit defined by the user was violated.

"9" Run-time system error message. The input-output statement was unsuccessfully executed because of a condition that is specified by the run-time system error message number. This value is used only to indicate a condition not indicated by other defined values of status key 1, or by specified combinations of the values of status key 1 and status key 2.

10.1.6.2.2 Status Key 2

The rightmost character position of the FILE STATUS data item is known as status key 2 and is used to further describe the results of the input-output operation.

The combination of status key 1 and status key 2 defines the result of the input-output operation as detailed below:

Successful Completion

If status key 1 contains "0" to indicate the successful completion of the input-output operation, status key 2 can contain one of the following values:

"0" (all files) No further information is available
"2" (indexed files only) Indicates one of two possibilities:

  • For a READ statement, the key value for the current key of reference is equal to the value of the same key in the next record within the current key of reference.

  • For a WRITE or REWRITE statement, the record just written created a duplicate key value for at least one alternate record key for which duplicates are allowed.
"4"

(all files) Indicates that the length of the record being processed does not conform to the fixed file attributes for that file.

"5"

(all files) Indicates that the referenced optional file was not present at the time the OPEN statement was executed.

"7"

(record sequential files only) Indicates that for a CLOSE statement with the NO REWIND, REEL/UNIT or FOR REWIND phrase, or an OPEN statement with the NO REWIND phrase, the referenced file is a non-reel/unit medium.

AT END Condition with Unsuccessful Completion

If status key 1 contains "1" to indicate the AT END condition, status key 2 can contain one of the following values:

"0" (all files) Indicates that there is no next logical record. This can be caused by two conditions:

  • The end of the file has been reached.

  • A sequential READ statement has been attempted for the first time on an optional input file that is not present.
"4"

(relative files only) Indicates that the number of significant digits in the relative record number is larger than the size of the relative key data item described for that file.

INVALID KEY Condition with Unsuccessful Completion

If status key 1 contains "2" to indicate INVALID KEY condition, status key 2 indicates the cause of the condition by one of the values:

"1" (sequentially accessed indexed files) Indicates a sequence error. The ascending sequence requirements of successive record key values have been violated (see the section The WRITE Statement later in this chapter), or the prime record key value has been changed by the COBOL program between the successful execution of a READ statement and the execution of the next REWRITE statement for that file.
"2" (relative and indexed files only) Indicates a duplicate key value. An attempt has been made either to write a record that would create a duplicate prime record key or to write or rewrite a record that would create a duplicate alternate record key when the DUPLICATES phrase is not specified for that alternate record key.
"3" (relative and indexed files only) Indicates no record found. An attempt has been made to access a record, identified by a key, and that record does not exist in the file, or a START or READ statement has been attempted on an optional input file that is not present.
"4" (relative and indexed files only) Indicates a boundary violation arising from one of the following conditions:

  • An attempt has been made to write beyond the externally defined boundaries of a file.

  • A sequential WRITE statement has been attempted for a relative file, but 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.

Permanent Error Condition with Unsuccessful Completion

If status key 1 contains "3" to indicate a permanent error condition, status key 2 can contain one of the following values to indicate the cause of that error:

"0" (all files) Indicates that no further information is available concerning the cause of the error.
"4" (sequential files only) Indicates a boundary violation. An attempt has been made to write beyond the externally defined boundaries of a file.
"5" (all files) Indicates that an OPEN statement with the INPUT, I/O, or EXTEND phrase has been attempted on a non-optional file that is not present.
"7" (all files) Indicates that an OPEN statement has been attempted on a file which will not support the open mode specified in the OPEN statement. The possible violations are:

  • The EXTEND or OUTPUT phrase has been specified but the file will not support write operations.

  • The I/O phrase has been specified but the file will not support the input and output operations that are permitted for a relative file when opened in the I/O mode.

  • The INPUT phrase has been specified but the file will not support read operations.
"8" (all files) Indicates that an OPEN statement has been attempted on a file previously closed with lock.
"9" (record sequential, relative and indexed files) Indicates that a conflict has been detected between the fixed file attributes and the attributes specified for that file in the program.

Logic Error Condition with Unsuccessful Completion

If status key 1 contains "4" to indicate a logic error condition, status key 2 can contain one of the following values to indicate the cause of that error:

"1" (all files) Indicates that an OPEN statement has been attempted for a file already in open mode.
"2" (all files) Indicates that a CLOSE statement has been attempted for a file not in open mode.
"3" (all files, sequential access mode only) Indicates that the last input-output statement executed for the associated file, prior to the execution of a DELETE or REWRITE statement, was not a successfully executed READ statement.
"4" (record sequential files only) Indicates that a boundary violation exists. A possible violation is that an attempt has been made to WRITE or REWRITE a record that is larger than the largest, or smaller than the smallest, record allowed by the RECORD IS VARYING clause of the associated file.
"5" (all files ) An attempt has been made to REWRITE a record to a file, and the record is not the same size as the record being replaced.

For line sequential files this refers to the physical size of the record, that is after space removal, tab compression and null insertion. In this case, the physical size of the new record is allowed to be smaller than that of the record being replaced.

"6" (all files) Indicates that a sequential READ statement has been attempted on a file open in input or I/O mode, but no valid next record has been established. This can be caused by the following conditions:

  • The preceding START statement was unsuccessful.

  • The preceding READ statement was unsuccessful but did not cause an at end condition.

  • The preceding READ statement caused an at end condition.
"7" (all files) Indicates that the execution of a READ or START statement has been attempted on a file not open in input or I/O mode.
"8" (all files) Indicates that the execution of a WRITE statement has been attempted on a file not open in I/O, output or extend mode, or on a file open I/O in sequential access mode.
"9" (all files) Indicates that the execution of a DELETE or REWRITE statement has been atte mpted on a file not open in I/O mode.

Run-Time System Error Message

If status key 1 contains " 9" to indicate a run-time system error message, status key 2 contains the run-time system error message number in binary. These are described in full in your Error Messages.

10.1.6.2.3 Valid Combinations of Status Keys 1 And 2

In the following table: "S" indicates a Record Sequential file
"L " indicates a Line Sequential file
"R" indicates a Relative file
"I" indicates an Indexed file.

A particular combination of status key 1 and status key 2 is valid for a given file organization if the letter for that organization is found at the corresponding intersection in Table 10-4.

Table 10-4: Valid Combinations of Status Keys 1 and 2

Status Key 1 Status Key 2
0 1 2 3 4 5 6 7 8 9
Successful Completion 0 SRIL   I   SRIL SRIL   S    
At End 1 SRIL       R          
Invalid Key 2   I RI RI RI          
Permanent Error 3 SRIL       SL SRIL   SRIL SRIL SRI
Logic Error 4   SRIL SRIL SRIL SRIL   SRIL SRIL SRIL SRIL
Implementor Defined 9 Run-Time System Error Message (SRIL)

10.1.6.3 The AT END Condition

The AT END condition can occur as a result of the execution of a READ statement. For details of the causes of the condition, see the section The READ Statement later in this chapter.

10.1.6.4 The INVALID KEY Condition

The INVALID KEY condition can occur as a result of the execution of a START, READ, WRITE, REWRITE or DELETE statement. For details of the causes of the condition, see the sections The START Statement, The READ Statement, The WRITE Statement, The REWRITE Statement, and The DELETE Statement later in this chapter.

If the INVALID KEY condition exists after the execution of the input-output operation specified in an input-output statement, the following actions occur in the order shown:

  1. A value is placed in the FILE STATUS data item, if specified for this file, to indicate an INVALID KEY condition. (See the section I/O Status earlier in this chapter.)

  2. If the INVALID KEY phrase is specified in the statement causing the condition, control is passed to the INVALID KEY imperative statement. Any USE procedure specified for this file is not executed.

  3. If the INVALID KEY phrase is not specified, but a USE procedure is specified, either explicitly or implicitly, for this file, that procedure is executed.

When the INVALID KEY condition occurs, execution of the input-output statement which recognized the condition is unsuccessful, and the file is not affected.

Note that INVALID KEY does not trap errors when status key 1 is set to "9". Such errors must be trapped either by explicitly testing the status key or by using declaratives instead of the INVALID KEY clause.

10.1.6.5 Sharing Files on Multi-user Systems

The run-time system (RTS) supports this COBOL system's multi-user facilities which allow files to be shared between users in a multi-user environment, and allow programs accessing those files to prevent access to records or entire files while data is being updated.

In single-user environments the multi-user syntax has no effect at run time, but programs can be developed for use in both single- and multi-user environments.

Files are either active or inactive. An active file is open to one or more run-units. An inactive file is one that is not open to any run-unit.

Active files can be open in one of two modes: exclusive or shareable.

10.1.6.5.1 Exclusive

A file which is in exclusive mode is open to one run unit only; any other run-unit which attempts to access it will receive a "File locked" error and be denied access. Exclusive mode implies that a file lock is held by the one run unit which is able to access the file; the file lock is released by that run unit closing the file.

10.1.6.5.2 Shareable

A file which is in shareable mode is available to any number of run units, each of which can protect data while using the file by locking one or more records at a time in the file. This prevents other run units from acquiring a lock on the individual records that are locked, but does not prevent access to the file otherwise. The organization of the file affects the way the file can be shared.

10.1.6.5.3 Record Sequential Files

Record sequential files opened for INPUT can be shared between run units but records cannot be locked in the file. Files opened for I/O or EXTEND can also be made shareable and each run unit can maintain a record lock for the file. Files opened for OUTPUT always have an exclusive file lock.

10.1.6.5.4 Line Sequential Files

Line sequential files that are opened INPUT or EXTEND can be made shareable but records cannot be locked in the file. Files that are opened OUTPUT always have an exclusive file lock.

10.1.6.5.5 Relative and Indexed Files

Files that are opened in INPUT mode are shareable, but records cannot be locked in the file. Files that are opened I/O can be shareable but files that are opened OUTPUT or EXTEND are exclusive.

10.1.6.5.6 Record Locking

Each run unit that is sharing access to a file can be locking either a single record or multiple records in that file. A run unit cannot select single record locking and multiple record locking for the same file.

10.1.6.5.7 Single Record Lock

A run unit that has specified single record locking for a file (either explicitly or implicitly) can hold only one record lock in that file at any one time. A run unit can acquire a record lock in two ways: manually or automatically.

10.1.6.5.8 Manual Record Locking

The run unit acquires a lock only if it accesses a record with a READ WITH LOCK statement.

10.1.6.5.9 Automatic Record Locking

The run unit acquires a lock whenever it reads a record in the file, unless you specify the READ WITH NO LOCK statement.

10.1.6.5.10 Releasing Single Record Locks

The lock is released by the same run unit:

10.1.6.5.11 Multiple Record Locks

Locking of multiple records in a file is available only when the organization of that file is relative, indexed or record sequential.

A run unit that has specified multiple record locking for a file can hold a number of record locks in one file simultaneously. This prevents other run units from updating or acquiring a lock on those locked records, but does not deny them access to any records that are not locked. Record locks can be acquired in two ways: manually or automatically.

10.1.6.5.12 Manual Record Locking

The run unit acquires a lock only if it accesses a record with a READ WITH LOCK or READ WITH KEPT LOCK statement.

10.1.6.5.13 Automatic Record Locking

The run unit acquires a lock whenever it reads a record in the file unless you explicitly specify that it should not. If the WRITELOCK Compiler directive has been specified at the time the program was submitted to your COBOL system, then a lock is acquired if the run unit accesses the file with a WRITE or REWRITE statement.

10.1.6.5.14 Releasing Multiple Record Locks

The locks are released by the same run unit:


Tables 10-5, 10-6 and 10-7 show the default type of locking which is used when files are opened in a particular open mode. The defa ult locking can be modified if the AUTOLOCK Compiler directive was specified at the time the program was submitted to your COBOL system. The tables also indicate whether the default type of locking can be overridden for individual files. This is done by inserting a suitable clause in the SELECT statement for the file. (See section The SELECT Statement later in this chapter for details of the required syntax.)

X/Open restricts those X/Open conforming source programs that use locking to either single record locks with automatic locking, or multiple record locks with manual locking.

Table 10-5: Default Locking For Record Sequential Files

OPEN Mode No Directive AUTOLOCK Compiler
Directive
Override in SELECT Statement
INPUT No lock No lock Yes, but only to Exclusive
I/O Exclusive Lock on single record Yes
OUTPUT Exclusive Exclusive No
EXTEND Exclusive No lock Yes, the file can be made shareable but no records are locked

Table 10-6: Default Lo cking For Line Sequential Files

OPEN Mode No Directive AUTOLOCK Compiler
Directive
Override in SELECT Statement
INPUT No lock No lock No
I/O Exclusive No lock No
OUTPUT Exclusive Exclusive No
EXTEND Exclusive No lock No

Table 10-7: Default Locking For Relative And Indexed Files

OPEN Mode No Directive AUTOLOCK Compiler
Directive
Override in SELECT Statement
INPUT No lock No lock Yes, but only to Exclusive
I/O Exclusive Automatic lock on single record Yes
OUTPUT Exclusive Exclusive No
EXTEND Exclusive Exclusive No


Notes:

  1. A file opened for OUTPUT causes the file to become exclusive,regardless of the specified lock mode.

  2. The programmer can select the type of locking for individual files by accepting the default locking (see Tables 4-15, 4-16 and 4-17) or by including a LOCK MODE clause in the file-control entry (see section The File-Control Entry later in this chapter).


Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousData Division - Screen Section Procedure Division - Intrinsic FunctionsNext