Data Division - Screen Section

Procedure Division - Intrinsic Functions

Chapter 10: Procedure Division

10.1 Procedure Division

The Procedure Division is optional . The procedure division in a program definition
function definition, or
method definition contains procedures to be executed. These procedures can be declarative and/or nondeclarative.

The procedure division for an object definition and a factory definition contains the methods that may be invoked on the object or factory object.

The procedure division in a call prototype contains no procedures, except that it may contain the ENTRY statement.

General Formats

Format 1 (with-sections)

Format 2 (without-sections)

Format 3 (interface-object-or-factory)

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

Format 3 can be used only in a
factory definition
, an
object definition
, or an
interface definition.

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 is composed of a paragraph or group of paragraphs, or a section or group of sections in the Procedure Division. A procedure-name is a word used to refer to a paragraph or section in the source element in which it occurs. It consists of a paragraph-name (that may be qualified) or a section-name.

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 or, if the paragraph-name is omitted, one or more successive sentences following the procedure division header or a section header. 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 or
method 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 the rules indicate some other order.

In a call prototype the Procedure Division is never executed.

In an
object definition or a
factory definition,
declaratives behave in the same way as if they had been specified in every contained method definition.

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.
   • DEFAULTCALLS - sets the default calling convention if none is explicitly coded in the Procedure Division header.

   • STICKY-LINKAGE - controls whether addressability to Linkage Section items is maintained between calls to different entry points in the same program.

Syntax Rules

All Formats

1. Mnemonic-name is necessary only if the runtime element is being invoked by another runtime element and that runtime element 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. If data-name-1 or data-name-2 is defined with the USAGE OBJECT REFERENCE clause, the ACTIVE-CLASS phrase must not be specified.

4. Data-name-3 must be defined as a level 01 or level 77 entry in the Linkage Section. The data description entry for data-name-3 must not contain a REDEFINES clause. A data item elsewhere in the Linkage Section may specify REDEFINES data-name-3.

5. Data-name-3 must not be the same as data-name-1 or data-name-2.

Format 1

6. 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

   . 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.

7. 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
   . Data-name-2 must be defined as a data item of class numeric, object or pointer.
   Data-name-2 can be of any class, but the length must be no greater than 8 bytes.

8. The RETURNING phrase must be specified in a function definition and in a function prototype definition.

9. The RETURNING phrase may be specified in

   a method definition or

   a program definition.

Format 2

10. 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.

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

12. 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

All Formats

1. Up to five data-names are permitted in the USING phrase.

   Up to sixty-two data-names are permitted in the USING phrase.

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

Format 1

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

4. 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 activated runtime element 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 activated runtime element. 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.

5. If the activating runtime element is COBOL the following rules apply. If the activating runtime element 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.

6. The USING phrase identifies the names of the formal parameters used by the program
   ,

   function or

   method for any arguments passed to it. The arguments passed to it are identified in the activating source element by one of the following:

   • the USING phrase of a CALL statement
   • the arguments in a function-identifier
   • the USING phrase of an INVOKE statement

   The correspondence between the two lists of names is established on a positional basis

7. If the argument is passed by content, the activated runtime element operates as if the record in the linkage section were allocated by the activating runtime element during the process of initiating the activation and as if this record does not occupy the same storage area as the argument in the activating runtime element. This allocated record is exactly the same number of alphanumeric character positions in length as the argument. That argument is moved to this allocated record without conversion. This record is then treated by the activated runtime element as if it were the argument and as if it were passed by reference.

8. If the argument is passed by reference, the activated runtime element operates as if the formal parameter occupies the same storage area as the argument.

9. If the argument is passed by value, the activated runtime element operates as if the record in the linkage section were allocated by the activating runtime element during the process of initiating the activation and as if this record does not occupy the same storage area as the argument in the activating runtime element. This allocated record is exactly the same number of alphanumeric character positions in length as the argument. That argument is moved to this allocated record without conversion. This record is then treated by the activated runtime element as if it were the argument and as if it were passed by reference.

10. At all times in the activated element, references to data-name-1,
    data-name-2 and data-name-3
    are resolved in accordance with their description in the Linkage Section. If this description defines a greater number of character positions than the corresponding data item in the activating element, 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.

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.

Format 2

13. 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.

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 , 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

• 1 + 6

  giving a result of 7.

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 behavior by truncating its results accordingly, with the following limitations:

• The maximum number of integer and decimal places allowed by this COBOL system is 18 for each. Truncation of intermediate results will cease at the point in the expression where this limit is reached. A warning message is issued at compile time if this occurs.

• The rules apply to fixed point numerical expressions only. If the expression contains any floating-point operands or any operation which causes it to be evaluated in floating point (see the section Intrinsic Functions), all truncation of intermediate results ceases.

• Floating-point results are, by their nature, inexact and may vary across platforms by a small degree.

10.1.4 Conditional Expressions

Conditional expressions identify conditions that are tested to enable selection 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:

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. 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 uppercase letters 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

   or national 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 run unit. (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.

If the compiler directive SWITCH-TYPE is set to 1, which is the default, it is only possible to use the Switch-Status Condition to test if a COBOL switch is set from within the runtime element that set the switch.

If the compiler directive SWITCH-TYPE is set to 2, which is set by the compiler when the compiler directive DIALECT is set to ISO2000, it is possible to use the Switch-Status Condition to test if a COBOL switch is set from within any runtime element of the run unit.

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:

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:
   • a simple condition

   • a negated simple condition

   • a combined condition

   • a negated combined condition; that is, the "NOT" logical operator followed by a combined condition enclosed within parentheses

   • combinations of the above, specified according to the rules summarized in Table 10-3.

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

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:

• the omission of the subject of the relation condition, or:

• the omission of the subject and relational operator of the relation condition.

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
and 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 there are no overlapping MOVE statements, 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, execution will continue, 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 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.

The meaning of the above conditions is as follows:

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:

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:

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 runtime element 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 source element.

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:

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

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 runtime elements 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 runtime elements 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:

• Accessing any record in the file with any file operation (except START for relative and indexed files)

• Executing an UNLOCK statement on that file

• Executing a COMMIT statement

• Executing a ROLLBACK statement

• Closing the file.

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 compilation group 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:

• Executing a DELETE statement referencing a record for which a lock is held. In this case, only the lock on that record is released

• Executing an UNLOCK statement for that file

• Executing a COMMIT statement

• Executing a ROLLBACK statement

• Closing the file.

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 compilation group 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

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

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

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).

10.1.7 Conformance for parameters and returning items

10.1.7.1 Parameters

The number of arguments in the activating unit shall be equal to the number of formal parameters in the activated unit.

If the numbers of operands are different, then if there are more operands in the activating statement, they are ignored and if there are more operands in the Procedure Division header, they must not be referenced within the activated runtime element. The positional correspondence may vary depending on the non-COBOL calling conventions implied by mnemonic-name. Any mismatch in the number of the operands will only be apparent at run time and so the directive FLAG will not cause this extension to be flagged.

The rules for conformance between arguments and formal parameters depend on whether either the formal parameter or its corresponding argument is a group item or both are elementary items.

10.1.7.1.1 Group Items

If either the formal parameter or the argument is a group item, the corresponding argument or formal parameter shall be a group item or an elementary item of category alphanumeric, and the formal parameter shall be described with the same number or a smaller number of character positions as the corresponding argument.

10.1.7.1.2 Elementary Items

The conformance rules for elementary items depend on whether the argument is passed by reference, by content, or by value.

10.1.7.1.2.1 Elementary Items Passed by Reference

If either the formal parameter or the corresponding argument is an object reference, the corresponding argument or formal parameter shall be an object reference following these rules:

1. If either the argument or the formal parameter is a universal object reference, the corresponding formal parameter or argument shall be a universal object reference.

2. If either the argument or the formal parameter is described with an interface-name, the corresponding formal parameter or argument shall be described with the same interface-name.

3. If either the argument or the formal parameter is described with a class-name, the corresponding formal parameter or argument shall be described with the same class-name, and the FACTORY and ONLY phrases shall be the same.

If either the argument or the formal parameter is of class pointer, the corresponding formal parameter or argument shall be of class pointer and the corresponding items shall be of the same category. The ADDRESS special register is considered to be of class pointer and category data-pointer.

If neither the formal parameter nor the argument is of class object or pointer, the conformance rules are the following:

1. If the activated unit is a program, the formal parameter shall be described with the same number of character positions as the corresponding argument.
2. If the activated unit is a method, the definition of the formal parameter and the definition of the argument shall have the same PICTURE, USAGE, SIGN, SYNCHRONIZED, JUSTIFIED, and BLANK clauses, with the following exceptions:
   1. All currency sign characters are considered the same.

   2. If the DECIMAL-POINT IS COMMA clause is in effect in only the activating or only the activated runtime element, the period picture symbol matches the comma picture symbol and the comma matches the period.

10.1.7.1.2.2 Elementary Items Passed by Content or by Value

If the formal parameter is of class object or pointer, the conformance rules shall be the same as if a SET statement were performed in the activating runtime element with the argument as the sending operand and the corresponding formal parameter as the receiving operand.

If the formal parameter is not of class object or pointer, the conformance rules are the following:

1. If the activated unit is a program, the formal parameter shall be described with the same number of character positions as the corresponding argument.

2. If the activated unit is a method, the conformance rules depend on the type of the formal parameter as specified in the following rules:
   1. If the formal parameter is numeric, the conformance rules shall be the same as for a COMPUTE statement with the argument as the sending operand and the corresponding formal parameter as the receiving operand.

   2. If the formal parameter is an index or pointer data item, the conformance rules shall be the same as for a SET statement with the argument as the sending operand and the corresponding formal parameter as the receiving operand.

   3. Otherwise, the conformance rules shall be the same as for a MOVE statement with the argument as the sending operand and the corresponding formal parameter as the receiving operand.

10.1.7.2 Returning Items

A returning item shall be specified in the activating statement, if and only if a returning item is specified in the procedure division header
or ENTRY statement
of the activated source element.

The returning item in the activated source element is the sending operand, the corresponding returning item in the activating source element is the receiving operand.

10.1.7.2.1 Group Items

If either the sending or the receiving operand is a group item, the corresponding returning item shall be a group item or an elementary item of category alphanumeric, and the receiving operand shall be described with the same number of character positions as the sending operand.

10.1.7.2.2 Elementary Items

If either of the operands is an object reference, the corresponding item shall be an object reference, and the following rules shall apply:

1. If the returning item in the activated source element is not described with an ACTIVE-CLASS phrase, the conformance rules shall be the same as if a SET statement were performed in the activated runtime element with the returning item in the activated source element as the sending operand and the corresponding returning item in the activating source element as the receiving operand.

2. If the returning item in the activated source element is described with an ACTIVE-CLASS phrase, the conformance rules are the same as if a SET statement were performed in the activating runtime element with the returning item in the activating source element as the receiving operand, and a sending operand described with USAGE OBJECT REFERENCE as determined by the following rules:
   1. If the activated method is invoked with a class-name, the sending operand is described with the same class-name and an ONLY phrase.

   2. If the activated method is invoked with the predefined object reference SELF or
      or SELFCLASS
      , the sending operand is described with an ACTIVE-CLASS phrase.

   3. If the activated method is invoked with an object reference described with an interface-name, the sending operand is a universal object reference.

   4. If the activated method is invoked with any other object reference, this identifier is used as the sending operand, including the ONLY phrase if specified.

   5. If the sending operand selected by applying the above rules is described with a class-name or an ACTIVE-CLASS phrase, the presence or absence of the FACTORY phrase is the same as in the returning item of the activated source element.

If the sending operand is not an object reference, the receiving operand shall have the same PICTURE, USAGE, SIGN, SYNCHRONIZED, JUSTIFIED, and BLANK clauses, with the following exceptions:

1. All currency sign characters are considered the same

2. If the DECIMAL-POINT IS COMMA clause is in effect in only the activating or only the activated runtime element, the period picture symbol matches the comma picture symbol and the comma matches the period.

Data Division - Screen Section

Procedure Division - Intrinsic Functions